diff -Nrc3pad gcc-3.3.2/gcc/ada/ChangeLog gcc-3.3.3/gcc/ada/ChangeLog *** gcc-3.3.2/gcc/ada/ChangeLog Thu Oct 16 19:43:01 2003 --- gcc-3.3.3/gcc/ada/ChangeLog Sat Feb 14 20:17:09 2004 *************** *** 1,3 **** --- 1,7 ---- + 2004-02-14 Release Manager + + * GCC 3.3.3 Released. + 2003-10-16 Release Manager * GCC 3.3.2 Released. diff -Nrc3pad gcc-3.3.2/gcc/ada/gnat-style.info gcc-3.3.3/gcc/ada/gnat-style.info *** gcc-3.3.2/gcc/ada/gnat-style.info Thu Oct 16 20:24:02 2003 --- gcc-3.3.3/gcc/ada/gnat-style.info Thu Jan 1 00:00:00 1970 *************** *** 1,483 **** - This is ada/gnat-style.info, produced by makeinfo version 4.2 from - ada/gnat-style.texi. - - INFO-DIR-SECTION Programming - START-INFO-DIR-ENTRY - * gnat-style: (gnat-style). GNAT Coding Style - END-INFO-DIR-ENTRY - - GNAT Coding Style - A guide for GNAT developers - Copyright (C) - 1992-2001 Ada Core Technologies, Inc. - -  - File: gnat-style.info, Node: Top, Next: General, Up: (dir) - - * Menu: - - * General:: - * Lexical Elements:: - * Declarations and Types:: - * Expressions and Names:: - * Statements:: - * Subprograms:: - * Packages:: - * Program Structure:: - -  - File: gnat-style.info, Node: General, Next: Lexical Elements, Prev: Top, Up: Top - - General - ******* - - Most of GNAT is written in Ada using a consistent style to ensure - readability of the code. This document has been written to help - maintain this consistent style, while having a large group of developers - work on the compiler. - - For the coding style in the C parts of the compiler and run time, see - the GNU Coding Guidelines. - - This document is structured after the Ada Reference manual. Those - familiar with that document should be able to quickly lookup style - rules for particular constructs. - -  - File: gnat-style.info, Node: Lexical Elements, Next: Declarations and Types, Prev: General, Up: Top - - Lexical Elements - **************** - - Character Set and Separators - ============================ - - * The character set used should be plain 7-bit ASCII. The only - separators allowed are space and the end-of-line sequence. No - other control character or format effector (such as HT, VT, FF) - should be used. The normal end-of-line sequence is used, which - may be LF, CR/LF or CR, depending on the host system. An optional - SUB (16#1A#) may be present as the last character in the file on - hosts using that character as file terminator. - - * Files that are checked in or distributed should be in host format. - - * A line should never be longer than 79 characters, not counting the - line separator. - - * Lines must not have trailing blanks. - - * Indentation is 3 characters per level for if statements, loops, - case statements. For exact information on required spacing - between lexical elements, see file `style.adb'. - - - Identifiers - =========== - - * Identifiers will start with an upper case letter, and each letter - following an underscore will be upper case. Short acronyms may be - all upper case. All other letters are lower case. An exception - is for identifiers matching a foreign language. In particular, we - use all lower case where appropriate for C. - - * Use underscores to separate words in an identifier. - - * Try to limit your use of abbreviations in identifiers. It is ok - to make a few abbreviations, explain what they mean, and then use - them frequently, but don't use lots of obscure abbreviations. An - example is the `ALI' word which stands for Ada Library Information - and is by convention always written in upper-case when used in - entity names. - - procedure Find_ALI_Files; - - * Don't use the variable `I', use `J' instead, `I' is too easily - mixed up with `1' in some fonts. Similarly don't use the variable - `O', which is too easily mixed up with `0'. - - Numeric Literals - ================ - - * Numeric literals should include underscores where helpful for - readability. - - 1_000_000 - 16#8000_000# - 3.14159_26535_89793_23846 - - Reserved Words - ============== - - * Reserved words use all lower case. - - return else - - * The words `Access', `Delta' and `Digits' are capitalized when used - as attribute_designator. - - Comments - ======== - - * Comment start with `-- ' (i.e. `--' followed by two spaces). The - only exception to this rule (i.e. one space is tolerated) is when - the comment ends with ` --'. It also accepted to have only one - space between `--' and the start of the comment when the comment - is at the end of a line, after some Ada code. - - * Every sentence in a comment should start with an upper-case letter - (including the first letter of the comment). - - * When declarations are commented with "hanging" comments, i.e. - comments after the declaration, there is no blank line before the - comment, and if it is absolutely necessary to have blank lines - within the comments these blank lines _do_ have a `--' (unlike the - normal rule, which is to use entirely blank lines for separating - comment paragraphs). The comment start at same level of - indentation as code they are commenting. - - z : Integer; - -- Integer value for storing value of z - -- - -- The previous line was a blank line. - - * Comments that are dubious or incomplete or comment on possibly - wrong or incomplete code should be preceded or followed by `???'. - - * Comments in a subprogram body must generally be surrounded by - blank lines, except after a `begin': - - begin - -- Comment for the next statement - - A := 5; - - -- Comment for the B statement - - B := 6; - - * In sequences of statements, comments at the end of the lines - should be aligned. - - My_Identifier := 5; -- First comment - Other_Id := 6; -- Second comment - - * Short comments that fit on a single line are _not_ ended with a - period. Comments taking more than a line are punctuated in the - normal manner. - - * Comments should focus on why instead of what. Descriptions of - what subprograms do go with the specification. - - * Comments describing a subprogram spec should specifically mention - the formal argument names. General rule: write a comment that - does not depend on the names of things. The names are - supplementary, not sufficient, as comments. - - * Do NOT put two spaces after periods in comments. - -  - File: gnat-style.info, Node: Declarations and Types, Next: Expressions and Names, Prev: Lexical Elements, Up: Top - - Declarations and Types - ********************** - - * In entity declarations, colons must be surrounded by spaces. - Colons should be aligned. - - Entity1 : Integer; - My_Entity : Integer; - - * Declarations should be grouped in a logical order. Related groups - of declarations may be preceded by a header comment. - - * All local subprograms in a subprogram or package body should be - declared before the first local subprogram body. - - * Don't declare local entities that hide global entities. - - * Don't declare multiple variables in one declaration that spans - lines. Start a new declaration on each line, instead. - - * The defining_identifiers of global declarations serve as comments - of a sort. So don't choose terse names, but look for names that - give useful information instead. - - * Local names can be shorter, because they are used only within one - context, where comments explain their purpose. - - -  - File: gnat-style.info, Node: Expressions and Names, Next: Statements, Prev: Declarations and Types, Up: Top - - Expressions and Names - ********************* - - * Every operator must be surrounded by spaces, except for the - exponentiation operator. - - E := A * B**2 + 3 * (C - D); - - * When folding a long line, fold before an operator, not after. - - * Use parentheses where they make the intended order of evaluation - clearer: - (A / B) * C - -  - File: gnat-style.info, Node: Statements, Next: Subprograms, Prev: Expressions and Names, Up: Top - - Statements - ********** - - Simple and Compound Statements - ============================== - - * Use only one statement or label per line. - - * A longer sequence_of_statements may be divided in logical groups - or separated from surrounding code using a blank line. - - If Statements - ============= - - * When the `if', `elsif' or `else' keywords fit on the same line - with the condition and the `then' keyword, then the statement is - formatted as follows: - - if CONDITION then - ... - elsif CONDITION then - ... - else - ... - end if; - - When the above layout is not possible, `then' should be aligned - with `if', and conditions should preferably be split before an - `and' or `or' keyword a follows: - - if LONG_CONDITION_THAT_HAS_TO_BE_SPLIT - and then CONTINUED_ON_THE_NEXT_LINE - then - ... - end if; - - The `elsif', `else' and `end if' always line up with the `if' - keyword. The preferred location for splitting the line is before - `and' or `or'. The continuation of a condition is indented with - two spaces or as many as needed to make nesting clear. As - exception, if conditions are closely related either of the - following is allowed: - - if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf - or else - x = asldkjhalkdsjfhhfd - or else - x = asdfadsfadsf - then - - if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else - x = asldkjhalkdsjfhhfd or else - x = asdfadsfadsf - then - - * Conditions should use short-circuit forms (`and then', `or else'). - - * Complex conditions in if statements are indented two characters: - - if THIS_COMPLEX_CONDITION - and then THAT_OTHER_ONE - and then ONE_LAST_ONE - then - ... - - * Every `if' block is preceded and followed by a blank line, except - where it begins or ends a sequence_of_statements. - - A := 5; - - if A = 5 then - null; - end if; - - A := 6; - - Case Statements - =============== - - * Layout is as below. For long case statements, the extra - indentation can be saved by aligning the when clauses with the - opening case. - - case EXPRESSION is - when CONDITION => - ... - when CONDITION => - ... - end case; - - Loop Statements - =============== - - When possible, have `for' or `while' on one line with the - condition and the `loop' keyword. - - for J in S'Range loop - ... - end loop; - - If the condition is too long, split the condition (see "If - statements" above) and align `loop' with the `for' or `while' - keyword. - - while LONG_CONDITION_THAT_HAS_TO_BE_SPLIT - and then CONTINUED_ON_THE_NEXT_LINE - loop - ... - end loop; - - If the loop_statement has an identifier, it is laid out as follows: - - Outer : while not CONDITION loop - ... - end Outer; - - Block Statements - ================ - - * The `declare' (optional), `begin' and `end' statements are - aligned, except when the block_statement is named. There is a - blank line before the `begin' keyword: - - Some_Block : declare - ... - - begin - ... - end Some_Block; - - -  - File: gnat-style.info, Node: Subprograms, Next: Packages, Prev: Statements, Up: Top - - Subprograms - *********** - - Subprogram Declarations - ======================= - - * Do not write the `in' for parameters, especially in functions: - - function Length (S : String) return Integer; - - * When the declaration line for a procedure or a function is too - long, fold it. In this case, align the colons, and, for - functions, the result type. - - function Head - (Source : String; - Count : Natural; - Pad : Character := Space) - return String; - - * The parameter list for a subprogram is preceded by a space: - - procedure Func (A : Integer); - - - Subprogram Bodies - ================= - - * The functions and procedures should always be sorted - alphabetically in a compilation unit. - - * All subprograms have a header giving the function name, with the - following format: - - ----------------- - -- My_Function -- - ----------------- - - procedure My_Function is - begin - - Note that the name in the header is preceded by a single space, - not two spaces as for other comments. - - * Every subprogram body must have a preceding subprogram_declaration. - - * If there any declarations in a subprogram, the `begin' keyword is - preceded by a blank line. - - * If the declarations in a subprogram contain at least one nested - subprogram body, then just before the of the enclosing subprogram - `begin', there is a line: - - -- Start of processing for ENCLOSING_SUBPROGRAM - - begin - - -  - File: gnat-style.info, Node: Packages, Next: Program Structure, Prev: Subprograms, Up: Top - - Packages and Visibility Rules - ***************************** - - * All program units and subprograms have their name at the end: - - package P is - ... - end P; - - * We will use the style of `use'-ing `with'-ed packages, with the - context clauses looking like: - - with A; use A; - with B; use B; - - * Names declared in the visible part of packages should be unique, - to prevent name clashes when the packages are `use'd. - - package Entity is - type Entity_Kind is ...; - ... - end Entity; - - * After the file header comment, the context clause and unit - specification should be the first thing in a program_unit. - -  - File: gnat-style.info, Node: Program Structure, Prev: Packages, Up: Top - - Program Structure and Compilation Issues - **************************************** - - * Every GNAT source file must be compiled with the `-gnatg' switch - to check the coding style (Note that you should look at - `style.adb' to see the lexical rules enforced by `-gnatg'). - - * Each source file should contain only one compilation unit. - - * Filenames should be 8 characters or less followed by the `.adb' - extension for a body or `.ads' for a spec. - - * Unit names should be distinct when krunched to 8 characters (see - `krunch.ads') and the filenames should match the unit name, except - that they are all lower case. - - -  - Tag Table: - Node: Top369 - Node: General596 - Node: Lexical Elements1194 - Node: Declarations and Types6078 - Node: Expressions and Names7174 - Node: Statements7659 - Node: Subprograms11650 - Node: Packages13383 - Node: Program Structure14236 -  - End Tag Table --- 0 ---- diff -Nrc3pad gcc-3.3.2/gcc/ada/gnat_rm.info gcc-3.3.3/gcc/ada/gnat_rm.info *** gcc-3.3.2/gcc/ada/gnat_rm.info Thu Oct 16 20:24:02 2003 --- gcc-3.3.3/gcc/ada/gnat_rm.info Thu Jan 1 00:00:00 1970 *************** *** 1,11454 **** - This is ada/gnat_rm.info, produced by makeinfo version 4.2 from - ada/gnat_rm.texi. - - INFO-DIR-SECTION GNU Ada tools - START-INFO-DIR-ENTRY - * GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools. - END-INFO-DIR-ENTRY - - Copyright (C) 1995-2001, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT Reference Manual", and with no Back-Cover - Texts. A copy of the license is included in the section entitled "GNU - Free Documentation License". -  - File: gnat_rm.info, Node: Top, Next: About This Guide, Prev: (dir), Up: (dir) - - GNAT Reference Manual - ********************* - - GNAT Reference Manual - - GNAT, The GNU Ada 95 Compiler - - GNAT Version for GCC 3.3.2 - - Ada Core Technologies, Inc. - - Copyright (C) 1995-2001, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT Reference Manual", and with no Back-Cover - Texts. A copy of the license is included in the section entitled "GNU - Free Documentation License". - * Menu: - - * About This Guide:: - * Implementation Defined Pragmas:: - * Implementation Defined Attributes:: - * Implementation Advice:: - * Implementation Defined Characteristics:: - * Intrinsic Subprograms:: - * Representation Clauses and Pragmas:: - * Standard Library Routines:: - * The Implementation of Standard I/O:: - * The GNAT Library:: - * Interfacing to Other Languages:: - * Machine Code Insertions:: - * GNAT Implementation of Tasking:: - * Code generation for array aggregates:: - * Specialized Needs Annexes:: - * Compatibility Guide:: - * GNU Free Documentation License:: - * Index:: - - --- The Detailed Node Listing --- - - About This Guide - - * What This Reference Manual Contains:: - * Related Information:: - - The Implementation of Standard I/O - - * Standard I/O Packages:: - * FORM Strings:: - * Direct_IO:: - * Sequential_IO:: - * Text_IO:: - * Wide_Text_IO:: - * Stream_IO:: - * Shared Files:: - * Open Modes:: - * Operations on C Streams:: - * Interfacing to C Streams:: - - The GNAT Library - - * Ada.Characters.Latin_9 (a-chlat9.ads):: - * Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: - * Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: - * Ada.Command_Line.Remove (a-colire.ads):: - * Ada.Direct_IO.C_Streams (a-diocst.ads):: - * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: - * Ada.Sequential_IO.C_Streams (a-siocst.ads):: - * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: - * Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: - * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: - * Ada.Text_IO.C_Streams (a-tiocst.ads):: - * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: - * GNAT.AWK (g-awk.ads):: - * GNAT.Bubble_Sort_A (g-busora.ads):: - * GNAT.Bubble_Sort_G (g-busorg.ads):: - * GNAT.Calendar (g-calend.ads):: - * GNAT.Calendar.Time_IO (g-catiio.ads):: - * GNAT.Case_Util (g-casuti.ads):: - * GNAT.CGI (g-cgi.ads):: - * GNAT.CGI.Cookie (g-cgicoo.ads):: - * GNAT.CGI.Debug (g-cgideb.ads):: - * GNAT.Command_Line (g-comlin.ads):: - * GNAT.CRC32 (g-crc32.ads):: - * GNAT.Current_Exception (g-curexc.ads):: - * GNAT.Debug_Pools (g-debpoo.ads):: - * GNAT.Debug_Utilities (g-debuti.ads):: - * GNAT.Directory_Operations (g-dirope.ads):: - * GNAT.Dynamic_Tables (g-dyntab.ads):: - * GNAT.Exception_Traces (g-exctra.ads):: - * GNAT.Expect (g-expect.ads):: - * GNAT.Float_Control (g-flocon.ads):: - * GNAT.Heap_Sort_A (g-hesora.ads):: - * GNAT.Heap_Sort_G (g-hesorg.ads):: - * GNAT.HTable (g-htable.ads):: - * GNAT.IO (g-io.ads):: - * GNAT.IO_Aux (g-io_aux.ads):: - * GNAT.Lock_Files (g-locfil.ads):: - * GNAT.MD5 (g-md5.ads):: - * GNAT.Most_Recent_Exception (g-moreex.ads):: - * GNAT.OS_Lib (g-os_lib.ads):: - * GNAT.Regexp (g-regexp.ads):: - * GNAT.Registry (g-regist.ads):: - * GNAT.Regpat (g-regpat.ads):: - * GNAT.Sockets (g-socket.ads):: - * GNAT.Source_Info (g-souinf.ads):: - * GNAT.Spell_Checker (g-speche.ads):: - * GNAT.Spitbol.Patterns (g-spipat.ads):: - * GNAT.Spitbol (g-spitbo.ads):: - * GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: - * GNAT.Spitbol.Table_Integer (g-sptain.ads):: - * GNAT.Spitbol.Table_VString (g-sptavs.ads):: - * GNAT.Table (g-table.ads):: - * GNAT.Task_Lock (g-tasloc.ads):: - * GNAT.Threads (g-thread.ads):: - * GNAT.Traceback (g-traceb.ads):: - * GNAT.Traceback.Symbolic (g-trasym.ads):: - * Interfaces.C.Extensions (i-cexten.ads):: - * Interfaces.C.Streams (i-cstrea.ads):: - * Interfaces.CPP (i-cpp.ads):: - * Interfaces.Os2lib (i-os2lib.ads):: - * Interfaces.Os2lib.Errors (i-os2err.ads):: - * Interfaces.Os2lib.Synchronization (i-os2syn.ads):: - * Interfaces.Os2lib.Threads (i-os2thr.ads):: - * Interfaces.Packed_Decimal (i-pacdec.ads):: - * Interfaces.VxWorks (i-vxwork.ads):: - * Interfaces.VxWorks.IO (i-vxwoio.ads):: - * System.Address_Image (s-addima.ads):: - * System.Assertions (s-assert.ads):: - * System.Partition_Interface (s-parint.ads):: - * System.Task_Info (s-tasinf.ads):: - * System.Wch_Cnv (s-wchcnv.ads):: - * System.Wch_Con (s-wchcon.ads):: - - Text_IO - - * Text_IO Stream Pointer Positioning:: - * Text_IO Reading and Writing Non-Regular Files:: - * Get_Immediate:: - * Treating Text_IO Files as Streams:: - * Text_IO Extensions:: - * Text_IO Facilities for Unbounded Strings:: - - Wide_Text_IO - - * Wide_Text_IO Stream Pointer Positioning:: - * Wide_Text_IO Reading and Writing Non-Regular Files:: - - Interfacing to Other Languages - - * Interfacing to C:: - * Interfacing to C++:: - * Interfacing to COBOL:: - * Interfacing to Fortran:: - * Interfacing to non-GNAT Ada code:: - - GNAT Implementation of Tasking - - * Mapping Ada Tasks onto the Underlying Kernel Threads:: - * Ensuring Compliance with the Real-Time Annex:: - -  - File: gnat_rm.info, Node: About This Guide, Next: Implementation Defined Pragmas, Prev: Top, Up: Top - - About This Guide - **************** - - This manual contains useful information in writing programs using the - GNAT compiler. It includes information on implementation dependent - characteristics of GNAT, including all the information required by Annex - M of the standard. - - Ada 95 is designed to be highly portable,and guarantees that, for - most programs, Ada 95 compilers behave in exactly the same manner on - different machines. However, since Ada 95 is designed to be used in a - wide variety of applications, it also contains a number of system - dependent features to Functbe used in interfacing to the external world. - - Note: Any program that makes use of implementation-dependent features - may be non-portable. You should follow good programming practice and - isolate and clearly document any sections of your program that make use - of these features in a non-portable manner. - - * Menu: - - * What This Reference Manual Contains:: - * Conventions:: - * Related Information:: - -  - File: gnat_rm.info, Node: What This Reference Manual Contains, Next: Conventions, Up: About This Guide - - What This Reference Manual Contains - =================================== - - This reference manual contains the following chapters: - - * *Note Implementation Defined Pragmas:: lists GNAT - implementation-dependent pragmas, which can be used to extend and - enhance the functionality of the compiler. - - * *Note Implementation Defined Attributes:: lists GNAT - implementation-dependent attributes which can be used to extend and - enhance the functionality of the compiler. - - * *Note Implementation Advice:: provides information on generally - desirable behavior which are not requirements that all compilers - must follow since it cannot be provided on all systems, or which - may be undesirable on some systems. - - * *Note Implementation Defined Characteristics:: provides a guide to - minimizing implementation dependent features. - - * *Note Intrinsic Subprograms:: describes the intrinsic subprograms - implemented by GNAT, and how they can be imported into user - application programs. - - * *Note Representation Clauses and Pragmas:: describes in detail the - way that GNAT represents data, and in particular the exact set of - representation clauses and pragmas that is accepted. - - * *Note Standard Library Routines:: provides a listing of packages - and a brief description of the functionality that is provided by - Ada's extensive set of standard library routines as implemented by - GNAT. - - * *Note The Implementation of Standard I/O:: details how the GNAT - implementation of the input-output facilities. - - * *Note Interfacing to Other Languages:: describes how programs - written in Ada using GNAT can be interfaced to other programming - languages. - - * *Note Specialized Needs Annexes:: describes the GNAT - implementation of all of the special needs annexes. - - * *Note Compatibility Guide:: includes sections on compatibility of - GNAT with other Ada 83 and Ada 95 compilation systems, to assist - in porting code from other environments. - - This reference manual assumes that you are familiar with Ada 95 - language, as described in the International Standard - ANSI/ISO/IEC-8652:1995, Jan 1995. - -  - File: gnat_rm.info, Node: Conventions, Next: Related Information, Prev: What This Reference Manual Contains, Up: About This Guide - - Conventions - =========== - - Following are examples of the typographical and graphic conventions used - in this guide: - - * `Functions', `utility program names', `standard names', and - `classes'. - - * `Option flags' - - * `File Names', `button names', and `field names'. - - * `Variables'. - - * _Emphasis_. - - * [optional information or parameters] - - * Examples are described by text - and then shown this way. - - Commands that are entered by the user are preceded in this manual by the - characters `$ ' (dollar sign followed by space). If your system uses - this sequence as a prompt, then the commands will appear exactly as you - see them in the manual. If your system uses some other prompt, then - the command will appear with the `$' replaced by whatever prompt - character you are using. - -  - File: gnat_rm.info, Node: Related Information, Prev: Conventions, Up: About This Guide - - Related Information - =================== - - See the following documents for further information on GNAT: - - * `GNAT User's Guide', which provides information on how to use the - GNAT compiler system. - - * `Ada 95 Reference Manual', which contains all reference material - for the Ada 95 programming language. - - * `Ada 95 Annotated Reference Manual', which is an annotated version - of the standard reference manual cited above. The annotations - describe detailed aspects of the design decision, and in - particular contain useful sections on Ada 83 compatibility. - - * `DEC Ada, Technical Overview and Comparison on DIGITAL Platforms', - which contains specific information on compatibility between GNAT - and DEC Ada 83 systems. - - * `DEC Ada, Language Reference Manual, part number AA-PYZAB-TK' which - describes in detail the pragmas and attributes provided by the DEC - Ada 83 compiler system. - - -  - File: gnat_rm.info, Node: Implementation Defined Pragmas, Next: Implementation Defined Attributes, Prev: About This Guide, Up: Top - - Implementation Defined Pragmas - ****************************** - - Ada 95 defines a set of pragmas that can be used to supply additional - information to the compiler. These language defined pragmas are - implemented in GNAT and work as described in the Ada 95 Reference - Manual. - - In addition, Ada 95 allows implementations to define additional - pragmas whose meaning is defined by the implementation. GNAT provides - a number of these implementation-dependent pragmas which can be used to - extend and enhance the functionality of the compiler. This section of - the GNAT Reference Manual describes these additional pragmas. - - Note that any program using these pragmas may not be portable to - other compilers (although GNAT implements this set of pragmas on all - platforms). Therefore if portability to other compilers is an important - consideration, the use of these pragmas should be minimized. - - `pragma Abort_Defer' - Syntax: - - pragma Abort_Defer; - - This pragma must appear at the start of the statement sequence of a - handled sequence of statements (right after the `begin'). It has - the effect of deferring aborts for the sequence of statements (but - not for the declarations or handlers, if any, associated with this - statement sequence). - - `pragma Ada_83' - Syntax: - - pragma Ada_83; - - A configuration pragma that establishes Ada 83 mode for the unit to - which it applies, regardless of the mode set by the command line - switches. In Ada 83 mode, GNAT attempts to be as compatible with - the syntax and semantics of Ada 83, as defined in the original Ada - 83 Reference Manual as possible. In particular, the new Ada 95 - keywords are not recognized, optional package bodies are allowed, - and generics may name types with unknown discriminants without - using the `(<>)' notation. In addition, some but not all of the - additional restrictions of Ada 83 are enforced. - - Ada 83 mode is intended for two purposes. Firstly, it allows - existing legacy Ada 83 code to be compiled and adapted to GNAT - with less effort. Secondly, it aids in keeping code backwards - compatible with Ada 83. However, there is no guarantee that code - that is processed correctly by GNAT in Ada 83 mode will in fact - compile and execute with an Ada 83 compiler, since GNAT does not - enforce all the additional checks required by Ada 83. - - `pragma Ada_95' - Syntax: - - pragma Ada_95; - - A configuration pragma that establishes Ada 95 mode for the unit - to which it applies, regardless of the mode set by the command - line switches. This mode is set automatically for the `Ada' and - `System' packages and their children, so you need not specify it - in these contexts. This pragma is useful when writing a reusable - component that itself uses Ada 95 features, but which is intended - to be usable from either Ada 83 or Ada 95 programs. - - `pragma Annotate' - Syntax: - - pragma Annotate (IDENTIFIER {, ARG}); - - ARG ::= NAME | EXPRESSION - - This pragma is used to annotate programs. IDENTIFIER identifies - the type of annotation. GNAT verifies this is an identifier, but - does not otherwise analyze it. The ARG argument can be either a - string literal or an expression. String literals are assumed to - be of type `Standard.String'. Names of entities are simply - analyzed as entity names. All other expressions are analyzed as - expressions, and must be unambiguous. - - The analyzed pragma is retained in the tree, but not otherwise - processed by any part of the GNAT compiler. This pragma is - intended for use by external tools, including ASIS. - - `pragma Assert' - Syntax: - - pragma Assert ( - boolean_EXPRESSION - [, static_string_EXPRESSION]) - - The effect of this pragma depends on whether the corresponding - command line switch is set to activate assertions. The pragma - expands into code equivalent to the following: - - if assertions-enabled then - if not boolean_EXPRESSION then - System.Assertions.Raise_Assert_Failure - (string_EXPRESSION); - end if; - end if; - - The string argument, if given, is the message that will be - associated with the exception occurrence if the exception is - raised. If no second argument is given, the default message is - `FILE:NNN', where FILE is the name of the source file containing - the assert, and NNN is the line number of the assert. A pragma is - not a statement, so if a statement sequence contains nothing but a - pragma assert, then a null statement is required in addition, as - in: - - ... - if J > 3 then - pragma Assert (K > 3, "Bad value for K"); - null; - end if; - - Note that, as with the `if' statement to which it is equivalent, - the type of the expression is either `Standard.Boolean', or any - type derived from this standard type. - - If assertions are disabled (switch `-gnata' not used), then there - is no effect (and in particular, any side effects from the - expression are suppressed). More precisely it is not quite true - that the pragma has no effect, since the expression is analyzed, - and may cause types to be frozen if they are mentioned here for - the first time. - - If assertions are enabled, then the given expression is tested, - and if it is `False' then `System.Assertions.Raise_Assert_Failure' - is called which results in the raising of `Assert_Failure' with - the given message. - - If the boolean expression has side effects, these side effects - will turn on and off with the setting of the assertions mode, - resulting in assertions that have an effect on the program. You - should generally avoid side effects in the expression arguments of - this pragma. However, the expressions are analyzed for semantic - correctness whether or not assertions are enabled, so turning - assertions on and off cannot affect the legality of a program. - - `pragma Ast_Entry' - Syntax: - - pragma AST_Entry (entry_IDENTIFIER); - - This pragma is implemented only in the OpenVMS implementation of - GNAT. The argument is the simple name of a single entry; at most - one `AST_Entry' pragma is allowed for any given entry. This - pragma must be used in conjunction with the `AST_Entry' attribute, - and is only allowed after the entry declaration and in the same - task type specification or single task as the entry to which it - applies. This pragma specifies that the given entry may be used - to handle an OpenVMS asynchronous system trap (`AST') resulting - from an OpenVMS system service call. The pragma does not affect - normal use of the entry. For further details on this pragma, see - the DEC Ada Language Reference Manual, section 9.12a. - - `pragma C_Pass_By_Copy' - Syntax: - - pragma C_Pass_By_Copy - ([Max_Size =>] static_integer_EXPRESSION); - - Normally the default mechanism for passing C convention records to - C convention subprograms is to pass them by reference, as - suggested by RM B.3(69). Use the configuration pragma - `C_Pass_By_Copy' to change this default, by requiring that record - formal parameters be passed by copy if all of the following - conditions are met: - - * The size of the record type does not exceed - STATIC_INTEGER_EXPRESSION. - - * The record type has `Convention C'. - - * The formal parameter has this record type, and the subprogram - has a foreign (non-Ada) convention. - - If these conditions are met the argument is passed by copy, i.e. - in a manner consistent with what C expects if the corresponding - formal in the C prototype is a struct (rather than a pointer to a - struct). - - You can also pass records by copy by specifying the convention - `C_Pass_By_Copy' for the record type, or by using the extended - `Import' and `Export' pragmas, which allow specification of - passing mechanisms on a parameter by parameter basis. - - `pragma Comment' - Syntax: - - pragma Comment (static_string_EXPRESSION); - - This is almost identical in effect to pragma `Ident'. It allows - the placement of a comment into the object file and hence into the - executable file if the operating system permits such usage. The - difference is that `Comment', unlike `Ident', has no limit on the - length of the string argument, and no limitations on placement of - the pragma (it can be placed anywhere in the main source unit). - - `pragma Common_Object' - Syntax: - - pragma Common_Object ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL] ) - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - This pragma enables the shared use of variables stored in overlaid - linker areas corresponding to the use of `COMMON' in Fortran. The - single object LOCAL_NAME is assigned to the area designated by the - EXTERNAL argument. You may define a record to correspond to a - series of fields. The SIZE argument is syntax checked in GNAT, - but otherwise ignored. - - `Common_Object' is not supported on all platforms. If no support - is available, then the code generator will issue a message - indicating that the necessary attribute for implementation of this - pragma is not available. - - `pragma Complex_Representation' - Syntax: - - pragma Complex_Representation - ([Entity =>] LOCAL_NAME); - - The ENTITY argument must be the name of a record type which has - two fields of the same floating-point type. The effect of this - pragma is to force gcc to use the special internal complex - representation form for this record, which may be more efficient. - Note that this may result in the code for this type not conforming - to standard ABI (application binary interface) requirements for - the handling of record types. For example, in some environments, - there is a requirement for passing records by pointer, and the use - of this pragma may result in passing this type in floating-point - registers. - - `pragma Component_Alignment' - Syntax: - - pragma Component_Alignment ( - [Form =>] ALIGNMENT_CHOICE - [, [Name =>] type_LOCAL_NAME]); - - ALIGNMENT_CHOICE ::= - Component_Size - | Component_Size_4 - | Storage_Unit - | Default - - Specifies the alignment of components in array or record types. - The meaning of the FORM argument is as follows: - - `Component_Size' - Aligns scalar components and subcomponents of the array or - record type on boundaries appropriate to their inherent size - (naturally aligned). For example, 1-byte components are - aligned on byte boundaries, 2-byte integer components are - aligned on 2-byte boundaries, 4-byte integer components are - aligned on 4-byte boundaries and so on. These alignment - rules correspond to the normal rules for C compilers on all - machines except the VAX. - - `Component_Size_4' - Naturally aligns components with a size of four or fewer - bytes. Components that are larger than 4 bytes are placed on - the next 4-byte boundary. - - `Storage_Unit' - Specifies that array or record components are byte aligned, - i.e. aligned on boundaries determined by the value of the - constant `System.Storage_Unit'. - - `Default' - Specifies that array or record components are aligned on - default boundaries, appropriate to the underlying hardware or - operating system or both. For OpenVMS VAX systems, the - `Default' choice is the same as the `Storage_Unit' choice - (byte alignment). For all other systems, the `Default' - choice is the same as `Component_Size' (natural alignment). - - If the `Name' parameter is present, TYPE_LOCAL_NAME must refer to - a local record or array type, and the specified alignment choice - applies to the specified type. The use of `Component_Alignment' - together with a pragma `Pack' causes the `Component_Alignment' - pragma to be ignored. The use of `Component_Alignment' together - with a record representation clause is only effective for fields - not specified by the representation clause. - - If the `Name' parameter is absent, the pragma can be used as either - a configuration pragma, in which case it applies to one or more - units in accordance with the normal rules for configuration - pragmas, or it can be used within a declarative part, in which - case it applies to types that are declared within this declarative - part, or within any nested scope within this declarative part. In - either case it specifies the alignment to be applied to any record - or array type which has otherwise standard representation. - - If the alignment for a record or array type is not specified (using - pragma `Pack', pragma `Component_Alignment', or a record rep - clause), the GNAT uses the default alignment as described - previously. - - `pragma Convention_Identifier' - Syntax: - - pragma Convention_Identifier ( - [Name =>] IDENTIFIER, - [Convention =>] convention_IDENTIFIER); - - This pragma provides a mechanism for supplying synonyms for - existing convention identifiers. The `Name' identifier can - subsequently be used as a synonym for the given convention in - other pragmas (including for example pragma `Import' or another - `Convention_Identifier' pragma). As an example of the use of this, - suppose you had legacy code which used Fortran77 as the identifier - for Fortran. Then the pragma: - - pragma Convention_Indentifier (Fortran77, Fortran); - - would allow the use of the convention identifier `Fortran77' in - subsequent code, avoiding the need to modify the sources. As - another example, you could use this to parametrize convention - requirements according to systems. Suppose you needed to use - `Stdcall' on windows systems, and `C' on some other system, then - you could define a convention identifier `Library' and use a single - `Convention_Identifier' pragma to specify which convention would - be used system-wide. - - `pragma CPP_Class' - Syntax: - - pragma CPP_Class ([Entity =>] LOCAL_NAME); - - The argument denotes an entity in the current declarative region - that is declared as a tagged or untagged record type. It - indicates that the type corresponds to an externally declared C++ - class type, and is to be laid out the same way that C++ would lay - out the type. - - If (and only if) the type is tagged, at least one component in the - record must be of type `Interfaces.CPP.Vtable_Ptr', corresponding - to the C++ Vtable (or Vtables in the case of multiple inheritance) - used for dispatching. - - Types for which `CPP_Class' is specified do not have assignment or - equality operators defined (such operations can be imported or - declared as subprograms as required). Initialization is allowed - only by constructor functions (see pragma `CPP_Constructor'). - - Pragma `CPP_Class' is intended primarily for automatic generation - using an automatic binding generator tool. See *Note Interfacing - to C++:: for related information. - - `pragma CPP_Constructor' - Syntax: - - pragma CPP_Constructor ([Entity =>] LOCAL_NAME); - - This pragma identifies an imported function (imported in the usual - way with pragma `Import') as corresponding to a C++ constructor. - The argument is a name that must have been previously mentioned in - a pragma `Import' with `Convention' = `CPP', and must be of one of - the following forms: - - * `function FNAME return T'Class' - - * `function FNAME (...) return T'Class' - - where T is a tagged type to which the pragma `CPP_Class' applies. - - The first form is the default constructor, used when an object of - type T is created on the Ada side with no explicit constructor. - Other constructors (including the copy constructor, which is - simply a special case of the second form in which the one and only - argument is of type T), can only appear in two contexts: - - * On the right side of an initialization of an object of type T. - - * In an extension aggregate for an object of a type derived - from T. - - Although the constructor is described as a function that returns a - value on the Ada side, it is typically a procedure with an extra - implicit argument (the object being initialized) at the - implementation level. GNAT issues the appropriate call, whatever - it is, to get the object properly initialized. - - In the case of derived objects, you may use one of two possible - forms for declaring and creating an object: - - * `New_Object : Derived_T' - - * `New_Object : Derived_T := (CONSTRUCTOR-FUNCTION-CALL WITH - ...)' - - In the first case the default constructor is called and extension - fields if any are initialized according to the default - initialization expressions in the Ada declaration. In the second - case, the given constructor is called and the extension aggregate - indicates the explicit values of the extension fields. - - If no constructors are imported, it is impossible to create any - objects on the Ada side. If no default constructor is imported, - only the initialization forms using an explicit call to a - constructor are permitted. - - Pragma `CPP_Constructor' is intended primarily for automatic - generation using an automatic binding generator tool. See *Note - Interfacing to C++:: for more related information. - - `pragma CPP_Virtual' - Syntax: - - pragma CPP_Virtual - [Entity =>] ENTITY, - [, [Vtable_Ptr =>] vtable_ENTITY,] - [, [Position =>] static_integer_EXPRESSION]) - - This pragma serves the same function as pragma `Import' in that - case of a virtual function imported from C++. The ENTITY argument - must be a primitive subprogram of a tagged type to which pragma - `CPP_Class' applies. The VTABLE_PTR argument specifies the - Vtable_Ptr component which contains the entry for this virtual - function. The POSITION argument is the sequential number counting - virtual functions for this Vtable starting at 1. - - The `Vtable_Ptr' and `Position' arguments may be omitted if there - is one Vtable_Ptr present (single inheritance case) and all - virtual functions are imported. In that case the compiler can - deduce both these values. - - No `External_Name' or `Link_Name' arguments are required for a - virtual function, since it is always accessed indirectly via the - appropriate Vtable entry. - - Pragma `CPP_Virtual' is intended primarily for automatic generation - using an automatic binding generator tool. See *Note Interfacing - to C++:: for related information. - - `pragma CPP_Vtable' - Syntax: - - pragma CPP_Vtable ( - [Entity =>] ENTITY, - [Vtable_Ptr =>] vtable_ENTITY, - [Entry_Count =>] static_integer_EXPRESSION); - - Given a record to which the pragma `CPP_Class' applies, this - pragma can be specified for each component of type - `CPP.Interfaces.Vtable_Ptr'. ENTITY is the tagged type, VTABLE_PTR - is the record field of type `Vtable_Ptr', and ENTRY_COUNT is the - number of virtual functions on the C++ side. Not all of these - functions need to be imported on the Ada side. - - You may omit the `CPP_Vtable' pragma if there is only one - `Vtable_Ptr' component in the record and all virtual functions are - imported on the Ada side (the default value for the entry count in - this case is simply the total number of virtual functions). - - Pragma `CPP_Vtable' is intended primarily for automatic generation - using an automatic binding generator tool. See *Note Interfacing - to C++:: for related information. - - `pragma Debug' - Syntax: - - pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON); - - PROCEDURE_CALL_WITHOUT_SEMICOLON ::= - PROCEDURE_NAME - | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART - - The argument has the syntactic form of an expression, meeting the - syntactic requirements for pragmas. - - If assertions are not enabled on the command line, this pragma has - no effect. If asserts are enabled, the semantics of the pragma is - exactly equivalent to the procedure call statement corresponding - to the argument with a terminating semicolon. Pragmas are - permitted in sequences of declarations, so you can use pragma - `Debug' to intersperse calls to debug procedures in the middle of - declarations. - - `pragma Elaboration_Checks' - Syntax: - - pragma Elaboration_Checks (RM | Static); - - This is a configuration pragma that provides control over the - elaboration model used by the compilation affected by the pragma. - If the parameter is RM, then the dynamic elaboration model - described in the Ada Reference Manual is used, as though the - `-gnatE' switch had been specified on the command line. If the - parameter is Static, then the default GNAT static model is used. - This configuration pragma overrides the setting of the command - line. For full details on the elaboration models used by the GNAT - compiler, see section "Elaboration Order Handling in GNAT" in the - `GNAT User's Guide'. - - `pragma Eliminate' - Syntax: - - pragma Eliminate ( - [Unit_Name =>] IDENTIFIER | - SELECTED_COMPONENT); - - pragma Eliminate ( - [Unit_Name =>] IDENTIFIER | - SELECTED_COMPONENT, - [Entity =>] IDENTIFIER | - SELECTED_COMPONENT | - STRING_LITERAL - [,[Parameter_Types =>] PARAMETER_TYPES] - [,[Result_Type =>] result_SUBTYPE_NAME] - [,[Homonym_Number =>] INTEGER_LITERAL]); - - PARAMETER_TYPES ::= (SUBTYPE_NAME {, SUBTYPE_NAME}) - SUBTYPE_NAME ::= STRING_LITERAL - - This pragma indicates that the given entity is not used outside the - compilation unit it is defined in. The entity may be either a - subprogram or a variable. - - If the entity to be eliminated is a library level subprogram, then - the first form of pragma `Eliminate' is used with only a single - argument. In this form, the `Unit_Name' argument specifies the - name of the library level unit to be eliminated. - - In all other cases, both `Unit_Name' and `Entity' arguments are - required. item is an entity of a library package, then the first - argument specifies the unit name, and the second argument specifies - the particular entity. If the second argument is in string form, - it must correspond to the internal manner in which GNAT stores - entity names (see compilation unit Namet in the compiler sources - for details). - - The remaining parameters are optionally used to distinguish - between overloaded subprograms. There are two ways of doing this. - - Use `Parameter_Types' and `Result_Type' to specify the profile of - the subprogram to be eliminated in a manner similar to that used - for the extended `Import' and `Export' pragmas, except that the - subtype names are always given as string literals, again - corresponding to the internal manner in which GNAT stores entity - names. - - Alternatively, the `Homonym_Number' parameter is used to specify - which overloaded alternative is to be eliminated. A value of 1 - indicates the first subprogram (in lexical order), 2 indicates the - second etc. - - The effect of the pragma is to allow the compiler to eliminate the - code or data associated with the named entity. Any reference to - an eliminated entity outside the compilation unit it is defined in, - causes a compile time or link time error. - - The parameters of this pragma may be given in any order, as long as - the usual rules for use of named parameters and position parameters - are used. - - The intention of pragma `Eliminate' is to allow a program to be - compiled in a system independent manner, with unused entities - eliminated, without the requirement of modifying the source text. - Normally the required set of `Eliminate' pragmas is constructed - automatically using the gnatelim tool. Elimination of unused - entities local to a compilation unit is automatic, without - requiring the use of pragma `Eliminate'. - - Note that the reason this pragma takes string literals where names - might be expected is that a pragma `Eliminate' can appear in a - context where the relevant names are not visible. - - `pragma Export_Exception' - Syntax: - - pragma Export_Exception ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL,] - [, [Form =>] Ada | VMS] - [, [Code =>] static_integer_EXPRESSION]); - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - This pragma is implemented only in the OpenVMS implementation of - GNAT. It causes the specified exception to be propagated outside - of the Ada program, so that it can be handled by programs written - in other OpenVMS languages. This pragma establishes an external - name for an Ada exception and makes the name available to the - OpenVMS Linker as a global symbol. For further details on this - pragma, see the DEC Ada Language Reference Manual, section - 13.9a3.2. - - `pragma Export_Function ...' - Syntax: - - pragma Export_Function ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Result_Type =>] result_SUBTYPE_MARK] - [, [Mechanism =>] MECHANISM] - [, [Result_Mechanism =>] MECHANISM_NAME]); - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - PARAMETER_TYPES ::= - null - | SUBTYPE_MARK {, SUBTYPE_MARK} - - MECHANISM ::= - MECHANISM_NAME - | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) - - MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - - MECHANISM_NAME ::= - Value - | Reference - | Descriptor [([Class =>] CLASS_NAME)] - - CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca - - Use this pragma to make a function externally callable and - optionally provide information on mechanisms to be used for - passing parameter and result values. We recommend, for the - purposes of improving portability, this pragma always be used in - conjunction with a separate pragma `Export', which must precede - the pragma `Export_Function'. GNAT does not require a separate - pragma `Export', but if none is present, `Convention Ada' is - assumed, which is usually not what is wanted, so it is usually - appropriate to use this pragma in conjunction with a `Export' or - `Convention' pragma that specifies the desired foreign convention. - Pragma `Export_Function' (and `Export', if present) must appear in - the same declarative region as the function to which they apply. - - INTERNAL_NAME must uniquely designate the function to which the - pragma applies. If more than one function name exists of this - name in the declarative part you must use the `Parameter_Types' and - `Result_Type' parameters is mandatory to achieve the required - unique designation. SUBTYPE_ MARKs in these parameters must - exactly match the subtypes in the corresponding function - specification, using positional notation to match parameters with - subtype marks. Passing by descriptor is supported only on the - OpenVMS ports of GNAT. - - `pragma Export_Object ...' - Syntax: - - pragma Export_Object - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL] - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - This pragma designates an object as exported, and apart from the - extended rules for external symbols, is identical in effect to the - use of the normal `Export' pragma applied to an object. You may - use a separate Export pragma (and you probably should from the - point of view of portability), but it is not required. SIZE is - syntax checked, but otherwise ignored by GNAT. - - `pragma Export_Procedure ...' - Syntax: - - pragma Export_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - PARAMETER_TYPES ::= - null - | SUBTYPE_MARK {, SUBTYPE_MARK} - - MECHANISM ::= - MECHANISM_NAME - | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) - - MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - - MECHANISM_NAME ::= - Value - | Reference - | Descriptor [([Class =>] CLASS_NAME)] - - CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca - - This pragma is identical to `Export_Function' except that it - applies to a procedure rather than a function and the parameters - `Result_Type' and `Result_Mechanism' are not permitted. GNAT does - not require a separate pragma `Export', but if none is present, - `Convention Ada' is assumed, which is usually not what is wanted, - so it is usually appropriate to use this pragma in conjunction - with a `Export' or `Convention' pragma that specifies the desired - foreign convention. - - `pragma Export_Valued_Procedure' - Syntax: - - pragma Export_Valued_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - PARAMETER_TYPES ::= - null - | SUBTYPE_MARK {, SUBTYPE_MARK} - - MECHANISM ::= - MECHANISM_NAME - | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) - - MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - - MECHANISM_NAME ::= - Value - | Reference - | Descriptor [([Class =>] CLASS_NAME)] - - CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca - - This pragma is identical to `Export_Procedure' except that the - first parameter of LOCAL_NAME, which must be present, must be of - mode `OUT', and externally the subprogram is treated as a function - with this parameter as the result of the function. GNAT provides - for this capability to allow the use of `OUT' and `IN OUT' - parameters in interfacing to external functions (which are not - permitted in Ada functions). GNAT does not require a separate - pragma `Export', but if none is present, `Convention Ada' is - assumed, which is almost certainly not what is wanted since the - whole point of this pragma is to interface with foreign language - functions, so it is usually appropriate to use this pragma in - conjunction with a `Export' or `Convention' pragma that specifies - the desired foreign convention. - - `pragma Extend_System' - Syntax: - - pragma Extend_System ([Name =>] IDENTIFIER); - - This pragma is used to provide backwards compatibility with other - implementations that extend the facilities of package `System'. In - GNAT, `System' contains only the definitions that are present in - the Ada 95 RM. However, other implementations, notably the DEC - Ada 83 implementation, provide many extensions to package `System'. - - For each such implementation accommodated by this pragma, GNAT - provides a package `Aux_XXX', e.g. `Aux_DEC' for the DEC Ada 83 - implementation, which provides the required additional - definitions. You can use this package in two ways. You can - `with' it in the normal way and access entities either by - selection or using a `use' clause. In this case no special - processing is required. - - However, if existing code contains references such as `System.XXX' - where XXX is an entity in the extended definitions provided in - package `System', you may use this pragma to extend visibility in - `System' in a non-standard way that provides greater compatibility - with the existing code. Pragma `Extend_System' is a configuration - pragma whose single argument is the name of the package containing - the extended definition (e.g. `Aux_DEC' for the DEC Ada case). A - unit compiled under control of this pragma will be processed using - special visibility processing that looks in package - `System.Aux_XXX' where `Aux_XXX' is the pragma argument for any - entity referenced in package `System', but not found in package - `System'. - - You can use this pragma either to access a predefined `System' - extension supplied with the compiler, for example `Aux_DEC' or you - can construct your own extension unit following the above - definition. Note that such a package is a child of `System' and - thus is considered part of the implementation. To compile it you - will have to use the appropriate switch for compiling system - units. See the GNAT User's Guide for details. - - `pragma External' - Syntax: - - pragma External ( - [ Convention =>] convention_IDENTIFIER, - [ Entity =>] local_NAME - [, [External_Name =>] static_string_EXPRESSION ] - [, [Link_Name =>] static_string_EXPRESSION ]); - - This pragma is identical in syntax and semantics to pragma - `Export' as defined in the Ada Reference Manual. It is provided - for compatibility with some Ada 83 compilers that used this pragma - for exactly the same purposes as pragma `Export' before the latter - was standardized. - - `pragma External_Name_Casing' - Syntax: - - pragma External_Name_Casing ( - Uppercase | Lowercase - [, Uppercase | Lowercase | As_Is]); - - This pragma provides control over the casing of external names - associated with Import and Export pragmas. There are two cases to - consider: - - Implicit external names - Implicit external names are derived from identifiers. The - most common case arises when a standard Ada 95 Import or - Export pragma is used with only two arguments, as in: - - pragma Import (C, C_Routine); - - Since Ada is a case insensitive language, the spelling of the - identifier in the Ada source program does not provide any - information on the desired casing of the external name, and - so a convention is needed. In GNAT the default treatment is - that such names are converted to all lower case letters. - This corresponds to the normal C style in many environments. - The first argument of pragma `External_Name_Casing' can be - used to control this treatment. If `Uppercase' is specified, - then the name will be forced to all uppercase letters. If - `Lowercase' is specified, then the normal default of all - lower case letters will be used. - - This same implicit treatment is also used in the case of - extended DEC Ada 83 compatible Import and Export pragmas - where an external name is explicitly specified using an - identifier rather than a string. - - Explicit external names - Explicit external names are given as string literals. The - most common case arises when a standard Ada 95 Import or - Export pragma is used with three arguments, as in: - - pragma Import (C, C_Routine, "C_routine"); - - In this case, the string literal normally provides the exact - casing required for the external name. The second argument - of pragma `External_Name_Casing' may be used to modify this - behavior. If `Uppercase' is specified, then the name will be - forced to all uppercase letters. If `Lowercase' is specified, - then the name will be forced to all lowercase letters. A - specification of `As_Is' provides the normal default behavior - in which the casing is taken from the string provided. - - This pragma may appear anywhere that a pragma is valid. In - particular, it can be used as a configuration pragma in the - `gnat.adc' file, in which case it applies to all subsequent - compilations, or it can be used as a program unit pragma, in which - case it only applies to the current unit, or it can be used more - locally to control individual Import/Export pragmas. - - It is primarily intended for use with OpenVMS systems, where many - compilers convert all symbols to upper case by default. For - interfacing to such compilers (e.g. the DEC C compiler), it may be - convenient to use the pragma: - - pragma External_Name_Casing (Uppercase, Uppercase); - - to enforce the upper casing of all external symbols. - - `pragma Finalize_Storage_Only' - Syntax: - - pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); - - This pragma allows the compiler not to emit a Finalize call for - objects defined at the library level. This is mostly useful for - types where finalization is only used to deal with storage - reclamation since in most environments it is not necessary to - reclaim memory just before terminating execution, hence the name. - - `pragma Float_Representation' - Syntax: - - pragma Float_Representation (FLOAT_REP); - - FLOAT_REP ::= VAX_Float | IEEE_Float - - This pragma is implemented only in the OpenVMS implementation of - GNAT. It allows control over the internal representation chosen - for the predefined floating point types declared in the packages - `Standard' and `System'. For further details on this pragma, see - the DEC Ada Language Reference Manual, section 3.5.7a. Note that - to use this pragma, the standard runtime libraries must be - recompiled. See the description of the `GNAT LIBRARY' command in - the OpenVMS version of the GNAT Users Guide for details on the use - of this command. - - `pragma Ident' - Syntax: - - pragma Ident (static_string_EXPRESSION); - - This pragma provides a string identification in the generated - object file, if the system supports the concept of this kind of - identification string. The maximum permitted length of the string - literal is 31 characters. This pragma is allowed only in the - outermost declarative part or declarative items of a compilation - unit. On OpenVMS systems, the effect of the pragma is identical - to the effect of the DEC Ada 83 pragma of the same name. - - `pragma Import_Exception' - Syntax: - - pragma Import_Exception ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL,] - [, [Form =>] Ada | VMS] - [, [Code =>] static_integer_EXPRESSION]); - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - This pragma is implemented only in the OpenVMS implementation of - GNAT. It allows OpenVMS conditions (for example, from OpenVMS - system services or other OpenVMS languages) to be propagated to - Ada programs as Ada exceptions. The pragma specifies that the - exception associated with an exception declaration in an Ada - program be defined externally (in non-Ada code). For further - details on this pragma, see the DEC Ada Language Reference Manual, - section 13.9a.3.1. - - `pragma Import_Function ...' - Syntax: - - pragma Import_Function ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Result_Type =>] SUBTYPE_MARK] - [, [Mechanism =>] MECHANISM] - [, [Result_Mechanism =>] MECHANISM_NAME] - [, [First_Optional_Parameter =>] IDENTIFIER]); - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - PARAMETER_TYPES ::= - null - | SUBTYPE_MARK {, SUBTYPE_MARK} - - MECHANISM ::= - MECHANISM_NAME - | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) - - MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - - MECHANISM_NAME ::= - Value - | Reference - | Descriptor [([Class =>] CLASS_NAME)] - - CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca - - This pragma is used in conjunction with a pragma `Import' to - specify additional information for an imported function. The - pragma `Import' (or equivalent pragma `Interface') must precede the - `Import_Function' pragma and both must appear in the same - declarative part as the function specification. - - The INTERNAL_NAME argument must uniquely designate the function to - which the pragma applies. If more than one function name exists - of this name in the declarative part you must use the - `Parameter_Types' and RESULT_TYPE parameters to achieve the - required unique designation. Subtype marks in these parameters - must exactly match the subtypes in the corresponding function - specification, using positional notation to match parameters with - subtype marks. - - You may optionally use the MECHANISM and RESULT_MECHANISM - parameters to specify passing mechanisms for the parameters and - result. If you specify a single mechanism name, it applies to all - parameters. Otherwise you may specify a mechanism on a parameter - by parameter basis using either positional or named notation. If - the mechanism is not specified, the default mechanism is used. - - Passing by descriptor is supported only on the to OpenVMS ports of - GNAT. - - `First_Optional_Parameter' applies only to OpenVMS ports of GNAT. - It specifies that the designated parameter and all following - parameters are optional, meaning that they are not passed at the - generated code level (this is distinct from the notion of optional - parameters in Ada where the parameters are passed anyway with the - designated optional parameters). All optional parameters must be - of mode `IN' and have default parameter values that are either - known at compile time expressions, or uses of the - `'Null_Parameter' attribute. - - `pragma Import_Object' - Syntax: - - pragma Import_Object - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL], - [, [Size =>] EXTERNAL_SYMBOL]) - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - This pragma designates an object as imported, and apart from the - extended rules for external symbols, is identical in effect to the - use of the normal `Import' pragma applied to an object. Unlike the - subprogram case, you need not use a separate `Import' pragma, - although you may do so (and probably should do so from a - portability point of view). SIZE is syntax checked, but otherwise - ignored by GNAT. - - `pragma Import_Procedure' - Syntax: - - pragma Import_Procedure ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM] - [, [First_Optional_Parameter =>] IDENTIFIER]); - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - PARAMETER_TYPES ::= - null - | SUBTYPE_MARK {, SUBTYPE_MARK} - - MECHANISM ::= - MECHANISM_NAME - | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) - - MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - - MECHANISM_NAME ::= - Value - | Reference - | Descriptor [([Class =>] CLASS_NAME)] - - CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca - - This pragma is identical to `Import_Function' except that it - applies to a procedure rather than a function and the parameters - `Result_Type' and `Result_Mechanism' are not permitted. - - `pragma Import_Valued_Procedure ...' - Syntax: - - pragma Import_Valued_Procedure ( - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM] - [, [First_Optional_Parameter =>] IDENTIFIER]); - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - PARAMETER_TYPES ::= - null - | SUBTYPE_MARK {, SUBTYPE_MARK} - - MECHANISM ::= - MECHANISM_NAME - | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) - - MECHANISM_ASSOCIATION ::= - [formal_parameter_NAME =>] MECHANISM_NAME - - MECHANISM_NAME ::= - Value - | Reference - | Descriptor [([Class =>] CLASS_NAME)] - - CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca - - This pragma is identical to `Import_Procedure' except that the - first parameter of LOCAL_NAME, which must be present, must be of - mode `OUT', and externally the subprogram is treated as a function - with this parameter as the result of the function. The purpose of - this capability is to allow the use of `OUT' and `IN OUT' - parameters in interfacing to external functions (which are not - permitted in Ada functions). You may optionally use the - `Mechanism' parameters to specify passing mechanisms for the - parameters. If you specify a single mechanism name, it applies to - all parameters. Otherwise you may specify a mechanism on a - parameter by parameter basis using either positional or named - notation. If the mechanism is not specified, the default - mechanism is used. - - Note that it is important to use this pragma in conjunction with a - separate pragma Import that specifies the desired convention, - since otherwise the default convention is Ada, which is almost - certainly not what is required. - - `pragma Initialize_Scalars' - Syntax: - - pragma Initialize_Scalars; - - This pragma is similar to `Normalize_Scalars' conceptually but has - two important differences. First, there is no requirement for the - pragma to be used uniformly in all units of a partition, in - particular, it is fine to use this just for some or all of the - application units of a partition, without needing to recompile the - run-time library. - - In the case where some units are compiled with the pragma, and - some without, then a declaration of a variable where the type is - defined in package Standard or is locally declared will always be - subject to initialization, as will any declaration of a scalar - variable. For composite variables, whether the variable is - initialized may also depend on whether the package in which the - type of the variable is declared is compiled with the pragma. - - The other important difference is that there is control over the - value used for initializing scalar objects. At bind time, you can - select whether to initialize with invalid values (like - Normalize_Scalars), or with high or low values, or with a - specified bit pattern. See the users guide for binder options for - specifying these cases. - - This means that you can compile a program, and then without having - to recompile the program, you can run it with different values - being used for initializing otherwise uninitialized values, to - test if your program behavior depends on the choice. Of course - the behavior should not change, and if it does, then most likely - you have an erroneous reference to an uninitialized value. - - Note that pragma `Initialize_Scalars' is particularly useful in - conjunction with the enhanced validity checking that is now - provided in GNAT, which checks for invalid values under more - conditions. Using this feature (see description of the `-gnatv' - flag in the users guide) in conjunction with pragma - `Initialize_Scalars' provides a powerful new tool to assist in the - detection of problems caused by uninitialized variables. - - `pragma Inline_Always' - Syntax: - - pragma Inline_Always (NAME [, NAME]); - - Similar to pragma `Inline' except that inlining is not subject to - the use of option `-gnatn' for inter-unit inlining. - - `pragma Inline_Generic' - Syntax: - - pragma Inline_Generic (generic_package_NAME) - - This is implemented for compatibility with DEC Ada 83 and is - recognized, but otherwise ignored, by GNAT. All generic - instantiations are inlined by default when using GNAT. - - `pragma Interface' - Syntax: - - pragma Interface ( - [Convention =>] convention_identifier, - [Entity =>] local_name - [, [External_Name =>] static_string_expression], - [, [Link_Name =>] static_string_expression]); - - This pragma is identical in syntax and semantics to the standard - Ada 95 pragma `Import'. It is provided for compatibility with Ada - 83. The definition is upwards compatible both with pragma - `Interface' as defined in the Ada 83 Reference Manual, and also - with some extended implementations of this pragma in certain Ada 83 - implementations. - - `pragma Interface_Name' - Syntax: - - pragma Interface_Name ( - [Entity =>] LOCAL_NAME - [, [External_Name =>] static_string_EXPRESSION] - [, [Link_Name =>] static_string_EXPRESSION]); - - This pragma provides an alternative way of specifying the - interface name for an interfaced subprogram, and is provided for - compatibility with Ada 83 compilers that use the pragma for this - purpose. You must provide at least one of EXTERNAL_NAME or - LINK_NAME. - - `pragma License' - Syntax: - - pragma License (Unrestricted | GPL | Modified_GPL | Restricted); - - This pragma is provided to allow automated checking for - appropriate license conditions with respect to the standard and - modified GPL. A pragma `License', which is a configuration pragma - that typically appears at the start of a source file or in a - separate `gnat.adc' file, specifies the licensing conditions of a - unit as follows: - - * Unrestricted This is used for a unit that can be freely used - with no license restrictions. Examples of such units are - public domain units, and units from the Ada Reference Manual. - - * GPL This is used for a unit that is licensed under the - unmodified GPL, and which therefore cannot be `with''ed by a - restricted unit. - - * Modified_GPL This is used for a unit licensed under the GNAT - modified GPL that includes a special exception paragraph that - specifically permits the inclusion of the unit in programs - without requiring the entire program to be released under the - GPL. This is the license used for the GNAT run-time which - ensures that the run-time can be used freely in any program - without GPL concerns. - - * Restricted This is used for a unit that is restricted in that - it is not permitted to depend on units that are licensed - under the GPL. Typical examples are proprietary code that is - to be released under more restrictive license conditions. - Note that restricted units are permitted to `with' units - which are licensed under the modified GPL (this is the whole - point of the modified GPL). - - - Normally a unit with no `License' pragma is considered to have an - unknown license, and no checking is done. However, standard GNAT - headers are recognized, and license information is derived from - them as follows. - - A GNAT license header starts with a line containing 78 - hyphens. The following comment text is searched for the - appearence of any of the following strings. - - If the string "GNU General Public License" is found, then the - unit is assumed to have GPL license, unless the string "As a - special exception" follows, in which case the license is - assumed to be modified GPL. - - If one of the strings "This specification is adapated from - the Ada Semantic Interface" or "This specification is derived - from the Ada Reference Manual" is found then the unit is - assumed to be unrestricted. - - These default actions means that a program with a restricted - license pragma will automatically get warnings if a GPL unit is - inappropriately `with''ed. For example, the program: - - with Sem_Ch3; - with GNAT.Sockets; - procedure Secret_Stuff is - ... - end Secret_Stuff - - if compiled with pragma `License' (`Restricted') in a `gnat.adc' - file will generate the warning: - - 1. with Sem_Ch3; - | - >>> license of withed unit "Sem_Ch3" is incompatible - - 2. with GNAT.Sockets; - 3. procedure Secret_Stuff is - - Here we get a warning on `Sem_Ch3' since it is part of the GNAT - compiler and is licensed under the GPL, but no warning for - `GNAT.Sockets' which is part of the GNAT run time, and is - therefore licensed under the modified GPL. - - `pragma Link_With' - Syntax: - - pragma Link_With (static_string_EXPRESSION {,static_string_EXPRESSION}); - - This pragma is provided for compatibility with certain Ada 83 - compilers. It has exactly the same effect as pragma - `Linker_Options' except that spaces occurring within one of the - string expressions are treated as separators. For example, in the - following case: - - pragma Link_With ("-labc -ldef"); - - results in passing the strings `-labc' and `-ldef' as two separate - arguments to the linker. In addition pragma Link_With allows - multiple arguments, with the same effect as successive pragmas. - - `pragma Linker_Alias' - Syntax: - - pragma Linker_Alias ( - [Entity =>] LOCAL_NAME - [Alias =>] static_string_EXPRESSION); - - This pragma establishes a linker alias for the given named entity. - For further details on the exact effect, consult the GCC manual. - - `pragma Linker_Section' - Syntax: - - pragma Linker_Section ( - [Entity =>] LOCAL_NAME - [Section =>] static_string_EXPRESSION); - - This pragma specifies the name of the linker section for the given - entity. For further details on the exact effect, consult the GCC - manual. - - `pragma No_Run_Time' - Syntax: - - pragma No_Run_Time; - - This is a configuration pragma that makes sure the user code does - not use nor need anything from the GNAT run time. This is mostly - useful in context where code certification is required. Please - consult the `GNAT Pro High-Integrity Edition User's Guide' for - additional information. - - `pragma Normalize_Scalars' - Syntax: - - pragma Normalize_Scalars; - - This is a language defined pragma which is fully implemented in - GNAT. The effect is to cause all scalar objects that are not - otherwise initialized to be initialized. The initial values are - implementation dependent and are as follows: - - `Standard.Character' - Objects whose root type is Standard.Character are initialized - to Character'Last. This will be out of range of the subtype - only if the subtype range excludes this value. - - `Standard.Wide_Character' - Objects whose root type is Standard.Wide_Character are - initialized to Wide_Character'Last. This will be out of - range of the subtype only if the subtype range excludes this - value. - - `Integer types' - Objects of an integer type are initialized to - base_type'First, where base_type is the base type of the - object type. This will be out of range of the subtype only - if the subtype range excludes this value. For example, if - you declare the subtype: - - subtype Ityp is integer range 1 .. 10; - - then objects of type x will be initialized to Integer'First, - a negative number that is certainly outside the range of - subtype `Ityp'. - - `Real types' - Objects of all real types (fixed and floating) are - initialized to base_type'First, where base_Type is the base - type of the object type. This will be out of range of the - subtype only if the subtype range excludes this value. - - `Modular types' - Objects of a modular type are initialized to typ'Last. This - will be out of range of the subtype only if the subtype - excludes this value. - - `Enumeration types' - Objects of an enumeration type are initialized to all - one-bits, i.e. to the value `2 ** typ'Size - 1'. This will - be out of range of the enumeration subtype in all cases - except where the subtype contains exactly 2**8, 2**16, or - 2**32 elements. - - `pragma Long_Float' - Syntax: - - pragma Long_Float (FLOAT_FORMAT); - - FLOAT_FORMAT ::= D_Float | G_Float - - This pragma is implemented only in the OpenVMS implementation of - GNAT. It allows control over the internal representation chosen - for the predefined type `Long_Float' and for floating point type - representations with `digits' specified in the range 7 through 15. - For further details on this pragma, see the `DEC Ada Language - Reference Manual', section 3.5.7b. Note that to use this pragma, - the standard runtime libraries must be recompiled. See the - description of the `GNAT LIBRARY' command in the OpenVMS version - of the GNAT User's Guide for details on the use of this command. - - `pragma Machine_Attribute ...' - Syntax: - - pragma Machine_Attribute ( - [Attribute_Name =>] string_EXPRESSION, - [Entity =>] LOCAL_NAME); - - Machine dependent attributes can be specified for types and/or - declarations. Currently only subprogram entities are supported. - This pragma is semantically equivalent to - `__attribute__((STRING_EXPRESSION))' in GNU C, where - `STRING_EXPRESSION' is recognized by the GNU C macros - `VALID_MACHINE_TYPE_ATTRIBUTE' and `VALID_MACHINE_DECL_ATTRIBUTE' - which are defined in the configuration header file `tm.h' for each - machine. See the GCC manual for further information. - - `pragma Main_Storage' - Syntax: - - pragma Main_Storage - (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); - - MAIN_STORAGE_OPTION ::= - [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION - | [TOP_GUARD =>] static_SIMPLE_EXPRESSION - - This pragma is provided for compatibility with OpenVMS Vax - Systems. It has no effect in GNAT, other than being syntax - checked. Note that the pragma also has no effect in DEC Ada 83 - for OpenVMS Alpha Systems. - - `pragma No_Return' - Syntax: - - pragma No_Return (procedure_LOCAL_NAME); - - PROCEDURE_LOCAL_NAME must refer to one or more procedure - declarations in the current declarative part. A procedure to - which this pragma is applied may not contain any explicit `return' - statements, and also may not contain any implicit return - statements from falling off the end of a statement sequence. One - use of this pragma is to identify procedures whose only purpose is - to raise an exception. - - Another use of this pragma is to suppress incorrect warnings about - missing returns in functions, where the last statement of a - function statement sequence is a call to such a procedure. - - `pragma Passive' - Syntax: - - pragma Passive ([Semaphore | No]); - - Syntax checked, but otherwise ignored by GNAT. This is recognized - for compatibility with DEC Ada 83 implementations, where it is - used within a task definition to request that a task be made - passive. If the argument `Semaphore' is present, or no argument - is omitted, then DEC Ada 83 treats the pragma as an assertion that - the containing task is passive and that optimization of context - switch with this task is permitted and desired. If the argument - `No' is present, the task must not be optimized. GNAT does not - attempt to optimize any tasks in this manner (since protected - objects are available in place of passive tasks). - - `pragma Polling' - Syntax: - - pragma Polling (ON | OFF); - - This pragma controls the generation of polling code. This is - normally off. If `pragma Polling (ON)' is used then periodic - calls are generated to the routine `Ada.Exceptions.Poll'. This - routine is a separate unit in the runtime library, and can be - found in file `a-excpol.adb'. - - Pragma `Polling' can appear as a configuration pragma (for example - it can be placed in the `gnat.adc' file) to enable polling - globally, or it can be used in the statement or declaration - sequence to control polling more locally. - - A call to the polling routine is generated at the start of every - loop and at the start of every subprogram call. This guarantees - that the `Poll' routine is called frequently, and places an upper - bound (determined by the complexity of the code) on the period - between two `Poll' calls. - - The primary purpose of the polling interface is to enable - asynchronous aborts on targets that cannot otherwise support it - (for example Windows NT), but it may be used for any other purpose - requiring periodic polling. The standard version is null, and can - be replaced by a user program. This will require re-compilation - of the `Ada.Exceptions' package that can be found in files - `a-except.ads' and `a-except.adb'. - - A standard alternative unit (in file `4wexcpol.adb' in the - standard GNAT distribution) is used to enable the asynchronous - abort capability on targets that do not normally support the - capability. The version of `Poll' in this file makes a call to - the appropriate runtime routine to test for an abort condition. - - Note that polling can also be enabled by use of the `-gnatP' - switch. See the `GNAT User's Guide' for details. - - `pragma Propagate_Exceptions' - Syntax: - - pragma Propagate_Exceptions (subprogram_LOCAL_NAME); - - This pragma indicates that the given entity, which is the name of - an imported foreign-language subprogram may receive an Ada - exception, and that the exception should be propagated. It is - relevant only if zero cost exception handling is in use, and is - thus never needed if the alternative `longjmp' / `setjmp' - implementation of exceptions is used (although it is harmless to - use it in such cases). - - The implementation of fast exceptions always properly propagates - exceptions through Ada code, as described in the Ada Reference - Manual. However, this manual is silent about the propagation of - exceptions through foreign code. For example, consider the - situation where `P1' calls `P2', and `P2' calls `P3', where `P1' - and `P3' are in Ada, but `P2' is in C. `P3' raises an Ada - exception. The question is whether or not it will be propagated - through `P2' and can be handled in `P1'. - - For the `longjmp' / `setjmp' implementation of exceptions, the - answer is always yes. For some targets on which zero cost - exception handling is implemented, the answer is also always yes. - However, there are some targets, notably in the current version - all x86 architecture targets, in which the answer is that such - propagation does not happen automatically. If such propagation is - required on these targets, it is mandatory to use - `Propagate_Exceptions' to name all foreign language routines - through which Ada exceptions may be propagated. - - `pragma Psect_Object' - Syntax: - - pragma Psect_Object - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL] - - EXTERNAL_SYMBOL ::= - IDENTIFIER - | static_string_EXPRESSION - - This pragma is identical in effect to pragma `Common_Object'. - - `pragma Pure_Function' - Syntax: - - pragma Pure_Function ([Entity =>] function_LOCAL_NAME); - - This pragma appears in the same declarative part as a function - declaration (or a set of function declarations if more than one - overloaded declaration exists, in which case the pragma applies to - all entities). If specifies that the function `Entity' is to be - considered pure for the purposes of code generation. This means - that the compiler can assume that there are no side effects, and - in particular that two calls with identical arguments produce the - same result. It also means that the function can be used in an - address clause. - - Note that, quite deliberately, there are no static checks to try - to ensure that this promise is met, so `Pure_Function' can be used - with functions that are conceptually pure, even if they do modify - global variables. For example, a square root function that is - instrumented to count the number of times it is called is still - conceptually pure, and can still be optimized, even though it - modifies a global variable (the count). Memo functions are another - example (where a table of previous calls is kept and consulted to - avoid re-computation). - - Note: Most functions in a `Pure' package are automatically pure, - and there is no need to use pragma `Pure_Function' for such - functions. An exception is any function that has at least one - formal of type `System.Address' or a type derived from it. Such - functions are not considered pure by default, since the compiler - assumes that the `Address' parameter may be functioning as a - pointer and that the referenced data may change even if the - address value does not. The use of pragma `Pure_Function' for - such a function will override this default assumption, and cause - the compiler to treat such a function as pure. - - Note: If pragma `Pure_Function' is applied to a renamed function, - it applies to the underlying renamed function. This can be used to - disambiguate cases of overloading where some but not all functions - in a set of overloaded functions are to be designated as pure. - - `pragma Ravenscar' - Syntax: - - pragma Ravenscar - - A configuration pragma that establishes the following set of - restrictions: - - `No_Abort_Statements' - [RM D.7] There are no abort_statements, and there are no - calls to Task_Identification.Abort_Task. - - `No_Select_Statements' - There are no select_statements. - - `No_Task_Hierarchy' - [RM D.7] All (non-environment) tasks depend directly on the - environment task of the partition. - - `No_Task_Allocators' - [RM D.7] There are no allocators for task types or types - containing task subcomponents. - - `No_Dynamic_Priorities' - [RM D.7] There are no semantic dependencies on the package - Dynamic_Priorities. - - `No_Terminate_Alternatives' - [RM D.7] There are no selective_accepts with - terminate_alternatives - - `No_Dynamic_Interrupts' - There are no semantic dependencies on Ada.Interrupts. - - `No_Protected_Type_Allocators' - There are no allocators for protected types or types - containing protected subcomponents. - - `No_Local_Protected_Objects' - Protected objects and access types that designate such - objects shall be declared only at library level. - - `No_Requeue' - Requeue statements are not allowed. - - `No_Calendar' - There are no semantic dependencies on the package - Ada.Calendar. - - `No_Relative_Delay' - There are no delay_relative_statements. - - `No_Task_Attributes' - There are no semantic dependencies on the Ada.Task_Attributes - package and there are no references to the attributes - Callable and Terminated [RM 9.9]. - - `Static_Storage_Size' - The expression for pragma Storage_Size is static. - - `Boolean_Entry_Barriers' - Entry barrier condition expressions shall be boolean objects - which are declared in the protected type which contains the - entry. - - `Max_Asynchronous_Select_Nesting = 0' - [RM D.7] Specifies the maximum dynamic nesting level of - asynchronous_selects. A value of zero prevents the use of - any asynchronous_select. - - `Max_Task_Entries = 0' - [RM D.7] Specifies the maximum number of entries per task. - The bounds of every entry family of a task unit shall be - static, or shall be defined by a discriminant of a subtype - whose corresponding bound is static. A value of zero - indicates that no rendezvous are possible. For the Ravenscar - pragma, the value of Max_Task_Entries is always 0 (zero). - - `Max_Protected_Entries = 1' - [RM D.7] Specifies the maximum number of entries per - protected type. The bounds of every entry family of a - protected unit shall be static, or shall be defined by a - discriminant of a subtype whose corresponding bound is - static. For the Ravenscar pragma the value of - Max_Protected_Entries is always 1. - - `Max_Select_Alternatives = 0' - [RM D.7] Specifies the maximum number of alternatives in a - selective_accept. For the Ravenscar pragma the value if - always 0. - - `No_Task_Termination' - Tasks which terminate are erroneous. - - `No_Entry_Queue' - No task can be queued on a protected entry. Note that this - restrictions is checked at run time. The violation of this - restriction generates a Program_Error exception. - - This set of restrictions corresponds to the definition of the - "Ravenscar Profile" for limited tasking, devised and published by - the `International Real-Time Ada Workshop', 1997. - - The above set is a superset of the restrictions provided by pragma - `Restricted_Run_Time', it includes six additional restrictions - (`Boolean_Entry_Barriers', `No_Select_Statements', `No_Calendar', - `Static_Storage_Size', `No_Relative_Delay' and - `No_Task_Termination'). This means that pragma `Ravenscar', like - the pragma `Restricted_Run_Time', automatically causes the use of - a simplified, more efficient version of the tasking run-time - system. - - `pragma Restricted_Run_Time' - Syntax: - - pragma Restricted_Run_Time - - A configuration pragma that establishes the following set of - restrictions: - - * No_Abort_Statements - - * No_Asynchronous_Control - - * No_Entry_Queue - - * No_Task_Hierarchy - - * No_Task_Allocators - - * No_Dynamic_Priorities - - * No_Terminate_Alternatives - - * No_Dynamic_Interrupts - - * No_Protected_Type_Allocators - - * No_Local_Protected_Objects - - * No_Requeue - - * No_Task_Attributes - - * Max_Asynchronous_Select_Nesting = 0 - - * Max_Task_Entries = 0 - - * Max_Protected_Entries = 1 - - * Max_Select_Alternatives = 0 - - This set of restrictions causes the automatic selection of a - simplified version of the run time that provides improved - performance for the limited set of tasking functionality permitted - by this set of restrictions. - - `pragma Share_Generic' - Syntax: - - pragma Share_Generic (NAME {, NAME}); - - This pragma is recognized for compatibility with other Ada - compilers but is ignored by GNAT. GNAT does not provide the - capability for sharing of generic code. All generic - instantiations result in making an inlined copy of the template - with appropriate substitutions. - - `pragma Source_File_Name' - Syntax: - - pragma Source_File_Name ( - [Unit_Name =>] unit_NAME, - Spec_File_Name => STRING_LITERAL); - - pragma Source_File_Name ( - [Unit_Name =>] unit_NAME, - Body_File_Name => STRING_LITERAL); - - Use this to override the normal naming convention. It is a - configuration pragma, and so has the usual applicability of - configuration pragmas (i.e. it applies to either an entire - partition, or to all units in a compilation, or to a single unit, - depending on how it is used. UNIT_NAME is mapped to - FILE_NAME_LITERAL. The identifier for the second argument is - required, and indicates whether this is the file name for the spec - or for the body. - - Another form of the `Source_File_Name' pragma allows the - specification of patterns defining alternative file naming schemes - to apply to all files. - - pragma Source_File_Name - (Spec_File_Name => STRING_LITERAL - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name - (Body_File_Name => STRING_LITERAL - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name - (Subunit_File_Name => STRING_LITERAL - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - CASING_SPEC ::= Lowercase | Uppercase | Mixedcase - - The first argument is a pattern that contains a single asterisk - indicating the point at which the unit name is to be inserted in - the pattern string to form the file name. The second argument is - optional. If present it specifies the casing of the unit name in - the resulting file name string. The default is lower case. - Finally the third argument allows for systematic replacement of - any dots in the unit name by the specified string literal. - - For more details on the use of the `Source_File_Name' pragma, see - the sections "Using Other File Names" and "Alternative File Naming - Schemes" in the `GNAT User's Guide'. - - `pragma Source_Reference' - Syntax: - - pragma Source_Reference (INTEGER_LITERAL, - STRING_LITERAL); - - This pragma must appear as the first line of a source file. - INTEGER_LITERAL is the logical line number of the line following - the pragma line (for use in error messages and debugging - information). STRING_LITERAL is a static string constant that - specifies the file name to be used in error messages and debugging - information. This is most notably used for the output of - `gnatchop' with the `-r' switch, to make sure that the original - unchopped source file is the one referred to. - - The second argument must be a string literal, it cannot be a static - string expression other than a string literal. This is because - its value is needed for error messages issued by all phases of the - compiler. - - `pragma Stream_Convert' - Syntax: - - pragma Stream_Convert ( - [Entity =>] type_LOCAL_NAME, - [Read =>] function_NAME, - [Write =>] function NAME); - - This pragma provides an efficient way of providing stream - functions for types defined in packages. Not only is it simpler - to use than declaring the necessary functions with attribute - representation clauses, but more significantly, it allows the - declaration to made in such a way that the stream packages are not - loaded unless they are needed. The use of the Stream_Convert - pragma adds no overhead at all, unless the stream attributes are - actually used on the designated type. - - The first argument specifies the type for which stream functions - are provided. The second parameter provides a function used to - read values of this type. It must name a function whose argument - type may be any subtype, and whose returned type must be the type - given as the first argument to the pragma. - - The meaning of the READ parameter is that if a stream attribute - directly or indirectly specifies reading of the type given as the - first parameter, then a value of the type given as the argument to - the Read function is read from the stream, and then the Read - function is used to convert this to the required target type. - - Similarly the WRITE parameter specifies how to treat write - attributes that directly or indirectly apply to the type given as - the first parameter. It must have an input parameter of the type - specified by the first parameter, and the return type must be the - same as the input type of the Read function. The effect is to - first call the Write function to convert to the given stream type, - and then write the result type to the stream. - - The Read and Write functions must not be overloaded subprograms. - If necessary renamings can be supplied to meet this requirement. - The usage of this attribute is best illustrated by a simple - example, taken from the GNAT implementation of package - Ada.Strings.Unbounded: - - function To_Unbounded (S : String) - return Unbounded_String - renames To_Unbounded_String; - - pragma Stream_Convert - (Unbounded_String, To_Unbounded, To_String); - - The specifications of the referenced functions, as given in the - Ada 95 Reference Manual are: - - function To_Unbounded_String (Source : String) - return Unbounded_String; - - function To_String (Source : Unbounded_String) - return String; - - The effect is that if the value of an unbounded string is written - to a stream, then the representation of the item in the stream is - in the same format used for `Standard.String', and this same - representation is expected when a value of this type is read from - the stream. - - `pragma Style_Checks' - Syntax: - - pragma Style_Checks (string_LITERAL | ALL_CHECKS | - On | Off [, LOCAL_NAME]); - - This pragma is used in conjunction with compiler switches to - control the built in style checking provided by GNAT. The - compiler switches, if set provide an initial setting for the - switches, and this pragma may be used to modify these settings, or - the settings may be provided entirely by the use of the pragma. - This pragma can be used anywhere that a pragma is legal, including - use as a configuration pragma (including use in the `gnat.adc' - file). - - The form with a string literal specifies which style options are - to be activated. These are additive, so they apply in addition to - any previously set style check options. The codes for the options - are the same as those used in the `-gnaty' switch to `gcc' or - `gnatmake'. For example the following two methods can be used to - enable layout checking: - - pragma Style_Checks ("l"); - gcc -c -gnatyl ... - - The form ALL_CHECKS activates all standard checks (its use is - equivalent to the use of the `gnaty' switch with no options. See - GNAT User's Guide for details. - - The forms with `Off' and `On' can be used to temporarily disable - style checks as shown in the following example: - - pragma Style_Checks ("k"); -- requires keywords in lower case - pragma Style_Checks (Off); -- turn off style checks - NULL; -- this will not generate an error message - pragma Style_Checks (On); -- turn style checks back on - NULL; -- this will generate an error message - - Finally the two argument form is allowed only if the first - argument is `On' or `Off'. The effect is to turn of semantic - style checks for the specified entity, as shown in the following - example: - - pragma Style_Checks ("r"); -- require consistency of identifier casing - Arg : Integer; - Rf1 : Integer := ARG; -- incorrect, wrong case - pragma Style_Checks (Off, Arg); - Rf2 : Integer := ARG; -- OK, no error - - `pragma Subtitle' - Syntax: - - pragma Subtitle ([Subtitle =>] STRING_LITERAL); - - This pragma is recognized for compatibility with other Ada - compilers but is ignored by GNAT. - - `pragma Suppress_All' - Syntax: - - pragma Suppress_All; - - This pragma can only appear immediately following a compilation - unit. The effect is to apply `Suppress (All_Checks)' to the unit - which it follows. This pragma is implemented for compatibility - with DEC Ada 83 usage. The use of pragma `Suppress (All_Checks)' - as a normal configuration pragma is the preferred usage in GNAT. - - `pragma Suppress_Initialization' - Syntax: - - pragma Suppress_Initialization ([Entity =>] type_Name); - - This pragma suppresses any implicit or explicit initialization - associated with the given type name for all variables of this type. - - `pragma Task_Info' - Syntax - - pragma Task_Info (EXPRESSION); - - This pragma appears within a task definition (like pragma - `Priority') and applies to the task in which it appears. The - argument must be of type `System.Task_Info.Task_Info_Type'. The - `Task_Info' pragma provides system dependent control over aspect - of tasking implementation, for example, the ability to map tasks - to specific processors. For details on the facilities available - for the version of GNAT that you are using, see the documentation - in the specification of package System.Task_Info in the runtime - library. - - `pragma Task_Name' - Syntax - - pragma Task_Name (string_EXPRESSION); - - This pragma appears within a task definition (like pragma - `Priority') and applies to the task in which it appears. The - argument must be of type String, and provides a name to be used for - the task instance when the task is created. Note that this - expression is not required to be static, and in particular, it can - contain references to task discriminants. This facility can be - used to provide different names for different tasks as they are - created, as illustrated in the example below. - - The task name is recorded internally in the run-time structures - and is accessible to tools like the debugger. In addition the - routine `Ada.Task_Identification.Image' will return this string, - with a unique task address appended. - - -- Example of the use of pragma Task_Name - - with Ada.Task_Identification; - use Ada.Task_Identification; - with Text_IO; use Text_IO; - procedure t3 is - - type Astring is access String; - - task type Task_Typ (Name : access String) is - pragma Task_Name (Name.all); - end Task_Typ; - - task body Task_Typ is - Nam : constant String := Image (Current_Task); - begin - Put_Line ("-->" & Nam (1 .. 14) & "<--"); - end Task_Typ; - - type Ptr_Task is access Task_Typ; - Task_Var : Ptr_Task; - - begin - Task_Var := - new Task_Typ (new String'("This is task 1")); - Task_Var := - new Task_Typ (new String'("This is task 2")); - end; - - `pragma Task_Storage' - Syntax: - - pragma Task_Storage - [Task_Type =>] LOCAL_NAME, - [Top_Guard =>] static_integer_EXPRESSION); - - This pragma specifies the length of the guard area for tasks. The - guard area is an additional storage area allocated to a task. A - value of zero means that either no guard area is created or a - minimal guard area is created, depending on the target. This - pragma can appear anywhere a `Storage_Size' attribute definition - clause is allowed for a task type. - - `pragma Time_Slice' - Syntax: - - pragma Time_Slice (static_duration_EXPRESSION); - - For implementations of GNAT on operating systems where it is - possible to supply a time slice value, this pragma may be used for - this purpose. It is ignored if it is used in a system that does - not allow this control, or if it appears in other than the main - program unit. Note that the effect of this pragma is identical to - the effect of the DEC Ada 83 pragma of the same name when - operating under OpenVMS systems. - - `pragma Title' - Syntax: - - pragma Title (TITLING_OPTION [, TITLING OPTION]); - - TITLING_OPTION ::= - [Title =>] STRING_LITERAL, - | [Subtitle =>] STRING_LITERAL - - Syntax checked but otherwise ignored by GNAT. This is a listing - control pragma used in DEC Ada 83 implementations to provide a - title and/or subtitle for the program listing. The program - listing generated by GNAT does not have titles or subtitles. - - Unlike other pragmas, the full flexibility of named notation is - allowed for this pragma, i.e. the parameters may be given in any - order if named notation is used, and named and positional notation - can be mixed following the normal rules for procedure calls in Ada. - - `pragma Unchecked_Union' - Syntax: - - pragma Unchecked_Union (first_subtype_LOCAL_NAME) - - This pragma is used to declare that the specified type should be - represented in a manner equivalent to a C union type, and is - intended only for use in interfacing with C code that uses union - types. In Ada terms, the named type must obey the following rules: - - * It is a non-tagged non-limited record type. - - * It has a single discrete discriminant with a default value. - - * The component list consists of a single variant part. - - * Each variant has a component list with a single component. - - * No nested variants are allowed. - - * No component has an explicit default value. - - * No component has a non-static constraint. - - In addition, given a type that meets the above requirements, the - following restrictions apply to its use throughout the program: - - * The discriminant name can be mentioned only in an aggregate. - - * No subtypes may be created of this type. - - * The type may not be constrained by giving a discriminant - value. - - * The type cannot be passed as the actual for a generic formal - with a discriminant. - - Equality and inequality operations on `unchecked_unions' are not - available, since there is no discriminant to compare and the - compiler does not even know how many bits to compare. It is - implementation dependent whether this is detected at compile time - as an illegality or whether it is undetected and considered to be - an erroneous construct. In GNAT, a direct comparison is illegal, - but GNAT does not attempt to catch the composite case (where two - composites are compared that contain an unchecked union - component), so such comparisons are simply considered erroneous. - - The layout of the resulting type corresponds exactly to a C union, - where each branch of the union corresponds to a single variant in - the Ada record. The semantics of the Ada program is not changed - in any way by the pragma, i.e. provided the above restrictions are - followed, and no erroneous incorrect references to fields or - erroneous comparisons occur, the semantics is exactly as described - by the Ada reference manual. Pragma `Suppress - (Discriminant_Check)' applies implicitly to the type and the - default convention is C - - `pragma Unimplemented_Unit' - Syntax: - - pragma Unimplemented_Unit; - - If this pragma occurs in a unit that is processed by the compiler, - GNAT aborts with the message `XXX not implemented', where XXX is - the name of the current compilation unit. This pragma is intended - to allow the compiler to handle unimplemented library units in a - clean manner. - - The abort only happens if code is being generated. Thus you can - use specs of unimplemented packages in syntax or semantic checking - mode. - - `pragma Unreferenced' - Syntax: - - pragma Unreferenced (local_Name {, local_Name}); - - This pragma signals that the entities whose names are listed are - deliberately not referenced. This suppresses warnings about the - entities being unreferenced, and in addition a warning will be - generated if one of these entities is in fact referenced. - - This is particularly useful for clearly signalling that a - particular parameter is not referenced in some particular - subprogram implementation and that this is deliberate. It can also - be useful in the case of objects declared only for their - initialization or finalization side effects. - - If `local_Name' identifies more than one matching homonym in the - current scope, then the entity most recently declared is the one - to which the pragma applies. - - `pragma Unreserve_All_Interrupts' - Syntax: - - pragma Unreserve_All_Interrupts; - - Normally certain interrupts are reserved to the implementation. - Any attempt to attach an interrupt causes Program_Error to be - raised, as described in RM C.3.2(22). A typical example is the - `SIGINT' interrupt used in many systems for an `Ctrl-C' interrupt. - Normally this interrupt is reserved to the implementation, so - that `Ctrl-C' can be used to interrupt execution. - - If the pragma `Unreserve_All_Interrupts' appears anywhere in any - unit in a program, then all such interrupts are unreserved. This - allows the program to handle these interrupts, but disables their - standard functions. For example, if this pragma is used, then - pressing `Ctrl-C' will not automatically interrupt execution. - However, a program can then handle the `SIGINT' interrupt as it - chooses. - - For a full list of the interrupts handled in a specific - implementation, see the source code for the specification of - `Ada.Interrupts.Names' in file `a-intnam.ads'. This is a target - dependent file that contains the list of interrupts recognized for - a given target. The documentation in this file also specifies - what interrupts are affected by the use of the - `Unreserve_All_Interrupts' pragma. - - `pragma Unsuppress' - Syntax: - - pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); - - This pragma undoes the effect of a previous pragma `Suppress'. If - there is no corresponding pragma `Suppress' in effect, it has no - effect. The range of the effect is the same as for pragma - `Suppress'. The meaning of the arguments is identical to that used - in pragma `Suppress'. - - One important application is to ensure that checks are on in cases - where code depends on the checks for its correct functioning, so - that the code will compile correctly even if the compiler switches - are set to suppress checks. - - `pragma Use_VADS_Size' - Syntax: - - pragma Use_VADS_Size; - - This is a configuration pragma. In a unit to which it applies, - any use of the 'Size attribute is automatically interpreted as a - use of the 'VADS_Size attribute. Note that this may result in - incorrect semantic processing of valid Ada 95 programs. This is - intended to aid in the handling of legacy code which depends on - the interpretation of Size as implemented in the VADS compiler. - See description of the VADS_Size attribute for further details. - - `pragma Validity_Checks' - Syntax: - - pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); - - This pragma is used in conjunction with compiler switches to - control the built in validity checking provided by GNAT. The - compiler switches, if set provide an initial setting for the - switches, and this pragma may be used to modify these settings, or - the settings may be provided entirely by the use of the pragma. - This pragma can be used anywhere that a pragma is legal, including - use as a configuration pragma (including use in the `gnat.adc' - file). - - The form with a string literal specifies which validity options - are to be activated. The validity checks are first set to include - only the default reference manual settings, and then a string of - letters in the string specifies the exact set of options required. - The form of this string is exactly as described for the `-gnatVx' - compiler switch (see the GNAT users guide for details). For - example the following two methods can be used to enable validity - checking for mode `in' and `in out' subprogram parameters: - - pragma Validity_Checks ("im"); - gcc -c -gnatVim ... - - The form ALL_CHECKS activates all standard checks (its use is - equivalent to the use of the `gnatva' switch. - - The forms with `Off' and `On' can be used to temporarily disable - validity checks as shown in the following example: - - pragma Validity_Checks ("c"); -- validity checks for copies - pragma Validity_Checks (Off); -- turn off validity checks - A := B; -- B will not be validity checked - pragma Validity_Checks (On); -- turn validity checks back on - A := C; -- C will be validity checked - - `pragma Volatile' - Syntax: - - pragma Volatile (local_NAME) - - This pragma is defined by the Ada 95 Reference Manual, and the GNAT - implementation is fully conformant with this definition. The - reason it is mentioned in this section is that a pragma of the - same name was supplied in some Ada 83 compilers, including DEC Ada - 83. The Ada 95 implementation of pragma Volatile is upwards - compatible with the implementation in Dec Ada 83. - - `pragma Warnings' - Syntax: - - pragma Warnings (On | Off [, LOCAL_NAME]); - - Normally warnings are enabled, with the output being controlled by - the command line switch. Warnings (`Off') turns off generation of - warnings until a Warnings (`On') is encountered or the end of the - current unit. If generation of warnings is turned off using this - pragma, then no warning messages are output, regardless of the - setting of the command line switches. - - The form with a single argument is a configuration pragma. - - If the LOCAL_NAME parameter is present, warnings are suppressed for - the specified entity. This suppression is effective from the - point where it occurs till the end of the extended scope of the - variable (similar to the scope of `Suppress'). - - `pragma Weak_External' - Syntax: - - pragma Weak_External ([Entity =>] LOCAL_NAME); - - This pragma specifies that the given entity should be marked as a - weak external (one that does not have to be resolved) for the - linker. For further details, consult the GCC manual. - -  - File: gnat_rm.info, Node: Implementation Defined Attributes, Next: Implementation Advice, Prev: Implementation Defined Pragmas, Up: Top - - Implementation Defined Attributes - ********************************* - - Ada 95 defines (throughout the Ada 95 reference manual, summarized - in annex K), a set of attributes that provide useful additional - functionality in all areas of the language. These language defined - attributes are implemented in GNAT and work as described in the Ada 95 - Reference Manual. - - In addition, Ada 95 allows implementations to define additional - attributes whose meaning is defined by the implementation. GNAT - provides a number of these implementation-dependent attributes which - can be used to extend and enhance the functionality of the compiler. - This section of the GNAT reference manual describes these additional - attributes. - - Note that any program using these attributes may not be portable to - other compilers (although GNAT implements this set of attributes on all - platforms). Therefore if portability to other compilers is an important - consideration, you should minimize the use of these attributes. - - `Abort_Signal' - `Standard'Abort_Signal' (`Standard' is the only allowed prefix) - provides the entity for the special exception used to signal task - abort or asynchronous transfer of control. Normally this attribute - should only be used in the tasking runtime (it is highly peculiar, - and completely outside the normal semantics of Ada, for a user - program to intercept the abort exception). - - `Address_Size' - `Standard'Address_Size' (`Standard' is the only allowed prefix) is - a static constant giving the number of bits in an `Address'. It - is used primarily for constructing the definition of `Memory_Size' - in package `Standard', but may be freely used in user programs and - has the advantage of being static, while a direct reference to - System.Address'Size is non-static because Address is a private - type. - - `Asm_Input' - The `Asm_Input' attribute denotes a function that takes two - parameters. The first is a string, the second is an expression of - the type designated by the prefix. The first (string) argument is - required to be a static expression, and is the constraint for the - parameter, (e.g. what kind of register is required). The second - argument is the value to be used as the input argument. The - possible values for the constant are the same as those used in the - RTL, and are dependent on the configuration file used to built the - GCC back end. *Note Machine Code Insertions:: - - `Asm_Output' - The `Asm_Output' attribute denotes a function that takes two - parameters. The first is a string, the second is the name of a - variable of the type designated by the attribute prefix. The - first (string) argument is required to be a static expression and - designates the constraint for the parameter (e.g. what kind of - register is required). The second argument is the variable to be - updated with the result. The possible values for constraint are - the same as those used in the RTL, and are dependent on the - configuration file used to build the GCC back end. If there are - no output operands, then this argument may either be omitted, or - explicitly given as `No_Output_Operands'. *Note Machine Code - Insertions:: - - `AST_Entry' - This attribute is implemented only in OpenVMS versions of GNAT. - Applied to the name of an entry, it yields a value of the - predefined type AST_Handler (declared in the predefined package - System, as extended by the use of pragma `Extend_System - (Aux_DEC)'). This value enables the given entry to be called when - an AST occurs. For further details, refer to the `DEC Ada - Language Reference Manual', section 9.12a. - - `Bit' - `OBJ'Bit', where OBJ is any object, yields the bit offset within - the storage unit (byte) that contains the first bit of storage - allocated for the object. The value of this attribute is of the - type `Universal_Integer', and is always a non-negative number not - exceeding the value of `System.Storage_Unit'. - - For an object that is a variable or a constant allocated in a - register, the value is zero. (The use of this attribute does not - force the allocation of a variable to memory). - - For an object that is a formal parameter, this attribute applies - to either the matching actual parameter or to a copy of the - matching actual parameter. - - For an access object the value is zero. Note that `OBJ.all'Bit' - is subject to an `Access_Check' for the designated object. - Similarly for a record component `X.C'Bit' is subject to a - discriminant check and `X(I).Bit' and `X(I1..I2)'Bit' are subject - to index checks. - - This attribute is designed to be compatible with the DEC Ada 83 - definition and implementation of the `Bit' attribute. - - `Bit_Position' - `R.C'Bit', where R is a record object and C is one of the fields - of the record type, yields the bit offset within the record - contains the first bit of storage allocated for the object. The - value of this attribute is of the type `Universal_Integer'. The - value depends only on the field C and is independent of the - alignment of the containing record R. - - `Code_Address' - The `'Address' attribute may be applied to subprograms in Ada 95, - but the intended effect from the Ada 95 reference manual seems to - be to provide an address value which can be used to call the - subprogram by means of an address clause as in the following - example: - - procedure K is ... - - procedure L; - for L'Address use K'Address; - pragma Import (Ada, L); - - A call to `L' is then expected to result in a call to `K'. In Ada - 83, where there were no access-to-subprogram values, this was a - common work around for getting the effect of an indirect call. - GNAT implements the above use of `Address' and the technique - illustrated by the example code works correctly. - - However, for some purposes, it is useful to have the address of - the start of the generated code for the subprogram. On some - architectures, this is not necessarily the same as the `Address' - value described above. For example, the `Address' value may - reference a subprogram descriptor rather than the subprogram - itself. - - The `'Code_Address' attribute, which can only be applied to - subprogram entities, always returns the address of the start of the - generated code of the specified subprogram, which may or may not be - the same value as is returned by the corresponding `'Address' - attribute. - - `Default_Bit_Order' - `Standard'Default_Bit_Order' (`Standard' is the only permissible - prefix), provides the value `System.Default_Bit_Order' as a `Pos' - value (0 for `High_Order_First', 1 for `Low_Order_First'). This - is used to construct the definition of `Default_Bit_Order' in - package `System'. - - `Elaborated' - The prefix of the `'Elaborated' attribute must be a unit name. The - value is a Boolean which indicates whether or not the given unit - has been elaborated. This attribute is primarily intended for - internal use by the generated code for dynamic elaboration - checking, but it can also be used in user programs. The value - will always be True once elaboration of all units has been - completed. - - `Elab_Body' - This attribute can only be applied to a program unit name. It - returns the entity for the corresponding elaboration procedure for - elaborating the body of the referenced unit. This is used in the - main generated elaboration procedure by the binder and is not - normally used in any other context. However, there may be - specialized situations in which it is useful to be able to call - this elaboration procedure from Ada code, e.g. if it is necessary - to do selective re-elaboration to fix some error. - - `Elab_Spec' - This attribute can only be applied to a program unit name. It - returns the entity for the corresponding elaboration procedure for - elaborating the specification of the referenced unit. This is - used in the main generated elaboration procedure by the binder and - is not normally used in any other context. However, there may be - specialized situations in which it is useful to be able to call - this elaboration procedure from Ada code, e.g. if it is necessary - to do selective re-elaboration to fix some error. - - `Emax' - The `Emax' attribute is provided for compatibility with Ada 83. - See the Ada 83 reference manual for an exact description of the - semantics of this attribute. - - `Enum_Rep' - For every enumeration subtype S, `S'Enum_Rep' denotes a function - with the following specification: - - function S'Enum_Rep (Arg : S'Base) - return Universal_Integer; - - It is also allowable to apply `Enum_Rep' directly to an object of - an enumeration type or to a non-overloaded enumeration literal. - In this case `S'Enum_Rep' is equivalent to `TYP'Enum_Rep(S)' where - TYP is the type of the enumeration literal or object. - - The function returns the representation value for the given - enumeration value. This will be equal to value of the `Pos' - attribute in the absence of an enumeration representation clause. - This is a static attribute (i.e. the result is static if the - argument is static). - - `S'Enum_Rep' can also be used with integer types and objects, in - which case it simply returns the integer value. The reason for - this is to allow it to be used for `(<>)' discrete formal - arguments in a generic unit that can be instantiated with either - enumeration types or integer types. Note that if `Enum_Rep' is - used on a modular type whose upper bound exceeds the upper bound - of the largest signed integer type, and the argument is a - variable, so that the universal integer calculation is done at - run-time, then the call to `Enum_Rep' may raise `Constraint_Error'. - - `Epsilon' - The `Epsilon' attribute is provided for compatibility with Ada 83. - See the Ada 83 reference manual for an exact description of the - semantics of this attribute. - - `Fixed_Value' - For every fixed-point type S, `S'Fixed_Value' denotes a function - with the following specification: - - function S'Fixed_Value (Arg : Universal_Integer) - return S; - - The value returned is the fixed-point value V such that - - V = Arg * S'Small - - The effect is thus equivalent to first converting the argument to - the integer type used to represent S, and then doing an unchecked - conversion to the fixed-point type. This attribute is primarily - intended for use in implementation of the input-output functions - for fixed-point values. - - `Has_Discriminants' - The prefix of the `Has_Discriminants' attribute is a type. The - result is a Boolean value which is True if the type has - discriminants, and False otherwise. The intended use of this - attribute is in conjunction with generic definitions. If the - attribute is applied to a generic private type, it indicates - whether or not the corresponding actual type has discriminants. - - `Img' - The `Img' attribute differs from `Image' in that it may be applied - to objects as well as types, in which case it gives the `Image' - for the subtype of the object. This is convenient for debugging: - - Put_Line ("X = " & X'Img); - - has the same meaning as the more verbose: - - Put_Line ("X = " & TYPE'Image (X)); - - where TYPE is the subtype of the object X. - - `Integer_Value' - For every integer type S, `S'Integer_Value' denotes a function - with the following specification: - - function S'Integer_Value (Arg : Universal_Fixed) - return S; - - The value returned is the integer value V, such that - - Arg = V * TYPE'Small - - The effect is thus equivalent to first doing an unchecked convert - from the fixed-point type to its corresponding implementation - type, and then converting the result to the target integer type. - This attribute is primarily intended for use in implementation of - the standard input-output functions for fixed-point values. - - `Large' - The `Large' attribute is provided for compatibility with Ada 83. - See the Ada 83 reference manual for an exact description of the - semantics of this attribute. - - `Machine_Size' - This attribute is identical to the `Object_Size' attribute. It is - provided for compatibility with the DEC Ada 83 attribute of this - name. - - `Mantissa' - The `Mantissa' attribute is provided for compatibility with Ada - 83. See the Ada 83 reference manual for an exact description of - the semantics of this attribute. - - `Max_Interrupt_Priority' - `Standard'Max_Interrupt_Priority' (`Standard' is the only - permissible prefix), provides the value - `System.Max_Interrupt_Priority' and is intended primarily for - constructing this definition in package `System'. - - `Max_Priority' - `Standard'Max_Priority' (`Standard' is the only permissible - prefix) provides the value `System.Max_Priority' and is intended - primarily for constructing this definition in package `System'. - - `Maximum_Alignment' - `Standard'Maximum_Alignment' (`Standard' is the only permissible - prefix) provides the maximum useful alignment value for the - target. This is a static value that can be used to specify the - alignment for an object, guaranteeing that it is properly aligned - in all cases. This is useful when an external object is imported - and its alignment requirements are unknown. - - `Mechanism_Code' - `FUNCTION'Mechanism_Code' yields an integer code for the mechanism - used for the result of function, and `SUBPROGRAM'Mechanism_Code - (N)' yields the mechanism used for formal parameter number N (a - static integer value with 1 meaning the first parameter) of - SUBPROGRAM. The code returned is: - - 1 - by copy (value) - - 2 - by reference - - 3 - by descriptor (default descriptor class) - - 4 - by descriptor (UBS: unaligned bit string) - - 5 - by descriptor (UBSB: aligned bit string with arbitrary bounds) - - 6 - by descriptor (UBA: unaligned bit array) - - 7 - by descriptor (S: string, also scalar access type parameter) - - 8 - by descriptor (SB: string with arbitrary bounds) - - 9 - by descriptor (A: contiguous array) - - 10 - by descriptor (NCA: non-contiguous array) - - Values from 3 through 10 are only relevant to Digital OpenVMS - implementations. - - `Null_Parameter' - A reference `T'Null_Parameter' denotes an imaginary object of type - or subtype T allocated at machine address zero. The attribute is - allowed only as the default expression of a formal parameter, or as - an actual expression of a subprogram call. In either case, the - subprogram must be imported. - - The identity of the object is represented by the address zero in - the argument list, independent of the passing mechanism (explicit - or default). - - This capability is needed to specify that a zero address should be - passed for a record or other composite object passed by reference. - There is no way of indicating this without the `Null_Parameter' - attribute. - - `Object_Size' - The size of an object is not necessarily the same as the size of - the type of an object. This is because by default object sizes - are increased to be a multiple of the alignment of the object. - For example, `Natural'Size' is 31, but by default objects of type - `Natural' will have a size of 32 bits. Similarly, a record - containing an integer and a character: - - type Rec is record - I : Integer; - C : Character; - end record; - - will have a size of 40 (that is `Rec'Size' will be 40. The - alignment will be 4, because of the integer field, and so the - default size of record objects for this type will be 64 (8 bytes). - - The `TYPE'Object_Size' attribute has been added to GNAT to allow - the default object size of a type to be easily determined. For - example, `Natural'Object_Size' is 32, and `Rec'Object_Size' (for - the record type in the above example) will be 64. Note also that, - unlike the situation with the `Size' attribute as defined in the - Ada RM, the `Object_Size' attribute can be specified individually - for different subtypes. For example: - - type R is new Integer; - subtype R1 is R range 1 .. 10; - subtype R2 is R range 1 .. 10; - for R2'Object_Size use 8; - - In this example, `R'Object_Size' and `R1'Object_Size' are both 32 - since the default object size for a subtype is the same as the - object size for the parent subtype. This means that objects of - type `R' or `R1' will by default be 32 bits (four bytes). But - objects of type `R2' will be only 8 bits (one byte), since - `R2'Object_Size' has been set to 8. - - `Passed_By_Reference' - `TYPE'Passed_By_Reference' for any subtype TYPE returns a value of - type `Boolean' value that is `True' if the type is normally passed - by reference and `False' if the type is normally passed by copy in - calls. For scalar types, the result is always `False' and is - static. For non-scalar types, the result is non-static. - - `Range_Length' - `TYPE'Range_Length' for any discrete type TYPE yields the number - of values represented by the subtype (zero for a null range). The - result is static for static subtypes. `Range_Length' applied to - the index subtype of a one dimensional array always gives the same - result as `Range' applied to the array itself. - - `Safe_Emax' - The `Safe_Emax' attribute is provided for compatibility with Ada - 83. See the Ada 83 reference manual for an exact description of - the semantics of this attribute. - - `Safe_Large' - The `Safe_Large' attribute is provided for compatibility with Ada - 83. See the Ada 83 reference manual for an exact description of - the semantics of this attribute. - - `Safe_Large' - The `Safe_Large' attribute is provided for compatibility with Ada - 83. See the Ada 83 reference manual for an exact description of - the semantics of this attribute. - - `Small' - The `Small' attribute is defined in Ada 95 only for fixed-point - types. GNAT also allows this attribute to be applied to - floating-point types for compatibility with Ada 83. See the Ada - 83 reference manual for an exact description of the semantics of - this attribute when applied to floating-point types. - - `Storage_Unit' - `Standard'Storage_Unit' (`Standard' is the only permissible - prefix) provides the value `System.Storage_Unit' and is intended - primarily for constructing this definition in package `System'. - - `Tick' - `Standard'Tick' (`Standard' is the only permissible prefix) - provides the value of `System.Tick' and is intended primarily for - constructing this definition in package `System'. - - `To_Address' - The `System'To_Address' (`System' is the only permissible prefix) - denotes a function identical to - `System.Storage_Elements.To_Address' except that it is a static - attribute. This means that if its argument is a static - expression, then the result of the attribute is a static - expression. The result is that such an expression can be used in - contexts (e.g. preelaborable packages) which require a static - expression and where the function call could not be used (since - the function call is always non-static, even if its argument is - static). - - `Type_Class' - `TYPE'Type_Class' for any type or subtype TYPE yields the value of - the type class for the full type of TYPE. If TYPE is a generic - formal type, the value is the value for the corresponding actual - subtype. The value of this attribute is of type - `System.Aux_DEC.Type_Class', which has the following definition: - - type Type_Class is - (Type_Class_Enumeration, - Type_Class_Integer, - Type_Class_Fixed_Point, - Type_Class_Floating_Point, - Type_Class_Array, - Type_Class_Record, - Type_Class_Access, - Type_Class_Task, - Type_Class_Address); - - Protected types yield the value `Type_Class_Task', which thus - applies to all concurrent types. This attribute is designed to be - compatible with the DEC Ada 83 attribute of the same name. - - `UET_Address' - The `UET_Address' attribute can only be used for a prefix which - denotes a library package. It yields the address of the unit - exception table when zero cost exception handling is used. This - attribute is intended only for use within the GNAT implementation. - See the unit `Ada.Exceptions' in files `a-except.ads' and - `a-except.adb' for details on how this attribute is used in the - implementation. - - `Universal_Literal_String' - The prefix of `Universal_Literal_String' must be a named number. - The static result is the string consisting of the characters of - the number as defined in the original source. This allows the user - program to access the actual text of named numbers without - intermediate conversions and without the need to enclose the - strings in quotes (which would preclude their use as numbers). - This is used internally for the construction of values of the - floating-point attributes from the file `ttypef.ads', but may also - be used by user programs. - - `Unrestricted_Access' - The `Unrestricted_Access' attribute is similar to `Access' except - that all accessibility and aliased view checks are omitted. This - is a user-beware attribute. It is similar to `Address', for which - it is a desirable replacement where the value desired is an access - type. In other words, its effect is identical to first applying - the `Address' attribute and then doing an unchecked conversion to - a desired access type. In GNAT, but not necessarily in other - implementations, the use of static chains for inner level - subprograms means that `Unrestricted_Access' applied to a - subprogram yields a value that can be called as long as the - subprogram is in scope (normal Ada 95 accessibility rules restrict - this usage). - - `VADS_Size' - The `'VADS_Size' attribute is intended to make it easier to port - legacy code which relies on the semantics of `'Size' as implemented - by the VADS Ada 83 compiler. GNAT makes a best effort at - duplicating the same semantic interpretation. In particular, - `'VADS_Size' applied to a predefined or other primitive type with - no Size clause yields the Object_Size (for example, `Natural'Size' - is 32 rather than 31 on typical machines). In addition - `'VADS_Size' applied to an object gives the result that would be - obtained by applying the attribute to the corresponding type. - - `Value_Size' - `TYPE'Value_Size' is the number of bits required to represent a - value of the given subtype. It is the same as `TYPE'Size', but, - unlike `Size', may be set for non-first subtypes. - - `Wchar_T_Size' - `Standard'Wchar_T_Size' (`Standard' is the only permissible - prefix) provides the size in bits of the C `wchar_t' type - primarily for constructing the definition of this type in package - `Interfaces.C'. - - `Word_Size' - `Standard'Word_Size' (`Standard' is the only permissible prefix) - provides the value `System.Word_Size' and is intended primarily - for constructing this definition in package `System'. - -  - File: gnat_rm.info, Node: Implementation Advice, Next: Implementation Defined Characteristics, Prev: Implementation Defined Attributes, Up: Top - - Implementation Advice - ********************* - - The main text of the Ada 95 Reference Manual describes the required - behavior of all Ada 95 compilers, and the GNAT compiler conforms to - these requirements. - - In addition, there are sections throughout the Ada 95 reference - manual headed by the phrase "implementation advice". These sections - are not normative, i.e. they do not specify requirements that all - compilers must follow. Rather they provide advice on generally - desirable behavior. You may wonder why they are not requirements. The - most typical answer is that they describe behavior that seems generally - desirable, but cannot be provided on all systems, or which may be - undesirable on some systems. - - As far as practical, GNAT follows the implementation advice sections - in the Ada 95 Reference Manual. This chapter contains a table giving - the reference manual section number, paragraph number and several - keywords for each advice. Each entry consists of the text of the - advice followed by the GNAT interpretation of this advice. Most often, - this simply says "followed", which means that GNAT follows the advice. - However, in a number of cases, GNAT deliberately deviates from this - advice, in which case the text describes what GNAT does and why. - - *1.1.3(20): Error Detection* - - If an implementation detects the use of an unsupported Specialized - Needs Annex feature at run time, it should raise `Program_Error' if - feasible. - Not relevant. All specialized needs annex features are either - supported, or diagnosed at compile time. - - *1.1.3(31): Child Units* - - If an implementation wishes to provide implementation-defined - extensions to the functionality of a language-defined library - unit, it should normally do so by adding children to the library - unit. - Followed. - - *1.1.5(12): Bounded Errors* - - If an implementation detects a bounded error or erroneous - execution, it should raise `Program_Error'. - Followed in all cases in which the implementation detects a bounded - error or erroneous execution. Not all such situations are - detected at runtime. - - *2.8(16): Pragmas* - - Normally, implementation-defined pragmas should have no semantic - effect for error-free programs; that is, if the - implementation-defined pragmas are removed from a working program, - the program should still be legal, and should still have the same - semantics. - The following implementation defined pragmas are exceptions to this - rule: - - `Abort_Defer' - Affects semantics - - `Ada_83' - Affects legality - - `Assert' - Affects semantics - - `CPP_Class' - Affects semantics - - `CPP_Constructor' - Affects semantics - - `CPP_Virtual' - Affects semantics - - `CPP_Vtable' - Affects semantics - - `Debug' - Affects semantics - - `Interface_Name' - Affects semantics - - `Machine_Attribute' - Affects semantics - - `Unimplemented_Unit' - Affects legality - - `Unchecked_Union' - Affects semantics - - In each of the above cases, it is essential to the purpose of the - pragma that this advice not be followed. For details see the - separate section on implementation defined pragmas. - - *2.8(17-19): Pragmas* - - Normally, an implementation should not define pragmas that can - make an illegal program legal, except as follows: - - - A pragma used to complete a declaration, such as a pragma `Import'; - - - A pragma used to configure the environment by adding, removing, or - replacing `library_items'. - See response to paragraph 16 of this same section. - - *3.5.2(5): Alternative Character Sets* - - If an implementation supports a mode with alternative - interpretations for `Character' and `Wide_Character', the set of - graphic characters of `Character' should nevertheless remain a - proper subset of the set of graphic characters of - `Wide_Character'. Any character set "localizations" should be - reflected in the results of the subprograms defined in the - language-defined package `Characters.Handling' (see A.3) available - in such a mode. In a mode with an alternative interpretation of - `Character', the implementation should also support a - corresponding change in what is a legal `identifier_letter'. - Not all wide character modes follow this advice, in particular the - JIS and IEC modes reflect standard usage in Japan, and in these - encoding, the upper half of the Latin-1 set is not part of the - wide-character subset, since the most significant bit is used for - wide character encoding. However, this only applies to the - external forms. Internally there is no such restriction. - - *3.5.4(28): Integer Types* - - An implementation should support `Long_Integer' in addition to - `Integer' if the target machine supports 32-bit (or longer) - arithmetic. No other named integer subtypes are recommended for - package `Standard'. Instead, appropriate named integer subtypes - should be provided in the library package `Interfaces' (see B.2). - `Long_Integer' is supported. Other standard integer types are - supported so this advice is not fully followed. These types are - supported for convenient interface to C, and so that all hardware - types of the machine are easily available. - - *3.5.4(29): Integer Types* - - An implementation for a two's complement machine should support - modular types with a binary modulus up to `System.Max_Int*2+2'. An - implementation should support a non-binary modules up to - `Integer'Last'. - Followed. - - *3.5.5(8): Enumeration Values* - - For the evaluation of a call on `S'Pos' for an enumeration - subtype, if the value of the operand does not correspond to the - internal code for any enumeration literal of its type (perhaps due - to an un-initialized variable), then the implementation should - raise `Program_Error'. This is particularly important for - enumeration types with noncontiguous internal codes specified by an - enumeration_representation_clause. - Followed. - - *3.5.7(17): Float Types* - - An implementation should support `Long_Float' in addition to - `Float' if the target machine supports 11 or more digits of - precision. No other named floating point subtypes are recommended - for package `Standard'. Instead, appropriate named floating point - subtypes should be provided in the library package `Interfaces' - (see B.2). - `Short_Float' and `Long_Long_Float' are also provided. The former - provides improved compatibility with other implementations - supporting this type. The latter corresponds to the highest - precision floating-point type supported by the hardware. On most - machines, this will be the same as `Long_Float', but on some - machines, it will correspond to the IEEE extended form. The - notable case is all ia32 (x86) implementations, where - `Long_Long_Float' corresponds to the 80-bit extended precision - format supported in hardware on this processor. Note that the - 128-bit format on SPARC is not supported, since this is a software - rather than a hardware format. - - *3.6.2(11): Multidimensional Arrays* - - An implementation should normally represent multidimensional - arrays in row-major order, consistent with the notation used for - multidimensional array aggregates (see 4.3.3). However, if a - pragma `Convention' (`Fortran', ...) applies to a multidimensional - array type, then column-major order should be used instead (see - B.5, "Interfacing with Fortran"). - Followed. - - *9.6(30-31): Duration'Small* - - Whenever possible in an implementation, the value of - `Duration'Small' should be no greater than 100 microseconds. - Followed. (`Duration'Small' = 10**(-9)). - - - The time base for `delay_relative_statements' should be monotonic; - it need not be the same time base as used for `Calendar.Clock'. - Followed. - - *10.2.1(12): Consistent Representation* - - In an implementation, a type declared in a pre-elaborated package - should have the same representation in every elaboration of a - given version of the package, whether the elaborations occur in - distinct executions of the same program, or in executions of - distinct programs or partitions that include the given version. - Followed, except in the case of tagged types. Tagged types involve - implicit pointers to a local copy of a dispatch table, and these - pointers have representations which thus depend on a particular - elaboration of the package. It is not easy to see how it would be - possible to follow this advice without severely impacting - efficiency of execution. - - *11.4.1(19): Exception Information* - - `Exception_Message' by default and `Exception_Information' should - produce information useful for debugging. `Exception_Message' - should be short, about one line. `Exception_Information' can be - long. `Exception_Message' should not include the - `Exception_Name'. `Exception_Information' should include both the - `Exception_Name' and the `Exception_Message'. - Followed. For each exception that doesn't have a specified - `Exception_Message', the compiler generates one containing the - location of the raise statement. This location has the form - "file:line", where file is the short file name (without path - information) and line is the line number in the file. Note that - in the case of the Zero Cost Exception mechanism, these messages - become redundant with the Exception_Information that contains a - full backtrace of the calling sequence, so they are disabled. To - disable explicitly the generation of the source location message, - use the Pragma `Discard_Names'. - - *11.5(28): Suppression of Checks* - - The implementation should minimize the code executed for checks - that have been suppressed. - Followed. - - *13.1 (21-24): Representation Clauses* - - The recommended level of support for all representation items is - qualified as follows: - - - An implementation need not support representation items containing - non-static expressions, except that an implementation should - support a representation item for a given entity if each - non-static expression in the representation item is a name that - statically denotes a constant declared before the entity. - Followed. GNAT does not support non-static expressions in - representation clauses unless they are constants declared before - the entity. For example: - - X : typ; - for X'Address use To_address (16#2000#); - - will be rejected, since the To_Address expression is non-static. - Instead write: - - X_Address : constant Address : = - To_Address ((16#2000#); - X : typ; - for X'Address use X_Address; - - - An implementation need not support a specification for the `Size' - for a given composite subtype, nor the size or storage place for an - object (including a component) of a given composite subtype, - unless the constraints on the subtype and its composite - subcomponents (if any) are all static constraints. - Followed. Size Clauses are not permitted on non-static - components, as described above. - - - An aliased component, or a component whose type is by-reference, - should always be allocated at an addressable location. - Followed. - - *13.2(6-8): Packed Types* - - If a type is packed, then the implementation should try to minimize - storage allocated to objects of the type, possibly at the expense - of speed of accessing components, subject to reasonable complexity - in addressing calculations. - - - The recommended level of support pragma `Pack' is: - - For a packed record type, the components should be packed as - tightly as possible subject to the Sizes of the component - subtypes, and subject to any `record_representation_clause' that - applies to the type; the implementation may, but need not, reorder - components or cross aligned word boundaries to improve the - packing. A component whose `Size' is greater than the word size - may be allocated an integral number of words. - Followed. Tight packing of arrays is supported for all component - sizes up to 64-bits. - - - An implementation should support Address clauses for imported - subprograms. - Followed. - - *13.3(14-19): Address Clauses* - - For an array X, `X'Address' should point at the first component of - the array, and not at the array bounds. - Followed. - - - The recommended level of support for the `Address' attribute is: - - `X'Address' should produce a useful result if X is an object that - is aliased or of a by-reference type, or is an entity whose - `Address' has been specified. - Followed. A valid address will be produced even if none of those - conditions have been met. If necessary, the object is forced into - memory to ensure the address is valid. - - - An implementation should support `Address' clauses for imported - subprograms. - Followed. - - - Objects (including subcomponents) that are aliased or of a - by-reference type should be allocated on storage element - boundaries. - Followed. - - - If the `Address' of an object is specified, or it is imported or - exported, then the implementation should not perform optimizations - based on assumptions of no aliases. - Followed. - - *13.3(29-35): Alignment Clauses* - - The recommended level of support for the `Alignment' attribute for - subtypes is: - - An implementation should support specified Alignments that are - factors and multiples of the number of storage elements per word, - subject to the following: - Followed. - - - An implementation need not support specified `Alignment's for - combinations of `Size's and `Alignment's that cannot be easily - loaded and stored by available machine instructions. - Followed. - - - An implementation need not support specified `Alignment's that are - greater than the maximum `Alignment' the implementation ever - returns by default. - Followed. - - - The recommended level of support for the `Alignment' attribute for - objects is: - - Same as above, for subtypes, but in addition: - Followed. - - - For stand-alone library-level objects of statically constrained - subtypes, the implementation should support all `Alignment's - supported by the target linker. For example, page alignment is - likely to be supported for such objects, but not for subtypes. - Followed. - - *13.3(42-43): Size Clauses* - - The recommended level of support for the `Size' attribute of - objects is: - - A `Size' clause should be supported for an object if the specified - `Size' is at least as large as its subtype's `Size', and - corresponds to a size in storage elements that is a multiple of the - object's `Alignment' (if the `Alignment' is nonzero). - Followed. - - *13.3(50-56): Size Clauses* - - If the `Size' of a subtype is specified, and allows for efficient - independent addressability (see 9.10) on the target architecture, - then the `Size' of the following objects of the subtype should - equal the `Size' of the subtype: - - Aliased objects (including components). - Followed. - - - `Size' clause on a composite subtype should not affect the - internal layout of components. - Followed. - - - The recommended level of support for the `Size' attribute of - subtypes is: - - - The `Size' (if not specified) of a static discrete or fixed point - subtype should be the number of bits needed to represent each value - belonging to the subtype using an unbiased representation, leaving - space for a sign bit only if the subtype contains negative values. - If such a subtype is a first subtype, then an implementation - should support a specified `Size' for it that reflects this - representation. - Followed. - - - For a subtype implemented with levels of indirection, the `Size' - should include the size of the pointers, but not the size of what - they point at. - Followed. - - *13.3(71-73): Component Size Clauses* - - The recommended level of support for the `Component_Size' - attribute is: - - - An implementation need not support specified `Component_Sizes' - that are less than the `Size' of the component subtype. - Followed. - - - An implementation should support specified `Component_Size's that - are factors and multiples of the word size. For such - `Component_Size's, the array should contain no gaps between - components. For other `Component_Size's (if supported), the array - should contain no gaps between components when packing is also - specified; the implementation should forbid this combination in - cases where it cannot support a no-gaps representation. - Followed. - - *13.4(9-10): Enumeration Representation Clauses* - - The recommended level of support for enumeration representation - clauses is: - - An implementation need not support enumeration representation - clauses for boolean types, but should at minimum support the - internal codes in the range `System.Min_Int.System.Max_Int'. - Followed. - - *13.5.1(17-22): Record Representation Clauses* - - The recommended level of support for - `record_representation_clauses' is: - - An implementation should support storage places that can be - extracted with a load, mask, shift sequence of machine code, and - set with a load, shift, mask, store sequence, given the available - machine instructions and run-time model. - Followed. - - - A storage place should be supported if its size is equal to the - `Size' of the component subtype, and it starts and ends on a - boundary that obeys the `Alignment' of the component subtype. - Followed. - - - If the default bit ordering applies to the declaration of a given - type, then for a component whose subtype's `Size' is less than the - word size, any storage place that does not cross an aligned word - boundary should be supported. - Followed. - - - An implementation may reserve a storage place for the tag field of - a tagged type, and disallow other components from overlapping that - place. - Followed. The storage place for the tag field is the beginning of - the tagged record, and its size is Address'Size. GNAT will reject - an explicit component clause for the tag field. - - - An implementation need not support a `component_clause' for a - component of an extension part if the storage place is not after - the storage places of all components of the parent type, whether - or not those storage places had been specified. - Followed. The above advice on record representation clauses is - followed, and all mentioned features are implemented. - - *13.5.2(5): Storage Place Attributes* - - If a component is represented using some form of pointer (such as - an offset) to the actual data of the component, and this data is - contiguous with the rest of the object, then the storage place - attributes should reflect the place of the actual data, not the - pointer. If a component is allocated discontinuously from the - rest of the object, then a warning should be generated upon - reference to one of its storage place attributes. - Followed. There are no such components in GNAT. - - *13.5.3(7-8): Bit Ordering* - - The recommended level of support for the non-default bit ordering - is: - - - If `Word_Size' = `Storage_Unit', then the implementation should - support the non-default bit ordering in addition to the default - bit ordering. - Followed. Word size does not equal storage size in this - implementation. Thus non-default bit ordering is not supported. - - *13.7(37): Address as Private* - - `Address' should be of a private type. - Followed. - - *13.7.1(16): Address Operations* - - Operations in `System' and its children should reflect the target - environment semantics as closely as is reasonable. For example, - on most machines, it makes sense for address arithmetic to "wrap - around". Operations that do not make sense should raise - `Program_Error'. - Followed. Address arithmetic is modular arithmetic that wraps - around. No operation raises `Program_Error', since all operations - make sense. - - *13.9(14-17): Unchecked Conversion* - - The `Size' of an array object should not include its bounds; hence, - the bounds should not be part of the converted data. - Followed. - - - The implementation should not generate unnecessary run-time checks - to ensure that the representation of S is a representation of the - target type. It should take advantage of the permission to return - by reference when possible. Restrictions on unchecked conversions - should be avoided unless required by the target environment. - Followed. There are no restrictions on unchecked conversion. A - warning is generated if the source and target types do not have - the same size since the semantics in this case may be target - dependent. - - - The recommended level of support for unchecked conversions is: - - - Unchecked conversions should be supported and should be reversible - in the cases where this clause defines the result. To enable - meaningful use of unchecked conversion, a contiguous - representation should be used for elementary subtypes, for - statically constrained array subtypes whose component subtype is - one of the subtypes described in this paragraph, and for record - subtypes without discriminants whose component subtypes are - described in this paragraph. - Followed. - - *13.11(23-25): Implicit Heap Usage* - - An implementation should document any cases in which it dynamically - allocates heap storage for a purpose other than the evaluation of - an allocator. - Followed, the only other points at which heap storage is - dynamically allocated are as follows: - - * At initial elaboration time, to allocate dynamically sized - global objects. - - * To allocate space for a task when a task is created. - - * To extend the secondary stack dynamically when needed. The - secondary stack is used for returning variable length results. - - - A default (implementation-provided) storage pool for an - access-to-constant type should not have overhead to support - deallocation of individual objects. - Followed. - - - A storage pool for an anonymous access type should be created at - the point of an allocator for the type, and be reclaimed when the - designated object becomes inaccessible. - Followed. - - *13.11.2(17): Unchecked De-allocation* - - For a standard storage pool, `Free' should actually reclaim the - storage. - Followed. - - *13.13.2(17): Stream Oriented Attributes* - - If a stream element is the same size as a storage element, then the - normal in-memory representation should be used by `Read' and - `Write' for scalar objects. Otherwise, `Read' and `Write' should - use the smallest number of stream elements needed to represent all - values in the base range of the scalar type. - Followed. In particular, the interpretation chosen is that of - AI-195, which specifies that the size to be used is that of the - first subtype. - - *A.1(52): Implementation Advice* - - If an implementation provides additional named predefined integer - types, then the names should end with `Integer' as in - `Long_Integer'. If an implementation provides additional named - predefined floating point types, then the names should end with - `Float' as in `Long_Float'. - Followed. - - *A.3.2(49): `Ada.Characters.Handling'* - - If an implementation provides a localized definition of `Character' - or `Wide_Character', then the effects of the subprograms in - `Characters.Handling' should reflect the localizations. See also - 3.5.2. - Followed. GNAT provides no such localized definitions. - - *A.4.4(106): Bounded-Length String Handling* - - Bounded string objects should not be implemented by implicit - pointers and dynamic allocation. - Followed. No implicit pointers or dynamic allocation are used. - - *A.5.2(46-47): Random Number Generation* - - Any storage associated with an object of type `Generator' should be - reclaimed on exit from the scope of the object. - Followed. - - - If the generator period is sufficiently long in relation to the - number of distinct initiator values, then each possible value of - `Initiator' passed to `Reset' should initiate a sequence of random - numbers that does not, in a practical sense, overlap the sequence - initiated by any other value. If this is not possible, then the - mapping between initiator values and generator states should be a - rapidly varying function of the initiator value. - Followed. The generator period is sufficiently long for the first - condition here to hold true. - - *A.10.7(23): `Get_Immediate'* - - The `Get_Immediate' procedures should be implemented with - unbuffered input. For a device such as a keyboard, input should be - "available" if a key has already been typed, whereas for a disk - file, input should always be available except at end of file. For - a file associated with a keyboard-like device, any line-editing - features of the underlying operating system should be disabled - during the execution of `Get_Immediate'. - Followed. - - *B.1(39-41): Pragma `Export'* - - If an implementation supports pragma `Export' to a given language, - then it should also allow the main subprogram to be written in that - language. It should support some mechanism for invoking the - elaboration of the Ada library units included in the system, and - for invoking the finalization of the environment task. On typical - systems, the recommended mechanism is to provide two subprograms - whose link names are `adainit' and `adafinal'. `adainit' should - contain the elaboration code for library units. `adafinal' should - contain the finalization code. These subprograms should have no - effect the second and subsequent time they are called. - Followed. - - - Automatic elaboration of pre-elaborated packages should be - provided when pragma `Export' is supported. - Followed when the main program is in Ada. If the main program is - in a foreign language, then `adainit' must be called to elaborate - pre-elaborated packages. - - - For each supported convention L other than `Intrinsic', an - implementation should support `Import' and `Export' pragmas for - objects of L-compatible types and for subprograms, and pragma - `Convention' for L-eligible types and for subprograms, presuming - the other language has corresponding features. Pragma - `Convention' need not be supported for scalar types. - Followed. - - *B.2(12-13): Package `Interfaces'* - - For each implementation-defined convention identifier, there - should be a child package of package Interfaces with the - corresponding name. This package should contain any declarations - that would be useful for interfacing to the language - (implementation) represented by the convention. Any declarations - useful for interfacing to any language on the given hardware - architecture should be provided directly in `Interfaces'. - Followed. An additional package not defined in the Ada 95 - Reference Manual is `Interfaces.CPP', used for interfacing to C++. - - - An implementation supporting an interface to C, COBOL, or Fortran - should provide the corresponding package or packages described in - the following clauses. - Followed. GNAT provides all the packages described in this - section. - - *B.3(63-71): Interfacing with C* - - An implementation should support the following interface - correspondences between Ada and C. - Followed. - - - An Ada procedure corresponds to a void-returning C function. - Followed. - - - An Ada function corresponds to a non-void C function. - Followed. - - - An Ada `in' scalar parameter is passed as a scalar argument to a C - function. - Followed. - - - An Ada `in' parameter of an access-to-object type with designated - type T is passed as a `T*' argument to a C function, where T is - the C type corresponding to the Ada type T. - Followed. - - - An Ada access T parameter, or an Ada `out' or `in out' parameter - of an elementary type T, is passed as a `T*' argument to a C - function, where T is the C type corresponding to the Ada type T. - In the case of an elementary `out' or `in out' parameter, a - pointer to a temporary copy is used to preserve by-copy semantics. - Followed. - - - An Ada parameter of a record type T, of any mode, is passed as a - `T*' argument to a C function, where T is the C structure - corresponding to the Ada type T. - Followed. This convention may be overridden by the use of the - C_Pass_By_Copy pragma, or Convention, or by explicitly specifying - the mechanism for a given call using an extended import or export - pragma. - - - An Ada parameter of an array type with component type T, of any - mode, is passed as a `T*' argument to a C function, where T is the - C type corresponding to the Ada type T. - Followed. - - - An Ada parameter of an access-to-subprogram type is passed as a - pointer to a C function whose prototype corresponds to the - designated subprogram's specification. - Followed. - - *B.4(95-98): Interfacing with COBOL* - - An Ada implementation should support the following interface - correspondences between Ada and COBOL. - Followed. - - - An Ada access T parameter is passed as a `BY REFERENCE' data item - of the COBOL type corresponding to T. - Followed. - - - An Ada in scalar parameter is passed as a `BY CONTENT' data item of - the corresponding COBOL type. - Followed. - - - Any other Ada parameter is passed as a `BY REFERENCE' data item of - the COBOL type corresponding to the Ada parameter type; for - scalars, a local copy is used if necessary to ensure by-copy - semantics. - Followed. - - *B.5(22-26): Interfacing with Fortran* - - An Ada implementation should support the following interface - correspondences between Ada and Fortran: - Followed. - - - An Ada procedure corresponds to a Fortran subroutine. - Followed. - - - An Ada function corresponds to a Fortran function. - Followed. - - - An Ada parameter of an elementary, array, or record type T is - passed as a T argument to a Fortran procedure, where T is the - Fortran type corresponding to the Ada type T, and where the INTENT - attribute of the corresponding dummy argument matches the Ada - formal parameter mode; the Fortran implementation's parameter - passing conventions are used. For elementary types, a local copy - is used if necessary to ensure by-copy semantics. - Followed. - - - An Ada parameter of an access-to-subprogram type is passed as a - reference to a Fortran procedure whose interface corresponds to the - designated subprogram's specification. - Followed. - - *C.1(3-5): Access to Machine Operations* - - The machine code or intrinsic support should allow access to all - operations normally available to assembly language programmers for - the target environment, including privileged instructions, if any. - Followed. - - - The interfacing pragmas (see Annex B) should support interface to - assembler; the default assembler should be associated with the - convention identifier `Assembler'. - Followed. - - - If an entity is exported to assembly language, then the - implementation should allocate it at an addressable location, and - should ensure that it is retained by the linking process, even if - not otherwise referenced from the Ada code. The implementation - should assume that any call to a machine code or assembler - subprogram is allowed to read or update every object that is - specified as exported. - Followed. - - *C.1(10-16): Access to Machine Operations* - - The implementation should ensure that little or no overhead is - associated with calling intrinsic and machine-code subprograms. - Followed for both intrinsics and machine-code subprograms. - - - It is recommended that intrinsic subprograms be provided for - convenient access to any machine operations that provide special - capabilities or efficiency and that are not otherwise available - through the language constructs. - Followed. A full set of machine operation intrinsic subprograms - is provided. - - - Atomic read-modify-write operations--e.g., test and set, compare - and swap, decrement and test, enqueue/dequeue. - Followed on any target supporting such operations. - - - Standard numeric functions--e.g., sin, log. - Followed on any target supporting such operations. - - - String manipulation operations--e.g., translate and test. - Followed on any target supporting such operations. - - - Vector operations--e.g., compare vector against thresholds. - Followed on any target supporting such operations. - - - Direct operations on I/O ports. - Followed on any target supporting such operations. - - *C.3(28): Interrupt Support* - - If the `Ceiling_Locking' policy is not in effect, the - implementation should provide means for the application to specify - which interrupts are to be blocked during protected actions, if - the underlying system allows for a finer-grain control of - interrupt blocking. - Followed. The underlying system does not allow for finer-grain - control of interrupt blocking. - - *C.3.1(20-21): Protected Procedure Handlers* - - Whenever possible, the implementation should allow interrupt - handlers to be called directly by the hardware. - Followed on any target where the underlying operating system - permits such direct calls. - - - Whenever practical, violations of any implementation-defined - restrictions should be detected before run time. - Followed. Compile time warnings are given when possible. - - *C.3.2(25): Package `Interrupts'* - - If implementation-defined forms of interrupt handler procedures are - supported, such as protected procedures with parameters, then for - each such form of a handler, a type analogous to - `Parameterless_Handler' should be specified in a child package of - `Interrupts', with the same operations as in the predefined - package Interrupts. - Followed. - - *C.4(14): Pre-elaboration Requirements* - - It is recommended that pre-elaborated packages be implemented in - such a way that there should be little or no code executed at run - time for the elaboration of entities not already covered by the - Implementation Requirements. - Followed. Executable code is generated in some cases, e.g. loops - to initialize large arrays. - - *C.5(8): Pragma `Discard_Names'* - - If the pragma applies to an entity, then the implementation should - reduce the amount of storage used for storing names associated - with that entity. - Followed. - - *C.7.2(30): The Package Task_Attributes* - - Some implementations are targeted to domains in which memory use - at run time must be completely deterministic. For such - implementations, it is recommended that the storage for task - attributes will be pre-allocated statically and not from the heap. - This can be accomplished by either placing restrictions on the - number and the size of the task's attributes, or by using the - pre-allocated storage for the first N attribute objects, and the - heap for the others. In the latter case, N should be documented. - Not followed. This implementation is not targeted to such a - domain. - - *D.3(17): Locking Policies* - - The implementation should use names that end with `_Locking' for - locking policies defined by the implementation. - Followed. A single implementation-defined locking policy is - defined, whose name (`Inheritance_Locking') follows this - suggestion. - - *D.4(16): Entry Queuing Policies* - - Names that end with `_Queuing' should be used for all - implementation-defined queuing policies. - Followed. No such implementation-defined queueing policies exist. - - *D.6(9-10): Preemptive Abort* - - Even though the `abort_statement' is included in the list of - potentially blocking operations (see 9.5.1), it is recommended - that this statement be implemented in a way that never requires - the task executing the `abort_statement' to block. - Followed. - - - On a multi-processor, the delay associated with aborting a task on - another processor should be bounded; the implementation should use - periodic polling, if necessary, to achieve this. - Followed. - - *D.7(21): Tasking Restrictions* - - When feasible, the implementation should take advantage of the - specified restrictions to produce a more efficient implementation. - GNAT currently takes advantage of these restrictions by providing - an optimized run time when the Ravenscar profile and the GNAT - restricted run time set of restrictions are specified. See pragma - `Ravenscar' and pragma `Restricted_Run_Time' for more details. - - *D.8(47-49): Monotonic Time* - - When appropriate, implementations should provide configuration - mechanisms to change the value of `Tick'. - Such configuration mechanisms are not appropriate to this - implementation and are thus not supported. - - - It is recommended that `Calendar.Clock' and `Real_Time.Clock' be - implemented as transformations of the same time base. - Followed. - - - It is recommended that the "best" time base which exists in the - underlying system be available to the application through `Clock'. - "Best" may mean highest accuracy or largest range. - Followed. - - *E.5(28-29): Partition Communication Subsystem* - - Whenever possible, the PCS on the called partition should allow for - multiple tasks to call the RPC-receiver with different messages and - should allow them to block until the corresponding subprogram body - returns. - Followed by GLADE, a separately supplied PCS that can be used with - GNAT. - - - The `Write' operation on a stream of type `Params_Stream_Type' - should raise `Storage_Error' if it runs out of space trying to - write the `Item' into the stream. - Followed by GLADE, a separately supplied PCS that can be used with - GNAT. - - *F(7): COBOL Support* - - If COBOL (respectively, C) is widely supported in the target - environment, implementations supporting the Information Systems - Annex should provide the child package `Interfaces.COBOL' - (respectively, `Interfaces.C') specified in Annex B and should - support a `convention_identifier' of COBOL (respectively, C) in - the interfacing pragmas (see Annex B), thus allowing Ada programs - to interface with programs written in that language. - Followed. - - *F.1(2): Decimal Radix Support* - - Packed decimal should be used as the internal representation for - objects of subtype S when S'Machine_Radix = 10. - Not followed. GNAT ignores S'Machine_Radix and always uses binary - representations. - - *G: Numerics* - - - If Fortran (respectively, C) is widely supported in the target - environment, implementations supporting the Numerics Annex should - provide the child package `Interfaces.Fortran' (respectively, - `Interfaces.C') specified in Annex B and should support a - `convention_identifier' of Fortran (respectively, C) in the - interfacing pragmas (see Annex B), thus allowing Ada programs to - interface with programs written in that language. - Followed. - - *G.1.1(56-58): Complex Types* - - - Because the usual mathematical meaning of multiplication of a - complex operand and a real operand is that of the scaling of both - components of the former by the latter, an implementation should - not perform this operation by first promoting the real operand to - complex type and then performing a full complex multiplication. - In systems that, in the future, support an Ada binding to IEC - 559:1989, the latter technique will not generate the required - result when one of the components of the complex operand is - infinite. (Explicit multiplication of the infinite component by - the zero component obtained during promotion yields a NaN that - propagates into the final result.) Analogous advice applies in the - case of multiplication of a complex operand and a pure-imaginary - operand, and in the case of division of a complex operand by a - real or pure-imaginary operand. - Not followed. - - - Similarly, because the usual mathematical meaning of addition of a - complex operand and a real operand is that the imaginary operand - remains unchanged, an implementation should not perform this - operation by first promoting the real operand to complex type and - then performing a full complex addition. In implementations in - which the `Signed_Zeros' attribute of the component type is `True' - (and which therefore conform to IEC 559:1989 in regard to the - handling of the sign of zero in predefined arithmetic operations), - the latter technique will not generate the required result when - the imaginary component of the complex operand is a negatively - signed zero. (Explicit addition of the negative zero to the zero - obtained during promotion yields a positive zero.) Analogous - advice applies in the case of addition of a complex operand and a - pure-imaginary operand, and in the case of subtraction of a - complex operand and a real or pure-imaginary operand. - Not followed. - - - Implementations in which `Real'Signed_Zeros' is `True' should - attempt to provide a rational treatment of the signs of zero - results and result components. As one example, the result of the - `Argument' function should have the sign of the imaginary - component of the parameter `X' when the point represented by that - parameter lies on the positive real axis; as another, the sign of - the imaginary component of the `Compose_From_Polar' function - should be the same as (respectively, the opposite of) that of the - `Argument' parameter when that parameter has a value of zero and - the `Modulus' parameter has a nonnegative (respectively, negative) - value. - Followed. - - *G.1.2(49): Complex Elementary Functions* - - Implementations in which `Complex_Types.Real'Signed_Zeros' is - `True' should attempt to provide a rational treatment of the signs - of zero results and result components. For example, many of the - complex elementary functions have components that are odd - functions of one of the parameter components; in these cases, the - result component should have the sign of the parameter component - at the origin. Other complex elementary functions have zero - components whose sign is opposite that of a parameter component at - the origin, or is always positive or always negative. - Followed. - - *G.2.4(19): Accuracy Requirements* - - The versions of the forward trigonometric functions without a - `Cycle' parameter should not be implemented by calling the - corresponding version with a `Cycle' parameter of - `2.0*Numerics.Pi', since this will not provide the required - accuracy in some portions of the domain. For the same reason, the - version of `Log' without a `Base' parameter should not be - implemented by calling the corresponding version with a `Base' - parameter of `Numerics.e'. - Followed. - - *G.2.6(15): Complex Arithmetic Accuracy* - - The version of the `Compose_From_Polar' function without a `Cycle' - parameter should not be implemented by calling the corresponding - version with a `Cycle' parameter of `2.0*Numerics.Pi', since this - will not provide the required accuracy in some portions of the - domain. - Followed. - -  - File: gnat_rm.info, Node: Implementation Defined Characteristics, Next: Intrinsic Subprograms, Prev: Implementation Advice, Up: Top - - Implementation Defined Characteristics - ************************************** - - In addition to the implementation dependent pragmas and attributes, - and the implementation advice, there are a number of other features of - Ada 95 that are potentially implementation dependent. These are - mentioned throughout the Ada 95 Reference Manual, and are summarized in - annex M. - - A requirement for conforming Ada compilers is that they provide - documentation describing how the implementation deals with each of these - issues. In this chapter, you will find each point in annex M listed - followed by a description in italic font of how GNAT handles the - implementation dependence. - - You can use this chapter as a guide to minimizing implementation - dependent features in your programs if portability to other compilers - and other operating systems is an important consideration. The numbers - in each section below correspond to the paragraph number in the Ada 95 - Reference Manual. - - - *2*. Whether or not each recommendation given in Implementation Advice - is followed. See 1.1.2(37). - - *Note Implementation Advice::. - - - *3*. Capacity limitations of the implementation. See 1.1.3(3). - - The complexity of programs that can be processed is limited only by the - total amount of available virtual memory, and disk space for the - generated object files. - - - *4*. Variations from the standard that are impractical to avoid given - the implementation's execution environment. See 1.1.3(6). - - There are no variations from the standard. - - - *5*. Which `code_statement's cause external interactions. See - 1.1.3(10). - - Any `code_statement' can potentially cause external interactions. - - - *6*. The coded representation for the text of an Ada program. See - 2.1(4). - - See separate section on source representation. - - - *7*. The control functions allowed in comments. See 2.1(14). - - See separate section on source representation. - - - *8*. The representation for an end of line. See 2.2(2). - - See separate section on source representation. - - - *9*. Maximum supported line length and lexical element length. See - 2.2(15). - - The maximum line length is 255 characters an the maximum length of a - lexical element is also 255 characters. - - - *10*. Implementation defined pragmas. See 2.8(14). - - *Note Implementation Defined Pragmas::. - - - *11*. Effect of pragma `Optimize'. See 2.8(27). - - Pragma `Optimize', if given with a `Time' or `Space' parameter, checks - that the optimization flag is set, and aborts if it is not. - - - *12*. The sequence of characters of the value returned by `S'Image' - when some of the graphic characters of `S'Wide_Image' are not defined - in `Character'. See 3.5(37). - - The sequence of characters is as defined by the wide character encoding - method used for the source. See section on source representation for - further details. - - - *13*. The predefined integer types declared in `Standard'. See - 3.5.4(25). - - `Short_Short_Integer' - 8 bit signed - - `Short_Integer' - (Short) 16 bit signed - - `Integer' - 32 bit signed - - `Long_Integer' - 64 bit signed (Alpha OpenVMS only) 32 bit signed (all other - targets) - - `Long_Long_Integer' - 64 bit signed - - - *14*. Any nonstandard integer types and the operators defined for - them. See 3.5.4(26). - - There are no nonstandard integer types. - - - *15*. Any nonstandard real types and the operators defined for them. - See 3.5.6(8). - - There are no nonstandard real types. - - - *16*. What combinations of requested decimal precision and range are - supported for floating point types. See 3.5.7(7). - - The precision and range is as defined by the IEEE standard. - - - *17*. The predefined floating point types declared in `Standard'. See - 3.5.7(16). - - `Short_Float' - 32 bit IEEE short - - `Float' - (Short) 32 bit IEEE short - - `Long_Float' - 64 bit IEEE long - - `Long_Long_Float' - 64 bit IEEE long (80 bit IEEE long on x86 processors) - - - *18*. The small of an ordinary fixed point type. See 3.5.9(8). - - `Fine_Delta' is 2**(-63) - - - *19*. What combinations of small, range, and digits are supported for - fixed point types. See 3.5.9(10). - - Any combinations are permitted that do not result in a small less than - `Fine_Delta' and do not result in a mantissa larger than 63 bits. If - the mantissa is larger than 53 bits on machines where Long_Long_Float - is 64 bits (true of all architectures except ia32), then the output from - Text_IO is accurate to only 53 bits, rather than the full mantissa. - This is because floating-point conversions are used to convert fixed - point. - - - *20*. The result of `Tags.Expanded_Name' for types declared within an - unnamed `block_statement'. See 3.9(10). - - Block numbers of the form `BNNN', where NNN is a decimal integer are - allocated. - - - *21*. Implementation-defined attributes. See 4.1.4(12). - - *Note Implementation Defined Attributes::. - - - *22*. Any implementation-defined time types. See 9.6(6). - - There are no implementation-defined time types. - - - *23*. The time base associated with relative delays. - - See 9.6(20). The time base used is that provided by the C library - function `gettimeofday'. - - - *24*. The time base of the type `Calendar.Time'. See 9.6(23). - - The time base used is that provided by the C library function - `gettimeofday'. - - - *25*. The time zone used for package `Calendar' operations. See - 9.6(24). - - The time zone used by package `Calendar' is the current system time zone - setting for local time, as accessed by the C library function - `localtime'. - - - *26*. Any limit on `delay_until_statements' of `select_statements'. - See 9.6(29). - - There are no such limits. - - - *27*. Whether or not two non overlapping parts of a composite object - are independently addressable, in the case where packing, record - layout, or `Component_Size' is specified for the object. See 9.10(1). - - Separate components are independently addressable if they do not share - overlapping storage units. - - - *28*. The representation for a compilation. See 10.1(2). - - A compilation is represented by a sequence of files presented to the - compiler in a single invocation of the `gcc' command. - - - *29*. Any restrictions on compilations that contain multiple - compilation_units. See 10.1(4). - - No single file can contain more than one compilation unit, but any - sequence of files can be presented to the compiler as a single - compilation. - - - *30*. The mechanisms for creating an environment and for adding and - replacing compilation units. See 10.1.4(3). - - See separate section on compilation model. - - - *31*. The manner of explicitly assigning library units to a partition. - See 10.2(2). - - If a unit contains an Ada main program, then the Ada units for the - partition are determined by recursive application of the rules in the - Ada Reference Manual section 10.2(2-6). In other words, the Ada units - will be those that are needed by the main program, and then this - definition of need is applied recursively to those units, and the - partition contains the transitive closure determined by this - relationship. In short, all the necessary units are included, with no - need to explicitly specify the list. If additional units are required, - e.g. by foreign language units, then all units must be mentioned in the - context clause of one of the needed Ada units. - - If the partition contains no main program, or if the main program is - in a language other than Ada, then GNAT provides the binder options - `-z' and `-n' respectively, and in this case a list of units can be - explicitly supplied to the binder for inclusion in the partition (all - units needed by these units will also be included automatically). For - full details on the use of these options, refer to the `GNAT User's - Guide' sections on Binding and Linking. - - - *32*. The implementation-defined means, if any, of specifying which - compilation units are needed by a given compilation unit. See 10.2(2). - - The units needed by a given compilation unit are as defined in the Ada - Reference Manual section 10.2(2-6). There are no - implementation-defined pragmas or other implementation-defined means - for specifying needed units. - - - *33*. The manner of designating the main subprogram of a partition. - See 10.2(7). - - The main program is designated by providing the name of the - corresponding `ALI' file as the input parameter to the binder. - - - *34*. The order of elaboration of `library_items'. See 10.2(18). - - The first constraint on ordering is that it meets the requirements of - chapter 10 of the Ada 95 Reference Manual. This still leaves some - implementation dependent choices, which are resolved by first - elaborating bodies as early as possible (i.e. in preference to specs - where there is a choice), and second by evaluating the immediate with - clauses of a unit to determine the probably best choice, and third by - elaborating in alphabetical order of unit names where a choice still - remains. - - - *35*. Parameter passing and function return for the main subprogram. - See 10.2(21). - - The main program has no parameters. It may be a procedure, or a - function returning an integer type. In the latter case, the returned - integer value is the return code of the program. - - - *36*. The mechanisms for building and running partitions. See - 10.2(24). - - GNAT itself supports programs with only a single partition. The - GNATDIST tool provided with the GLADE package (which also includes an - implementation of the PCS) provides a completely flexible method for - building and running programs consisting of multiple partitions. See - the separate GLADE manual for details. - - - *37*. The details of program execution, including program termination. - See 10.2(25). - - See separate section on compilation model. - - - *38*. The semantics of any non-active partitions supported by the - implementation. See 10.2(28). - - Passive partitions are supported on targets where shared memory is - provided by the operating system. See the GLADE reference manual for - further details. - - - *39*. The information returned by `Exception_Message'. See 11.4.1(10). - - Exception message returns the null string unless a specific message has - been passed by the program. - - - *40*. The result of `Exceptions.Exception_Name' for types declared - within an unnamed `block_statement'. See 11.4.1(12). - - Blocks have implementation defined names of the form `BNNN' where NNN - is an integer. - - - *41*. The information returned by `Exception_Information'. See - 11.4.1(13). - - `Exception_Information' returns a string in the following format: - - _Exception_Name:_ nnnnn - _Message:_ mmmmm - _PID:_ ppp - _Call stack traceback locations:_ - 0xhhhh 0xhhhh 0xhhhh ... 0xhhh - - where - - * `nnnn' is the fully qualified name of the exception in all upper - case letters. This line is always present. - - * `mmmm' is the message (this line present only if message is - non-null) - - * `ppp' is the Process Id value as a decimal integer (this line is - present only if the Process Id is non-zero). Currently we are not - making use of this field. - - * The Call stack traceback locations line and the following values - are present only if at least one traceback location was recorded. - The values are given in C style format, with lower case letters - for a-f, and only as many digits present as are necessary. - - The line terminator sequence at the end of each line, including the - last line is a single `LF' character (`16#0A#'). - - - *42*. Implementation-defined check names. See 11.5(27). - - No implementation-defined check names are supported. - - - *43*. The interpretation of each aspect of representation. See - 13.1(20). - - See separate section on data representations. - - - *44*. Any restrictions placed upon representation items. See 13.1(20). - - See separate section on data representations. - - - *45*. The meaning of `Size' for indefinite subtypes. See 13.3(48). - - Size for an indefinite subtype is the maximum possible size, except that - for the case of a subprogram parameter, the size of the parameter object - is the actual size. - - - *46*. The default external representation for a type tag. See - 13.3(75). - - The default external representation for a type tag is the fully expanded - name of the type in upper case letters. - - - *47*. What determines whether a compilation unit is the same in two - different partitions. See 13.3(76). - - A compilation unit is the same in two different partitions if and only - if it derives from the same source file. - - - *48*. Implementation-defined components. See 13.5.1(15). - - The only implementation defined component is the tag for a tagged type, - which contains a pointer to the dispatching table. - - - *49*. If `Word_Size' = `Storage_Unit', the default bit ordering. See - 13.5.3(5). - - `Word_Size' (32) is not the same as `Storage_Unit' (8) for this - implementation, so no non-default bit ordering is supported. The - default bit ordering corresponds to the natural endianness of the - target architecture. - - - *50*. The contents of the visible part of package `System' and its - language-defined children. See 13.7(2). - - See the definition of these packages in files `system.ads' and - `s-stoele.ads'. - - - *51*. The contents of the visible part of package - `System.Machine_Code', and the meaning of `code_statements'. See - 13.8(7). - - See the definition and documentation in file `s-maccod.ads'. - - - *52*. The effect of unchecked conversion. See 13.9(11). - - Unchecked conversion between types of the same size and results in an - uninterpreted transmission of the bits from one type to the other. If - the types are of unequal sizes, then in the case of discrete types, a - shorter source is first zero or sign extended as necessary, and a - shorter target is simply truncated on the left. For all non-discrete - types, the source is first copied if necessary to ensure that the - alignment requirements of the target are met, then a pointer is - constructed to the source value, and the result is obtained by - dereferencing this pointer after converting it to be a pointer to the - target type. - - - *53*. The manner of choosing a storage pool for an access type when - `Storage_Pool' is not specified for the type. See 13.11(17). - - There are 3 different standard pools used by the compiler when - `Storage_Pool' is not specified depending whether the type is local to - a subprogram or defined at the library level and whether - `Storage_Size'is specified or not. See documentation in the runtime - library units `System.Pool_Global', `System.Pool_Size' and - `System.Pool_Local' in files `s-poosiz.ads', `s-pooglo.ads' and - `s-pooloc.ads' for full details on the default pools used. - - - *54*. Whether or not the implementation provides user-accessible names - for the standard pool type(s). See 13.11(17). - - See documentation in the sources of the run time mentioned in paragraph - *53* . All these pools are accessible by means of `with''ing these - units. - - - *55*. The meaning of `Storage_Size'. See 13.11(18). - - `Storage_Size' is measured in storage units, and refers to the total - space available for an access type collection, or to the primary stack - space for a task. - - - *56*. Implementation-defined aspects of storage pools. See 13.11(22). - - See documentation in the sources of the run time mentioned in paragraph - *53* for details on GNAT-defined aspects of storage pools. - - - *57*. The set of restrictions allowed in a pragma `Restrictions'. See - 13.12(7). - - All RM defined Restriction identifiers are implemented. The following - additional restriction identifiers are provided. There are two separate - lists of implementation dependent restriction identifiers. The first - set requires consistency throughout a partition (in other words, if the - restriction identifier is used for any compilation unit in the - partition, then all compilation units in the partition must obey the - restriction. - - `Boolean_Entry_Barriers' - This restriction ensures at compile time that barriers in entry - declarations for protected types are restricted to references to - simple boolean variables defined in the private part of the - protected type. No other form of entry barriers is permitted. - This is one of the restrictions of the Ravenscar profile for - limited tasking (see also pragma `Ravenscar'). - - `Max_Entry_Queue_Depth => Expr' - This restriction is a declaration that any protected entry - compiled in the scope of the restriction has at most the specified - number of tasks waiting on the entry at any one time, and so no - queue is required. This restriction is not checked at compile - time. A program execution is erroneous if an attempt is made to - queue more than the specified number of tasks on such an entry. - - `No_Calendar' - This restriction ensures at compile time that there is no implicit - or explicit dependence on the package `Ada.Calendar'. - - `No_Dynamic_Interrupts' - This restriction ensures at compile time that there is no attempt - to dynamically associate interrupts. Only static association is - allowed. - - `No_Enumeration_Maps' - This restriction ensures at compile time that no operations - requiring enumeration maps are used (that is Image and Value - attributes applied to enumeration types). - - `No_Entry_Calls_In_Elaboration_Code' - This restriction ensures at compile time that no task or protected - entry calls are made during elaboration code. As a result of the - use of this restriction, the compiler can assume that no code past - an accept statement in a task can be executed at elaboration time. - - `No_Exception_Handlers' - This restriction ensures at compile time that there are no explicit - exception handlers. - - `No_Implicit_Conditionals' - This restriction ensures that the generated code does not contain - any implicit conditionals, either by modifying the generated code - where possible, or by rejecting any construct that would otherwise - generate an implicit conditional. The details and use of this - restriction are described in more detail in the High Integrity - product documentation. - - `No_Implicit_Loops' - This restriction ensures that the generated code does not contain - any implicit `for' loops, either by modifying the generated code - where possible, or by rejecting any construct that would otherwise - generate an implicit `for' loop. The details and use of this - restriction are described in more detail in the High Integrity - product documentation. - - `No_Local_Protected_Objects' - This restriction ensures at compile time that protected objects are - only declared at the library level. - - `No_Protected_Type_Allocators' - This restriction ensures at compile time that there are no - allocator expressions that attempt to allocate protected objects. - - `No_Secondary_Stack' - This restriction ensures at compile time that the generated code - does not contain any reference to the secondary stack. The - secondary stack is used to implement functions returning - unconstrained objects (arrays or records) on some targets. The - details and use of this restriction are described in more detail - in the High Integrity product documentation. - - `No_Select_Statements' - This restriction ensures at compile time no select statements of - any kind are permitted, that is the keyword `select' may not - appear. This is one of the restrictions of the Ravenscar profile - for limited tasking (see also pragma `Ravenscar'). - - `No_Standard_Storage_Pools' - This restriction ensures at compile time that no access types use - the standard default storage pool. Any access type declared must - have an explicit Storage_Pool attribute defined specifying a - user-defined storage pool. - - `No_Streams' - This restriction ensures at compile time that there are no - implicit or explicit dependencies on the package `Ada.Streams'. - - `No_Task_Attributes' - This restriction ensures at compile time that there are no - implicit or explicit dependencies on the package - `Ada.Task_Attributes'. - - `No_Task_Termination' - This restriction ensures at compile time that no terminate - alternatives appear in any task body. - - `No_Tasking' - This restriction prevents the declaration of tasks or task types - throughout the partition. It is similar in effect to the use of - `Max_Tasks => 0' except that violations are caught at compile time - and cause an error message to be output either by the compiler or - binder. - - `No_Wide_Characters' - This restriction ensures at compile time that no uses of the types - `Wide_Character' or `Wide_String' appear, and that no wide - character literals appear in the program (that is literals - representing characters not in type `Character'. - - `Static_Priorities' - This restriction ensures at compile time that all priority - expressions are static, and that there are no dependencies on the - package `Ada.Dynamic_Priorities'. - - `Static_Storage_Size' - This restriction ensures at compile time that any expression - appearing in a Storage_Size pragma or attribute definition clause - is static. - - The second set of implementation dependent restriction identifiers does - not require partition-wide consistency. The restriction may be - enforced for a single compilation unit without any effect on any of the - other compilation units in the partition. - - `No_Elaboration_Code' - This restriction ensures at compile time that no elaboration code - is generated. Note that this is not the same condition as is - enforced by pragma `Preelaborate'. There are cases in which - pragma `Preelaborate' still permits code to be generated (e.g. - code to initialize a large array to all zeroes), and there are - cases of units which do not meet the requirements for pragma - `Preelaborate', but for which no elaboration code is generated. - Generally, it is the case that preelaborable units will meet the - restrictions, with the exception of large aggregates initialized - with an others_clause, and exception declarations (which generate - calls to a run-time registry procedure). Note that this - restriction is enforced on a unit by unit basis, it need not be - obeyed consistently throughout a partition. - - `No_Entry_Queue' - This restriction is a declaration that any protected entry - compiled in the scope of the restriction has at most one task - waiting on the entry at any one time, and so no queue is required. - This restriction is not checked at compile time. A program - execution is erroneous if an attempt is made to queue a second - task on such an entry. - - `No_Implementation_Attributes' - This restriction checks at compile time that no GNAT-defined - attributes are present. With this restriction, the only - attributes that can be used are those defined in the Ada 95 - Reference Manual. - - `No_Implementation_Pragmas' - This restriction checks at compile time that no GNAT-defined - pragmas are present. With this restriction, the only pragmas that - can be used are those defined in the Ada 95 Reference Manual. - - `No_Implementation_Restrictions' - This restriction checks at compile time that no GNAT-defined - restriction identifiers (other than - `No_Implementation_Restrictions' itself) are present. With this - restriction, the only other restriction identifiers that can be - used are those defined in the Ada 95 Reference Manual. - - - *58*. The consequences of violating limitations on `Restrictions' - pragmas. See 13.12(9). - - Restrictions that can be checked at compile time result in illegalities - if violated. Currently there are no other consequences of violating - restrictions. - - - *59*. The representation used by the `Read' and `Write' attributes of - elementary types in terms of stream elements. See 13.13.2(9). - - The representation is the in-memory representation of the base type of - the type, using the number of bits corresponding to the `TYPE'Size' - value, and the natural ordering of the machine. - - - *60*. The names and characteristics of the numeric subtypes declared - in the visible part of package `Standard'. See A.1(3). - - See items describing the integer and floating-point types supported. - - - *61*. The accuracy actually achieved by the elementary functions. See - A.5.1(1). - - The elementary functions correspond to the functions available in the C - library. Only fast math mode is implemented. - - - *62*. The sign of a zero result from some of the operators or - functions in `Numerics.Generic_Elementary_Functions', when - `Float_Type'Signed_Zeros' is `True'. See A.5.1(46). - - The sign of zeroes follows the requirements of the IEEE 754 standard on - floating-point. - - - *63*. The value of `Numerics.Float_Random.Max_Image_Width'. See - A.5.2(27). - - Maximum image width is 649, see library file `a-numran.ads'. - - - *64*. The value of `Numerics.Discrete_Random.Max_Image_Width'. See - A.5.2(27). - - Maximum image width is 80, see library file `a-nudira.ads'. - - - *65*. The algorithms for random number generation. See A.5.2(32). - - The algorithm is documented in the source files `a-numran.ads' and - `a-numran.adb'. - - - *66*. The string representation of a random number generator's state. - See A.5.2(38). - - See the documentation contained in the file `a-numran.adb'. - - - *67*. The minimum time interval between calls to the time-dependent - Reset procedure that are guaranteed to initiate different random number - sequences. See A.5.2(45). - - The minimum period between reset calls to guarantee distinct series of - random numbers is one microsecond. - - - *68*. The values of the `Model_Mantissa', `Model_Emin', - `Model_Epsilon', `Model', `Safe_First', and `Safe_Last' attributes, if - the Numerics Annex is not supported. See A.5.3(72). - - See the source file `ttypef.ads' for the values of all numeric - attributes. - - - *69*. Any implementation-defined characteristics of the input-output - packages. See A.7(14). - - There are no special implementation defined characteristics for these - packages. - - - *70*. The value of `Buffer_Size' in `Storage_IO'. See A.9(10). - - All type representations are contiguous, and the `Buffer_Size' is the - value of `TYPE'Size' rounded up to the next storage unit boundary. - - - *71*. External files for standard input, standard output, and standard - error See A.10(5). - - These files are mapped onto the files provided by the C streams - libraries. See source file `i-cstrea.ads' for further details. - - - *72*. The accuracy of the value produced by `Put'. See A.10.9(36). - - If more digits are requested in the output than are represented by the - precision of the value, zeroes are output in the corresponding least - significant digit positions. - - - *73*. The meaning of `Argument_Count', `Argument', and `Command_Name'. - See A.15(1). - - These are mapped onto the `argv' and `argc' parameters of the main - program in the natural manner. - - - *74*. Implementation-defined convention names. See B.1(11). - - The following convention names are supported - - `Ada' - Ada - - `Assembler' - Assembly language - - `Asm' - Synonym for Assembler - - `Assembly' - Synonym for Assembler - - `C' - C - - `C_Pass_By_Copy' - Allowed only for record types, like C, but also notes that record - is to be passed by copy rather than reference. - - `COBOL' - COBOL - - `CPP' - C++ - - `Default' - Treated the same as C - - `External' - Treated the same as C - - `Fortran' - Fortran - - `Intrinsic' - For support of pragma `Import' with convention Intrinsic, see - separate section on Intrinsic Subprograms. - - `Stdcall' - Stdcall (used for Windows implementations only). This convention - correspond to the WINAPI (previously called Pascal convention) - C/C++ convention under Windows. A function with this convention - cleans the stack before exit. - - `DLL' - Synonym for Stdcall - - `Win32' - Synonym for Stdcall - - `Stubbed' - Stubbed is a special convention used to indicate that the body of - the subprogram will be entirely ignored. Any call to the - subprogram is converted into a raise of the `Program_Error' - exception. If a pragma `Import' specifies convention `stubbed' - then no body need be present at all. This convention is useful - during development for the inclusion of subprograms whose body has - not yet been written. - - In addition, all otherwise unrecognized convention names are also - treated as being synonymous with convention C. In all implementations - except for VMS, use of such other names results in a warning. In VMS - implementations, these names are accepted silently. - - - *75*. The meaning of link names. See B.1(36). - - Link names are the actual names used by the linker. - - - *76*. The manner of choosing link names when neither the link name nor - the address of an imported or exported entity is specified. See - B.1(36). - - The default linker name is that which would be assigned by the relevant - external language, interpreting the Ada name as being in all lower case - letters. - - - *77*. The effect of pragma `Linker_Options'. See B.1(37). - - The string passed to `Linker_Options' is presented uninterpreted as an - argument to the link command, unless it contains Ascii.NUL characters. - NUL characters if they appear act as argument separators, so for example - - pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef"); - - causes two separate arguments `-labc' and `-ldef' to be passed to the - linker. The order of linker options is preserved for a given unit. The - final list of options passed to the linker is in reverse order of the - elaboration order. For example, linker options fo a body always appear - before the options from the corresponding package spec. - - - *78*. The contents of the visible part of package `Interfaces' and its - language-defined descendants. See B.2(1). - - See files with prefix `i-' in the distributed library. - - - *79*. Implementation-defined children of package `Interfaces'. The - contents of the visible part of package `Interfaces'. See B.2(11). - - See files with prefix `i-' in the distributed library. - - - *80*. The types `Floating', `Long_Floating', `Binary', `Long_Binary', - `Decimal_ Element', and `COBOL_Character'; and the initialization of - the variables `Ada_To_COBOL' and `COBOL_To_Ada', in `Interfaces.COBOL'. - See B.4(50). - - `Floating' - Float - - `Long_Floating' - (Floating) Long_Float - - `Binary' - Integer - - `Long_Binary' - Long_Long_Integer - - `Decimal_Element' - Character - - `COBOL_Character' - Character - - For initialization, see the file `i-cobol.ads' in the distributed - library. - - - *81*. Support for access to machine instructions. See C.1(1). - - See documentation in file `s-maccod.ads' in the distributed library. - - - *82*. Implementation-defined aspects of access to machine operations. - See C.1(9). - - See documentation in file `s-maccod.ads' in the distributed library. - - - *83*. Implementation-defined aspects of interrupts. See C.3(2). - - Interrupts are mapped to signals or conditions as appropriate. See - definition of unit `Ada.Interrupt_Names' in source file `a-intnam.ads' - for details on the interrupts supported on a particular target. - - - *84*. Implementation-defined aspects of pre-elaboration. See C.4(13). - - GNAT does not permit a partition to be restarted without reloading, - except under control of the debugger. - - - *85*. The semantics of pragma `Discard_Names'. See C.5(7). - - Pragma `Discard_Names' causes names of enumeration literals to be - suppressed. In the presence of this pragma, the Image attribute - provides the image of the Pos of the literal, and Value accepts Pos - values. - - - *86*. The result of the `Task_Identification.Image' attribute. See - C.7.1(7). - - The result of this attribute is an 8-digit hexadecimal string - representing the virtual address of the task control block. - - - *87*. The value of `Current_Task' when in a protected entry or - interrupt handler. See C.7.1(17). - - Protected entries or interrupt handlers can be executed by any - convenient thread, so the value of `Current_Task' is undefined. - - - *88*. The effect of calling `Current_Task' from an entry body or - interrupt handler. See C.7.1(19). - - The effect of calling `Current_Task' from an entry body or interrupt - handler is to return the identification of the task currently executing - the code. - - - *89*. Implementation-defined aspects of `Task_Attributes'. See - C.7.2(19). - - There are no implementation-defined aspects of `Task_Attributes'. - - - *90*. Values of all `Metrics'. See D(2). - - The metrics information for GNAT depends on the performance of the - underlying operating system. The sources of the run-time for tasking - implementation, together with the output from `-gnatG' can be used to - determine the exact sequence of operating systems calls made to - implement various tasking constructs. Together with appropriate - information on the performance of the underlying operating system, on - the exact target in use, this information can be used to determine the - required metrics. - - - *91*. The declarations of `Any_Priority' and `Priority'. See D.1(11). - - See declarations in file `system.ads'. - - - *92*. Implementation-defined execution resources. See D.1(15). - - There are no implementation-defined execution resources. - - - *93*. Whether, on a multiprocessor, a task that is waiting for access - to a protected object keeps its processor busy. See D.2.1(3). - - On a multi-processor, a task that is waiting for access to a protected - object does not keep its processor busy. - - - *94*. The affect of implementation defined execution resources on task - dispatching. See D.2.1(9). - - Tasks map to threads in the threads package used by GNAT. Where - possible and appropriate, these threads correspond to native threads of - the underlying operating system. - - - *95*. Implementation-defined `policy_identifiers' allowed in a pragma - `Task_Dispatching_Policy'. See D.2.2(3). - - There are no implementation-defined policy-identifiers allowed in this - pragma. - - - *96*. Implementation-defined aspects of priority inversion. See - D.2.2(16). - - Execution of a task cannot be preempted by the implementation processing - of delay expirations for lower priority tasks. - - - *97*. Implementation defined task dispatching. See D.2.2(18). - - The policy is the same as that of the underlying threads implementation. - - - *98*. Implementation-defined `policy_identifiers' allowed in a pragma - `Locking_Policy'. See D.3(4). - - The only implementation defined policy permitted in GNAT is - `Inheritance_Locking'. On targets that support this policy, locking is - implemented by inheritance, i.e. the task owning the lock operates at a - priority equal to the highest priority of any task currently requesting - the lock. - - - *99*. Default ceiling priorities. See D.3(10). - - The ceiling priority of protected objects of the type - `System.Interrupt_Priority'Last' as described in the Ada 95 Reference - Manual D.3(10), - - - *100*. The ceiling of any protected object used internally by the - implementation. See D.3(16). - - The ceiling priority of internal protected objects is - `System.Priority'Last'. - - - *101*. Implementation-defined queuing policies. See D.4(1). - - There are no implementation-defined queueing policies. - - - *102*. On a multiprocessor, any conditions that cause the completion - of an aborted construct to be delayed later than what is specified for - a single processor. See D.6(3). - - The semantics for abort on a multi-processor is the same as on a single - processor, there are no further delays. - - - *103*. Any operations that implicitly require heap storage allocation. - See D.7(8). - - The only operation that implicitly requires heap storage allocation is - task creation. - - - *104*. Implementation-defined aspects of pragma `Restrictions'. See - D.7(20). - - There are no such implementation-defined aspects. - - - *105*. Implementation-defined aspects of package `Real_Time'. See - D.8(17). - - There are no implementation defined aspects of package `Real_Time'. - - - *106*. Implementation-defined aspects of `delay_statements'. See - D.9(8). - - Any difference greater than one microsecond will cause the task to be - delayed (see D.9(7)). - - - *107*. The upper bound on the duration of interrupt blocking caused by - the implementation. See D.12(5). - - The upper bound is determined by the underlying operating system. In - no cases is it more than 10 milliseconds. - - - *108*. The means for creating and executing distributed programs. See - E(5). - - The GLADE package provides a utility GNATDIST for creating and executing - distributed programs. See the GLADE reference manual for further - details. - - - *109*. Any events that can result in a partition becoming - inaccessible. See E.1(7). - - See the GLADE reference manual for full details on such events. - - - *110*. The scheduling policies, treatment of priorities, and - management of shared resources between partitions in certain cases. See - E.1(11). - - See the GLADE reference manual for full details on these aspects of - multi-partition execution. - - - *111*. Events that cause the version of a compilation unit to change. - See E.3(5). - - Editing the source file of a compilation unit, or the source files of - any units on which it is dependent in a significant way cause the - version to change. No other actions cause the version number to - change. All changes are significant except those which affect only - layout, capitalization or comments. - - - *112*. Whether the execution of the remote subprogram is immediately - aborted as a result of cancellation. See E.4(13). - - See the GLADE reference manual for details on the effect of abort in a - distributed application. - - - *113*. Implementation-defined aspects of the PCS. See E.5(25). - - See the GLADE reference manual for a full description of all - implementation defined aspects of the PCS. - - - *114*. Implementation-defined interfaces in the PCS. See E.5(26). - - See the GLADE reference manual for a full description of all - implementation defined interfaces. - - - *115*. The values of named numbers in the package `Decimal'. See - F.2(7). - - `Max_Scale' - +18 - - `Min_Scale' - -18 - - `Min_Delta' - 1.0E-18 - - `Max_Delta' - 1.0E+18 - - `Max_Decimal_Digits' - 18 - - - *116*. The value of `Max_Picture_Length' in the package - `Text_IO.Editing'. See F.3.3(16). - - 64 - - - *117*. The value of `Max_Picture_Length' in the package - `Wide_Text_IO.Editing'. See F.3.4(5). - - 64 - - - *118*. The accuracy actually achieved by the complex elementary - functions and by other complex arithmetic operations. See G.1(1). - - Standard library functions are used for the complex arithmetic - operations. Only fast math mode is currently supported. - - - *119*. The sign of a zero result (or a component thereof) from any - operator or function in `Numerics.Generic_Complex_Types', when - `Real'Signed_Zeros' is True. See G.1.1(53). - - The signs of zero values are as recommended by the relevant - implementation advice. - - - *120*. The sign of a zero result (or a component thereof) from any - operator or function in - `Numerics.Generic_Complex_Elementary_Functions', when - `Real'Signed_Zeros' is `True'. See G.1.2(45). - - The signs of zero values are as recommended by the relevant - implementation advice. - - - *121*. Whether the strict mode or the relaxed mode is the default. - See G.2(2). - - The strict mode is the default. There is no separate relaxed mode. - GNAT provides a highly efficient implementation of strict mode. - - - *122*. The result interval in certain cases of fixed-to-float - conversion. See G.2.1(10). - - For cases where the result interval is implementation dependent, the - accuracy is that provided by performing all operations in 64-bit IEEE - floating-point format. - - - *123*. The result of a floating point arithmetic operation in overflow - situations, when the `Machine_Overflows' attribute of the result type - is `False'. See G.2.1(13). - - Infinite and Nan values are produced as dictated by the IEEE - floating-point standard. - - - *124*. The result interval for division (or exponentiation by a - negative exponent), when the floating point hardware implements division - as multiplication by a reciprocal. See G.2.1(16). - - Not relevant, division is IEEE exact. - - - *125*. The definition of close result set, which determines the - accuracy of certain fixed point multiplications and divisions. See - G.2.3(5). - - Operations in the close result set are performed using IEEE long format - floating-point arithmetic. The input operands are converted to - floating-point, the operation is done in floating-point, and the result - is converted to the target type. - - - *126*. Conditions on a `universal_real' operand of a fixed point - multiplication or division for which the result shall be in the perfect - result set. See G.2.3(22). - - The result is only defined to be in the perfect result set if the result - can be computed by a single scaling operation involving a scale factor - representable in 64-bits. - - - *127*. The result of a fixed point arithmetic operation in overflow - situations, when the `Machine_Overflows' attribute of the result type - is `False'. See G.2.3(27). - - Not relevant, `Machine_Overflows' is `True' for fixed-point types. - - - *128*. The result of an elementary function reference in overflow - situations, when the `Machine_Overflows' attribute of the result type - is `False'. See G.2.4(4). - - IEEE infinite and Nan values are produced as appropriate. - - - *129*. The value of the angle threshold, within which certain - elementary functions, complex arithmetic operations, and complex - elementary functions yield results conforming to a maximum relative - error bound. See G.2.4(10). - - Information on this subject is not yet available. - - - *130*. The accuracy of certain elementary functions for parameters - beyond the angle threshold. See G.2.4(10). - - Information on this subject is not yet available. - - - *131*. The result of a complex arithmetic operation or complex - elementary function reference in overflow situations, when the - `Machine_Overflows' attribute of the corresponding real type is - `False'. See G.2.6(5). - - IEEE infinite and Nan values are produced as appropriate. - - - *132*. The accuracy of certain complex arithmetic operations and - certain complex elementary functions for parameters (or components - thereof) beyond the angle threshold. See G.2.6(8). - - Information on those subjects is not yet available. - - - *133*. Information regarding bounded errors and erroneous execution. - See H.2(1). - - Information on this subject is not yet available. - - - *134*. Implementation-defined aspects of pragma `Inspection_Point'. - See H.3.2(8). - - Pragma `Inspection_Point' ensures that the variable is live and can be - examined by the debugger at the inspection point. - - - *135*. Implementation-defined aspects of pragma `Restrictions'. See - H.4(25). - - There are no implementation-defined aspects of pragma `Restrictions'. - The use of pragma `Restrictions [No_Exceptions]' has no effect on the - generated code. Checks must suppressed by use of pragma `Suppress'. - - - *136*. Any restrictions on pragma `Restrictions'. See H.4(27). - - There are no restrictions on pragma `Restrictions'. - -  - File: gnat_rm.info, Node: Intrinsic Subprograms, Next: Representation Clauses and Pragmas, Prev: Implementation Defined Characteristics, Up: Top - - Intrinsic Subprograms - ********************* - - * Menu: - - * Intrinsic Operators:: - * Enclosing_Entity:: - * Exception_Information:: - * Exception_Message:: - * Exception_Name:: - * File:: - * Line:: - * Rotate_Left:: - * Rotate_Right:: - * Shift_Left:: - * Shift_Right:: - * Shift_Right_Arithmetic:: - * Source_Location:: - - GNAT allows a user application program to write the declaration: - - pragma Import (Intrinsic, name); - - providing that the name corresponds to one of the implemented intrinsic - subprograms in GNAT, and that the parameter profile of the referenced - subprogram meets the requirements. This chapter describes the set of - implemented intrinsic subprograms, and the requirements on parameter - profiles. Note that no body is supplied; as with other uses of pragma - Import, the body is supplied elsewhere (in this case by the compiler - itself). Note that any use of this feature is potentially - non-portable, since the Ada standard does not require Ada compilers to - implement this feature. - -  - File: gnat_rm.info, Node: Intrinsic Operators, Next: Enclosing_Entity, Up: Intrinsic Subprograms - - Intrinsic Operators - =================== - - All the predefined numeric operators in package Standard in `pragma - Import (Intrinsic,..)' declarations. In the binary operator case, the - operands must have the same size. The operand or operands must also be - appropriate for the operator. For example, for addition, the operands - must both be floating-point or both be fixed-point, and the right - operand for `"**"' must have a root type of `Standard.Integer'Base'. - You can use an intrinsic operator declaration as in the following - example: - - type Int1 is new Integer; - type Int2 is new Integer; - - function "+" (X1 : Int1; X2 : Int2) return Int1; - function "+" (X1 : Int1; X2 : Int2) return Int2; - pragma Import (Intrinsic, "+"); - - This declaration would permit "mixed mode" arithmetic on items of the - differing types `Int1' and `Int2'. It is also possible to specify such - operators for private types, if the full views are appropriate - arithmetic types. - -  - File: gnat_rm.info, Node: Enclosing_Entity, Next: Exception_Information, Prev: Intrinsic Operators, Up: Intrinsic Subprograms - - Enclosing_Entity - ================ - - This intrinsic subprogram is used in the implementation of the library - routine `GNAT.Source_Info'. The only useful use of the intrinsic - import in this case is the one in this unit, so an application program - should simply call the function `GNAT.Source_Info.Enclosing_Entity' to - obtain the name of the current subprogram, package, task, entry, or - protected subprogram. - -  - File: gnat_rm.info, Node: Exception_Information, Next: Exception_Message, Prev: Enclosing_Entity, Up: Intrinsic Subprograms - - Exception_Information - ===================== - - This intrinsic subprogram is used in the implementation of the library - routine `GNAT.Current_Exception'. The only useful use of the intrinsic - import in this case is the one in this unit, so an application program - should simply call the function - `GNAT.Current_Exception.Exception_Information' to obtain the exception - information associated with the current exception. - -  - File: gnat_rm.info, Node: Exception_Message, Next: Exception_Name, Prev: Exception_Information, Up: Intrinsic Subprograms - - Exception_Message - ================= - - This intrinsic subprogram is used in the implementation of the library - routine `GNAT.Current_Exception'. The only useful use of the intrinsic - import in this case is the one in this unit, so an application program - should simply call the function - `GNAT.Current_Exception.Exception_Message' to obtain the message - associated with the current exception. - -  - File: gnat_rm.info, Node: Exception_Name, Next: File, Prev: Exception_Message, Up: Intrinsic Subprograms - - Exception_Name - ============== - - This intrinsic subprogram is used in the implementation of the library - routine `GNAT.Current_Exception'. The only useful use of the intrinsic - import in this case is the one in this unit, so an application program - should simply call the function `GNAT.Current_Exception.Exception_Name' - to obtain the name of the current exception. - -  - File: gnat_rm.info, Node: File, Next: Line, Prev: Exception_Name, Up: Intrinsic Subprograms - - File - ==== - - This intrinsic subprogram is used in the implementation of the library - routine `GNAT.Source_Info'. The only useful use of the intrinsic - import in this case is the one in this unit, so an application program - should simply call the function `GNAT.Source_Info.File' to obtain the - name of the current file. - -  - File: gnat_rm.info, Node: Line, Next: Rotate_Left, Prev: File, Up: Intrinsic Subprograms - - Line - ==== - - This intrinsic subprogram is used in the implementation of the library - routine `GNAT.Source_Info'. The only useful use of the intrinsic - import in this case is the one in this unit, so an application program - should simply call the function `GNAT.Source_Info.Line' to obtain the - number of the current source line. - -  - File: gnat_rm.info, Node: Rotate_Left, Next: Rotate_Right, Prev: Line, Up: Intrinsic Subprograms - - Rotate_Left - =========== - - In standard Ada 95, the `Rotate_Left' function is available only for - the predefined modular types in package `Interfaces'. However, in GNAT - it is possible to define a Rotate_Left function for a user defined - modular type or any signed integer type as in this example: - - function Shift_Left - (Value : My_Modular_Type; - Amount : Natural) - return My_Modular_Type; - - The requirements are that the profile be exactly as in the example - above. The only modifications allowed are in the formal parameter - names, and in the type of `Value' and the return type, which must be - the same, and must be either a signed integer type, or a modular - integer type with a binary modulus, and the size must be 8. 16, 32 or - 64 bits. - -  - File: gnat_rm.info, Node: Rotate_Right, Next: Shift_Left, Prev: Rotate_Left, Up: Intrinsic Subprograms - - Rotate_Right - ============ - - A `Rotate_Right' function can be defined for any user defined binary - modular integer type, or signed integer type, as described above for - `Rotate_Left'. - -  - File: gnat_rm.info, Node: Shift_Left, Next: Shift_Right, Prev: Rotate_Right, Up: Intrinsic Subprograms - - Shift_Left - ========== - - A `Shift_Left' function can be defined for any user defined binary - modular integer type, or signed integer type, as described above for - `Rotate_Left'. - -  - File: gnat_rm.info, Node: Shift_Right, Next: Shift_Right_Arithmetic, Prev: Shift_Left, Up: Intrinsic Subprograms - - Shift_Right - =========== - - A `Shift_Right' function can be defined for any user defined binary - modular integer type, or signed integer type, as described above for - `Rotate_Left'. - -  - File: gnat_rm.info, Node: Shift_Right_Arithmetic, Next: Source_Location, Prev: Shift_Right, Up: Intrinsic Subprograms - - Shift_Right_Arithmetic - ====================== - - A `Shift_Right_Arithmetic' function can be defined for any user defined - binary modular integer type, or signed integer type, as described above - for `Rotate_Left'. - -  - File: gnat_rm.info, Node: Source_Location, Prev: Shift_Right_Arithmetic, Up: Intrinsic Subprograms - - Source_Location - =============== - - This intrinsic subprogram is used in the implementation of the library - routine `GNAT.Source_Info'. The only useful use of the intrinsic - import in this case is the one in this unit, so an application program - should simply call the function `GNAT.Source_Info.Source_Location' to - obtain the current source file location. - -  - File: gnat_rm.info, Node: Representation Clauses and Pragmas, Next: Standard Library Routines, Prev: Intrinsic Subprograms, Up: Top - - Representation Clauses and Pragmas - ********************************** - - * Menu: - - * Alignment Clauses:: - * Size Clauses:: - * Storage_Size Clauses:: - * Size of Variant Record Objects:: - * Biased Representation :: - * Value_Size and Object_Size Clauses:: - * Component_Size Clauses:: - * Bit_Order Clauses:: - * Effect of Bit_Order on Byte Ordering:: - * Pragma Pack for Arrays:: - * Pragma Pack for Records:: - * Record Representation Clauses:: - * Enumeration Clauses:: - * Address Clauses:: - * Effect of Convention on Representation:: - * Determining the Representations chosen by GNAT:: - - This section describes the representation clauses accepted by GNAT, and - their effect on the representation of corresponding data objects. - - GNAT fully implements Annex C (Systems Programming). This means - that all the implementation advice sections in chapter 13 are fully - implemented. However, these sections only require a minimal level of - support for representation clauses. GNAT provides much more extensive - capabilities, and this section describes the additional capabilities - provided. - -  - File: gnat_rm.info, Node: Alignment Clauses, Next: Size Clauses, Up: Representation Clauses and Pragmas - - Alignment Clauses - ================= - - GNAT requires that all alignment clauses specify a power of 2, and all - default alignments are always a power of 2. The default alignment - values are as follows: - - * Primitive Types For primitive types, the alignment is the maximum - of the actual size of objects of the type, and the maximum - alignment supported by the target. For example, for type - Long_Float, the object size is 8 bytes, and the default alignment - will be 8 on any target that supports alignments this large, but - on some targets, the maximum alignment may be smaller than 8, in - which case objects of type Long_Float will be maximally aligned. - - * Arrays For arrays, the alignment is equal to the alignment of the - component type for the normal case where no packing or component - size is given. If the array is packed, and the packing is - effective (see separate section on packed arrays), then the - alignment will be one for long packed arrays, or arrays whose - length is not known at compile time. For short packed arrays, - which are handled internally as modular types, the alignment will - be as described for primitive types, e.g. a packed array of length - 31 bits will have an object size of four bytes, and an alignment - of 4. - - * Records For the normal non-packed case, the alignment of a record - is equal to the maximum alignment of any of its components. For - tagged records, this includes the implicit access type used for - the tag. If a pragma `Pack' is used and all fields are packable - (see separate section on pragma `Pack'), then the resulting - alignment is 1. - - A special case is when the size of the record is given explicitly, - or a full record representation clause is given, and the size of - the record is 2, 4, or 8 bytes. In this case, an alignment is - chosen to match the size of the record. For example, if we have: - - type Small is record - A, B : Character; - end record; - - then the default alignment of the record type `Small' is 2, not 1. - This leads to more efficient code when the record is treated as a - unit, and also allows the type to specified as `Atomic' on - architectures requiring strict alignment. - - - An alignment clause may always specify a larger alignment than the - default value, up to some maximum value dependent on the target - (obtainable by using the attribute reference System'Maximum_Alignment). - The only case in which it is permissible to specify a smaller - alignment than the default value is in the case of a record for which a - record representation clause is given. In this case, packable fields - for which a component clause is given still result in a default - alignment corresponding to the original type, but this may be - overridden, since these components in fact only require an alignment of - one byte. For example, given - - type v is record - a : integer; - end record; - - for v use record - a at 0 range 0 .. 31; - end record; - - for v'alignment use 1; - - The default alignment for the type `v' is 4, as a result of the integer - field in the record, but since this field is placed with a component - clause, it is permissible, as shown, to override the default alignment - of the record to a smaller value. - -  - File: gnat_rm.info, Node: Size Clauses, Next: Storage_Size Clauses, Prev: Alignment Clauses, Up: Representation Clauses and Pragmas - - Size Clauses - ============ - - The default size of types is as specified in the reference manual. For - objects, GNAT will generally increase the type size so that the object - size is a multiple of storage units, and also a multiple of the - alignment. For example - - type Smallint is range 1 .. 6; - - type Rec is record - y1 : integer; - y2 : boolean; - end record; - - In this example, `Smallint' has a size of 3, as specified by the RM - rules, but objects of this type will have a size of 8, since objects by - default occupy an integral number of storage units. On some targets, - notably older versions of the Digital Alpha, the size of stand alone - objects of this type may be 32, reflecting the inability of the - hardware to do byte load/stores. - - Similarly, the size of type `Rec' is 40 bits, but the alignment is - 4, so objects of this type will have their size increased to 64 bits so - that it is a multiple of the alignment. The reason for this decision, - which is in accordance with the specific note in RM 13.3(43): - - A Size clause should be supported for an object if the specified - Size is at least as large as its subtype's Size, and corresponds - to a size in storage elements that is a multiple of the object's - Alignment (if the Alignment is nonzero). - - An explicit size clause may be used to override the default size by - increasing it. For example, if we have: - - type My_Boolean is new Boolean; - for My_Boolean'Size use 32; - - then objects of this type will always be 32 bits long. In the case of - discrete types, the size can be increased up to 64 bits, with the effect - that the entire specified field is used to hold the value, sign- or - zero-extended as appropriate. If more than 64 bits is specified, then - padding space is allocated after the value, and a warning is issued that - there are unused bits. - - Similarly the size of records and arrays may be increased, and the - effect is to add padding bits after the value. This also causes a - warning message to be generated. - - The largest Size value permitted in GNAT is 2**32-1. Since this is a - Size in bits, this corresponds to an object of size 256 megabytes (minus - one). This limitation is true on all targets. The reason for this - limitation is that it improves the quality of the code in many cases if - it is known that a Size value can be accommodated in an object of type - Integer. - -  - File: gnat_rm.info, Node: Storage_Size Clauses, Next: Size of Variant Record Objects, Prev: Size Clauses, Up: Representation Clauses and Pragmas - - Storage_Size Clauses - ==================== - - For tasks, the `Storage_Size' clause specifies the amount of space to - be allocated for the task stack. This cannot be extended, and if the - stack is exhausted, then `Storage_Error' will be raised if stack - checking is enabled. If the default size of 20K bytes is insufficient, - then you need to use a `Storage_Size' attribute definition clause, or a - `Storage_Size' pragma in the task definition to set the appropriate - required size. A useful technique is to include in every task - definition a pragma of the form: - - pragma Storage_Size (Default_Stack_Size); - - Then Default_Stack_Size can be defined in a global package, and modified - as required. Any tasks requiring different task stack sizes from the - default can have an appropriate alternative reference in the pragma. - - For access types, the `Storage_Size' clause specifies the maximum - space available for allocation of objects of the type. If this space is - exceeded then `Storage_Error' will be raised by an allocation attempt. - In the case where the access type is declared local to a subprogram, the - use of a `Storage_Size' clause triggers automatic use of a special - predefined storage pool (`System.Pool_Size') that ensures that all - space for the pool is automatically reclaimed on exit from the scope in - which the type is declared. - - A special case recognized by the compiler is the specification of a - `Storage_Size' of zero for an access type. This means that no items - can be allocated from the pool, and this is recognized at compile time, - and all the overhead normally associated with maintaining a fixed size - storage pool is eliminated. Consider the following example: - - procedure p is - type R is array (Natural) of Character; - type P is access all R; - for P'Storage_Size use 0; - -- Above access type intended only for interfacing purposes - - y : P; - - procedure g (m : P); - pragma Import (C, g); - - -- ... - - begin - -- ... - y := new R; - end; - - As indicated in this example, these dummy storage pools are often - useful in connection with interfacing where no object will ever be - allocated. If you compile the above example, you get the warning: - - p.adb:16:09: warning: allocation from empty storage pool - p.adb:16:09: warning: Storage_Error will be raised at run time - - Of course in practice, there will not be any explicit allocators in the - case of such an access declaration. - -  - File: gnat_rm.info, Node: Size of Variant Record Objects, Next: Biased Representation, Prev: Storage_Size Clauses, Up: Representation Clauses and Pragmas - - Size of Variant Record Objects - ============================== - - An issue arises in the case of variant record objects of whether Size - gives information about a particular variant, or the maximum size - required for any variant. Consider the following program - - with Text_IO; use Text_IO; - procedure q is - type R1 (A : Boolean := False) is record - case A is - when True => X : Character; - when False => null; - end case; - end record; - - V1 : R1 (False); - V2 : R1; - - begin - Put_Line (Integer'Image (V1'Size)); - Put_Line (Integer'Image (V2'Size)); - end q; - - Here we are dealing with a variant record, where the True variant - requires 16 bits, and the False variant requires 8 bits. In the above - example, both V1 and V2 contain the False variant, which is only 8 bits - long. However, the result of running the program is: - - 8 - 16 - - The reason for the difference here is that the discriminant value of V1 - is fixed, and will always be False. It is not possible to assign a - True variant value to V1, therefore 8 bits is sufficient. On the other - hand, in the case of V2, the initial discriminant value is False (from - the default), but it is possible to assign a True variant value to V2, - therefore 16 bits must be allocated for V2 in the general case, even - fewer bits may be needed at any particular point during the program - execution. - - As can be seen from the output of this program, the `'Size' - attribute applied to such an object in GNAT gives the actual allocated - size of the variable, which is the largest size of any of the variants. - The Ada Reference Manual is not completely clear on what choice should - be made here, but the GNAT behavior seems most consistent with the - language in the RM. - - In some cases, it may be desirable to obtain the size of the current - variant, rather than the size of the largest variant. This can be - achieved in GNAT by making use of the fact that in the case of a - subprogram parameter, GNAT does indeed return the size of the current - variant (because a subprogram has no way of knowing how much space is - actually allocated for the actual). - - Consider the following modified version of the above program: - - with Text_IO; use Text_IO; - procedure q is - type R1 (A : Boolean := False) is record - case A is - when True => X : Character; - when False => null; - end case; - end record; - - V2 : R1; - - function Size (V : R1) return Integer is - begin - return V'Size; - end Size; - - begin - Put_Line (Integer'Image (V2'Size)); - Put_Line (Integer'IMage (Size (V2))); - V2 := (True, 'x'); - Put_Line (Integer'Image (V2'Size)); - Put_Line (Integer'IMage (Size (V2))); - end q; - - The output from this program is - - 16 - 8 - 16 - 16 - - Here we see that while the `'Size' attribute always returns the maximum - size, regardless of the current variant value, the `Size' function does - indeed return the size of the current variant value. - -  - File: gnat_rm.info, Node: Biased Representation, Next: Value_Size and Object_Size Clauses, Prev: Size of Variant Record Objects, Up: Representation Clauses and Pragmas - - Biased Representation - ===================== - - In the case of scalars with a range starting at other than zero, it is - possible in some cases to specify a size smaller than the default - minimum value, and in such cases, GNAT uses an unsigned biased - representation, in which zero is used to represent the lower bound, and - successive values represent successive values of the type. - - For example, suppose we have the declaration: - - type Small is range -7 .. -4; - for Small'Size use 2; - - Although the default size of type `Small' is 4, the `Size' clause is - accepted by GNAT and results in the following representation scheme: - - -7 is represented as 2#00# - -6 is represented as 2#01# - -5 is represented as 2#10# - -4 is represented as 2#11# - - Biased representation is only used if the specified `Size' clause - cannot be accepted in any other manner. These reduced sizes that force - biased representation can be used for all discrete types except for - enumeration types for which a representation clause is given. - -  - File: gnat_rm.info, Node: Value_Size and Object_Size Clauses, Next: Component_Size Clauses, Prev: Biased Representation, Up: Representation Clauses and Pragmas - - Value_Size and Object_Size Clauses - ================================== - - In Ada 95, the `Size' of a discrete type is the minimum number of bits - required to hold values of the type. Although this interpretation was - allowed in Ada 83, it was not required, and this requirement in practice - can cause some significant difficulties. For example, in most Ada 83 - compilers, `Natural'Size' was 32. However, in Ada-95, `Natural'Size' is - typically 31. This means that code may change in behavior when moving - from Ada 83 to Ada 95. For example, consider: - - type Rec is record; - A : Natural; - B : Natural; - end record; - - for Rec use record - for A use at 0 range 0 .. Natural'Size - 1; - for B use at 0 range Natural'Size .. 2 * Natural'Size - 1; - end record; - - In the above code, since the typical size of `Natural' objects is 32 - bits and `Natural'Size' is 31, the above code can cause unexpected - inefficient packing in Ada 95, and in general there are surprising - cases where the fact that the object size can exceed the size of the - type causes surprises. - - To help get around this problem GNAT provides two implementation - dependent attributes `Value_Size' and `Object_Size'. When applied to a - type, these attributes yield the size of the type (corresponding to the - RM defined size attribute), and the size of objects of the type - respectively. - - The `Object_Size' is used for determining the default size of - objects and components. This size value can be referred to using the - `Object_Size' attribute. The phrase "is used" here means that it is - the basis of the determination of the size. The backend is free to pad - this up if necessary for efficiency, e.g. an 8-bit stand-alone - character might be stored in 32 bits on a machine with no efficient - byte access instructions such as the Alpha. - - The default rules for the value of `Object_Size' for fixed-point and - discrete types are as follows: - - * The `Object_Size' for base subtypes reflect the natural hardware - size in bits (run the utility `gnatpsta' to find those values for - numeric types). Enumeration types and fixed-point base subtypes - have 8, 16, 32 or 64 bits for this size, depending on the range of - values to be stored. - - * The `Object_Size' of a subtype is the same as the `Object_Size' of - the type from which it is obtained. - - * The `Object_Size' of a derived base type is copied from the parent - base type, and the `Object_Size' of a derived first subtype is - copied from the parent first subtype. - - The `Value_Size' attribute is the number of bits required to store a - value of the type. This size can be referred to using the `Value_Size' - attribute. This value is used to determine how tightly to pack records - or arrays with components of this type, and also affects the semantics - of unchecked conversion (unchecked conversions where the `Value_Size' - values differ generate a warning, and are potentially target dependent). - - The default rules for the value of `Value_Size' are as follows: - - * The `Value_Size' for a base subtype is the minimum number of bits - required to store all values of the type (including the sign bit - only if negative values are possible). - - * If a subtype statically matches the first subtype of a given type, - then it has by default the same `Value_Size' as the first subtype. - This is a consequence of RM 13.1(14) ("if two subtypes statically - match, then their subtype-specific aspects are the same".) - - * All other subtypes have a `Value_Size' corresponding to the minimum - number of bits required to store all values of the subtype. For - dynamic bounds, it is assumed that the value can range down or up - to the corresponding bound of the ancestor - - The RM defined attribute `Size' corresponds to the `Value_Size' - attribute. - - The `Size' attribute may be defined for a first-named subtype. This - sets the `Value_Size' of the first-named subtype to the given value, - and the `Object_Size' of this first-named subtype to the given value - padded up to an appropriate boundary. It is a consequence of the - default rules above that this `Object_Size' will apply to all further - subtypes. On the other hand, `Value_Size' is affected only for the - first subtype, any dynamic subtypes obtained from it directly, and any - statically matching subtypes. The `Value_Size' of any other static - subtypes is not affected. - - `Value_Size' and `Object_Size' may be explicitly set for any subtype - using an attribute definition clause. Note that the use of these - attributes can cause the RM 13.1(14) rule to be violated. If two - access types reference aliased objects whose subtypes have differing - `Object_Size' values as a result of explicit attribute definition - clauses, then it is erroneous to convert from one access subtype to the - other. - - At the implementation level, Esize stores the Object_SIze and the - RM_Size field stores the `Value_Size' (and hence the value of the - `Size' attribute, which, as noted above, is equivalent to `Value_Size'). - - To get a feel for the difference, consider the following examples - (note that in each case the base is short_short_integer with a size of - 8): - - Object_Size Value_Size - - type x1 is range 0 .. 5; 8 3 - - type x2 is range 0 .. 5; - for x2'size use 12; 12 12 - - subtype x3 is x2 range 0 .. 3; 12 2 - - subtype x4 is x2'base range 0 .. 10; 8 4 - - subtype x5 is x2 range 0 .. dynamic; 12 (7) - - subtype x6 is x2'base range 0 .. dynamic; 8 (7) - - Note: the entries marked (7) are not actually specified by the Ada 95 - RM, but it seems in the spirit of the RM rules to allocate the minimum - number of bits known to be large enough to hold the given range of - values. - - So far, so good, but GNAT has to obey the RM rules, so the question - is under what conditions must the RM `Size' be used. The following is - a list of the occasions on which the RM `Size' must be used: - - * Component size for packed arrays or records - - * Value of the attribute `Size' for a type - - * Warning about sizes not matching for unchecked conversion - - For types other than discrete and fixed-point types, the `Object_Size' - and Value_Size are the same (and equivalent to the RM attribute `Size'). - Only `Size' may be specified for such types. - -  - File: gnat_rm.info, Node: Component_Size Clauses, Next: Bit_Order Clauses, Prev: Value_Size and Object_Size Clauses, Up: Representation Clauses and Pragmas - - Component_Size Clauses - ====================== - - Normally, the value specified in a component clause must be consistent - with the subtype of the array component with regard to size and - alignment. In other words, the value specified must be at least equal - to the size of this subtype, and must be a multiple of the alignment - value. - - In addition, component size clauses are allowed which cause the array - to be packed, by specifying a smaller value. The cases in which this - is allowed are for component size values in the range 1 through 63. - The value specified must not be smaller than the Size of the subtype. - GNAT will accurately honor all packing requests in this range. For - example, if we have: - - type r is array (1 .. 8) of Natural; - for r'Size use 31; - - then the resulting array has a length of 31 bytes (248 bits = 8 * 31). - Of course access to the components of such an array is considerably - less efficient than if the natural component size of 32 is used. - -  - File: gnat_rm.info, Node: Bit_Order Clauses, Next: Effect of Bit_Order on Byte Ordering, Prev: Component_Size Clauses, Up: Representation Clauses and Pragmas - - Bit_Order Clauses - ================= - - For record subtypes, GNAT permits the specification of the `Bit_Order' - attribute. The specification may either correspond to the default bit - order for the target, in which case the specification has no effect and - places no additional restrictions, or it may be for the non-standard - setting (that is the opposite of the default). - - In the case where the non-standard value is specified, the effect is - to renumber bits within each byte, but the ordering of bytes is not - affected. There are certain restrictions placed on component clauses - as follows: - - * Components fitting within a single storage unit. - - These are unrestricted, and the effect is merely to renumber bits. - For example if we are on a little-endian machine with - `Low_Order_First' being the default, then the following two - declarations have exactly the same effect: - - type R1 is record - A : Boolean; - B : Integer range 1 .. 120; - end record; - - for R1 use record - A at 0 range 0 .. 0; - B at 0 range 1 .. 7; - end record; - - type R2 is record - A : Boolean; - B : Integer range 1 .. 120; - end record; - - for R2'Bit_Order use High_Order_First; - - for R2 use record - A at 0 range 7 .. 7; - B at 0 range 0 .. 6; - end record; - - The useful application here is to write the second declaration - with the `Bit_Order' attribute definition clause, and know that it - will be treated the same, regardless of whether the target is - little-endian or big-endian. - - * Components occupying an integral number of bytes. - - These are components that exactly fit in two or more bytes. Such - component declarations are allowed, but have no effect, since it - is important to realize that the `Bit_Order' specification does - not affect the ordering of bytes. In particular, the following - attempt at getting an endian-independent integer does not work: - - type R2 is record - A : Integer; - end record; - - for R2'Bit_Order use High_Order_First; - - for R2 use record - A at 0 range 0 .. 31; - end record; - - This declaration will result in a little-endian integer on a - little-endian machine, and a big-endian integer on a big-endian - machine. If byte flipping is required for interoperability - between big- and little-endian machines, this must be explicitly - programmed. This capability is not provided by `Bit_Order'. - - * Components that are positioned across byte boundaries - - but do not occupy an integral number of bytes. Given that bytes - are not reordered, such fields would occupy a non-contiguous - sequence of bits in memory, requiring non-trivial code to - reassemble. They are for this reason not permitted, and any - component clause specifying such a layout will be flagged as - illegal by GNAT. - - - Since the misconception that Bit_Order automatically deals with all - endian-related incompatibilities is a common one, the specification of - a component field that is an integral number of bytes will always - generate a warning. This warning may be suppressed using `pragma - Suppress' if desired. The following section contains additional - details regarding the issue of byte ordering. - -  - File: gnat_rm.info, Node: Effect of Bit_Order on Byte Ordering, Next: Pragma Pack for Arrays, Prev: Bit_Order Clauses, Up: Representation Clauses and Pragmas - - Effect of Bit_Order on Byte Ordering - ==================================== - - In this section we will review the effect of the `Bit_Order' attribute - definition clause on byte ordering. Briefly, it has no effect at all, - but a detailed example will be helpful. Before giving this example, - let us review the precise definition of the effect of defining - `Bit_Order'. The effect of a non-standard bit order is described in - section 15.5.3 of the Ada Reference Manual: - - 2 A bit ordering is a method of interpreting the meaning of - the storage place attributes. - - To understand the precise definition of storage place attributes in - this context, we visit section 13.5.1 of the manual: - - 13 A record_representation_clause (without the mod_clause) - specifies the layout. The storage place attributes (see 13.5.2) - are taken from the values of the position, first_bit, and last_bit - expressions after normalizing those values so that first_bit is - less than Storage_Unit. - - The critical point here is that storage places are taken from the - values after normalization, not before. So the `Bit_Order' - interpretation applies to normalized values. The interpretation is - described in the later part of the 15.5.3 paragraph: - - 2 A bit ordering is a method of interpreting the meaning of - the storage place attributes. High_Order_First (known in the - vernacular as ``big endian'') means that the first bit of a - storage element (bit 0) is the most significant bit (interpreting - the sequence of bits that represent a component as an unsigned - integer value). Low_Order_First (known in the vernacular as - ``little endian'') means the opposite: the first bit is the - least significant. - - Note that the numbering is with respect to the bits of a storage unit. - In other words, the specification affects only the numbering of bits - within a single storage unit. - - We can make the effect clearer by giving an example. - - Suppose that we have an external device which presents two bytes, - the first byte presented, which is the first (low addressed byte) of - the two byte record is called Master, and the second byte is called - Slave. - - The left most (most significant bit is called Control for each byte, - and the remaining 7 bits are called V1, V2, ... V7, where V7 is the - rightmost (least significant) bit. - - On a big-endian machine, we can write the following representation - clause - - type Data is record - Master_Control : Bit; - Master_V1 : Bit; - Master_V2 : Bit; - Master_V3 : Bit; - Master_V4 : Bit; - Master_V5 : Bit; - Master_V6 : Bit; - Master_V7 : Bit; - Slave_Control : Bit; - Slave_V1 : Bit; - Slave_V2 : Bit; - Slave_V3 : Bit; - Slave_V4 : Bit; - Slave_V5 : Bit; - Slave_V6 : Bit; - Slave_V7 : Bit; - end record; - - for Data use record - Master_Control at 0 range 0 .. 0; - Master_V1 at 0 range 1 .. 1; - Master_V2 at 0 range 2 .. 2; - Master_V3 at 0 range 3 .. 3; - Master_V4 at 0 range 4 .. 4; - Master_V5 at 0 range 5 .. 5; - Master_V6 at 0 range 6 .. 6; - Master_V7 at 0 range 7 .. 7; - Slave_Control at 1 range 0 .. 0; - Slave_V1 at 1 range 1 .. 1; - Slave_V2 at 1 range 2 .. 2; - Slave_V3 at 1 range 3 .. 3; - Slave_V4 at 1 range 4 .. 4; - Slave_V5 at 1 range 5 .. 5; - Slave_V6 at 1 range 6 .. 6; - Slave_V7 at 1 range 7 .. 7; - end record; - - Now if we move this to a little endian machine, then the bit ordering - within the byte is backwards, so we have to rewrite the record rep - clause as: - - for Data use record - Master_Control at 0 range 7 .. 7; - Master_V1 at 0 range 6 .. 6; - Master_V2 at 0 range 5 .. 5; - Master_V3 at 0 range 4 .. 4; - Master_V4 at 0 range 3 .. 3; - Master_V5 at 0 range 2 .. 2; - Master_V6 at 0 range 1 .. 1; - Master_V7 at 0 range 0 .. 0; - Slave_Control at 1 range 7 .. 7; - Slave_V1 at 1 range 6 .. 6; - Slave_V2 at 1 range 5 .. 5; - Slave_V3 at 1 range 4 .. 4; - Slave_V4 at 1 range 3 .. 3; - Slave_V5 at 1 range 2 .. 2; - Slave_V6 at 1 range 1 .. 1; - Slave_V7 at 1 range 0 .. 0; - end record; - - It is a nuisance to have to rewrite the clause, especially if the - code has to be maintained on both machines. However, this is a case - that we can handle with the `Bit_Order' attribute if it is implemented. - Note that the implementation is not required on byte addressed - machines, but it is indeed implemented in GNAT. This means that we can - simply use the first record clause, together with the declaration - - for Data'Bit_Order use High_Order_First; - - and the effect is what is desired, namely the layout is exactly the - same, independent of whether the code is compiled on a big-endian or - little-endian machine. - - The important point to understand is that byte ordering is not - affected. A `Bit_Order' attribute definition never affects which byte - a field ends up in, only where it ends up in that byte. To make this - clear, let us rewrite the record rep clause of the previous example as: - - for Data'Bit_Order use High_Order_First; - for Data use record - Master_Control at 0 range 0 .. 0; - Master_V1 at 0 range 1 .. 1; - Master_V2 at 0 range 2 .. 2; - Master_V3 at 0 range 3 .. 3; - Master_V4 at 0 range 4 .. 4; - Master_V5 at 0 range 5 .. 5; - Master_V6 at 0 range 6 .. 6; - Master_V7 at 0 range 7 .. 7; - Slave_Control at 0 range 8 .. 8; - Slave_V1 at 0 range 9 .. 9; - Slave_V2 at 0 range 10 .. 10; - Slave_V3 at 0 range 11 .. 11; - Slave_V4 at 0 range 12 .. 12; - Slave_V5 at 0 range 13 .. 13; - Slave_V6 at 0 range 14 .. 14; - Slave_V7 at 0 range 15 .. 15; - end record; - - This is exactly equivalent to saying (a repeat of the first example): - - for Data'Bit_Order use High_Order_First; - for Data use record - Master_Control at 0 range 0 .. 0; - Master_V1 at 0 range 1 .. 1; - Master_V2 at 0 range 2 .. 2; - Master_V3 at 0 range 3 .. 3; - Master_V4 at 0 range 4 .. 4; - Master_V5 at 0 range 5 .. 5; - Master_V6 at 0 range 6 .. 6; - Master_V7 at 0 range 7 .. 7; - Slave_Control at 1 range 0 .. 0; - Slave_V1 at 1 range 1 .. 1; - Slave_V2 at 1 range 2 .. 2; - Slave_V3 at 1 range 3 .. 3; - Slave_V4 at 1 range 4 .. 4; - Slave_V5 at 1 range 5 .. 5; - Slave_V6 at 1 range 6 .. 6; - Slave_V7 at 1 range 7 .. 7; - end record; - - Why are they equivalent? Well take a specific field, the `Slave_V2' - field. The storage place attributes are obtained by normalizing the - values given so that the `First_Bit' value is less than 8. After - nromalizing the values (0,10,10) we get (1,2,2) which is exactly what - we specified in the other case. - - Now one might expect that the `Bit_Order' attribute might affect bit - numbering within the entire record component (two bytes in this case, - thus affecting which byte fields end up in), but that is not the way - this feature is defined, it only affects numbering of bits, not which - byte they end up in. - - Consequently it never makes sense to specify a starting bit number - greater than 7 (for a byte addressable field) if an attribute - definition for `Bit_Order' has been given, and indeed it may be - actively confusing to specify such a value, so the compiler generates a - warning for such usage. - - If you do need to control byte ordering then appropriate conditional - values must be used. If in our example, the slave byte came first on - some machines we might write: - - Master_Byte_First constant Boolean := ...; - - Master_Byte : constant Natural := - 1 - Boolean'Pos (Master_Byte_First); - Slave_Byte : constant Natural := - Boolean'Pos (Master_Byte_First); - - for Data'Bit_Order use High_Order_First; - for Data use record - Master_Control at Master_Byte range 0 .. 0; - Master_V1 at Master_Byte range 1 .. 1; - Master_V2 at Master_Byte range 2 .. 2; - Master_V3 at Master_Byte range 3 .. 3; - Master_V4 at Master_Byte range 4 .. 4; - Master_V5 at Master_Byte range 5 .. 5; - Master_V6 at Master_Byte range 6 .. 6; - Master_V7 at Master_Byte range 7 .. 7; - Slave_Control at Slave_Byte range 0 .. 0; - Slave_V1 at Slave_Byte range 1 .. 1; - Slave_V2 at Slave_Byte range 2 .. 2; - Slave_V3 at Slave_Byte range 3 .. 3; - Slave_V4 at Slave_Byte range 4 .. 4; - Slave_V5 at Slave_Byte range 5 .. 5; - Slave_V6 at Slave_Byte range 6 .. 6; - Slave_V7 at Slave_Byte range 7 .. 7; - end record; - - Now to switch between machines, all that is necessary is to set the - boolean constant `Master_Byte_First' in an appropriate manner. - -  - File: gnat_rm.info, Node: Pragma Pack for Arrays, Next: Pragma Pack for Records, Prev: Effect of Bit_Order on Byte Ordering, Up: Representation Clauses and Pragmas - - Pragma Pack for Arrays - ====================== - - Pragma `Pack' applied to an array has no effect unless the component - type is packable. For a component type to be packable, it must be one - of the following cases: - - * Any scalar type - - * Any fixed-point type - - * Any type whose size is specified with a size clause - - * Any packed array type with a static size - - For all these cases, if the component subtype size is in the range 1 - through 63, then the effect of the pragma `Pack' is exactly as though a - component size were specified giving the component subtype size. For - example if we have: - - type r is range 0 .. 17; - - type ar is array (1 .. 8) of r; - pragma Pack (ar); - - Then the component size of `ar' will be set to 5 (i.e. to `r'size', and - the size of the array `ar' will be exactly 40 bits. - - Note that in some cases this rather fierce approach to packing can - produce unexpected effects. For example, in Ada 95, type Natural - typically has a size of 31, meaning that if you pack an array of - Natural, you get 31-bit close packing, which saves a few bits, but - results in far less efficient access. Since many other Ada compilers - will ignore such a packing request, GNAT will generate a warning on - some uses of pragma `Pack' that it guesses might not be what is - intended. You can easily remove this warning by using an explicit - `Component_Size' setting instead, which never generates a warning, - since the intention of the programmer is clear in this case. - - GNAT treats packed arrays in one of two ways. If the size of the - array is known at compile time and is less than 64 bits, then - internally the array is represented as a single modular type, of - exactly the appropriate number of bits. If the length is greater than - 63 bits, or is not known at compile time, then the packed array is - represented as an array of bytes, and the length is always a multiple - of 8 bits. - -  - File: gnat_rm.info, Node: Pragma Pack for Records, Next: Record Representation Clauses, Prev: Pragma Pack for Arrays, Up: Representation Clauses and Pragmas - - Pragma Pack for Records - ======================= - - Pragma `Pack' applied to a record will pack the components to reduce - wasted space from alignment gaps and by reducing the amount of space - taken by components. We distinguish between package components and - non-packable components. Components of the following types are - considered packable: - - * All scalar types are packable. - - * All fixed-point types are represented internally as integers, and - are packable. - - * Small packed arrays, whose size does not exceed 64 bits, and where - the size is statically known at compile time, are represented - internally as modular integers, and so they are also packable. - - - All packable components occupy the exact number of bits corresponding to - their `Size' value, and are packed with no padding bits, i.e. they can - start on an arbitrary bit boundary. - - All other types are non-packable, they occupy an integral number of - storage units, and are placed at a boundary corresponding to their - alignment requirements. - - For example, consider the record - - type Rb1 is array (1 .. 13) of Boolean; - pragma Pack (rb1); - - type Rb2 is array (1 .. 65) of Boolean; - pragma Pack (rb2); - - type x2 is record - l1 : Boolean; - l2 : Duration; - l3 : Float; - l4 : Boolean; - l5 : Rb1; - l6 : Rb2; - end record; - pragma Pack (x2); - - The representation for the record x2 is as follows: - - for x2'Size use 224; - for x2 use record - l1 at 0 range 0 .. 0; - l2 at 0 range 1 .. 64; - l3 at 12 range 0 .. 31; - l4 at 16 range 0 .. 0; - l5 at 16 range 1 .. 13; - l6 at 18 range 0 .. 71; - end record; - - Studying this example, we see that the packable fields `l1' and `l2' are - of length equal to their sizes, and placed at specific bit boundaries - (and not byte boundaries) to eliminate padding. But `l3' is of a - non-packable float type, so it is on the next appropriate alignment - boundary. - - The next two fields are fully packable, so `l4' and `l5' are - minimally packed with no gaps. However, type `Rb2' is a packed array - that is longer than 64 bits, so it is itself non-packable. Thus the - `l6' field is aligned to the next byte boundary, and takes an integral - number of bytes, i.e. 72 bits. - -  - File: gnat_rm.info, Node: Record Representation Clauses, Next: Enumeration Clauses, Prev: Pragma Pack for Records, Up: Representation Clauses and Pragmas - - Record Representation Clauses - ============================= - - Record representation clauses may be given for all record types, - including types obtained by record extension. Component clauses are - allowed for any static component. The restrictions on component - clauses depend on the type of the component. - - For all components of an elementary type, the only restriction on - component clauses is that the size must be at least the 'Size value of - the type (actually the Value_Size). There are no restrictions due to - alignment, and such components may freely cross storage boundaries. - - Packed arrays with a size up to and including 64 bits are represented - internally using a modular type with the appropriate number of bits, and - thus the same lack of restriction applies. For example, if you declare: - - type R is array (1 .. 49) of Boolean; - pragma Pack (R); - for R'Size use 49; - - then a component clause for a component of type R may start on any - specified bit boundary, and may specify a value of 49 bits or greater. - - For non-primitive types, including packed arrays with a size greater - than 64 bits, component clauses must respect the alignment requirement - of the type, in particular, always starting on a byte boundary, and the - length must be a multiple of the storage unit. - - The tag field of a tagged type always occupies an address sized - field at the start of the record. No component clause may attempt to - overlay this tag. - - In the case of a record extension T1, of a type T, no component - clause applied to the type T1 can specify a storage location that would - overlap the first T'Size bytes of the record. - -  - File: gnat_rm.info, Node: Enumeration Clauses, Next: Address Clauses, Prev: Record Representation Clauses, Up: Representation Clauses and Pragmas - - Enumeration Clauses - =================== - - The only restriction on enumeration clauses is that the range of - values must be representable. For the signed case, if one or more of - the representation values are negative, all values must be in the range: - - System.Min_Int .. System.Max_Int - - For the unsigned case, where all values are non negative, the values - must be in the range: - - 0 .. System.Max_Binary_Modulus; - - A _confirming_ representation clause is one in which the values range - from 0 in sequence, i.e. a clause that confirms the default - representation for an enumeration type. Such a confirming - representation is permitted by these rules, and is specially recognized - by the compiler so that no extra overhead results from the use of such - a clause. - - If an array has an index type which is an enumeration type to which - an enumeration clause has been applied, then the array is stored in a - compact manner. Consider the declarations: - - type r is (A, B, C); - for r use (A => 1, B => 5, C => 10); - type t is array (r) of Character; - - The array type t corresponds to a vector with exactly three elements and - has a default size equal to `3*Character'Size'. This ensures efficient - use of space, but means that accesses to elements of the array will - incur the overhead of converting representation values to the - corresponding positional values, (i.e. the value delivered by the `Pos' - attribute). - -  - File: gnat_rm.info, Node: Address Clauses, Next: Effect of Convention on Representation, Prev: Enumeration Clauses, Up: Representation Clauses and Pragmas - - Address Clauses - =============== - - The reference manual allows a general restriction on representation - clauses, as found in RM 13.1(22): - - An implementation need not support representation - items containing nonstatic expressions, except that - an implementation should support a representation item - for a given entity if each nonstatic expression in the - representation item is a name that statically denotes - a constant declared before the entity. - - In practice this is applicable only to address clauses, since this is - the only case in which a non-static expression is permitted by the - syntax. As the AARM notes in sections 13.1 (22.a-22.h): - - 22.a Reason: This is to avoid the following sort - of thing: - - 22.b X : Integer := F(...); - Y : Address := G(...); - for X'Address use Y; - - 22.c In the above, we have to evaluate the - initialization expression for X before we - know where to put the result. This seems - like an unreasonable implementation burden. - - 22.d The above code should instead be written - like this: - - 22.e Y : constant Address := G(...); - X : Integer := F(...); - for X'Address use Y; - - 22.f This allows the expression ``Y'' to be safely - evaluated before X is created. - - 22.g The constant could be a formal parameter of mode in. - - 22.h An implementation can support other nonstatic - expressions if it wants to. Expressions of type - Address are hardly ever static, but their value - might be known at compile time anyway in many - cases. - - GNAT does indeed permit many additional cases of non-static - expressions. In particular, if the type involved is elementary there - are no restrictions (since in this case, holding a temporary copy of - the initialization value, if one is present, is inexpensive). In - addition, if there is no implicit or explicit initialization, then - there are no restrictions. GNAT will reject only the case where all - three of these conditions hold: - - * The type of the item is non-elementary (e.g. a record or array). - - * There is explicit or implicit initialization required for the - object. - - * The address value is non-static. Here GNAT is more permissive - than the RM, and allows the address value to be the address of a - previously declared stand-alone variable, as long as it does not - itself have an address clause. - - Anchor : Some_Initialized_Type; - Overlay : Some_Initialized_Type; - for Overlay'Address use Anchor'Address; - - However, the prefix of the address clause cannot be an array - component, or a component of a discriminated record. - - - As noted above in section 22.h, address values are typically - non-static. In particular the To_Address function, even if applied to - a literal value, is a non-static function call. To avoid this minor - annoyance, GNAT provides the implementation defined attribute - 'To_Address. The following two expressions have identical values: - - Another issue with address clauses is the interaction with alignment - requirements. When an address clause is given for an object, the - address value must be consistent with the alignment of the object - (which is usually the same as the alignment of the type of the object). - If an address clause is given that specifies an inappropriately - aligned address value, then the program execution is erroneous. - - Since this source of erroneous behavior can have unfortunate - effects, GNAT checks (at compile time if possible, generating a - warning, or at execution time with a run-time check) that the alignment - is appropriate. If the run-time check fails, then `Program_Error' is - raised. This run-time check is suppressed if range checks are - suppressed, or if `pragma Restrictions (No_Elaboration_Code)' is in - effect. - - To_Address (16#1234_0000#) - System'To_Address (16#1234_0000#); - - except that the second form is considered to be a static expression, and - thus when used as an address clause value is always permitted. - - Additionally, GNAT treats as static an address clause that is an - unchecked_conversion of a static integer value. This simplifies the - porting of legacy code, and provides a portable equivalent to the GNAT - attribute To_Address. - - An address clause cannot be given for an exported object. More - understandably the real restriction is that objects with an address - clause cannot be exported. This is because such variables are not - defined by the Ada program, so there is no external object so export. - - It is permissible to give an address clause and a pragma Import for - the same object. In this case, the variable is not really defined by - the Ada program, so there is no external symbol to be linked. The link - name and the external name are ignored in this case. The reason that - we allow this combination is that it provides a useful idiom to avoid - unwanted initializations on objects with address clauses. - - When an address clause is given for an object that has implicit or - explicit initialization, then by default initialization takes place. - This means that the effect of the object declaration is to overwrite the - memory at the specified address. This is almost always not what the - programmer wants, so GNAT will output a warning: - - with System; - package G is - type R is record - M : Integer := 0; - end record; - - Ext : R; - for Ext'Address use System'To_Address (16#1234_1234#); - | - >>> warning: implicit initialization of "Ext" may - modify overlaid storage - >>> warning: use pragma Import for "Ext" to suppress - initialization (RM B(24)) - - end G; - - As indicated by the warning message, the solution is to use a (dummy) - pragma Import to suppress this initialization. The pragma tell the - compiler that the object is declared and initialized elsewhere. The - following package compiles without warnings (and the initialization is - suppressed): - - with System; - package G is - type R is record - M : Integer := 0; - end record; - - Ext : R; - for Ext'Address use System'To_Address (16#1234_1234#); - pragma Import (Ada, Ext); - end G; - -  - File: gnat_rm.info, Node: Effect of Convention on Representation, Next: Determining the Representations chosen by GNAT, Prev: Address Clauses, Up: Representation Clauses and Pragmas - - Effect of Convention on Representation - ====================================== - - Normally the specification of a foreign language convention for a type - or an object has no effect on the chosen representation. In - particular, the representation chosen for data in GNAT generally meets - the standard system conventions, and for example records are laid out - in a manner that is consistent with C. This means that specifying - convention C (for example) has no effect. - - There are three exceptions to this general rule: - - * Convention Fortran and array subtypes If pragma Convention Fortran - is specified for an array subtype, then in accordance with the - implementation advice in section 3.6.2(11) of the Ada Reference - Manual, the array will be stored in a Fortran-compatible - column-major manner, instead of the normal default row-major order. - - * Convention C and enumeration types GNAT normally stores - enumeration types in 8, 16, or 32 bits as required to accommodate - all values of the type. For example, for the enumeration type - declared by: - - type Color is (Red, Green, Blue); - - 8 bits is sufficient to store all values of the type, so by - default, objects of type `Color' will be represented using 8 bits. - However, normal C convention is to use 32 bits for all enum - values in C, since enum values are essentially of type int. If - pragma `Convention C' is specified for an Ada enumeration type, - then the size is modified as necessary (usually to 32 bits) to be - consistent with the C convention for enum values. - - * Convention C/Fortran and Boolean types In C, the usual convention - for boolean values, that is values used for conditions, is that - zero represents false, and nonzero values represent true. In Ada, - the normal convention is that two specific values, typically 0/1, - are used to represent false/true respectively. - - Fortran has a similar convention for `LOGICAL' values (any nonzero - value represents true). - - To accommodate the Fortran and C conventions, if a pragma - Convention specifies C or Fortran convention for a derived - Boolean, as in the following example: - - type C_Switch is new Boolean; - pragma Convention (C, C_Switch); - - then the GNAT generated code will treat any nonzero value as true. - For truth values generated by GNAT, the conventional value 1 will - be used for True, but when one of these values is read, any - nonzero value is treated as True. - - -  - File: gnat_rm.info, Node: Determining the Representations chosen by GNAT, Prev: Effect of Convention on Representation, Up: Representation Clauses and Pragmas - - Determining the Representations chosen by GNAT - ============================================== - - Although the descriptions in this section are intended to be complete, - it is often easier to simply experiment to see what GNAT accepts and - what the effect is on the layout of types and objects. - - As required by the Ada RM, if a representation clause is not - accepted, then it must be rejected as illegal by the compiler. - However, when a representation clause or pragma is accepted, there can - still be questions of what the compiler actually does. For example, if - a partial record representation clause specifies the location of some - components and not others, then where are the non-specified components - placed? Or if pragma `Pack' is used on a record, then exactly where are - the resulting fields placed? The section on pragma `Pack' in this - chapter can be used to answer the second question, but it is often - easier to just see what the compiler does. - - For this purpose, GNAT provides the option `-gnatR'. If you compile - with this option, then the compiler will output information on the - actual representations chosen, in a format similar to source - representation clauses. For example, if we compile the package: - - package q is - type r (x : boolean) is tagged record - case x is - when True => S : String (1 .. 100); - when False => null; - end case; - end record; - - type r2 is new r (false) with record - y2 : integer; - end record; - - for r2 use record - y2 at 16 range 0 .. 31; - end record; - - type x is record - y : character; - end record; - - type x1 is array (1 .. 10) of x; - for x1'component_size use 11; - - type ia is access integer; - - type Rb1 is array (1 .. 13) of Boolean; - pragma Pack (rb1); - - type Rb2 is array (1 .. 65) of Boolean; - pragma Pack (rb2); - - type x2 is record - l1 : Boolean; - l2 : Duration; - l3 : Float; - l4 : Boolean; - l5 : Rb1; - l6 : Rb2; - end record; - pragma Pack (x2); - end q; - - using the switch `-gnatR' we obtain the following output: - - Representation information for unit q - ------------------------------------- - - for r'Size use ??; - for r'Alignment use 4; - for r use record - x at 4 range 0 .. 7; - _tag at 0 range 0 .. 31; - s at 5 range 0 .. 799; - end record; - - for r2'Size use 160; - for r2'Alignment use 4; - for r2 use record - x at 4 range 0 .. 7; - _tag at 0 range 0 .. 31; - _parent at 0 range 0 .. 63; - y2 at 16 range 0 .. 31; - end record; - - for x'Size use 8; - for x'Alignment use 1; - for x use record - y at 0 range 0 .. 7; - end record; - - for x1'Size use 112; - for x1'Alignment use 1; - for x1'Component_Size use 11; - - for rb1'Size use 13; - for rb1'Alignment use 2; - for rb1'Component_Size use 1; - - for rb2'Size use 72; - for rb2'Alignment use 1; - for rb2'Component_Size use 1; - - for x2'Size use 224; - for x2'Alignment use 4; - for x2 use record - l1 at 0 range 0 .. 0; - l2 at 0 range 1 .. 64; - l3 at 12 range 0 .. 31; - l4 at 16 range 0 .. 0; - l5 at 16 range 1 .. 13; - l6 at 18 range 0 .. 71; - end record; - - The Size values are actually the Object_Size, i.e. the default size that - will be allocated for objects of the type. The ?? size for type r - indicates that we have a variant record, and the actual size of objects - will depend on the discriminant value. - - The Alignment values show the actual alignment chosen by the compiler - for each record or array type. - - The record representation clause for type r shows where all fields - are placed, including the compiler generated tag field (whose location - cannot be controlled by the programmer). - - The record representation clause for the type extension r2 shows all - the fields present, including the parent field, which is a copy of the - fields of the parent type of r2, i.e. r1. - - The component size and size clauses for types rb1 and rb2 show the - exact effect of pragma `Pack' on these arrays, and the record - representation clause for type x2 shows how pragma `Pack' affects this - record type. - - In some cases, it may be useful to cut and paste the representation - clauses generated by the compiler into the original source to fix and - guarantee the actual representation to be used. - -  - File: gnat_rm.info, Node: Standard Library Routines, Next: The Implementation of Standard I/O, Prev: Representation Clauses and Pragmas, Up: Top - - Standard Library Routines - ************************* - - The Ada 95 Reference Manual contains in Annex A a full description of an - extensive set of standard library routines that can be used in any Ada - program, and which must be provided by all Ada compilers. They are - analogous to the standard C library used by C programs. - - GNAT implements all of the facilities described in annex A, and for - most purposes the description in the Ada 95 reference manual, or - appropriate Ada text book, will be sufficient for making use of these - facilities. - - In the case of the input-output facilities, *Note The Implementation - of Standard I/O::, gives details on exactly how GNAT interfaces to the - file system. For the remaining packages, the Ada 95 reference manual - should be sufficient. The following is a list of the packages included, - together with a brief description of the functionality that is provided. - - For completeness, references are included to other predefined library - routines defined in other sections of the Ada 95 reference manual - (these are cross-indexed from annex A). - - `Ada (A.2)' - This is a parent package for all the standard library packages. - It is usually included implicitly in your program, and itself - contains no useful data or routines. - - `Ada.Calendar (9.6)' - `Calendar' provides time of day access, and routines for - manipulating times and durations. - - `Ada.Characters (A.3.1)' - This is a dummy parent package that contains no useful entities - - `Ada.Characters.Handling (A.3.2)' - This package provides some basic character handling capabilities, - including classification functions for classes of characters (e.g. - test for letters, or digits). - - `Ada.Characters.Latin_1 (A.3.3)' - This package includes a complete set of definitions of the - characters that appear in type CHARACTER. It is useful for - writing programs that will run in international environments. For - example, if you want an upper case E with an acute accent in a - string, it is often better to use the definition of `UC_E_Acute' - in this package. Then your program will print in an - understandable manner even if your environment does not support - these extended characters. - - `Ada.Command_Line (A.15)' - This package provides access to the command line parameters and - the name of the current program (analogous to the use of `argc' - and `argv' in C), and also allows the exit status for the program - to be set in a system-independent manner. - - `Ada.Decimal (F.2)' - This package provides constants describing the range of decimal - numbers implemented, and also a decimal divide routine (analogous - to the COBOL verb DIVIDE .. GIVING .. REMAINDER ..) - - `Ada.Direct_IO (A.8.4)' - This package provides input-output using a model of a set of - records of fixed-length, containing an arbitrary definite Ada - type, indexed by an integer record number. - - `Ada.Dynamic_Priorities (D.5)' - This package allows the priorities of a task to be adjusted - dynamically as the task is running. - - `Ada.Exceptions (11.4.1)' - This package provides additional information on exceptions, and - also contains facilities for treating exceptions as data objects, - and raising exceptions with associated messages. - - `Ada.Finalization (7.6)' - This package contains the declarations and subprograms to support - the use of controlled types, providing for automatic - initialization and finalization (analogous to the constructors and - destructors of C++) - - `Ada.Interrupts (C.3.2)' - This package provides facilities for interfacing to interrupts, - which includes the set of signals or conditions that can be raised - and recognized as interrupts. - - `Ada.Interrupts.Names (C.3.2)' - This package provides the set of interrupt names (actually signal - or condition names) that can be handled by GNAT. - - `Ada.IO_Exceptions (A.13)' - This package defines the set of exceptions that can be raised by - use of the standard IO packages. - - `Ada.Numerics' - This package contains some standard constants and exceptions used - throughout the numerics packages. Note that the constants pi and - e are defined here, and it is better to use these definitions than - rolling your own. - - `Ada.Numerics.Complex_Elementary_Functions' - Provides the implementation of standard elementary functions (such - as log and trigonometric functions) operating on complex numbers - using the standard `Float' and the `Complex' and `Imaginary' types - created by the package `Numerics.Complex_Types'. - - `Ada.Numerics.Complex_Types' - This is a predefined instantiation of - `Numerics.Generic_Complex_Types' using `Standard.Float' to build - the type `Complex' and `Imaginary'. - - `Ada.Numerics.Discrete_Random' - This package provides a random number generator suitable for - generating random integer values from a specified range. - - `Ada.Numerics.Float_Random' - This package provides a random number generator suitable for - generating uniformly distributed floating point values. - - `Ada.Numerics.Generic_Complex_Elementary_Functions' - This is a generic version of the package that provides the - implementation of standard elementary functions (such as log and - trigonometric functions) for an arbitrary complex type. - - The following predefined instantiations of this package are - provided: - - `Short_Float' - `Ada.Numerics.Short_Complex_Elementary_Functions' - - `Float' - `Ada.Numerics.Complex_Elementary_Functions' - - `Long_Float' - `Ada.Numerics. Long_Complex_Elementary_Functions' - - `Ada.Numerics.Generic_Complex_Types' - This is a generic package that allows the creation of complex - types, with associated complex arithmetic operations. - - The following predefined instantiations of this package exist - `Short_Float' - `Ada.Numerics.Short_Complex_Complex_Types' - - `Float' - `Ada.Numerics.Complex_Complex_Types' - - `Long_Float' - `Ada.Numerics.Long_Complex_Complex_Types' - - `Ada.Numerics.Generic_Elementary_Functions' - This is a generic package that provides the implementation of - standard elementary functions (such as log an trigonometric - functions) for an arbitrary float type. - - The following predefined instantiations of this package exist - - `Short_Float' - `Ada.Numerics.Short_Elementary_Functions' - - `Float' - `Ada.Numerics.Elementary_Functions' - - `Long_Float' - `Ada.Numerics.Long_Elementary_Functions' - - `Ada.Real_Time (D.8)' - This package provides facilities similar to those of `Calendar', - but operating with a finer clock suitable for real time control. - Note that annex D requires that there be no backward clock jumps, - and GNAT generally guarantees this behavior, but of course if the - external clock on which the GNAT runtime depends is deliberately - reset by some external event, then such a backward jump may occur. - - `Ada.Sequential_IO (A.8.1)' - This package provides input-output facilities for sequential files, - which can contain a sequence of values of a single type, which can - be any Ada type, including indefinite (unconstrained) types. - - `Ada.Storage_IO (A.9)' - This package provides a facility for mapping arbitrary Ada types - to and from a storage buffer. It is primarily intended for the - creation of new IO packages. - - `Ada.Streams (13.13.1)' - This is a generic package that provides the basic support for the - concept of streams as used by the stream attributes (`Input', - `Output', `Read' and `Write'). - - `Ada.Streams.Stream_IO (A.12.1)' - This package is a specialization of the type `Streams' defined in - package `Streams' together with a set of operations providing - Stream_IO capability. The Stream_IO model permits both random and - sequential access to a file which can contain an arbitrary set of - values of one or more Ada types. - - `Ada.Strings (A.4.1)' - This package provides some basic constants used by the string - handling packages. - - `Ada.Strings.Bounded (A.4.4)' - This package provides facilities for handling variable length - strings. The bounded model requires a maximum length. It is thus - somewhat more limited than the unbounded model, but avoids the use - of dynamic allocation or finalization. - - `Ada.Strings.Fixed (A.4.3)' - This package provides facilities for handling fixed length strings. - - `Ada.Strings.Maps (A.4.2)' - This package provides facilities for handling character mappings - and arbitrarily defined subsets of characters. For instance it is - useful in defining specialized translation tables. - - `Ada.Strings.Maps.Constants (A.4.6)' - This package provides a standard set of predefined mappings and - predefined character sets. For example, the standard upper to - lower case conversion table is found in this package. Note that - upper to lower case conversion is non-trivial if you want to take - the entire set of characters, including extended characters like E - with an acute accent, into account. You should use the mappings - in this package (rather than adding 32 yourself) to do case - mappings. - - `Ada.Strings.Unbounded (A.4.5)' - This package provides facilities for handling variable length - strings. The unbounded model allows arbitrary length strings, but - requires the use of dynamic allocation and finalization. - - `Ada.Strings.Wide_Bounded (A.4.7)' - `Ada.Strings.Wide_Fixed (A.4.7)' - `Ada.Strings.Wide_Maps (A.4.7)' - `Ada.Strings.Wide_Maps.Constants (A.4.7)' - `Ada.Strings.Wide_Unbounded (A.4.7)' - These package provide analogous capabilities to the corresponding - packages without `Wide_' in the name, but operate with the types - `Wide_String' and `Wide_Character' instead of `String' and - `Character'. - - `Ada.Synchronous_Task_Control (D.10)' - This package provides some standard facilities for controlling task - communication in a synchronous manner. - - `Ada.Tags' - This package contains definitions for manipulation of the tags of - tagged values. - - `Ada.Task_Attributes' - This package provides the capability of associating arbitrary - task-specific data with separate tasks. - - `Ada.Text_IO' - This package provides basic text input-output capabilities for - character, string and numeric data. The subpackages of this - package are listed next. - - `Ada.Text_IO.Decimal_IO' - Provides input-output facilities for decimal fixed-point types - - `Ada.Text_IO.Enumeration_IO' - Provides input-output facilities for enumeration types. - - `Ada.Text_IO.Fixed_IO' - Provides input-output facilities for ordinary fixed-point types. - - `Ada.Text_IO.Float_IO' - Provides input-output facilities for float types. The following - predefined instantiations of this generic package are available: - - `Short_Float' - `Short_Float_Text_IO' - - `Float' - `Float_Text_IO' - - `Long_Float' - `Long_Float_Text_IO' - - `Ada.Text_IO.Integer_IO' - Provides input-output facilities for integer types. The following - predefined instantiations of this generic package are available: - - `Short_Short_Integer' - `Ada.Short_Short_Integer_Text_IO' - - `Short_Integer' - `Ada.Short_Integer_Text_IO' - - `Integer' - `Ada.Integer_Text_IO' - - `Long_Integer' - `Ada.Long_Integer_Text_IO' - - `Long_Long_Integer' - `Ada.Long_Long_Integer_Text_IO' - - `Ada.Text_IO.Modular_IO' - Provides input-output facilities for modular (unsigned) types - - `Ada.Text_IO.Complex_IO (G.1.3)' - This package provides basic text input-output capabilities for - complex data. - - `Ada.Text_IO.Editing (F.3.3)' - This package contains routines for edited output, analogous to the - use of pictures in COBOL. The picture formats used by this - package are a close copy of the facility in COBOL. - - `Ada.Text_IO.Text_Streams (A.12.2)' - This package provides a facility that allows Text_IO files to be - treated as streams, so that the stream attributes can be used for - writing arbitrary data, including binary data, to Text_IO files. - - `Ada.Unchecked_Conversion (13.9)' - This generic package allows arbitrary conversion from one type to - another of the same size, providing for breaking the type safety in - special circumstances. - - If the types have the same Size (more accurately the same - Value_Size), then the effect is simply to transfer the bits from - the source to the target type without any modification. This - usage is well defined, and for simple types whose representation - is typically the same across all implementations, gives a portable - method of performing such conversions. - - If the types do not have the same size, then the result is - implementation defined, and thus may be non-portable. The - following describes how GNAT handles such unchecked conversion - cases. - - If the types are of different sizes, and are both discrete types, - then the effect is of a normal type conversion without any - constraint checking. In particular if the result type has a - larger size, the result will be zero or sign extended. If the - result type has a smaller size, the result will be truncated by - ignoring high order bits. - - If the types are of different sizes, and are not both discrete - types, then the conversion works as though pointers were created - to the source and target, and the pointer value is converted. The - effect is that bits are copied from successive low order storage - units and bits of the source up to the length of the target type. - - A warning is issued if the lengths differ, since the effect in this - case is implementation dependent, and the above behavior may not - match that of some other compiler. - - A pointer to one type may be converted to a pointer to another - type using unchecked conversion. The only case in which the - effect is undefined is when one or both pointers are pointers to - unconstrained array types. In this case, the bounds information - may get incorrectly transferred, and in particular, GNAT uses - double size pointers for such types, and it is meaningless to - convert between such pointer types. GNAT will issue a warning if - the alignment of the target designated type is more strict than - the alignment of the source designated type (since the result may - be unaligned in this case). - - A pointer other than a pointer to an unconstrained array type may - be converted to and from System.Address. Such usage is common in - Ada 83 programs, but note that Ada.Address_To_Access_Conversions - is the preferred method of performing such conversions in Ada 95. - Neither unchecked conversion nor Ada.Address_To_Access_Conversions - should be used in conjunction with pointers to unconstrained - objects, since the bounds information cannot be handled correctly - in this case. - - `Ada.Unchecked_Deallocation (13.11.2)' - This generic package allows explicit freeing of storage previously - allocated by use of an allocator. - - `Ada.Wide_Text_IO (A.11)' - This package is similar to `Ada.Text_IO', except that the external - file supports wide character representations, and the internal - types are `Wide_Character' and `Wide_String' instead of `Character' - and `String'. It contains generic subpackages listed next. - - `Ada.Wide_Text_IO.Decimal_IO' - Provides input-output facilities for decimal fixed-point types - - `Ada.Wide_Text_IO.Enumeration_IO' - Provides input-output facilities for enumeration types. - - `Ada.Wide_Text_IO.Fixed_IO' - Provides input-output facilities for ordinary fixed-point types. - - `Ada.Wide_Text_IO.Float_IO' - Provides input-output facilities for float types. The following - predefined instantiations of this generic package are available: - - `Short_Float' - `Short_Float_Wide_Text_IO' - - `Float' - `Float_Wide_Text_IO' - - `Long_Float' - `Long_Float_Wide_Text_IO' - - `Ada.Wide_Text_IO.Integer_IO' - Provides input-output facilities for integer types. The following - predefined instantiations of this generic package are available: - - `Short_Short_Integer' - `Ada.Short_Short_Integer_Wide_Text_IO' - - `Short_Integer' - `Ada.Short_Integer_Wide_Text_IO' - - `Integer' - `Ada.Integer_Wide_Text_IO' - - `Long_Integer' - `Ada.Long_Integer_Wide_Text_IO' - - `Long_Long_Integer' - `Ada.Long_Long_Integer_Wide_Text_IO' - - `Ada.Wide_Text_IO.Modular_IO' - Provides input-output facilities for modular (unsigned) types - - `Ada.Wide_Text_IO.Complex_IO (G.1.3)' - This package is similar to `Ada.Text_IO.Complex_IO', except that - the external file supports wide character representations. - - `Ada.Wide_Text_IO.Editing (F.3.4)' - This package is similar to `Ada.Text_IO.Editing', except that the - types are `Wide_Character' and `Wide_String' instead of - `Character' and `String'. - - `Ada.Wide_Text_IO.Streams (A.12.3)' - This package is similar to `Ada.Text_IO.Streams', except that the - types are `Wide_Character' and `Wide_String' instead of - `Character' and `String'. - -  - File: gnat_rm.info, Node: The Implementation of Standard I/O, Next: The GNAT Library, Prev: Standard Library Routines, Up: Top - - The Implementation of Standard I/O - ********************************** - - GNAT implements all the required input-output facilities described in - A.6 through A.14. These sections of the Ada 95 reference manual - describe the required behavior of these packages from the Ada point of - view, and if you are writing a portable Ada program that does not need - to know the exact manner in which Ada maps to the outside world when it - comes to reading or writing external files, then you do not need to - read this chapter. As long as your files are all regular files (not - pipes or devices), and as long as you write and read the files only - from Ada, the description in the Ada 95 reference manual is sufficient. - - However, if you want to do input-output to pipes or other devices, - such as the keyboard or screen, or if the files you are dealing with are - either generated by some other language, or to be read by some other - language, then you need to know more about the details of how the GNAT - implementation of these input-output facilities behaves. - - In this chapter we give a detailed description of exactly how GNAT - interfaces to the file system. As always, the sources of the system are - available to you for answering questions at an even more detailed level, - but for most purposes the information in this chapter will suffice. - - Another reason that you may need to know more about how input-output - is implemented arises when you have a program written in mixed languages - where, for example, files are shared between the C and Ada sections of - the same program. GNAT provides some additional facilities, in the form - of additional child library packages, that facilitate this sharing, and - these additional facilities are also described in this chapter. - - * Menu: - - * Standard I/O Packages:: - * FORM Strings:: - * Direct_IO:: - * Sequential_IO:: - * Text_IO:: - * Wide_Text_IO:: - * Stream_IO:: - * Shared Files:: - * Open Modes:: - * Operations on C Streams:: - * Interfacing to C Streams:: - -  - File: gnat_rm.info, Node: Standard I/O Packages, Next: FORM Strings, Up: The Implementation of Standard I/O - - Standard I/O Packages - ===================== - - The Standard I/O packages described in Annex A for - - * Ada.Text_IO - - * Ada.Text_IO.Complex_IO - - * Ada.Text_IO.Text_Streams, - - * Ada.Wide_Text_IO - - * Ada.Wide_Text_IO.Complex_IO, - - * Ada.Wide_Text_IO.Text_Streams - - * Ada.Stream_IO - - * Ada.Sequential_IO - - * Ada.Direct_IO - - are implemented using the C library streams facility; where - - * All files are opened using `fopen'. - - * All input/output operations use `fread'/`fwrite'. - - There is no internal buffering of any kind at the Ada library level. - The only buffering is that provided at the system level in the - implementation of the C library routines that support streams. This - facilitates shared use of these streams by mixed language programs. - -  - File: gnat_rm.info, Node: FORM Strings, Next: Direct_IO, Prev: Standard I/O Packages, Up: The Implementation of Standard I/O - - FORM Strings - ============ - - The format of a FORM string in GNAT is: - - "keyword=value,keyword=value,...,keyword=value" - - where letters may be in upper or lower case, and there are no spaces - between values. The order of the entries is not important. Currently - there are two keywords defined. - - SHARED=[YES|NO] - WCEM=[n|h|u|s\e] - - The use of these parameters is described later in this section. - -  - File: gnat_rm.info, Node: Direct_IO, Next: Sequential_IO, Prev: FORM Strings, Up: The Implementation of Standard I/O - - Direct_IO - ========= - - Direct_IO can only be instantiated for definite types. This is a - restriction of the Ada language, which means that the records are fixed - length (the length being determined by `TYPE'Size', rounded up to the - next storage unit boundary if necessary). - - The records of a Direct_IO file are simply written to the file in - index sequence, with the first record starting at offset zero, and - subsequent records following. There is no control information of any - kind. For example, if 32-bit integers are being written, each record - takes 4-bytes, so the record at index K starts at offset (K-1)*4. - - There is no limit on the size of Direct_IO files, they are expanded - as necessary to accommodate whatever records are written to the file. - -  - File: gnat_rm.info, Node: Sequential_IO, Next: Text_IO, Prev: Direct_IO, Up: The Implementation of Standard I/O - - Sequential_IO - ============= - - Sequential_IO may be instantiated with either a definite (constrained) - or indefinite (unconstrained) type. - - For the definite type case, the elements written to the file are - simply the memory images of the data values with no control information - of any kind. The resulting file should be read using the same type, no - validity checking is performed on input. - - For the indefinite type case, the elements written consist of two - parts. First is the size of the data item, written as the memory image - of a `Interfaces.C.size_t' value, followed by the memory image of the - data value. The resulting file can only be read using the same - (unconstrained) type. Normal assignment checks are performed on these - read operations, and if these checks fail, `Data_Error' is raised. In - particular, in the array case, the lengths must match, and in the - variant record case, if the variable for a particular read operation is - constrained, the discriminants must match. - - Note that it is not possible to use Sequential_IO to write variable - length array items, and then read the data back into different length - arrays. For example, the following will raise `Data_Error': - - package IO is new Sequential_IO (String); - F : IO.File_Type; - S : String (1..4); - ... - IO.Create (F) - IO.Write (F, "hello!") - IO.Reset (F, Mode=>In_File); - IO.Read (F, S); - Put_Line (S); - - On some Ada implementations, this will print `hell', but the program - is clearly incorrect, since there is only one element in the file, and - that element is the string `hello!'. - - In Ada 95, this kind of behavior can be legitimately achieved using - Stream_IO, and this is the preferred mechanism. In particular, the - above program fragment rewritten to use Stream_IO will work correctly. - -  - File: gnat_rm.info, Node: Text_IO, Next: Wide_Text_IO, Prev: Sequential_IO, Up: The Implementation of Standard I/O - - Text_IO - ======= - - Text_IO files consist of a stream of characters containing the following - special control characters: - - LF (line feed, 16#0A#) Line Mark - FF (form feed, 16#0C#) Page Mark - - A canonical Text_IO file is defined as one in which the following - conditions are met: - - * The character `LF' is used only as a line mark, i.e. to mark the - end of the line. - - * The character `FF' is used only as a page mark, i.e. to mark the - end of a page and consequently can appear only immediately - following a `LF' (line mark) character. - - * The file ends with either `LF' (line mark) or `LF'-`FF' (line - mark, page mark). In the former case, the page mark is implicitly - assumed to be present. - - A file written using Text_IO will be in canonical form provided that - no explicit `LF' or `FF' characters are written using `Put' or - `Put_Line'. There will be no `FF' character at the end of the file - unless an explicit `New_Page' operation was performed before closing - the file. - - A canonical Text_IO file that is a regular file, i.e. not a device - or a pipe, can be read using any of the routines in Text_IO. The - semantics in this case will be exactly as defined in the Ada 95 - reference manual and all the routines in Text_IO are fully implemented. - - A text file that does not meet the requirements for a canonical - Text_IO file has one of the following: - - * The file contains `FF' characters not immediately following a `LF' - character. - - * The file contains `LF' or `FF' characters written by `Put' or - `Put_Line', which are not logically considered to be line marks or - page marks. - - * The file ends in a character other than `LF' or `FF', i.e. there - is no explicit line mark or page mark at the end of the file. - - Text_IO can be used to read such non-standard text files but - subprograms to do with line or page numbers do not have defined - meanings. In particular, a `FF' character that does not follow a `LF' - character may or may not be treated as a page mark from the point of - view of page and line numbering. Every `LF' character is considered to - end a line, and there is an implied `LF' character at the end of the - file. - - * Menu: - - * Text_IO Stream Pointer Positioning:: - * Text_IO Reading and Writing Non-Regular Files:: - * Get_Immediate:: - * Treating Text_IO Files as Streams:: - * Text_IO Extensions:: - * Text_IO Facilities for Unbounded Strings:: - -  - File: gnat_rm.info, Node: Text_IO Stream Pointer Positioning, Next: Text_IO Reading and Writing Non-Regular Files, Up: Text_IO - - Stream Pointer Positioning - -------------------------- - - `Ada.Text_IO' has a definition of current position for a file that is - being read. No internal buffering occurs in Text_IO, and usually the - physical position in the stream used to implement the file corresponds - to this logical position defined by Text_IO. There are two exceptions: - - * After a call to `End_Of_Page' that returns `True', the stream is - positioned past the `LF' (line mark) that precedes the page mark. - Text_IO maintains an internal flag so that subsequent read - operations properly handle the logical position which is unchanged - by the `End_Of_Page' call. - - * After a call to `End_Of_File' that returns `True', if the Text_IO - file was positioned before the line mark at the end of file before - the call, then the logical position is unchanged, but the stream - is physically positioned right at the end of file (past the line - mark, and past a possible page mark following the line mark. - Again Text_IO maintains internal flags so that subsequent read - operations properly handle the logical position. - - These discrepancies have no effect on the observable behavior of - Text_IO, but if a single Ada stream is shared between a C program and - Ada program, or shared (using `shared=yes' in the form string) between - two Ada files, then the difference may be observable in some situations. - -  - File: gnat_rm.info, Node: Text_IO Reading and Writing Non-Regular Files, Next: Get_Immediate, Prev: Text_IO Stream Pointer Positioning, Up: Text_IO - - Reading and Writing Non-Regular Files - ------------------------------------- - - A non-regular file is a device (such as a keyboard), or a pipe. Text_IO - can be used for reading and writing. Writing is not affected and the - sequence of characters output is identical to the normal file case, but - for reading, the behavior of Text_IO is modified to avoid undesirable - look-ahead as follows: - - An input file that is not a regular file is considered to have no - page marks. Any `Ascii.FF' characters (the character normally used for - a page mark) appearing in the file are considered to be data - characters. In particular: - - * `Get_Line' and `Skip_Line' do not test for a page mark following a - line mark. If a page mark appears, it will be treated as a data - character. - - * This avoids the need to wait for an extra character to be typed or - entered from the pipe to complete one of these operations. - - * `End_Of_Page' always returns `False' - - * `End_Of_File' will return `False' if there is a page mark at the - end of the file. - - Output to non-regular files is the same as for regular files. Page - marks may be written to non-regular files using `New_Page', but as noted - above they will not be treated as page marks on input if the output is - piped to another Ada program. - - Another important discrepancy when reading non-regular files is that - the end of file indication is not "sticky". If an end of file is - entered, e.g. by pressing the key, then end of file is signalled - once (i.e. the test `End_Of_File' will yield `True', or a read will - raise `End_Error'), but then reading can resume to read data past that - end of file indication, until another end of file indication is entered. - -  - File: gnat_rm.info, Node: Get_Immediate, Next: Treating Text_IO Files as Streams, Prev: Text_IO Reading and Writing Non-Regular Files, Up: Text_IO - - Get_Immediate - ------------- - - Get_Immediate returns the next character (including control characters) - from the input file. In particular, Get_Immediate will return LF or FF - characters used as line marks or page marks. Such operations leave the - file positioned past the control character, and it is thus not treated - as having its normal function. This means that page, line and column - counts after this kind of Get_Immediate call are set as though the mark - did not occur. In the case where a Get_Immediate leaves the file - positioned between the line mark and page mark (which is not normally - possible), it is undefined whether the FF character will be treated as a - page mark. - -  - File: gnat_rm.info, Node: Treating Text_IO Files as Streams, Next: Text_IO Extensions, Prev: Get_Immediate, Up: Text_IO - - Treating Text_IO Files as Streams - --------------------------------- - - The package `Text_IO.Streams' allows a Text_IO file to be treated as a - stream. Data written to a Text_IO file in this stream mode is binary - data. If this binary data contains bytes 16#0A# (`LF') or 16#0C# - (`FF'), the resulting file may have non-standard format. Similarly if - read operations are used to read from a Text_IO file treated as a - stream, then `LF' and `FF' characters may be skipped and the effect is - similar to that described above for `Get_Immediate'. - -  - File: gnat_rm.info, Node: Text_IO Extensions, Next: Text_IO Facilities for Unbounded Strings, Prev: Treating Text_IO Files as Streams, Up: Text_IO - - Text_IO Extensions - ------------------ - - A package GNAT.IO_Aux in the GNAT library provides some useful - extensions to the standard `Text_IO' package: - - * function File_Exists (Name : String) return Boolean; Determines if - a file of the given name exists and can be successfully opened - (without actually performing the open operation). - - * function Get_Line return String; Reads a string from the standard - input file. The value returned is exactly the length of the line - that was read. - - * function Get_Line (File : Ada.Text_IO.File_Type) return String; - Similar, except that the parameter File specifies the file from - which the string is to be read. - - -  - File: gnat_rm.info, Node: Text_IO Facilities for Unbounded Strings, Prev: Text_IO Extensions, Up: Text_IO - - Text_IO Facilities for Unbounded Strings - ---------------------------------------- - - The package `Ada.Strings.Unbounded.Text_IO' in library files - `a-suteio.ads/adb' contains some GNAT-specific subprograms useful for - Text_IO operations on unbounded strings: - - * function Get_Line (File : File_Type) return Unbounded_String; - Reads a line from the specified file and returns the result as an - unbounded string. - - * procedure Put (File : File_Type; U : Unbounded_String); Writes the - value of the given unbounded string to the specified file Similar - to the effect of `Put (To_String (U))' except that an extra copy - is avoided. - - * procedure Put_Line (File : File_Type; U : Unbounded_String); - Writes the value of the given unbounded string to the specified - file, followed by a `New_Line'. Similar to the effect of - `Put_Line (To_String (U))' except that an extra copy is avoided. - - In the above procedures, `File' is of type `Ada.Text_IO.File_Type' and - is optional. If the parameter is omitted, then the standard input or - output file is referenced as appropriate. - - The package `Ada.Strings.Wide_Unbounded.Wide_Text_IO' in library - files `a-swuwti.ads' and `a-swuwti.adb' provides similar extended - `Wide_Text_IO' functionality for unbounded wide strings. - -  - File: gnat_rm.info, Node: Wide_Text_IO, Next: Stream_IO, Prev: Text_IO, Up: The Implementation of Standard I/O - - Wide_Text_IO - ============ - - `Wide_Text_IO' is similar in most respects to Text_IO, except that both - input and output files may contain special sequences that represent - wide character values. The encoding scheme for a given file may be - specified using a FORM parameter: - - WCEM=X - - as part of the FORM string (WCEM = wide character encoding method), - where X is one of the following characters - - `h' - Hex ESC encoding - - `u' - Upper half encoding - - `s' - Shift-JIS encoding - - `e' - EUC Encoding - - `8' - UTF-8 encoding - - `b' - Brackets encoding - - The encoding methods match those that can be used in a source - program, but there is no requirement that the encoding method used for - the source program be the same as the encoding method used for files, - and different files may use different encoding methods. - - The default encoding method for the standard files, and for opened - files for which no WCEM parameter is given in the FORM string matches - the wide character encoding specified for the main program (the default - being brackets encoding if no coding method was specified with -gnatW). - - Hex Coding - In this encoding, a wide character is represented by a five - character sequence: - - ESC a b c d - - where A, B, C, D are the four hexadecimal characters (using upper - case letters) of the wide character code. For example, ESC A345 - is used to represent the wide character with code 16#A345#. This - scheme is compatible with use of the full `Wide_Character' set. - - Upper Half Coding - The wide character with encoding 16#abcd#, where the upper bit is - on (i.e. a is in the range 8-F) is represented as two bytes 16#ab# - and 16#cd#. The second byte may never be a format control - character, but is not required to be in the upper half. This - method can be also used for shift-JIS or EUC where the internal - coding matches the external coding. - - Shift JIS Coding - A wide character is represented by a two character sequence 16#ab# - and 16#cd#, with the restrictions described for upper half - encoding as described above. The internal character code is the - corresponding JIS character according to the standard algorithm - for Shift-JIS conversion. Only characters defined in the JIS code - set table can be used with this encoding method. - - EUC Coding - A wide character is represented by a two character sequence 16#ab# - and 16#cd#, with both characters being in the upper half. The - internal character code is the corresponding JIS character - according to the EUC encoding algorithm. Only characters defined - in the JIS code set table can be used with this encoding method. - - UTF-8 Coding - A wide character is represented using UCS Transformation Format 8 - (UTF-8) as defined in Annex R of ISO 10646-1/Am.2. Depending on - the character value, the representation is a one, two, or three - byte sequence: - - 16#0000#-16#007f#: 2#0xxxxxxx# - 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# - 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# - - where the xxx bits correspond to the left-padded bits of the - 16-bit character value. Note that all lower half ASCII characters - are represented as ASCII bytes and all upper half characters and - other wide characters are represented as sequences of upper-half - (The full UTF-8 scheme allows for encoding 31-bit characters as - 6-byte sequences, but in this implementation, all UTF-8 sequences - of four or more bytes length will raise a Constraint_Error, as - will all invalid UTF-8 sequences.) - - Brackets Coding - In this encoding, a wide character is represented by the following - eight character sequence: - - [ " a b c d " ] - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For - example, `["A345"]' is used to represent the wide character with - code `16#A345#'. This scheme is compatible with use of the full - Wide_Character set. On input, brackets coding can also be used - for upper half characters, e.g. `["C1"]' for lower case a. - However, on output, brackets notation is only used for wide - characters with a code greater than `16#FF#'. - - For the coding schemes other than Hex and Brackets encoding, not all - wide character values can be represented. An attempt to output a - character that cannot be represented using the encoding scheme for the - file causes Constraint_Error to be raised. An invalid wide character - sequence on input also causes Constraint_Error to be raised. - - * Menu: - - * Wide_Text_IO Stream Pointer Positioning:: - * Wide_Text_IO Reading and Writing Non-Regular Files:: - -  - File: gnat_rm.info, Node: Wide_Text_IO Stream Pointer Positioning, Next: Wide_Text_IO Reading and Writing Non-Regular Files, Up: Wide_Text_IO - - Stream Pointer Positioning - -------------------------- - - `Ada.Wide_Text_IO' is similar to `Ada.Text_IO' in its handling of - stream pointer positioning (*note Text_IO::). There is one additional - case: - - If `Ada.Wide_Text_IO.Look_Ahead' reads a character outside the - normal lower ASCII set (i.e. a character in the range: - - Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) - - then although the logical position of the file pointer is unchanged by - the `Look_Ahead' call, the stream is physically positioned past the - wide character sequence. Again this is to avoid the need for buffering - or backup, and all `Wide_Text_IO' routines check the internal - indication that this situation has occurred so that this is not visible - to a normal program using `Wide_Text_IO'. However, this discrepancy - can be observed if the wide text file shares a stream with another file. - -  - File: gnat_rm.info, Node: Wide_Text_IO Reading and Writing Non-Regular Files, Prev: Wide_Text_IO Stream Pointer Positioning, Up: Wide_Text_IO - - Reading and Writing Non-Regular Files - ------------------------------------- - - As in the case of Text_IO, when a non-regular file is read, it is - assumed that the file contains no page marks (any form characters are - treated as data characters), and `End_Of_Page' always returns `False'. - Similarly, the end of file indication is not sticky, so it is possible - to read beyond an end of file. - -  - File: gnat_rm.info, Node: Stream_IO, Next: Shared Files, Prev: Wide_Text_IO, Up: The Implementation of Standard I/O - - Stream_IO - ========= - - A stream file is a sequence of bytes, where individual elements are - written to the file as described in the Ada 95 reference manual. The - type `Stream_Element' is simply a byte. There are two ways to read or - write a stream file. - - * The operations `Read' and `Write' directly read or write a - sequence of stream elements with no control information. - - * The stream attributes applied to a stream file transfer data in the - manner described for stream attributes. - -  - File: gnat_rm.info, Node: Shared Files, Next: Open Modes, Prev: Stream_IO, Up: The Implementation of Standard I/O - - Shared Files - ============ - - Section A.14 of the Ada 95 Reference Manual allows implementations to - provide a wide variety of behavior if an attempt is made to access the - same external file with two or more internal files. - - To provide a full range of functionality, while at the same time - minimizing the problems of portability caused by this implementation - dependence, GNAT handles file sharing as follows: - - * In the absence of a `shared=XXX' form parameter, an attempt to - open two or more files with the same full name is considered an - error and is not supported. The exception `Use_Error' will be - raised. Note that a file that is not explicitly closed by the - program remains open until the program terminates. - - * If the form parameter `shared=no' appears in the form string, the - file can be opened or created with its own separate stream - identifier, regardless of whether other files sharing the same - external file are opened. The exact effect depends on how the C - stream routines handle multiple accesses to the same external - files using separate streams. - - * If the form parameter `shared=yes' appears in the form string for - each of two or more files opened using the same full name, the same - stream is shared between these files, and the semantics are as - described in Ada 95 Reference Manual, Section A.14. - - When a program that opens multiple files with the same name is ported - from another Ada compiler to GNAT, the effect will be that `Use_Error' - is raised. - - The documentation of the original compiler and the documentation of - the program should then be examined to determine if file sharing was - expected, and `shared=XXX' parameters added to `Open' and `Create' - calls as required. - - When a program is ported from GNAT to some other Ada compiler, no - special attention is required unless the `shared=XXX' form parameter is - used in the program. In this case, you must examine the documentation - of the new compiler to see if it supports the required file sharing - semantics, and form strings modified appropriately. Of course it may - be the case that the program cannot be ported if the target compiler - does not support the required functionality. The best approach in - writing portable code is to avoid file sharing (and hence the use of - the `shared=XXX' parameter in the form string) completely. - - One common use of file sharing in Ada 83 is the use of - instantiations of Sequential_IO on the same file with different types, - to achieve heterogeneous input-output. Although this approach will - work in GNAT if `shared=yes' is specified, it is preferable in Ada 95 - to use Stream_IO for this purpose (using the stream attributes) - -  - File: gnat_rm.info, Node: Open Modes, Next: Operations on C Streams, Prev: Shared Files, Up: The Implementation of Standard I/O - - Open Modes - ========== - - `Open' and `Create' calls result in a call to `fopen' using the mode - shown in Table 6.1 - - - - Table 6-1 `Open' and `Create' Call Modes - OPEN CREATE - Append_File "r+" "w+" - In_File "r" "w+" - Out_File (Direct_IO) "r+" "w" - Out_File (all other cases) "w" "w" - Inout_File "r+" "w+" - - If text file translation is required, then either `b' or `t' is - added to the mode, depending on the setting of Text. Text file - translation refers to the mapping of CR/LF sequences in an external file - to LF characters internally. This mapping only occurs in DOS and - DOS-like systems, and is not relevant to other systems. - - A special case occurs with Stream_IO. As shown in the above table, - the file is initially opened in `r' or `w' mode for the `In_File' and - `Out_File' cases. If a `Set_Mode' operation subsequently requires - switching from reading to writing or vice-versa, then the file is - reopened in `r+' mode to permit the required operation. - -  - File: gnat_rm.info, Node: Operations on C Streams, Next: Interfacing to C Streams, Prev: Open Modes, Up: The Implementation of Standard I/O - - Operations on C Streams - ======================= - - The package `Interfaces.C_Streams' provides an Ada program with - direct access to the C library functions for operations on C streams: - - package Interfaces.C_Streams is - -- Note: the reason we do not use the types that are in - -- Interfaces.C is that we want to avoid dragging in the - -- code in this unit if possible. - subtype chars is System.Address; - -- Pointer to null-terminated array of characters - subtype FILEs is System.Address; - -- Corresponds to the C type FILE* - subtype voids is System.Address; - -- Corresponds to the C type void* - subtype int is Integer; - subtype long is Long_Integer; - -- Note: the above types are subtypes deliberately, and it - -- is part of this spec that the above correspondences are - -- guaranteed. This means that it is legitimate to, for - -- example, use Integer instead of int. We provide these - -- synonyms for clarity, but in some cases it may be - -- convenient to use the underlying types (for example to - -- avoid an unnecessary dependency of a spec on the spec - -- of this unit). - type size_t is mod 2 ** Standard'Address_Size; - NULL_Stream : constant FILEs; - -- Value returned (NULL in C) to indicate an - -- fdopen/fopen/tmpfile error - ---------------------------------- - -- Constants Defined in stdio.h -- - ---------------------------------- - EOF : constant int; - -- Used by a number of routines to indicate error or - -- end of file - IOFBF : constant int; - IOLBF : constant int; - IONBF : constant int; - -- Used to indicate buffering mode for setvbuf call - SEEK_CUR : constant int; - SEEK_END : constant int; - SEEK_SET : constant int; - -- Used to indicate origin for fseek call - function stdin return FILEs; - function stdout return FILEs; - function stderr return FILEs; - -- Streams associated with standard files - -------------------------- - -- Standard C functions -- - -------------------------- - -- The functions selected below are ones that are - -- available in DOS, OS/2, UNIX and Xenix (but not - -- necessarily in ANSI C). These are very thin interfaces - -- which copy exactly the C headers. For more - -- documentation on these functions, see the Microsoft C - -- "Run-Time Library Reference" (Microsoft Press, 1990, - -- ISBN 1-55615-225-6), which includes useful information - -- on system compatibility. - procedure clearerr (stream : FILEs); - function fclose (stream : FILEs) return int; - function fdopen (handle : int; mode : chars) return FILEs; - function feof (stream : FILEs) return int; - function ferror (stream : FILEs) return int; - function fflush (stream : FILEs) return int; - function fgetc (stream : FILEs) return int; - function fgets (strng : chars; n : int; stream : FILEs) - return chars; - function fileno (stream : FILEs) return int; - function fopen (filename : chars; Mode : chars) - return FILEs; - -- Note: to maintain target independence, use - -- text_translation_required, a boolean variable defined in - -- a-sysdep.c to deal with the target dependent text - -- translation requirement. If this variable is set, - -- then b/t should be appended to the standard mode - -- argument to set the text translation mode off or on - -- as required. - function fputc (C : int; stream : FILEs) return int; - function fputs (Strng : chars; Stream : FILEs) return int; - function fread - (buffer : voids; - size : size_t; - count : size_t; - stream : FILEs) - return size_t; - function freopen - (filename : chars; - mode : chars; - stream : FILEs) - return FILEs; - function fseek - (stream : FILEs; - offset : long; - origin : int) - return int; - function ftell (stream : FILEs) return long; - function fwrite - (buffer : voids; - size : size_t; - count : size_t; - stream : FILEs) - return size_t; - function isatty (handle : int) return int; - procedure mktemp (template : chars); - -- The return value (which is just a pointer to template) - -- is discarded - procedure rewind (stream : FILEs); - function rmtmp return int; - function setvbuf - (stream : FILEs; - buffer : chars; - mode : int; - size : size_t) - return int; - - function tmpfile return FILEs; - function ungetc (c : int; stream : FILEs) return int; - function unlink (filename : chars) return int; - --------------------- - -- Extra functions -- - --------------------- - -- These functions supply slightly thicker bindings than - -- those above. They are derived from functions in the - -- C Run-Time Library, but may do a bit more work than - -- just directly calling one of the Library functions. - function is_regular_file (handle : int) return int; - -- Tests if given handle is for a regular file (result 1) - -- or for a non-regular file (pipe or device, result 0). - --------------------------------- - -- Control of Text/Binary Mode -- - --------------------------------- - -- If text_translation_required is true, then the following - -- functions may be used to dynamically switch a file from - -- binary to text mode or vice versa. These functions have - -- no effect if text_translation_required is false (i.e. in - -- normal UNIX mode). Use fileno to get a stream handle. - procedure set_binary_mode (handle : int); - procedure set_text_mode (handle : int); - ---------------------------- - -- Full Path Name support -- - ---------------------------- - procedure full_name (nam : chars; buffer : chars); - -- Given a NUL terminated string representing a file - -- name, returns in buffer a NUL terminated string - -- representing the full path name for the file name. - -- On systems where it is relevant the drive is also - -- part of the full path name. It is the responsibility - -- of the caller to pass an actual parameter for buffer - -- that is big enough for any full path name. Use - -- max_path_len given below as the size of buffer. - max_path_len : integer; - -- Maximum length of an allowable full path name on the - -- system, including a terminating NUL character. - end Interfaces.C_Streams; - -  - File: gnat_rm.info, Node: Interfacing to C Streams, Prev: Operations on C Streams, Up: The Implementation of Standard I/O - - Interfacing to C Streams - ======================== - - The packages in this section permit interfacing Ada files to C Stream - operations. - - with Interfaces.C_Streams; - package Ada.Sequential_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); - end Ada.Sequential_IO.C_Streams; - - with Interfaces.C_Streams; - package Ada.Direct_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); - end Ada.Direct_IO.C_Streams; - - with Interfaces.C_Streams; - package Ada.Text_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); - end Ada.Text_IO.C_Streams; - - with Interfaces.C_Streams; - package Ada.Wide_Text_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); - end Ada.Wide_Text_IO.C_Streams; - - with Interfaces.C_Streams; - package Ada.Stream_IO.C_Streams is - function C_Stream (F : File_Type) - return Interfaces.C_Streams.FILEs; - procedure Open - (File : in out File_Type; - Mode : in File_Mode; - C_Stream : in Interfaces.C_Streams.FILEs; - Form : in String := ""); - end Ada.Stream_IO.C_Streams; - - In each of these five packages, the `C_Stream' function obtains the - `FILE' pointer from a currently opened Ada file. It is then possible - to use the `Interfaces.C_Streams' package to operate on this stream, or - the stream can be passed to a C program which can operate on it - directly. Of course the program is responsible for ensuring that only - appropriate sequences of operations are executed. - - One particular use of relevance to an Ada program is that the - `setvbuf' function can be used to control the buffering of the stream - used by an Ada file. In the absence of such a call the standard - default buffering is used. - - The `Open' procedures in these packages open a file giving an - existing C Stream instead of a file name. Typically this stream is - imported from a C program, allowing an Ada file to operate on an - existing C file. - -  - File: gnat_rm.info, Node: The GNAT Library, Next: Interfacing to Other Languages, Prev: The Implementation of Standard I/O, Up: Top - - The GNAT Library - **************** - - The GNAT library contains a number of general and special purpose - packages. It represents functionality that the GNAT developers have - found useful, and which is made available to GNAT users. The packages - described here are fully supported, and upwards compatibility will be - maintained in future releases, so you can use these facilities with the - confidence that the same functionality will be available in future - releases. - - The chapter here simply gives a brief summary of the facilities - available. The full documentation is found in the spec file for the - package. The full sources of these library packages, including both - spec and body, are provided with all GNAT releases. For example, to - find out the full specifications of the SPITBOL pattern matching - capability, including a full tutorial and extensive examples, look in - the `g-spipat.ads' file in the library. - - For each entry here, the package name (as it would appear in a `with' - clause) is given, followed by the name of the corresponding spec file in - parentheses. The packages are children in four hierarchies, `Ada', - `Interfaces', `System', and `GNAT', the latter being a GNAT-specific - hierarchy. - - Note that an application program should only use packages in one of - these four hierarchies if the package is defined in the Ada Reference - Manual, or is listed in this section of the GNAT Programmers Reference - Manual. All other units should be considered internal implementation - units and should not be directly `with''ed by application code. The - use of a `with' statement that references one of these internal - implementation units makes an application potentially dependent on - changes in versions of GNAT, and will generate a warning message. - - * Menu: - - * Ada.Characters.Latin_9 (a-chlat9.ads):: - * Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: - * Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: - * Ada.Command_Line.Remove (a-colire.ads):: - * Ada.Direct_IO.C_Streams (a-diocst.ads):: - * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: - * Ada.Sequential_IO.C_Streams (a-siocst.ads):: - * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: - * Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: - * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: - * Ada.Text_IO.C_Streams (a-tiocst.ads):: - * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: - * GNAT.AWK (g-awk.ads):: - * GNAT.Bubble_Sort_A (g-busora.ads):: - * GNAT.Bubble_Sort_G (g-busorg.ads):: - * GNAT.Calendar (g-calend.ads):: - * GNAT.Calendar.Time_IO (g-catiio.ads):: - * GNAT.CRC32 (g-crc32.ads):: - * GNAT.Case_Util (g-casuti.ads):: - * GNAT.CGI (g-cgi.ads):: - * GNAT.CGI.Cookie (g-cgicoo.ads):: - * GNAT.CGI.Debug (g-cgideb.ads):: - * GNAT.Command_Line (g-comlin.ads):: - * GNAT.Current_Exception (g-curexc.ads):: - * GNAT.Debug_Pools (g-debpoo.ads):: - * GNAT.Debug_Utilities (g-debuti.ads):: - * GNAT.Directory_Operations (g-dirope.ads):: - * GNAT.Dynamic_Tables (g-dyntab.ads):: - * GNAT.Exception_Traces (g-exctra.ads):: - * GNAT.Expect (g-expect.ads):: - * GNAT.Float_Control (g-flocon.ads):: - * GNAT.Heap_Sort_A (g-hesora.ads):: - * GNAT.Heap_Sort_G (g-hesorg.ads):: - * GNAT.HTable (g-htable.ads):: - * GNAT.IO (g-io.ads):: - * GNAT.IO_Aux (g-io_aux.ads):: - * GNAT.Lock_Files (g-locfil.ads):: - * GNAT.MD5 (g-md5.ads):: - * GNAT.Most_Recent_Exception (g-moreex.ads):: - * GNAT.OS_Lib (g-os_lib.ads):: - * GNAT.Regexp (g-regexp.ads):: - * GNAT.Registry (g-regist.ads):: - * GNAT.Regpat (g-regpat.ads):: - * GNAT.Sockets (g-socket.ads):: - * GNAT.Source_Info (g-souinf.ads):: - * GNAT.Spell_Checker (g-speche.ads):: - * GNAT.Spitbol.Patterns (g-spipat.ads):: - * GNAT.Spitbol (g-spitbo.ads):: - * GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: - * GNAT.Spitbol.Table_Integer (g-sptain.ads):: - * GNAT.Spitbol.Table_VString (g-sptavs.ads):: - * GNAT.Table (g-table.ads):: - * GNAT.Task_Lock (g-tasloc.ads):: - * GNAT.Threads (g-thread.ads):: - * GNAT.Traceback (g-traceb.ads):: - * GNAT.Traceback.Symbolic (g-trasym.ads):: - * Interfaces.C.Extensions (i-cexten.ads):: - * Interfaces.C.Streams (i-cstrea.ads):: - * Interfaces.CPP (i-cpp.ads):: - * Interfaces.Os2lib (i-os2lib.ads):: - * Interfaces.Os2lib.Errors (i-os2err.ads):: - * Interfaces.Os2lib.Synchronization (i-os2syn.ads):: - * Interfaces.Os2lib.Threads (i-os2thr.ads):: - * Interfaces.Packed_Decimal (i-pacdec.ads):: - * Interfaces.VxWorks (i-vxwork.ads):: - * Interfaces.VxWorks.IO (i-vxwoio.ads):: - * System.Address_Image (s-addima.ads):: - * System.Assertions (s-assert.ads):: - * System.Partition_Interface (s-parint.ads):: - * System.Task_Info (s-tasinf.ads):: - * System.Wch_Cnv (s-wchcnv.ads):: - * System.Wch_Con (s-wchcon.ads):: - -  - File: gnat_rm.info, Node: Ada.Characters.Latin_9 (a-chlat9.ads), Next: Ada.Characters.Wide_Latin_1 (a-cwila1.ads), Up: The GNAT Library - - `Ada.Characters.Latin_9' (`a-chlat9.ads') - ========================================= - - This child of `Ada.Characters' provides a set of definitions - corresponding to those in the RM-defined package - `Ada.Characters.Latin_1' but with the few modifications required for - `Latin-9' The provision of such a package is specifically authorized by - the Ada Reference Manual (RM A.3(27)). - -  - File: gnat_rm.info, Node: Ada.Characters.Wide_Latin_1 (a-cwila1.ads), Next: Ada.Characters.Wide_Latin_9 (a-cwila9.ads), Prev: Ada.Characters.Latin_9 (a-chlat9.ads), Up: The GNAT Library - - `Ada.Characters.Wide_Latin_1' (`a-cwila1.ads') - ============================================== - - This child of `Ada.Characters' provides a set of definitions - corresponding to those in the RM-defined package - `Ada.Characters.Latin_1' but with the types of the constants being - `Wide_Character' instead of `Character'. The provision of such a - package is specifically authorized by the Ada Reference Manual (RM - A.3(27)). - -  - File: gnat_rm.info, Node: Ada.Characters.Wide_Latin_9 (a-cwila9.ads), Next: Ada.Command_Line.Remove (a-colire.ads), Prev: Ada.Characters.Wide_Latin_1 (a-cwila1.ads), Up: The GNAT Library - - `Ada.Characters.Wide_Latin_9' (`a-cwila1.ads') - ============================================== - - This child of `Ada.Characters' provides a set of definitions - corresponding to those in the GNAT defined package - `Ada.Characters.Latin_9' but with the types of the constants being - `Wide_Character' instead of `Character'. The provision of such a - package is specifically authorized by the Ada Reference Manual (RM - A.3(27)). - -  - File: gnat_rm.info, Node: Ada.Command_Line.Remove (a-colire.ads), Next: Ada.Direct_IO.C_Streams (a-diocst.ads), Prev: Ada.Characters.Wide_Latin_9 (a-cwila9.ads), Up: The GNAT Library - - `Ada.Command_Line.Remove' (`a-colire.ads') - ========================================== - - This child of `Ada.Command_Line' provides a mechanism for logically - removing arguments from the argument list. Once removed, an argument - is not visible to further calls on the subprograms in - `Ada.Command_Line' will not see the removed argument. - -  - File: gnat_rm.info, Node: Ada.Direct_IO.C_Streams (a-diocst.ads), Next: Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads), Prev: Ada.Command_Line.Remove (a-colire.ads), Up: The GNAT Library - - `Ada.Direct_IO.C_Streams' (`a-diocst.ads') - ========================================== - - This package provides subprograms that allow interfacing between C - streams and `Direct_IO'. The stream identifier can be extracted from a - file opened on the Ada side, and an Ada file can be constructed from a - stream opened on the C side. - -  - File: gnat_rm.info, Node: Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads), Next: Ada.Sequential_IO.C_Streams (a-siocst.ads), Prev: Ada.Direct_IO.C_Streams (a-diocst.ads), Up: The GNAT Library - - `Ada.Exceptions.Is_Null_Occurrence' (`a-einuoc.ads') - ==================================================== - - This child subprogram provides a way of testing for the null exception - occurrence (`Null_Occurrence') without raising an exception. - -  - File: gnat_rm.info, Node: Ada.Sequential_IO.C_Streams (a-siocst.ads), Next: Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads), Prev: Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads), Up: The GNAT Library - - `Ada.Sequential_IO.C_Streams' (`a-siocst.ads') - ============================================== - - This package provides subprograms that allow interfacing between C - streams and `Sequential_IO'. The stream identifier can be extracted - from a file opened on the Ada side, and an Ada file can be constructed - from a stream opened on the C side. - -  - File: gnat_rm.info, Node: Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads), Next: Ada.Strings.Unbounded.Text_IO (a-suteio.ads), Prev: Ada.Sequential_IO.C_Streams (a-siocst.ads), Up: The GNAT Library - - `Ada.Streams.Stream_IO.C_Streams' (`a-ssicst.ads') - ================================================== - - This package provides subprograms that allow interfacing between C - streams and `Stream_IO'. The stream identifier can be extracted from a - file opened on the Ada side, and an Ada file can be constructed from a - stream opened on the C side. - -  - File: gnat_rm.info, Node: Ada.Strings.Unbounded.Text_IO (a-suteio.ads), Next: Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads), Prev: Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads), Up: The GNAT Library - - `Ada.Strings.Unbounded.Text_IO' (`a-suteio.ads') - ================================================ - - This package provides subprograms for Text_IO for unbounded strings, - avoiding the necessity for an intermediate operation with ordinary - strings. - -  - File: gnat_rm.info, Node: Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads), Next: Ada.Text_IO.C_Streams (a-tiocst.ads), Prev: Ada.Strings.Unbounded.Text_IO (a-suteio.ads), Up: The GNAT Library - - `Ada.Strings.Wide_Unbounded.Wide_Text_IO' (`a-swuwti.ads') - ========================================================== - - This package provides subprograms for Text_IO for unbounded wide - strings, avoiding the necessity for an intermediate operation with - ordinary wide strings. - -  - File: gnat_rm.info, Node: Ada.Text_IO.C_Streams (a-tiocst.ads), Next: Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads), Prev: Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads), Up: The GNAT Library - - `Ada.Text_IO.C_Streams' (`a-tiocst.ads') - ======================================== - - This package provides subprograms that allow interfacing between C - streams and `Text_IO'. The stream identifier can be extracted from a - file opened on the Ada side, and an Ada file can be constructed from a - stream opened on the C side. - -  - File: gnat_rm.info, Node: Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads), Next: GNAT.AWK (g-awk.ads), Prev: Ada.Text_IO.C_Streams (a-tiocst.ads), Up: The GNAT Library - - `Ada.Wide_Text_IO.C_Streams' (`a-wtcstr.ads') - ============================================= - - This package provides subprograms that allow interfacing between C - streams and `Wide_Text_IO'. The stream identifier can be extracted - from a file opened on the Ada side, and an Ada file can be constructed - from a stream opened on the C side. - -  - File: gnat_rm.info, Node: GNAT.AWK (g-awk.ads), Next: GNAT.Bubble_Sort_A (g-busora.ads), Prev: Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads), Up: The GNAT Library - - `GNAT.AWK' (`g-awk.ads') - ======================== - - Provides AWK-like parsing functions, with an easy interface for parsing - one or more files containing formatted data. The file is viewed as a - database where each record is a line and a field is a data element in - this line. - -  - File: gnat_rm.info, Node: GNAT.Bubble_Sort_A (g-busora.ads), Next: GNAT.Bubble_Sort_G (g-busorg.ads), Prev: GNAT.AWK (g-awk.ads), Up: The GNAT Library - - `GNAT.Bubble_Sort_A' (`g-busora.ads') - ===================================== - - Provides a general implementation of bubble sort usable for sorting - arbitrary data items. Move and comparison procedures are provided by - passing access-to-procedure values. - -  - File: gnat_rm.info, Node: GNAT.Bubble_Sort_G (g-busorg.ads), Next: GNAT.Calendar (g-calend.ads), Prev: GNAT.Bubble_Sort_A (g-busora.ads), Up: The GNAT Library - - `GNAT.Bubble_Sort_G' (`g-busorg.ads') - ===================================== - - Similar to `Bubble_Sort_A' except that the move and sorting procedures - are provided as generic parameters, this improves efficiency, especially - if the procedures can be inlined, at the expense of duplicating code for - multiple instantiations. - -  - File: gnat_rm.info, Node: GNAT.Calendar (g-calend.ads), Next: GNAT.Calendar.Time_IO (g-catiio.ads), Prev: GNAT.Bubble_Sort_G (g-busorg.ads), Up: The GNAT Library - - `GNAT.Calendar' (`g-calend.ads') - ================================ - - Extends the facilities provided by `Ada.Calendar' to include handling - of days of the week, an extended `Split' and `Time_Of' capability. - Also provides conversion of `Ada.Calendar.Time' values to and from the - C `timeval' format. - -  - File: gnat_rm.info, Node: GNAT.Calendar.Time_IO (g-catiio.ads), Next: GNAT.CRC32 (g-crc32.ads), Prev: GNAT.Calendar (g-calend.ads), Up: The GNAT Library - - `GNAT.Calendar.Time_IO' (`g-catiio.ads') - ======================================== - -  - File: gnat_rm.info, Node: GNAT.CRC32 (g-crc32.ads), Next: GNAT.Case_Util (g-casuti.ads), Prev: GNAT.Calendar.Time_IO (g-catiio.ads), Up: The GNAT Library - - `GNAT.CRC32' (`g-crc32.ads') - ============================ - - This package implements the CRC-32 algorithm. For a full description - of this algorithm you should have a look at: "Computation of Cyclic - Redundancy Checks via Table Look-Up", `Communications of the ACM', Vol. - 31 No. 8, pp. 1008-1013, Aug. 1988. Sarwate, D.V. - - Provides an extended capability for formatted output of time values with - full user control over the format. Modeled on the GNU Date - specification. - -  - File: gnat_rm.info, Node: GNAT.Case_Util (g-casuti.ads), Next: GNAT.CGI (g-cgi.ads), Prev: GNAT.CRC32 (g-crc32.ads), Up: The GNAT Library - - `GNAT.Case_Util' (`g-casuti.ads') - ================================= - - A set of simple routines for handling upper and lower casing of strings - without the overhead of the full casing tables in - `Ada.Characters.Handling'. - -  - File: gnat_rm.info, Node: GNAT.CGI (g-cgi.ads), Next: GNAT.CGI.Cookie (g-cgicoo.ads), Prev: GNAT.Case_Util (g-casuti.ads), Up: The GNAT Library - - `GNAT.CGI' (`g-cgi.ads') - ======================== - - This is a package for interfacing a GNAT program with a Web server via - the Common Gateway Interface (CGI). Basically this package parses the - CGI parameters, which are a set of key/value pairs sent by the Web - server. It builds a table whose index is the key and provides some - services to deal with this table. - -  - File: gnat_rm.info, Node: GNAT.CGI.Cookie (g-cgicoo.ads), Next: GNAT.CGI.Debug (g-cgideb.ads), Prev: GNAT.CGI (g-cgi.ads), Up: The GNAT Library - - `GNAT.CGI.Cookie' (`g-cgicoo.ads') - ================================== - - This is a package to interface a GNAT program with a Web server via the - Common Gateway Interface (CGI). It exports services to deal with Web - cookies (piece of information kept in the Web client software). - -  - File: gnat_rm.info, Node: GNAT.CGI.Debug (g-cgideb.ads), Next: GNAT.Command_Line (g-comlin.ads), Prev: GNAT.CGI.Cookie (g-cgicoo.ads), Up: The GNAT Library - - `GNAT.CGI.Debug' (`g-cgideb.ads') - ================================= - - This is a package to help debugging CGI (Common Gateway Interface) - programs written in Ada. - -  - File: gnat_rm.info, Node: GNAT.Command_Line (g-comlin.ads), Next: GNAT.Current_Exception (g-curexc.ads), Prev: GNAT.CGI.Debug (g-cgideb.ads), Up: The GNAT Library - - `GNAT.Command_Line' (`g-comlin.ads') - ==================================== - - Provides a high level interface to `Ada.Command_Line' facilities, - including the ability to scan for named switches with optional - parameters and expand file names using wild card notations. - -  - File: gnat_rm.info, Node: GNAT.Current_Exception (g-curexc.ads), Next: GNAT.Debug_Pools (g-debpoo.ads), Prev: GNAT.Command_Line (g-comlin.ads), Up: The GNAT Library - - `GNAT.Current_Exception' (`g-curexc.ads') - ========================================= - - Provides access to information on the current exception that has been - raised without the need for using the Ada-95 exception choice parameter - specification syntax. This is particularly useful in simulating - typical facilities for obtaining information about exceptions provided - by Ada 83 compilers. - -  - File: gnat_rm.info, Node: GNAT.Debug_Pools (g-debpoo.ads), Next: GNAT.Debug_Utilities (g-debuti.ads), Prev: GNAT.Current_Exception (g-curexc.ads), Up: The GNAT Library - - `GNAT.Debug_Pools' (`g-debpoo.ads') - =================================== - - Provide a debugging storage pools that helps tracking memory corruption - problems. See section "Finding memory problems with GNAT Debug Pool" in - the `GNAT User's Guide'. - -  - File: gnat_rm.info, Node: GNAT.Debug_Utilities (g-debuti.ads), Next: GNAT.Directory_Operations (g-dirope.ads), Prev: GNAT.Debug_Pools (g-debpoo.ads), Up: The GNAT Library - - `GNAT.Debug_Utilities' (`g-debuti.ads') - ======================================= - - Provides a few useful utilities for debugging purposes, including - conversion to and from string images of address values. - -  - File: gnat_rm.info, Node: GNAT.Directory_Operations (g-dirope.ads), Next: GNAT.Dynamic_Tables (g-dyntab.ads), Prev: GNAT.Debug_Utilities (g-debuti.ads), Up: The GNAT Library - - `GNAT.Directory_Operations' (g-dirope.ads) - ========================================== - - Provides a set of routines for manipulating directories, including - changing the current directory, making new directories, and scanning - the files in a directory. - -  - File: gnat_rm.info, Node: GNAT.Dynamic_Tables (g-dyntab.ads), Next: GNAT.Exception_Traces (g-exctra.ads), Prev: GNAT.Directory_Operations (g-dirope.ads), Up: The GNAT Library - - `GNAT.Dynamic_Tables' (`g-dyntab.ads') - ====================================== - - A generic package providing a single dimension array abstraction where - the length of the array can be dynamically modified. - - This package provides a facility similar to that of GNAT.Table, except - that this package declares a type that can be used to define dynamic - instances of the table, while an instantiation of GNAT.Table creates a - single instance of the table type. - -  - File: gnat_rm.info, Node: GNAT.Exception_Traces (g-exctra.ads), Next: GNAT.Expect (g-expect.ads), Prev: GNAT.Dynamic_Tables (g-dyntab.ads), Up: The GNAT Library - - `GNAT.Exception_Traces' (`g-exctra.ads') - ======================================== - - Provides an interface allowing to control automatic output upon - exception occurrences. - -  - File: gnat_rm.info, Node: GNAT.Expect (g-expect.ads), Next: GNAT.Float_Control (g-flocon.ads), Prev: GNAT.Exception_Traces (g-exctra.ads), Up: The GNAT Library - - `GNAT.Expect' (`g-expect.ads') - ============================== - - Provides a set of subprograms similar to what is available with the - standard Tcl Expect tool. It allows you to easily spawn and - communicate with an external process. You can send commands or inputs - to the process, and compare the output with some expected regular - expression. Currently GNAT.Expect is implemented on all native GNAT - ports except for OpenVMS. It is not implemented for cross ports, and - in particular is not implemented for VxWorks or LynxOS. - -  - File: gnat_rm.info, Node: GNAT.Float_Control (g-flocon.ads), Next: GNAT.Heap_Sort_A (g-hesora.ads), Prev: GNAT.Expect (g-expect.ads), Up: The GNAT Library - - `GNAT.Float_Control' (`g-flocon.ads') - ===================================== - - Provides an interface for resetting the floating-point processor into - the mode required for correct semantic operation in Ada. Some third - party library calls may cause this mode to be modified, and the Reset - procedure in this package can be used to reestablish the required mode. - -  - File: gnat_rm.info, Node: GNAT.Heap_Sort_A (g-hesora.ads), Next: GNAT.Heap_Sort_G (g-hesorg.ads), Prev: GNAT.Float_Control (g-flocon.ads), Up: The GNAT Library - - `GNAT.Heap_Sort_A' (`g-hesora.ads') - =================================== - - Provides a general implementation of heap sort usable for sorting - arbitrary data items. Move and comparison procedures are provided by - passing access-to-procedure values. The algorithm used is a modified - heap sort that performs approximately N*log(N) comparisons in the worst - case. - -  - File: gnat_rm.info, Node: GNAT.Heap_Sort_G (g-hesorg.ads), Next: GNAT.HTable (g-htable.ads), Prev: GNAT.Heap_Sort_A (g-hesora.ads), Up: The GNAT Library - - `GNAT.Heap_Sort_G' (`g-hesorg.ads') - =================================== - - Similar to `Heap_Sort_A' except that the move and sorting procedures - are provided as generic parameters, this improves efficiency, especially - if the procedures can be inlined, at the expense of duplicating code for - multiple instantiations. - -  - File: gnat_rm.info, Node: GNAT.HTable (g-htable.ads), Next: GNAT.IO (g-io.ads), Prev: GNAT.Heap_Sort_G (g-hesorg.ads), Up: The GNAT Library - - `GNAT.HTable' (`g-htable.ads') - ============================== - - A generic implementation of hash tables that can be used to hash - arbitrary data. Provides two approaches, one a simple static approach, - and the other allowing arbitrary dynamic hash tables. - -  - File: gnat_rm.info, Node: GNAT.IO (g-io.ads), Next: GNAT.IO_Aux (g-io_aux.ads), Prev: GNAT.HTable (g-htable.ads), Up: The GNAT Library - - `GNAT.IO' (`g-io.ads') - ====================== - - A simple preealborable input-output package that provides a subset of - simple Text_IO functions for reading characters and strings from - Standard_Input, and writing characters, strings and integers to either - Standard_Output or Standard_Error. - -  - File: gnat_rm.info, Node: GNAT.IO_Aux (g-io_aux.ads), Next: GNAT.Lock_Files (g-locfil.ads), Prev: GNAT.IO (g-io.ads), Up: The GNAT Library - - `GNAT.IO_Aux' (`g-io_aux.ads') - ============================== - - Provides some auxiliary functions for use with Text_IO, including a - test for whether a file exists, and functions for reading a line of - text. - -  - File: gnat_rm.info, Node: GNAT.Lock_Files (g-locfil.ads), Next: GNAT.MD5 (g-md5.ads), Prev: GNAT.IO_Aux (g-io_aux.ads), Up: The GNAT Library - - `GNAT.Lock_Files' (`g-locfil.ads') - ================================== - - Provides a general interface for using files as locks. Can be used for - providing program level synchronization. - -  - File: gnat_rm.info, Node: GNAT.MD5 (g-md5.ads), Next: GNAT.Most_Recent_Exception (g-moreex.ads), Prev: GNAT.Lock_Files (g-locfil.ads), Up: The GNAT Library - - `GNAT.MD5' (`g-md5.ads') - ======================== - - Implements the MD5 Message-Digest Algorithm as described in RFC 1321. - -  - File: gnat_rm.info, Node: GNAT.Most_Recent_Exception (g-moreex.ads), Next: GNAT.OS_Lib (g-os_lib.ads), Prev: GNAT.MD5 (g-md5.ads), Up: The GNAT Library - - `GNAT.Most_Recent_Exception' (`g-moreex.ads') - ============================================= - - Provides access to the most recently raised exception. Can be used for - various logging purposes, including duplicating functionality of some - Ada 83 implementation dependent extensions. - -  - File: gnat_rm.info, Node: GNAT.OS_Lib (g-os_lib.ads), Next: GNAT.Regexp (g-regexp.ads), Prev: GNAT.Most_Recent_Exception (g-moreex.ads), Up: The GNAT Library - - `GNAT.OS_Lib' (`g-os_lib.ads') - ============================== - - Provides a range of target independent operating system interface - functions, including time/date management, file operations, subprocess - management, including a portable spawn procedure, and access to - environment variables and error return codes. - -  - File: gnat_rm.info, Node: GNAT.Regexp (g-regexp.ads), Next: GNAT.Registry (g-regist.ads), Prev: GNAT.OS_Lib (g-os_lib.ads), Up: The GNAT Library - - `GNAT.Regexp' (`g-regexp.ads') - ============================== - - A simple implementation of regular expressions, using a subset of - regular expression syntax copied from familiar Unix style utilities. - This is the simples of the three pattern matching packages provided, - and is particularly suitable for "file globbing" applications. - -  - File: gnat_rm.info, Node: GNAT.Registry (g-regist.ads), Next: GNAT.Regpat (g-regpat.ads), Prev: GNAT.Regexp (g-regexp.ads), Up: The GNAT Library - - `GNAT.Registry' (`g-regist.ads') - ================================ - - This is a high level binding to the Windows registry. It is possible to - do simple things like reading a key value, creating a new key. For full - registry API, but at a lower level of abstraction, refer to the - Win32.Winreg package provided with the Win32Ada binding - -  - File: gnat_rm.info, Node: GNAT.Regpat (g-regpat.ads), Next: GNAT.Sockets (g-socket.ads), Prev: GNAT.Registry (g-regist.ads), Up: The GNAT Library - - `GNAT.Regpat' (`g-regpat.ads') - ============================== - - A complete implementation of Unix-style regular expression matching, - copied from the original V7 style regular expression library written in - C by Henry Spencer (and binary compatible with this C library). - -  - File: gnat_rm.info, Node: GNAT.Sockets (g-socket.ads), Next: GNAT.Source_Info (g-souinf.ads), Prev: GNAT.Regpat (g-regpat.ads), Up: The GNAT Library - - `GNAT.Sockets' (`g-socket.ads') - =============================== - - A high level and portable interface to develop sockets based - applications. This package is based on the sockets thin binding found - in GNAT.Sockets.Thin. Currently GNAT.Sockets is implemented on all - native GNAT ports except for OpenVMS. It is not implemented for the - LynxOS cross port. - -  - File: gnat_rm.info, Node: GNAT.Source_Info (g-souinf.ads), Next: GNAT.Spell_Checker (g-speche.ads), Prev: GNAT.Sockets (g-socket.ads), Up: The GNAT Library - - `GNAT.Source_Info' (`g-souinf.ads') - =================================== - - Provides subprograms that give access to source code information known - at compile time, such as the current file name and line number. - -  - File: gnat_rm.info, Node: GNAT.Spell_Checker (g-speche.ads), Next: GNAT.Spitbol.Patterns (g-spipat.ads), Prev: GNAT.Source_Info (g-souinf.ads), Up: The GNAT Library - - `GNAT.Spell_Checker' (`g-speche.ads') - ===================================== - - Provides a function for determining whether one string is a plausible - near misspelling of another string. - -  - File: gnat_rm.info, Node: GNAT.Spitbol.Patterns (g-spipat.ads), Next: GNAT.Spitbol (g-spitbo.ads), Prev: GNAT.Spell_Checker (g-speche.ads), Up: The GNAT Library - - `GNAT.Spitbol.Patterns' (`g-spipat.ads') - ======================================== - - A complete implementation of SNOBOL4 style pattern matching. This is - the most elaborate of the pattern matching packages provided. It fully - duplicates the SNOBOL4 dynamic pattern construction and matching - capabilities, using the efficient algorithm developed by Robert Dewar - for the SPITBOL system. - -  - File: gnat_rm.info, Node: GNAT.Spitbol (g-spitbo.ads), Next: GNAT.Spitbol.Table_Boolean (g-sptabo.ads), Prev: GNAT.Spitbol.Patterns (g-spipat.ads), Up: The GNAT Library - - `GNAT.Spitbol' (`g-spitbo.ads') - =============================== - - The top level package of the collection of SPITBOL-style functionality, - this package provides basic SNOBOL4 string manipulation functions, such - as Pad, Reverse, Trim, Substr capability, as well as a generic table - function useful for constructing arbitrary mappings from strings in the - style of the SNOBOL4 TABLE function. - -  - File: gnat_rm.info, Node: GNAT.Spitbol.Table_Boolean (g-sptabo.ads), Next: GNAT.Spitbol.Table_Integer (g-sptain.ads), Prev: GNAT.Spitbol (g-spitbo.ads), Up: The GNAT Library - - `GNAT.Spitbol.Table_Boolean' (`g-sptabo.ads') - ============================================= - - A library level of instantiation of `GNAT.Spitbol.Patterns.Table' for - type `Standard.Boolean', giving an implementation of sets of string - values. - -  - File: gnat_rm.info, Node: GNAT.Spitbol.Table_Integer (g-sptain.ads), Next: GNAT.Spitbol.Table_VString (g-sptavs.ads), Prev: GNAT.Spitbol.Table_Boolean (g-sptabo.ads), Up: The GNAT Library - - `GNAT.Spitbol.Table_Integer' (`g-sptain.ads') - ============================================= - - A library level of instantiation of `GNAT.Spitbol.Patterns.Table' for - type `Standard.Integer', giving an implementation of maps from string - to integer values. - -  - File: gnat_rm.info, Node: GNAT.Spitbol.Table_VString (g-sptavs.ads), Next: GNAT.Table (g-table.ads), Prev: GNAT.Spitbol.Table_Integer (g-sptain.ads), Up: The GNAT Library - - `GNAT.Spitbol.Table_VString' (`g-sptavs.ads') - ============================================= - - A library level of instantiation of GNAT.Spitbol.Patterns.Table for a - variable length string type, giving an implementation of general maps - from strings to strings. - -  - File: gnat_rm.info, Node: GNAT.Table (g-table.ads), Next: GNAT.Task_Lock (g-tasloc.ads), Prev: GNAT.Spitbol.Table_VString (g-sptavs.ads), Up: The GNAT Library - - `GNAT.Table' (`g-table.ads') - ============================ - - A generic package providing a single dimension array abstraction where - the length of the array can be dynamically modified. - - This package provides a facility similar to that of GNAT.Dynamic_Tables, - except that this package declares a single instance of the table type, - while an instantiation of GNAT.Dynamic_Tables creates a type that can be - used to define dynamic instances of the table. - -  - File: gnat_rm.info, Node: GNAT.Task_Lock (g-tasloc.ads), Next: GNAT.Threads (g-thread.ads), Prev: GNAT.Table (g-table.ads), Up: The GNAT Library - - `GNAT.Task_Lock' (`g-tasloc.ads') - ================================= - - A very simple facility for locking and unlocking sections of code using - a single global task lock. Appropriate for use in situations where - contention between tasks is very rarely expected. - -  - File: gnat_rm.info, Node: GNAT.Threads (g-thread.ads), Next: GNAT.Traceback (g-traceb.ads), Prev: GNAT.Task_Lock (g-tasloc.ads), Up: The GNAT Library - - `GNAT.Threads' (`g-thread.ads') - =============================== - - Provides facilities for creating and destroying threads with explicit - calls. These threads are known to the GNAT run-time system. These - subprograms are exported C-convention procedures intended to be called - from foreign code. By using these primitives rather than directly - calling operating systems routines, compatibility with the Ada tasking - runt-time is provided. - -  - File: gnat_rm.info, Node: GNAT.Traceback (g-traceb.ads), Next: GNAT.Traceback.Symbolic (g-trasym.ads), Prev: GNAT.Threads (g-thread.ads), Up: The GNAT Library - - `GNAT.Traceback' (`g-traceb.ads') - ================================= - - Provides a facility for obtaining non-symbolic traceback information, - useful in various debugging situations. - -  - File: gnat_rm.info, Node: GNAT.Traceback.Symbolic (g-trasym.ads), Next: Interfaces.C.Extensions (i-cexten.ads), Prev: GNAT.Traceback (g-traceb.ads), Up: The GNAT Library - - `GNAT.Traceback.Symbolic' (`g-trasym.ads') - ========================================== - - Provides symbolic traceback information that includes the subprogram - name and line number information. - -  - File: gnat_rm.info, Node: Interfaces.C.Extensions (i-cexten.ads), Next: Interfaces.C.Streams (i-cstrea.ads), Prev: GNAT.Traceback.Symbolic (g-trasym.ads), Up: The GNAT Library - - `Interfaces.C.Extensions' (`i-cexten.ads') - ========================================== - - This package contains additional C-related definitions, intended for - use with either manually or automatically generated bindings to C - libraries. - -  - File: gnat_rm.info, Node: Interfaces.C.Streams (i-cstrea.ads), Next: Interfaces.CPP (i-cpp.ads), Prev: Interfaces.C.Extensions (i-cexten.ads), Up: The GNAT Library - - `Interfaces.C.Streams' (`i-cstrea.ads') - ======================================= - - This package is a binding for the most commonly used operations on C - streams. - -  - File: gnat_rm.info, Node: Interfaces.CPP (i-cpp.ads), Next: Interfaces.Os2lib (i-os2lib.ads), Prev: Interfaces.C.Streams (i-cstrea.ads), Up: The GNAT Library - - `Interfaces.CPP' (`i-cpp.ads') - ============================== - - This package provides facilities for use in interfacing to C++. It is - primarily intended to be used in connection with automated tools for - the generation of C++ interfaces. - -  - File: gnat_rm.info, Node: Interfaces.Os2lib (i-os2lib.ads), Next: Interfaces.Os2lib.Errors (i-os2err.ads), Prev: Interfaces.CPP (i-cpp.ads), Up: The GNAT Library - - `Interfaces.Os2lib' (`i-os2lib.ads') - ==================================== - - This package provides interface definitions to the OS/2 library. It is - a thin binding which is a direct translation of the various `' - files. - -  - File: gnat_rm.info, Node: Interfaces.Os2lib.Errors (i-os2err.ads), Next: Interfaces.Os2lib.Synchronization (i-os2syn.ads), Prev: Interfaces.Os2lib (i-os2lib.ads), Up: The GNAT Library - - `Interfaces.Os2lib.Errors' (`i-os2err.ads') - =========================================== - - This package provides definitions of the OS/2 error codes. - -  - File: gnat_rm.info, Node: Interfaces.Os2lib.Synchronization (i-os2syn.ads), Next: Interfaces.Os2lib.Threads (i-os2thr.ads), Prev: Interfaces.Os2lib.Errors (i-os2err.ads), Up: The GNAT Library - - `Interfaces.Os2lib.Synchronization' (`i-os2syn.ads') - ==================================================== - - This is a child package that provides definitions for interfacing to - the `OS/2' synchronization primitives. - -  - File: gnat_rm.info, Node: Interfaces.Os2lib.Threads (i-os2thr.ads), Next: Interfaces.Packed_Decimal (i-pacdec.ads), Prev: Interfaces.Os2lib.Synchronization (i-os2syn.ads), Up: The GNAT Library - - `Interfaces.Os2lib.Threads' (`i-os2thr.ads') - ============================================ - - This is a child package that provides definitions for interfacing to - the `OS/2' thread primitives. - -  - File: gnat_rm.info, Node: Interfaces.Packed_Decimal (i-pacdec.ads), Next: Interfaces.VxWorks (i-vxwork.ads), Prev: Interfaces.Os2lib.Threads (i-os2thr.ads), Up: The GNAT Library - - `Interfaces.Packed_Decimal' (`i-pacdec.ads') - ============================================ - - This package provides a set of routines for conversions to and from a - packed decimal format compatible with that used on IBM mainframes. - -  - File: gnat_rm.info, Node: Interfaces.VxWorks (i-vxwork.ads), Next: Interfaces.VxWorks.IO (i-vxwoio.ads), Prev: Interfaces.Packed_Decimal (i-pacdec.ads), Up: The GNAT Library - - `Interfaces.VxWorks' (`i-vxwork.ads') - ===================================== - - This package provides a limited binding to the VxWorks API. In - particular, it interfaces with the VxWorks hardware interrupt - facilities. - -  - File: gnat_rm.info, Node: Interfaces.VxWorks.IO (i-vxwoio.ads), Next: System.Address_Image (s-addima.ads), Prev: Interfaces.VxWorks (i-vxwork.ads), Up: The GNAT Library - - `Interfaces.VxWorks.IO' (`i-vxwoio.ads') - ======================================== - - This package provides a limited binding to the VxWorks' I/O API. In - particular, it provides procedures that enable the use of Get_Immediate - under VxWorks. - -  - File: gnat_rm.info, Node: System.Address_Image (s-addima.ads), Next: System.Assertions (s-assert.ads), Prev: Interfaces.VxWorks.IO (i-vxwoio.ads), Up: The GNAT Library - - `System.Address_Image' (`s-addima.ads') - ======================================= - - This function provides a useful debugging function that gives an - (implementation dependent) string which identifies an address. - -  - File: gnat_rm.info, Node: System.Assertions (s-assert.ads), Next: System.Partition_Interface (s-parint.ads), Prev: System.Address_Image (s-addima.ads), Up: The GNAT Library - - `System.Assertions' (`s-assert.ads') - ==================================== - - This package provides the declaration of the exception raised by an - run-time assertion failure, as well as the routine that is used - internally to raise this assertion. - -  - File: gnat_rm.info, Node: System.Partition_Interface (s-parint.ads), Next: System.Task_Info (s-tasinf.ads), Prev: System.Assertions (s-assert.ads), Up: The GNAT Library - - `System.Partition_Interface' (`s-parint.ads') - ============================================= - - This package provides facilities for partition interfacing. It is used - primarily in a distribution context when using Annex E with `GLADE'. - -  - File: gnat_rm.info, Node: System.Task_Info (s-tasinf.ads), Next: System.Wch_Cnv (s-wchcnv.ads), Prev: System.Partition_Interface (s-parint.ads), Up: The GNAT Library - - `System.Task_Info' (`s-tasinf.ads') - =================================== - - This package provides target dependent functionality that is used to - support the `Task_Info' pragma - -  - File: gnat_rm.info, Node: System.Wch_Cnv (s-wchcnv.ads), Next: System.Wch_Con (s-wchcon.ads), Prev: System.Task_Info (s-tasinf.ads), Up: The GNAT Library - - `System.Wch_Cnv' (`s-wchcnv.ads') - ================================= - - This package provides routines for converting between wide characters - and a representation as a value of type `Standard.String', using a - specified wide character encoding method. It uses definitions in - package `System.Wch_Con'. - -  - File: gnat_rm.info, Node: System.Wch_Con (s-wchcon.ads), Prev: System.Wch_Cnv (s-wchcnv.ads), Up: The GNAT Library - - `System.Wch_Con' (`s-wchcon.ads') - ================================= - - This package provides definitions and descriptions of the various - methods used for encoding wide characters in ordinary strings. These - definitions are used by the package `System.Wch_Cnv'. - -  - File: gnat_rm.info, Node: Interfacing to Other Languages, Next: Machine Code Insertions, Prev: The GNAT Library, Up: Top - - Interfacing to Other Languages - ****************************** - - The facilities in annex B of the Ada 95 Reference Manual are fully - implemented in GNAT, and in addition, a full interface to C++ is - provided. - - * Menu: - - * Interfacing to C:: - * Interfacing to C++:: - * Interfacing to COBOL:: - * Interfacing to Fortran:: - * Interfacing to non-GNAT Ada code:: - -  - File: gnat_rm.info, Node: Interfacing to C, Next: Interfacing to C++, Up: Interfacing to Other Languages - - Interfacing to C - ================ - - Interfacing to C with GNAT can use one of two approaches: - - 1. The types in the package `Interfaces.C' may be used. - - 2. Standard Ada types may be used directly. This may be less - portable to other compilers, but will work on all GNAT compilers, - which guarantee correspondence between the C and Ada types. - - Pragma `Convention C' maybe applied to Ada types, but mostly has no - effect, since this is the default. The following table shows the - correspondence between Ada scalar types and the corresponding C types. - - `Integer' - `int' - - `Short_Integer' - `short' - - `Short_Short_Integer' - `signed char' - - `Long_Integer' - `long' - - `Long_Long_Integer' - `long long' - - `Short_Float' - `float' - - `Float' - `float' - - `Long_Float' - `double' - - `Long_Long_Float' - This is the longest floating-point type supported by the hardware. - - * Ada enumeration types map to C enumeration types directly if pragma - `Convention C' is specified, which causes them to have int length. - Without pragma `Convention C', Ada enumeration types map to 8, - 16, or 32 bits (i.e. C types `signed char', `short', `int', - respectively) depending on the number of values passed. This is - the only case in which pragma `Convention C' affects the - representation of an Ada type. - - * Ada access types map to C pointers, except for the case of - pointers to unconstrained types in Ada, which have no direct C - equivalent. - - * Ada arrays map directly to C arrays. - - * Ada records map directly to C structures. - - * Packed Ada records map to C structures where all members are bit - fields of the length corresponding to the `TYPE'Size' value in Ada. - -  - File: gnat_rm.info, Node: Interfacing to C++, Next: Interfacing to COBOL, Prev: Interfacing to C, Up: Interfacing to Other Languages - - Interfacing to C++ - ================== - - The interface to C++ makes use of the following pragmas, which are - primarily intended to be constructed automatically using a binding - generator tool, although it is possible to construct them by hand. No - suitable binding generator tool is supplied with GNAT though. - - Using these pragmas it is possible to achieve complete - inter-operability between Ada tagged types and C class definitions. - See *Note Implementation Defined Pragmas:: for more details. - - `pragma CPP_Class ([Entity =>] LOCAL_NAME)' - The argument denotes an entity in the current declarative region - that is declared as a tagged or untagged record type. It - indicates that the type corresponds to an externally declared C++ - class type, and is to be laid out the same way that C++ would lay - out the type. - - `pragma CPP_Constructor ([Entity =>] LOCAL_NAME)' - This pragma identifies an imported function (imported in the usual - way with pragma `Import') as corresponding to a C++ constructor. - - `pragma CPP_Vtable ...' - One `CPP_Vtable' pragma can be present for each component of type - `CPP.Interfaces.Vtable_Ptr' in a record to which pragma `CPP_Class' - applies. - -  - File: gnat_rm.info, Node: Interfacing to COBOL, Next: Interfacing to Fortran, Prev: Interfacing to C++, Up: Interfacing to Other Languages - - Interfacing to COBOL - ==================== - - Interfacing to COBOL is achieved as described in section B.4 of the Ada - 95 reference manual. - -  - File: gnat_rm.info, Node: Interfacing to Fortran, Next: Interfacing to non-GNAT Ada code, Prev: Interfacing to COBOL, Up: Interfacing to Other Languages - - Interfacing to Fortran - ====================== - - Interfacing to Fortran is achieved as described in section B.5 of the - reference manual. The pragma `Convention Fortran', applied to a - multi-dimensional array causes the array to be stored in column-major - order as required for convenient interface to Fortran. - -  - File: gnat_rm.info, Node: Interfacing to non-GNAT Ada code, Prev: Interfacing to Fortran, Up: Interfacing to Other Languages - - Interfacing to non-GNAT Ada code - ================================ - - It is possible to specify the convention `Ada' in a pragma `Import' - or pragma `Export'. However this refers to the calling conventions used - by GNAT, which may or may not be similar enough to those used by some - other Ada 83 or Ada 95 compiler to allow interoperation. - - If arguments types are kept simple, and if the foreign compiler - generally follows system calling conventions, then it may be possible - to integrate files compiled by other Ada compilers, provided that the - elaboration issues are adequately addressed (for example by eliminating - the need for any load time elaboration). - - In particular, GNAT running on VMS is designed to be highly - compatible with the DEC Ada 83 compiler, so this is one case in which - it is possible to import foreign units of this type, provided that the - data items passed are restricted to simple scalar values or simple - record types without variants, or simple array types with fixed bounds. - -  - File: gnat_rm.info, Node: Machine Code Insertions, Next: GNAT Implementation of Tasking, Prev: Interfacing to Other Languages, Up: Top - - Machine Code Insertions - *********************** - - Package `Machine_Code' provides machine code support as described in - the Ada 95 Reference Manual in two separate forms: - * Machine code statements, consisting of qualified expressions that - fit the requirements of RM section 13.8. - - * An intrinsic callable procedure, providing an alternative - mechanism of including machine instructions in a subprogram. - - The two features are similar, and both closely related to the - mechanism provided by the asm instruction in the GNU C compiler. Full - understanding and use of the facilities in this package requires - understanding the asm instruction as described in `Using and Porting - the GNU Compiler Collection (GCC)' by Richard Stallman. Calls to the - function `Asm' and the procedure `Asm' have identical semantic - restrictions and effects as described below. Both are provided so that - the procedure call can be used as a statement, and the function call - can be used to form a code_statement. - - The first example given in the GCC documentation is the C `asm' - instruction: - asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); - - The equivalent can be written for GNAT as: - - Asm ("fsinx %1 %0", - My_Float'Asm_Output ("=f", result), - My_Float'Asm_Input ("f", angle)); - - The first argument to `Asm' is the assembler template, and is - identical to what is used in GNU C. This string must be a static - expression. The second argument is the output operand list. It is - either a single `Asm_Output' attribute reference, or a list of such - references enclosed in parentheses (technically an array aggregate of - such references). - - The `Asm_Output' attribute denotes a function that takes two - parameters. The first is a string, the second is the name of a variable - of the type designated by the attribute prefix. The first (string) - argument is required to be a static expression and designates the - constraint for the parameter (e.g. what kind of register is required). - The second argument is the variable to be updated with the result. The - possible values for constraint are the same as those used in the RTL, - and are dependent on the configuration file used to build the GCC back - end. If there are no output operands, then this argument may either be - omitted, or explicitly given as `No_Output_Operands'. - - The second argument of `MY_FLOAT'Asm_Output' functions as though it - were an `out' parameter, which is a little curious, but all names have - the form of expressions, so there is no syntactic irregularity, even - though normally functions would not be permitted `out' parameters. The - third argument is the list of input operands. It is either a single - `Asm_Input' attribute reference, or a list of such references enclosed - in parentheses (technically an array aggregate of such references). - - The `Asm_Input' attribute denotes a function that takes two - parameters. The first is a string, the second is an expression of the - type designated by the prefix. The first (string) argument is required - to be a static expression, and is the constraint for the parameter, - (e.g. what kind of register is required). The second argument is the - value to be used as the input argument. The possible values for the - constant are the same as those used in the RTL, and are dependent on - the configuration file used to built the GCC back end. - - If there are no input operands, this argument may either be omitted, - or explicitly given as `No_Input_Operands'. The fourth argument, not - present in the above example, is a list of register names, called the - "clobber" argument. This argument, if given, must be a static string - expression, and is a space or comma separated list of names of registers - that must be considered destroyed as a result of the `Asm' call. If - this argument is the null string (the default value), then the code - generator assumes that no additional registers are destroyed. - - The fifth argument, not present in the above example, called the - "volatile" argument, is by default `False'. It can be set to the - literal value `True' to indicate to the code generator that all - optimizations with respect to the instruction specified should be - suppressed, and that in particular, for an instruction that has outputs, - the instruction will still be generated, even if none of the outputs are - used. See the full description in the GCC manual for further details. - - The `Asm' subprograms may be used in two ways. First the procedure - forms can be used anywhere a procedure call would be valid, and - correspond to what the RM calls "intrinsic" routines. Such calls can - be used to intersperse machine instructions with other Ada statements. - Second, the function forms, which return a dummy value of the limited - private type `Asm_Insn', can be used in code statements, and indeed - this is the only context where such calls are allowed. Code statements - appear as aggregates of the form: - - Asm_Insn'(Asm (...)); - Asm_Insn'(Asm_Volatile (...)); - - In accordance with RM rules, such code statements are allowed only - within subprograms whose entire body consists of such statements. It is - not permissible to intermix such statements with other Ada statements. - - Typically the form using intrinsic procedure calls is more convenient - and more flexible. The code statement form is provided to meet the RM - suggestion that such a facility should be made available. The following - is the exact syntax of the call to `Asm' (of course if named notation is - used, the arguments may be given in arbitrary order, following the - normal rules for use of positional and named arguments) - - ASM_CALL ::= Asm ( - [Template =>] static_string_EXPRESSION - [,[Outputs =>] OUTPUT_OPERAND_LIST ] - [,[Inputs =>] INPUT_OPERAND_LIST ] - [,[Clobber =>] static_string_EXPRESSION ] - [,[Volatile =>] static_boolean_EXPRESSION] ) - OUTPUT_OPERAND_LIST ::= - No_Output_Operands - | OUTPUT_OPERAND_ATTRIBUTE - | (OUTPUT_OPERAND_ATTRIBUTE {,OUTPUT_OPERAND_ATTRIBUTE}) - OUTPUT_OPERAND_ATTRIBUTE ::= - SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) - INPUT_OPERAND_LIST ::= - No_Input_Operands - | INPUT_OPERAND_ATTRIBUTE - | (INPUT_OPERAND_ATTRIBUTE {,INPUT_OPERAND_ATTRIBUTE}) - INPUT_OPERAND_ATTRIBUTE ::= - SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) - -  - File: gnat_rm.info, Node: GNAT Implementation of Tasking, Next: Code generation for array aggregates, Prev: Machine Code Insertions, Up: Top - - GNAT Implementation of Tasking - ****************************** - - * Menu: - - * Mapping Ada Tasks onto the Underlying Kernel Threads:: - * Ensuring Compliance with the Real-Time Annex:: - -  - File: gnat_rm.info, Node: Mapping Ada Tasks onto the Underlying Kernel Threads, Next: Ensuring Compliance with the Real-Time Annex, Up: GNAT Implementation of Tasking - - Mapping Ada Tasks onto the Underlying Kernel Threads - ==================================================== - - GNAT run-time system comprises two layers: - - * GNARL (GNAT Run-time Layer) - - * GNULL (GNAT Low-level Library) - - In GNAT, Ada's tasking services rely on a platform and OS independent - layer known as GNARL. This code is responsible for implementing the - correct semantics of Ada's task creation, rendezvous, protected - operations etc. - - GNARL decomposes Ada's tasking semantics into simpler lower level - operations such as create a thread, set the priority of a thread, - yield, create a lock, lock/unlock, etc. The spec for these low-level - operations constitutes GNULLI, the GNULL Interface. This interface is - directly inspired from the POSIX real-time API. - - If the underlying executive or OS implements the POSIX standard - faithfully, the GNULL Interface maps as is to the services offered by - the underlying kernel. Otherwise, some target dependent glue code maps - the services offered by the underlying kernel to the semantics expected - by GNARL. - - Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) - the key point is that each Ada task is mapped on a thread in the - underlying kernel. For example, in the case of VxWorks, one Ada task = - one VxWorks task. - - In addition Ada task priorities map onto the underlying thread - priorities. Mapping Ada tasks onto the underlying kernel threads has - several advantages: - - 1. The underlying scheduler is used to schedule the Ada tasks. This - makes Ada tasks as efficient as kernel threads from a scheduling - standpoint. - - 2. Interaction with code written in C containing threads is eased - since at the lowest level Ada tasks and C threads map onto the same - underlying kernel concept. - - 3. When an Ada task is blocked during I/O the remaining Ada tasks are - able to proceed. - - 4. On multi-processor systems Ada Tasks can execute in parallel. - -  - File: gnat_rm.info, Node: Ensuring Compliance with the Real-Time Annex, Prev: Mapping Ada Tasks onto the Underlying Kernel Threads, Up: GNAT Implementation of Tasking - - Ensuring Compliance with the Real-Time Annex - ============================================ - - The reader will be quick to notice that while mapping Ada tasks onto - the underlying threads has significant advantages, it does create some - complications when it comes to respecting the scheduling semantics - specified in the real-time annex (Annex D). - - For instance Annex D requires that for the FIFO_Within_Priorities - scheduling policy we have: - - When the active priority of a ready task that is not running - changes, or the setting of its base priority takes effect, the - task is removed from the ready queue for its old active priority - and is added at the tail of the ready queue for its new active - priority, except in the case where the active priority is lowered - due to the loss of inherited priority, in which case the task is - added at the head of the ready queue for its new active priority. - - While most kernels do put tasks at the end of the priority queue when - a task changes its priority, (which respects the main - FIFO_Within_Priorities requirement), almost none keep a thread at the - beginning of its priority queue when its priority drops from the loss - of inherited priority. - - As a result most vendors have provided incomplete Annex D - implementations. - - The GNAT run-time, has a nice cooperative solution to this problem - which ensures that accurate FIFO_Within_Priorities semantics are - respected. - - The principle is as follows. When an Ada task T is about to start - running, it checks whether some other Ada task R with the same priority - as T has been suspended due to the loss of priority inheritance. If - this is the case, T yields and is placed at the end of its priority - queue. When R arrives at the front of the queue it executes. - - Note that this simple scheme preserves the relative order of the - tasks that were ready to execute in the priority queue where R has been - placed at the end. - -  - File: gnat_rm.info, Node: Code generation for array aggregates, Next: Specialized Needs Annexes, Prev: GNAT Implementation of Tasking, Up: Top - - Code generation for array aggregates - ************************************ - - * Menu: - - * Static constant aggregates with static bounds:: - * Constant aggregates with an unconstrained nominal types:: - * Aggregates with static bounds:: - * Aggregates with non-static bounds:: - * Aggregates in assignments statements:: - - Aggregate have a rich syntax and allow the user to specify the - values of complex data structures by means of a single construct. As a - result, the code generated for aggregates can be quite complex and - involve loops, case statements and multiple assignments. In the - simplest cases, however, the compiler will recognize aggregates whose - components and constraints are fully static, and in those cases the - compiler will generate little or no executable code. The following is - an outline of the code that GNAT generates for various aggregate - constructs. For further details, the user will find it useful to - examine the output produced by the -gnatG flag to see the expanded - source that is input to the code generator. The user will also want to - examine the assembly code generated at various levels of optimization. - - The code generated for aggregates depends on the context, the - component values, and the type. In the context of an object - declaration the code generated is generally simpler than in the case of - an assignment. As a general rule, static component values and static - subtypes also lead to simpler code. - -  - File: gnat_rm.info, Node: Static constant aggregates with static bounds, Next: Constant aggregates with an unconstrained nominal types, Up: Code generation for array aggregates - - Static constant aggregates with static bounds - ============================================= - - For the declarations: - type One_Dim is array (1..10) of integer; - ar0 : constant One_Dim := ( 1, 2, 3, 4, 5, 6, 7, 8, 9, 0); - - GNAT generates no executable code: the constant ar0 is placed in - static memory. The same is true for constant aggregates with named - associations: - - Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1=> 1); - Cr3 : constant One_Dim := (others => 7777); - - The same is true for multidimensional constant arrays such as: - - type two_dim is array (1..3, 1..3) of integer; - Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); - - The same is true for arrays of one-dimensional arrays: the following - are static: - - type ar1b is array (1..3) of boolean; - type ar_ar is array (1..3) of ar1b; - None : constant ar1b := (others => false); -- fully static - None2 : constant ar_ar := (1..3 => None); -- fully static - - However, for multidimensional aggregates with named associations, - GNAT will generate assignments and loops, even if all associations are - static. The following two declarations generate a loop for the first - dimension, and individual component assignments for the second - dimension: - - Zero1: constant two_dim := (1..3 => (1..3 => 0)); - Zero2: constant two_dim := (others => (others => 0)); - -  - File: gnat_rm.info, Node: Constant aggregates with an unconstrained nominal types, Next: Aggregates with static bounds, Prev: Static constant aggregates with static bounds, Up: Code generation for array aggregates - - Constant aggregates with an unconstrained nominal types - ======================================================= - - In such cases the aggregate itself establishes the subtype, so that - associations with `others' cannot be used. GNAT determines the bounds - for the actual subtype of the aggregate, and allocates the aggregate - statically as well. No code is generated for the following: - - type One_Unc is array (natural range <>) of integer; - Cr_Unc : constant One_Unc := (12,24,36); - -  - File: gnat_rm.info, Node: Aggregates with static bounds, Next: Aggregates with non-static bounds, Prev: Constant aggregates with an unconstrained nominal types, Up: Code generation for array aggregates - - Aggregates with static bounds - ============================= - - In all previous examples the aggregate was the initial (and - immutable) value of a constant. If the aggregate initializes a - variable, then code is generated for it as a combination of individual - assignments and loops over the target object. The declarations - - Cr_Var1 : One_Dim := (2, 5, 7, 11); - Cr_Var2 : One_Dim := (others > -1); - - generate the equivalent of - - Cr_Var1 (1) := 2; - Cr_Var1 (2) := 3; - Cr_Var1 (3) := 5; - Cr_Var1 (4) := 11; - - for I in Cr_Var2'range loop - Cr_Var2 (I) := =-1; - end loop; - -  - File: gnat_rm.info, Node: Aggregates with non-static bounds, Next: Aggregates in assignments statements, Prev: Aggregates with static bounds, Up: Code generation for array aggregates - - Aggregates with non-static bounds - ================================= - - If the bounds of the aggregate are not statically compatible with - the bounds of the nominal subtype of the target, then constraint - checks have to be generated on the bounds. For a multidimensional - array, constraint checks may have to be applied to sub-arrays - individually, if they do not have statically compatible subtypes. - -  - File: gnat_rm.info, Node: Aggregates in assignments statements, Prev: Aggregates with non-static bounds, Up: Code generation for array aggregates - - Aggregates in assignments statements - ==================================== - - In general, aggregate assignment requires the construction of a - temporary, and a copy from the temporary to the target of the - assignment. This is because it is not always possible to convert the - assignment into a series of individual component assignments. For - example, consider the simple case: - - A := (A(2), A(1)); - - This cannot be converted into: - - A(1) := A(2); - A(2) := A(1); - - So the aggregate has to be built first in a separate location, and - then copied into the target. GNAT recognizes simple cases where this - intermediate step is not required, and the assignments can be performed - in place, directly into the target. The following sufficient criteria - are applied: - - 1. The bounds of the aggregate are static, and the associations are - static. - - 2. The components of the aggregate are static constants, names of - simple variables that are not renamings, or expressions not - involving indexed components whose operands obey these rules. - - If any of these conditions are violated, the aggregate will be built - in a temporary (created either by the front-end or the code generator) - and then that temporary will be copied onto the target. - -  - File: gnat_rm.info, Node: Specialized Needs Annexes, Next: Compatibility Guide, Prev: Code generation for array aggregates, Up: Top - - Specialized Needs Annexes - ************************* - - Ada 95 defines a number of specialized needs annexes, which are not - required in all implementations. However, as described in this chapter, - GNAT implements all of these special needs annexes: - - Systems Programming (Annex C) - The Systems Programming Annex is fully implemented. - - Real-Time Systems (Annex D) - The Real-Time Systems Annex is fully implemented. - - Distributed Systems (Annex E) - Stub generation is fully implemented in the GNAT compiler. In - addition, a complete compatible PCS is available as part of the - GLADE system, a separate product. When the two products are used - in conjunction, this annex is fully implemented. - - Information Systems (Annex F) - The Information Systems annex is fully implemented. - - Numerics (Annex G) - The Numerics Annex is fully implemented. - - Safety and Security (Annex H) - The Safety and Security annex is fully implemented. - -  - File: gnat_rm.info, Node: Compatibility Guide, Next: GNU Free Documentation License, Prev: Specialized Needs Annexes, Up: Top - - Compatibility Guide - ******************* - - This chapter contains sections that describe compatibility issues - between GNAT and other Ada 83 and Ada 95 compilation systems, to aid in - porting applications developed in other Ada environments. - - * Menu: - - * Compatibility with Ada 83:: - * Compatibility with DEC Ada 83:: - * Compatibility with Other Ada 95 Systems:: - * Representation Clauses:: - -  - File: gnat_rm.info, Node: Compatibility with Ada 83, Next: Compatibility with DEC Ada 83, Up: Compatibility Guide - - Compatibility with Ada 83 - ========================= - - Ada 95 is designed to be highly upwards compatible with Ada 83. In - particular, the design intention is that the difficulties associated - with moving from Ada 83 to Ada 95 should be no greater than those that - occur when moving from one Ada 83 system to another. - - However, there are a number of points at which there are minor - incompatibilities. The Ada 95 Annotated Reference Manual contains full - details of these issues, and should be consulted for a complete - treatment. In practice the following are the most likely issues to be - encountered. - - Character range - The range of `Standard.Character' is now the full 256 characters - of Latin-1, whereas in most Ada 83 implementations it was - restricted to 128 characters. This may show up as compile time or - runtime errors. The desirable fix is to adapt the program to - accommodate the full character set, but in some cases it may be - convenient to define a subtype or derived type of Character that - covers only the restricted range. - - New reserved words - The identifiers `abstract', `aliased', `protected', `requeue', - `tagged', and `until' are reserved in Ada 95. Existing Ada 83 - code using any of these identifiers must be edited to use some - alternative name. - - Freezing rules - The rules in Ada 95 are slightly different with regard to the - point at which entities are frozen, and representation pragmas and - clauses are not permitted past the freeze point. This shows up - most typically in the form of an error message complaining that a - representation item appears too late, and the appropriate - corrective action is to move the item nearer to the declaration of - the entity to which it refers. - - A particular case is that representation pragmas (including the - extended DEC Ada 83 compatibility pragmas such as - `Export_Procedure'), cannot be applied to a subprogram body. If - necessary, a separate subprogram declaration must be introduced to - which the pragma can be applied. - - Optional bodies for library packages - In Ada 83, a package that did not require a package body was - nevertheless allowed to have one. This lead to certain surprises - in compiling large systems (situations in which the body could be - unexpectedly ignored). In Ada 95, if a package does not require a - body then it is not permitted to have a body. To fix this - problem, simply remove a redundant body if it is empty, or, if it - is non-empty, introduce a dummy declaration into the spec that - makes the body required. One approach is to add a private part to - the package declaration (if necessary), and define a parameterless - procedure called Requires_Body, which must then be given a dummy - procedure body in the package body, which then becomes required. - - `Numeric_Error' is now the same as `Constraint_Error' - In Ada 95, the exception `Numeric_Error' is a renaming of - `Constraint_Error'. This means that it is illegal to have - separate exception handlers for the two exceptions. The fix is - simply to remove the handler for the `Numeric_Error' case (since - even in Ada 83, a compiler was free to raise `Constraint_Error' in - place of `Numeric_Error' in all cases). - - Indefinite subtypes in generics - In Ada 83, it was permissible to pass an indefinite type (e.g. - `String') as the actual for a generic formal private type, but - then the instantiation would be illegal if there were any - instances of declarations of variables of this type in the generic - body. In Ada 95, to avoid this clear violation of the contract - model, the generic declaration clearly indicates whether or not - such instantiations are permitted. If a generic formal parameter - has explicit unknown discriminants, indicated by using `(<>)' - after the type name, then it can be instantiated with indefinite - types, but no variables can be declared of this type. Any attempt - to declare a variable will result in an illegality at the time the - generic is declared. If the `(<>)' notation is not used, then it - is illegal to instantiate the generic with an indefinite type. - This will show up as a compile time error, and the fix is usually - simply to add the `(<>)' to the generic declaration. - - All implementations of GNAT provide a switch that causes GNAT to - operate in Ada 83 mode. In this mode, some but not all compatibility - problems of the type described above are handled automatically. For - example, the new Ada 95 protected keywords are not recognized in this - mode. However, in practice, it is usually advisable to make the - necessary modifications to the program to remove the need for using - this switch. - -  - File: gnat_rm.info, Node: Compatibility with Other Ada 95 Systems, Next: Representation Clauses, Prev: Compatibility with DEC Ada 83, Up: Compatibility Guide - - Compatibility with Other Ada 95 Systems - ======================================= - - Providing that programs avoid the use of implementation dependent and - implementation defined features of Ada 95, as documented in the Ada 95 - reference manual, there should be a high degree of portability between - GNAT and other Ada 95 systems. The following are specific items which - have proved troublesome in moving GNAT programs to other Ada 95 - compilers, but do not affect porting code to GNAT. - - Ada 83 Pragmas and Attributes - Ada 95 compilers are allowed, but not required, to implement the - missing Ada 83 pragmas and attributes that are no longer defined - in Ada 95. GNAT implements all such pragmas and attributes, - eliminating this as a compatibility concern, but some other Ada 95 - compilers reject these pragmas and attributes. - - Special-needs Annexes - GNAT implements the full set of special needs annexes. At the - current time, it is the only Ada 95 compiler to do so. This means - that programs making use of these features may not be portable to - other Ada 95 compilation systems. - - Representation Clauses - Some other Ada 95 compilers implement only the minimal set of - representation clauses required by the Ada 95 reference manual. - GNAT goes far beyond this minimal set, as described in the next - section. - -  - File: gnat_rm.info, Node: Representation Clauses, Prev: Compatibility with Other Ada 95 Systems, Up: Compatibility Guide - - Representation Clauses - ====================== - - The Ada 83 reference manual was quite vague in describing both the - minimal required implementation of representation clauses, and also - their precise effects. The Ada 95 reference manual is much more - explicit, but the minimal set of capabilities required in Ada 95 is - quite limited. - - GNAT implements the full required set of capabilities described in - the Ada 95 reference manual, but also goes much beyond this, and in - particular an effort has been made to be compatible with existing Ada - 83 usage to the greatest extent possible. - - A few cases exist in which Ada 83 compiler behavior is incompatible - with requirements in the Ada 95 reference manual. These are instances - of intentional or accidental dependence on specific implementation - dependent characteristics of these Ada 83 compilers. The following is - a list of the cases most likely to arise in existing legacy Ada 83 code. - - Implicit Packing - Some Ada 83 compilers allowed a Size specification to cause - implicit packing of an array or record. This could cause - expensive implicit conversions for change of representation in the - presence of derived types, and the Ada design intends to avoid - this possibility. Subsequent AI's were issued to make it clear - that such implicit change of representation in response to a Size - clause is inadvisable, and this recommendation is represented - explicitly in the Ada 95 RM as implementation advice that is - followed by GNAT. The problem will show up as an error message - rejecting the size clause. The fix is simply to provide the - explicit pragma `Pack', or for more fine tuned control, provide a - Component_Size clause. - - Meaning of Size Attribute - The Size attribute in Ada 95 for discrete types is defined as - being the minimal number of bits required to hold values of the - type. For example, on a 32-bit machine, the size of Natural will - typically be 31 and not 32 (since no sign bit is required). Some - Ada 83 compilers gave 31, and some 32 in this situation. This - problem will usually show up as a compile time error, but not - always. It is a good idea to check all uses of the 'Size - attribute when porting Ada 83 code. The GNAT specific attribute - Object_Size can provide a useful way of duplicating the behavior of - some Ada 83 compiler systems. - - Size of Access Types - A common assumption in Ada 83 code is that an access type is in - fact a pointer, and that therefore it will be the same size as a - System.Address value. This assumption is true for GNAT in most - cases with one exception. For the case of a pointer to an - unconstrained array type (where the bounds may vary from one value - of the access type to another), the default is to use a "fat - pointer", which is represented as two separate pointers, one to - the bounds, and one to the array. This representation has a - number of advantages, including improved efficiency. However, it - may cause some difficulties in porting existing Ada 83 code which - makes the assumption that, for example, pointers fit in 32 bits on - a machine with 32-bit addressing. - - To get around this problem, GNAT also permits the use of "thin - pointers" for access types in this case (where the designated type - is an unconstrained array type). These thin pointers are indeed - the same size as a System.Address value. To specify a thin - pointer, use a size clause for the type, for example: - - type X is access all String; - for X'Size use Standard'Address_Size; - - which will cause the type X to be represented using a single - pointer. When using this representation, the bounds are right - behind the array. This representation is slightly less efficient, - and does not allow quite such flexibility in the use of foreign - pointers or in using the Unrestricted_Access attribute to create - pointers to non-aliased objects. But for any standard portable - use of the access type it will work in a functionally correct - manner and allow porting of existing code. Note that another way - of forcing a thin pointer representation is to use a component - size clause for the element size in an array, or a record - representation clause for an access field in a record. - -  - File: gnat_rm.info, Node: Compatibility with DEC Ada 83, Next: Compatibility with Other Ada 95 Systems, Prev: Compatibility with Ada 83, Up: Compatibility Guide - - Compatibility with DEC Ada 83 - ============================= - - The VMS version of GNAT fully implements all the pragmas and attributes - provided by DEC Ada 83, as well as providing the standard DEC Ada 83 - libraries, including Starlet. In addition, data layouts and parameter - passing conventions are highly compatible. This means that porting - existing DEC Ada 83 code to GNAT in VMS systems should be easier than - most other porting efforts. The following are some of the most - significant differences between GNAT and DEC Ada 83. - - Default floating-point representation - In GNAT, the default floating-point format is IEEE, whereas in DEC - Ada 83, it is VMS format. GNAT does implement the necessary - pragmas (Long_Float, Float_Representation) for changing this - default. - - System - The package System in GNAT exactly corresponds to the definition - in the Ada 95 reference manual, which means that it excludes many - of the DEC Ada 83 extensions. However, a separate package Aux_DEC - is provided that contains the additional definitions, and a - special pragma, Extend_System allows this package to be treated - transparently as an extension of package System. - - To_Address - The definitions provided by Aux_DEC are exactly compatible with - those in the DEC Ada 83 version of System, with one exception. - DEC Ada provides the following declarations: - - TO_ADDRESS(INTEGER) - TO_ADDRESS(UNSIGNED_LONGWORD) - TO_ADDRESS(universal_integer) - - The version of TO_ADDRESS taking a universal integer argument is - in fact an extension to Ada 83 not strictly compatible with the - reference manual. In GNAT, we are constrained to be exactly - compatible with the standard, and this means we cannot provide - this capability. In DEC Ada 83, the point of this definition is - to deal with a call like: - - TO_ADDRESS (16#12777#); - - Normally, according to the Ada 83 standard, one would expect this - to be ambiguous, since it matches both the INTEGER and - UNSIGNED_LONGWORD forms of TO_ADDRESS. However, in DEC Ada 83, - there is no ambiguity, since the definition using - universal_integer takes precedence. - - In GNAT, since the version with universal_integer cannot be - supplied, it is not possible to be 100% compatible. Since there - are many programs using numeric constants for the argument to - TO_ADDRESS, the decision in GNAT was to change the name of the - function in the UNSIGNED_LONGWORD case, so the declarations - provided in the GNAT version of AUX_Dec are: - - function To_Address (X : Integer) return Address; - pragma Pure_Function (To_Address); - - function To_Address_Long (X : Unsigned_Longword) - return Address; - pragma Pure_Function (To_Address_Long); - - This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD - must change the name to TO_ADDRESS_LONG. - - Task_Id values - The Task_Id values assigned will be different in the two systems, - and GNAT does not provide a specified value for the Task_Id of the - environment task, which in GNAT is treated like any other declared - task. - - For full details on these and other less significant compatibility - issues, see appendix E of the Digital publication entitled `DEC Ada, - Technical Overview and Comparison on DIGITAL Platforms'. - - For GNAT running on other than VMS systems, all the DEC Ada 83 - pragmas and attributes are recognized, although only a subset of them - can sensibly be implemented. The description of pragmas in this - reference manual indicates whether or not they are applicable to - non-VMS systems. - -  - File: gnat_rm.info, Node: GNU Free Documentation License, Next: Index, Prev: Compatibility Guide, Up: Top - - GNU Free Documentation License - ****************************** - - Version 1.2, November 2002 - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warrany Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - - ADDENDUM: How to use this License for your documents - ==================================================== - - To use this License in a document you have written, include a copy of - the License in the document and put the following copyright and license - notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover - Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other - combination of the three, merge those two alternatives to suit the - situation. - - If your document contains nontrivial examples of program code, we - recommend releasing these examples in parallel under your choice of - free software license, such as the GNU General Public License, to - permit their use in free software. - -  - File: gnat_rm.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - - Index - ***** - - * Menu: - - * -gnatR switch: Determining the Representations chosen by GNAT. - * Abort_Defer: Implementation Defined Pragmas. - * Abort_Signal: Implementation Defined Attributes. - * Access, unrestricted: Implementation Defined Attributes. - * Accuracy requirements: Implementation Advice. - * Accuracy, complex arithmetic: Implementation Advice. - * Ada 83 attributes: Implementation Defined Attributes. - * Ada 95 ISO/ANSI Standard: What This Reference Manual Contains. - * Ada.Characters.Handling: Implementation Advice. - * Ada.Characters.Latin_9 (a-chlat9.ads): Ada.Characters.Latin_9 (a-chlat9.ads). - * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada.Characters.Wide_Latin_1 (a-cwila1.ads). - * Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada.Characters.Wide_Latin_9 (a-cwila9.ads). - * Ada.Command_Line.Remove (a-colire.ads): Ada.Command_Line.Remove (a-colire.ads). - * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada.Direct_IO.C_Streams (a-diocst.ads). - * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads). - * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada.Sequential_IO.C_Streams (a-siocst.ads). - * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads). - * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada.Strings.Unbounded.Text_IO (a-suteio.ads). - * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads). - * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada.Text_IO.C_Streams (a-tiocst.ads). - * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads). - * Ada_83: Implementation Defined Pragmas. - * Ada_95: Implementation Defined Pragmas. - * Address Clause: Address Clauses. - * Address clauses: Implementation Advice. - * Address image: System.Address_Image (s-addima.ads). - * Address of subprogram code: Implementation Defined Attributes. - * Address, as private type: Implementation Advice. - * Address, operations of: Implementation Advice. - * Address_Size: Implementation Defined Attributes. - * Alignment Clause: Alignment Clauses. - * Alignment clauses: Implementation Advice. - * Alignment, default: Alignment Clauses. - * Alignment, maximum: Implementation Defined Attributes. - * Alignments of components: Implementation Defined Pragmas. - * Alternative Character Sets: Implementation Advice. - * Annotate: Implementation Defined Pragmas. - * Argument passing mechanisms: Implementation Defined Pragmas. - * Arrays, extendable <1>: GNAT.Table (g-table.ads). - * Arrays, extendable: GNAT.Dynamic_Tables (g-dyntab.ads). - * Arrays, multidimensional: Implementation Advice. - * Asm_Input: Implementation Defined Attributes. - * Asm_Output: Implementation Defined Attributes. - * Assert: Implementation Defined Pragmas. - * Assert_Failure, exception: System.Assertions (s-assert.ads). - * Assertions: System.Assertions (s-assert.ads). - * AST_Entry: Implementation Defined Attributes. - * Ast_Entry: Implementation Defined Pragmas. - * Attribute: Address Clauses. - * AWK: GNAT.AWK (g-awk.ads). - * Biased representation: Biased Representation. - * Big endian: Implementation Defined Attributes. - * Bit: Implementation Defined Attributes. - * bit ordering: Bit_Order Clauses. - * Bit ordering: Implementation Advice. - * Bit_Order Clause: Bit_Order Clauses. - * Bit_Position: Implementation Defined Attributes. - * Boolean_Entry_Barriers: Implementation Defined Characteristics. - * Bounded errors: Implementation Advice. - * Bounded-length strings: Implementation Advice. - * Bubble sort <1>: GNAT.Bubble_Sort_G (g-busorg.ads). - * Bubble sort: GNAT.Bubble_Sort_A (g-busora.ads). - * byte ordering: Effect of Bit_Order on Byte Ordering. - * C streams, interfacing: Interfaces.C.Streams (i-cstrea.ads). - * C Streams, Interfacing with Direct_IO: Ada.Direct_IO.C_Streams (a-diocst.ads). - * C Streams, Interfacing with Sequential_IO: Ada.Sequential_IO.C_Streams (a-siocst.ads). - * C Streams, Interfacing with Stream_IO: Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads). - * C Streams, Interfacing with Text_IO: Ada.Text_IO.C_Streams (a-tiocst.ads). - * C Streams, Interfacing with Wide_Text_IO: Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads). - * C++ interfacing: Interfaces.CPP (i-cpp.ads). - * C, interfacing with: Implementation Advice. - * C_Pass_By_Copy: Implementation Defined Pragmas. - * Calendar <1>: GNAT.Calendar.Time_IO (g-catiio.ads). - * Calendar: GNAT.Calendar (g-calend.ads). - * Casing of External names: Implementation Defined Pragmas. - * Casing utilities: GNAT.Case_Util (g-casuti.ads). - * CGI (Common Gateway Interface): GNAT.CGI (g-cgi.ads). - * CGI (Common Gateway Interface) cookie support: GNAT.CGI.Cookie (g-cgicoo.ads). - * CGI (Common Gateway Interface) debugging: GNAT.CGI.Debug (g-cgideb.ads). - * Character handling (GNAT.Case_Util): GNAT.Case_Util (g-casuti.ads). - * Character Sets: Implementation Advice. - * Checks, suppression of: Implementation Advice. - * Child Units: Implementation Advice. - * COBOL support: Implementation Advice. - * COBOL, interfacing with: Implementation Advice. - * Code_Address: Implementation Defined Attributes. - * Command line: GNAT.Command_Line (g-comlin.ads). - * Command line, argument removal: Ada.Command_Line.Remove (a-colire.ads). - * Comment: Implementation Defined Pragmas. - * Common_Object: Implementation Defined Pragmas. - * Compatibility (between Ada 83 and Ada 95): Compatibility with Ada 83. - * Complex arithmetic accuracy: Implementation Advice. - * Complex elementary functions: Implementation Advice. - * Complex types: Implementation Advice. - * Complex_Representation: Implementation Defined Pragmas. - * Component Clause: Record Representation Clauses. - * Component_Alignment: Implementation Defined Pragmas. - * Component_Size: Implementation Defined Pragmas. - * Component_Size Clause: Component_Size Clauses. - * Component_Size clauses: Implementation Advice. - * Component_Size_4: Implementation Defined Pragmas. - * Convention, effect on representation: Effect of Convention on Representation. - * Convention_Identifier: Implementation Defined Pragmas. - * Conventions, synonyms: Implementation Defined Pragmas. - * Conventions, typographical: Conventions. - * Cookie support in CGI: GNAT.CGI.Cookie (g-cgicoo.ads). - * CPP_Class: Implementation Defined Pragmas. - * CPP_Constructor: Implementation Defined Pragmas. - * CPP_Virtual: Implementation Defined Pragmas. - * CPP_Vtable: Implementation Defined Pragmas. - * CRC32: GNAT.CRC32 (g-crc32.ads). - * Current exception: GNAT.Current_Exception (g-curexc.ads). - * Cyclic Redundancy Check: GNAT.CRC32 (g-crc32.ads). - * Debug: Implementation Defined Pragmas. - * Debug pools: GNAT.Debug_Pools (g-debpoo.ads). - * Debugging <1>: GNAT.Exception_Traces (g-exctra.ads). - * Debugging <2>: GNAT.Debug_Utilities (g-debuti.ads). - * Debugging: GNAT.Debug_Pools (g-debpoo.ads). - * debugging with Initialize_Scalars: Implementation Defined Pragmas. - * Dec Ada 83: Implementation Defined Pragmas. - * Dec Ada 83 casing compatibility: Implementation Defined Pragmas. - * Decimal radix support: Implementation Advice. - * Default_Bit_Order: Implementation Defined Attributes. - * Deferring aborts: Implementation Defined Pragmas. - * Directory operations: GNAT.Directory_Operations (g-dirope.ads). - * Discriminants, testing for: Implementation Defined Attributes. - * Duration'Small: Implementation Advice. - * Elab_Body: Implementation Defined Attributes. - * Elab_Spec: Implementation Defined Attributes. - * Elaborated: Implementation Defined Attributes. - * Elaboration control: Implementation Defined Pragmas. - * Elaboration_Checks: Implementation Defined Pragmas. - * Eliminate: Implementation Defined Pragmas. - * Elimination of unused subprograms: Implementation Defined Pragmas. - * Emax: Implementation Defined Attributes. - * Enclosing_Entity: Enclosing_Entity. - * Entry queuing policies: Implementation Advice. - * Enum_Rep: Implementation Defined Attributes. - * Enumeration representation clauses: Implementation Advice. - * Enumeration values: Implementation Advice. - * Epsilon: Implementation Defined Attributes. - * Error detection: Implementation Advice. - * Exception information: Implementation Advice. - * Exception retrieval: GNAT.Current_Exception (g-curexc.ads). - * Exception traces: GNAT.Exception_Traces (g-exctra.ads). - * Exception, obtaining most recent: GNAT.Most_Recent_Exception (g-moreex.ads). - * Exception_Information': Exception_Information. - * Exception_Message: Exception_Message. - * Exception_Name: Exception_Name. - * Export <1>: Address Clauses. - * Export: Implementation Advice. - * Export_Exception: Implementation Defined Pragmas. - * Export_Function: Implementation Defined Pragmas. - * Export_Object: Implementation Defined Pragmas. - * Export_Procedure: Implementation Defined Pragmas. - * Export_Valued_Procedure: Implementation Defined Pragmas. - * Extend_System: Implementation Defined Pragmas. - * External: Implementation Defined Pragmas. - * External Names, casing: Implementation Defined Pragmas. - * External_Name_Casing: Implementation Defined Pragmas. - * FDL, GNU Free Documentation License: GNU Free Documentation License. - * File: File. - * File locking: GNAT.Lock_Files (g-locfil.ads). - * Finalize_Storage_Only: Implementation Defined Pragmas. - * Fixed_Value: Implementation Defined Attributes. - * Float types: Implementation Advice. - * Float_Representation: Implementation Defined Pragmas. - * Floating-Point Processor: GNAT.Float_Control (g-flocon.ads). - * Foreign threads: GNAT.Threads (g-thread.ads). - * Fortran, interfacing with: Implementation Advice. - * Get_Immediate <1>: Get_Immediate. - * Get_Immediate: Implementation Advice. - * GNAT.AWK (g-awk.ads): GNAT.AWK (g-awk.ads). - * GNAT.Bubble_Sort_A (g-busora.ads): GNAT.Bubble_Sort_A (g-busora.ads). - * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT.Bubble_Sort_G (g-busorg.ads). - * GNAT.Calendar (g-calend.ads): GNAT.Calendar (g-calend.ads). - * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT.Calendar.Time_IO (g-catiio.ads). - * GNAT.Case_Util (g-casuti.ads): GNAT.Case_Util (g-casuti.ads). - * GNAT.CGI (g-cgi.ads): GNAT.CGI (g-cgi.ads). - * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT.CGI.Cookie (g-cgicoo.ads). - * GNAT.CGI.Debug (g-cgideb.ads): GNAT.CGI.Debug (g-cgideb.ads). - * GNAT.Command_Line (g-comlin.ads): GNAT.Command_Line (g-comlin.ads). - * GNAT.CRC32 (g-crc32.ads): GNAT.CRC32 (g-crc32.ads). - * GNAT.Current_Exception (g-curexc.ads): GNAT.Current_Exception (g-curexc.ads). - * GNAT.Debug_Pools (g-debpoo.ads): GNAT.Debug_Pools (g-debpoo.ads). - * GNAT.Debug_Utilities (g-debuti.ads): GNAT.Debug_Utilities (g-debuti.ads). - * GNAT.Directory_Operations (g-dirope.ads): GNAT.Directory_Operations (g-dirope.ads). - * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT.Dynamic_Tables (g-dyntab.ads). - * GNAT.Exception_Traces (g-exctra.ads): GNAT.Exception_Traces (g-exctra.ads). - * GNAT.Expect (g-expect.ads): GNAT.Expect (g-expect.ads). - * GNAT.Float_Control (g-flocon.ads): GNAT.Float_Control (g-flocon.ads). - * GNAT.Heap_Sort_A (g-hesora.ads): GNAT.Heap_Sort_A (g-hesora.ads). - * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT.Heap_Sort_G (g-hesorg.ads). - * GNAT.HTable (g-htable.ads): GNAT.HTable (g-htable.ads). - * GNAT.IO (g-io.ads): GNAT.IO (g-io.ads). - * GNAT.IO_Aux (g-io_aux.ads): GNAT.IO_Aux (g-io_aux.ads). - * GNAT.Lock_Files (g-locfil.ads): GNAT.Lock_Files (g-locfil.ads). - * GNAT.MD5 (g-md5.ads): GNAT.MD5 (g-md5.ads). - * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT.Most_Recent_Exception (g-moreex.ads). - * GNAT.OS_Lib (g-os_lib.ads): GNAT.OS_Lib (g-os_lib.ads). - * GNAT.Regexp (g-regexp.ads): GNAT.Regexp (g-regexp.ads). - * GNAT.Registry (g-regist.ads): GNAT.Registry (g-regist.ads). - * GNAT.Regpat (g-regpat.ads): GNAT.Regpat (g-regpat.ads). - * GNAT.Sockets (g-socket.ads): GNAT.Sockets (g-socket.ads). - * GNAT.Source_Info (g-souinf.ads): GNAT.Source_Info (g-souinf.ads). - * GNAT.Spell_Checker (g-speche.ads): GNAT.Spell_Checker (g-speche.ads). - * GNAT.Spitbol (g-spitbo.ads): GNAT.Spitbol (g-spitbo.ads). - * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT.Spitbol.Patterns (g-spipat.ads). - * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT.Spitbol.Table_Boolean (g-sptabo.ads). - * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT.Spitbol.Table_Integer (g-sptain.ads). - * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT.Spitbol.Table_VString (g-sptavs.ads). - * GNAT.Table (g-table.ads): GNAT.Table (g-table.ads). - * GNAT.Task_Lock (g-tasloc.ads): GNAT.Task_Lock (g-tasloc.ads). - * GNAT.Threads (g-thread.ads): GNAT.Threads (g-thread.ads). - * GNAT.Traceback (g-traceb.ads): GNAT.Traceback (g-traceb.ads). - * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT.Traceback.Symbolic (g-trasym.ads). - * Has_Discriminants: Implementation Defined Attributes. - * Hash tables: GNAT.HTable (g-htable.ads). - * Heap usage, implicit: Implementation Advice. - * IBM Packed Format: Interfaces.Packed_Decimal (i-pacdec.ads). - * Ident: Implementation Defined Pragmas. - * Image, of an address: System.Address_Image (s-addima.ads). - * Img: Implementation Defined Attributes. - * Implementation-dependent features: About This Guide. - * Import: Address Clauses. - * Import_Exception: Implementation Defined Pragmas. - * Import_Function: Implementation Defined Pragmas. - * Import_Object: Implementation Defined Pragmas. - * Import_Procedure: Implementation Defined Pragmas. - * Import_Valued_Procedure: Implementation Defined Pragmas. - * Initialization, suppression of: Implementation Defined Pragmas. - * Initialize_Scalars: Implementation Defined Pragmas. - * Inline_Always: Implementation Defined Pragmas. - * Inline_Generic: Implementation Defined Pragmas. - * Input/Output facilities <1>: GNAT.IO_Aux (g-io_aux.ads). - * Input/Output facilities: GNAT.IO (g-io.ads). - * Integer maps: GNAT.Spitbol.Table_Integer (g-sptain.ads). - * Integer types: Implementation Advice. - * Integer_Value: Implementation Defined Attributes. - * Interface: Implementation Defined Pragmas. - * Interface_Name: Implementation Defined Pragmas. - * Interfaces: Implementation Advice. - * Interfaces.C.Extensions (i-cexten.ads): Interfaces.C.Extensions (i-cexten.ads). - * Interfaces.C.Streams (i-cstrea.ads): Interfaces.C.Streams (i-cstrea.ads). - * Interfaces.CPP (i-cpp.ads): Interfaces.CPP (i-cpp.ads). - * Interfaces.Os2lib (i-os2lib.ads): Interfaces.Os2lib (i-os2lib.ads). - * Interfaces.Os2lib.Errors (i-os2err.ads): Interfaces.Os2lib.Errors (i-os2err.ads). - * Interfaces.Os2lib.Synchronization (i-os2syn.ads): Interfaces.Os2lib.Synchronization (i-os2syn.ads). - * Interfaces.Os2lib.Threads (i-os2thr.ads): Interfaces.Os2lib.Threads (i-os2thr.ads). - * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces.Packed_Decimal (i-pacdec.ads). - * Interfaces.VxWorks (i-vxwork.ads): Interfaces.VxWorks (i-vxwork.ads). - * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces.VxWorks.IO (i-vxwoio.ads). - * Interfacing to C++: Implementation Defined Pragmas. - * Interfacing to VxWorks: Interfaces.VxWorks (i-vxwork.ads). - * Interfacing to VxWorks' I/O: Interfaces.VxWorks.IO (i-vxwoio.ads). - * Interfacing with C++: Implementation Defined Pragmas. - * Interfacing, to C++: Interfaces.CPP (i-cpp.ads). - * Interfacing, to OS/2 <1>: Interfaces.Os2lib.Threads (i-os2thr.ads). - * Interfacing, to OS/2 <2>: Interfaces.Os2lib.Synchronization (i-os2syn.ads). - * Interfacing, to OS/2 <3>: Interfaces.Os2lib.Errors (i-os2err.ads). - * Interfacing, to OS/2: Interfaces.Os2lib (i-os2lib.ads). - * Interrupt priority, maximum: Implementation Defined Attributes. - * Interrupt support: Implementation Advice. - * Interrupts: Implementation Advice. - * Intrinsic operator: Intrinsic Operators. - * Intrinsic Subprograms: Intrinsic Subprograms. - * Large: Implementation Defined Attributes. - * Latin-1: Compatibility with Ada 83. - * Latin_1 constants for Wide_Character: Ada.Characters.Wide_Latin_1 (a-cwila1.ads). - * Latin_9 constants for Character: Ada.Characters.Latin_9 (a-chlat9.ads). - * Latin_9 constants for Wide_Character: Ada.Characters.Wide_Latin_9 (a-cwila9.ads). - * License: Implementation Defined Pragmas. - * License checking: Implementation Defined Pragmas. - * Line: Line. - * Link_With: Implementation Defined Pragmas. - * Linker_Alias: Implementation Defined Pragmas. - * Linker_Section: Implementation Defined Pragmas. - * Little endian: Implementation Defined Attributes. - * Locking: GNAT.Task_Lock (g-tasloc.ads). - * Locking Policies: Implementation Advice. - * Locking using files: GNAT.Lock_Files (g-locfil.ads). - * Long_Float: Implementation Defined Pragmas. - * Machine operations: Implementation Advice. - * Machine_Attribute: Implementation Defined Pragmas. - * Machine_Size: Implementation Defined Attributes. - * Main_Storage: Implementation Defined Pragmas. - * Mantissa: Implementation Defined Attributes. - * Maps <1>: GNAT.Spitbol.Table_VString (g-sptavs.ads). - * Maps: GNAT.Spitbol.Table_Integer (g-sptain.ads). - * Max_Entry_Queue_Depth: Implementation Defined Characteristics. - * Max_Interrupt_Priority: Implementation Defined Attributes. - * Max_Priority: Implementation Defined Attributes. - * Maximum_Alignment: Implementation Defined Attributes. - * Mechanism_Code: Implementation Defined Attributes. - * Memory corruption debugging: GNAT.Debug_Pools (g-debpoo.ads). - * Message Digest MD5: GNAT.MD5 (g-md5.ads). - * Multidimensional arrays: Implementation Advice. - * Named numbers, representation of: Implementation Defined Attributes. - * No_Calendar: Implementation Defined Characteristics. - * No_Dynamic_Interrupts: Implementation Defined Characteristics. - * No_Elaboration_Code: Implementation Defined Characteristics. - * No_Entry_Calls_In_Elaboration_Code: Implementation Defined Characteristics. - * No_Entry_Queue: Implementation Defined Characteristics. - * No_Enumeration_Maps: Implementation Defined Characteristics. - * No_Exception_Handlers: Implementation Defined Characteristics. - * No_Implementation_Attributes: Implementation Defined Characteristics. - * No_Implementation_Pragmas: Implementation Defined Characteristics. - * No_Implementation_Restrictions: Implementation Defined Characteristics. - * No_Implicit_Conditionals: Implementation Defined Characteristics. - * No_Implicit_Loops: Implementation Defined Characteristics. - * No_Local_Protected_Objects: Implementation Defined Characteristics. - * No_Protected_Type_Allocators: Implementation Defined Characteristics. - * No_Return: Implementation Defined Pragmas. - * No_Run_Time: Implementation Defined Pragmas. - * No_Secondary_Stack: Implementation Defined Characteristics. - * No_Select_Statements: Implementation Defined Characteristics. - * No_Standard_Storage_Pools: Implementation Defined Characteristics. - * No_Streams: Implementation Defined Characteristics. - * No_Task_Attributes: Implementation Defined Characteristics. - * No_Task_Termination: Implementation Defined Characteristics. - * No_Tasking: Implementation Defined Characteristics. - * No_Wide_Characters: Implementation Defined Characteristics. - * Normalize_Scalars: Implementation Defined Pragmas. - * Null_Occurrence, testing for: Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads). - * Null_Parameter: Implementation Defined Attributes. - * Numerics: Implementation Advice. - * Object_Size <1>: Value_Size and Object_Size Clauses. - * Object_Size: Implementation Defined Attributes. - * OpenVMS <1>: Implementation Defined Attributes. - * OpenVMS: Implementation Defined Pragmas. - * Operating System interface: GNAT.OS_Lib (g-os_lib.ads). - * Operations, on Address: Implementation Advice. - * ordering, of bits: Bit_Order Clauses. - * ordering, of bytes: Effect of Bit_Order on Byte Ordering. - * OS/2 Error codes: Interfaces.Os2lib.Errors (i-os2err.ads). - * OS/2 interfacing <1>: Interfaces.Os2lib.Errors (i-os2err.ads). - * OS/2 interfacing: Interfaces.Os2lib (i-os2lib.ads). - * OS/2 synchronization primitives: Interfaces.Os2lib.Synchronization (i-os2syn.ads). - * OS/2 thread interfacing: Interfaces.Os2lib.Threads (i-os2thr.ads). - * Package Interfaces: Implementation Advice. - * Package Interrupts: Implementation Advice. - * Package Task_Attributes: Implementation Advice. - * Packed Decimal: Interfaces.Packed_Decimal (i-pacdec.ads). - * Packed types: Implementation Advice. - * Parameters, passing mechanism: Implementation Defined Attributes. - * Parameters, when passed by reference: Implementation Defined Attributes. - * Parsing: GNAT.AWK (g-awk.ads). - * Partition communication subsystem: Implementation Advice. - * Partition intefacing functions: System.Partition_Interface (s-parint.ads). - * Passed_By_Reference: Implementation Defined Attributes. - * Passing by copy: Implementation Defined Pragmas. - * Passing by descriptor: Implementation Defined Pragmas. - * Passive: Implementation Defined Pragmas. - * Pattern matching <1>: GNAT.Spitbol.Patterns (g-spipat.ads). - * Pattern matching <2>: GNAT.Regpat (g-regpat.ads). - * Pattern matching: GNAT.Regexp (g-regexp.ads). - * PCS: Implementation Advice. - * Polling: Implementation Defined Pragmas. - * Portability: About This Guide. - * Pragma Pack (for arrays): Pragma Pack for Arrays. - * Pragma Pack (for records): Pragma Pack for Records. - * Pragma, representation: Representation Clauses and Pragmas. - * Pragmas: Implementation Advice. - * Pre-elaboration requirements: Implementation Advice. - * Preemptive abort: Implementation Advice. - * Priority, maximum: Implementation Defined Attributes. - * Propagate_Exceptions: Implementation Defined Pragmas. - * Protected procedure handlers: Implementation Advice. - * Psect_Object: Implementation Defined Pragmas. - * Pure: Implementation Defined Pragmas. - * Pure_Function: Implementation Defined Pragmas. - * Random number generation: Implementation Advice. - * Range_Length: Implementation Defined Attributes. - * Ravenscar: Implementation Defined Pragmas. - * Record Representation Clause: Record Representation Clauses. - * Record representation clauses: Implementation Advice. - * Regular expressions <1>: GNAT.Regpat (g-regpat.ads). - * Regular expressions: GNAT.Regexp (g-regexp.ads). - * Removing command line arguments: Ada.Command_Line.Remove (a-colire.ads). - * Representation Clause: Representation Clauses and Pragmas. - * Representation Clauses: Representation Clauses and Pragmas. - * Representation clauses: Implementation Advice. - * Representation clauses, enumeration: Implementation Advice. - * Representation clauses, records: Implementation Advice. - * Representation of enums: Implementation Defined Attributes. - * Representation of wide characters: System.Wch_Cnv (s-wchcnv.ads). - * Representation Pragma: Representation Clauses and Pragmas. - * Representation, determination of: Determining the Representations chosen by GNAT. - * Restricted_Run_Time: Implementation Defined Pragmas. - * Return values, passing mechanism: Implementation Defined Attributes. - * Rotate_Left: Rotate_Left. - * Rotate_Right: Rotate_Right. - * Safe_Emax: Implementation Defined Attributes. - * Safe_Large: Implementation Defined Attributes. - * Sets of strings: GNAT.Spitbol.Table_Boolean (g-sptabo.ads). - * Share_Generic: Implementation Defined Pragmas. - * Shift_Left: Shift_Left. - * Shift_Right: Shift_Right. - * Shift_Right_Arithmetic: Shift_Right_Arithmetic. - * Simple I/O: GNAT.IO (g-io.ads). - * Size Clause: Size Clauses. - * Size clauses: Implementation Advice. - * Size for biased representation: Biased Representation. - * Size of Address: Implementation Defined Attributes. - * Size, of objects: Value_Size and Object_Size Clauses. - * Size, setting for not-first subtype: Implementation Defined Attributes. - * Size, used for objects: Implementation Defined Attributes. - * Size, VADS compatibility <1>: Implementation Defined Attributes. - * Size, VADS compatibility: Implementation Defined Pragmas. - * Size, variant record objects: Size of Variant Record Objects. - * Small: Implementation Defined Attributes. - * Sockets: GNAT.Sockets (g-socket.ads). - * Sorting <1>: GNAT.Heap_Sort_G (g-hesorg.ads). - * Sorting <2>: GNAT.Heap_Sort_A (g-hesora.ads). - * Sorting <3>: GNAT.Bubble_Sort_G (g-busorg.ads). - * Sorting: GNAT.Bubble_Sort_A (g-busora.ads). - * Source Information: GNAT.Source_Info (g-souinf.ads). - * Source_File_Name: Implementation Defined Pragmas. - * Source_Location: Source_Location. - * Source_Reference: Implementation Defined Pragmas. - * Spawn capability: GNAT.OS_Lib (g-os_lib.ads). - * Spell checking: GNAT.Spell_Checker (g-speche.ads). - * SPITBOL interface: GNAT.Spitbol (g-spitbo.ads). - * SPITBOL pattern matching: GNAT.Spitbol.Patterns (g-spipat.ads). - * SPITBOL Tables <1>: GNAT.Spitbol.Table_VString (g-sptavs.ads). - * SPITBOL Tables <2>: GNAT.Spitbol.Table_Integer (g-sptain.ads). - * SPITBOL Tables: GNAT.Spitbol.Table_Boolean (g-sptabo.ads). - * Static_Priorities: Implementation Defined Characteristics. - * Static_Storage_Size: Implementation Defined Characteristics. - * Storage place attributes: Implementation Advice. - * Storage_Size Clause: Storage_Size Clauses. - * Storage_Unit <1>: Implementation Defined Attributes. - * Storage_Unit: Implementation Defined Pragmas. - * Stream files: Treating Text_IO Files as Streams. - * Stream oriented attributes: Implementation Advice. - * Stream_Convert: Implementation Defined Pragmas. - * String maps: GNAT.Spitbol.Table_VString (g-sptavs.ads). - * Style_Checks: Implementation Defined Pragmas. - * Subprogram address: Implementation Defined Attributes. - * Subtitle: Implementation Defined Pragmas. - * Suppress_All: Implementation Defined Pragmas. - * Suppress_Initialization: Implementation Defined Pragmas. - * Suppressing initialization: Implementation Defined Pragmas. - * Suppression of checks: Implementation Advice. - * Synchronization, OS/2: Interfaces.Os2lib.Synchronization (i-os2syn.ads). - * system, extending: Implementation Defined Pragmas. - * System.Address_Image (s-addima.ads): System.Address_Image (s-addima.ads). - * System.Assertions (s-assert.ads): System.Assertions (s-assert.ads). - * System.Partition_Interface (s-parint.ads): System.Partition_Interface (s-parint.ads). - * System.Task_Info (s-tasinf.ads): System.Task_Info (s-tasinf.ads). - * System.Wch_Cnv (s-wchcnv.ads): System.Wch_Cnv (s-wchcnv.ads). - * System.Wch_Con (s-wchcon.ads): System.Wch_Con (s-wchcon.ads). - * Table implementation <1>: GNAT.Table (g-table.ads). - * Table implementation: GNAT.Dynamic_Tables (g-dyntab.ads). - * Task locking: GNAT.Task_Lock (g-tasloc.ads). - * Task synchronization: GNAT.Task_Lock (g-tasloc.ads). - * Task_Attributes: Implementation Advice. - * Task_Info: Implementation Defined Pragmas. - * Task_Info pragma: System.Task_Info (s-tasinf.ads). - * Task_Name: Implementation Defined Pragmas. - * Task_Storage: Implementation Defined Pragmas. - * Tasking restrictions: Implementation Advice. - * Text_IO: GNAT.IO_Aux (g-io_aux.ads). - * Text_IO extensions: Text_IO Extensions. - * Text_IO for unbounded strings: Text_IO Facilities for Unbounded Strings. - * Text_IO, extensions for unbounded strings: Ada.Strings.Unbounded.Text_IO (a-suteio.ads). - * Text_IO, extensions for unbounded wide strings: Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads). - * Thread control, OS/2: Interfaces.Os2lib.Threads (i-os2thr.ads). - * Threads, foreign: GNAT.Threads (g-thread.ads). - * Tick: Implementation Defined Attributes. - * Time: GNAT.Calendar.Time_IO (g-catiio.ads). - * Time, monotonic: Implementation Advice. - * Time_Slice: Implementation Defined Pragmas. - * Title: Implementation Defined Pragmas. - * To_Address <1>: Address Clauses. - * To_Address: Implementation Defined Attributes. - * Trace back facilities <1>: GNAT.Traceback.Symbolic (g-trasym.ads). - * Trace back facilities: GNAT.Traceback (g-traceb.ads). - * Type_Class: Implementation Defined Attributes. - * Typographical conventions: Conventions. - * UET_Address: Implementation Defined Attributes. - * Unbounded_String, IO support: Ada.Strings.Unbounded.Text_IO (a-suteio.ads). - * Unbounded_String, Text_IO operations: Text_IO Facilities for Unbounded Strings. - * Unbounded_Wide_String, IO support: Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads). - * Unchecked conversion: Implementation Advice. - * Unchecked deallocation: Implementation Advice. - * Unchecked_Union: Implementation Defined Pragmas. - * Unimplemented_Unit: Implementation Defined Pragmas. - * Unions in C: Implementation Defined Pragmas. - * Universal_Literal_String: Implementation Defined Attributes. - * Unreferenced: Implementation Defined Pragmas. - * Unreserve_All_Interrupts: Implementation Defined Pragmas. - * Unrestricted_Access: Implementation Defined Attributes. - * Unsuppress: Implementation Defined Pragmas. - * Use_VADS_Size: Implementation Defined Pragmas. - * VADS_Size: Implementation Defined Attributes. - * Validity_Checks: Implementation Defined Pragmas. - * Value_Size <1>: Value_Size and Object_Size Clauses. - * Value_Size: Implementation Defined Attributes. - * Variant record objects, size: Size of Variant Record Objects. - * Volatile: Implementation Defined Pragmas. - * VxWorks, Get_Immediate: Interfaces.VxWorks.IO (i-vxwoio.ads). - * VxWorks, I/O interfacing: Interfaces.VxWorks.IO (i-vxwoio.ads). - * VxWorks, interfacing: Interfaces.VxWorks (i-vxwork.ads). - * Warnings: Implementation Defined Pragmas. - * Warnings, unreferenced: Implementation Defined Pragmas. - * Wchar_T_Size: Implementation Defined Attributes. - * Weak_External: Implementation Defined Pragmas. - * Wide Character, Representation: System.Wch_Cnv (s-wchcnv.ads). - * Wide String, Conversion: System.Wch_Cnv (s-wchcnv.ads). - * Windows Registry: GNAT.Registry (g-regist.ads). - * Word_Size: Implementation Defined Attributes. - * Zero address, passing: Implementation Defined Attributes. - * Zero Cost Exceptions: Implementation Defined Pragmas. - - -  - Tag Table: - Node: Top228 - Node: About This Guide5850 - Node: What This Reference Manual Contains6923 - Node: Conventions9219 - Node: Related Information10155 - Node: Implementation Defined Pragmas11183 - Node: Implementation Defined Attributes109042 - Node: Implementation Advice133113 - Node: Implementation Defined Characteristics177748 - Node: Intrinsic Subprograms220488 - Node: Intrinsic Operators221623 - Node: Enclosing_Entity222713 - Node: Exception_Information223251 - Node: Exception_Message223796 - Node: Exception_Name224313 - Node: File224788 - Node: Line225203 - Node: Rotate_Left225624 - Node: Rotate_Right226503 - Node: Shift_Left226794 - Node: Shift_Right227079 - Node: Shift_Right_Arithmetic227377 - Node: Source_Location227713 - Node: Representation Clauses and Pragmas228171 - Node: Alignment Clauses229369 - Node: Size Clauses232853 - Node: Storage_Size Clauses235409 - Node: Size of Variant Record Objects238109 - Node: Biased Representation241393 - Node: Value_Size and Object_Size Clauses242609 - Node: Component_Size Clauses249320 - Node: Bit_Order Clauses250456 - Node: Effect of Bit_Order on Byte Ordering254163 - Node: Pragma Pack for Arrays264112 - Node: Pragma Pack for Records266194 - Node: Record Representation Clauses268703 - Node: Enumeration Clauses270512 - Node: Address Clauses272099 - Node: Effect of Convention on Representation278801 - Node: Determining the Representations chosen by GNAT281532 - Node: Standard Library Routines286347 - Node: The Implementation of Standard I/O303855 - Node: Standard I/O Packages305956 - Node: FORM Strings306836 - Node: Direct_IO307375 - Node: Sequential_IO308256 - Node: Text_IO310194 - Node: Text_IO Stream Pointer Positioning312729 - Node: Text_IO Reading and Writing Non-Regular Files314266 - Node: Get_Immediate316138 - Node: Treating Text_IO Files as Streams316971 - Node: Text_IO Extensions317636 - Node: Text_IO Facilities for Unbounded Strings318475 - Node: Wide_Text_IO319881 - Node: Wide_Text_IO Stream Pointer Positioning324738 - Node: Wide_Text_IO Reading and Writing Non-Regular Files325764 - Node: Stream_IO326299 - Node: Shared Files326920 - Node: Open Modes329756 - Node: Operations on C Streams331067 - Node: Interfacing to C Streams338032 - Node: The GNAT Library341121 - Node: Ada.Characters.Latin_9 (a-chlat9.ads)345796 - Node: Ada.Characters.Wide_Latin_1 (a-cwila1.ads)346314 - Node: Ada.Characters.Wide_Latin_9 (a-cwila9.ads)346923 - Node: Ada.Command_Line.Remove (a-colire.ads)347535 - Node: Ada.Direct_IO.C_Streams (a-diocst.ads)348059 - Node: Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)348582 - Node: Ada.Sequential_IO.C_Streams (a-siocst.ads)349022 - Node: Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)349569 - Node: Ada.Strings.Unbounded.Text_IO (a-suteio.ads)350116 - Node: Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)350577 - Node: Ada.Text_IO.C_Streams (a-tiocst.ads)351058 - Node: Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)351582 - Node: GNAT.AWK (g-awk.ads)352087 - Node: GNAT.Bubble_Sort_A (g-busora.ads)352528 - Node: GNAT.Bubble_Sort_G (g-busorg.ads)352938 - Node: GNAT.Calendar (g-calend.ads)353424 - Node: GNAT.Calendar.Time_IO (g-catiio.ads)353889 - Node: GNAT.CRC32 (g-crc32.ads)354132 - Node: GNAT.Case_Util (g-casuti.ads)354763 - Node: GNAT.CGI (g-cgi.ads)355127 - Node: GNAT.CGI.Cookie (g-cgicoo.ads)355641 - Node: GNAT.CGI.Debug (g-cgideb.ads)356070 - Node: GNAT.Command_Line (g-comlin.ads)356395 - Node: GNAT.Current_Exception (g-curexc.ads)356830 - Node: GNAT.Debug_Pools (g-debpoo.ads)357387 - Node: GNAT.Debug_Utilities (g-debuti.ads)357806 - Node: GNAT.Directory_Operations (g-dirope.ads)358188 - Node: GNAT.Dynamic_Tables (g-dyntab.ads)358619 - Node: GNAT.Exception_Traces (g-exctra.ads)359252 - Node: GNAT.Expect (g-expect.ads)359591 - Node: GNAT.Float_Control (g-flocon.ads)360283 - Node: GNAT.Heap_Sort_A (g-hesora.ads)360804 - Node: GNAT.Heap_Sort_G (g-hesorg.ads)361329 - Node: GNAT.HTable (g-htable.ads)361803 - Node: GNAT.IO (g-io.ads)362205 - Node: GNAT.IO_Aux (g-io_aux.ads)362636 - Node: GNAT.Lock_Files (g-locfil.ads)362991 - Node: GNAT.MD5 (g-md5.ads)363324 - Node: GNAT.Most_Recent_Exception (g-moreex.ads)363610 - Node: GNAT.OS_Lib (g-os_lib.ads)364049 - Node: GNAT.Regexp (g-regexp.ads)364525 - Node: GNAT.Registry (g-regist.ads)365008 - Node: GNAT.Regpat (g-regpat.ads)365494 - Node: GNAT.Sockets (g-socket.ads)365916 - Node: GNAT.Source_Info (g-souinf.ads)366426 - Node: GNAT.Spell_Checker (g-speche.ads)366798 - Node: GNAT.Spitbol.Patterns (g-spipat.ads)367154 - Node: GNAT.Spitbol (g-spitbo.ads)367707 - Node: GNAT.Spitbol.Table_Boolean (g-sptabo.ads)368271 - Node: GNAT.Spitbol.Table_Integer (g-sptain.ads)368692 - Node: GNAT.Spitbol.Table_VString (g-sptavs.ads)369140 - Node: GNAT.Table (g-table.ads)369577 - Node: GNAT.Task_Lock (g-tasloc.ads)370192 - Node: GNAT.Threads (g-thread.ads)370604 - Node: GNAT.Traceback (g-traceb.ads)371197 - Node: GNAT.Traceback.Symbolic (g-trasym.ads)371543 - Node: Interfaces.C.Extensions (i-cexten.ads)371911 - Node: Interfaces.C.Streams (i-cstrea.ads)372328 - Node: Interfaces.CPP (i-cpp.ads)372659 - Node: Interfaces.Os2lib (i-os2lib.ads)373062 - Node: Interfaces.Os2lib.Errors (i-os2err.ads)373456 - Node: Interfaces.Os2lib.Synchronization (i-os2syn.ads)373796 - Node: Interfaces.Os2lib.Threads (i-os2thr.ads)374211 - Node: Interfaces.Packed_Decimal (i-pacdec.ads)374602 - Node: Interfaces.VxWorks (i-vxwork.ads)375016 - Node: Interfaces.VxWorks.IO (i-vxwoio.ads)375413 - Node: System.Address_Image (s-addima.ads)375829 - Node: System.Assertions (s-assert.ads)376214 - Node: System.Partition_Interface (s-parint.ads)376638 - Node: System.Task_Info (s-tasinf.ads)377049 - Node: System.Wch_Cnv (s-wchcnv.ads)377396 - Node: System.Wch_Con (s-wchcon.ads)377856 - Node: Interfacing to Other Languages378237 - Node: Interfacing to C378714 - Node: Interfacing to C++380546 - Node: Interfacing to COBOL381896 - Node: Interfacing to Fortran382179 - Node: Interfacing to non-GNAT Ada code382647 - Node: Machine Code Insertions383782 - Node: GNAT Implementation of Tasking390378 - Node: Mapping Ada Tasks onto the Underlying Kernel Threads390705 - Node: Ensuring Compliance with the Real-Time Annex392823 - Node: Code generation for array aggregates394943 - Node: Static constant aggregates with static bounds396527 - Node: Constant aggregates with an unconstrained nominal types398122 - Node: Aggregates with static bounds398842 - Node: Aggregates with non-static bounds399728 - Node: Aggregates in assignments statements400318 - Node: Specialized Needs Annexes401754 - Node: Compatibility Guide402847 - Node: Compatibility with Ada 83403363 - Node: Compatibility with Other Ada 95 Systems408299 - Node: Representation Clauses409821 - Node: Compatibility with DEC Ada 83414345 - Node: GNU Free Documentation License418206 - Node: Index440624 -  - End Tag Table --- 0 ---- diff -Nrc3pad gcc-3.3.2/gcc/ada/gnat_ug_unx.info gcc-3.3.3/gcc/ada/gnat_ug_unx.info *** gcc-3.3.2/gcc/ada/gnat_ug_unx.info Thu Oct 16 20:24:00 2003 --- gcc-3.3.3/gcc/ada/gnat_ug_unx.info Thu Jan 1 00:00:00 1970 *************** *** 1,17759 **** - This is ada/gnat_ug_unx.info, produced by makeinfo version 4.2 from - ada/gnat_ug_unx.texi. - - Copyright (C) 1995-2002, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT User's Guide for Unix Platforms", and - with no Back-Cover Texts. A copy of the license is included in the - section entitled "GNU Free Documentation License". -  - File: gnat_ug_unx.info, Node: Top, Next: About This Guide, Prev: (dir), Up: (dir) - - GNAT User's Guide - ***************** - - GNAT User's Guide for Unix Platforms - - GNAT, The GNU Ada 95 Compiler - - GNAT Version for GCC 3.3.2 - - Ada Core Technologies, Inc. - - Copyright (C) 1995-2002, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT User's Guide for Unix Platforms", and - with no Back-Cover Texts. A copy of the license is included in the - section entitled "GNU Free Documentation License". - * Menu: - - * About This Guide:: - * Getting Started with GNAT:: - * The GNAT Compilation Model:: - * Compiling Using gcc:: - * Binding Using gnatbind:: - * Linking Using gnatlink:: - * The GNAT Make Program gnatmake:: - * Renaming Files Using gnatchop:: - * Configuration Pragmas:: - * Handling Arbitrary File Naming Conventions Using gnatname:: - * GNAT Project Manager:: - * Elaboration Order Handling in GNAT:: - * The Cross-Referencing Tools gnatxref and gnatfind:: - * File Name Krunching Using gnatkr:: - * Preprocessing Using gnatprep:: - * The GNAT Library Browser gnatls:: - * GNAT and Libraries:: - * Using the GNU make Utility:: - * Finding Memory Problems with gnatmem:: - * Finding Memory Problems with GNAT Debug Pool:: - * Creating Sample Bodies Using gnatstub:: - * Reducing the Size of Ada Executables with gnatelim:: - * Other Utility Programs:: - * Running and Debugging Ada Programs:: - * Inline Assembler:: - * Performance Considerations:: - * GNU Free Documentation License:: - * Index:: - - --- The Detailed Node Listing --- - - About This Guide - - * What This Guide Contains:: - * What You Should Know before Reading This Guide:: - * Related Information:: - * Conventions:: - - - Getting Started with GNAT - - * Running GNAT:: - * Running a Simple Ada Program:: - * Running a Program with Multiple Units:: - * Using the gnatmake Utility:: - - The GNAT Compilation Model - - * Source Representation:: - * Foreign Language Representation:: - * File Naming Rules:: - * Using Other File Names:: - * Alternative File Naming Schemes:: - * Generating Object Files:: - * Source Dependencies:: - * The Ada Library Information Files:: - * Binding an Ada Program:: - * Mixed Language Programming:: - * Building Mixed Ada & C++ Programs:: - * Comparison between GNAT and C/C++ Compilation Models:: - * Comparison between GNAT and Conventional Ada Library Models:: - - Foreign Language Representation - - * Latin-1:: - * Other 8-Bit Codes:: - * Wide Character Encodings:: - - Compiling Ada Programs With gcc - - * Compiling Programs:: - * Switches for gcc:: - * Search Paths and the Run-Time Library (RTL):: - * Order of Compilation Issues:: - * Examples:: - - Switches for gcc - - * Output and Error Message Control:: - * Debugging and Assertion Control:: - * Run-Time Checks:: - * Stack Overflow Checking:: - * Run-Time Control:: - * Validity Checking:: - * Style Checking:: - * Using gcc for Syntax Checking:: - * Using gcc for Semantic Checking:: - * Compiling Ada 83 Programs:: - * Character Set Control:: - * File Naming Control:: - * Subprogram Inlining Control:: - * Auxiliary Output Control:: - * Debugging Control:: - * Units to Sources Mapping Files:: - - Binding Ada Programs With gnatbind - - * Running gnatbind:: - * Generating the Binder Program in C:: - * Consistency-Checking Modes:: - * Binder Error Message Control:: - * Elaboration Control:: - * Output Control:: - * Binding with Non-Ada Main Programs:: - * Binding Programs with No Main Subprogram:: - * Summary of Binder Switches:: - * Command-Line Access:: - * Search Paths for gnatbind:: - * Examples of gnatbind Usage:: - - Linking Using gnatlink - - * Running gnatlink:: - * Switches for gnatlink:: - * Setting Stack Size from gnatlink:: - * Setting Heap Size from gnatlink:: - - The GNAT Make Program gnatmake - - * Running gnatmake:: - * Switches for gnatmake:: - * Mode Switches for gnatmake:: - * Notes on the Command Line:: - * How gnatmake Works:: - * Examples of gnatmake Usage:: - - Renaming Files Using gnatchop - - * Handling Files with Multiple Units:: - * Operating gnatchop in Compilation Mode:: - * Command Line for gnatchop:: - * Switches for gnatchop:: - * Examples of gnatchop Usage:: - - Configuration Pragmas - - * Handling of Configuration Pragmas:: - * The Configuration Pragmas Files:: - - Handling Arbitrary File Naming Conventions Using gnatname - - * Arbitrary File Naming Conventions:: - * Running gnatname:: - * Switches for gnatname:: - * Examples of gnatname Usage:: - - GNAT Project Manager - - * Introduction:: - * Examples of Project Files:: - * Project File Syntax:: - * Objects and Sources in Project Files:: - * Importing Projects:: - * Project Extension:: - * External References in Project Files:: - * Packages in Project Files:: - * Variables from Imported Projects:: - * Naming Schemes:: - * Library Projects:: - * Switches Related to Project Files:: - * Tools Supporting Project Files:: - * An Extended Example:: - * Project File Complete Syntax:: - - Elaboration Order Handling in GNAT - - * Elaboration Code in Ada 95:: - * Checking the Elaboration Order in Ada 95:: - * Controlling the Elaboration Order in Ada 95:: - * Controlling Elaboration in GNAT - Internal Calls:: - * Controlling Elaboration in GNAT - External Calls:: - * Default Behavior in GNAT - Ensuring Safety:: - * Elaboration Issues for Library Tasks:: - * Mixing Elaboration Models:: - * What to Do If the Default Elaboration Behavior Fails:: - * Elaboration for Access-to-Subprogram Values:: - * Summary of Procedures for Elaboration Control:: - * Other Elaboration Order Considerations:: - - The Cross-Referencing Tools gnatxref and gnatfind - - * gnatxref Switches:: - * gnatfind Switches:: - * Project Files for gnatxref and gnatfind:: - * Regular Expressions in gnatfind and gnatxref:: - * Examples of gnatxref Usage:: - * Examples of gnatfind Usage:: - - File Name Krunching Using gnatkr - - * About gnatkr:: - * Using gnatkr:: - * Krunching Method:: - * Examples of gnatkr Usage:: - - Preprocessing Using gnatprep - - * Using gnatprep:: - * Switches for gnatprep:: - * Form of Definitions File:: - * Form of Input Text for gnatprep:: - - - The GNAT Library Browser gnatls - - * Running gnatls:: - * Switches for gnatls:: - * Examples of gnatls Usage:: - - - GNAT and Libraries - - * Creating an Ada Library:: - * Installing an Ada Library:: - * Using an Ada Library:: - * Creating an Ada Library to be Used in a Non-Ada Context:: - * Rebuilding the GNAT Run-Time Library:: - - Using the GNU make Utility - - * Using gnatmake in a Makefile:: - * Automatically Creating a List of Directories:: - * Generating the Command Line Switches:: - * Overcoming Command Line Length Limits:: - - Finding Memory Problems with gnatmem - - * Running gnatmem (GDB Mode):: - * Running gnatmem (GMEM Mode):: - * Switches for gnatmem:: - * Examples of gnatmem Usage:: - * GDB and GMEM Modes:: - * Implementation Note:: - - - Finding Memory Problems with GNAT Debug Pool - - Creating Sample Bodies Using gnatstub - - * Running gnatstub:: - * Switches for gnatstub:: - - Reducing the Size of Ada Executables with gnatelim - - * About gnatelim:: - * Eliminate Pragma:: - * Tree Files:: - * Preparing Tree and Bind Files for gnatelim:: - * Running gnatelim:: - * Correcting the List of Eliminate Pragmas:: - * Making Your Executables Smaller:: - * Summary of the gnatelim Usage Cycle:: - - Other Utility Programs - - * Using Other Utility Programs with GNAT:: - * The gnatpsta Utility Program:: - * The External Symbol Naming Scheme of GNAT:: - * Ada Mode for Glide:: - * Converting Ada Files to html with gnathtml:: - - - Running and Debugging Ada Programs - - * The GNAT Debugger GDB:: - * Running GDB:: - * Introduction to GDB Commands:: - * Using Ada Expressions:: - * Calling User-Defined Subprograms:: - * Using the Next Command in a Function:: - * Ada Exceptions:: - * Ada Tasks:: - * Debugging Generic Units:: - * GNAT Abnormal Termination or Failure to Terminate:: - * Naming Conventions for GNAT Source Files:: - * Getting Internal Debugging Information:: - * Stack Traceback:: - - Inline Assembler - - * Basic Assembler Syntax:: - * A Simple Example of Inline Assembler:: - * Output Variables in Inline Assembler:: - * Input Variables in Inline Assembler:: - * Inlining Inline Assembler Code:: - * Other Asm Functionality:: - * A Complete Example:: - - - - Performance Considerations - - * Controlling Run-Time Checks:: - * Optimization Levels:: - * Debugging Optimized Code:: - * Inlining of Subprograms:: - - * Index:: - -  - File: gnat_ug_unx.info, Node: About This Guide, Next: Getting Started with GNAT, Prev: Top, Up: Top - - About This Guide - **************** - - This guide describes the use of GNAT, a compiler and software - development toolset for the full Ada 95 programming language. It - describes the features of the compiler and tools, and details how to - use them to build Ada 95 applications. - - * Menu: - - * What This Guide Contains:: - * What You Should Know before Reading This Guide:: - * Related Information:: - * Conventions:: - -  - File: gnat_ug_unx.info, Node: What This Guide Contains, Next: What You Should Know before Reading This Guide, Up: About This Guide - - What This Guide Contains - ======================== - - This guide contains the following chapters: - * *Note Getting Started with GNAT::, describes how to get started - compiling and running Ada programs with the GNAT Ada programming - environment. - - * *Note The GNAT Compilation Model::, describes the compilation - model used by GNAT. - - * *Note Compiling Using gcc::, describes how to compile Ada programs - with `gcc', the Ada compiler. - - * *Note Binding Using gnatbind::, describes how to perform binding - of Ada programs with `gnatbind', the GNAT binding utility. - - * *Note Linking Using gnatlink::, describes `gnatlink', a program - that provides for linking using the GNAT run-time library to - construct a program. `gnatlink' can also incorporate foreign - language object units into the executable. - - * *Note The GNAT Make Program gnatmake::, describes `gnatmake', a - utility that automatically determines the set of sources needed by - an Ada compilation unit, and executes the necessary compilations - binding and link. - - * *Note Renaming Files Using gnatchop::, describes `gnatchop', a - utility that allows you to preprocess a file that contains Ada - source code, and split it into one or more new files, one for each - compilation unit. - - * *Note Configuration Pragmas::, describes the configuration pragmas - handled by GNAT. - - * *Note Handling Arbitrary File Naming Conventions Using gnatname::, - shows how to override the default GNAT file naming conventions, - either for an individual unit or globally. - - * *Note GNAT Project Manager::, describes how to use project files - to organize large projects. - - * *Note Elaboration Order Handling in GNAT::, describes how GNAT - helps you deal with elaboration order issues. - - * *Note The Cross-Referencing Tools gnatxref and gnatfind::, - discusses `gnatxref' and `gnatfind', two tools that provide an easy - way to navigate through sources. - - * *Note File Name Krunching Using gnatkr::, describes the `gnatkr' - file name krunching utility, used to handle shortened file names - on operating systems with a limit on the length of names. - - * *Note Preprocessing Using gnatprep::, describes `gnatprep', a - preprocessor utility that allows a single source file to be used to - generate multiple or parameterized source files, by means of macro - substitution. - - * *Note The GNAT Library Browser gnatls::, describes `gnatls', a - utility that displays information about compiled units, including - dependences on the corresponding sources files, and consistency of - compilations. - - * *Note GNAT and Libraries::, describes the process of creating and - using Libraries with GNAT. It also describes how to recompile the - GNAT run-time library. - - * *Note Using the GNU make Utility::, describes some techniques for - using the GNAT toolset in Makefiles. - - * *Note Finding Memory Problems with gnatmem::, describes `gnatmem', - a utility that monitors dynamic allocation and deallocation - activity in a program, and displays information about incorrect - deallocations and sources of possible memory leaks. - - * *Note Finding Memory Problems with GNAT Debug Pool::, describes - how to use the GNAT-specific Debug Pool in order to detect as - early as possible the use of incorrect memory references. - - * *Note Creating Sample Bodies Using gnatstub::, discusses - `gnatstub', a utility that generates empty but compilable bodies - for library units. - - * *Note Reducing the Size of Ada Executables with gnatelim::, - describes `gnatelim', a tool which detects unused subprograms and - helps the compiler to create a smaller executable for the program. - - * *Note Other Utility Programs::, discusses several other GNAT - utilities, including `gnatpsta'. - - * *Note Running and Debugging Ada Programs::, describes how to run - and debug Ada programs. - - * *Note Inline Assembler::, shows how to use the inline assembly - facility in an Ada program. - - * *Note Performance Considerations::, reviews the trade offs between - using defaults or options in program development. - -  - File: gnat_ug_unx.info, Node: What You Should Know before Reading This Guide, Next: Related Information, Prev: What This Guide Contains, Up: About This Guide - - What You Should Know before Reading This Guide - ============================================== - - This user's guide assumes that you are familiar with Ada 95 language, as - described in the International Standard ANSI/ISO/IEC-8652:1995, Jan - 1995. - -  - File: gnat_ug_unx.info, Node: Related Information, Next: Conventions, Prev: What You Should Know before Reading This Guide, Up: About This Guide - - Related Information - =================== - - For further information about related tools, refer to the following - documents: - - * `GNAT Reference Manual', which contains all reference material for - the GNAT implementation of Ada 95. - - * `Ada 95 Language Reference Manual', which contains all reference - material for the Ada 95 programming language. - - * `Debugging with GDB' contains all details on the use of the GNU - source-level debugger. - - * `GNU Emacs Manual' contains full information on the extensible - editor and programming environment Emacs. - - -  - File: gnat_ug_unx.info, Node: Conventions, Prev: Related Information, Up: About This Guide - - Conventions - =========== - - Following are examples of the typographical and graphic conventions used - in this guide: - - * `Functions', `utility program names', `standard names', and - `classes'. - - * `Option flags' - - * `File Names', `button names', and `field names'. - - * VARIABLES. - - * _Emphasis_. - - * [optional information or parameters] - - * Examples are described by text - and then shown this way. - - Commands that are entered by the user are preceded in this manual by the - characters "`$ '" (dollar sign followed by space). If your system uses - this sequence as a prompt, then the commands will appear exactly as you - see them in the manual. If your system uses some other prompt, then the - command will appear with the `$' replaced by whatever prompt character - you are using. - -  - File: gnat_ug_unx.info, Node: Getting Started with GNAT, Next: The GNAT Compilation Model, Prev: About This Guide, Up: Top - - Getting Started with GNAT - ************************* - - This chapter describes some simple ways of using GNAT to build - executable Ada programs. - - * Menu: - - * Running GNAT:: - * Running a Simple Ada Program:: - - * Running a Program with Multiple Units:: - - * Using the gnatmake Utility:: - * Introduction to Glide and GVD:: - -  - File: gnat_ug_unx.info, Node: Running GNAT, Next: Running a Simple Ada Program, Up: Getting Started with GNAT - - Running GNAT - ============ - - Three steps are needed to create an executable file from an Ada source - file: - - 1. The source file(s) must be compiled. - - 2. The file(s) must be bound using the GNAT binder. - - 3. All appropriate object files must be linked to produce an - executable. - - All three steps are most commonly handled by using the `gnatmake' - utility program that, given the name of the main program, automatically - performs the necessary compilation, binding and linking steps. - -  - File: gnat_ug_unx.info, Node: Running a Simple Ada Program, Next: Running a Program with Multiple Units, Prev: Running GNAT, Up: Getting Started with GNAT - - Running a Simple Ada Program - ============================ - - Any text editor may be used to prepare an Ada program. If `Glide' is - used, the optional Ada mode may be helpful in laying out the program. - The program text is a normal text file. We will suppose in our initial - example that you have used your editor to prepare the following - standard format text file: - - with Ada.Text_IO; use Ada.Text_IO; - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - This file should be named `hello.adb'. With the normal default file - naming conventions, GNAT requires that each file contain a single - compilation unit whose file name is the unit name, with periods - replaced by hyphens; the extension is `ads' for a spec and `adb' for a - body. You can override this default file naming convention by use of - the special pragma `Source_File_Name' (*note Using Other File Names::). - Alternatively, if you want to rename your files according to this - default convention, which is probably more convenient if you will be - using GNAT for all your compilations, then the `gnatchop' utility can - be used to generate correctly-named source files (*note Renaming Files - Using gnatchop::). - - You can compile the program using the following command (`$' is used - as the command prompt in the examples in this document): - - $ gcc -c hello.adb - - `gcc' is the command used to run the compiler. This compiler is capable - of compiling programs in several languages, including Ada 95 and C. It - assumes that you have given it an Ada program if the file extension is - either `.ads' or `.adb', and it will then call the GNAT compiler to - compile the specified file. - - The `-c' switch is required. It tells `gcc' to only do a - compilation. (For C programs, `gcc' can also do linking, but this - capability is not used directly for Ada programs, so the `-c' switch - must always be present.) - - This compile command generates a file `hello.o', which is the object - file corresponding to your Ada program. It also generates an "Ada - Library Information" file `hello.ali', which contains additional - information used to check that an Ada program is consistent. To build - an executable file, use `gnatbind' to bind the program and `gnatlink' - to link it. The argument to both `gnatbind' and `gnatlink' is the name - of the `ali' file, but the default extension of `.ali' can be omitted. - This means that in the most common case, the argument is simply the - name of the main program: - - $ gnatbind hello - $ gnatlink hello - - A simpler method of carrying out these steps is to use `gnatmake', a - master program that invokes all the required compilation, binding and - linking tools in the correct order. In particular, `gnatmake' - automatically recompiles any sources that have been modified since they - were last compiled, or sources that depend on such modified sources, so - that "version skew" is avoided. - - $ gnatmake hello.adb - - The result is an executable program called `hello', which can be run by - entering: - - $ hello - - assuming that the current directory is on the search path for - executable programs. - - and, if all has gone well, you will see - - Hello WORLD! - - appear in response to this command. - -  - File: gnat_ug_unx.info, Node: Running a Program with Multiple Units, Next: Using the gnatmake Utility, Prev: Running a Simple Ada Program, Up: Getting Started with GNAT - - Running a Program with Multiple Units - ===================================== - - Consider a slightly more complicated example that has three files: a - main program, and the spec and body of a package: - - package Greetings is - procedure Hello; - procedure Goodbye; - end Greetings; - - with Ada.Text_IO; use Ada.Text_IO; - package body Greetings is - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - procedure Goodbye is - begin - Put_Line ("Goodbye WORLD!"); - end Goodbye; - end Greetings; - - with Greetings; - procedure Gmain is - begin - Greetings.Hello; - Greetings.Goodbye; - end Gmain; - - Following the one-unit-per-file rule, place this program in the - following three separate files: - - `greetings.ads' - spec of package `Greetings' - - `greetings.adb' - body of package `Greetings' - - `gmain.adb' - body of main program - - To build an executable version of this program, we could use four - separate steps to compile, bind, and link the program, as follows: - - $ gcc -c gmain.adb - $ gcc -c greetings.adb - $ gnatbind gmain - $ gnatlink gmain - - Note that there is no required order of compilation when using GNAT. - In particular it is perfectly fine to compile the main program first. - Also, it is not necessary to compile package specs in the case where - there is an accompanying body; you only need to compile the body. If - you want to submit these files to the compiler for semantic checking - and not code generation, then use the `-gnatc' switch: - - $ gcc -c greetings.ads -gnatc - - Although the compilation can be done in separate steps as in the above - example, in practice it is almost always more convenient to use the - `gnatmake' tool. All you need to know in this case is the name of the - main program's source file. The effect of the above four commands can - be achieved with a single one: - - $ gnatmake gmain.adb - - In the next section we discuss the advantages of using `gnatmake' in - more detail. - -  - File: gnat_ug_unx.info, Node: Using the gnatmake Utility, Next: Introduction to Glide and GVD, Prev: Running a Program with Multiple Units, Up: Getting Started with GNAT - - Using the `gnatmake' Utility - ============================ - - If you work on a program by compiling single components at a time using - `gcc', you typically keep track of the units you modify. In order to - build a consistent system, you compile not only these units, but also - any units that depend on the units you have modified. For example, in - the preceding case, if you edit `gmain.adb', you only need to recompile - that file. But if you edit `greetings.ads', you must recompile both - `greetings.adb' and `gmain.adb', because both files contain units that - depend on `greetings.ads'. - - `gnatbind' will warn you if you forget one of these compilation - steps, so that it is impossible to generate an inconsistent program as a - result of forgetting to do a compilation. Nevertheless it is tedious and - error-prone to keep track of dependencies among units. One approach to - handle the dependency-bookkeeping is to use a makefile. However, - makefiles present maintenance problems of their own: if the - dependencies change as you change the program, you must make sure that - the makefile is kept up-to-date manually, which is also an error-prone - process. - - The `gnatmake' utility takes care of these details automatically. - Invoke it using either one of the following forms: - - $ gnatmake gmain.adb - $ gnatmake gmain - - The argument is the name of the file containing the main program; you - may omit the extension. `gnatmake' examines the environment, - automatically recompiles any files that need recompiling, and binds and - links the resulting set of object files, generating the executable - file, `gmain'. In a large program, it can be extremely helpful to use - `gnatmake', because working out by hand what needs to be recompiled can - be difficult. - - Note that `gnatmake' takes into account all the Ada 95 rules that - establish dependencies among units. These include dependencies that - result from inlining subprogram bodies, and from generic instantiation. - Unlike some other Ada make tools, `gnatmake' does not rely on the - dependencies that were found by the compiler on a previous compilation, - which may possibly be wrong when sources change. `gnatmake' determines - the exact set of dependencies from scratch each time it is run. - -  - File: gnat_ug_unx.info, Node: Introduction to Glide and GVD, Prev: Using the gnatmake Utility, Up: Getting Started with GNAT - - Introduction to Glide and GVD - ============================= - - Although it is possible to develop programs using only the command line - interface (`gnatmake', etc.) a graphical Interactive Development - Environment can make it easier for you to compose, navigate, and debug - programs. This section describes the main features of Glide, the GNAT - graphical IDE, and also shows how to use the basic commands in GVD, the - GNU Visual Debugger. Additional information may be found in the - on-line help for these tools. - - * Menu: - - * Building a New Program with Glide:: - * Simple Debugging with GVD:: - * Other Glide Features:: - -  - File: gnat_ug_unx.info, Node: Building a New Program with Glide, Next: Simple Debugging with GVD, Up: Introduction to Glide and GVD - - Building a New Program with Glide - --------------------------------- - - The simplest way to invoke Glide is to enter `glide' at the command - prompt. It will generally be useful to issue this as a background - command, thus allowing you to continue using your command window for - other purposes while Glide is running: - - $ glide& - - Glide will start up with an initial screen displaying the top-level - menu items as well as some other information. The menu selections are - as follows - * `Buffers' - - * `Files' - - * `Tools' - - * `Edit' - - * `Search' - - * `Mule' - - * `Glide' - - * `Help' - - For this introductory example, you will need to create a new Ada source - file. First, select the `Files' menu. This will pop open a menu with - around a dozen or so items. To create a file, select the `Open - file...' choice. Depending on the platform, you may see a pop-up - window where you can browse to an appropriate directory and then enter - the file name, or else simply see a line at the bottom of the Glide - window where you can likewise enter the file name. Note that in Glide, - when you attempt to open a non-existent file, the effect is to create a - file with that name. For this example enter `hello.adb' as the name of - the file. - - A new buffer will now appear, occupying the entire Glide window, - with the file name at the top. The menu selections are slightly - different from the ones you saw on the opening screen; there is an - `Entities' item, and in place of `Glide' there is now an `Ada' item. - Glide uses the file extension to identify the source language, so `adb' - indicates an Ada source file. - - You will enter some of the source program lines explicitly, and use - the syntax-oriented template mechanism to enter other lines. First, - type the following text: - with Ada.Text_IO; use Ada.Text_IO; - procedure Hello is - begin - - Observe that Glide uses different colors to distinguish reserved words - from identifiers. Also, after the `procedure Hello is' line, the - cursor is automatically indented in anticipation of declarations. When - you enter `begin', Glide recognizes that there are no declarations and - thus places `begin' flush left. But after the `begin' line the cursor - is again indented, where the statement(s) will be placed. - - The main part of the program will be a `for' loop. Instead of - entering the text explicitly, however, use a statement template. - Select the `Ada' item on the top menu bar, move the mouse to the - `Statements' item, and you will see a large selection of alternatives. - Choose `for loop'. You will be prompted (at the bottom of the buffer) - for a loop name; simply press the key since a loop name is not - needed. You should see the beginning of a `for' loop appear in the - source program window. You will now be prompted for the name of the - loop variable; enter a line with the identifier `ind' (lower case). - Note that, by default, Glide capitalizes the name (you can override - such behavior if you wish, although this is outside the scope of this - introduction). Next, Glide prompts you for the loop range; enter a - line containing `1..5' and you will see this also appear in the source - program, together with the remaining elements of the `for' loop syntax. - - Next enter the statement (with an intentional error, a missing - semicolon) that will form the body of the loop: - Put_Line("Hello, World" & Integer'Image(I)) - - Finally, type `end Hello;' as the last line in the program. Now save - the file: choose the `File' menu item, and then the `Save buffer' - selection. You will see a message at the bottom of the buffer - confirming that the file has been saved. - - You are now ready to attempt to build the program. Select the `Ada' - item from the top menu bar. Although we could choose simply to compile - the file, we will instead attempt to do a build (which invokes - `gnatmake') since, if the compile is successful, we want to build an - executable. Thus select `Ada build'. This will fail because of the - compilation error, and you will notice that the Glide window has been - split: the top window contains the source file, and the bottom window - contains the output from the GNAT tools. Glide allows you to navigate - from a compilation error to the source file position corresponding to - the error: click the middle mouse button (or simultaneously press the - left and right buttons, on a two-button mouse) on the diagnostic line - in the tool window. The focus will shift to the source window, and the - cursor will be positioned on the character at which the error was - detected. - - Correct the error: type in a semicolon to terminate the statement. - Although you can again save the file explicitly, you can also simply - invoke `Ada' => `Build' and you will be prompted to save the file. - This time the build will succeed; the tool output window shows you the - options that are supplied by default. The GNAT tools' output (e.g., - object and ALI files, executable) will go in the directory from which - Glide was launched. - - To execute the program, choose `Ada' and then `Run'. You should see - the program's output displayed in the bottom window: - - Hello, world 1 - Hello, world 2 - Hello, world 3 - Hello, world 4 - Hello, world 5 - -  - File: gnat_ug_unx.info, Node: Simple Debugging with GVD, Next: Other Glide Features, Prev: Building a New Program with Glide, Up: Introduction to Glide and GVD - - Simple Debugging with GVD - ------------------------- - - This section describes how to set breakpoints, examine/modify - variables, and step through execution. - - In order to enable debugging, you need to pass the `-g' switch to - both the compiler and to `gnatlink'. If you are using the command - line, passing `-g' to `gnatmake' will have this effect. You can then - launch GVD, e.g. on the `hello' program, by issuing the command: - - $ gvd hello - - If you are using Glide, then `-g' is passed to the relevant tools by - default when you do a build. Start the debugger by selecting the `Ada' - menu item, and then `Debug'. - - GVD comes up in a multi-part window. One pane shows the names of - files comprising your executable; another pane shows the source code of - the current unit (initially your main subprogram), another pane shows - the debugger output and user interactions, and the fourth pane (the - data canvas at the top of the window) displays data objects that you - have selected. - - To the left of the source file pane, you will notice green dots - adjacent to some lines. These are lines for which object code exists - and where breakpoints can thus be set. You set/reset a breakpoint by - clicking the green dot. When a breakpoint is set, the dot is replaced - by an `X' in a red circle. Clicking the circle toggles the breakpoint - off, and the red circle is replaced by the green dot. - - For this example, set a breakpoint at the statement where `Put_Line' - is invoked. - - Start program execution by selecting the `Run' button on the top - menu bar. (The `Start' button will also start your program, but it - will cause program execution to break at the entry to your main - subprogram.) Evidence of reaching the breakpoint will appear: the - source file line will be highlighted, and the debugger interactions - pane will display a relevant message. - - You can examine the values of variables in several ways. Move the - mouse over an occurrence of `Ind' in the `for' loop, and you will see - the value (now `1') displayed. Alternatively, right-click on `Ind' and - select `Display Ind'; a box showing the variable's name and value will - appear in the data canvas. - - Although a loop index is a constant with respect to Ada semantics, - you can change its value in the debugger. Right-click in the box for - `Ind', and select the `Set Value of Ind' item. Enter `2' as the new - value, and press `OK'. The box for `Ind' shows the update. - - Press the `Step' button on the top menu bar; this will step through - one line of program text (the invocation of `Put_Line'), and you can - observe the effect of having modified `Ind' since the value displayed - is `2'. - - Remove the breakpoint, and resume execution by selecting the `Cont' - button. You will see the remaining output lines displayed in the - debugger interaction window, along with a message confirming normal - program termination. - -  - File: gnat_ug_unx.info, Node: Other Glide Features, Prev: Simple Debugging with GVD, Up: Introduction to Glide and GVD - - Other Glide Features - -------------------- - - You may have observed that some of the menu selections contain - abbreviations; e.g., `(C-x C-f)' for `Open file...' in the `Files' - menu. These are _shortcut keys_ that you can use instead of selecting - menu items. The stands for ; thus `(C-x C-f)' means - followed by , and this sequence can be used instead of - selecting `Files' and then `Open file...'. - - To abort a Glide command, type . - - If you want Glide to start with an existing source file, you can - either launch Glide as above and then open the file via `Files' => - `Open file...', or else simply pass the name of the source file on the - command line: - - $ glide hello.adb& - - While you are using Glide, a number of _buffers_ exist. You create - some explicitly; e.g., when you open/create a file. Others arise as an - effect of the commands that you issue; e.g., the buffer containing the - output of the tools invoked during a build. If a buffer is hidden, you - can bring it into a visible window by first opening the `Buffers' menu - and then selecting the desired entry. - - If a buffer occupies only part of the Glide screen and you want to - expand it to fill the entire screen, then click in the buffer and then - select `Files' => `One Window'. - - If a window is occupied by one buffer and you want to split the - window to bring up a second buffer, perform the following steps: - * Select `Files' => `Split Window'; this will produce two windows - each of which holds the original buffer (these are not copies, but - rather different views of the same buffer contents) - - * With the focus in one of the windows, select the desired buffer - from the `Buffers' menu - - To exit from Glide, choose `Files' => `Exit'. - -  - File: gnat_ug_unx.info, Node: The GNAT Compilation Model, Next: Compiling Using gcc, Prev: Getting Started with GNAT, Up: Top - - The GNAT Compilation Model - ************************** - - * Menu: - - * Source Representation:: - * Foreign Language Representation:: - * File Naming Rules:: - * Using Other File Names:: - * Alternative File Naming Schemes:: - * Generating Object Files:: - * Source Dependencies:: - * The Ada Library Information Files:: - * Binding an Ada Program:: - * Mixed Language Programming:: - * Building Mixed Ada & C++ Programs:: - * Comparison between GNAT and C/C++ Compilation Models:: - * Comparison between GNAT and Conventional Ada Library Models:: - - This chapter describes the compilation model used by GNAT. Although - similar to that used by other languages, such as C and C++, this model - is substantially different from the traditional Ada compilation models, - which are based on a library. The model is initially described without - reference to the library-based model. If you have not previously used an - Ada compiler, you need only read the first part of this chapter. The - last section describes and discusses the differences between the GNAT - model and the traditional Ada compiler models. If you have used other - Ada compilers, this section will help you to understand those - differences, and the advantages of the GNAT model. - -  - File: gnat_ug_unx.info, Node: Source Representation, Next: Foreign Language Representation, Up: The GNAT Compilation Model - - Source Representation - ===================== - - Ada source programs are represented in standard text files, using - Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar - 7-bit ASCII set, plus additional characters used for representing - foreign languages (*note Foreign Language Representation:: for support - of non-USA character sets). The format effector characters are - represented using their standard ASCII encodings, as follows: - - `VT' - Vertical tab, `16#0B#' - - `HT' - Horizontal tab, `16#09#' - - `CR' - Carriage return, `16#0D#' - - `LF' - Line feed, `16#0A#' - - `FF' - Form feed, `16#0C#' - - Source files are in standard text file format. In addition, GNAT will - recognize a wide variety of stream formats, in which the end of physical - physical lines is marked by any of the following sequences: `LF', `CR', - `CR-LF', or `LF-CR'. This is useful in accommodating files that are - imported from other operating systems. - - The end of a source file is normally represented by the physical end - of file. However, the control character `16#1A#' (`SUB') is also - recognized as signalling the end of the source file. Again, this is - provided for compatibility with other operating systems where this code - is used to represent the end of file. - - Each file contains a single Ada compilation unit, including any - pragmas associated with the unit. For example, this means you must - place a package declaration (a package "spec") and the corresponding - body in separate files. An Ada "compilation" (which is a sequence of - compilation units) is represented using a sequence of files. Similarly, - you will place each subunit or child unit in a separate file. - -  - File: gnat_ug_unx.info, Node: Foreign Language Representation, Next: File Naming Rules, Prev: Source Representation, Up: The GNAT Compilation Model - - Foreign Language Representation - =============================== - - GNAT supports the standard character sets defined in Ada 95 as well as - several other non-standard character sets for use in localized versions - of the compiler (*note Character Set Control::). - - * Menu: - - * Latin-1:: - * Other 8-Bit Codes:: - * Wide Character Encodings:: - -  - File: gnat_ug_unx.info, Node: Latin-1, Next: Other 8-Bit Codes, Up: Foreign Language Representation - - Latin-1 - ------- - - The basic character set is Latin-1. This character set is defined by ISO - standard 8859, part 1. The lower half (character codes `16#00#' ... - `16#7F#)' is identical to standard ASCII coding, but the upper half is - used to represent additional characters. These include extended letters - used by European languages, such as French accents, the vowels with - umlauts used in German, and the extra letter A-ring used in Swedish. - - For a complete list of Latin-1 codes and their encodings, see the - source file of library unit `Ada.Characters.Latin_1' in file - `a-chlat1.ads'. You may use any of these extended characters freely in - character or string literals. In addition, the extended characters that - represent letters can be used in identifiers. - -  - File: gnat_ug_unx.info, Node: Other 8-Bit Codes, Next: Wide Character Encodings, Prev: Latin-1, Up: Foreign Language Representation - - Other 8-Bit Codes - ----------------- - - GNAT also supports several other 8-bit coding schemes: - - Latin-2 - Latin-2 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-3 - Latin-3 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-4 - Latin-4 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-5 - Latin-4 letters (Cyrillic) allowed in identifiers, with uppercase - and lowercase equivalence. - - IBM PC (code page 437) - This code page is the normal default for PCs in the U.S. It - corresponds to the original IBM PC character set. This set has - some, but not all, of the extended Latin-1 letters, but these - letters do not have the same encoding as Latin-1. In this mode, - these letters are allowed in identifiers with uppercase and - lowercase equivalence. - - IBM PC (code page 850) - This code page is a modification of 437 extended to include all the - Latin-1 letters, but still not with the usual Latin-1 encoding. In - this mode, all these letters are allowed in identifiers with - uppercase and lowercase equivalence. - - Full Upper 8-bit - Any character in the range 80-FF allowed in identifiers, and all - are considered distinct. In other words, there are no uppercase - and lowercase equivalences in this range. This is useful in - conjunction with certain encoding schemes used for some foreign - character sets (e.g. the typical method of representing Chinese - characters on the PC). - - No Upper-Half - No upper-half characters in the range 80-FF are allowed in - identifiers. This gives Ada 83 compatibility for identifier names. - - For precise data on the encodings permitted, and the uppercase and - lowercase equivalences that are recognized, see the file `csets.adb' in - the GNAT compiler sources. You will need to obtain a full source release - of GNAT to obtain this file. - -  - File: gnat_ug_unx.info, Node: Wide Character Encodings, Prev: Other 8-Bit Codes, Up: Foreign Language Representation - - Wide Character Encodings - ------------------------ - - GNAT allows wide character codes to appear in character and string - literals, and also optionally in identifiers, by means of the following - possible encoding schemes: - - Hex Coding - In this encoding, a wide character is represented by the following - five character sequence: - - ESC a b c d - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For example, - ESC A345 is used to represent the wide character with code - `16#A345#'. This scheme is compatible with use of the full - Wide_Character set. - - Upper-Half Coding - The wide character with encoding `16#abcd#' where the upper bit is - on (in other words, "a" is in the range 8-F) is represented as two - bytes, `16#ab#' and `16#cd#'. The second byte cannot be a format - control character, but is not required to be in the upper half. - This method can be also used for shift-JIS or EUC, where the - internal coding matches the external coding. - - Shift JIS Coding - A wide character is represented by a two-character sequence, - `16#ab#' and `16#cd#', with the restrictions described for - upper-half encoding as described above. The internal character - code is the corresponding JIS character according to the standard - algorithm for Shift-JIS conversion. Only characters defined in the - JIS code set table can be used with this encoding method. - - EUC Coding - A wide character is represented by a two-character sequence - `16#ab#' and `16#cd#', with both characters being in the upper - half. The internal character code is the corresponding JIS - character according to the EUC encoding algorithm. Only characters - defined in the JIS code set table can be used with this encoding - method. - - UTF-8 Coding - A wide character is represented using UCS Transformation Format 8 - (UTF-8) as defined in Annex R of ISO 10646-1/Am.2. Depending on - the character value, the representation is a one, two, or three - byte sequence: - 16#0000#-16#007f#: 2#0xxxxxxx# - 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# - 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# - - where the xxx bits correspond to the left-padded bits of the - 16-bit character value. Note that all lower half ASCII characters - are represented as ASCII bytes and all upper half characters and - other wide characters are represented as sequences of upper-half - (The full UTF-8 scheme allows for encoding 31-bit characters as - 6-byte sequences, but in this implementation, all UTF-8 sequences - of four or more bytes length will be treated as illegal). - - Brackets Coding - In this encoding, a wide character is represented by the following - eight character sequence: - - [ " a b c d " ] - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For example, - ["A345"] is used to represent the wide character with code - `16#A345#'. It is also possible (though not required) to use the - Brackets coding for upper half characters. For example, the code - `16#A3#' can be represented as `["A3"]'. - - This scheme is compatible with use of the full Wide_Character set, - and is also the method used for wide character encoding in the - standard ACVC (Ada Compiler Validation Capability) test suite - distributions. - - Note: Some of these coding schemes do not permit the full use of the - Ada 95 character set. For example, neither Shift JIS, nor EUC allow the - use of the upper half of the Latin-1 set. - -  - File: gnat_ug_unx.info, Node: File Naming Rules, Next: Using Other File Names, Prev: Foreign Language Representation, Up: The GNAT Compilation Model - - File Naming Rules - ================= - - The default file name is determined by the name of the unit that the - file contains. The name is formed by taking the full expanded name of - the unit and replacing the separating dots with hyphens and using - lowercase for all letters. - - An exception arises if the file name generated by the above rules - starts with one of the characters a,g,i, or s, and the second character - is a minus. In this case, the character tilde is used in place of the - minus. The reason for this special rule is to avoid clashes with the - standard names for child units of the packages System, Ada, Interfaces, - and GNAT, which use the prefixes s- a- i- and g- respectively. - - The file extension is `.ads' for a spec and `.adb' for a body. The - following list shows some examples of these rules. - - `main.ads' - Main (spec) - - `main.adb' - Main (body) - - `arith_functions.ads' - Arith_Functions (package spec) - - `arith_functions.adb' - Arith_Functions (package body) - - `func-spec.ads' - Func.Spec (child package spec) - - `func-spec.adb' - Func.Spec (child package body) - - `main-sub.adb' - Sub (subunit of Main) - - `a~bad.adb' - A.Bad (child package body) - - Following these rules can result in excessively long file names if - corresponding unit names are long (for example, if child units or - subunits are heavily nested). An option is available to shorten such - long file names (called file name "krunching"). This may be - particularly useful when programs being developed with GNAT are to be - used on operating systems with limited file name lengths. *Note Using - gnatkr::. - - Of course, no file shortening algorithm can guarantee uniqueness over - all possible unit names; if file name krunching is used, it is your - responsibility to ensure no name clashes occur. Alternatively you can - specify the exact file names that you want used, as described in the - next section. Finally, if your Ada programs are migrating from a - compiler with a different naming convention, you can use the gnatchop - utility to produce source files that follow the GNAT naming conventions. - (For details *note Renaming Files Using gnatchop::.) - -  - File: gnat_ug_unx.info, Node: Using Other File Names, Next: Alternative File Naming Schemes, Prev: File Naming Rules, Up: The GNAT Compilation Model - - Using Other File Names - ====================== - - In the previous section, we have described the default rules used by - GNAT to determine the file name in which a given unit resides. It is - often convenient to follow these default rules, and if you follow them, - the compiler knows without being explicitly told where to find all the - files it needs. - - However, in some cases, particularly when a program is imported from - another Ada compiler environment, it may be more convenient for the - programmer to specify which file names contain which units. GNAT allows - arbitrary file names to be used by means of the Source_File_Name pragma. - The form of this pragma is as shown in the following examples: - - pragma Source_File_Name (My_Utilities.Stacks, - Spec_File_Name => "myutilst_a.ada"); - pragma Source_File_name (My_Utilities.Stacks, - Body_File_Name => "myutilst.ada"); - - As shown in this example, the first argument for the pragma is the unit - name (in this example a child unit). The second argument has the form - of a named association. The identifier indicates whether the file name - is for a spec or a body; the file name itself is given by a string - literal. - - The source file name pragma is a configuration pragma, which means - that normally it will be placed in the `gnat.adc' file used to hold - configuration pragmas that apply to a complete compilation environment. - For more details on how the `gnat.adc' file is created and used *note - Handling of Configuration Pragmas:: - - GNAT allows completely arbitrary file names to be specified using the - source file name pragma. However, if the file name specified has an - extension other than `.ads' or `.adb' it is necessary to use a special - syntax when compiling the file. The name in this case must be preceded - by the special sequence `-x' followed by a space and the name of the - language, here `ada', as in: - - $ gcc -c -x ada peculiar_file_name.sim - - `gnatmake' handles non-standard file names in the usual manner (the - non-standard file name for the main program is simply used as the - argument to gnatmake). Note that if the extension is also non-standard, - then it must be included in the gnatmake command, it may not be omitted. - -  - File: gnat_ug_unx.info, Node: Alternative File Naming Schemes, Next: Generating Object Files, Prev: Using Other File Names, Up: The GNAT Compilation Model - - Alternative File Naming Schemes - =============================== - - In the previous section, we described the use of the - `Source_File_Name' pragma to allow arbitrary names to be assigned to - individual source files. However, this approach requires one pragma - for each file, and especially in large systems can result in very long - `gnat.adc' files, and also create a maintenance problem. - - GNAT also provides a facility for specifying systematic file naming - schemes other than the standard default naming scheme previously - described. An alternative scheme for naming is specified by the use of - `Source_File_Name' pragmas having the following format: - - pragma Source_File_Name ( - Spec_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name ( - Body_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name ( - Subunit_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - FILE_NAME_PATTERN ::= STRING_LITERAL - CASING_SPEC ::= Lowercase | Uppercase | Mixedcase - - The `FILE_NAME_PATTERN' string shows how the file name is constructed. - It contains a single asterisk character, and the unit name is - substituted systematically for this asterisk. The optional parameter - `Casing' indicates whether the unit name is to be all upper-case - letters, all lower-case letters, or mixed-case. If no `Casing' - parameter is used, then the default is all lower-case. - - The optional `Dot_Replacement' string is used to replace any periods - that occur in subunit or child unit names. If no `Dot_Replacement' - argument is used then separating dots appear unchanged in the resulting - file name. Although the above syntax indicates that the `Casing' - argument must appear before the `Dot_Replacement' argument, but it is - also permissible to write these arguments in the opposite order. - - As indicated, it is possible to specify different naming schemes for - bodies, specs, and subunits. Quite often the rule for subunits is the - same as the rule for bodies, in which case, there is no need to give a - separate `Subunit_File_Name' rule, and in this case the - `Body_File_name' rule is used for subunits as well. - - The separate rule for subunits can also be used to implement the - rather unusual case of a compilation environment (e.g. a single - directory) which contains a subunit and a child unit with the same unit - name. Although both units cannot appear in the same partition, the Ada - Reference Manual allows (but does not require) the possibility of the - two units coexisting in the same environment. - - The file name translation works in the following steps: - - * If there is a specific `Source_File_Name' pragma for the given - unit, then this is always used, and any general pattern rules are - ignored. - - * If there is a pattern type `Source_File_Name' pragma that applies - to the unit, then the resulting file name will be used if the file - exists. If more than one pattern matches, the latest one will be - tried first, and the first attempt resulting in a reference to a - file that exists will be used. - - * If no pattern type `Source_File_Name' pragma that applies to the - unit for which the corresponding file exists, then the standard - GNAT default naming rules are used. - - - As an example of the use of this mechanism, consider a commonly used - scheme in which file names are all lower case, with separating periods - copied unchanged to the resulting file name, and specs end with - ".1.ada", and bodies end with ".2.ada". GNAT will follow this scheme if - the following two pragmas appear: - - pragma Source_File_Name - (Spec_File_Name => "*.1.ada"); - pragma Source_File_Name - (Body_File_Name => "*.2.ada"); - - The default GNAT scheme is actually implemented by providing the - following default pragmas internally: - - pragma Source_File_Name - (Spec_File_Name => "*.ads", Dot_Replacement => "-"); - pragma Source_File_Name - (Body_File_Name => "*.adb", Dot_Replacement => "-"); - - Our final example implements a scheme typically used with one of the - Ada 83 compilers, where the separator character for subunits was "__" - (two underscores), specs were identified by adding `_.ADA', bodies by - adding `.ADA', and subunits by adding `.SEP'. All file names were upper - case. Child units were not present of course since this was an Ada 83 - compiler, but it seems reasonable to extend this scheme to use the same - double underscore separator for child units. - - pragma Source_File_Name - (Spec_File_Name => "*_.ADA", - Dot_Replacement => "__", - Casing = Uppercase); - pragma Source_File_Name - (Body_File_Name => "*.ADA", - Dot_Replacement => "__", - Casing = Uppercase); - pragma Source_File_Name - (Subunit_File_Name => "*.SEP", - Dot_Replacement => "__", - Casing = Uppercase); - -  - File: gnat_ug_unx.info, Node: Generating Object Files, Next: Source Dependencies, Prev: Alternative File Naming Schemes, Up: The GNAT Compilation Model - - Generating Object Files - ======================= - - An Ada program consists of a set of source files, and the first step in - compiling the program is to generate the corresponding object files. - These are generated by compiling a subset of these source files. The - files you need to compile are the following: - - * If a package spec has no body, compile the package spec to produce - the object file for the package. - - * If a package has both a spec and a body, compile the body to - produce the object file for the package. The source file for the - package spec need not be compiled in this case because there is - only one object file, which contains the code for both the spec - and body of the package. - - * For a subprogram, compile the subprogram body to produce the - object file for the subprogram. The spec, if one is present, is as - usual in a separate file, and need not be compiled. - - * In the case of subunits, only compile the parent unit. A single - object file is generated for the entire subunit tree, which - includes all the subunits. - - * Compile child units independently of their parent units (though, - of course, the spec of all the ancestor unit must be present in - order to compile a child unit). - - * Compile generic units in the same manner as any other units. The - object files in this case are small dummy files that contain at - most the flag used for elaboration checking. This is because GNAT - always handles generic instantiation by means of macro expansion. - However, it is still necessary to compile generic units, for - dependency checking and elaboration purposes. - - The preceding rules describe the set of files that must be compiled to - generate the object files for a program. Each object file has the same - name as the corresponding source file, except that the extension is - `.o' as usual. - - You may wish to compile other files for the purpose of checking their - syntactic and semantic correctness. For example, in the case where a - package has a separate spec and body, you would not normally compile the - spec. However, it is convenient in practice to compile the spec to make - sure it is error-free before compiling clients of this spec, because - such compilations will fail if there is an error in the spec. - - GNAT provides an option for compiling such files purely for the - purposes of checking correctness; such compilations are not required as - part of the process of building a program. To compile a file in this - checking mode, use the `-gnatc' switch. - -  - File: gnat_ug_unx.info, Node: Source Dependencies, Next: The Ada Library Information Files, Prev: Generating Object Files, Up: The GNAT Compilation Model - - Source Dependencies - =================== - - A given object file clearly depends on the source file which is compiled - to produce it. Here we are using "depends" in the sense of a typical - `make' utility; in other words, an object file depends on a source file - if changes to the source file require the object file to be recompiled. - In addition to this basic dependency, a given object may depend on - additional source files as follows: - - * If a file being compiled `with''s a unit X, the object file - depends on the file containing the spec of unit X. This includes - files that are `with''ed implicitly either because they are parents - of `with''ed child units or they are run-time units required by the - language constructs used in a particular unit. - - * If a file being compiled instantiates a library level generic - unit, the object file depends on both the spec and body files for - this generic unit. - - * If a file being compiled instantiates a generic unit defined - within a package, the object file depends on the body file for the - package as well as the spec file. - - * If a file being compiled contains a call to a subprogram for which - pragma `Inline' applies and inlining is activated with the - `-gnatn' switch, the object file depends on the file containing the - body of this subprogram as well as on the file containing the - spec. Note that for inlining to actually occur as a result of the - use of this switch, it is necessary to compile in optimizing mode. - - The use of `-gnatN' activates a more extensive inlining - optimization that is performed by the front end of the compiler. - This inlining does not require that the code generation be - optimized. Like `-gnatn', the use of this switch generates - additional dependencies. - - * If an object file O depends on the proper body of a subunit - through inlining or instantiation, it depends on the parent unit - of the subunit. This means that any modification of the parent - unit or one of its subunits affects the compilation of O. - - * The object file for a parent unit depends on all its subunit body - files. - - * The previous two rules meant that for purposes of computing - dependencies and recompilation, a body and all its subunits are - treated as an indivisible whole. - - These rules are applied transitively: if unit `A' `with''s unit - `B', whose elaboration calls an inlined procedure in package `C', - the object file for unit `A' will depend on the body of `C', in - file `c.adb'. - - The set of dependent files described by these rules includes all - the files on which the unit is semantically dependent, as - described in the Ada 95 Language Reference Manual. However, it is - a superset of what the ARM describes, because it includes generic, - inline, and subunit dependencies. - - An object file must be recreated by recompiling the corresponding - source file if any of the source files on which it depends are - modified. For example, if the `make' utility is used to control - compilation, the rule for an Ada object file must mention all the - source files on which the object file depends, according to the - above definition. The determination of the necessary - recompilations is done automatically when one uses `gnatmake'. - -  - File: gnat_ug_unx.info, Node: The Ada Library Information Files, Next: Binding an Ada Program, Prev: Source Dependencies, Up: The GNAT Compilation Model - - The Ada Library Information Files - ================================= - - Each compilation actually generates two output files. The first of these - is the normal object file that has a `.o' extension. The second is a - text file containing full dependency information. It has the same name - as the source file, but an `.ali' extension. This file is known as the - Ada Library Information (`ali') file. The following information is - contained in the `ali' file. - - * Version information (indicates which version of GNAT was used to - compile the unit(s) in question) - - * Main program information (including priority and time slice - settings, as well as the wide character encoding used during - compilation). - - * List of arguments used in the `gcc' command for the compilation - - * Attributes of the unit, including configuration pragmas used, an - indication of whether the compilation was successful, exception - model used etc. - - * A list of relevant restrictions applying to the unit (used for - consistency) checking. - - * Categorization information (e.g. use of pragma `Pure'). - - * Information on all `with''ed units, including presence of - `Elaborate' or `Elaborate_All' pragmas. - - * Information from any `Linker_Options' pragmas used in the unit - - * Information on the use of `Body_Version' or `Version' attributes - in the unit. - - * Dependency information. This is a list of files, together with - time stamp and checksum information. These are files on which the - unit depends in the sense that recompilation is required if any of - these units are modified. - - * Cross-reference data. Contains information on all entities - referenced in the unit. Used by tools like `gnatxref' and - `gnatfind' to provide cross-reference information. - - - For a full detailed description of the format of the `ali' file, see - the source of the body of unit `Lib.Writ', contained in file - `lib-writ.adb' in the GNAT compiler sources. - -  - File: gnat_ug_unx.info, Node: Binding an Ada Program, Next: Mixed Language Programming, Prev: The Ada Library Information Files, Up: The GNAT Compilation Model - - Binding an Ada Program - ====================== - - When using languages such as C and C++, once the source files have been - compiled the only remaining step in building an executable program is - linking the object modules together. This means that it is possible to - link an inconsistent version of a program, in which two units have - included different versions of the same header. - - The rules of Ada do not permit such an inconsistent program to be - built. For example, if two clients have different versions of the same - package, it is illegal to build a program containing these two clients. - These rules are enforced by the GNAT binder, which also determines an - elaboration order consistent with the Ada rules. - - The GNAT binder is run after all the object files for a program have - been created. It is given the name of the main program unit, and from - this it determines the set of units required by the program, by reading - the corresponding ALI files. It generates error messages if the program - is inconsistent or if no valid order of elaboration exists. - - If no errors are detected, the binder produces a main program, in - Ada by default, that contains calls to the elaboration procedures of - those compilation unit that require them, followed by a call to the - main program. This Ada program is compiled to generate the object file - for the main program. The name of the Ada file is `b~XXX.adb' (with the - corresponding spec `b~XXX.ads') where XXX is the name of the main - program unit. - - Finally, the linker is used to build the resulting executable - program, using the object from the main program from the bind step as - well as the object files for the Ada units of the program. - -  - File: gnat_ug_unx.info, Node: Mixed Language Programming, Next: Building Mixed Ada & C++ Programs, Prev: Binding an Ada Program, Up: The GNAT Compilation Model - - Mixed Language Programming - ========================== - - * Menu: - - * Interfacing to C:: - * Calling Conventions:: - -  - File: gnat_ug_unx.info, Node: Interfacing to C, Next: Calling Conventions, Up: Mixed Language Programming - - Interfacing to C - ---------------- - - There are two ways to build a program that contains some Ada files and - some other language files depending on whether the main program is in - Ada or not. If the main program is in Ada, you should proceed as - follows: - - 1. Compile the other language files to generate object files. For - instance: - gcc -c file1.c - gcc -c file2.c - - 2. Compile the Ada units to produce a set of object files and ALI - files. For instance: - gnatmake -c my_main.adb - - 3. Run the Ada binder on the Ada main program. For instance: - gnatbind my_main.ali - - 4. Link the Ada main program, the Ada objects and the other language - objects. For instance: - gnatlink my_main.ali file1.o file2.o - - The three last steps can be grouped in a single command: - gnatmake my_main.adb -largs file1.o file2.o - - If the main program is in some language other than Ada, Then you may - have more than one entry point in the Ada subsystem. You must use a - special option of the binder to generate callable routines to initialize - and finalize the Ada units (*note Binding with Non-Ada Main Programs::). - Calls to the initialization and finalization routines must be inserted - in the main program, or some other appropriate point in the code. The - call to initialize the Ada units must occur before the first Ada - subprogram is called, and the call to finalize the Ada units must occur - after the last Ada subprogram returns. You use the same procedure for - building the program as described previously. In this case, however, - the binder only places the initialization and finalization subprograms - into file `b~XXX.adb' instead of the main program. So, if the main - program is not in Ada, you should proceed as follows: - - 1. Compile the other language files to generate object files. For - instance: - gcc -c file1.c - gcc -c file2.c - - 2. Compile the Ada units to produce a set of object files and ALI - files. For instance: - gnatmake -c entry_point1.adb - gnatmake -c entry_point2.adb - - 3. Run the Ada binder on the Ada main program. For instance: - gnatbind -n entry_point1.ali entry_point2.ali - - 4. Link the Ada main program, the Ada objects and the other language - objects. You only need to give the last entry point here. For - instance: - gnatlink entry_point2.ali file1.o file2.o - -  - File: gnat_ug_unx.info, Node: Calling Conventions, Prev: Interfacing to C, Up: Mixed Language Programming - - Calling Conventions - ------------------- - - GNAT follows standard calling sequence conventions and will thus - interface to any other language that also follows these conventions. - The following Convention identifiers are recognized by GNAT: - - * Ada. This indicates that the standard Ada calling sequence will be - used and all Ada data items may be passed without any limitations - in the case where GNAT is used to generate both the caller and - callee. It is also possible to mix GNAT generated code and code - generated by another Ada compiler. In this case, the data types - should be restricted to simple cases, including primitive types. - Whether complex data types can be passed depends on the situation. - Probably it is safe to pass simple arrays, such as arrays of - integers or floats. Records may or may not work, depending on - whether both compilers lay them out identically. Complex structures - involving variant records, access parameters, tasks, or protected - types, are unlikely to be able to be passed. - - Note that in the case of GNAT running on a platform that supports - DEC Ada 83, a higher degree of compatibility can be guaranteed, - and in particular records are layed out in an identical manner in - the two compilers. Note also that if output from two different - compilers is mixed, the program is responsible for dealing with - elaboration issues. Probably the safest approach is to write the - main program in the version of Ada other than GNAT, so that it - takes care of its own elaboration requirements, and then call the - GNAT-generated adainit procedure to ensure elaboration of the GNAT - components. Consult the documentation of the other Ada compiler - for further details on elaboration. - - However, it is not possible to mix the tasking run time of GNAT and - DEC Ada 83, All the tasking operations must either be entirely - within GNAT compiled sections of the program, or entirely within - DEC Ada 83 compiled sections of the program. - - * Assembler. Specifies assembler as the convention. In practice this - has the same effect as convention Ada (but is not equivalent in - the sense of being considered the same convention). - - * Asm. Equivalent to Assembler. - - * Asm. Equivalent to Assembly. - - * COBOL. Data will be passed according to the conventions described - in section B.4 of the Ada 95 Reference Manual. - - * C. Data will be passed according to the conventions described in - section B.3 of the Ada 95 Reference Manual. - - * Default. Equivalent to C. - - * External. Equivalent to C. - - * CPP. This stands for C++. For most purposes this is identical to C. - See the separate description of the specialized GNAT pragmas - relating to C++ interfacing for further details. - - * Fortran. Data will be passed according to the conventions described - in section B.5 of the Ada 95 Reference Manual. - - * Intrinsic. This applies to an intrinsic operation, as defined in - the Ada 95 Reference Manual. If a a pragma Import (Intrinsic) - applies to a subprogram, this means that the body of the - subprogram is provided by the compiler itself, usually by means of - an efficient code sequence, and that the user does not supply an - explicit body for it. In an application program, the pragma can - only be applied to the following two sets of names, which the GNAT - compiler recognizes. - * Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, - Shift_Right_- Arithmetic. The corresponding subprogram - declaration must have two formal parameters. The first one - must be a signed integer type or a modular type with a binary - modulus, and the second parameter must be of type Natural. - The return type must be the same as the type of the first - argument. The size of this type can only be 8, 16, 32, or 64. - - * binary arithmetic operators: "+", "-", "*", "/" The - corresponding operator declaration must have parameters and - result type that have the same root numeric type (for - example, all three are long_float types). This simplifies the - definition of operations that use type checking to perform - dimensional checks: - type Distance is new Long_Float; - type Time is new Long_Float; - type Velocity is new Long_Float; - function "/" (D : Distance; T : Time) - return Velocity; - pragma Import (Intrinsic, "/"); - - This common idiom is often programmed with a generic - definition and an explicit body. The pragma makes it simpler - to introduce such declarations. It incurs no overhead in - compilation time or code size, because it is implemented as a - single machine instruction. - - * Stdcall. This is relevant only to NT/Win95 implementations of GNAT, - and specifies that the Stdcall calling sequence will be used, as - defined by the NT API. - - * DLL. This is equivalent to Stdcall. - - * Win32. This is equivalent to Stdcall. - - * Stubbed. This is a special convention that indicates that the - compiler should provide a stub body that raises `Program_Error'. - - GNAT additionally provides a useful pragma `Convention_Identifier' that - can be used to parametrize conventions and allow additional synonyms to - be specified. For example if you have legacy code in which the - convention identifier Fortran77 was used for Fortran, you can use the - configuration pragma: - - pragma Convention_Identifier (Fortran77, Fortran); - - And from now on the identifier Fortran77 may be used as a convention - identifier (for example in an `Import' pragma) with the same meaning as - Fortran. - -  - File: gnat_ug_unx.info, Node: Building Mixed Ada & C++ Programs, Next: Comparison between GNAT and C/C++ Compilation Models, Prev: Mixed Language Programming, Up: The GNAT Compilation Model - - Building Mixed Ada & C++ Programs - ================================= - - Building a mixed application containing both Ada and C++ code may be a - challenge for the unaware programmer. As a matter of fact, this - interfacing has not been standardized in the Ada 95 reference manual due - to the immaturity and lack of standard of C++ at the time. This section - gives a few hints that should make this task easier. In particular the - first section addresses the differences with interfacing with C. The - second section looks into the delicate problem of linking the complete - application from its Ada and C++ parts. The last section give some - hints on how the GNAT run time can be adapted in order to allow - inter-language dispatching with a new C++ compiler. - - * Menu: - - * Interfacing to C++:: - * Linking a Mixed C++ & Ada Program:: - * A Simple Example:: - * Adapting the Run Time to a New C++ Compiler:: - -  - File: gnat_ug_unx.info, Node: Interfacing to C++, Next: Linking a Mixed C++ & Ada Program, Up: Building Mixed Ada & C++ Programs - - Interfacing to C++ - ------------------ - - GNAT supports interfacing with C++ compilers generating code that is - compatible with the standard Application Binary Interface of the given - platform. - - Interfacing can be done at 3 levels: simple data, subprograms and - classes. In the first 2 cases, GNAT offer a specific CONVENTION CPP - that behaves exactly like CONVENTION C. Usually C++ mangle names of - subprograms and currently GNAT does not provide any help to solve the - demangling problem. This problem can be addressed in 2 ways: - * by modifying the C++ code in order to force a C convention using - the EXTERN "C" syntax. - - * by figuring out the mangled name and use it as the Link_Name - argument of the pragma import. - - Interfacing at the class level can be achieved by using the GNAT - specific pragmas such as `CPP_Class' and `CPP_Virtual'. See the GNAT - Reference Manual for additional information. - -  - File: gnat_ug_unx.info, Node: Linking a Mixed C++ & Ada Program, Next: A Simple Example, Prev: Interfacing to C++, Up: Building Mixed Ada & C++ Programs - - Linking a Mixed C++ & Ada Program - --------------------------------- - - Usually the linker of the C++ development system must be used to link - mixed applications because most C++ systems will resolve elaboration - issues (such as calling constructors on global class instances) - transparently during the link phase. GNAT has been adapted to ease the - use of a foreign linker for the last phase. Three cases can be - considered: - 1. Using GNAT and G++ (GNU C++ compiler) from the same GCC - installation. The c++ linker can simply be called by using the c++ - specific driver called `c++'. Note that this setup is not very - common because it may request recompiling the whole GCC tree from - sources and it does not allow to upgrade easily to a new version - of one compiler for one of the two languages without taking the - risk of destabilizing the other. - - $ c++ -c file1.C - $ c++ -c file2.C - $ gnatmake ada_unit -largs file1.o file2.o --LINK=c++ - - 2. Using GNAT and G++ from 2 different GCC installations. If both - compilers are on the PATH, the same method can be used. It is - important to be aware that environment variables such as - C_INCLUDE_PATH, GCC_EXEC_PREFIX, BINUTILS_ROOT or GCC_ROOT will - affect both compilers at the same time and thus may make one of - the 2 compilers operate improperly if they are set for the other. - In particular it is important that the link command has access to - the proper gcc library `libgcc.a', that is to say the one that is - part of the C++ compiler installation. The implicit link command - as suggested in the gnatmake command from the former example can - be replaced by an explicit link command with full verbosity in - order to verify which library is used: - $ gnatbind ada_unit - $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ - If there is a problem due to interfering environment variables, it - can be workaround by using an intermediate script. The following - example shows the proper script to use when GNAT has not been - installed at its default location and g++ has been installed at - its default location: - - $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script - $ cat ./my_script - #!/bin/sh - unset BINUTILS_ROOT - unset GCC_ROOT - c++ $* - - 3. Using a non GNU C++ compiler. The same set of command as previously - described can be used to insure that the c++ linker is used. - Nonetheless, you need to add the path to libgcc explicitely, since - some libraries needed by GNAT are located in this directory: - - - $ gnatlink ada_unit file1.o file2.o --LINK=./my_script - $ cat ./my_script - #!/bin/sh - CC $* `gcc -print-libgcc-file-name` - - Where CC is the name of the non GNU C++ compiler. - - -  - File: gnat_ug_unx.info, Node: A Simple Example, Next: Adapting the Run Time to a New C++ Compiler, Prev: Linking a Mixed C++ & Ada Program, Up: Building Mixed Ada & C++ Programs - - A Simple Example - ---------------- - - The following example, provided as part of the GNAT examples, show how - to achieve procedural interfacing between Ada and C++ in both - directions. The C++ class A has 2 methods. The first method is exported - to Ada by the means of an extern C wrapper function. The second method - calls an Ada subprogram. On the Ada side, The C++ calls is modelized by - a limited record with a layout comparable to the C++ class. The Ada - subprogram, in turn, calls the c++ method. So from the C++ main program - the code goes back and forth between the 2 languages. - - Here are the compilation commands for native configurations: - $ gnatmake -c simple_cpp_interface - $ c++ -c cpp_main.C - $ c++ -c ex7.C - $ gnatbind -n simple_cpp_interface - $ gnatlink simple_cpp_interface -o cpp_main --LINK=$(CPLUSPLUS) - -lstdc++ ex7.o cpp_main.o - - Here are the corresponding sources: - - //cpp_main.C - - #include "ex7.h" - - extern "C" { - void adainit (void); - void adafinal (void); - void method1 (A *t); - } - - void method1 (A *t) - { - t->method1 (); - } - - int main () - { - A obj; - adainit (); - obj.method2 (3030); - adafinal (); - } - - //ex7.h - - class Origin { - public: - int o_value; - }; - class A : public Origin { - public: - void method1 (void); - virtual void method2 (int v); - A(); - int a_value; - }; - - //ex7.C - - #include "ex7.h" - #include - - extern "C" { void ada_method2 (A *t, int v);} - - void A::method1 (void) - { - a_value = 2020; - printf ("in A::method1, a_value = %d \n",a_value); - - } - - void A::method2 (int v) - { - ada_method2 (this, v); - printf ("in A::method2, a_value = %d \n",a_value); - - } - - A::A(void) - { - a_value = 1010; - printf ("in A::A, a_value = %d \n",a_value); - } - - -- Ada sources - package body Simple_Cpp_Interface is - - procedure Ada_Method2 (This : in out A; V : Integer) is - begin - Method1 (This); - This.A_Value := V; - end Ada_Method2; - - end Simple_Cpp_Interface; - - package Simple_Cpp_Interface is - type A is limited - record - O_Value : Integer; - A_Value : Integer; - end record; - pragma Convention (C, A); - - procedure Method1 (This : in out A); - pragma Import (C, Method1); - - procedure Ada_Method2 (This : in out A; V : Integer); - pragma Export (C, Ada_Method2); - - end Simple_Cpp_Interface; - -  - File: gnat_ug_unx.info, Node: Adapting the Run Time to a New C++ Compiler, Prev: A Simple Example, Up: Building Mixed Ada & C++ Programs - - Adapting the Run Time to a New C++ Compiler - ------------------------------------------- - - GNAT offers the capability to derive Ada 95 tagged types directly from - preexisting C++ classes and . See "Interfacing with C++" in the GNAT - reference manual. The mechanism used by GNAT for achieving such a goal - has been made user configurable through a GNAT library unit - `Interfaces.CPP'. The default version of this file is adapted to the - GNU c++ compiler. Internal knowledge of the virtual table layout used - by the new C++ compiler is needed to configure properly this unit. The - Interface of this unit is known by the compiler and cannot be changed - except for the value of the constants defining the characteristics of - the virtual table: CPP_DT_Prologue_Size, CPP_DT_Entry_Size, - CPP_TSD_Prologue_Size, CPP_TSD_Entry_Size. Read comments in the source - of this unit for more details. - -  - File: gnat_ug_unx.info, Node: Comparison between GNAT and C/C++ Compilation Models, Next: Comparison between GNAT and Conventional Ada Library Models, Prev: Building Mixed Ada & C++ Programs, Up: The GNAT Compilation Model - - Comparison between GNAT and C/C++ Compilation Models - ==================================================== - - The GNAT model of compilation is close to the C and C++ models. You can - think of Ada specs as corresponding to header files in C. As in C, you - don't need to compile specs; they are compiled when they are used. The - Ada `with' is similar in effect to the `#include' of a C header. - - One notable difference is that, in Ada, you may compile specs - separately to check them for semantic and syntactic accuracy. This is - not always possible with C headers because they are fragments of - programs that have less specific syntactic or semantic rules. - - The other major difference is the requirement for running the binder, - which performs two important functions. First, it checks for - consistency. In C or C++, the only defense against assembling - inconsistent programs lies outside the compiler, in a makefile, for - example. The binder satisfies the Ada requirement that it be impossible - to construct an inconsistent program when the compiler is used in normal - mode. - - The other important function of the binder is to deal with - elaboration issues. There are also elaboration issues in C++ that are - handled automatically. This automatic handling has the advantage of - being simpler to use, but the C++ programmer has no control over - elaboration. Where `gnatbind' might complain there was no valid order - of elaboration, a C++ compiler would simply construct a program that - malfunctioned at run time. - -  - File: gnat_ug_unx.info, Node: Comparison between GNAT and Conventional Ada Library Models, Prev: Comparison between GNAT and C/C++ Compilation Models, Up: The GNAT Compilation Model - - Comparison between GNAT and Conventional Ada Library Models - =========================================================== - - This section is intended to be useful to Ada programmers who have - previously used an Ada compiler implementing the traditional Ada library - model, as described in the Ada 95 Language Reference Manual. If you - have not used such a system, please go on to the next section. - - In GNAT, there is no "library" in the normal sense. Instead, the set - of source files themselves acts as the library. Compiling Ada programs - does not generate any centralized information, but rather an object - file and a ALI file, which are of interest only to the binder and - linker. In a traditional system, the compiler reads information not - only from the source file being compiled, but also from the centralized - library. This means that the effect of a compilation depends on what - has been previously compiled. In particular: - - * When a unit is `with''ed, the unit seen by the compiler corresponds - to the version of the unit most recently compiled into the library. - - * Inlining is effective only if the necessary body has already been - compiled into the library. - - * Compiling a unit may obsolete other units in the library. - - In GNAT, compiling one unit never affects the compilation of any other - units because the compiler reads only source files. Only changes to - source files can affect the results of a compilation. In particular: - - * When a unit is `with''ed, the unit seen by the compiler corresponds - to the source version of the unit that is currently accessible to - the compiler. - - * Inlining requires the appropriate source files for the package or - subprogram bodies to be available to the compiler. Inlining is - always effective, independent of the order in which units are - complied. - - * Compiling a unit never affects any other compilations. The editing - of sources may cause previous compilations to be out of date if - they depended on the source file being modified. - - The most important result of these differences is that order of - compilation is never significant in GNAT. There is no situation in - which one is required to do one compilation before another. What shows - up as order of compilation requirements in the traditional Ada library - becomes, in GNAT, simple source dependencies; in other words, there is - only a set of rules saying what source files must be present when a - file is compiled. - -  - File: gnat_ug_unx.info, Node: Compiling Using gcc, Next: Binding Using gnatbind, Prev: The GNAT Compilation Model, Up: Top - - Compiling Using `gcc' - ********************* - - This chapter discusses how to compile Ada programs using the `gcc' - command. It also describes the set of switches that can be used to - control the behavior of the compiler. - - * Menu: - - * Compiling Programs:: - * Switches for gcc:: - * Search Paths and the Run-Time Library (RTL):: - * Order of Compilation Issues:: - * Examples:: - -  - File: gnat_ug_unx.info, Node: Compiling Programs, Next: Switches for gcc, Up: Compiling Using gcc - - Compiling Programs - ================== - - The first step in creating an executable program is to compile the units - of the program using the `gcc' command. You must compile the following - files: - - * the body file (`.adb') for a library level subprogram or generic - subprogram - - * the spec file (`.ads') for a library level package or generic - package that has no body - - * the body file (`.adb') for a library level package or generic - package that has a body - - - You need _not_ compile the following files - - * the spec of a library unit which has a body - - * subunits - - because they are compiled as part of compiling related units. GNAT - package specs when the corresponding body is compiled, and subunits - when the parent is compiled. If you attempt to compile any of these - files, you will get one of the following error messages (where fff is - the name of the file you compiled): - - No code generated for file FFF (PACKAGE SPEC) - No code generated for file FFF (SUBUNIT) - - The basic command for compiling a file containing an Ada unit is - - $ gcc -c [SWITCHES] `file name' - - where FILE NAME is the name of the Ada file (usually having an extension - `.ads' for a spec or `.adb' for a body). You specify the `-c' switch - to tell `gcc' to compile, but not link, the file. The result of a - successful compilation is an object file, which has the same name as - the source file but an extension of `.o' and an Ada Library Information - (ALI) file, which also has the same name as the source file, but with - `.ali' as the extension. GNAT creates these two output files in the - current directory, but you may specify a source file in any directory - using an absolute or relative path specification containing the - directory information. - - `gcc' is actually a driver program that looks at the extensions of - the file arguments and loads the appropriate compiler. For example, the - GNU C compiler is `cc1', and the Ada compiler is `gnat1'. These - programs are in directories known to the driver program (in some - configurations via environment variables you set), but need not be in - your path. The `gcc' driver also calls the assembler and any other - utilities needed to complete the generation of the required object - files. - - It is possible to supply several file names on the same `gcc' - command. This causes `gcc' to call the appropriate compiler for each - file. For example, the following command lists three separate files to - be compiled: - - $ gcc -c x.adb y.adb z.c - - calls `gnat1' (the Ada compiler) twice to compile `x.adb' and `y.adb', - and `cc1' (the C compiler) once to compile `z.c'. The compiler - generates three object files `x.o', `y.o' and `z.o' and the two ALI - files `x.ali' and `y.ali' from the Ada compilations. Any switches apply - to all the files listed, except for `-gnatX' switches, which apply only - to Ada compilations. - -  - File: gnat_ug_unx.info, Node: Switches for gcc, Next: Search Paths and the Run-Time Library (RTL), Prev: Compiling Programs, Up: Compiling Using gcc - - Switches for `gcc' - ================== - - The `gcc' command accepts switches that control the compilation - process. These switches are fully described in this section. First we - briefly list all the switches, in alphabetical order, then we describe - the switches in more detail in functionally grouped sections. - - * Menu: - - * Output and Error Message Control:: - * Debugging and Assertion Control:: - * Run-Time Checks:: - * Stack Overflow Checking:: - * Run-Time Control:: - * Validity Checking:: - * Style Checking:: - * Using gcc for Syntax Checking:: - * Using gcc for Semantic Checking:: - * Compiling Ada 83 Programs:: - * Character Set Control:: - * File Naming Control:: - * Subprogram Inlining Control:: - * Auxiliary Output Control:: - * Debugging Control:: - * Units to Sources Mapping Files:: - - `-b TARGET' - Compile your program to run on TARGET, which is the name of a - system configuration. You must have a GNAT cross-compiler built if - TARGET is not the same as your host system. - - `-BDIR' - Load compiler executables (for example, `gnat1', the Ada compiler) - from DIR instead of the default location. Only use this switch - when multiple versions of the GNAT compiler are available. See the - `gcc' manual page for further details. You would normally use the - `-b' or `-V' switch instead. - - `-c' - Compile. Always use this switch when compiling Ada programs. - - Note: for some other languages when using `gcc', notably in the - case of C and C++, it is possible to use use `gcc' without a `-c' - switch to compile and link in one step. In the case of GNAT, you - cannot use this approach, because the binder must be run and `gcc' - cannot be used to run the GNAT binder. - - `-g' - Generate debugging information. This information is stored in the - object file and copied from there to the final executable file by - the linker, where it can be read by the debugger. You must use the - `-g' switch if you plan on using the debugger. - - `-IDIR' - Direct GNAT to search the DIR directory for source files needed by - the current compilation (*note Search Paths and the Run-Time - Library (RTL)::). - - `-I-' - Except for the source file named in the command line, do not look - for source files in the directory containing the source file named - in the command line (*note Search Paths and the Run-Time Library - (RTL)::). - - `-o FILE' - This switch is used in `gcc' to redirect the generated object file - and its associated ALI file. Beware of this switch with GNAT, - because it may cause the object file and ALI file to have - different names which in turn may confuse the binder and the - linker. - - `-O[N]' - N controls the optimization level. - - n = 0 - No optimization, the default setting if no `-O' appears - - n = 1 - Normal optimization, the default if you specify `-O' without - an operand. - - n = 2 - Extensive optimization - - n = 3 - Extensive optimization with automatic inlining. This applies - only to inlining within a unit. For details on control of - inter-unit inlining see *Note Subprogram Inlining Control::. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-S' - Used in place of `-c' to cause the assembler source file to be - generated, using `.s' as the extension, instead of the object file. - This may be useful if you need to examine the generated assembly - code. - - `-v' - Show commands generated by the `gcc' driver. Normally used only for - debugging purposes or if you need to be sure what version of the - compiler you are executing. - - `-V VER' - Execute VER version of the compiler. This is the `gcc' version, - not the GNAT version. - - `-gnata' - Assertions enabled. `Pragma Assert' and `pragma Debug' to be - activated. - - `-gnatA' - Avoid processing `gnat.adc'. If a gnat.adc file is present, it - will be ignored. - - `-gnatb' - Generate brief messages to `stderr' even if verbose mode set. - - `-gnatc' - Check syntax and semantics only (no code generation attempted). - - `-gnatC' - Compress debug information and external symbol name table entries. - - `-gnatD' - Output expanded source files for source level debugging. This - switch also suppress generation of cross-reference information - (see -gnatx). - - `-gnatecPATH' - Specify a configuration pragma file. (see *Note The Configuration - Pragmas Files::) - - `-gnatemPATH' - Specify a mapping file. (see *Note Units to Sources Mapping - Files::) - - `-gnatE' - Full dynamic elaboration checks. - - `-gnatf' - Full errors. Multiple errors per line, all undefined references. - - `-gnatF' - Externals names are folded to all uppercase. - - `-gnatg' - Internal GNAT implementation mode. This should not be used for - applications programs, it is intended only for use by the compiler - and its run-time library. For documentation, see the GNAT sources. - - `-gnatG' - List generated expanded code in source form. - - `-gnatiC' - Identifier character set (C=1/2/3/4/8/9/p/f/n/w). - - `-gnath' - Output usage information. The output is written to `stdout'. - - `-gnatkN' - Limit file names to N (1-999) characters (`k' = krunch). - - `-gnatl' - Output full source listing with embedded error messages. - - `-gnatmN' - Limit number of detected errors to N (1-999). - - `-gnatn' - Activate inlining across unit boundaries for subprograms for which - pragma `inline' is specified. - - `-gnatN' - Activate front end inlining. - - `-fno-inline' - Suppresses all inlining, even if other optimization or inlining - switches are set. - - `-fstack-check' - Activates stack checking. See separate section on stack checking - for details of the use of this option. - - `-gnato' - Enable numeric overflow checking (which is not normally enabled by - default). Not that division by zero is a separate check that is not - controlled by this switch (division by zero checking is on by - default). - - `-gnatp' - Suppress all checks. - - `-gnatq' - Don't quit; try semantics, even if parse errors. - - `-gnatQ' - Don't quit; generate `ali' and tree files even if illegalities. - - `-gnatP' - Enable polling. This is required on some systems (notably Windows - NT) to obtain asynchronous abort and asynchronous transfer of - control capability. See the description of pragma Polling in the - GNAT Reference Manual for full details. - - `-gnatR[0/1/2/3][s]' - Output representation information for declared types and objects. - - `-gnats' - Syntax check only. - - `-gnatt' - Tree output file to be generated. - - `-gnatT nnn' - Set time slice to specified number of microseconds - - `-gnatu' - List units for this compilation. - - `-gnatU' - Tag all error messages with the unique string "error:" - - `-gnatv' - Verbose mode. Full error output with source lines to `stdout'. - - `-gnatV' - Control level of validity checking. See separate section describing - this feature. - - `-gnatwxxxXXX' - Warning mode where XXX is a string of options describing the exact - warnings that are enabled or disabled. See separate section on - warning control. - - `-gnatWE' - Wide character encoding method (E=n/h/u/s/e/8). - - `-gnatx' - Suppress generation of cross-reference information. - - `-gnaty' - Enable built-in style checks. See separate section describing this - feature. - - `-gnatzM' - Distribution stub generation and compilation (M=r/c for - receiver/caller stubs). - - `-gnat83' - Enforce Ada 83 restrictions. - - `-pass-exit-codes' - Catch exit codes from the compiler and use the most meaningful as - exit status. - - You may combine a sequence of GNAT switches into a single switch. For - example, the combined switch - - -gnatofi3 - - is equivalent to specifying the following sequence of switches: - - -gnato -gnatf -gnati3 - - The following restrictions apply to the combination of switches in this - manner: - - * The switch `-gnatc' if combined with other switches must come - first in the string. - - * The switch `-gnats' if combined with other switches must come - first in the string. - - * Once a "y" appears in the string (that is a use of the `-gnaty' - switch), then all further characters in the switch are interpreted - as style modifiers (see description of `-gnaty'). - - * Once a "d" appears in the string (that is a use of the `-gnatd' - switch), then all further characters in the switch are interpreted - as debug flags (see description of `-gnatd'). - - * Once a "w" appears in the string (that is a use of the `-gnatw' - switch), then all further characters in the switch are interpreted - as warning mode modifiers (see description of `-gnatw'). - - * Once a "V" appears in the string (that is a use of the `-gnatV' - switch), then all further characters in the switch are interpreted - as validity checking options (see description of `-gnatV'). - - -  - File: gnat_ug_unx.info, Node: Output and Error Message Control, Next: Debugging and Assertion Control, Up: Switches for gcc - - Output and Error Message Control - -------------------------------- - - The standard default format for error messages is called "brief format." - Brief format messages are written to `stderr' (the standard error file) - and have the following form: - - e.adb:3:04: Incorrect spelling of keyword "function" - e.adb:4:20: ";" should be "is" - - The first integer after the file name is the line number in the file, - and the second integer is the column number within the line. `glide' - can parse the error messages and point to the referenced character. - The following switches provide control over the error message format: - - `-gnatv' - The v stands for verbose. The effect of this setting is to write - long-format error messages to `stdout' (the standard output file. - The same program compiled with the `-gnatv' switch would generate: - - 3. funcion X (Q : Integer) - | - >>> Incorrect spelling of keyword "function" - 4. return Integer; - | - >>> ";" should be "is" - - The vertical bar indicates the location of the error, and the `>>>' - prefix can be used to search for error messages. When this switch - is used the only source lines output are those with errors. - - `-gnatl' - The `l' stands for list. This switch causes a full listing of the - file to be generated. The output might look as follows: - - 1. procedure E is - 2. V : Integer; - 3. funcion X (Q : Integer) - | - >>> Incorrect spelling of keyword "function" - 4. return Integer; - | - >>> ";" should be "is" - 5. begin - 6. return Q + Q; - 7. end; - 8. begin - 9. V := X + X; - 10.end E; - - When you specify the `-gnatv' or `-gnatl' switches and standard - output is redirected, a brief summary is written to `stderr' - (standard error) giving the number of error messages and warning - messages generated. - - `-gnatU' - This switch forces all error messages to be preceded by the unique - string "error:". This means that error messages take a few more - characters in space, but allows easy searching for and - identification of error messages. - - `-gnatb' - The `b' stands for brief. This switch causes GNAT to generate the - brief format error messages to `stderr' (the standard error file) - as well as the verbose format message or full listing (which as - usual is written to `stdout' (the standard output file). - - `-gnatmN' - The `m' stands for maximum. N is a decimal integer in the range - of 1 to 999 and limits the number of error messages to be - generated. For example, using `-gnatm2' might yield - - e.adb:3:04: Incorrect spelling of keyword "function" - e.adb:5:35: missing ".." - fatal error: maximum errors reached - compilation abandoned - - `-gnatf' - The `f' stands for full. Normally, the compiler suppresses error - messages that are likely to be redundant. This switch causes all - error messages to be generated. In particular, in the case of - references to undefined variables. If a given variable is - referenced several times, the normal format of messages is - e.adb:7:07: "V" is undefined (more references follow) - - where the parenthetical comment warns that there are additional - references to the variable `V'. Compiling the same program with the - `-gnatf' switch yields - - e.adb:7:07: "V" is undefined - e.adb:8:07: "V" is undefined - e.adb:8:12: "V" is undefined - e.adb:8:16: "V" is undefined - e.adb:9:07: "V" is undefined - e.adb:9:12: "V" is undefined - - `-gnatq' - The `q' stands for quit (really "don't quit"). In normal - operation mode, the compiler first parses the program and - determines if there are any syntax errors. If there are, - appropriate error messages are generated and compilation is - immediately terminated. This switch tells GNAT to continue with - semantic analysis even if syntax errors have been found. This may - enable the detection of more errors in a single run. On the other - hand, the semantic analyzer is more likely to encounter some - internal fatal error when given a syntactically invalid tree. - - `-gnatQ' - In normal operation mode, the `ali' file is not generated if any - illegalities are detected in the program. The use of `-gnatQ' - forces generation of the `ali' file. This file is marked as being - in error, so it cannot be used for binding purposes, but it does - contain reasonably complete cross-reference information, and thus - may be useful for use by tools (e.g. semantic browsing tools or - integrated development environments) that are driven from the - `ali' file. - - In addition, if `-gnatt' is also specified, then the tree file is - generated even if there are illegalities. It may be useful in this - case to also specify `-gnatq' to ensure that full semantic - processing occurs. The resulting tree file can be processed by - ASIS, for the purpose of providing partial information about - illegal units, but if the error causes the tree to be badly - malformed, then ASIS may crash during the analysis. - - In addition to error messages, which correspond to illegalities as - defined in the Ada 95 Reference Manual, the compiler detects two kinds - of warning situations. - - First, the compiler considers some constructs suspicious and - generates a warning message to alert you to a possible error. Second, - if the compiler detects a situation that is sure to raise an exception - at run time, it generates a warning message. The following shows an - example of warning messages: - e.adb:4:24: warning: creation of object may raise Storage_Error - e.adb:10:17: warning: static value out of range - e.adb:10:17: warning: "Constraint_Error" will be raised at run time - - GNAT considers a large number of situations as appropriate for the - generation of warning messages. As always, warnings are not definite - indications of errors. For example, if you do an out-of-range - assignment with the deliberate intention of raising a - `Constraint_Error' exception, then the warning that may be issued does - not indicate an error. Some of the situations for which GNAT issues - warnings (at least some of the time) are given in the following list, - which is not necessarily complete. - - * Possible infinitely recursive calls - - * Out-of-range values being assigned - - * Possible order of elaboration problems - - * Unreachable code - - * Fixed-point type declarations with a null range - - * Variables that are never assigned a value - - * Variables that are referenced before being initialized - - * Task entries with no corresponding accept statement - - * Duplicate accepts for the same task entry in a select - - * Objects that take too much storage - - * Unchecked conversion between types of differing sizes - - * Missing return statements along some execution paths in a function - - * Incorrect (unrecognized) pragmas - - * Incorrect external names - - * Allocation from empty storage pool - - * Potentially blocking operations in protected types - - * Suspicious parenthesization of expressions - - * Mismatching bounds in an aggregate - - * Attempt to return local value by reference - - * Unrecognized pragmas - - * Premature instantiation of a generic body - - * Attempt to pack aliased components - - * Out of bounds array subscripts - - * Wrong length on string assignment - - * Violations of style rules if style checking is enabled - - * Unused with clauses - - * Bit_Order usage that does not have any effect - - * Compile time biased rounding of floating-point constant - - * Standard.Duration used to resolve universal fixed expression - - * Dereference of possibly null value - - * Declaration that is likely to cause storage error - - * Internal GNAT unit with'ed by application unit - - * Values known to be out of range at compile time - - * Unreferenced labels and variables - - * Address overlays that could clobber memory - - * Unexpected initialization when address clause present - - * Bad alignment for address clause - - * Useless type conversions - - * Redundant assignment statements - - * Accidental hiding of name by child unit - - * Unreachable code - - * Access before elaboration detected at compile time - - * A range in a `for' loop that is known to be null or might be null - - - The following switches are available to control the handling of warning - messages: - - `-gnatwa (activate all optional errors)' - This switch activates most optional warning messages, see - remaining list in this section for details on optional warning - messages that can be individually controlled. The warnings that - are not turned on by this switch are `-gnatwb' (biased rounding), - `-gnatwd' (implicit dereferencing), and `-gnatwh' (hiding). All - other optional warnings are turned on. - - `-gnatwA (suppress all optional errors)' - This switch suppresses all optional warning messages, see - remaining list in this section for details on optional warning - messages that can be individually controlled. - - `-gnatwb (activate warnings on biased rounding)' - If a static floating-point expression has a value that is exactly - half way between two adjacent machine numbers, then the rules of - Ada (Ada Reference Manual, section 4.9(38)) require that this - rounding be done away from zero, even if the normal unbiased - rounding rules at run time would require rounding towards zero. - This warning message alerts you to such instances where - compile-time rounding and run-time rounding are not equivalent. If - it is important to get proper run-time rounding, then you can - force this by making one of the operands into a variable. The - default is that such warnings are not generated. Note that - `-gnatwa' does not affect the setting of this warning option. - - `-gnatwB (suppress warnings on biased rounding)' - This switch disables warnings on biased rounding. - - `-gnatwc (activate warnings on conditionals)' - This switch activates warnings for conditional expressions used in - tests that are known to be True or False at compile time. The - default is that such warnings are not generated. This warning can - also be turned on using `-gnatwa'. - - `-gnatwC (suppress warnings on conditionals)' - This switch suppresses warnings for conditional expressions used in - tests that are known to be True or False at compile time. - - `-gnatwd (activate warnings on implicit dereferencing)' - If this switch is set, then the use of a prefix of an access type - in an indexed component, slice, or selected component without an - explicit `.all' will generate a warning. With this warning - enabled, access checks occur only at points where an explicit - `.all' appears in the source code (assuming no warnings are - generated as a result of this switch). The default is that such - warnings are not generated. Note that `-gnatwa' does not affect - the setting of this warning option. - - `-gnatwD (suppress warnings on implicit dereferencing)' - This switch suppresses warnings for implicit deferences in indexed - components, slices, and selected components. - - `-gnatwe (treat warnings as errors)' - This switch causes warning messages to be treated as errors. The - warning string still appears, but the warning messages are counted - as errors, and prevent the generation of an object file. - - `-gnatwf (activate warnings on unreferenced formals)' - This switch causes a warning to be generated if a formal parameter - is not referenced in the body of the subprogram. This warning can - also be turned on using `-gnatwa' or `-gnatwu'. - - `-gnatwF (suppress warnings on unreferenced formals)' - This switch suppresses warnings for unreferenced formal - parameters. Note that the combination `-gnatwu' followed by - `-gnatwF' has the effect of warning on unreferenced entities other - than subprogram formals. - - `-gnatwh (activate warnings on hiding)' - This switch activates warnings on hiding declarations. A - declaration is considered hiding if it is for a non-overloadable - entity, and it declares an entity with the same name as some other - entity that is directly or use-visible. The default is that such - warnings are not generated. Note that `-gnatwa' does not affect - the setting of this warning option. - - `-gnatwH (suppress warnings on hiding)' - This switch suppresses warnings on hiding declarations. - - `-gnatwi (activate warnings on implementation units).' - This switch activates warnings for a `with' of an internal GNAT - implementation unit, defined as any unit from the `Ada', - `Interfaces', `GNAT', or `System' hierarchies that is not - documented in either the Ada Reference Manual or the GNAT - Programmer's Reference Manual. Such units are intended only for - internal implementation purposes and should not be `with''ed by - user programs. The default is that such warnings are generated - This warning can also be turned on using `-gnatwa'. - - `-gnatwI (disable warnings on implementation units).' - This switch disables warnings for a `with' of an internal GNAT - implementation unit. - - `-gnatwl (activate warnings on elaboration pragmas)' - This switch activates warnings on missing pragma Elaborate_All - statements. See the section in this guide on elaboration checking - for details on when such pragma should be used. The default is - that such warnings are not generated. This warning can also be - turned on using `-gnatwa'. - - `-gnatwL (suppress warnings on elaboration pragmas)' - This switch suppresses warnings on missing pragma Elaborate_All - statements. See the section in this guide on elaboration checking - for details on when such pragma should be used. - - `-gnatwo (activate warnings on address clause overlays)' - This switch activates warnings for possibly unintended - initialization effects of defining address clauses that cause one - variable to overlap another. The default is that such warnings are - generated. This warning can also be turned on using `-gnatwa'. - - `-gnatwO (suppress warnings on address clause overlays)' - This switch suppresses warnings on possibly unintended - initialization effects of defining address clauses that cause one - variable to overlap another. - - `-gnatwp (activate warnings on ineffective pragma Inlines)' - This switch activates warnings for failure of front end inlining - (activated by `-gnatN') to inline a particular call. There are - many reasons for not being able to inline a call, including most - commonly that the call is too complex to inline. This warning can - also be turned on using `-gnatwa'. - - `-gnatwP (suppress warnings on ineffective pragma Inlines)' - This switch suppresses warnings on ineffective pragma Inlines. If - the inlining mechanism cannot inline a call, it will simply ignore - the request silently. - - `-gnatwr (activate warnings on redundant constructs)' - This switch activates warnings for redundant constructs. The - following is the current list of constructs regarded as redundant: - This warning can also be turned on using `-gnatwa'. - - * Assignment of an item to itself. - - * Type conversion that converts an expression to its own type. - - * Use of the attribute `Base' where `typ'Base' is the same as - `typ'. - - * Use of pragma `Pack' when all components are placed by a - record representation clause. - - `-gnatwR (suppress warnings on redundant constructs)' - This switch suppresses warnings for redundant constructs. - - `-gnatws (suppress all warnings)' - This switch completely suppresses the output of all warning - messages from the GNAT front end. Note that it does not suppress - warnings from the `gcc' back end. To suppress these back end - warnings as well, use the switch `-w' in addition to `-gnatws'. - - `-gnatwu (activate warnings on unused entities)' - This switch activates warnings to be generated for entities that - are defined but not referenced, and for units that are `with''ed - and not referenced. In the case of packages, a warning is also - generated if no entities in the package are referenced. This means - that if the package is referenced but the only references are in - `use' clauses or `renames' declarations, a warning is still - generated. A warning is also generated for a generic package that - is `with''ed but never instantiated. In the case where a package - or subprogram body is compiled, and there is a `with' on the - corresponding spec that is only referenced in the body, a warning - is also generated, noting that the `with' can be moved to the - body. The default is that such warnings are not generated. This - switch also activates warnings on unreferenced formals (it is - includes the effect of `-gnatwf'). This warning can also be - turned on using `-gnatwa'. - - `-gnatwU (suppress warnings on unused entities)' - This switch suppresses warnings for unused entities and packages. - It also turns off warnings on unreferenced formals (and thus - includes the effect of `-gnatwF'). - - A string of warning parameters can be used in the same parameter. - For example: - - -gnatwaLe - - Would turn on all optional warnings except for elaboration pragma - warnings, and also specify that warnings should be treated as - errors. - - `-w' - This switch suppresses warnings from the `gcc' backend. It may be - used in conjunction with `-gnatws' to ensure that all warnings are - suppressed during the entire compilation process. - -  - File: gnat_ug_unx.info, Node: Debugging and Assertion Control, Next: Run-Time Checks, Prev: Output and Error Message Control, Up: Switches for gcc - - Debugging and Assertion Control - ------------------------------- - - `-gnata' - The pragmas `Assert' and `Debug' normally have no effect and are - ignored. This switch, where `a' stands for assert, causes `Assert' - and `Debug' pragmas to be activated. - - The pragmas have the form: - - pragma Assert (BOOLEAN-EXPRESSION [, - STATIC-STRING-EXPRESSION]) - pragma Debug (PROCEDURE CALL) - - The `Assert' pragma causes BOOLEAN-EXPRESSION to be tested. If - the result is `True', the pragma has no effect (other than - possible side effects from evaluating the expression). If the - result is `False', the exception `Assert_Failure' declared in the - package `System.Assertions' is raised (passing - STATIC-STRING-EXPRESSION, if present, as the message associated - with the exception). If no string expression is given the default - is a string giving the file name and line number of the pragma. - - The `Debug' pragma causes PROCEDURE to be called. Note that - `pragma Debug' may appear within a declaration sequence, allowing - debugging procedures to be called between declarations. - -  - File: gnat_ug_unx.info, Node: Validity Checking, Next: Style Checking, Prev: Run-Time Control, Up: Switches for gcc - - Validity Checking - ----------------- - - The Ada 95 Reference Manual has specific requirements for checking for - invalid values. In particular, RM 13.9.1 requires that the evaluation - of invalid values (for example from unchecked conversions), not result - in erroneous execution. In GNAT, the result of such an evaluation in - normal default mode is to either use the value unmodified, or to raise - Constraint_Error in those cases where use of the unmodified value would - cause erroneous execution. The cases where unmodified values might lead - to erroneous execution are case statements (where a wild jump might - result from an invalid value), and subscripts on the left hand side - (where memory corruption could occur as a result of an invalid value). - - The `-gnatVx' switch allows more control over the validity checking - mode. The `x' argument here is a string of letters which control which - validity checks are performed in addition to the default checks - described above. - - * `-gnatVc' Validity checks for copies - - The right hand side of assignments, and the initializing values of - object declarations are validity checked. - - * `-gnatVd' Default (RM) validity checks - - Some validity checks are done by default following normal Ada - semantics (RM 13.9.1 (9-11)). A check is done in case statements - that the expression is within the range of the subtype. If it is - not, Constraint_Error is raised. For assignments to array - components, a check is done that the expression used as index is - within the range. If it is not, Constraint_Error is raised. Both - these validity checks may be turned off using switch `-gnatVD'. - They are turned on by default. If `-gnatVD' is specified, a - subsequent switch `-gnatVd' will leave the checks turned on. - Switch `-gnatVD' should be used only if you are sure that all such - expressions have valid values. If you use this switch and invalid - values are present, then the program is erroneous, and wild jumps - or memory overwriting may occur. - - * `-gnatVi' Validity checks for `in' mode parameters - - Arguments for parameters of mode `in' are validity checked in - function and procedure calls at the point of call. - - * `-gnatVm' Validity checks for `in out' mode parameters - - Arguments for parameters of mode `in out' are validity checked in - procedure calls at the point of call. The `'m'' here stands for - modify, since this concerns parameters that can be modified by the - call. Note that there is no specific option to test `out' - parameters, but any reference within the subprogram will be tested - in the usual manner, and if an invalid value is copied back, any - reference to it will be subject to validity checking. - - * `-gnatVo' Validity checks for operator and attribute operands - - Arguments for predefined operators and attributes are validity - checked. This includes all operators in package `Standard', the - shift operators defined as intrinsic in package `Interfaces' and - operands for attributes such as `Pos'. - - * `-gnatVr' Validity checks for function returns - - The expression in `return' statements in functions is validity - checked. - - * `-gnatVs' Validity checks for subscripts - - All subscripts expressions are checked for validity, whether they - appear on the right side or left side (in default mode only left - side subscripts are validity checked). - - * `-gnatVt' Validity checks for tests - - Expressions used as conditions in `if', `while' or `exit' - statements are checked, as well as guard expressions in entry - calls. - - * `-gnatVf' Validity checks for floating-point values - - In the absence of this switch, validity checking occurs only for - discrete values. If `-gnatVf' is specified, then validity checking - also applies for floating-point values, and NaN's and infinities - are considered invalid, as well as out of range values for - constrained types. Note that this means that standard `IEEE' - infinity mode is not allowed. The exact contexts in which - floating-point values are checked depends on the setting of other - options. For example `-gnatVif' or `-gnatVfi' (the order does not - matter) specifies that floating-point parameters of mode `in' - should be validity checked. - - * `-gnatVa' All validity checks - - All the above validity checks are turned on. That is `-gnatVa' is - equivalent to `gnatVcdfimorst'. - - * `-gnatVn' No validity checks - - This switch turns off all validity checking, including the default - checking for case statements and left hand side subscripts. Note - that the use of the switch `-gnatp' supresses all run-time checks, - including validity checks, and thus implies `-gnatVn'. - - - The `-gnatV' switch may be followed by a string of letters to turn on - a series of validity checking options. For example, `-gnatVcr' specifies - that in addition to the default validity checking, copies and function - return expressions be validity checked. In order to make it easier to - specify a set of options, the upper case letters `CDFIMORST' may be - used to turn off the corresponding lower case option, so for example - `-gnatVaM' turns on all validity checking options except for checking - of `in out' procedure arguments. - - The specification of additional validity checking generates extra - code (and in the case of `-gnatva' the code expansion can be - substantial. However, these additional checks can be very useful in - smoking out cases of uninitialized variables, incorrect use of - unchecked conversion, and other errors leading to invalid values. The - use of pragma `Initialize_Scalars' is useful in conjunction with the - extra validity checking, since this ensures that wherever possible - uninitialized variables have invalid values. - - See also the pragma `Validity_Checks' which allows modification of - the validity checking mode at the program source level, and also allows - for temporary disabling of validity checks. - -  - File: gnat_ug_unx.info, Node: Style Checking, Next: Using gcc for Syntax Checking, Prev: Validity Checking, Up: Switches for gcc - - Style Checking - -------------- - - The -gnatyX switch causes the compiler to enforce specified style - rules. A limited set of style rules has been used in writing the GNAT - sources themselves. This switch allows user programs to activate all or - some of these checks. If the source program fails a specified style - check, an appropriate warning message is given, preceded by the - character sequence "(style)". The string X is a sequence of letters or - digits indicating the particular style checks to be performed. The - following checks are defined: - - `1-9 (specify indentation level)' - If a digit from 1-9 appears in the string after `-gnaty' then - proper indentation is checked, with the digit indicating the - indentation level required. The general style of required - indentation is as specified by the examples in the Ada Reference - Manual. Full line comments must be aligned with the `--' starting - on a column that is a multiple of the alignment level. - - `a (check attribute casing)' - If the letter a appears in the string after `-gnaty' then - attribute names, including the case of keywords such as `digits' - used as attributes names, must be written in mixed case, that is, - the initial letter and any letter following an underscore must be - uppercase. All other letters must be lowercase. - - `b (blanks not allowed at statement end)' - If the letter b appears in the string after `-gnaty' then trailing - blanks are not allowed at the end of statements. The purpose of - this rule, together with h (no horizontal tabs), is to enforce a - canonical format for the use of blanks to separate source tokens. - - `c (check comments)' - If the letter c appears in the string after `-gnaty' then comments - must meet the following set of rules: - - * The "-" that starts the column must either start in column - one, or else at least one blank must precede this sequence. - - * Comments that follow other tokens on a line must have at - least one blank following the "-" at the start of the comment. - - * Full line comments must have two blanks following the "-" - that starts the comment, with the following exceptions. - - * A line consisting only of the "-" characters, possibly - preceded by blanks is permitted. - - * A comment starting with "-x" where x is a special character - is permitted. This alows proper processing of the output - generated by specialized tools including `gnatprep' (where -! - is used) and the SPARK annnotation language (where -# is - used). For the purposes of this rule, a special character is - defined as being in one of the ASCII ranges 16#21#..16#2F# or - 16#3A#..16#3F#. - - * A line consisting entirely of minus signs, possibly preceded - by blanks, is permitted. This allows the construction of box - comments where lines of minus signs are used to form the top - and bottom of the box. - - * If a comment starts and ends with "-" is permitted as long as - at least one blank follows the initial "-". Together with the - preceding rule, this allows the construction of box comments, - as shown in the following example: - --------------------------- - -- This is a box comment -- - -- with two text lines. -- - --------------------------- - - `e (check end/exit labels)' - If the letter e appears in the string after `-gnaty' then optional - labels on `end' statements ending subprograms and on `exit' - statements exiting named loops, are required to be present. - - `f (no form feeds or vertical tabs)' - If the letter f appears in the string after `-gnaty' then neither - form feeds nor vertical tab characters are not permitted in the - source text. - - `h (no horizontal tabs)' - If the letter h appears in the string after `-gnaty' then - horizontal tab characters are not permitted in the source text. - Together with the b (no blanks at end of line) check, this - enforces a canonical form for the use of blanks to separate source - tokens. - - `i (check if-then layout)' - If the letter i appears in the string after `-gnaty', then the - keyword `then' must appear either on the same line as - corresponding `if', or on a line on its own, lined up under the - `if' with at least one non-blank line in between containing all or - part of the condition to be tested. - - `k (check keyword casing)' - If the letter k appears in the string after `-gnaty' then all - keywords must be in lower case (with the exception of keywords - such as `digits' used as attribute names to which this check does - not apply). - - `l (check layout)' - If the letter l appears in the string after `-gnaty' then layout - of statement and declaration constructs must follow the - recommendations in the Ada Reference Manual, as indicated by the - form of the syntax rules. For example an `else' keyword must be - lined up with the corresponding `if' keyword. - - There are two respects in which the style rule enforced by this - check option are more liberal than those in the Ada Reference - Manual. First in the case of record declarations, it is - permissible to put the `record' keyword on the same line as the - `type' keyword, and then the `end' in `end record' must line up - under `type'. For example, either of the following two layouts is - acceptable: - - type q is record - a : integer; - b : integer; - end record; - - type q is - record - a : integer; - b : integer; - end record; - - Second, in the case of a block statement, a permitted alternative - is to put the block label on the same line as the `declare' or - `begin' keyword, and then line the `end' keyword up under the - block label. For example both the following are permitted: - - Block : declare - A : Integer := 3; - begin - Proc (A, A); - end Block; - - Block : - declare - A : Integer := 3; - begin - Proc (A, A); - end Block; - - The same alternative format is allowed for loops. For example, - both of the following are permitted: - - Clear : while J < 10 loop - A (J) := 0; - end loop Clear; - - Clear : - while J < 10 loop - A (J) := 0; - end loop Clear; - - `m (check maximum line length)' - If the letter m appears in the string after `-gnaty' then the - length of source lines must not exceed 79 characters, including - any trailing blanks. The value of 79 allows convenient display on - an 80 character wide device or window, allowing for possible - special treatment of 80 character lines. - - `Mnnn (set maximum line length)' - If the sequence Mnnn, where nnn is a decimal number, appears in - the string after `-gnaty' then the length of lines must not exceed - the given value. - - `n (check casing of entities in Standard)' - If the letter n appears in the string after `-gnaty' then any - identifier from Standard must be cased to match the presentation - in the Ada Reference Manual (for example, `Integer' and - `ASCII.NUL'). - - `o (check order of subprogram bodies)' - If the letter o appears in the string after `-gnaty' then all - subprogram bodies in a given scope (e.g. a package body) must be - in alphabetical order. The ordering rule uses normal Ada rules for - comparing strings, ignoring casing of letters, except that if - there is a trailing numeric suffix, then the value of this suffix - is used in the ordering (e.g. Junk2 comes before Junk10). - - `p (check pragma casing)' - If the letter p appears in the string after `-gnaty' then pragma - names must be written in mixed case, that is, the initial letter - and any letter following an underscore must be uppercase. All - other letters must be lowercase. - - `r (check references)' - If the letter r appears in the string after `-gnaty' then all - identifier references must be cased in the same way as the - corresponding declaration. No specific casing style is imposed on - identifiers. The only requirement is for consistency of references - with declarations. - - `s (check separate specs)' - If the letter s appears in the string after `-gnaty' then separate - declarations ("specs") are required for subprograms (a body is not - allowed to serve as its own declaration). The only exception is - that parameterless library level procedures are not required to - have a separate declaration. This exception covers the most - frequent form of main program procedures. - - `t (check token spacing)' - If the letter t appears in the string after `-gnaty' then the - following token spacing rules are enforced: - - * The keywords `abs' and `not' must be followed by a space. - - * The token `=>' must be surrounded by spaces. - - * The token `<>' must be preceded by a space or a left - parenthesis. - - * Binary operators other than `**' must be surrounded by spaces. - There is no restriction on the layout of the `**' binary - operator. - - * Colon must be surrounded by spaces. - - * Colon-equal (assignment) must be surrounded by spaces. - - * Comma must be the first non-blank character on the line, or be - immediately preceded by a non-blank character, and must be - followed by a space. - - * If the token preceding a left paren ends with a letter or - digit, then a space must separate the two tokens. - - * A right parenthesis must either be the first non-blank - character on a line, or it must be preceded by a non-blank - character. - - * A semicolon must not be preceded by a space, and must not be - followed by a non-blank character. - - * A unary plus or minus may not be followed by a space. - - * A vertical bar must be surrounded by spaces. - - In the above rules, appearing in column one is always permitted, - that is, counts as meeting either a requirement for a required - preceding space, or as meeting a requirement for no preceding - space. - - Appearing at the end of a line is also always permitted, that is, - counts as meeting either a requirement for a following space, or - as meeting a requirement for no following space. - - If any of these style rules is violated, a message is generated giving - details on the violation. The initial characters of such messages are - always "(style)". Note that these messages are treated as warning - messages, so they normally do not prevent the generation of an object - file. The `-gnatwe' switch can be used to treat warning messages, - including style messages, as fatal errors. - - The switch `-gnaty' on its own (that is not followed by any letters or - digits), is equivalent to `gnaty3abcefhiklmprst', that is all checking - options are enabled with the exception of -gnatyo, with an indentation - level of 3. This is the standard checking option that is used for the - GNAT sources. - -  - File: gnat_ug_unx.info, Node: Run-Time Checks, Next: Stack Overflow Checking, Prev: Debugging and Assertion Control, Up: Switches for gcc - - Run-Time Checks - --------------- - - If you compile with the default options, GNAT will insert many run-time - checks into the compiled code, including code that performs range - checking against constraints, but not arithmetic overflow checking for - integer operations (including division by zero) or checks for access - before elaboration on subprogram calls. All other run-time checks, as - required by the Ada 95 Reference Manual, are generated by default. The - following `gcc' switches refine this default behavior: - - `-gnatp' - Suppress all run-time checks as though `pragma Suppress - (all_checks') had been present in the source. Validity checks are - also suppressed (in other words `-gnatp' also implies `-gnatVn'. - Use this switch to improve the performance of the code at the - expense of safety in the presence of invalid data or program bugs. - - `-gnato' - Enables overflow checking for integer operations. This causes - GNAT to generate slower and larger executable programs by adding - code to check for overflow (resulting in raising - `Constraint_Error' as required by standard Ada semantics). These - overflow checks correspond to situations in which the true value - of the result of an operation may be outside the base range of the - result type. The following example shows the distinction: - - X1 : Integer := Integer'Last; - X2 : Integer range 1 .. 5 := 5; - ... - X1 := X1 + 1; -- `-gnato' required to catch the Constraint_Error - X2 := X2 + 1; -- range check, `-gnato' has no effect here - - Here the first addition results in a value that is outside the - base range of Integer, and hence requires an overflow check for - detection of the constraint error. The second increment operation - results in a violation of the explicit range constraint, and such - range checks are always performed. Basically the compiler can - assume that in the absence of the `-gnato' switch that any value - of type `xxx' is in range of the base type of `xxx'. - - Note that the `-gnato' switch does not affect the code generated - for any floating-point operations; it applies only to integer - semantics). For floating-point, GNAT has the `Machine_Overflows' - attribute set to `False' and the normal mode of operation is to - generate IEEE NaN and infinite values on overflow or invalid - operations (such as dividing 0.0 by 0.0). - - The reason that we distinguish overflow checking from other kinds - of range constraint checking is that a failure of an overflow - check can generate an incorrect value, but cannot cause erroneous - behavior. This is unlike the situation with a constraint check on - an array subscript, where failure to perform the check can result - in random memory description, or the range check on a case - statement, where failure to perform the check can cause a wild - jump. - - Note again that `-gnato' is off by default, so overflow checking is - not performed in default mode. This means that out of the box, - with the default settings, GNAT does not do all the checks - expected from the language description in the Ada Reference - Manual. If you want all constraint checks to be performed, as - described in this Manual, then you must explicitly use the -gnato - switch either on the `gnatmake' or `gcc' command. - - `-gnatE' - Enables dynamic checks for access-before-elaboration on subprogram - calls and generic instantiations. For full details of the effect - and use of this switch, *Note Compiling Using gcc::. - - The setting of these switches only controls the default setting of the - checks. You may modify them using either `Suppress' (to remove checks) - or `Unsuppress' (to add back suppressed checks) pragmas in the program - source. - -  - File: gnat_ug_unx.info, Node: Stack Overflow Checking, Next: Run-Time Control, Prev: Run-Time Checks, Up: Switches for gcc - - Stack Overflow Checking - ----------------------- - - For most operating systems, `gcc' does not perform stack overflow - checking by default. This means that if the main environment task or - some other task exceeds the available stack space, then unpredictable - behavior will occur. - - To activate stack checking, compile all units with the gcc option - `-fstack-check'. For example: - - gcc -c -fstack-check package1.adb - - Units compiled with this option will generate extra instructions to - check that any use of the stack (for procedure calls or for declaring - local variables in declare blocks) do not exceed the available stack - space. If the space is exceeded, then a `Storage_Error' exception is - raised. - - For declared tasks, the stack size is always controlled by the size - given in an applicable `Storage_Size' pragma (or is set to the default - size if no pragma is used. - - For the environment task, the stack size depends on system defaults - and is unknown to the compiler. The stack may even dynamically grow on - some systems, precluding the normal Ada semantics for stack overflow. - In the worst case, unbounded stack usage, causes unbounded stack - expansion resulting in the system running out of virtual memory. - - The stack checking may still work correctly if a fixed size stack is - allocated, but this cannot be guaranteed. To ensure that a clean - exception is signalled for stack overflow, set the environment variable - `GNAT_STACK_LIMIT' to indicate the maximum stack area that can be used, - as in: - - SET GNAT_STACK_LIMIT 1600 - - The limit is given in kilobytes, so the above declaration would set the - stack limit of the environment task to 1.6 megabytes. Note that the - only purpose of this usage is to limit the amount of stack used by the - environment task. If it is necessary to increase the amount of stack - for the environment task, then this is an operating systems issue, and - must be addressed with the appropriate operating systems commands. - -  - File: gnat_ug_unx.info, Node: Run-Time Control, Next: Validity Checking, Prev: Stack Overflow Checking, Up: Switches for gcc - - Run-Time Control - ---------------- - - `-gnatT nnn' - The `gnatT' switch can be used to specify the time-slicing value - to be used for task switching between equal priority tasks. The - value `nnn' is given in microseconds as a decimal integer. - - Setting the time-slicing value is only effective if the underlying - thread control system can accommodate time slicing. Check the - documentation of your operating system for details. Note that the - time-slicing value can also be set by use of pragma `Time_Slice' - or by use of the `t' switch in the gnatbind step. The pragma - overrides a command line argument if both are present, and the `t' - switch for gnatbind overrides both the pragma and the `gcc' - command line switch. - -  - File: gnat_ug_unx.info, Node: Using gcc for Syntax Checking, Next: Using gcc for Semantic Checking, Prev: Style Checking, Up: Switches for gcc - - Using `gcc' for Syntax Checking - ------------------------------- - - `-gnats' - The `s' stands for syntax. - - Run GNAT in syntax checking only mode. For example, the command - - $ gcc -c -gnats x.adb - - compiles file `x.adb' in syntax-check-only mode. You can check a - series of files in a single command , and can use wild cards to - specify such a group of files. Note that you must specify the - `-c' (compile only) flag in addition to the `-gnats' flag. . - - You may use other switches in conjunction with `-gnats'. In - particular, `-gnatl' and `-gnatv' are useful to control the format - of any generated error messages. - - The output is simply the error messages, if any. No object file or - ALI file is generated by a syntax-only compilation. Also, no units - other than the one specified are accessed. For example, if a unit - `X' `with''s a unit `Y', compiling unit `X' in syntax check only - mode does not access the source file containing unit `Y'. - - Normally, GNAT allows only a single unit in a source file. - However, this restriction does not apply in syntax-check-only - mode, and it is possible to check a file containing multiple - compilation units concatenated together. This is primarily used by - the `gnatchop' utility (*note Renaming Files Using gnatchop::). - -  - File: gnat_ug_unx.info, Node: Using gcc for Semantic Checking, Next: Compiling Ada 83 Programs, Prev: Using gcc for Syntax Checking, Up: Switches for gcc - - Using `gcc' for Semantic Checking - --------------------------------- - - `-gnatc' - The `c' stands for check. Causes the compiler to operate in - semantic check mode, with full checking for all illegalities - specified in the Ada 95 Reference Manual, but without generation - of any object code (no object file is generated). - - Because dependent files must be accessed, you must follow the GNAT - semantic restrictions on file structuring to operate in this mode: - - * The needed source files must be accessible (*note Search - Paths and the Run-Time Library (RTL)::). - - * Each file must contain only one compilation unit. - - * The file name and unit name must match (*note File Naming - Rules::). - - The output consists of error messages as appropriate. No object - file is generated. An `ALI' file is generated for use in the - context of cross-reference tools, but this file is marked as not - being suitable for binding (since no object file is generated). - The checking corresponds exactly to the notion of legality in the - Ada 95 Reference Manual. - - Any unit can be compiled in semantics-checking-only mode, including - units that would not normally be compiled (subunits, and - specifications where a separate body is present). - -  - File: gnat_ug_unx.info, Node: Compiling Ada 83 Programs, Next: Character Set Control, Prev: Using gcc for Semantic Checking, Up: Switches for gcc - - Compiling Ada 83 Programs - ------------------------- - - `-gnat83' - Although GNAT is primarily an Ada 95 compiler, it accepts this - switch to specify that an Ada 83 program is to be compiled in - Ada83 mode. If you specify this switch, GNAT rejects most Ada 95 - extensions and applies Ada 83 semantics where this can be done - easily. It is not possible to guarantee this switch does a perfect - job; for example, some subtle tests, such as are found in earlier - ACVC tests (that have been removed from the ACVC suite for Ada - 95), may not compile correctly. However, for most purposes, using - this switch should help to ensure that programs that compile - correctly under the `-gnat83' switch can be ported easily to an - Ada 83 compiler. This is the main use of the switch. - - With few exceptions (most notably the need to use `<>' on - unconstrained generic formal parameters, the use of the new Ada 95 - keywords, and the use of packages with optional bodies), it is not - necessary to use the `-gnat83' switch when compiling Ada 83 - programs, because, with rare exceptions, Ada 95 is upwardly - compatible with Ada 83. This means that a correct Ada 83 program - is usually also a correct Ada 95 program. - -  - File: gnat_ug_unx.info, Node: Character Set Control, Next: File Naming Control, Prev: Compiling Ada 83 Programs, Up: Switches for gcc - - Character Set Control - --------------------- - - `-gnatiC' - Normally GNAT recognizes the Latin-1 character set in source - program identifiers, as described in the Ada 95 Reference Manual. - This switch causes GNAT to recognize alternate character sets in - identifiers. C is a single character indicating the character - set, as follows: - - `1' - Latin-1 identifiers - - `2' - Latin-2 letters allowed in identifiers - - `3' - Latin-3 letters allowed in identifiers - - `4' - Latin-4 letters allowed in identifiers - - `5' - Latin-5 (Cyrillic) letters allowed in identifiers - - `9' - Latin-9 letters allowed in identifiers - - `p' - IBM PC letters (code page 437) allowed in identifiers - - `8' - IBM PC letters (code page 850) allowed in identifiers - - `f' - Full upper-half codes allowed in identifiers - - `n' - No upper-half codes allowed in identifiers - - `w' - Wide-character codes (that is, codes greater than 255) - allowed in identifiers - - *Note Foreign Language Representation::, for full details on the - implementation of these character sets. - - `-gnatWE' - Specify the method of encoding for wide characters. E is one of - the following: - - `h' - Hex encoding (brackets coding also recognized) - - `u' - Upper half encoding (brackets encoding also recognized) - - `s' - Shift/JIS encoding (brackets encoding also recognized) - - `e' - EUC encoding (brackets encoding also recognized) - - `8' - UTF-8 encoding (brackets encoding also recognized) - - `b' - Brackets encoding only (default value) For full details on - the these encoding methods see *Note Wide Character Encodings::. - Note that brackets coding is always accepted, even if one of the - other options is specified, so for example `-gnatW8' specifies - that both brackets and `UTF-8' encodings will be recognized. The - units that are with'ed directly or indirectly will be scanned - using the specified representation scheme, and so if one of the - non-brackets scheme is used, it must be used consistently - throughout the program. However, since brackets encoding is always - recognized, it may be conveniently used in standard libraries, - allowing these libraries to be used with any of the available - coding schemes. scheme. If no `-gnatW?' parameter is present, - then the default representation is Brackets encoding only. - - Note that the wide character representation that is specified - (explicitly or by default) for the main program also acts as the - default encoding used for Wide_Text_IO files if not specifically - overridden by a WCEM form parameter. - -  - File: gnat_ug_unx.info, Node: File Naming Control, Next: Subprogram Inlining Control, Prev: Character Set Control, Up: Switches for gcc - - File Naming Control - ------------------- - - `-gnatkN' - Activates file name "krunching". N, a decimal integer in the range - 1-999, indicates the maximum allowable length of a file name (not - including the `.ads' or `.adb' extension). The default is not to - enable file name krunching. - - For the source file naming rules, *Note File Naming Rules::. - -  - File: gnat_ug_unx.info, Node: Subprogram Inlining Control, Next: Auxiliary Output Control, Prev: File Naming Control, Up: Switches for gcc - - Subprogram Inlining Control - --------------------------- - - `-gnatn' - The `n' here is intended to suggest the first syllable of the word - "inline". GNAT recognizes and processes `Inline' pragmas. - However, for the inlining to actually occur, optimization must be - enabled. To enable inlining across unit boundaries, this is, - inlining a call in one unit of a subprogram declared in a - `with''ed unit, you must also specify this switch. In the absence - of this switch, GNAT does not attempt inlining across units and - does not need to access the bodies of subprograms for which - `pragma Inline' is specified if they are not in the current unit. - - If you specify this switch the compiler will access these bodies, - creating an extra source dependency for the resulting object file, - and where possible, the call will be inlined. For further details - on when inlining is possible see *Note Inlining of Subprograms::. - - `-gnatN' - The front end inlining activated by this switch is generally more - extensive, and quite often more effective than the standard - `-gnatn' inlining mode. It will also generate additional - dependencies. - -  - File: gnat_ug_unx.info, Node: Auxiliary Output Control, Next: Debugging Control, Prev: Subprogram Inlining Control, Up: Switches for gcc - - Auxiliary Output Control - ------------------------ - - `-gnatt' - Causes GNAT to write the internal tree for a unit to a file (with - the extension `.adt'. This not normally required, but is used by - separate analysis tools. Typically these tools do the necessary - compilations automatically, so you should not have to specify this - switch in normal operation. - - `-gnatu' - Print a list of units required by this compilation on `stdout'. - The listing includes all units on which the unit being compiled - depends either directly or indirectly. - - `-pass-exit-codes' - If this switch is not used, the exit code returned by `gcc' when - compiling multiple files indicates whether all source files have - been successfully used to generate object files or not. - - When `-pass-exit-codes' is used, `gcc' exits with an extended exit - status and allows an integrated development environment to better - react to a compilation failure. Those exit status are: - - 5 - There was an error in at least one source file. - - 3 - At least one source file did not generate an object file. - - 2 - The compiler died unexpectedly (internal error for example). - - 0 - An object file has been generated for every source file. - -  - File: gnat_ug_unx.info, Node: Debugging Control, Next: Units to Sources Mapping Files, Prev: Auxiliary Output Control, Up: Switches for gcc - - Debugging Control - ----------------- - - `-gnatdX' - Activate internal debugging switches. X is a letter or digit, or - string of letters or digits, which specifies the type of debugging - outputs desired. Normally these are used only for internal - development or system debugging purposes. You can find full - documentation for these switches in the body of the `Debug' unit - in the compiler source file `debug.adb'. - - `-gnatG' - This switch causes the compiler to generate auxiliary output - containing a pseudo-source listing of the generated expanded code. - Like most Ada compilers, GNAT works by first transforming the high - level Ada code into lower level constructs. For example, tasking - operations are transformed into calls to the tasking run-time - routines. A unique capability of GNAT is to list this expanded - code in a form very close to normal Ada source. This is very - useful in understanding the implications of various Ada usage on - the efficiency of the generated code. There are many cases in Ada - (e.g. the use of controlled types), where simple Ada statements can - generate a lot of run-time code. By using `-gnatG' you can identify - these cases, and consider whether it may be desirable to modify - the coding approach to improve efficiency. - - The format of the output is very similar to standard Ada source, - and is easily understood by an Ada programmer. The following - special syntactic additions correspond to low level features used - in the generated code that do not have any exact analogies in pure - Ada source form. The following is a partial list of these special - constructions. See the specification of package `Sprint' in file - `sprint.ads' for a full list. - - `new XXX [storage_pool = YYY]' - Shows the storage pool being used for an allocator. - - `at end PROCEDURE-NAME;' - Shows the finalization (cleanup) procedure for a scope. - - `(if EXPR then EXPR else EXPR)' - Conditional expression equivalent to the `x?y:z' construction - in C. - - `TARGET^(SOURCE)' - A conversion with floating-point truncation instead of - rounding. - - `TARGET?(SOURCE)' - A conversion that bypasses normal Ada semantic checking. In - particular enumeration types and fixed-point types are - treated simply as integers. - - `TARGET?^(SOURCE)' - Combines the above two cases. - - `X #/ Y' - `X #mod Y' - `X #* Y' - `X #rem Y' - A division or multiplication of fixed-point values which are - treated as integers without any kind of scaling. - - `free EXPR [storage_pool = XXX]' - Shows the storage pool associated with a `free' statement. - - `freeze TYPENAME [ACTIONS]' - Shows the point at which TYPENAME is frozen, with possible - associated actions to be performed at the freeze point. - - `reference ITYPE' - Reference (and hence definition) to internal type ITYPE. - - `FUNCTION-NAME! (ARG, ARG, ARG)' - Intrinsic function call. - - `LABELNAME : label' - Declaration of label LABELNAME. - - `EXPR && EXPR && EXPR ... && EXPR' - A multiple concatenation (same effect as EXPR & EXPR & EXPR, - but handled more efficiently). - - `[constraint_error]' - Raise the `Constraint_Error' exception. - - `EXPRESSION'reference' - A pointer to the result of evaluating EXPRESSION. - - `TARGET-TYPE!(SOURCE-EXPRESSION)' - An unchecked conversion of SOURCE-EXPRESSION to TARGET-TYPE. - - `[NUMERATOR/DENOMINATOR]' - Used to represent internal real literals (that) have no exact - representation in base 2-16 (for example, the result of - compile time evaluation of the expression 1.0/27.0). - - `-gnatD' - This switch is used in conjunction with `-gnatG' to cause the - expanded source, as described above to be written to files - with names `xxx.dg', where `xxx' is the normal file name, for - example, if the source file name is `hello.adb', then a file - `hello.adb.dg' will be written. The debugging information - generated by the `gcc' `-g' switch will refer to the generated - `xxx.dg' file. This allows you to do source level debugging - using the generated code which is sometimes useful for - complex code, for example to find out exactly which part of a - complex construction raised an exception. This switch also - suppress generation of cross-reference information (see - -gnatx). - - `-gnatC' - In the generated debugging information, and also in the case - of long external names, the compiler uses a compression - mechanism if the name is very long. This compression method - uses a checksum, and avoids trouble on some operating systems - which have difficulty with very long names. The `-gnatC' - switch forces this compression approach to be used on all - external names and names in the debugging information tables. - This reduces the size of the generated executable, at the - expense of making the naming scheme more complex. The - compression only affects the qualification of the name. Thus - a name in the source: - - Very_Long_Package.Very_Long_Inner_Package.Var - - would normally appear in these tables as: - - very_long_package__very_long_inner_package__var - - but if the `-gnatC' switch is used, then the name appears as - - XCb7e0c705__var - - Here b7e0c705 is a compressed encoding of the qualification - prefix. The GNAT Ada aware version of GDB understands these - encoded prefixes, so if this debugger is used, the encoding - is largely hidden from the user of the compiler. - - `-gnatR[0|1|2|3][s]' - This switch controls output from the compiler of a listing showing - representation information for declared types and objects. For - `-gnatR0', no information is output (equivalent to omitting the - `-gnatR' switch). For `-gnatR1' (which is the default, so `-gnatR' - with no parameter has the same effect), size and alignment - information is listed for declared array and record types. For - `-gnatR2', size and alignment information is listed for all - expression information for values that are computed at run time for - variant records. These symbolic expressions have a mostly obvious - format with #n being used to represent the value of the n'th - discriminant. See source files `repinfo.ads/adb' in the `GNAT' - sources for full detalis on the format of `-gnatR3' output. If the - switch is followed by an s (e.g. `-gnatR2s'), then the output is - to a file with the name `file.rep' where file is the name of the - corresponding source file. - - `-gnatx' - Normally the compiler generates full cross-referencing information - in the `ALI' file. This information is used by a number of tools, - including `gnatfind' and `gnatxref'. The -gnatx switch suppresses - this information. This saves some space and may slightly speed up - compilation, but means that these tools cannot be used. - -  - File: gnat_ug_unx.info, Node: Units to Sources Mapping Files, Prev: Debugging Control, Up: Switches for gcc - - Units to Sources Mapping Files - ------------------------------ - - `-gnatemPATH' - A mapping file is a way to communicate to the compiler two - mappings: from unit names to file names (without any directory - information) and from file names to path names (with full - directory information). These mappings are used by the compiler to - short-circuit the path search. - - A mapping file is a sequence of sets of three lines. In each set, - the first line is the unit name, in lower case, with "%s" appended - for specifications and "%b" appended for bodies; the second line - is the file name; and the third line is the path name. - - Example: - main%b - main.2.ada - /gnat/project1/sources/main.2.ada - - When the switch `-gnatem' is specified, the compiler will create - in memory the two mappings from the specified file. If there is - any problem (non existent file, truncated file or duplicate - entries), no mapping will be created. - - Several `-gnatem' switches may be specified; however, only the last - one on the command line will be taken into account. - - When using a project file, `gnatmake' create a temporary mapping - file and communicates it to the compiler using this switch. - -  - File: gnat_ug_unx.info, Node: Search Paths and the Run-Time Library (RTL), Next: Order of Compilation Issues, Prev: Switches for gcc, Up: Compiling Using gcc - - Search Paths and the Run-Time Library (RTL) - =========================================== - - With the GNAT source-based library system, the compiler must be able to - find source files for units that are needed by the unit being compiled. - Search paths are used to guide this process. - - The compiler compiles one source file whose name must be given - explicitly on the command line. In other words, no searching is done - for this file. To find all other source files that are needed (the most - common being the specs of units), the compiler examines the following - directories, in the following order: - - 1. The directory containing the source file of the main unit being - compiled (the file name on the command line). - - 2. Each directory named by an `-I' switch given on the `gcc' command - line, in the order given. - - 3. Each of the directories listed in the value of the - `ADA_INCLUDE_PATH' environment variable. Construct this value - exactly as the `PATH' environment variable: a list of directory - names separated by colons (semicolons when working with the NT - version). - - 4. The content of the "ada_source_path" file which is part of the GNAT - installation tree and is used to store standard libraries such as - the GNAT Run Time Library (RTL) source files. *Note Installing an - Ada Library:: - - Specifying the switch `-I-' inhibits the use of the directory - containing the source file named in the command line. You can still - have this directory on your search path, but in this case it must be - explicitly requested with a `-I' switch. - - Specifying the switch `-nostdinc' inhibits the search of the default - location for the GNAT Run Time Library (RTL) source files. - - The compiler outputs its object files and ALI files in the current - working directory. Caution: The object file can be redirected with the - `-o' switch; however, `gcc' and `gnat1' have not been coordinated on - this so the ALI file will not go to the right place. Therefore, you - should avoid using the `-o' switch. - - The packages `Ada', `System', and `Interfaces' and their children - make up the GNAT RTL, together with the simple `System.IO' package used - in the "Hello World" example. The sources for these units are needed by - the compiler and are kept together in one directory. Not all of the - bodies are needed, but all of the sources are kept together anyway. In - a normal installation, you need not specify these directory names when - compiling or binding. Either the environment variables or the built-in - defaults cause these files to be found. - - In addition to the language-defined hierarchies (System, Ada and - Interfaces), the GNAT distribution provides a fourth hierarchy, - consisting of child units of GNAT. This is a collection of generally - useful routines. See the GNAT Reference Manual for further details. - - Besides simplifying access to the RTL, a major use of search paths is - in compiling sources from multiple directories. This can make - development environments much more flexible. - -  - File: gnat_ug_unx.info, Node: Order of Compilation Issues, Next: Examples, Prev: Search Paths and the Run-Time Library (RTL), Up: Compiling Using gcc - - Order of Compilation Issues - =========================== - - If, in our earlier example, there was a spec for the `hello' procedure, - it would be contained in the file `hello.ads'; yet this file would not - have to be explicitly compiled. This is the result of the model we - chose to implement library management. Some of the consequences of this - model are as follows: - - * There is no point in compiling specs (except for package specs - with no bodies) because these are compiled as needed by clients. If - you attempt a useless compilation, you will receive an error - message. It is also useless to compile subunits because they are - compiled as needed by the parent. - - * There are no order of compilation requirements: performing a - compilation never obsoletes anything. The only way you can obsolete - something and require recompilations is to modify one of the - source files on which it depends. - - * There is no library as such, apart from the ALI files (*note The - Ada Library Information Files::, for information on the format of - these files). For now we find it convenient to create separate ALI - files, but eventually the information therein may be incorporated - into the object file directly. - - * When you compile a unit, the source files for the specs of all - units that it `with''s, all its subunits, and the bodies of any - generics it instantiates must be available (reachable by the - search-paths mechanism described above), or you will receive a - fatal error message. - -  - File: gnat_ug_unx.info, Node: Examples, Prev: Order of Compilation Issues, Up: Compiling Using gcc - - Examples - ======== - - The following are some typical Ada compilation command line examples: - - `$ gcc -c xyz.adb' - Compile body in file `xyz.adb' with all default options. - - `$ gcc -c -O2 -gnata xyz-def.adb' - Compile the child unit package in file `xyz-def.adb' with extensive - optimizations, and pragma `Assert'/`Debug' statements enabled. - - `$ gcc -c -gnatc abc-def.adb' - Compile the subunit in file `abc-def.adb' in semantic-checking-only - mode. - -  - File: gnat_ug_unx.info, Node: Binding Using gnatbind, Next: Linking Using gnatlink, Prev: Compiling Using gcc, Up: Top - - Binding Using `gnatbind' - ************************ - - * Menu: - - * Running gnatbind:: - * Generating the Binder Program in C:: - * Consistency-Checking Modes:: - * Binder Error Message Control:: - * Elaboration Control:: - * Output Control:: - * Binding with Non-Ada Main Programs:: - * Binding Programs with No Main Subprogram:: - * Summary of Binder Switches:: - * Command-Line Access:: - * Search Paths for gnatbind:: - * Examples of gnatbind Usage:: - - This chapter describes the GNAT binder, `gnatbind', which is used to - bind compiled GNAT objects. The `gnatbind' program performs four - separate functions: - - 1. Checks that a program is consistent, in accordance with the rules - in Chapter 10 of the Ada 95 Reference Manual. In particular, error - messages are generated if a program uses inconsistent versions of a - given unit. - - 2. Checks that an acceptable order of elaboration exists for the - program and issues an error message if it cannot find an order of - elaboration that satisfies the rules in Chapter 10 of the Ada 95 - Language Manual. - - 3. Generates a main program incorporating the given elaboration order. - This program is a small Ada package (body and spec) that must be - subsequently compiled using the GNAT compiler. The necessary - compilation step is usually performed automatically by `gnatlink'. - The two most important functions of this program are to call the - elaboration routines of units in an appropriate order and to call - the main program. - - 4. Determines the set of object files required by the given main - program. This information is output in the forms of comments in - the generated program, to be read by the `gnatlink' utility used - to link the Ada application. - -  - File: gnat_ug_unx.info, Node: Running gnatbind, Next: Generating the Binder Program in C, Up: Binding Using gnatbind - - Running `gnatbind' - ================== - - The form of the `gnatbind' command is - - $ gnatbind [SWITCHES] MAINPROG[.ali] [SWITCHES] - - where MAINPROG.adb is the Ada file containing the main program unit - body. If no switches are specified, `gnatbind' constructs an Ada - package in two files which names are `b~ADA_MAIN.ads', and - `b~ADA_MAIN.adb'. For example, if given the parameter `hello.ali', for - a main program contained in file `hello.adb', the binder output files - would be `b~hello.ads' and `b~hello.adb'. - - When doing consistency checking, the binder takes into consideration - any source files it can locate. For example, if the binder determines - that the given main program requires the package `Pack', whose `.ali' - file is `pack.ali' and whose corresponding source spec file is - `pack.ads', it attempts to locate the source file `pack.ads' (using the - same search path conventions as previously described for the `gcc' - command). If it can locate this source file, it checks that the time - stamps or source checksums of the source and its references to in `ali' - files match. In other words, any `ali' files that mentions this spec - must have resulted from compiling this version of the source file (or - in the case where the source checksums match, a version close enough - that the difference does not matter). - - The effect of this consistency checking, which includes source - files, is that the binder ensures that the program is consistent with - the latest version of the source files that can be located at bind - time. Editing a source file without compiling files that depend on the - source file cause error messages to be generated by the binder. - - For example, suppose you have a main program `hello.adb' and a - package `P', from file `p.ads' and you perform the following steps: - - 1. Enter `gcc -c hello.adb' to compile the main program. - - 2. Enter `gcc -c p.ads' to compile package `P'. - - 3. Edit file `p.ads'. - - 4. Enter `gnatbind hello'. - - At this point, the file `p.ali' contains an out-of-date time stamp - because the file `p.ads' has been edited. The attempt at binding fails, - and the binder generates the following error messages: - - error: "hello.adb" must be recompiled ("p.ads" has been modified) - error: "p.ads" has been modified and must be recompiled - - Now both files must be recompiled as indicated, and then the bind can - succeed, generating a main program. You need not normally be concerned - with the contents of this file, but it is similar to the following which - is the binder file generated for a simple "hello world" program. - - -- The package is called Ada_Main unless this name is actually used - -- as a unit name in the partition, in which case some other unique - -- name is used. - - with System; - package ada_main is - - Elab_Final_Code : Integer; - pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code"); - - -- The main program saves the parameters (argument count, - -- argument values, environment pointer) in global variables - -- for later access by other units including - -- Ada.Command_Line. - - gnat_argc : Integer; - gnat_argv : System.Address; - gnat_envp : System.Address; - - -- The actual variables are stored in a library routine. This - -- is useful for some shared library situations, where there - -- are problems if variables are not in the library. - - pragma Import (C, gnat_argc); - pragma Import (C, gnat_argv); - pragma Import (C, gnat_envp); - - -- The exit status is similarly an external location - - gnat_exit_status : Integer; - pragma Import (C, gnat_exit_status); - - GNAT_Version : constant String := - "GNAT Version: 3.15w (20010315)"; - pragma Export (C, GNAT_Version, "__gnat_version"); - - -- This is the generated adafinal routine that performs - -- finalization at the end of execution. In the case where - -- Ada is the main program, this main program makes a call - -- to adafinal at program termination. - - procedure adafinal; - pragma Export (C, adafinal, "adafinal"); - - -- This is the generated adainit routine that performs - -- initialization at the start of execution. In the case - -- where Ada is the main program, this main program makes - -- a call to adainit at program startup. - - procedure adainit; - pragma Export (C, adainit, "adainit"); - - -- This routine is called at the start of execution. It is - -- a dummy routine that is used by the debugger to breakpoint - -- at the start of execution. - - procedure Break_Start; - pragma Import (C, Break_Start, "__gnat_break_start"); - - -- This is the actual generated main program (it would be - -- suppressed if the no main program switch were used). As - -- required by standard system conventions, this program has - -- the external name main. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer; - pragma Export (C, main, "main"); - - -- The following set of constants give the version - -- identification values for every unit in the bound - -- partition. This identification is computed from all - -- dependent semantic units, and corresponds to the - -- string that would be returned by use of the - -- Body_Version or Version attributes. - - type Version_32 is mod 2 ** 32; - u00001 : constant Version_32 := 16#7880BEB3#; - u00002 : constant Version_32 := 16#0D24CBD0#; - u00003 : constant Version_32 := 16#3283DBEB#; - u00004 : constant Version_32 := 16#2359F9ED#; - u00005 : constant Version_32 := 16#664FB847#; - u00006 : constant Version_32 := 16#68E803DF#; - u00007 : constant Version_32 := 16#5572E604#; - u00008 : constant Version_32 := 16#46B173D8#; - u00009 : constant Version_32 := 16#156A40CF#; - u00010 : constant Version_32 := 16#033DABE0#; - u00011 : constant Version_32 := 16#6AB38FEA#; - u00012 : constant Version_32 := 16#22B6217D#; - u00013 : constant Version_32 := 16#68A22947#; - u00014 : constant Version_32 := 16#18CC4A56#; - u00015 : constant Version_32 := 16#08258E1B#; - u00016 : constant Version_32 := 16#367D5222#; - u00017 : constant Version_32 := 16#20C9ECA4#; - u00018 : constant Version_32 := 16#50D32CB6#; - u00019 : constant Version_32 := 16#39A8BB77#; - u00020 : constant Version_32 := 16#5CF8FA2B#; - u00021 : constant Version_32 := 16#2F1EB794#; - u00022 : constant Version_32 := 16#31AB6444#; - u00023 : constant Version_32 := 16#1574B6E9#; - u00024 : constant Version_32 := 16#5109C189#; - u00025 : constant Version_32 := 16#56D770CD#; - u00026 : constant Version_32 := 16#02F9DE3D#; - u00027 : constant Version_32 := 16#08AB6B2C#; - u00028 : constant Version_32 := 16#3FA37670#; - u00029 : constant Version_32 := 16#476457A0#; - u00030 : constant Version_32 := 16#731E1B6E#; - u00031 : constant Version_32 := 16#23C2E789#; - u00032 : constant Version_32 := 16#0F1BD6A1#; - u00033 : constant Version_32 := 16#7C25DE96#; - u00034 : constant Version_32 := 16#39ADFFA2#; - u00035 : constant Version_32 := 16#571DE3E7#; - u00036 : constant Version_32 := 16#5EB646AB#; - u00037 : constant Version_32 := 16#4249379B#; - u00038 : constant Version_32 := 16#0357E00A#; - u00039 : constant Version_32 := 16#3784FB72#; - u00040 : constant Version_32 := 16#2E723019#; - u00041 : constant Version_32 := 16#623358EA#; - u00042 : constant Version_32 := 16#107F9465#; - u00043 : constant Version_32 := 16#6843F68A#; - u00044 : constant Version_32 := 16#63305874#; - u00045 : constant Version_32 := 16#31E56CE1#; - u00046 : constant Version_32 := 16#02917970#; - u00047 : constant Version_32 := 16#6CCBA70E#; - u00048 : constant Version_32 := 16#41CD4204#; - u00049 : constant Version_32 := 16#572E3F58#; - u00050 : constant Version_32 := 16#20729FF5#; - u00051 : constant Version_32 := 16#1D4F93E8#; - u00052 : constant Version_32 := 16#30B2EC3D#; - u00053 : constant Version_32 := 16#34054F96#; - u00054 : constant Version_32 := 16#5A199860#; - u00055 : constant Version_32 := 16#0E7F912B#; - u00056 : constant Version_32 := 16#5760634A#; - u00057 : constant Version_32 := 16#5D851835#; - - -- The following Export pragmas export the version numbers - -- with symbolic names ending in B (for body) or S - -- (for spec) so that they can be located in a link. The - -- information provided here is sufficient to track down - -- the exact versions of units used in a given build. - - pragma Export (C, u00001, "helloB"); - pragma Export (C, u00002, "system__standard_libraryB"); - pragma Export (C, u00003, "system__standard_libraryS"); - pragma Export (C, u00004, "adaS"); - pragma Export (C, u00005, "ada__text_ioB"); - pragma Export (C, u00006, "ada__text_ioS"); - pragma Export (C, u00007, "ada__exceptionsB"); - pragma Export (C, u00008, "ada__exceptionsS"); - pragma Export (C, u00009, "gnatS"); - pragma Export (C, u00010, "gnat__heap_sort_aB"); - pragma Export (C, u00011, "gnat__heap_sort_aS"); - pragma Export (C, u00012, "systemS"); - pragma Export (C, u00013, "system__exception_tableB"); - pragma Export (C, u00014, "system__exception_tableS"); - pragma Export (C, u00015, "gnat__htableB"); - pragma Export (C, u00016, "gnat__htableS"); - pragma Export (C, u00017, "system__exceptionsS"); - pragma Export (C, u00018, "system__machine_state_operationsB"); - pragma Export (C, u00019, "system__machine_state_operationsS"); - pragma Export (C, u00020, "system__machine_codeS"); - pragma Export (C, u00021, "system__storage_elementsB"); - pragma Export (C, u00022, "system__storage_elementsS"); - pragma Export (C, u00023, "system__secondary_stackB"); - pragma Export (C, u00024, "system__secondary_stackS"); - pragma Export (C, u00025, "system__parametersB"); - pragma Export (C, u00026, "system__parametersS"); - pragma Export (C, u00027, "system__soft_linksB"); - pragma Export (C, u00028, "system__soft_linksS"); - pragma Export (C, u00029, "system__stack_checkingB"); - pragma Export (C, u00030, "system__stack_checkingS"); - pragma Export (C, u00031, "system__tracebackB"); - pragma Export (C, u00032, "system__tracebackS"); - pragma Export (C, u00033, "ada__streamsS"); - pragma Export (C, u00034, "ada__tagsB"); - pragma Export (C, u00035, "ada__tagsS"); - pragma Export (C, u00036, "system__string_opsB"); - pragma Export (C, u00037, "system__string_opsS"); - pragma Export (C, u00038, "interfacesS"); - pragma Export (C, u00039, "interfaces__c_streamsB"); - pragma Export (C, u00040, "interfaces__c_streamsS"); - pragma Export (C, u00041, "system__file_ioB"); - pragma Export (C, u00042, "system__file_ioS"); - pragma Export (C, u00043, "ada__finalizationB"); - pragma Export (C, u00044, "ada__finalizationS"); - pragma Export (C, u00045, "system__finalization_rootB"); - pragma Export (C, u00046, "system__finalization_rootS"); - pragma Export (C, u00047, "system__finalization_implementationB"); - pragma Export (C, u00048, "system__finalization_implementationS"); - pragma Export (C, u00049, "system__string_ops_concat_3B"); - pragma Export (C, u00050, "system__string_ops_concat_3S"); - pragma Export (C, u00051, "system__stream_attributesB"); - pragma Export (C, u00052, "system__stream_attributesS"); - pragma Export (C, u00053, "ada__io_exceptionsS"); - pragma Export (C, u00054, "system__unsigned_typesS"); - pragma Export (C, u00055, "system__file_control_blockS"); - pragma Export (C, u00056, "ada__finalization__list_controllerB"); - pragma Export (C, u00057, "ada__finalization__list_controllerS"); - - -- BEGIN ELABORATION ORDER - -- ada (spec) - -- gnat (spec) - -- gnat.heap_sort_a (spec) - -- gnat.heap_sort_a (body) - -- gnat.htable (spec) - -- gnat.htable (body) - -- interfaces (spec) - -- system (spec) - -- system.machine_code (spec) - -- system.parameters (spec) - -- system.parameters (body) - -- interfaces.c_streams (spec) - -- interfaces.c_streams (body) - -- system.standard_library (spec) - -- ada.exceptions (spec) - -- system.exception_table (spec) - -- system.exception_table (body) - -- ada.io_exceptions (spec) - -- system.exceptions (spec) - -- system.storage_elements (spec) - -- system.storage_elements (body) - -- system.machine_state_operations (spec) - -- system.machine_state_operations (body) - -- system.secondary_stack (spec) - -- system.stack_checking (spec) - -- system.soft_links (spec) - -- system.soft_links (body) - -- system.stack_checking (body) - -- system.secondary_stack (body) - -- system.standard_library (body) - -- system.string_ops (spec) - -- system.string_ops (body) - -- ada.tags (spec) - -- ada.tags (body) - -- ada.streams (spec) - -- system.finalization_root (spec) - -- system.finalization_root (body) - -- system.string_ops_concat_3 (spec) - -- system.string_ops_concat_3 (body) - -- system.traceback (spec) - -- system.traceback (body) - -- ada.exceptions (body) - -- system.unsigned_types (spec) - -- system.stream_attributes (spec) - -- system.stream_attributes (body) - -- system.finalization_implementation (spec) - -- system.finalization_implementation (body) - -- ada.finalization (spec) - -- ada.finalization (body) - -- ada.finalization.list_controller (spec) - -- ada.finalization.list_controller (body) - -- system.file_control_block (spec) - -- system.file_io (spec) - -- system.file_io (body) - -- ada.text_io (spec) - -- ada.text_io (body) - -- hello (body) - -- END ELABORATION ORDER - - end ada_main; - - -- The following source file name pragmas allow the generated file - -- names to be unique for different main programs. They are needed - -- since the package name will always be Ada_Main. - - pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads"); - pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb"); - - -- Generated package body for Ada_Main starts here - - package body ada_main is - - -- The actual finalization is performed by calling the - -- library routine in System.Standard_Library.Adafinal - - procedure Do_Finalize; - pragma Import (C, Do_Finalize, "system__standard_library__adafinal"); - - ------------- - -- adainit -- - ------------- - - procedure adainit is - - -- These booleans are set to True once the associated unit has - -- been elaborated. It is also used to avoid elaborating the - -- same unit twice. - - E040 : Boolean; pragma Import (Ada, E040, "interfaces__c_streams_E"); - E008 : Boolean; pragma Import (Ada, E008, "ada__exceptions_E"); - E014 : Boolean; pragma Import (Ada, E014, "system__exception_table_E"); - E053 : Boolean; pragma Import (Ada, E053, "ada__io_exceptions_E"); - E017 : Boolean; pragma Import (Ada, E017, "system__exceptions_E"); - E024 : Boolean; pragma Import (Ada, E024, "system__secondary_stack_E"); - E030 : Boolean; pragma Import (Ada, E030, "system__stack_checking_E"); - E028 : Boolean; pragma Import (Ada, E028, "system__soft_links_E"); - E035 : Boolean; pragma Import (Ada, E035, "ada__tags_E"); - E033 : Boolean; pragma Import (Ada, E033, "ada__streams_E"); - E046 : Boolean; pragma Import (Ada, E046, "system__finalization_root_E"); - E048 : Boolean; pragma Import (Ada, E048, "system__finalization_implementation_E"); - E044 : Boolean; pragma Import (Ada, E044, "ada__finalization_E"); - E057 : Boolean; pragma Import (Ada, E057, "ada__finalization__list_controller_E"); - E055 : Boolean; pragma Import (Ada, E055, "system__file_control_block_E"); - E042 : Boolean; pragma Import (Ada, E042, "system__file_io_E"); - E006 : Boolean; pragma Import (Ada, E006, "ada__text_io_E"); - - -- Set_Globals is a library routine that stores away the - -- value of the indicated set of global values in global - -- variables within the library. - - procedure Set_Globals - (Main_Priority : Integer; - Time_Slice_Value : Integer; - WC_Encoding : Character; - Locking_Policy : Character; - Queuing_Policy : Character; - Task_Dispatching_Policy : Character; - Adafinal : System.Address; - Unreserve_All_Interrupts : Integer; - Exception_Tracebacks : Integer); - pragma Import (C, Set_Globals, "__gnat_set_globals"); - - -- SDP_Table_Build is a library routine used to build the - -- exception tables. See unit Ada.Exceptions in files - -- a-except.ads/adb for full details of how zero cost - -- exception handling works. This procedure, the call to - -- it, and the two following tables are all omitted if the - -- build is in longjmp/setjump exception mode. - - procedure SDP_Table_Build - (SDP_Addresses : System.Address; - SDP_Count : Natural; - Elab_Addresses : System.Address; - Elab_Addr_Count : Natural); - pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build"); - - -- Table of Unit_Exception_Table addresses. Used for zero - -- cost exception handling to build the top level table. - - ST : aliased constant array (1 .. 23) of System.Address := ( - Hello'UET_Address, - Ada.Text_Io'UET_Address, - Ada.Exceptions'UET_Address, - Gnat.Heap_Sort_A'UET_Address, - System.Exception_Table'UET_Address, - System.Machine_State_Operations'UET_Address, - System.Secondary_Stack'UET_Address, - System.Parameters'UET_Address, - System.Soft_Links'UET_Address, - System.Stack_Checking'UET_Address, - System.Traceback'UET_Address, - Ada.Streams'UET_Address, - Ada.Tags'UET_Address, - System.String_Ops'UET_Address, - Interfaces.C_Streams'UET_Address, - System.File_Io'UET_Address, - Ada.Finalization'UET_Address, - System.Finalization_Root'UET_Address, - System.Finalization_Implementation'UET_Address, - System.String_Ops_Concat_3'UET_Address, - System.Stream_Attributes'UET_Address, - System.File_Control_Block'UET_Address, - Ada.Finalization.List_Controller'UET_Address); - - -- Table of addresses of elaboration routines. Used for - -- zero cost exception handling to make sure these - -- addresses are included in the top level procedure - -- address table. - - EA : aliased constant array (1 .. 23) of System.Address := ( - adainit'Code_Address, - Do_Finalize'Code_Address, - Ada.Exceptions'Elab_Spec'Address, - System.Exceptions'Elab_Spec'Address, - Interfaces.C_Streams'Elab_Spec'Address, - System.Exception_Table'Elab_Body'Address, - Ada.Io_Exceptions'Elab_Spec'Address, - System.Stack_Checking'Elab_Spec'Address, - System.Soft_Links'Elab_Body'Address, - System.Secondary_Stack'Elab_Body'Address, - Ada.Tags'Elab_Spec'Address, - Ada.Tags'Elab_Body'Address, - Ada.Streams'Elab_Spec'Address, - System.Finalization_Root'Elab_Spec'Address, - Ada.Exceptions'Elab_Body'Address, - System.Finalization_Implementation'Elab_Spec'Address, - System.Finalization_Implementation'Elab_Body'Address, - Ada.Finalization'Elab_Spec'Address, - Ada.Finalization.List_Controller'Elab_Spec'Address, - System.File_Control_Block'Elab_Spec'Address, - System.File_Io'Elab_Body'Address, - Ada.Text_Io'Elab_Spec'Address, - Ada.Text_Io'Elab_Body'Address); - - -- Start of processing for adainit - - begin - - -- Call SDP_Table_Build to build the top level procedure - -- table for zero cost exception handling (omitted in - -- longjmp/setjump mode). - - SDP_Table_Build (ST'Address, 23, EA'Address, 23); - - -- Call Set_Globals to record various information for - -- this partition. The values are derived by the binder - -- from information stored in the ali files by the compiler. - - Set_Globals - (Main_Priority => -1, - -- Priority of main program, -1 if no pragma Priority used - - Time_Slice_Value => -1, - -- Time slice from Time_Slice pragma, -1 if none used - - WC_Encoding => 'b', - -- Wide_Character encoding used, default is brackets - - Locking_Policy => ' ', - -- Locking_Policy used, default of space means not - -- specified, otherwise it is the first character of - -- the policy name. - - Queuing_Policy => ' ', - -- Queuing_Policy used, default of space means not - -- specified, otherwise it is the first character of - -- the policy name. - - Task_Dispatching_Policy => ' ', - -- Task_Dispatching_Policy used, default of space means - -- not specified, otherwise first character of the - -- policy name. - - Adafinal => System.Null_Address, - -- Address of Adafinal routine, not used anymore - - Unreserve_All_Interrupts => 0, - -- Set true if pragma Unreserve_All_Interrupts was used - - Exception_Tracebacks => 0); - -- Indicates if exception tracebacks are enabled - - Elab_Final_Code := 1; - - -- Now we have the elaboration calls for all units in the partition. - -- The Elab_Spec and Elab_Body attributes generate references to the - -- implicit elaboration procedures generated by the compiler for - -- each unit that requires elaboration. - - if not E040 then - Interfaces.C_Streams'Elab_Spec; - end if; - E040 := True; - if not E008 then - Ada.Exceptions'Elab_Spec; - end if; - if not E014 then - System.Exception_Table'Elab_Body; - E014 := True; - end if; - if not E053 then - Ada.Io_Exceptions'Elab_Spec; - E053 := True; - end if; - if not E017 then - System.Exceptions'Elab_Spec; - E017 := True; - end if; - if not E030 then - System.Stack_Checking'Elab_Spec; - end if; - if not E028 then - System.Soft_Links'Elab_Body; - E028 := True; - end if; - E030 := True; - if not E024 then - System.Secondary_Stack'Elab_Body; - E024 := True; - end if; - if not E035 then - Ada.Tags'Elab_Spec; - end if; - if not E035 then - Ada.Tags'Elab_Body; - E035 := True; - end if; - if not E033 then - Ada.Streams'Elab_Spec; - E033 := True; - end if; - if not E046 then - System.Finalization_Root'Elab_Spec; - end if; - E046 := True; - if not E008 then - Ada.Exceptions'Elab_Body; - E008 := True; - end if; - if not E048 then - System.Finalization_Implementation'Elab_Spec; - end if; - if not E048 then - System.Finalization_Implementation'Elab_Body; - E048 := True; - end if; - if not E044 then - Ada.Finalization'Elab_Spec; - end if; - E044 := True; - if not E057 then - Ada.Finalization.List_Controller'Elab_Spec; - end if; - E057 := True; - if not E055 then - System.File_Control_Block'Elab_Spec; - E055 := True; - end if; - if not E042 then - System.File_Io'Elab_Body; - E042 := True; - end if; - if not E006 then - Ada.Text_Io'Elab_Spec; - end if; - if not E006 then - Ada.Text_Io'Elab_Body; - E006 := True; - end if; - - Elab_Final_Code := 0; - end adainit; - - -------------- - -- adafinal -- - -------------- - - procedure adafinal is - begin - Do_Finalize; - end adafinal; - - ---------- - -- main -- - ---------- - - -- main is actually a function, as in the ANSI C standard, - -- defined to return the exit status. The three parameters - -- are the argument count, argument values and environment - -- pointer. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer - is - -- The initialize routine performs low level system - -- initialization using a standard library routine which - -- sets up signal handling and performs any other - -- required setup. The routine can be found in file - -- a-init.c. - - procedure initialize; - pragma Import (C, initialize, "__gnat_initialize"); - - -- The finalize routine performs low level system - -- finalization using a standard library routine. The - -- routine is found in file a-final.c and in the standard - -- distribution is a dummy routine that does nothing, so - -- really this is a hook for special user finalization. - - procedure finalize; - pragma Import (C, finalize, "__gnat_finalize"); - - -- We get to the main program of the partition by using - -- pragma Import because if we try to with the unit and - -- call it Ada style, then not only do we waste time - -- recompiling it, but also, we don't really know the right - -- switches (e.g. identifier character set) to be used - -- to compile it. - - procedure Ada_Main_Program; - pragma Import (Ada, Ada_Main_Program, "_ada_hello"); - - -- Start of processing for main - - begin - -- Save global variables - - gnat_argc := argc; - gnat_argv := argv; - gnat_envp := envp; - - -- Call low level system initialization - - Initialize; - - -- Call our generated Ada initialization routine - - adainit; - - -- This is the point at which we want the debugger to get - -- control - - Break_Start; - - -- Now we call the main program of the partition - - Ada_Main_Program; - - -- Perform Ada finalization - - adafinal; - - -- Perform low level system finalization - - Finalize; - - -- Return the proper exit status - return (gnat_exit_status); - end; - - -- This section is entirely comments, so it has no effect on the - -- compilation of the Ada_Main package. It provides the list of - -- object files and linker options, as well as some standard - -- libraries needed for the link. The gnatlink utility parses - -- this b~hello.adb file to read these comment lines to generate - -- the appropriate command line arguments for the call to the - -- system linker. The BEGIN/END lines are used for sentinels for - -- this parsing operation. - - -- The exact file names will of course depend on the environment, - -- host/target and location of files on the host system. - - -- BEGIN Object file/option list - -- ./hello.o - -- -L./ - -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/ - -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a - -- END Object file/option list - - end ada_main; - - The Ada code in the above example is exactly what is generated by the - binder. We have added comments to more clearly indicate the function of - each part of the generated `Ada_Main' package. - - The code is standard Ada in all respects, and can be processed by any - tools that handle Ada. In particular, it is possible to use the debugger - in Ada mode to debug the generated Ada_Main package. For example, - suppose that for reasons that you do not understand, your program is - blowing up during elaboration of the body of `Ada.Text_IO'. To chase - this bug down, you can place a breakpoint on the call: - - Ada.Text_Io'Elab_Body; - - and trace the elaboration routine for this package to find out where - the problem might be (more usually of course you would be debugging - elaboration code in your own application). - -  - File: gnat_ug_unx.info, Node: Generating the Binder Program in C, Next: Consistency-Checking Modes, Prev: Running gnatbind, Up: Binding Using gnatbind - - Generating the Binder Program in C - ================================== - - In most normal usage, the default mode of `gnatbind' which is to - generate the main package in Ada, as described in the previous section. - In particular, this means that any Ada programmer can read and - understand the generated main program. It can also be debugged just - like any other Ada code provided the `-g' switch is used for `gnatbind' - and `gnatlink'. - - However for some purposes it may be convenient to generate the main - program in C rather than Ada. This may for example be helpful when you - are generating a mixed language program with the main program in C. The - GNAT compiler itself is an example. The use of the `-C' switch for both - `gnatbind' and `gnatlink' will cause the program to be generated in C - (and compiled using the gnu C compiler). The following shows the C code - generated for the same "Hello World" program: - - - #ifdef __STDC__ - #define PARAMS(paramlist) paramlist - #else - #define PARAMS(paramlist) () - #endif - - extern void __gnat_set_globals - PARAMS ((int, int, int, int, int, int, - void (*) PARAMS ((void)), int, int)); - extern void adafinal PARAMS ((void)); - extern void adainit PARAMS ((void)); - extern void system__standard_library__adafinal PARAMS ((void)); - extern int main PARAMS ((int, char **, char **)); - extern void exit PARAMS ((int)); - extern void __gnat_break_start PARAMS ((void)); - extern void _ada_hello PARAMS ((void)); - extern void __gnat_initialize PARAMS ((void)); - extern void __gnat_finalize PARAMS ((void)); - - extern void ada__exceptions___elabs PARAMS ((void)); - extern void system__exceptions___elabs PARAMS ((void)); - extern void interfaces__c_streams___elabs PARAMS ((void)); - extern void system__exception_table___elabb PARAMS ((void)); - extern void ada__io_exceptions___elabs PARAMS ((void)); - extern void system__stack_checking___elabs PARAMS ((void)); - extern void system__soft_links___elabb PARAMS ((void)); - extern void system__secondary_stack___elabb PARAMS ((void)); - extern void ada__tags___elabs PARAMS ((void)); - extern void ada__tags___elabb PARAMS ((void)); - extern void ada__streams___elabs PARAMS ((void)); - extern void system__finalization_root___elabs PARAMS ((void)); - extern void ada__exceptions___elabb PARAMS ((void)); - extern void system__finalization_implementation___elabs PARAMS ((void)); - extern void system__finalization_implementation___elabb PARAMS ((void)); - extern void ada__finalization___elabs PARAMS ((void)); - extern void ada__finalization__list_controller___elabs PARAMS ((void)); - extern void system__file_control_block___elabs PARAMS ((void)); - extern void system__file_io___elabb PARAMS ((void)); - extern void ada__text_io___elabs PARAMS ((void)); - extern void ada__text_io___elabb PARAMS ((void)); - - extern int __gnat_inside_elab_final_code; - - extern int gnat_argc; - extern char **gnat_argv; - extern char **gnat_envp; - extern int gnat_exit_status; - - char __gnat_version[] = "GNAT Version: 3.15w (20010315)"; - void adafinal () { - system__standard_library__adafinal (); - } - - void adainit () - { - extern char ada__exceptions_E; - extern char system__exceptions_E; - extern char interfaces__c_streams_E; - extern char system__exception_table_E; - extern char ada__io_exceptions_E; - extern char system__secondary_stack_E; - extern char system__stack_checking_E; - extern char system__soft_links_E; - extern char ada__tags_E; - extern char ada__streams_E; - extern char system__finalization_root_E; - extern char system__finalization_implementation_E; - extern char ada__finalization_E; - extern char ada__finalization__list_controller_E; - extern char system__file_control_block_E; - extern char system__file_io_E; - extern char ada__text_io_E; - - extern void *__gnat_hello__SDP; - extern void *__gnat_ada__text_io__SDP; - extern void *__gnat_ada__exceptions__SDP; - extern void *__gnat_gnat__heap_sort_a__SDP; - extern void *__gnat_system__exception_table__SDP; - extern void *__gnat_system__machine_state_operations__SDP; - extern void *__gnat_system__secondary_stack__SDP; - extern void *__gnat_system__parameters__SDP; - extern void *__gnat_system__soft_links__SDP; - extern void *__gnat_system__stack_checking__SDP; - extern void *__gnat_system__traceback__SDP; - extern void *__gnat_ada__streams__SDP; - extern void *__gnat_ada__tags__SDP; - extern void *__gnat_system__string_ops__SDP; - extern void *__gnat_interfaces__c_streams__SDP; - extern void *__gnat_system__file_io__SDP; - extern void *__gnat_ada__finalization__SDP; - extern void *__gnat_system__finalization_root__SDP; - extern void *__gnat_system__finalization_implementation__SDP; - extern void *__gnat_system__string_ops_concat_3__SDP; - extern void *__gnat_system__stream_attributes__SDP; - extern void *__gnat_system__file_control_block__SDP; - extern void *__gnat_ada__finalization__list_controller__SDP; - - void **st[23] = { - &__gnat_hello__SDP, - &__gnat_ada__text_io__SDP, - &__gnat_ada__exceptions__SDP, - &__gnat_gnat__heap_sort_a__SDP, - &__gnat_system__exception_table__SDP, - &__gnat_system__machine_state_operations__SDP, - &__gnat_system__secondary_stack__SDP, - &__gnat_system__parameters__SDP, - &__gnat_system__soft_links__SDP, - &__gnat_system__stack_checking__SDP, - &__gnat_system__traceback__SDP, - &__gnat_ada__streams__SDP, - &__gnat_ada__tags__SDP, - &__gnat_system__string_ops__SDP, - &__gnat_interfaces__c_streams__SDP, - &__gnat_system__file_io__SDP, - &__gnat_ada__finalization__SDP, - &__gnat_system__finalization_root__SDP, - &__gnat_system__finalization_implementation__SDP, - &__gnat_system__string_ops_concat_3__SDP, - &__gnat_system__stream_attributes__SDP, - &__gnat_system__file_control_block__SDP, - &__gnat_ada__finalization__list_controller__SDP}; - - extern void ada__exceptions___elabs (); - extern void system__exceptions___elabs (); - extern void interfaces__c_streams___elabs (); - extern void system__exception_table___elabb (); - extern void ada__io_exceptions___elabs (); - extern void system__stack_checking___elabs (); - extern void system__soft_links___elabb (); - extern void system__secondary_stack___elabb (); - extern void ada__tags___elabs (); - extern void ada__tags___elabb (); - extern void ada__streams___elabs (); - extern void system__finalization_root___elabs (); - extern void ada__exceptions___elabb (); - extern void system__finalization_implementation___elabs (); - extern void system__finalization_implementation___elabb (); - extern void ada__finalization___elabs (); - extern void ada__finalization__list_controller___elabs (); - extern void system__file_control_block___elabs (); - extern void system__file_io___elabb (); - extern void ada__text_io___elabs (); - extern void ada__text_io___elabb (); - - void (*ea[23]) () = { - adainit, - system__standard_library__adafinal, - ada__exceptions___elabs, - system__exceptions___elabs, - interfaces__c_streams___elabs, - system__exception_table___elabb, - ada__io_exceptions___elabs, - system__stack_checking___elabs, - system__soft_links___elabb, - system__secondary_stack___elabb, - ada__tags___elabs, - ada__tags___elabb, - ada__streams___elabs, - system__finalization_root___elabs, - ada__exceptions___elabb, - system__finalization_implementation___elabs, - system__finalization_implementation___elabb, - ada__finalization___elabs, - ada__finalization__list_controller___elabs, - system__file_control_block___elabs, - system__file_io___elabb, - ada__text_io___elabs, - ada__text_io___elabb}; - - __gnat_SDP_Table_Build (&st, 23, ea, 23); - __gnat_set_globals ( - -1, /* Main_Priority */ - -1, /* Time_Slice_Value */ - 'b', /* WC_Encoding */ - ' ', /* Locking_Policy */ - ' ', /* Queuing_Policy */ - ' ', /* Tasking_Dispatching_Policy */ - 0, /* Finalization routine address, not used anymore */ - 0, /* Unreserve_All_Interrupts */ - 0); /* Exception_Tracebacks */ - - __gnat_inside_elab_final_code = 1; - - if (ada__exceptions_E == 0) { - ada__exceptions___elabs (); - } - if (system__exceptions_E == 0) { - system__exceptions___elabs (); - system__exceptions_E++; - } - if (interfaces__c_streams_E == 0) { - interfaces__c_streams___elabs (); - } - interfaces__c_streams_E = 1; - if (system__exception_table_E == 0) { - system__exception_table___elabb (); - system__exception_table_E++; - } - if (ada__io_exceptions_E == 0) { - ada__io_exceptions___elabs (); - ada__io_exceptions_E++; - } - if (system__stack_checking_E == 0) { - system__stack_checking___elabs (); - } - if (system__soft_links_E == 0) { - system__soft_links___elabb (); - system__soft_links_E++; - } - system__stack_checking_E = 1; - if (system__secondary_stack_E == 0) { - system__secondary_stack___elabb (); - system__secondary_stack_E++; - } - if (ada__tags_E == 0) { - ada__tags___elabs (); - } - if (ada__tags_E == 0) { - ada__tags___elabb (); - ada__tags_E++; - } - if (ada__streams_E == 0) { - ada__streams___elabs (); - ada__streams_E++; - } - if (system__finalization_root_E == 0) { - system__finalization_root___elabs (); - } - system__finalization_root_E = 1; - if (ada__exceptions_E == 0) { - ada__exceptions___elabb (); - ada__exceptions_E++; - } - if (system__finalization_implementation_E == 0) { - system__finalization_implementation___elabs (); - } - if (system__finalization_implementation_E == 0) { - system__finalization_implementation___elabb (); - system__finalization_implementation_E++; - } - if (ada__finalization_E == 0) { - ada__finalization___elabs (); - } - ada__finalization_E = 1; - if (ada__finalization__list_controller_E == 0) { - ada__finalization__list_controller___elabs (); - } - ada__finalization__list_controller_E = 1; - if (system__file_control_block_E == 0) { - system__file_control_block___elabs (); - system__file_control_block_E++; - } - if (system__file_io_E == 0) { - system__file_io___elabb (); - system__file_io_E++; - } - if (ada__text_io_E == 0) { - ada__text_io___elabs (); - } - if (ada__text_io_E == 0) { - ada__text_io___elabb (); - ada__text_io_E++; - } - - __gnat_inside_elab_final_code = 0; - } - int main (argc, argv, envp) - int argc; - char **argv; - char **envp; - { - gnat_argc = argc; - gnat_argv = argv; - gnat_envp = envp; - - __gnat_initialize (); - adainit (); - __gnat_break_start (); - - _ada_hello (); - - system__standard_library__adafinal (); - __gnat_finalize (); - exit (gnat_exit_status); - } - unsigned helloB = 0x7880BEB3; - unsigned system__standard_libraryB = 0x0D24CBD0; - unsigned system__standard_libraryS = 0x3283DBEB; - unsigned adaS = 0x2359F9ED; - unsigned ada__text_ioB = 0x47C85FC4; - unsigned ada__text_ioS = 0x496FE45C; - unsigned ada__exceptionsB = 0x74F50187; - unsigned ada__exceptionsS = 0x6736945B; - unsigned gnatS = 0x156A40CF; - unsigned gnat__heap_sort_aB = 0x033DABE0; - unsigned gnat__heap_sort_aS = 0x6AB38FEA; - unsigned systemS = 0x0331C6FE; - unsigned system__exceptionsS = 0x20C9ECA4; - unsigned system__exception_tableB = 0x68A22947; - unsigned system__exception_tableS = 0x394BADD5; - unsigned gnat__htableB = 0x08258E1B; - unsigned gnat__htableS = 0x367D5222; - unsigned system__machine_state_operationsB = 0x4F3B7492; - unsigned system__machine_state_operationsS = 0x182F5CF4; - unsigned system__storage_elementsB = 0x2F1EB794; - unsigned system__storage_elementsS = 0x102C83C7; - unsigned system__secondary_stackB = 0x1574B6E9; - unsigned system__secondary_stackS = 0x708E260A; - unsigned system__parametersB = 0x56D770CD; - unsigned system__parametersS = 0x237E39BE; - unsigned system__soft_linksB = 0x08AB6B2C; - unsigned system__soft_linksS = 0x1E2491F3; - unsigned system__stack_checkingB = 0x476457A0; - unsigned system__stack_checkingS = 0x5299FCED; - unsigned system__tracebackB = 0x2971EBDE; - unsigned system__tracebackS = 0x2E9C3122; - unsigned ada__streamsS = 0x7C25DE96; - unsigned ada__tagsB = 0x39ADFFA2; - unsigned ada__tagsS = 0x769A0464; - unsigned system__string_opsB = 0x5EB646AB; - unsigned system__string_opsS = 0x63CED018; - unsigned interfacesS = 0x0357E00A; - unsigned interfaces__c_streamsB = 0x3784FB72; - unsigned interfaces__c_streamsS = 0x2E723019; - unsigned system__file_ioB = 0x623358EA; - unsigned system__file_ioS = 0x31F873E6; - unsigned ada__finalizationB = 0x6843F68A; - unsigned ada__finalizationS = 0x63305874; - unsigned system__finalization_rootB = 0x31E56CE1; - unsigned system__finalization_rootS = 0x23169EF3; - unsigned system__finalization_implementationB = 0x6CCBA70E; - unsigned system__finalization_implementationS = 0x604AA587; - unsigned system__string_ops_concat_3B = 0x572E3F58; - unsigned system__string_ops_concat_3S = 0x01F57876; - unsigned system__stream_attributesB = 0x1D4F93E8; - unsigned system__stream_attributesS = 0x30B2EC3D; - unsigned ada__io_exceptionsS = 0x34054F96; - unsigned system__unsigned_typesS = 0x7B9E7FE3; - unsigned system__file_control_blockS = 0x2FF876A8; - unsigned ada__finalization__list_controllerB = 0x5760634A; - unsigned ada__finalization__list_controllerS = 0x5D851835; - - /* BEGIN ELABORATION ORDER - ada (spec) - gnat (spec) - gnat.heap_sort_a (spec) - gnat.htable (spec) - gnat.htable (body) - interfaces (spec) - system (spec) - system.parameters (spec) - system.standard_library (spec) - ada.exceptions (spec) - system.exceptions (spec) - system.parameters (body) - gnat.heap_sort_a (body) - interfaces.c_streams (spec) - interfaces.c_streams (body) - system.exception_table (spec) - system.exception_table (body) - ada.io_exceptions (spec) - system.storage_elements (spec) - system.storage_elements (body) - system.machine_state_operations (spec) - system.machine_state_operations (body) - system.secondary_stack (spec) - system.stack_checking (spec) - system.soft_links (spec) - system.soft_links (body) - system.stack_checking (body) - system.secondary_stack (body) - system.standard_library (body) - system.string_ops (spec) - system.string_ops (body) - ada.tags (spec) - ada.tags (body) - ada.streams (spec) - system.finalization_root (spec) - system.finalization_root (body) - system.string_ops_concat_3 (spec) - system.string_ops_concat_3 (body) - system.traceback (spec) - system.traceback (body) - ada.exceptions (body) - system.unsigned_types (spec) - system.stream_attributes (spec) - system.stream_attributes (body) - system.finalization_implementation (spec) - system.finalization_implementation (body) - ada.finalization (spec) - ada.finalization (body) - ada.finalization.list_controller (spec) - ada.finalization.list_controller (body) - system.file_control_block (spec) - system.file_io (spec) - system.file_io (body) - ada.text_io (spec) - ada.text_io (body) - hello (body) - END ELABORATION ORDER */ - - /* BEGIN Object file/option list - ./hello.o - -L./ - -L/usr/local/gnat/lib/gcc-lib/alpha-dec-osf5.1/2.8.1/adalib/ - /usr/local/gnat/lib/gcc-lib/alpha-dec-osf5.1/2.8.1/adalib/libgnat.a - -lexc - END Object file/option list */ - - Here again, the C code is exactly what is generated by the binder. The - functions of the various parts of this code correspond in an obvious - manner with the commented Ada code shown in the example in the previous - section. - -  - File: gnat_ug_unx.info, Node: Consistency-Checking Modes, Next: Binder Error Message Control, Prev: Generating the Binder Program in C, Up: Binding Using gnatbind - - Consistency-Checking Modes - ========================== - - As described in the previous section, by default `gnatbind' checks that - object files are consistent with one another and are consistent with - any source files it can locate. The following switches control binder - access to sources. - - `-s' - Require source files to be present. In this mode, the binder must - be able to locate all source files that are referenced, in order - to check their consistency. In normal mode, if a source file - cannot be located it is simply ignored. If you specify this - switch, a missing source file is an error. - - `-x' - Exclude source files. In this mode, the binder only checks that ALI - files are consistent with one another. Source files are not - accessed. The binder runs faster in this mode, and there is still - a guarantee that the resulting program is self-consistent. If a - source file has been edited since it was last compiled, and you - specify this switch, the binder will not detect that the object - file is out of date with respect to the source file. Note that - this is the mode that is automatically used by `gnatmake' because - in this case the checking against sources has already been - performed by `gnatmake' in the course of compilation (i.e. before - binding). - -  - File: gnat_ug_unx.info, Node: Binder Error Message Control, Next: Elaboration Control, Prev: Consistency-Checking Modes, Up: Binding Using gnatbind - - Binder Error Message Control - ============================ - - The following switches provide control over the generation of error - messages from the binder: - - `-v' - Verbose mode. In the normal mode, brief error messages are - generated to `stderr'. If this switch is present, a header is - written to `stdout' and any error messages are directed to - `stdout'. All that is written to `stderr' is a brief summary - message. - - `-b' - Generate brief error messages to `stderr' even if verbose mode is - specified. This is relevant only when used with the `-v' switch. - - `-mN' - Limits the number of error messages to N, a decimal integer in the - range 1-999. The binder terminates immediately if this limit is - reached. - - `-MXXX' - Renames the generated main program from `main' to `xxx'. This is - useful in the case of some cross-building environments, where the - actual main program is separate from the one generated by - `gnatbind'. - - `-ws' - Suppress all warning messages. - - `-we' - Treat any warning messages as fatal errors. - - `-t' - The binder performs a number of consistency checks including: - - * Check that time stamps of a given source unit are consistent - - * Check that checksums of a given source unit are consistent - - * Check that consistent versions of `GNAT' were used for - compilation - - * Check consistency of configuration pragmas as required - - Normally failure of such checks, in accordance with the consistency - requirements of the Ada Reference Manual, causes error messages to - be generated which abort the binder and prevent the output of a - binder file and subsequent link to obtain an executable. - - The `-t' switch converts these error messages into warnings, so - that binding and linking can continue to completion even in the - presence of such errors. The result may be a failed link (due to - missing symbols), or a non-functional executable which has - undefined semantics. _This means that `-t' should be used only in - unusual situations, with extreme care._ - -  - File: gnat_ug_unx.info, Node: Elaboration Control, Next: Output Control, Prev: Binder Error Message Control, Up: Binding Using gnatbind - - Elaboration Control - =================== - - The following switches provide additional control over the elaboration - order. For full details see *Note Elaboration Order Handling in GNAT::. - - `-p' - Normally the binder attempts to choose an elaboration order that is - likely to minimize the likelihood of an elaboration order error - resulting in raising a `Program_Error' exception. This switch - reverses the action of the binder, and requests that it - deliberately choose an order that is likely to maximize the - likelihood of an elaboration error. This is useful in ensuring - portability and avoiding dependence on accidental fortuitous - elaboration ordering. - - Normally it only makes sense to use the `-p' switch if dynamic - elaboration checking is used (`-gnatE' switch used for - compilation). This is because in the default static elaboration - mode, all necessary `Elaborate_All' pragmas are implicitly - inserted. These implicit pragmas are still respected by the binder - in `-p' mode, so a safe elaboration order is assured. - -  - File: gnat_ug_unx.info, Node: Output Control, Next: Binding with Non-Ada Main Programs, Prev: Elaboration Control, Up: Binding Using gnatbind - - Output Control - ============== - - The following switches allow additional control over the output - generated by the binder. - - `-A' - Generate binder program in Ada (default). The binder program is - named `b~MAINPROG.adb' by default. This can be changed with `-o' - `gnatbind' option. - - `-c' - Check only. Do not generate the binder output file. In this mode - the binder performs all error checks but does not generate an - output file. - - `-C' - Generate binder program in C. The binder program is named - `b_MAINPROG.c'. This can be changed with `-o' `gnatbind' option. - - `-e' - Output complete list of elaboration-order dependencies, showing the - reason for each dependency. This output can be rather extensive - but may be useful in diagnosing problems with elaboration order. - The output is written to `stdout'. - - `-h' - Output usage information. The output is written to `stdout'. - - `-K' - Output linker options to `stdout'. Includes library search paths, - contents of pragmas Ident and Linker_Options, and libraries added - by `gnatbind'. - - `-l' - Output chosen elaboration order. The output is written to `stdout'. - - `-O' - Output full names of all the object files that must be linked to - provide the Ada component of the program. The output is written to - `stdout'. This list includes the files explicitly supplied and - referenced by the user as well as implicitly referenced run-time - unit files. The latter are omitted if the corresponding units - reside in shared libraries. The directory names for the run-time - units depend on the system configuration. - - `-o FILE' - Set name of output file to FILE instead of the normal - `b~MAINPROG.adb' default. Note that FILE denote the Ada binder - generated body filename. In C mode you would normally give FILE an - extension of `.c' because it will be a C source program. Note - that if this option is used, then linking must be done manually. - It is not possible to use gnatlink in this case, since it cannot - locate the binder file. - - `-r' - Generate list of `pragma Rerstrictions' that could be applied to - the current unit. This is useful for code audit purposes, and also - may be used to improve code generation in some cases. - -  - File: gnat_ug_unx.info, Node: Binding with Non-Ada Main Programs, Next: Binding Programs with No Main Subprogram, Prev: Output Control, Up: Binding Using gnatbind - - Binding with Non-Ada Main Programs - ================================== - - In our description so far we have assumed that the main program is in - Ada, and that the task of the binder is to generate a corresponding - function `main' that invokes this Ada main program. GNAT also supports - the building of executable programs where the main program is not in - Ada, but some of the called routines are written in Ada and compiled - using GNAT (*note Mixed Language Programming::). The following switch - is used in this situation: - - `-n' - No main program. The main program is not in Ada. - - In this case, most of the functions of the binder are still required, - but instead of generating a main program, the binder generates a file - containing the following callable routines: - - `adainit' - You must call this routine to initialize the Ada part of the - program by calling the necessary elaboration routines. A call to - `adainit' is required before the first call to an Ada subprogram. - - Note that it is assumed that the basic execution environment must - be setup to be appropriate for Ada execution at the point where - the first Ada subprogram is called. In particular, if the Ada code - will do any floating-point operations, then the FPU must be setup - in an appropriate manner. For the case of the x86, for example, - full precision mode is required. The procedure - GNAT.Float_Control.Reset may be used to ensure that the FPU is in - the right state. - - `adafinal' - You must call this routine to perform any library-level - finalization required by the Ada subprograms. A call to `adafinal' - is required after the last call to an Ada subprogram, and before - the program terminates. - - If the `-n' switch is given, more than one ALI file may appear on the - command line for `gnatbind'. The normal "closure" calculation is - performed for each of the specified units. Calculating the closure - means finding out the set of units involved by tracing `with' - references. The reason it is necessary to be able to specify more than - one ALI file is that a given program may invoke two or more quite - separate groups of Ada units. - - The binder takes the name of its output file from the last specified - ALI file, unless overridden by the use of the `-o file'. The output is - an Ada unit in source form that can be compiled with GNAT unless the -C - switch is used in which case the output is a C source file, which must - be compiled using the C compiler. This compilation occurs - automatically as part of the `gnatlink' processing. - - Currently the GNAT run time requires a FPU using 80 bits mode - precision. Under targets where this is not the default it is required to - call GNAT.Float_Control.Reset before using floating point numbers (this - include float computation, float input and output) in the Ada code. A - side effect is that this could be the wrong mode for the foreign code - where floating point computation could be broken after this call. - -  - File: gnat_ug_unx.info, Node: Binding Programs with No Main Subprogram, Next: Summary of Binder Switches, Prev: Binding with Non-Ada Main Programs, Up: Binding Using gnatbind - - Binding Programs with No Main Subprogram - ======================================== - - It is possible to have an Ada program which does not have a main - subprogram. This program will call the elaboration routines of all the - packages, then the finalization routines. - - The following switch is used to bind programs organized in this - manner: - - `-z' - Normally the binder checks that the unit name given on the command - line corresponds to a suitable main subprogram. When this switch - is used, a list of ALI files can be given, and the execution of - the program consists of elaboration of these units in an - appropriate order. - -  - File: gnat_ug_unx.info, Node: Summary of Binder Switches, Next: Command-Line Access, Prev: Binding Programs with No Main Subprogram, Up: Binding Using gnatbind - - Summary of Binder Switches - ========================== - - The following are the switches available with `gnatbind': - - `-aO' - Specify directory to be searched for ALI files. - - `-aI' - Specify directory to be searched for source file. - - `-A' - Generate binder program in Ada (default) - - `-b' - Generate brief messages to `stderr' even if verbose mode set. - - `-c' - Check only, no generation of binder output file. - - `-C' - Generate binder program in C - - `-e' - Output complete list of elaboration-order dependencies. - - `-E' - Store tracebacks in exception occurrences when the target supports - it. This is the default with the zero cost exception mechanism. - This option is currently supported on the following targets: all - x86 ports, Solaris, Windows, HP-UX, AIX, PowerPC VxWorks and Alpha - VxWorks. See also the packages `GNAT.Traceback' and - `GNAT.Traceback.Symbolic' for more information. Note that on x86 - ports, you must not use `-fomit-frame-pointer' `gcc' option. - - `-h' - Output usage (help) information - - `-I' - Specify directory to be searched for source and ALI files. - - `-I-' - Do not look for sources in the current directory where `gnatbind' - was invoked, and do not look for ALI files in the directory - containing the ALI file named in the `gnatbind' command line. - - `-l' - Output chosen elaboration order. - - `-Lxxx' - Binds the units for library building. In this case the adainit and - adafinal procedures (See *note Binding with Non-Ada Main - Programs::) are renamed to xxxinit and xxxfinal. Implies -n. See - *note GNAT and Libraries:: for more details. - - `-Mxyz' - Rename generated main program from main to xyz - - `-mN' - Limit number of detected errors to N (1-999). - - `-n' - No main program. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-o FILE' - Name the output file FILE (default is `b~XXX.adb'). Note that if - this option is used, then linking must be done manually, gnatlink - cannot be used. - - `-O' - Output object list. - - `-p' - Pessimistic (worst-case) elaboration order - - `-s' - Require all source files to be present. - - `-static' - Link against a static GNAT run time. - - `-shared' - Link against a shared GNAT run time when available. - - `-t' - Tolerate time stamp and other consistency errors - - `-TN' - Set the time slice value to n microseconds. A value of zero means - no time slicing and also indicates to the tasking run time to - match as close as possible to the annex D requirements of the RM. - - `-v' - Verbose mode. Write error messages, header, summary output to - `stdout'. - - `-wX' - Warning mode (X=s/e for suppress/treat as error) - - `-x' - Exclude source files (check object consistency only). - - `-z' - No main subprogram. - - You may obtain this listing by running the program `gnatbind' with - no arguments. - -  - File: gnat_ug_unx.info, Node: Command-Line Access, Next: Search Paths for gnatbind, Prev: Summary of Binder Switches, Up: Binding Using gnatbind - - Command-Line Access - =================== - - The package `Ada.Command_Line' provides access to the command-line - arguments and program name. In order for this interface to operate - correctly, the two variables - - int gnat_argc; - char **gnat_argv; - - are declared in one of the GNAT library routines. These variables must - be set from the actual `argc' and `argv' values passed to the main - program. With no `n' present, `gnatbind' generates the C main program - to automatically set these variables. If the `n' switch is used, there - is no automatic way to set these variables. If they are not set, the - procedures in `Ada.Command_Line' will not be available, and any attempt - to use them will raise `Constraint_Error'. If command line access is - required, your main program must set `gnat_argc' and `gnat_argv' from - the `argc' and `argv' values passed to it. - -  - File: gnat_ug_unx.info, Node: Search Paths for gnatbind, Next: Examples of gnatbind Usage, Prev: Command-Line Access, Up: Binding Using gnatbind - - Search Paths for `gnatbind' - =========================== - - The binder takes the name of an ALI file as its argument and needs to - locate source files as well as other ALI files to verify object - consistency. - - For source files, it follows exactly the same search rules as `gcc' - (*note Search Paths and the Run-Time Library (RTL)::). For ALI files the - directories searched are: - - 1. The directory containing the ALI file named in the command line, - unless the switch `-I-' is specified. - - 2. All directories specified by `-I' switches on the `gnatbind' - command line, in the order given. - - 3. Each of the directories listed in the value of the - `ADA_OBJECTS_PATH' environment variable. Construct this value - exactly as the `PATH' environment variable: a list of directory - names separated by colons (semicolons when working with the NT - version of GNAT). - - 4. The content of the "ada_object_path" file which is part of the GNAT - installation tree and is used to store standard libraries such as - the GNAT Run Time Library (RTL) unless the switch `-nostdlib' is - specified. *Note Installing an Ada Library:: - - In the binder the switch `-I' is used to specify both source and - library file paths. Use `-aI' instead if you want to specify source - paths only, and `-aO' if you want to specify library paths only. This - means that for the binder `-I'DIR is equivalent to `-aI'DIR `-aO'DIR. - The binder generates the bind file (a C language source file) in the - current working directory. - - The packages `Ada', `System', and `Interfaces' and their children - make up the GNAT Run-Time Library, together with the package GNAT and - its children, which contain a set of useful additional library - functions provided by GNAT. The sources for these units are needed by - the compiler and are kept together in one directory. The ALI files and - object files generated by compiling the RTL are needed by the binder - and the linker and are kept together in one directory, typically - different from the directory containing the sources. In a normal - installation, you need not specify these directory names when compiling - or binding. Either the environment variables or the built-in defaults - cause these files to be found. - - Besides simplifying access to the RTL, a major use of search paths is - in compiling sources from multiple directories. This can make - development environments much more flexible. - -  - File: gnat_ug_unx.info, Node: Examples of gnatbind Usage, Prev: Search Paths for gnatbind, Up: Binding Using gnatbind - - Examples of `gnatbind' Usage - ============================ - - This section contains a number of examples of using the GNAT binding - utility `gnatbind'. - - `gnatbind hello' - The main program `Hello' (source program in `hello.adb') is bound - using the standard switch settings. The generated main program is - `b~hello.adb'. This is the normal, default use of the binder. - - `gnatbind hello -o mainprog.adb' - The main program `Hello' (source program in `hello.adb') is bound - using the standard switch settings. The generated main program is - `mainprog.adb' with the associated spec in `mainprog.ads'. Note - that you must specify the body here not the spec, in the case - where the output is in Ada. Note that if this option is used, then - linking must be done manually, since gnatlink will not be able to - find the generated file. - - `gnatbind main -C -o mainprog.c -x' - The main program `Main' (source program in `main.adb') is bound, - excluding source files from the consistency checking, generating - the file `mainprog.c'. - - `gnatbind -x main_program -C -o mainprog.c' - This command is exactly the same as the previous example. Switches - may appear anywhere in the command line, and single letter - switches may be combined into a single switch. - - `gnatbind -n math dbase -C -o ada-control.c' - The main program is in a language other than Ada, but calls to - subprograms in packages `Math' and `Dbase' appear. This call to - `gnatbind' generates the file `ada-control.c' containing the - `adainit' and `adafinal' routines to be called before and after - accessing the Ada units. - -  - File: gnat_ug_unx.info, Node: Linking Using gnatlink, Next: The GNAT Make Program gnatmake, Prev: Binding Using gnatbind, Up: Top - - Linking Using `gnatlink' - ************************ - - This chapter discusses `gnatlink', a utility program used to link Ada - programs and build an executable file. This is a simple program that - invokes the Unix linker (via the `gcc' command) with a correct list of - object files and library references. `gnatlink' automatically - determines the list of files and references for the Ada part of a - program. It uses the binder file generated by the binder to determine - this list. - - * Menu: - - * Running gnatlink:: - * Switches for gnatlink:: - * Setting Stack Size from gnatlink:: - * Setting Heap Size from gnatlink:: - -  - File: gnat_ug_unx.info, Node: Running gnatlink, Next: Switches for gnatlink, Up: Linking Using gnatlink - - Running `gnatlink' - ================== - - The form of the `gnatlink' command is - - $ gnatlink [SWITCHES] MAINPROG[.ali] [NON-ADA OBJECTS] - [LINKER OPTIONS] - - `MAINPROG.ali' references the ALI file of the main program. The `.ali' - extension of this file can be omitted. From this reference, `gnatlink' - locates the corresponding binder file `b~MAINPROG.adb' and, using the - information in this file along with the list of non-Ada objects and - linker options, constructs a Unix linker command file to create the - executable. - - The arguments following `MAINPROG.ali' are passed to the linker - uninterpreted. They typically include the names of object files for - units written in other languages than Ada and any library references - required to resolve references in any of these foreign language units, - or in `pragma Import' statements in any Ada units. - - LINKER OPTIONS is an optional list of linker specific switches. The - default linker called by gnatlink is GCC which in turn calls the - appropriate system linker usually called LD. Standard options for the - linker such as `-lmy_lib' or `-Ldir' can be added as is. For options - that are not recognized by GCC as linker options, the GCC switches - `-Xlinker' or `-Wl,' shall be used. Refer to the GCC documentation for - details. Here is an example showing how to generate a linker map - assuming that the underlying linker is GNU ld: - - $ gnatlink my_prog -Wl,-Map,MAPFILE - - Using LINKER OPTIONS it is possible to set the program stack and - heap size. See *note Setting Stack Size from gnatlink:: and *note - Setting Heap Size from gnatlink::. - - `gnatlink' determines the list of objects required by the Ada - program and prepends them to the list of objects passed to the linker. - `gnatlink' also gathers any arguments set by the use of `pragma - Linker_Options' and adds them to the list of arguments presented to the - linker. - -  - File: gnat_ug_unx.info, Node: Switches for gnatlink, Next: Setting Stack Size from gnatlink, Prev: Running gnatlink, Up: Linking Using gnatlink - - Switches for `gnatlink' - ======================= - - The following switches are available with the `gnatlink' utility: - - `-A' - The binder has generated code in Ada. This is the default. - - `-C' - If instead of generating a file in Ada, the binder has generated - one in C, then the linker needs to know about it. Use this switch - to signal to `gnatlink' that the binder has generated C code - rather than Ada code. - - `-f' - On some targets, the command line length is limited, and `gnatlink' - will generate a separate file for the linker if the list of object - files is too long. The `-f' flag forces this file to be generated - even if the limit is not exceeded. This is useful in some cases to - deal with special situations where the command line length is - exceeded. - - `-g' - The option to include debugging information causes the Ada bind - file (in other words, `b~MAINPROG.adb') to be compiled with `-g'. - In addition, the binder does not delete the `b~MAINPROG.adb', - `b~MAINPROG.o' and `b~MAINPROG.ali' files. Without `-g', the - binder removes these files by default. The same procedure apply if - a C bind file was generated using `-C' `gnatbind' option, in this - case the filenames are `b_MAINPROG.c' and `b_MAINPROG.o'. - - `-n' - Do not compile the file generated by the binder. This may be used - when a link is rerun with different options, but there is no need - to recompile the binder file. - - `-v' - Causes additional information to be output, including a full list - of the included object files. This switch option is most useful - when you want to see what set of object files are being used in - the link step. - - `-v -v' - Very verbose mode. Requests that the compiler operate in verbose - mode when it compiles the binder file, and that the system linker - run in verbose mode. - - `-o EXEC-NAME' - EXEC-NAME specifies an alternate name for the generated executable - program. If this switch is omitted, the executable has the same - name as the main unit. For example, `gnatlink try.ali' creates an - executable called `try'. - - `-b TARGET' - Compile your program to run on TARGET, which is the name of a - system configuration. You must have a GNAT cross-compiler built if - TARGET is not the same as your host system. - - `-BDIR' - Load compiler executables (for example, `gnat1', the Ada compiler) - from DIR instead of the default location. Only use this switch - when multiple versions of the GNAT compiler are available. See the - `gcc' manual page for further details. You would normally use the - `-b' or `-V' switch instead. - - `--GCC=COMPILER_NAME' - Program used for compiling the binder file. The default is - ``gcc''. You need to use quotes around COMPILER_NAME if - `compiler_name' contains spaces or other separator characters. As - an example `--GCC="foo -x -y"' will instruct `gnatlink' to use - `foo -x -y' as your compiler. Note that switch `-c' is always - inserted after your command name. Thus in the above example the - compiler command that will be used by `gnatlink' will be `foo -c - -x -y'. If several `--GCC=compiler_name' are used, only the last - COMPILER_NAME is taken into account. However, all the additional - switches are also taken into account. Thus, `--GCC="foo -x -y" - --GCC="bar -z -t"' is equivalent to `--GCC="bar -x -y -z -t"'. - - `--LINK=NAME' - NAME is the name of the linker to be invoked. This is especially - useful in mixed language programs since languages such as c++ - require their own linker to be used. When this switch is omitted, - the default name for the linker is (`gcc'). When this switch is - used, the specified linker is called instead of (`gcc') with - exactly the same parameters that would have been passed to (`gcc') - so if the desired linker requires different parameters it is - necessary to use a wrapper script that massages the parameters - before invoking the real linker. It may be useful to control the - exact invocation by using the verbose switch. - -  - File: gnat_ug_unx.info, Node: Setting Stack Size from gnatlink, Next: Setting Heap Size from gnatlink, Prev: Switches for gnatlink, Up: Linking Using gnatlink - - Setting Stack Size from `gnatlink' - ================================== - - It is possible to specify the program stack size from `gnatlink'. - Assuming that the underlying linker is GNU ld there is two ways to do - so: - - * using `-Xlinker' linker option - - $ gnatlink hello -Xlinker --stack=0x10000,0x1000 - - This set the stack reserve size to 0x10000 bytes and the stack - commit size to 0x1000 bytes. - - * using `-Wl' linker option - - $ gnatlink hello -Wl,--stack=0x1000000 - - This set the stack reserve size to 0x1000000 bytes. Note that with - `-Wl' option it is not possible to set the stack commit size - because the coma is a separator for this option. - - -  - File: gnat_ug_unx.info, Node: Setting Heap Size from gnatlink, Prev: Setting Stack Size from gnatlink, Up: Linking Using gnatlink - - Setting Heap Size from `gnatlink' - ================================= - - It is possible to specify the program heap size from `gnatlink'. - Assuming that the underlying linker is GNU ld there is two ways to do - so: - - * using `-Xlinker' linker option - - $ gnatlink hello -Xlinker --heap=0x10000,0x1000 - - This set the heap reserve size to 0x10000 bytes and the heap commit - size to 0x1000 bytes. - - * using `-Wl' linker option - - $ gnatlink hello -Wl,--heap=0x1000000 - - This set the heap reserve size to 0x1000000 bytes. Note that with - `-Wl' option it is not possible to set the heap commit size - because the coma is a separator for this option. - - -  - File: gnat_ug_unx.info, Node: The GNAT Make Program gnatmake, Next: Renaming Files Using gnatchop, Prev: Linking Using gnatlink, Up: Top - - The GNAT Make Program `gnatmake' - ******************************** - - * Menu: - - * Running gnatmake:: - * Switches for gnatmake:: - * Mode Switches for gnatmake:: - * Notes on the Command Line:: - * How gnatmake Works:: - * Examples of gnatmake Usage:: - - A typical development cycle when working on an Ada program consists of - the following steps: - - 1. Edit some sources to fix bugs. - - 2. Add enhancements. - - 3. Compile all sources affected. - - 4. Rebind and relink. - - 5. Test. - - The third step can be tricky, because not only do the modified files - have to be compiled, but any files depending on these files must also be - recompiled. The dependency rules in Ada can be quite complex, especially - in the presence of overloading, `use' clauses, generics and inlined - subprograms. - - `gnatmake' automatically takes care of the third and fourth steps of - this process. It determines which sources need to be compiled, compiles - them, and binds and links the resulting object files. - - Unlike some other Ada make programs, the dependencies are always - accurately recomputed from the new sources. The source based approach of - the GNAT compilation model makes this possible. This means that if - changes to the source program cause corresponding changes in - dependencies, they will always be tracked exactly correctly by - `gnatmake'. - -  - File: gnat_ug_unx.info, Node: Running gnatmake, Next: Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Running `gnatmake' - ================== - - The usual form of the `gnatmake' command is - - $ gnatmake [SWITCHES] FILE_NAME [FILE_NAMES] [MODE_SWITCHES] - - The only required argument is one FILE_NAME, which specifies a - compilation unit that is a main program. Several FILE_NAMES can be - specified: this will result in several executables being built. If - `switches' are present, they can be placed before the first FILE_NAME, - between FILE_NAMES or after the last FILE_NAME. If MODE_SWITCHES are - present, they must always be placed after the last FILE_NAME and all - `switches'. - - If you are using standard file extensions (.adb and .ads), then the - extension may be omitted from the FILE_NAME arguments. However, if you - are using non-standard extensions, then it is required that the - extension be given. A relative or absolute directory path can be - specified in a FILE_NAME, in which case, the input source file will be - searched for in the specified directory only. Otherwise, the input - source file will first be searched in the directory where `gnatmake' - was invoked and if it is not found, it will be search on the source - path of the compiler as described in *Note Search Paths and the - Run-Time Library (RTL)::. - - When several FILE_NAMES are specified, if an executable needs to be - rebuilt and relinked, all subsequent executables will be rebuilt and - relinked, even if this would not be absolutely necessary. - - All `gnatmake' output (except when you specify `-M') is to `stderr'. - The output produced by the `-M' switch is send to `stdout'. - -  - File: gnat_ug_unx.info, Node: Switches for gnatmake, Next: Mode Switches for gnatmake, Prev: Running gnatmake, Up: The GNAT Make Program gnatmake - - Switches for `gnatmake' - ======================= - - You may specify any of the following switches to `gnatmake': - - `--GCC=COMPILER_NAME' - Program used for compiling. The default is ``gcc''. You need to use - quotes around COMPILER_NAME if `compiler_name' contains spaces or - other separator characters. As an example `--GCC="foo -x -y"' will - instruct `gnatmake' to use `foo -x -y' as your compiler. Note that - switch `-c' is always inserted after your command name. Thus in - the above example the compiler command that will be used by - `gnatmake' will be `foo -c -x -y'. If several - `--GCC=compiler_name' are used, only the last COMPILER_NAME is - taken into account. However, all the additional switches are also - taken into account. Thus, `--GCC="foo -x -y" --GCC="bar -z -t"' is - equivalent to `--GCC="bar -x -y -z -t"'. - - `--GNATBIND=BINDER_NAME' - Program used for binding. The default is ``gnatbind''. You need to - use quotes around BINDER_NAME if BINDER_NAME contains spaces or - other separator characters. As an example `--GNATBIND="bar -x -y"' - will instruct `gnatmake' to use `bar -x -y' as your binder. Binder - switches that are normally appended by `gnatmake' to ``gnatbind'' - are now appended to the end of `bar -x -y'. - - `--GNATLINK=LINKER_NAME' - Program used for linking. The default is ``gnatlink''. You need to - use quotes around LINKER_NAME if LINKER_NAME contains spaces or - other separator characters. As an example `--GNATLINK="lan -x -y"' - will instruct `gnatmake' to use `lan -x -y' as your linker. Linker - switches that are normally appended by `gnatmake' to ``gnatlink'' - are now appended to the end of `lan -x -y'. - - `-a' - Consider all files in the make process, even the GNAT internal - system files (for example, the predefined Ada library files), as - well as any locked files. Locked files are files whose ALI file is - write-protected. By default, `gnatmake' does not check these - files, because the assumption is that the GNAT internal files are - properly up to date, and also that any write protected ALI files - have been properly installed. Note that if there is an - installation problem, such that one of these files is not up to - date, it will be properly caught by the binder. You may have to - specify this switch if you are working on GNAT itself. `-a' is - also useful in conjunction with `-f' if you need to recompile an - entire application, including run-time files, using special - configuration pragma settings, such as a non-standard - `Float_Representation' pragma. By default `gnatmake -a' compiles - all GNAT internal files with `gcc -c -gnatpg' rather than `gcc -c'. - - `-b' - Bind only. Can be combined with `-c' to do compilation and - binding, but no link. Can be combined with `-l' to do binding and - linking. When not combined with `-c' all the units in the closure - of the main program must have been previously compiled and must be - up to date. The root unit specified by FILE_NAME may be given - without extension, with the source extension or, if no GNAT - Project File is specified, with the ALI file extension. - - `-c' - Compile only. Do not perform binding, except when `-b' is also - specified. Do not perform linking, except if both `-b' and `-l' - are also specified. If the root unit specified by FILE_NAME is - not a main unit, this is the default. Otherwise `gnatmake' will - attempt binding and linking unless all objects are up to date and - the executable is more recent than the objects. - - `-C' - Use a mapping file. A mapping file is a way to communicate to the - compiler two mappings: from unit names to file names (without any - directory information) and from file names to path names (with - full directory information). These mappings are used by the - compiler to short-circuit the path search. When `gnatmake' is - invoked with this switch, it will create a mapping file, initially - populated by the project manager, if `-P' is used, otherwise - initially empty. Each invocation of the compiler will add the newly - accessed sources to the mapping file. This will improve the source - search during the next invocation of the compiler. - - `-f' - Force recompilations. Recompile all sources, even though some - object files may be up to date, but don't recompile predefined or - GNAT internal files or locked files (files with a write-protected - ALI file), unless the `-a' switch is also specified. - - `' - - `-i' - In normal mode, `gnatmake' compiles all object files and ALI files - into the current directory. If the `-i' switch is used, then - instead object files and ALI files that already exist are - overwritten in place. This means that once a large project is - organized into separate directories in the desired manner, then - `gnatmake' will automatically maintain and update this - organization. If no ALI files are found on the Ada object path - (*Note Search Paths and the Run-Time Library (RTL)::), the new - object and ALI files are created in the directory containing the - source being compiled. If another organization is desired, where - objects and sources are kept in different directories, a useful - technique is to create dummy ALI files in the desired directories. - When detecting such a dummy file, `gnatmake' will be forced to - recompile the corresponding source file, and it will be put the - resulting object and ALI files in the directory where it found the - dummy file. - - `-jN' - Use N processes to carry out the (re)compilations. On a - multiprocessor machine compilations will occur in parallel. In the - event of compilation errors, messages from various compilations - might get interspersed (but `gnatmake' will give you the full - ordered list of failing compiles at the end). If this is - problematic, rerun the make process with n set to 1 to get a clean - list of messages. - - `-k' - Keep going. Continue as much as possible after a compilation - error. To ease the programmer's task in case of compilation - errors, the list of sources for which the compile fails is given - when `gnatmake' terminates. - - If `gnatmake' is invoked with several `file_names' and with this - switch, if there are compilation errors when building an - executable, `gnatmake' will not attempt to build the following - executables. - - `-l' - Link only. Can be combined with `-b' to binding and linking. - Linking will not be performed if combined with `-c' but not with - `-b'. When not combined with `-b' all the units in the closure of - the main program must have been previously compiled and must be up - to date, and the main program need to have been bound. The root - unit specified by FILE_NAME may be given without extension, with - the source extension or, if no GNAT Project File is specified, - with the ALI file extension. - - `-m' - Specifies that the minimum necessary amount of recompilations be - performed. In this mode `gnatmake' ignores time stamp differences - when the only modifications to a source file consist in - adding/removing comments, empty lines, spaces or tabs. This means - that if you have changed the comments in a source file or have - simply reformatted it, using this switch will tell gnatmake not to - recompile files that depend on it (provided other sources on which - these files depend have undergone no semantic modifications). Note - that the debugging information may be out of date with respect to - the sources if the `-m' switch causes a compilation to be - switched, so the use of this switch represents a trade-off between - compilation time and accurate debugging information. - - `-M' - Check if all objects are up to date. If they are, output the object - dependences to `stdout' in a form that can be directly exploited in - a `Makefile'. By default, each source file is prefixed with its - (relative or absolute) directory name. This name is whatever you - specified in the various `-aI' and `-I' switches. If you use - `gnatmake -M' `-q' (see below), only the source file names, - without relative paths, are output. If you just specify the `-M' - switch, dependencies of the GNAT internal system files are - omitted. This is typically what you want. If you also specify the - `-a' switch, dependencies of the GNAT internal files are also - listed. Note that dependencies of the objects in external Ada - libraries (see switch `-aL'DIR in the following list) are never - reported. - - `-n' - Don't compile, bind, or link. Checks if all objects are up to date. - If they are not, the full name of the first file that needs to be - recompiled is printed. Repeated use of this option, followed by - compiling the indicated source file, will eventually result in - recompiling all required units. - - `-o EXEC_NAME' - Output executable name. The name of the final executable program - will be EXEC_NAME. If the `-o' switch is omitted the default name - for the executable will be the name of the input file in - appropriate form for an executable file on the host system. - - This switch cannot be used when invoking `gnatmake' with several - `file_names'. - - `-q' - Quiet. When this flag is not set, the commands carried out by - `gnatmake' are displayed. - - `-s' - Recompile if compiler switches have changed since last compilation. - All compiler switches but -I and -o are taken into account in the - following way: orders between different "first letter" switches - are ignored, but orders between same switches are taken into - account. For example, `-O -O2' is different than `-O2 -O', but `-g - -O' is equivalent to `-O -g'. - - `-u' - Unique. Recompile at most the main file. It implies -c. Combined - with -f, it is equivalent to calling the compiler directly. - - `-v' - Verbose. Displays the reason for all recompilations `gnatmake' - decides are necessary. - - `-z' - No main subprogram. Bind and link the program even if the unit name - given on the command line is a package name. The resulting - executable will execute the elaboration routines of the package - and its closure, then the finalization routines. - - ``gcc' switches' - The switch `-g' or any uppercase switch (other than `-A', `-L' or - `-S') or any switch that is more than one character is passed to - `gcc' (e.g. `-O', `-gnato,' etc.) - - Source and library search path switches: - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source files search is undertaken is described in - *Note Search Paths and the Run-Time Library (RTL)::. - - `-aLDIR' - Consider DIR as being an externally provided Ada library. - Instructs `gnatmake' to skip compilation units whose `.ali' files - have been located in directory DIR. This allows you to have - missing bodies for the units in DIR and to ignore out of date - bodies for the same units. You still need to specify the location - of the specs for these units by using the switches `-aIDIR' or - `-IDIR'. Note: this switch is provided for compatibility with - previous versions of `gnatmake'. The easier method of causing - standard libraries to be excluded from consideration is to - write-protect the corresponding ALI files. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is described in - *Note Search Paths for gnatbind::. - - `-ADIR' - Equivalent to `-aLDIR -aIDIR'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-I-' - Do not look for source files in the directory containing the source - file named in the command line. Do not look for ALI or object - files in the directory where `gnatmake' was invoked. - - `-LDIR' - Add directory DIR to the list of directories in which the linker - will search for libraries. This is equivalent to `-largs -L'DIR. - - `-nostdinc' - Do not look for source files in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. We look for - the runtime in the following directories, and stop as soon as a - valid runtime is found ("adainclude" or "ada_source_path", and - "adalib" or "ada_object_path" present): - - * /$rts_path - - * /$rts_path - - * /rts-$rts_path - - The selected path is handled like a normal RTS path. - -  - File: gnat_ug_unx.info, Node: Mode Switches for gnatmake, Next: Notes on the Command Line, Prev: Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Mode Switches for `gnatmake' - ============================ - - The mode switches (referred to as `mode_switches') allow the inclusion - of switches that are to be passed to the compiler itself, the binder or - the linker. The effect of a mode switch is to cause all subsequent - switches up to the end of the switch list, or up to the next mode - switch, to be interpreted as switches to be passed on to the designated - component of GNAT. - - `-cargs SWITCHES' - Compiler switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all compile - steps performed by `gnatmake'. - - `-bargs SWITCHES' - Binder switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all bind steps - performed by `gnatmake'. - - `-largs SWITCHES' - Linker switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all link steps - performed by `gnatmake'. - -  - File: gnat_ug_unx.info, Node: Notes on the Command Line, Next: How gnatmake Works, Prev: Mode Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Notes on the Command Line - ========================= - - This section contains some additional useful notes on the operation of - the `gnatmake' command. - - * If `gnatmake' finds no ALI files, it recompiles the main program - and all other units required by the main program. This means that - `gnatmake' can be used for the initial compile, as well as during - subsequent steps of the development cycle. - - * If you enter `gnatmake FILE.adb', where `FILE.adb' is a subunit or - body of a generic unit, `gnatmake' recompiles `FILE.adb' (because - it finds no ALI) and stops, issuing a warning. - - * In `gnatmake' the switch `-I' is used to specify both source and - library file paths. Use `-aI' instead if you just want to specify - source paths only and `-aO' if you want to specify library paths - only. - - * `gnatmake' examines both an ALI file and its corresponding object - file for consistency. If an ALI is more recent than its - corresponding object, or if the object file is missing, the - corresponding source will be recompiled. Note that `gnatmake' - expects an ALI and the corresponding object file to be in the same - directory. - - * `gnatmake' will ignore any files whose ALI file is write-protected. - This may conveniently be used to exclude standard libraries from - consideration and in particular it means that the use of the `-f' - switch will not recompile these files unless `-a' is also - specified. - - * `gnatmake' has been designed to make the use of Ada libraries - particularly convenient. Assume you have an Ada library organized - as follows: OBJ-DIR contains the objects and ALI files for of your - Ada compilation units, whereas INCLUDE-DIR contains the specs of - these units, but no bodies. Then to compile a unit stored in - `main.adb', which uses this Ada library you would just type - - $ gnatmake -aIINCLUDE-DIR -aLOBJ-DIR main - - * Using `gnatmake' along with the `-m (minimal recompilation)' - switch provides a mechanism for avoiding unnecessary - rcompilations. Using this switch, you can update the - comments/format of your source files without having to recompile - everything. Note, however, that adding or deleting lines in a - source files may render its debugging info obsolete. If the file - in question is a spec, the impact is rather limited, as that - debugging info will only be useful during the elaboration phase of - your program. For bodies the impact can be more significant. In - all events, your debugger will warn you if a source file is more - recent than the corresponding object, and alert you to the fact - that the debugging information may be out of date. - -  - File: gnat_ug_unx.info, Node: How gnatmake Works, Next: Examples of gnatmake Usage, Prev: Notes on the Command Line, Up: The GNAT Make Program gnatmake - - How `gnatmake' Works - ==================== - - Generally `gnatmake' automatically performs all necessary - recompilations and you don't need to worry about how it works. However, - it may be useful to have some basic understanding of the `gnatmake' - approach and in particular to understand how it uses the results of - previous compilations without incorrectly depending on them. - - First a definition: an object file is considered "up to date" if the - corresponding ALI file exists and its time stamp predates that of the - object file and if all the source files listed in the dependency - section of this ALI file have time stamps matching those in the ALI - file. This means that neither the source file itself nor any files that - it depends on have been modified, and hence there is no need to - recompile this file. - - `gnatmake' works by first checking if the specified main unit is up - to date. If so, no compilations are required for the main unit. If not, - `gnatmake' compiles the main program to build a new ALI file that - reflects the latest sources. Then the ALI file of the main unit is - examined to find all the source files on which the main program depends, - and `gnatmake' recursively applies the above procedure on all these - files. - - This process ensures that `gnatmake' only trusts the dependencies in - an existing ALI file if they are known to be correct. Otherwise it - always recompiles to determine a new, guaranteed accurate set of - dependencies. As a result the program is compiled "upside down" from - what may be more familiar as the required order of compilation in some - other Ada systems. In particular, clients are compiled before the units - on which they depend. The ability of GNAT to compile in any order is - critical in allowing an order of compilation to be chosen that - guarantees that `gnatmake' will recompute a correct set of new - dependencies if necessary. - - When invoking `gnatmake' with several FILE_NAMES, if a unit is - imported by several of the executables, it will be recompiled at most - once. - -  - File: gnat_ug_unx.info, Node: Examples of gnatmake Usage, Prev: How gnatmake Works, Up: The GNAT Make Program gnatmake - - Examples of `gnatmake' Usage - ============================ - - `gnatmake hello.adb' - Compile all files necessary to bind and link the main program - `hello.adb' (containing unit `Hello') and bind and link the - resulting object files to generate an executable file `hello'. - - `gnatmake main1 main2 main3' - Compile all files necessary to bind and link the main programs - `main1.adb' (containing unit `Main1'), `main2.adb' (containing - unit `Main2') and `main3.adb' (containing unit `Main3') and bind - and link the resulting object files to generate three executable - files `main1', `main2' and `main3'. - - `gnatmake -q Main_Unit -cargs -O2 -bargs -l' - Compile all files necessary to bind and link the main program unit - `Main_Unit' (from file `main_unit.adb'). All compilations will be - done with optimization level 2 and the order of elaboration will be - listed by the binder. `gnatmake' will operate in quiet mode, not - displaying commands it is executing. - -  - File: gnat_ug_unx.info, Node: Renaming Files Using gnatchop, Next: Configuration Pragmas, Prev: The GNAT Make Program gnatmake, Up: Top - - Renaming Files Using `gnatchop' - ******************************* - - This chapter discusses how to handle files with multiple units by using - the `gnatchop' utility. This utility is also useful in renaming files - to meet the standard GNAT default file naming conventions. - - * Menu: - - * Handling Files with Multiple Units:: - * Operating gnatchop in Compilation Mode:: - * Command Line for gnatchop:: - * Switches for gnatchop:: - * Examples of gnatchop Usage:: - -  - File: gnat_ug_unx.info, Node: Handling Files with Multiple Units, Next: Operating gnatchop in Compilation Mode, Up: Renaming Files Using gnatchop - - Handling Files with Multiple Units - ================================== - - The basic compilation model of GNAT requires that a file submitted to - the compiler have only one unit and there be a strict correspondence - between the file name and the unit name. - - The `gnatchop' utility allows both of these rules to be relaxed, - allowing GNAT to process files which contain multiple compilation units - and files with arbitrary file names. `gnatchop' reads the specified - file and generates one or more output files, containing one unit per - file. The unit and the file name correspond, as required by GNAT. - - If you want to permanently restructure a set of "foreign" files so - that they match the GNAT rules, and do the remaining development using - the GNAT structure, you can simply use `gnatchop' once, generate the - new set of files and work with them from that point on. - - Alternatively, if you want to keep your files in the "foreign" - format, perhaps to maintain compatibility with some other Ada - compilation system, you can set up a procedure where you use `gnatchop' - each time you compile, regarding the source files that it writes as - temporary files that you throw away. - -  - File: gnat_ug_unx.info, Node: Operating gnatchop in Compilation Mode, Next: Command Line for gnatchop, Prev: Handling Files with Multiple Units, Up: Renaming Files Using gnatchop - - Operating gnatchop in Compilation Mode - ====================================== - - The basic function of `gnatchop' is to take a file with multiple units - and split it into separate files. The boundary between files is - reasonably clear, except for the issue of comments and pragmas. In - default mode, the rule is that any pragmas between units belong to the - previous unit, except that configuration pragmas always belong to the - following unit. Any comments belong to the following unit. These rules - almost always result in the right choice of the split point without - needing to mark it explicitly and most users will find this default to - be what they want. In this default mode it is incorrect to submit a - file containing only configuration pragmas, or one that ends in - configuration pragmas, to `gnatchop'. - - However, using a special option to activate "compilation mode", - `gnatchop' can perform another function, which is to provide exactly - the semantics required by the RM for handling of configuration pragmas - in a compilation. In the absence of configuration pragmas (at the main - file level), this option has no effect, but it causes such - configuration pragmas to be handled in a quite different manner. - - First, in compilation mode, if `gnatchop' is given a file that - consists of only configuration pragmas, then this file is appended to - the `gnat.adc' file in the current directory. This behavior provides - the required behavior described in the RM for the actions to be taken - on submitting such a file to the compiler, namely that these pragmas - should apply to all subsequent compilations in the same compilation - environment. Using GNAT, the current directory, possibly containing a - `gnat.adc' file is the representation of a compilation environment. For - more information on the `gnat.adc' file, see the section on handling of - configuration pragmas *note Handling of Configuration Pragmas::. - - Second, in compilation mode, if `gnatchop' is given a file that - starts with configuration pragmas, and contains one or more units, then - these configuration pragmas are prepended to each of the chopped files. - This behavior provides the required behavior described in the RM for the - actions to be taken on compiling such a file, namely that the pragmas - apply to all units in the compilation, but not to subsequently compiled - units. - - Finally, if configuration pragmas appear between units, they are - appended to the previous unit. This results in the previous unit being - illegal, since the compiler does not accept configuration pragmas that - follow a unit. This provides the required RM behavior that forbids - configuration pragmas other than those preceding the first compilation - unit of a compilation. - - For most purposes, `gnatchop' will be used in default mode. The - compilation mode described above is used only if you need exactly - accurate behavior with respect to compilations, and you have files that - contain multiple units and configuration pragmas. In this circumstance - the use of `gnatchop' with the compilation mode switch provides the - required behavior, and is for example the mode in which GNAT processes - the ACVC tests. - -  - File: gnat_ug_unx.info, Node: Command Line for gnatchop, Next: Switches for gnatchop, Prev: Operating gnatchop in Compilation Mode, Up: Renaming Files Using gnatchop - - Command Line for `gnatchop' - =========================== - - The `gnatchop' command has the form: - - $ gnatchop switches FILE NAME [FILE NAME FILE NAME ...] - [DIRECTORY] - - The only required argument is the file name of the file to be chopped. - There are no restrictions on the form of this file name. The file itself - contains one or more Ada units, in normal GNAT format, concatenated - together. As shown, more than one file may be presented to be chopped. - - When run in default mode, `gnatchop' generates one output file in - the current directory for each unit in each of the files. - - DIRECTORY, if specified, gives the name of the directory to which - the output files will be written. If it is not specified, all files are - written to the current directory. - - For example, given a file called `hellofiles' containing - - procedure hello; - - with Text_IO; use Text_IO; - procedure hello is - begin - Put_Line ("Hello"); - end hello; - - the command - - $ gnatchop hellofiles - - generates two files in the current directory, one called `hello.ads' - containing the single line that is the procedure spec, and the other - called `hello.adb' containing the remaining text. The original file is - not affected. The generated files can be compiled in the normal manner. - -  - File: gnat_ug_unx.info, Node: Switches for gnatchop, Next: Examples of gnatchop Usage, Prev: Command Line for gnatchop, Up: Renaming Files Using gnatchop - - Switches for `gnatchop' - ======================= - - `gnatchop' recognizes the following switches: - - `-c' - Causes `gnatchop' to operate in compilation mode, in which - configuration pragmas are handled according to strict RM rules. See - previous section for a full description of this mode. - - `-gnatxxx' - This passes the given `-gnatxxx' switch to `gnat' which is used to - parse the given file. Not all `xxx' options make sense, but for - example, the use of `-gnati2' allows `gnatchop' to process a - source file that uses Latin-2 coding for identifiers. - - `-h' - Causes `gnatchop' to generate a brief help summary to the standard - output file showing usage information. - - `-kMM' - Limit generated file names to the specified number `mm' of - characters. This is useful if the resulting set of files is - required to be interoperable with systems which limit the length - of file names. No space is allowed between the `-k' and the - numeric value. The numeric value may be omitted in which case a - default of `-k8', suitable for use with DOS-like file systems, is - used. If no `-k' switch is present then there is no limit on the - length of file names. - - `-p' - Causes the file modification time stamp of the input file to be - preserved and used for the time stamp of the output file(s). This - may be useful for preserving coherency of time stamps in an - enviroment where `gnatchop' is used as part of a standard build - process. - - `-q' - Causes output of informational messages indicating the set of - generated files to be suppressed. Warnings and error messages are - unaffected. - - `-r' - Generate `Source_Reference' pragmas. Use this switch if the output - files are regarded as temporary and development is to be done in - terms of the original unchopped file. This switch causes - `Source_Reference' pragmas to be inserted into each of the - generated files to refers back to the original file name and line - number. The result is that all error messages refer back to the - original unchopped file. In addition, the debugging information - placed into the object file (when the `-g' switch of `gcc' or - `gnatmake' is specified) also refers back to this original file so - that tools like profilers and debuggers will give information in - terms of the original unchopped file. - - If the original file to be chopped itself contains a - `Source_Reference' pragma referencing a third file, then gnatchop - respects this pragma, and the generated `Source_Reference' pragmas - in the chopped file refer to the original file, with appropriate - line numbers. This is particularly useful when `gnatchop' is used - in conjunction with `gnatprep' to compile files that contain - preprocessing statements and multiple units. - - `-v' - Causes `gnatchop' to operate in verbose mode. The version number - and copyright notice are output, as well as exact copies of the - gnat1 commands spawned to obtain the chop control information. - - `-w' - Overwrite existing file names. Normally `gnatchop' regards it as a - fatal error if there is already a file with the same name as a - file it would otherwise output, in other words if the files to be - chopped contain duplicated units. This switch bypasses this check, - and causes all but the last instance of such duplicated units to - be skipped. - - `--GCC=xxxx' - Specify the path of the GNAT parser to be used. When this switch - is used, no attempt is made to add the prefix to the GNAT parser - executable. - -  - File: gnat_ug_unx.info, Node: Examples of gnatchop Usage, Prev: Switches for gnatchop, Up: Renaming Files Using gnatchop - - Examples of `gnatchop' Usage - ============================ - - `gnatchop -w hello_s.ada ichbiah/files' - Chops the source file `hello_s.ada'. The output files will be - placed in the directory `ichbiah/files', overwriting any files - with matching names in that directory (no files in the current - directory are modified). - - `gnatchop archive' - Chops the source file `archive' into the current directory. One - useful application of `gnatchop' is in sending sets of sources - around, for example in email messages. The required sources are - simply concatenated (for example, using a Unix `cat' command), and - then `gnatchop' is used at the other end to reconstitute the - original file names. - - `gnatchop file1 file2 file3 direc' - Chops all units in files `file1', `file2', `file3', placing the - resulting files in the directory `direc'. Note that if any units - occur more than once anywhere within this set of files, an error - message is generated, and no files are written. To override this - check, use the `-w' switch, in which case the last occurrence in - the last file will be the one that is output, and earlier - duplicate occurrences for a given unit will be skipped. - -  - File: gnat_ug_unx.info, Node: Configuration Pragmas, Next: Handling Arbitrary File Naming Conventions Using gnatname, Prev: Renaming Files Using gnatchop, Up: Top - - Configuration Pragmas - ********************* - - In Ada 95, configuration pragmas include those pragmas described as - such in the Ada 95 Reference Manual, as well as - implementation-dependent pragmas that are configuration pragmas. See the - individual descriptions of pragmas in the GNAT Reference Manual for - details on these additional GNAT-specific configuration pragmas. Most - notably, the pragma `Source_File_Name', which allows specifying - non-default names for source files, is a configuration pragma. The - following is a complete list of configuration pragmas recognized by - `GNAT': - - Ada_83 - Ada_95 - C_Pass_By_Copy - Component_Alignment - Discard_Names - Elaboration_Checks - Eliminate - Extend_System - Extensions_Allowed - External_Name_Casing - Float_Representation - Initialize_Scalars - License - Locking_Policy - Long_Float - No_Run_Time - Normalize_Scalars - Polling - Propagate_Exceptions - Queuing_Policy - Ravenscar - Restricted_Run_Time - Restrictions - Reviewable - Source_File_Name - Style_Checks - Suppress - Task_Dispatching_Policy - Unsuppress - Use_VADS_Size - Warnings - Validity_Checks - - * Menu: - - * Handling of Configuration Pragmas:: - * The Configuration Pragmas Files:: - -  - File: gnat_ug_unx.info, Node: Handling of Configuration Pragmas, Next: The Configuration Pragmas Files, Up: Configuration Pragmas - - Handling of Configuration Pragmas - ================================= - - Configuration pragmas may either appear at the start of a compilation - unit, in which case they apply only to that unit, or they may apply to - all compilations performed in a given compilation environment. - - GNAT also provides the `gnatchop' utility to provide an automatic - way to handle configuration pragmas following the semantics for - compilations (that is, files with multiple units), described in the RM. - See section *note Operating gnatchop in Compilation Mode:: for details. - However, for most purposes, it will be more convenient to edit the - `gnat.adc' file that contains configuration pragmas directly, as - described in the following section. - -  - File: gnat_ug_unx.info, Node: The Configuration Pragmas Files, Prev: Handling of Configuration Pragmas, Up: Configuration Pragmas - - The Configuration Pragmas Files - =============================== - - In GNAT a compilation environment is defined by the current directory - at the time that a compile command is given. This current directory is - searched for a file whose name is `gnat.adc'. If this file is present, - it is expected to contain one or more configuration pragmas that will - be applied to the current compilation. However, if the switch `-gnatA' - is used, `gnat.adc' is not considered. - - Configuration pragmas may be entered into the `gnat.adc' file either - by running `gnatchop' on a source file that consists only of - configuration pragmas, or more conveniently by direct editing of the - `gnat.adc' file, which is a standard format source file. - - In addition to `gnat.adc', one additional file containing - configuration pragmas may be applied to the current compilation using - the switch `-gnatec'PATH. PATH must designate an existing file that - contains only configuration pragmas. These configuration pragmas are in - addition to those found in `gnat.adc' (provided `gnat.adc' is present - and switch `-gnatA' is not used). - - It is allowed to specify several switches `-gnatec', however only - the last one on the command line will be taken into account. - -  - File: gnat_ug_unx.info, Node: Handling Arbitrary File Naming Conventions Using gnatname, Next: GNAT Project Manager, Prev: Configuration Pragmas, Up: Top - - Handling Arbitrary File Naming Conventions Using `gnatname' - *********************************************************** - - * Menu: - - * Arbitrary File Naming Conventions:: - * Running gnatname:: - * Switches for gnatname:: - * Examples of gnatname Usage:: - -  - File: gnat_ug_unx.info, Node: Arbitrary File Naming Conventions, Next: Running gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Arbitrary File Naming Conventions - ================================= - - The GNAT compiler must be able to know the source file name of a - compilation unit. When using the standard GNAT default file naming - conventions (`.ads' for specs, `.adb' for bodies), the GNAT compiler - does not need additional information. - - When the source file names do not follow the standard GNAT default file - naming conventions, the GNAT compiler must be given additional - information through a configuration pragmas file (see *Note - Configuration Pragmas::) or a project file. When the non standard file - naming conventions are well-defined, a small number of pragmas - `Source_File_Name' specifying a naming pattern (see *Note Alternative - File Naming Schemes::) may be sufficient. However, if the file naming - conventions are irregular or arbitrary, a number of pragma - `Source_File_Name' for individual compilation units must be defined. - To help maintain the correspondence between compilation unit names and - source file names within the compiler, GNAT provides a tool `gnatname' - to generate the required pragmas for a set of files. - -  - File: gnat_ug_unx.info, Node: Running gnatname, Next: Switches for gnatname, Prev: Arbitrary File Naming Conventions, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Running `gnatname' - ================== - - The usual form of the `gnatname' command is - - $ gnatname [SWITCHES] NAMING_PATTERN [NAMING_PATTERNS] - - All of the arguments are optional. If invoked without any argument, - `gnatname' will display its usage. - - When used with at least one naming pattern, `gnatname' will attempt to - find all the compilation units in files that follow at least one of the - naming patterns. To find these compilation units, `gnatname' will use - the GNAT compiler in syntax-check-only mode on all regular files. - - One or several Naming Patterns may be given as arguments to `gnatname'. - Each Naming Pattern is enclosed between double quotes. A Naming - Pattern is a regular expression similar to the wildcard patterns used - in file names by the Unix shells or the DOS prompt. - - Examples of Naming Patterns are - - "*.[12].ada" - "*.ad[sb]*" - "body_*" "spec_*" - - For a more complete description of the syntax of Naming Patterns, see - the second kind of regular expressions described in `g-regexp.ads' (the - "Glob" regular expressions). - - When invoked with no switches, `gnatname' will create a configuration - pragmas file `gnat.adc' in the current working directory, with pragmas - `Source_File_Name' for each file that contains a valid Ada unit. - -  - File: gnat_ug_unx.info, Node: Switches for gnatname, Next: Examples of gnatname Usage, Prev: Running gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Switches for `gnatname' - ======================= - - Switches for `gnatname' must precede any specified Naming Pattern. - - You may specify any of the following switches to `gnatname': - - `-c`file'' - Create a configuration pragmas file `file' (instead of the default - `gnat.adc'). There may be zero, one or more space between `-c' and - `file'. `file' may include directory information. `file' must be - writeable. There may be only one switch `-c'. When a switch `-c' is - specified, no switch `-P' may be specified (see below). - - `-d`dir'' - Look for source files in directory `dir'. There may be zero, one - or more spaces between `-d' and `dir'. When a switch `-d' is - specified, the current working directory will not be searched for - source files, unless it is explictly specified with a `-d' or `-D' - switch. Several switches `-d' may be specified. If `dir' is a - relative path, it is relative to the directory of the - configuration pragmas file specified with switch `-c', or to the - directory of the project file specified with switch `-P' or, if - neither switch `-c' nor switch `-P' are specified, it is relative - to the current working directory. The directory specified with - switch `-c' must exist and be readable. - - `-D`file'' - Look for source files in all directories listed in text file - `file'. There may be zero, one or more spaces between `-d' and - `dir'. `file' must be an existing, readable text file. Each non - empty line in `file' must be a directory. Specifying switch `-D' - is equivalent to specifying as many switches `-d' as there are non - empty lines in `file'. - - `-h' - Output usage (help) information. The output is written to `stdout'. - - `-P`proj'' - Create or update project file `proj'. There may be zero, one or - more space between `-P' and `proj'. `proj' may include directory - information. `proj' must be writeable. There may be only one - switch `-P'. When a switch `-P' is specified, no switch `-c' may - be specified. - - `-v' - Verbose mode. Output detailed explanation of behavior to `stdout'. - This includes name of the file written, the name of the - directories to search and, for each file in those directories - whose name matches at least one of the Naming Patterns, an - indication of whether the file contains a unit, and if so the name - of the unit. - - `-v -v' - Very Verbose mode. In addition to the output produced in verbose - mode, for each file in the searched directories whose name matches - none of the Naming Patterns, an indication is given that there is - no match. - - `-x`pattern'' - Excluded patterns. Using this switch, it is possible to exclude - some files that would match the name patterns. For example, - `"gnatname -x "*_nt.ada" "*.ada"' will look for Ada units in all - files with the `.ada' extension, except those whose names end with - `_nt.ada'. - -  - File: gnat_ug_unx.info, Node: Examples of gnatname Usage, Prev: Switches for gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Examples of `gnatname' Usage - ============================ - - $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" - - In this example, the directory `/home/me' must already exist and be - writeable. In addition, the directory `/home/me/sources' (specified by - `-d sources') must exist and be readable. Note the optional spaces after - `-c' and `-d'. - - $ gnatname -P/home/me/proj -x "*_nt_body.ada" -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" - - Note that several switches `-d' may be used, even in conjunction - with one or several switches `-D'. Several Naming Patterns and one - excluded pattern are used in this example. - -  - File: gnat_ug_unx.info, Node: GNAT Project Manager, Next: Elaboration Order Handling in GNAT, Prev: Handling Arbitrary File Naming Conventions Using gnatname, Up: Top - - GNAT Project Manager - ******************** - - * Menu: - - * Introduction:: - * Examples of Project Files:: - * Project File Syntax:: - * Objects and Sources in Project Files:: - * Importing Projects:: - * Project Extension:: - * External References in Project Files:: - * Packages in Project Files:: - * Variables from Imported Projects:: - * Naming Schemes:: - * Library Projects:: - * Switches Related to Project Files:: - * Tools Supporting Project Files:: - * An Extended Example:: - * Project File Complete Syntax:: - -  - File: gnat_ug_unx.info, Node: Introduction, Next: Examples of Project Files, Up: GNAT Project Manager - - Introduction - ============ - - This chapter describes GNAT's _Project Manager_, a facility that lets - you configure various properties for a collection of source files. In - particular, you can specify: - * The directory or set of directories containing the source files, - and/or the names of the specific source files themselves - - * The directory in which the compiler's output (`ALI' files, object - files, tree files) will be placed - - * The directory in which the executable programs will be placed - - * Switch settings for any of the project-enabled tools (`gnatmake', - compiler, binder, linker, `gnatls', `gnatxref', `gnatfind'); you - can apply these settings either globally or to individual units - - * The source files containing the main subprogram(s) to be built - - * The source programming language(s) (currently Ada and/or C) - - * Source file naming conventions; you can specify these either - globally or for individual units - - * Menu: - - * Project Files:: - -  - File: gnat_ug_unx.info, Node: Project Files, Up: Introduction - - Project Files - ------------- - - A "project" is a specific set of values for these properties. You can - define a project's settings in a "project file", a text file with an - Ada-like syntax; a property value is either a string or a list of - strings. Properties that are not explicitly set receive default - values. A project file may interrogate the values of "external - variables" (user-defined command-line switches or environment - variables), and it may specify property settings conditionally, based - on the value of such variables. - - In simple cases, a project's source files depend only on other - source files in the same project, or on the predefined libraries. - ("Dependence" is in the technical sense; for example, one Ada unit - "with"ing another.) However, the Project Manager also allows much more - sophisticated arrangements, with the source files in one project - depending on source files in other projects: - * One project can _import_ other projects containing needed source - files. - - * You can organize GNAT projects in a hierarchy: a _child_ project - can extend a _parent_ project, inheriting the parent's source - files and optionally overriding any of them with alternative - versions - - More generally, the Project Manager lets you structure large development - efforts into hierarchical subsystems, with build decisions deferred to - the subsystem level and thus different compilation environments (switch - settings) used for different subsystems. - - The Project Manager is invoked through the `-P_projectfile_' switch - to `gnatmake' or to the `gnat' front driver. If you want to define (on - the command line) an external variable that is queried by the project - file, additionally use the `-X_vbl_=_value_' switch. The Project - Manager parses and interprets the project file, and drives the invoked - tool based on the project settings. - - The Project Manager supports a wide range of development strategies, - for systems of all sizes. Some typical practices that are easily - handled: - * Using a common set of source files, but generating object files in - different directories via different switch settings - - * Using a mostly-shared set of source files, but with different - versions of some unit or units - - The destination of an executable can be controlled inside a project file - using the `-o' switch. In the absence of such a switch either inside - the project file or on the command line, any executable files generated - by `gnatmake' will be placed in the directory `Exec_Dir' specified in - the project file. If no `Exec_Dir' is specified, they will be placed in - the object directory of the project. - - You can use project files to achieve some of the effects of a source - versioning system (for example, defining separate projects for the - different sets of sources that comprise different releases) but the - Project Manager is independent of any source configuration management - tools that might be used by the developers. - - The next section introduces the main features of GNAT's project - facility through a sequence of examples; subsequent sections will - present the syntax and semantics in more detail. - -  - File: gnat_ug_unx.info, Node: Examples of Project Files, Next: Project File Syntax, Prev: Introduction, Up: GNAT Project Manager - - Examples of Project Files - ========================= - - This section illustrates some of the typical uses of project files and - explains their basic structure and behavior. - - * Menu: - - * Common Sources with Different Switches and Different Output Directories:: - * Using External Variables:: - * Importing Other Projects:: - * Extending a Project:: - -  - File: gnat_ug_unx.info, Node: Common Sources with Different Switches and Different Output Directories, Next: Using External Variables, Up: Examples of Project Files - - Common Sources with Different Switches and Different Output Directories - ----------------------------------------------------------------------- - - * Menu: - - * Source Files:: - * Specifying the Object Directory:: - * Specifying the Exec Directory:: - * Project File Packages:: - * Specifying Switch Settings:: - * Main Subprograms:: - * Source File Naming Conventions:: - * Source Language(s):: - - Assume that the Ada source files `pack.ads', `pack.adb', and `proc.adb' - are in the `/common' directory. The file `proc.adb' contains an Ada - main subprogram `Proc' that "with"s package `Pack'. We want to compile - these source files under two sets of switches: - * When debugging, we want to pass the `-g' switch to `gnatmake', and - the `-gnata', `-gnato', and `-gnatE' switches to the compiler; the - compiler's output is to appear in `/common/debug' - - * When preparing a release version, we want to pass the `-O2' switch - to the compiler; the compiler's output is to appear in - `/common/release' - - The GNAT project files shown below, respectively `debug.gpr' and - `release.gpr' in the `/common' directory, achieve these effects. - - Diagrammatically: - /common - debug.gpr - release.gpr - pack.ads - pack.adb - proc.adb - /common/debug {-g, -gnata, -gnato, -gnatE} - proc.ali, proc.o - pack.ali, pack.o - /common/release {-O2} - proc.ali, proc.o - pack.ali, pack.o - Here are the project files: - project Debug is - for Object_Dir use "debug"; - for Main use ("proc"); - - package Builder is - for Default_Switches ("Ada") use ("-g"); - end Builder; - - package Compiler is - for Default_Switches ("Ada") - use ("-fstack-check", "-gnata", "-gnato", "-gnatE"); - end Compiler; - end Debug; - - project Release is - for Object_Dir use "release"; - for Exec_Dir use "."; - for Main use ("proc"); - - package Compiler is - for Default_Switches ("Ada") use ("-O2"); - end Compiler; - end Release; - - The name of the project defined by `debug.gpr' is `"Debug"' (case - insensitive), and analogously the project defined by `release.gpr' is - `"Release"'. For consistency the file should have the same name as the - project, and the project file's extension should be `"gpr"'. These - conventions are not required, but a warning is issued if they are not - followed. - - If the current directory is `/temp', then the command - gnatmake -P/common/debug.gpr - - generates object and ALI files in `/common/debug', and the `proc' - executable also in `/common/debug', using the switch settings defined in - the project file. - - Likewise, the command - gnatmake -P/common/release.gpr - - generates object and ALI files in `/common/release', and the `proc' - executable in `/common', using the switch settings from the project - file. - -  - File: gnat_ug_unx.info, Node: Source Files, Next: Specifying the Object Directory, Up: Common Sources with Different Switches and Different Output Directories - - Source Files - ............ - - If a project file does not explicitly specify a set of source - directories or a set of source files, then by default the project's - source files are the Ada source files in the project file directory. - Thus `pack.ads', `pack.adb', and `proc.adb' are the source files for - both projects. - -  - File: gnat_ug_unx.info, Node: Specifying the Object Directory, Next: Specifying the Exec Directory, Prev: Source Files, Up: Common Sources with Different Switches and Different Output Directories - - Specifying the Object Directory - ............................... - - Several project properties are modeled by Ada-style _attributes_; you - define the property by supplying the equivalent of an Ada attribute - definition clause in the project file. A project's object directory is - such a property; the corresponding attribute is `Object_Dir', and its - value is a string expression. A directory may be specified either as - absolute or as relative; in the latter case, it is relative to the - project file directory. Thus the compiler's output is directed to - `/common/debug' (for the `Debug' project) and to `/common/release' (for - the `Release' project). If `Object_Dir' is not specified, then the - default is the project file directory. - -  - File: gnat_ug_unx.info, Node: Specifying the Exec Directory, Next: Project File Packages, Prev: Specifying the Object Directory, Up: Common Sources with Different Switches and Different Output Directories - - Specifying the Exec Directory - ............................. - - A project's exec directory is another property; the corresponding - attribute is `Exec_Dir', and its value is also a string expression, - either specified as relative or absolute. If `Exec_Dir' is not - specified, then the default is the object directory (which may also be - the project file directory if attribute `Object_Dir' is not specified). - Thus the executable is placed in `/common/debug' for the `Debug' - project (attribute `Exec_Dir' not specified) and in `/common' for the - `Release' project. - -  - File: gnat_ug_unx.info, Node: Project File Packages, Next: Specifying Switch Settings, Prev: Specifying the Exec Directory, Up: Common Sources with Different Switches and Different Output Directories - - Project File Packages - ..................... - - A GNAT tool integrated with the Project Manager is modeled by a - corresponding package in the project file. The `Debug' project defines - the packages `Builder' (for `gnatmake') and `Compiler'; the `Release' - project defines only the `Compiler' package. - - The Ada package syntax is not to be taken literally. Although - packages in project files bear a surface resemblance to packages in Ada - source code, the notation is simply a way to convey a grouping of - properties for a named entity. Indeed, the package names permitted in - project files are restricted to a predefined set, corresponding to the - project-aware tools, and the contents of packages are limited to a - small set of constructs. The packages in the example above contain - attribute definitions. - -  - File: gnat_ug_unx.info, Node: Specifying Switch Settings, Next: Main Subprograms, Prev: Project File Packages, Up: Common Sources with Different Switches and Different Output Directories - - Specifying Switch Settings - .......................... - - Switch settings for a project-aware tool can be specified through - attributes in the package corresponding to the tool. The example above - illustrates one of the relevant attributes, `Default_Switches', defined - in the packages in both project files. Unlike simple attributes like - `Source_Dirs', `Default_Switches' is known as an _associative array_. - When you define this attribute, you must supply an "index" (a literal - string), and the effect of the attribute definition is to set the value - of the "array" at the specified "index". For the `Default_Switches' - attribute, the index is a programming language (in our case, Ada) , and - the value specified (after `use') must be a list of string expressions. - - The attributes permitted in project files are restricted to a - predefined set. Some may appear at project level, others in packages. - For any attribute that is an associate array, the index must always be a - literal string, but the restrictions on this string (e.g., a file name - or a language name) depend on the individual attribute. Also depending - on the attribute, its specified value will need to be either a string - or a string list. - - In the `Debug' project, we set the switches for two tools, - `gnatmake' and the compiler, and thus we include corresponding - packages, with each package defining the `Default_Switches' attribute - with index `"Ada"'. Note that the package corresponding to `gnatmake' - is named `Builder'. The `Release' project is similar, but with just - the `Compiler' package. - - In project `Debug' above the switches starting with `-gnat' that are - specified in package `Compiler' could have been placed in package - `Builder', since `gnatmake' transmits all such switches to the compiler. - -  - File: gnat_ug_unx.info, Node: Main Subprograms, Next: Source File Naming Conventions, Prev: Specifying Switch Settings, Up: Common Sources with Different Switches and Different Output Directories - - Main Subprograms - ................ - - One of the properties of a project is its list of main subprograms - (actually a list of names of source files containing main subprograms, - with the file extension optional. This property is captured in the - `Main' attribute, whose value is a list of strings. If a project - defines the `Main' attribute, then you do not need to identify the main - subprogram(s) when invoking `gnatmake' (see *Note gnatmake and Project - Files::). - -  - File: gnat_ug_unx.info, Node: Source File Naming Conventions, Next: Source Language(s), Prev: Main Subprograms, Up: Common Sources with Different Switches and Different Output Directories - - Source File Naming Conventions - .............................. - - Since the project files do not specify any source file naming - conventions, the GNAT defaults are used. The mechanism for defining - source file naming conventions - a package named `Naming' - will be - described below (*note Naming Schemes::). - -  - File: gnat_ug_unx.info, Node: Source Language(s), Prev: Source File Naming Conventions, Up: Common Sources with Different Switches and Different Output Directories - - Source Language(s) - .................. - - Since the project files do not specify a `Languages' attribute, by - default the GNAT tools assume that the language of the project file is - Ada. More generally, a project can comprise source files in Ada, C, - and/or other languages. - -  - File: gnat_ug_unx.info, Node: Using External Variables, Next: Importing Other Projects, Prev: Common Sources with Different Switches and Different Output Directories, Up: Examples of Project Files - - Using External Variables - ------------------------ - - Instead of supplying different project files for debug and release, we - can define a single project file that queries an external variable (set - either on the command line or via an environment variable) in order to - conditionally define the appropriate settings. Again, assume that the - source files `pack.ads', `pack.adb', and `proc.adb' are located in - directory `/common'. The following project file, `build.gpr', queries - the external variable named `STYLE' and defines an object directory and - switch settings based on whether the value is `"deb"' (debug) or - `"rel"' (release), where the default is `"deb"'. - - project Build is - for Main use ("proc"); - - type Style_Type is ("deb", "rel"); - Style : Style_Type := external ("STYLE", "deb"); - - case Style is - when "deb" => - for Object_Dir use "debug"; - - when "rel" => - for Object_Dir use "release"; - for Exec_Dir use "."; - end case; - - package Builder is - - case Style is - when "deb" => - for Default_Switches ("Ada") use ("-g"); - end case; - - end Builder; - - package Compiler is - - case Style is - when "deb" => - for Default_Switches ("Ada") use ("-gnata", "-gnato", "-gnatE"); - - when "rel" => - for Default_Switches ("Ada") use ("-O2"); - end case; - - end Compiler; - - end Build; - - `Style_Type' is an example of a _string type_, which is the project - file analog of an Ada enumeration type but containing string literals - rather than identifiers. `Style' is declared as a variable of this - type. - - The form `external("STYLE", "deb")' is known as an _external - reference_; its first argument is the name of an _external variable_, - and the second argument is a default value to be used if the external - variable doesn't exist. You can define an external variable on the - command line via the `-X' switch, or you can use an environment - variable as an external variable. - - Each `case' construct is expanded by the Project Manager based on the - value of `Style'. Thus the command - gnatmake -P/common/build.gpr -XSTYLE=deb - - is equivalent to the `gnatmake' invocation using the project file - `debug.gpr' in the earlier example. So is the command - gnatmake -P/common/build.gpr - - since `"deb"' is the default for `STYLE'. - - Analogously, - gnatmake -P/common/build.gpr -XSTYLE=rel - - is equivalent to the `gnatmake' invocation using the project file - `release.gpr' in the earlier example. - -  - File: gnat_ug_unx.info, Node: Importing Other Projects, Next: Extending a Project, Prev: Using External Variables, Up: Examples of Project Files - - Importing Other Projects - ------------------------ - - A compilation unit in a source file in one project may depend on - compilation units in source files in other projects. To obtain this - behavior, the dependent project must _import_ the projects containing - the needed source files. This effect is embodied in syntax similar to - an Ada `with' clause, but the "with"ed entities are strings denoting - project files. - - As an example, suppose that the two projects `GUI_Proj' and - `Comm_Proj' are defined in the project files `gui_proj.gpr' and - `comm_proj.gpr' in directories `/gui' and `/comm', respectively. - Assume that the source files for `GUI_Proj' are `gui.ads' and - `gui.adb', and that the source files for `Comm_Proj' are `comm.ads' and - `comm.adb', with each set of files located in its respective project - file directory. Diagrammatically: - - /gui - gui_proj.gpr - gui.ads - gui.adb - - /comm - comm_proj.gpr - comm.ads - comm.adb - - We want to develop an application in directory `/app' that "with"s the - packages `GUI' and `Comm', using the properties of the corresponding - project files (e.g. the switch settings and object directory). - Skeletal code for a main procedure might be something like the - following: - - with GUI, Comm; - procedure App_Main is - ... - begin - ... - end App_Main; - - Here is a project file, `app_proj.gpr', that achieves the desired - effect: - - with "/gui/gui_proj", "/comm/comm_proj"; - project App_Proj is - for Main use ("app_main"); - end App_Proj; - - Building an executable is achieved through the command: - gnatmake -P/app/app_proj - - which will generate the `app_main' executable in the directory where - `app_proj.gpr' resides. - - If an imported project file uses the standard extension (`gpr') then - (as illustrated above) the `with' clause can omit the extension. - - Our example specified an absolute path for each imported project - file. Alternatively, you can omit the directory if either - * The imported project file is in the same directory as the - importing project file, or - - * You have defined an environment variable `ADA_PROJECT_PATH' that - includes the directory containing the needed project file. - - Thus, if we define `ADA_PROJECT_PATH' to include `/gui' and `/comm', - then our project file `app_proj.gpr' could be written as follows: - - with "gui_proj", "comm_proj"; - project App_Proj is - for Main use ("app_main"); - end App_Proj; - - Importing other projects raises the possibility of ambiguities. For - example, the same unit might be present in different imported projects, - or it might be present in both the importing project and an imported - project. Both of these conditions are errors. Note that in the - current version of the Project Manager, it is illegal to have an - ambiguous unit even if the unit is never referenced by the importing - project. This restriction may be relaxed in a future release. - -  - File: gnat_ug_unx.info, Node: Extending a Project, Prev: Importing Other Projects, Up: Examples of Project Files - - Extending a Project - ------------------- - - A common situation in large software systems is to have multiple - implementations for a common interface; in Ada terms, multiple versions - of a package body for the same specification. For example, one - implementation might be safe for use in tasking programs, while another - might only be used in sequential applications. This can be modeled in - GNAT using the concept of _project extension_. If one project (the - "child") _extends_ another project (the "parent") then by default all - source files of the parent project are inherited by the child, but the - child project can override any of the parent's source files with new - versions, and can also add new files. This facility is the project - analog of extension in Object-Oriented Programming. Project - hierarchies are permitted (a child project may be the parent of yet - another project), and a project that inherits one project can also - import other projects. - - As an example, suppose that directory `/seq' contains the project - file `seq_proj.gpr' and the source files `pack.ads', `pack.adb', and - `proc.adb': - - /seq - pack.ads - pack.adb - proc.adb - seq_proj.gpr - - Note that the project file can simply be empty (that is, no attribute or - package is defined): - - project Seq_Proj is - end Seq_Proj; - - implying that its source files are all the Ada source files in the - project directory. - - Suppose we want to supply an alternate version of `pack.adb', in - directory `/tasking', but use the existing versions of `pack.ads' and - `proc.adb'. We can define a project `Tasking_Proj' that inherits - `Seq_Proj': - - /tasking - pack.adb - tasking_proj.gpr - - project Tasking_Proj extends "/seq/seq_proj" is - end Tasking_Proj; - - The version of `pack.adb' used in a build depends on which project file - is specified. - - Note that we could have designed this using project import rather - than project inheritance; a `base' project would contain the sources for - `pack.ads' and `proc.adb', a sequential project would import `base' and - add `pack.adb', and likewise a tasking project would import `base' and - add a different version of `pack.adb'. The choice depends on whether - other sources in the original project need to be overridden. If they - do, then project extension is necessary, otherwise, importing is - sufficient. - -  - File: gnat_ug_unx.info, Node: Project File Syntax, Next: Objects and Sources in Project Files, Prev: Examples of Project Files, Up: GNAT Project Manager - - Project File Syntax - =================== - - * Menu: - - * Basic Syntax:: - * Packages:: - * Expressions:: - * String Types:: - * Variables:: - * Attributes:: - * Associative Array Attributes:: - * case Constructions:: - - This section describes the structure of project files. - - A project may be an _independent project_, entirely defined by a - single project file. Any Ada source file in an independent project - depends only on the predefined library and other Ada source files in - the same project. - - A project may also "depend on" other projects, in either or both of the - following ways: - * It may import any number of projects - - * It may extend at most one other project - - The dependence relation is a directed acyclic graph (the subgraph - reflecting the "extends" relation is a tree). - - A project's "immediate sources" are the source files directly - defined by that project, either implicitly by residing in the project - file's directory, or explicitly through any of the source-related - attributes described below. More generally, a project PROJ's "sources" - are the immediate sources of PROJ together with the immediate sources - (unless overridden) of any project on which PROJ depends (either - directly or indirectly). - -  - File: gnat_ug_unx.info, Node: Basic Syntax, Next: Packages, Up: Project File Syntax - - Basic Syntax - ------------ - - As seen in the earlier examples, project files have an Ada-like syntax. - The minimal project file is: - project Empty is - - end Empty; - - The identifier `Empty' is the name of the project. This project name - must be present after the reserved word `end' at the end of the project - file, followed by a semi-colon. - - Any name in a project file, such as the project name or a variable - name, has the same syntax as an Ada identifier. - - The reserved words of project files are the Ada reserved words plus - `extends', `external', and `project'. Note that the only Ada reserved - words currently used in project file syntax are: - - * `case' - - * `end' - - * `for' - - * `is' - - * `others' - - * `package' - - * `renames' - - * `type' - - * `use' - - * `when' - - * `with' - - Comments in project files have the same syntax as in Ada, two - consecutives hyphens through the end of the line. - -  - File: gnat_ug_unx.info, Node: Packages, Next: Expressions, Prev: Basic Syntax, Up: Project File Syntax - - Packages - -------- - - A project file may contain _packages_. The name of a package must be one - of the identifiers (case insensitive) from a predefined list, and a - package with a given name may only appear once in a project file. The - predefined list includes the following packages: - - * `Naming' - - * `Builder' - - * `Compiler' - - * `Binder' - - * `Linker' - - * `Finder' - - * `Cross_Reference' - - * `gnatls' - - (The complete list of the package names and their attributes can be - found in file `prj-attr.adb'). - - In its simplest form, a package may be empty: - - project Simple is - package Builder is - end Builder; - end Simple; - - A package may contain _attribute declarations_, _variable declarations_ - and _case constructions_, as will be described below. - - When there is ambiguity between a project name and a package name, - the name always designates the project. To avoid possible confusion, it - is always a good idea to avoid naming a project with one of the names - allowed for packages or any name that starts with `gnat'. - -  - File: gnat_ug_unx.info, Node: Expressions, Next: String Types, Prev: Packages, Up: Project File Syntax - - Expressions - ----------- - - An _expression_ is either a _string expression_ or a _string list - expression_. - - A _string expression_ is either a _simple string expression_ or a - _compound string expression_. - - A _simple string expression_ is one of the following: - * A literal string; e.g.`"comm/my_proj.gpr"' - - * A string-valued variable reference (see *Note Variables::) - - * A string-valued attribute reference (see *Note Attributes::) - - * An external reference (see *Note External References in Project - Files::) - - A _compound string expression_ is a concatenation of string expressions, - using `"&"' - Path & "/" & File_Name & ".ads" - - A _string list expression_ is either a _simple string list expression_ - or a _compound string list expression_. - - A _simple string list expression_ is one of the following: - * A parenthesized list of zero or more string expressions, separated - by commas - File_Names := (File_Name, "gnat.adc", File_Name & ".orig"); - Empty_List := (); - - * A string list-valued variable reference - - * A string list-valued attribute reference - - A _compound string list expression_ is the concatenation (using `"&"') - of a simple string list expression and an expression. Note that each - term in a compound string list expression, except the first, may be - either a string expression or a string list expression. - - File_Name_List := () & File_Name; -- One string in this list - Extended_File_Name_List := File_Name_List & (File_Name & ".orig"); - -- Two strings - Big_List := File_Name_List & Extended_File_Name_List; - -- Concatenation of two string lists: three strings - Illegal_List := "gnat.adc" & Extended_File_Name_List; - -- Illegal: must start with a string list - -  - File: gnat_ug_unx.info, Node: String Types, Next: Variables, Prev: Expressions, Up: Project File Syntax - - String Types - ------------ - - The value of a variable may be restricted to a list of string literals. - The restricted list of string literals is given in a _string type - declaration_. - - Here is an example of a string type declaration: - - type OS is ("NT, "nt", "Unix", "Linux", "other OS"); - - Variables of a string type are called _typed variables_; all other - variables are called _untyped variables_. Typed variables are - particularly useful in `case' constructions (see *Note case - Constructions::). - - A string type declaration starts with the reserved word `type', - followed by the name of the string type (case-insensitive), followed by - the reserved word `is', followed by a parenthesized list of one or more - string literals separated by commas, followed by a semicolon. - - The string literals in the list are case sensitive and must all be - different. They may include any graphic characters allowed in Ada, - including spaces. - - A string type may only be declared at the project level, not inside - a package. - - A string type may be referenced by its name if it has been declared - in the same project file, or by its project name, followed by a dot, - followed by the string type name. - -  - File: gnat_ug_unx.info, Node: Variables, Next: Attributes, Prev: String Types, Up: Project File Syntax - - Variables - --------- - - A variable may be declared at the project file level, or in a package. - Here are some examples of variable declarations: - - This_OS : OS := external ("OS"); -- a typed variable declaration - That_OS := "Linux"; -- an untyped variable declaration - - A _typed variable declaration_ includes the variable name, followed by - a colon, followed by the name of a string type, followed by `:=', - followed by a simple string expression. - - An _untyped variable declaration_ includes the variable name, - followed by `:=', followed by an expression. Note that, despite the - terminology, this form of "declaration" resembles more an assignment - than a declaration in Ada. It is a declaration in several senses: - * The variable name does not need to be defined previously - - * The declaration establishes the _kind_ (string versus string list) - of the variable, and later declarations of the same variable need - to be consistent with this - - A string variable declaration (typed or untyped) declares a variable - whose value is a string. This variable may be used as a string - expression. - File_Name := "readme.txt"; - Saved_File_Name := File_Name & ".saved"; - - A string list variable declaration declares a variable whose value is a - list of strings. The list may contain any number (zero or more) of - strings. - - Empty_List := (); - List_With_One_Element := ("-gnaty"); - List_With_Two_Elements := List_With_One_Element & "-gnatg"; - Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada" - "pack2.ada", "util_.ada", "util.ada"); - - The same typed variable may not be declared more than once at project - level, and it may not be declared more than once in any package; it is - in effect a constant or a readonly variable. - - The same untyped variable may be declared several times. In this - case, the new value replaces the old one, and any subsequent reference - to the variable uses the new value. However, as noted above, if a - variable has been declared as a string, all subsequent declarations - must give it a string value. Similarly, if a variable has been declared - as a string list, all subsequent declarations must give it a string - list value. - - A _variable reference_ may take several forms: - - * The simple variable name, for a variable in the current package - (if any) or in the current project - - * A context name, followed by a dot, followed by the variable name. - - A _context_ may be one of the following: - - * The name of an existing package in the current project - - * The name of an imported project of the current project - - * The name of an ancestor project (i.e., a project extended by the - current project, either directly or indirectly) - - * An imported/parent project name, followed by a dot, followed by a - package name - - A variable reference may be used in an expression. - -  - File: gnat_ug_unx.info, Node: Attributes, Next: Associative Array Attributes, Prev: Variables, Up: Project File Syntax - - Attributes - ---------- - - A project (and its packages) may have _attributes_ that define the - project's properties. Some attributes have values that are strings; - others have values that are string lists. - - There are two categories of attributes: _simple attributes_ and - _associative arrays_ (see *Note Associative Array Attributes::). - - The names of the attributes are restricted; there is a list of - project attributes, and a list of package attributes for each package. - The names are not case sensitive. - - The project attributes are as follows (all are simple attributes): - - _Attribute Name_ _Value_ - `Source_Files' string list - `Source_Dirs' string list - `Source_List_File' string - `Object_Dir' string - `Exec_Dir' string - `Main' string list - `Languages' string list - `Library_Dir' string - `Library_Name' string - `Library_Kind' string - `Library_Elaboration' string - `Library_Version' string - - The attributes for package `Naming' are as follows (see *Note Naming - Schemes::): - - Attribute Name Category Index Value - `Specification_Suffix' associative language name string - array - `Implementation_Suffix' associative language name string - array - `Separate_Suffix' simple n/a string - attribute - `Casing' simple n/a string - attribute - `Dot_Replacement' simple n/a string - attribute - `Specification' associative Ada unit name string - array - `Implementation' associative Ada unit name string - array - `Specification_Exceptions' associative language name string list - array - `Implementation_Exceptions' associative language name string list - array - - The attributes for package `Builder', `Compiler', `Binder', `Linker', - `Cross_Reference', and `Finder' are as follows (see *Note Switches and - Project Files::). - - Attribute Name Category Index Value - `Default_Switches' associative language name string list - array - `Switches' associative file name string list - array - - In addition, package `Builder' has a single string attribute - `Local_Configuration_Pragmas' and package `Builder' has a single string - attribute `Global_Configuration_Pragmas'. - - The attribute for package `Glide' are not documented: they are for - internal use only. - - Each simple attribute has a default value: the empty string (for - string-valued attributes) and the empty list (for string list-valued - attributes). - - Similar to variable declarations, an attribute declaration defines a - new value for an attribute. - - Examples of simple attribute declarations: - - for Object_Dir use "objects"; - for Source_Dirs use ("units", "test/drivers"); - - A "simple attribute declaration" starts with the reserved word `for', - followed by the name of the attribute, followed by the reserved word - `use', followed by an expression (whose kind depends on the attribute), - followed by a semicolon. - - Attributes may be referenced in expressions. The general form for - such a reference is `'': the entity for which the - attribute is defined, followed by an apostrophe, followed by the name - of the attribute. For associative array attributes, a litteral string - between parentheses need to be supplied as index. - - Examples are: - - project'Object_Dir - Naming'Dot_Replacement - Imported_Project'Source_Dirs - Imported_Project.Naming'Casing - Builder'Default_Switches("Ada") - - The entity may be: - * `project' for an attribute of the current project - - * The name of an existing package of the current project - - * The name of an imported project - - * The name of a parent project (extended by the current project) - - * An imported/parent project name, followed by a dot, followed - by a package name - - Example: - project Prj is - for Source_Dirs use project'Source_Dirs & "units"; - for Source_Dirs use project'Source_Dirs & "test/drivers" - end Prj; - - In the first attribute declaration, initially the attribute - `Source_Dirs' has the default value: an empty string list. After this - declaration, `Source_Dirs' is a string list of one element: "units". - After the second attribute declaration `Source_Dirs' is a string list of - two elements: "units" and "test/drivers". - - Note: this example is for illustration only. In practice, the - project file would contain only one attribute declaration: - - for Source_Dirs use ("units", "test/drivers"); - -  - File: gnat_ug_unx.info, Node: Associative Array Attributes, Next: case Constructions, Prev: Attributes, Up: Project File Syntax - - Associative Array Attributes - ---------------------------- - - Some attributes are defined as _associative arrays_. An associative - array may be regarded as a function that takes a string as a parameter - and delivers a string or string list value as its result. - - Here are some examples of associative array attribute declarations: - - for Implementation ("main") use "Main.ada"; - for Switches ("main.ada") use ("-v", "-gnatv"); - for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g"; - - Like untyped variables and simple attributes, associative array - attributes may be declared several times. Each declaration supplies a - new value for the attribute, replacing the previous setting. - -  - File: gnat_ug_unx.info, Node: case Constructions, Prev: Associative Array Attributes, Up: Project File Syntax - - `case' Constructions - -------------------- - - A `case' construction is used in a project file to effect conditional - behavior. Here is a typical example: - - project MyProj is - type OS_Type is ("Linux", "Unix", "NT", "VMS"); - - OS : OS_Type := external ("OS", "Linux"); - - package Compiler is - case OS is - when "Linux" | "Unix" => - for Default_Switches ("Ada") use ("-gnath"); - when "NT" => - for Default_Switches ("Ada") use ("-gnatP"); - when others => - end case; - end Compiler; - end MyProj; - - The syntax of a `case' construction is based on the Ada case statement - (although there is no `null' construction for empty alternatives). - - Following the reserved word `case' there is the case variable (a - typed string variable), the reserved word `is', and then a sequence of - one or more alternatives. Each alternative comprises the reserved word - `when', either a list of literal strings separated by the `"|"' - character or the reserved word `others', and the `"=>"' token. Each - literal string must belong to the string type that is the type of the - case variable. An `others' alternative, if present, must occur last. - The `end case;' sequence terminates the case construction. - - After each `=>', there are zero or more constructions. The only - constructions allowed in a case construction are other case - constructions and attribute declarations. String type declarations, - variable declarations and package declarations are not allowed. - - The value of the case variable is often given by an external - reference (see *Note External References in Project Files::). - -  - File: gnat_ug_unx.info, Node: Objects and Sources in Project Files, Next: Importing Projects, Prev: Project File Syntax, Up: GNAT Project Manager - - Objects and Sources in Project Files - ==================================== - - * Menu: - - * Object Directory:: - * Exec Directory:: - * Source Directories:: - * Source File Names:: - - Each project has exactly one object directory and one or more source - directories. The source directories must contain at least one source - file, unless the project file explicitly specifies that no source - files are present (see *Note Source File Names::). - -  - File: gnat_ug_unx.info, Node: Object Directory, Next: Exec Directory, Up: Objects and Sources in Project Files - - Object Directory - ---------------- - - The object directory for a project is the directory containing the - compiler's output (such as `ALI' files and object files) for the - project's immediate sources. Note that for inherited sources (when - extending a parent project) the parent project's object directory is - used. - - The object directory is given by the value of the attribute - `Object_Dir' in the project file. - - for Object_Dir use "objects"; - - The attribute OBJECT_DIR has a string value, the path name of the object - directory. The path name may be absolute or relative to the directory - of the project file. This directory must already exist, and be readable - and writable. - - By default, when the attribute `Object_Dir' is not given an explicit - value or when its value is the empty string, the object directory is - the same as the directory containing the project file. - -  - File: gnat_ug_unx.info, Node: Exec Directory, Next: Source Directories, Prev: Object Directory, Up: Objects and Sources in Project Files - - Exec Directory - -------------- - - The exec directory for a project is the directory containing the - executables for the project's main subprograms. - - The exec directory is given by the value of the attribute `Exec_Dir' - in the project file. - - for Exec_Dir use "executables"; - - The attribute EXEC_DIR has a string value, the path name of the exec - directory. The path name may be absolute or relative to the directory - of the project file. This directory must already exist, and be writable. - - By default, when the attribute `Exec_Dir' is not given an explicit - value or when its value is the empty string, the exec directory is the - same as the object directory of the project file. - -  - File: gnat_ug_unx.info, Node: Source Directories, Next: Source File Names, Prev: Exec Directory, Up: Objects and Sources in Project Files - - Source Directories - ------------------ - - The source directories of a project are specified by the project file - attribute `Source_Dirs'. - - This attribute's value is a string list. If the attribute is not - given an explicit value, then there is only one source directory, the - one where the project file resides. - - A `Source_Dirs' attribute that is explicitly defined to be the empty - list, as in - - for Source_Dirs use (); - - indicates that the project contains no source files. - - Otherwise, each string in the string list designates one or more - source directories. - - for Source_Dirs use ("sources", "test/drivers"); - - If a string in the list ends with `"/**"', then the directory whose - path name precedes the two asterisks, as well as all its subdirectories - (recursively), are source directories. - - for Source_Dirs use ("/system/sources/**"); - - Here the directory `/system/sources' and all of its subdirectories - (recursively) are source directories. - - To specify that the source directories are the directory of the - project file and all of its subdirectories, you can declare - `Source_Dirs' as follows: - for Source_Dirs use ("./**"); - - Each of the source directories must exist and be readable. - -  - File: gnat_ug_unx.info, Node: Source File Names, Prev: Source Directories, Up: Objects and Sources in Project Files - - Source File Names - ----------------- - - In a project that contains source files, their names may be specified - by the attributes `Source_Files' (a string list) or `Source_List_File' - (a string). Source file names never include any directory information. - - If the attribute `Source_Files' is given an explicit value, then each - element of the list is a source file name. - - for Source_Files use ("main.adb"); - for Source_Files use ("main.adb", "pack1.ads", "pack2.adb"); - - If the attribute `Source_Files' is not given an explicit value, but the - attribute `Source_List_File' is given a string value, then the source - file names are contained in the text file whose path name (absolute or - relative to the directory of the project file) is the value of the - attribute `Source_List_File'. - - Each line in the file that is not empty or is not a comment contains - a source file name. A comment line starts with two hyphens. - - for Source_List_File use "source_list.txt"; - - By default, if neither the attribute `Source_Files' nor the attribute - `Source_List_File' is given an explicit value, then each file in the - source directories that conforms to the project's naming scheme (see - *Note Naming Schemes::) is an immediate source of the project. - - A warning is issued if both attributes `Source_Files' and - `Source_List_File' are given explicit values. In this case, the - attribute `Source_Files' prevails. - - Each source file name must be the name of one and only one existing - source file in one of the source directories. - - A `Source_Files' attribute defined with an empty list as its value - indicates that there are no source files in the project. - - Except for projects that are clearly specified as containing no Ada - source files (`Source_Dirs' or `Source_Files' specified as an empty - list, or `Languages' specified without `"Ada"' in the list) - for Source_Dirs use (); - for Source_Files use (); - for Languages use ("C", "C++"); - - a project must contain at least one immediate source. - - Projects with no source files are useful as template packages (see - *Note Packages in Project Files::) for other projects; in particular to - define a package `Naming' (see *Note Naming Schemes::). - -  - File: gnat_ug_unx.info, Node: Importing Projects, Next: Project Extension, Prev: Objects and Sources in Project Files, Up: GNAT Project Manager - - Importing Projects - ================== - - An immediate source of a project P may depend on source files that are - neither immediate sources of P nor in the predefined library. To get - this effect, P must _import_ the projects that contain the needed - source files. - - with "project1", "utilities.gpr"; - with "/namings/apex.gpr"; - project Main is - ... - - As can be seen in this example, the syntax for importing projects is - similar to the syntax for importing compilation units in Ada. However, - project files use literal strings instead of names, and the `with' - clause identifies project files rather than packages. - - Each literal string is the file name or path name (absolute or - relative) of a project file. If a string is simply a file name, with no - path, then its location is determined by the _project path_: - - * If the environment variable `ADA_PROJECT_PATH' exists, then the - project path includes all the directories in this environment - variable, plus the directory of the project file. - - * If the environment variable `ADA_PROJECT_PATH' does not exist, - then the project path contains only one directory, namely the one - where the project file is located. - - If a relative pathname is used as in - - with "tests/proj"; - - then the path is relative to the directory where the importing project - file is located. Any symbolic link will be fully resolved in the - directory of the importing project file before the imported project - file is looked up. - - When the `with''ed project file name does not have an extension, the - default is `.gpr'. If a file with this extension is not found, then the - file name as specified in the `with' clause (no extension) will be - used. In the above example, if a file `project1.gpr' is found, then it - will be used; otherwise, if a file `project1' exists then it will be - used; if neither file exists, this is an error. - - A warning is issued if the name of the project file does not match - the name of the project; this check is case insensitive. - - Any source file that is an immediate source of the imported project - can be used by the immediate sources of the importing project, and - recursively. Thus if `A' imports `B', and `B' imports `C', the immediate - sources of `A' may depend on the immediate sources of `C', even if `A' - does not import `C' explicitly. However, this is not recommended, - because if and when `B' ceases to import `C', some sources in `A' will - no longer compile. - - A side effect of this capability is that cyclic dependences are not - permitted: if `A' imports `B' (directly or indirectly) then `B' is not - allowed to import `A'. - -  - File: gnat_ug_unx.info, Node: Project Extension, Next: External References in Project Files, Prev: Importing Projects, Up: GNAT Project Manager - - Project Extension - ================= - - During development of a large system, it is sometimes necessary to use - modified versions of some of the source files without changing the - original sources. This can be achieved through a facility known as - _project extension_. - - project Modified_Utilities extends "/baseline/utilities.gpr" is ... - - The project file for the project being extended (the _parent_) is - identified by the literal string that follows the reserved word - `extends', which itself follows the name of the extending project (the - _child_). - - By default, a child project inherits all the sources of its parent. - However, inherited sources can be overridden: a unit with the same name - as one in the parent will hide the original unit. Inherited sources - are considered to be sources (but not immediate sources) of the child - project; see *Note Project File Syntax::. - - An inherited source file retains any switches specified in the - parent project. - - For example if the project `Utilities' contains the specification - and the body of an Ada package `Util_IO', then the project - `Modified_Utilities' can contain a new body for package `Util_IO'. The - original body of `Util_IO' will not be considered in program builds. - However, the package specification will still be found in the project - `Utilities'. - - A child project can have only one parent but it may import any - number of other projects. - - A project is not allowed to import directly or indirectly at the - same time a child project and any of its ancestors. - -  - File: gnat_ug_unx.info, Node: External References in Project Files, Next: Packages in Project Files, Prev: Project Extension, Up: GNAT Project Manager - - External References in Project Files - ==================================== - - A project file may contain references to external variables; such - references are called _external references_. - - An external variable is either defined as part of the environment (an - environment variable in Unix, for example) or else specified on the - command line via the `-X_vbl_=_value_' switch. If both, then the - command line value is used. - - An external reference is denoted by the built-in function - `external', which returns a string value. This function has two forms: - * `external (external_variable_name)' - - * `external (external_variable_name, default_value)' - - Each parameter must be a string literal. For example: - - external ("USER") - external ("OS", "Linux") - - In the form with one parameter, the function returns the value of the - external variable given as parameter. If this name is not present in the - environment, then the returned value is an empty string. - - In the form with two string parameters, the second parameter is the - value returned when the variable given as the first parameter is not - present in the environment. In the example above, if `"OS"' is not the - name of an environment variable and is not passed on the command line, - then the returned value will be `"Linux"'. - - An external reference may be part of a string expression or of a - string list expression, to define variables or attributes. - - type Mode_Type is ("Debug", "Release"); - Mode : Mode_Type := external ("MODE"); - case Mode is - when "Debug" => - ... - -  - File: gnat_ug_unx.info, Node: Packages in Project Files, Next: Variables from Imported Projects, Prev: External References in Project Files, Up: GNAT Project Manager - - Packages in Project Files - ========================= - - The _package_ is the project file feature that defines the settings for - project-aware tools. For each such tool you can declare a - corresponding package; the names for these packages are preset (see - *Note Packages::) but are not case sensitive. A package may contain - variable declarations, attribute declarations, and case constructions. - - project Proj is - package Builder is -- used by gnatmake - for Default_Switches ("Ada") use ("-v", "-g"); - end Builder; - end Proj; - - A package declaration starts with the reserved word `package', followed - by the package name (case insensitive), followed by the reserved word - `is'. It ends with the reserved word `end', followed by the package - name, finally followed by a semi-colon. - - Most of the packages have an attribute `Default_Switches'. This - attribute is an associative array, and its value is a string list. The - index of the associative array is the name of a programming language - (case insensitive). This attribute indicates the switch or switches to - be used with the corresponding tool. - - Some packages also have another attribute, `Switches', an associative - array whose value is a string list. The index is the name of a source - file. This attribute indicates the switch or switches to be used by - the corresponding tool when dealing with this specific file. - - Further information on these switch-related attributes is found in - *Note Switches and Project Files::. - - A package may be declared as a _renaming_ of another package; e.g., - from the project file for an imported project. - - with "/global/apex.gpr"; - project Example is - package Naming renames Apex.Naming; - ... - end Example; - - Packages that are renamed in other project files often come from - project files that have no sources: they are just used as templates. - Any modification in the template will be reflected automatically in all - the project files that rename a package from the template. - - In addition to the tool-oriented packages, you can also declare a - package named `Naming' to establish specialized source file naming - conventions (see *Note Naming Schemes::). - -  - File: gnat_ug_unx.info, Node: Variables from Imported Projects, Next: Naming Schemes, Prev: Packages in Project Files, Up: GNAT Project Manager - - Variables from Imported Projects - ================================ - - An attribute or variable defined in an imported or parent project can - be used in expressions in the importing / extending project. Such an - attribute or variable is prefixed with the name of the project and (if - relevant) the name of package where it is defined. - - with "imported"; - project Main extends "base" is - Var1 := Imported.Var; - Var2 := Base.Var & ".new"; - - package Builder is - for Default_Switches ("Ada") use Imported.Builder.Ada_Switches & - "-gnatg" & "-v"; - end Builder; - - package Compiler is - for Default_Switches ("Ada") use Base.Compiler.Ada_Switches; - end Compiler; - end Main; - - In this example: - - * `Var1' is a copy of the variable `Var' defined in the project file - `"imported.gpr"' - - * the value of `Var2' is a copy of the value of variable `Var' - defined in the project file `base.gpr', concatenated with `".new"' - - * attribute `Default_Switches ("Ada")' in package `Builder' is a - string list that includes in its value a copy of variable - `Ada_Switches' defined in the `Builder' package in project file - `imported.gpr' plus two new elements: `"-gnatg"' and `"-v"'; - - * attribute `Default_Switches ("Ada")' in package `Compiler' is a - copy of the variable `Ada_Switches' defined in the `Compiler' - package in project file `base.gpr', the project being extended. - -  - File: gnat_ug_unx.info, Node: Naming Schemes, Next: Library Projects, Prev: Variables from Imported Projects, Up: GNAT Project Manager - - Naming Schemes - ============== - - Sometimes an Ada software system is ported from a foreign compilation - environment to GNAT, with file names that do not use the default GNAT - conventions. Instead of changing all the file names (which for a - variety of reasons might not be possible), you can define the relevant - file naming scheme in the `Naming' package in your project file. For - example, the following package models the Apex file naming rules: - - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "."; - for Specification_Suffix ("Ada") use ".1.ada"; - for Implementation_Suffix ("Ada") use ".2.ada"; - end Naming; - - You can define the following attributes in package `Naming': - - `CASING' - This must be a string with one of the three values `"lowercase"', - `"uppercase"' or `"mixedcase"'; these strings are case insensitive. - - If CASING is not specified, then the default is `"lowercase"'. - - `DOT_REPLACEMENT' - This must be a string whose value satisfies the following - conditions: - - * It must not be empty - - * It cannot start or end with an alphanumeric character - - * It cannot be a single underscore - - * It cannot start with an underscore followed by an alphanumeric - - * It cannot contain a dot `'.'' except if it the entire string - is `"."' - - If `Dot_Replacement' is not specified, then the default is `"-"'. - - `SPECIFICATION_SUFFIX' - This is an associative array (indexed by the programming language - name, case insensitive) whose value is a string that must satisfy - the following conditions: - - * It must not be empty - - * It cannot start with an alphanumeric character - - * It cannot start with an underscore followed by an - alphanumeric character - - If `Specification_Suffix ("Ada")' is not specified, then the - default is `".ads"'. - - `IMPLEMENTATION_SUFFIX' - This is an associative array (indexed by the programming language - name, case insensitive) whose value is a string that must satisfy - the following conditions: - - * It must not be empty - - * It cannot start with an alphanumeric character - - * It cannot start with an underscore followed by an - alphanumeric character - - * It cannot be a suffix of `Specification_Suffix' - - If `Implementation_Suffix ("Ada")' is not specified, then the - default is `".adb"'. - - `SEPARATE_SUFFIX' - This must be a string whose value satisfies the same conditions as - `Implementation_Suffix'. - - If `Separate_Suffix ("Ada")' is not specified, then it defaults to - same value as `Implementation_Suffix ("Ada")'. - - `SPECIFICATION' - You can use the `Specification' attribute, an associative array, - to define the source file name for an individual Ada compilation - unit's spec. The array index must be a string literal that - identifies the Ada unit (case insensitive). The value of this - attribute must be a string that identifies the file that contains - this unit's spec (case sensitive or insensitive depending on the - operating system). - - for Specification ("MyPack.MyChild") use "mypack.mychild.spec"; - - `IMPLEMENTATION' - You can use the `Implementation' attribute, an associative array, - to define the source file name for an individual Ada compilation - unit's body (possibly a subunit). The array index must be a - string literal that identifies the Ada unit (case insensitive). - The value of this attribute must be a string that identifies the - file that contains this unit's body or subunit (case sensitive or - insensitive depending on the operating system). - - for Implementation ("MyPack.MyChild") use "mypack.mychild.body"; - -  - File: gnat_ug_unx.info, Node: Library Projects, Next: Switches Related to Project Files, Prev: Naming Schemes, Up: GNAT Project Manager - - Library Projects - ================ - - _Library projects_ are projects whose object code is placed in a - library. (Note that this facility is not yet supported on all - platforms) - - To create a library project, you need to define in its project file - two project-level attributes: `Library_Name' and `Library_Dir'. - Additionally, you may define the library-related attributes - `Library_Kind', `Library_Version' and `Library_Elaboration'. - - The `Library_Name' attribute has a string value that must start with - a letter and include only letters and digits. - - The `Library_Dir' attribute has a string value that designates the - path (absolute or relative) of the directory where the library will - reside. It must designate an existing directory, and this directory - needs to be different from the project's object directory. It also - needs to be writable. - - If both `Library_Name' and `Library_Dir' are specified and are - legal, then the project file defines a library project. The optional - library-related attributes are checked only for such project files. - - The `Library_Kind' attribute has a string value that must be one of - the following (case insensitive): `"static"', `"dynamic"' or - `"relocatable"'. If this attribute is not specified, the library is a - static library. Otherwise, the library may be dynamic or relocatable. - Depending on the operating system, there may or may not be a distinction - between dynamic and relocatable libraries. For example, on Unix there - is no such distinction. - - The `Library_Version' attribute has a string value whose - interpretation is platform dependent. On Unix, it is used only for - dynamic/relocatable libraries as the internal name of the library (the - `"soname"'). If the library file name (built from the `Library_Name') - is different from the `Library_Version', then the library file will be - a symbolic link to the actual file whose name will be `Library_Version'. - - Example (on Unix): - - project Plib is - - Version := "1"; - - for Library_Dir use "lib_dir"; - for Library_Name use "dummy"; - for Library_Kind use "relocatable"; - for Library_Version use "libdummy.so." & Version; - - end Plib; - - Directory `lib_dir' will contain the internal library file whose name - will be `libdummy.so.1', and `libdummy.so' will be a symbolic link to - `libdummy.so.1'. - - When `gnatmake' detects that a project file (not the main project - file) is a library project file, it will check all immediate sources of - the project and rebuild the library if any of the sources have been - recompiled. All `ALI' files will also be copied from the object - directory to the library directory. To build executables, `gnatmake' - will use the library rather than the individual object files. - -  - File: gnat_ug_unx.info, Node: Switches Related to Project Files, Next: Tools Supporting Project Files, Prev: Library Projects, Up: GNAT Project Manager - - Switches Related to Project Files - ================================= - - The following switches are used by GNAT tools that support project - files: - - ``-PPROJECT'' - Indicates the name of a project file. This project file will be - parsed with the verbosity indicated by `-vP_x_', if any, and using - the external references indicated by `-X' switches, if any. - - There must be only one `-P' switch on the command line. - - Since the Project Manager parses the project file only after all - the switches on the command line are checked, the order of the - switches `-P', `-Vp_x_' or `-X' is not significant. - - ``-XNAME=VALUE'' - Indicates that external variable NAME has the value VALUE. The - Project Manager will use this value for occurrences of - `external(name)' when parsing the project file. - - If NAME or VALUE includes a space, then NAME=VALUE should be put - between quotes. - -XOS=NT - -X"user=John Doe" - - Several `-X' switches can be used simultaneously. If several `-X' - switches specify the same NAME, only the last one is used. - - An external variable specified with a `-X' switch takes precedence - over the value of the same name in the environment. - - ``-vP_x_'' - Indicates the verbosity of the parsing of GNAT project files. - `-vP0' means Default (no output for syntactically correct project - files); `-vP1' means Medium; `-vP2' means High. - - The default is Default. - - If several `-vP_x_' switches are present, only the last one is - used. - -  - File: gnat_ug_unx.info, Node: Tools Supporting Project Files, Next: An Extended Example, Prev: Switches Related to Project Files, Up: GNAT Project Manager - - Tools Supporting Project Files - ============================== - - * Menu: - - * gnatmake and Project Files:: - * The GNAT Driver and Project Files:: - * Glide and Project Files:: - -  - File: gnat_ug_unx.info, Node: gnatmake and Project Files, Next: The GNAT Driver and Project Files, Up: Tools Supporting Project Files - - gnatmake and Project Files - -------------------------- - - This section covers two topics related to `gnatmake' and project files: - defining switches for `gnatmake' and for the tools that it invokes; and - the use of the `Main' attribute. - - * Menu: - - * Switches and Project Files:: - * Project Files and Main Subprograms:: - -  - File: gnat_ug_unx.info, Node: Switches and Project Files, Next: Project Files and Main Subprograms, Up: gnatmake and Project Files - - Switches and Project Files - .......................... - - For each of the packages `Builder', `Compiler', `Binder', and `Linker', - you can specify a `Default_Switches' attribute, a `Switches' attribute, - or both; as their names imply, these switch-related attributes affect - which switches are used for which files when `gnatmake' is invoked. As - will be explained below, these package-contributed switches precede the - switches passed on the `gnatmake' command line. - - The `Default_Switches' attribute is an associative array indexed by - language name (case insensitive) and returning a string list. For - example: - - package Compiler is - for Default_Switches ("Ada") use ("-gnaty", "-v"); - end Compiler; - - The `Switches' attribute is also an associative array, indexed by a file - name (which may or may not be case sensitive, depending on the operating - system) and returning a string list. For example: - - package Builder is - for Switches ("main1.adb") use ("-O2"); - for Switches ("main2.adb") use ("-g"); - end Builder; - - For the `Builder' package, the file names should designate source files - for main subprograms. For the `Binder' and `Linker' packages, the file - names should designate `ALI' or source files for main subprograms. In - each case just the file name (without explicit extension) is acceptable. - - For each tool used in a program build (`gnatmake', the compiler, the - binder, and the linker), its corresponding package "contributes" a set - of switches for each file on which the tool is invoked, based on the - switch-related attributes defined in the package. In particular, the - switches that each of these packages contributes for a given file F - comprise: - - * the value of attribute `Switches (F)', if it is specified in the - package for the given file, - - * otherwise, the value of `Default_Switches ("Ada")', if it is - specified in the package. - - If neither of these attributes is defined in the package, then the - package does not contribute any switches for the given file. - - When `gnatmake' is invoked on a file, the switches comprise two sets, - in the following order: those contributed for the file by the `Builder' - package; and the switches passed on the command line. - - When `gnatmake' invokes a tool (compiler, binder, linker) on a file, - the switches passed to the tool comprise three sets, in the following - order: - - 1. the applicable switches contributed for the file by the `Builder' - package in the project file supplied on the command line; - - 2. those contributed for the file by the package (in the relevant - project file - see below) corresponding to the tool; and - - 3. the applicable switches passed on the command line. - - The term _applicable switches_ reflects the fact that `gnatmake' - switches may or may not be passed to individual tools, depending on the - individual switch. - - `gnatmake' may invoke the compiler on source files from different - projects. The Project Manager will use the appropriate project file to - determine the `Compiler' package for each source file being compiled. - Likewise for the `Binder' and `Linker' packages. - - As an example, consider the following package in a project file: - - project Proj1 is - package Compiler is - for Default_Switches ("Ada") use ("-g"); - for Switches ("a.adb") use ("-O1"); - for Switches ("b.adb") use ("-O2", "-gnaty"); - end Compiler; - end Proj1; - - If `gnatmake' is invoked with this project file, and it needs to - compile, say, the files `a.adb', `b.adb', and `c.adb', then `a.adb' - will be compiled with the switch `-O1', `b.adb' with switches `-O2' and - `-gnaty', and `c.adb' with `-g'. - - Another example illustrates the ordering of the switches contributed - by different packages: - - project Proj2 is - package Builder is - for Switches ("main.adb") use ("-g", "-O1", "-f"); - end Builder; - - package Compiler is - for Switches ("main.adb") use ("-O2"); - end Compiler; - end Proj2; - - If you issue the command: - - gnatmake -PProj2 -O0 main - - then the compiler will be invoked on `main.adb' with the following - sequence of switches - - -g -O1 -O2 -O0 - - with the last `-O' switch having precedence over the earlier ones; - several other switches (such as `-c') are added implicitly. - - The switches `-g' and `-O1' are contributed by package `Builder', - `-O2' is contributed by the package `Compiler' and `-O0' comes from the - command line. - - The `-g' switch will also be passed in the invocation of `gnatlink.' - - A final example illustrates switch contributions from packages in - different project files: - - project Proj3 is - for Source_Files use ("pack.ads", "pack.adb"); - package Compiler is - for Default_Switches ("Ada") use ("-gnata"); - end Compiler; - end Proj3; - - with "Proj3"; - project Proj4 is - for Source_Files use ("foo_main.adb", "bar_main.adb"); - package Builder is - for Switches ("foo_main.adb") use ("-s", "-g"); - end Builder; - end Proj4; - - -- Ada source file: - with Pack; - procedure Foo_Main is - ... - end Foo_Main; - - If the command is - gnatmake -PProj4 foo_main.adb -cargs -gnato - - then the switches passed to the compiler for `foo_main.adb' are `-g' - (contributed by the package `Proj4.Builder') and `-gnato' (passed on - the command line). When the imported package `Pack' is compiled, the - switches used are `-g' from `Proj4.Builder', `-gnata' (contributed from - package `Proj3.Compiler', and `-gnato' from the command line. - -  - File: gnat_ug_unx.info, Node: Project Files and Main Subprograms, Prev: Switches and Project Files, Up: gnatmake and Project Files - - Project Files and Main Subprograms - .................................. - - When using a project file, you can invoke `gnatmake' with several main - subprograms, by specifying their source files on the command line. - Each of these needs to be an immediate source file of the project. - - gnatmake -Pprj main1 main2 main3 - - When using a project file, you can also invoke `gnatmake' without - explicitly specifying any main, and the effect depends on whether you - have defined the `Main' attribute. This attribute has a string list - value, where each element in the list is the name of a source file (the - file extension is optional) containing a main subprogram. - - If the `Main' attribute is defined in a project file as a non-empty - string list and the switch `-u' is not used on the command line, then - invoking `gnatmake' with this project file but without any main on the - command line is equivalent to invoking `gnatmake' with all the file - names in the `Main' attribute on the command line. - - Example: - project Prj is - for Main use ("main1", "main2", "main3"); - end Prj; - - With this project file, `"gnatmake -Pprj"' is equivalent to `"gnatmake - -Pprj main1 main2 main3"'. - - When the project attribute `Main' is not specified, or is specified - as an empty string list, or when the switch `-u' is used on the command - line, then invoking `gnatmake' with no main on the command line will - result in all immediate sources of the project file being checked, and - potentially recompiled. Depending on the presence of the switch `-u', - sources from other project files on which the immediate sources of the - main project file depend are also checked and potentially recompiled. - In other words, the `-u' switch is applied to all of the immediate - sources of themain project file. - -  - File: gnat_ug_unx.info, Node: The GNAT Driver and Project Files, Next: Glide and Project Files, Prev: gnatmake and Project Files, Up: Tools Supporting Project Files - - The GNAT Driver and Project Files - --------------------------------- - - A number of GNAT tools, other than `gnatmake' are project-aware: - `gnatbind', `gnatfind', `gnatlink', `gnatls' and `gnatxref'. However, - none of these tools can be invoked directly with a project file switch - (`-P'). They need to be invoke through the `gnat' driver. - - The `gnat' driver is a front-end that accepts a number of commands - and call the corresponding tool. It has been designed initially for VMS - to convert VMS style qualifiers to Unix style switches, but it is now - available to all the GNAT supported platforms. - - On non VMS platforms, the `gnat' driver accepts the following - commands (case insensitive): - - * BIND to invoke `gnatbind' - - * CHOP to invoke `gnatchop' - - * COMP or COMPILE to invoke the compiler - - * ELIM to invoke `gnatelim' - - * FIND to invoke `gnatfind' - - * KR or KRUNCH to invoke `gnatkr' - - * LINK to invoke `gnatlink' - - * LS or LIST to invoke `gnatls' - - * MAKE to invoke `gnatmake' - - * NAME to invoke `gnatname' - - * PREP or PREPROCESS to invoke `gnatprep' - - * PSTA or STANDARD to invoke `gnatpsta' - - * STUB to invoke `gnatstub' - - * XREF to invoke `gnatxref' - - Note that the compiler is invoked using the command `gnatmake -f -u'. - - Following the command, you may put switches and arguments for the - invoked tool. - - gnat bind -C main.ali - gnat ls -a main - gnat chop foo.txt - - In addition, for command BIND, FIND, LS or LIST, LINK and XREF, the - project file related switches (`-P', `-X' and `-vPx') may be used in - addition to the switches of the invoking tool. - - For each of these command, there is possibly a package in the main - project that corresponds to the invoked tool. - - * package `Binder' for command BIND (invoking `gnatbind') - - * package `Finder' for command FIND (invoking `gnatfind') - - * package `Gnatls' for command LS or LIST (invoking `gnatls') - - * package `Linker' for command LINK (invoking `gnatlink') - - * package `Cross_Reference' for command XREF (invoking `gnatlink') - - - Package `Gnatls' has a unique attribute `Switches', a simple variable - with a string list value. It contains switches for the invocation of - `gnatls'. - - project Proj1 is - package gnatls is - for Switches use ("-a", "-v"); - end gnatls; - end Proj1; - - All other packages contains a switch `Default_Switches', an associative - array, indexed by the programming language (case insensitive) and - having a string list value. `Default_Switches ("Ada")' contains the - switches for the invocation of the tool corresponding to the package. - - project Proj is - - for Source_Dirs use ("./**"); - - package gnatls is - for Switches use ("-a", "-v"); - end gnatls; - - package Binder is - for Default_Switches ("Ada") use ("-C", "-e"); - end Binder; - - package Linker is - for Default_Switches ("Ada") use ("-C"); - end Linker; - - package Finder is - for Default_Switches ("Ada") use ("-a", "-f"); - end Finder; - - package Cross_Reference is - for Default_Switches ("Ada") use ("-a", "-f", "-d", "-u"); - end Cross_Reference; - end Proj; - - With the above project file, commands such as - - gnat ls -Pproj main - gnat xref -Pproj main - gnat bind -Pproj main.ali - - will set up the environment properly and invoke the tool with the - switches found in the package corresponding to the tool. - -  - File: gnat_ug_unx.info, Node: Glide and Project Files, Prev: The GNAT Driver and Project Files, Up: Tools Supporting Project Files - - Glide and Project Files - ----------------------- - - Glide will automatically recognize the `.gpr' extension for project - files, and will convert them to its own internal format automatically. - However, it doesn't provide a syntax-oriented editor for modifying these - files. The project file will be loaded as text when you select the - menu item `Ada' => `Project' => `Edit'. You can edit this text and - save the `gpr' file; when you next select this project file in Glide it - will be automatically reloaded. - -  - File: gnat_ug_unx.info, Node: An Extended Example, Next: Project File Complete Syntax, Prev: Tools Supporting Project Files, Up: GNAT Project Manager - - An Extended Example - =================== - - Suppose that we have two programs, PROG1 and PROG2, with the sources in - the respective directories. We would like to build them with a single - `gnatmake' command, and we would like to place their object files into - `.build' subdirectories of the source directories. Furthermore, we would - like to have to have two separate subdirectories in `.build' - - `release' and `debug' - which will contain the object files compiled - with different set of compilation flags. - - In other words, we have the following structure: - - main - |- prog1 - | |- .build - | | debug - | | release - |- prog2 - |- .build - | debug - | release - - Here are the project files that we need to create in a directory `main' - to maintain this structure: - - 1. We create a `Common' project with a package `Compiler' that - specifies the compilation switches: - - File "common.gpr": - project Common is - - for Source_Dirs use (); -- No source files - - type Build_Type is ("release", "debug"); - Build : Build_Type := External ("BUILD", "debug"); - package Compiler is - case Build is - when "release" => - for Default_Switches ("Ada") use ("-O2"); - when "debug" => - for Default_Switches ("Ada") use ("-g"); - end case; - end Compiler; - - end Common; - - 2. We create separate projects for the two programs: - - File "prog1.gpr": - - with "common"; - project Prog1 is - - for Source_Dirs use ("prog1"); - for Object_Dir use "prog1/.build/" & Common.Build; - - package Compiler renames Common.Compiler; - - end Prog1; - - File "prog2.gpr": - - with "common"; - project Prog2 is - - for Source_Dirs use ("prog2"); - for Object_Dir use "prog2/.build/" & Common.Build; - - package Compiler renames Common.Compiler; - end Prog2; - - 3. We create a wrapping project MAIN: - - File "main.gpr": - - with "common"; - with "prog1"; - with "prog2"; - project Main is - - package Compiler renames Common.Compiler; - - end Main; - - 4. Finally we need to create a dummy procedure that `with's (either - explicitly or implicitly) all the sources of our two programs. - - - Now we can build the programs using the command - - gnatmake -Pmain dummy - - for the Debug mode, or - - gnatmake -Pmain -XBUILD=release - - for the Release mode. - -  - File: gnat_ug_unx.info, Node: Project File Complete Syntax, Prev: An Extended Example, Up: GNAT Project Manager - - Project File Complete Syntax - ============================ - - project ::= - context_clause project_declaration - - context_clause ::= - {with_clause} - - with_clause ::= - with literal_string { , literal_string } ; - - project_declaration ::= - project simple_name [ extends literal_string ] is - {declarative_item} - end simple_name; - - declarative_item ::= - package_declaration | - typed_string_declaration | - other_declarative_item - - package_declaration ::= - package simple_name package_completion - - package_completion ::= - package_body | package_renaming - - package body ::= - is - {other_declarative_item} - end simple_name ; - - package_renaming ::== - renames simple_name.simple_name ; - - typed_string_declaration ::= - type _simple_name is - ( literal_string {, literal_string} ); - - other_declarative_item ::= - attribute_declaration | - typed_variable_declaration | - variable_declaration | - case_construction - - attribute_declaration ::= - for attribute use expression ; - - attribute ::= - simple_name | - simple_name ( literal_string ) - - typed_variable_declaration ::= - simple_name : name := string_expression ; - - variable_declaration ::= - simple_name := expression; - - expression ::= - term {& term} - - term ::= - literal_string | - string_list | - name | - external_value | - attribute_reference - - literal_string ::= - (same as Ada) - - string_list ::= - ( expression { , expression } ) - - external_value ::= - external ( literal_string [, literal_string] ) - - attribute_reference ::= - attribute_parent ' simple_name [ ( literal_string ) ] - - attribute_parent ::= - project | - simple_name | - simple_name . simple_name - - case_construction ::= - case name is - {case_item} - end case ; - - case_item ::= - when discrete_choice_list => {case_construction | attribute_declaration} - - discrete_choice_list ::= - literal_string {| literal_string} - - name ::= - simple_name {. simple_name} - - simple_name ::= - identifier (same as Ada) - -  - File: gnat_ug_unx.info, Node: Elaboration Order Handling in GNAT, Next: The Cross-Referencing Tools gnatxref and gnatfind, Prev: GNAT Project Manager, Up: Top - - Elaboration Order Handling in GNAT - ********************************** - - * Menu: - - * Elaboration Code in Ada 95:: - * Checking the Elaboration Order in Ada 95:: - * Controlling the Elaboration Order in Ada 95:: - * Controlling Elaboration in GNAT - Internal Calls:: - * Controlling Elaboration in GNAT - External Calls:: - * Default Behavior in GNAT - Ensuring Safety:: - * Elaboration Issues for Library Tasks:: - * Mixing Elaboration Models:: - * What to Do If the Default Elaboration Behavior Fails:: - * Elaboration for Access-to-Subprogram Values:: - * Summary of Procedures for Elaboration Control:: - * Other Elaboration Order Considerations:: - - This chapter describes the handling of elaboration code in Ada 95 and - in GNAT, and discusses how the order of elaboration of program units can - be controlled in GNAT, either automatically or with explicit programming - features. - -  - File: gnat_ug_unx.info, Node: Elaboration Code in Ada 95, Next: Checking the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Elaboration Code in Ada 95 - ========================== - - Ada 95 provides rather general mechanisms for executing code at - elaboration time, that is to say before the main program starts - executing. Such code arises in three contexts: - - Initializers for variables. - Variables declared at the library level, in package specs or - bodies, can require initialization that is performed at - elaboration time, as in: - Sqrt_Half : Float := Sqrt (0.5); - - Package initialization code - Code in a `BEGIN-END' section at the outer level of a package body - is executed as part of the package body elaboration code. - - Library level task allocators - Tasks that are declared using task allocators at the library level - start executing immediately and hence can execute at elaboration - time. - - Subprogram calls are possible in any of these contexts, which means that - any arbitrary part of the program may be executed as part of the - elaboration code. It is even possible to write a program which does all - its work at elaboration time, with a null main program, although - stylistically this would usually be considered an inappropriate way to - structure a program. - - An important concern arises in the context of elaboration code: we - have to be sure that it is executed in an appropriate order. What we - have is a series of elaboration code sections, potentially one section - for each unit in the program. It is important that these execute in the - correct order. Correctness here means that, taking the above example of - the declaration of `Sqrt_Half', if some other piece of elaboration code - references `Sqrt_Half', then it must run after the section of - elaboration code that contains the declaration of `Sqrt_Half'. - - There would never be any order of elaboration problem if we made a - rule that whenever you `with' a unit, you must elaborate both the spec - and body of that unit before elaborating the unit doing the `with''ing: - - with Unit_1; - package Unit_2 is ... - - would require that both the body and spec of `Unit_1' be elaborated - before the spec of `Unit_2'. However, a rule like that would be far too - restrictive. In particular, it would make it impossible to have routines - in separate packages that were mutually recursive. - - You might think that a clever enough compiler could look at the - actual elaboration code and determine an appropriate correct order of - elaboration, but in the general case, this is not possible. Consider - the following example. - - In the body of `Unit_1', we have a procedure `Func_1' that references - the variable `Sqrt_1', which is declared in the elaboration code of the - body of `Unit_1': - - Sqrt_1 : Float := Sqrt (0.1); - - The elaboration code of the body of `Unit_1' also contains: - - if expression_1 = 1 then - Q := Unit_2.Func_2; - end if; - - `Unit_2' is exactly parallel, it has a procedure `Func_2' that - references the variable `Sqrt_2', which is declared in the elaboration - code of the body `Unit_2': - - Sqrt_2 : Float := Sqrt (0.1); - - The elaboration code of the body of `Unit_2' also contains: - - if expression_2 = 2 then - Q := Unit_1.Func_1; - end if; - - Now the question is, which of the following orders of elaboration is - acceptable: - - Spec of Unit_1 - Spec of Unit_2 - Body of Unit_1 - Body of Unit_2 - - or - - Spec of Unit_2 - Spec of Unit_1 - Body of Unit_2 - Body of Unit_1 - - If you carefully analyze the flow here, you will see that you cannot - tell at compile time the answer to this question. If `expression_1' is - not equal to 1, and `expression_2' is not equal to 2, then either order - is acceptable, because neither of the function calls is executed. If - both tests evaluate to true, then neither order is acceptable and in - fact there is no correct order. - - If one of the two expressions is true, and the other is false, then - one of the above orders is correct, and the other is incorrect. For - example, if `expression_1' = 1 and `expression_2' /= 2, then the call - to `Func_2' will occur, but not the call to `Func_1.' This means that - it is essential to elaborate the body of `Unit_1' before the body of - `Unit_2', so the first order of elaboration is correct and the second - is wrong. - - By making `expression_1' and `expression_2' depend on input data, or - perhaps the time of day, we can make it impossible for the compiler or - binder to figure out which of these expressions will be true, and hence - it is impossible to guarantee a safe order of elaboration at run time. - -  - File: gnat_ug_unx.info, Node: Checking the Elaboration Order in Ada 95, Next: Controlling the Elaboration Order in Ada 95, Prev: Elaboration Code in Ada 95, Up: Elaboration Order Handling in GNAT - - Checking the Elaboration Order in Ada 95 - ======================================== - - In some languages that involve the same kind of elaboration problems, - e.g. Java and C++, the programmer is expected to worry about these - ordering problems himself, and it is common to write a program in which - an incorrect elaboration order gives surprising results, because it - references variables before they are initialized. Ada 95 is designed - to be a safe language, and a programmer-beware approach is clearly not - sufficient. Consequently, the language provides three lines of defense: - - Standard rules - Some standard rules restrict the possible choice of elaboration - order. In particular, if you `with' a unit, then its spec is always - elaborated before the unit doing the `with'. Similarly, a parent - spec is always elaborated before the child spec, and finally a - spec is always elaborated before its corresponding body. - - Dynamic elaboration checks - Dynamic checks are made at run time, so that if some entity is - accessed before it is elaborated (typically by means of a - subprogram call) then the exception (`Program_Error') is raised. - - Elaboration control - Facilities are provided for the programmer to specify the desired - order of elaboration. - - Let's look at these facilities in more detail. First, the rules for - dynamic checking. One possible rule would be simply to say that the - exception is raised if you access a variable which has not yet been - elaborated. The trouble with this approach is that it could require - expensive checks on every variable reference. Instead Ada 95 has two - rules which are a little more restrictive, but easier to check, and - easier to state: - - Restrictions on calls - A subprogram can only be called at elaboration time if its body - has been elaborated. The rules for elaboration given above - guarantee that the spec of the subprogram has been elaborated - before the call, but not the body. If this rule is violated, then - the exception `Program_Error' is raised. - - Restrictions on instantiations - A generic unit can only be instantiated if the body of the generic - unit has been elaborated. Again, the rules for elaboration given - above guarantee that the spec of the generic unit has been - elaborated before the instantiation, but not the body. If this - rule is violated, then the exception `Program_Error' is raised. - - The idea is that if the body has been elaborated, then any variables it - references must have been elaborated; by checking for the body being - elaborated we guarantee that none of its references causes any trouble. - As we noted above, this is a little too restrictive, because a - subprogram that has no non-local references in its body may in fact be - safe to call. However, it really would be unsafe to rely on this, - because it would mean that the caller was aware of details of the - implementation in the body. This goes against the basic tenets of Ada. - - A plausible implementation can be described as follows. A Boolean - variable is associated with each subprogram and each generic unit. This - variable is initialized to False, and is set to True at the point body - is elaborated. Every call or instantiation checks the variable, and - raises `Program_Error' if the variable is False. - - Note that one might think that it would be good enough to have one - Boolean variable for each package, but that would not deal with cases - of trying to call a body in the same package as the call that has not - been elaborated yet. Of course a compiler may be able to do enough - analysis to optimize away some of the Boolean variables as unnecessary, - and `GNAT' indeed does such optimizations, but still the easiest - conceptual model is to think of there being one variable per subprogram. - -  - File: gnat_ug_unx.info, Node: Controlling the Elaboration Order in Ada 95, Next: Controlling Elaboration in GNAT - Internal Calls, Prev: Checking the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Controlling the Elaboration Order in Ada 95 - =========================================== - - In the previous section we discussed the rules in Ada 95 which ensure - that `Program_Error' is raised if an incorrect elaboration order is - chosen. This prevents erroneous executions, but we need mechanisms to - specify a correct execution and avoid the exception altogether. To - achieve this, Ada 95 provides a number of features for controlling the - order of elaboration. We discuss these features in this section. - - First, there are several ways of indicating to the compiler that a - given unit has no elaboration problems: - - packages that do not require a body - In Ada 95, a library package that does not require a body does not - permit a body. This means that if we have a such a package, as in: - - package Definitions is - generic - type m is new integer; - package Subp is - type a is array (1 .. 10) of m; - type b is array (1 .. 20) of m; - end Subp; - end Definitions; - - A package that `with''s `Definitions' may safely instantiate - `Definitions.Subp' because the compiler can determine that there - definitely is no package body to worry about in this case - - pragma Pure - Places sufficient restrictions on a unit to guarantee that no call - to any subprogram in the unit can result in an elaboration - problem. This means that the compiler does not need to worry about - the point of elaboration of such units, and in particular, does - not need to check any calls to any subprograms in this unit. - - pragma Preelaborate - This pragma places slightly less stringent restrictions on a unit - than does pragma Pure, but these restrictions are still sufficient - to ensure that there are no elaboration problems with any calls to - the unit. - - pragma Elaborate_Body - This pragma requires that the body of a unit be elaborated - immediately after its spec. Suppose a unit `A' has such a pragma, - and unit `B' does a `with' of unit `A'. Recall that the standard - rules require the spec of unit `A' to be elaborated before the - `with''ing unit; given the pragma in `A', we also know that the - body of `A' will be elaborated before `B', so that calls to `A' - are safe and do not need a check. - - Note that, unlike pragma `Pure' and pragma `Preelaborate', the use of - `Elaborate_Body' does not guarantee that the program is free of - elaboration problems, because it may not be possible to satisfy the - requested elaboration order. Let's go back to the example with - `Unit_1' and `Unit_2'. If a programmer marks `Unit_1' as - `Elaborate_Body', and not `Unit_2,' then the order of elaboration will - be: - - Spec of Unit_2 - Spec of Unit_1 - Body of Unit_1 - Body of Unit_2 - - Now that means that the call to `Func_1' in `Unit_2' need not be - checked, it must be safe. But the call to `Func_2' in `Unit_1' may - still fail if `Expression_1' is equal to 1, and the programmer must - still take responsibility for this not being the case. - - If all units carry a pragma `Elaborate_Body', then all problems are - eliminated, except for calls entirely within a body, which are in any - case fully under programmer control. However, using the pragma - everywhere is not always possible. In particular, for our - `Unit_1'/`Unit_2' example, if we marked both of them as having pragma - `Elaborate_Body', then clearly there would be no possible elaboration - order. - - The above pragmas allow a server to guarantee safe use by clients, - and clearly this is the preferable approach. Consequently a good rule in - Ada 95 is to mark units as `Pure' or `Preelaborate' if possible, and if - this is not possible, mark them as `Elaborate_Body' if possible. As we - have seen, there are situations where neither of these three pragmas - can be used. So we also provide methods for clients to control the - order of elaboration of the servers on which they depend: - - pragma Elaborate (unit) - This pragma is placed in the context clause, after a `with' clause, - and it requires that the body of the named unit be elaborated - before the unit in which the pragma occurs. The idea is to use - this pragma if the current unit calls at elaboration time, - directly or indirectly, some subprogram in the named unit. - - pragma Elaborate_All (unit) - This is a stronger version of the Elaborate pragma. Consider the - following example: - - Unit A `with''s unit B and calls B.Func in elab code - Unit B `with''s unit C, and B.Func calls C.Func - - Now if we put a pragma `Elaborate (B)' in unit `A', this ensures - that the body of `B' is elaborated before the call, but not the - body of `C', so the call to `C.Func' could still cause - `Program_Error' to be raised. - - The effect of a pragma `Elaborate_All' is stronger, it requires - not only that the body of the named unit be elaborated before the - unit doing the `with', but also the bodies of all units that the - named unit uses, following `with' links transitively. For example, - if we put a pragma `Elaborate_All (B)' in unit `A', then it - requires not only that the body of `B' be elaborated before `A', - but also the body of `C', because `B' `with''s `C'. - - We are now in a position to give a usage rule in Ada 95 for avoiding - elaboration problems, at least if dynamic dispatching and access to - subprogram values are not used. We will handle these cases separately - later. - - The rule is simple. If a unit has elaboration code that can directly - or indirectly make a call to a subprogram in a `with''ed unit, or - instantiate a generic unit in a `with''ed unit, then if the `with''ed - unit does not have pragma `Pure' or `Preelaborate', then the client - should have a pragma `Elaborate_All' for the `with''ed unit. By - following this rule a client is assured that calls can be made without - risk of an exception. If this rule is not followed, then a program may - be in one of four states: - - No order exists - No order of elaboration exists which follows the rules, taking into - account any `Elaborate', `Elaborate_All', or `Elaborate_Body' - pragmas. In this case, an Ada 95 compiler must diagnose the - situation at bind time, and refuse to build an executable program. - - One or more orders exist, all incorrect - One or more acceptable elaboration orders exists, and all of them - generate an elaboration order problem. In this case, the binder - can build an executable program, but `Program_Error' will be raised - when the program is run. - - Several orders exist, some right, some incorrect - One or more acceptable elaboration orders exists, and some of them - work, and some do not. The programmer has not controlled the order - of elaboration, so the binder may or may not pick one of the - correct orders, and the program may or may not raise an exception - when it is run. This is the worst case, because it means that the - program may fail when moved to another compiler, or even another - version of the same compiler. - - One or more orders exists, all correct - One ore more acceptable elaboration orders exist, and all of them - work. In this case the program runs successfully. This state of - affairs can be guaranteed by following the rule we gave above, but - may be true even if the rule is not followed. - - Note that one additional advantage of following our Elaborate_All rule - is that the program continues to stay in the ideal (all orders OK) state - even if maintenance changes some bodies of some subprograms. - Conversely, if a program that does not follow this rule happens to be - safe at some point, this state of affairs may deteriorate silently as a - result of maintenance changes. - - You may have noticed that the above discussion did not mention the - use of `Elaborate_Body'. This was a deliberate omission. If you `with' - an `Elaborate_Body' unit, it still may be the case that code in the - body makes calls to some other unit, so it is still necessary to use - `Elaborate_All' on such units. - -  - File: gnat_ug_unx.info, Node: Controlling Elaboration in GNAT - Internal Calls, Next: Controlling Elaboration in GNAT - External Calls, Prev: Controlling the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Controlling Elaboration in GNAT - Internal Calls - ================================================ - - In the case of internal calls, i.e. calls within a single package, the - programmer has full control over the order of elaboration, and it is up - to the programmer to elaborate declarations in an appropriate order. For - example writing: - - function One return Float; - - Q : Float := One; - - function One return Float is - begin - return 1.0; - end One; - - will obviously raise `Program_Error' at run time, because function One - will be called before its body is elaborated. In this case GNAT will - generate a warning that the call will raise `Program_Error': - - 1. procedure y is - 2. function One return Float; - 3. - 4. Q : Float := One; - | - >>> warning: cannot call "One" before body is elaborated - >>> warning: Program_Error will be raised at run time - - 5. - 6. function One return Float is - 7. begin - 8. return 1.0; - 9. end One; - 10. - 11. begin - 12. null; - 13. end; - - Note that in this particular case, it is likely that the call is safe, - because the function `One' does not access any global variables. - Nevertheless in Ada 95, we do not want the validity of the check to - depend on the contents of the body (think about the separate - compilation case), so this is still wrong, as we discussed in the - previous sections. - - The error is easily corrected by rearranging the declarations so - that the body of One appears before the declaration containing the call - (note that in Ada 95, declarations can appear in any order, so there is - no restriction that would prevent this reordering, and if we write: - - function One return Float; - - function One return Float is - begin - return 1.0; - end One; - - Q : Float := One; - - then all is well, no warning is generated, and no `Program_Error' - exception will be raised. Things are more complicated when a chain of - subprograms is executed: - - function A return Integer; - function B return Integer; - function C return Integer; - - function B return Integer is begin return A; end; - function C return Integer is begin return B; end; - - X : Integer := C; - - function A return Integer is begin return 1; end; - - Now the call to `C' at elaboration time in the declaration of `X' is - correct, because the body of `C' is already elaborated, and the call to - `B' within the body of `C' is correct, but the call to `A' within the - body of `B' is incorrect, because the body of `A' has not been - elaborated, so `Program_Error' will be raised on the call to `A'. In - this case GNAT will generate a warning that `Program_Error' may be - raised at the point of the call. Let's look at the warning: - - 1. procedure x is - 2. function A return Integer; - 3. function B return Integer; - 4. function C return Integer; - 5. - 6. function B return Integer is begin return A; end; - | - >>> warning: call to "A" before body is elaborated may - raise Program_Error - >>> warning: "B" called at line 7 - >>> warning: "C" called at line 9 - - 7. function C return Integer is begin return B; end; - 8. - 9. X : Integer := C; - 10. - 11. function A return Integer is begin return 1; end; - 12. - 13. begin - 14. null; - 15. end; - - Note that the message here says "may raise", instead of the direct case, - where the message says "will be raised". That's because whether `A' is - actually called depends in general on run-time flow of control. For - example, if the body of `B' said - - function B return Integer is - begin - if some-condition-depending-on-input-data then - return A; - else - return 1; - end if; - end B; - - then we could not know until run time whether the incorrect call to A - would actually occur, so `Program_Error' might or might not be raised. - It is possible for a compiler to do a better job of analyzing bodies, to - determine whether or not `Program_Error' might be raised, but it - certainly couldn't do a perfect job (that would require solving the - halting problem and is provably impossible), and because this is a - warning anyway, it does not seem worth the effort to do the analysis. - Cases in which it would be relevant are rare. - - In practice, warnings of either of the forms given above will - usually correspond to real errors, and should be examined carefully and - eliminated. In the rare case where a warning is bogus, it can be - suppressed by any of the following methods: - - * Compile with the `-gnatws' switch set - - * Suppress `Elaboration_Checks' for the called subprogram - - * Use pragma `Warnings_Off' to turn warnings off for the call - - For the internal elaboration check case, GNAT by default generates the - necessary run-time checks to ensure that `Program_Error' is raised if - any call fails an elaboration check. Of course this can only happen if a - warning has been issued as described above. The use of pragma `Suppress - (Elaboration_Checks)' may (but is not guaranteed to) suppress some of - these checks, meaning that it may be possible (but is not guaranteed) - for a program to be able to call a subprogram whose body is not yet - elaborated, without raising a `Program_Error' exception. - -  - File: gnat_ug_unx.info, Node: Controlling Elaboration in GNAT - External Calls, Next: Default Behavior in GNAT - Ensuring Safety, Prev: Controlling Elaboration in GNAT - Internal Calls, Up: Elaboration Order Handling in GNAT - - Controlling Elaboration in GNAT - External Calls - ================================================ - - The previous section discussed the case in which the execution of a - particular thread of elaboration code occurred entirely within a single - unit. This is the easy case to handle, because a programmer has direct - and total control over the order of elaboration, and furthermore, - checks need only be generated in cases which are rare and which the - compiler can easily detect. The situation is more complex when - separate compilation is taken into account. Consider the following: - - package Math is - function Sqrt (Arg : Float) return Float; - end Math; - - package body Math is - function Sqrt (Arg : Float) return Float is - begin - ... - end Sqrt; - end Math; - - with Math; - package Stuff is - X : Float := Math.Sqrt (0.5); - end Stuff; - - with Stuff; - procedure Main is - begin - ... - end Main; - - where `Main' is the main program. When this program is executed, the - elaboration code must first be executed, and one of the jobs of the - binder is to determine the order in which the units of a program are to - be elaborated. In this case we have four units: the spec and body of - `Math', the spec of `Stuff' and the body of `Main'). In what order - should the four separate sections of elaboration code be executed? - - There are some restrictions in the order of elaboration that the - binder can choose. In particular, if unit U has a `with' for a package - `X', then you are assured that the spec of `X' is elaborated before U , - but you are not assured that the body of `X' is elaborated before U. - This means that in the above case, the binder is allowed to choose the - order: - - spec of Math - spec of Stuff - body of Math - body of Main - - but that's not good, because now the call to `Math.Sqrt' that happens - during the elaboration of the `Stuff' spec happens before the body of - `Math.Sqrt' is elaborated, and hence causes `Program_Error' exception - to be raised. At first glance, one might say that the binder is - misbehaving, because obviously you want to elaborate the body of - something you `with' first, but that is not a general rule that can be - followed in all cases. Consider - - package X is ... - - package Y is ... - - with X; - package body Y is ... - - with Y; - package body X is ... - - This is a common arrangement, and, apart from the order of elaboration - problems that might arise in connection with elaboration code, this - works fine. A rule that says that you must first elaborate the body of - anything you `with' cannot work in this case: the body of `X' `with''s - `Y', which means you would have to elaborate the body of `Y' first, but - that `with''s `X', which means you have to elaborate the body of `X' - first, but ... and we have a loop that cannot be broken. - - It is true that the binder can in many cases guess an order of - elaboration that is unlikely to cause a `Program_Error' exception to be - raised, and it tries to do so (in the above example of - `Math/Stuff/Spec', the GNAT binder will by default elaborate the body - of `Math' right after its spec, so all will be well). - - However, a program that blindly relies on the binder to be helpful - can get into trouble, as we discussed in the previous sections, so GNAT - provides a number of facilities for assisting the programmer in - developing programs that are robust with respect to elaboration order. - -  - File: gnat_ug_unx.info, Node: Default Behavior in GNAT - Ensuring Safety, Next: Elaboration Issues for Library Tasks, Prev: Controlling Elaboration in GNAT - External Calls, Up: Elaboration Order Handling in GNAT - - Default Behavior in GNAT - Ensuring Safety - ========================================== - - The default behavior in GNAT ensures elaboration safety. In its default - mode GNAT implements the rule we previously described as the right - approach. Let's restate it: - - * _If a unit has elaboration code that can directly or indirectly - make a call to a subprogram in a `with''ed unit, or instantiate a - generic unit in a `with''ed unit, then if the `with''ed unit does - not have pragma `Pure' or `Preelaborate', then the client should - have an `Elaborate_All' for the `with''ed unit._ - - By following this rule a client is assured that calls and - instantiations can be made without risk of an exception. - - In this mode GNAT traces all calls that are potentially made from - elaboration code, and puts in any missing implicit `Elaborate_All' - pragmas. The advantage of this approach is that no elaboration problems - are possible if the binder can find an elaboration order that is - consistent with these implicit `Elaborate_All' pragmas. The - disadvantage of this approach is that no such order may exist. - - If the binder does not generate any diagnostics, then it means that - it has found an elaboration order that is guaranteed to be safe. - However, the binder may still be relying on implicitly generated - `Elaborate_All' pragmas so portability to other compilers than GNAT is - not guaranteed. - - If it is important to guarantee portability, then the compilations - should use the `-gnatwl' (warn on elaboration problems) switch. This - will cause warning messages to be generated indicating the missing - `Elaborate_All' pragmas. Consider the following source program: - - with k; - package j is - m : integer := k.r; - end; - - where it is clear that there should be a pragma `Elaborate_All' for - unit `k'. An implicit pragma will be generated, and it is likely that - the binder will be able to honor it. However, it is safer to include - the pragma explicitly in the source. If this unit is compiled with the - `-gnatwl' switch, then the compiler outputs a warning: - - 1. with k; - 2. package j is - 3. m : integer := k.r; - | - >>> warning: call to "r" may raise Program_Error - >>> warning: missing pragma Elaborate_All for "k" - - 4. end; - - and these warnings can be used as a guide for supplying manually the - missing pragmas. - - This default mode is more restrictive than the Ada Reference Manual, - and it is possible to construct programs which will compile using the - dynamic model described there, but will run into a circularity using - the safer static model we have described. - - Of course any Ada compiler must be able to operate in a mode - consistent with the requirements of the Ada Reference Manual, and in - particular must have the capability of implementing the standard - dynamic model of elaboration with run-time checks. - - In GNAT, this standard mode can be achieved either by the use of the - `-gnatE' switch on the compiler (`gcc' or `gnatmake') command, or by - the use of the configuration pragma: - - pragma Elaboration_Checks (RM); - - Either approach will cause the unit affected to be compiled using the - standard dynamic run-time elaboration checks described in the Ada - Reference Manual. The static model is generally preferable, since it is - clearly safer to rely on compile and link time checks rather than - run-time checks. However, in the case of legacy code, it may be - difficult to meet the requirements of the static model. This issue is - further discussed in *Note What to Do If the Default Elaboration - Behavior Fails::. - - Note that the static model provides a strict subset of the allowed - behavior and programs of the Ada Reference Manual, so if you do adhere - to the static model and no circularities exist, then you are assured - that your program will work using the dynamic model. - -  - File: gnat_ug_unx.info, Node: Elaboration Issues for Library Tasks, Next: Mixing Elaboration Models, Prev: Default Behavior in GNAT - Ensuring Safety, Up: Elaboration Order Handling in GNAT - - Elaboration Issues for Library Tasks - ==================================== - - In this section we examine special elaboration issues that arise for - programs that declare library level tasks. - - Generally the model of execution of an Ada program is that all units - are elaborated, and then execution of the program starts. However, the - declaration of library tasks definitely does not fit this model. The - reason for this is that library tasks start as soon as they are declared - (more precisely, as soon as the statement part of the enclosing package - body is reached), that is to say before elaboration of the program is - complete. This means that if such a task calls a subprogram, or an - entry in another task, the callee may or may not be elaborated yet, and - in the standard Reference Manual model of dynamic elaboration checks, - you can even get timing dependent Program_Error exceptions, since there - can be a race between the elaboration code and the task code. - - The static model of elaboration in GNAT seeks to avoid all such - dynamic behavior, by being conservative, and the conservative approach - in this particular case is to assume that all the code in a task body - is potentially executed at elaboration time if a task is declared at - the library level. - - This can definitely result in unexpected circularities. Consider the - following example - - package Decls is - task Lib_Task is - entry Start; - end Lib_Task; - - type My_Int is new Integer; - - function Ident (M : My_Int) return My_Int; - end Decls; - - with Utils; - package body Decls is - task body Lib_Task is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task; - - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls; - - with Decls; - package Utils is - procedure Put_Val (Arg : Decls.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls.My_Int) is - begin - Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls; - procedure Main is - begin - Decls.Lib_Task.Start; - end; - - If the above example is compiled in the default static elaboration - mode, then a circularity occurs. The circularity comes from the call - `Utils.Put_Val' in the task body of `Decls.Lib_Task'. Since this call - occurs in elaboration code, we need an implicit pragma `Elaborate_All' - for `Utils'. This means that not only must the spec and body of `Utils' - be elaborated before the body of `Decls', but also the spec and body of - any unit that is `with'ed' by the body of `Utils' must also be - elaborated before the body of `Decls'. This is the transitive - implication of pragma `Elaborate_All' and it makes sense, because in - general the body of `Put_Val' might have a call to something in a - `with'ed' unit. - - In this case, the body of Utils (actually its spec) `with's' - `Decls'. Unfortunately this means that the body of `Decls' must be - elaborated before itself, in case there is a call from the body of - `Utils'. - - Here is the exact chain of events we are worrying about: - - 1. In the body of `Decls' a call is made from within the body of a - library task to a subprogram in the package `Utils'. Since this - call may occur at elaboration time (given that the task is - activated at elaboration time), we have to assume the worst, i.e. - that the call does happen at elaboration time. - - 2. This means that the body and spec of `Util' must be elaborated - before the body of `Decls' so that this call does not cause an - access before elaboration. - - 3. Within the body of `Util', specifically within the body of - `Util.Put_Val' there may be calls to any unit `with''ed by this - package. - - 4. One such `with''ed package is package `Decls', so there might be a - call to a subprogram in `Decls' in `Put_Val'. In fact there is - such a call in this example, but we would have to assume that - there was such a call even if it were not there, since we are not - supposed to write the body of `Decls' knowing what is in the body - of `Utils'; certainly in the case of the static elaboration model, - the compiler does not know what is in other bodies and must assume - the worst. - - 5. This means that the spec and body of `Decls' must also be - elaborated before we elaborate the unit containing the call, but - that unit is `Decls'! This means that the body of `Decls' must be - elaborated before itself, and that's a circularity. - - Indeed, if you add an explicit pragma Elaborate_All for `Utils' in the - body of `Decls' you will get a true Ada Reference Manual circularity - that makes the program illegal. - - In practice, we have found that problems with the static model of - elaboration in existing code often arise from library tasks, so we must - address this particular situation. - - Note that if we compile and run the program above, using the dynamic - model of elaboration (that is to say use the `-gnatE' switch), then it - compiles, binds, links, and runs, printing the expected result of 2. - Therefore in some sense the circularity here is only apparent, and we - need to capture the properties of this program that distinguish it - from other library-level tasks that have real elaboration problems. - - We have four possible answers to this question: - - * Use the dynamic model of elaboration. - - If we use the `-gnatE' switch, then as noted above, the program - works. Why is this? If we examine the task body, it is apparent - that the task cannot proceed past the `accept' statement until - after elaboration has been completed, because the corresponding - entry call comes from the main program, not earlier. This is why - the dynamic model works here. But that's really giving up on a - precise analysis, and we prefer to take this approach only if we - cannot solve the problem in any other manner. So let us examine - two ways to reorganize the program to avoid the potential - elaboration problem. - - * Split library tasks into separate packages. - - Write separate packages, so that library tasks are isolated from - other declarations as much as possible. Let us look at a variation - on the above program. - - package Decls1 is - task Lib_Task is - entry Start; - end Lib_Task; - end Decls1; - - with Utils; - package body Decls1 is - task body Lib_Task is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task; - end Decls1; - - package Decls2 is - type My_Int is new Integer; - function Ident (M : My_Int) return My_Int; - end Decls2; - - with Utils; - package body Decls2 is - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls2; - - with Decls2; - package Utils is - procedure Put_Val (Arg : Decls2.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls2.My_Int) is - begin - Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls1; - procedure Main is - begin - Decls1.Lib_Task.Start; - end; - - All we have done is to split `Decls' into two packages, one - containing the library task, and one containing everything else. - Now there is no cycle, and the program compiles, binds, links and - executes using the default static model of elaboration. - - * Declare separate task types. - - A significant part of the problem arises because of the use of the - single task declaration form. This means that the elaboration of - the task type, and the elaboration of the task itself (i.e. the - creation of the task) happen at the same time. A good rule of - style in Ada 95 is to always create explicit task types. By - following the additional step of placing task objects in separate - packages from the task type declaration, many elaboration problems - are avoided. Here is another modified example of the example - program: - - package Decls is - task type Lib_Task_Type is - entry Start; - end Lib_Task_Type; - - type My_Int is new Integer; - - function Ident (M : My_Int) return My_Int; - end Decls; - - with Utils; - package body Decls is - task body Lib_Task_Type is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task_Type; - - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls; - - with Decls; - package Utils is - procedure Put_Val (Arg : Decls.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls.My_Int) is - begin - Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls; - package Declst is - Lib_Task : Decls.Lib_Task_Type; - end Declst; - - with Declst; - procedure Main is - begin - Declst.Lib_Task.Start; - end; - - What we have done here is to replace the `task' declaration in - package `Decls' with a `task type' declaration. Then we introduce - a separate package `Declst' to contain the actual task object. - This separates the elaboration issues for the `task type' - declaration, which causes no trouble, from the elaboration issues - of the task object, which is also unproblematic, since it is now - independent of the elaboration of `Utils'. This separation of - concerns also corresponds to a generally sound engineering - principle of separating declarations from instances. This version - of the program also compiles, binds, links, and executes, - generating the expected output. - - * Use No_Entry_Calls_In_Elaboration_Code restriction. - - The previous two approaches described how a program can be - restructured to avoid the special problems caused by library task - bodies. in practice, however, such restructuring may be difficult - to apply to existing legacy code, so we must consider solutions - that do not require massive rewriting. - - Let us consider more carefully why our original sample program - works under the dynamic model of elaboration. The reason is that - the code in the task body blocks immediately on the `accept' - statement. Now of course there is nothing to prohibit elaboration - code from making entry calls (for example from another library - level task), so we cannot tell in isolation that the task will not - execute the accept statement during elaboration. - - However, in practice it is very unusual to see elaboration code - make any entry calls, and the pattern of tasks starting at - elaboration time and then immediately blocking on `accept' or - `select' statements is very common. What this means is that the - compiler is being too pessimistic when it analyzes the whole - package body as though it might be executed at elaboration time. - - If we know that the elaboration code contains no entry calls, (a - very safe assumption most of the time, that could almost be made - the default behavior), then we can compile all units of the - program under control of the following configuration pragma: - - pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); - - This pragma can be placed in the `gnat.adc' file in the usual - manner. If we take our original unmodified program and compile it - in the presence of a `gnat.adc' containing the above pragma, then - once again, we can compile, bind, link, and execute, obtaining the - expected result. In the presence of this pragma, the compiler does - not trace calls in a task body, that appear after the first - `accept' or `select' statement, and therefore does not report a - potential circularity in the original program. - - The compiler will check to the extent it can that the above - restriction is not violated, but it is not always possible to do a - complete check at compile time, so it is important to use this - pragma only if the stated restriction is in fact met, that is to - say no task receives an entry call before elaboration of all units - is completed. - - -  - File: gnat_ug_unx.info, Node: Mixing Elaboration Models, Next: What to Do If the Default Elaboration Behavior Fails, Prev: Elaboration Issues for Library Tasks, Up: Elaboration Order Handling in GNAT - - Mixing Elaboration Models - ========================= - - So far, we have assumed that the entire program is either compiled - using the dynamic model or static model, ensuring consistency. It is - possible to mix the two models, but rules have to be followed if this - mixing is done to ensure that elaboration checks are not omitted. - - The basic rule is that _a unit compiled with the static model cannot - be `with'ed' by a unit compiled with the dynamic model_. The reason for - this is that in the static model, a unit assumes that its clients - guarantee to use (the equivalent of) pragma `Elaborate_All' so that no - elaboration checks are required in inner subprograms, and this - assumption is violated if the client is compiled with dynamic checks. - - The precise rule is as follows. A unit that is compiled with dynamic - checks can only `with' a unit that meets at least one of the following - criteria: - - * The `with'ed' unit is itself compiled with dynamic elaboration - checks (that is with the `-gnatE' switch. - - * The `with'ed' unit is an internal GNAT implementation unit from - the System, Interfaces, Ada, or GNAT hierarchies. - - * The `with'ed' unit has pragma Preelaborate or pragma Pure. - - * The `with'ing' unit (that is the client) has an explicit pragma - `Elaborate_All' for the `with'ed' unit. - - - If this rule is violated, that is if a unit with dynamic elaboration - checks `with's' a unit that does not meet one of the above four - criteria, then the binder (`gnatbind') will issue a warning similar to - that in the following example: - - warning: "x.ads" has dynamic elaboration checks and with's - warning: "y.ads" which has static elaboration checks - - These warnings indicate that the rule has been violated, and that as a - result elaboration checks may be missed in the resulting executable - file. This warning may be suppressed using the `-ws' binder switch in - the usual manner. - - One useful application of this mixing rule is in the case of a - subsystem which does not itself `with' units from the remainder of the - application. In this case, the entire subsystem can be compiled with - dynamic checks to resolve a circularity in the subsystem, while - allowing the main application that uses this subsystem to be compiled - using the more reliable default static model. - -  - File: gnat_ug_unx.info, Node: What to Do If the Default Elaboration Behavior Fails, Next: Elaboration for Access-to-Subprogram Values, Prev: Mixing Elaboration Models, Up: Elaboration Order Handling in GNAT - - What to Do If the Default Elaboration Behavior Fails - ==================================================== - - If the binder cannot find an acceptable order, it outputs detailed - diagnostics. For example: - error: elaboration circularity detected - info: "proc (body)" must be elaborated before "pack (body)" - info: reason: Elaborate_All probably needed in unit "pack (body)" - info: recompile "pack (body)" with -gnatwl - info: for full details - info: "proc (body)" - info: is needed by its spec: - info: "proc (spec)" - info: which is withed by: - info: "pack (body)" - info: "pack (body)" must be elaborated before "proc (body)" - info: reason: pragma Elaborate in unit "proc (body)" - - - In this case we have a cycle that the binder cannot break. On the one - hand, there is an explicit pragma Elaborate in `proc' for `pack'. This - means that the body of `pack' must be elaborated before the body of - `proc'. On the other hand, there is elaboration code in `pack' that - calls a subprogram in `proc'. This means that for maximum safety, there - should really be a pragma Elaborate_All in `pack' for `proc' which - would require that the body of `proc' be elaborated before the body of - `pack'. Clearly both requirements cannot be satisfied. Faced with a - circularity of this kind, you have three different options. - - Fix the program - The most desirable option from the point of view of long-term - maintenance is to rearrange the program so that the elaboration - problems are avoided. One useful technique is to place the - elaboration code into separate child packages. Another is to move - some of the initialization code to explicitly called subprograms, - where the program controls the order of initialization explicitly. - Although this is the most desirable option, it may be impractical - and involve too much modification, especially in the case of - complex legacy code. - - Perform dynamic checks - If the compilations are done using the `-gnatE' (dynamic - elaboration check) switch, then GNAT behaves in a quite different - manner. Dynamic checks are generated for all calls that could - possibly result in raising an exception. With this switch, the - compiler does not generate implicit `Elaborate_All' pragmas. The - behavior then is exactly as specified in the Ada 95 Reference - Manual. The binder will generate an executable program that may - or may not raise `Program_Error', and then it is the programmer's - job to ensure that it does not raise an exception. Note that it is - important to compile all units with the switch, it cannot be used - selectively. - - Suppress checks - The drawback of dynamic checks is that they generate a significant - overhead at run time, both in space and time. If you are - absolutely sure that your program cannot raise any elaboration - exceptions, and you still want to use the dynamic elaboration - model, then you can use the configuration pragma `Suppress - (Elaboration_Checks)' to suppress all such checks. For example - this pragma could be placed in the `gnat.adc' file. - - Suppress checks selectively - When you know that certain calls in elaboration code cannot - possibly lead to an elaboration error, and the binder nevertheless - generates warnings on those calls and inserts Elaborate_All - pragmas that lead to elaboration circularities, it is possible to - remove those warnings locally and obtain a program that will bind. - Clearly this can be unsafe, and it is the responsibility of the - programmer to make sure that the resulting program has no - elaboration anomalies. The pragma `Suppress (Elaboration_Check)' - can be used with different granularity to suppress warnings and - break elaboration circularities: - - * Place the pragma that names the called subprogram in the - declarative part that contains the call. - - * Place the pragma in the declarative part, without naming an - entity. This disables warnings on all calls in the - corresponding declarative region. - - * Place the pragma in the package spec that declares the called - subprogram, and name the subprogram. This disables warnings - on all elaboration calls to that subprogram. - - * Place the pragma in the package spec that declares the called - subprogram, without naming any entity. This disables warnings - on all elaboration calls to all subprograms declared in this - spec. - - These four cases are listed in order of decreasing safety, and - therefore require increasing programmer care in their application. - Consider the following program: - - package Pack1 is - function F1 return Integer; - X1 : Integer; - end Pack1; - - package Pack2 is - function F2 return Integer; - function Pure (x : integer) return integer; - -- pragma Suppress (Elaboration_Check, On => Pure); -- (3) - -- pragma Suppress (Elaboration_Check); -- (4) - end Pack2; - - with Pack2; - package body Pack1 is - function F1 return Integer is - begin - return 100; - end F1; - Val : integer := Pack2.Pure (11); -- Elab. call (1) - begin - declare - -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1) - -- pragma Suppress(Elaboration_Check); -- (2) - begin - X1 := Pack2.F2 + 1; -- Elab. call (2) - end; - end Pack1; - - with Pack1; - package body Pack2 is - function F2 return Integer is - begin - return Pack1.F1; - end F2; - function Pure (x : integer) return integer is - begin - return x ** 3 - 3 * x; - end; - end Pack2; - - with Pack1, Ada.Text_IO; - procedure Proc3 is - begin - Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 - end Proc3; - In the absence of any pragmas, an attempt to bind this program - produces the following diagnostics: - error: elaboration circularity detected - info: "pack1 (body)" must be elaborated before "pack1 (body)" - info: reason: Elaborate_All probably needed in unit "pack1 (body)" - info: recompile "pack1 (body)" with -gnatwl for full details - info: "pack1 (body)" - info: must be elaborated along with its spec: - info: "pack1 (spec)" - info: which is withed by: - info: "pack2 (body)" - info: which must be elaborated along with its spec: - info: "pack2 (spec)" - info: which is withed by: - info: "pack1 (body)" - The sources of the circularity are the two calls to - `Pack2.Pure' and `Pack2.F2' in the body of `Pack1'. We can see - that the call to F2 is safe, even though F2 calls F1, because the - call appears after the elaboration of the body of F1. Therefore - the pragma (1) is safe, and will remove the warning on the call. - It is also possible to use pragma (2) because there are no other - potentially unsafe calls in the block. - - The call to `Pure' is safe because this function does not depend - on the state of `Pack2'. Therefore any call to this function is - safe, and it is correct to place pragma (3) in the corresponding - package spec. - - Finally, we could place pragma (4) in the spec of `Pack2' to - disable warnings on all calls to functions declared therein. Note - that this is not necessarily safe, and requires more detailed - examination of the subprogram bodies involved. In particular, a - call to `F2' requires that `F1' be already elaborated. - - It is hard to generalize on which of these four approaches should be - taken. Obviously if it is possible to fix the program so that the - default treatment works, this is preferable, but this may not always be - practical. It is certainly simple enough to use `-gnatE' but the - danger in this case is that, even if the GNAT binder finds a correct - elaboration order, it may not always do so, and certainly a binder from - another Ada compiler might not. A combination of testing and analysis - (for which the warnings generated with the `-gnatwl' switch can be - useful) must be used to ensure that the program is free of errors. One - switch that is useful in this testing is the `-p (pessimistic - elaboration order)' switch for `gnatbind'. Normally the binder tries - to find an order that has the best chance of of avoiding elaboration - problems. With this switch, the binder plays a devil's advocate role, - and tries to choose the order that has the best chance of failing. If - your program works even with this switch, then it has a better chance - of being error free, but this is still not a guarantee. - - For an example of this approach in action, consider the C-tests - (executable tests) from the ACVC suite. If these are compiled and run - with the default treatment, then all but one of them succeed without - generating any error diagnostics from the binder. However, there is one - test that fails, and this is not surprising, because the whole point of - this test is to ensure that the compiler can handle cases where it is - impossible to determine a correct order statically, and it checks that - an exception is indeed raised at run time. - - This one test must be compiled and run using the `-gnatE' switch, - and then it passes. Alternatively, the entire suite can be run using - this switch. It is never wrong to run with the dynamic elaboration - switch if your code is correct, and we assume that the C-tests are - indeed correct (it is less efficient, but efficiency is not a factor in - running the ACVC tests.) - -  - File: gnat_ug_unx.info, Node: Elaboration for Access-to-Subprogram Values, Next: Summary of Procedures for Elaboration Control, Prev: What to Do If the Default Elaboration Behavior Fails, Up: Elaboration Order Handling in GNAT - - Elaboration for Access-to-Subprogram Values - =========================================== - - The introduction of access-to-subprogram types in Ada 95 complicates - the handling of elaboration. The trouble is that it becomes impossible - to tell at compile time which procedure is being called. This means - that it is not possible for the binder to analyze the elaboration - requirements in this case. - - If at the point at which the access value is created (i.e., the - evaluation of `P'Access' for a subprogram `P'), the body of the - subprogram is known to have been elaborated, then the access value is - safe, and its use does not require a check. This may be achieved by - appropriate arrangement of the order of declarations if the subprogram - is in the current unit, or, if the subprogram is in another unit, by - using pragma `Pure', `Preelaborate', or `Elaborate_Body' on the - referenced unit. - - If the referenced body is not known to have been elaborated at the - point the access value is created, then any use of the access value - must do a dynamic check, and this dynamic check will fail and raise a - `Program_Error' exception if the body has not been elaborated yet. - GNAT will generate the necessary checks, and in addition, if the - `-gnatwl' switch is set, will generate warnings that such checks are - required. - - The use of dynamic dispatching for tagged types similarly generates - a requirement for dynamic checks, and premature calls to any primitive - operation of a tagged type before the body of the operation has been - elaborated, will result in the raising of `Program_Error'. - -  - File: gnat_ug_unx.info, Node: Summary of Procedures for Elaboration Control, Next: Other Elaboration Order Considerations, Prev: Elaboration for Access-to-Subprogram Values, Up: Elaboration Order Handling in GNAT - - Summary of Procedures for Elaboration Control - ============================================= - - First, compile your program with the default options, using none of the - special elaboration control switches. If the binder successfully binds - your program, then you can be confident that, apart from issues raised - by the use of access-to-subprogram types and dynamic dispatching, the - program is free of elaboration errors. If it is important that the - program be portable, then use the `-gnatwl' switch to generate warnings - about missing `Elaborate_All' pragmas, and supply the missing pragmas. - - If the program fails to bind using the default static elaboration - handling, then you can fix the program to eliminate the binder message, - or recompile the entire program with the `-gnatE' switch to generate - dynamic elaboration checks, and, if you are sure there really are no - elaboration problems, use a global pragma `Suppress - (Elaboration_Checks)'. - -  - File: gnat_ug_unx.info, Node: Other Elaboration Order Considerations, Prev: Summary of Procedures for Elaboration Control, Up: Elaboration Order Handling in GNAT - - Other Elaboration Order Considerations - ====================================== - - This section has been entirely concerned with the issue of finding a - valid elaboration order, as defined by the Ada Reference Manual. In a - case where several elaboration orders are valid, the task is to find one - of the possible valid elaboration orders (and the static model in GNAT - will ensure that this is achieved). - - The purpose of the elaboration rules in the Ada Reference Manual is - to make sure that no entity is accessed before it has been elaborated. - For a subprogram, this means that the spec and body must have been - elaborated before the subprogram is called. For an object, this means - that the object must have been elaborated before its value is read or - written. A violation of either of these two requirements is an access - before elaboration order, and this section has been all about avoiding - such errors. - - In the case where more than one order of elaboration is possible, in - the sense that access before elaboration errors are avoided, then any - one of the orders is "correct" in the sense that it meets the - requirements of the Ada Reference Manual, and no such error occurs. - - However, it may be the case for a given program, that there are - constraints on the order of elaboration that come not from consideration - of avoiding elaboration errors, but rather from extra-lingual logic - requirements. Consider this example: - - with Init_Constants; - package Constants is - X : Integer := 0; - Y : Integer := 0; - end Constants; - - package Init_Constants is - procedure Calc; - end Init_Constants; - - with Constants; - package body Init_Constants is - procedure Calc is begin null; end; - begin - Constants.X := 3; - Constants.Y := 4; - end Init_Constants; - - with Constants; - package Calc is - Z : Integer := Constants.X + Constants.Y; - end Calc; - - with Calc; - with Text_IO; use Text_IO; - procedure Main is - begin - Put_Line (Calc.Z'Img); - end Main; - - In this example, there is more than one valid order of elaboration. For - example both the following are correct orders: - - Init_Constants spec - Constants spec - Calc spec - Main body - Init_Constants body - - and - - Init_Constants spec - Init_Constants body - Constants spec - Calc spec - Main body - - There is no language rule to prefer one or the other, both are correct - from an order of elaboration point of view. But the programmatic effects - of the two orders are very different. In the first, the elaboration - routine of `Calc' initializes `Z' to zero, and then the main program - runs with this value of zero. But in the second order, the elaboration - routine of `Calc' runs after the body of Init_Constants has set `X' and - `Y' and thus `Z' is set to 7 before `Main' runs. - - One could perhaps by applying pretty clever non-artificial - intelligence to the situation guess that it is more likely that the - second order of elaboration is the one desired, but there is no formal - linguistic reason to prefer one over the other. In fact in this - particular case, GNAT will prefer the second order, because of the rule - that bodies are elaborated as soon as possible, but it's just luck that - this is what was wanted (if indeed the second order was preferred). - - If the program cares about the order of elaboration routines in a - case like this, it is important to specify the order required. In this - particular case, that could have been achieved by adding to the spec of - Calc: - - pragma Elaborate_All (Constants); - - which requires that the body (if any) and spec of `Constants', as well - as the body and spec of any unit `with''ed by `Constants' be elaborated - before `Calc' is elaborated. - - Clearly no automatic method can always guess which alternative you - require, and if you are working with legacy code that had constraints - of this kind which were not properly specified by adding `Elaborate' or - `Elaborate_All' pragmas, then indeed it is possible that two different - compilers can choose different orders. - - The `gnatbind' `-p' switch may be useful in smoking out problems. - This switch causes bodies to be elaborated as late as possible instead - of as early as possible. In the example above, it would have forced the - choice of the first elaboration order. If you get different results - when using this switch, and particularly if one set of results is right, - and one is wrong as far as you are concerned, it shows that you have - some missing `Elaborate' pragmas. For the example above, we have the - following output: - - gnatmake -f -q main - main - 7 - gnatmake -f -q main -bargs -p - main - 0 - - It is of course quite unlikely that both these results are correct, so - it is up to you in a case like this to investigate the source of the - difference, by looking at the two elaboration orders that are chosen, - and figuring out which is correct, and then adding the necessary - `Elaborate_All' pragmas to ensure the desired order. - -  - File: gnat_ug_unx.info, Node: The Cross-Referencing Tools gnatxref and gnatfind, Next: File Name Krunching Using gnatkr, Prev: Elaboration Order Handling in GNAT, Up: Top - - The Cross-Referencing Tools `gnatxref' and `gnatfind' - ***************************************************** - - The compiler generates cross-referencing information (unless you set - the `-gnatx' switch), which are saved in the `.ali' files. This - information indicates where in the source each entity is declared and - referenced. Note that entities in package Standard are not included, but - entities in all other predefined units are included in the output. - - Before using any of these two tools, you need to compile - successfully your application, so that GNAT gets a chance to generate - the cross-referencing information. - - The two tools `gnatxref' and `gnatfind' take advantage of this - information to provide the user with the capability to easily locate the - declaration and references to an entity. These tools are quite similar, - the difference being that `gnatfind' is intended for locating - definitions and/or references to a specified entity or entities, whereas - `gnatxref' is oriented to generating a full report of all - cross-references. - - To use these tools, you must not compile your application using the - `-gnatx' switch on the `gnatmake' command line (*note (gnat_ug)The GNAT - Make Program gnatmake::). Otherwise, cross-referencing information will - not be generated. - - * Menu: - - * gnatxref Switches:: - * gnatfind Switches:: - * Project Files for gnatxref and gnatfind:: - * Regular Expressions in gnatfind and gnatxref:: - * Examples of gnatxref Usage:: - * Examples of gnatfind Usage:: - -  - File: gnat_ug_unx.info, Node: gnatxref Switches, Next: gnatfind Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - `gnatxref' Switches - =================== - - The command lines for `gnatxref' is: - $ gnatxref [switches] sourcefile1 [sourcefile2 ...] - - where - - `sourcefile1, sourcefile2' - identifies the source files for which a report is to be generated. - The 'with'ed units will be processed too. You must provide at - least one file. - - These file names are considered to be regular expressions, so for - instance specifying 'source*.adb' is the same as giving every file - in the current directory whose name starts with 'source' and whose - extension is 'adb'. - - The switches can be : - `-a' - If this switch is present, `gnatfind' and `gnatxref' will parse - the read-only files found in the library search path. Otherwise, - these files will be ignored. This option can be used to protect - Gnat sources or your own libraries from being parsed, thus making - `gnatfind' and `gnatxref' much faster, and their output much - smaller. - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source file search is undertaken is the same as for - `gnatmake'. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is the same as - for `gnatmake'. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-d' - If this switch is set `gnatxref' will output the parent type - reference for each matching derived types. - - `-f' - If this switch is set, the output file names will be preceded by - their directory (if the file was found in the search path). If - this switch is not set, the directory will not be printed. - - `-g' - If this switch is set, information is output only for library-level - entities, ignoring local entities. The use of this switch may - accelerate `gnatfind' and `gnatxref'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-pFILE' - Specify a project file to use *Note Project Files::. By default, - `gnatxref' and `gnatfind' will try to locate a project file in the - current directory. - - If a project file is either specified or found by the tools, then - the content of the source directory and object directory lines are - added as if they had been specified respectively by `-aI' and - `-aO'. - - `-u' - Output only unused symbols. This may be really useful if you give - your main compilation unit on the command line, as `gnatxref' will - then display every unused entity and 'with'ed package. - - `-v' - Instead of producing the default output, `gnatxref' will generate a - `tags' file that can be used by vi. For examples how to use this - feature, see *Note Examples of gnatxref Usage::. The tags file is - output to the standard output, thus you will have to redirect it - to a file. - - All these switches may be in any order on the command line, and may - even appear after the file names. They need not be separated by spaces, - thus you can say `gnatxref -ag' instead of `gnatxref -a -g'. - -  - File: gnat_ug_unx.info, Node: gnatfind Switches, Next: Project Files for gnatxref and gnatfind, Prev: gnatxref Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - `gnatfind' Switches - =================== - - The command line for `gnatfind' is: - - $ gnatfind [switches] pattern[:sourcefile[:line[:column]]] - [file1 file2 ...] - - where - - `pattern' - An entity will be output only if it matches the regular expression - found in `pattern', see *Note Regular Expressions in gnatfind and - gnatxref::. - - Omitting the pattern is equivalent to specifying `*', which will - match any entity. Note that if you do not provide a pattern, you - have to provide both a sourcefile and a line. - - Entity names are given in Latin-1, with uppercase/lowercase - equivalence for matching purposes. At the current time there is no - support for 8-bit codes other than Latin-1, or for wide characters - in identifiers. - - `sourcefile' - `gnatfind' will look for references, bodies or declarations of - symbols referenced in `sourcefile', at line `line' and column - `column'. See *note Examples of gnatfind Usage:: for syntax - examples. - - `line' - is a decimal integer identifying the line number containing the - reference to the entity (or entities) to be located. - - `column' - is a decimal integer identifying the exact location on the line of - the first character of the identifier for the entity reference. - Columns are numbered from 1. - - `file1 file2 ...' - The search will be restricted to these files. If none are given, - then the search will be done for every library file in the search - path. These file must appear only after the pattern or sourcefile. - - These file names are considered to be regular expressions, so for - instance specifying 'source*.adb' is the same as giving every file - in the current directory whose name starts with 'source' and whose - extension is 'adb'. - - Not that if you specify at least one file in this part, `gnatfind' - may sometimes not be able to find the body of the subprograms... - - At least one of 'sourcefile' or 'pattern' has to be present on the - command line. - - The following switches are available: - `-a' - If this switch is present, `gnatfind' and `gnatxref' will parse - the read-only files found in the library search path. Otherwise, - these files will be ignored. This option can be used to protect - Gnat sources or your own libraries from being parsed, thus making - `gnatfind' and `gnatxref' much faster, and their output much - smaller. - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source file search is undertaken is the same as for - `gnatmake'. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is the same as - for `gnatmake'. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-d' - If this switch is set, then `gnatfind' will output the parent type - reference for each matching derived types. - - `-e' - By default, `gnatfind' accept the simple regular expression set for - `pattern'. If this switch is set, then the pattern will be - considered as full Unix-style regular expression. - - `-f' - If this switch is set, the output file names will be preceded by - their directory (if the file was found in the search path). If - this switch is not set, the directory will not be printed. - - `-g' - If this switch is set, information is output only for library-level - entities, ignoring local entities. The use of this switch may - accelerate `gnatfind' and `gnatxref'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-pFILE' - Specify a project file (*note Project Files::) to use. By - default, `gnatxref' and `gnatfind' will try to locate a project - file in the current directory. - - If a project file is either specified or found by the tools, then - the content of the source directory and object directory lines are - added as if they had been specified respectively by `-aI' and - `-aO'. - - `-r' - By default, `gnatfind' will output only the information about the - declaration, body or type completion of the entities. If this - switch is set, the `gnatfind' will locate every reference to the - entities in the files specified on the command line (or in every - file in the search path if no file is given on the command line). - - `-s' - If this switch is set, then `gnatfind' will output the content of - the Ada source file lines were the entity was found. - - `-t' - If this switch is set, then `gnatfind' will output the type - hierarchy for the specified type. It act like -d option but - recursively from parent type to parent type. When this switch is - set it is not possible to specify more than one file. - - All these switches may be in any order on the command line, and may - even appear after the file names. They need not be separated by spaces, - thus you can say `gnatxref -ag' instead of `gnatxref -a -g'. - - As stated previously, gnatfind will search in every directory in the - search path. You can force it to look only in the current directory if - you specify `*' at the end of the command line. - -  - File: gnat_ug_unx.info, Node: Project Files for gnatxref and gnatfind, Next: Regular Expressions in gnatfind and gnatxref, Prev: gnatfind Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Project Files for `gnatxref' and `gnatfind' - =========================================== - - Project files allow a programmer to specify how to compile its - application, where to find sources,... These files are used primarily by - the Glide Ada mode, but they can also be used by the two tools - `gnatxref' and `gnatfind'. - - A project file name must end with `.adp'. If a single one is present - in the current directory, then `gnatxref' and `gnatfind' will extract - the information from it. If multiple project files are found, none of - them is read, and you have to use the `-p' switch to specify the one - you want to use. - - The following lines can be included, even though most of them have - default values which can be used in most cases. The lines can be - entered in any order in the file. Except for `src_dir' and `obj_dir', - you can only have one instance of each line. If you have multiple - instances, only the last one is taken into account. - - `src_dir=DIR [default: "./"]' - specifies a directory where to look for source files. Multiple - src_dir lines can be specified and they will be searched in the - order they are specified. - - `obj_dir=DIR [default: "./"]' - specifies a directory where to look for object and library files. - Multiple obj_dir lines can be specified and they will be searched - in the order they are specified - - `comp_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${comp_opt}' notation. This is intended to store the default - switches given to `gnatmake' and `gcc'. - - `bind_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${bind_opt}' notation. This is intended to store the default - switches given to `gnatbind'. - - `link_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${link_opt}' notation. This is intended to store the default - switches given to `gnatlink'. - - `main=EXECUTABLE [default: ""]' - specifies the name of the executable for the application. This - variable can be referred to in the following lines by using the - `${main}' notation. - - `comp_cmd=COMMAND [default: "gcc -c -I${src_dir} -g -gnatq"]' - specifies the command used to compile a single file in the - application. - - `make_cmd=COMMAND [default: "gnatmake ${main} -aI${src_dir} -aO${obj_dir} -g -gnatq -cargs ${comp_opt} -bargs ${bind_opt} -largs ${link_opt}"]' - specifies the command used to recompile the whole application. - - `run_cmd=COMMAND [default: "${main}"]' - specifies the command used to run the application. - - `debug_cmd=COMMAND [default: "gdb ${main}"]' - specifies the command used to debug the application - - `gnatxref' and `gnatfind' only take into account the `src_dir' and - `obj_dir' lines, and ignore the others. - -  - File: gnat_ug_unx.info, Node: Regular Expressions in gnatfind and gnatxref, Next: Examples of gnatxref Usage, Prev: Project Files for gnatxref and gnatfind, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Regular Expressions in `gnatfind' and `gnatxref' - ================================================ - - As specified in the section about `gnatfind', the pattern can be a - regular expression. Actually, there are to set of regular expressions - which are recognized by the program : - - `globbing patterns' - These are the most usual regular expression. They are the same - that you generally used in a Unix shell command line, or in a DOS - session. - - Here is a more formal grammar : - regexp ::= term - term ::= elmt -- matches elmt - term ::= elmt elmt -- concatenation (elmt then elmt) - term ::= * -- any string of 0 or more characters - term ::= ? -- matches any character - term ::= [char {char}] -- matches any character listed - term ::= [char - char] -- matches any character in range - - `full regular expression' - The second set of regular expressions is much more powerful. This - is the type of regular expressions recognized by utilities such a - `grep'. - - The following is the form of a regular expression, expressed in Ada - reference manual style BNF is as follows - - regexp ::= term {| term} -- alternation (term or term ...) - - term ::= item {item} -- concatenation (item then item) - - item ::= elmt -- match elmt - item ::= elmt * -- zero or more elmt's - item ::= elmt + -- one or more elmt's - item ::= elmt ? -- matches elmt or nothing - elmt ::= nschar -- matches given character - elmt ::= [nschar {nschar}] -- matches any character listed - elmt ::= [^ nschar {nschar}] -- matches any character not listed - elmt ::= [char - char] -- matches chars in given range - elmt ::= \ char -- matches given character - elmt ::= . -- matches any single character - elmt ::= ( regexp ) -- parens used for grouping - - char ::= any character, including special characters - nschar ::= any character except ()[].*+?^ - - Following are a few examples : - - `abcde|fghi' - will match any of the two strings 'abcde' and 'fghi'. - - `abc*d' - will match any string like 'abd', 'abcd', 'abccd', 'abcccd', - and so on - - `[a-z]+' - will match any string which has only lowercase characters in - it (and at least one character - -  - File: gnat_ug_unx.info, Node: Examples of gnatxref Usage, Next: Examples of gnatfind Usage, Prev: Regular Expressions in gnatfind and gnatxref, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Examples of `gnatxref' Usage - ============================ - - General Usage - ------------- - - For the following examples, we will consider the following units : - - main.ads: - 1: with Bar; - 2: package Main is - 3: procedure Foo (B : in Integer); - 4: C : Integer; - 5: private - 6: D : Integer; - 7: end Main; - - main.adb: - 1: package body Main is - 2: procedure Foo (B : in Integer) is - 3: begin - 4: C := B; - 5: D := B; - 6: Bar.Print (B); - 7: Bar.Print (C); - 8: end Foo; - 9: end Main; - - bar.ads: - 1: package Bar is - 2: procedure Print (B : Integer); - 3: end bar; - - The first thing to do is to recompile your application (for - instance, in that case just by doing a `gnatmake main', so that - GNAT generates the cross-referencing information. You can then - issue any of the following commands: - - `gnatxref main.adb' - `gnatxref' generates cross-reference information for main.adb and - every unit 'with'ed by main.adb. - - The output would be: - B Type: Integer - Decl: bar.ads 2:22 - B Type: Integer - Decl: main.ads 3:20 - Body: main.adb 2:20 - Ref: main.adb 4:13 5:13 6:19 - Bar Type: Unit - Decl: bar.ads 1:9 - Ref: main.adb 6:8 7:8 - main.ads 1:6 - C Type: Integer - Decl: main.ads 4:5 - Modi: main.adb 4:8 - Ref: main.adb 7:19 - D Type: Integer - Decl: main.ads 6:5 - Modi: main.adb 5:8 - Foo Type: Unit - Decl: main.ads 3:15 - Body: main.adb 2:15 - Main Type: Unit - Decl: main.ads 2:9 - Body: main.adb 1:14 - Print Type: Unit - Decl: bar.ads 2:15 - Ref: main.adb 6:12 7:12 - - that is the entity `Main' is declared in main.ads, line 2, column - 9, its body is in main.adb, line 1, column 14 and is not - referenced any where. - - The entity `Print' is declared in bar.ads, line 2, column 15 and it - it referenced in main.adb, line 6 column 12 and line 7 column 12. - - `gnatxref package1.adb package2.ads' - `gnatxref' will generates cross-reference information for - package1.adb, package2.ads and any other package 'with'ed by any - of these. - - Using gnatxref with vi - ---------------------- - - `gnatxref' can generate a tags file output, which can be used - directly from `vi'. Note that the standard version of `vi' will not - work properly with overloaded symbols. Consider using another free - implementation of `vi', such as `vim'. - - $ gnatxref -v gnatfind.adb > tags - - will generate the tags file for `gnatfind' itself (if the sources are - in the search path!). - - From `vi', you can then use the command `:tag entity' (replacing - entity by whatever you are looking for), and vi will display a new file - with the corresponding declaration of entity. - -  - File: gnat_ug_unx.info, Node: Examples of gnatfind Usage, Prev: Examples of gnatxref Usage, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Examples of `gnatfind' Usage - ============================ - - `gnatfind -f xyz:main.adb' - Find declarations for all entities xyz referenced at least once in - main.adb. The references are search in every library file in the - search path. - - The directories will be printed as well (as the `-f' switch is set) - - The output will look like: - directory/main.ads:106:14: xyz <= declaration - directory/main.adb:24:10: xyz <= body - directory/foo.ads:45:23: xyz <= declaration - - that is to say, one of the entities xyz found in main.adb is - declared at line 12 of main.ads (and its body is in main.adb), and - another one is declared at line 45 of foo.ads - - `gnatfind -fs xyz:main.adb' - This is the same command as the previous one, instead `gnatfind' - will display the content of the Ada source file lines. - - The output will look like: - - directory/main.ads:106:14: xyz <= declaration - procedure xyz; - directory/main.adb:24:10: xyz <= body - procedure xyz is - directory/foo.ads:45:23: xyz <= declaration - xyz : Integer; - - This can make it easier to find exactly the location your are - looking for. - - `gnatfind -r "*x*":main.ads:123 foo.adb' - Find references to all entities containing an x that are - referenced on line 123 of main.ads. The references will be - searched only in main.adb and foo.adb. - - `gnatfind main.ads:123' - Find declarations and bodies for all entities that are referenced - on line 123 of main.ads. - - This is the same as `gnatfind "*":main.adb:123'. - - `gnatfind mydir/main.adb:123:45' - Find the declaration for the entity referenced at column 45 in - line 123 of file main.adb in directory mydir. Note that it is - usual to omit the identifier name when the column is given, since - the column position identifies a unique reference. - - The column has to be the beginning of the identifier, and should - not point to any character in the middle of the identifier. - -  - File: gnat_ug_unx.info, Node: File Name Krunching Using gnatkr, Next: Preprocessing Using gnatprep, Prev: The Cross-Referencing Tools gnatxref and gnatfind, Up: Top - - File Name Krunching Using `gnatkr' - ********************************** - - This chapter discusses the method used by the compiler to shorten the - default file names chosen for Ada units so that they do not exceed the - maximum length permitted. It also describes the `gnatkr' utility that - can be used to determine the result of applying this shortening. - - * Menu: - - * About gnatkr:: - * Using gnatkr:: - * Krunching Method:: - * Examples of gnatkr Usage:: - -  - File: gnat_ug_unx.info, Node: About gnatkr, Next: Using gnatkr, Up: File Name Krunching Using gnatkr - - About `gnatkr' - ============== - - The default file naming rule in GNAT is that the file name must be - derived from the unit name. The exact default rule is as follows: - * Take the unit name and replace all dots by hyphens. - - * If such a replacement occurs in the second character position of a - name, and the first character is a, g, s, or i then replace the - dot by the character ~ (tilde) instead of a minus. - The reason for this exception is to avoid clashes with the standard - names for children of System, Ada, Interfaces, and GNAT, which use the - prefixes s- a- i- and g- respectively. - - The `-gnatkNN' switch of the compiler activates a "krunching" - circuit that limits file names to nn characters (where nn is a decimal - integer). For example, using OpenVMS, where the maximum file name - length is 39, the value of nn is usually set to 39, but if you want to - generate a set of files that would be usable if ported to a system with - some different maximum file length, then a different value can be - specified. The default value of 39 for OpenVMS need not be specified. - - The `gnatkr' utility can be used to determine the krunched name for - a given file, when krunched to a specified maximum length. - -  - File: gnat_ug_unx.info, Node: Using gnatkr, Next: Krunching Method, Prev: About gnatkr, Up: File Name Krunching Using gnatkr - - Using `gnatkr' - ============== - - The `gnatkr' command has the form - - $ gnatkr NAME [LENGTH] - - NAME can be an Ada name with dots or the GNAT name of the unit, where - the dots representing child units or subunit are replaced by hyphens. - The only confusion arises if a name ends in `.ads' or `.adb'. `gnatkr' - takes this to be an extension if there are no other dots in the name - and the whole name is in lowercase. - - LENGTH represents the length of the krunched name. The default when - no argument is given is 8 characters. A length of zero stands for - unlimited, in other words do not chop except for system files which are - always 8. - - The output is the krunched name. The output has an extension only if the - original argument was a file name with an extension. - -  - File: gnat_ug_unx.info, Node: Krunching Method, Next: Examples of gnatkr Usage, Prev: Using gnatkr, Up: File Name Krunching Using gnatkr - - Krunching Method - ================ - - The initial file name is determined by the name of the unit that the - file contains. The name is formed by taking the full expanded name of - the unit and replacing the separating dots with hyphens and using - lowercase for all letters, except that a hyphen in the second character - position is replaced by a tilde if the first character is a, i, g, or s. - The extension is `.ads' for a specification and `.adb' for a body. - Krunching does not affect the extension, but the file name is shortened - to the specified length by following these rules: - - * The name is divided into segments separated by hyphens, tildes or - underscores and all hyphens, tildes, and underscores are - eliminated. If this leaves the name short enough, we are done. - - * If the name is too long, the longest segment is located (left-most - if there are two of equal length), and shortened by dropping its - last character. This is repeated until the name is short enough. - - As an example, consider the krunching of - `our-strings-wide_fixed.adb' to fit the name into 8 characters as - required by some operating systems. - - our-strings-wide_fixed 22 - our strings wide fixed 19 - our string wide fixed 18 - our strin wide fixed 17 - our stri wide fixed 16 - our stri wide fixe 15 - our str wide fixe 14 - our str wid fixe 13 - our str wid fix 12 - ou str wid fix 11 - ou st wid fix 10 - ou st wi fix 9 - ou st wi fi 8 - Final file name: oustwifi.adb - - * The file names for all predefined units are always krunched to - eight characters. The krunching of these predefined units uses the - following special prefix replacements: - - `ada-' - replaced by `a-' - - `gnat-' - replaced by `g-' - - `interfaces-' - replaced by `i-' - - `system-' - replaced by `s-' - - These system files have a hyphen in the second character position. - That is why normal user files replace such a character with a - tilde, to avoid confusion with system file names. - - As an example of this special rule, consider - `ada-strings-wide_fixed.adb', which gets krunched as follows: - - ada-strings-wide_fixed 22 - a- strings wide fixed 18 - a- string wide fixed 17 - a- strin wide fixed 16 - a- stri wide fixed 15 - a- stri wide fixe 14 - a- str wide fixe 13 - a- str wid fixe 12 - a- str wid fix 11 - a- st wid fix 10 - a- st wi fix 9 - a- st wi fi 8 - Final file name: a-stwifi.adb - - Of course no file shortening algorithm can guarantee uniqueness over - all possible unit names, and if file name krunching is used then it is - your responsibility to ensure that no name clashes occur. The utility - program `gnatkr' is supplied for conveniently determining the krunched - name of a file. - -  - File: gnat_ug_unx.info, Node: Examples of gnatkr Usage, Prev: Krunching Method, Up: File Name Krunching Using gnatkr - - Examples of `gnatkr' Usage - ========================== - - $ gnatkr very_long_unit_name.ads --> velounna.ads - $ gnatkr grandparent-parent-child.ads --> grparchi.ads - $ gnatkr Grandparent.Parent.Child --> grparchi - $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads - $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads - -  - File: gnat_ug_unx.info, Node: Preprocessing Using gnatprep, Next: The GNAT Library Browser gnatls, Prev: File Name Krunching Using gnatkr, Up: Top - - Preprocessing Using `gnatprep' - ****************************** - - The `gnatprep' utility provides a simple preprocessing capability for - Ada programs. It is designed for use with GNAT, but is not dependent - on any special features of GNAT. - - * Menu: - - * Using gnatprep:: - * Switches for gnatprep:: - * Form of Definitions File:: - * Form of Input Text for gnatprep:: - -  - File: gnat_ug_unx.info, Node: Using gnatprep, Next: Switches for gnatprep, Up: Preprocessing Using gnatprep - - Using `gnatprep' - ================ - - To call `gnatprep' use - - $ gnatprep [-bcrsu] [-Dsymbol=value] infile outfile [deffile] - - where - `infile' - is the full name of the input file, which is an Ada source file - containing preprocessor directives. - - `outfile' - is the full name of the output file, which is an Ada source in - standard Ada form. When used with GNAT, this file name will - normally have an ads or adb suffix. - - `deffile' - is the full name of a text file containing definitions of symbols - to be referenced by the preprocessor. This argument is optional, - and can be replaced by the use of the `-D' switch. - - `switches' - is an optional sequence of switches as described in the next - section. - -  - File: gnat_ug_unx.info, Node: Switches for gnatprep, Next: Form of Definitions File, Prev: Using gnatprep, Up: Preprocessing Using gnatprep - - Switches for `gnatprep' - ======================= - - `-b' - Causes both preprocessor lines and the lines deleted by - preprocessing to be replaced by blank lines in the output source - file, preserving line numbers in the output file. - - `-c' - Causes both preprocessor lines and the lines deleted by - preprocessing to be retained in the output source as comments - marked with the special string "-! ". This option will result in - line numbers being preserved in the output file. - - `-Dsymbol=value' - Defines a new symbol, associated with value. If no value is given - on the command line, then symbol is considered to be `True'. This - switch can be used in place of a definition file. - - `-r' - Causes a `Source_Reference' pragma to be generated that references - the original input file, so that error messages will use the file - name of this original file. The use of this switch implies that - preprocessor lines are not to be removed from the file, so its use - will force `-b' mode if `-c' has not been specified explicitly. - - Note that if the file to be preprocessed contains multiple units, - then it will be necessary to `gnatchop' the output file from - `gnatprep'. If a `Source_Reference' pragma is present in the - preprocessed file, it will be respected by `gnatchop -r' so that - the final chopped files will correctly refer to the original input - source file for `gnatprep'. - - `-s' - Causes a sorted list of symbol names and values to be listed on - the standard output file. - - `-u' - Causes undefined symbols to be treated as having the value FALSE - in the context of a preprocessor test. In the absence of this - option, an undefined symbol in a `#if' or `#elsif' test will be - treated as an error. - - Note: if neither `-b' nor `-c' is present, then preprocessor lines and - deleted lines are completely removed from the output, unless -r is - specified, in which case -b is assumed. - -  - File: gnat_ug_unx.info, Node: Form of Definitions File, Next: Form of Input Text for gnatprep, Prev: Switches for gnatprep, Up: Preprocessing Using gnatprep - - Form of Definitions File - ======================== - - The definitions file contains lines of the form - - symbol := value - - where symbol is an identifier, following normal Ada (case-insensitive) - rules for its syntax, and value is one of the following: - - * Empty, corresponding to a null substitution - - * A string literal using normal Ada syntax - - * Any sequence of characters from the set (letters, digits, period, - underline). - - Comment lines may also appear in the definitions file, starting with - the usual `--', and comments may be added to the definitions lines. - -  - File: gnat_ug_unx.info, Node: Form of Input Text for gnatprep, Prev: Form of Definitions File, Up: Preprocessing Using gnatprep - - Form of Input Text for `gnatprep' - ================================= - - The input text may contain preprocessor conditional inclusion lines, as - well as general symbol substitution sequences. - - The preprocessor conditional inclusion commands have the form - - #if expression [then] - lines - #elsif expression [then] - lines - #elsif expression [then] - lines - ... - #else - lines - #end if; - - In this example, expression is defined by the following grammar: - expression ::= - expression ::= = "" - expression ::= = - expression ::= 'Defined - expression ::= not expression - expression ::= expression and expression - expression ::= expression or expression - expression ::= expression and then expression - expression ::= expression or else expression - expression ::= ( expression ) - - For the first test (expression ::= ) the symbol must have - either the value true or false, that is to say the right-hand of the - symbol definition must be one of the (case-insensitive) literals `True' - or `False'. If the value is true, then the corresponding lines are - included, and if the value is false, they are excluded. - - The test (expression ::= `'Defined') is true only if the - symbol has been defined in the definition file or by a `-D' switch on - the command line. Otherwise, the test is false. - - The equality tests are case insensitive, as are all the preprocessor - lines. - - If the symbol referenced is not defined in the symbol definitions - file, then the effect depends on whether or not switch `-u' is - specified. If so, then the symbol is treated as if it had the value - false and the test fails. If this switch is not specified, then it is - an error to reference an undefined symbol. It is also an error to - reference a symbol that is defined with a value other than `True' or - `False'. - - The use of the `not' operator inverts the sense of this logical - test, so that the lines are included only if the symbol is not defined. - The `then' keyword is optional as shown - - The `#' must be the first non-blank character on a line, but - otherwise the format is free form. Spaces or tabs may appear between - the `#' and the keyword. The keywords and the symbols are case - insensitive as in normal Ada code. Comments may be used on a - preprocessor line, but other than that, no other tokens may appear on a - preprocessor line. Any number of `elsif' clauses can be present, - including none at all. The `else' is optional, as in Ada. - - The `#' marking the start of a preprocessor line must be the first - non-blank character on the line, i.e. it must be preceded only by - spaces or horizontal tabs. - - Symbol substitution outside of preprocessor lines is obtained by - using the sequence - - $symbol - - anywhere within a source line, except in a comment or within a string - literal. The identifier following the `$' must match one of the symbols - defined in the symbol definition file, and the result is to substitute - the value of the symbol in place of `$symbol' in the output file. - - Note that although the substitution of strings within a string - literal is not possible, it is possible to have a symbol whose defined - value is a string literal. So instead of setting XYZ to `hello' and - writing: - - Header : String := "$XYZ"; - - you should set XYZ to `"hello"' and write: - - Header : String := $XYZ; - - and then the substitution will occur as desired. - -  - File: gnat_ug_unx.info, Node: The GNAT Library Browser gnatls, Next: GNAT and Libraries, Prev: Preprocessing Using gnatprep, Up: Top - - The GNAT Library Browser `gnatls' - ********************************* - - `gnatls' is a tool that outputs information about compiled units. It - gives the relationship between objects, unit names and source files. It - can also be used to check the source dependencies of a unit as well as - various characteristics. - - * Menu: - - * Running gnatls:: - * Switches for gnatls:: - * Examples of gnatls Usage:: - -  - File: gnat_ug_unx.info, Node: Running gnatls, Next: Switches for gnatls, Up: The GNAT Library Browser gnatls - - Running `gnatls' - ================ - - The `gnatls' command has the form - - $ gnatls switches OBJECT_OR_ALI_FILE - - The main argument is the list of object or `ali' files (*note The Ada - Library Information Files::) for which information is requested. - - In normal mode, without additional option, `gnatls' produces a - four-column listing. Each line represents information for a specific - object. The first column gives the full path of the object, the second - column gives the name of the principal unit in this object, the third - column gives the status of the source and the fourth column gives the - full path of the source representing this unit. Here is a simple - example of use: - - $ gnatls *.o - ./demo1.o demo1 DIF demo1.adb - ./demo2.o demo2 OK demo2.adb - ./hello.o h1 OK hello.adb - ./instr-child.o instr.child MOK instr-child.adb - ./instr.o instr OK instr.adb - ./tef.o tef DIF tef.adb - ./text_io_example.o text_io_example OK text_io_example.adb - ./tgef.o tgef DIF tgef.adb - - The first line can be interpreted as follows: the main unit which is - contained in object file `demo1.o' is demo1, whose main source is in - `demo1.adb'. Furthermore, the version of the source used for the - compilation of demo1 has been modified (DIF). Each source file has a - status qualifier which can be: - - `OK (unchanged)' - The version of the source file used for the compilation of the - specified unit corresponds exactly to the actual source file. - - `MOK (slightly modified)' - The version of the source file used for the compilation of the - specified unit differs from the actual source file but not enough - to require recompilation. If you use gnatmake with the qualifier - `-m (minimal recompilation)', a file marked MOK will not be - recompiled. - - `DIF (modified)' - No version of the source found on the path corresponds to the - source used to build this object. - - `??? (file not found)' - No source file was found for this unit. - - `HID (hidden, unchanged version not first on PATH)' - The version of the source that corresponds exactly to the source - used for compilation has been found on the path but it is hidden - by another version of the same source that has been modified. - -  - File: gnat_ug_unx.info, Node: Switches for gnatls, Next: Examples of gnatls Usage, Prev: Running gnatls, Up: The GNAT Library Browser gnatls - - Switches for `gnatls' - ===================== - - `gnatls' recognizes the following switches: - - `-a' - Consider all units, including those of the predefined Ada library. - Especially useful with `-d'. - - `-d' - List sources from which specified units depend on. - - `-h' - Output the list of options. - - `-o' - Only output information about object files. - - `-s' - Only output information about source files. - - `-u' - Only output information about compilation units. - - `-aODIR' - `-aIDIR' - `-IDIR' - `-I-' - `-nostdinc' - Source path manipulation. Same meaning as the equivalent - `gnatmake' flags (see *Note Switches for gnatmake::). - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-v' - Verbose mode. Output the complete source and object paths. Do not - use the default column layout but instead use long format giving - as much as information possible on each requested units, including - special characteristics such as: - - `Preelaborable' - The unit is preelaborable in the Ada 95 sense. - - `No_Elab_Code' - No elaboration code has been produced by the compiler for - this unit. - - `Pure' - The unit is pure in the Ada 95 sense. - - `Elaborate_Body' - The unit contains a pragma Elaborate_Body. - - `Remote_Types' - The unit contains a pragma Remote_Types. - - `Shared_Passive' - The unit contains a pragma Shared_Passive. - - `Predefined' - This unit is part of the predefined environment and cannot be - modified by the user. - - `Remote_Call_Interface' - The unit contains a pragma Remote_Call_Interface. - -  - File: gnat_ug_unx.info, Node: Examples of gnatls Usage, Prev: Switches for gnatls, Up: The GNAT Library Browser gnatls - - Example of `gnatls' Usage - ========================= - - Example of using the verbose switch. Note how the source and object - paths are affected by the -I switch. - - $ gnatls -v -I.. demo1.o - - GNATLS 3.10w (970212) Copyright 1999 Free Software Foundation, Inc. - - Source Search Path: - - ../ - /home/comar/local/adainclude/ - - Object Search Path: - - ../ - /home/comar/local/lib/gcc-lib/mips-sni-sysv4/2.7.2/adalib/ - - ./demo1.o - Unit => - Name => demo1 - Kind => subprogram body - Flags => No_Elab_Code - Source => demo1.adb modified - - The following is an example of use of the dependency list. Note the - use of the -s switch which gives a straight list of source files. This - can be useful for building specialized scripts. - - $ gnatls -d demo2.o - ./demo2.o demo2 OK demo2.adb - OK gen_list.ads - OK gen_list.adb - OK instr.ads - OK instr-child.ads - - $ gnatls -d -s -a demo1.o - demo1.adb - /home/comar/local/adainclude/ada.ads - /home/comar/local/adainclude/a-finali.ads - /home/comar/local/adainclude/a-filico.ads - /home/comar/local/adainclude/a-stream.ads - /home/comar/local/adainclude/a-tags.ads - gen_list.ads - gen_list.adb - /home/comar/local/adainclude/gnat.ads - /home/comar/local/adainclude/g-io.ads - instr.ads - /home/comar/local/adainclude/system.ads - /home/comar/local/adainclude/s-exctab.ads - /home/comar/local/adainclude/s-finimp.ads - /home/comar/local/adainclude/s-finroo.ads - /home/comar/local/adainclude/s-secsta.ads - /home/comar/local/adainclude/s-stalib.ads - /home/comar/local/adainclude/s-stoele.ads - /home/comar/local/adainclude/s-stratt.ads - /home/comar/local/adainclude/s-tasoli.ads - /home/comar/local/adainclude/s-unstyp.ads - /home/comar/local/adainclude/unchconv.ads - -  - File: gnat_ug_unx.info, Node: GNAT and Libraries, Next: Using the GNU make Utility, Prev: The GNAT Library Browser gnatls, Up: Top - - GNAT and Libraries - ****************** - - This chapter addresses some of the issues related to building and using - a library with GNAT. It also shows how the GNAT run-time library can be - recompiled. - - * Menu: - - * Creating an Ada Library:: - * Installing an Ada Library:: - * Using an Ada Library:: - * Creating an Ada Library to be Used in a Non-Ada Context:: - * Rebuilding the GNAT Run-Time Library:: - -  - File: gnat_ug_unx.info, Node: Creating an Ada Library, Next: Installing an Ada Library, Up: GNAT and Libraries - - Creating an Ada Library - ======================= - - In the GNAT environment, a library has two components: - * Source files. - - * Compiled code and Ali files. See *Note The Ada Library Information - Files::. - - In order to use other packages *Note The GNAT Compilation Model:: - requires a certain number of sources to be available to the compiler. - The minimal set of sources required includes the specs of all the - packages that make up the visible part of the library as well as all - the sources upon which they depend. The bodies of all visible generic - units must also be provided. - - Although it is not strictly mandatory, it is recommended that all - sources needed to recompile the library be provided, so that the user - can make full use of inter-unit inlining and source-level debugging. - This can also make the situation easier for users that need to upgrade - their compilation toolchain and thus need to recompile the library from - sources. - - The compiled code can be provided in different ways. The simplest way is - to provide directly the set of objects produced by the compiler during - the compilation of the library. It is also possible to group the objects - into an archive using whatever commands are provided by the operating - system. Finally, it is also possible to create a shared library (see - option -shared in the GCC manual). - - There are various possibilities for compiling the units that make up the - library: for example with a Makefile *Note Using the GNU make Utility::, - or with a conventional script. For simple libraries, it is also - possible to create a dummy main program which depends upon all the - packages that comprise the interface of the library. This dummy main - program can then be given to gnatmake, in order to build all the - necessary objects. Here is an example of such a dummy program and the - generic commands used to build an archive or a shared library. - - with My_Lib.Service1; - with My_Lib.Service2; - with My_Lib.Service3; - procedure My_Lib_Dummy is - begin - null; - end; - - # compiling the library - $ gnatmake -c my_lib_dummy.adb - - # we don't need the dummy object itself - $ rm my_lib_dummy.o my_lib_dummy.ali - - # create an archive with the remaining objects - $ ar rc libmy_lib.a *.o - # some systems may require "ranlib" to be run as well - - # or create a shared library - $ gcc -shared -o libmy_lib.so *.o - # some systems may require the code to have been compiled with -fPIC - - When the objects are grouped in an archive or a shared library, the user - needs to specify the desired library at link time, unless a pragma - linker_options has been used in one of the sources: - pragma Linker_Options ("-lmy_lib"); - -  - File: gnat_ug_unx.info, Node: Installing an Ada Library, Next: Using an Ada Library, Prev: Creating an Ada Library, Up: GNAT and Libraries - - Installing an Ada Library - ========================= - - In the GNAT model, installing a library consists in copying into a - specific location the files that make up this library. It is possible - to install the sources in a different directory from the other files - (ALI, objects, archives) since the source path and the object path can - easily be specified separately. - - For general purpose libraries, it is possible for the system - administrator to put those libraries in the default compiler paths. To - achieve this, he must specify their location in the configuration files - "ada_source_path" and "ada_object_path" that must be located in the GNAT - installation tree at the same place as the gcc spec file. The location - of the gcc spec file can be determined as follows: - $ gcc -v - - The configuration files mentioned above have simple format: each line - in them must contain one unique directory name. Those names are added - to the corresponding path in their order of appearance in the file. The - names can be either absolute or relative, in the latter case, they are - relative to where theses files are located. - - "ada_source_path" and "ada_object_path" might actually not be present - in a GNAT installation, in which case, GNAT will look for its run-time - library in the directories "adainclude" for the sources and "adalib" - for the objects and ALI files. When the files exist, the compiler does - not look in "adainclude" and "adalib" at all, and thus the - "ada_source_path" file must contain the location for the GNAT run-time - sources (which can simply be "adainclude"). In the same way, the - "ada_object_path" file must contain the location for the GNAT run-time - objects (which can simply be "adalib"). - - You can also specify a new default path to the runtime library at - compilation time with the switch "-RTS=RTS-PATH". You can easily choose - and change the runtime you want your program to be compiled with. This - switch is recognized by gcc, gnatmake, gnatbind, gnatls, gnatfind and - gnatxref. - - It is possible to install a library before or after the standard GNAT - library, by reordering the lines in the configuration files. In - general, a library must be installed before the GNAT library if it - redefines any part of it. - -  - File: gnat_ug_unx.info, Node: Using an Ada Library, Next: Creating an Ada Library to be Used in a Non-Ada Context, Prev: Installing an Ada Library, Up: GNAT and Libraries - - Using an Ada Library - ==================== - - In order to use a Ada library, you need to make sure that this library - is on both your source and object path *Note Search Paths and the - Run-Time Library (RTL):: and *Note Search Paths for gnatbind::. For - instance, you can use the library "mylib" installed in "/dir/my_lib_src" - and "/dir/my_lib_obj" with the following commands: - - $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \ - -largs -lmy_lib - - This can be simplified down to the following: - $ gnatmake my_appl - when the following conditions are met: - * "/dir/my_lib_src" has been added by the user to the environment - variable "ADA_INCLUDE_PATH", or by the administrator to the file - "ada_source_path" - - * "/dir/my_lib_obj" has been added by the user to the environment - variable "ADA_OBJECTS_PATH", or by the administrator to the file - "ada_object_path" - - * a pragma linker_options, as mentioned in *Note Creating an Ada - Library:: as been added to the sources. - -  - File: gnat_ug_unx.info, Node: Creating an Ada Library to be Used in a Non-Ada Context, Next: Rebuilding the GNAT Run-Time Library, Prev: Using an Ada Library, Up: GNAT and Libraries - - Creating an Ada Library to be Used in a Non-Ada Context - ======================================================= - - The previous sections detailed how to create and install a library that - was usable from an Ada main program. Using this library in a non-Ada - context is not possible, because the elaboration of the library is - automatically done as part of the main program elaboration. - - GNAT also provides the ability to build libraries that can be used - both in an Ada and non-Ada context. This section describes how to - build such a library, and then how to use it from a C program. The - method for interfacing with the library from other languages such as - Fortran for instance remains the same. - - Creating the Library - -------------------- - - * Identify the units representing the interface of the library. - - Here is an example of simple library interface: - - package Interface is - - procedure Do_Something; - - procedure Do_Something_Else; - - end Interface; - - * Use `pragma Export' or `pragma Convention' for the exported - entities. - - Our package `Interface' is then updated as follow: - package Interface is - - procedure Do_Something; - pragma Export (C, Do_Something, "do_something"); - - procedure Do_Something_Else; - pragma Export (C, Do_Something_Else, "do_something_else"); - - end Interface; - - * Compile all the units composing the library. - - * Bind the library objects. - - This step is performed by invoking gnatbind with the `-L' - switch. `gnatbind' will then generate the library elaboration - procedure (named `init') and the run-time finalization - procedure (named `final'). - - # generate the binder file in Ada - $ gnatbind -Lmylib interface - - # generate the binder file in C - $ gnatbind -C -Lmylib interface - - * Compile the files generated by the binder - - $ gcc -c b~interface.adb - - * Create the library; - - The procedure is identical to the procedure explained in *Note - Creating an Ada Library::, except that `b~interface.o' needs to be - added to the list of objects. - - # create an archive file - $ ar cr libmylib.a b~interface.o - - # create a shared library - $ gcc -shared -o libmylib.so b~interface.o - - * Provide a "foreign" view of the library interface; - - The example below shows the content of `mylib_interface.h' (note - that there is no rule for the naming of this file, any name can be - used) - /* the library elaboration procedure */ - extern void mylibinit (void); - - /* the library finalization procedure */ - extern void mylibfinal (void); - - /* the interface exported by the library */ - extern void do_something (void); - extern void do_something_else (void); - - Using the Library - ----------------- - - Libraries built as explained above can be used from any program, - provided that the elaboration procedures (named `mylibinit' in the - previous example) are called before the library services are used. Any - number of libraries can be used simultaneously, as long as the - elaboration procedure of each library is called. - - Below is an example of C program that uses our `mylib' library. - - #include "mylib_interface.h" - - int - main (void) - { - /* First, elaborate the library before using it */ - mylibinit (); - - /* Main program, using the library exported entities */ - do_something (); - do_something_else (); - - /* Library finalization at the end of the program */ - mylibfinal (); - return 0; - } - - Note that this same library can be used from an equivalent Ada main - program. In addition, if the libraries are installed as detailed in - *Note Installing an Ada Library::, it is not necessary to invoke the - library elaboration and finalization routines. The binder will ensure - that this is done as part of the main program elaboration and - finalization phases. - - The Finalization Phase - ---------------------- - - Invoking any library finalization procedure generated by `gnatbind' - shuts down the Ada run time permanently. Consequently, the finalization - of all Ada libraries must be performed at the end of the program. No - call to these libraries nor the Ada run time should be made past the - finalization phase. - - Restrictions in Libraries - ------------------------- - - The pragmas listed below should be used with caution inside libraries, - as they can create incompatibilities with other Ada libraries: - * pragma `Locking_Policy' - - * pragma `Queuing_Policy' - - * pragma `Task_Dispatching_Policy' - - * pragma `Unreserve_All_Interrupts' - When using a library that contains such pragmas, the user must make - sure that all libraries use the same pragmas with the same values. - Otherwise, a `Program_Error' will be raised during the elaboration of - the conflicting libraries. The usage of these pragmas and its - consequences for the user should therefore be well documented. - - Similarly, the traceback in exception occurrences mechanism should be - enabled or disabled in a consistent manner across all libraries. - Otherwise, a Program_Error will be raised during the elaboration of the - conflicting libraries. - - If the `'Version' and `'Body_Version' attributes are used inside a - library, then it is necessary to perform a `gnatbind' step that - mentions all ali files in all libraries, so that version identifiers - can be properly computed. In practice these attributes are rarely - used, so this is unlikely to be a consideration. - -  - File: gnat_ug_unx.info, Node: Rebuilding the GNAT Run-Time Library, Prev: Creating an Ada Library to be Used in a Non-Ada Context, Up: GNAT and Libraries - - Rebuilding the GNAT Run-Time Library - ==================================== - - It may be useful to recompile the GNAT library in various contexts, the - most important one being the use of partition-wide configuration pragmas - such as Normalize_Scalar. A special Makefile called `Makefile.adalib' - is provided to that effect and can be found in the directory containing - the GNAT library. The location of this directory depends on the way the - GNAT environment has been installed and can be determined by means of - the command: - - $ gnatls -v - - The last entry in the object search path usually contains the gnat - library. This Makefile contains its own documentation and in particular - the set of instructions needed to rebuild a new library and to use it. - -  - File: gnat_ug_unx.info, Node: Using the GNU make Utility, Next: Finding Memory Problems with gnatmem, Prev: GNAT and Libraries, Up: Top - - Using the GNU `make' Utility - **************************** - - This chapter offers some examples of makefiles that solve specific - problems. It does not explain how to write a makefile (see the GNU make - documentation), nor does it try to replace the `gnatmake' utility - (*note The GNAT Make Program gnatmake::). - - All the examples in this section are specific to the GNU version of - make. Although `make' is a standard utility, and the basic language is - the same, these examples use some advanced features found only in `GNU - make'. - - * Menu: - - * Using gnatmake in a Makefile:: - * Automatically Creating a List of Directories:: - * Generating the Command Line Switches:: - * Overcoming Command Line Length Limits:: - -  - File: gnat_ug_unx.info, Node: Using gnatmake in a Makefile, Next: Automatically Creating a List of Directories, Up: Using the GNU make Utility - - Using gnatmake in a Makefile - ============================ - - Complex project organizations can be handled in a very powerful way by - using GNU make combined with gnatmake. For instance, here is a Makefile - which allows you to build each subsystem of a big project into a - separate shared library. Such a makefile allows you to significantly - reduce the link time of very big applications while maintaining full - coherence at each step of the build process. - - The list of dependencies are handled automatically by `gnatmake'. - The Makefile is simply used to call gnatmake in each of the appropriate - directories. - - Note that you should also read the example on how to automatically - create the list of directories (*note Automatically Creating a List of - Directories::) which might help you in case your project has a lot of - subdirectories. - - ## This Makefile is intended to be used with the following directory - ## configuration: - ## - The sources are split into a series of csc (computer software components) - ## Each of these csc is put in its own directory. - ## Their name are referenced by the directory names. - ## They will be compiled into shared library (although this would also work - ## with static libraries - ## - The main program (and possibly other packages that do not belong to any - ## csc is put in the top level directory (where the Makefile is). - ## toplevel_dir __ first_csc (sources) __ lib (will contain the library) - ## \_ second_csc (sources) __ lib (will contain the library) - ## \_ ... - ## Although this Makefile is build for shared library, it is easy to modify - ## to build partial link objects instead (modify the lines with -shared and - ## gnatlink below) - ## - ## With this makefile, you can change any file in the system or add any new - ## file, and everything will be recompiled correctly (only the relevant shared - ## objects will be recompiled, and the main program will be re-linked). - - # The list of computer software component for your project. This might be - # generated automatically. - CSC_LIST=aa bb cc - - # Name of the main program (no extension) - MAIN=main - - # If we need to build objects with -fPIC, uncomment the following line - #NEED_FPIC=-fPIC - - # The following variable should give the directory containing libgnat.so - # You can get this directory through 'gnatls -v'. This is usually the last - # directory in the Object_Path. - GLIB=... - - # The directories for the libraries - # (This macro expands the list of CSC to the list of shared libraries, you - # could simply use the expanded form : - # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so - LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so} - - ${MAIN}: objects ${LIB_DIR} - gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared - gnatlink ${MAIN} ${CSC_LIST:%=-l%} - - objects:: - # recompile the sources - gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%} - - # Note: In a future version of GNAT, the following commands will be simplified - # by a new tool, gnatmlib - ${LIB_DIR}: - mkdir -p ${dir $@ } - cd ${dir $@ }; gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat - cd ${dir $@ }; cp -f ../*.ali . - - # The dependencies for the modules - # Note that we have to force the expansion of *.o, since in some cases make won't - # be able to do it itself. - aa/lib/libaa.so: ${wildcard aa/*.o} - bb/lib/libbb.so: ${wildcard bb/*.o} - cc/lib/libcc.so: ${wildcard cc/*.o} - - # Make sure all of the shared libraries are in the path before starting the - # program - run:: - LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN} - - clean:: - ${RM} -rf ${CSC_LIST:%=%/lib} - ${RM} ${CSC_LIST:%=%/*.ali} - ${RM} ${CSC_LIST:%=%/*.o} - ${RM} *.o *.ali ${MAIN} - -  - File: gnat_ug_unx.info, Node: Automatically Creating a List of Directories, Next: Generating the Command Line Switches, Prev: Using gnatmake in a Makefile, Up: Using the GNU make Utility - - Automatically Creating a List of Directories - ============================================ - - In most makefiles, you will have to specify a list of directories, and - store it in a variable. For small projects, it is often easier to - specify each of them by hand, since you then have full control over what - is the proper order for these directories, which ones should be - included... - - However, in larger projects, which might involve hundreds of - subdirectories, it might be more convenient to generate this list - automatically. - - The example below presents two methods. The first one, although less - general, gives you more control over the list. It involves wildcard - characters, that are automatically expanded by `make'. Its shortcoming - is that you need to explicitly specify some of the organization of your - project, such as for instance the directory tree depth, whether some - directories are found in a separate tree,... - - The second method is the most general one. It requires an external - program, called `find', which is standard on all Unix systems. All the - directories found under a given root directory will be added to the - list. - - # The examples below are based on the following directory hierarchy: - # All the directories can contain any number of files - # ROOT_DIRECTORY -> a -> aa -> aaa - # -> ab - # -> ac - # -> b -> ba -> baa - # -> bb - # -> bc - # This Makefile creates a variable called DIRS, that can be reused any time - # you need this list (see the other examples in this section) - - # The root of your project's directory hierarchy - ROOT_DIRECTORY=. - - #### - # First method: specify explicitly the list of directories - # This allows you to specify any subset of all the directories you need. - #### - - DIRS := a/aa/ a/ab/ b/ba/ - - #### - # Second method: use wildcards - # Note that the argument(s) to wildcard below should end with a '/'. - # Since wildcards also return file names, we have to filter them out - # to avoid duplicate directory names. - # We thus use make's `dir' and `sort' functions. - # It sets DIRs to the following value (note that the directories aaa and baa - # are not given, unless you change the arguments to wildcard). - # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ - #### - - DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/ ${ROOT_DIRECTORY}/*/*/}}} - - #### - # Third method: use an external program - # This command is much faster if run on local disks, avoiding NFS slowdowns. - # This is the most complete command: it sets DIRs to the following value: - # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc - #### - - DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print} - -  - File: gnat_ug_unx.info, Node: Generating the Command Line Switches, Next: Overcoming Command Line Length Limits, Prev: Automatically Creating a List of Directories, Up: Using the GNU make Utility - - Generating the Command Line Switches - ==================================== - - Once you have created the list of directories as explained in the - previous section (*note Automatically Creating a List of Directories::), - you can easily generate the command line arguments to pass to gnatmake. - - For the sake of completeness, this example assumes that the source - path is not the same as the object path, and that you have two separate - lists of directories. - - # see "Automatically creating a list of directories" to create - # these variables - SOURCE_DIRS= - OBJECT_DIRS= - - GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}} - GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}} - - all: - gnatmake ${GNATMAKE_SWITCHES} main_unit - -  - File: gnat_ug_unx.info, Node: Overcoming Command Line Length Limits, Prev: Generating the Command Line Switches, Up: Using the GNU make Utility - - Overcoming Command Line Length Limits - ===================================== - - One problem that might be encountered on big projects is that many - operating systems limit the length of the command line. It is thus hard - to give gnatmake the list of source and object directories. - - This example shows how you can set up environment variables, which - will make `gnatmake' behave exactly as if the directories had been - specified on the command line, but have a much higher length limit (or - even none on most systems). - - It assumes that you have created a list of directories in your - Makefile, using one of the methods presented in *Note Automatically - Creating a List of Directories::. For the sake of completeness, we - assume that the object path (where the ALI files are found) is - different from the sources patch. - - Note a small trick in the Makefile below: for efficiency reasons, we - create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are - expanded immediately by `make'. This way we overcome the standard make - behavior which is to expand the variables only when they are actually - used. - - # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH. - # This is the same thing as putting the -I arguments on the command line. - # (the equivalent of using -aI on the command line would be to define - # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECT_PATH). - # You can of course have different values for these variables. - # - # Note also that we need to keep the previous values of these variables, since - # they might have been set before running 'make' to specify where the GNAT - # library is installed. - - # see "Automatically creating a list of directories" to create these - # variables - SOURCE_DIRS= - OBJECT_DIRS= - - empty:= - space:=${empty} ${empty} - SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}} - OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}} - ADA_INCLUDE_PATH += ${SOURCE_LIST} - ADA_OBJECT_PATH += ${OBJECT_LIST} - export ADA_INCLUDE_PATH - export ADA_OBJECT_PATH - - all: - gnatmake main_unit - -  - File: gnat_ug_unx.info, Node: Finding Memory Problems with gnatmem, Next: Finding Memory Problems with GNAT Debug Pool, Prev: Using the GNU make Utility, Up: Top - - Finding Memory Problems with `gnatmem' - ************************************** - - `gnatmem', is a tool that monitors dynamic allocation and deallocation - activity in a program, and displays information about incorrect - deallocations and possible sources of memory leaks. Gnatmem provides - three type of information: - * General information concerning memory management, such as the total - number of allocations and deallocations, the amount of allocated - memory and the high water mark, i.e. the largest amount of - allocated memory in the course of program execution. - - * Backtraces for all incorrect deallocations, that is to say - deallocations which do not correspond to a valid allocation. - - * Information on each allocation that is potentially the origin of a - memory leak. - - The `gnatmem' command has two modes. It can be used with `gdb' or - with instrumented allocation and deallocation routines. The later mode - is called the `GMEM' mode. Both modes produce the very same output. - - * Menu: - - * Running gnatmem (GDB Mode):: - * Running gnatmem (GMEM Mode):: - * Switches for gnatmem:: - * Examples of gnatmem Usage:: - * GDB and GMEM Modes:: - * Implementation Note:: - -  - File: gnat_ug_unx.info, Node: Running gnatmem (GDB Mode), Next: Running gnatmem (GMEM Mode), Up: Finding Memory Problems with gnatmem - - Running `gnatmem' (GDB Mode) - ============================ - - The `gnatmem' command has the form - - $ gnatmem [-q] [n] [-o file] user_program [program_arg]* - or - $ gnatmem [-q] [n] -i file - - Gnatmem must be supplied with the executable to examine, followed by its - run-time inputs. For example, if a program is executed with the command: - $ my_program arg1 arg2 - then it can be run under `gnatmem' control using the command: - $ gnatmem my_program arg1 arg2 - - The program is transparently executed under the control of the - debugger *Note The GNAT Debugger GDB::. This does not affect the - behavior of the program, except for sensitive real-time programs. When - the program has completed execution, `gnatmem' outputs a report - containing general allocation/deallocation information and potential - memory leak. For better results, the user program should be compiled - with debugging options *Note Switches for gcc::. - - Here is a simple example of use: - - *************** debut cc - $ gnatmem test_gm - - Global information - ------------------ - Total number of allocations : 45 - Total number of deallocations : 6 - Final Water Mark (non freed mem) : 11.29 Kilobytes - High Water Mark : 11.40 Kilobytes - - . - . - . - Allocation Root # 2 - ------------------- - Number of non freed allocations : 11 - Final Water Mark (non freed mem) : 1.16 Kilobytes - High Water Mark : 1.27 Kilobytes - Backtrace : - test_gm.adb:23 test_gm.alloc - . - . - . - - The first block of output give general information. In this case, the - Ada construct "new" was executed 45 times, and only 6 calls to an - unchecked deallocation routine occurred. - - Subsequent paragraphs display information on all allocation roots. - An allocation root is a specific point in the execution of the program - that generates some dynamic allocation, such as a "new" construct. This - root is represented by an execution backtrace (or subprogram call - stack). By default the backtrace depth for allocations roots is 1, so - that a root corresponds exactly to a source location. The backtrace can - be made deeper, to make the root more specific. - -  - File: gnat_ug_unx.info, Node: Running gnatmem (GMEM Mode), Next: Switches for gnatmem, Prev: Running gnatmem (GDB Mode), Up: Finding Memory Problems with gnatmem - - Running `gnatmem' (GMEM Mode) - ============================= - - The `gnatmem' command has the form - - $ gnatmem [-q] [n] -i gmem.out user_program [program_arg]* - - The program must have been linked with the instrumented version of - the allocation and deallocation routines. This is done with linking - with the `libgmem.a' library. For better results, the user program - should be compiled with debugging options *Note Switches for gcc::. For - example to build `my_program': - - $ gnatmake -g my_program -largs -lgmem - - When running `my_program' the file `gmem.out' is produced. This file - contains information about all allocations and deallocations done by the - program. It is produced by the instrumented allocations and - deallocations routines and will be used by `gnatmem'. - - Gnatmem must be supplied with the `gmem.out' file and the executable to - examine followed by its run-time inputs. For example, if a program is - executed with the command: - $ my_program arg1 arg2 - then `gmem.out' can be analysed by `gnatmem' using the command: - $ gnatmem -i gmem.out my_program arg1 arg2 - -  - File: gnat_ug_unx.info, Node: Switches for gnatmem, Next: Examples of gnatmem Usage, Prev: Running gnatmem (GMEM Mode), Up: Finding Memory Problems with gnatmem - - Switches for `gnatmem' - ====================== - - `gnatmem' recognizes the following switches: - - ``-q'' - Quiet. Gives the minimum output needed to identify the origin of - the memory leaks. Omit statistical information. - - ``n'' - N is an integer literal (usually between 1 and 10) which controls - the depth of the backtraces defining allocation root. The default - value for N is 1. The deeper the backtrace, the more precise the - localization of the root. Note that the total number of roots can - depend on this parameter. - - ``-o file'' - Direct the gdb output to the specified file. The `gdb' script used - to generate this output is also saved in the file `gnatmem.tmp'. - - ``-i file'' - Do the `gnatmem' processing starting from `file' which has been - generated by a previous call to `gnatmem' with the -o switch or - `gmem.out' produced by `GMEM' mode. This is useful for post mortem - processing. - -  - File: gnat_ug_unx.info, Node: Examples of gnatmem Usage, Next: GDB and GMEM Modes, Prev: Switches for gnatmem, Up: Finding Memory Problems with gnatmem - - Example of `gnatmem' Usage - ========================== - - This section is based on the `GDB' mode of `gnatmem'. The same results - can be achieved using `GMEM' mode. See section *Note Running gnatmem - (GMEM Mode)::. - - The first example shows the use of `gnatmem' on a simple leaking - program. Suppose that we have the following Ada program: - - with Unchecked_Deallocation; - procedure Test_Gm is - - type T is array (1..1000) of Integer; - type Ptr is access T; - procedure Free is new Unchecked_Deallocation (T, Ptr); - A : Ptr; - - procedure My_Alloc is - begin - A := new T; - end My_Alloc; - - procedure My_DeAlloc is - B : Ptr := A; - begin - Free (B); - end My_DeAlloc; - - begin - My_Alloc; - for I in 1 .. 5 loop - for J in I .. 5 loop - My_Alloc; - end loop; - My_Dealloc; - end loop; - end; - - The program needs to be compiled with debugging option: - - $ gnatmake -g test_gm - - `gnatmem' is invoked simply with - $ gnatmem test_gm - - which produces the following output: - - Global information - ------------------ - Total number of allocations : 18 - Total number of deallocations : 5 - Final Water Mark (non freed mem) : 53.00 Kilobytes - High Water Mark : 56.90 Kilobytes - - Allocation Root # 1 - ------------------- - Number of non freed allocations : 11 - Final Water Mark (non freed mem) : 42.97 Kilobytes - High Water Mark : 46.88 Kilobytes - Backtrace : - test_gm.adb:11 test_gm.my_alloc - - Allocation Root # 2 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 10.02 Kilobytes - High Water Mark : 10.02 Kilobytes - Backtrace : - s-secsta.adb:81 system.secondary_stack.ss_init - - Allocation Root # 3 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 12 Bytes - High Water Mark : 12 Bytes - Backtrace : - s-secsta.adb:181 system.secondary_stack.ss_init - - Note that the GNAT run time contains itself a certain number of - allocations that have no corresponding deallocation, as shown here for - root #2 and root #1. This is a normal behavior when the number of non - freed allocations is one, it locates dynamic data structures that the - run time needs for the complete lifetime of the program. Note also that - there is only one allocation root in the user program with a single - line back trace: test_gm.adb:11 test_gm.my_alloc, whereas a careful - analysis of the program shows that 'My_Alloc' is called at 2 different - points in the source (line 21 and line 24). If those two allocation - roots need to be distinguished, the backtrace depth parameter can be - used: - - $ gnatmem 3 test_gm - - which will give the following output: - - Global information - ------------------ - Total number of allocations : 18 - Total number of deallocations : 5 - Final Water Mark (non freed mem) : 53.00 Kilobytes - High Water Mark : 56.90 Kilobytes - - Allocation Root # 1 - ------------------- - Number of non freed allocations : 10 - Final Water Mark (non freed mem) : 39.06 Kilobytes - High Water Mark : 42.97 Kilobytes - Backtrace : - test_gm.adb:11 test_gm.my_alloc - test_gm.adb:24 test_gm - b_test_gm.c:52 main - - Allocation Root # 2 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 10.02 Kilobytes - High Water Mark : 10.02 Kilobytes - Backtrace : - s-secsta.adb:81 system.secondary_stack.ss_init - s-secsta.adb:283 - b_test_gm.c:33 adainit - - Allocation Root # 3 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 3.91 Kilobytes - High Water Mark : 3.91 Kilobytes - Backtrace : - test_gm.adb:11 test_gm.my_alloc - test_gm.adb:21 test_gm - b_test_gm.c:52 main - - Allocation Root # 4 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 12 Bytes - High Water Mark : 12 Bytes - Backtrace : - s-secsta.adb:181 system.secondary_stack.ss_init - s-secsta.adb:283 - b_test_gm.c:33 adainit - - The allocation root #1 of the first example has been split in 2 roots #1 - and #3 thanks to the more precise associated backtrace. - -  - File: gnat_ug_unx.info, Node: GDB and GMEM Modes, Next: Implementation Note, Prev: Examples of gnatmem Usage, Up: Finding Memory Problems with gnatmem - - GDB and GMEM Modes - ================== - - The main advantage of the `GMEM' mode is that it is a lot faster than - the `GDB' mode where the application must be monitored by a `GDB' - script. But the `GMEM' mode is available only for DEC Unix, Linux x86, - Solaris (sparc and x86) and Windows 95/98/NT/2000 (x86). - - The main advantage of the `GDB' mode is that it is available on all - supported platforms. But it can be very slow if the application does a - lot of allocations and deallocations. - -  - File: gnat_ug_unx.info, Node: Implementation Note, Prev: GDB and GMEM Modes, Up: Finding Memory Problems with gnatmem - - Implementation Note - =================== - - * Menu: - - * gnatmem Using GDB Mode:: - * gnatmem Using GMEM Mode:: - -  - File: gnat_ug_unx.info, Node: gnatmem Using GDB Mode, Next: gnatmem Using GMEM Mode, Up: Implementation Note - - `gnatmem' Using `GDB' Mode - -------------------------- - - `gnatmem' executes the user program under the control of `GDB' using a - script that sets breakpoints and gathers information on each dynamic - allocation and deallocation. The output of the script is then analyzed - by `gnatmem' in order to locate memory leaks and their origin in the - program. Gnatmem works by recording each address returned by the - allocation procedure (`__gnat_malloc') along with the backtrace at the - allocation point. On each deallocation, the deallocated address is - matched with the corresponding allocation. At the end of the processing, - the unmatched allocations are considered potential leaks. All the - allocations associated with the same backtrace are grouped together and - form an allocation root. The allocation roots are then sorted so that - those with the biggest number of unmatched allocation are printed - first. A delicate aspect of this technique is to distinguish between the - data produced by the user program and the data produced by the gdb - script. Currently, on systems that allow probing the terminal, the gdb - command "tty" is used to force the program output to be redirected to - the current terminal while the `gdb' output is directed to a file or to - a pipe in order to be processed subsequently by `gnatmem'. - -  - File: gnat_ug_unx.info, Node: gnatmem Using GMEM Mode, Prev: gnatmem Using GDB Mode, Up: Implementation Note - - `gnatmem' Using `GMEM' Mode - --------------------------- - - This mode use the same algorithm to detect memory leak as the `GDB' - mode of `gnatmem', the only difference is in the way data are gathered. - In `GMEM' mode the program is linked with instrumented version of - `__gnat_malloc' and `__gnat_free' routines. Information needed to find - memory leak are recorded by these routines in file `gmem.out'. This - mode also require that the stack traceback be available, this is only - implemented on some platforms *Note GDB and GMEM Modes::. - -  - File: gnat_ug_unx.info, Node: Finding Memory Problems with GNAT Debug Pool, Next: Creating Sample Bodies Using gnatstub, Prev: Finding Memory Problems with gnatmem, Up: Top - - Finding Memory Problems with GNAT Debug Pool - ******************************************** - - The use of unchecked deallocation and unchecked conversion can easily - lead to incorrect memory references. The problems generated by such - references are usually difficult to tackle because the symptoms can be - very remote from the origin of the problem. In such cases, it is very - helpful to detect the problem as early as possible. This is the purpose - of the Storage Pool provided by `GNAT.Debug_Pools'. - - In order to use the GNAT specific debugging pool, the user must - associate a debug pool object with each of the access types that may be - related to suspected memory problems. See Ada Reference Manual 13.11. - type Ptr is access Some_Type; - Pool : GNAT.Debug_Pools.Debug_Pool; - for Ptr'Storage_Pool use Pool; - - `GNAT.Debug_Pools' is derived from of a GNAT-specific kind of pool: - the Checked_Pool. Such pools, like standard Ada storage pools, allow - the user to redefine allocation and deallocation strategies. They also - provide a checkpoint for each dereference, through the use of the - primitive operation `Dereference' which is implicitly called at each - dereference of an access value. - - Once an access type has been associated with a debug pool, - operations on values of the type may raise four distinct exceptions, - which correspond to four potential kinds of memory corruption: - * `GNAT.Debug_Pools.Accessing_Not_Allocated_Storage' - - * `GNAT.Debug_Pools.Accessing_Deallocated_Storage' - - * `GNAT.Debug_Pools.Freeing_Not_Allocated_Storage' - - * `GNAT.Debug_Pools.Freeing_Deallocated_Storage ' - - For types associated with a Debug_Pool, dynamic allocation is performed - using the standard GNAT allocation routine. References to all allocated - chunks of memory are kept in an internal dictionary. The deallocation - strategy consists in not releasing the memory to the underlying system - but rather to fill it with a memory pattern easily recognizable during - debugging sessions: The memory pattern is the old IBM hexadecimal - convention: 16#DEADBEEF#. Upon each dereference, a check is made that - the access value denotes a properly allocated memory location. Here is - a complete example of use of `Debug_Pools', that includes typical - instances of memory corruption: - with Gnat.Io; use Gnat.Io; - with Unchecked_Deallocation; - with Unchecked_Conversion; - with GNAT.Debug_Pools; - with System.Storage_Elements; - with Ada.Exceptions; use Ada.Exceptions; - procedure Debug_Pool_Test is - - type T is access Integer; - type U is access all T; - - P : GNAT.Debug_Pools.Debug_Pool; - for T'Storage_Pool use P; - - procedure Free is new Unchecked_Deallocation (Integer, T); - function UC is new Unchecked_Conversion (U, T); - A, B : aliased T; - - procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); - - begin - Info (P); - A := new Integer; - B := new Integer; - B := A; - Info (P); - Free (A); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - B := UC(A'Access); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - Info (P); - end Debug_Pool_Test; - - The debug pool mechanism provides the following precise diagnostics on - the execution of this erroneous program: - Debug Pool info: - Total allocated bytes : 0 - Total deallocated bytes : 0 - Current Water Mark: 0 - High Water Mark: 0 - - Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 0 - Current Water Mark: 8 - High Water Mark: 8 - - raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE - Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 4 - Current Water Mark: 4 - High Water Mark: 8 - -  - File: gnat_ug_unx.info, Node: Creating Sample Bodies Using gnatstub, Next: Reducing the Size of Ada Executables with gnatelim, Prev: Finding Memory Problems with GNAT Debug Pool, Up: Top - - Creating Sample Bodies Using `gnatstub' - *************************************** - - `gnatstub' creates body stubs, that is, empty but compilable bodies for - library unit declarations. - - To create a body stub, `gnatstub' has to compile the library unit - declaration. Therefore, bodies can be created only for legal library - units. Moreover, if a library unit depends semantically upon units - located outside the current directory, you have to provide the source - search path when calling `gnatstub', see the description of `gnatstub' - switches below. - - * Menu: - - * Running gnatstub:: - * Switches for gnatstub:: - -  - File: gnat_ug_unx.info, Node: Running gnatstub, Next: Switches for gnatstub, Up: Creating Sample Bodies Using gnatstub - - Running `gnatstub' - ================== - - `gnatstub' has the command-line interface of the form - - $ gnatstub [switches] filename [directory] - - where - `filename' - is the name of the source file that contains a library unit - declaration for which a body must be created. This name should - follow the GNAT file name conventions. No crunching is allowed for - this file name. The file name may contain the path information. - - `directory' - indicates the directory to place a body stub (default is the - current directory) - - `switches' - is an optional sequence of switches as described in the next - section - -  - File: gnat_ug_unx.info, Node: Switches for gnatstub, Prev: Running gnatstub, Up: Creating Sample Bodies Using gnatstub - - Switches for `gnatstub' - ======================= - - `-f' - If the destination directory already contains a file with a name - of the body file for the argument spec file, replace it with the - generated body stub. - - `-hs' - Put the comment header (i.e. all the comments preceding the - compilation unit) from the source of the library unit declaration - into the body stub. - - `-hg' - Put a sample comment header into the body stub. - - `-IDIR' - `-I-' - These switches have the same meaning as in calls to gcc. They - define the source search path in the call to gcc issued by - `gnatstub' to compile an argument source file. - - `-iN' - (N is a decimal natural number). Set the indentation level in the - generated body sample to n, '-i0' means "no indentation", the - default indentation is 3. - - `-k' - Do not remove the tree file (i.e. the snapshot of the compiler - internal structures used by `gnatstub') after creating the body - stub. - - `-lN' - (N is a decimal positive number) Set the maximum line length in the - body stub to n, the default is 78. - - `-q' - Quiet mode: do not generate a confirmation when a body is - successfully created or a message when a body is not required for - an argument unit. - - `-r' - Reuse the tree file (if it exists) instead of creating it: instead - of creating the tree file for the library unit declaration, - gnatstub tries to find it in the current directory and use it for - creating a body. If the tree file is not found, no body is - created. `-r' also implies `-k', whether or not `-k' is set - explicitly. - - `-t' - Overwrite the existing tree file: if the current directory already - contains the file which, according to the GNAT file name rules - should be considered as a tree file for the argument source file, - gnatstub will refuse to create the tree file needed to create a - body sampler, unless `-t' option is set - - `-v' - Verbose mode: generate version information. - -  - File: gnat_ug_unx.info, Node: Reducing the Size of Ada Executables with gnatelim, Next: Other Utility Programs, Prev: Creating Sample Bodies Using gnatstub, Up: Top - - Reducing the Size of Ada Executables with `gnatelim' - **************************************************** - - * Menu: - - * About gnatelim:: - * Eliminate Pragma:: - * Tree Files:: - * Preparing Tree and Bind Files for gnatelim:: - * Running gnatelim:: - * Correcting the List of Eliminate Pragmas:: - * Making Your Executables Smaller:: - * Summary of the gnatelim Usage Cycle:: - -  - File: gnat_ug_unx.info, Node: About gnatelim, Next: Eliminate Pragma, Up: Reducing the Size of Ada Executables with gnatelim - - About `gnatelim' - ================ - - When a program shares a set of Ada packages with other programs, it may - happen that this program uses only a fraction of the subprograms - defined in these packages. The code created for these unused - subprograms increases the size of the executable. - - `gnatelim' tracks unused subprograms in an Ada program and outputs a - list of GNAT-specific `Eliminate' pragmas (see next section) marking - all the subprograms that are declared but never called. By placing the - list of `Eliminate' pragmas in the GNAT configuration file `gnat.adc' - and recompiling your program, you may decrease the size of its - executable, because the compiler will not generate the code for - 'eliminated' subprograms. - - `gnatelim' needs as its input data a set of tree files (see *Note - Tree Files::) representing all the components of a program to process - and a bind file for a main subprogram (see *Note Preparing Tree and - Bind Files for gnatelim::). - -  - File: gnat_ug_unx.info, Node: Eliminate Pragma, Next: Tree Files, Prev: About gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - `Eliminate' Pragma - ================== - - The simplified syntax of the Eliminate pragma used by `gnatelim' is: - - pragma Eliminate (Library_Unit_Name, Subprogram_Name); - - where - `Library_Unit_Name' - full expanded Ada name of a library unit - - `Subprogram_Name' - a simple or expanded name of a subprogram declared within this - compilation unit - - The effect of an `Eliminate' pragma placed in the GNAT configuration - file `gnat.adc' is: - - * If the subprogram `Subprogram_Name' is declared within the library - unit `Library_Unit_Name', the compiler will not generate code for - this subprogram. This applies to all overloaded subprograms denoted - by `Subprogram_Name'. - - * If a subprogram marked by the pragma `Eliminate' is used (called) - in a program, the compiler will produce an error message in the - place where it is called. - -  - File: gnat_ug_unx.info, Node: Tree Files, Next: Preparing Tree and Bind Files for gnatelim, Prev: Eliminate Pragma, Up: Reducing the Size of Ada Executables with gnatelim - - Tree Files - ========== - - A tree file stores a snapshot of the compiler internal data structures - at the very end of a successful compilation. It contains all the - syntactic and semantic information for the compiled unit and all the - units upon which it depends semantically. To use tools that make use - of tree files, you need to first produce the right set of tree files. - - GNAT produces correct tree files when -gnatt -gnatc options are set - in a gcc call. The tree files have an .adt extension. Therefore, to - produce a tree file for the compilation unit contained in a file named - `foo.adb', you must use the command - - $ gcc -c -gnatc -gnatt foo.adb - - and you will get the tree file `foo.adt'. compilation. - -  - File: gnat_ug_unx.info, Node: Preparing Tree and Bind Files for gnatelim, Next: Running gnatelim, Prev: Tree Files, Up: Reducing the Size of Ada Executables with gnatelim - - Preparing Tree and Bind Files for `gnatelim' - ============================================ - - A set of tree files covering the program to be analyzed with `gnatelim' - and the bind file for the main subprogram does not have to be in the - current directory. '-T' gnatelim option may be used to provide the - search path for tree files, and '-b' option may be used to point to the - bind file to process (see *Note Running gnatelim::) - - If you do not have the appropriate set of tree files and the right - bind file, you may create them in the current directory using the - following procedure. - - Let `Main_Prog' be the name of a main subprogram, and suppose this - subprogram is in a file named `main_prog.adb'. - - To create a bind file for `gnatelim', run `gnatbind' for the main - subprogram. `gnatelim' can work with both Ada and C bind files; when - both are present, it uses the Ada bind file. The following commands - will build the program and create the bind file: - - $ gnatmake -c Main_Prog - $ gnatbind main_prog - - To create a minimal set of tree files covering the whole program, call - `gnatmake' for this program as follows: - - $ gnatmake -f -c -gnatc -gnatt Main_Prog - - The `-c' gnatmake option turns off the bind and link steps, that are - useless anyway because the sources are compiled with `-gnatc' option - which turns off code generation. - - The `-f' gnatmake option forces recompilation of all the needed - sources. - - This sequence of actions will create all the data needed by - `gnatelim' from scratch and therefore guarantee its consistency. If you - would like to use some existing set of files as `gnatelim' output, you - must make sure that the set of files is complete and consistent. You - can use the `-m' switch to check if there are missed tree files - - Note, that `gnatelim' needs neither object nor ALI files. - -  - File: gnat_ug_unx.info, Node: Running gnatelim, Next: Correcting the List of Eliminate Pragmas, Prev: Preparing Tree and Bind Files for gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - Running `gnatelim' - ================== - - `gnatelim' has the following command-line interface: - - $ gnatelim [options] name - - `name' should be a full expanded Ada name of a main subprogram of a - program (partition). - - `gnatelim' options: - - `-q' - Quiet mode: by default `gnatelim' generates to the standard error - stream a trace of the source file names of the compilation units - being processed. This option turns this trace off. - - `-v' - Verbose mode: `gnatelim' version information is printed as Ada - comments to the standard output stream. - - `-a' - Also look for subprograms from the GNAT run time that can be - eliminated. - - `-m' - Check if any tree files are missing for an accurate result. - - `-TDIR' - When looking for tree files also look in directory DIR - - `-bBIND_FILE' - Specifies BIND_FILE as the bind file to process. If not set, the - name of the bind file is computed from the full expanded Ada name - of a main subprogram. - - `-dX' - Activate internal debugging switches. X is a letter or digit, or - string of letters or digits, which specifies the type of debugging - mode desired. Normally these are used only for internal - development or system debugging purposes. You can find full - documentation for these switches in the body of the - `Gnatelim.Options' unit in the compiler source file - `gnatelim-options.adb'. - - `gnatelim' sends its output to the standard output stream, and all the - tracing and debug information is sent to the standard error stream. In - order to produce a proper GNAT configuration file `gnat.adc', - redirection must be used: - - $ gnatelim Main_Prog > gnat.adc - - or - - $ gnatelim Main_Prog >> gnat.adc - - In order to append the `gnatelim' output to the existing contents of - `gnat.adc'. - -  - File: gnat_ug_unx.info, Node: Correcting the List of Eliminate Pragmas, Next: Making Your Executables Smaller, Prev: Running gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - Correcting the List of Eliminate Pragmas - ======================================== - - In some rare cases it may happen that `gnatelim' will try to eliminate - subprograms which are actually called in the program. In this case, the - compiler will generate an error message of the form: - - file.adb:106:07: cannot call eliminated subprogram "My_Prog" - - You will need to manually remove the wrong `Eliminate' pragmas from the - `gnat.adc' file. It is advised that you recompile your program from - scratch after that because you need a consistent `gnat.adc' file during - the entire compilation. - -  - File: gnat_ug_unx.info, Node: Making Your Executables Smaller, Next: Summary of the gnatelim Usage Cycle, Prev: Correcting the List of Eliminate Pragmas, Up: Reducing the Size of Ada Executables with gnatelim - - Making Your Executables Smaller - =============================== - - In order to get a smaller executable for your program you now have to - recompile the program completely with the new `gnat.adc' file created - by `gnatelim' in your current directory: - - $ gnatmake -f Main_Prog - - (you will need `-f' option for gnatmake to recompile everything with - the set of pragmas `Eliminate' you have obtained with `gnatelim'). - - Be aware that the set of `Eliminate' pragmas is specific to each - program. It is not recommended to merge sets of `Eliminate' pragmas - created for different programs in one `gnat.adc' file. - -  - File: gnat_ug_unx.info, Node: Summary of the gnatelim Usage Cycle, Prev: Making Your Executables Smaller, Up: Reducing the Size of Ada Executables with gnatelim - - Summary of the gnatelim Usage Cycle - =================================== - - Here is a quick summary of the steps to be taken in order to reduce the - size of your executables with `gnatelim'. You may use other GNAT - options to control the optimization level, to produce the debugging - information, to set search path, etc. - - 1. Produce a bind file and a set of tree files - - $ gnatmake -c Main_Prog - $ gnatbind main_prog - $ gnatmake -f -c -gnatc -gnatt Main_Prog - - 2. Generate a list of `Eliminate' pragmas - $ gnatelim Main_Prog >[>] gnat.adc - - 3. Recompile the application - - $ gnatmake -f Main_Prog - - -  - File: gnat_ug_unx.info, Node: Other Utility Programs, Next: Running and Debugging Ada Programs, Prev: Reducing the Size of Ada Executables with gnatelim, Up: Top - - Other Utility Programs - ********************** - - This chapter discusses some other utility programs available in the Ada - environment. - - * Menu: - - * Using Other Utility Programs with GNAT:: - * The gnatpsta Utility Program:: - * The External Symbol Naming Scheme of GNAT:: - * Ada Mode for Glide:: - * Converting Ada Files to html with gnathtml:: - * Installing gnathtml:: - -  - File: gnat_ug_unx.info, Node: Using Other Utility Programs with GNAT, Next: The gnatpsta Utility Program, Up: Other Utility Programs - - Using Other Utility Programs with GNAT - ====================================== - - The object files generated by GNAT are in standard system format and in - particular the debugging information uses this format. This means - programs generated by GNAT can be used with existing utilities that - depend on these formats. - - In general, any utility program that works with C will also often - work with Ada programs generated by GNAT. This includes software - utilities such as gprof (a profiling program), `gdb' (the FSF - debugger), and utilities such as Purify. - -  - File: gnat_ug_unx.info, Node: The gnatpsta Utility Program, Next: The External Symbol Naming Scheme of GNAT, Prev: Using Other Utility Programs with GNAT, Up: Other Utility Programs - - The `gnatpsta' Utility Program - ============================== - - Many of the definitions in package Standard are - implementation-dependent. However, the source of this package does not - exist as an Ada source file, so these values cannot be determined by - inspecting the source. They can be determined by examining in detail - the coding of `cstand.adb' which creates the image of Standard in the - compiler, but this is awkward and requires a great deal of internal - knowledge about the system. - - The `gnatpsta' utility is designed to deal with this situation. It - is an Ada program that dynamically determines the values of all the - relevant parameters in Standard, and prints them out in the form of an - Ada source listing for Standard, displaying all the values of interest. - This output is generated to `stdout'. - - To determine the value of any parameter in package Standard, simply - run `gnatpsta' with no qualifiers or arguments, and examine the output. - This is preferable to consulting documentation, because you know that - the values you are getting are the actual ones provided by the - executing system. - -  - File: gnat_ug_unx.info, Node: The External Symbol Naming Scheme of GNAT, Next: Ada Mode for Glide, Prev: The gnatpsta Utility Program, Up: Other Utility Programs - - The External Symbol Naming Scheme of GNAT - ========================================= - - In order to interpret the output from GNAT, when using tools that are - originally intended for use with other languages, it is useful to - understand the conventions used to generate link names from the Ada - entity names. - - All link names are in all lowercase letters. With the exception of - library procedure names, the mechanism used is simply to use the full - expanded Ada name with dots replaced by double underscores. For - example, suppose we have the following package spec: - - package QRS is - MN : Integer; - end QRS; - - The variable `MN' has a full expanded Ada name of `QRS.MN', so the - corresponding link name is `qrs__mn'. Of course if a `pragma Export' - is used this may be overridden: - - package Exports is - Var1 : Integer; - pragma Export (Var1, C, External_Name => "var1_name"); - Var2 : Integer; - pragma Export (Var2, C, Link_Name => "var2_link_name"); - end Exports; - - In this case, the link name for VAR1 is whatever link name the C - compiler would assign for the C function VAR1_NAME. This typically - would be either VAR1_NAME or _VAR1_NAME, depending on operating system - conventions, but other possibilities exist. The link name for VAR2 is - VAR2_LINK_NAME, and this is not operating system dependent. - - One exception occurs for library level procedures. A potential - ambiguity arises between the required name `_main' for the C main - program, and the name we would otherwise assign to an Ada library level - procedure called `Main' (which might well not be the main program). - - To avoid this ambiguity, we attach the prefix `_ada_' to such names. - So if we have a library level procedure such as - - procedure Hello (S : String); - - the external name of this procedure will be _ADA_HELLO. - -  - File: gnat_ug_unx.info, Node: Ada Mode for Glide, Next: Converting Ada Files to html with gnathtml, Prev: The External Symbol Naming Scheme of GNAT, Up: Other Utility Programs - - Ada Mode for `Glide' - ==================== - - The Glide mode for programming in Ada (both, Ada83 and Ada95) helps the - user in understanding existing code and facilitates writing new code. It - furthermore provides some utility functions for easier integration of - standard Emacs features when programming in Ada. - - General Features: - ----------------- - - * Full Integrated Development Environment : - - * support of 'project files' for the configuration (directories, - compilation options,...) - - * compiling and stepping through error messages. - - * running and debugging your applications within Glide. - - * easy to use for beginners by pull-down menus, - - * user configurable by many user-option variables. - - Ada Mode Features That Help Understanding Code: - ----------------------------------------------- - - * functions for easy and quick stepping through Ada code, - - * getting cross reference information for identifiers (e.g. find the - defining place by a keystroke), - - * displaying an index menu of types and subprograms and move point to - the chosen one, - - * automatic color highlighting of the various entities in Ada code. - - Glide Support for Writing Ada Code: - ----------------------------------- - - * switching between spec and body files with possible autogeneration - of body files, - - * automatic formating of subprograms parameter lists. - - * automatic smart indentation according to Ada syntax, - - * automatic completion of identifiers, - - * automatic casing of identifiers, keywords, and attributes, - - * insertion of statement templates, - - * filling comment paragraphs like filling normal text, - - For more information, please refer to the online Glide documentation - available in the Glide -> Help Menu. - -  - File: gnat_ug_unx.info, Node: Converting Ada Files to html with gnathtml, Next: Installing gnathtml, Prev: Ada Mode for Glide, Up: Other Utility Programs - - Converting Ada Files to html with `gnathtml' - ============================================ - - This `Perl' script allows Ada source files to be browsed using standard - Web browsers. For installation procedure, see the section *Note - Installing gnathtml::. - - Ada reserved keywords are highlighted in a bold font and Ada - comments in a blue font. Unless your program was compiled with the gcc - `-gnatx' switch to suppress the generation of cross-referencing - information, user defined variables and types will appear in a - different color; you will be able to click on any identifier and go to - its declaration. - - The command line is as follow: - $ perl gnathtml.pl [switches] ada-files - - You can pass it as many Ada files as you want. `gnathtml' will - generate an html file for every ada file, and a global file called - `index.htm'. This file is an index of every identifier defined in the - files. - - The available switches are the following ones : - - `-83' - Only the subset on the Ada 83 keywords will be highlighted, not - the full Ada 95 keywords set. - - `-cc COLOR' - This option allows you to change the color used for comments. The - default value is green. The color argument can be any name - accepted by html. - - `-d' - If the ada files depend on some other files (using for instance the - `with' command, the latter will also be converted to html. Only - the files in the user project will be converted to html, not the - files in the run-time library itself. - - `-D' - This command is the same as -d above, but `gnathtml' will also look - for files in the run-time library, and generate html files for - them. - - `-f' - By default, gnathtml will generate html links only for global - entities ('with'ed units, global variables and types,...). If you - specify the `-f' on the command line, then links will be generated - for local entities too. - - `-l NUMBER' - If this switch is provided and NUMBER is not 0, then `gnathtml' - will number the html files every NUMBER line. - - `-I DIR' - Specify a directory to search for library files (`.ali' files) and - source files. You can provide several -I switches on the command - line, and the directories will be parsed in the order of the - command line. - - `-o DIR' - Specify the output directory for html files. By default, gnathtml - will saved the generated html files in a subdirectory named - `html/'. - - `-p FILE' - If you are using Emacs and the most recent Emacs Ada mode, which - provides a full Integrated Development Environment for compiling, - checking, running and debugging applications, you may be using - `.adp' files to give the directories where Emacs can find sources - and object files. - - Using this switch, you can tell gnathtml to use these files. This - allows you to get an html version of your application, even if it - is spread over multiple directories. - - `-sc COLOR' - This option allows you to change the color used for symbol - definitions. The default value is red. The color argument can be - any name accepted by html. - - `-t FILE' - This switch provides the name of a file. This file contains a list - of file names to be converted, and the effect is exactly as though - they had appeared explicitly on the command line. This is the - recommended way to work around the command line length limit on - some systems. - -  - File: gnat_ug_unx.info, Node: Installing gnathtml, Prev: Converting Ada Files to html with gnathtml, Up: Other Utility Programs - - Installing `gnathtml' - ===================== - - `Perl' needs to be installed on your machine to run this script. - `Perl' is freely available for almost every architecture and Operating - System via the Internet. - - On Unix systems, you may want to modify the first line of the - script `gnathtml', to explicitly tell the Operating system where - Perl is. The syntax of this line is : - #!full_path_name_to_perl - - Alternatively, you may run the script using the following command line: - - $ perl gnathtml.pl [switches] files - -  - File: gnat_ug_unx.info, Node: Running and Debugging Ada Programs, Next: Inline Assembler, Prev: Other Utility Programs, Up: Top - - Running and Debugging Ada Programs - ********************************** - - This chapter discusses how to debug Ada programs. An incorrect Ada - program may be handled in three ways by the GNAT compiler: - - 1. The illegality may be a violation of the static semantics of Ada. - In that case GNAT diagnoses the constructs in the program that are - illegal. It is then a straightforward matter for the user to - modify those parts of the program. - - 2. The illegality may be a violation of the dynamic semantics of Ada. - In that case the program compiles and executes, but may generate - incorrect results, or may terminate abnormally with some exception. - - 3. When presented with a program that contains convoluted errors, GNAT - itself may terminate abnormally without providing full diagnostics - on the incorrect user program. - - * Menu: - - * The GNAT Debugger GDB:: - * Running GDB:: - * Introduction to GDB Commands:: - * Using Ada Expressions:: - * Calling User-Defined Subprograms:: - * Using the Next Command in a Function:: - * Ada Exceptions:: - * Ada Tasks:: - * Debugging Generic Units:: - * GNAT Abnormal Termination or Failure to Terminate:: - * Naming Conventions for GNAT Source Files:: - * Getting Internal Debugging Information:: - * Stack Traceback:: - -  - File: gnat_ug_unx.info, Node: The GNAT Debugger GDB, Next: Running GDB, Up: Running and Debugging Ada Programs - - The GNAT Debugger GDB - ===================== - - `GDB' is a general purpose, platform-independent debugger that can be - used to debug mixed-language programs compiled with `GCC', and in - particular is capable of debugging Ada programs compiled with GNAT. The - latest versions of `GDB' are Ada-aware and can handle complex Ada data - structures. - - The manual `Debugging with GDB' contains full details on the usage - of `GDB', including a section on its usage on programs. This manual - should be consulted for full details. The section that follows is a - brief introduction to the philosophy and use of `GDB'. - - When GNAT programs are compiled, the compiler optionally writes - debugging information into the generated object file, including - information on line numbers, and on declared types and variables. This - information is separate from the generated code. It makes the object - files considerably larger, but it does not add to the size of the - actual executable that will be loaded into memory, and has no impact on - run-time performance. The generation of debug information is triggered - by the use of the -g switch in the gcc or gnatmake command used to - carry out the compilations. It is important to emphasize that the use - of these options does not change the generated code. - - The debugging information is written in standard system formats that - are used by many tools, including debuggers and profilers. The format - of the information is typically designed to describe C types and - semantics, but GNAT implements a translation scheme which allows full - details about Ada types and variables to be encoded into these standard - C formats. Details of this encoding scheme may be found in the file - exp_dbug.ads in the GNAT source distribution. However, the details of - this encoding are, in general, of no interest to a user, since `GDB' - automatically performs the necessary decoding. - - When a program is bound and linked, the debugging information is - collected from the object files, and stored in the executable image of - the program. Again, this process significantly increases the size of - the generated executable file, but it does not increase the size of the - executable program itself. Furthermore, if this program is run in the - normal manner, it runs exactly as if the debug information were not - present, and takes no more actual memory. - - However, if the program is run under control of `GDB', the debugger - is activated. The image of the program is loaded, at which point it is - ready to run. If a run command is given, then the program will run - exactly as it would have if `GDB' were not present. This is a crucial - part of the `GDB' design philosophy. `GDB' is entirely non-intrusive - until a breakpoint is encountered. If no breakpoint is ever hit, the - program will run exactly as it would if no debugger were present. When - a breakpoint is hit, `GDB' accesses the debugging information and can - respond to user commands to inspect variables, and more generally to - report on the state of execution. - -  - File: gnat_ug_unx.info, Node: Running GDB, Next: Introduction to GDB Commands, Prev: The GNAT Debugger GDB, Up: Running and Debugging Ada Programs - - Running GDB - =========== - - The debugger can be launched directly and simply from `glide' or - through its graphical interface: `gvd'. It can also be used directly in - text mode. Here is described the basic use of `GDB' in text mode. All - the commands described below can be used in the `gvd' console window - eventhough there is usually other more graphical ways to achieve the - same goals. - - The command to run de graphical interface of the debugger is - $ gvd program - - The command to run `GDB' in text mode is - - $ gdb program - - where `program' is the name of the executable file. This activates the - debugger and results in a prompt for debugger commands. The simplest - command is simply `run', which causes the program to run exactly as if - the debugger were not present. The following section describes some of - the additional commands that can be given to `GDB'. - -  - File: gnat_ug_unx.info, Node: Introduction to GDB Commands, Next: Using Ada Expressions, Prev: Running GDB, Up: Running and Debugging Ada Programs - - Introduction to GDB Commands - ============================ - - `GDB' contains a large repertoire of commands. The manual `Debugging - with GDB' includes extensive documentation on the use of these - commands, together with examples of their use. Furthermore, the command - HELP invoked from within `GDB' activates a simple help facility which - summarizes the available commands and their options. In this section - we summarize a few of the most commonly used commands to give an idea - of what `GDB' is about. You should create a simple program with - debugging information and experiment with the use of these `GDB' - commands on the program as you read through the following section. - - `set args ARGUMENTS' - The ARGUMENTS list above is a list of arguments to be passed to - the program on a subsequent run command, just as though the - arguments had been entered on a normal invocation of the program. - The `set args' command is not needed if the program does not - require arguments. - - `run' - The `run' command causes execution of the program to start from - the beginning. If the program is already running, that is to say if - you are currently positioned at a breakpoint, then a prompt will - ask for confirmation that you want to abandon the current - execution and restart. - - `breakpoint LOCATION' - The breakpoint command sets a breakpoint, that is to say a point - at which execution will halt and `GDB' will await further - commands. LOCATION is either a line number within a file, given in - the format `file:linenumber', or it is the name of a subprogram. - If you request that a breakpoint be set on a subprogram that is - overloaded, a prompt will ask you to specify on which of those - subprograms you want to breakpoint. You can also specify that all - of them should be breakpointed. If the program is run and - execution encounters the breakpoint, then the program stops and - `GDB' signals that the breakpoint was encountered by printing the - line of code before which the program is halted. - - `breakpoint exception NAME' - A special form of the breakpoint command which breakpoints whenever - exception NAME is raised. If NAME is omitted, then a breakpoint - will occur when any exception is raised. - - `print EXPRESSION' - This will print the value of the given expression. Most simple Ada - expression formats are properly handled by `GDB', so the expression - can contain function calls, variables, operators, and attribute - references. - - `continue' - Continues execution following a breakpoint, until the next - breakpoint or the termination of the program. - - `step' - Executes a single line after a breakpoint. If the next statement - is a subprogram call, execution continues into (the first - statement of) the called subprogram. - - `next' - Executes a single line. If this line is a subprogram call, - executes and returns from the call. - - `list' - Lists a few lines around the current source location. In practice, - it is usually more convenient to have a separate edit window open - with the relevant source file displayed. Successive applications - of this command print subsequent lines. The command can be given - an argument which is a line number, in which case it displays a - few lines around the specified one. - - `backtrace' - Displays a backtrace of the call chain. This command is typically - used after a breakpoint has occurred, to examine the sequence of - calls that leads to the current breakpoint. The display includes - one line for each activation record (frame) corresponding to an - active subprogram. - - `up' - At a breakpoint, `GDB' can display the values of variables local - to the current frame. The command `up' can be used to examine the - contents of other active frames, by moving the focus up the stack, - that is to say from callee to caller, one frame at a time. - - `down' - Moves the focus of `GDB' down from the frame currently being - examined to the frame of its callee (the reverse of the previous - command), - - `frame N' - Inspect the frame with the given number. The value 0 denotes the - frame of the current breakpoint, that is to say the top of the - call stack. - - The above list is a very short introduction to the commands that - `GDB' provides. Important additional capabilities, including conditional - breakpoints, the ability to execute command sequences on a breakpoint, - the ability to debug at the machine instruction level and many other - features are described in detail in `Debugging with GDB'. Note that - most commands can be abbreviated (for example, c for continue, bt for - backtrace). - -  - File: gnat_ug_unx.info, Node: Using Ada Expressions, Next: Calling User-Defined Subprograms, Prev: Introduction to GDB Commands, Up: Running and Debugging Ada Programs - - Using Ada Expressions - ===================== - - `GDB' supports a fairly large subset of Ada expression syntax, with some - extensions. The philosophy behind the design of this subset is - - * That `GDB' should provide basic literals and access to operations - for arithmetic, dereferencing, field selection, indexing, and - subprogram calls, leaving more sophisticated computations to - subprograms written into the program (which therefore may be - called from `GDB'). - - * That type safety and strict adherence to Ada language restrictions - are not particularly important to the `GDB' user. - - * That brevity is important to the `GDB' user. - - Thus, for brevity, the debugger acts as if there were implicit - `with' and `use' clauses in effect for all user-written packages, thus - making it unnecessary to fully qualify most names with their packages, - regardless of context. Where this causes ambiguity, `GDB' asks the - user's intent. - - For details on the supported Ada syntax, see `Debugging with GDB'. - -  - File: gnat_ug_unx.info, Node: Calling User-Defined Subprograms, Next: Using the Next Command in a Function, Prev: Using Ada Expressions, Up: Running and Debugging Ada Programs - - Calling User-Defined Subprograms - ================================ - - An important capability of `GDB' is the ability to call user-defined - subprograms while debugging. This is achieved simply by entering a - subprogram call statement in the form: - - call subprogram-name (parameters) - - The keyword `call' can be omitted in the normal case where the - `subprogram-name' does not coincide with any of the predefined `GDB' - commands. - - The effect is to invoke the given subprogram, passing it the list of - parameters that is supplied. The parameters can be expressions and can - include variables from the program being debugged. The subprogram must - be defined at the library level within your program, and `GDB' will - call the subprogram within the environment of your program execution - (which means that the subprogram is free to access or even modify - variables within your program). - - The most important use of this facility is in allowing the inclusion - of debugging routines that are tailored to particular data structures - in your program. Such debugging routines can be written to provide a - suitably high-level description of an abstract type, rather than a - low-level dump of its physical layout. After all, the standard `GDB - print' command only knows the physical layout of your types, not their - abstract meaning. Debugging routines can provide information at the - desired semantic level and are thus enormously useful. - - For example, when debugging GNAT itself, it is crucial to have - access to the contents of the tree nodes used to represent the program - internally. But tree nodes are represented simply by an integer value - (which in turn is an index into a table of nodes). Using the `print' - command on a tree node would simply print this integer value, which is - not very useful. But the PN routine (defined in file treepr.adb in the - GNAT sources) takes a tree node as input, and displays a useful high - level representation of the tree node, which includes the syntactic - category of the node, its position in the source, the integers that - denote descendant nodes and parent node, as well as varied semantic - information. To study this example in more detail, you might want to - look at the body of the PN procedure in the stated file. - -  - File: gnat_ug_unx.info, Node: Using the Next Command in a Function, Next: Ada Exceptions, Prev: Calling User-Defined Subprograms, Up: Running and Debugging Ada Programs - - Using the Next Command in a Function - ==================================== - - When you use the `next' command in a function, the current source - location will advance to the next statement as usual. A special case - arises in the case of a `return' statement. - - Part of the code for a return statement is the "epilog" of the - function. This is the code that returns to the caller. There is only - one copy of this epilog code, and it is typically associated with the - last return statement in the function if there is more than one return. - In some implementations, this epilog is associated with the first - statement of the function. - - The result is that if you use the `next' command from a return - statement that is not the last return statement of the function you may - see a strange apparent jump to the last return statement or to the - start of the function. You should simply ignore this odd jump. The - value returned is always that from the first return statement that was - stepped through. - -  - File: gnat_ug_unx.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Using the Next Command in a Function, Up: Running and Debugging Ada Programs - - Breaking on Ada Exceptions - ========================== - - You can set breakpoints that trip when your program raises selected - exceptions. - - `break exception' - Set a breakpoint that trips whenever (any task in the) program - raises any exception. - - `break exception NAME' - Set a breakpoint that trips whenever (any task in the) program - raises the exception NAME. - - `break exception unhandled' - Set a breakpoint that trips whenever (any task in the) program - raises an exception for which there is no handler. - - `info exceptions' - `info exceptions REGEXP' - The `info exceptions' command permits the user to examine all - defined exceptions within Ada programs. With a regular expression, - REGEXP, as argument, prints out only those exceptions whose name - matches REGEXP. - -  - File: gnat_ug_unx.info, Node: Ada Tasks, Next: Debugging Generic Units, Prev: Ada Exceptions, Up: Running and Debugging Ada Programs - - Ada Tasks - ========= - - `GDB' allows the following task-related commands: - - `info tasks' - This command shows a list of current Ada tasks, as in the - following example: - - (gdb) info tasks - ID TID P-ID Thread Pri State Name - 1 8088000 0 807e000 15 Child Activation Wait main_task - 2 80a4000 1 80ae000 15 Accept/Select Wait b - 3 809a800 1 80a4800 15 Child Activation Wait a - * 4 80ae800 3 80b8000 15 Running c - - In this listing, the asterisk before the first task indicates it - to be the currently running task. The first column lists the task - ID that is used to refer to tasks in the following commands. - - `break LINESPEC task TASKID' - `break LINESPEC task TASKID if ...' - These commands are like the `break ... thread ...'. LINESPEC - specifies source lines. - - Use the qualifier `task TASKID' with a breakpoint command to - specify that you only want `GDB' to stop the program when a - particular Ada task reaches this breakpoint. TASKID is one of the - numeric task identifiers assigned by `GDB', shown in the first - column of the `info tasks' display. - - If you do not specify `task TASKID' when you set a breakpoint, the - breakpoint applies to _all_ tasks of your program. - - You can use the `task' qualifier on conditional breakpoints as - well; in this case, place `task TASKID' before the breakpoint - condition (before the `if'). - - `task TASKNO' - This command allows to switch to the task referred by TASKNO. In - particular, This allows to browse the backtrace of the specified - task. It is advised to switch back to the original task before - continuing execution otherwise the scheduling of the program may be - perturbated. - - For more detailed information on the tasking support, see `Debugging - with GDB'. - -  - File: gnat_ug_unx.info, Node: Debugging Generic Units, Next: GNAT Abnormal Termination or Failure to Terminate, Prev: Ada Tasks, Up: Running and Debugging Ada Programs - - Debugging Generic Units - ======================= - - GNAT always uses code expansion for generic instantiation. This means - that each time an instantiation occurs, a complete copy of the original - code is made, with appropriate substitutions of formals by actuals. - - It is not possible to refer to the original generic entities in - `GDB', but it is always possible to debug a particular instance of a - generic, by using the appropriate expanded names. For example, if we - have - - procedure g is - - generic package k is - procedure kp (v1 : in out integer); - end k; - - package body k is - procedure kp (v1 : in out integer) is - begin - v1 := v1 + 1; - end kp; - end k; - - package k1 is new k; - package k2 is new k; - - var : integer := 1; - - begin - k1.kp (var); - k2.kp (var); - k1.kp (var); - k2.kp (var); - end; - - Then to break on a call to procedure kp in the k2 instance, simply use - the command: - - (gdb) break g.k2.kp - - When the breakpoint occurs, you can step through the code of the - instance in the normal manner and examine the values of local - variables, as for other units. - -  - File: gnat_ug_unx.info, Node: GNAT Abnormal Termination or Failure to Terminate, Next: Naming Conventions for GNAT Source Files, Prev: Debugging Generic Units, Up: Running and Debugging Ada Programs - - GNAT Abnormal Termination or Failure to Terminate - ================================================= - - When presented with programs that contain serious errors in syntax or - semantics, GNAT may on rare occasions experience problems in - operation, such as aborting with a segmentation fault or illegal memory - access, raising an internal exception, terminating abnormally, or - failing to terminate at all. In such cases, you can activate various - features of GNAT that can help you pinpoint the construct in your - program that is the likely source of the problem. - - The following strategies are presented in increasing order of - difficulty, corresponding to your experience in using GNAT and your - familiarity with compiler internals. - - 1. Run `gcc' with the `-gnatf'. This first switch causes all errors - on a given line to be reported. In its absence, only the first - error on a line is displayed. - - The `-gnatdO' switch causes errors to be displayed as soon as they - are encountered, rather than after compilation is terminated. If - GNAT terminates prematurely or goes into an infinite loop, the - last error message displayed may help to pinpoint the culprit. - - 2. Run `gcc' with the `-v (verbose)' switch. In this mode, `gcc' - produces ongoing information about the progress of the compilation - and provides the name of each procedure as code is generated. This - switch allows you to find which Ada procedure was being compiled - when it encountered a code generation problem. - - 3. Run `gcc' with the `-gnatdc' switch. This is a GNAT specific - switch that does for the front-end what `-v' does for the back end. - The system prints the name of each unit, either a compilation unit - or nested unit, as it is being analyzed. - - 4. Finally, you can start `gdb' directly on the `gnat1' executable. - `gnat1' is the front-end of GNAT, and can be run independently - (normally it is just called from `gcc'). You can use `gdb' on - `gnat1' as you would on a C program (but *note The GNAT Debugger - GDB:: for caveats). The `where' command is the first line of - attack; the variable `lineno' (seen by `print lineno'), used by - the second phase of `gnat1' and by the `gcc' backend, indicates - the source line at which the execution stopped, and `input_file - name' indicates the name of the source file. - -  - File: gnat_ug_unx.info, Node: Naming Conventions for GNAT Source Files, Next: Getting Internal Debugging Information, Prev: GNAT Abnormal Termination or Failure to Terminate, Up: Running and Debugging Ada Programs - - Naming Conventions for GNAT Source Files - ======================================== - - In order to examine the workings of the GNAT system, the following - brief description of its organization may be helpful: - - * Files with prefix `sc' contain the lexical scanner. - - * All files prefixed with `par' are components of the parser. The - numbers correspond to chapters of the Ada 95 Reference Manual. For - example, parsing of select statements can be found in - `par-ch9.adb'. - - * All files prefixed with `sem' perform semantic analysis. The - numbers correspond to chapters of the Ada standard. For example, - all issues involving context clauses can be found in - `sem_ch10.adb'. In addition, some features of the language require - sufficient special processing to justify their own semantic files: - sem_aggr for aggregates, sem_disp for dynamic dispatching, etc. - - * All files prefixed with `exp' perform normalization and expansion - of the intermediate representation (abstract syntax tree, or AST). - these files use the same numbering scheme as the parser and - semantics files. For example, the construction of record - initialization procedures is done in `exp_ch3.adb'. - - * The files prefixed with `bind' implement the binder, which - verifies the consistency of the compilation, determines an order of - elaboration, and generates the bind file. - - * The files `atree.ads' and `atree.adb' detail the low-level data - structures used by the front-end. - - * The files `sinfo.ads' and `sinfo.adb' detail the structure of the - abstract syntax tree as produced by the parser. - - * The files `einfo.ads' and `einfo.adb' detail the attributes of all - entities, computed during semantic analysis. - - * Library management issues are dealt with in files with prefix - `lib'. - - * Ada files with the prefix `a-' are children of `Ada', as defined - in Annex A. - - * Files with prefix `i-' are children of `Interfaces', as defined in - Annex B. - - * Files with prefix `s-' are children of `System'. This includes - both language-defined children and GNAT run-time routines. - - * Files with prefix `g-' are children of `GNAT'. These are useful - general-purpose packages, fully documented in their - specifications. All the other `.c' files are modifications of - common `gcc' files. - -  - File: gnat_ug_unx.info, Node: Getting Internal Debugging Information, Next: Stack Traceback, Prev: Naming Conventions for GNAT Source Files, Up: Running and Debugging Ada Programs - - Getting Internal Debugging Information - ====================================== - - Most compilers have internal debugging switches and modes. GNAT does - also, except GNAT internal debugging switches and modes are not secret. - A summary and full description of all the compiler and binder debug - flags are in the file `debug.adb'. You must obtain the sources of the - compiler to see the full detailed effects of these flags. - - The switches that print the source of the program (reconstructed from - the internal tree) are of general interest for user programs, as are the - options to print the full internal tree, and the entity table (the - symbol table information). The reconstructed source provides a readable - version of the program after the front-end has completed analysis and - expansion, and is useful when studying the performance of specific - constructs. For example, constraint checks are indicated, complex - aggregates are replaced with loops and assignments, and tasking - primitives are replaced with run-time calls. - -  - File: gnat_ug_unx.info, Node: Stack Traceback, Prev: Getting Internal Debugging Information, Up: Running and Debugging Ada Programs - - Stack Traceback - =============== - - Traceback is a mechanism to display the sequence of subprogram calls - that leads to a specified execution point in a program. Often (but not - always) the execution point is an instruction at which an exception has - been raised. This mechanism is also known as stack unwinding because - it obtains its information by scanning the run-time stack and - recovering the activation records of all active subprograms. Stack - unwinding is one of the most important tools for program debugging. - - The first entry stored in traceback corresponds to the deepest calling - level, that is to say the subprogram currently executing the instruction - from which we want to obtain the traceback. - - Note that there is no runtime performance penalty when stack traceback - is enabled and no exception are raised during program execution. - - * Menu: - - * Non-Symbolic Traceback:: - * Symbolic Traceback:: - -  - File: gnat_ug_unx.info, Node: Non-Symbolic Traceback, Next: Symbolic Traceback, Up: Stack Traceback - - Non-Symbolic Traceback - ---------------------- - - Note: this feature is not supported on all platforms. See - `GNAT.Traceback spec in g-traceb.ads' for a complete list of supported - platforms. - - * Menu: - - * Tracebacks From an Unhandled Exception:: - * Tracebacks From Exception Occurrences (non-symbolic):: - * Tracebacks From Anywhere in a Program (non-symbolic):: - -  - File: gnat_ug_unx.info, Node: Tracebacks From an Unhandled Exception, Next: Tracebacks From Exception Occurrences (non-symbolic), Up: Non-Symbolic Traceback - - Tracebacks From an Unhandled Exception - ...................................... - - A runtime non-symbolic traceback is a list of addresses of call - instructions. To enable this feature you must use the `-E' - `gnatbind''s option. With this option a stack traceback is stored as - part of exception information. It is possible to retrieve this - information using the standard `Ada.Exception.Exception_Information' - routine. - - Let's have a look at a simple example: - - procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - $ gnatmake stb -bargs -E - $ stb - - Execution terminated by unhandled exception - Exception name: CONSTRAINT_ERROR - Message: stb.adb:5 - Call stack traceback locations: - 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - - As we see the traceback lists a sequence of addresses for the unhandled - exception `CONSTAINT_ERROR' raised in procedure P1. It is easy to guess - that this exception come from procedure P1. To translate these - addresses into the source lines where the calls appear, the `addr2line' - tool, described below, is invaluable. The use of this tool requires the - program to be compiled with debug information. - - $ gnatmake -g stb -bargs -E - $ stb - - Execution terminated by unhandled exception - Exception name: CONSTRAINT_ERROR - Message: stb.adb:5 - Call stack traceback locations: - 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - - $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 - 0x4011f1 0x77e892a4 - - 00401373 at d:/stb/stb.adb:5 - 0040138B at d:/stb/stb.adb:10 - 0040139C at d:/stb/stb.adb:14 - 00401335 at d:/stb/b~stb.adb:104 - 004011C4 at /build/.../crt1.c:200 - 004011F1 at /build/.../crt1.c:222 - 77E892A4 in ?? at ??:0 - - `addr2line' has a number of other useful options: - - `--functions' - to get the function name corresponding to any location - - `--demangle=gnat' - to use the gnat decoding mode for the function names. Note that - for binutils version 2.9.x the option is simply `--demangle'. - - $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b - 0x40139c 0x401335 0x4011c4 0x4011f1 - - 00401373 in stb.p1 at d:/stb/stb.adb:5 - 0040138B in stb.p2 at d:/stb/stb.adb:10 - 0040139C in stb at d:/stb/stb.adb:14 - 00401335 in main at d:/stb/b~stb.adb:104 - 004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200 - 004011F1 in at /build/.../crt1.c:222 - - From this traceback we can see that the exception was raised in - `stb.adb' at line 5, which was reached from a procedure call in - `stb.adb' at line 10, and so on. The `b~std.adb' is the binder file, - which contains the call to the main program. *note Running gnatbind::. - The remaining entries are assorted runtime routines, and the output - will vary from platform to platform. - - It is also possible to use `GDB' with these traceback addresses to debug - the program. For example, we can break at a given code location, as - reported in the stack traceback: - - $ gdb -nw stb - - (gdb) break *0x401373 - Breakpoint 1 at 0x401373: file stb.adb, line 5. - - It is important to note that the stack traceback addresses do not - change when debug information is included. This is particularly useful - because it makes it possible to release software without debug - information (to minimize object size), get a field report that includes - a stack traceback whenever an internal bug occurs, and then be able to - retrieve the sequence of calls with the same program compiled with - debug information. - -  - File: gnat_ug_unx.info, Node: Tracebacks From Exception Occurrences (non-symbolic), Next: Tracebacks From Anywhere in a Program (non-symbolic), Prev: Tracebacks From an Unhandled Exception, Up: Non-Symbolic Traceback - - Tracebacks From Exception Occurrences - ..................................... - - Non-symbolic tracebacks are obtained by using the `-E' binder argument. - The stack traceback is attached to the exception information string, - and can be retrieved in an exception handler within the Ada program, by - means of the Ada95 facilities defined in `Ada.Exceptions'. Here is a - simple example: - - with Ada.Text_IO; - with Ada.Exceptions; - - procedure STB is - - use Ada; - use Ada.Exceptions; - - procedure P1 is - K : Positive := 1; - begin - K := K - 1; - exception - when E : others => - Text_IO.Put_Line (Exception_Information (E)); - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - This program will output: - - $ stb - - Exception name: CONSTRAINT_ERROR - Message: stb.adb:12 - Call stack traceback locations: - 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 - -  - File: gnat_ug_unx.info, Node: Tracebacks From Anywhere in a Program (non-symbolic), Prev: Tracebacks From Exception Occurrences (non-symbolic), Up: Non-Symbolic Traceback - - Tracebacks From Anywhere in a Program - ..................................... - - It is also possible to retrieve a stack traceback from anywhere in a - program. For this you need to use the `GNAT.Traceback' API. This - package includes a procedure called `Call_Chain' that computes a - complete stack traceback, as well as useful display procedures - described below. It is not necessary to use the `-E gnatbind' option in - this case, because the stack traceback mechanism is invoked explicitly. - - In the following example we compute a traceback at a specific location - in the program, and we display it using `GNAT.Debug_Utilities.Image' to - convert addresses to strings: - - with Ada.Text_IO; - with GNAT.Traceback; - with GNAT.Debug_Utilities; - - procedure STB is - - use Ada; - use GNAT; - use GNAT.Traceback; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - - Text_IO.Put ("In STB.P1 : "); - - for K in 1 .. Len loop - Text_IO.Put (Debug_Utilities.Image (TB (K))); - Text_IO.Put (' '); - end loop; - - Text_IO.New_Line; - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - $ gnatmake stb - $ stb - - In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# - 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# - -  - File: gnat_ug_unx.info, Node: Symbolic Traceback, Prev: Non-Symbolic Traceback, Up: Stack Traceback - - Symbolic Traceback - ------------------ - - A symbolic traceback is a stack traceback in which procedure names are - associated with each code location. - - Note that this feature is not supported on all platforms. See - `GNAT.Traceback.Symbolic spec in g-trasym.ads' for a complete list of - currently supported platforms. - - Note that the symbolic traceback requires that the program be compiled - with debug information. If it is not compiled with debug information - only the non-symbolic information will be valid. - - * Menu: - - * Tracebacks From Exception Occurrences (symbolic):: - * Tracebacks From Anywhere in a Program (symbolic):: - -  - File: gnat_ug_unx.info, Node: Tracebacks From Exception Occurrences (symbolic), Next: Tracebacks From Anywhere in a Program (symbolic), Up: Symbolic Traceback - - Tracebacks From Exception Occurrences - ..................................... - - with Ada.Text_IO; - with GNAT.Traceback.Symbolic; - - procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - procedure P3 is - begin - P2; - end P3; - - begin - P3; - exception - when E : others => - Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); - end STB; - - $ gnatmake -g stb -bargs -E -largs -lgnat -laddr2line -lintl - $ stb - - 0040149F in stb.p1 at stb.adb:8 - 004014B7 in stb.p2 at stb.adb:13 - 004014CF in stb.p3 at stb.adb:18 - 004015DD in ada.stb at stb.adb:22 - 00401461 in main at b~stb.adb:168 - 004011C4 in __mingw_CRTStartup at crt1.c:200 - 004011F1 in mainCRTStartup at crt1.c:222 - 77E892A4 in ?? at ??:0 - - The exact sequence of linker options may vary from platform to platform. - The above `-largs' section is for Windows platforms. By contrast, under - Unix there is no need for the `-largs' section. Differences across - platforms are due to details of linker implementation. - -  - File: gnat_ug_unx.info, Node: Tracebacks From Anywhere in a Program (symbolic), Prev: Tracebacks From Exception Occurrences (symbolic), Up: Symbolic Traceback - - Tracebacks From Anywhere in a Program - ..................................... - - It is possible to get a symbolic stack traceback from anywhere in a - program, just as for non-symbolic tracebacks. The first step is to - obtain a non-symbolic traceback, and then call `Symbolic_Traceback' to - compute the symbolic information. Here is an example: - - with Ada.Text_IO; - with GNAT.Traceback; - with GNAT.Traceback.Symbolic; - - procedure STB is - - use Ada; - use GNAT.Traceback; - use GNAT.Traceback.Symbolic; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - -  - File: gnat_ug_unx.info, Node: Inline Assembler, Next: Performance Considerations, Prev: Running and Debugging Ada Programs, Up: Top - - Inline Assembler - **************** - - If you need to write low-level software that interacts directly with - the hardware, Ada provides two ways to incorporate assembly language - code into your program. First, you can import and invoke external - routines written in assembly language, an Ada feature fully supported - by GNAT. However, for small sections of code it may be simpler or more - efficient to include assembly language statements directly in your Ada - source program, using the facilities of the implementation-defined - package `System.Machine_Code', which incorporates the gcc Inline - Assembler. The Inline Assembler approach offers a number of - advantages, including the following: - - * No need to use non-Ada tools - - * Consistent interface over different targets - - * Automatic usage of the proper calling conventions - - * Access to Ada constants and variables - - * Definition of intrinsic routines - - * Possibility of inlining a subprogram comprising assembler code - - * Code optimizer can take Inline Assembler code into account - - This chapter presents a series of examples to show you how to use - the Inline Assembler. Although it focuses on the Intel x86, the - general approach applies also to other processors. It is assumed that - you are familiar with Ada and with assembly language programming. - - * Menu: - - * Basic Assembler Syntax:: - * A Simple Example of Inline Assembler:: - * Output Variables in Inline Assembler:: - * Input Variables in Inline Assembler:: - * Inlining Inline Assembler Code:: - * Other Asm Functionality:: - * A Complete Example:: - -  - File: gnat_ug_unx.info, Node: Basic Assembler Syntax, Next: A Simple Example of Inline Assembler, Up: Inline Assembler - - Basic Assembler Syntax - ====================== - - The assembler used by GNAT and gcc is based not on the Intel assembly - language, but rather on a language that descends from the AT&T Unix - assembler _as_ (and which is often referred to as "AT&T syntax"). The - following table summarizes the main features of _as_ syntax and points - out the differences from the Intel conventions. See the gcc _as_ and - _gas_ (an _as_ macro pre-processor) documentation for further - information. - - Register names - gcc / _as_: Prefix with "%"; for example `%eax' - Intel: No extra punctuation; for example `eax' - - Immediate operand - gcc / _as_: Prefix with "$"; for example `$4' - Intel: No extra punctuation; for example `4' - - Address - gcc / _as_: Prefix with "$"; for example `$loc' - Intel: No extra punctuation; for example `loc' - - Memory contents - gcc / _as_: No extra punctuation; for example `loc' - Intel: Square brackets; for example `[loc]' - - Register contents - gcc / _as_: Parentheses; for example `(%eax)' - Intel: Square brackets; for example `[eax]' - - Hexadecimal numbers - gcc / _as_: Leading "0x" (C language syntax); for example `0xA0' - Intel: Trailing "h"; for example `A0h' - - Operand size - gcc / _as_: Explicit in op code; for example `movw' to move a - 16-bit word - Intel: Implicit, deduced by assembler; for example `mov' - - Instruction repetition - gcc / _as_: Split into two lines; for example - `rep' - `stosl' - Intel: Keep on one line; for example `rep stosl' - - Order of operands - gcc / _as_: Source first; for example `movw $4, %eax' - Intel: Destination first; for example `mov eax, 4' - -  - File: gnat_ug_unx.info, Node: A Simple Example of Inline Assembler, Next: Output Variables in Inline Assembler, Prev: Basic Assembler Syntax, Up: Inline Assembler - - A Simple Example of Inline Assembler - ==================================== - - The following example will generate a single assembly language - statement, `nop', which does nothing. Despite its lack of run-time - effect, the example will be useful in illustrating the basics of the - Inline Assembler facility. - - with System.Machine_Code; use System.Machine_Code; - procedure Nothing is - begin - Asm ("nop"); - end Nothing; - - `Asm' is a procedure declared in package `System.Machine_Code'; here - it takes one parameter, a _template string_ that must be a static - expression and that will form the generated instruction. `Asm' may be - regarded as a compile-time procedure that parses the template string - and additional parameters (none here), from which it generates a - sequence of assembly language instructions. - - The examples in this chapter will illustrate several of the forms - for invoking `Asm'; a complete specification of the syntax is found in - the `GNAT Reference Manual'. - - Under the standard GNAT conventions, the `Nothing' procedure should - be in a file named `nothing.adb'. You can build the executable in the - usual way: - gnatmake nothing - However, the interesting aspect of this example is not its run-time - behavior but rather the generated assembly code. To see this output, - invoke the compiler as follows: - gcc -c -S -fomit-frame-pointer -gnatp `nothing.adb' - where the options are: - - `-c' - compile only (no bind or link) - - `-S' - generate assembler listing - - `-fomit-frame-pointer' - do not set up separate stack frames - - `-gnatp' - do not add runtime checks - - This gives a human-readable assembler version of the code. The - resulting file will have the same name as the Ada source file, but with - a `.s' extension. In our example, the file `nothing.s' has the - following contents: - - .file "nothing.adb" - gcc2_compiled.: - ___gnu_compiled_ada: - .text - .align 4 - .globl __ada_nothing - __ada_nothing: - #APP - nop - #NO_APP - jmp L1 - .align 2,0x90 - L1: - ret - - The assembly code you included is clearly indicated by the compiler, - between the `#APP' and `#NO_APP' delimiters. The character before the - 'APP' and 'NOAPP' can differ on different targets. For example, Linux - uses '#APP' while on NT you will see '/APP'. - - If you make a mistake in your assembler code (such as using the - wrong size modifier, or using a wrong operand for the instruction) GNAT - will report this error in a temporary file, which will be deleted when - the compilation is finished. Generating an assembler file will help in - such cases, since you can assemble this file separately using the _as_ - assembler that comes with gcc. - - Assembling the file using the command - - as `nothing.s' - - will give you error messages whose lines correspond to the assembler - input file, so you can easily find and correct any mistakes you made. - If there are no errors, _as_ will generate an object file `nothing.out'. - -  - File: gnat_ug_unx.info, Node: Output Variables in Inline Assembler, Next: Input Variables in Inline Assembler, Prev: A Simple Example of Inline Assembler, Up: Inline Assembler - - Output Variables in Inline Assembler - ==================================== - - The examples in this section, showing how to access the processor - flags, illustrate how to specify the destination operands for assembly - language statements. - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags; - - In order to have a nicely aligned assembly listing, we have separated - multiple assembler statements in the Asm template string with linefeed - (ASCII.LF) and horizontal tab (ASCII.HT) characters. The resulting - section of the assembly output file is: - - #APP - pushfl - popl %eax - movl %eax, -40(%ebp) - #NO_APP - - It would have been legal to write the Asm invocation as: - - Asm ("pushfl popl %%eax movl %%eax, %0") - - but in the generated assembler file, this would come out as: - - #APP - pushfl popl %eax movl %eax, -40(%ebp) - #NO_APP - - which is not so convenient for the human reader. - - We use Ada comments at the end of each line to explain what the - assembler instructions actually do. This is a useful convention. - - When writing Inline Assembler instructions, you need to precede each - register and variable name with a percent sign. Since the assembler - already requires a percent sign at the beginning of a register name, - you need two consecutive percent signs for such names in the Asm - template string, thus `%%eax'. In the generated assembly code, one of - the percent signs will be stripped off. - - Names such as `%0', `%1', `%2', etc., denote input or output - variables: operands you later define using `Input' or `Output' - parameters to `Asm'. An output variable is illustrated in the third - statement in the Asm template string: - movl %%eax, %0 - The intent is to store the contents of the eax register in a - variable that can be accessed in Ada. Simply writing `movl %%eax, - Flags' would not necessarily work, since the compiler might optimize by - using a register to hold Flags, and the expansion of the `movl' - instruction would not be aware of this optimization. The solution is - not to store the result directly but rather to advise the compiler to - choose the correct operand form; that is the purpose of the `%0' output - variable. - - Information about the output variable is supplied in the `Outputs' - parameter to `Asm': - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - - The output is defined by the `Asm_Output' attribute of the target - type; the general format is - Type'Asm_Output (constraint_string, variable_name) - - The constraint string directs the compiler how to store/access the - associated variable. In the example - Unsigned_32'Asm_Output ("=m", Flags); - the `"m"' (memory) constraint tells the compiler that the variable - `Flags' should be stored in a memory variable, thus preventing the - optimizer from keeping it in a register. In contrast, - Unsigned_32'Asm_Output ("=r", Flags); - uses the `"r"' (register) constraint, telling the compiler to store - the variable in a register. - - If the constraint is preceded by the equal character (*=*), it tells - the compiler that the variable will be used to store data into it. - - In the `Get_Flags' example, we used the "g" (global) constraint, - allowing the optimizer to choose whatever it deems best. - - There are a fairly large number of constraints, but the ones that - are most useful (for the Intel x86 processor) are the following: - - `=' - output constraint - - `g' - global (i.e. can be stored anywhere) - - `m' - in memory - - `I' - a constant - - `a' - use eax - - `b' - use ebx - - `c' - use ecx - - `d' - use edx - - `S' - use esi - - `D' - use edi - - `r' - use one of eax, ebx, ecx or edx - - `q' - use one of eax, ebx, ecx, edx, esi or edi - - The full set of constraints is described in the gcc and _as_ - documentation; note that it is possible to combine certain constraints - in one constraint string. - - You specify the association of an output variable with an assembler - operand through the `%'_n_ notation, where _n_ is a non-negative - integer. Thus in - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - - `%0' will be replaced in the expanded code by the appropriate operand, - whatever the compiler decided for the `Flags' variable. - - In general, you may have any number of output variables: - * Count the operands starting at 0; thus `%0', `%1', etc. - - * Specify the `Outputs' parameter as a parenthesized comma-separated - list of `Asm_Output' attributes - - For example: - Asm ("movl %%eax, %0" & LF & HT & - "movl %%ebx, %1" & LF & HT & - "movl %%ecx, %2", - Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A - Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B - Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C - - where `Var_A', `Var_B', and `Var_C' are variables in the Ada program. - - As a variation on the `Get_Flags' example, we can use the - constraints string to direct the compiler to store the eax register - into the `Flags' variable, instead of including the store instruction - explicitly in the `Asm' template string: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags_2 is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax", -- save flags in eax - Outputs => Unsigned_32'Asm_Output ("=a", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags_2; - - The `"a"' constraint tells the compiler that the `Flags' variable will - come from the eax register. Here is the resulting code: - - #APP - pushfl - popl %eax - #NO_APP - movl %eax,-40(%ebp) - - The compiler generated the store of eax into Flags after expanding the - assembler code. - - Actually, there was no need to pop the flags into the eax register; - more simply, we could just pop the flags directly into the program - variable: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags_3 is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "pop %0", -- save flags in Flags - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags_3; - -  - File: gnat_ug_unx.info, Node: Input Variables in Inline Assembler, Next: Inlining Inline Assembler Code, Prev: Output Variables in Inline Assembler, Up: Inline Assembler - - Input Variables in Inline Assembler - =================================== - - The example in this section illustrates how to specify the source - operands for assembly language statements. The program simply - increments its input value by 1: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Increment is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Inputs => Unsigned_32'Asm_Input ("a", Value), - Outputs => Unsigned_32'Asm_Output ("=a", Result)); - return Result; - end Incr; - - Value : Unsigned_32; - - begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Incr (Value); - Put_Line ("Value after is" & Value'Img); - end Increment; - - The `Outputs' parameter to `Asm' specifies that the result will be - in the eax register and that it is to be stored in the `Result' - variable. - - The `Inputs' parameter looks much like the `Outputs' parameter, but - with an `Asm_Input' attribute. The `"="' constraint, indicating an - output value, is not present. - - You can have multiple input variables, in the same way that you can - have more than one output variable. - - The parameter count (%0, %1) etc, now starts at the first input - statement, and continues with the output statements. When both - parameters use the same variable, the compiler will treat them as the - same %n operand, which is the case here. - - Just as the `Outputs' parameter causes the register to be stored - into the target variable after execution of the assembler statements, - so does the `Inputs' parameter cause its variable to be loaded into the - register before execution of the assembler statements. - - Thus the effect of the `Asm' invocation is: - 1. load the 32-bit value of `Value' into eax - - 2. execute the `incl %eax' instruction - - 3. store the contents of eax into the `Result' variable - - The resulting assembler file (with `-O2' optimization) contains: - _increment__incr.1: - subl $4,%esp - movl 8(%esp),%eax - #APP - incl %eax - #NO_APP - movl %eax,%edx - movl %ecx,(%esp) - addl $4,%esp - ret - -  - File: gnat_ug_unx.info, Node: Inlining Inline Assembler Code, Next: Other Asm Functionality, Prev: Input Variables in Inline Assembler, Up: Inline Assembler - - Inlining Inline Assembler Code - ============================== - - For a short subprogram such as the `Incr' function in the previous - section, the overhead of the call and return (creating / deleting the - stack frame) can be significant, compared to the amount of code in the - subprogram body. A solution is to apply Ada's `Inline' pragma to the - subprogram, which directs the compiler to expand invocations of the - subprogram at the point(s) of call, instead of setting up a stack frame - for out-of-line calls. Here is the resulting program: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Increment_2 is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Inputs => Unsigned_32'Asm_Input ("a", Value), - Outputs => Unsigned_32'Asm_Output ("=a", Result)); - return Result; - end Incr; - pragma Inline (Increment); - - Value : Unsigned_32; - - begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Increment (Value); - Put_Line ("Value after is" & Value'Img); - end Increment_2; - - Compile the program with both optimization (`-O2') and inlining - enabled (`-gnatpn' instead of `-gnatp'). - - The `Incr' function is still compiled as usual, but at the point in - `Increment' where our function used to be called: - - pushl %edi - call _increment__incr.1 - - the code for the function body directly appears: - - movl %esi,%eax - #APP - incl %eax - #NO_APP - movl %eax,%edx - - thus saving the overhead of stack frame setup and an out-of-line call. - -  - File: gnat_ug_unx.info, Node: Other Asm Functionality, Next: A Complete Example, Prev: Inlining Inline Assembler Code, Up: Inline Assembler - - Other `Asm' Functionality - ========================= - - This section describes two important parameters to the `Asm' procedure: - `Clobber', which identifies register usage; and `Volatile', which - inhibits unwanted optimizations. - - * Menu: - - * The Clobber Parameter:: - * The Volatile Parameter:: - -  - File: gnat_ug_unx.info, Node: The Clobber Parameter, Next: The Volatile Parameter, Up: Other Asm Functionality - - The `Clobber' Parameter - ----------------------- - - One of the dangers of intermixing assembly language and a compiled - language such as Ada is that the compiler needs to be aware of which - registers are being used by the assembly code. In some cases, such as - the earlier examples, the constraint string is sufficient to indicate - register usage (e.g. "a" for the eax register). But more generally, the - compiler needs an explicit identification of the registers that are - used by the Inline Assembly statements. - - Using a register that the compiler doesn't know about could be a - side effect of an instruction (like `mull' storing its result in both - eax and edx). It can also arise from explicit register usage in your - assembly code; for example: - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out)); - - where the compiler (since it does not analyze the `Asm' template string) - does not know you are using the ebx register. - - In such cases you need to supply the `Clobber' parameter to `Asm', - to identify the registers that will be used by your assembly code: - - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Clobber => "ebx"); - - The Clobber parameter is a static string expression specifying the - register(s) you are using. Note that register names are _not_ prefixed - by a percent sign. Also, if more than one register is used then their - names are separated by commas; e.g., `"eax, ebx"' - - The `Clobber' parameter has several additional uses: - 1. Use the "register" name `cc' to indicate that flags might have - changed - - 2. Use the "register" name `memory' if you changed a memory location - -  - File: gnat_ug_unx.info, Node: The Volatile Parameter, Prev: The Clobber Parameter, Up: Other Asm Functionality - - The `Volatile' Parameter - ------------------------ - - Compiler optimizations in the presence of Inline Assembler may - sometimes have unwanted effects. For example, when an `Asm' invocation - with an input variable is inside a loop, the compiler might move the - loading of the input variable outside the loop, regarding it as a - one-time initialization. - - If this effect is not desired, you can disable such optimizations by - setting the `Volatile' parameter to `True'; for example: - - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Clobber => "ebx", - Volatile => True); - - By default, `Volatile' is set to `False' unless there is no `Outputs' - parameter. - - Although setting `Volatile' to `True' prevents unwanted - optimizations, it will also disable other optimizations that might be - important for efficiency. In general, you should set `Volatile' to - `True' only if the compiler's optimizations have created problems. - -  - File: gnat_ug_unx.info, Node: A Complete Example, Prev: Other Asm Functionality, Up: Inline Assembler - - A Complete Example - ================== - - This section contains a complete program illustrating a realistic usage - of GNAT's Inline Assembler capabilities. It comprises a main procedure - `Check_CPU' and a package `Intel_CPU'. The package declares a - collection of functions that detect the properties of the 32-bit x86 - processor that is running the program. The main procedure invokes - these functions and displays the information. - - The Intel_CPU package could be enhanced by adding functions to - detect the type of x386 co-processor, the processor caching options and - special operations such as the SIMD extensions. - - Although the Intel_CPU package has been written for 32-bit Intel - compatible CPUs, it is OS neutral. It has been tested on DOS, - Windows/NT and Linux. - - * Menu: - - * Check_CPU Procedure:: - * Intel_CPU Package Specification:: - * Intel_CPU Package Body:: - -  - File: gnat_ug_unx.info, Node: Check_CPU Procedure, Next: Intel_CPU Package Specification, Up: A Complete Example - - `Check_CPU' Procedure - --------------------- - - --------------------------------------------------------------------- - -- -- - -- Uses the Intel_CPU package to identify the CPU the program is -- - -- running on, and some of the features it supports. -- - -- -- - --------------------------------------------------------------------- - - with Intel_CPU; -- Intel CPU detection functions - with Ada.Text_IO; -- Standard text I/O - with Ada.Command_Line; -- To set the exit status - - procedure Check_CPU is - - Type_Found : Boolean := False; - -- Flag to indicate that processor was identified - - Features : Intel_CPU.Processor_Features; - -- The processor features - - Signature : Intel_CPU.Processor_Signature; - -- The processor type signature - - begin - - ----------------------------------- - -- Display the program banner. -- - ----------------------------------- - - Ada.Text_IO.Put_Line (Ada.Command_Line.Command_Name & - ": check Intel CPU version and features, v1.0"); - Ada.Text_IO.Put_Line ("distribute freely, but no warranty whatsoever"); - Ada.Text_IO.New_Line; - - ----------------------------------------------------------------------- - -- We can safely start with the assumption that we are on at least -- - -- a x386 processor. If the CPUID instruction is present, then we -- - -- have a later processor type. -- - ----------------------------------------------------------------------- - - if Intel_CPU.Has_CPUID = False then - - -- No CPUID instruction, so we assume this is indeed a x386 - -- processor. We can still check if it has a FP co-processor. - if Intel_CPU.Has_FPU then - Ada.Text_IO.Put_Line - ("x386-type processor with a FP co-processor"); - else - Ada.Text_IO.Put_Line - ("x386-type processor without a FP co-processor"); - end if; -- check for FPU - - -- Program done - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - return; - - end if; -- check for CPUID - - ----------------------------------------------------------------------- - -- If CPUID is supported, check if this is a true Intel processor, -- - -- if it is not, display a warning. -- - ----------------------------------------------------------------------- - - if Intel_CPU.Vendor_ID /= Intel_CPU.Intel_Processor then - Ada.Text_IO.Put_Line ("*** This is a Intel compatible processor"); - Ada.Text_IO.Put_Line ("*** Some information may be incorrect"); - end if; -- check if Intel - - ---------------------------------------------------------------------- - -- With the CPUID instruction present, we can assume at least a -- - -- x486 processor. If the CPUID support level is < 1 then we have -- - -- to leave it at that. -- - ---------------------------------------------------------------------- - - if Intel_CPU.CPUID_Level < 1 then - - -- Ok, this is a x486 processor. we still can get the Vendor ID - Ada.Text_IO.Put_Line ("x486-type processor"); - Ada.Text_IO.Put_Line ("Vendor ID is " & Intel_CPU.Vendor_ID); - - -- We can also check if there is a FPU present - if Intel_CPU.Has_FPU then - Ada.Text_IO.Put_Line ("Floating-Point support"); - else - Ada.Text_IO.Put_Line ("No Floating-Point support"); - end if; -- check for FPU - - -- Program done - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - return; - - end if; -- check CPUID level - - --------------------------------------------------------------------- - -- With a CPUID level of 1 we can use the processor signature to -- - -- determine it's exact type. -- - --------------------------------------------------------------------- - - Signature := Intel_CPU.Signature; - - ---------------------------------------------------------------------- - -- Ok, now we go into a lot of messy comparisons to get the -- - -- processor type. For clarity, no attememt to try to optimize the -- - -- comparisons has been made. Note that since Intel_CPU does not -- - -- support getting cache info, we cannot distinguish between P5 -- - -- and Celeron types yet. -- - ---------------------------------------------------------------------- - - -- x486SL - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486SL processor"); - end if; - - -- x486DX2 Write-Back - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#0111# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Write-Back Enhanced x486DX2 processor"); - end if; - - -- x486DX4 - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#1000# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486DX4 processor"); - end if; - - -- x486DX4 Overdrive - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0100# and - Signature.Model = 2#1000# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486DX4 OverDrive processor"); - end if; - - -- Pentium (60, 66) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium processor (60, 66)"); - end if; - - -- Pentium (75, 90, 100, 120, 133, 150, 166, 200) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0010# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium processor (75, 90, 100, 120, 133, 150, 166, 200)"); - end if; - - -- Pentium OverDrive (60, 66) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium OverDrive processor (60, 66)"); - end if; - - -- Pentium OverDrive (75, 90, 100, 120, 133, 150, 166, 200) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0010# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive cpu (75, 90, 100, 120, 133, 150, 166, 200)"); - end if; - - -- Pentium OverDrive processor for x486 processor-based systems - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive processor for x486 processor-based systems"); - end if; - - -- Pentium processor with MMX technology (166, 200) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium processor with MMX technology (166, 200)"); - end if; - - -- Pentium OverDrive with MMX for Pentium (75, 90, 100, 120, 133) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive processor with MMX " & - "technology for Pentium processor (75, 90, 100, 120, 133)"); - end if; - - -- Pentium Pro processor - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium Pro processor"); - end if; - - -- Pentium II processor, model 3 - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium II processor, model 3"); - end if; - - -- Pentium II processor, model 5 or Celeron processor - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0101# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium II processor, model 5 or Celeron processor"); - end if; - - -- Pentium Pro OverDrive processor - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0110# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium Pro OverDrive processor"); - end if; - - -- If no type recognized, we have an unknown. Display what - -- we _do_ know - if Type_Found = False then - Ada.Text_IO.Put_Line ("Unknown processor"); - end if; - - ----------------------------------------- - -- Display processor stepping level. -- - ----------------------------------------- - - Ada.Text_IO.Put_Line ("Stepping level:" & Signature.Stepping'Img); - - --------------------------------- - -- Display vendor ID string. -- - --------------------------------- - - Ada.Text_IO.Put_Line ("Vendor ID: " & Intel_CPU.Vendor_ID); - - ------------------------------------ - -- Get the processors features. -- - ------------------------------------ - - Features := Intel_CPU.Features; - - ----------------------------- - -- Check for a FPU unit. -- - ----------------------------- - - if Features.FPU = True then - Ada.Text_IO.Put_Line ("Floating-Point unit available"); - else - Ada.Text_IO.Put_Line ("no Floating-Point unit"); - end if; -- check for FPU - - -------------------------------- - -- List processor features. -- - -------------------------------- - - Ada.Text_IO.Put_Line ("Supported features: "); - - -- Virtual Mode Extension - if Features.VME = True then - Ada.Text_IO.Put_Line (" VME - Virtual Mode Extension"); - end if; - - -- Debugging Extension - if Features.DE = True then - Ada.Text_IO.Put_Line (" DE - Debugging Extension"); - end if; - - -- Page Size Extension - if Features.PSE = True then - Ada.Text_IO.Put_Line (" PSE - Page Size Extension"); - end if; - - -- Time Stamp Counter - if Features.TSC = True then - Ada.Text_IO.Put_Line (" TSC - Time Stamp Counter"); - end if; - - -- Model Specific Registers - if Features.MSR = True then - Ada.Text_IO.Put_Line (" MSR - Model Specific Registers"); - end if; - - -- Physical Address Extension - if Features.PAE = True then - Ada.Text_IO.Put_Line (" PAE - Physical Address Extension"); - end if; - - -- Machine Check Extension - if Features.MCE = True then - Ada.Text_IO.Put_Line (" MCE - Machine Check Extension"); - end if; - - -- CMPXCHG8 instruction supported - if Features.CX8 = True then - Ada.Text_IO.Put_Line (" CX8 - CMPXCHG8 instruction"); - end if; - - -- on-chip APIC hardware support - if Features.APIC = True then - Ada.Text_IO.Put_Line (" APIC - on-chip APIC hardware support"); - end if; - - -- Fast System Call - if Features.SEP = True then - Ada.Text_IO.Put_Line (" SEP - Fast System Call"); - end if; - - -- Memory Type Range Registers - if Features.MTRR = True then - Ada.Text_IO.Put_Line (" MTTR - Memory Type Range Registers"); - end if; - - -- Page Global Enable - if Features.PGE = True then - Ada.Text_IO.Put_Line (" PGE - Page Global Enable"); - end if; - - -- Machine Check Architecture - if Features.MCA = True then - Ada.Text_IO.Put_Line (" MCA - Machine Check Architecture"); - end if; - - -- Conditional Move Instruction Supported - if Features.CMOV = True then - Ada.Text_IO.Put_Line - (" CMOV - Conditional Move Instruction Supported"); - end if; - - -- Page Attribute Table - if Features.PAT = True then - Ada.Text_IO.Put_Line (" PAT - Page Attribute Table"); - end if; - - -- 36-bit Page Size Extension - if Features.PSE_36 = True then - Ada.Text_IO.Put_Line (" PSE_36 - 36-bit Page Size Extension"); - end if; - - -- MMX technology supported - if Features.MMX = True then - Ada.Text_IO.Put_Line (" MMX - MMX technology supported"); - end if; - - -- Fast FP Save and Restore - if Features.FXSR = True then - Ada.Text_IO.Put_Line (" FXSR - Fast FP Save and Restore"); - end if; - - --------------------- - -- Program done. -- - --------------------- - - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - - exception - - when others => - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Failure); - raise; - - end Check_CPU; - -  - File: gnat_ug_unx.info, Node: Intel_CPU Package Specification, Next: Intel_CPU Package Body, Prev: Check_CPU Procedure, Up: A Complete Example - - `Intel_CPU' Package Specification - --------------------------------- - - ------------------------------------------------------------------------- - -- -- - -- file: intel_cpu.ads -- - -- -- - -- ********************************************* -- - -- * WARNING: for 32-bit Intel processors only * -- - -- ********************************************* -- - -- -- - -- This package contains a number of subprograms that are useful in -- - -- determining the Intel x86 CPU (and the features it supports) on -- - -- which the program is running. -- - -- -- - -- The package is based upon the information given in the Intel -- - -- Application Note AP-485: "Intel Processor Identification and the -- - -- CPUID Instruction" as of April 1998. This application note can be -- - -- found on www.intel.com. -- - -- -- - -- It currently deals with 32-bit processors only, will not detect -- - -- features added after april 1998, and does not guarantee proper -- - -- results on Intel-compatible processors. -- - -- -- - -- Cache info and x386 fpu type detection are not supported. -- - -- -- - -- This package does not use any privileged instructions, so should -- - -- work on any OS running on a 32-bit Intel processor. -- - -- -- - ------------------------------------------------------------------------- - - with Interfaces; use Interfaces; - -- for using unsigned types - - with System.Machine_Code; use System.Machine_Code; - -- for using inline assembler code - - with Ada.Characters.Latin_1; use Ada.Characters.Latin_1; - -- for inserting control characters - - package Intel_CPU is - - ---------------------- - -- Processor bits -- - ---------------------- - - subtype Num_Bits is Natural range 0 .. 31; - -- the number of processor bits (32) - - -------------------------- - -- Processor register -- - -------------------------- - - -- define a processor register type for easy access to - -- the individual bits - - type Processor_Register is array (Num_Bits) of Boolean; - pragma Pack (Processor_Register); - for Processor_Register'Size use 32; - - ------------------------- - -- Unsigned register -- - ------------------------- - - -- define a processor register type for easy access to - -- the individual bytes - - type Unsigned_Register is - record - L1 : Unsigned_8; - H1 : Unsigned_8; - L2 : Unsigned_8; - H2 : Unsigned_8; - end record; - - for Unsigned_Register use - record - L1 at 0 range 0 .. 7; - H1 at 0 range 8 .. 15; - L2 at 0 range 16 .. 23; - H2 at 0 range 24 .. 31; - end record; - - for Unsigned_Register'Size use 32; - - --------------------------------- - -- Intel processor vendor ID -- - --------------------------------- - - Intel_Processor : constant String (1 .. 12) := "GenuineIntel"; - -- indicates an Intel manufactured processor - - ------------------------------------ - -- Processor signature register -- - ------------------------------------ - - -- a register type to hold the processor signature - - type Processor_Signature is - record - Stepping : Natural range 0 .. 15; - Model : Natural range 0 .. 15; - Family : Natural range 0 .. 15; - Processor_Type : Natural range 0 .. 3; - Reserved : Natural range 0 .. 262143; - end record; - - for Processor_Signature use - record - Stepping at 0 range 0 .. 3; - Model at 0 range 4 .. 7; - Family at 0 range 8 .. 11; - Processor_Type at 0 range 12 .. 13; - Reserved at 0 range 14 .. 31; - end record; - - for Processor_Signature'Size use 32; - - ----------------------------------- - -- Processor features register -- - ----------------------------------- - - -- a processor register to hold the processor feature flags - - type Processor_Features is - record - FPU : Boolean; -- floating point unit on chip - VME : Boolean; -- virtual mode extension - DE : Boolean; -- debugging extension - PSE : Boolean; -- page size extension - TSC : Boolean; -- time stamp counter - MSR : Boolean; -- model specific registers - PAE : Boolean; -- physical address extension - MCE : Boolean; -- machine check extension - CX8 : Boolean; -- cmpxchg8 instruction - APIC : Boolean; -- on-chip apic hardware - Res_1 : Boolean; -- reserved for extensions - SEP : Boolean; -- fast system call - MTRR : Boolean; -- memory type range registers - PGE : Boolean; -- page global enable - MCA : Boolean; -- machine check architecture - CMOV : Boolean; -- conditional move supported - PAT : Boolean; -- page attribute table - PSE_36 : Boolean; -- 36-bit page size extension - Res_2 : Natural range 0 .. 31; -- reserved for extensions - MMX : Boolean; -- MMX technology supported - FXSR : Boolean; -- fast FP save and restore - Res_3 : Natural range 0 .. 127; -- reserved for extensions - end record; - - for Processor_Features use - record - FPU at 0 range 0 .. 0; - VME at 0 range 1 .. 1; - DE at 0 range 2 .. 2; - PSE at 0 range 3 .. 3; - TSC at 0 range 4 .. 4; - MSR at 0 range 5 .. 5; - PAE at 0 range 6 .. 6; - MCE at 0 range 7 .. 7; - CX8 at 0 range 8 .. 8; - APIC at 0 range 9 .. 9; - Res_1 at 0 range 10 .. 10; - SEP at 0 range 11 .. 11; - MTRR at 0 range 12 .. 12; - PGE at 0 range 13 .. 13; - MCA at 0 range 14 .. 14; - CMOV at 0 range 15 .. 15; - PAT at 0 range 16 .. 16; - PSE_36 at 0 range 17 .. 17; - Res_2 at 0 range 18 .. 22; - MMX at 0 range 23 .. 23; - FXSR at 0 range 24 .. 24; - Res_3 at 0 range 25 .. 31; - end record; - - for Processor_Features'Size use 32; - - ------------------- - -- Subprograms -- - ------------------- - - function Has_FPU return Boolean; - -- return True if a FPU is found - -- use only if CPUID is not supported - - function Has_CPUID return Boolean; - -- return True if the processor supports the CPUID instruction - - function CPUID_Level return Natural; - -- return the CPUID support level (0, 1 or 2) - -- can only be called if the CPUID instruction is supported - - function Vendor_ID return String; - -- return the processor vendor identification string - -- can only be called if the CPUID instruction is supported - - function Signature return Processor_Signature; - -- return the processor signature - -- can only be called if the CPUID instruction is supported - - function Features return Processor_Features; - -- return the processors features - -- can only be called if the CPUID instruction is supported - - private - - ------------------------ - -- EFLAGS bit names -- - ------------------------ - - ID_Flag : constant Num_Bits := 21; - -- ID flag bit - - end Intel_CPU; - -  - File: gnat_ug_unx.info, Node: Intel_CPU Package Body, Prev: Intel_CPU Package Specification, Up: A Complete Example - - `Intel_CPU' Package Body - ------------------------ - - package body Intel_CPU is - - --------------------------- - -- Detect FPU presence -- - --------------------------- - - -- There is a FPU present if we can set values to the FPU Status - -- and Control Words. - - function Has_FPU return Boolean is - - Register : Unsigned_16; - -- processor register to store a word - - begin - - -- check if we can change the status word - Asm ( - - -- the assembler code - "finit" & LF & HT & -- reset status word - "movw $0x5A5A, %%ax" & LF & HT & -- set value status word - "fnstsw %0" & LF & HT & -- save status word - "movw %%ax, %0", -- store status word - - -- output stored in Register - -- register must be a memory location - Outputs => Unsigned_16'Asm_output ("=m", Register), - - -- tell compiler that we used eax - Clobber => "eax"); - - -- if the status word is zero, there is no FPU - if Register = 0 then - return False; -- no status word - end if; -- check status word value - - -- check if we can get the control word - Asm ( - - -- the assembler code - "fnstcw %0", -- save the control word - - -- output into Register - -- register must be a memory location - Outputs => Unsigned_16'Asm_output ("=m", Register)); - - -- check the relevant bits - if (Register and 16#103F#) /= 16#003F# then - return False; -- no control word - end if; -- check control word value - - -- FPU found - return True; - - end Has_FPU; - - -------------------------------- - -- Detect CPUID instruction -- - -------------------------------- - - -- The processor supports the CPUID instruction if it is possible - -- to change the value of ID flag bit in the EFLAGS register. - - function Has_CPUID return Boolean is - - Original_Flags, Modified_Flags : Processor_Register; - -- EFLAG contents before and after changing the ID flag - - begin - - -- try flipping the ID flag in the EFLAGS register - Asm ( - - -- the assembler code - "pushfl" & LF & HT & -- push EFLAGS on stack - "pop %%eax" & LF & HT & -- pop EFLAGS into eax - "movl %%eax, %0" & LF & HT & -- save EFLAGS content - "xor $0x200000, %%eax" & LF & HT & -- flip ID flag - "push %%eax" & LF & HT & -- push EFLAGS on stack - "popfl" & LF & HT & -- load EFLAGS register - "pushfl" & LF & HT & -- push EFLAGS on stack - "pop %1", -- save EFLAGS content - - -- output values, may be anything - -- Original_Flags is %0 - -- Modified_Flags is %1 - Outputs => - (Processor_Register'Asm_output ("=g", Original_Flags), - Processor_Register'Asm_output ("=g", Modified_Flags)), - - -- tell compiler eax is destroyed - Clobber => "eax"); - - -- check if CPUID is supported - if Original_Flags(ID_Flag) /= Modified_Flags(ID_Flag) then - return True; -- ID flag was modified - else - return False; -- ID flag unchanged - end if; -- check for CPUID - - end Has_CPUID; - - ------------------------------- - -- Get CPUID support level -- - ------------------------------- - - function CPUID_Level return Natural is - - Level : Unsigned_32; - -- returned support level - - begin - - -- execute CPUID, storing the results in the Level register - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- zero is stored in eax - -- returning the support level in eax - Inputs => Unsigned_32'Asm_input ("a", 0), - - -- eax is stored in Level - Outputs => Unsigned_32'Asm_output ("=a", Level), - - -- tell compiler ebx, ecx and edx registers are destroyed - Clobber => "ebx, ecx, edx"); - - -- return the support level - return Natural (Level); - - end CPUID_Level; - - -------------------------------- - -- Get CPU Vendor ID String -- - -------------------------------- - - -- The vendor ID string is returned in the ebx, ecx and edx register - -- after executing the CPUID instruction with eax set to zero. - -- In case of a true Intel processor the string returned is - -- "GenuineIntel" - - function Vendor_ID return String is - - Ebx, Ecx, Edx : Unsigned_Register; - -- registers containing the vendor ID string - - Vendor_ID : String (1 .. 12); - -- the vendor ID string - - begin - - -- execute CPUID, storing the results in the processor registers - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- zero stored in eax - -- vendor ID string returned in ebx, ecx and edx - Inputs => Unsigned_32'Asm_input ("a", 0), - - -- ebx is stored in Ebx - -- ecx is stored in Ecx - -- edx is stored in Edx - Outputs => (Unsigned_Register'Asm_output ("=b", Ebx), - Unsigned_Register'Asm_output ("=c", Ecx), - Unsigned_Register'Asm_output ("=d", Edx))); - - -- now build the vendor ID string - Vendor_ID( 1) := Character'Val (Ebx.L1); - Vendor_ID( 2) := Character'Val (Ebx.H1); - Vendor_ID( 3) := Character'Val (Ebx.L2); - Vendor_ID( 4) := Character'Val (Ebx.H2); - Vendor_ID( 5) := Character'Val (Edx.L1); - Vendor_ID( 6) := Character'Val (Edx.H1); - Vendor_ID( 7) := Character'Val (Edx.L2); - Vendor_ID( 8) := Character'Val (Edx.H2); - Vendor_ID( 9) := Character'Val (Ecx.L1); - Vendor_ID(10) := Character'Val (Ecx.H1); - Vendor_ID(11) := Character'Val (Ecx.L2); - Vendor_ID(12) := Character'Val (Ecx.H2); - - -- return string - return Vendor_ID; - - end Vendor_ID; - - ------------------------------- - -- Get processor signature -- - ------------------------------- - - function Signature return Processor_Signature is - - Result : Processor_Signature; - -- processor signature returned - - begin - - -- execute CPUID, storing the results in the Result variable - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- one is stored in eax - -- processor signature returned in eax - Inputs => Unsigned_32'Asm_input ("a", 1), - - -- eax is stored in Result - Outputs => Processor_Signature'Asm_output ("=a", Result), - - -- tell compiler that ebx, ecx and edx are also destroyed - Clobber => "ebx, ecx, edx"); - - -- return processor signature - return Result; - - end Signature; - - ------------------------------ - -- Get processor features -- - ------------------------------ - - function Features return Processor_Features is - - Result : Processor_Features; - -- processor features returned - - begin - - -- execute CPUID, storing the results in the Result variable - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- one stored in eax - -- processor features returned in edx - Inputs => Unsigned_32'Asm_input ("a", 1), - - -- edx is stored in Result - Outputs => Processor_Features'Asm_output ("=d", Result), - - -- tell compiler that ebx and ecx are also destroyed - Clobber => "ebx, ecx"); - - -- return processor signature - return Result; - - end Features; - - end Intel_CPU; - -  - File: gnat_ug_unx.info, Node: Performance Considerations, Next: GNU Free Documentation License, Prev: Inline Assembler, Up: Top - - Performance Considerations - ************************** - - The GNAT system provides a number of options that allow a trade-off - between - - * performance of the generated code - - * speed of compilation - - * minimization of dependences and recompilation - - * the degree of run-time checking. - - The defaults (if no options are selected) aim at improving the speed of - compilation and minimizing dependences, at the expense of performance - of the generated code: - - * no optimization - - * no inlining of subprogram calls - - * all run-time checks enabled except overflow and elaboration checks - - These options are suitable for most program development purposes. This - chapter describes how you can modify these choices, and also provides - some guidelines on debugging optimized code. - - * Menu: - - * Controlling Run-Time Checks:: - * Optimization Levels:: - * Debugging Optimized Code:: - * Inlining of Subprograms:: - -  - File: gnat_ug_unx.info, Node: Controlling Run-Time Checks, Next: Optimization Levels, Up: Performance Considerations - - Controlling Run-Time Checks - =========================== - - By default, GNAT generates all run-time checks, except arithmetic - overflow checking for integer operations and checks for access before - elaboration on subprogram calls. The latter are not required in default - mode, because all necessary checking is done at compile time. Two gnat - switches, `-gnatp' and `-gnato' allow this default to be modified. - *Note Run-Time Checks::. - - Our experience is that the default is suitable for most development - purposes. - - We treat integer overflow specially because these are quite - expensive and in our experience are not as important as other run-time - checks in the development process. Note that division by zero is not - considered an overflow check, and divide by zero checks are generated - where required by default. - - Elaboration checks are off by default, and also not needed by - default, since GNAT uses a static elaboration analysis approach that - avoids the need for run-time checking. This manual contains a full - chapter discussing the issue of elaboration checks, and if the default - is not satisfactory for your use, you should read this chapter. - - For validity checks, the minimal checks required by the Ada Reference - Manual (for case statements and assignments to array elements) are on - by default. These can be suppressed by use of the `-gnatVn' switch. - Note that in Ada 83, there were no validity checks, so if the Ada 83 - mode is acceptable (or when comparing GNAT performance with an Ada 83 - compiler), it may be reasonable to routinely use `-gnatVn'. Validity - checks are also suppressed entirely if `-gnatp' is used. - - Note that the setting of the switches controls the default setting of - the checks. They may be modified using either `pragma Suppress' (to - remove checks) or `pragma Unsuppress' (to add back suppressed checks) - in the program source. - -  - File: gnat_ug_unx.info, Node: Optimization Levels, Next: Debugging Optimized Code, Prev: Controlling Run-Time Checks, Up: Performance Considerations - - Optimization Levels - =================== - - The default is optimization off. This results in the fastest compile - times, but GNAT makes absolutely no attempt to optimize, and the - generated programs are considerably larger and slower than when - optimization is enabled. You can use the `-ON' switch, where N is an - integer from 0 to 3, on the `gcc' command line to control the - optimization level: - - `-O0' - no optimization (the default) - - `-O1' - medium level optimization - - `-O2' - full optimization - - `-O3' - full optimization, and also attempt automatic inlining of small - subprograms within a unit (*note Inlining of Subprograms::). - - Higher optimization levels perform more global transformations on the - program and apply more expensive analysis algorithms in order to - generate faster and more compact code. The price in compilation time, - and the resulting improvement in execution time, both depend on the - particular application and the hardware environment. You should - experiment to find the best level for your application. - - Note: Unlike some other compilation systems, `gcc' has been tested - extensively at all optimization levels. There are some bugs which - appear only with optimization turned on, but there have also been bugs - which show up only in _unoptimized_ code. Selecting a lower level of - optimization does not improve the reliability of the code generator, - which in practice is highly reliable at all optimization levels. - - Note regarding the use of `-O3': The use of this optimization level - is generally discouraged with GNAT, since it often results in larger - executables which run more slowly. See further discussion of this point - in *note Inlining of Subprograms::. - -  - File: gnat_ug_unx.info, Node: Debugging Optimized Code, Next: Inlining of Subprograms, Prev: Optimization Levels, Up: Performance Considerations - - Debugging Optimized Code - ======================== - - Since the compiler generates debugging tables for a compilation unit - before it performs optimizations, the optimizing transformations may - invalidate some of the debugging data. You therefore need to - anticipate certain anomalous situations that may arise while debugging - optimized code. This section describes the most common cases. - - 1. The "hopping Program Counter": Repeated 'step' or 'next' commands - show the PC bouncing back and forth in the code. This may result - from any of the following optimizations: - - * Common subexpression elimination: using a single instance of - code for a quantity that the source computes several times. - As a result you may not be able to stop on what looks like a - statement. - - * Invariant code motion: moving an expression that does not - change within a loop, to the beginning of the loop. - - * Instruction scheduling: moving instructions so as to overlap - loads and stores (typically) with other code, or in general - to move computations of values closer to their uses. Often - this causes you to pass an assignment statement without the - assignment happening and then later bounce back to the - statement when the value is actually needed. Placing a - breakpoint on a line of code and then stepping over it may, - therefore, not always cause all the expected side-effects. - - 2. The "big leap": More commonly known as cross-jumping, in which two - identical pieces of code are merged and the program counter - suddenly jumps to a statement that is not supposed to be executed, - simply because it (and the code following) translates to the same - thing as the code that _was_ supposed to be executed. This effect - is typically seen in sequences that end in a jump, such as a - `goto', a `return', or a `break' in a C `switch' statement. - - 3. The "roving variable": The symptom is an unexpected value in a - variable. There are various reasons for this effect: - - * In a subprogram prologue, a parameter may not yet have been - moved to its "home". - - * A variable may be dead, and its register re-used. This is - probably the most common cause. - - * As mentioned above, the assignment of a value to a variable - may have been moved. - - * A variable may be eliminated entirely by value propagation or - other means. In this case, GCC may incorrectly generate - debugging information for the variable - - In general, when an unexpected value appears for a local variable - or parameter you should first ascertain if that value was actually - computed by your program, as opposed to being incorrectly reported - by the debugger. Record fields or array elements in an object - designated by an access value are generally less of a problem, - once you have ascertained that the access value is sensible. - Typically, this means checking variables in the preceding code and - in the calling subprogram to verify that the value observed is - explainable from other values (one must apply the procedure - recursively to those other values); or re-running the code and - stopping a little earlier (perhaps before the call) and stepping - to better see how the variable obtained the value in question; or - continuing to step _from_ the point of the strange value to see if - code motion had simply moved the variable's assignments later. - -  - File: gnat_ug_unx.info, Node: Inlining of Subprograms, Prev: Debugging Optimized Code, Up: Performance Considerations - - Inlining of Subprograms - ======================= - - A call to a subprogram in the current unit is inlined if all the - following conditions are met: - - * The optimization level is at least `-O1'. - - * The called subprogram is suitable for inlining: It must be small - enough and not contain nested subprograms or anything else that - `gcc' cannot support in inlined subprograms. - - * The call occurs after the definition of the body of the subprogram. - - * Either `pragma Inline' applies to the subprogram or it is small - and automatic inlining (optimization level `-O3') is specified. - - Calls to subprograms in `with''ed units are normally not inlined. To - achieve this level of inlining, the following conditions must all be - true: - - * The optimization level is at least `-O1'. - - * The called subprogram is suitable for inlining: It must be small - enough and not contain nested subprograms or anything else `gcc' - cannot support in inlined subprograms. - - * The call appears in a body (not in a package spec). - - * There is a `pragma Inline' for the subprogram. - - * The `-gnatn' switch is used in the `gcc' command line - - Note that specifying the `-gnatn' switch causes additional - compilation dependencies. Consider the following: - - package R is - procedure Q; - pragma Inline (Q); - end R; - package body R is - ... - end R; - - with R; - procedure Main is - begin - ... - R.Q; - end Main; - - With the default behavior (no `-gnatn' switch specified), the - compilation of the `Main' procedure depends only on its own source, - `main.adb', and the spec of the package in file `r.ads'. This means - that editing the body of `R' does not require recompiling `Main'. - - On the other hand, the call `R.Q' is not inlined under these - circumstances. If the `-gnatn' switch is present when `Main' is - compiled, the call will be inlined if the body of `Q' is small enough, - but now `Main' depends on the body of `R' in `r.adb' as well as on the - spec. This means that if this body is edited, the main program must be - recompiled. Note that this extra dependency occurs whether or not the - call is in fact inlined by `gcc'. - - The use of front end inlining with `-gnatN' generates similar - additional dependencies. - - Note: The `-fno-inline' switch can be used to prevent all inlining. - This switch overrides all other conditions and ensures that no inlining - occurs. The extra dependences resulting from `-gnatn' will still be - active, even if this switch is used to suppress the resulting inlining - actions. - - Note regarding the use of `-O3': There is no difference in inlining - behavior between `-O2' and `-O3' for subprograms with an explicit - pragma `Inline' assuming the use of `-gnatn' or `-gnatN' (the switches - that activate inlining). If you have used pragma `Inline' in - appropriate cases, then it is usually much better to use `-O2' and - `-gnatn' and avoid the use of `-O3' which in this case only has the - effect of inlining subprograms you did not think should be inlined. We - often find that the use of `-O3' slows down code by performing - excessive inlining, leading to increased instruction cache pressure - from the increased code size. So the bottom line here is that you - should not automatically assume that `-O3' is better than `-O2', and - indeed you should use `-O3' only if tests show that it actually - improves performance. - -  - File: gnat_ug_unx.info, Node: GNU Free Documentation License, Next: Index, Prev: Performance Considerations, Up: Top - - GNU Free Documentation License - ****************************** - - Version 1.2, November 2002 - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warrany Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - - ADDENDUM: How to use this License for your documents - ==================================================== - - To use this License in a document you have written, include a copy of - the License in the document and put the following copyright and license - notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover - Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other - combination of the three, merge those two alternatives to suit the - situation. - - If your document contains nontrivial examples of program code, we - recommend releasing these examples in parallel under your choice of - free software license, such as the GNU General Public License, to - permit their use in free software. - -  - File: gnat_ug_unx.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - - Index - ***** - - * Menu: - - * --GCC= (gnatchop): Switches for gnatchop. - * --GCC=compiler_name (gnatlink): Switches for gnatlink. - * --GCC=compiler_name (gnatmake): Switches for gnatmake. - * --GNATBIND=binder_name (gnatmake): Switches for gnatmake. - * --GNATLINK=linker_name (gnatmake): Switches for gnatmake. - * --LINK= (gnatlink): Switches for gnatlink. - * --RTS (gcc): Switches for gcc. - * --RTS (gnatbind): Summary of Binder Switches. - * --RTS (gnatfind): gnatfind Switches. - * --RTS (gnatls): Switches for gnatls. - * --RTS (gnatmake): Switches for gnatmake. - * --RTS (gnatxref): gnatxref Switches. - * -83 (gnathtml): Converting Ada Files to html with gnathtml. - * -A (gnatbind): Output Control. - * -A (gnatlink): Switches for gnatlink. - * -a (gnatls): Switches for gnatls. - * -A (gnatmake): Switches for gnatmake. - * -a (gnatmake): Switches for gnatmake. - * -aI (gnatmake): Switches for gnatmake. - * -aL (gnatmake): Switches for gnatmake. - * -aO (gnatmake): Switches for gnatmake. - * -B (gcc): Switches for gcc. - * -b (gcc): Switches for gcc. - * -b (gnatbind): Binder Error Message Control. - * -B (gnatlink): Switches for gnatlink. - * -b (gnatlink): Switches for gnatlink. - * -b (gnatmake): Switches for gnatmake. - * -bargs (gnatmake): Mode Switches for gnatmake. - * -c (gcc): Switches for gcc. - * -C (gnatbind): Output Control. - * -c (gnatbind): Output Control. - * -c (gnatchop): Switches for gnatchop. - * -C (gnatlink): Switches for gnatlink. - * -C (gnatmake): Switches for gnatmake. - * -c (gnatmake): Switches for gnatmake. - * -c (gnatname): Switches for gnatname. - * -cargs (gnatmake): Mode Switches for gnatmake. - * -d (gnathtml): Converting Ada Files to html with gnathtml. - * -d (gnatls): Switches for gnatls. - * -D (gnatname): Switches for gnatname. - * -d (gnatname): Switches for gnatname. - * -e (gnatbind): Output Control. - * -f (gnathtml): Converting Ada Files to html with gnathtml. - * -f (gnatlink): Switches for gnatlink. - * -f (gnatmake): Switches for gnatmake. - * -fno-inline (gcc): Inlining of Subprograms. - * -fstack-check: Stack Overflow Checking. - * -g (gcc): Switches for gcc. - * -g (gnatlink): Switches for gnatlink. - * -gnat83 (gcc): Compiling Ada 83 Programs. - * -gnata (gcc): Debugging and Assertion Control. - * -gnatb (gcc): Output and Error Message Control. - * -gnatc (gcc): Using gcc for Semantic Checking. - * -gnatD (gcc): Debugging Control. - * -gnatdc switch: GNAT Abnormal Termination or Failure to Terminate. - * -gnatE (gcc) <1>: Debugging Control. - * -gnatE (gcc): Run-Time Checks. - * -gnatem (gcc): Units to Sources Mapping Files. - * -gnatf (gcc): Output and Error Message Control. - * -gnatG (gcc): Debugging Control. - * -gnati (gcc): Character Set Control. - * -gnatk (gcc): File Naming Control. - * -gnatl (gcc): Output and Error Message Control. - * -gnatm (gcc): Output and Error Message Control. - * -gnatn (gcc): Inlining of Subprograms. - * -gnatN (gcc): Subprogram Inlining Control. - * -gnatn (gcc): Subprogram Inlining Control. - * -gnatN switch: Source Dependencies. - * -gnatn switch: Source Dependencies. - * -gnato (gcc) <1>: Controlling Run-Time Checks. - * -gnato (gcc): Run-Time Checks. - * -gnatp (gcc) <1>: Controlling Run-Time Checks. - * -gnatp (gcc): Run-Time Checks. - * -gnatq (gcc): Output and Error Message Control. - * -gnatR (gcc): Debugging Control. - * -gnats (gcc): Using gcc for Syntax Checking. - * -gnatt (gcc): Auxiliary Output Control. - * -gnatT (gcc): Run-Time Control. - * -gnatu (gcc): Auxiliary Output Control. - * -gnatU (gcc): Output and Error Message Control. - * -gnatv (gcc): Output and Error Message Control. - * -gnatW (gcc): Character Set Control. - * -gnatwA (gcc): Output and Error Message Control. - * -gnatwa (gcc): Output and Error Message Control. - * -gnatwB (gcc): Output and Error Message Control. - * -gnatwb (gcc): Output and Error Message Control. - * -gnatwC (gcc): Output and Error Message Control. - * -gnatwc (gcc): Output and Error Message Control. - * -gnatwD (gcc): Output and Error Message Control. - * -gnatwd (gcc): Output and Error Message Control. - * -gnatwe (gcc): Output and Error Message Control. - * -gnatwF (gcc): Output and Error Message Control. - * -gnatwf (gcc): Output and Error Message Control. - * -gnatwH (gcc): Output and Error Message Control. - * -gnatwh (gcc): Output and Error Message Control. - * -gnatwI (gcc): Output and Error Message Control. - * -gnatwi (gcc): Output and Error Message Control. - * -gnatwL (gcc): Output and Error Message Control. - * -gnatwl (gcc): Output and Error Message Control. - * -gnatwO (gcc): Output and Error Message Control. - * -gnatwo (gcc): Output and Error Message Control. - * -gnatwP (gcc): Output and Error Message Control. - * -gnatwp (gcc): Output and Error Message Control. - * -gnatwR (gcc): Output and Error Message Control. - * -gnatwr (gcc): Output and Error Message Control. - * -gnatws (gcc): Output and Error Message Control. - * -gnatwU (gcc): Output and Error Message Control. - * -gnatwu (gcc): Output and Error Message Control. - * -gnatx (gcc): Debugging Control. - * -h (gnatbind) <1>: Output Control. - * -h (gnatbind): Elaboration Control. - * -h (gnatls): Switches for gnatls. - * -h (gnatname): Switches for gnatname. - * -I (gcc): Switches for gcc. - * -I (gnathtml): Converting Ada Files to html with gnathtml. - * -I (gnatmake): Switches for gnatmake. - * -i (gnatmake): Switches for gnatmake. - * -i (gnatmem): Switches for gnatmem. - * -I- (gcc): Switches for gcc. - * -I- (gnatmake): Switches for gnatmake. - * -j (gnatmake): Switches for gnatmake. - * -K (gnatbind): Output Control. - * -k (gnatchop): Switches for gnatchop. - * -k (gnatmake): Switches for gnatmake. - * -l (gnatbind): Output Control. - * -l (gnathtml): Converting Ada Files to html with gnathtml. - * -L (gnatmake): Switches for gnatmake. - * -l (gnatmake): Switches for gnatmake. - * -largs (gnatmake): Mode Switches for gnatmake. - * -M (gnatbind): Binder Error Message Control. - * -m (gnatbind): Binder Error Message Control. - * -M (gnatmake): Switches for gnatmake. - * -m (gnatmake): Switches for gnatmake. - * -n (gnatbind): Binding with Non-Ada Main Programs. - * -n (gnatlink): Switches for gnatlink. - * -n (gnatmake): Switches for gnatmake. - * -nostdinc (gnatmake): Switches for gnatmake. - * -nostdlib (gnatmake): Switches for gnatmake. - * -O (gcc) <1>: Optimization Levels. - * -O (gcc): Switches for gcc. - * -o (gcc): Switches for gcc. - * -o (gnatbind): Output Control. - * -O (gnatbind): Output Control. - * -o (gnathtml): Converting Ada Files to html with gnathtml. - * -o (gnatlink): Switches for gnatlink. - * -o (gnatls): Switches for gnatls. - * -o (gnatmake): Switches for gnatmake. - * -o (gnatmem): Switches for gnatmem. - * -p (gnatchop): Switches for gnatchop. - * -p (gnathtml): Converting Ada Files to html with gnathtml. - * -P (gnatname): Switches for gnatname. - * -pass-exit-codes (gcc): Auxiliary Output Control. - * -q (gnatchop): Switches for gnatchop. - * -q (gnatmake): Switches for gnatmake. - * -q (gnatmem): Switches for gnatmem. - * -r (gnatbind): Output Control. - * -r (gnatchop): Switches for gnatchop. - * -S (gcc): Switches for gcc. - * -s (gnatbind): Consistency-Checking Modes. - * -s (gnatls): Switches for gnatls. - * -s (gnatmake): Switches for gnatmake. - * -sc (gnathtml): Converting Ada Files to html with gnathtml. - * -t (gnatbind): Binder Error Message Control. - * -t (gnathtml): Converting Ada Files to html with gnathtml. - * -u (gnatls): Switches for gnatls. - * -u (gnatmake): Switches for gnatmake. - * -V (gcc): Switches for gcc. - * -v (gcc): Switches for gcc. - * -v (gnatbind): Binder Error Message Control. - * -v (gnatchop): Switches for gnatchop. - * -v (gnatlink): Switches for gnatlink. - * -v (gnatmake): Switches for gnatmake. - * -v (gnatname): Switches for gnatname. - * -v -v (gnatlink): Switches for gnatlink. - * -w: Output and Error Message Control. - * -w (gnatchop): Switches for gnatchop. - * -we (gnatbind): Binder Error Message Control. - * -ws (gnatbind): Binder Error Message Control. - * -x (gnatbind): Consistency-Checking Modes. - * -z (gnatbind): Binding Programs with No Main Subprogram. - * -z (gnatmake): Switches for gnatmake. - * __gnat_finalize: Running gnatbind. - * __gnat_initialize: Running gnatbind. - * __gnat_set_globals: Running gnatbind. - * _main: The External Symbol Naming Scheme of GNAT. - * Access before elaboration: Run-Time Checks. - * Access-to-subprogram: Elaboration for Access-to-Subprogram Values. - * ACVC, Ada 83 tests: Compiling Ada 83 Programs. - * Ada <1>: Naming Conventions for GNAT Source Files. - * Ada: Search Paths for gnatbind. - * Ada 83 compatibility: Compiling Ada 83 Programs. - * Ada 95 Language Reference Manual: What You Should Know before Reading This Guide. - * Ada expressions: Using Ada Expressions. - * Ada Library Information files: The Ada Library Information Files. - * Ada.Characters.Latin_1: Latin-1. - * ADA_INCLUDE_PATH: Search Paths and the Run-Time Library (RTL). - * ADA_OBJECTS_PATH: Search Paths for gnatbind. - * adafinal <1>: Binding with Non-Ada Main Programs. - * adafinal: Running gnatbind. - * adainit <1>: Binding with Non-Ada Main Programs. - * adainit: Running gnatbind. - * Address Clauses, warnings: Output and Error Message Control. - * ali files: The Ada Library Information Files. - * Annex A: Naming Conventions for GNAT Source Files. - * Annex B: Naming Conventions for GNAT Source Files. - * Arbitrary File Naming Conventions: Handling Arbitrary File Naming Conventions Using gnatname. - * Asm: Calling Conventions. - * Assert: Debugging and Assertion Control. - * Assertions: Debugging and Assertion Control. - * Biased rounding: Output and Error Message Control. - * Binder consistency checks: Binder Error Message Control. - * Binder output file: Interfacing to C. - * Binder, multiple input files: Binding with Non-Ada Main Programs. - * Breakpoints and tasks: Ada Tasks. - * C: Calling Conventions. - * C++: Calling Conventions. - * Calling Conventions: Calling Conventions. - * Check, elaboration: Run-Time Checks. - * Check, overflow: Run-Time Checks. - * Check_CPU procedure: Check_CPU Procedure. - * Checks, access before elaboration: Run-Time Checks. - * Checks, division by zero: Run-Time Checks. - * Checks, elaboration: Checking the Elaboration Order in Ada 95. - * Checks, overflow: Controlling Run-Time Checks. - * Checks, suppressing: Run-Time Checks. - * COBOL: Calling Conventions. - * code page 437: Other 8-Bit Codes. - * code page 850: Other 8-Bit Codes. - * Combining GNAT switches: Switches for gcc. - * Command line length: Switches for gnatlink. - * Compilation model: The GNAT Compilation Model. - * Conditionals, constant: Output and Error Message Control. - * Configuration pragmas: Configuration Pragmas. - * Consistency checks, in binder: Binder Error Message Control. - * Convention Ada: Calling Conventions. - * Convention Asm: Calling Conventions. - * Convention Assembler: Calling Conventions. - * Convention C: Calling Conventions. - * Convention C++: Calling Conventions. - * Convention COBOL: Calling Conventions. - * Convention Default: Calling Conventions. - * Convention DLL: Calling Conventions. - * Convention External: Calling Conventions. - * Convention Fortran: Calling Conventions. - * Convention Stdcall: Calling Conventions. - * Convention Stubbed: Calling Conventions. - * Convention Win32: Calling Conventions. - * Conventions: Conventions. - * CR: Source Representation. - * Cyrillic: Other 8-Bit Codes. - * Debug: Debugging and Assertion Control. - * Debug Pool: Finding Memory Problems with GNAT Debug Pool. - * Debugger: Running and Debugging Ada Programs. - * Debugging: Running and Debugging Ada Programs. - * Debugging Generic Units: Debugging Generic Units. - * Debugging information, including: Switches for gnatlink. - * Debugging options: Debugging Control. - * Default: Calling Conventions. - * Dependencies, producing list: Switches for gnatmake. - * Dependency rules: The GNAT Make Program gnatmake. - * Dereferencing, implicit: Output and Error Message Control. - * Division by zero: Run-Time Checks. - * DLL: Calling Conventions. - * Elaborate: Controlling the Elaboration Order in Ada 95. - * Elaborate_All: Controlling the Elaboration Order in Ada 95. - * Elaborate_Body: Controlling the Elaboration Order in Ada 95. - * Elaboration checks <1>: Checking the Elaboration Order in Ada 95. - * Elaboration checks: Run-Time Checks. - * Elaboration control <1>: Summary of Procedures for Elaboration Control. - * Elaboration control: Elaboration Order Handling in GNAT. - * Elaboration of library tasks: Elaboration Issues for Library Tasks. - * Elaboration order control: Comparison between GNAT and C/C++ Compilation Models. - * Elaboration, warnings: Output and Error Message Control. - * Eliminate: Eliminate Pragma. - * End of source file: Source Representation. - * Error messages, suppressing: Output and Error Message Control. - * EUC Coding: Wide Character Encodings. - * Exceptions: Ada Exceptions. - * Export: The External Symbol Naming Scheme of GNAT. - * External: Calling Conventions. - * FDL, GNU Free Documentation License: GNU Free Documentation License. - * FF: Source Representation. - * File names <1>: Alternative File Naming Schemes. - * File names: Using Other File Names. - * File naming schemes, alternative: Alternative File Naming Schemes. - * Foreign Languages: Calling Conventions. - * Formals, unreferenced: Output and Error Message Control. - * Fortran: Calling Conventions. - * gdb: Running and Debugging Ada Programs. - * Generic formal parameters: Compiling Ada 83 Programs. - * Generics <1>: Debugging Generic Units. - * Generics: Generating Object Files. - * Glide: Introduction to Glide and GVD. - * GMEM (gnatmem): Running gnatmem (GMEM Mode). - * GNAT <1>: Naming Conventions for GNAT Source Files. - * GNAT: Search Paths for gnatbind. - * GNAT Abnormal Termination or Failure to Terminate: GNAT Abnormal Termination or Failure to Terminate. - * GNAT compilation model: The GNAT Compilation Model. - * GNAT library: Comparison between GNAT and Conventional Ada Library Models. - * gnat.adc <1>: The Configuration Pragmas Files. - * gnat.adc: Using Other File Names. - * gnat1: Compiling Programs. - * gnat_argc: Command-Line Access. - * gnat_argv: Command-Line Access. - * GNAT_STACK_LIMIT: Stack Overflow Checking. - * gnatbind: Binding Using gnatbind. - * gnatchop: Renaming Files Using gnatchop. - * gnatelim: Reducing the Size of Ada Executables with gnatelim. - * gnatfind: The Cross-Referencing Tools gnatxref and gnatfind. - * gnatkr: File Name Krunching Using gnatkr. - * gnatlink: Linking Using gnatlink. - * gnatls: The GNAT Library Browser gnatls. - * gnatmake: The GNAT Make Program gnatmake. - * gnatmem: Finding Memory Problems with gnatmem. - * gnatprep: Preprocessing Using gnatprep. - * gnatstub: Creating Sample Bodies Using gnatstub. - * gnatxref: The Cross-Referencing Tools gnatxref and gnatfind. - * GNU make: Using gnatmake in a Makefile. - * GVD: Introduction to Glide and GVD. - * Hiding of Declarations: Output and Error Message Control. - * HT: Source Representation. - * Implicit dereferencing: Output and Error Message Control. - * Inline <1>: Inlining of Subprograms. - * Inline: Source Dependencies. - * Inlining: Comparison between GNAT and Conventional Ada Library Models. - * Inlining, warnings: Output and Error Message Control. - * Intel_CPU package body: Intel_CPU Package Body. - * Intel_CPU package specification: Intel_CPU Package Specification. - * Interfaces <1>: Naming Conventions for GNAT Source Files. - * Interfaces: Search Paths for gnatbind. - * Interfacing to Ada: Calling Conventions. - * Interfacing to Assembly: Calling Conventions. - * Interfacing to C: Calling Conventions. - * Interfacing to C++: Calling Conventions. - * Interfacing to COBOL: Calling Conventions. - * Interfacing to Fortran: Calling Conventions. - * Internal trees, writing to file: Auxiliary Output Control. - * Latin-1 <1>: Latin-1. - * Latin-1: Source Representation. - * Latin-2: Other 8-Bit Codes. - * Latin-3: Other 8-Bit Codes. - * Latin-4: Other 8-Bit Codes. - * Latin-5: Other 8-Bit Codes. - * LF: Source Representation. - * Library browser: The GNAT Library Browser gnatls. - * Library tasks, elaboration issues: Elaboration Issues for Library Tasks. - * Library, building, installing: GNAT and Libraries. - * Linker libraries: Switches for gnatmake. - * Machine_Overflows: Run-Time Checks. - * Main Program: Running gnatbind. - * make: Using the GNU make Utility. - * makefile: Using gnatmake in a Makefile. - * Mixed Language Programming: Mixed Language Programming. - * Multiple units, syntax checking: Using gcc for Syntax Checking. - * n (gnatmem): Switches for gnatmem. - * No code generated: Compiling Programs. - * No_Entry_Calls_In_Elaboration_Code: Elaboration Issues for Library Tasks. - * Object file list: Running gnatbind. - * Order of elaboration: Elaboration Order Handling in GNAT. - * Other Ada compilers: Calling Conventions. - * Overflow checks <1>: Controlling Run-Time Checks. - * Overflow checks: Run-Time Checks. - * Parallel make: Switches for gnatmake. - * Performance: Performance Considerations. - * pragma Elaborate: Controlling the Elaboration Order in Ada 95. - * pragma Elaborate_All: Controlling the Elaboration Order in Ada 95. - * pragma Elaborate_Body: Controlling the Elaboration Order in Ada 95. - * pragma Inline: Inlining of Subprograms. - * pragma Preelaborate: Controlling the Elaboration Order in Ada 95. - * pragma Pure: Controlling the Elaboration Order in Ada 95. - * pragma Suppress: Controlling Run-Time Checks. - * pragma Unsuppress: Controlling Run-Time Checks. - * Pragmas, configuration: Configuration Pragmas. - * Preelaborate: Controlling the Elaboration Order in Ada 95. - * Pure: Controlling the Elaboration Order in Ada 95. - * Recompilation, by gnatmake: Notes on the Command Line. - * Rounding, biased: Output and Error Message Control. - * RTL: Switches for gcc. - * SDP_Table_Build: Running gnatbind. - * Search paths, for gnatmake: Switches for gnatmake. - * Shift JIS Coding: Wide Character Encodings. - * Source file, end: Source Representation. - * Source files, suppressing search: Switches for gnatmake. - * Source files, use by binder: Running gnatbind. - * Source_File_Name pragma <1>: Alternative File Naming Schemes. - * Source_File_Name pragma: Using Other File Names. - * Source_Reference: Switches for gnatchop. - * Stack Overflow Checking: Stack Overflow Checking. - * stack traceback: Stack Traceback. - * stack unwinding: Stack Traceback. - * Stdcall: Calling Conventions. - * stderr: Output and Error Message Control. - * stdout: Output and Error Message Control. - * storage, pool, memory corruption: Finding Memory Problems with GNAT Debug Pool. - * Stubbed: Calling Conventions. - * Style checking: Style Checking. - * SUB: Source Representation. - * Subunits: Generating Object Files. - * Suppress <1>: Controlling Run-Time Checks. - * Suppress: Run-Time Checks. - * Suppressing checks: Run-Time Checks. - * System <1>: Naming Conventions for GNAT Source Files. - * System: Search Paths for gnatbind. - * System.IO: Search Paths and the Run-Time Library (RTL). - * Task switching: Ada Tasks. - * Tasks: Ada Tasks. - * Time Slicing: Run-Time Control. - * Time stamp checks, in binder: Binder Error Message Control. - * traceback: Stack Traceback. - * traceback, non-symbolic: Non-Symbolic Traceback. - * traceback, symbolic: Symbolic Traceback. - * Tree file: Tree Files. - * Typographical conventions: Conventions. - * Unsuppress <1>: Controlling Run-Time Checks. - * Unsuppress: Run-Time Checks. - * Upper-Half Coding: Wide Character Encodings. - * Validity Checking: Validity Checking. - * Version skew (avoided by gnatmake): Running a Simple Ada Program. - * Volatile parameter: The Volatile Parameter. - * VT: Source Representation. - * Warning messages: Output and Error Message Control. - * Warnings: Binder Error Message Control. - * Warnings, treat as error: Output and Error Message Control. - * Win32: Calling Conventions. - * Writing internal trees: Auxiliary Output Control. - * Zero Cost Exceptions: Running gnatbind. - - -  - Tag Table: - Node: Top91 - Node: About This Guide8875 - Node: What This Guide Contains9384 - Node: What You Should Know before Reading This Guide13729 - Node: Related Information14137 - Node: Conventions14860 - Node: Getting Started with GNAT15754 - Node: Running GNAT16195 - Node: Running a Simple Ada Program16797 - Node: Running a Program with Multiple Units20151 - Node: Using the gnatmake Utility22382 - Node: Introduction to Glide and GVD24782 - Node: Building a New Program with Glide25524 - Node: Simple Debugging with GVD30862 - Node: Other Glide Features33899 - Node: The GNAT Compilation Model35782 - Node: Source Representation37112 - Node: Foreign Language Representation38898 - Node: Latin-139384 - Node: Other 8-Bit Codes40250 - Node: Wide Character Encodings42343 - Node: File Naming Rules46149 - Node: Using Other File Names48438 - Node: Alternative File Naming Schemes50791 - Node: Generating Object Files56023 - Node: Source Dependencies58737 - Node: The Ada Library Information Files62260 - Node: Binding an Ada Program64393 - Node: Mixed Language Programming66241 - Node: Interfacing to C66518 - Node: Calling Conventions69024 - Node: Building Mixed Ada & C++ Programs74948 - Node: Interfacing to C++76029 - Node: Linking a Mixed C++ & Ada Program77069 - Node: A Simple Example80103 - Node: Adapting the Run Time to a New C++ Compiler83015 - Node: Comparison between GNAT and C/C++ Compilation Models84031 - Node: Comparison between GNAT and Conventional Ada Library Models85760 - Node: Compiling Using gcc88411 - Node: Compiling Programs88906 - Node: Switches for gcc91856 - Node: Output and Error Message Control101040 - Node: Debugging and Assertion Control119126 - Node: Validity Checking120456 - Node: Style Checking126603 - Node: Run-Time Checks138076 - Node: Stack Overflow Checking142060 - Node: Run-Time Control144147 - Node: Using gcc for Syntax Checking145041 - Node: Using gcc for Semantic Checking146540 - Node: Compiling Ada 83 Programs148018 - Node: Character Set Control149439 - Node: File Naming Control152366 - Node: Subprogram Inlining Control152874 - Node: Auxiliary Output Control154215 - Node: Debugging Control155646 - Node: Units to Sources Mapping Files163086 - Node: Search Paths and the Run-Time Library (RTL)164476 - Node: Order of Compilation Issues167647 - Node: Examples169348 - Node: Binding Using gnatbind169916 - Node: Running gnatbind171778 - Node: Generating the Binder Program in C202539 - Node: Consistency-Checking Modes219984 - Node: Binder Error Message Control221479 - Node: Elaboration Control223745 - Node: Output Control224970 - Node: Binding with Non-Ada Main Programs227411 - Node: Binding Programs with No Main Subprogram230551 - Node: Summary of Binder Switches231374 - Node: Command-Line Access234697 - Node: Search Paths for gnatbind235702 - Node: Examples of gnatbind Usage238268 - Node: Linking Using gnatlink240039 - Node: Running gnatlink240778 - Node: Switches for gnatlink242763 - Node: Setting Stack Size from gnatlink247036 - Node: Setting Heap Size from gnatlink247890 - Node: The GNAT Make Program gnatmake248705 - Node: Running gnatmake250156 - Node: Switches for gnatmake251815 - Node: Mode Switches for gnatmake264779 - Node: Notes on the Command Line265937 - Node: How gnatmake Works268833 - Node: Examples of gnatmake Usage271003 - Node: Renaming Files Using gnatchop272130 - Node: Handling Files with Multiple Units272719 - Node: Operating gnatchop in Compilation Mode274040 - Node: Command Line for gnatchop277363 - Node: Switches for gnatchop278828 - Node: Examples of gnatchop Usage282609 - Node: Configuration Pragmas283968 - Node: Handling of Configuration Pragmas285520 - Node: The Configuration Pragmas Files286379 - Node: Handling Arbitrary File Naming Conventions Using gnatname287742 - Node: Arbitrary File Naming Conventions288150 - Node: Running gnatname289411 - Node: Switches for gnatname290870 - Node: Examples of gnatname Usage294004 - Node: GNAT Project Manager294805 - Node: Introduction295467 - Node: Project Files296563 - Node: Examples of Project Files299766 - Node: Common Sources with Different Switches and Different Output Directories300240 - Node: Source Files303271 - Node: Specifying the Object Directory303747 - Node: Specifying the Exec Directory304679 - Node: Project File Packages305447 - Node: Specifying Switch Settings306456 - Node: Main Subprograms308424 - Node: Source File Naming Conventions309088 - Node: Source Language(s)309588 - Node: Using External Variables310029 - Node: Importing Other Projects312870 - Node: Extending a Project315978 - Node: Project File Syntax318449 - Node: Basic Syntax319811 - Node: Packages320819 - Node: Expressions321973 - Node: String Types323871 - Node: Variables325174 - Node: Attributes328202 - Node: Associative Array Attributes333635 - Node: case Constructions334480 - Node: Objects and Sources in Project Files336277 - Node: Object Directory336857 - Node: Exec Directory337848 - Node: Source Directories338677 - Node: Source File Names340044 - Node: Importing Projects342381 - Node: Project Extension345160 - Node: External References in Project Files346839 - Node: Packages in Project Files348582 - Node: Variables from Imported Projects350978 - Node: Naming Schemes352650 - Node: Library Projects356623 - Node: Switches Related to Project Files359517 - Node: Tools Supporting Project Files361221 - Node: gnatmake and Project Files361553 - Node: Switches and Project Files362006 - Node: Project Files and Main Subprograms367750 - Node: The GNAT Driver and Project Files369675 - Node: Glide and Project Files373343 - Node: An Extended Example373982 - Node: Project File Complete Syntax376977 - Node: Elaboration Order Handling in GNAT379769 - Node: Elaboration Code in Ada 95380789 - Node: Checking the Elaboration Order in Ada 95385435 - Node: Controlling the Elaboration Order in Ada 95389436 - Node: Controlling Elaboration in GNAT - Internal Calls397753 - Node: Controlling Elaboration in GNAT - External Calls403460 - Node: Default Behavior in GNAT - Ensuring Safety407194 - Node: Elaboration Issues for Library Tasks411277 - Node: Mixing Elaboration Models424482 - Node: What to Do If the Default Elaboration Behavior Fails426983 - Node: Elaboration for Access-to-Subprogram Values437298 - Node: Summary of Procedures for Elaboration Control439105 - Node: Other Elaboration Order Considerations440268 - Node: The Cross-Referencing Tools gnatxref and gnatfind445497 - Node: gnatxref Switches447161 - Node: gnatfind Switches450600 - Node: Project Files for gnatxref and gnatfind456196 - Node: Regular Expressions in gnatfind and gnatxref459302 - Node: Examples of gnatxref Usage462081 - Node: Examples of gnatfind Usage465880 - Node: File Name Krunching Using gnatkr468083 - Node: About gnatkr468697 - Node: Using gnatkr470019 - Node: Krunching Method470910 - Node: Examples of gnatkr Usage474147 - Node: Preprocessing Using gnatprep474637 - Node: Using gnatprep475148 - Node: Switches for gnatprep476000 - Node: Form of Definitions File478122 - Node: Form of Input Text for gnatprep478861 - Node: The GNAT Library Browser gnatls482480 - Node: Running gnatls483009 - Node: Switches for gnatls485519 - Node: Examples of gnatls Usage487414 - Node: GNAT and Libraries489603 - Node: Creating an Ada Library490131 - Node: Installing an Ada Library492971 - Node: Using an Ada Library495328 - Node: Creating an Ada Library to be Used in a Non-Ada Context496519 - Node: Rebuilding the GNAT Run-Time Library502487 - Node: Using the GNU make Utility503394 - Node: Using gnatmake in a Makefile504240 - Node: Automatically Creating a List of Directories508448 - Node: Generating the Command Line Switches511586 - Node: Overcoming Command Line Length Limits512564 - Node: Finding Memory Problems with gnatmem514869 - Node: Running gnatmem (GDB Mode)516220 - Node: Running gnatmem (GMEM Mode)518657 - Node: Switches for gnatmem519915 - Node: Examples of gnatmem Usage521023 - Node: GDB and GMEM Modes526247 - Node: Implementation Note526888 - Node: gnatmem Using GDB Mode527118 - Node: gnatmem Using GMEM Mode528531 - Node: Finding Memory Problems with GNAT Debug Pool529177 - Node: Creating Sample Bodies Using gnatstub533881 - Node: Running gnatstub534676 - Node: Switches for gnatstub535430 - Node: Reducing the Size of Ada Executables with gnatelim537562 - Node: About gnatelim538095 - Node: Eliminate Pragma539183 - Node: Tree Files540191 - Node: Preparing Tree and Bind Files for gnatelim541080 - Node: Running gnatelim543082 - Node: Correcting the List of Eliminate Pragmas545077 - Node: Making Your Executables Smaller545858 - Node: Summary of the gnatelim Usage Cycle546680 - Node: Other Utility Programs547489 - Node: Using Other Utility Programs with GNAT548017 - Node: The gnatpsta Utility Program548705 - Node: The External Symbol Naming Scheme of GNAT549999 - Node: Ada Mode for Glide551996 - Node: Converting Ada Files to html with gnathtml553947 - Node: Installing gnathtml557520 - Node: Running and Debugging Ada Programs558184 - Node: The GNAT Debugger GDB559578 - Node: Running GDB562696 - Node: Introduction to GDB Commands563712 - Node: Using Ada Expressions568577 - Node: Calling User-Defined Subprograms569771 - Node: Using the Next Command in a Function572191 - Node: Ada Exceptions573356 - Node: Ada Tasks574310 - Node: Debugging Generic Units576373 - Node: GNAT Abnormal Termination or Failure to Terminate577776 - Node: Naming Conventions for GNAT Source Files580355 - Node: Getting Internal Debugging Information582946 - Node: Stack Traceback584148 - Node: Non-Symbolic Traceback585185 - Node: Tracebacks From an Unhandled Exception585646 - Node: Tracebacks From Exception Occurrences (non-symbolic)589583 - Node: Tracebacks From Anywhere in a Program (non-symbolic)590866 - Node: Symbolic Traceback592709 - Node: Tracebacks From Exception Occurrences (symbolic)593432 - Node: Tracebacks From Anywhere in a Program (symbolic)594841 - Node: Inline Assembler596033 - Node: Basic Assembler Syntax597731 - Node: A Simple Example of Inline Assembler599508 - Node: Output Variables in Inline Assembler602675 - Node: Input Variables in Inline Assembler610055 - Node: Inlining Inline Assembler Code612563 - Node: Other Asm Functionality614497 - Node: The Clobber Parameter614932 - Node: The Volatile Parameter616931 - Node: A Complete Example618123 - Node: Check_CPU Procedure619097 - Node: Intel_CPU Package Specification634144 - Node: Intel_CPU Package Body643572 - Node: Performance Considerations652730 - Node: Controlling Run-Time Checks653764 - Node: Optimization Levels655749 - Node: Debugging Optimized Code657606 - Node: Inlining of Subprograms661339 - Node: GNU Free Documentation License664863 - Node: Index687292 -  - End Tag Table --- 0 ---- diff -Nrc3pad gcc-3.3.2/gcc/ada/gnat_ug_vms.info gcc-3.3.3/gcc/ada/gnat_ug_vms.info *** gcc-3.3.2/gcc/ada/gnat_ug_vms.info Thu Oct 16 20:23:57 2003 --- gcc-3.3.3/gcc/ada/gnat_ug_vms.info Thu Jan 1 00:00:00 1970 *************** *** 1,17933 **** - This is ada/gnat_ug_vms.info, produced by makeinfo version 4.2 from - ada/gnat_ug_vms.texi. - - Copyright (C) 1995-2002, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT User's Guide for OpenVMS Alpha", and with - no Back-Cover Texts. A copy of the license is included in the section - entitled "GNU Free Documentation License". -  - File: gnat_ug_vms.info, Node: Top, Next: About This Guide, Prev: (dir), Up: (dir) - - GNAT User's Guide - ***************** - - GNAT User's Guide for OpenVMS Alpha - - GNAT, The GNU Ada 95 Compiler - - GNAT Version for GCC 3.3.2 - - Ada Core Technologies, Inc. - - Copyright (C) 1995-2002, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT User's Guide for OpenVMS Alpha", and with - no Back-Cover Texts. A copy of the license is included in the section - entitled "GNU Free Documentation License". - * Menu: - - * About This Guide:: - * Getting Started with GNAT:: - * The GNAT Compilation Model:: - * Compiling Using GNAT COMPILE:: - * Binding Using GNAT BIND:: - * Linking Using GNAT LINK:: - * The GNAT Make Program GNAT MAKE:: - * Renaming Files Using GNAT CHOP:: - * Configuration Pragmas:: - * Handling Arbitrary File Naming Conventions Using gnatname:: - * GNAT Project Manager:: - * Elaboration Order Handling in GNAT:: - * The Cross-Referencing Tools GNAT XREF and GNAT FIND:: - * File Name Krunching Using GNAT KRUNCH:: - * Preprocessing Using GNAT PREPROCESS:: - * The GNAT Run-Time Library Builder GNAT LIBRARY:: - * The GNAT Library Browser GNAT LIST:: - * Finding Memory Problems with GNAT Debug Pool:: - * Creating Sample Bodies Using GNAT STUB:: - * Reducing the Size of Ada Executables with GNAT ELIM:: - * Other Utility Programs:: - * Compatibility with DEC Ada:: - * Running and Debugging Ada Programs:: - * Inline Assembler:: - * Performance Considerations:: - * GNU Free Documentation License:: - * Index:: - - --- The Detailed Node Listing --- - - About This Guide - - * What This Guide Contains:: - * What You Should Know before Reading This Guide:: - * Related Information:: - * Conventions:: - - - Getting Started with GNAT - - * Running GNAT:: - * Running a Simple Ada Program:: - * Running a Program with Multiple Units:: - * Using the GNAT MAKE Utility:: - * Editing with EMACS:: - - The GNAT Compilation Model - - * Source Representation:: - * Foreign Language Representation:: - * File Naming Rules:: - * Using Other File Names:: - * Alternative File Naming Schemes:: - * Generating Object Files:: - * Source Dependencies:: - * The Ada Library Information Files:: - * Binding an Ada Program:: - * Mixed Language Programming:: - * Building Mixed Ada & C++ Programs:: - * Comparison between GNAT and C/C++ Compilation Models:: - * Comparison between GNAT and Conventional Ada Library Models:: - - Foreign Language Representation - - * Latin-1:: - * Other 8-Bit Codes:: - * Wide Character Encodings:: - - Compiling Ada Programs With GNAT COMPILE - - * Compiling Programs:: - * Qualifiers for GNAT COMPILE:: - * Search Paths and the Run-Time Library (RTL):: - * Order of Compilation Issues:: - * Examples:: - - Qualifiers for GNAT COMPILE - - * Output and Error Message Control:: - * Debugging and Assertion Control:: - * Run-Time Checks:: - * Stack Overflow Checking:: - * Run-Time Control:: - * Validity Checking:: - * Style Checking:: - * Using GNAT COMPILE for Syntax Checking:: - * Using GNAT COMPILE for Semantic Checking:: - * Compiling Ada 83 Programs:: - * Character Set Control:: - * File Naming Control:: - * Subprogram Inlining Control:: - * Auxiliary Output Control:: - * Debugging Control:: - * Units to Sources Mapping Files:: - - Binding Ada Programs With GNAT BIND - - * Running GNAT BIND:: - * Generating the Binder Program in C:: - * Consistency-Checking Modes:: - * Binder Error Message Control:: - * Elaboration Control:: - * Output Control:: - * Binding with Non-Ada Main Programs:: - * Binding Programs with No Main Subprogram:: - * Summary of Binder Qualifiers:: - * Command-Line Access:: - * Search Paths for GNAT BIND:: - * Examples of GNAT BIND Usage:: - - Linking Using GNAT LINK - - * Running GNAT LINK:: - * Qualifiers for GNAT LINK:: - * Setting Stack Size from GNAT LINK:: - * Setting Heap Size from GNAT LINK:: - - The GNAT Make Program GNAT MAKE - - * Running GNAT MAKE:: - * Qualifiers for GNAT MAKE:: - * Mode Qualifiers for GNAT MAKE:: - * Notes on the Command Line:: - * How GNAT MAKE Works:: - * Examples of GNAT MAKE Usage:: - - Renaming Files Using GNAT CHOP - - * Handling Files with Multiple Units:: - * Operating GNAT CHOP in Compilation Mode:: - * Command Line for GNAT CHOP:: - * Qualifiers for GNAT CHOP:: - * Examples of GNAT CHOP Usage:: - - Configuration Pragmas - - * Handling of Configuration Pragmas:: - * The Configuration Pragmas Files:: - - Handling Arbitrary File Naming Conventions Using gnatname - - * Arbitrary File Naming Conventions:: - * Running gnatname:: - * Qualifiers for gnatname:: - * Examples of gnatname Usage:: - - GNAT Project Manager - - * Introduction:: - * Examples of Project Files:: - * Project File Syntax:: - * Objects and Sources in Project Files:: - * Importing Projects:: - * Project Extension:: - * External References in Project Files:: - * Packages in Project Files:: - * Variables from Imported Projects:: - * Naming Schemes:: - * Library Projects:: - * Qualifiers Related to Project Files:: - * Tools Supporting Project Files:: - * An Extended Example:: - * Project File Complete Syntax:: - - Elaboration Order Handling in GNAT - - * Elaboration Code in Ada 95:: - * Checking the Elaboration Order in Ada 95:: - * Controlling the Elaboration Order in Ada 95:: - * Controlling Elaboration in GNAT - Internal Calls:: - * Controlling Elaboration in GNAT - External Calls:: - * Default Behavior in GNAT - Ensuring Safety:: - * Elaboration Issues for Library Tasks:: - * Mixing Elaboration Models:: - * What to Do If the Default Elaboration Behavior Fails:: - * Elaboration for Access-to-Subprogram Values:: - * Summary of Procedures for Elaboration Control:: - * Other Elaboration Order Considerations:: - - The Cross-Referencing Tools GNAT XREF and GNAT FIND - - * GNAT XREF Qualifiers:: - * GNAT FIND Qualifiers:: - * Project Files for GNAT XREF and GNAT FIND:: - * Regular Expressions in GNAT FIND and GNAT XREF:: - * Examples of GNAT XREF Usage:: - * Examples of GNAT FIND Usage:: - - File Name Krunching Using GNAT KRUNCH - - * About GNAT KRUNCH:: - * Using GNAT KRUNCH:: - * Krunching Method:: - * Examples of GNAT KRUNCH Usage:: - - Preprocessing Using GNAT PREPROCESS - - * Using GNAT PREPROCESS:: - * Qualifiers for GNAT PREPROCESS:: - * Form of Definitions File:: - * Form of Input Text for GNAT PREPROCESS:: - - The GNAT Run-Time Library Builder GNAT LIBRARY - - * Running GNAT LIBRARY:: - * Qualifiers for GNAT LIBRARY:: - * Examples of GNAT LIBRARY Usage:: - - The GNAT Library Browser GNAT LIST - - * Running GNAT LIST:: - * Qualifiers for GNAT LIST:: - * Examples of GNAT LIST Usage:: - - - Finding Memory Problems with GNAT Debug Pool - - Creating Sample Bodies Using GNAT STUB - - * Running GNAT STUB:: - * Qualifiers for GNAT STUB:: - - Reducing the Size of Ada Executables with GNAT ELIM - - * About GNAT ELIM:: - * Eliminate Pragma:: - * Tree Files:: - * Preparing Tree and Bind Files for GNAT ELIM:: - * Running GNAT ELIM:: - * Correcting the List of Eliminate Pragmas:: - * Making Your Executables Smaller:: - * Summary of the GNAT ELIM Usage Cycle:: - - Other Utility Programs - - * Using Other Utility Programs with GNAT:: - * The GNAT STANDARD Utility Program:: - * The External Symbol Naming Scheme of GNAT:: - * Ada Mode for Glide:: - * Converting Ada Files to html with gnathtml:: - * LSE:: - - Compatibility with DEC Ada - - * Ada 95 Compatibility:: - * Differences in the Definition of Package System:: - * Language-Related Features:: - * The Package STANDARD:: - * The Package SYSTEM:: - * Tasking and Task-Related Features:: - * Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems:: - * Pragmas and Pragma-Related Features:: - * Library of Predefined Units:: - * Bindings:: - * Main Program Definition:: - * Implementation-Defined Attributes:: - * Compiler and Run-Time Interfacing:: - * Program Compilation and Library Management:: - * Input-Output:: - * Implementation Limits:: - * Tools:: - - Language-Related Features - - * Integer Types and Representations:: - * Floating-Point Types and Representations:: - * Pragmas Float_Representation and Long_Float:: - * Fixed-Point Types and Representations:: - * Record and Array Component Alignment:: - * Address Clauses:: - * Other Representation Clauses:: - - Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems - - * Assigning Task IDs:: - * Task IDs and Delays:: - * Task-Related Pragmas:: - * Scheduling and Task Priority:: - * The Task Stack:: - * External Interrupts:: - - Pragmas and Pragma-Related Features - - * Restrictions on the Pragma INLINE:: - * Restrictions on the Pragma INTERFACE:: - * Restrictions on the Pragma SYSTEM_NAME:: - - Library of Predefined Units - - * Changes to DECLIB:: - - Bindings - - * Shared Libraries and Options Files:: - * Interfaces to C:: - - Running and Debugging Ada Programs - - * The GNAT Debugger GDB:: - * Running GDB:: - * Introduction to GDB Commands:: - * Using Ada Expressions:: - * Calling User-Defined Subprograms:: - * Using the Next Command in a Function:: - * Ada Exceptions:: - * Ada Tasks:: - * Debugging Generic Units:: - * GNAT Abnormal Termination or Failure to Terminate:: - * Naming Conventions for GNAT Source Files:: - * Getting Internal Debugging Information:: - * Stack Traceback:: - - Inline Assembler - - * Basic Assembler Syntax:: - * A Simple Example of Inline Assembler:: - * Output Variables in Inline Assembler:: - * Input Variables in Inline Assembler:: - * Inlining Inline Assembler Code:: - * Other Asm Functionality:: - * A Complete Example:: - - - - Performance Considerations - - * Controlling Run-Time Checks:: - * Optimization Levels:: - * Debugging Optimized Code:: - * Inlining of Subprograms:: - * Coverage Analysis:: - - * Index:: - -  - File: gnat_ug_vms.info, Node: About This Guide, Next: Getting Started with GNAT, Prev: Top, Up: Top - - About This Guide - **************** - - This guide describes the use of of GNAT, a full language compiler for - the Ada 95 programming language, implemented on DIGITAL OpenVMS Alpha - Systems. It describes the features of the compiler and tools, and - details how to use them to build Ada 95 applications. - - * Menu: - - * What This Guide Contains:: - * What You Should Know before Reading This Guide:: - * Related Information:: - * Conventions:: - -  - File: gnat_ug_vms.info, Node: What This Guide Contains, Next: What You Should Know before Reading This Guide, Up: About This Guide - - What This Guide Contains - ======================== - - This guide contains the following chapters: - * *Note Getting Started with GNAT::, describes how to get started - compiling and running Ada programs with the GNAT Ada programming - environment. - - * *Note The GNAT Compilation Model::, describes the compilation - model used by GNAT. - - * *Note Compiling Using GNAT COMPILE::, describes how to compile Ada - programs with `GNAT COMPILE', the Ada compiler. - - * *Note Binding Using GNAT BIND::, describes how to perform binding - of Ada programs with `GNAT BIND', the GNAT binding utility. - - * *Note Linking Using GNAT LINK::, describes `GNAT LINK', a program - that provides for linking using the GNAT run-time library to - construct a program. `GNAT LINK' can also incorporate foreign - language object units into the executable. - - * *Note The GNAT Make Program GNAT MAKE::, describes `GNAT MAKE', a - utility that automatically determines the set of sources needed by - an Ada compilation unit, and executes the necessary compilations - binding and link. - - * *Note Renaming Files Using GNAT CHOP::, describes `GNAT CHOP', a - utility that allows you to preprocess a file that contains Ada - source code, and split it into one or more new files, one for each - compilation unit. - - * *Note Configuration Pragmas::, describes the configuration pragmas - handled by GNAT. - - * *Note Handling Arbitrary File Naming Conventions Using gnatname::, - shows how to override the default GNAT file naming conventions, - either for an individual unit or globally. - - * *Note GNAT Project Manager::, describes how to use project files - to organize large projects. - - * *Note Elaboration Order Handling in GNAT::, describes how GNAT - helps you deal with elaboration order issues. - - * *Note The Cross-Referencing Tools GNAT XREF and GNAT FIND::, - discusses `GNAT XREF' and `GNAT FIND', two tools that provide an - easy way to navigate through sources. - - * *Note File Name Krunching Using GNAT KRUNCH::, describes the `GNAT - KRUNCH' file name krunching utility, used to handle shortened file - names on operating systems with a limit on the length of names. - - * *Note Preprocessing Using GNAT PREPROCESS::, describes `GNAT - PREPROCESS', a preprocessor utility that allows a single source - file to be used to generate multiple or parameterized source - files, by means of macro substitution. - - * *Note The GNAT Library Browser GNAT LIST::, describes `GNAT LIST', - a utility that displays information about compiled units, - including dependences on the corresponding sources files, and - consistency of compilations. - - * *Note Finding Memory Problems with GNAT Debug Pool::, describes - how to use the GNAT-specific Debug Pool in order to detect as - early as possible the use of incorrect memory references. - - * *Note Creating Sample Bodies Using GNAT STUB::, discusses `GNAT - STUB', a utility that generates empty but compilable bodies for - library units. - - * *Note Reducing the Size of Ada Executables with GNAT ELIM::, - describes `GNAT ELIM', a tool which detects unused subprograms and - helps the compiler to create a smaller executable for the program. - - * *Note Other Utility Programs::, discusses several other GNAT - utilities, including `GNAT STANDARD'. - - * *Note Running and Debugging Ada Programs::, describes how to run - and debug Ada programs. - - * *Note Inline Assembler::, shows how to use the inline assembly - facility in an Ada program. - - * *Note Performance Considerations::, reviews the trade offs between - using defaults or options in program development. - - * *Note Compatibility with DEC Ada::, details the compatibility of - GNAT with DEC Ada 83 for OpenVMS Alpha. - -  - File: gnat_ug_vms.info, Node: What You Should Know before Reading This Guide, Next: Related Information, Prev: What This Guide Contains, Up: About This Guide - - What You Should Know before Reading This Guide - ============================================== - - This user's guide assumes that you are familiar with Ada 95 language, as - described in the International Standard ANSI/ISO/IEC-8652:1995, Jan - 1995. - -  - File: gnat_ug_vms.info, Node: Related Information, Next: Conventions, Prev: What You Should Know before Reading This Guide, Up: About This Guide - - Related Information - =================== - - For further information about related tools, refer to the following - documents: - - * `GNAT Reference Manual', which contains all reference material for - the GNAT implementation of Ada 95. - - * `Ada 95 Language Reference Manual', which contains all reference - material for the Ada 95 programming language. - - * `Debugging with GDB' , located in the GNU:[DOCS] directory, - contains all details on the use of the GNU source-level debugger. - - * `GNU EMACS Manual' , located in the GNU:[DOCS] directory if the - EMACS kit is installed, contains full information on the - extensible editor and programming environment EMACS. - - -  - File: gnat_ug_vms.info, Node: Conventions, Prev: Related Information, Up: About This Guide - - Conventions - =========== - - Following are examples of the typographical and graphic conventions used - in this guide: - - * `Functions', `utility program names', `standard names', and - `classes'. - - * `Option flags' - - * `File Names', `button names', and `field names'. - - * VARIABLES. - - * _Emphasis_. - - * [optional information or parameters] - - * Examples are described by text - and then shown this way. - - Commands that are entered by the user are preceded in this manual by the - characters "`$ '" (dollar sign followed by space). If your system uses - this sequence as a prompt, then the commands will appear exactly as you - see them in the manual. If your system uses some other prompt, then the - command will appear with the `$' replaced by whatever prompt character - you are using. - -  - File: gnat_ug_vms.info, Node: Getting Started with GNAT, Next: The GNAT Compilation Model, Prev: About This Guide, Up: Top - - Getting Started with GNAT - ************************* - - This chapter describes some simple ways of using GNAT to build - executable Ada programs. - - * Menu: - - * Running GNAT:: - * Running a Simple Ada Program:: - - * Running a Program with Multiple Units:: - - * Using the GNAT MAKE Utility:: - * Editing with EMACS:: - -  - File: gnat_ug_vms.info, Node: Running GNAT, Next: Running a Simple Ada Program, Up: Getting Started with GNAT - - Running GNAT - ============ - - Three steps are needed to create an executable file from an Ada source - file: - - 1. The source file(s) must be compiled. - - 2. The file(s) must be bound using the GNAT binder. - - 3. All appropriate object files must be linked to produce an - executable. - - All three steps are most commonly handled by using the `GNAT MAKE' - utility program that, given the name of the main program, automatically - performs the necessary compilation, binding and linking steps. - -  - File: gnat_ug_vms.info, Node: Running a Simple Ada Program, Next: Running a Program with Multiple Units, Prev: Running GNAT, Up: Getting Started with GNAT - - Running a Simple Ada Program - ============================ - - Any text editor may be used to prepare an Ada program. If `Glide' is - used, the optional Ada mode may be helpful in laying out the program. - The program text is a normal text file. We will suppose in our initial - example that you have used your editor to prepare the following - standard format text file: - - with Ada.Text_IO; use Ada.Text_IO; - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - This file should be named `HELLO.ADB'. With the normal default file - naming conventions, GNAT requires that each file contain a single - compilation unit whose file name is the unit name, with periods - replaced by hyphens; the extension is `ads' for a spec and `adb' for a - body. You can override this default file naming convention by use of - the special pragma `Source_File_Name' (*note Using Other File Names::). - Alternatively, if you want to rename your files according to this - default convention, which is probably more convenient if you will be - using GNAT for all your compilations, then the `GNAT CHOP' utility can - be used to generate correctly-named source files (*note Renaming Files - Using GNAT CHOP::). - - You can compile the program using the following command (`$' is used - as the command prompt in the examples in this document): - - $ GNAT COMPILE HELLO.ADB - - `GNAT COMPILE' is the command used to run the compiler. This compiler is - capable of compiling programs in several languages, including Ada 95 and - C. It assumes that you have given it an Ada program if the file - extension is either `.ADS' or `.ADB', and it will then call the GNAT - compiler to compile the specified file. - - This compile command generates a file `HELLO.OBJ', which is the - object file corresponding to your Ada program. It also generates an - "Ada Library Information" file `HELLO.ALI', which contains additional - information used to check that an Ada program is consistent. To build - an executable file, use `GNAT BIND' to bind the program and `GNAT LINK' - to link it. The argument to both `GNAT BIND' and `GNAT LINK' is the - name of the `ali' file, but the default extension of `.ALI' can be - omitted. This means that in the most common case, the argument is - simply the name of the main program: - - $ GNAT BIND hello - $ GNAT LINK hello - - A simpler method of carrying out these steps is to use `GNAT MAKE', a - master program that invokes all the required compilation, binding and - linking tools in the correct order. In particular, `GNAT MAKE' - automatically recompiles any sources that have been modified since they - were last compiled, or sources that depend on such modified sources, so - that "version skew" is avoided. - - $ GNAT MAKE HELLO.ADB - - The result is an executable program called `hello', which can be run by - entering: - - $ hello - - assuming that the current directory is on the search path for - executable programs. - - and, if all has gone well, you will see - - Hello WORLD! - - appear in response to this command. - -  - File: gnat_ug_vms.info, Node: Running a Program with Multiple Units, Next: Using the GNAT MAKE Utility, Prev: Running a Simple Ada Program, Up: Getting Started with GNAT - - Running a Program with Multiple Units - ===================================== - - Consider a slightly more complicated example that has three files: a - main program, and the spec and body of a package: - - package Greetings is - procedure Hello; - procedure Goodbye; - end Greetings; - - with Ada.Text_IO; use Ada.Text_IO; - package body Greetings is - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - procedure Goodbye is - begin - Put_Line ("Goodbye WORLD!"); - end Goodbye; - end Greetings; - - with Greetings; - procedure Gmain is - begin - Greetings.Hello; - Greetings.Goodbye; - end Gmain; - - Following the one-unit-per-file rule, place this program in the - following three separate files: - - `GREETINGS.ADS' - spec of package `Greetings' - - `GREETINGS.ADB' - body of package `Greetings' - - `GMAIN.ADB' - body of main program - - To build an executable version of this program, we could use four - separate steps to compile, bind, and link the program, as follows: - - $ GNAT COMPILE GMAIN.ADB - $ GNAT COMPILE GREETINGS.ADB - $ GNAT BIND gmain - $ GNAT LINK gmain - - Note that there is no required order of compilation when using GNAT. - In particular it is perfectly fine to compile the main program first. - Also, it is not necessary to compile package specs in the case where - there is an accompanying body; you only need to compile the body. If - you want to submit these files to the compiler for semantic checking - and not code generation, then use the `/NOLOAD' qualifier: - - $ GNAT COMPILE GREETINGS.ADS /NOLOAD - - Although the compilation can be done in separate steps as in the above - example, in practice it is almost always more convenient to use the - `GNAT MAKE' tool. All you need to know in this case is the name of the - main program's source file. The effect of the above four commands can - be achieved with a single one: - - $ GNAT MAKE GMAIN.ADB - - In the next section we discuss the advantages of using `GNAT MAKE' in - more detail. - -  - File: gnat_ug_vms.info, Node: Using the GNAT MAKE Utility, Next: Editing with EMACS, Prev: Running a Program with Multiple Units, Up: Getting Started with GNAT - - Using the `GNAT MAKE' Utility - ============================= - - If you work on a program by compiling single components at a time using - `GNAT COMPILE', you typically keep track of the units you modify. In - order to build a consistent system, you compile not only these units, - but also any units that depend on the units you have modified. For - example, in the preceding case, if you edit `GMAIN.ADB', you only need - to recompile that file. But if you edit `GREETINGS.ADS', you must - recompile both `GREETINGS.ADB' and `GMAIN.ADB', because both files - contain units that depend on `GREETINGS.ADS'. - - `GNAT BIND' will warn you if you forget one of these compilation - steps, so that it is impossible to generate an inconsistent program as a - result of forgetting to do a compilation. Nevertheless it is tedious and - error-prone to keep track of dependencies among units. One approach to - handle the dependency-bookkeeping is to use a makefile. However, - makefiles present maintenance problems of their own: if the - dependencies change as you change the program, you must make sure that - the makefile is kept up-to-date manually, which is also an error-prone - process. - - The `GNAT MAKE' utility takes care of these details automatically. - Invoke it using either one of the following forms: - - $ GNAT MAKE GMAIN.ADB - $ GNAT MAKE GMAIN - - The argument is the name of the file containing the main program; you - may omit the extension. `GNAT MAKE' examines the environment, - automatically recompiles any files that need recompiling, and binds and - links the resulting set of object files, generating the executable - file, `GMAIN.EXE'. In a large program, it can be extremely helpful to - use `GNAT MAKE', because working out by hand what needs to be - recompiled can be difficult. - - Note that `GNAT MAKE' takes into account all the Ada 95 rules that - establish dependencies among units. These include dependencies that - result from inlining subprogram bodies, and from generic instantiation. - Unlike some other Ada make tools, `GNAT MAKE' does not rely on the - dependencies that were found by the compiler on a previous compilation, - which may possibly be wrong when sources change. `GNAT MAKE' determines - the exact set of dependencies from scratch each time it is run. - -  - File: gnat_ug_vms.info, Node: Editing with EMACS, Prev: Using the GNAT MAKE Utility, Up: Getting Started with GNAT - - Editing with EMACS - ================== - - EMACS is an extensible self-documenting text editor that is available - in a separate VMSINSTAL kit. - - Invoke EMACS by typing "EMACS" at the command prompt. To get started, - click on the EMACS Help menu and run the EMACS Tutorial. In a - character cell terminal, EMACS help is invoked with "Ctrl-h" (also - written as "C-h"), and the tutorial by "C-h t". - - Documentation on EMACS and other tools is available in EMACS under - the pull-down menu button: Help - Info. After selecting Info, use the - middle mouse button to select a topic (e.g. EMACS). - - In a character cell terminal, do "C-h i" to invoke info, and then "m" - (stands for menu) followed by the menu item desired, as in "m EMACS", - to get to the EMACS manual. Help on EMACS is also available by typing - "HELP EMACS" at the DCL command prompt. - - The tutorial is highly recommended in order to learn the intricacies - of EMACS, which is sufficiently extensible to provide for a complete - programming environment and shell for the sophisticated user. - -  - File: gnat_ug_vms.info, Node: The GNAT Compilation Model, Next: Compiling Using GNAT COMPILE, Prev: Getting Started with GNAT, Up: Top - - The GNAT Compilation Model - ************************** - - * Menu: - - * Source Representation:: - * Foreign Language Representation:: - * File Naming Rules:: - * Using Other File Names:: - * Alternative File Naming Schemes:: - * Generating Object Files:: - * Source Dependencies:: - * The Ada Library Information Files:: - * Binding an Ada Program:: - * Mixed Language Programming:: - * Building Mixed Ada & C++ Programs:: - * Comparison between GNAT and C/C++ Compilation Models:: - * Comparison between GNAT and Conventional Ada Library Models:: - - This chapter describes the compilation model used by GNAT. Although - similar to that used by other languages, such as C and C++, this model - is substantially different from the traditional Ada compilation models, - which are based on a library. The model is initially described without - reference to the library-based model. If you have not previously used an - Ada compiler, you need only read the first part of this chapter. The - last section describes and discusses the differences between the GNAT - model and the traditional Ada compiler models. If you have used other - Ada compilers, this section will help you to understand those - differences, and the advantages of the GNAT model. - -  - File: gnat_ug_vms.info, Node: Source Representation, Next: Foreign Language Representation, Up: The GNAT Compilation Model - - Source Representation - ===================== - - Ada source programs are represented in standard text files, using - Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar - 7-bit ASCII set, plus additional characters used for representing - foreign languages (*note Foreign Language Representation:: for support - of non-USA character sets). The format effector characters are - represented using their standard ASCII encodings, as follows: - - `VT' - Vertical tab, `16#0B#' - - `HT' - Horizontal tab, `16#09#' - - `CR' - Carriage return, `16#0D#' - - `LF' - Line feed, `16#0A#' - - `FF' - Form feed, `16#0C#' - - Source files are in standard text file format. In addition, GNAT will - recognize a wide variety of stream formats, in which the end of physical - physical lines is marked by any of the following sequences: `LF', `CR', - `CR-LF', or `LF-CR'. This is useful in accommodating files that are - imported from other operating systems. - - The end of a source file is normally represented by the physical end - of file. However, the control character `16#1A#' (`SUB') is also - recognized as signalling the end of the source file. Again, this is - provided for compatibility with other operating systems where this code - is used to represent the end of file. - - Each file contains a single Ada compilation unit, including any - pragmas associated with the unit. For example, this means you must - place a package declaration (a package "spec") and the corresponding - body in separate files. An Ada "compilation" (which is a sequence of - compilation units) is represented using a sequence of files. Similarly, - you will place each subunit or child unit in a separate file. - -  - File: gnat_ug_vms.info, Node: Foreign Language Representation, Next: File Naming Rules, Prev: Source Representation, Up: The GNAT Compilation Model - - Foreign Language Representation - =============================== - - GNAT supports the standard character sets defined in Ada 95 as well as - several other non-standard character sets for use in localized versions - of the compiler (*note Character Set Control::). - - * Menu: - - * Latin-1:: - * Other 8-Bit Codes:: - * Wide Character Encodings:: - -  - File: gnat_ug_vms.info, Node: Latin-1, Next: Other 8-Bit Codes, Up: Foreign Language Representation - - Latin-1 - ------- - - The basic character set is Latin-1. This character set is defined by ISO - standard 8859, part 1. The lower half (character codes `16#00#' ... - `16#7F#)' is identical to standard ASCII coding, but the upper half is - used to represent additional characters. These include extended letters - used by European languages, such as French accents, the vowels with - umlauts used in German, and the extra letter A-ring used in Swedish. - - For a complete list of Latin-1 codes and their encodings, see the - source file of library unit `Ada.Characters.Latin_1' in file - `A-CHLAT1.ADS'. You may use any of these extended characters freely in - character or string literals. In addition, the extended characters that - represent letters can be used in identifiers. - -  - File: gnat_ug_vms.info, Node: Other 8-Bit Codes, Next: Wide Character Encodings, Prev: Latin-1, Up: Foreign Language Representation - - Other 8-Bit Codes - ----------------- - - GNAT also supports several other 8-bit coding schemes: - - Latin-2 - Latin-2 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-3 - Latin-3 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-4 - Latin-4 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-5 - Latin-4 letters (Cyrillic) allowed in identifiers, with uppercase - and lowercase equivalence. - - IBM PC (code page 437) - This code page is the normal default for PCs in the U.S. It - corresponds to the original IBM PC character set. This set has - some, but not all, of the extended Latin-1 letters, but these - letters do not have the same encoding as Latin-1. In this mode, - these letters are allowed in identifiers with uppercase and - lowercase equivalence. - - IBM PC (code page 850) - This code page is a modification of 437 extended to include all the - Latin-1 letters, but still not with the usual Latin-1 encoding. In - this mode, all these letters are allowed in identifiers with - uppercase and lowercase equivalence. - - Full Upper 8-bit - Any character in the range 80-FF allowed in identifiers, and all - are considered distinct. In other words, there are no uppercase - and lowercase equivalences in this range. This is useful in - conjunction with certain encoding schemes used for some foreign - character sets (e.g. the typical method of representing Chinese - characters on the PC). - - No Upper-Half - No upper-half characters in the range 80-FF are allowed in - identifiers. This gives Ada 83 compatibility for identifier names. - - For precise data on the encodings permitted, and the uppercase and - lowercase equivalences that are recognized, see the file `CSETS.ADB' in - the GNAT compiler sources. You will need to obtain a full source release - of GNAT to obtain this file. - -  - File: gnat_ug_vms.info, Node: Wide Character Encodings, Prev: Other 8-Bit Codes, Up: Foreign Language Representation - - Wide Character Encodings - ------------------------ - - GNAT allows wide character codes to appear in character and string - literals, and also optionally in identifiers, by means of the following - possible encoding schemes: - - Hex Coding - In this encoding, a wide character is represented by the following - five character sequence: - - ESC a b c d - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For example, - ESC A345 is used to represent the wide character with code - `16#A345#'. This scheme is compatible with use of the full - Wide_Character set. - - Upper-Half Coding - The wide character with encoding `16#abcd#' where the upper bit is - on (in other words, "a" is in the range 8-F) is represented as two - bytes, `16#ab#' and `16#cd#'. The second byte cannot be a format - control character, but is not required to be in the upper half. - This method can be also used for shift-JIS or EUC, where the - internal coding matches the external coding. - - Shift JIS Coding - A wide character is represented by a two-character sequence, - `16#ab#' and `16#cd#', with the restrictions described for - upper-half encoding as described above. The internal character - code is the corresponding JIS character according to the standard - algorithm for Shift-JIS conversion. Only characters defined in the - JIS code set table can be used with this encoding method. - - EUC Coding - A wide character is represented by a two-character sequence - `16#ab#' and `16#cd#', with both characters being in the upper - half. The internal character code is the corresponding JIS - character according to the EUC encoding algorithm. Only characters - defined in the JIS code set table can be used with this encoding - method. - - UTF-8 Coding - A wide character is represented using UCS Transformation Format 8 - (UTF-8) as defined in Annex R of ISO 10646-1/Am.2. Depending on - the character value, the representation is a one, two, or three - byte sequence: - 16#0000#-16#007f#: 2#0xxxxxxx# - 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# - 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# - - where the xxx bits correspond to the left-padded bits of the - 16-bit character value. Note that all lower half ASCII characters - are represented as ASCII bytes and all upper half characters and - other wide characters are represented as sequences of upper-half - (The full UTF-8 scheme allows for encoding 31-bit characters as - 6-byte sequences, but in this implementation, all UTF-8 sequences - of four or more bytes length will be treated as illegal). - - Brackets Coding - In this encoding, a wide character is represented by the following - eight character sequence: - - [ " a b c d " ] - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For example, - ["A345"] is used to represent the wide character with code - `16#A345#'. It is also possible (though not required) to use the - Brackets coding for upper half characters. For example, the code - `16#A3#' can be represented as `["A3"]'. - - This scheme is compatible with use of the full Wide_Character set, - and is also the method used for wide character encoding in the - standard ACVC (Ada Compiler Validation Capability) test suite - distributions. - - Note: Some of these coding schemes do not permit the full use of the - Ada 95 character set. For example, neither Shift JIS, nor EUC allow the - use of the upper half of the Latin-1 set. - -  - File: gnat_ug_vms.info, Node: File Naming Rules, Next: Using Other File Names, Prev: Foreign Language Representation, Up: The GNAT Compilation Model - - File Naming Rules - ================= - - The default file name is determined by the name of the unit that the - file contains. The name is formed by taking the full expanded name of - the unit and replacing the separating dots with hyphens and using - uppercase for all letters. - - An exception arises if the file name generated by the above rules - starts with one of the characters A,G,I, or S, and the second character - is a minus. In this case, the character dollar sign is used in place of - the minus. The reason for this special rule is to avoid clashes with - the standard names for child units of the packages System, Ada, - Interfaces, and GNAT, which use the prefixes S- A- I- and G- - respectively. - - The file extension is `.ADS' for a spec and `.ADB' for a body. The - following list shows some examples of these rules. - - `MAIN.ADS' - Main (spec) - - `MAIN.ADB' - Main (body) - - `ARITH_FUNCTIONS.ADS' - Arith_Functions (package spec) - - `ARITH_FUNCTIONS.ADB' - Arith_Functions (package body) - - `FUNC-SPEC.ADS' - Func.Spec (child package spec) - - `FUNC-SPEC.ADB' - Func.Spec (child package body) - - `MAIN-SUB.ADB' - Sub (subunit of Main) - - `A$BAD.ADB' - A.Bad (child package body) - - Following these rules can result in excessively long file names if - corresponding unit names are long (for example, if child units or - subunits are heavily nested). An option is available to shorten such - long file names (called file name "krunching"). This may be - particularly useful when programs being developed with GNAT are to be - used on operating systems with limited file name lengths. *Note Using - GNAT KRUNCH::. - - Of course, no file shortening algorithm can guarantee uniqueness over - all possible unit names; if file name krunching is used, it is your - responsibility to ensure no name clashes occur. Alternatively you can - specify the exact file names that you want used, as described in the - next section. Finally, if your Ada programs are migrating from a - compiler with a different naming convention, you can use the GNAT CHOP - utility to produce source files that follow the GNAT naming conventions. - (For details *note Renaming Files Using GNAT CHOP::.) - -  - File: gnat_ug_vms.info, Node: Using Other File Names, Next: Alternative File Naming Schemes, Prev: File Naming Rules, Up: The GNAT Compilation Model - - Using Other File Names - ====================== - - In the previous section, we have described the default rules used by - GNAT to determine the file name in which a given unit resides. It is - often convenient to follow these default rules, and if you follow them, - the compiler knows without being explicitly told where to find all the - files it needs. - - However, in some cases, particularly when a program is imported from - another Ada compiler environment, it may be more convenient for the - programmer to specify which file names contain which units. GNAT allows - arbitrary file names to be used by means of the Source_File_Name pragma. - The form of this pragma is as shown in the following examples: - - pragma Source_File_Name (My_Utilities.Stacks, - Spec_File_Name => "MYUTILST_A.ADA"); - pragma Source_File_name (My_Utilities.Stacks, - Body_File_Name => "MYUTILST.ADA"); - - As shown in this example, the first argument for the pragma is the unit - name (in this example a child unit). The second argument has the form - of a named association. The identifier indicates whether the file name - is for a spec or a body; the file name itself is given by a string - literal. - - The source file name pragma is a configuration pragma, which means - that normally it will be placed in the `GNAT.ADC' file used to hold - configuration pragmas that apply to a complete compilation environment. - For more details on how the `GNAT.ADC' file is created and used *note - Handling of Configuration Pragmas:: - - `GNAT MAKE' handles non-standard file names in the usual manner (the - non-standard file name for the main program is simply used as the - argument to GNAT MAKE). Note that if the extension is also non-standard, - then it must be included in the GNAT MAKE command, it may not be - omitted. - -  - File: gnat_ug_vms.info, Node: Alternative File Naming Schemes, Next: Generating Object Files, Prev: Using Other File Names, Up: The GNAT Compilation Model - - Alternative File Naming Schemes - =============================== - - In the previous section, we described the use of the - `Source_File_Name' pragma to allow arbitrary names to be assigned to - individual source files. However, this approach requires one pragma - for each file, and especially in large systems can result in very long - `GNAT.ADC' files, and also create a maintenance problem. - - GNAT also provides a facility for specifying systematic file naming - schemes other than the standard default naming scheme previously - described. An alternative scheme for naming is specified by the use of - `Source_File_Name' pragmas having the following format: - - pragma Source_File_Name ( - Spec_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name ( - Body_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name ( - Subunit_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - FILE_NAME_PATTERN ::= STRING_LITERAL - CASING_SPEC ::= Lowercase | Uppercase | Mixedcase - - The `FILE_NAME_PATTERN' string shows how the file name is constructed. - It contains a single asterisk character, and the unit name is - substituted systematically for this asterisk. The optional parameter - `Casing' indicates whether the unit name is to be all upper-case - letters, all lower-case letters, or mixed-case. If no `Casing' - parameter is used, then the default is all upper-case. - - The optional `Dot_Replacement' string is used to replace any periods - that occur in subunit or child unit names. If no `Dot_Replacement' - argument is used then separating dots appear unchanged in the resulting - file name. Although the above syntax indicates that the `Casing' - argument must appear before the `Dot_Replacement' argument, but it is - also permissible to write these arguments in the opposite order. - - As indicated, it is possible to specify different naming schemes for - bodies, specs, and subunits. Quite often the rule for subunits is the - same as the rule for bodies, in which case, there is no need to give a - separate `Subunit_File_Name' rule, and in this case the - `Body_File_name' rule is used for subunits as well. - - The separate rule for subunits can also be used to implement the - rather unusual case of a compilation environment (e.g. a single - directory) which contains a subunit and a child unit with the same unit - name. Although both units cannot appear in the same partition, the Ada - Reference Manual allows (but does not require) the possibility of the - two units coexisting in the same environment. - - The file name translation works in the following steps: - - * If there is a specific `Source_File_Name' pragma for the given - unit, then this is always used, and any general pattern rules are - ignored. - - * If there is a pattern type `Source_File_Name' pragma that applies - to the unit, then the resulting file name will be used if the file - exists. If more than one pattern matches, the latest one will be - tried first, and the first attempt resulting in a reference to a - file that exists will be used. - - * If no pattern type `Source_File_Name' pragma that applies to the - unit for which the corresponding file exists, then the standard - GNAT default naming rules are used. - - - As an example of the use of this mechanism, consider a commonly used - scheme in which file names are all lower case, with separating periods - copied unchanged to the resulting file name, and specs end with - ".1.ADA", and bodies end with ".2.ADA". GNAT will follow this scheme if - the following two pragmas appear: - - pragma Source_File_Name - (Spec_File_Name => "*.1.ADA"); - pragma Source_File_Name - (Body_File_Name => "*.2.ADA"); - - The default GNAT scheme is actually implemented by providing the - following default pragmas internally: - - pragma Source_File_Name - (Spec_File_Name => "*.ADS", Dot_Replacement => "-"); - pragma Source_File_Name - (Body_File_Name => "*.ADB", Dot_Replacement => "-"); - - Our final example implements a scheme typically used with one of the - Ada 83 compilers, where the separator character for subunits was "__" - (two underscores), specs were identified by adding `_.ADA', bodies by - adding `.ADA', and subunits by adding `.SEP'. All file names were upper - case. Child units were not present of course since this was an Ada 83 - compiler, but it seems reasonable to extend this scheme to use the same - double underscore separator for child units. - - pragma Source_File_Name - (Spec_File_Name => "*_.ADA", - Dot_Replacement => "__", - Casing = Uppercase); - pragma Source_File_Name - (Body_File_Name => "*.ADA", - Dot_Replacement => "__", - Casing = Uppercase); - pragma Source_File_Name - (Subunit_File_Name => "*.SEP", - Dot_Replacement => "__", - Casing = Uppercase); - -  - File: gnat_ug_vms.info, Node: Generating Object Files, Next: Source Dependencies, Prev: Alternative File Naming Schemes, Up: The GNAT Compilation Model - - Generating Object Files - ======================= - - An Ada program consists of a set of source files, and the first step in - compiling the program is to generate the corresponding object files. - These are generated by compiling a subset of these source files. The - files you need to compile are the following: - - * If a package spec has no body, compile the package spec to produce - the object file for the package. - - * If a package has both a spec and a body, compile the body to - produce the object file for the package. The source file for the - package spec need not be compiled in this case because there is - only one object file, which contains the code for both the spec - and body of the package. - - * For a subprogram, compile the subprogram body to produce the - object file for the subprogram. The spec, if one is present, is as - usual in a separate file, and need not be compiled. - - * In the case of subunits, only compile the parent unit. A single - object file is generated for the entire subunit tree, which - includes all the subunits. - - * Compile child units independently of their parent units (though, - of course, the spec of all the ancestor unit must be present in - order to compile a child unit). - - * Compile generic units in the same manner as any other units. The - object files in this case are small dummy files that contain at - most the flag used for elaboration checking. This is because GNAT - always handles generic instantiation by means of macro expansion. - However, it is still necessary to compile generic units, for - dependency checking and elaboration purposes. - - The preceding rules describe the set of files that must be compiled to - generate the object files for a program. Each object file has the same - name as the corresponding source file, except that the extension is - `.OBJ' as usual. - - You may wish to compile other files for the purpose of checking their - syntactic and semantic correctness. For example, in the case where a - package has a separate spec and body, you would not normally compile the - spec. However, it is convenient in practice to compile the spec to make - sure it is error-free before compiling clients of this spec, because - such compilations will fail if there is an error in the spec. - - GNAT provides an option for compiling such files purely for the - purposes of checking correctness; such compilations are not required as - part of the process of building a program. To compile a file in this - checking mode, use the `/NOLOAD' qualifier. - -  - File: gnat_ug_vms.info, Node: Source Dependencies, Next: The Ada Library Information Files, Prev: Generating Object Files, Up: The GNAT Compilation Model - - Source Dependencies - =================== - - A given object file clearly depends on the source file which is compiled - to produce it. Here we are using "depends" in the sense of a typical - `make' utility; in other words, an object file depends on a source file - if changes to the source file require the object file to be recompiled. - In addition to this basic dependency, a given object may depend on - additional source files as follows: - - * If a file being compiled `with''s a unit X, the object file - depends on the file containing the spec of unit X. This includes - files that are `with''ed implicitly either because they are parents - of `with''ed child units or they are run-time units required by the - language constructs used in a particular unit. - - * If a file being compiled instantiates a library level generic - unit, the object file depends on both the spec and body files for - this generic unit. - - * If a file being compiled instantiates a generic unit defined - within a package, the object file depends on the body file for the - package as well as the spec file. - - * If a file being compiled contains a call to a subprogram for which - pragma `Inline' applies and inlining is activated with the - `/INLINE=PRAGMA' qualifier, the object file depends on the file - containing the body of this subprogram as well as on the file - containing the spec. Note that for inlining to actually occur as a - result of the use of this qualifier, it is necessary to compile in - optimizing mode. - - The use of `-gnatN' activates a more extensive inlining - optimization that is performed by the front end of the compiler. - This inlining does not require that the code generation be - optimized. Like `/INLINE=PRAGMA', the use of this qualifier - generates additional dependencies. - - * If an object file O depends on the proper body of a subunit - through inlining or instantiation, it depends on the parent unit - of the subunit. This means that any modification of the parent - unit or one of its subunits affects the compilation of O. - - * The object file for a parent unit depends on all its subunit body - files. - - * The previous two rules meant that for purposes of computing - dependencies and recompilation, a body and all its subunits are - treated as an indivisible whole. - - These rules are applied transitively: if unit `A' `with''s unit - `B', whose elaboration calls an inlined procedure in package `C', - the object file for unit `A' will depend on the body of `C', in - file `C.ADB'. - - The set of dependent files described by these rules includes all - the files on which the unit is semantically dependent, as - described in the Ada 95 Language Reference Manual. However, it is - a superset of what the ARM describes, because it includes generic, - inline, and subunit dependencies. - - An object file must be recreated by recompiling the corresponding - source file if any of the source files on which it depends are - modified. For example, if the `make' utility is used to control - compilation, the rule for an Ada object file must mention all the - source files on which the object file depends, according to the - above definition. The determination of the necessary - recompilations is done automatically when one uses `GNAT MAKE'. - -  - File: gnat_ug_vms.info, Node: The Ada Library Information Files, Next: Binding an Ada Program, Prev: Source Dependencies, Up: The GNAT Compilation Model - - The Ada Library Information Files - ================================= - - Each compilation actually generates two output files. The first of these - is the normal object file that has a `.OBJ' extension. The second is a - text file containing full dependency information. It has the same name - as the source file, but an `.ALI' extension. This file is known as the - Ada Library Information (`ali') file. The following information is - contained in the `ali' file. - - * Version information (indicates which version of GNAT was used to - compile the unit(s) in question) - - * Main program information (including priority and time slice - settings, as well as the wide character encoding used during - compilation). - - * List of arguments used in the `GNAT COMPILE' command for the - compilation - - * Attributes of the unit, including configuration pragmas used, an - indication of whether the compilation was successful, exception - model used etc. - - * A list of relevant restrictions applying to the unit (used for - consistency) checking. - - * Categorization information (e.g. use of pragma `Pure'). - - * Information on all `with''ed units, including presence of - `Elaborate' or `Elaborate_All' pragmas. - - * Information from any `Linker_Options' pragmas used in the unit - - * Information on the use of `Body_Version' or `Version' attributes - in the unit. - - * Dependency information. This is a list of files, together with - time stamp and checksum information. These are files on which the - unit depends in the sense that recompilation is required if any of - these units are modified. - - * Cross-reference data. Contains information on all entities - referenced in the unit. Used by tools like `GNAT XREF' and `GNAT - FIND' to provide cross-reference information. - - - For a full detailed description of the format of the `ali' file, see - the source of the body of unit `Lib.Writ', contained in file - `LIB-WRIT.ADB' in the GNAT compiler sources. - -  - File: gnat_ug_vms.info, Node: Binding an Ada Program, Next: Mixed Language Programming, Prev: The Ada Library Information Files, Up: The GNAT Compilation Model - - Binding an Ada Program - ====================== - - When using languages such as C and C++, once the source files have been - compiled the only remaining step in building an executable program is - linking the object modules together. This means that it is possible to - link an inconsistent version of a program, in which two units have - included different versions of the same header. - - The rules of Ada do not permit such an inconsistent program to be - built. For example, if two clients have different versions of the same - package, it is illegal to build a program containing these two clients. - These rules are enforced by the GNAT binder, which also determines an - elaboration order consistent with the Ada rules. - - The GNAT binder is run after all the object files for a program have - been created. It is given the name of the main program unit, and from - this it determines the set of units required by the program, by reading - the corresponding ALI files. It generates error messages if the program - is inconsistent or if no valid order of elaboration exists. - - If no errors are detected, the binder produces a main program, in - Ada by default, that contains calls to the elaboration procedures of - those compilation unit that require them, followed by a call to the - main program. This Ada program is compiled to generate the object file - for the main program. The name of the Ada file is `B$XXX.ADB' (with the - corresponding spec `B$XXX.ADS') where XXX is the name of the main - program unit. - - Finally, the linker is used to build the resulting executable - program, using the object from the main program from the bind step as - well as the object files for the Ada units of the program. - -  - File: gnat_ug_vms.info, Node: Mixed Language Programming, Next: Building Mixed Ada & C++ Programs, Prev: Binding an Ada Program, Up: The GNAT Compilation Model - - Mixed Language Programming - ========================== - - * Menu: - - * Interfacing to C:: - * Calling Conventions:: - -  - File: gnat_ug_vms.info, Node: Interfacing to C, Next: Calling Conventions, Up: Mixed Language Programming - - Interfacing to C - ---------------- - - There are two ways to build a program that contains some Ada files and - some other language files depending on whether the main program is in - Ada or not. If the main program is in Ada, you should proceed as - follows: - - 1. Compile the other language files to generate object files. For - instance: - GNAT COMPILE FILE1.C - GNAT COMPILE FILE2.C - - 2. Compile the Ada units to produce a set of object files and ALI - files. For instance: - GNAT MAKE /ACTIONS=COMPILE MY_MAIN.ADB - - 3. Run the Ada binder on the Ada main program. For instance: - GNAT BIND MY_MAIN.ALI - - 4. Link the Ada main program, the Ada objects and the other language - objects. For instance: - GNAT LINK MY_MAIN.ALI FILE1.OBJ FILE2.OBJ - - The three last steps can be grouped in a single command: - GNAT MAKE MY_MAIN.ADB /LINKER_QUALIFIERS FILE1.OBJ FILE2.OBJ - - If the main program is in some language other than Ada, Then you may - have more than one entry point in the Ada subsystem. You must use a - special option of the binder to generate callable routines to initialize - and finalize the Ada units (*note Binding with Non-Ada Main Programs::). - Calls to the initialization and finalization routines must be inserted - in the main program, or some other appropriate point in the code. The - call to initialize the Ada units must occur before the first Ada - subprogram is called, and the call to finalize the Ada units must occur - after the last Ada subprogram returns. You use the same procedure for - building the program as described previously. In this case, however, - the binder only places the initialization and finalization subprograms - into file `B$XXX.ADB' instead of the main program. So, if the main - program is not in Ada, you should proceed as follows: - - 1. Compile the other language files to generate object files. For - instance: - GNAT COMPILE FILE1.C - GNAT COMPILE FILE2.C - - 2. Compile the Ada units to produce a set of object files and ALI - files. For instance: - GNAT MAKE /ACTIONS=COMPILE ENTRY_POINT1.ADB - GNAT MAKE /ACTIONS=COMPILE ENTRY_POINT2.ADB - - 3. Run the Ada binder on the Ada main program. For instance: - GNAT BIND /NOMAIN ENTRY_POINT1.ALI ENTRY_POINT2.ALI - - 4. Link the Ada main program, the Ada objects and the other language - objects. You only need to give the last entry point here. For - instance: - GNAT LINK ENTRY_POINT2.ALI FILE1.OBJ FILE2.OBJ - -  - File: gnat_ug_vms.info, Node: Calling Conventions, Prev: Interfacing to C, Up: Mixed Language Programming - - Calling Conventions - ------------------- - - GNAT follows standard calling sequence conventions and will thus - interface to any other language that also follows these conventions. - The following Convention identifiers are recognized by GNAT: - - * Ada. This indicates that the standard Ada calling sequence will be - used and all Ada data items may be passed without any limitations - in the case where GNAT is used to generate both the caller and - callee. It is also possible to mix GNAT generated code and code - generated by another Ada compiler. In this case, the data types - should be restricted to simple cases, including primitive types. - Whether complex data types can be passed depends on the situation. - Probably it is safe to pass simple arrays, such as arrays of - integers or floats. Records may or may not work, depending on - whether both compilers lay them out identically. Complex structures - involving variant records, access parameters, tasks, or protected - types, are unlikely to be able to be passed. - - Note that in the case of GNAT running on a platform that supports - DEC Ada 83, a higher degree of compatibility can be guaranteed, - and in particular records are layed out in an identical manner in - the two compilers. Note also that if output from two different - compilers is mixed, the program is responsible for dealing with - elaboration issues. Probably the safest approach is to write the - main program in the version of Ada other than GNAT, so that it - takes care of its own elaboration requirements, and then call the - GNAT-generated adainit procedure to ensure elaboration of the GNAT - components. Consult the documentation of the other Ada compiler - for further details on elaboration. - - However, it is not possible to mix the tasking run time of GNAT and - DEC Ada 83, All the tasking operations must either be entirely - within GNAT compiled sections of the program, or entirely within - DEC Ada 83 compiled sections of the program. - - * Assembler. Specifies assembler as the convention. In practice this - has the same effect as convention Ada (but is not equivalent in - the sense of being considered the same convention). - - * Asm. Equivalent to Assembler. - - * Asm. Equivalent to Assembly. - - * COBOL. Data will be passed according to the conventions described - in section B.4 of the Ada 95 Reference Manual. - - * C. Data will be passed according to the conventions described in - section B.3 of the Ada 95 Reference Manual. - - * Default. Equivalent to C. - - * External. Equivalent to C. - - * CPP. This stands for C++. For most purposes this is identical to C. - See the separate description of the specialized GNAT pragmas - relating to C++ interfacing for further details. - - * Fortran. Data will be passed according to the conventions described - in section B.5 of the Ada 95 Reference Manual. - - * Intrinsic. This applies to an intrinsic operation, as defined in - the Ada 95 Reference Manual. If a a pragma Import (Intrinsic) - applies to a subprogram, this means that the body of the - subprogram is provided by the compiler itself, usually by means of - an efficient code sequence, and that the user does not supply an - explicit body for it. In an application program, the pragma can - only be applied to the following two sets of names, which the GNAT - compiler recognizes. - * Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, - Shift_Right_- Arithmetic. The corresponding subprogram - declaration must have two formal parameters. The first one - must be a signed integer type or a modular type with a binary - modulus, and the second parameter must be of type Natural. - The return type must be the same as the type of the first - argument. The size of this type can only be 8, 16, 32, or 64. - - * binary arithmetic operators: "+", "-", "*", "/" The - corresponding operator declaration must have parameters and - result type that have the same root numeric type (for - example, all three are long_float types). This simplifies the - definition of operations that use type checking to perform - dimensional checks: - type Distance is new Long_Float; - type Time is new Long_Float; - type Velocity is new Long_Float; - function "/" (D : Distance; T : Time) - return Velocity; - pragma Import (Intrinsic, "/"); - - This common idiom is often programmed with a generic - definition and an explicit body. The pragma makes it simpler - to introduce such declarations. It incurs no overhead in - compilation time or code size, because it is implemented as a - single machine instruction. - - * Stdcall. This is relevant only to NT/Win95 implementations of GNAT, - and specifies that the Stdcall calling sequence will be used, as - defined by the NT API. - - * DLL. This is equivalent to Stdcall. - - * Win32. This is equivalent to Stdcall. - - * Stubbed. This is a special convention that indicates that the - compiler should provide a stub body that raises `Program_Error'. - - GNAT additionally provides a useful pragma `Convention_Identifier' that - can be used to parametrize conventions and allow additional synonyms to - be specified. For example if you have legacy code in which the - convention identifier Fortran77 was used for Fortran, you can use the - configuration pragma: - - pragma Convention_Identifier (Fortran77, Fortran); - - And from now on the identifier Fortran77 may be used as a convention - identifier (for example in an `Import' pragma) with the same meaning as - Fortran. - -  - File: gnat_ug_vms.info, Node: Building Mixed Ada & C++ Programs, Next: Comparison between GNAT and C/C++ Compilation Models, Prev: Mixed Language Programming, Up: The GNAT Compilation Model - - Building Mixed Ada & C++ Programs - ================================= - - Building a mixed application containing both Ada and C++ code may be a - challenge for the unaware programmer. As a matter of fact, this - interfacing has not been standardized in the Ada 95 reference manual due - to the immaturity and lack of standard of C++ at the time. This section - gives a few hints that should make this task easier. In particular the - first section addresses the differences with interfacing with C. The - second section looks into the delicate problem of linking the complete - application from its Ada and C++ parts. The last section give some - hints on how the GNAT run time can be adapted in order to allow - inter-language dispatching with a new C++ compiler. - - * Menu: - - * Interfacing to C++:: - * Linking a Mixed C++ & Ada Program:: - * A Simple Example:: - * Adapting the Run Time to a New C++ Compiler:: - -  - File: gnat_ug_vms.info, Node: Interfacing to C++, Next: Linking a Mixed C++ & Ada Program, Up: Building Mixed Ada & C++ Programs - - Interfacing to C++ - ------------------ - - GNAT supports interfacing with C++ compilers generating code that is - compatible with the standard Application Binary Interface of the given - platform. - - Interfacing can be done at 3 levels: simple data, subprograms and - classes. In the first 2 cases, GNAT offer a specific CONVENTION CPP - that behaves exactly like CONVENTION C. Usually C++ mangle names of - subprograms and currently GNAT does not provide any help to solve the - demangling problem. This problem can be addressed in 2 ways: - * by modifying the C++ code in order to force a C convention using - the EXTERN "C" syntax. - - * by figuring out the mangled name and use it as the Link_Name - argument of the pragma import. - - Interfacing at the class level can be achieved by using the GNAT - specific pragmas such as `CPP_Class' and `CPP_Virtual'. See the GNAT - Reference Manual for additional information. - -  - File: gnat_ug_vms.info, Node: Linking a Mixed C++ & Ada Program, Next: A Simple Example, Prev: Interfacing to C++, Up: Building Mixed Ada & C++ Programs - - Linking a Mixed C++ & Ada Program - --------------------------------- - - Usually the linker of the C++ development system must be used to link - mixed applications because most C++ systems will resolve elaboration - issues (such as calling constructors on global class instances) - transparently during the link phase. GNAT has been adapted to ease the - use of a foreign linker for the last phase. Three cases can be - considered: - 1. Using GNAT and G++ (GNU C++ compiler) from the same GCC - installation. The c++ linker can simply be called by using the c++ - specific driver called `c++'. Note that this setup is not very - common because it may request recompiling the whole GCC tree from - sources and it does not allow to upgrade easily to a new version - of one compiler for one of the two languages without taking the - risk of destabilizing the other. - - $ c++ -c file1.C - $ c++ -c file2.C - $ GNAT MAKE ada_unit /LINKER_QUALIFIERS FILE1.OBJ FILE2.OBJ --LINK=c++ - - 2. Using GNAT and G++ from 2 different GCC installations. If both - compilers are on the PATH, the same method can be used. It is - important to be aware that environment variables such as - C_INCLUDE_PATH, GCC_EXEC_PREFIX, BINUTILS_ROOT or GCC_ROOT will - affect both compilers at the same time and thus may make one of - the 2 compilers operate improperly if they are set for the other. - In particular it is important that the link command has access to - the proper GNAT COMPILE library `libgcc.a', that is to say the one - that is part of the C++ compiler installation. The implicit link - command as suggested in the GNAT MAKE command from the former - example can be replaced by an explicit link command with full - verbosity in order to verify which library is used: - $ GNAT BIND ada_unit - $ GNAT LINK -v -v ada_unit FILE1.OBJ FILE2.OBJ --LINK=c++ - If there is a problem due to interfering environment variables, it - can be workaround by using an intermediate script. The following - example shows the proper script to use when GNAT has not been - installed at its default location and g++ has been installed at - its default location: - - $ GNAT LINK -v -v ada_unit FILE1.OBJ FILE2.OBJ --LINK=./my_script - $ cat ./my_script - #!/bin/sh - unset BINUTILS_ROOT - unset GCC_ROOT - c++ $* - - 3. Using a non GNU C++ compiler. The same set of command as previously - described can be used to insure that the c++ linker is used. - Nonetheless, you need to add the path to libgcc explicitely, since - some libraries needed by GNAT are located in this directory: - - - $ GNAT LINK ada_unit FILE1.OBJ FILE2.OBJ --LINK=./my_script - $ cat ./my_script - #!/bin/sh - CC $* `GNAT COMPILE -print-libgcc-file-name` - - Where CC is the name of the non GNU C++ compiler. - - -  - File: gnat_ug_vms.info, Node: A Simple Example, Next: Adapting the Run Time to a New C++ Compiler, Prev: Linking a Mixed C++ & Ada Program, Up: Building Mixed Ada & C++ Programs - - A Simple Example - ---------------- - - The following example, provided as part of the GNAT examples, show how - to achieve procedural interfacing between Ada and C++ in both - directions. The C++ class A has 2 methods. The first method is exported - to Ada by the means of an extern C wrapper function. The second method - calls an Ada subprogram. On the Ada side, The C++ calls is modelized by - a limited record with a layout comparable to the C++ class. The Ada - subprogram, in turn, calls the c++ method. So from the C++ main program - the code goes back and forth between the 2 languages. - - Here are the compilation commands for native configurations: - $ GNAT MAKE -c simple_cpp_interface - $ c++ -c cpp_main.C - $ c++ -c ex7.C - $ GNAT BIND -n simple_cpp_interface - $ GNAT LINK simple_cpp_interface -o cpp_main --LINK=$(CPLUSPLUS) - -lstdc++ EX7.OBJ CPP_MAIN.OBJ - - Here are the corresponding sources: - - //cpp_main.C - - #include "ex7.h" - - extern "C" { - void adainit (void); - void adafinal (void); - void method1 (A *t); - } - - void method1 (A *t) - { - t->method1 (); - } - - int main () - { - A obj; - adainit (); - obj.method2 (3030); - adafinal (); - } - - //ex7.h - - class Origin { - public: - int o_value; - }; - class A : public Origin { - public: - void method1 (void); - virtual void method2 (int v); - A(); - int a_value; - }; - - //ex7.C - - #include "ex7.h" - #include - - extern "C" { void ada_method2 (A *t, int v);} - - void A::method1 (void) - { - a_value = 2020; - printf ("in A::method1, a_value = %d \n",a_value); - - } - - void A::method2 (int v) - { - ada_method2 (this, v); - printf ("in A::method2, a_value = %d \n",a_value); - - } - - A::A(void) - { - a_value = 1010; - printf ("in A::A, a_value = %d \n",a_value); - } - - -- Ada sources - package body Simple_Cpp_Interface is - - procedure Ada_Method2 (This : in out A; V : Integer) is - begin - Method1 (This); - This.A_Value := V; - end Ada_Method2; - - end Simple_Cpp_Interface; - - package Simple_Cpp_Interface is - type A is limited - record - O_Value : Integer; - A_Value : Integer; - end record; - pragma Convention (C, A); - - procedure Method1 (This : in out A); - pragma Import (C, Method1); - - procedure Ada_Method2 (This : in out A; V : Integer); - pragma Export (C, Ada_Method2); - - end Simple_Cpp_Interface; - -  - File: gnat_ug_vms.info, Node: Adapting the Run Time to a New C++ Compiler, Prev: A Simple Example, Up: Building Mixed Ada & C++ Programs - - Adapting the Run Time to a New C++ Compiler - ------------------------------------------- - - GNAT offers the capability to derive Ada 95 tagged types directly from - preexisting C++ classes and . See "Interfacing with C++" in the GNAT - reference manual. The mechanism used by GNAT for achieving such a goal - has been made user configurable through a GNAT library unit - `Interfaces.CPP'. The default version of this file is adapted to the - GNU c++ compiler. Internal knowledge of the virtual table layout used - by the new C++ compiler is needed to configure properly this unit. The - Interface of this unit is known by the compiler and cannot be changed - except for the value of the constants defining the characteristics of - the virtual table: CPP_DT_Prologue_Size, CPP_DT_Entry_Size, - CPP_TSD_Prologue_Size, CPP_TSD_Entry_Size. Read comments in the source - of this unit for more details. - -  - File: gnat_ug_vms.info, Node: Comparison between GNAT and C/C++ Compilation Models, Next: Comparison between GNAT and Conventional Ada Library Models, Prev: Building Mixed Ada & C++ Programs, Up: The GNAT Compilation Model - - Comparison between GNAT and C/C++ Compilation Models - ==================================================== - - The GNAT model of compilation is close to the C and C++ models. You can - think of Ada specs as corresponding to header files in C. As in C, you - don't need to compile specs; they are compiled when they are used. The - Ada `with' is similar in effect to the `#include' of a C header. - - One notable difference is that, in Ada, you may compile specs - separately to check them for semantic and syntactic accuracy. This is - not always possible with C headers because they are fragments of - programs that have less specific syntactic or semantic rules. - - The other major difference is the requirement for running the binder, - which performs two important functions. First, it checks for - consistency. In C or C++, the only defense against assembling - inconsistent programs lies outside the compiler, in a makefile, for - example. The binder satisfies the Ada requirement that it be impossible - to construct an inconsistent program when the compiler is used in normal - mode. - - The other important function of the binder is to deal with - elaboration issues. There are also elaboration issues in C++ that are - handled automatically. This automatic handling has the advantage of - being simpler to use, but the C++ programmer has no control over - elaboration. Where `GNAT BIND' might complain there was no valid order - of elaboration, a C++ compiler would simply construct a program that - malfunctioned at run time. - -  - File: gnat_ug_vms.info, Node: Comparison between GNAT and Conventional Ada Library Models, Prev: Comparison between GNAT and C/C++ Compilation Models, Up: The GNAT Compilation Model - - Comparison between GNAT and Conventional Ada Library Models - =========================================================== - - This section is intended to be useful to Ada programmers who have - previously used an Ada compiler implementing the traditional Ada library - model, as described in the Ada 95 Language Reference Manual. If you - have not used such a system, please go on to the next section. - - In GNAT, there is no "library" in the normal sense. Instead, the set - of source files themselves acts as the library. Compiling Ada programs - does not generate any centralized information, but rather an object - file and a ALI file, which are of interest only to the binder and - linker. In a traditional system, the compiler reads information not - only from the source file being compiled, but also from the centralized - library. This means that the effect of a compilation depends on what - has been previously compiled. In particular: - - * When a unit is `with''ed, the unit seen by the compiler corresponds - to the version of the unit most recently compiled into the library. - - * Inlining is effective only if the necessary body has already been - compiled into the library. - - * Compiling a unit may obsolete other units in the library. - - In GNAT, compiling one unit never affects the compilation of any other - units because the compiler reads only source files. Only changes to - source files can affect the results of a compilation. In particular: - - * When a unit is `with''ed, the unit seen by the compiler corresponds - to the source version of the unit that is currently accessible to - the compiler. - - * Inlining requires the appropriate source files for the package or - subprogram bodies to be available to the compiler. Inlining is - always effective, independent of the order in which units are - complied. - - * Compiling a unit never affects any other compilations. The editing - of sources may cause previous compilations to be out of date if - they depended on the source file being modified. - - The most important result of these differences is that order of - compilation is never significant in GNAT. There is no situation in - which one is required to do one compilation before another. What shows - up as order of compilation requirements in the traditional Ada library - becomes, in GNAT, simple source dependencies; in other words, there is - only a set of rules saying what source files must be present when a - file is compiled. - -  - File: gnat_ug_vms.info, Node: Compiling Using GNAT COMPILE, Next: Binding Using GNAT BIND, Prev: The GNAT Compilation Model, Up: Top - - Compiling Using `GNAT COMPILE' - ****************************** - - This chapter discusses how to compile Ada programs using the `GNAT - COMPILE' command. It also describes the set of qualifiers that can be - used to control the behavior of the compiler. - - * Menu: - - * Compiling Programs:: - * Qualifiers for GNAT COMPILE:: - * Search Paths and the Run-Time Library (RTL):: - * Order of Compilation Issues:: - * Examples:: - -  - File: gnat_ug_vms.info, Node: Compiling Programs, Next: Qualifiers for GNAT COMPILE, Up: Compiling Using GNAT COMPILE - - Compiling Programs - ================== - - The first step in creating an executable program is to compile the units - of the program using the `GNAT COMPILE' command. You must compile the - following files: - - * the body file (`.ADB') for a library level subprogram or generic - subprogram - - * the spec file (`.ADS') for a library level package or generic - package that has no body - - * the body file (`.ADB') for a library level package or generic - package that has a body - - - You need _not_ compile the following files - - * the spec of a library unit which has a body - - * subunits - - because they are compiled as part of compiling related units. GNAT - package specs when the corresponding body is compiled, and subunits - when the parent is compiled. If you attempt to compile any of these - files, you will get one of the following error messages (where fff is - the name of the file you compiled): - - No code generated for file FFF (PACKAGE SPEC) - No code generated for file FFF (SUBUNIT) - - The basic command for compiling a file containing an Ada unit is - - $ GNAT COMPILE [QUALIFIERS] `file name' - - where FILE NAME is the name of the Ada file (usually having an extension - `.ADS' for a spec or `.ADB' for a body). The result of a successful - compilation is an object file, which has the same name as the source - file but an extension of `.OBJ' and an Ada Library Information (ALI) - file, which also has the same name as the source file, but with `.ALI' - as the extension. GNAT creates these two output files in the current - directory, but you may specify a source file in any directory using an - absolute or relative path specification containing the directory - information. - - `GNAT COMPILE' is actually a driver program that looks at the - extensions of the file arguments and loads the appropriate compiler. - For example, the GNU C compiler is `CC1', and the Ada compiler is - `GNAT1'. These programs are in directories known to the driver program - (in some configurations via environment variables you set), but need - not be in your path. The `GNAT COMPILE' driver also calls the assembler - and any other utilities needed to complete the generation of the - required object files. - - It is possible to supply several file names on the same `GNAT - COMPILE' command. This causes `GNAT COMPILE' to call the appropriate - compiler for each file. For example, the following command lists three - separate files to be compiled: - - $ GNAT COMPILE X.ADB Y.ADB Z.C - - calls `GNAT1' (the Ada compiler) twice to compile `X.ADB' and `Y.ADB', - and `CC1' (the C compiler) once to compile `Z.C'. The compiler - generates three object files `X.OBJ', `Y.OBJ' and `Z.OBJ' and the two - ALI files `X.ALI' and `Y.ALI' from the Ada compilations. Any qualifiers - apply to all the files listed. - -  - File: gnat_ug_vms.info, Node: Qualifiers for GNAT COMPILE, Next: Search Paths and the Run-Time Library (RTL), Prev: Compiling Programs, Up: Compiling Using GNAT COMPILE - - Qualifiers for `GNAT COMPILE' - ============================= - - The `GNAT COMPILE' command accepts qualifiers that control the - compilation process. These qualifiers are fully described in this - section. First we briefly list all the qualifiers, in alphabetical - order, then we describe the qualifiers in more detail in functionally - grouped sections. - - * Menu: - - * Output and Error Message Control:: - * Debugging and Assertion Control:: - * Run-Time Checks:: - * Stack Overflow Checking:: - * Run-Time Control:: - * Validity Checking:: - * Style Checking:: - * Using GNAT COMPILE for Syntax Checking:: - * Using GNAT COMPILE for Semantic Checking:: - * Compiling Ada 83 Programs:: - * Character Set Control:: - * File Naming Control:: - * Subprogram Inlining Control:: - * Auxiliary Output Control:: - * Debugging Control:: - * Units to Sources Mapping Files:: - - `/DEBUG' - Generate debugging information. This information is stored in the - object file and copied from there to the final executable file by - the linker, where it can be read by the debugger. You must use the - `/DEBUG' qualifier if you plan on using the debugger. - - `/SEARCH=DIR' - Direct GNAT to search the DIR directory for source files needed by - the current compilation (*note Search Paths and the Run-Time - Library (RTL)::). - - `/NOCURRENT_DIRECTORY' - Except for the source file named in the command line, do not look - for source files in the directory containing the source file named - in the command line (*note Search Paths and the Run-Time Library - (RTL)::). - - `/NOOPTIMIZE (default)' - `/OPTIMIZE[=(keyword[,...])]' - Selects the level of optimization for your program. The supported - keywords are as follows: - `ALL (default)' - Perform most optimizations, including those that be expensive. - - `NONE' - Do not do any optimizations. Same as `/NOOPTIMIZE'. - - `SOME' - Perform some optimizations, but omit ones that are costly. - - `DEVELOPMENT' - Same as `SOME'. - - `INLINING' - Full optimization, and also attempt automatic inlining of - small subprograms within a unit (*note Inlining of - Subprograms::). - - `UNROLL_LOOPS' - Try to unroll loops. This keyword may be specified together - with any keyword above other than `NONE'. Loop unrolling - usually, but not always, improves the performance of programs. - - `/RUNTIME_SYSTEM=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `GNAT MAKE' flag (see *Note Qualifiers - for GNAT MAKE::). - - `/ASM' - Used to cause the assembler source file to be generated, using - `.S' as the extension, instead of the object file. This may be - useful if you need to examine the generated assembly code. - - `/VERBOSE' - Show commands generated by the `GNAT COMPILE' driver. Normally - used only for debugging purposes or if you need to be sure what - version of the compiler you are executing. - - `/CHECKS=ASSERTIONS' - Assertions enabled. `Pragma Assert' and `pragma Debug' to be - activated. - - `-gnatA' - Avoid processing `GNAT.ADC'. If a GNAT.ADC file is present, it - will be ignored. - - `/WARNINGS=BRIEF' - Generate brief messages to `SYS$ERROR' even if verbose mode set. - - `/NOLOAD' - Check syntax and semantics only (no code generation attempted). - - `/COMPRESS_NAMES' - Compress debug information and external symbol name table entries. - - `/XDEBUG' - Output expanded source files for source level debugging. This - qualifier also suppress generation of cross-reference information - (see /XREF=SUPPRESS). - - `-gnatecPATH' - Specify a configuration pragma file. (see *Note The Configuration - Pragmas Files::) - - `-gnatemPATH' - Specify a mapping file. (see *Note Units to Sources Mapping - Files::) - - `/CHECKS=ELABORATION' - Full dynamic elaboration checks. - - `/REPORT_ERRORS=FULL' - Full errors. Multiple errors per line, all undefined references. - - `/UPPERCASE_EXTERNALS' - Externals names are folded to all uppercase. - - `/STYLE=GNAT' - Internal GNAT implementation mode. This should not be used for - applications programs, it is intended only for use by the compiler - and its run-time library. For documentation, see the GNAT sources. - - `/EXPAND_SOURCE' - List generated expanded code in source form. - - `/IDENTIFIER_CHARACTER_SET=C' - Identifier character set For details of the possible selections - for C, see *Note Character Set Control::. - - `/HELP' - Output usage information. The output is written to `SYS$OUTPUT'. - - `/FILE_NAME_MAX_LENGTH=N' - Limit file names to N (1-999) characters . - - `/LIST' - Output full source listing with embedded error messages. - - `/ERROR_LIMIT=N' - Limit number of detected errors to N (1-999). - - `/INLINE=PRAGMA' - Activate inlining across unit boundaries for subprograms for which - pragma `inline' is specified. - - `-gnatN' - Activate front end inlining. - - `/INLINE=SUPPRESS' - Suppresses all inlining, even if other optimization or inlining - qualifiers are set. - - `/CHECKS=OVERFLOW' - Enable numeric overflow checking (which is not normally enabled by - default). Not that division by zero is a separate check that is not - controlled by this qualifier (division by zero checking is on by - default). - - `/CHECKS=SUPPRESS_ALL' - Suppress all checks. - - `/TRY_SEMANTICS' - Don't quit; try semantics, even if parse errors. - - `/FORCE_ALI' - Don't quit; generate `ali' and tree files even if illegalities. - - `/POLLING_ENABLE' - Enable polling. This is required on some systems (notably Windows - NT) to obtain asynchronous abort and asynchronous transfer of - control capability. See the description of pragma Polling in the - GNAT Reference Manual for full details. - - `/REPRESENTATION_INFO[0/1/2/3][s]' - Output representation information for declared types and objects. - - `/SYNTAX_ONLY' - Syntax check only. - - `/TREE_OUTPUT' - Tree output file to be generated. - - `-gnatT nnn' - Set time slice to specified number of microseconds - - `/UNITS_LIST' - List units for this compilation. - - `/UNIQUE_ERROR_TAG' - Tag all error messages with the unique string "error:" - - `/REPORT_ERRORS=VERBOSE' - Verbose mode. Full error output with source lines to `SYS$OUTPUT'. - - `/VALIDITY_CHECKING' - Control level of validity checking. See separate section describing - this feature. - - `/WARNINGS=XXX' - Warning mode where XXX is a string of options describing the exact - warnings that are enabled or disabled. See separate section on - warning control. - - `/WIDE_CHARACTER_ENCODING=E' - Wide character encoding method (E=`BRACKETS, NONE, HEX, UPPER, - SHIFT_JIS, EUC, UTF8') - - `/XREF=SUPPRESS' - Suppress generation of cross-reference information. - - `/STYLE_CHECKS=(option,option..)' - Enable built-in style checks. See separate section describing this - feature. - - `/DISTRIBUTION_STUBS=M' - Distribution stub generation and compilation (M=`RECEIVER' or - `CALLER' to specify the type of stubs to be generated and - compiled). - - `/83' - Enforce Ada 83 restrictions. - - The following restrictions apply to the combination of qualifiers in - this manner: - - * The qualifier `/NOLOAD' if combined with other qualifiers must come - first in the string. - - * The qualifier `/SYNTAX_ONLY' if combined with other qualifiers - must come first in the string. - - * Once a "y" appears in the string (that is a use of the `/STYLE=' - qualifier), then all further characters in the qualifier are - interpreted as style modifiers (see description of `/STYLE='). - - * Once a "d" appears in the string (that is a use of the `-gnatd' - qualifier), then all further characters in the qualifier are - interpreted as debug flags (see description of `-gnatd'). - - * Once a "w" appears in the string (that is a use of the `-gnatw' - qualifier), then all further characters in the qualifier are - interpreted as warning mode modifiers (see description of - `-gnatw'). - - * Once a "V" appears in the string (that is a use of the - `/VALIDITY_CHECKING' qualifier), then all further characters in - the qualifier are interpreted as validity checking options (see - description of `/VALIDITY_CHECKING'). - - -  - File: gnat_ug_vms.info, Node: Output and Error Message Control, Next: Debugging and Assertion Control, Up: Qualifiers for GNAT COMPILE - - Output and Error Message Control - -------------------------------- - - The standard default format for error messages is called "brief format." - Brief format messages are written to `SYS$ERROR' (the standard error - file) and have the following form: - - E.ADB:3:04: Incorrect spelling of keyword "function" - E.ADB:4:20: ";" should be "is" - - The first integer after the file name is the line number in the file, - and the second integer is the column number within the line. `glide' - can parse the error messages and point to the referenced character. - The following qualifiers provide control over the error message format: - - `/REPORT_ERRORS=VERBOSE' - The effect of this setting is to write long-format error messages - to `SYS$OUTPUT' (the standard output file. The same program - compiled with the `/REPORT_ERRORS=VERBOSE' qualifier would - generate: - - 3. funcion X (Q : Integer) - | - >>> Incorrect spelling of keyword "function" - 4. return Integer; - | - >>> ";" should be "is" - - The vertical bar indicates the location of the error, and the `>>>' - prefix can be used to search for error messages. When this - qualifier is used the only source lines output are those with - errors. - - `/LIST' - This qualifier causes a full listing of the file to be generated. - The output might look as follows: - - 1. procedure E is - 2. V : Integer; - 3. funcion X (Q : Integer) - | - >>> Incorrect spelling of keyword "function" - 4. return Integer; - | - >>> ";" should be "is" - 5. begin - 6. return Q + Q; - 7. end; - 8. begin - 9. V := X + X; - 10.end E; - - When you specify the `/REPORT_ERRORS=VERBOSE' or `/LIST' - qualifiers and standard output is redirected, a brief summary is - written to `SYS$ERROR' (standard error) giving the number of error - messages and warning messages generated. - - `/UNIQUE_ERROR_TAG' - This qualifier forces all error messages to be preceded by the - unique string "error:". This means that error messages take a few - more characters in space, but allows easy searching for and - identification of error messages. - - `/WARNINGS=BRIEF' - This qualifier causes GNAT to generate the brief format error - messages to `SYS$ERROR' (the standard error file) as well as the - verbose format message or full listing (which as usual is written - to `SYS$OUTPUT' (the standard output file). - - `/ERROR_LIMIT=N' - N is a decimal integer in the range of 1 to 999 and limits the - number of error messages to be generated. For example, using - `/ERROR_LIMIT=2' might yield - - E.ADB:3:04: Incorrect spelling of keyword "function" - E.ADB:5:35: missing ".." - fatal error: maximum errors reached - compilation abandoned - - `/REPORT_ERRORS=FULL' - Normally, the compiler suppresses error messages that are likely - to be redundant. This qualifier causes all error messages to be - generated. In particular, in the case of references to undefined - variables. If a given variable is referenced several times, the - normal format of messages is - E.ADB:7:07: "V" is undefined (more references follow) - - where the parenthetical comment warns that there are additional - references to the variable `V'. Compiling the same program with the - `/REPORT_ERRORS=FULL' qualifier yields - - E.ADB:7:07: "V" is undefined - E.ADB:8:07: "V" is undefined - E.ADB:8:12: "V" is undefined - E.ADB:8:16: "V" is undefined - E.ADB:9:07: "V" is undefined - E.ADB:9:12: "V" is undefined - - `/TRY_SEMANTICS' - In normal operation mode, the compiler first parses the program and - determines if there are any syntax errors. If there are, - appropriate error messages are generated and compilation is - immediately terminated. This qualifier tells GNAT to continue - with semantic analysis even if syntax errors have been found. This - may enable the detection of more errors in a single run. On the - other hand, the semantic analyzer is more likely to encounter some - internal fatal error when given a syntactically invalid tree. - - `/FORCE_ALI' - In normal operation mode, the `ali' file is not generated if any - illegalities are detected in the program. The use of `/FORCE_ALI' - forces generation of the `ali' file. This file is marked as being - in error, so it cannot be used for binding purposes, but it does - contain reasonably complete cross-reference information, and thus - may be useful for use by tools (e.g. semantic browsing tools or - integrated development environments) that are driven from the - `ali' file. - - In addition, if `/TREE_OUTPUT' is also specified, then the tree - file is generated even if there are illegalities. It may be useful - in this case to also specify `/TRY_SEMANTICS' to ensure that full - semantic processing occurs. The resulting tree file can be - processed by ASIS, for the purpose of providing partial - information about illegal units, but if the error causes the tree - to be badly malformed, then ASIS may crash during the analysis. - - In addition to error messages, which correspond to illegalities as - defined in the Ada 95 Reference Manual, the compiler detects two kinds - of warning situations. - - First, the compiler considers some constructs suspicious and - generates a warning message to alert you to a possible error. Second, - if the compiler detects a situation that is sure to raise an exception - at run time, it generates a warning message. The following shows an - example of warning messages: - E.ADB:4:24: warning: creation of object may raise Storage_Error - E.ADB:10:17: warning: static value out of range - E.ADB:10:17: warning: "Constraint_Error" will be raised at run time - - GNAT considers a large number of situations as appropriate for the - generation of warning messages. As always, warnings are not definite - indications of errors. For example, if you do an out-of-range - assignment with the deliberate intention of raising a - `Constraint_Error' exception, then the warning that may be issued does - not indicate an error. Some of the situations for which GNAT issues - warnings (at least some of the time) are given in the following list, - which is not necessarily complete. - - * Possible infinitely recursive calls - - * Out-of-range values being assigned - - * Possible order of elaboration problems - - * Unreachable code - - * Fixed-point type declarations with a null range - - * Variables that are never assigned a value - - * Variables that are referenced before being initialized - - * Task entries with no corresponding accept statement - - * Duplicate accepts for the same task entry in a select - - * Objects that take too much storage - - * Unchecked conversion between types of differing sizes - - * Missing return statements along some execution paths in a function - - * Incorrect (unrecognized) pragmas - - * Incorrect external names - - * Allocation from empty storage pool - - * Potentially blocking operations in protected types - - * Suspicious parenthesization of expressions - - * Mismatching bounds in an aggregate - - * Attempt to return local value by reference - - * Unrecognized pragmas - - * Premature instantiation of a generic body - - * Attempt to pack aliased components - - * Out of bounds array subscripts - - * Wrong length on string assignment - - * Violations of style rules if style checking is enabled - - * Unused with clauses - - * Bit_Order usage that does not have any effect - - * Compile time biased rounding of floating-point constant - - * Standard.Duration used to resolve universal fixed expression - - * Dereference of possibly null value - - * Declaration that is likely to cause storage error - - * Internal GNAT unit with'ed by application unit - - * Values known to be out of range at compile time - - * Unreferenced labels and variables - - * Address overlays that could clobber memory - - * Unexpected initialization when address clause present - - * Bad alignment for address clause - - * Useless type conversions - - * Redundant assignment statements - - * Accidental hiding of name by child unit - - * Unreachable code - - * Access before elaboration detected at compile time - - * A range in a `for' loop that is known to be null or might be null - - - The following qualifiers are available to control the handling of - warning messages: - - `/WARNINGS=OPTIONAL (activate all optional errors)' - This qualifier activates most optional warning messages, see - remaining list in this section for details on optional warning - messages that can be individually controlled. The warnings that - are not turned on by this qualifier are - `/WARNINGS=BIASED_ROUNDING' (biased rounding), - `/WARNINGS=IMPLICIT_DEREFERENCE' (implicit dereferencing), and - `/WARNINGS=HIDING' (hiding). All other optional warnings are - turned on. - - `/WARNINGS=NOOPTIONAL (suppress all optional errors)' - This qualifier suppresses all optional warning messages, see - remaining list in this section for details on optional warning - messages that can be individually controlled. - - `/WARNINGS=BIASED_ROUNDING (activate warnings on biased rounding)' - If a static floating-point expression has a value that is exactly - half way between two adjacent machine numbers, then the rules of - Ada (Ada Reference Manual, section 4.9(38)) require that this - rounding be done away from zero, even if the normal unbiased - rounding rules at run time would require rounding towards zero. - This warning message alerts you to such instances where - compile-time rounding and run-time rounding are not equivalent. If - it is important to get proper run-time rounding, then you can - force this by making one of the operands into a variable. The - default is that such warnings are not generated. Note that - `/WARNINGS=OPTIONAL' does not affect the setting of this warning - option. - - `/WARNINGS=NOBIASED_ROUNDING (suppress warnings on biased rounding)' - This qualifier disables warnings on biased rounding. - - `/WARNINGS=CONDITIONALS (activate warnings on conditionals)' - This qualifier activates warnings for conditional expressions used - in tests that are known to be True or False at compile time. The - default is that such warnings are not generated. This warning can - also be turned on using `/WARNINGS=OPTIONAL'. - - `/WARNINGS=NOCONDITIONALS (suppress warnings on conditionals)' - This qualifier suppresses warnings for conditional expressions - used in tests that are known to be True or False at compile time. - - `/WARNINGS=IMPLICIT_DEREFERENCE (activate warnings on implicit dereferencing)' - If this qualifier is set, then the use of a prefix of an access - type in an indexed component, slice, or selected component without - an explicit `.all' will generate a warning. With this warning - enabled, access checks occur only at points where an explicit - `.all' appears in the source code (assuming no warnings are - generated as a result of this qualifier). The default is that such - warnings are not generated. Note that `/WARNINGS=OPTIONAL' does - not affect the setting of this warning option. - - `/WARNINGS=NOIMPLICIT_DEREFERENCE (suppress warnings on implicit dereferencing)' - This qualifier suppresses warnings for implicit deferences in - indexed components, slices, and selected components. - - `/WARNINGS=ERROR (treat warnings as errors)' - This qualifier causes warning messages to be treated as errors. - The warning string still appears, but the warning messages are - counted as errors, and prevent the generation of an object file. - - `/WARNINGS=UNREFERENCED_FORMALS (activate warnings on unreferenced formals)' - This qualifier causes a warning to be generated if a formal - parameter is not referenced in the body of the subprogram. This - warning can also be turned on using `/WARNINGS=OPTIONAL' or - `/WARNINGS=UNUSED'. - - `/WARNINGS=NOUNREFERENCED_FORMALS (suppress warnings on unreferenced formals)' - This qualifier suppresses warnings for unreferenced formal - parameters. Note that the combination `/WARNINGS=UNUSED' followed - by `/WARNINGS=NOUNREFERENCED_FORMALS' has the effect of warning on - unreferenced entities other than subprogram formals. - - `/WARNINGS=HIDING (activate warnings on hiding)' - This qualifier activates warnings on hiding declarations. A - declaration is considered hiding if it is for a non-overloadable - entity, and it declares an entity with the same name as some other - entity that is directly or use-visible. The default is that such - warnings are not generated. Note that `/WARNINGS=OPTIONAL' does - not affect the setting of this warning option. - - `/WARNINGS=NOHIDING (suppress warnings on hiding)' - This qualifier suppresses warnings on hiding declarations. - - `/WARNINGS=IMPLEMENTATION (activate warnings on implementation units).' - This qualifier activates warnings for a `with' of an internal GNAT - implementation unit, defined as any unit from the `Ada', - `Interfaces', `GNAT', `DEC', or `System' hierarchies that is not - documented in either the Ada Reference Manual or the GNAT - Programmer's Reference Manual. Such units are intended only for - internal implementation purposes and should not be `with''ed by - user programs. The default is that such warnings are generated - This warning can also be turned on using `/WARNINGS=OPTIONAL'. - - `/WARNINGS=NOIMPLEMENTATION (disable warnings on implementation units).' - This qualifier disables warnings for a `with' of an internal GNAT - implementation unit. - - `/WARNINGS=ELABORATION (activate warnings on elaboration pragmas)' - This qualifier activates warnings on missing pragma Elaborate_All - statements. See the section in this guide on elaboration checking - for details on when such pragma should be used. The default is - that such warnings are not generated. This warning can also be - turned on using `/WARNINGS=OPTIONAL'. - - `/WARNINGS=NOELABORATION (suppress warnings on elaboration pragmas)' - This qualifier suppresses warnings on missing pragma Elaborate_All - statements. See the section in this guide on elaboration checking - for details on when such pragma should be used. - - `/WARNINGS=OVERLAYS (activate warnings on address clause overlays)' - This qualifier activates warnings for possibly unintended - initialization effects of defining address clauses that cause one - variable to overlap another. The default is that such warnings are - generated. This warning can also be turned on using - `/WARNINGS=OPTIONAL'. - - `/WARNINGS=NOOVERLAYS (suppress warnings on address clause overlays)' - This qualifier suppresses warnings on possibly unintended - initialization effects of defining address clauses that cause one - variable to overlap another. - - `-gnatwp (activate warnings on ineffective pragma Inlines)' - This qualifier activates warnings for failure of front end inlining - (activated by `-gnatN') to inline a particular call. There are - many reasons for not being able to inline a call, including most - commonly that the call is too complex to inline. This warning can - also be turned on using `/WARNINGS=OPTIONAL'. - - `-gnatwP (suppress warnings on ineffective pragma Inlines)' - This qualifier suppresses warnings on ineffective pragma Inlines. - If the inlining mechanism cannot inline a call, it will simply - ignore the request silently. - - `/WARNINGS=REDUNDANT (activate warnings on redundant constructs)' - This qualifier activates warnings for redundant constructs. The - following is the current list of constructs regarded as redundant: - This warning can also be turned on using `/WARNINGS=OPTIONAL'. - - * Assignment of an item to itself. - - * Type conversion that converts an expression to its own type. - - * Use of the attribute `Base' where `typ'Base' is the same as - `typ'. - - * Use of pragma `Pack' when all components are placed by a - record representation clause. - - `/WARNINGS=NOREDUNDANT (suppress warnings on redundant constructs)' - This qualifier suppresses warnings for redundant constructs. - - `/WARNINGS=SUPPRESS (suppress all warnings)' - This qualifier completely suppresses the output of all warning - messages from the GNAT front end. Note that it does not suppress - warnings from the `GNAT COMPILE' back end. To suppress these back - end warnings as well, use the qualifier `-w' in addition to - `/WARNINGS=SUPPRESS'. - - `/WARNINGS=UNUSED (activate warnings on unused entities)' - This qualifier activates warnings to be generated for entities that - are defined but not referenced, and for units that are `with''ed - and not referenced. In the case of packages, a warning is also - generated if no entities in the package are referenced. This means - that if the package is referenced but the only references are in - `use' clauses or `renames' declarations, a warning is still - generated. A warning is also generated for a generic package that - is `with''ed but never instantiated. In the case where a package - or subprogram body is compiled, and there is a `with' on the - corresponding spec that is only referenced in the body, a warning - is also generated, noting that the `with' can be moved to the - body. The default is that such warnings are not generated. This - qualifier also activates warnings on unreferenced formals (it is - includes the effect of `/WARNINGS=UNREFERENCED_FORMALS'). This - warning can also be turned on using `/WARNINGS=OPTIONAL'. - - `/WARNINGS=NOUNUSED (suppress warnings on unused entities)' - This qualifier suppresses warnings for unused entities and - packages. It also turns off warnings on unreferenced formals (and - thus includes the effect of `/WARNINGS=NOUNREFERENCED_FORMALS'). - - A string of warning parameters can be used in the same parameter. - For example: - - -gnatwaLe - - Would turn on all optional warnings except for elaboration pragma - warnings, and also specify that warnings should be treated as - errors. - - `-w' - This qualifier suppresses warnings from the `GNAT COMPILE' - backend. It may be used in conjunction with `/WARNINGS=SUPPRESS' - to ensure that all warnings are suppressed during the entire - compilation process. - -  - File: gnat_ug_vms.info, Node: Debugging and Assertion Control, Next: Run-Time Checks, Prev: Output and Error Message Control, Up: Qualifiers for GNAT COMPILE - - Debugging and Assertion Control - ------------------------------- - - `/CHECKS=ASSERTIONS' - The pragmas `Assert' and `Debug' normally have no effect and are - ignored. This qualifier, where `a' stands for assert, causes - `Assert' and `Debug' pragmas to be activated. - - The pragmas have the form: - - pragma Assert (BOOLEAN-EXPRESSION [, - STATIC-STRING-EXPRESSION]) - pragma Debug (PROCEDURE CALL) - - The `Assert' pragma causes BOOLEAN-EXPRESSION to be tested. If - the result is `True', the pragma has no effect (other than - possible side effects from evaluating the expression). If the - result is `False', the exception `Assert_Failure' declared in the - package `System.Assertions' is raised (passing - STATIC-STRING-EXPRESSION, if present, as the message associated - with the exception). If no string expression is given the default - is a string giving the file name and line number of the pragma. - - The `Debug' pragma causes PROCEDURE to be called. Note that - `pragma Debug' may appear within a declaration sequence, allowing - debugging procedures to be called between declarations. - - `/DEBUG[=debug-level]' - `/NODEBUG' - Specifies how much debugging information is to be included in the - resulting object file where 'debug-level' is one of the following: - `TRACEBACK (default)' - Include both debugger symbol records and traceback the object - file. - - `ALL' - Include both debugger symbol records and traceback in object - file. - - `NONE' - Excludes both debugger symbol records and traceback the - object file. Same as /NODEBUG. - - `SYMBOLS' - Includes only debugger symbol records in the object file. - Note that this doesn't include traceback information. - -  - File: gnat_ug_vms.info, Node: Validity Checking, Next: Style Checking, Prev: Run-Time Control, Up: Qualifiers for GNAT COMPILE - - Validity Checking - ----------------- - - The Ada 95 Reference Manual has specific requirements for checking for - invalid values. In particular, RM 13.9.1 requires that the evaluation - of invalid values (for example from unchecked conversions), not result - in erroneous execution. In GNAT, the result of such an evaluation in - normal default mode is to either use the value unmodified, or to raise - Constraint_Error in those cases where use of the unmodified value would - cause erroneous execution. The cases where unmodified values might lead - to erroneous execution are case statements (where a wild jump might - result from an invalid value), and subscripts on the left hand side - (where memory corruption could occur as a result of an invalid value). - - The `-gnatVx' qualifier allows more control over the validity - checking mode. The `x' argument here is a string of letters which - control which validity checks are performed in addition to the default - checks described above. - - * `-gnatVc' Validity checks for copies - - The right hand side of assignments, and the initializing values of - object declarations are validity checked. - - * `/VALIDITY_CHECKING=RM' Default (RM) validity checks - - Some validity checks are done by default following normal Ada - semantics (RM 13.9.1 (9-11)). A check is done in case statements - that the expression is within the range of the subtype. If it is - not, Constraint_Error is raised. For assignments to array - components, a check is done that the expression used as index is - within the range. If it is not, Constraint_Error is raised. Both - these validity checks may be turned off using qualifier `-gnatVD'. - They are turned on by default. If `-gnatVD' is specified, a - subsequent qualifier `/VALIDITY_CHECKING=RM' will leave the checks - turned on. Qualifier `-gnatVD' should be used only if you are - sure that all such expressions have valid values. If you use this - qualifier and invalid values are present, then the program is - erroneous, and wild jumps or memory overwriting may occur. - - * `-gnatVi' Validity checks for `in' mode parameters - - Arguments for parameters of mode `in' are validity checked in - function and procedure calls at the point of call. - - * `-gnatVm' Validity checks for `in out' mode parameters - - Arguments for parameters of mode `in out' are validity checked in - procedure calls at the point of call. The `'m'' here stands for - modify, since this concerns parameters that can be modified by the - call. Note that there is no specific option to test `out' - parameters, but any reference within the subprogram will be tested - in the usual manner, and if an invalid value is copied back, any - reference to it will be subject to validity checking. - - * `-gnatVo' Validity checks for operator and attribute operands - - Arguments for predefined operators and attributes are validity - checked. This includes all operators in package `Standard', the - shift operators defined as intrinsic in package `Interfaces' and - operands for attributes such as `Pos'. - - * `-gnatVr' Validity checks for function returns - - The expression in `return' statements in functions is validity - checked. - - * `-gnatVs' Validity checks for subscripts - - All subscripts expressions are checked for validity, whether they - appear on the right side or left side (in default mode only left - side subscripts are validity checked). - - * `-gnatVt' Validity checks for tests - - Expressions used as conditions in `if', `while' or `exit' - statements are checked, as well as guard expressions in entry - calls. - - * `/VALIDITY_CHECKING=FULL' Validity checks for floating-point values - - In the absence of this qualifier, validity checking occurs only - for discrete values. If `/VALIDITY_CHECKING=FULL' is specified, - then validity checking also applies for floating-point values, and - NaN's and infinities are considered invalid, as well as out of - range values for constrained types. Note that this means that - standard `IEEE' infinity mode is not allowed. The exact contexts - in which floating-point values are checked depends on the setting - of other options. For example `-gnatVif' or `-gnatVfi' (the order - does not matter) specifies that floating-point parameters of mode - `in' should be validity checked. - - * `-gnatVa' All validity checks - - All the above validity checks are turned on. That is `-gnatVa' is - equivalent to `gnatVcdfimorst'. - - * `-gnatVn' No validity checks - - This qualifier turns off all validity checking, including the - default checking for case statements and left hand side - subscripts. Note that the use of the qualifier - `/CHECKS=SUPPRESS_ALL' supresses all run-time checks, including - validity checks, and thus implies `-gnatVn'. - - - The `/VALIDITY_CHECKING' qualifier may be followed by a string of - letters to turn on a series of validity checking options. For example, - `-gnatVcr' specifies that in addition to the default validity checking, - copies and function return expressions be validity checked. In order to - make it easier to specify a set of options, the upper case letters - `CDFIMORST' may be used to turn off the corresponding lower case - option, so for example `-gnatVaM' turns on all validity checking - options except for checking of `in out' procedure arguments. - - The specification of additional validity checking generates extra - code (and in the case of `-gnatva' the code expansion can be - substantial. However, these additional checks can be very useful in - smoking out cases of uninitialized variables, incorrect use of - unchecked conversion, and other errors leading to invalid values. The - use of pragma `Initialize_Scalars' is useful in conjunction with the - extra validity checking, since this ensures that wherever possible - uninitialized variables have invalid values. - - See also the pragma `Validity_Checks' which allows modification of - the validity checking mode at the program source level, and also allows - for temporary disabling of validity checks. - -  - File: gnat_ug_vms.info, Node: Style Checking, Next: Using GNAT COMPILE for Syntax Checking, Prev: Validity Checking, Up: Qualifiers for GNAT COMPILE - - Style Checking - -------------- - - The /STYLE=(OPTION,OPTION,..) qualifier causes the compiler to enforce - specified style rules. A limited set of style rules has been used in - writing the GNAT sources themselves. This qualifier allows user programs - to activate all or some of these checks. If the source program fails a - specified style check, an appropriate warning message is given, - preceded by the character sequence "(style)". (OPTION,OPTION,..) is a - sequence of keywords indicating the particular style checks to be - performed. The following checks are defined: - - `1-9 (specify indentation level)' - If a digit from 1-9 appears in the string after `/STYLE=' then - proper indentation is checked, with the digit indicating the - indentation level required. The general style of required - indentation is as specified by the examples in the Ada Reference - Manual. Full line comments must be aligned with the `--' starting - on a column that is a multiple of the alignment level. - - `ATTRIBUTE (check attribute casing)' - If the word ATTRIBUTE appears in the string after `/STYLE=' then - attribute names, including the case of keywords such as `digits' - used as attributes names, must be written in mixed case, that is, - the initial letter and any letter following an underscore must be - uppercase. All other letters must be lowercase. - - `BLANKS (blanks not allowed at statement end)' - If the word BLANKS appears in the string after `/STYLE=' then - trailing blanks are not allowed at the end of statements. The - purpose of this rule, together with h (no horizontal tabs), is to - enforce a canonical format for the use of blanks to separate - source tokens. - - `COMMENTS (check comments)' - If the word COMMENTS appears in the string after `/STYLE=' then - comments must meet the following set of rules: - - * The "-" that starts the column must either start in column - one, or else at least one blank must precede this sequence. - - * Comments that follow other tokens on a line must have at - least one blank following the "-" at the start of the comment. - - * Full line comments must have two blanks following the "-" - that starts the comment, with the following exceptions. - - * A line consisting only of the "-" characters, possibly - preceded by blanks is permitted. - - * A comment starting with "-x" where x is a special character - is permitted. This alows proper processing of the output - generated by specialized tools including `GNAT PREPROCESS' - (where -! is used) and the SPARK annnotation language (where - -# is used). For the purposes of this rule, a special - character is defined as being in one of the ASCII ranges - 16#21#..16#2F# or 16#3A#..16#3F#. - - * A line consisting entirely of minus signs, possibly preceded - by blanks, is permitted. This allows the construction of box - comments where lines of minus signs are used to form the top - and bottom of the box. - - * If a comment starts and ends with "-" is permitted as long as - at least one blank follows the initial "-". Together with the - preceding rule, this allows the construction of box comments, - as shown in the following example: - --------------------------- - -- This is a box comment -- - -- with two text lines. -- - --------------------------- - - `END (check end/exit labels)' - If the word END appears in the string after `/STYLE=' then - optional labels on `end' statements ending subprograms and on - `exit' statements exiting named loops, are required to be present. - - `VTABS (no form feeds or vertical tabs)' - If the word VTABS appears in the string after `/STYLE=' then - neither form feeds nor vertical tab characters are not permitted - in the source text. - - `HTABS (no horizontal tabs)' - If the word HTABS appears in the string after `/STYLE=' then - horizontal tab characters are not permitted in the source text. - Together with the b (no blanks at end of line) check, this - enforces a canonical form for the use of blanks to separate source - tokens. - - `IF_THEN (check if-then layout)' - If the word IF_THEN appears in the string after `/STYLE=', then - the keyword `then' must appear either on the same line as - corresponding `if', or on a line on its own, lined up under the - `if' with at least one non-blank line in between containing all or - part of the condition to be tested. - - `KEYWORD (check keyword casing)' - If the word KEYWORD appears in the string after `/STYLE=' then all - keywords must be in lower case (with the exception of keywords - such as `digits' used as attribute names to which this check does - not apply). - - `LAYOUT (check layout)' - If the word LAYOUT appears in the string after `/STYLE=' then - layout of statement and declaration constructs must follow the - recommendations in the Ada Reference Manual, as indicated by the - form of the syntax rules. For example an `else' keyword must be - lined up with the corresponding `if' keyword. - - There are two respects in which the style rule enforced by this - check option are more liberal than those in the Ada Reference - Manual. First in the case of record declarations, it is - permissible to put the `record' keyword on the same line as the - `type' keyword, and then the `end' in `end record' must line up - under `type'. For example, either of the following two layouts is - acceptable: - - type q is record - a : integer; - b : integer; - end record; - - type q is - record - a : integer; - b : integer; - end record; - - Second, in the case of a block statement, a permitted alternative - is to put the block label on the same line as the `declare' or - `begin' keyword, and then line the `end' keyword up under the - block label. For example both the following are permitted: - - Block : declare - A : Integer := 3; - begin - Proc (A, A); - end Block; - - Block : - declare - A : Integer := 3; - begin - Proc (A, A); - end Block; - - The same alternative format is allowed for loops. For example, - both of the following are permitted: - - Clear : while J < 10 loop - A (J) := 0; - end loop Clear; - - Clear : - while J < 10 loop - A (J) := 0; - end loop Clear; - - `LINE_LENGTH (check maximum line length)' - If the word LINE_LENGTH appears in the string after `/STYLE=' then - the length of source lines must not exceed 79 characters, including - any trailing blanks. The value of 79 allows convenient display on - an 80 character wide device or window, allowing for possible - special treatment of 80 character lines. - - `MAX_LENGTH=nnn (set maximum line length)' - If the sequence MAX_LENGTH=nnn, where nnn is a decimal number, - appears in the string after `/STYLE=' then the length of lines - must not exceed the given value. - - `STANDARD_CASING (check casing of entities in Standard)' - If the word STANDARD_CASING appears in the string after `/STYLE=' - then any identifier from Standard must be cased to match the - presentation in the Ada Reference Manual (for example, `Integer' - and `ASCII.NUL'). - - `ORDERED_SUBPROGRAMS (check order of subprogram bodies)' - If the word ORDERED_SUBPROGRAMS appears in the string after - `/STYLE=' then all subprogram bodies in a given scope (e.g. a - package body) must be in alphabetical order. The ordering rule - uses normal Ada rules for comparing strings, ignoring casing of - letters, except that if there is a trailing numeric suffix, then - the value of this suffix is used in the ordering (e.g. Junk2 comes - before Junk10). - - `PRAGMA (check pragma casing)' - If the word PRAGMA appears in the string after `/STYLE=' then - pragma names must be written in mixed case, that is, the initial - letter and any letter following an underscore must be uppercase. - All other letters must be lowercase. - - `REFERENCES (check references)' - If the word REFERENCES appears in the string after `/STYLE=' then - all identifier references must be cased in the same way as the - corresponding declaration. No specific casing style is imposed on - identifiers. The only requirement is for consistency of references - with declarations. - - `SPECS (check separate specs)' - If the word SPECS appears in the string after `/STYLE=' then - separate declarations ("specs") are required for subprograms (a - body is not allowed to serve as its own declaration). The only - exception is that parameterless library level procedures are not - required to have a separate declaration. This exception covers the - most frequent form of main program procedures. - - `TOKEN (check token spacing)' - If the word TOKEN appears in the string after `/STYLE=' then the - following token spacing rules are enforced: - - * The keywords `abs' and `not' must be followed by a space. - - * The token `=>' must be surrounded by spaces. - - * The token `<>' must be preceded by a space or a left - parenthesis. - - * Binary operators other than `**' must be surrounded by spaces. - There is no restriction on the layout of the `**' binary - operator. - - * Colon must be surrounded by spaces. - - * Colon-equal (assignment) must be surrounded by spaces. - - * Comma must be the first non-blank character on the line, or be - immediately preceded by a non-blank character, and must be - followed by a space. - - * If the token preceding a left paren ends with a letter or - digit, then a space must separate the two tokens. - - * A right parenthesis must either be the first non-blank - character on a line, or it must be preceded by a non-blank - character. - - * A semicolon must not be preceded by a space, and must not be - followed by a non-blank character. - - * A unary plus or minus may not be followed by a space. - - * A vertical bar must be surrounded by spaces. - - In the above rules, appearing in column one is always permitted, - that is, counts as meeting either a requirement for a required - preceding space, or as meeting a requirement for no preceding - space. - - Appearing at the end of a line is also always permitted, that is, - counts as meeting either a requirement for a following space, or - as meeting a requirement for no following space. - - If any of these style rules is violated, a message is generated giving - details on the violation. The initial characters of such messages are - always "(style)". Note that these messages are treated as warning - messages, so they normally do not prevent the generation of an object - file. The `/WARNINGS=ERROR' qualifier can be used to treat warning - messages, including style messages, as fatal errors. - - The qualifier /STYLE_CHECKS=ALL_BUILTIN is equivalent to all checking - options enabled with the exception of ORDERED_SUBPROGRAMS, with an - indentation level of 3. This is the standard checking option that is - used for the GNAT sources. - -  - File: gnat_ug_vms.info, Node: Run-Time Checks, Next: Stack Overflow Checking, Prev: Debugging and Assertion Control, Up: Qualifiers for GNAT COMPILE - - Run-Time Checks - --------------- - - If you compile with the default options, GNAT will insert many run-time - checks into the compiled code, including code that performs range - checking against constraints, but not arithmetic overflow checking for - integer operations (including division by zero) or checks for access - before elaboration on subprogram calls. All other run-time checks, as - required by the Ada 95 Reference Manual, are generated by default. The - following `GNAT COMPILE' qualifiers refine this default behavior: - - `/CHECKS=SUPPRESS_ALL' - Suppress all run-time checks as though `pragma Suppress - (all_checks') had been present in the source. Validity checks are - also suppressed (in other words `/CHECKS=SUPPRESS_ALL' also - implies `-gnatVn'. Use this qualifier to improve the performance - of the code at the expense of safety in the presence of invalid - data or program bugs. - - `/CHECKS=OVERFLOW' - Enables overflow checking for integer operations. This causes - GNAT to generate slower and larger executable programs by adding - code to check for overflow (resulting in raising - `Constraint_Error' as required by standard Ada semantics). These - overflow checks correspond to situations in which the true value - of the result of an operation may be outside the base range of the - result type. The following example shows the distinction: - - X1 : Integer := Integer'Last; - X2 : Integer range 1 .. 5 := 5; - ... - X1 := X1 + 1; -- `/CHECKS=OVERFLOW' required to catch the Constraint_Error - X2 := X2 + 1; -- range check, `/CHECKS=OVERFLOW' has no effect here - - Here the first addition results in a value that is outside the - base range of Integer, and hence requires an overflow check for - detection of the constraint error. The second increment operation - results in a violation of the explicit range constraint, and such - range checks are always performed. Basically the compiler can - assume that in the absence of the `/CHECKS=OVERFLOW' qualifier - that any value of type `xxx' is in range of the base type of `xxx'. - - Note that the `/CHECKS=OVERFLOW' qualifier does not affect the - code generated for any floating-point operations; it applies only - to integer semantics). For floating-point, GNAT has the - `Machine_Overflows' attribute set to `False' and the normal mode - of operation is to generate IEEE NaN and infinite values on - overflow or invalid operations (such as dividing 0.0 by 0.0). - - The reason that we distinguish overflow checking from other kinds - of range constraint checking is that a failure of an overflow - check can generate an incorrect value, but cannot cause erroneous - behavior. This is unlike the situation with a constraint check on - an array subscript, where failure to perform the check can result - in random memory description, or the range check on a case - statement, where failure to perform the check can cause a wild - jump. - - Note again that `/CHECKS=OVERFLOW' is off by default, so overflow - checking is not performed in default mode. This means that out of - the box, with the default settings, GNAT does not do all the - checks expected from the language description in the Ada Reference - Manual. If you want all constraint checks to be performed, as - described in this Manual, then you must explicitly use the - /CHECKS=OVERFLOW qualifier either on the `GNAT MAKE' or `GNAT - COMPILE' command. - - `/CHECKS=ELABORATION' - Enables dynamic checks for access-before-elaboration on subprogram - calls and generic instantiations. For full details of the effect - and use of this qualifier, *Note Compiling Using GNAT COMPILE::. - - The setting of these qualifiers only controls the default setting of the - checks. You may modify them using either `Suppress' (to remove checks) - or `Unsuppress' (to add back suppressed checks) pragmas in the program - source. - -  - File: gnat_ug_vms.info, Node: Stack Overflow Checking, Next: Run-Time Control, Prev: Run-Time Checks, Up: Qualifiers for GNAT COMPILE - - Stack Overflow Checking - ----------------------- - - For most operating systems, `GNAT COMPILE' does not perform stack - overflow checking by default. This means that if the main environment - task or some other task exceeds the available stack space, then - unpredictable behavior will occur. - - To activate stack checking, compile all units with the GNAT COMPILE - option `-fstack-check'. For example: - - GNAT COMPILE -fstack-check PACKAGE1.ADB - - Units compiled with this option will generate extra instructions to - check that any use of the stack (for procedure calls or for declaring - local variables in declare blocks) do not exceed the available stack - space. If the space is exceeded, then a `Storage_Error' exception is - raised. - - For declared tasks, the stack size is always controlled by the size - given in an applicable `Storage_Size' pragma (or is set to the default - size if no pragma is used. - - For the environment task, the stack size depends on system defaults - and is unknown to the compiler. The stack may even dynamically grow on - some systems, precluding the normal Ada semantics for stack overflow. - In the worst case, unbounded stack usage, causes unbounded stack - expansion resulting in the system running out of virtual memory. - - The stack checking may still work correctly if a fixed size stack is - allocated, but this cannot be guaranteed. To ensure that a clean - exception is signalled for stack overflow, set the environment variable - `GNAT_STACK_LIMIT' to indicate the maximum stack area that can be used, - as in: - - SET GNAT_STACK_LIMIT 1600 - - The limit is given in kilobytes, so the above declaration would set the - stack limit of the environment task to 1.6 megabytes. Note that the - only purpose of this usage is to limit the amount of stack used by the - environment task. If it is necessary to increase the amount of stack - for the environment task, then this is an operating systems issue, and - must be addressed with the appropriate operating systems commands. - -  - File: gnat_ug_vms.info, Node: Run-Time Control, Next: Validity Checking, Prev: Stack Overflow Checking, Up: Qualifiers for GNAT COMPILE - - Run-Time Control - ---------------- - - `-gnatT nnn' - The `gnatT' qualifier can be used to specify the time-slicing value - to be used for task switching between equal priority tasks. The - value `nnn' is given in microseconds as a decimal integer. - - Setting the time-slicing value is only effective if the underlying - thread control system can accommodate time slicing. Check the - documentation of your operating system for details. Note that the - time-slicing value can also be set by use of pragma `Time_Slice' - or by use of the `t' qualifier in the GNAT BIND step. The pragma - overrides a command line argument if both are present, and the `t' - qualifier for GNAT BIND overrides both the pragma and the `GNAT - COMPILE' command line qualifier. - -  - File: gnat_ug_vms.info, Node: Using GNAT COMPILE for Syntax Checking, Next: Using GNAT COMPILE for Semantic Checking, Prev: Style Checking, Up: Qualifiers for GNAT COMPILE - - Using `GNAT COMPILE' for Syntax Checking - ---------------------------------------- - - `/SYNTAX_ONLY' - Run GNAT in syntax checking only mode. For example, the command - - $ GNAT COMPILE /SYNTAX_ONLY X.ADB - - compiles file `X.ADB' in syntax-check-only mode. You can check a - series of files in a single command . - - You may use other qualifiers in conjunction with `/SYNTAX_ONLY'. In - particular, `/LIST' and `/REPORT_ERRORS=VERBOSE' are useful to - control the format of any generated error messages. - - The output is simply the error messages, if any. No object file or - ALI file is generated by a syntax-only compilation. Also, no units - other than the one specified are accessed. For example, if a unit - `X' `with''s a unit `Y', compiling unit `X' in syntax check only - mode does not access the source file containing unit `Y'. - - Normally, GNAT allows only a single unit in a source file. - However, this restriction does not apply in syntax-check-only - mode, and it is possible to check a file containing multiple - compilation units concatenated together. This is primarily used by - the `GNAT CHOP' utility (*note Renaming Files Using GNAT CHOP::). - -  - File: gnat_ug_vms.info, Node: Using GNAT COMPILE for Semantic Checking, Next: Compiling Ada 83 Programs, Prev: Using GNAT COMPILE for Syntax Checking, Up: Qualifiers for GNAT COMPILE - - Using `GNAT COMPILE' for Semantic Checking - ------------------------------------------ - - `/NOLOAD' - Causes the compiler to operate in semantic check mode, with full - checking for all illegalities specified in the Ada 95 Reference - Manual, but without generation of any object code (no object file - is generated). - - Because dependent files must be accessed, you must follow the GNAT - semantic restrictions on file structuring to operate in this mode: - - * The needed source files must be accessible (*note Search - Paths and the Run-Time Library (RTL)::). - - * Each file must contain only one compilation unit. - - * The file name and unit name must match (*note File Naming - Rules::). - - The output consists of error messages as appropriate. No object - file is generated. An `ALI' file is generated for use in the - context of cross-reference tools, but this file is marked as not - being suitable for binding (since no object file is generated). - The checking corresponds exactly to the notion of legality in the - Ada 95 Reference Manual. - - Any unit can be compiled in semantics-checking-only mode, including - units that would not normally be compiled (subunits, and - specifications where a separate body is present). - -  - File: gnat_ug_vms.info, Node: Compiling Ada 83 Programs, Next: Character Set Control, Prev: Using GNAT COMPILE for Semantic Checking, Up: Qualifiers for GNAT COMPILE - - Compiling Ada 83 Programs - ------------------------- - - `/83' - Although GNAT is primarily an Ada 95 compiler, it accepts this - qualifier to specify that an Ada 83 program is to be compiled in - Ada83 mode. If you specify this qualifier, GNAT rejects most Ada - 95 extensions and applies Ada 83 semantics where this can be done - easily. It is not possible to guarantee this qualifier does a - perfect job; for example, some subtle tests, such as are found in - earlier ACVC tests (that have been removed from the ACVC suite for - Ada 95), may not compile correctly. However, for most purposes, - using this qualifier should help to ensure that programs that - compile correctly under the `/83' qualifier can be ported easily - to an Ada 83 compiler. This is the main use of the qualifier. - - With few exceptions (most notably the need to use `<>' on - unconstrained generic formal parameters, the use of the new Ada 95 - keywords, and the use of packages with optional bodies), it is not - necessary to use the `/83' qualifier when compiling Ada 83 - programs, because, with rare exceptions, Ada 95 is upwardly - compatible with Ada 83. This means that a correct Ada 83 program - is usually also a correct Ada 95 program. - -  - File: gnat_ug_vms.info, Node: Character Set Control, Next: File Naming Control, Prev: Compiling Ada 83 Programs, Up: Qualifiers for GNAT COMPILE - - Character Set Control - --------------------- - - `/IDENTIFIER_CHARACTER_SET=C' - Normally GNAT recognizes the Latin-1 character set in source - program identifiers, as described in the Ada 95 Reference Manual. - This qualifier causes GNAT to recognize alternate character sets - in identifiers. C is a single character or word indicating the - character set, as follows: - - `1' - Latin-1 identifiers - - `2' - Latin-2 letters allowed in identifiers - - `3' - Latin-3 letters allowed in identifiers - - `4' - Latin-4 letters allowed in identifiers - - `5' - Latin-5 (Cyrillic) letters allowed in identifiers - - `9' - Latin-9 letters allowed in identifiers - - `PC' - IBM PC letters (code page 437) allowed in identifiers - - `PC850' - IBM PC letters (code page 850) allowed in identifiers - - `FULL_UPPER' - Full upper-half codes allowed in identifiers - - `NO_UPPER' - No upper-half codes allowed in identifiers - - `WIDE' - Wide-character codes (that is, codes greater than 255) - allowed in identifiers - - *Note Foreign Language Representation::, for full details on the - implementation of these character sets. - - `/WIDE_CHARACTER_ENCODING=E' - Specify the method of encoding for wide characters. E is one of - the following: - - `HEX' - Hex encoding (brackets coding also recognized) - - `UPPER' - Upper half encoding (brackets encoding also recognized) - - `SHIFT_JIS' - Shift/JIS encoding (brackets encoding also recognized) - - `EUC' - EUC encoding (brackets encoding also recognized) - - `UTF8' - UTF-8 encoding (brackets encoding also recognized) - - `BRACKETS' - Brackets encoding only (default value) For full details on - the these encoding methods see *Note Wide Character Encodings::. - Note that brackets coding is always accepted, even if one of the - other options is specified, so for example - `/WIDE_CHARACTER_ENCODING=UTF8' specifies that both brackets and - `UTF-8' encodings will be recognized. The units that are with'ed - directly or indirectly will be scanned using the specified - representation scheme, and so if one of the non-brackets scheme is - used, it must be used consistently throughout the program. However, - since brackets encoding is always recognized, it may be - conveniently used in standard libraries, allowing these libraries - to be used with any of the available coding schemes. scheme. If - no `/WIDE_CHARACTER_ENCODING=?' parameter is present, then the - default representation is Brackets encoding only. - - Note that the wide character representation that is specified - (explicitly or by default) for the main program also acts as the - default encoding used for Wide_Text_IO files if not specifically - overridden by a WCEM form parameter. - -  - File: gnat_ug_vms.info, Node: File Naming Control, Next: Subprogram Inlining Control, Prev: Character Set Control, Up: Qualifiers for GNAT COMPILE - - File Naming Control - ------------------- - - `/FILE_NAME_MAX_LENGTH=N' - Activates file name "krunching". N, a decimal integer in the range - 1-999, indicates the maximum allowable length of a file name (not - including the `.ADS' or `.ADB' extension). The default is not to - enable file name krunching. - - For the source file naming rules, *Note File Naming Rules::. - -  - File: gnat_ug_vms.info, Node: Subprogram Inlining Control, Next: Auxiliary Output Control, Prev: File Naming Control, Up: Qualifiers for GNAT COMPILE - - Subprogram Inlining Control - --------------------------- - - `/INLINE=PRAGMA' - GNAT recognizes and processes `Inline' pragmas. However, for the - inlining to actually occur, optimization must be enabled. To enable - inlining across unit boundaries, this is, inlining a call in one - unit of a subprogram declared in a `with''ed unit, you must also - specify this qualifier. In the absence of this qualifier, GNAT - does not attempt inlining across units and does not need to access - the bodies of subprograms for which `pragma Inline' is specified - if they are not in the current unit. - - If you specify this qualifier the compiler will access these - bodies, creating an extra source dependency for the resulting - object file, and where possible, the call will be inlined. For - further details on when inlining is possible see *Note Inlining of - Subprograms::. - - `-gnatN' - The front end inlining activated by this qualifier is generally - more extensive, and quite often more effective than the standard - `/INLINE=PRAGMA' inlining mode. It will also generate additional - dependencies. - -  - File: gnat_ug_vms.info, Node: Auxiliary Output Control, Next: Debugging Control, Prev: Subprogram Inlining Control, Up: Qualifiers for GNAT COMPILE - - Auxiliary Output Control - ------------------------ - - `/TREE_OUTPUT' - Causes GNAT to write the internal tree for a unit to a file (with - the extension `.adt'. This not normally required, but is used by - separate analysis tools. Typically these tools do the necessary - compilations automatically, so you should not have to specify this - qualifier in normal operation. - - `/UNITS_LIST' - Print a list of units required by this compilation on `SYS$OUTPUT'. - The listing includes all units on which the unit being compiled - depends either directly or indirectly. - -  - File: gnat_ug_vms.info, Node: Debugging Control, Next: Units to Sources Mapping Files, Prev: Auxiliary Output Control, Up: Qualifiers for GNAT COMPILE - - Debugging Control - ----------------- - - `/EXPAND_SOURCE' - This qualifier causes the compiler to generate auxiliary output - containing a pseudo-source listing of the generated expanded code. - Like most Ada compilers, GNAT works by first transforming the high - level Ada code into lower level constructs. For example, tasking - operations are transformed into calls to the tasking run-time - routines. A unique capability of GNAT is to list this expanded - code in a form very close to normal Ada source. This is very - useful in understanding the implications of various Ada usage on - the efficiency of the generated code. There are many cases in Ada - (e.g. the use of controlled types), where simple Ada statements can - generate a lot of run-time code. By using `/EXPAND_SOURCE' you can - identify these cases, and consider whether it may be desirable to - modify the coding approach to improve efficiency. - - The format of the output is very similar to standard Ada source, - and is easily understood by an Ada programmer. The following - special syntactic additions correspond to low level features used - in the generated code that do not have any exact analogies in pure - Ada source form. The following is a partial list of these special - constructions. See the specification of package `Sprint' in file - `SPRINT.ADS' for a full list. - - `new XXX [storage_pool = YYY]' - Shows the storage pool being used for an allocator. - - `at end PROCEDURE-NAME;' - Shows the finalization (cleanup) procedure for a scope. - - `(if EXPR then EXPR else EXPR)' - Conditional expression equivalent to the `x?y:z' construction - in C. - - `TARGET^(SOURCE)' - A conversion with floating-point truncation instead of - rounding. - - `TARGET?(SOURCE)' - A conversion that bypasses normal Ada semantic checking. In - particular enumeration types and fixed-point types are - treated simply as integers. - - `TARGET?^(SOURCE)' - Combines the above two cases. - - `X #/ Y' - `X #mod Y' - `X #* Y' - `X #rem Y' - A division or multiplication of fixed-point values which are - treated as integers without any kind of scaling. - - `free EXPR [storage_pool = XXX]' - Shows the storage pool associated with a `free' statement. - - `freeze TYPENAME [ACTIONS]' - Shows the point at which TYPENAME is frozen, with possible - associated actions to be performed at the freeze point. - - `reference ITYPE' - Reference (and hence definition) to internal type ITYPE. - - `FUNCTION-NAME! (ARG, ARG, ARG)' - Intrinsic function call. - - `LABELNAME : label' - Declaration of label LABELNAME. - - `EXPR && EXPR && EXPR ... && EXPR' - A multiple concatenation (same effect as EXPR & EXPR & EXPR, - but handled more efficiently). - - `[constraint_error]' - Raise the `Constraint_Error' exception. - - `EXPRESSION'reference' - A pointer to the result of evaluating EXPRESSION. - - `TARGET-TYPE!(SOURCE-EXPRESSION)' - An unchecked conversion of SOURCE-EXPRESSION to TARGET-TYPE. - - `[NUMERATOR/DENOMINATOR]' - Used to represent internal real literals (that) have no exact - representation in base 2-16 (for example, the result of - compile time evaluation of the expression 1.0/27.0). - - `/XDEBUG' - This qualifier is used in conjunction with `/EXPAND_SOURCE' - to cause the expanded source, as described above to be - written to files with names `XXX_DG', where `xxx' is the - normal file name, for example, if the source file name is - `HELLO.ADB', then a file `HELLO.ADB_DG' will be written. The - debugging information generated by the `GNAT COMPILE' - `/DEBUG' qualifier will refer to the generated `XXX_DG' file. - This allows you to do source level debugging using the - generated code which is sometimes useful for complex code, - for example to find out exactly which part of a complex - construction raised an exception. This qualifier also - suppress generation of cross-reference information (see - /XREF=SUPPRESS). - - `/COMPRESS_NAMES' - In the generated debugging information, and also in the case - of long external names, the compiler uses a compression - mechanism if the name is very long. This compression method - uses a checksum, and avoids trouble on some operating systems - which have difficulty with very long names. The - `/COMPRESS_NAMES' qualifier forces this compression approach - to be used on all external names and names in the debugging - information tables. This reduces the size of the generated - executable, at the expense of making the naming scheme more - complex. The compression only affects the qualification of - the name. Thus a name in the source: - - Very_Long_Package.Very_Long_Inner_Package.Var - - would normally appear in these tables as: - - very_long_package__very_long_inner_package__var - - but if the `/COMPRESS_NAMES' qualifier is used, then the name - appears as - - XCb7e0c705__var - - Here b7e0c705 is a compressed encoding of the qualification - prefix. The GNAT Ada aware version of GDB understands these - encoded prefixes, so if this debugger is used, the encoding - is largely hidden from the user of the compiler. - - `/REPRESENTATION_INFO[0|1|2|3][s]' - This qualifier controls output from the compiler of a listing - showing representation information for declared types and objects. - For `/REPRESENTATION_INFO=NONE', no information is output - (equivalent to omitting the `/REPRESENTATION_INFO' qualifier). For - `/REPRESENTATION_INFO=ARRAYS' (which is the default, so - `/REPRESENTATION_INFO' with no parameter has the same effect), - size and alignment information is listed for declared array and - record types. For `/REPRESENTATION_INFO=OBJECTS', size and - alignment information is listed for all expression information for - values that are computed at run time for variant records. These - symbolic expressions have a mostly obvious format with #n being - used to represent the value of the n'th discriminant. See source - files `REPINFO.ADS/adb' in the `GNAT' sources for full detalis on - the format of `/REPRESENTATION_INFO=SYMBOLIC' output. If the - qualifier is followed by an s (e.g. `-gnatR2s'), then the output - is to a file with the name `file_REP' where file is the name of - the corresponding source file. - - `/XREF=SUPPRESS' - Normally the compiler generates full cross-referencing information - in the `ALI' file. This information is used by a number of tools, - including `GNAT FIND' and `GNAT XREF'. The /XREF=SUPPRESS qualifier - suppresses this information. This saves some space and may slightly - speed up compilation, but means that these tools cannot be used. - -  - File: gnat_ug_vms.info, Node: Units to Sources Mapping Files, Prev: Debugging Control, Up: Qualifiers for GNAT COMPILE - - Units to Sources Mapping Files - ------------------------------ - - `-gnatemPATH' - A mapping file is a way to communicate to the compiler two - mappings: from unit names to file names (without any directory - information) and from file names to path names (with full - directory information). These mappings are used by the compiler to - short-circuit the path search. - - A mapping file is a sequence of sets of three lines. In each set, - the first line is the unit name, in lower case, with "%s" appended - for specifications and "%b" appended for bodies; the second line - is the file name; and the third line is the path name. - - Example: - main%b - main.2.ADA - /gnat/project1/sources/main.2.ADA - - When the qualifier `-gnatem' is specified, the compiler will create - in memory the two mappings from the specified file. If there is - any problem (non existent file, truncated file or duplicate - entries), no mapping will be created. - - Several `-gnatem' qualifiers may be specified; however, only the - last one on the command line will be taken into account. - - When using a project file, `GNAT MAKE' create a temporary mapping - file and communicates it to the compiler using this qualifier. - -  - File: gnat_ug_vms.info, Node: Search Paths and the Run-Time Library (RTL), Next: Order of Compilation Issues, Prev: Qualifiers for GNAT COMPILE, Up: Compiling Using GNAT COMPILE - - Search Paths and the Run-Time Library (RTL) - =========================================== - - With the GNAT source-based library system, the compiler must be able to - find source files for units that are needed by the unit being compiled. - Search paths are used to guide this process. - - The compiler compiles one source file whose name must be given - explicitly on the command line. In other words, no searching is done - for this file. To find all other source files that are needed (the most - common being the specs of units), the compiler examines the following - directories, in the following order: - - 1. The directory containing the source file of the main unit being - compiled (the file name on the command line). - - 2. Each directory named by an `/SOURCE_SEARCH' qualifier given on the - `GNAT COMPILE' command line, in the order given. - - 3. Each of the directories listed in the value of the - `ADA_INCLUDE_PATH' logical name. Normally, define this value as a - logical name containing a comma separated list of directory names. - - This variable can also be defined by means of an environment string - (an argument to the DEC C exec* set of functions). - - Logical Name: - DEFINE ANOTHER_PATH FOO:[BAG] - DEFINE ADA_INCLUDE_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR] - - By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] - first, followed by the standard Ada 95 libraries in - GNU:[LIB.OPENVMS7_x.2_8_x.ADAINCLUDE]. If this is not redefined, - the user will obtain the DEC Ada83 IO packages (Text_IO, - Sequential_IO, etc) instead of the Ada95 packages. Thus, in order - to get the Ada 95 packages by default, ADA_INCLUDE_PATH must be - redefined. - - 4. The content of the "ada_source_path" file which is part of the GNAT - installation tree and is used to store standard libraries such as - the GNAT Run Time Library (RTL) source files. - - Specifying the qualifier `/NOCURRENT_DIRECTORY' inhibits the use of the - directory containing the source file named in the command line. You can - still have this directory on your search path, but in this case it must - be explicitly requested with a `/SOURCE_SEARCH' qualifier. - - Specifying the qualifier `/NOSTD_INCLUDES' inhibits the search of - the default location for the GNAT Run Time Library (RTL) source files. - - The compiler outputs its object files and ALI files in the current - working directory. - - The packages `Ada', `System', and `Interfaces' and their children - make up the GNAT RTL, together with the simple `System.IO' package used - in the "Hello World" example. The sources for these units are needed by - the compiler and are kept together in one directory. Not all of the - bodies are needed, but all of the sources are kept together anyway. In - a normal installation, you need not specify these directory names when - compiling or binding. Either the environment variables or the built-in - defaults cause these files to be found. - - In addition to the language-defined hierarchies (System, Ada and - Interfaces), the GNAT distribution provides a fourth hierarchy, - consisting of child units of GNAT. This is a collection of generally - useful routines. See the GNAT Reference Manual for further details. - - Besides simplifying access to the RTL, a major use of search paths is - in compiling sources from multiple directories. This can make - development environments much more flexible. - -  - File: gnat_ug_vms.info, Node: Order of Compilation Issues, Next: Examples, Prev: Search Paths and the Run-Time Library (RTL), Up: Compiling Using GNAT COMPILE - - Order of Compilation Issues - =========================== - - If, in our earlier example, there was a spec for the `hello' procedure, - it would be contained in the file `HELLO.ADS'; yet this file would not - have to be explicitly compiled. This is the result of the model we - chose to implement library management. Some of the consequences of this - model are as follows: - - * There is no point in compiling specs (except for package specs - with no bodies) because these are compiled as needed by clients. If - you attempt a useless compilation, you will receive an error - message. It is also useless to compile subunits because they are - compiled as needed by the parent. - - * There are no order of compilation requirements: performing a - compilation never obsoletes anything. The only way you can obsolete - something and require recompilations is to modify one of the - source files on which it depends. - - * There is no library as such, apart from the ALI files (*note The - Ada Library Information Files::, for information on the format of - these files). For now we find it convenient to create separate ALI - files, but eventually the information therein may be incorporated - into the object file directly. - - * When you compile a unit, the source files for the specs of all - units that it `with''s, all its subunits, and the bodies of any - generics it instantiates must be available (reachable by the - search-paths mechanism described above), or you will receive a - fatal error message. - -  - File: gnat_ug_vms.info, Node: Examples, Prev: Order of Compilation Issues, Up: Compiling Using GNAT COMPILE - - Examples - ======== - - The following are some typical Ada compilation command line examples: - - `$ GNAT COMPILE XYZ.ADB' - Compile body in file `XYZ.ADB' with all default options. - - `$ GNAT COMPILE /OPTIMIZE=ALL /CHECKS=ASSERTIONS XYZ-DEF.ADB' - Compile the child unit package in file `XYZ-DEF.ADB' with extensive - optimizations, and pragma `Assert'/`Debug' statements enabled. - - `$ GNAT COMPILE /NOLOAD ABC-DEF.ADB' - Compile the subunit in file `ABC-DEF.ADB' in semantic-checking-only - mode. - -  - File: gnat_ug_vms.info, Node: Binding Using GNAT BIND, Next: Linking Using GNAT LINK, Prev: Compiling Using GNAT COMPILE, Up: Top - - Binding Using `GNAT BIND' - ************************* - - * Menu: - - * Running GNAT BIND:: - * Generating the Binder Program in C:: - * Consistency-Checking Modes:: - * Binder Error Message Control:: - * Elaboration Control:: - * Output Control:: - * Binding with Non-Ada Main Programs:: - * Binding Programs with No Main Subprogram:: - * Summary of Binder Qualifiers:: - * Command-Line Access:: - * Search Paths for GNAT BIND:: - * Examples of GNAT BIND Usage:: - - This chapter describes the GNAT binder, `GNAT BIND', which is used to - bind compiled GNAT objects. The `GNAT BIND' program performs four - separate functions: - - 1. Checks that a program is consistent, in accordance with the rules - in Chapter 10 of the Ada 95 Reference Manual. In particular, error - messages are generated if a program uses inconsistent versions of a - given unit. - - 2. Checks that an acceptable order of elaboration exists for the - program and issues an error message if it cannot find an order of - elaboration that satisfies the rules in Chapter 10 of the Ada 95 - Language Manual. - - 3. Generates a main program incorporating the given elaboration order. - This program is a small Ada package (body and spec) that must be - subsequently compiled using the GNAT compiler. The necessary - compilation step is usually performed automatically by `GNAT - LINK'. The two most important functions of this program are to - call the elaboration routines of units in an appropriate order and - to call the main program. - - 4. Determines the set of object files required by the given main - program. This information is output in the forms of comments in - the generated program, to be read by the `GNAT LINK' utility used - to link the Ada application. - -  - File: gnat_ug_vms.info, Node: Running GNAT BIND, Next: Generating the Binder Program in C, Up: Binding Using GNAT BIND - - Running `GNAT BIND' - =================== - - The form of the `GNAT BIND' command is - - $ GNAT BIND [QUALIFIERS] MAINPROG[.ALI] [QUALIFIERS] - - where MAINPROG.ADB is the Ada file containing the main program unit - body. If no qualifiers are specified, `GNAT BIND' constructs an Ada - package in two files which names are `B$ADA_MAIN.ADS', and - `B$ADA_MAIN.ADB'. For example, if given the parameter `HELLO.ALI', for - a main program contained in file `HELLO.ADB', the binder output files - would be `B~HELLO.ADS' and `B~HELLO.ADB'. - - When doing consistency checking, the binder takes into consideration - any source files it can locate. For example, if the binder determines - that the given main program requires the package `Pack', whose `.ALI' - file is `PACK.ALI' and whose corresponding source spec file is - `PACK.ADS', it attempts to locate the source file `PACK.ADS' (using the - same search path conventions as previously described for the `GNAT - COMPILE' command). If it can locate this source file, it checks that - the time stamps or source checksums of the source and its references to - in `ali' files match. In other words, any `ali' files that mentions - this spec must have resulted from compiling this version of the source - file (or in the case where the source checksums match, a version close - enough that the difference does not matter). - - The effect of this consistency checking, which includes source - files, is that the binder ensures that the program is consistent with - the latest version of the source files that can be located at bind - time. Editing a source file without compiling files that depend on the - source file cause error messages to be generated by the binder. - - For example, suppose you have a main program `HELLO.ADB' and a - package `P', from file `P.ADS' and you perform the following steps: - - 1. Enter `GNAT COMPILE HELLO.ADB' to compile the main program. - - 2. Enter `GNAT COMPILE P.ADS' to compile package `P'. - - 3. Edit file `P.ADS'. - - 4. Enter `GNAT BIND hello'. - - At this point, the file `P.ALI' contains an out-of-date time stamp - because the file `P.ADS' has been edited. The attempt at binding fails, - and the binder generates the following error messages: - - error: "HELLO.ADB" must be recompiled ("P.ADS" has been modified) - error: "P.ADS" has been modified and must be recompiled - - Now both files must be recompiled as indicated, and then the bind can - succeed, generating a main program. You need not normally be concerned - with the contents of this file, but it is similar to the following which - is the binder file generated for a simple "hello world" program. - - -- The package is called Ada_Main unless this name is actually used - -- as a unit name in the partition, in which case some other unique - -- name is used. - - with System; - package ada_main is - - Elab_Final_Code : Integer; - pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code"); - - -- The main program saves the parameters (argument count, - -- argument values, environment pointer) in global variables - -- for later access by other units including - -- Ada.Command_Line. - - gnat_argc : Integer; - gnat_argv : System.Address; - gnat_envp : System.Address; - - -- The actual variables are stored in a library routine. This - -- is useful for some shared library situations, where there - -- are problems if variables are not in the library. - - pragma Import (C, gnat_argc); - pragma Import (C, gnat_argv); - pragma Import (C, gnat_envp); - - -- The exit status is similarly an external location - - gnat_exit_status : Integer; - pragma Import (C, gnat_exit_status); - - GNAT_Version : constant String := - "GNAT Version: 3.15w (20010315)"; - pragma Export (C, GNAT_Version, "__gnat_version"); - - -- This is the generated adafinal routine that performs - -- finalization at the end of execution. In the case where - -- Ada is the main program, this main program makes a call - -- to adafinal at program termination. - - procedure adafinal; - pragma Export (C, adafinal, "adafinal"); - - -- This is the generated adainit routine that performs - -- initialization at the start of execution. In the case - -- where Ada is the main program, this main program makes - -- a call to adainit at program startup. - - procedure adainit; - pragma Export (C, adainit, "adainit"); - - -- This routine is called at the start of execution. It is - -- a dummy routine that is used by the debugger to breakpoint - -- at the start of execution. - - procedure Break_Start; - pragma Import (C, Break_Start, "__gnat_break_start"); - - -- This is the actual generated main program (it would be - -- suppressed if the no main program qualifier were used). As - -- required by standard system conventions, this program has - -- the external name main. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer; - pragma Export (C, main, "main"); - - -- The following set of constants give the version - -- identification values for every unit in the bound - -- partition. This identification is computed from all - -- dependent semantic units, and corresponds to the - -- string that would be returned by use of the - -- Body_Version or Version attributes. - - type Version_32 is mod 2 ** 32; - u00001 : constant Version_32 := 16#7880BEB3#; - u00002 : constant Version_32 := 16#0D24CBD0#; - u00003 : constant Version_32 := 16#3283DBEB#; - u00004 : constant Version_32 := 16#2359F9ED#; - u00005 : constant Version_32 := 16#664FB847#; - u00006 : constant Version_32 := 16#68E803DF#; - u00007 : constant Version_32 := 16#5572E604#; - u00008 : constant Version_32 := 16#46B173D8#; - u00009 : constant Version_32 := 16#156A40CF#; - u00010 : constant Version_32 := 16#033DABE0#; - u00011 : constant Version_32 := 16#6AB38FEA#; - u00012 : constant Version_32 := 16#22B6217D#; - u00013 : constant Version_32 := 16#68A22947#; - u00014 : constant Version_32 := 16#18CC4A56#; - u00015 : constant Version_32 := 16#08258E1B#; - u00016 : constant Version_32 := 16#367D5222#; - u00017 : constant Version_32 := 16#20C9ECA4#; - u00018 : constant Version_32 := 16#50D32CB6#; - u00019 : constant Version_32 := 16#39A8BB77#; - u00020 : constant Version_32 := 16#5CF8FA2B#; - u00021 : constant Version_32 := 16#2F1EB794#; - u00022 : constant Version_32 := 16#31AB6444#; - u00023 : constant Version_32 := 16#1574B6E9#; - u00024 : constant Version_32 := 16#5109C189#; - u00025 : constant Version_32 := 16#56D770CD#; - u00026 : constant Version_32 := 16#02F9DE3D#; - u00027 : constant Version_32 := 16#08AB6B2C#; - u00028 : constant Version_32 := 16#3FA37670#; - u00029 : constant Version_32 := 16#476457A0#; - u00030 : constant Version_32 := 16#731E1B6E#; - u00031 : constant Version_32 := 16#23C2E789#; - u00032 : constant Version_32 := 16#0F1BD6A1#; - u00033 : constant Version_32 := 16#7C25DE96#; - u00034 : constant Version_32 := 16#39ADFFA2#; - u00035 : constant Version_32 := 16#571DE3E7#; - u00036 : constant Version_32 := 16#5EB646AB#; - u00037 : constant Version_32 := 16#4249379B#; - u00038 : constant Version_32 := 16#0357E00A#; - u00039 : constant Version_32 := 16#3784FB72#; - u00040 : constant Version_32 := 16#2E723019#; - u00041 : constant Version_32 := 16#623358EA#; - u00042 : constant Version_32 := 16#107F9465#; - u00043 : constant Version_32 := 16#6843F68A#; - u00044 : constant Version_32 := 16#63305874#; - u00045 : constant Version_32 := 16#31E56CE1#; - u00046 : constant Version_32 := 16#02917970#; - u00047 : constant Version_32 := 16#6CCBA70E#; - u00048 : constant Version_32 := 16#41CD4204#; - u00049 : constant Version_32 := 16#572E3F58#; - u00050 : constant Version_32 := 16#20729FF5#; - u00051 : constant Version_32 := 16#1D4F93E8#; - u00052 : constant Version_32 := 16#30B2EC3D#; - u00053 : constant Version_32 := 16#34054F96#; - u00054 : constant Version_32 := 16#5A199860#; - u00055 : constant Version_32 := 16#0E7F912B#; - u00056 : constant Version_32 := 16#5760634A#; - u00057 : constant Version_32 := 16#5D851835#; - - -- The following Export pragmas export the version numbers - -- with symbolic names ending in B (for body) or S - -- (for spec) so that they can be located in a link. The - -- information provided here is sufficient to track down - -- the exact versions of units used in a given build. - - pragma Export (C, u00001, "helloB"); - pragma Export (C, u00002, "system__standard_libraryB"); - pragma Export (C, u00003, "system__standard_libraryS"); - pragma Export (C, u00004, "adaS"); - pragma Export (C, u00005, "ada__text_ioB"); - pragma Export (C, u00006, "ada__text_ioS"); - pragma Export (C, u00007, "ada__exceptionsB"); - pragma Export (C, u00008, "ada__exceptionsS"); - pragma Export (C, u00009, "gnatS"); - pragma Export (C, u00010, "gnat__heap_sort_aB"); - pragma Export (C, u00011, "gnat__heap_sort_aS"); - pragma Export (C, u00012, "systemS"); - pragma Export (C, u00013, "system__exception_tableB"); - pragma Export (C, u00014, "system__exception_tableS"); - pragma Export (C, u00015, "gnat__htableB"); - pragma Export (C, u00016, "gnat__htableS"); - pragma Export (C, u00017, "system__exceptionsS"); - pragma Export (C, u00018, "system__machine_state_operationsB"); - pragma Export (C, u00019, "system__machine_state_operationsS"); - pragma Export (C, u00020, "system__machine_codeS"); - pragma Export (C, u00021, "system__storage_elementsB"); - pragma Export (C, u00022, "system__storage_elementsS"); - pragma Export (C, u00023, "system__secondary_stackB"); - pragma Export (C, u00024, "system__secondary_stackS"); - pragma Export (C, u00025, "system__parametersB"); - pragma Export (C, u00026, "system__parametersS"); - pragma Export (C, u00027, "system__soft_linksB"); - pragma Export (C, u00028, "system__soft_linksS"); - pragma Export (C, u00029, "system__stack_checkingB"); - pragma Export (C, u00030, "system__stack_checkingS"); - pragma Export (C, u00031, "system__tracebackB"); - pragma Export (C, u00032, "system__tracebackS"); - pragma Export (C, u00033, "ada__streamsS"); - pragma Export (C, u00034, "ada__tagsB"); - pragma Export (C, u00035, "ada__tagsS"); - pragma Export (C, u00036, "system__string_opsB"); - pragma Export (C, u00037, "system__string_opsS"); - pragma Export (C, u00038, "interfacesS"); - pragma Export (C, u00039, "interfaces__c_streamsB"); - pragma Export (C, u00040, "interfaces__c_streamsS"); - pragma Export (C, u00041, "system__file_ioB"); - pragma Export (C, u00042, "system__file_ioS"); - pragma Export (C, u00043, "ada__finalizationB"); - pragma Export (C, u00044, "ada__finalizationS"); - pragma Export (C, u00045, "system__finalization_rootB"); - pragma Export (C, u00046, "system__finalization_rootS"); - pragma Export (C, u00047, "system__finalization_implementationB"); - pragma Export (C, u00048, "system__finalization_implementationS"); - pragma Export (C, u00049, "system__string_ops_concat_3B"); - pragma Export (C, u00050, "system__string_ops_concat_3S"); - pragma Export (C, u00051, "system__stream_attributesB"); - pragma Export (C, u00052, "system__stream_attributesS"); - pragma Export (C, u00053, "ada__io_exceptionsS"); - pragma Export (C, u00054, "system__unsigned_typesS"); - pragma Export (C, u00055, "system__file_control_blockS"); - pragma Export (C, u00056, "ada__finalization__list_controllerB"); - pragma Export (C, u00057, "ada__finalization__list_controllerS"); - - -- BEGIN ELABORATION ORDER - -- ada (spec) - -- gnat (spec) - -- gnat.heap_sort_a (spec) - -- gnat.heap_sort_a (body) - -- gnat.htable (spec) - -- gnat.htable (body) - -- interfaces (spec) - -- system (spec) - -- system.machine_code (spec) - -- system.parameters (spec) - -- system.parameters (body) - -- interfaces.c_streams (spec) - -- interfaces.c_streams (body) - -- system.standard_library (spec) - -- ada.exceptions (spec) - -- system.exception_table (spec) - -- system.exception_table (body) - -- ada.io_exceptions (spec) - -- system.exceptions (spec) - -- system.storage_elements (spec) - -- system.storage_elements (body) - -- system.machine_state_operations (spec) - -- system.machine_state_operations (body) - -- system.secondary_stack (spec) - -- system.stack_checking (spec) - -- system.soft_links (spec) - -- system.soft_links (body) - -- system.stack_checking (body) - -- system.secondary_stack (body) - -- system.standard_library (body) - -- system.string_ops (spec) - -- system.string_ops (body) - -- ada.tags (spec) - -- ada.tags (body) - -- ada.streams (spec) - -- system.finalization_root (spec) - -- system.finalization_root (body) - -- system.string_ops_concat_3 (spec) - -- system.string_ops_concat_3 (body) - -- system.traceback (spec) - -- system.traceback (body) - -- ada.exceptions (body) - -- system.unsigned_types (spec) - -- system.stream_attributes (spec) - -- system.stream_attributes (body) - -- system.finalization_implementation (spec) - -- system.finalization_implementation (body) - -- ada.finalization (spec) - -- ada.finalization (body) - -- ada.finalization.list_controller (spec) - -- ada.finalization.list_controller (body) - -- system.file_control_block (spec) - -- system.file_io (spec) - -- system.file_io (body) - -- ada.text_io (spec) - -- ada.text_io (body) - -- hello (body) - -- END ELABORATION ORDER - - end ada_main; - - -- The following source file name pragmas allow the generated file - -- names to be unique for different main programs. They are needed - -- since the package name will always be Ada_Main. - - pragma Source_File_Name (ada_main, Spec_File_Name => "B~HELLO.ADS"); - pragma Source_File_Name (ada_main, Body_File_Name => "B~HELLO.ADB"); - - -- Generated package body for Ada_Main starts here - - package body ada_main is - - -- The actual finalization is performed by calling the - -- library routine in System.Standard_Library.Adafinal - - procedure Do_Finalize; - pragma Import (C, Do_Finalize, "system__standard_library__adafinal"); - - ------------- - -- adainit -- - ------------- - - procedure adainit is - - -- These booleans are set to True once the associated unit has - -- been elaborated. It is also used to avoid elaborating the - -- same unit twice. - - E040 : Boolean; pragma Import (Ada, E040, "interfaces__c_streams_E"); - E008 : Boolean; pragma Import (Ada, E008, "ada__exceptions_E"); - E014 : Boolean; pragma Import (Ada, E014, "system__exception_table_E"); - E053 : Boolean; pragma Import (Ada, E053, "ada__io_exceptions_E"); - E017 : Boolean; pragma Import (Ada, E017, "system__exceptions_E"); - E024 : Boolean; pragma Import (Ada, E024, "system__secondary_stack_E"); - E030 : Boolean; pragma Import (Ada, E030, "system__stack_checking_E"); - E028 : Boolean; pragma Import (Ada, E028, "system__soft_links_E"); - E035 : Boolean; pragma Import (Ada, E035, "ada__tags_E"); - E033 : Boolean; pragma Import (Ada, E033, "ada__streams_E"); - E046 : Boolean; pragma Import (Ada, E046, "system__finalization_root_E"); - E048 : Boolean; pragma Import (Ada, E048, "system__finalization_implementation_E"); - E044 : Boolean; pragma Import (Ada, E044, "ada__finalization_E"); - E057 : Boolean; pragma Import (Ada, E057, "ada__finalization__list_controller_E"); - E055 : Boolean; pragma Import (Ada, E055, "system__file_control_block_E"); - E042 : Boolean; pragma Import (Ada, E042, "system__file_io_E"); - E006 : Boolean; pragma Import (Ada, E006, "ada__text_io_E"); - - -- Set_Globals is a library routine that stores away the - -- value of the indicated set of global values in global - -- variables within the library. - - procedure Set_Globals - (Main_Priority : Integer; - Time_Slice_Value : Integer; - WC_Encoding : Character; - Locking_Policy : Character; - Queuing_Policy : Character; - Task_Dispatching_Policy : Character; - Adafinal : System.Address; - Unreserve_All_Interrupts : Integer; - Exception_Tracebacks : Integer); - pragma Import (C, Set_Globals, "__gnat_set_globals"); - - -- SDP_Table_Build is a library routine used to build the - -- exception tables. See unit Ada.Exceptions in files - -- A-EXCEPT.ADS/adb for full details of how zero cost - -- exception handling works. This procedure, the call to - -- it, and the two following tables are all omitted if the - -- build is in longjmp/setjump exception mode. - - procedure SDP_Table_Build - (SDP_Addresses : System.Address; - SDP_Count : Natural; - Elab_Addresses : System.Address; - Elab_Addr_Count : Natural); - pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build"); - - -- Table of Unit_Exception_Table addresses. Used for zero - -- cost exception handling to build the top level table. - - ST : aliased constant array (1 .. 23) of System.Address := ( - Hello'UET_Address, - Ada.Text_Io'UET_Address, - Ada.Exceptions'UET_Address, - Gnat.Heap_Sort_A'UET_Address, - System.Exception_Table'UET_Address, - System.Machine_State_Operations'UET_Address, - System.Secondary_Stack'UET_Address, - System.Parameters'UET_Address, - System.Soft_Links'UET_Address, - System.Stack_Checking'UET_Address, - System.Traceback'UET_Address, - Ada.Streams'UET_Address, - Ada.Tags'UET_Address, - System.String_Ops'UET_Address, - Interfaces.C_Streams'UET_Address, - System.File_Io'UET_Address, - Ada.Finalization'UET_Address, - System.Finalization_Root'UET_Address, - System.Finalization_Implementation'UET_Address, - System.String_Ops_Concat_3'UET_Address, - System.Stream_Attributes'UET_Address, - System.File_Control_Block'UET_Address, - Ada.Finalization.List_Controller'UET_Address); - - -- Table of addresses of elaboration routines. Used for - -- zero cost exception handling to make sure these - -- addresses are included in the top level procedure - -- address table. - - EA : aliased constant array (1 .. 23) of System.Address := ( - adainit'Code_Address, - Do_Finalize'Code_Address, - Ada.Exceptions'Elab_Spec'Address, - System.Exceptions'Elab_Spec'Address, - Interfaces.C_Streams'Elab_Spec'Address, - System.Exception_Table'Elab_Body'Address, - Ada.Io_Exceptions'Elab_Spec'Address, - System.Stack_Checking'Elab_Spec'Address, - System.Soft_Links'Elab_Body'Address, - System.Secondary_Stack'Elab_Body'Address, - Ada.Tags'Elab_Spec'Address, - Ada.Tags'Elab_Body'Address, - Ada.Streams'Elab_Spec'Address, - System.Finalization_Root'Elab_Spec'Address, - Ada.Exceptions'Elab_Body'Address, - System.Finalization_Implementation'Elab_Spec'Address, - System.Finalization_Implementation'Elab_Body'Address, - Ada.Finalization'Elab_Spec'Address, - Ada.Finalization.List_Controller'Elab_Spec'Address, - System.File_Control_Block'Elab_Spec'Address, - System.File_Io'Elab_Body'Address, - Ada.Text_Io'Elab_Spec'Address, - Ada.Text_Io'Elab_Body'Address); - - -- Start of processing for adainit - - begin - - -- Call SDP_Table_Build to build the top level procedure - -- table for zero cost exception handling (omitted in - -- longjmp/setjump mode). - - SDP_Table_Build (ST'Address, 23, EA'Address, 23); - - -- Call Set_Globals to record various information for - -- this partition. The values are derived by the binder - -- from information stored in the ali files by the compiler. - - Set_Globals - (Main_Priority => -1, - -- Priority of main program, -1 if no pragma Priority used - - Time_Slice_Value => -1, - -- Time slice from Time_Slice pragma, -1 if none used - - WC_Encoding => 'b', - -- Wide_Character encoding used, default is brackets - - Locking_Policy => ' ', - -- Locking_Policy used, default of space means not - -- specified, otherwise it is the first character of - -- the policy name. - - Queuing_Policy => ' ', - -- Queuing_Policy used, default of space means not - -- specified, otherwise it is the first character of - -- the policy name. - - Task_Dispatching_Policy => ' ', - -- Task_Dispatching_Policy used, default of space means - -- not specified, otherwise first character of the - -- policy name. - - Adafinal => System.Null_Address, - -- Address of Adafinal routine, not used anymore - - Unreserve_All_Interrupts => 0, - -- Set true if pragma Unreserve_All_Interrupts was used - - Exception_Tracebacks => 0); - -- Indicates if exception tracebacks are enabled - - Elab_Final_Code := 1; - - -- Now we have the elaboration calls for all units in the partition. - -- The Elab_Spec and Elab_Body attributes generate references to the - -- implicit elaboration procedures generated by the compiler for - -- each unit that requires elaboration. - - if not E040 then - Interfaces.C_Streams'Elab_Spec; - end if; - E040 := True; - if not E008 then - Ada.Exceptions'Elab_Spec; - end if; - if not E014 then - System.Exception_Table'Elab_Body; - E014 := True; - end if; - if not E053 then - Ada.Io_Exceptions'Elab_Spec; - E053 := True; - end if; - if not E017 then - System.Exceptions'Elab_Spec; - E017 := True; - end if; - if not E030 then - System.Stack_Checking'Elab_Spec; - end if; - if not E028 then - System.Soft_Links'Elab_Body; - E028 := True; - end if; - E030 := True; - if not E024 then - System.Secondary_Stack'Elab_Body; - E024 := True; - end if; - if not E035 then - Ada.Tags'Elab_Spec; - end if; - if not E035 then - Ada.Tags'Elab_Body; - E035 := True; - end if; - if not E033 then - Ada.Streams'Elab_Spec; - E033 := True; - end if; - if not E046 then - System.Finalization_Root'Elab_Spec; - end if; - E046 := True; - if not E008 then - Ada.Exceptions'Elab_Body; - E008 := True; - end if; - if not E048 then - System.Finalization_Implementation'Elab_Spec; - end if; - if not E048 then - System.Finalization_Implementation'Elab_Body; - E048 := True; - end if; - if not E044 then - Ada.Finalization'Elab_Spec; - end if; - E044 := True; - if not E057 then - Ada.Finalization.List_Controller'Elab_Spec; - end if; - E057 := True; - if not E055 then - System.File_Control_Block'Elab_Spec; - E055 := True; - end if; - if not E042 then - System.File_Io'Elab_Body; - E042 := True; - end if; - if not E006 then - Ada.Text_Io'Elab_Spec; - end if; - if not E006 then - Ada.Text_Io'Elab_Body; - E006 := True; - end if; - - Elab_Final_Code := 0; - end adainit; - - -------------- - -- adafinal -- - -------------- - - procedure adafinal is - begin - Do_Finalize; - end adafinal; - - ---------- - -- main -- - ---------- - - -- main is actually a function, as in the ANSI C standard, - -- defined to return the exit status. The three parameters - -- are the argument count, argument values and environment - -- pointer. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer - is - -- The initialize routine performs low level system - -- initialization using a standard library routine which - -- sets up signal handling and performs any other - -- required setup. The routine can be found in file - -- A-INIT.C. - - procedure initialize; - pragma Import (C, initialize, "__gnat_initialize"); - - -- The finalize routine performs low level system - -- finalization using a standard library routine. The - -- routine is found in file A-FINAL.C and in the standard - -- distribution is a dummy routine that does nothing, so - -- really this is a hook for special user finalization. - - procedure finalize; - pragma Import (C, finalize, "__gnat_finalize"); - - -- We get to the main program of the partition by using - -- pragma Import because if we try to with the unit and - -- call it Ada style, then not only do we waste time - -- recompiling it, but also, we don't really know the right - -- qualifiers (e.g. identifier character set) to be used - -- to compile it. - - procedure Ada_Main_Program; - pragma Import (Ada, Ada_Main_Program, "_ada_hello"); - - -- Start of processing for main - - begin - -- Save global variables - - gnat_argc := argc; - gnat_argv := argv; - gnat_envp := envp; - - -- Call low level system initialization - - Initialize; - - -- Call our generated Ada initialization routine - - adainit; - - -- This is the point at which we want the debugger to get - -- control - - Break_Start; - - -- Now we call the main program of the partition - - Ada_Main_Program; - - -- Perform Ada finalization - - adafinal; - - -- Perform low level system finalization - - Finalize; - - -- Return the proper exit status - return (gnat_exit_status); - end; - - -- This section is entirely comments, so it has no effect on the - -- compilation of the Ada_Main package. It provides the list of - -- object files and linker options, as well as some standard - -- libraries needed for the link. The GNAT LINK utility parses - -- this B~HELLO.ADB file to read these comment lines to generate - -- the appropriate command line arguments for the call to the - -- system linker. The BEGIN/END lines are used for sentinels for - -- this parsing operation. - - -- The exact file names will of course depend on the environment, - -- host/target and location of files on the host system. - - -- BEGIN Object file/option list - -- ./HELLO.OBJ - -- -L./ - -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/ - -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a - -- END Object file/option list - - end ada_main; - - The Ada code in the above example is exactly what is generated by the - binder. We have added comments to more clearly indicate the function of - each part of the generated `Ada_Main' package. - - The code is standard Ada in all respects, and can be processed by any - tools that handle Ada. In particular, it is possible to use the debugger - in Ada mode to debug the generated Ada_Main package. For example, - suppose that for reasons that you do not understand, your program is - blowing up during elaboration of the body of `Ada.Text_IO'. To chase - this bug down, you can place a breakpoint on the call: - - Ada.Text_Io'Elab_Body; - - and trace the elaboration routine for this package to find out where - the problem might be (more usually of course you would be debugging - elaboration code in your own application). - -  - File: gnat_ug_vms.info, Node: Generating the Binder Program in C, Next: Consistency-Checking Modes, Prev: Running GNAT BIND, Up: Binding Using GNAT BIND - - Generating the Binder Program in C - ================================== - - In most normal usage, the default mode of `GNAT BIND' which is to - generate the main package in Ada, as described in the previous section. - In particular, this means that any Ada programmer can read and - understand the generated main program. It can also be debugged just - like any other Ada code provided the `-g' qualifier is used for `GNAT - BIND' and `GNAT LINK'. - - However for some purposes it may be convenient to generate the main - program in C rather than Ada. This may for example be helpful when you - are generating a mixed language program with the main program in C. The - GNAT compiler itself is an example. The use of the `-C' qualifier for - both `GNAT BIND' and `GNAT LINK' will cause the program to be generated - in C (and compiled using the gnu C compiler). The following shows the C - code generated for the same "Hello World" program: - - - #ifdef __STDC__ - #define PARAMS(paramlist) paramlist - #else - #define PARAMS(paramlist) () - #endif - - extern void __gnat_set_globals - PARAMS ((int, int, int, int, int, int, - void (*) PARAMS ((void)), int, int)); - extern void adafinal PARAMS ((void)); - extern void adainit PARAMS ((void)); - extern void system__standard_library__adafinal PARAMS ((void)); - extern int main PARAMS ((int, char **, char **)); - extern void exit PARAMS ((int)); - extern void __gnat_break_start PARAMS ((void)); - extern void _ada_hello PARAMS ((void)); - extern void __gnat_initialize PARAMS ((void)); - extern void __gnat_finalize PARAMS ((void)); - - extern void ada__exceptions___elabs PARAMS ((void)); - extern void system__exceptions___elabs PARAMS ((void)); - extern void interfaces__c_streams___elabs PARAMS ((void)); - extern void system__exception_table___elabb PARAMS ((void)); - extern void ada__io_exceptions___elabs PARAMS ((void)); - extern void system__stack_checking___elabs PARAMS ((void)); - extern void system__soft_links___elabb PARAMS ((void)); - extern void system__secondary_stack___elabb PARAMS ((void)); - extern void ada__tags___elabs PARAMS ((void)); - extern void ada__tags___elabb PARAMS ((void)); - extern void ada__streams___elabs PARAMS ((void)); - extern void system__finalization_root___elabs PARAMS ((void)); - extern void ada__exceptions___elabb PARAMS ((void)); - extern void system__finalization_implementation___elabs PARAMS ((void)); - extern void system__finalization_implementation___elabb PARAMS ((void)); - extern void ada__finalization___elabs PARAMS ((void)); - extern void ada__finalization__list_controller___elabs PARAMS ((void)); - extern void system__file_control_block___elabs PARAMS ((void)); - extern void system__file_io___elabb PARAMS ((void)); - extern void ada__text_io___elabs PARAMS ((void)); - extern void ada__text_io___elabb PARAMS ((void)); - - extern int __gnat_inside_elab_final_code; - - extern int gnat_argc; - extern char **gnat_argv; - extern char **gnat_envp; - extern int gnat_exit_status; - - char __gnat_version[] = "GNAT Version: 3.15w (20010315)"; - void adafinal () { - system__standard_library__adafinal (); - } - - void adainit () - { - extern char ada__exceptions_E; - extern char system__exceptions_E; - extern char interfaces__c_streams_E; - extern char system__exception_table_E; - extern char ada__io_exceptions_E; - extern char system__secondary_stack_E; - extern char system__stack_checking_E; - extern char system__soft_links_E; - extern char ada__tags_E; - extern char ada__streams_E; - extern char system__finalization_root_E; - extern char system__finalization_implementation_E; - extern char ada__finalization_E; - extern char ada__finalization__list_controller_E; - extern char system__file_control_block_E; - extern char system__file_io_E; - extern char ada__text_io_E; - - extern void *__gnat_hello__SDP; - extern void *__gnat_ada__text_io__SDP; - extern void *__gnat_ada__exceptions__SDP; - extern void *__gnat_gnat__heap_sort_a__SDP; - extern void *__gnat_system__exception_table__SDP; - extern void *__gnat_system__machine_state_operations__SDP; - extern void *__gnat_system__secondary_stack__SDP; - extern void *__gnat_system__parameters__SDP; - extern void *__gnat_system__soft_links__SDP; - extern void *__gnat_system__stack_checking__SDP; - extern void *__gnat_system__traceback__SDP; - extern void *__gnat_ada__streams__SDP; - extern void *__gnat_ada__tags__SDP; - extern void *__gnat_system__string_ops__SDP; - extern void *__gnat_interfaces__c_streams__SDP; - extern void *__gnat_system__file_io__SDP; - extern void *__gnat_ada__finalization__SDP; - extern void *__gnat_system__finalization_root__SDP; - extern void *__gnat_system__finalization_implementation__SDP; - extern void *__gnat_system__string_ops_concat_3__SDP; - extern void *__gnat_system__stream_attributes__SDP; - extern void *__gnat_system__file_control_block__SDP; - extern void *__gnat_ada__finalization__list_controller__SDP; - - void **st[23] = { - &__gnat_hello__SDP, - &__gnat_ada__text_io__SDP, - &__gnat_ada__exceptions__SDP, - &__gnat_gnat__heap_sort_a__SDP, - &__gnat_system__exception_table__SDP, - &__gnat_system__machine_state_operations__SDP, - &__gnat_system__secondary_stack__SDP, - &__gnat_system__parameters__SDP, - &__gnat_system__soft_links__SDP, - &__gnat_system__stack_checking__SDP, - &__gnat_system__traceback__SDP, - &__gnat_ada__streams__SDP, - &__gnat_ada__tags__SDP, - &__gnat_system__string_ops__SDP, - &__gnat_interfaces__c_streams__SDP, - &__gnat_system__file_io__SDP, - &__gnat_ada__finalization__SDP, - &__gnat_system__finalization_root__SDP, - &__gnat_system__finalization_implementation__SDP, - &__gnat_system__string_ops_concat_3__SDP, - &__gnat_system__stream_attributes__SDP, - &__gnat_system__file_control_block__SDP, - &__gnat_ada__finalization__list_controller__SDP}; - - extern void ada__exceptions___elabs (); - extern void system__exceptions___elabs (); - extern void interfaces__c_streams___elabs (); - extern void system__exception_table___elabb (); - extern void ada__io_exceptions___elabs (); - extern void system__stack_checking___elabs (); - extern void system__soft_links___elabb (); - extern void system__secondary_stack___elabb (); - extern void ada__tags___elabs (); - extern void ada__tags___elabb (); - extern void ada__streams___elabs (); - extern void system__finalization_root___elabs (); - extern void ada__exceptions___elabb (); - extern void system__finalization_implementation___elabs (); - extern void system__finalization_implementation___elabb (); - extern void ada__finalization___elabs (); - extern void ada__finalization__list_controller___elabs (); - extern void system__file_control_block___elabs (); - extern void system__file_io___elabb (); - extern void ada__text_io___elabs (); - extern void ada__text_io___elabb (); - - void (*ea[23]) () = { - adainit, - system__standard_library__adafinal, - ada__exceptions___elabs, - system__exceptions___elabs, - interfaces__c_streams___elabs, - system__exception_table___elabb, - ada__io_exceptions___elabs, - system__stack_checking___elabs, - system__soft_links___elabb, - system__secondary_stack___elabb, - ada__tags___elabs, - ada__tags___elabb, - ada__streams___elabs, - system__finalization_root___elabs, - ada__exceptions___elabb, - system__finalization_implementation___elabs, - system__finalization_implementation___elabb, - ada__finalization___elabs, - ada__finalization__list_controller___elabs, - system__file_control_block___elabs, - system__file_io___elabb, - ada__text_io___elabs, - ada__text_io___elabb}; - - __gnat_SDP_Table_Build (&st, 23, ea, 23); - __gnat_set_globals ( - -1, /* Main_Priority */ - -1, /* Time_Slice_Value */ - 'b', /* WC_Encoding */ - ' ', /* Locking_Policy */ - ' ', /* Queuing_Policy */ - ' ', /* Tasking_Dispatching_Policy */ - 0, /* Finalization routine address, not used anymore */ - 0, /* Unreserve_All_Interrupts */ - 0); /* Exception_Tracebacks */ - - __gnat_inside_elab_final_code = 1; - - if (ada__exceptions_E == 0) { - ada__exceptions___elabs (); - } - if (system__exceptions_E == 0) { - system__exceptions___elabs (); - system__exceptions_E++; - } - if (interfaces__c_streams_E == 0) { - interfaces__c_streams___elabs (); - } - interfaces__c_streams_E = 1; - if (system__exception_table_E == 0) { - system__exception_table___elabb (); - system__exception_table_E++; - } - if (ada__io_exceptions_E == 0) { - ada__io_exceptions___elabs (); - ada__io_exceptions_E++; - } - if (system__stack_checking_E == 0) { - system__stack_checking___elabs (); - } - if (system__soft_links_E == 0) { - system__soft_links___elabb (); - system__soft_links_E++; - } - system__stack_checking_E = 1; - if (system__secondary_stack_E == 0) { - system__secondary_stack___elabb (); - system__secondary_stack_E++; - } - if (ada__tags_E == 0) { - ada__tags___elabs (); - } - if (ada__tags_E == 0) { - ada__tags___elabb (); - ada__tags_E++; - } - if (ada__streams_E == 0) { - ada__streams___elabs (); - ada__streams_E++; - } - if (system__finalization_root_E == 0) { - system__finalization_root___elabs (); - } - system__finalization_root_E = 1; - if (ada__exceptions_E == 0) { - ada__exceptions___elabb (); - ada__exceptions_E++; - } - if (system__finalization_implementation_E == 0) { - system__finalization_implementation___elabs (); - } - if (system__finalization_implementation_E == 0) { - system__finalization_implementation___elabb (); - system__finalization_implementation_E++; - } - if (ada__finalization_E == 0) { - ada__finalization___elabs (); - } - ada__finalization_E = 1; - if (ada__finalization__list_controller_E == 0) { - ada__finalization__list_controller___elabs (); - } - ada__finalization__list_controller_E = 1; - if (system__file_control_block_E == 0) { - system__file_control_block___elabs (); - system__file_control_block_E++; - } - if (system__file_io_E == 0) { - system__file_io___elabb (); - system__file_io_E++; - } - if (ada__text_io_E == 0) { - ada__text_io___elabs (); - } - if (ada__text_io_E == 0) { - ada__text_io___elabb (); - ada__text_io_E++; - } - - __gnat_inside_elab_final_code = 0; - } - int main (argc, argv, envp) - int argc; - char **argv; - char **envp; - { - gnat_argc = argc; - gnat_argv = argv; - gnat_envp = envp; - - __gnat_initialize (); - adainit (); - __gnat_break_start (); - - _ada_hello (); - - system__standard_library__adafinal (); - __gnat_finalize (); - exit (gnat_exit_status); - } - unsigned helloB = 0x7880BEB3; - unsigned system__standard_libraryB = 0x0D24CBD0; - unsigned system__standard_libraryS = 0x3283DBEB; - unsigned adaS = 0x2359F9ED; - unsigned ada__text_ioB = 0x47C85FC4; - unsigned ada__text_ioS = 0x496FE45C; - unsigned ada__exceptionsB = 0x74F50187; - unsigned ada__exceptionsS = 0x6736945B; - unsigned gnatS = 0x156A40CF; - unsigned gnat__heap_sort_aB = 0x033DABE0; - unsigned gnat__heap_sort_aS = 0x6AB38FEA; - unsigned systemS = 0x0331C6FE; - unsigned system__exceptionsS = 0x20C9ECA4; - unsigned system__exception_tableB = 0x68A22947; - unsigned system__exception_tableS = 0x394BADD5; - unsigned gnat__htableB = 0x08258E1B; - unsigned gnat__htableS = 0x367D5222; - unsigned system__machine_state_operationsB = 0x4F3B7492; - unsigned system__machine_state_operationsS = 0x182F5CF4; - unsigned system__storage_elementsB = 0x2F1EB794; - unsigned system__storage_elementsS = 0x102C83C7; - unsigned system__secondary_stackB = 0x1574B6E9; - unsigned system__secondary_stackS = 0x708E260A; - unsigned system__parametersB = 0x56D770CD; - unsigned system__parametersS = 0x237E39BE; - unsigned system__soft_linksB = 0x08AB6B2C; - unsigned system__soft_linksS = 0x1E2491F3; - unsigned system__stack_checkingB = 0x476457A0; - unsigned system__stack_checkingS = 0x5299FCED; - unsigned system__tracebackB = 0x2971EBDE; - unsigned system__tracebackS = 0x2E9C3122; - unsigned ada__streamsS = 0x7C25DE96; - unsigned ada__tagsB = 0x39ADFFA2; - unsigned ada__tagsS = 0x769A0464; - unsigned system__string_opsB = 0x5EB646AB; - unsigned system__string_opsS = 0x63CED018; - unsigned interfacesS = 0x0357E00A; - unsigned interfaces__c_streamsB = 0x3784FB72; - unsigned interfaces__c_streamsS = 0x2E723019; - unsigned system__file_ioB = 0x623358EA; - unsigned system__file_ioS = 0x31F873E6; - unsigned ada__finalizationB = 0x6843F68A; - unsigned ada__finalizationS = 0x63305874; - unsigned system__finalization_rootB = 0x31E56CE1; - unsigned system__finalization_rootS = 0x23169EF3; - unsigned system__finalization_implementationB = 0x6CCBA70E; - unsigned system__finalization_implementationS = 0x604AA587; - unsigned system__string_ops_concat_3B = 0x572E3F58; - unsigned system__string_ops_concat_3S = 0x01F57876; - unsigned system__stream_attributesB = 0x1D4F93E8; - unsigned system__stream_attributesS = 0x30B2EC3D; - unsigned ada__io_exceptionsS = 0x34054F96; - unsigned system__unsigned_typesS = 0x7B9E7FE3; - unsigned system__file_control_blockS = 0x2FF876A8; - unsigned ada__finalization__list_controllerB = 0x5760634A; - unsigned ada__finalization__list_controllerS = 0x5D851835; - - /* BEGIN ELABORATION ORDER - ada (spec) - gnat (spec) - gnat.heap_sort_a (spec) - gnat.htable (spec) - gnat.htable (body) - interfaces (spec) - system (spec) - system.parameters (spec) - system.standard_library (spec) - ada.exceptions (spec) - system.exceptions (spec) - system.parameters (body) - gnat.heap_sort_a (body) - interfaces.c_streams (spec) - interfaces.c_streams (body) - system.exception_table (spec) - system.exception_table (body) - ada.io_exceptions (spec) - system.storage_elements (spec) - system.storage_elements (body) - system.machine_state_operations (spec) - system.machine_state_operations (body) - system.secondary_stack (spec) - system.stack_checking (spec) - system.soft_links (spec) - system.soft_links (body) - system.stack_checking (body) - system.secondary_stack (body) - system.standard_library (body) - system.string_ops (spec) - system.string_ops (body) - ada.tags (spec) - ada.tags (body) - ada.streams (spec) - system.finalization_root (spec) - system.finalization_root (body) - system.string_ops_concat_3 (spec) - system.string_ops_concat_3 (body) - system.traceback (spec) - system.traceback (body) - ada.exceptions (body) - system.unsigned_types (spec) - system.stream_attributes (spec) - system.stream_attributes (body) - system.finalization_implementation (spec) - system.finalization_implementation (body) - ada.finalization (spec) - ada.finalization (body) - ada.finalization.list_controller (spec) - ada.finalization.list_controller (body) - system.file_control_block (spec) - system.file_io (spec) - system.file_io (body) - ada.text_io (spec) - ada.text_io (body) - hello (body) - END ELABORATION ORDER */ - - /* BEGIN Object file/option list - ./HELLO.OBJ - -L./ - -L/usr/local/gnat/lib/gcc-lib/alpha-dec-osf5.1/2.8.1/adalib/ - /usr/local/gnat/lib/gcc-lib/alpha-dec-osf5.1/2.8.1/adalib/libgnat.a - -lexc - END Object file/option list */ - - Here again, the C code is exactly what is generated by the binder. The - functions of the various parts of this code correspond in an obvious - manner with the commented Ada code shown in the example in the previous - section. - -  - File: gnat_ug_vms.info, Node: Consistency-Checking Modes, Next: Binder Error Message Control, Prev: Generating the Binder Program in C, Up: Binding Using GNAT BIND - - Consistency-Checking Modes - ========================== - - As described in the previous section, by default `GNAT BIND' checks - that object files are consistent with one another and are consistent - with any source files it can locate. The following qualifiers control - binder access to sources. - - `/READ_SOURCES=ALL' - Require source files to be present. In this mode, the binder must - be able to locate all source files that are referenced, in order - to check their consistency. In normal mode, if a source file - cannot be located it is simply ignored. If you specify this - qualifier, a missing source file is an error. - - `/READ_SOURCES=NONE' - Exclude source files. In this mode, the binder only checks that ALI - files are consistent with one another. Source files are not - accessed. The binder runs faster in this mode, and there is still - a guarantee that the resulting program is self-consistent. If a - source file has been edited since it was last compiled, and you - specify this qualifier, the binder will not detect that the object - file is out of date with respect to the source file. Note that - this is the mode that is automatically used by `GNAT MAKE' because - in this case the checking against sources has already been - performed by `GNAT MAKE' in the course of compilation (i.e. before - binding). - - `/READ_SOURCES=AVAILABLE' - This is the default mode in which source files are checked if they - are available, and ignored if they are not available. - -  - File: gnat_ug_vms.info, Node: Binder Error Message Control, Next: Elaboration Control, Prev: Consistency-Checking Modes, Up: Binding Using GNAT BIND - - Binder Error Message Control - ============================ - - The following qualifiers provide control over the generation of error - messages from the binder: - - `/REPORT_ERRORS=VERBOSE' - Verbose mode. In the normal mode, brief error messages are - generated to `SYS$ERROR'. If this qualifier is present, a header - is written to `SYS$OUTPUT' and any error messages are directed to - `SYS$OUTPUT'. All that is written to `SYS$ERROR' is a brief - summary message. - - `/REPORT_ERRORS=BRIEF' - Generate brief error messages to `SYS$ERROR' even if verbose mode - is specified. This is relevant only when used with the - `/REPORT_ERRORS=VERBOSE' qualifier. - - `/WARNINGS=SUPPRESS' - Suppress all warning messages. - - `/WARNINGS=ERROR' - Treat any warning messages as fatal errors. - - `/WARNINGS=NORMAL' - Standard mode with warnings generated, but warnings do not get - treated as errors. - - `/NOTIME_STAMP_CHECK' - The binder performs a number of consistency checks including: - - * Check that time stamps of a given source unit are consistent - - * Check that checksums of a given source unit are consistent - - * Check that consistent versions of `GNAT' were used for - compilation - - * Check consistency of configuration pragmas as required - - Normally failure of such checks, in accordance with the consistency - requirements of the Ada Reference Manual, causes error messages to - be generated which abort the binder and prevent the output of a - binder file and subsequent link to obtain an executable. - - The `/NOTIME_STAMP_CHECK' qualifier converts these error messages - into warnings, so that binding and linking can continue to - completion even in the presence of such errors. The result may be - a failed link (due to missing symbols), or a non-functional - executable which has undefined semantics. _This means that - `/NOTIME_STAMP_CHECK' should be used only in unusual situations, - with extreme care._ - -  - File: gnat_ug_vms.info, Node: Elaboration Control, Next: Output Control, Prev: Binder Error Message Control, Up: Binding Using GNAT BIND - - Elaboration Control - =================== - - The following qualifiers provide additional control over the elaboration - order. For full details see *Note Elaboration Order Handling in GNAT::. - - `/PESSIMISTIC_ELABORATION' - Normally the binder attempts to choose an elaboration order that is - likely to minimize the likelihood of an elaboration order error - resulting in raising a `Program_Error' exception. This qualifier - reverses the action of the binder, and requests that it - deliberately choose an order that is likely to maximize the - likelihood of an elaboration error. This is useful in ensuring - portability and avoiding dependence on accidental fortuitous - elaboration ordering. - - Normally it only makes sense to use the `-p' qualifier if dynamic - elaboration checking is used (`/CHECKS=ELABORATION' qualifier used - for compilation). This is because in the default static - elaboration mode, all necessary `Elaborate_All' pragmas are - implicitly inserted. These implicit pragmas are still respected by - the binder in `-p' mode, so a safe elaboration order is assured. - -  - File: gnat_ug_vms.info, Node: Output Control, Next: Binding with Non-Ada Main Programs, Prev: Elaboration Control, Up: Binding Using GNAT BIND - - Output Control - ============== - - The following qualifiers allow additional control over the output - generated by the binder. - - `/BIND_FILE=ADA' - Generate binder program in Ada (default). The binder program is - named `B$MAINPROG.ADB' by default. This can be changed with `-o' - `GNAT BIND' option. - - `/NOOUTPUT' - Check only. Do not generate the binder output file. In this mode - the binder performs all error checks but does not generate an - output file. - - `/BIND_FILE=C' - Generate binder program in C. The binder program is named - `B_MAINPROG.C'. This can be changed with `-o' `GNAT BIND' option. - - `/ELABORATION_DEPENDENCIES' - Output complete list of elaboration-order dependencies, showing the - reason for each dependency. This output can be rather extensive - but may be useful in diagnosing problems with elaboration order. - The output is written to `SYS$OUTPUT'. - - `/HELP' - Output usage information. The output is written to `SYS$OUTPUT'. - - `/LINKER_OPTION_LIST' - Output linker options to `SYS$OUTPUT'. Includes library search - paths, contents of pragmas Ident and Linker_Options, and libraries - added by `GNAT BIND'. - - `/ORDER_OF_ELABORATION' - Output chosen elaboration order. The output is written to - `SYS$OUTPUT'. - - `/OBJECT_LIST' - Output full names of all the object files that must be linked to - provide the Ada component of the program. The output is written to - `SYS$OUTPUT'. This list includes the files explicitly supplied - and referenced by the user as well as implicitly referenced - run-time unit files. The latter are omitted if the corresponding - units reside in shared libraries. The directory names for the - run-time units depend on the system configuration. - - `/OUTPUT=FILE' - Set name of output file to FILE instead of the normal - `B$MAINPROG.ADB' default. Note that FILE denote the Ada binder - generated body filename. In C mode you would normally give FILE an - extension of `.C' because it will be a C source program. Note - that if this option is used, then linking must be done manually. - It is not possible to use GNAT LINK in this case, since it cannot - locate the binder file. - - `/RESTRICTION_LIST' - Generate list of `pragma Rerstrictions' that could be applied to - the current unit. This is useful for code audit purposes, and also - may be used to improve code generation in some cases. - -  - File: gnat_ug_vms.info, Node: Binding with Non-Ada Main Programs, Next: Binding Programs with No Main Subprogram, Prev: Output Control, Up: Binding Using GNAT BIND - - Binding with Non-Ada Main Programs - ================================== - - In our description so far we have assumed that the main program is in - Ada, and that the task of the binder is to generate a corresponding - function `main' that invokes this Ada main program. GNAT also supports - the building of executable programs where the main program is not in - Ada, but some of the called routines are written in Ada and compiled - using GNAT (*note Mixed Language Programming::). The following - qualifier is used in this situation: - - `/NOMAIN' - No main program. The main program is not in Ada. - - In this case, most of the functions of the binder are still required, - but instead of generating a main program, the binder generates a file - containing the following callable routines: - - `adainit' - You must call this routine to initialize the Ada part of the - program by calling the necessary elaboration routines. A call to - `adainit' is required before the first call to an Ada subprogram. - - Note that it is assumed that the basic execution environment must - be setup to be appropriate for Ada execution at the point where - the first Ada subprogram is called. In particular, if the Ada code - will do any floating-point operations, then the FPU must be setup - in an appropriate manner. For the case of the x86, for example, - full precision mode is required. The procedure - GNAT.Float_Control.Reset may be used to ensure that the FPU is in - the right state. - - `adafinal' - You must call this routine to perform any library-level - finalization required by the Ada subprograms. A call to `adafinal' - is required after the last call to an Ada subprogram, and before - the program terminates. - - If the `/NOMAIN' qualifier is given, more than one ALI file may appear - on the command line for `GNAT BIND'. The normal "closure" calculation - is performed for each of the specified units. Calculating the closure - means finding out the set of units involved by tracing `with' - references. The reason it is necessary to be able to specify more than - one ALI file is that a given program may invoke two or more quite - separate groups of Ada units. - - The binder takes the name of its output file from the last specified - ALI file, unless overridden by the use of the `/OUTPUT=file'. The - output is an Ada unit in source form that can be compiled with GNAT - unless the -C qualifier is used in which case the output is a C source - file, which must be compiled using the C compiler. This compilation - occurs automatically as part of the `GNAT LINK' processing. - - Currently the GNAT run time requires a FPU using 80 bits mode - precision. Under targets where this is not the default it is required to - call GNAT.Float_Control.Reset before using floating point numbers (this - include float computation, float input and output) in the Ada code. A - side effect is that this could be the wrong mode for the foreign code - where floating point computation could be broken after this call. - -  - File: gnat_ug_vms.info, Node: Binding Programs with No Main Subprogram, Next: Summary of Binder Qualifiers, Prev: Binding with Non-Ada Main Programs, Up: Binding Using GNAT BIND - - Binding Programs with No Main Subprogram - ======================================== - - It is possible to have an Ada program which does not have a main - subprogram. This program will call the elaboration routines of all the - packages, then the finalization routines. - - The following qualifier is used to bind programs organized in this - manner: - - `/ZERO_MAIN' - Normally the binder checks that the unit name given on the command - line corresponds to a suitable main subprogram. When this - qualifier is used, a list of ALI files can be given, and the - execution of the program consists of elaboration of these units in - an appropriate order. - -  - File: gnat_ug_vms.info, Node: Summary of Binder Qualifiers, Next: Command-Line Access, Prev: Binding Programs with No Main Subprogram, Up: Binding Using GNAT BIND - - Summary of Binder Qualifiers - ============================ - - The following are the qualifiers available with `GNAT BIND': - - `/OBJECT_SEARCH' - Specify directory to be searched for ALI files. - - `/SOURCE_SEARCH' - Specify directory to be searched for source file. - - `/BIND_FILE=ADA' - Generate binder program in Ada (default) - - `/REPORT_ERRORS=BRIEF' - Generate brief messages to `SYS$ERROR' even if verbose mode set. - - `/NOOUTPUT' - Check only, no generation of binder output file. - - `/BIND_FILE=C' - Generate binder program in C - - `/ELABORATION_DEPENDENCIES' - Output complete list of elaboration-order dependencies. - - `-E' - Store tracebacks in exception occurrences when the target supports - it. This is the default with the zero cost exception mechanism. - This option is currently supported on the following targets: all - x86 ports, Solaris, Windows, HP-UX, AIX, PowerPC VxWorks and Alpha - VxWorks. See also the packages `GNAT.Traceback' and - `GNAT.Traceback.Symbolic' for more information. Note that on x86 - ports, you must not use `-fomit-frame-pointer' `GNAT COMPILE' - option. - - `-h' - Output usage (help) information - - `/SEARCH' - Specify directory to be searched for source and ALI files. - - `/NOCURRENT_DIRECTORY' - Do not look for sources in the current directory where `GNAT BIND' - was invoked, and do not look for ALI files in the directory - containing the ALI file named in the `GNAT BIND' command line. - - `/ORDER_OF_ELABORATION' - Output chosen elaboration order. - - `-Lxxx' - Binds the units for library building. In this case the adainit and - adafinal procedures (See *note Binding with Non-Ada Main - Programs::) are renamed to xxxinit and xxxfinal. Implies -n. - - `-Mxyz' - Rename generated main program from main to xyz - - `/ERROR_LIMIT=N' - Limit number of detected errors to N (1-999). - - `/NOMAIN' - No main program. - - `/NOSTD_INCLUDES' - Do not look for sources in the system default directory. - - `/NOSTD_LIBRARIES' - Do not look for library files in the system default directory. - - `/RUNTIME_SYSTEM=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `GNAT MAKE' flag (see *Note Qualifiers - for GNAT MAKE::). - - `/OUTPUT=FILE' - Name the output file FILE (default is `B$XXX.ADB'). Note that if - this option is used, then linking must be done manually, GNAT LINK - cannot be used. - - `/OBJECT_LIST' - Output object list. - - `-p' - Pessimistic (worst-case) elaboration order - - `/READ_SOURCES=ALL' - Require all source files to be present. - - `/NOTIME_STAMP_CHECK' - Tolerate time stamp and other consistency errors - - `-TN' - Set the time slice value to n microseconds. A value of zero means - no time slicing and also indicates to the tasking run time to - match as close as possible to the annex D requirements of the RM. - - `/REPORT_ERRORS=VERBOSE' - Verbose mode. Write error messages, header, summary output to - `SYS$OUTPUT'. - - `/WARNINGS=NORMAL' - Normal warnings mode. Warnings are issued but ignored - - `/WARNINGS=SUPPRESS' - All warning messages are suppressed - - `/WARNINGS=ERROR' - Warning messages are treated as fatal errors - - `/READ_SOURCES=NONE' - Exclude source files (check object consistency only). - - `/READ_SOURCES=AVAILABLE' - Default mode, in which sources are checked for consistency only if - they are available. - - `/ZERO_MAIN' - No main subprogram. - -  - File: gnat_ug_vms.info, Node: Command-Line Access, Next: Search Paths for GNAT BIND, Prev: Summary of Binder Qualifiers, Up: Binding Using GNAT BIND - - Command-Line Access - =================== - - The package `Ada.Command_Line' provides access to the command-line - arguments and program name. In order for this interface to operate - correctly, the two variables - - int gnat_argc; - char **gnat_argv; - - are declared in one of the GNAT library routines. These variables must - be set from the actual `argc' and `argv' values passed to the main - program. With no `/NOMAIN' present, `GNAT BIND' generates the C main - program to automatically set these variables. If the `/NOMAIN' - qualifier is used, there is no automatic way to set these variables. If - they are not set, the procedures in `Ada.Command_Line' will not be - available, and any attempt to use them will raise `Constraint_Error'. - If command line access is required, your main program must set - `gnat_argc' and `gnat_argv' from the `argc' and `argv' values passed to - it. - -  - File: gnat_ug_vms.info, Node: Search Paths for GNAT BIND, Next: Examples of GNAT BIND Usage, Prev: Command-Line Access, Up: Binding Using GNAT BIND - - Search Paths for `GNAT BIND' - ============================ - - The binder takes the name of an ALI file as its argument and needs to - locate source files as well as other ALI files to verify object - consistency. - - For source files, it follows exactly the same search rules as `GNAT - COMPILE' (*note Search Paths and the Run-Time Library (RTL)::). For ALI - files the directories searched are: - - 1. The directory containing the ALI file named in the command line, - unless the qualifier `/NOCURRENT_DIRECTORY' is specified. - - 2. All directories specified by `/SEARCH' qualifiers on the `GNAT - BIND' command line, in the order given. - - 3. Each of the directories listed in the value of the - `ADA_OBJECTS_PATH' logical name. Normally, define this value as a - logical name containing a comma separated list of directory names. - - This variable can also be defined by means of an environment string - (an argument to the DEC C exec* set of functions). - - Logical Name: - DEFINE ANOTHER_PATH FOO:[BAG] - DEFINE ADA_OBJECTS_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR] - - By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] - first, followed by the standard Ada 95 libraries in - GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB]. If this is not redefined, the - user will obtain the DEC Ada83 IO packages (Text_IO, - Sequential_IO, etc) instead of the Ada95 packages. Thus, in order - to get the Ada 95 packages by default, ADA_OBJECTS_PATH must be - redefined. - - 4. The content of the "ada_object_path" file which is part of the GNAT - installation tree and is used to store standard libraries such as - the GNAT Run Time Library (RTL) unless the qualifier - `/NOSTD_LIBRARIES' is specified. - - In the binder the qualifier `/SEARCH' is used to specify both source and - library file paths. Use `/SOURCE_SEARCH' instead if you want to specify - source paths only, and `/LIBRARY_SEARCH' if you want to specify library - paths only. This means that for the binder `/SEARCH='DIR is equivalent - to `/SOURCE_SEARCH='DIR `/OBJECT_SEARCH='DIR. The binder generates the - bind file (a C language source file) in the current working directory. - - The packages `Ada', `System', and `Interfaces' and their children - make up the GNAT Run-Time Library, together with the package GNAT and - its children, which contain a set of useful additional library - functions provided by GNAT. The sources for these units are needed by - the compiler and are kept together in one directory. The ALI files and - object files generated by compiling the RTL are needed by the binder - and the linker and are kept together in one directory, typically - different from the directory containing the sources. In a normal - installation, you need not specify these directory names when compiling - or binding. Either the environment variables or the built-in defaults - cause these files to be found. - - Besides simplifying access to the RTL, a major use of search paths is - in compiling sources from multiple directories. This can make - development environments much more flexible. - -  - File: gnat_ug_vms.info, Node: Examples of GNAT BIND Usage, Prev: Search Paths for GNAT BIND, Up: Binding Using GNAT BIND - - Examples of `GNAT BIND' Usage - ============================= - - This section contains a number of examples of using the GNAT binding - utility `GNAT BIND'. - - `GNAT BIND hello' - The main program `Hello' (source program in `HELLO.ADB') is bound - using the standard qualifier settings. The generated main program - is `B~HELLO.ADB'. This is the normal, default use of the binder. - - `GNAT BIND HELLO.ALI /OUTPUT=Mainprog.ADB' - The main program `Hello' (source program in `HELLO.ADB') is bound - using the standard qualifier settings. The generated main program - is `MAINPROG.ADB' with the associated spec in `MAINPROG.ADS'. Note - that you must specify the body here not the spec, in the case - where the output is in Ada. Note that if this option is used, then - linking must be done manually, since GNAT LINK will not be able to - find the generated file. - - `GNAT BIND MAIN.ALI /BIND_FILE=C /OUTPUT=Mainprog.C /READ_SOURCES=NONE' - The main program `Main' (source program in `MAIN.ADB') is bound, - excluding source files from the consistency checking, generating - the file `MAINPROG.C'. - - `GNAT BIND /NOMAIN math dbase /BIND_FILE=C /OUTPUT=ADA-CONTROL.C' - The main program is in a language other than Ada, but calls to - subprograms in packages `Math' and `Dbase' appear. This call to - `GNAT BIND' generates the file `ADA-CONTROL.C' containing the - `adainit' and `adafinal' routines to be called before and after - accessing the Ada units. - -  - File: gnat_ug_vms.info, Node: Linking Using GNAT LINK, Next: The GNAT Make Program GNAT MAKE, Prev: Binding Using GNAT BIND, Up: Top - - Linking Using `GNAT LINK' - ************************* - - This chapter discusses `GNAT LINK', a utility program used to link Ada - programs and build an executable file. This is a simple program that - invokes the Unix linker (via the `GNAT COMPILE' command) with a correct - list of object files and library references. `GNAT LINK' automatically - determines the list of files and references for the Ada part of a - program. It uses the binder file generated by the binder to determine - this list. - - * Menu: - - * Running GNAT LINK:: - * Qualifiers for GNAT LINK:: - * Setting Stack Size from GNAT LINK:: - * Setting Heap Size from GNAT LINK:: - -  - File: gnat_ug_vms.info, Node: Running GNAT LINK, Next: Qualifiers for GNAT LINK, Up: Linking Using GNAT LINK - - Running `GNAT LINK' - =================== - - The form of the `GNAT LINK' command is - - $ GNAT LINK [QUALIFIERS] MAINPROG[.ALI] [NON-ADA OBJECTS] - [LINKER OPTIONS] - - `MAINPROG.ALI' references the ALI file of the main program. The `.ALI' - extension of this file can be omitted. From this reference, `GNAT LINK' - locates the corresponding binder file `B$MAINPROG.ADB' and, using the - information in this file along with the list of non-Ada objects and - linker options, constructs a Unix linker command file to create the - executable. - - The arguments following `MAINPROG.ALI' are passed to the linker - uninterpreted. They typically include the names of object files for - units written in other languages than Ada and any library references - required to resolve references in any of these foreign language units, - or in `pragma Import' statements in any Ada units. - - LINKER OPTIONS is an optional list of linker specific qualifiers. - The default linker called by GNAT LINK is GNAT COMPILE which in turn - calls the appropriate system linker usually called LD. Standard options - for the linker such as `-lmy_lib' or `-Ldir' can be added as is. For - options that are not recognized by GNAT COMPILE as linker options, the - GNAT COMPILE qualifiers `-Xlinker' or `-Wl,' shall be used. Refer to - the GCC documentation for details. Here is an example showing how to - generate a linker map assuming that the underlying linker is GNU ld: - - $ GNAT LINK my_prog -Wl,-Map,MAPFILE - - Using LINKER OPTIONS it is possible to set the program stack and - heap size. See *note Setting Stack Size from GNAT LINK:: and *note - Setting Heap Size from GNAT LINK::. - - `GNAT LINK' determines the list of objects required by the Ada - program and prepends them to the list of objects passed to the linker. - `GNAT LINK' also gathers any arguments set by the use of `pragma - Linker_Options' and adds them to the list of arguments presented to the - linker. - - `GNAT LINK' accepts the following types of extra files on the command - line: objects (.OBJ), libraries (.OLB), shareable images (.EXE), and - options files (.OPT). These are recognized and handled according to - their extension. - -  - File: gnat_ug_vms.info, Node: Qualifiers for GNAT LINK, Next: Setting Stack Size from GNAT LINK, Prev: Running GNAT LINK, Up: Linking Using GNAT LINK - - Qualifiers for `GNAT LINK' - ========================== - - The following qualifiers are available with the `GNAT LINK' utility: - - `/BIND_FILE=ADA' - The binder has generated code in Ada. This is the default. - - `/BIND_FILE=C' - If instead of generating a file in Ada, the binder has generated - one in C, then the linker needs to know about it. Use this - qualifier to signal to `GNAT LINK' that the binder has generated C - code rather than Ada code. - - `-f' - On some targets, the command line length is limited, and `GNAT - LINK' will generate a separate file for the linker if the list of - object files is too long. The `-f' flag forces this file to be - generated even if the limit is not exceeded. This is useful in - some cases to deal with special situations where the command line - length is exceeded. - - `/DEBUG' - The option to include debugging information causes the Ada bind - file (in other words, `B$MAINPROG.ADB') to be compiled with - `/DEBUG'. In addition, the binder does not delete the - `B$MAINPROG.ADB', `B$MAINPROG.OBJ' and `B$MAINPROG.ALI' files. - Without `/DEBUG', the binder removes these files by default. The - same procedure apply if a C bind file was generated using - `/BIND_FILE=C' `GNAT BIND' option, in this case the filenames are - `B_MAINPROG.C' and `B_MAINPROG.OBJ'. - - `/VERBOSE' - Causes additional information to be output, including a full list - of the included object files. This qualifier option is most useful - when you want to see what set of object files are being used in - the link step. - - `/EXECUTABLE=EXEC-NAME' - EXEC-NAME specifies an alternate name for the generated executable - program. If this qualifier is omitted, the executable has the same - name as the main unit. For example, `GNAT LINK TRY.ALI' creates an - executable called `TRY.EXE'. - - `/DEBUG=TRACEBACK' - This qualifier causes sufficient information to be included in the - executable file to allow a traceback, but does not include the full - symbol information needed by the debugger. - - `/IDENTIFICATION=""' - "" specifies the string to be stored in the image file - identification field in the image header. It overrides any pragma - Ident specified string. - - `/NOINHIBIT-EXEC' - Generate the executable file even if there are linker warnings. - - `/NOSTART_FILES' - Don't link in the object file containing the "main" transfer - address. Used when linking with a foreign language main program - compiled with a Digital compiler. - - `/STATIC' - Prefer linking with object libraries over shareable images, even - without /DEBUG. - -  - File: gnat_ug_vms.info, Node: Setting Stack Size from GNAT LINK, Next: Setting Heap Size from GNAT LINK, Prev: Qualifiers for GNAT LINK, Up: Linking Using GNAT LINK - - Setting Stack Size from `GNAT LINK' - =================================== - - It is possible to specify the program stack size from `GNAT LINK'. - Assuming that the underlying linker is GNU ld there is two ways to do - so: - - * using `-Xlinker' linker option - - $ GNAT LINK hello -Xlinker --stack=0x10000,0x1000 - - This set the stack reserve size to 0x10000 bytes and the stack - commit size to 0x1000 bytes. - - * using `-Wl' linker option - - $ GNAT LINK hello -Wl,--stack=0x1000000 - - This set the stack reserve size to 0x1000000 bytes. Note that with - `-Wl' option it is not possible to set the stack commit size - because the coma is a separator for this option. - - -  - File: gnat_ug_vms.info, Node: Setting Heap Size from GNAT LINK, Prev: Setting Stack Size from GNAT LINK, Up: Linking Using GNAT LINK - - Setting Heap Size from `GNAT LINK' - ================================== - - It is possible to specify the program heap size from `GNAT LINK'. - Assuming that the underlying linker is GNU ld there is two ways to do - so: - - * using `-Xlinker' linker option - - $ GNAT LINK hello -Xlinker --heap=0x10000,0x1000 - - This set the heap reserve size to 0x10000 bytes and the heap commit - size to 0x1000 bytes. - - * using `-Wl' linker option - - $ GNAT LINK hello -Wl,--heap=0x1000000 - - This set the heap reserve size to 0x1000000 bytes. Note that with - `-Wl' option it is not possible to set the heap commit size - because the coma is a separator for this option. - - -  - File: gnat_ug_vms.info, Node: The GNAT Make Program GNAT MAKE, Next: Renaming Files Using GNAT CHOP, Prev: Linking Using GNAT LINK, Up: Top - - The GNAT Make Program `GNAT MAKE' - ********************************* - - * Menu: - - * Running GNAT MAKE:: - * Qualifiers for GNAT MAKE:: - * Mode Qualifiers for GNAT MAKE:: - * Notes on the Command Line:: - * How GNAT MAKE Works:: - * Examples of GNAT MAKE Usage:: - - A typical development cycle when working on an Ada program consists of - the following steps: - - 1. Edit some sources to fix bugs. - - 2. Add enhancements. - - 3. Compile all sources affected. - - 4. Rebind and relink. - - 5. Test. - - The third step can be tricky, because not only do the modified files - have to be compiled, but any files depending on these files must also be - recompiled. The dependency rules in Ada can be quite complex, especially - in the presence of overloading, `use' clauses, generics and inlined - subprograms. - - `GNAT MAKE' automatically takes care of the third and fourth steps - of this process. It determines which sources need to be compiled, - compiles them, and binds and links the resulting object files. - - Unlike some other Ada make programs, the dependencies are always - accurately recomputed from the new sources. The source based approach of - the GNAT compilation model makes this possible. This means that if - changes to the source program cause corresponding changes in - dependencies, they will always be tracked exactly correctly by `GNAT - MAKE'. - -  - File: gnat_ug_vms.info, Node: Running GNAT MAKE, Next: Qualifiers for GNAT MAKE, Up: The GNAT Make Program GNAT MAKE - - Running `GNAT MAKE' - =================== - - The usual form of the `GNAT MAKE' command is - - $ GNAT MAKE [QUALIFIERS] FILE_NAME [FILE_NAMES] [MODE_QUALIFIERS] - - The only required argument is one FILE_NAME, which specifies a - compilation unit that is a main program. Several FILE_NAMES can be - specified: this will result in several executables being built. If - `qualifiers' are present, they can be placed before the first - FILE_NAME, between FILE_NAMES or after the last FILE_NAME. If - MODE_QUALIFIERS are present, they must always be placed after the last - FILE_NAME and all `qualifiers'. - - If you are using standard file extensions (.ADB and .ADS), then the - extension may be omitted from the FILE_NAME arguments. However, if you - are using non-standard extensions, then it is required that the - extension be given. A relative or absolute directory path can be - specified in a FILE_NAME, in which case, the input source file will be - searched for in the specified directory only. Otherwise, the input - source file will first be searched in the directory where `GNAT MAKE' - was invoked and if it is not found, it will be search on the source - path of the compiler as described in *Note Search Paths and the - Run-Time Library (RTL)::. - - When several FILE_NAMES are specified, if an executable needs to be - rebuilt and relinked, all subsequent executables will be rebuilt and - relinked, even if this would not be absolutely necessary. - - All `GNAT MAKE' output (except when you specify - `/DEPENDENCIES_LIST') is to `SYS$ERROR'. The output produced by the - `/DEPENDENCIES_LIST' qualifier is send to `SYS$OUTPUT'. - -  - File: gnat_ug_vms.info, Node: Qualifiers for GNAT MAKE, Next: Mode Qualifiers for GNAT MAKE, Prev: Running GNAT MAKE, Up: The GNAT Make Program GNAT MAKE - - Qualifiers for `GNAT MAKE' - ========================== - - You may specify any of the following qualifiers to `GNAT MAKE': - - `/ALL_FILES' - Consider all files in the make process, even the GNAT internal - system files (for example, the predefined Ada library files), as - well as any locked files. Locked files are files whose ALI file is - write-protected. By default, `GNAT MAKE' does not check these - files, because the assumption is that the GNAT internal files are - properly up to date, and also that any write protected ALI files - have been properly installed. Note that if there is an - installation problem, such that one of these files is not up to - date, it will be properly caught by the binder. You may have to - specify this qualifier if you are working on GNAT itself. - `/ALL_FILES' is also useful in conjunction with `/FORCE_COMPILE' - if you need to recompile an entire application, including run-time - files, using special configuration pragma settings, such as a - non-standard `Float_Representation' pragma. By default `GNAT MAKE - /ALL_FILES' compiles all GNAT internal files with the - `/CHECKS=SUPPRESS_ALL /STYLE_CHECKS=GNAT' qualifier. - - `/ACTIONS=BIND' - Bind only. Can be combined with `/ACTIONS=COMPILE' to do - compilation and binding, but no link. Can be combined with - `/ACTIONS=LINK' to do binding and linking. When not combined with - `/ACTIONS=COMPILE' all the units in the closure of the main - program must have been previously compiled and must be up to date. - The root unit specified by FILE_NAME may be given without - extension, with the source extension or, if no GNAT Project File - is specified, with the ALI file extension. - - `/ACTIONS=COMPILE' - Compile only. Do not perform binding, except when `/ACTIONS=BIND' - is also specified. Do not perform linking, except if both - `/ACTIONS=BIND' and `/ACTIONS=LINK' are also specified. If the - root unit specified by FILE_NAME is not a main unit, this is the - default. Otherwise `GNAT MAKE' will attempt binding and linking - unless all objects are up to date and the executable is more - recent than the objects. - - `/MAPPING' - Use a mapping file. A mapping file is a way to communicate to the - compiler two mappings: from unit names to file names (without any - directory information) and from file names to path names (with - full directory information). These mappings are used by the - compiler to short-circuit the path search. When `GNAT MAKE' is - invoked with this qualifier, it will create a mapping file, - initially populated by the project manager, if `-P' is used, - otherwise initially empty. Each invocation of the compiler will - add the newly accessed sources to the mapping file. This will - improve the source search during the next invocation of the - compiler. - - `/FORCE_COMPILE' - Force recompilations. Recompile all sources, even though some - object files may be up to date, but don't recompile predefined or - GNAT internal files or locked files (files with a write-protected - ALI file), unless the `/ALL_FILES' qualifier is also specified. - - `' - - `/IN_PLACE' - In normal mode, `GNAT MAKE' compiles all object files and ALI files - into the current directory. If the `/IN_PLACE' qualifier is used, - then instead object files and ALI files that already exist are - overwritten in place. This means that once a large project is - organized into separate directories in the desired manner, then - `GNAT MAKE' will automatically maintain and update this - organization. If no ALI files are found on the Ada object path - (*Note Search Paths and the Run-Time Library (RTL)::), the new - object and ALI files are created in the directory containing the - source being compiled. If another organization is desired, where - objects and sources are kept in different directories, a useful - technique is to create dummy ALI files in the desired directories. - When detecting such a dummy file, `GNAT MAKE' will be forced to - recompile the corresponding source file, and it will be put the - resulting object and ALI files in the directory where it found the - dummy file. - - `/PROCESSES=N' - Use N processes to carry out the (re)compilations. On a - multiprocessor machine compilations will occur in parallel. In the - event of compilation errors, messages from various compilations - might get interspersed (but `GNAT MAKE' will give you the full - ordered list of failing compiles at the end). If this is - problematic, rerun the make process with n set to 1 to get a clean - list of messages. - - `/CONTINUE_ON_ERROR' - Keep going. Continue as much as possible after a compilation - error. To ease the programmer's task in case of compilation - errors, the list of sources for which the compile fails is given - when `GNAT MAKE' terminates. - - If `GNAT MAKE' is invoked with several `file_names' and with this - qualifier, if there are compilation errors when building an - executable, `GNAT MAKE' will not attempt to build the following - executables. - - `/ACTIONS=LINK' - Link only. Can be combined with `/ACTIONS=BIND' to binding and - linking. Linking will not be performed if combined with - `/ACTIONS=COMPILE' but not with `/ACTIONS=BIND'. When not - combined with `/ACTIONS=BIND' all the units in the closure of the - main program must have been previously compiled and must be up to - date, and the main program need to have been bound. The root unit - specified by FILE_NAME may be given without extension, with the - source extension or, if no GNAT Project File is specified, with - the ALI file extension. - - `/MINIMAL_RECOMPILATION' - Specifies that the minimum necessary amount of recompilations be - performed. In this mode `GNAT MAKE' ignores time stamp differences - when the only modifications to a source file consist in - adding/removing comments, empty lines, spaces or tabs. This means - that if you have changed the comments in a source file or have - simply reformatted it, using this qualifier will tell GNAT MAKE - not to recompile files that depend on it (provided other sources - on which these files depend have undergone no semantic - modifications). Note that the debugging information may be out of - date with respect to the sources if the `-m' qualifier causes a - compilation to be switched, so the use of this qualifier - represents a trade-off between compilation time and accurate - debugging information. - - `/DEPENDENCIES_LIST' - Check if all objects are up to date. If they are, output the object - dependences to `SYS$OUTPUT' in a form that can be directly - exploited in a `Makefile'. By default, each source file is - prefixed with its (relative or absolute) directory name. This name - is whatever you specified in the various `/SOURCE_SEARCH' and - `/SEARCH' qualifiers. If you use `GNAT MAKE /DEPENDENCIES_LIST' - `/QUIET' (see below), only the source file names, without relative - paths, are output. If you just specify the `/DEPENDENCIES_LIST' - qualifier, dependencies of the GNAT internal system files are - omitted. This is typically what you want. If you also specify the - `/ALL_FILES' qualifier, dependencies of the GNAT internal files - are also listed. Note that dependencies of the objects in external - Ada libraries (see qualifier `/SKIP_MISSING='DIR in the following - list) are never reported. - - `/DO_OBJECT_CHECK' - Don't compile, bind, or link. Checks if all objects are up to date. - If they are not, the full name of the first file that needs to be - recompiled is printed. Repeated use of this option, followed by - compiling the indicated source file, will eventually result in - recompiling all required units. - - `/EXECUTABLE=EXEC_NAME' - Output executable name. The name of the final executable program - will be EXEC_NAME. If the `/EXECUTABLE' qualifier is omitted the - default name for the executable will be the name of the input file - in appropriate form for an executable file on the host system. - - This qualifier cannot be used when invoking `GNAT MAKE' with - several `file_names'. - - `/QUIET' - Quiet. When this flag is not set, the commands carried out by - `GNAT MAKE' are displayed. - - `/SWITCH_CHECK/' - Recompile if compiler qualifiers have changed since last - compilation. All compiler qualifiers but -I and -o are taken into - account in the following way: orders between different "first - letter" qualifiers are ignored, but orders between same qualifiers - are taken into account. For example, `-O /OPTIMIZE=ALL' is - different than `/OPTIMIZE=ALL -O', but `-g -O' is equivalent to - `-O -g'. - - `/UNIQUE' - Unique. Recompile at most the main file. It implies -c. Combined - with -f, it is equivalent to calling the compiler directly. - - `/REASONS' - Verbose. Displays the reason for all recompilations `GNAT MAKE' - decides are necessary. - - `/NOMAIN' - No main subprogram. Bind and link the program even if the unit name - given on the command line is a package name. The resulting - executable will execute the elaboration routines of the package - and its closure, then the finalization routines. - - ``GNAT COMPILE' qualifiers' - Any qualifier that cannot be recognized as a qualifier for `GNAT - MAKE' but is recognizable as a valid qualifier for `GNAT COMPILE' - is automatically treated as a compiler qualifier, and passed on to - all compilations that are carried out. - - Source and library search path qualifiers: - - `/SOURCE_SEARCH=DIR' - When looking for source files also look in directory DIR. The - order in which source files search is undertaken is described in - *Note Search Paths and the Run-Time Library (RTL)::. - - `/SKIP_MISSING=DIR' - Consider DIR as being an externally provided Ada library. - Instructs `GNAT MAKE' to skip compilation units whose `.ALI' files - have been located in directory DIR. This allows you to have - missing bodies for the units in DIR and to ignore out of date - bodies for the same units. You still need to specify the location - of the specs for these units by using the qualifiers - `/SOURCE_SEARCH=DIR' or `/SEARCH=DIR'. Note: this qualifier is - provided for compatibility with previous versions of `GNAT MAKE'. - The easier method of causing standard libraries to be excluded - from consideration is to write-protect the corresponding ALI files. - - `/OBJECT_SEARCH=DIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is described in - *Note Search Paths for GNAT BIND::. - - `/CONDITIONAL_SOURCE_SEARCH=DIR' - Equivalent to `/SKIP_MISSING=DIR /SOURCE_SEARCH=DIR'. - - `/SEARCH=DIR' - Equivalent to `/OBJECT_SEARCH=DIR /SOURCE_SEARCH=DIR'. - - `/NOCURRENT_DIRECTORY' - Do not look for source files in the directory containing the source - file named in the command line. Do not look for ALI or object - files in the directory where `GNAT MAKE' was invoked. - - `/LIBRARY_SEARCH=DIR' - Add directory DIR to the list of directories in which the linker - will search for libraries. This is equivalent to - `/LINKER_QUALIFIERS /LIBRARY_SEARCH='DIR. - - `/NOSTD_INCLUDES' - Do not look for source files in the system default directory. - - `/NOSTD_LIBRARIES' - Do not look for library files in the system default directory. - - `/RUNTIME_SYSTEM=RTS-PATH' - Specifies the default location of the runtime library. We look for - the runtime in the following directories, and stop as soon as a - valid runtime is found ("adainclude" or "ada_source_path", and - "adalib" or "ada_object_path" present): - - * /$rts_path - - * /$rts_path - - * /rts-$rts_path - - The selected path is handled like a normal RTS path. - -  - File: gnat_ug_vms.info, Node: Mode Qualifiers for GNAT MAKE, Next: Notes on the Command Line, Prev: Qualifiers for GNAT MAKE, Up: The GNAT Make Program GNAT MAKE - - Mode Qualifiers for `GNAT MAKE' - =============================== - - The mode qualifiers (referred to as `mode_qualifiers') allow the - inclusion of qualifiers that are to be passed to the compiler itself, - the binder or the linker. The effect of a mode qualifier is to cause all - subsequent qualifiers up to the end of the qualifier list, or up to the - next mode qualifier, to be interpreted as qualifiers to be passed on to - the designated component of GNAT. - - `/COMPILER_QUALIFIERS QUALIFIERS' - Compiler qualifiers. Here QUALIFIERS is a list of qualifiers that - are valid qualifiers for `GNAT COMPILE'. They will be passed on to - all compile steps performed by `GNAT MAKE'. - - `/BINDER_QUALIFIERS QUALIFIERS' - Binder qualifiers. Here QUALIFIERS is a list of qualifiers that - are valid qualifiers for `GNAT COMPILE'. They will be passed on to - all bind steps performed by `GNAT MAKE'. - - `/LINKER_QUALIFIERS QUALIFIERS' - Linker qualifiers. Here QUALIFIERS is a list of qualifiers that - are valid qualifiers for `GNAT COMPILE'. They will be passed on to - all link steps performed by `GNAT MAKE'. - -  - File: gnat_ug_vms.info, Node: Notes on the Command Line, Next: How GNAT MAKE Works, Prev: Mode Qualifiers for GNAT MAKE, Up: The GNAT Make Program GNAT MAKE - - Notes on the Command Line - ========================= - - This section contains some additional useful notes on the operation of - the `GNAT MAKE' command. - - * If `GNAT MAKE' finds no ALI files, it recompiles the main program - and all other units required by the main program. This means that - `GNAT MAKE' can be used for the initial compile, as well as during - subsequent steps of the development cycle. - - * If you enter `GNAT MAKE FILE.ADB', where `FILE.ADB' is a subunit - or body of a generic unit, `GNAT MAKE' recompiles `FILE.ADB' - (because it finds no ALI) and stops, issuing a warning. - - * In `GNAT MAKE' the qualifier `/SEARCH' is used to specify both - source and library file paths. Use `/SOURCE_SEARCH' instead if you - just want to specify source paths only and `/OBJECT_SEARCH' if you - want to specify library paths only. - - * `GNAT MAKE' examines both an ALI file and its corresponding object - file for consistency. If an ALI is more recent than its - corresponding object, or if the object file is missing, the - corresponding source will be recompiled. Note that `GNAT MAKE' - expects an ALI and the corresponding object file to be in the same - directory. - - * `GNAT MAKE' will ignore any files whose ALI file is - write-protected. This may conveniently be used to exclude - standard libraries from consideration and in particular it means - that the use of the `/FORCE_COMPILE' qualifier will not recompile - these files unless `/ALL_FILES' is also specified. - - * `GNAT MAKE' has been designed to make the use of Ada libraries - particularly convenient. Assume you have an Ada library organized - as follows: [OBJ_DIR] contains the objects and ALI files for of - your Ada compilation units, whereas [INCLUDE_DIR] contains the - specs of these units, but no bodies. Then to compile a unit stored - in `MAIN.ADB', which uses this Ada library you would just type - - $ GNAT MAKE /SOURCE_SEARCH=[INCLUDE_DIR] - /SKIP_MISSING=[OBJ_DIR] main - - * Using `GNAT MAKE' along with the `/MINIMAL_RECOMPILATION' - qualifier provides a mechanism for avoiding unnecessary - rcompilations. Using this qualifier, you can update the - comments/format of your source files without having to recompile - everything. Note, however, that adding or deleting lines in a - source files may render its debugging info obsolete. If the file - in question is a spec, the impact is rather limited, as that - debugging info will only be useful during the elaboration phase of - your program. For bodies the impact can be more significant. In - all events, your debugger will warn you if a source file is more - recent than the corresponding object, and alert you to the fact - that the debugging information may be out of date. - -  - File: gnat_ug_vms.info, Node: How GNAT MAKE Works, Next: Examples of GNAT MAKE Usage, Prev: Notes on the Command Line, Up: The GNAT Make Program GNAT MAKE - - How `GNAT MAKE' Works - ===================== - - Generally `GNAT MAKE' automatically performs all necessary - recompilations and you don't need to worry about how it works. However, - it may be useful to have some basic understanding of the `GNAT MAKE' - approach and in particular to understand how it uses the results of - previous compilations without incorrectly depending on them. - - First a definition: an object file is considered "up to date" if the - corresponding ALI file exists and its time stamp predates that of the - object file and if all the source files listed in the dependency - section of this ALI file have time stamps matching those in the ALI - file. This means that neither the source file itself nor any files that - it depends on have been modified, and hence there is no need to - recompile this file. - - `GNAT MAKE' works by first checking if the specified main unit is up - to date. If so, no compilations are required for the main unit. If not, - `GNAT MAKE' compiles the main program to build a new ALI file that - reflects the latest sources. Then the ALI file of the main unit is - examined to find all the source files on which the main program depends, - and `GNAT MAKE' recursively applies the above procedure on all these - files. - - This process ensures that `GNAT MAKE' only trusts the dependencies - in an existing ALI file if they are known to be correct. Otherwise it - always recompiles to determine a new, guaranteed accurate set of - dependencies. As a result the program is compiled "upside down" from - what may be more familiar as the required order of compilation in some - other Ada systems. In particular, clients are compiled before the units - on which they depend. The ability of GNAT to compile in any order is - critical in allowing an order of compilation to be chosen that - guarantees that `GNAT MAKE' will recompute a correct set of new - dependencies if necessary. - - When invoking `GNAT MAKE' with several FILE_NAMES, if a unit is - imported by several of the executables, it will be recompiled at most - once. - -  - File: gnat_ug_vms.info, Node: Examples of GNAT MAKE Usage, Prev: How GNAT MAKE Works, Up: The GNAT Make Program GNAT MAKE - - Examples of `GNAT MAKE' Usage - ============================= - - `GNAT MAKE HELLO.ADB' - Compile all files necessary to bind and link the main program - `HELLO.ADB' (containing unit `Hello') and bind and link the - resulting object files to generate an executable file `HELLO.EXE'. - - `GNAT MAKE main1 main2 main3' - Compile all files necessary to bind and link the main programs - `MAIN1.ADB' (containing unit `Main1'), `MAIN2.ADB' (containing - unit `Main2') and `MAIN3.ADB' (containing unit `Main3') and bind - and link the resulting object files to generate three executable - files `MAIN1.EXE', `MAIN2.EXE' and `MAIN3.EXE'. - - `GNAT MAKE Main_Unit /QUIET /COMPILER_QUALIFIERS /OPTIMIZE=ALL /BINDER_QUALIFIERS /ORDER_OF_ELABORATION' - Compile all files necessary to bind and link the main program unit - `Main_Unit' (from file `MAIN_UNIT.ADB'). All compilations will be - done with optimization level 2 and the order of elaboration will be - listed by the binder. `GNAT MAKE' will operate in quiet mode, not - displaying commands it is executing. - -  - File: gnat_ug_vms.info, Node: Renaming Files Using GNAT CHOP, Next: Configuration Pragmas, Prev: The GNAT Make Program GNAT MAKE, Up: Top - - Renaming Files Using `GNAT CHOP' - ******************************** - - This chapter discusses how to handle files with multiple units by using - the `GNAT CHOP' utility. This utility is also useful in renaming files - to meet the standard GNAT default file naming conventions. - - * Menu: - - * Handling Files with Multiple Units:: - * Operating GNAT CHOP in Compilation Mode:: - * Command Line for GNAT CHOP:: - * Qualifiers for GNAT CHOP:: - * Examples of GNAT CHOP Usage:: - -  - File: gnat_ug_vms.info, Node: Handling Files with Multiple Units, Next: Operating GNAT CHOP in Compilation Mode, Up: Renaming Files Using GNAT CHOP - - Handling Files with Multiple Units - ================================== - - The basic compilation model of GNAT requires that a file submitted to - the compiler have only one unit and there be a strict correspondence - between the file name and the unit name. - - The `GNAT CHOP' utility allows both of these rules to be relaxed, - allowing GNAT to process files which contain multiple compilation units - and files with arbitrary file names. `GNAT CHOP' reads the specified - file and generates one or more output files, containing one unit per - file. The unit and the file name correspond, as required by GNAT. - - If you want to permanently restructure a set of "foreign" files so - that they match the GNAT rules, and do the remaining development using - the GNAT structure, you can simply use `GNAT CHOP' once, generate the - new set of files and work with them from that point on. - - Alternatively, if you want to keep your files in the "foreign" - format, perhaps to maintain compatibility with some other Ada - compilation system, you can set up a procedure where you use `GNAT - CHOP' each time you compile, regarding the source files that it writes - as temporary files that you throw away. - -  - File: gnat_ug_vms.info, Node: Operating GNAT CHOP in Compilation Mode, Next: Command Line for GNAT CHOP, Prev: Handling Files with Multiple Units, Up: Renaming Files Using GNAT CHOP - - Operating GNAT CHOP in Compilation Mode - ======================================= - - The basic function of `GNAT CHOP' is to take a file with multiple units - and split it into separate files. The boundary between files is - reasonably clear, except for the issue of comments and pragmas. In - default mode, the rule is that any pragmas between units belong to the - previous unit, except that configuration pragmas always belong to the - following unit. Any comments belong to the following unit. These rules - almost always result in the right choice of the split point without - needing to mark it explicitly and most users will find this default to - be what they want. In this default mode it is incorrect to submit a - file containing only configuration pragmas, or one that ends in - configuration pragmas, to `GNAT CHOP'. - - However, using a special option to activate "compilation mode", - `GNAT CHOP' can perform another function, which is to provide exactly - the semantics required by the RM for handling of configuration pragmas - in a compilation. In the absence of configuration pragmas (at the main - file level), this option has no effect, but it causes such - configuration pragmas to be handled in a quite different manner. - - First, in compilation mode, if `GNAT CHOP' is given a file that - consists of only configuration pragmas, then this file is appended to - the `GNAT.ADC' file in the current directory. This behavior provides - the required behavior described in the RM for the actions to be taken - on submitting such a file to the compiler, namely that these pragmas - should apply to all subsequent compilations in the same compilation - environment. Using GNAT, the current directory, possibly containing a - `GNAT.ADC' file is the representation of a compilation environment. For - more information on the `GNAT.ADC' file, see the section on handling of - configuration pragmas *note Handling of Configuration Pragmas::. - - Second, in compilation mode, if `GNAT CHOP' is given a file that - starts with configuration pragmas, and contains one or more units, then - these configuration pragmas are prepended to each of the chopped files. - This behavior provides the required behavior described in the RM for the - actions to be taken on compiling such a file, namely that the pragmas - apply to all units in the compilation, but not to subsequently compiled - units. - - Finally, if configuration pragmas appear between units, they are - appended to the previous unit. This results in the previous unit being - illegal, since the compiler does not accept configuration pragmas that - follow a unit. This provides the required RM behavior that forbids - configuration pragmas other than those preceding the first compilation - unit of a compilation. - - For most purposes, `GNAT CHOP' will be used in default mode. The - compilation mode described above is used only if you need exactly - accurate behavior with respect to compilations, and you have files that - contain multiple units and configuration pragmas. In this circumstance - the use of `GNAT CHOP' with the compilation mode qualifier provides the - required behavior, and is for example the mode in which GNAT processes - the ACVC tests. - -  - File: gnat_ug_vms.info, Node: Command Line for GNAT CHOP, Next: Qualifiers for GNAT CHOP, Prev: Operating GNAT CHOP in Compilation Mode, Up: Renaming Files Using GNAT CHOP - - Command Line for `GNAT CHOP' - ============================ - - The `GNAT CHOP' command has the form: - - $ GNAT CHOP qualifiers FILE NAME [FILE NAME FILE NAME ...] - [DIRECTORY] - - The only required argument is the file name of the file to be chopped. - There are no restrictions on the form of this file name. The file itself - contains one or more Ada units, in normal GNAT format, concatenated - together. As shown, more than one file may be presented to be chopped. - - When run in default mode, `GNAT CHOP' generates one output file in - the current directory for each unit in each of the files. - - DIRECTORY, if specified, gives the name of the directory to which - the output files will be written. If it is not specified, all files are - written to the current directory. - - For example, given a file called `hellofiles' containing - - procedure hello; - - with Text_IO; use Text_IO; - procedure hello is - begin - Put_Line ("Hello"); - end hello; - - the command - - $ GNAT CHOP HELLOFILES. - - generates two files in the current directory, one called `HELLO.ADS' - containing the single line that is the procedure spec, and the other - called `HELLO.ADB' containing the remaining text. The original file is - not affected. The generated files can be compiled in the normal manner. - -  - File: gnat_ug_vms.info, Node: Qualifiers for GNAT CHOP, Next: Examples of GNAT CHOP Usage, Prev: Command Line for GNAT CHOP, Up: Renaming Files Using GNAT CHOP - - Qualifiers for `GNAT CHOP' - ========================== - - `GNAT CHOP' recognizes the following qualifiers: - - `/COMPILATION' - Causes `GNAT CHOP' to operate in compilation mode, in which - configuration pragmas are handled according to strict RM rules. See - previous section for a full description of this mode. - - `/HELP' - Causes `GNAT CHOP' to generate a brief help summary to the standard - output file showing usage information. - - `/FILE_NAME_MAX_LENGTH=MM' - Limit generated file names to the specified number `mm' of - characters. This is useful if the resulting set of files is - required to be interoperable with systems which limit the length - of file names. If no value is given, or if no - `/FILE_NAME_MAX_LENGTH' qualifier is given, a default of 39, - suitable for OpenVMS Alpha Systems, is assumed - - `/PRESERVE' - Causes the file creation time stamp of the input file to be - preserved and used for the time stamp of the output file(s). This - may be useful for preserving coherency of time stamps in an - enviroment where `GNAT CHOP' is used as part of a standard build - process. - - `/QUIET' - Causes output of informational messages indicating the set of - generated files to be suppressed. Warnings and error messages are - unaffected. - - `/REFERENCE' - Generate `Source_Reference' pragmas. Use this qualifier if the - output files are regarded as temporary and development is to be - done in terms of the original unchopped file. This qualifier causes - `Source_Reference' pragmas to be inserted into each of the - generated files to refers back to the original file name and line - number. The result is that all error messages refer back to the - original unchopped file. In addition, the debugging information - placed into the object file (when the `/DEBUG' qualifier of `GNAT - COMPILE' or `GNAT MAKE' is specified) also refers back to this - original file so that tools like profilers and debuggers will give - information in terms of the original unchopped file. - - If the original file to be chopped itself contains a - `Source_Reference' pragma referencing a third file, then GNAT CHOP - respects this pragma, and the generated `Source_Reference' pragmas - in the chopped file refer to the original file, with appropriate - line numbers. This is particularly useful when `GNAT CHOP' is used - in conjunction with `GNAT PREPROCESS' to compile files that - contain preprocessing statements and multiple units. - - `/VERBOSE' - Causes `GNAT CHOP' to operate in verbose mode. The version number - and copyright notice are output, as well as exact copies of the - GNAT1 commands spawned to obtain the chop control information. - - `/OVERWRITE' - Overwrite existing file names. Normally `GNAT CHOP' regards it as a - fatal error if there is already a file with the same name as a - file it would otherwise output, in other words if the files to be - chopped contain duplicated units. This qualifier bypasses this - check, and causes all but the last instance of such duplicated - units to be skipped. - -  - File: gnat_ug_vms.info, Node: Examples of GNAT CHOP Usage, Prev: Qualifiers for GNAT CHOP, Up: Renaming Files Using GNAT CHOP - - Examples of `GNAT CHOP' Usage - ============================= - - `GNAT CHOP /OVERWRITE HELLO_S.ADA [ICHBIAH.FILES]' - Chops the source file `HELLO_S.ADA'. The output files will be - placed in the directory `[ICHBIAH.FILES]', overwriting any files - with matching names in that directory (no files in the current - directory are modified). - - `GNAT CHOP ARCHIVE.' - Chops the source file `ARCHIVE.' into the current directory. One - useful application of `GNAT CHOP' is in sending sets of sources - around, for example in email messages. The required sources are - simply concatenated (for example, using a VMS `APPEND/NEW' - command), and then `GNAT CHOP' is used at the other end to - reconstitute the original file names. - - `GNAT CHOP file1 file2 file3 direc' - Chops all units in files `file1', `file2', `file3', placing the - resulting files in the directory `direc'. Note that if any units - occur more than once anywhere within this set of files, an error - message is generated, and no files are written. To override this - check, use the `/OVERWRITE' qualifier, in which case the last - occurrence in the last file will be the one that is output, and - earlier duplicate occurrences for a given unit will be skipped. - -  - File: gnat_ug_vms.info, Node: Configuration Pragmas, Next: Handling Arbitrary File Naming Conventions Using gnatname, Prev: Renaming Files Using GNAT CHOP, Up: Top - - Configuration Pragmas - ********************* - - In Ada 95, configuration pragmas include those pragmas described as - such in the Ada 95 Reference Manual, as well as - implementation-dependent pragmas that are configuration pragmas. See the - individual descriptions of pragmas in the GNAT Reference Manual for - details on these additional GNAT-specific configuration pragmas. Most - notably, the pragma `Source_File_Name', which allows specifying - non-default names for source files, is a configuration pragma. The - following is a complete list of configuration pragmas recognized by - `GNAT': - - Ada_83 - Ada_95 - C_Pass_By_Copy - Component_Alignment - Discard_Names - Elaboration_Checks - Eliminate - Extend_System - Extensions_Allowed - External_Name_Casing - Float_Representation - Initialize_Scalars - License - Locking_Policy - Long_Float - No_Run_Time - Normalize_Scalars - Polling - Propagate_Exceptions - Queuing_Policy - Ravenscar - Restricted_Run_Time - Restrictions - Reviewable - Source_File_Name - Style_Checks - Suppress - Task_Dispatching_Policy - Unsuppress - Use_VADS_Size - Warnings - Validity_Checks - - * Menu: - - * Handling of Configuration Pragmas:: - * The Configuration Pragmas Files:: - -  - File: gnat_ug_vms.info, Node: Handling of Configuration Pragmas, Next: The Configuration Pragmas Files, Up: Configuration Pragmas - - Handling of Configuration Pragmas - ================================= - - Configuration pragmas may either appear at the start of a compilation - unit, in which case they apply only to that unit, or they may apply to - all compilations performed in a given compilation environment. - - GNAT also provides the `GNAT CHOP' utility to provide an automatic - way to handle configuration pragmas following the semantics for - compilations (that is, files with multiple units), described in the RM. - See section *note Operating GNAT CHOP in Compilation Mode:: for details. - However, for most purposes, it will be more convenient to edit the - `GNAT.ADC' file that contains configuration pragmas directly, as - described in the following section. - -  - File: gnat_ug_vms.info, Node: The Configuration Pragmas Files, Prev: Handling of Configuration Pragmas, Up: Configuration Pragmas - - The Configuration Pragmas Files - =============================== - - In GNAT a compilation environment is defined by the current directory - at the time that a compile command is given. This current directory is - searched for a file whose name is `GNAT.ADC'. If this file is present, - it is expected to contain one or more configuration pragmas that will - be applied to the current compilation. However, if the qualifier - `-gnatA' is used, `GNAT.ADC' is not considered. - - Configuration pragmas may be entered into the `GNAT.ADC' file either - by running `GNAT CHOP' on a source file that consists only of - configuration pragmas, or more conveniently by direct editing of the - `GNAT.ADC' file, which is a standard format source file. - - In addition to `GNAT.ADC', one additional file containing - configuration pragmas may be applied to the current compilation using - the qualifier `-gnatec'PATH. PATH must designate an existing file that - contains only configuration pragmas. These configuration pragmas are in - addition to those found in `GNAT.ADC' (provided `GNAT.ADC' is present - and qualifier `-gnatA' is not used). - - It is allowed to specify several qualifiers `-gnatec', however only - the last one on the command line will be taken into account. - - Of special interest to GNAT OpenVMS Alpha is the following - configuration pragma: - - pragma Extend_System (Aux_DEC); - - In the presence of this pragma, GNAT adds to the definition of the - predefined package SYSTEM all the additional types and subprograms that - are defined in DEC Ada. See *note Compatibility with DEC Ada:: for - details. - -  - File: gnat_ug_vms.info, Node: Handling Arbitrary File Naming Conventions Using gnatname, Next: GNAT Project Manager, Prev: Configuration Pragmas, Up: Top - - Handling Arbitrary File Naming Conventions Using `gnatname' - *********************************************************** - - * Menu: - - * Arbitrary File Naming Conventions:: - * Running gnatname:: - * Qualifiers for gnatname:: - * Examples of gnatname Usage:: - -  - File: gnat_ug_vms.info, Node: Arbitrary File Naming Conventions, Next: Running gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Arbitrary File Naming Conventions - ================================= - - The GNAT compiler must be able to know the source file name of a - compilation unit. When using the standard GNAT default file naming - conventions (`.ADS' for specs, `.ADB' for bodies), the GNAT compiler - does not need additional information. - - When the source file names do not follow the standard GNAT default file - naming conventions, the GNAT compiler must be given additional - information through a configuration pragmas file (see *Note - Configuration Pragmas::) or a project file. When the non standard file - naming conventions are well-defined, a small number of pragmas - `Source_File_Name' specifying a naming pattern (see *Note Alternative - File Naming Schemes::) may be sufficient. However, if the file naming - conventions are irregular or arbitrary, a number of pragma - `Source_File_Name' for individual compilation units must be defined. - To help maintain the correspondence between compilation unit names and - source file names within the compiler, GNAT provides a tool `gnatname' - to generate the required pragmas for a set of files. - -  - File: gnat_ug_vms.info, Node: Running gnatname, Next: Qualifiers for gnatname, Prev: Arbitrary File Naming Conventions, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Running `gnatname' - ================== - - The usual form of the `gnatname' command is - - $ gnatname [QUALIFIERS] NAMING_PATTERN [NAMING_PATTERNS] - - All of the arguments are optional. If invoked without any argument, - `gnatname' will display its usage. - - When used with at least one naming pattern, `gnatname' will attempt to - find all the compilation units in files that follow at least one of the - naming patterns. To find these compilation units, `gnatname' will use - the GNAT compiler in syntax-check-only mode on all regular files. - - One or several Naming Patterns may be given as arguments to `gnatname'. - Each Naming Pattern is enclosed between double quotes. A Naming - Pattern is a regular expression similar to the wildcard patterns used - in file names by the Unix shells or the DOS prompt. - - Examples of Naming Patterns are - - "*.[12].ADA" - "*.ad[sb]*" - "body_*" "spec_*" - - For a more complete description of the syntax of Naming Patterns, see - the second kind of regular expressions described in `G-REGEXP.ADS' (the - "Glob" regular expressions). - - When invoked with no qualifiers, `gnatname' will create a configuration - pragmas file `GNAT.ADC' in the current working directory, with pragmas - `Source_File_Name' for each file that contains a valid Ada unit. - -  - File: gnat_ug_vms.info, Node: Qualifiers for gnatname, Next: Examples of gnatname Usage, Prev: Running gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Qualifiers for `gnatname' - ========================= - - Qualifiers for `gnatname' must precede any specified Naming Pattern. - - You may specify any of the following qualifiers to `gnatname': - - `-c`file'' - Create a configuration pragmas file `file' (instead of the default - `GNAT.ADC'). There may be zero, one or more space between `-c' and - `file'. `file' may include directory information. `file' must be - writeable. There may be only one qualifier `-c'. When a qualifier - `-c' is specified, no qualifier `-P' may be specified (see below). - - `-d`dir'' - Look for source files in directory `dir'. There may be zero, one - or more spaces between `-d' and `dir'. When a qualifier `-d' is - specified, the current working directory will not be searched for - source files, unless it is explictly specified with a `-d' or `-D' - qualifier. Several qualifiers `-d' may be specified. If `dir' is a - relative path, it is relative to the directory of the - configuration pragmas file specified with qualifier `-c', or to - the directory of the project file specified with qualifier `-P' - or, if neither qualifier `-c' nor qualifier `-P' are specified, it - is relative to the current working directory. The directory - specified with qualifier `-c' must exist and be readable. - - `-D`file'' - Look for source files in all directories listed in text file - `file'. There may be zero, one or more spaces between `-d' and - `dir'. `file' must be an existing, readable text file. Each non - empty line in `file' must be a directory. Specifying qualifier - `-D' is equivalent to specifying as many qualifiers `-d' as there - are non empty lines in `file'. - - `-h' - Output usage (help) information. The output is written to - `SYS$OUTPUT'. - - `-P`proj'' - Create or update project file `proj'. There may be zero, one or - more space between `-P' and `proj'. `proj' may include directory - information. `proj' must be writeable. There may be only one - qualifier `-P'. When a qualifier `-P' is specified, no qualifier - `-c' may be specified. - - `-v' - Verbose mode. Output detailed explanation of behavior to - `SYS$OUTPUT'. This includes name of the file written, the name of - the directories to search and, for each file in those directories - whose name matches at least one of the Naming Patterns, an - indication of whether the file contains a unit, and if so the name - of the unit. - - `-v -v' - Very Verbose mode. In addition to the output produced in verbose - mode, for each file in the searched directories whose name matches - none of the Naming Patterns, an indication is given that there is - no match. - - `-x`pattern'' - Excluded patterns. Using this qualifier, it is possible to exclude - some files that would match the name patterns. For example, - `"gnatname -x "*_NT.ADA" "*.ADA"' will look for Ada units in all - files with the `.ADA' extension, except those whose names end with - `_NT.ADA'. - -  - File: gnat_ug_vms.info, Node: Examples of gnatname Usage, Prev: Qualifiers for gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Examples of `gnatname' Usage - ============================ - - $ gnatname -c /home/me/NAMES.ADC -d sources "[a-z]*.ADA*" - - In this example, the directory `/home/me' must already exist and be - writeable. In addition, the directory `/home/me/sources' (specified by - `-d sources') must exist and be readable. Note the optional spaces after - `-c' and `-d'. - - $ gnatname -P/home/me/proj -x "*_NT_BODY.ADA" -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" - - Note that several qualifiers `-d' may be used, even in conjunction - with one or several qualifiers `-D'. Several Naming Patterns and one - excluded pattern are used in this example. - -  - File: gnat_ug_vms.info, Node: GNAT Project Manager, Next: Elaboration Order Handling in GNAT, Prev: Handling Arbitrary File Naming Conventions Using gnatname, Up: Top - - GNAT Project Manager - ******************** - - * Menu: - - * Introduction:: - * Examples of Project Files:: - * Project File Syntax:: - * Objects and Sources in Project Files:: - * Importing Projects:: - * Project Extension:: - * External References in Project Files:: - * Packages in Project Files:: - * Variables from Imported Projects:: - * Naming Schemes:: - * Library Projects:: - * Qualifiers Related to Project Files:: - * Tools Supporting Project Files:: - * An Extended Example:: - * Project File Complete Syntax:: - -  - File: gnat_ug_vms.info, Node: Introduction, Next: Examples of Project Files, Up: GNAT Project Manager - - Introduction - ============ - - This chapter describes GNAT's _Project Manager_, a facility that lets - you configure various properties for a collection of source files. In - particular, you can specify: - * The directory or set of directories containing the source files, - and/or the names of the specific source files themselves - - * The directory in which the compiler's output (`ALI' files, object - files, tree files) will be placed - - * The directory in which the executable programs will be placed - - * Qualifier settings for any of the project-enabled tools (`GNAT - MAKE', compiler, binder, linker, `GNAT LIST', `GNAT XREF', `GNAT - FIND'); you can apply these settings either globally or to - individual units - - * The source files containing the main subprogram(s) to be built - - * The source programming language(s) (currently Ada and/or C) - - * Source file naming conventions; you can specify these either - globally or for individual units - - * Menu: - - * Project Files:: - -  - File: gnat_ug_vms.info, Node: Project Files, Up: Introduction - - Project Files - ------------- - - A "project" is a specific set of values for these properties. You can - define a project's settings in a "project file", a text file with an - Ada-like syntax; a property value is either a string or a list of - strings. Properties that are not explicitly set receive default - values. A project file may interrogate the values of "external - variables" (user-defined command-line qualifiers or environment - variables), and it may specify property settings conditionally, based - on the value of such variables. - - In simple cases, a project's source files depend only on other - source files in the same project, or on the predefined libraries. - ("Dependence" is in the technical sense; for example, one Ada unit - "with"ing another.) However, the Project Manager also allows much more - sophisticated arrangements, with the source files in one project - depending on source files in other projects: - * One project can _import_ other projects containing needed source - files. - - * You can organize GNAT projects in a hierarchy: a _child_ project - can extend a _parent_ project, inheriting the parent's source - files and optionally overriding any of them with alternative - versions - - More generally, the Project Manager lets you structure large development - efforts into hierarchical subsystems, with build decisions deferred to - the subsystem level and thus different compilation environments - (qualifier settings) used for different subsystems. - - The Project Manager is invoked through the `-P_projectfile_' - qualifier to `GNAT MAKE' or to the `gnat' front driver. If you want to - define (on the command line) an external variable that is queried by - the project file, additionally use the `-X_vbl_=_value_' qualifier. - The Project Manager parses and interprets the project file, and drives - the invoked tool based on the project settings. - - The Project Manager supports a wide range of development strategies, - for systems of all sizes. Some typical practices that are easily - handled: - * Using a common set of source files, but generating object files in - different directories via different qualifier settings - - * Using a mostly-shared set of source files, but with different - versions of some unit or units - - The destination of an executable can be controlled inside a project file - using the `-o' qualifier. In the absence of such a qualifier either - inside the project file or on the command line, any executable files - generated by `GNAT MAKE' will be placed in the directory `Exec_Dir' - specified in the project file. If no `Exec_Dir' is specified, they will - be placed in the object directory of the project. - - You can use project files to achieve some of the effects of a source - versioning system (for example, defining separate projects for the - different sets of sources that comprise different releases) but the - Project Manager is independent of any source configuration management - tools that might be used by the developers. - - The next section introduces the main features of GNAT's project - facility through a sequence of examples; subsequent sections will - present the syntax and semantics in more detail. - -  - File: gnat_ug_vms.info, Node: Examples of Project Files, Next: Project File Syntax, Prev: Introduction, Up: GNAT Project Manager - - Examples of Project Files - ========================= - - This section illustrates some of the typical uses of project files and - explains their basic structure and behavior. - - * Menu: - - * Common Sources with Different Qualifiers and Different Output Directories:: - * Using External Variables:: - * Importing Other Projects:: - * Extending a Project:: - -  - File: gnat_ug_vms.info, Node: Common Sources with Different Qualifiers and Different Output Directories, Next: Using External Variables, Up: Examples of Project Files - - Common Sources with Different Qualifiers and Different Output Directories - ------------------------------------------------------------------------- - - * Menu: - - * Source Files:: - * Specifying the Object Directory:: - * Specifying the Exec Directory:: - * Project File Packages:: - * Specifying Qualifier Settings:: - * Main Subprograms:: - * Source File Naming Conventions:: - * Source Language(s):: - - Assume that the Ada source files `PACK.ADS', `PACK.ADB', and `PROC.ADB' - are in the `/common' directory. The file `PROC.ADB' contains an Ada - main subprogram `Proc' that "with"s package `Pack'. We want to compile - these source files under two sets of qualifiers: - * When debugging, we want to pass the `-g' qualifier to `GNAT MAKE', - and the `/CHECKS=ASSERTIONS', `/CHECKS=OVERFLOW', and - `/CHECKS=ELABORATION' qualifiers to the compiler; the compiler's - output is to appear in `/common/debug' - - * When preparing a release version, we want to pass the - `/OPTIMIZE=ALL' qualifier to the compiler; the compiler's output - is to appear in `/common/release' - - The GNAT project files shown below, respectively `debug.gpr' and - `release.gpr' in the `/common' directory, achieve these effects. - - Diagrammatically: - /common - debug.gpr - release.gpr - PACK.ADS - PACK.ADB - PROC.ADB - /common/debug {-g, /CHECKS=ASSERTIONS, /CHECKS=OVERFLOW, /CHECKS=ELABORATION} - PROC.ALI, PROC.OBJ - PACK.ALI, PACK.OBJ - /common/release {/OPTIMIZE=ALL} - PROC.ALI, PROC.OBJ - PACK.ALI, PACK.OBJ - Here are the project files: - project Debug is - for Object_Dir use "debug"; - for Main use ("proc"); - - package Builder is - for Default_Qualifiers ("Ada") use ("-g"); - end Builder; - - package Compiler is - for Default_Qualifiers ("Ada") - use ("-fstack-check", "/CHECKS=ASSERTIONS", "/CHECKS=OVERFLOW", "/CHECKS=ELABORATION"); - end Compiler; - end Debug; - - project Release is - for Object_Dir use "release"; - for Exec_Dir use "."; - for Main use ("proc"); - - package Compiler is - for Default_Qualifiers ("Ada") use ("/OPTIMIZE=ALL"); - end Compiler; - end Release; - - The name of the project defined by `debug.gpr' is `"Debug"' (case - insensitive), and analogously the project defined by `release.gpr' is - `"Release"'. For consistency the file should have the same name as the - project, and the project file's extension should be `"gpr"'. These - conventions are not required, but a warning is issued if they are not - followed. - - If the current directory is `/temp', then the command - GNAT MAKE -P/common/debug.gpr - - generates object and ALI files in `/common/debug', and the `proc' - executable also in `/common/debug', using the qualifier settings - defined in the project file. - - Likewise, the command - GNAT MAKE -P/common/release.gpr - - generates object and ALI files in `/common/release', and the `proc' - executable in `/common', using the qualifier settings from the project - file. - -  - File: gnat_ug_vms.info, Node: Source Files, Next: Specifying the Object Directory, Up: Common Sources with Different Qualifiers and Different Output Directories - - Source Files - ............ - - If a project file does not explicitly specify a set of source - directories or a set of source files, then by default the project's - source files are the Ada source files in the project file directory. - Thus `PACK.ADS', `PACK.ADB', and `PROC.ADB' are the source files for - both projects. - -  - File: gnat_ug_vms.info, Node: Specifying the Object Directory, Next: Specifying the Exec Directory, Prev: Source Files, Up: Common Sources with Different Qualifiers and Different Output Directories - - Specifying the Object Directory - ............................... - - Several project properties are modeled by Ada-style _attributes_; you - define the property by supplying the equivalent of an Ada attribute - definition clause in the project file. A project's object directory is - such a property; the corresponding attribute is `Object_Dir', and its - value is a string expression. A directory may be specified either as - absolute or as relative; in the latter case, it is relative to the - project file directory. Thus the compiler's output is directed to - `/common/debug' (for the `Debug' project) and to `/common/release' (for - the `Release' project). If `Object_Dir' is not specified, then the - default is the project file directory. - -  - File: gnat_ug_vms.info, Node: Specifying the Exec Directory, Next: Project File Packages, Prev: Specifying the Object Directory, Up: Common Sources with Different Qualifiers and Different Output Directories - - Specifying the Exec Directory - ............................. - - A project's exec directory is another property; the corresponding - attribute is `Exec_Dir', and its value is also a string expression, - either specified as relative or absolute. If `Exec_Dir' is not - specified, then the default is the object directory (which may also be - the project file directory if attribute `Object_Dir' is not specified). - Thus the executable is placed in `/common/debug' for the `Debug' - project (attribute `Exec_Dir' not specified) and in `/common' for the - `Release' project. - -  - File: gnat_ug_vms.info, Node: Project File Packages, Next: Specifying Qualifier Settings, Prev: Specifying the Exec Directory, Up: Common Sources with Different Qualifiers and Different Output Directories - - Project File Packages - ..................... - - A GNAT tool integrated with the Project Manager is modeled by a - corresponding package in the project file. The `Debug' project defines - the packages `Builder' (for `GNAT MAKE') and `Compiler'; the `Release' - project defines only the `Compiler' package. - - The Ada package syntax is not to be taken literally. Although - packages in project files bear a surface resemblance to packages in Ada - source code, the notation is simply a way to convey a grouping of - properties for a named entity. Indeed, the package names permitted in - project files are restricted to a predefined set, corresponding to the - project-aware tools, and the contents of packages are limited to a - small set of constructs. The packages in the example above contain - attribute definitions. - -  - File: gnat_ug_vms.info, Node: Specifying Qualifier Settings, Next: Main Subprograms, Prev: Project File Packages, Up: Common Sources with Different Qualifiers and Different Output Directories - - Specifying Qualifier Settings - ............................. - - Qualifier settings for a project-aware tool can be specified through - attributes in the package corresponding to the tool. The example above - illustrates one of the relevant attributes, `Default_Qualifiers', - defined in the packages in both project files. Unlike simple - attributes like `Source_Dirs', `Default_Qualifiers' is known as an - _associative array_. When you define this attribute, you must supply - an "index" (a literal string), and the effect of the attribute - definition is to set the value of the "array" at the specified "index". - For the `Default_Qualifiers' attribute, the index is a programming - language (in our case, Ada) , and the value specified (after `use') - must be a list of string expressions. - - The attributes permitted in project files are restricted to a - predefined set. Some may appear at project level, others in packages. - For any attribute that is an associate array, the index must always be a - literal string, but the restrictions on this string (e.g., a file name - or a language name) depend on the individual attribute. Also depending - on the attribute, its specified value will need to be either a string - or a string list. - - In the `Debug' project, we set the qualifiers for two tools, `GNAT - MAKE' and the compiler, and thus we include corresponding packages, - with each package defining the `Default_Qualifiers' attribute with - index `"Ada"'. Note that the package corresponding to `GNAT MAKE' is - named `Builder'. The `Release' project is similar, but with just the - `Compiler' package. - - In project `Debug' above the qualifiers starting with `-gnat' that - are specified in package `Compiler' could have been placed in package - `Builder', since `GNAT MAKE' transmits all such qualifiers to the - compiler. - -  - File: gnat_ug_vms.info, Node: Main Subprograms, Next: Source File Naming Conventions, Prev: Specifying Qualifier Settings, Up: Common Sources with Different Qualifiers and Different Output Directories - - Main Subprograms - ................ - - One of the properties of a project is its list of main subprograms - (actually a list of names of source files containing main subprograms, - with the file extension optional. This property is captured in the - `Main' attribute, whose value is a list of strings. If a project - defines the `Main' attribute, then you do not need to identify the main - subprogram(s) when invoking `GNAT MAKE' (see *Note GNAT MAKE and - Project Files::). - -  - File: gnat_ug_vms.info, Node: Source File Naming Conventions, Next: Source Language(s), Prev: Main Subprograms, Up: Common Sources with Different Qualifiers and Different Output Directories - - Source File Naming Conventions - .............................. - - Since the project files do not specify any source file naming - conventions, the GNAT defaults are used. The mechanism for defining - source file naming conventions - a package named `Naming' - will be - described below (*note Naming Schemes::). - -  - File: gnat_ug_vms.info, Node: Source Language(s), Prev: Source File Naming Conventions, Up: Common Sources with Different Qualifiers and Different Output Directories - - Source Language(s) - .................. - - Since the project files do not specify a `Languages' attribute, by - default the GNAT tools assume that the language of the project file is - Ada. More generally, a project can comprise source files in Ada, C, - and/or other languages. - -  - File: gnat_ug_vms.info, Node: Using External Variables, Next: Importing Other Projects, Prev: Common Sources with Different Qualifiers and Different Output Directories, Up: Examples of Project Files - - Using External Variables - ------------------------ - - Instead of supplying different project files for debug and release, we - can define a single project file that queries an external variable (set - either on the command line or via an environment variable) in order to - conditionally define the appropriate settings. Again, assume that the - source files `PACK.ADS', `PACK.ADB', and `PROC.ADB' are located in - directory `/common'. The following project file, `build.gpr', queries - the external variable named `STYLE' and defines an object directory and - qualifier settings based on whether the value is `"deb"' (debug) or - `"rel"' (release), where the default is `"deb"'. - - project Build is - for Main use ("proc"); - - type Style_Type is ("deb", "rel"); - Style : Style_Type := external ("STYLE", "deb"); - - case Style is - when "deb" => - for Object_Dir use "debug"; - - when "rel" => - for Object_Dir use "release"; - for Exec_Dir use "."; - end case; - - package Builder is - - case Style is - when "deb" => - for Default_Qualifiers ("Ada") use ("-g"); - end case; - - end Builder; - - package Compiler is - - case Style is - when "deb" => - for Default_Qualifiers ("Ada") use ("/CHECKS=ASSERTIONS", "/CHECKS=OVERFLOW", "/CHECKS=ELABORATION"); - - when "rel" => - for Default_Qualifiers ("Ada") use ("/OPTIMIZE=ALL"); - end case; - - end Compiler; - - end Build; - - `Style_Type' is an example of a _string type_, which is the project - file analog of an Ada enumeration type but containing string literals - rather than identifiers. `Style' is declared as a variable of this - type. - - The form `external("STYLE", "deb")' is known as an _external - reference_; its first argument is the name of an _external variable_, - and the second argument is a default value to be used if the external - variable doesn't exist. You can define an external variable on the - command line via the `-X' qualifier, or you can use an environment - variable as an external variable. - - Each `case' construct is expanded by the Project Manager based on the - value of `Style'. Thus the command - GNAT MAKE -P/common/build.gpr -XSTYLE=deb - - is equivalent to the `GNAT MAKE' invocation using the project file - `debug.gpr' in the earlier example. So is the command - GNAT MAKE -P/common/build.gpr - - since `"deb"' is the default for `STYLE'. - - Analogously, - GNAT MAKE -P/common/build.gpr -XSTYLE=rel - - is equivalent to the `GNAT MAKE' invocation using the project file - `release.gpr' in the earlier example. - -  - File: gnat_ug_vms.info, Node: Importing Other Projects, Next: Extending a Project, Prev: Using External Variables, Up: Examples of Project Files - - Importing Other Projects - ------------------------ - - A compilation unit in a source file in one project may depend on - compilation units in source files in other projects. To obtain this - behavior, the dependent project must _import_ the projects containing - the needed source files. This effect is embodied in syntax similar to - an Ada `with' clause, but the "with"ed entities are strings denoting - project files. - - As an example, suppose that the two projects `GUI_Proj' and - `Comm_Proj' are defined in the project files `gui_proj.gpr' and - `comm_proj.gpr' in directories `/gui' and `/comm', respectively. - Assume that the source files for `GUI_Proj' are `GUI.ADS' and - `GUI.ADB', and that the source files for `Comm_Proj' are `COMM.ADS' and - `COMM.ADB', with each set of files located in its respective project - file directory. Diagrammatically: - - /gui - gui_proj.gpr - GUI.ADS - GUI.ADB - - /comm - comm_proj.gpr - COMM.ADS - COMM.ADB - - We want to develop an application in directory `/app' that "with"s the - packages `GUI' and `Comm', using the properties of the corresponding - project files (e.g. the qualifier settings and object directory). - Skeletal code for a main procedure might be something like the - following: - - with GUI, Comm; - procedure App_Main is - ... - begin - ... - end App_Main; - - Here is a project file, `app_proj.gpr', that achieves the desired - effect: - - with "/gui/gui_proj", "/comm/comm_proj"; - project App_Proj is - for Main use ("app_main"); - end App_Proj; - - Building an executable is achieved through the command: - GNAT MAKE -P/app/app_proj - - which will generate the `app_main' executable in the directory where - `app_proj.gpr' resides. - - If an imported project file uses the standard extension (`gpr') then - (as illustrated above) the `with' clause can omit the extension. - - Our example specified an absolute path for each imported project - file. Alternatively, you can omit the directory if either - * The imported project file is in the same directory as the - importing project file, or - - * You have defined an environment variable `ADA_PROJECT_PATH' that - includes the directory containing the needed project file. - - Thus, if we define `ADA_PROJECT_PATH' to include `/gui' and `/comm', - then our project file `app_proj.gpr' could be written as follows: - - with "gui_proj", "comm_proj"; - project App_Proj is - for Main use ("app_main"); - end App_Proj; - - Importing other projects raises the possibility of ambiguities. For - example, the same unit might be present in different imported projects, - or it might be present in both the importing project and an imported - project. Both of these conditions are errors. Note that in the - current version of the Project Manager, it is illegal to have an - ambiguous unit even if the unit is never referenced by the importing - project. This restriction may be relaxed in a future release. - -  - File: gnat_ug_vms.info, Node: Extending a Project, Prev: Importing Other Projects, Up: Examples of Project Files - - Extending a Project - ------------------- - - A common situation in large software systems is to have multiple - implementations for a common interface; in Ada terms, multiple versions - of a package body for the same specification. For example, one - implementation might be safe for use in tasking programs, while another - might only be used in sequential applications. This can be modeled in - GNAT using the concept of _project extension_. If one project (the - "child") _extends_ another project (the "parent") then by default all - source files of the parent project are inherited by the child, but the - child project can override any of the parent's source files with new - versions, and can also add new files. This facility is the project - analog of extension in Object-Oriented Programming. Project - hierarchies are permitted (a child project may be the parent of yet - another project), and a project that inherits one project can also - import other projects. - - As an example, suppose that directory `/seq' contains the project - file `seq_proj.gpr' and the source files `PACK.ADS', `PACK.ADB', and - `PROC.ADB': - - /seq - PACK.ADS - PACK.ADB - PROC.ADB - seq_proj.gpr - - Note that the project file can simply be empty (that is, no attribute or - package is defined): - - project Seq_Proj is - end Seq_Proj; - - implying that its source files are all the Ada source files in the - project directory. - - Suppose we want to supply an alternate version of `PACK.ADB', in - directory `/tasking', but use the existing versions of `PACK.ADS' and - `PROC.ADB'. We can define a project `Tasking_Proj' that inherits - `Seq_Proj': - - /tasking - PACK.ADB - tasking_proj.gpr - - project Tasking_Proj extends "/seq/seq_proj" is - end Tasking_Proj; - - The version of `PACK.ADB' used in a build depends on which project file - is specified. - - Note that we could have designed this using project import rather - than project inheritance; a `base' project would contain the sources for - `PACK.ADS' and `PROC.ADB', a sequential project would import `base' and - add `PACK.ADB', and likewise a tasking project would import `base' and - add a different version of `PACK.ADB'. The choice depends on whether - other sources in the original project need to be overridden. If they - do, then project extension is necessary, otherwise, importing is - sufficient. - -  - File: gnat_ug_vms.info, Node: Project File Syntax, Next: Objects and Sources in Project Files, Prev: Examples of Project Files, Up: GNAT Project Manager - - Project File Syntax - =================== - - * Menu: - - * Basic Syntax:: - * Packages:: - * Expressions:: - * String Types:: - * Variables:: - * Attributes:: - * Associative Array Attributes:: - * case Constructions:: - - This section describes the structure of project files. - - A project may be an _independent project_, entirely defined by a - single project file. Any Ada source file in an independent project - depends only on the predefined library and other Ada source files in - the same project. - - A project may also "depend on" other projects, in either or both of the - following ways: - * It may import any number of projects - - * It may extend at most one other project - - The dependence relation is a directed acyclic graph (the subgraph - reflecting the "extends" relation is a tree). - - A project's "immediate sources" are the source files directly - defined by that project, either implicitly by residing in the project - file's directory, or explicitly through any of the source-related - attributes described below. More generally, a project PROJ's "sources" - are the immediate sources of PROJ together with the immediate sources - (unless overridden) of any project on which PROJ depends (either - directly or indirectly). - -  - File: gnat_ug_vms.info, Node: Basic Syntax, Next: Packages, Up: Project File Syntax - - Basic Syntax - ------------ - - As seen in the earlier examples, project files have an Ada-like syntax. - The minimal project file is: - project Empty is - - end Empty; - - The identifier `Empty' is the name of the project. This project name - must be present after the reserved word `end' at the end of the project - file, followed by a semi-colon. - - Any name in a project file, such as the project name or a variable - name, has the same syntax as an Ada identifier. - - The reserved words of project files are the Ada reserved words plus - `extends', `external', and `project'. Note that the only Ada reserved - words currently used in project file syntax are: - - * `case' - - * `end' - - * `for' - - * `is' - - * `others' - - * `package' - - * `renames' - - * `type' - - * `use' - - * `when' - - * `with' - - Comments in project files have the same syntax as in Ada, two - consecutives hyphens through the end of the line. - -  - File: gnat_ug_vms.info, Node: Packages, Next: Expressions, Prev: Basic Syntax, Up: Project File Syntax - - Packages - -------- - - A project file may contain _packages_. The name of a package must be one - of the identifiers (case insensitive) from a predefined list, and a - package with a given name may only appear once in a project file. The - predefined list includes the following packages: - - * `Naming' - - * `Builder' - - * `Compiler' - - * `Binder' - - * `Linker' - - * `Finder' - - * `Cross_Reference' - - * `GNAT LIST' - - (The complete list of the package names and their attributes can be - found in file `PRJ-ATTR.ADB'). - - In its simplest form, a package may be empty: - - project Simple is - package Builder is - end Builder; - end Simple; - - A package may contain _attribute declarations_, _variable declarations_ - and _case constructions_, as will be described below. - - When there is ambiguity between a project name and a package name, - the name always designates the project. To avoid possible confusion, it - is always a good idea to avoid naming a project with one of the names - allowed for packages or any name that starts with `gnat'. - -  - File: gnat_ug_vms.info, Node: Expressions, Next: String Types, Prev: Packages, Up: Project File Syntax - - Expressions - ----------- - - An _expression_ is either a _string expression_ or a _string list - expression_. - - A _string expression_ is either a _simple string expression_ or a - _compound string expression_. - - A _simple string expression_ is one of the following: - * A literal string; e.g.`"comm/my_proj.gpr"' - - * A string-valued variable reference (see *Note Variables::) - - * A string-valued attribute reference (see *Note Attributes::) - - * An external reference (see *Note External References in Project - Files::) - - A _compound string expression_ is a concatenation of string expressions, - using `"&"' - Path & "/" & File_Name & ".ADS" - - A _string list expression_ is either a _simple string list expression_ - or a _compound string list expression_. - - A _simple string list expression_ is one of the following: - * A parenthesized list of zero or more string expressions, separated - by commas - File_Names := (File_Name, "GNAT.ADC", File_Name & ".orig"); - Empty_List := (); - - * A string list-valued variable reference - - * A string list-valued attribute reference - - A _compound string list expression_ is the concatenation (using `"&"') - of a simple string list expression and an expression. Note that each - term in a compound string list expression, except the first, may be - either a string expression or a string list expression. - - File_Name_List := () & File_Name; -- One string in this list - Extended_File_Name_List := File_Name_List & (File_Name & ".orig"); - -- Two strings - Big_List := File_Name_List & Extended_File_Name_List; - -- Concatenation of two string lists: three strings - Illegal_List := "GNAT.ADC" & Extended_File_Name_List; - -- Illegal: must start with a string list - -  - File: gnat_ug_vms.info, Node: String Types, Next: Variables, Prev: Expressions, Up: Project File Syntax - - String Types - ------------ - - The value of a variable may be restricted to a list of string literals. - The restricted list of string literals is given in a _string type - declaration_. - - Here is an example of a string type declaration: - - type OS is ("NT, "nt", "Unix", "Linux", "other OS"); - - Variables of a string type are called _typed variables_; all other - variables are called _untyped variables_. Typed variables are - particularly useful in `case' constructions (see *Note case - Constructions::). - - A string type declaration starts with the reserved word `type', - followed by the name of the string type (case-insensitive), followed by - the reserved word `is', followed by a parenthesized list of one or more - string literals separated by commas, followed by a semicolon. - - The string literals in the list are case sensitive and must all be - different. They may include any graphic characters allowed in Ada, - including spaces. - - A string type may only be declared at the project level, not inside - a package. - - A string type may be referenced by its name if it has been declared - in the same project file, or by its project name, followed by a dot, - followed by the string type name. - -  - File: gnat_ug_vms.info, Node: Variables, Next: Attributes, Prev: String Types, Up: Project File Syntax - - Variables - --------- - - A variable may be declared at the project file level, or in a package. - Here are some examples of variable declarations: - - This_OS : OS := external ("OS"); -- a typed variable declaration - That_OS := "Linux"; -- an untyped variable declaration - - A _typed variable declaration_ includes the variable name, followed by - a colon, followed by the name of a string type, followed by `:=', - followed by a simple string expression. - - An _untyped variable declaration_ includes the variable name, - followed by `:=', followed by an expression. Note that, despite the - terminology, this form of "declaration" resembles more an assignment - than a declaration in Ada. It is a declaration in several senses: - * The variable name does not need to be defined previously - - * The declaration establishes the _kind_ (string versus string list) - of the variable, and later declarations of the same variable need - to be consistent with this - - A string variable declaration (typed or untyped) declares a variable - whose value is a string. This variable may be used as a string - expression. - File_Name := "readme.txt"; - Saved_File_Name := File_Name & ".saved"; - - A string list variable declaration declares a variable whose value is a - list of strings. The list may contain any number (zero or more) of - strings. - - Empty_List := (); - List_With_One_Element := ("/STYLE="); - List_With_Two_Elements := List_With_One_Element & "/STYLE=GNAT"; - Long_List := ("MAIN.ADA", "PACK1_.ADA", "PACK1.ADA", "PACK2_.ADA" - "PACK2.ADA", "UTIL_.ADA", "UTIL.ADA"); - - The same typed variable may not be declared more than once at project - level, and it may not be declared more than once in any package; it is - in effect a constant or a readonly variable. - - The same untyped variable may be declared several times. In this - case, the new value replaces the old one, and any subsequent reference - to the variable uses the new value. However, as noted above, if a - variable has been declared as a string, all subsequent declarations - must give it a string value. Similarly, if a variable has been declared - as a string list, all subsequent declarations must give it a string - list value. - - A _variable reference_ may take several forms: - - * The simple variable name, for a variable in the current package - (if any) or in the current project - - * A context name, followed by a dot, followed by the variable name. - - A _context_ may be one of the following: - - * The name of an existing package in the current project - - * The name of an imported project of the current project - - * The name of an ancestor project (i.e., a project extended by the - current project, either directly or indirectly) - - * An imported/parent project name, followed by a dot, followed by a - package name - - A variable reference may be used in an expression. - -  - File: gnat_ug_vms.info, Node: Attributes, Next: Associative Array Attributes, Prev: Variables, Up: Project File Syntax - - Attributes - ---------- - - A project (and its packages) may have _attributes_ that define the - project's properties. Some attributes have values that are strings; - others have values that are string lists. - - There are two categories of attributes: _simple attributes_ and - _associative arrays_ (see *Note Associative Array Attributes::). - - The names of the attributes are restricted; there is a list of - project attributes, and a list of package attributes for each package. - The names are not case sensitive. - - The project attributes are as follows (all are simple attributes): - - _Attribute Name_ _Value_ - `Source_Files' string list - `Source_Dirs' string list - `Source_List_File' string - `Object_Dir' string - `Exec_Dir' string - `Main' string list - `Languages' string list - `Library_Dir' string - `Library_Name' string - `Library_Kind' string - `Library_Elaboration' string - `Library_Version' string - - The attributes for package `Naming' are as follows (see *Note Naming - Schemes::): - - Attribute Name Category Index Value - `Specification_Suffix' associative language name string - array - `Implementation_Suffix' associative language name string - array - `Separate_Suffix' simple n/a string - attribute - `Casing' simple n/a string - attribute - `Dot_Replacement' simple n/a string - attribute - `Specification' associative Ada unit name string - array - `Implementation' associative Ada unit name string - array - `Specification_Exceptions' associative language name string list - array - `Implementation_Exceptions' associative language name string list - array - - The attributes for package `Builder', `Compiler', `Binder', `Linker', - `Cross_Reference', and `Finder' are as follows (see *Note Qualifiers - and Project Files::). - - Attribute Name Category Index Value - `Default_Qualifiers' associative language name string list - array - `Qualifiers' associative file name string list - array - - In addition, package `Builder' has a single string attribute - `Local_Configuration_Pragmas' and package `Builder' has a single string - attribute `Global_Configuration_Pragmas'. - - The attribute for package `Glide' are not documented: they are for - internal use only. - - Each simple attribute has a default value: the empty string (for - string-valued attributes) and the empty list (for string list-valued - attributes). - - Similar to variable declarations, an attribute declaration defines a - new value for an attribute. - - Examples of simple attribute declarations: - - for Object_Dir use "objects"; - for Source_Dirs use ("units", "test/drivers"); - - A "simple attribute declaration" starts with the reserved word `for', - followed by the name of the attribute, followed by the reserved word - `use', followed by an expression (whose kind depends on the attribute), - followed by a semicolon. - - Attributes may be referenced in expressions. The general form for - such a reference is `'': the entity for which the - attribute is defined, followed by an apostrophe, followed by the name - of the attribute. For associative array attributes, a litteral string - between parentheses need to be supplied as index. - - Examples are: - - project'Object_Dir - Naming'Dot_Replacement - Imported_Project'Source_Dirs - Imported_Project.Naming'Casing - Builder'Default_Qualifiers("Ada") - - The entity may be: - * `project' for an attribute of the current project - - * The name of an existing package of the current project - - * The name of an imported project - - * The name of a parent project (extended by the current project) - - * An imported/parent project name, followed by a dot, followed - by a package name - - Example: - project Prj is - for Source_Dirs use project'Source_Dirs & "units"; - for Source_Dirs use project'Source_Dirs & "test/drivers" - end Prj; - - In the first attribute declaration, initially the attribute - `Source_Dirs' has the default value: an empty string list. After this - declaration, `Source_Dirs' is a string list of one element: "units". - After the second attribute declaration `Source_Dirs' is a string list of - two elements: "units" and "test/drivers". - - Note: this example is for illustration only. In practice, the - project file would contain only one attribute declaration: - - for Source_Dirs use ("units", "test/drivers"); - -  - File: gnat_ug_vms.info, Node: Associative Array Attributes, Next: case Constructions, Prev: Attributes, Up: Project File Syntax - - Associative Array Attributes - ---------------------------- - - Some attributes are defined as _associative arrays_. An associative - array may be regarded as a function that takes a string as a parameter - and delivers a string or string list value as its result. - - Here are some examples of associative array attribute declarations: - - for Implementation ("main") use "MAIN.ADA"; - for Qualifiers ("MAIN.ADA") use ("-v", "/REPORT_ERRORS=VERBOSE"); - for Qualifiers ("MAIN.ADA") use Builder'Qualifiers ("MAIN.ADA") & "-g"; - - Like untyped variables and simple attributes, associative array - attributes may be declared several times. Each declaration supplies a - new value for the attribute, replacing the previous setting. - -  - File: gnat_ug_vms.info, Node: case Constructions, Prev: Associative Array Attributes, Up: Project File Syntax - - `case' Constructions - -------------------- - - A `case' construction is used in a project file to effect conditional - behavior. Here is a typical example: - - project MyProj is - type OS_Type is ("Linux", "Unix", "NT", "VMS"); - - OS : OS_Type := external ("OS", "Linux"); - - package Compiler is - case OS is - when "Linux" | "Unix" => - for Default_Qualifiers ("Ada") use ("-gnath"); - when "NT" => - for Default_Qualifiers ("Ada") use ("/POLLING_ENABLE"); - when others => - end case; - end Compiler; - end MyProj; - - The syntax of a `case' construction is based on the Ada case statement - (although there is no `null' construction for empty alternatives). - - Following the reserved word `case' there is the case variable (a - typed string variable), the reserved word `is', and then a sequence of - one or more alternatives. Each alternative comprises the reserved word - `when', either a list of literal strings separated by the `"|"' - character or the reserved word `others', and the `"=>"' token. Each - literal string must belong to the string type that is the type of the - case variable. An `others' alternative, if present, must occur last. - The `end case;' sequence terminates the case construction. - - After each `=>', there are zero or more constructions. The only - constructions allowed in a case construction are other case - constructions and attribute declarations. String type declarations, - variable declarations and package declarations are not allowed. - - The value of the case variable is often given by an external - reference (see *Note External References in Project Files::). - -  - File: gnat_ug_vms.info, Node: Objects and Sources in Project Files, Next: Importing Projects, Prev: Project File Syntax, Up: GNAT Project Manager - - Objects and Sources in Project Files - ==================================== - - * Menu: - - * Object Directory:: - * Exec Directory:: - * Source Directories:: - * Source File Names:: - - Each project has exactly one object directory and one or more source - directories. The source directories must contain at least one source - file, unless the project file explicitly specifies that no source - files are present (see *Note Source File Names::). - -  - File: gnat_ug_vms.info, Node: Object Directory, Next: Exec Directory, Up: Objects and Sources in Project Files - - Object Directory - ---------------- - - The object directory for a project is the directory containing the - compiler's output (such as `ALI' files and object files) for the - project's immediate sources. Note that for inherited sources (when - extending a parent project) the parent project's object directory is - used. - - The object directory is given by the value of the attribute - `Object_Dir' in the project file. - - for Object_Dir use "objects"; - - The attribute OBJECT_DIR has a string value, the path name of the object - directory. The path name may be absolute or relative to the directory - of the project file. This directory must already exist, and be readable - and writable. - - By default, when the attribute `Object_Dir' is not given an explicit - value or when its value is the empty string, the object directory is - the same as the directory containing the project file. - -  - File: gnat_ug_vms.info, Node: Exec Directory, Next: Source Directories, Prev: Object Directory, Up: Objects and Sources in Project Files - - Exec Directory - -------------- - - The exec directory for a project is the directory containing the - executables for the project's main subprograms. - - The exec directory is given by the value of the attribute `Exec_Dir' - in the project file. - - for Exec_Dir use "executables"; - - The attribute EXEC_DIR has a string value, the path name of the exec - directory. The path name may be absolute or relative to the directory - of the project file. This directory must already exist, and be writable. - - By default, when the attribute `Exec_Dir' is not given an explicit - value or when its value is the empty string, the exec directory is the - same as the object directory of the project file. - -  - File: gnat_ug_vms.info, Node: Source Directories, Next: Source File Names, Prev: Exec Directory, Up: Objects and Sources in Project Files - - Source Directories - ------------------ - - The source directories of a project are specified by the project file - attribute `Source_Dirs'. - - This attribute's value is a string list. If the attribute is not - given an explicit value, then there is only one source directory, the - one where the project file resides. - - A `Source_Dirs' attribute that is explicitly defined to be the empty - list, as in - - for Source_Dirs use (); - - indicates that the project contains no source files. - - Otherwise, each string in the string list designates one or more - source directories. - - for Source_Dirs use ("sources", "test/drivers"); - - If a string in the list ends with `"/**"', then the directory whose - path name precedes the two asterisks, as well as all its subdirectories - (recursively), are source directories. - - for Source_Dirs use ("/system/sources/**"); - - Here the directory `/system/sources' and all of its subdirectories - (recursively) are source directories. - - To specify that the source directories are the directory of the - project file and all of its subdirectories, you can declare - `Source_Dirs' as follows: - for Source_Dirs use ("./**"); - - Each of the source directories must exist and be readable. - -  - File: gnat_ug_vms.info, Node: Source File Names, Prev: Source Directories, Up: Objects and Sources in Project Files - - Source File Names - ----------------- - - In a project that contains source files, their names may be specified - by the attributes `Source_Files' (a string list) or `Source_List_File' - (a string). Source file names never include any directory information. - - If the attribute `Source_Files' is given an explicit value, then each - element of the list is a source file name. - - for Source_Files use ("MAIN.ADB"); - for Source_Files use ("MAIN.ADB", "PACK1.ADS", "PACK2.ADB"); - - If the attribute `Source_Files' is not given an explicit value, but the - attribute `Source_List_File' is given a string value, then the source - file names are contained in the text file whose path name (absolute or - relative to the directory of the project file) is the value of the - attribute `Source_List_File'. - - Each line in the file that is not empty or is not a comment contains - a source file name. A comment line starts with two hyphens. - - for Source_List_File use "source_list.txt"; - - By default, if neither the attribute `Source_Files' nor the attribute - `Source_List_File' is given an explicit value, then each file in the - source directories that conforms to the project's naming scheme (see - *Note Naming Schemes::) is an immediate source of the project. - - A warning is issued if both attributes `Source_Files' and - `Source_List_File' are given explicit values. In this case, the - attribute `Source_Files' prevails. - - Each source file name must be the name of one and only one existing - source file in one of the source directories. - - A `Source_Files' attribute defined with an empty list as its value - indicates that there are no source files in the project. - - Except for projects that are clearly specified as containing no Ada - source files (`Source_Dirs' or `Source_Files' specified as an empty - list, or `Languages' specified without `"Ada"' in the list) - for Source_Dirs use (); - for Source_Files use (); - for Languages use ("C", "C++"); - - a project must contain at least one immediate source. - - Projects with no source files are useful as template packages (see - *Note Packages in Project Files::) for other projects; in particular to - define a package `Naming' (see *Note Naming Schemes::). - -  - File: gnat_ug_vms.info, Node: Importing Projects, Next: Project Extension, Prev: Objects and Sources in Project Files, Up: GNAT Project Manager - - Importing Projects - ================== - - An immediate source of a project P may depend on source files that are - neither immediate sources of P nor in the predefined library. To get - this effect, P must _import_ the projects that contain the needed - source files. - - with "project1", "utilities.gpr"; - with "/namings/apex.gpr"; - project Main is - ... - - As can be seen in this example, the syntax for importing projects is - similar to the syntax for importing compilation units in Ada. However, - project files use literal strings instead of names, and the `with' - clause identifies project files rather than packages. - - Each literal string is the file name or path name (absolute or - relative) of a project file. If a string is simply a file name, with no - path, then its location is determined by the _project path_: - - * If the environment variable `ADA_PROJECT_PATH' exists, then the - project path includes all the directories in this environment - variable, plus the directory of the project file. - - * If the environment variable `ADA_PROJECT_PATH' does not exist, - then the project path contains only one directory, namely the one - where the project file is located. - - If a relative pathname is used as in - - with "tests/proj"; - - then the path is relative to the directory where the importing project - file is located. Any symbolic link will be fully resolved in the - directory of the importing project file before the imported project - file is looked up. - - When the `with''ed project file name does not have an extension, the - default is `.gpr'. If a file with this extension is not found, then the - file name as specified in the `with' clause (no extension) will be - used. In the above example, if a file `project1.gpr' is found, then it - will be used; otherwise, if a file `project1' exists then it will be - used; if neither file exists, this is an error. - - A warning is issued if the name of the project file does not match - the name of the project; this check is case insensitive. - - Any source file that is an immediate source of the imported project - can be used by the immediate sources of the importing project, and - recursively. Thus if `A' imports `B', and `B' imports `C', the immediate - sources of `A' may depend on the immediate sources of `C', even if `A' - does not import `C' explicitly. However, this is not recommended, - because if and when `B' ceases to import `C', some sources in `A' will - no longer compile. - - A side effect of this capability is that cyclic dependences are not - permitted: if `A' imports `B' (directly or indirectly) then `B' is not - allowed to import `A'. - -  - File: gnat_ug_vms.info, Node: Project Extension, Next: External References in Project Files, Prev: Importing Projects, Up: GNAT Project Manager - - Project Extension - ================= - - During development of a large system, it is sometimes necessary to use - modified versions of some of the source files without changing the - original sources. This can be achieved through a facility known as - _project extension_. - - project Modified_Utilities extends "/baseline/utilities.gpr" is ... - - The project file for the project being extended (the _parent_) is - identified by the literal string that follows the reserved word - `extends', which itself follows the name of the extending project (the - _child_). - - By default, a child project inherits all the sources of its parent. - However, inherited sources can be overridden: a unit with the same name - as one in the parent will hide the original unit. Inherited sources - are considered to be sources (but not immediate sources) of the child - project; see *Note Project File Syntax::. - - An inherited source file retains any qualifiers specified in the - parent project. - - For example if the project `Utilities' contains the specification - and the body of an Ada package `Util_IO', then the project - `Modified_Utilities' can contain a new body for package `Util_IO'. The - original body of `Util_IO' will not be considered in program builds. - However, the package specification will still be found in the project - `Utilities'. - - A child project can have only one parent but it may import any - number of other projects. - - A project is not allowed to import directly or indirectly at the - same time a child project and any of its ancestors. - -  - File: gnat_ug_vms.info, Node: External References in Project Files, Next: Packages in Project Files, Prev: Project Extension, Up: GNAT Project Manager - - External References in Project Files - ==================================== - - A project file may contain references to external variables; such - references are called _external references_. - - An external variable is either defined as part of the environment (an - environment variable in Unix, for example) or else specified on the - command line via the `-X_vbl_=_value_' qualifier. If both, then the - command line value is used. - - An external reference is denoted by the built-in function - `external', which returns a string value. This function has two forms: - * `external (external_variable_name)' - - * `external (external_variable_name, default_value)' - - Each parameter must be a string literal. For example: - - external ("USER") - external ("OS", "Linux") - - In the form with one parameter, the function returns the value of the - external variable given as parameter. If this name is not present in the - environment, then the returned value is an empty string. - - In the form with two string parameters, the second parameter is the - value returned when the variable given as the first parameter is not - present in the environment. In the example above, if `"OS"' is not the - name of an environment variable and is not passed on the command line, - then the returned value will be `"Linux"'. - - An external reference may be part of a string expression or of a - string list expression, to define variables or attributes. - - type Mode_Type is ("Debug", "Release"); - Mode : Mode_Type := external ("MODE"); - case Mode is - when "Debug" => - ... - -  - File: gnat_ug_vms.info, Node: Packages in Project Files, Next: Variables from Imported Projects, Prev: External References in Project Files, Up: GNAT Project Manager - - Packages in Project Files - ========================= - - The _package_ is the project file feature that defines the settings for - project-aware tools. For each such tool you can declare a - corresponding package; the names for these packages are preset (see - *Note Packages::) but are not case sensitive. A package may contain - variable declarations, attribute declarations, and case constructions. - - project Proj is - package Builder is -- used by GNAT MAKE - for Default_Qualifiers ("Ada") use ("-v", "-g"); - end Builder; - end Proj; - - A package declaration starts with the reserved word `package', followed - by the package name (case insensitive), followed by the reserved word - `is'. It ends with the reserved word `end', followed by the package - name, finally followed by a semi-colon. - - Most of the packages have an attribute `Default_Qualifiers'. This - attribute is an associative array, and its value is a string list. The - index of the associative array is the name of a programming language - (case insensitive). This attribute indicates the qualifier or - qualifiers to be used with the corresponding tool. - - Some packages also have another attribute, `Qualifiers', an - associative array whose value is a string list. The index is the name - of a source file. This attribute indicates the qualifier or qualifiers - to be used by the corresponding tool when dealing with this specific - file. - - Further information on these qualifier-related attributes is found in - *Note Qualifiers and Project Files::. - - A package may be declared as a _renaming_ of another package; e.g., - from the project file for an imported project. - - with "/global/apex.gpr"; - project Example is - package Naming renames Apex.Naming; - ... - end Example; - - Packages that are renamed in other project files often come from - project files that have no sources: they are just used as templates. - Any modification in the template will be reflected automatically in all - the project files that rename a package from the template. - - In addition to the tool-oriented packages, you can also declare a - package named `Naming' to establish specialized source file naming - conventions (see *Note Naming Schemes::). - -  - File: gnat_ug_vms.info, Node: Variables from Imported Projects, Next: Naming Schemes, Prev: Packages in Project Files, Up: GNAT Project Manager - - Variables from Imported Projects - ================================ - - An attribute or variable defined in an imported or parent project can - be used in expressions in the importing / extending project. Such an - attribute or variable is prefixed with the name of the project and (if - relevant) the name of package where it is defined. - - with "imported"; - project Main extends "base" is - Var1 := Imported.Var; - Var2 := Base.Var & ".new"; - - package Builder is - for Default_Qualifiers ("Ada") use Imported.Builder.Ada_Qualifiers & - "/STYLE=GNAT" & "-v"; - end Builder; - - package Compiler is - for Default_Qualifiers ("Ada") use Base.Compiler.Ada_Qualifiers; - end Compiler; - end Main; - - In this example: - - * `Var1' is a copy of the variable `Var' defined in the project file - `"imported.gpr"' - - * the value of `Var2' is a copy of the value of variable `Var' - defined in the project file `base.gpr', concatenated with `".new"' - - * attribute `Default_Qualifiers ("Ada")' in package `Builder' is a - string list that includes in its value a copy of variable - `Ada_Qualifiers' defined in the `Builder' package in project file - `imported.gpr' plus two new elements: `"/STYLE=GNAT"' and `"-v"'; - - * attribute `Default_Qualifiers ("Ada")' in package `Compiler' is a - copy of the variable `Ada_Qualifiers' defined in the `Compiler' - package in project file `base.gpr', the project being extended. - -  - File: gnat_ug_vms.info, Node: Naming Schemes, Next: Library Projects, Prev: Variables from Imported Projects, Up: GNAT Project Manager - - Naming Schemes - ============== - - Sometimes an Ada software system is ported from a foreign compilation - environment to GNAT, with file names that do not use the default GNAT - conventions. Instead of changing all the file names (which for a - variety of reasons might not be possible), you can define the relevant - file naming scheme in the `Naming' package in your project file. For - example, the following package models the Apex file naming rules: - - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "."; - for Specification_Suffix ("Ada") use ".1.ADA"; - for Implementation_Suffix ("Ada") use ".2.ADA"; - end Naming; - - You can define the following attributes in package `Naming': - - `CASING' - This must be a string with one of the three values `"lowercase"', - `"uppercase"' or `"mixedcase"'; these strings are case insensitive. - - If CASING is not specified, then the default is `"lowercase"'. - - `DOT_REPLACEMENT' - This must be a string whose value satisfies the following - conditions: - - * It must not be empty - - * It cannot start or end with an alphanumeric character - - * It cannot be a single underscore - - * It cannot start with an underscore followed by an alphanumeric - - * It cannot contain a dot `'.'' except if it the entire string - is `"."' - - If `Dot_Replacement' is not specified, then the default is `"-"'. - - `SPECIFICATION_SUFFIX' - This is an associative array (indexed by the programming language - name, case insensitive) whose value is a string that must satisfy - the following conditions: - - * It must not be empty - - * It cannot start with an alphanumeric character - - * It cannot start with an underscore followed by an - alphanumeric character - - If `Specification_Suffix ("Ada")' is not specified, then the - default is `".ADS"'. - - `IMPLEMENTATION_SUFFIX' - This is an associative array (indexed by the programming language - name, case insensitive) whose value is a string that must satisfy - the following conditions: - - * It must not be empty - - * It cannot start with an alphanumeric character - - * It cannot start with an underscore followed by an - alphanumeric character - - * It cannot be a suffix of `Specification_Suffix' - - If `Implementation_Suffix ("Ada")' is not specified, then the - default is `".ADB"'. - - `SEPARATE_SUFFIX' - This must be a string whose value satisfies the same conditions as - `Implementation_Suffix'. - - If `Separate_Suffix ("Ada")' is not specified, then it defaults to - same value as `Implementation_Suffix ("Ada")'. - - `SPECIFICATION' - You can use the `Specification' attribute, an associative array, - to define the source file name for an individual Ada compilation - unit's spec. The array index must be a string literal that - identifies the Ada unit (case insensitive). The value of this - attribute must be a string that identifies the file that contains - this unit's spec (case sensitive or insensitive depending on the - operating system). - - for Specification ("MyPack.MyChild") use "mypack.mychild.spec"; - - `IMPLEMENTATION' - You can use the `Implementation' attribute, an associative array, - to define the source file name for an individual Ada compilation - unit's body (possibly a subunit). The array index must be a - string literal that identifies the Ada unit (case insensitive). - The value of this attribute must be a string that identifies the - file that contains this unit's body or subunit (case sensitive or - insensitive depending on the operating system). - - for Implementation ("MyPack.MyChild") use "mypack.mychild.body"; - -  - File: gnat_ug_vms.info, Node: Library Projects, Next: Qualifiers Related to Project Files, Prev: Naming Schemes, Up: GNAT Project Manager - - Library Projects - ================ - - _Library projects_ are projects whose object code is placed in a - library. (Note that this facility is not yet supported on all - platforms) - - To create a library project, you need to define in its project file - two project-level attributes: `Library_Name' and `Library_Dir'. - Additionally, you may define the library-related attributes - `Library_Kind', `Library_Version' and `Library_Elaboration'. - - The `Library_Name' attribute has a string value that must start with - a letter and include only letters and digits. - - The `Library_Dir' attribute has a string value that designates the - path (absolute or relative) of the directory where the library will - reside. It must designate an existing directory, and this directory - needs to be different from the project's object directory. It also - needs to be writable. - - If both `Library_Name' and `Library_Dir' are specified and are - legal, then the project file defines a library project. The optional - library-related attributes are checked only for such project files. - - The `Library_Kind' attribute has a string value that must be one of - the following (case insensitive): `"static"', `"dynamic"' or - `"relocatable"'. If this attribute is not specified, the library is a - static library. Otherwise, the library may be dynamic or relocatable. - Depending on the operating system, there may or may not be a distinction - between dynamic and relocatable libraries. For example, on Unix there - is no such distinction. - - The `Library_Version' attribute has a string value whose - interpretation is platform dependent. On Unix, it is used only for - dynamic/relocatable libraries as the internal name of the library (the - `"soname"'). If the library file name (built from the `Library_Name') - is different from the `Library_Version', then the library file will be - a symbolic link to the actual file whose name will be `Library_Version'. - - Example (on Unix): - - project Plib is - - Version := "1"; - - for Library_Dir use "lib_dir"; - for Library_Name use "dummy"; - for Library_Kind use "relocatable"; - for Library_Version use "libdummy.so." & Version; - - end Plib; - - Directory `lib_dir' will contain the internal library file whose name - will be `libdummy.so.1', and `libdummy.so' will be a symbolic link to - `libdummy.so.1'. - - When `GNAT MAKE' detects that a project file (not the main project - file) is a library project file, it will check all immediate sources of - the project and rebuild the library if any of the sources have been - recompiled. All `ALI' files will also be copied from the object - directory to the library directory. To build executables, `GNAT MAKE' - will use the library rather than the individual object files. - -  - File: gnat_ug_vms.info, Node: Qualifiers Related to Project Files, Next: Tools Supporting Project Files, Prev: Library Projects, Up: GNAT Project Manager - - Qualifiers Related to Project Files - =================================== - - The following qualifiers are used by GNAT tools that support project - files: - - ``-PPROJECT'' - Indicates the name of a project file. This project file will be - parsed with the verbosity indicated by `-vP_x_', if any, and using - the external references indicated by `-X' qualifiers, if any. - - There must be only one `-P' qualifier on the command line. - - Since the Project Manager parses the project file only after all - the qualifiers on the command line are checked, the order of the - qualifiers `-P', `-Vp_x_' or `-X' is not significant. - - ``-XNAME=VALUE'' - Indicates that external variable NAME has the value VALUE. The - Project Manager will use this value for occurrences of - `external(name)' when parsing the project file. - - If NAME or VALUE includes a space, then NAME=VALUE should be put - between quotes. - -XOS=NT - -X"user=John Doe" - - Several `-X' qualifiers can be used simultaneously. If several - `-X' qualifiers specify the same NAME, only the last one is used. - - An external variable specified with a `-X' qualifier takes - precedence over the value of the same name in the environment. - - ``-vP_x_'' - Indicates the verbosity of the parsing of GNAT project files. - `-vP0' means Default (no output for syntactically correct project - files); `-vP1' means Medium; `-vP2' means High. - - The default is Default. - - If several `-vP_x_' qualifiers are present, only the last one is - used. - -  - File: gnat_ug_vms.info, Node: Tools Supporting Project Files, Next: An Extended Example, Prev: Qualifiers Related to Project Files, Up: GNAT Project Manager - - Tools Supporting Project Files - ============================== - - * Menu: - - * GNAT MAKE and Project Files:: - * The GNAT Driver and Project Files:: - -  - File: gnat_ug_vms.info, Node: GNAT MAKE and Project Files, Next: The GNAT Driver and Project Files, Up: Tools Supporting Project Files - - GNAT MAKE and Project Files - --------------------------- - - This section covers two topics related to `GNAT MAKE' and project files: - defining qualifiers for `GNAT MAKE' and for the tools that it invokes; - and the use of the `Main' attribute. - - * Menu: - - * Qualifiers and Project Files:: - * Project Files and Main Subprograms:: - -  - File: gnat_ug_vms.info, Node: Qualifiers and Project Files, Next: Project Files and Main Subprograms, Up: GNAT MAKE and Project Files - - Qualifiers and Project Files - ............................ - - For each of the packages `Builder', `Compiler', `Binder', and `Linker', - you can specify a `Default_Qualifiers' attribute, a `Qualifiers' - attribute, or both; as their names imply, these qualifier-related - attributes affect which qualifiers are used for which files when `GNAT - MAKE' is invoked. As will be explained below, these - package-contributed qualifiers precede the qualifiers passed on the - `GNAT MAKE' command line. - - The `Default_Qualifiers' attribute is an associative array indexed by - language name (case insensitive) and returning a string list. For - example: - - package Compiler is - for Default_Qualifiers ("Ada") use ("/STYLE=", "-v"); - end Compiler; - - The `Qualifiers' attribute is also an associative array, indexed by a - file name (which may or may not be case sensitive, depending on the - operating system) and returning a string list. For example: - - package Builder is - for Qualifiers ("MAIN1.ADB") use ("/OPTIMIZE=ALL"); - for Qualifiers ("MAIN2.ADB") use ("-g"); - end Builder; - - For the `Builder' package, the file names should designate source files - for main subprograms. For the `Binder' and `Linker' packages, the file - names should designate `ALI' or source files for main subprograms. In - each case just the file name (without explicit extension) is acceptable. - - For each tool used in a program build (`GNAT MAKE', the compiler, the - binder, and the linker), its corresponding package "contributes" a set - of qualifiers for each file on which the tool is invoked, based on the - qualifier-related attributes defined in the package. In particular, the - qualifiers that each of these packages contributes for a given file F - comprise: - - * the value of attribute `Qualifiers (F)', if it is specified in the - package for the given file, - - * otherwise, the value of `Default_Qualifiers ("Ada")', if it is - specified in the package. - - If neither of these attributes is defined in the package, then the - package does not contribute any qualifiers for the given file. - - When `GNAT MAKE' is invoked on a file, the qualifiers comprise two - sets, in the following order: those contributed for the file by the - `Builder' package; and the qualifiers passed on the command line. - - When `GNAT MAKE' invokes a tool (compiler, binder, linker) on a file, - the qualifiers passed to the tool comprise three sets, in the following - order: - - 1. the applicable qualifiers contributed for the file by the - `Builder' package in the project file supplied on the command line; - - 2. those contributed for the file by the package (in the relevant - project file - see below) corresponding to the tool; and - - 3. the applicable qualifiers passed on the command line. - - The term _applicable qualifiers_ reflects the fact that `GNAT MAKE' - qualifiers may or may not be passed to individual tools, depending on - the individual qualifier. - - `GNAT MAKE' may invoke the compiler on source files from different - projects. The Project Manager will use the appropriate project file to - determine the `Compiler' package for each source file being compiled. - Likewise for the `Binder' and `Linker' packages. - - As an example, consider the following package in a project file: - - project Proj1 is - package Compiler is - for Default_Qualifiers ("Ada") use ("-g"); - for Qualifiers ("A.ADB") use ("/OPTIMIZE=SOME"); - for Qualifiers ("B.ADB") use ("/OPTIMIZE=ALL", "/STYLE="); - end Compiler; - end Proj1; - - If `GNAT MAKE' is invoked with this project file, and it needs to - compile, say, the files `A.ADB', `B.ADB', and `C.ADB', then `A.ADB' - will be compiled with the qualifier `/OPTIMIZE=SOME', `B.ADB' with - qualifiers `/OPTIMIZE=ALL' and `/STYLE=', and `C.ADB' with `-g'. - - Another example illustrates the ordering of the qualifiers - contributed by different packages: - - project Proj2 is - package Builder is - for Qualifiers ("MAIN.ADB") use ("-g", "/OPTIMIZE=SOME", "-f"); - end Builder; - - package Compiler is - for Qualifiers ("MAIN.ADB") use ("/OPTIMIZE=ALL"); - end Compiler; - end Proj2; - - If you issue the command: - - GNAT MAKE -PProj2 /OPTIMIZE=NONE main - - then the compiler will be invoked on `MAIN.ADB' with the following - sequence of qualifiers - - -g /OPTIMIZE=SOME /OPTIMIZE=ALL /OPTIMIZE=NONE - - with the last `-O' qualifier having precedence over the earlier ones; - several other qualifiers (such as `-c') are added implicitly. - - The qualifiers `-g' and `/OPTIMIZE=SOME' are contributed by package - `Builder', `/OPTIMIZE=ALL' is contributed by the package `Compiler' - and `/OPTIMIZE=NONE' comes from the command line. - - The `-g' qualifier will also be passed in the invocation of `GNAT - LINK.' - - A final example illustrates qualifier contributions from packages in - different project files: - - project Proj3 is - for Source_Files use ("PACK.ADS", "PACK.ADB"); - package Compiler is - for Default_Qualifiers ("Ada") use ("/CHECKS=ASSERTIONS"); - end Compiler; - end Proj3; - - with "Proj3"; - project Proj4 is - for Source_Files use ("FOO_MAIN.ADB", "BAR_MAIN.ADB"); - package Builder is - for Qualifiers ("FOO_MAIN.ADB") use ("-s", "-g"); - end Builder; - end Proj4; - - -- Ada source file: - with Pack; - procedure Foo_Main is - ... - end Foo_Main; - - If the command is - GNAT MAKE -PProj4 FOO_MAIN.ADB /COMPILER_QUALIFIERS /CHECKS=OVERFLOW - - then the qualifiers passed to the compiler for `FOO_MAIN.ADB' are `-g' - (contributed by the package `Proj4.Builder') and `/CHECKS=OVERFLOW' - (passed on the command line). When the imported package `Pack' is - compiled, the qualifiers used are `-g' from `Proj4.Builder', - `/CHECKS=ASSERTIONS' (contributed from package `Proj3.Compiler', and - `/CHECKS=OVERFLOW' from the command line. - -  - File: gnat_ug_vms.info, Node: Project Files and Main Subprograms, Prev: Qualifiers and Project Files, Up: GNAT MAKE and Project Files - - Project Files and Main Subprograms - .................................. - - When using a project file, you can invoke `GNAT MAKE' with several main - subprograms, by specifying their source files on the command line. - Each of these needs to be an immediate source file of the project. - - GNAT MAKE -Pprj main1 main2 main3 - - When using a project file, you can also invoke `GNAT MAKE' without - explicitly specifying any main, and the effect depends on whether you - have defined the `Main' attribute. This attribute has a string list - value, where each element in the list is the name of a source file (the - file extension is optional) containing a main subprogram. - - If the `Main' attribute is defined in a project file as a non-empty - string list and the qualifier `-u' is not used on the command line, then - invoking `GNAT MAKE' with this project file but without any main on the - command line is equivalent to invoking `GNAT MAKE' with all the file - names in the `Main' attribute on the command line. - - Example: - project Prj is - for Main use ("main1", "main2", "main3"); - end Prj; - - With this project file, `"GNAT MAKE -Pprj"' is equivalent to `"GNAT - MAKE -Pprj main1 main2 main3"'. - - When the project attribute `Main' is not specified, or is specified - as an empty string list, or when the qualifier `-u' is used on the - command line, then invoking `GNAT MAKE' with no main on the command - line will result in all immediate sources of the project file being - checked, and potentially recompiled. Depending on the presence of the - qualifier `-u', sources from other project files on which the immediate - sources of the main project file depend are also checked and - potentially recompiled. In other words, the `-u' qualifier is applied - to all of the immediate sources of themain project file. - -  - File: gnat_ug_vms.info, Node: The GNAT Driver and Project Files, Prev: GNAT MAKE and Project Files, Up: Tools Supporting Project Files - - The GNAT Driver and Project Files - --------------------------------- - - A number of GNAT tools, other than `GNAT MAKE' are project-aware: `GNAT - BIND', `GNAT FIND', `GNAT LINK', `GNAT LIST' and `GNAT XREF'. However, - none of these tools can be invoked directly with a project file - qualifier (`-P'). They need to be invoke through the `gnat' driver. - - The `gnat' driver is a front-end that accepts a number of commands - and call the corresponding tool. It has been designed initially for VMS - to convert VMS style qualifiers to Unix style qualifiers, but it is now - available to all the GNAT supported platforms. - - On non VMS platforms, the `gnat' driver accepts the following - commands (case insensitive): - - * BIND to invoke `GNAT BIND' - - * CHOP to invoke `GNAT CHOP' - - * COMP or COMPILE to invoke the compiler - - * ELIM to invoke `GNAT ELIM' - - * FIND to invoke `GNAT FIND' - - * KR or KRUNCH to invoke `GNAT KRUNCH' - - * LINK to invoke `GNAT LINK' - - * LS or LIST to invoke `GNAT LIST' - - * MAKE to invoke `GNAT MAKE' - - * NAME to invoke `gnatname' - - * PREP or PREPROCESS to invoke `GNAT PREPROCESS' - - * PSTA or STANDARD to invoke `GNAT STANDARD' - - * STUB to invoke `GNAT STUB' - - * XREF to invoke `GNAT XREF' - - Note that the compiler is invoked using the command `GNAT MAKE -f -u'. - - Following the command, you may put qualifiers and arguments for the - invoked tool. - - gnat bind -C MAIN.ALI - gnat ls -a main - gnat chop foo.txt - - In addition, for command BIND, FIND, LS or LIST, LINK and XREF, the - project file related qualifiers (`-P', `-X' and `-vPx') may be used in - addition to the qualifiers of the invoking tool. - - For each of these command, there is possibly a package in the main - project that corresponds to the invoked tool. - - * package `Binder' for command BIND (invoking `GNAT BIND') - - * package `Finder' for command FIND (invoking `GNAT FIND') - - * package `GNAT LIST' for command LS or LIST (invoking `GNAT LIST') - - * package `Linker' for command LINK (invoking `GNAT LINK') - - * package `Cross_Reference' for command XREF (invoking `GNAT LINK') - - - Package `GNAT LIST' has a unique attribute `Qualifiers', a simple - variable with a string list value. It contains qualifiers for the - invocation of `GNAT LIST'. - - project Proj1 is - package GNAT LIST is - for Qualifiers use ("-a", "-v"); - end GNAT LIST; - end Proj1; - - All other packages contains a qualifier `Default_Qualifiers', an - associative array, indexed by the programming language (case - insensitive) and having a string list value. `Default_Qualifiers - ("Ada")' contains the qualifiers for the invocation of the tool - corresponding to the package. - - project Proj is - - for Source_Dirs use ("./**"); - - package GNAT LIST is - for Qualifiers use ("-a", "-v"); - end GNAT LIST; - - package Binder is - for Default_Qualifiers ("Ada") use ("-C", "-e"); - end Binder; - - package Linker is - for Default_Qualifiers ("Ada") use ("-C"); - end Linker; - - package Finder is - for Default_Qualifiers ("Ada") use ("-a", "-f"); - end Finder; - - package Cross_Reference is - for Default_Qualifiers ("Ada") use ("-a", "-f", "-d", "-u"); - end Cross_Reference; - end Proj; - - With the above project file, commands such as - - gnat ls -Pproj main - gnat xref -Pproj main - gnat bind -Pproj MAIN.ALI - - will set up the environment properly and invoke the tool with the - qualifiers found in the package corresponding to the tool. - -  - File: gnat_ug_vms.info, Node: An Extended Example, Next: Project File Complete Syntax, Prev: Tools Supporting Project Files, Up: GNAT Project Manager - - An Extended Example - =================== - - Suppose that we have two programs, PROG1 and PROG2, with the sources in - the respective directories. We would like to build them with a single - `GNAT MAKE' command, and we would like to place their object files into - `.build' subdirectories of the source directories. Furthermore, we would - like to have to have two separate subdirectories in `.build' - - `release' and `debug' - which will contain the object files compiled - with different set of compilation flags. - - In other words, we have the following structure: - - main - |- prog1 - | |- .build - | | debug - | | release - |- prog2 - |- .build - | debug - | release - - Here are the project files that we need to create in a directory `main' - to maintain this structure: - - 1. We create a `Common' project with a package `Compiler' that - specifies the compilation qualifiers: - - File "common.gpr": - project Common is - - for Source_Dirs use (); -- No source files - - type Build_Type is ("release", "debug"); - Build : Build_Type := External ("BUILD", "debug"); - package Compiler is - case Build is - when "release" => - for Default_Qualifiers ("Ada") use ("/OPTIMIZE=ALL"); - when "debug" => - for Default_Qualifiers ("Ada") use ("-g"); - end case; - end Compiler; - - end Common; - - 2. We create separate projects for the two programs: - - File "prog1.gpr": - - with "common"; - project Prog1 is - - for Source_Dirs use ("prog1"); - for Object_Dir use "prog1/.build/" & Common.Build; - - package Compiler renames Common.Compiler; - - end Prog1; - - File "prog2.gpr": - - with "common"; - project Prog2 is - - for Source_Dirs use ("prog2"); - for Object_Dir use "prog2/.build/" & Common.Build; - - package Compiler renames Common.Compiler; - end Prog2; - - 3. We create a wrapping project MAIN: - - File "main.gpr": - - with "common"; - with "prog1"; - with "prog2"; - project Main is - - package Compiler renames Common.Compiler; - - end Main; - - 4. Finally we need to create a dummy procedure that `with's (either - explicitly or implicitly) all the sources of our two programs. - - - Now we can build the programs using the command - - GNAT MAKE -Pmain dummy - - for the Debug mode, or - - GNAT MAKE -Pmain -XBUILD=release - - for the Release mode. - -  - File: gnat_ug_vms.info, Node: Project File Complete Syntax, Prev: An Extended Example, Up: GNAT Project Manager - - Project File Complete Syntax - ============================ - - project ::= - context_clause project_declaration - - context_clause ::= - {with_clause} - - with_clause ::= - with literal_string { , literal_string } ; - - project_declaration ::= - project simple_name [ extends literal_string ] is - {declarative_item} - end simple_name; - - declarative_item ::= - package_declaration | - typed_string_declaration | - other_declarative_item - - package_declaration ::= - package simple_name package_completion - - package_completion ::= - package_body | package_renaming - - package body ::= - is - {other_declarative_item} - end simple_name ; - - package_renaming ::== - renames simple_name.simple_name ; - - typed_string_declaration ::= - type _simple_name is - ( literal_string {, literal_string} ); - - other_declarative_item ::= - attribute_declaration | - typed_variable_declaration | - variable_declaration | - case_construction - - attribute_declaration ::= - for attribute use expression ; - - attribute ::= - simple_name | - simple_name ( literal_string ) - - typed_variable_declaration ::= - simple_name : name := string_expression ; - - variable_declaration ::= - simple_name := expression; - - expression ::= - term {& term} - - term ::= - literal_string | - string_list | - name | - external_value | - attribute_reference - - literal_string ::= - (same as Ada) - - string_list ::= - ( expression { , expression } ) - - external_value ::= - external ( literal_string [, literal_string] ) - - attribute_reference ::= - attribute_parent ' simple_name [ ( literal_string ) ] - - attribute_parent ::= - project | - simple_name | - simple_name . simple_name - - case_construction ::= - case name is - {case_item} - end case ; - - case_item ::= - when discrete_choice_list => {case_construction | attribute_declaration} - - discrete_choice_list ::= - literal_string {| literal_string} - - name ::= - simple_name {. simple_name} - - simple_name ::= - identifier (same as Ada) - -  - File: gnat_ug_vms.info, Node: Elaboration Order Handling in GNAT, Next: The Cross-Referencing Tools GNAT XREF and GNAT FIND, Prev: GNAT Project Manager, Up: Top - - Elaboration Order Handling in GNAT - ********************************** - - * Menu: - - * Elaboration Code in Ada 95:: - * Checking the Elaboration Order in Ada 95:: - * Controlling the Elaboration Order in Ada 95:: - * Controlling Elaboration in GNAT - Internal Calls:: - * Controlling Elaboration in GNAT - External Calls:: - * Default Behavior in GNAT - Ensuring Safety:: - * Elaboration Issues for Library Tasks:: - * Mixing Elaboration Models:: - * What to Do If the Default Elaboration Behavior Fails:: - * Elaboration for Access-to-Subprogram Values:: - * Summary of Procedures for Elaboration Control:: - * Other Elaboration Order Considerations:: - - This chapter describes the handling of elaboration code in Ada 95 and - in GNAT, and discusses how the order of elaboration of program units can - be controlled in GNAT, either automatically or with explicit programming - features. - -  - File: gnat_ug_vms.info, Node: Elaboration Code in Ada 95, Next: Checking the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Elaboration Code in Ada 95 - ========================== - - Ada 95 provides rather general mechanisms for executing code at - elaboration time, that is to say before the main program starts - executing. Such code arises in three contexts: - - Initializers for variables. - Variables declared at the library level, in package specs or - bodies, can require initialization that is performed at - elaboration time, as in: - Sqrt_Half : Float := Sqrt (0.5); - - Package initialization code - Code in a `BEGIN-END' section at the outer level of a package body - is executed as part of the package body elaboration code. - - Library level task allocators - Tasks that are declared using task allocators at the library level - start executing immediately and hence can execute at elaboration - time. - - Subprogram calls are possible in any of these contexts, which means that - any arbitrary part of the program may be executed as part of the - elaboration code. It is even possible to write a program which does all - its work at elaboration time, with a null main program, although - stylistically this would usually be considered an inappropriate way to - structure a program. - - An important concern arises in the context of elaboration code: we - have to be sure that it is executed in an appropriate order. What we - have is a series of elaboration code sections, potentially one section - for each unit in the program. It is important that these execute in the - correct order. Correctness here means that, taking the above example of - the declaration of `Sqrt_Half', if some other piece of elaboration code - references `Sqrt_Half', then it must run after the section of - elaboration code that contains the declaration of `Sqrt_Half'. - - There would never be any order of elaboration problem if we made a - rule that whenever you `with' a unit, you must elaborate both the spec - and body of that unit before elaborating the unit doing the `with''ing: - - with Unit_1; - package Unit_2 is ... - - would require that both the body and spec of `Unit_1' be elaborated - before the spec of `Unit_2'. However, a rule like that would be far too - restrictive. In particular, it would make it impossible to have routines - in separate packages that were mutually recursive. - - You might think that a clever enough compiler could look at the - actual elaboration code and determine an appropriate correct order of - elaboration, but in the general case, this is not possible. Consider - the following example. - - In the body of `Unit_1', we have a procedure `Func_1' that references - the variable `Sqrt_1', which is declared in the elaboration code of the - body of `Unit_1': - - Sqrt_1 : Float := Sqrt (0.1); - - The elaboration code of the body of `Unit_1' also contains: - - if expression_1 = 1 then - Q := Unit_2.Func_2; - end if; - - `Unit_2' is exactly parallel, it has a procedure `Func_2' that - references the variable `Sqrt_2', which is declared in the elaboration - code of the body `Unit_2': - - Sqrt_2 : Float := Sqrt (0.1); - - The elaboration code of the body of `Unit_2' also contains: - - if expression_2 = 2 then - Q := Unit_1.Func_1; - end if; - - Now the question is, which of the following orders of elaboration is - acceptable: - - Spec of Unit_1 - Spec of Unit_2 - Body of Unit_1 - Body of Unit_2 - - or - - Spec of Unit_2 - Spec of Unit_1 - Body of Unit_2 - Body of Unit_1 - - If you carefully analyze the flow here, you will see that you cannot - tell at compile time the answer to this question. If `expression_1' is - not equal to 1, and `expression_2' is not equal to 2, then either order - is acceptable, because neither of the function calls is executed. If - both tests evaluate to true, then neither order is acceptable and in - fact there is no correct order. - - If one of the two expressions is true, and the other is false, then - one of the above orders is correct, and the other is incorrect. For - example, if `expression_1' = 1 and `expression_2' /= 2, then the call - to `Func_2' will occur, but not the call to `Func_1.' This means that - it is essential to elaborate the body of `Unit_1' before the body of - `Unit_2', so the first order of elaboration is correct and the second - is wrong. - - By making `expression_1' and `expression_2' depend on input data, or - perhaps the time of day, we can make it impossible for the compiler or - binder to figure out which of these expressions will be true, and hence - it is impossible to guarantee a safe order of elaboration at run time. - -  - File: gnat_ug_vms.info, Node: Checking the Elaboration Order in Ada 95, Next: Controlling the Elaboration Order in Ada 95, Prev: Elaboration Code in Ada 95, Up: Elaboration Order Handling in GNAT - - Checking the Elaboration Order in Ada 95 - ======================================== - - In some languages that involve the same kind of elaboration problems, - e.g. Java and C++, the programmer is expected to worry about these - ordering problems himself, and it is common to write a program in which - an incorrect elaboration order gives surprising results, because it - references variables before they are initialized. Ada 95 is designed - to be a safe language, and a programmer-beware approach is clearly not - sufficient. Consequently, the language provides three lines of defense: - - Standard rules - Some standard rules restrict the possible choice of elaboration - order. In particular, if you `with' a unit, then its spec is always - elaborated before the unit doing the `with'. Similarly, a parent - spec is always elaborated before the child spec, and finally a - spec is always elaborated before its corresponding body. - - Dynamic elaboration checks - Dynamic checks are made at run time, so that if some entity is - accessed before it is elaborated (typically by means of a - subprogram call) then the exception (`Program_Error') is raised. - - Elaboration control - Facilities are provided for the programmer to specify the desired - order of elaboration. - - Let's look at these facilities in more detail. First, the rules for - dynamic checking. One possible rule would be simply to say that the - exception is raised if you access a variable which has not yet been - elaborated. The trouble with this approach is that it could require - expensive checks on every variable reference. Instead Ada 95 has two - rules which are a little more restrictive, but easier to check, and - easier to state: - - Restrictions on calls - A subprogram can only be called at elaboration time if its body - has been elaborated. The rules for elaboration given above - guarantee that the spec of the subprogram has been elaborated - before the call, but not the body. If this rule is violated, then - the exception `Program_Error' is raised. - - Restrictions on instantiations - A generic unit can only be instantiated if the body of the generic - unit has been elaborated. Again, the rules for elaboration given - above guarantee that the spec of the generic unit has been - elaborated before the instantiation, but not the body. If this - rule is violated, then the exception `Program_Error' is raised. - - The idea is that if the body has been elaborated, then any variables it - references must have been elaborated; by checking for the body being - elaborated we guarantee that none of its references causes any trouble. - As we noted above, this is a little too restrictive, because a - subprogram that has no non-local references in its body may in fact be - safe to call. However, it really would be unsafe to rely on this, - because it would mean that the caller was aware of details of the - implementation in the body. This goes against the basic tenets of Ada. - - A plausible implementation can be described as follows. A Boolean - variable is associated with each subprogram and each generic unit. This - variable is initialized to False, and is set to True at the point body - is elaborated. Every call or instantiation checks the variable, and - raises `Program_Error' if the variable is False. - - Note that one might think that it would be good enough to have one - Boolean variable for each package, but that would not deal with cases - of trying to call a body in the same package as the call that has not - been elaborated yet. Of course a compiler may be able to do enough - analysis to optimize away some of the Boolean variables as unnecessary, - and `GNAT' indeed does such optimizations, but still the easiest - conceptual model is to think of there being one variable per subprogram. - -  - File: gnat_ug_vms.info, Node: Controlling the Elaboration Order in Ada 95, Next: Controlling Elaboration in GNAT - Internal Calls, Prev: Checking the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Controlling the Elaboration Order in Ada 95 - =========================================== - - In the previous section we discussed the rules in Ada 95 which ensure - that `Program_Error' is raised if an incorrect elaboration order is - chosen. This prevents erroneous executions, but we need mechanisms to - specify a correct execution and avoid the exception altogether. To - achieve this, Ada 95 provides a number of features for controlling the - order of elaboration. We discuss these features in this section. - - First, there are several ways of indicating to the compiler that a - given unit has no elaboration problems: - - packages that do not require a body - In Ada 95, a library package that does not require a body does not - permit a body. This means that if we have a such a package, as in: - - package Definitions is - generic - type m is new integer; - package Subp is - type a is array (1 .. 10) of m; - type b is array (1 .. 20) of m; - end Subp; - end Definitions; - - A package that `with''s `Definitions' may safely instantiate - `Definitions.Subp' because the compiler can determine that there - definitely is no package body to worry about in this case - - pragma Pure - Places sufficient restrictions on a unit to guarantee that no call - to any subprogram in the unit can result in an elaboration - problem. This means that the compiler does not need to worry about - the point of elaboration of such units, and in particular, does - not need to check any calls to any subprograms in this unit. - - pragma Preelaborate - This pragma places slightly less stringent restrictions on a unit - than does pragma Pure, but these restrictions are still sufficient - to ensure that there are no elaboration problems with any calls to - the unit. - - pragma Elaborate_Body - This pragma requires that the body of a unit be elaborated - immediately after its spec. Suppose a unit `A' has such a pragma, - and unit `B' does a `with' of unit `A'. Recall that the standard - rules require the spec of unit `A' to be elaborated before the - `with''ing unit; given the pragma in `A', we also know that the - body of `A' will be elaborated before `B', so that calls to `A' - are safe and do not need a check. - - Note that, unlike pragma `Pure' and pragma `Preelaborate', the use of - `Elaborate_Body' does not guarantee that the program is free of - elaboration problems, because it may not be possible to satisfy the - requested elaboration order. Let's go back to the example with - `Unit_1' and `Unit_2'. If a programmer marks `Unit_1' as - `Elaborate_Body', and not `Unit_2,' then the order of elaboration will - be: - - Spec of Unit_2 - Spec of Unit_1 - Body of Unit_1 - Body of Unit_2 - - Now that means that the call to `Func_1' in `Unit_2' need not be - checked, it must be safe. But the call to `Func_2' in `Unit_1' may - still fail if `Expression_1' is equal to 1, and the programmer must - still take responsibility for this not being the case. - - If all units carry a pragma `Elaborate_Body', then all problems are - eliminated, except for calls entirely within a body, which are in any - case fully under programmer control. However, using the pragma - everywhere is not always possible. In particular, for our - `Unit_1'/`Unit_2' example, if we marked both of them as having pragma - `Elaborate_Body', then clearly there would be no possible elaboration - order. - - The above pragmas allow a server to guarantee safe use by clients, - and clearly this is the preferable approach. Consequently a good rule in - Ada 95 is to mark units as `Pure' or `Preelaborate' if possible, and if - this is not possible, mark them as `Elaborate_Body' if possible. As we - have seen, there are situations where neither of these three pragmas - can be used. So we also provide methods for clients to control the - order of elaboration of the servers on which they depend: - - pragma Elaborate (unit) - This pragma is placed in the context clause, after a `with' clause, - and it requires that the body of the named unit be elaborated - before the unit in which the pragma occurs. The idea is to use - this pragma if the current unit calls at elaboration time, - directly or indirectly, some subprogram in the named unit. - - pragma Elaborate_All (unit) - This is a stronger version of the Elaborate pragma. Consider the - following example: - - Unit A `with''s unit B and calls B.Func in elab code - Unit B `with''s unit C, and B.Func calls C.Func - - Now if we put a pragma `Elaborate (B)' in unit `A', this ensures - that the body of `B' is elaborated before the call, but not the - body of `C', so the call to `C.Func' could still cause - `Program_Error' to be raised. - - The effect of a pragma `Elaborate_All' is stronger, it requires - not only that the body of the named unit be elaborated before the - unit doing the `with', but also the bodies of all units that the - named unit uses, following `with' links transitively. For example, - if we put a pragma `Elaborate_All (B)' in unit `A', then it - requires not only that the body of `B' be elaborated before `A', - but also the body of `C', because `B' `with''s `C'. - - We are now in a position to give a usage rule in Ada 95 for avoiding - elaboration problems, at least if dynamic dispatching and access to - subprogram values are not used. We will handle these cases separately - later. - - The rule is simple. If a unit has elaboration code that can directly - or indirectly make a call to a subprogram in a `with''ed unit, or - instantiate a generic unit in a `with''ed unit, then if the `with''ed - unit does not have pragma `Pure' or `Preelaborate', then the client - should have a pragma `Elaborate_All' for the `with''ed unit. By - following this rule a client is assured that calls can be made without - risk of an exception. If this rule is not followed, then a program may - be in one of four states: - - No order exists - No order of elaboration exists which follows the rules, taking into - account any `Elaborate', `Elaborate_All', or `Elaborate_Body' - pragmas. In this case, an Ada 95 compiler must diagnose the - situation at bind time, and refuse to build an executable program. - - One or more orders exist, all incorrect - One or more acceptable elaboration orders exists, and all of them - generate an elaboration order problem. In this case, the binder - can build an executable program, but `Program_Error' will be raised - when the program is run. - - Several orders exist, some right, some incorrect - One or more acceptable elaboration orders exists, and some of them - work, and some do not. The programmer has not controlled the order - of elaboration, so the binder may or may not pick one of the - correct orders, and the program may or may not raise an exception - when it is run. This is the worst case, because it means that the - program may fail when moved to another compiler, or even another - version of the same compiler. - - One or more orders exists, all correct - One ore more acceptable elaboration orders exist, and all of them - work. In this case the program runs successfully. This state of - affairs can be guaranteed by following the rule we gave above, but - may be true even if the rule is not followed. - - Note that one additional advantage of following our Elaborate_All rule - is that the program continues to stay in the ideal (all orders OK) state - even if maintenance changes some bodies of some subprograms. - Conversely, if a program that does not follow this rule happens to be - safe at some point, this state of affairs may deteriorate silently as a - result of maintenance changes. - - You may have noticed that the above discussion did not mention the - use of `Elaborate_Body'. This was a deliberate omission. If you `with' - an `Elaborate_Body' unit, it still may be the case that code in the - body makes calls to some other unit, so it is still necessary to use - `Elaborate_All' on such units. - -  - File: gnat_ug_vms.info, Node: Controlling Elaboration in GNAT - Internal Calls, Next: Controlling Elaboration in GNAT - External Calls, Prev: Controlling the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Controlling Elaboration in GNAT - Internal Calls - ================================================ - - In the case of internal calls, i.e. calls within a single package, the - programmer has full control over the order of elaboration, and it is up - to the programmer to elaborate declarations in an appropriate order. For - example writing: - - function One return Float; - - Q : Float := One; - - function One return Float is - begin - return 1.0; - end One; - - will obviously raise `Program_Error' at run time, because function One - will be called before its body is elaborated. In this case GNAT will - generate a warning that the call will raise `Program_Error': - - 1. procedure y is - 2. function One return Float; - 3. - 4. Q : Float := One; - | - >>> warning: cannot call "One" before body is elaborated - >>> warning: Program_Error will be raised at run time - - 5. - 6. function One return Float is - 7. begin - 8. return 1.0; - 9. end One; - 10. - 11. begin - 12. null; - 13. end; - - Note that in this particular case, it is likely that the call is safe, - because the function `One' does not access any global variables. - Nevertheless in Ada 95, we do not want the validity of the check to - depend on the contents of the body (think about the separate - compilation case), so this is still wrong, as we discussed in the - previous sections. - - The error is easily corrected by rearranging the declarations so - that the body of One appears before the declaration containing the call - (note that in Ada 95, declarations can appear in any order, so there is - no restriction that would prevent this reordering, and if we write: - - function One return Float; - - function One return Float is - begin - return 1.0; - end One; - - Q : Float := One; - - then all is well, no warning is generated, and no `Program_Error' - exception will be raised. Things are more complicated when a chain of - subprograms is executed: - - function A return Integer; - function B return Integer; - function C return Integer; - - function B return Integer is begin return A; end; - function C return Integer is begin return B; end; - - X : Integer := C; - - function A return Integer is begin return 1; end; - - Now the call to `C' at elaboration time in the declaration of `X' is - correct, because the body of `C' is already elaborated, and the call to - `B' within the body of `C' is correct, but the call to `A' within the - body of `B' is incorrect, because the body of `A' has not been - elaborated, so `Program_Error' will be raised on the call to `A'. In - this case GNAT will generate a warning that `Program_Error' may be - raised at the point of the call. Let's look at the warning: - - 1. procedure x is - 2. function A return Integer; - 3. function B return Integer; - 4. function C return Integer; - 5. - 6. function B return Integer is begin return A; end; - | - >>> warning: call to "A" before body is elaborated may - raise Program_Error - >>> warning: "B" called at line 7 - >>> warning: "C" called at line 9 - - 7. function C return Integer is begin return B; end; - 8. - 9. X : Integer := C; - 10. - 11. function A return Integer is begin return 1; end; - 12. - 13. begin - 14. null; - 15. end; - - Note that the message here says "may raise", instead of the direct case, - where the message says "will be raised". That's because whether `A' is - actually called depends in general on run-time flow of control. For - example, if the body of `B' said - - function B return Integer is - begin - if some-condition-depending-on-input-data then - return A; - else - return 1; - end if; - end B; - - then we could not know until run time whether the incorrect call to A - would actually occur, so `Program_Error' might or might not be raised. - It is possible for a compiler to do a better job of analyzing bodies, to - determine whether or not `Program_Error' might be raised, but it - certainly couldn't do a perfect job (that would require solving the - halting problem and is provably impossible), and because this is a - warning anyway, it does not seem worth the effort to do the analysis. - Cases in which it would be relevant are rare. - - In practice, warnings of either of the forms given above will - usually correspond to real errors, and should be examined carefully and - eliminated. In the rare case where a warning is bogus, it can be - suppressed by any of the following methods: - - * Compile with the `/WARNINGS=SUPPRESS' qualifier set - - * Suppress `Elaboration_Checks' for the called subprogram - - * Use pragma `Warnings_Off' to turn warnings off for the call - - For the internal elaboration check case, GNAT by default generates the - necessary run-time checks to ensure that `Program_Error' is raised if - any call fails an elaboration check. Of course this can only happen if a - warning has been issued as described above. The use of pragma `Suppress - (Elaboration_Checks)' may (but is not guaranteed to) suppress some of - these checks, meaning that it may be possible (but is not guaranteed) - for a program to be able to call a subprogram whose body is not yet - elaborated, without raising a `Program_Error' exception. - -  - File: gnat_ug_vms.info, Node: Controlling Elaboration in GNAT - External Calls, Next: Default Behavior in GNAT - Ensuring Safety, Prev: Controlling Elaboration in GNAT - Internal Calls, Up: Elaboration Order Handling in GNAT - - Controlling Elaboration in GNAT - External Calls - ================================================ - - The previous section discussed the case in which the execution of a - particular thread of elaboration code occurred entirely within a single - unit. This is the easy case to handle, because a programmer has direct - and total control over the order of elaboration, and furthermore, - checks need only be generated in cases which are rare and which the - compiler can easily detect. The situation is more complex when - separate compilation is taken into account. Consider the following: - - package Math is - function Sqrt (Arg : Float) return Float; - end Math; - - package body Math is - function Sqrt (Arg : Float) return Float is - begin - ... - end Sqrt; - end Math; - - with Math; - package Stuff is - X : Float := Math.Sqrt (0.5); - end Stuff; - - with Stuff; - procedure Main is - begin - ... - end Main; - - where `Main' is the main program. When this program is executed, the - elaboration code must first be executed, and one of the jobs of the - binder is to determine the order in which the units of a program are to - be elaborated. In this case we have four units: the spec and body of - `Math', the spec of `Stuff' and the body of `Main'). In what order - should the four separate sections of elaboration code be executed? - - There are some restrictions in the order of elaboration that the - binder can choose. In particular, if unit U has a `with' for a package - `X', then you are assured that the spec of `X' is elaborated before U , - but you are not assured that the body of `X' is elaborated before U. - This means that in the above case, the binder is allowed to choose the - order: - - spec of Math - spec of Stuff - body of Math - body of Main - - but that's not good, because now the call to `Math.Sqrt' that happens - during the elaboration of the `Stuff' spec happens before the body of - `Math.Sqrt' is elaborated, and hence causes `Program_Error' exception - to be raised. At first glance, one might say that the binder is - misbehaving, because obviously you want to elaborate the body of - something you `with' first, but that is not a general rule that can be - followed in all cases. Consider - - package X is ... - - package Y is ... - - with X; - package body Y is ... - - with Y; - package body X is ... - - This is a common arrangement, and, apart from the order of elaboration - problems that might arise in connection with elaboration code, this - works fine. A rule that says that you must first elaborate the body of - anything you `with' cannot work in this case: the body of `X' `with''s - `Y', which means you would have to elaborate the body of `Y' first, but - that `with''s `X', which means you have to elaborate the body of `X' - first, but ... and we have a loop that cannot be broken. - - It is true that the binder can in many cases guess an order of - elaboration that is unlikely to cause a `Program_Error' exception to be - raised, and it tries to do so (in the above example of - `Math/Stuff/Spec', the GNAT binder will by default elaborate the body - of `Math' right after its spec, so all will be well). - - However, a program that blindly relies on the binder to be helpful - can get into trouble, as we discussed in the previous sections, so GNAT - provides a number of facilities for assisting the programmer in - developing programs that are robust with respect to elaboration order. - -  - File: gnat_ug_vms.info, Node: Default Behavior in GNAT - Ensuring Safety, Next: Elaboration Issues for Library Tasks, Prev: Controlling Elaboration in GNAT - External Calls, Up: Elaboration Order Handling in GNAT - - Default Behavior in GNAT - Ensuring Safety - ========================================== - - The default behavior in GNAT ensures elaboration safety. In its default - mode GNAT implements the rule we previously described as the right - approach. Let's restate it: - - * _If a unit has elaboration code that can directly or indirectly - make a call to a subprogram in a `with''ed unit, or instantiate a - generic unit in a `with''ed unit, then if the `with''ed unit does - not have pragma `Pure' or `Preelaborate', then the client should - have an `Elaborate_All' for the `with''ed unit._ - - By following this rule a client is assured that calls and - instantiations can be made without risk of an exception. - - In this mode GNAT traces all calls that are potentially made from - elaboration code, and puts in any missing implicit `Elaborate_All' - pragmas. The advantage of this approach is that no elaboration problems - are possible if the binder can find an elaboration order that is - consistent with these implicit `Elaborate_All' pragmas. The - disadvantage of this approach is that no such order may exist. - - If the binder does not generate any diagnostics, then it means that - it has found an elaboration order that is guaranteed to be safe. - However, the binder may still be relying on implicitly generated - `Elaborate_All' pragmas so portability to other compilers than GNAT is - not guaranteed. - - If it is important to guarantee portability, then the compilations - should use the `/WARNINGS=ELABORATION' (warn on elaboration problems) - qualifier. This will cause warning messages to be generated indicating - the missing `Elaborate_All' pragmas. Consider the following source - program: - - with k; - package j is - m : integer := k.r; - end; - - where it is clear that there should be a pragma `Elaborate_All' for - unit `k'. An implicit pragma will be generated, and it is likely that - the binder will be able to honor it. However, it is safer to include - the pragma explicitly in the source. If this unit is compiled with the - `/WARNINGS=ELABORATION' qualifier, then the compiler outputs a warning: - - 1. with k; - 2. package j is - 3. m : integer := k.r; - | - >>> warning: call to "r" may raise Program_Error - >>> warning: missing pragma Elaborate_All for "k" - - 4. end; - - and these warnings can be used as a guide for supplying manually the - missing pragmas. - - This default mode is more restrictive than the Ada Reference Manual, - and it is possible to construct programs which will compile using the - dynamic model described there, but will run into a circularity using - the safer static model we have described. - - Of course any Ada compiler must be able to operate in a mode - consistent with the requirements of the Ada Reference Manual, and in - particular must have the capability of implementing the standard - dynamic model of elaboration with run-time checks. - - In GNAT, this standard mode can be achieved either by the use of the - `/CHECKS=ELABORATION' qualifier on the compiler (`GNAT COMPILE' or - `GNAT MAKE') command, or by the use of the configuration pragma: - - pragma Elaboration_Checks (RM); - - Either approach will cause the unit affected to be compiled using the - standard dynamic run-time elaboration checks described in the Ada - Reference Manual. The static model is generally preferable, since it is - clearly safer to rely on compile and link time checks rather than - run-time checks. However, in the case of legacy code, it may be - difficult to meet the requirements of the static model. This issue is - further discussed in *Note What to Do If the Default Elaboration - Behavior Fails::. - - Note that the static model provides a strict subset of the allowed - behavior and programs of the Ada Reference Manual, so if you do adhere - to the static model and no circularities exist, then you are assured - that your program will work using the dynamic model. - -  - File: gnat_ug_vms.info, Node: Elaboration Issues for Library Tasks, Next: Mixing Elaboration Models, Prev: Default Behavior in GNAT - Ensuring Safety, Up: Elaboration Order Handling in GNAT - - Elaboration Issues for Library Tasks - ==================================== - - In this section we examine special elaboration issues that arise for - programs that declare library level tasks. - - Generally the model of execution of an Ada program is that all units - are elaborated, and then execution of the program starts. However, the - declaration of library tasks definitely does not fit this model. The - reason for this is that library tasks start as soon as they are declared - (more precisely, as soon as the statement part of the enclosing package - body is reached), that is to say before elaboration of the program is - complete. This means that if such a task calls a subprogram, or an - entry in another task, the callee may or may not be elaborated yet, and - in the standard Reference Manual model of dynamic elaboration checks, - you can even get timing dependent Program_Error exceptions, since there - can be a race between the elaboration code and the task code. - - The static model of elaboration in GNAT seeks to avoid all such - dynamic behavior, by being conservative, and the conservative approach - in this particular case is to assume that all the code in a task body - is potentially executed at elaboration time if a task is declared at - the library level. - - This can definitely result in unexpected circularities. Consider the - following example - - package Decls is - task Lib_Task is - entry Start; - end Lib_Task; - - type My_Int is new Integer; - - function Ident (M : My_Int) return My_Int; - end Decls; - - with Utils; - package body Decls is - task body Lib_Task is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task; - - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls; - - with Decls; - package Utils is - procedure Put_Val (Arg : Decls.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls.My_Int) is - begin - Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls; - procedure Main is - begin - Decls.Lib_Task.Start; - end; - - If the above example is compiled in the default static elaboration - mode, then a circularity occurs. The circularity comes from the call - `Utils.Put_Val' in the task body of `Decls.Lib_Task'. Since this call - occurs in elaboration code, we need an implicit pragma `Elaborate_All' - for `Utils'. This means that not only must the spec and body of `Utils' - be elaborated before the body of `Decls', but also the spec and body of - any unit that is `with'ed' by the body of `Utils' must also be - elaborated before the body of `Decls'. This is the transitive - implication of pragma `Elaborate_All' and it makes sense, because in - general the body of `Put_Val' might have a call to something in a - `with'ed' unit. - - In this case, the body of Utils (actually its spec) `with's' - `Decls'. Unfortunately this means that the body of `Decls' must be - elaborated before itself, in case there is a call from the body of - `Utils'. - - Here is the exact chain of events we are worrying about: - - 1. In the body of `Decls' a call is made from within the body of a - library task to a subprogram in the package `Utils'. Since this - call may occur at elaboration time (given that the task is - activated at elaboration time), we have to assume the worst, i.e. - that the call does happen at elaboration time. - - 2. This means that the body and spec of `Util' must be elaborated - before the body of `Decls' so that this call does not cause an - access before elaboration. - - 3. Within the body of `Util', specifically within the body of - `Util.Put_Val' there may be calls to any unit `with''ed by this - package. - - 4. One such `with''ed package is package `Decls', so there might be a - call to a subprogram in `Decls' in `Put_Val'. In fact there is - such a call in this example, but we would have to assume that - there was such a call even if it were not there, since we are not - supposed to write the body of `Decls' knowing what is in the body - of `Utils'; certainly in the case of the static elaboration model, - the compiler does not know what is in other bodies and must assume - the worst. - - 5. This means that the spec and body of `Decls' must also be - elaborated before we elaborate the unit containing the call, but - that unit is `Decls'! This means that the body of `Decls' must be - elaborated before itself, and that's a circularity. - - Indeed, if you add an explicit pragma Elaborate_All for `Utils' in the - body of `Decls' you will get a true Ada Reference Manual circularity - that makes the program illegal. - - In practice, we have found that problems with the static model of - elaboration in existing code often arise from library tasks, so we must - address this particular situation. - - Note that if we compile and run the program above, using the dynamic - model of elaboration (that is to say use the `/CHECKS=ELABORATION' - qualifier), then it compiles, binds, links, and runs, printing the - expected result of 2. Therefore in some sense the circularity here is - only apparent, and we need to capture the properties of this program - that distinguish it from other library-level tasks that have real - elaboration problems. - - We have four possible answers to this question: - - * Use the dynamic model of elaboration. - - If we use the `/CHECKS=ELABORATION' qualifier, then as noted - above, the program works. Why is this? If we examine the task - body, it is apparent that the task cannot proceed past the - `accept' statement until after elaboration has been completed, - because the corresponding entry call comes from the main program, - not earlier. This is why the dynamic model works here. But that's - really giving up on a precise analysis, and we prefer to take this - approach only if we cannot solve the problem in any other manner. - So let us examine two ways to reorganize the program to avoid the - potential elaboration problem. - - * Split library tasks into separate packages. - - Write separate packages, so that library tasks are isolated from - other declarations as much as possible. Let us look at a variation - on the above program. - - package Decls1 is - task Lib_Task is - entry Start; - end Lib_Task; - end Decls1; - - with Utils; - package body Decls1 is - task body Lib_Task is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task; - end Decls1; - - package Decls2 is - type My_Int is new Integer; - function Ident (M : My_Int) return My_Int; - end Decls2; - - with Utils; - package body Decls2 is - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls2; - - with Decls2; - package Utils is - procedure Put_Val (Arg : Decls2.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls2.My_Int) is - begin - Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls1; - procedure Main is - begin - Decls1.Lib_Task.Start; - end; - - All we have done is to split `Decls' into two packages, one - containing the library task, and one containing everything else. - Now there is no cycle, and the program compiles, binds, links and - executes using the default static model of elaboration. - - * Declare separate task types. - - A significant part of the problem arises because of the use of the - single task declaration form. This means that the elaboration of - the task type, and the elaboration of the task itself (i.e. the - creation of the task) happen at the same time. A good rule of - style in Ada 95 is to always create explicit task types. By - following the additional step of placing task objects in separate - packages from the task type declaration, many elaboration problems - are avoided. Here is another modified example of the example - program: - - package Decls is - task type Lib_Task_Type is - entry Start; - end Lib_Task_Type; - - type My_Int is new Integer; - - function Ident (M : My_Int) return My_Int; - end Decls; - - with Utils; - package body Decls is - task body Lib_Task_Type is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task_Type; - - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls; - - with Decls; - package Utils is - procedure Put_Val (Arg : Decls.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls.My_Int) is - begin - Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls; - package Declst is - Lib_Task : Decls.Lib_Task_Type; - end Declst; - - with Declst; - procedure Main is - begin - Declst.Lib_Task.Start; - end; - - What we have done here is to replace the `task' declaration in - package `Decls' with a `task type' declaration. Then we introduce - a separate package `Declst' to contain the actual task object. - This separates the elaboration issues for the `task type' - declaration, which causes no trouble, from the elaboration issues - of the task object, which is also unproblematic, since it is now - independent of the elaboration of `Utils'. This separation of - concerns also corresponds to a generally sound engineering - principle of separating declarations from instances. This version - of the program also compiles, binds, links, and executes, - generating the expected output. - - * Use No_Entry_Calls_In_Elaboration_Code restriction. - - The previous two approaches described how a program can be - restructured to avoid the special problems caused by library task - bodies. in practice, however, such restructuring may be difficult - to apply to existing legacy code, so we must consider solutions - that do not require massive rewriting. - - Let us consider more carefully why our original sample program - works under the dynamic model of elaboration. The reason is that - the code in the task body blocks immediately on the `accept' - statement. Now of course there is nothing to prohibit elaboration - code from making entry calls (for example from another library - level task), so we cannot tell in isolation that the task will not - execute the accept statement during elaboration. - - However, in practice it is very unusual to see elaboration code - make any entry calls, and the pattern of tasks starting at - elaboration time and then immediately blocking on `accept' or - `select' statements is very common. What this means is that the - compiler is being too pessimistic when it analyzes the whole - package body as though it might be executed at elaboration time. - - If we know that the elaboration code contains no entry calls, (a - very safe assumption most of the time, that could almost be made - the default behavior), then we can compile all units of the - program under control of the following configuration pragma: - - pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); - - This pragma can be placed in the `GNAT.ADC' file in the usual - manner. If we take our original unmodified program and compile it - in the presence of a `GNAT.ADC' containing the above pragma, then - once again, we can compile, bind, link, and execute, obtaining the - expected result. In the presence of this pragma, the compiler does - not trace calls in a task body, that appear after the first - `accept' or `select' statement, and therefore does not report a - potential circularity in the original program. - - The compiler will check to the extent it can that the above - restriction is not violated, but it is not always possible to do a - complete check at compile time, so it is important to use this - pragma only if the stated restriction is in fact met, that is to - say no task receives an entry call before elaboration of all units - is completed. - - -  - File: gnat_ug_vms.info, Node: Mixing Elaboration Models, Next: What to Do If the Default Elaboration Behavior Fails, Prev: Elaboration Issues for Library Tasks, Up: Elaboration Order Handling in GNAT - - Mixing Elaboration Models - ========================= - - So far, we have assumed that the entire program is either compiled - using the dynamic model or static model, ensuring consistency. It is - possible to mix the two models, but rules have to be followed if this - mixing is done to ensure that elaboration checks are not omitted. - - The basic rule is that _a unit compiled with the static model cannot - be `with'ed' by a unit compiled with the dynamic model_. The reason for - this is that in the static model, a unit assumes that its clients - guarantee to use (the equivalent of) pragma `Elaborate_All' so that no - elaboration checks are required in inner subprograms, and this - assumption is violated if the client is compiled with dynamic checks. - - The precise rule is as follows. A unit that is compiled with dynamic - checks can only `with' a unit that meets at least one of the following - criteria: - - * The `with'ed' unit is itself compiled with dynamic elaboration - checks (that is with the `/CHECKS=ELABORATION' qualifier. - - * The `with'ed' unit is an internal GNAT implementation unit from - the System, Interfaces, Ada, or GNAT hierarchies. - - * The `with'ed' unit has pragma Preelaborate or pragma Pure. - - * The `with'ing' unit (that is the client) has an explicit pragma - `Elaborate_All' for the `with'ed' unit. - - - If this rule is violated, that is if a unit with dynamic elaboration - checks `with's' a unit that does not meet one of the above four - criteria, then the binder (`GNAT BIND') will issue a warning similar to - that in the following example: - - warning: "X.ADS" has dynamic elaboration checks and with's - warning: "Y.ADS" which has static elaboration checks - - These warnings indicate that the rule has been violated, and that as a - result elaboration checks may be missed in the resulting executable - file. This warning may be suppressed using the `-ws' binder qualifier - in the usual manner. - - One useful application of this mixing rule is in the case of a - subsystem which does not itself `with' units from the remainder of the - application. In this case, the entire subsystem can be compiled with - dynamic checks to resolve a circularity in the subsystem, while - allowing the main application that uses this subsystem to be compiled - using the more reliable default static model. - -  - File: gnat_ug_vms.info, Node: What to Do If the Default Elaboration Behavior Fails, Next: Elaboration for Access-to-Subprogram Values, Prev: Mixing Elaboration Models, Up: Elaboration Order Handling in GNAT - - What to Do If the Default Elaboration Behavior Fails - ==================================================== - - If the binder cannot find an acceptable order, it outputs detailed - diagnostics. For example: - error: elaboration circularity detected - info: "proc (body)" must be elaborated before "pack (body)" - info: reason: Elaborate_All probably needed in unit "pack (body)" - info: recompile "pack (body)" with /WARNINGS=ELABORATION - info: for full details - info: "proc (body)" - info: is needed by its spec: - info: "proc (spec)" - info: which is withed by: - info: "pack (body)" - info: "pack (body)" must be elaborated before "proc (body)" - info: reason: pragma Elaborate in unit "proc (body)" - - - In this case we have a cycle that the binder cannot break. On the one - hand, there is an explicit pragma Elaborate in `proc' for `pack'. This - means that the body of `pack' must be elaborated before the body of - `proc'. On the other hand, there is elaboration code in `pack' that - calls a subprogram in `proc'. This means that for maximum safety, there - should really be a pragma Elaborate_All in `pack' for `proc' which - would require that the body of `proc' be elaborated before the body of - `pack'. Clearly both requirements cannot be satisfied. Faced with a - circularity of this kind, you have three different options. - - Fix the program - The most desirable option from the point of view of long-term - maintenance is to rearrange the program so that the elaboration - problems are avoided. One useful technique is to place the - elaboration code into separate child packages. Another is to move - some of the initialization code to explicitly called subprograms, - where the program controls the order of initialization explicitly. - Although this is the most desirable option, it may be impractical - and involve too much modification, especially in the case of - complex legacy code. - - Perform dynamic checks - If the compilations are done using the `/CHECKS=ELABORATION' - (dynamic elaboration check) qualifier, then GNAT behaves in a - quite different manner. Dynamic checks are generated for all calls - that could possibly result in raising an exception. With this - qualifier, the compiler does not generate implicit `Elaborate_All' - pragmas. The behavior then is exactly as specified in the Ada 95 - Reference Manual. The binder will generate an executable program - that may or may not raise `Program_Error', and then it is the - programmer's job to ensure that it does not raise an exception. - Note that it is important to compile all units with the qualifier, - it cannot be used selectively. - - Suppress checks - The drawback of dynamic checks is that they generate a significant - overhead at run time, both in space and time. If you are - absolutely sure that your program cannot raise any elaboration - exceptions, and you still want to use the dynamic elaboration - model, then you can use the configuration pragma `Suppress - (Elaboration_Checks)' to suppress all such checks. For example - this pragma could be placed in the `GNAT.ADC' file. - - Suppress checks selectively - When you know that certain calls in elaboration code cannot - possibly lead to an elaboration error, and the binder nevertheless - generates warnings on those calls and inserts Elaborate_All - pragmas that lead to elaboration circularities, it is possible to - remove those warnings locally and obtain a program that will bind. - Clearly this can be unsafe, and it is the responsibility of the - programmer to make sure that the resulting program has no - elaboration anomalies. The pragma `Suppress (Elaboration_Check)' - can be used with different granularity to suppress warnings and - break elaboration circularities: - - * Place the pragma that names the called subprogram in the - declarative part that contains the call. - - * Place the pragma in the declarative part, without naming an - entity. This disables warnings on all calls in the - corresponding declarative region. - - * Place the pragma in the package spec that declares the called - subprogram, and name the subprogram. This disables warnings - on all elaboration calls to that subprogram. - - * Place the pragma in the package spec that declares the called - subprogram, without naming any entity. This disables warnings - on all elaboration calls to all subprograms declared in this - spec. - - These four cases are listed in order of decreasing safety, and - therefore require increasing programmer care in their application. - Consider the following program: - - package Pack1 is - function F1 return Integer; - X1 : Integer; - end Pack1; - - package Pack2 is - function F2 return Integer; - function Pure (x : integer) return integer; - -- pragma Suppress (Elaboration_Check, On => Pure); -- (3) - -- pragma Suppress (Elaboration_Check); -- (4) - end Pack2; - - with Pack2; - package body Pack1 is - function F1 return Integer is - begin - return 100; - end F1; - Val : integer := Pack2.Pure (11); -- Elab. call (1) - begin - declare - -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1) - -- pragma Suppress(Elaboration_Check); -- (2) - begin - X1 := Pack2.F2 + 1; -- Elab. call (2) - end; - end Pack1; - - with Pack1; - package body Pack2 is - function F2 return Integer is - begin - return Pack1.F1; - end F2; - function Pure (x : integer) return integer is - begin - return x ** 3 - 3 * x; - end; - end Pack2; - - with Pack1, Ada.Text_IO; - procedure Proc3 is - begin - Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 - end Proc3; - In the absence of any pragmas, an attempt to bind this program - produces the following diagnostics: - error: elaboration circularity detected - info: "pack1 (body)" must be elaborated before "pack1 (body)" - info: reason: Elaborate_All probably needed in unit "pack1 (body)" - info: recompile "pack1 (body)" with /WARNINGS=ELABORATION for full details - info: "pack1 (body)" - info: must be elaborated along with its spec: - info: "pack1 (spec)" - info: which is withed by: - info: "pack2 (body)" - info: which must be elaborated along with its spec: - info: "pack2 (spec)" - info: which is withed by: - info: "pack1 (body)" - The sources of the circularity are the two calls to - `Pack2.Pure' and `Pack2.F2' in the body of `Pack1'. We can see - that the call to F2 is safe, even though F2 calls F1, because the - call appears after the elaboration of the body of F1. Therefore - the pragma (1) is safe, and will remove the warning on the call. - It is also possible to use pragma (2) because there are no other - potentially unsafe calls in the block. - - The call to `Pure' is safe because this function does not depend - on the state of `Pack2'. Therefore any call to this function is - safe, and it is correct to place pragma (3) in the corresponding - package spec. - - Finally, we could place pragma (4) in the spec of `Pack2' to - disable warnings on all calls to functions declared therein. Note - that this is not necessarily safe, and requires more detailed - examination of the subprogram bodies involved. In particular, a - call to `F2' requires that `F1' be already elaborated. - - It is hard to generalize on which of these four approaches should be - taken. Obviously if it is possible to fix the program so that the - default treatment works, this is preferable, but this may not always be - practical. It is certainly simple enough to use `/CHECKS=ELABORATION' - but the danger in this case is that, even if the GNAT binder finds a - correct elaboration order, it may not always do so, and certainly a - binder from another Ada compiler might not. A combination of testing - and analysis (for which the warnings generated with the - `/WARNINGS=ELABORATION' qualifier can be useful) must be used to ensure - that the program is free of errors. One qualifier that is useful in - this testing is the `/PESSIMISTIC_ELABORATION_ORDER' qualifier for - `GNAT BIND'. Normally the binder tries to find an order that has the - best chance of of avoiding elaboration problems. With this qualifier, - the binder plays a devil's advocate role, and tries to choose the order - that has the best chance of failing. If your program works even with - this qualifier, then it has a better chance of being error free, but - this is still not a guarantee. - - For an example of this approach in action, consider the C-tests - (executable tests) from the ACVC suite. If these are compiled and run - with the default treatment, then all but one of them succeed without - generating any error diagnostics from the binder. However, there is one - test that fails, and this is not surprising, because the whole point of - this test is to ensure that the compiler can handle cases where it is - impossible to determine a correct order statically, and it checks that - an exception is indeed raised at run time. - - This one test must be compiled and run using the - `/CHECKS=ELABORATION' qualifier, and then it passes. Alternatively, the - entire suite can be run using this qualifier. It is never wrong to run - with the dynamic elaboration qualifier if your code is correct, and we - assume that the C-tests are indeed correct (it is less efficient, but - efficiency is not a factor in running the ACVC tests.) - -  - File: gnat_ug_vms.info, Node: Elaboration for Access-to-Subprogram Values, Next: Summary of Procedures for Elaboration Control, Prev: What to Do If the Default Elaboration Behavior Fails, Up: Elaboration Order Handling in GNAT - - Elaboration for Access-to-Subprogram Values - =========================================== - - The introduction of access-to-subprogram types in Ada 95 complicates - the handling of elaboration. The trouble is that it becomes impossible - to tell at compile time which procedure is being called. This means - that it is not possible for the binder to analyze the elaboration - requirements in this case. - - If at the point at which the access value is created (i.e., the - evaluation of `P'Access' for a subprogram `P'), the body of the - subprogram is known to have been elaborated, then the access value is - safe, and its use does not require a check. This may be achieved by - appropriate arrangement of the order of declarations if the subprogram - is in the current unit, or, if the subprogram is in another unit, by - using pragma `Pure', `Preelaborate', or `Elaborate_Body' on the - referenced unit. - - If the referenced body is not known to have been elaborated at the - point the access value is created, then any use of the access value - must do a dynamic check, and this dynamic check will fail and raise a - `Program_Error' exception if the body has not been elaborated yet. - GNAT will generate the necessary checks, and in addition, if the - `/WARNINGS=ELABORATION' qualifier is set, will generate warnings that - such checks are required. - - The use of dynamic dispatching for tagged types similarly generates - a requirement for dynamic checks, and premature calls to any primitive - operation of a tagged type before the body of the operation has been - elaborated, will result in the raising of `Program_Error'. - -  - File: gnat_ug_vms.info, Node: Summary of Procedures for Elaboration Control, Next: Other Elaboration Order Considerations, Prev: Elaboration for Access-to-Subprogram Values, Up: Elaboration Order Handling in GNAT - - Summary of Procedures for Elaboration Control - ============================================= - - First, compile your program with the default options, using none of the - special elaboration control qualifiers. If the binder successfully - binds your program, then you can be confident that, apart from issues - raised by the use of access-to-subprogram types and dynamic dispatching, - the program is free of elaboration errors. If it is important that the - program be portable, then use the `/WARNINGS=ELABORATION' qualifier to - generate warnings about missing `Elaborate_All' pragmas, and supply the - missing pragmas. - - If the program fails to bind using the default static elaboration - handling, then you can fix the program to eliminate the binder message, - or recompile the entire program with the `/CHECKS=ELABORATION' - qualifier to generate dynamic elaboration checks, and, if you are sure - there really are no elaboration problems, use a global pragma `Suppress - (Elaboration_Checks)'. - -  - File: gnat_ug_vms.info, Node: Other Elaboration Order Considerations, Prev: Summary of Procedures for Elaboration Control, Up: Elaboration Order Handling in GNAT - - Other Elaboration Order Considerations - ====================================== - - This section has been entirely concerned with the issue of finding a - valid elaboration order, as defined by the Ada Reference Manual. In a - case where several elaboration orders are valid, the task is to find one - of the possible valid elaboration orders (and the static model in GNAT - will ensure that this is achieved). - - The purpose of the elaboration rules in the Ada Reference Manual is - to make sure that no entity is accessed before it has been elaborated. - For a subprogram, this means that the spec and body must have been - elaborated before the subprogram is called. For an object, this means - that the object must have been elaborated before its value is read or - written. A violation of either of these two requirements is an access - before elaboration order, and this section has been all about avoiding - such errors. - - In the case where more than one order of elaboration is possible, in - the sense that access before elaboration errors are avoided, then any - one of the orders is "correct" in the sense that it meets the - requirements of the Ada Reference Manual, and no such error occurs. - - However, it may be the case for a given program, that there are - constraints on the order of elaboration that come not from consideration - of avoiding elaboration errors, but rather from extra-lingual logic - requirements. Consider this example: - - with Init_Constants; - package Constants is - X : Integer := 0; - Y : Integer := 0; - end Constants; - - package Init_Constants is - procedure Calc; - end Init_Constants; - - with Constants; - package body Init_Constants is - procedure Calc is begin null; end; - begin - Constants.X := 3; - Constants.Y := 4; - end Init_Constants; - - with Constants; - package Calc is - Z : Integer := Constants.X + Constants.Y; - end Calc; - - with Calc; - with Text_IO; use Text_IO; - procedure Main is - begin - Put_Line (Calc.Z'Img); - end Main; - - In this example, there is more than one valid order of elaboration. For - example both the following are correct orders: - - Init_Constants spec - Constants spec - Calc spec - Main body - Init_Constants body - - and - - Init_Constants spec - Init_Constants body - Constants spec - Calc spec - Main body - - There is no language rule to prefer one or the other, both are correct - from an order of elaboration point of view. But the programmatic effects - of the two orders are very different. In the first, the elaboration - routine of `Calc' initializes `Z' to zero, and then the main program - runs with this value of zero. But in the second order, the elaboration - routine of `Calc' runs after the body of Init_Constants has set `X' and - `Y' and thus `Z' is set to 7 before `Main' runs. - - One could perhaps by applying pretty clever non-artificial - intelligence to the situation guess that it is more likely that the - second order of elaboration is the one desired, but there is no formal - linguistic reason to prefer one over the other. In fact in this - particular case, GNAT will prefer the second order, because of the rule - that bodies are elaborated as soon as possible, but it's just luck that - this is what was wanted (if indeed the second order was preferred). - - If the program cares about the order of elaboration routines in a - case like this, it is important to specify the order required. In this - particular case, that could have been achieved by adding to the spec of - Calc: - - pragma Elaborate_All (Constants); - - which requires that the body (if any) and spec of `Constants', as well - as the body and spec of any unit `with''ed by `Constants' be elaborated - before `Calc' is elaborated. - - Clearly no automatic method can always guess which alternative you - require, and if you are working with legacy code that had constraints - of this kind which were not properly specified by adding `Elaborate' or - `Elaborate_All' pragmas, then indeed it is possible that two different - compilers can choose different orders. - - The `GNAT BIND' `/PESSIMISTIC_ELABORATION' qualifier may be useful - in smoking out problems. This qualifier causes bodies to be elaborated - as late as possible instead of as early as possible. In the example - above, it would have forced the choice of the first elaboration order. - If you get different results when using this qualifier, and - particularly if one set of results is right, and one is wrong as far as - you are concerned, it shows that you have some missing `Elaborate' - pragmas. For the example above, we have the following output: - - GNAT MAKE -f -q main - main - 7 - GNAT MAKE -f -q main /BINDER_QUALIFIERS -p - main - 0 - - It is of course quite unlikely that both these results are correct, so - it is up to you in a case like this to investigate the source of the - difference, by looking at the two elaboration orders that are chosen, - and figuring out which is correct, and then adding the necessary - `Elaborate_All' pragmas to ensure the desired order. - -  - File: gnat_ug_vms.info, Node: The Cross-Referencing Tools GNAT XREF and GNAT FIND, Next: File Name Krunching Using GNAT KRUNCH, Prev: Elaboration Order Handling in GNAT, Up: Top - - The Cross-Referencing Tools `GNAT XREF' and `GNAT FIND' - ******************************************************* - - The compiler generates cross-referencing information (unless you set - the `/XREF=SUPPRESS' qualifier), which are saved in the `.ALI' files. - This information indicates where in the source each entity is declared - and referenced. Note that entities in package Standard are not - included, but entities in all other predefined units are included in - the output. - - Before using any of these two tools, you need to compile - successfully your application, so that GNAT gets a chance to generate - the cross-referencing information. - - The two tools `GNAT XREF' and `GNAT FIND' take advantage of this - information to provide the user with the capability to easily locate the - declaration and references to an entity. These tools are quite similar, - the difference being that `GNAT FIND' is intended for locating - definitions and/or references to a specified entity or entities, whereas - `GNAT XREF' is oriented to generating a full report of all - cross-references. - - To use these tools, you must not compile your application using the - `/XREF=SUPPRESS' qualifier on the `GNAT MAKE' command line (*note - (gnat_ug)The GNAT Make Program GNAT MAKE::). Otherwise, - cross-referencing information will not be generated. - - * Menu: - - * GNAT XREF Qualifiers:: - * GNAT FIND Qualifiers:: - * Project Files for GNAT XREF and GNAT FIND:: - * Regular Expressions in GNAT FIND and GNAT XREF:: - * Examples of GNAT XREF Usage:: - * Examples of GNAT FIND Usage:: - -  - File: gnat_ug_vms.info, Node: GNAT XREF Qualifiers, Next: GNAT FIND Qualifiers, Up: The Cross-Referencing Tools GNAT XREF and GNAT FIND - - `GNAT XREF' Qualifiers - ====================== - - The command lines for `GNAT XREF' is: - $ GNAT XREF [qualifiers] sourcefile1 [sourcefile2 ...] - - where - - `sourcefile1, sourcefile2' - identifies the source files for which a report is to be generated. - The 'with'ed units will be processed too. You must provide at - least one file. - - These file names are considered to be regular expressions, so for - instance specifying 'source*.ADB' is the same as giving every file - in the current directory whose name starts with 'source' and whose - extension is 'adb'. - - The qualifiers can be : - `/ALL_FILES' - If this qualifier is present, `GNAT FIND' and `GNAT XREF' will - parse the read-only files found in the library search path. - Otherwise, these files will be ignored. This option can be used to - protect Gnat sources or your own libraries from being parsed, thus - making `GNAT FIND' and `GNAT XREF' much faster, and their output - much smaller. - - `/SOURCE_SEARCH=direc' - When looking for source files also look in directory DIR. The - order in which source file search is undertaken is the same as for - `GNAT MAKE'. - - `/OBJECT_SEARCH=direc' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is the same as - for `GNAT MAKE'. - - `/NOSTD_INCLUDES' - Do not look for sources in the system default directory. - - `/NOSTD_LIBRARIES' - Do not look for library files in the system default directory. - - `/RUNTIME_SYSTEM=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `GNAT MAKE' flag (see *Note Qualifiers - for GNAT MAKE::). - - `-d' - If this qualifier is set `GNAT XREF' will output the parent type - reference for each matching derived types. - - `/FULL_PATHNAME' - If this qualifier is set, the output file names will be preceded - by their directory (if the file was found in the search path). If - this qualifier is not set, the directory will not be printed. - - `/IGNORE_LOCALS' - If this qualifier is set, information is output only for - library-level entities, ignoring local entities. The use of this - qualifier may accelerate `GNAT FIND' and `GNAT XREF'. - - `/SEARCH=direc' - Equivalent to `/OBJECT_SEARCH=direc /SOURCE_SEARCH=direc'. - - `/PROJECT=file' - Specify a project file to use *Note Project Files::. By default, - `GNAT XREF' and `GNAT FIND' will try to locate a project file in - the current directory. - - If a project file is either specified or found by the tools, then - the content of the source directory and object directory lines are - added as if they had been specified respectively by - `/SOURCE_SEARCH' and `OBJECT_SEARCH'. - - `/UNUSED' - Output only unused symbols. This may be really useful if you give - your main compilation unit on the command line, as `GNAT XREF' - will then display every unused entity and 'with'ed package. - - All these qualifiers may be in any order on the command line, and - may even appear after the file names. They need not be separated by - spaces, thus you can say `GNAT XREF /ALL_FILES/IGNORE_LOCALS' instead of - `GNAT XREF /ALL_FILES /IGNORE_LOCALS'. - -  - File: gnat_ug_vms.info, Node: GNAT FIND Qualifiers, Next: Project Files for GNAT XREF and GNAT FIND, Prev: GNAT XREF Qualifiers, Up: The Cross-Referencing Tools GNAT XREF and GNAT FIND - - `GNAT FIND' Qualifiers - ====================== - - The command line for `GNAT FIND' is: - - $ GNAT FIND [qualifiers] pattern[:sourcefile[:line[:column]]] - [file1 file2 ...] - - where - - `pattern' - An entity will be output only if it matches the regular expression - found in `pattern', see *Note Regular Expressions in GNAT FIND and - GNAT XREF::. - - Omitting the pattern is equivalent to specifying `*', which will - match any entity. Note that if you do not provide a pattern, you - have to provide both a sourcefile and a line. - - Entity names are given in Latin-1, with uppercase/lowercase - equivalence for matching purposes. At the current time there is no - support for 8-bit codes other than Latin-1, or for wide characters - in identifiers. - - `sourcefile' - `GNAT FIND' will look for references, bodies or declarations of - symbols referenced in `sourcefile', at line `line' and column - `column'. See *note Examples of GNAT FIND Usage:: for syntax - examples. - - `line' - is a decimal integer identifying the line number containing the - reference to the entity (or entities) to be located. - - `column' - is a decimal integer identifying the exact location on the line of - the first character of the identifier for the entity reference. - Columns are numbered from 1. - - `file1 file2 ...' - The search will be restricted to these files. If none are given, - then the search will be done for every library file in the search - path. These file must appear only after the pattern or sourcefile. - - These file names are considered to be regular expressions, so for - instance specifying 'source*.ADB' is the same as giving every file - in the current directory whose name starts with 'source' and whose - extension is 'adb'. - - Not that if you specify at least one file in this part, `GNAT - FIND' may sometimes not be able to find the body of the - subprograms... - - At least one of 'sourcefile' or 'pattern' has to be present on the - command line. - - The following qualifiers are available: - `/ALL_FILES' - If this qualifier is present, `GNAT FIND' and `GNAT XREF' will - parse the read-only files found in the library search path. - Otherwise, these files will be ignored. This option can be used to - protect Gnat sources or your own libraries from being parsed, thus - making `GNAT FIND' and `GNAT XREF' much faster, and their output - much smaller. - - `/SOURCE_SEARCH=direc' - When looking for source files also look in directory DIR. The - order in which source file search is undertaken is the same as for - `GNAT MAKE'. - - `/OBJECT_SEARCH=direc' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is the same as - for `GNAT MAKE'. - - `/NOSTD_INCLUDES' - Do not look for sources in the system default directory. - - `/NOSTD_LIBRARIES' - Do not look for library files in the system default directory. - - `/RUNTIME_SYSTEM=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `GNAT MAKE' flag (see *Note Qualifiers - for GNAT MAKE::). - - `-d' - If this qualifier is set, then `GNAT FIND' will output the parent - type reference for each matching derived types. - - `/EXPRESSIONS' - By default, `GNAT FIND' accept the simple regular expression set - for `pattern'. If this qualifier is set, then the pattern will be - considered as full Unix-style regular expression. - - `/FULL_PATHNAME' - If this qualifier is set, the output file names will be preceded - by their directory (if the file was found in the search path). If - this qualifier is not set, the directory will not be printed. - - `/IGNORE_LOCALS' - If this qualifier is set, information is output only for - library-level entities, ignoring local entities. The use of this - qualifier may accelerate `GNAT FIND' and `GNAT XREF'. - - `/SEARCH=direc' - Equivalent to `/OBJECT_SEARCH=direc /SOURCE_SEARCH=direc'. - - `/PROJECT=file' - Specify a project file (*note Project Files::) to use. By - default, `GNAT XREF' and `GNAT FIND' will try to locate a project - file in the current directory. - - If a project file is either specified or found by the tools, then - the content of the source directory and object directory lines are - added as if they had been specified respectively by - `/SOURCE_SEARCH' and `/OBJECT_SEARCH'. - - `/REFERENCES' - By default, `GNAT FIND' will output only the information about the - declaration, body or type completion of the entities. If this - qualifier is set, the `GNAT FIND' will locate every reference to - the entities in the files specified on the command line (or in - every file in the search path if no file is given on the command - line). - - `/PRINT_LINES' - If this qualifier is set, then `GNAT FIND' will output the content - of the Ada source file lines were the entity was found. - - `-t' - If this qualifier is set, then `GNAT FIND' will output the type - hierarchy for the specified type. It act like -d option but - recursively from parent type to parent type. When this qualifier - is set it is not possible to specify more than one file. - - All these qualifiers may be in any order on the command line, and - may even appear after the file names. They need not be separated by - spaces, thus you can say `GNAT XREF /ALL_FILES/IGNORE_LOCALS' instead of - `GNAT XREF /ALL_FILES /IGNORE_LOCALS'. - - As stated previously, GNAT FIND will search in every directory in the - search path. You can force it to look only in the current directory if - you specify `*' at the end of the command line. - -  - File: gnat_ug_vms.info, Node: Project Files for GNAT XREF and GNAT FIND, Next: Regular Expressions in GNAT FIND and GNAT XREF, Prev: GNAT FIND Qualifiers, Up: The Cross-Referencing Tools GNAT XREF and GNAT FIND - - Project Files for `GNAT XREF' and `GNAT FIND' - ============================================= - - Project files allow a programmer to specify how to compile its - application, where to find sources,... These files are used primarily by - the Glide Ada mode, but they can also be used by the two tools `GNAT - XREF' and `GNAT FIND'. - - A project file name must end with `.adp'. If a single one is present - in the current directory, then `GNAT XREF' and `GNAT FIND' will extract - the information from it. If multiple project files are found, none of - them is read, and you have to use the `-p' qualifier to specify the one - you want to use. - - The following lines can be included, even though most of them have - default values which can be used in most cases. The lines can be - entered in any order in the file. Except for `src_dir' and `obj_dir', - you can only have one instance of each line. If you have multiple - instances, only the last one is taken into account. - - `src_dir=DIR [default: "[]"]' - specifies a directory where to look for source files. Multiple - src_dir lines can be specified and they will be searched in the - order they are specified. - - `obj_dir=DIR [default: "[]"]' - specifies a directory where to look for object and library files. - Multiple obj_dir lines can be specified and they will be searched - in the order they are specified - - `comp_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${comp_opt}' notation. This is intended to store the default - qualifiers given to `GNAT MAKE' and `GNAT COMPILE'. - - `bind_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${bind_opt}' notation. This is intended to store the default - qualifiers given to `GNAT BIND'. - - `link_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${link_opt}' notation. This is intended to store the default - qualifiers given to `GNAT LINK'. - - `main=EXECUTABLE [default: ""]' - specifies the name of the executable for the application. This - variable can be referred to in the following lines by using the - `${main}' notation. - - `comp_cmd=COMMAND [default: "GNAT COMPILE /SEARCH=${src_dir} /DEBUG /TRY_SEMANTICS"]' - specifies the command used to compile a single file in the - application. - - `make_cmd=COMMAND [default: "GNAT MAKE ${main} /SOURCE_SEARCH=${src_dir} /OBJECT_SEARCH=${obj_dir} /DEBUG /TRY_SEMANTICS /COMPILER_QUALIFIERS ${comp_opt} /BINDER_QUALIFIERS ${bind_opt} /LINKER_QUALIFIERS ${link_opt}"]' - specifies the command used to recompile the whole application. - - `run_cmd=COMMAND [default: "${main}"]' - specifies the command used to run the application. - - `debug_cmd=COMMAND [default: "GDB ${main}"]' - specifies the command used to debug the application - - `GNAT XREF' and `GNAT FIND' only take into account the `src_dir' and - `obj_dir' lines, and ignore the others. - -  - File: gnat_ug_vms.info, Node: Regular Expressions in GNAT FIND and GNAT XREF, Next: Examples of GNAT XREF Usage, Prev: Project Files for GNAT XREF and GNAT FIND, Up: The Cross-Referencing Tools GNAT XREF and GNAT FIND - - Regular Expressions in `GNAT FIND' and `GNAT XREF' - ================================================== - - As specified in the section about `GNAT FIND', the pattern can be a - regular expression. Actually, there are to set of regular expressions - which are recognized by the program : - - `globbing patterns' - These are the most usual regular expression. They are the same - that you generally used in a Unix shell command line, or in a DOS - session. - - Here is a more formal grammar : - regexp ::= term - term ::= elmt -- matches elmt - term ::= elmt elmt -- concatenation (elmt then elmt) - term ::= * -- any string of 0 or more characters - term ::= ? -- matches any character - term ::= [char {char}] -- matches any character listed - term ::= [char - char] -- matches any character in range - - `full regular expression' - The second set of regular expressions is much more powerful. This - is the type of regular expressions recognized by utilities such a - `grep'. - - The following is the form of a regular expression, expressed in Ada - reference manual style BNF is as follows - - regexp ::= term {| term} -- alternation (term or term ...) - - term ::= item {item} -- concatenation (item then item) - - item ::= elmt -- match elmt - item ::= elmt * -- zero or more elmt's - item ::= elmt + -- one or more elmt's - item ::= elmt ? -- matches elmt or nothing - elmt ::= nschar -- matches given character - elmt ::= [nschar {nschar}] -- matches any character listed - elmt ::= [^ nschar {nschar}] -- matches any character not listed - elmt ::= [char - char] -- matches chars in given range - elmt ::= \ char -- matches given character - elmt ::= . -- matches any single character - elmt ::= ( regexp ) -- parens used for grouping - - char ::= any character, including special characters - nschar ::= any character except ()[].*+?^ - - Following are a few examples : - - `abcde|fghi' - will match any of the two strings 'abcde' and 'fghi'. - - `abc*d' - will match any string like 'abd', 'abcd', 'abccd', 'abcccd', - and so on - - `[a-z]+' - will match any string which has only lowercase characters in - it (and at least one character - -  - File: gnat_ug_vms.info, Node: Examples of GNAT XREF Usage, Next: Examples of GNAT FIND Usage, Prev: Regular Expressions in GNAT FIND and GNAT XREF, Up: The Cross-Referencing Tools GNAT XREF and GNAT FIND - - Examples of `GNAT XREF' Usage - ============================= - - General Usage - ------------- - - For the following examples, we will consider the following units : - - MAIN.ADS: - 1: with Bar; - 2: package Main is - 3: procedure Foo (B : in Integer); - 4: C : Integer; - 5: private - 6: D : Integer; - 7: end Main; - - MAIN.ADB: - 1: package body Main is - 2: procedure Foo (B : in Integer) is - 3: begin - 4: C := B; - 5: D := B; - 6: Bar.Print (B); - 7: Bar.Print (C); - 8: end Foo; - 9: end Main; - - BAR.ADS: - 1: package Bar is - 2: procedure Print (B : Integer); - 3: end bar; - - The first thing to do is to recompile your application (for - instance, in that case just by doing a `GNAT MAKE main', so that - GNAT generates the cross-referencing information. You can then - issue any of the following commands: - - `GNAT XREF MAIN.ADB' - `GNAT XREF' generates cross-reference information for MAIN.ADB and - every unit 'with'ed by MAIN.ADB. - - The output would be: - B Type: Integer - Decl: BAR.ADS 2:22 - B Type: Integer - Decl: MAIN.ADS 3:20 - Body: MAIN.ADB 2:20 - Ref: MAIN.ADB 4:13 5:13 6:19 - Bar Type: Unit - Decl: BAR.ADS 1:9 - Ref: MAIN.ADB 6:8 7:8 - MAIN.ADS 1:6 - C Type: Integer - Decl: MAIN.ADS 4:5 - Modi: MAIN.ADB 4:8 - Ref: MAIN.ADB 7:19 - D Type: Integer - Decl: MAIN.ADS 6:5 - Modi: MAIN.ADB 5:8 - Foo Type: Unit - Decl: MAIN.ADS 3:15 - Body: MAIN.ADB 2:15 - Main Type: Unit - Decl: MAIN.ADS 2:9 - Body: MAIN.ADB 1:14 - Print Type: Unit - Decl: BAR.ADS 2:15 - Ref: MAIN.ADB 6:12 7:12 - - that is the entity `Main' is declared in MAIN.ADS, line 2, column - 9, its body is in MAIN.ADB, line 1, column 14 and is not - referenced any where. - - The entity `Print' is declared in BAR.ADS, line 2, column 15 and it - it referenced in MAIN.ADB, line 6 column 12 and line 7 column 12. - - `GNAT XREF PACKAGE1.ADB PACKAGE2.ADS' - `GNAT XREF' will generates cross-reference information for - PACKAGE1.ADB, PACKAGE2.ADS and any other package 'with'ed by any - of these. - -  - File: gnat_ug_vms.info, Node: Examples of GNAT FIND Usage, Prev: Examples of GNAT XREF Usage, Up: The Cross-Referencing Tools GNAT XREF and GNAT FIND - - Examples of `GNAT FIND' Usage - ============================= - - `GNAT FIND /FULL_PATHNAME xyz:MAIN.ADB' - Find declarations for all entities xyz referenced at least once in - MAIN.ADB. The references are search in every library file in the - search path. - - The directories will be printed as well (as the `/FULL_PATHNAME' - qualifier is set) - - The output will look like: - [directory]MAIN.ADS:106:14: xyz <= declaration - [directory]MAIN.ADB:24:10: xyz <= body - [directory]FOO.ADS:45:23: xyz <= declaration - - that is to say, one of the entities xyz found in MAIN.ADB is - declared at line 12 of MAIN.ADS (and its body is in MAIN.ADB), and - another one is declared at line 45 of FOO.ADS - - `GNAT FIND /FULL_PATHNAME/SOURCE_LINE xyz:MAIN.ADB' - This is the same command as the previous one, instead `GNAT FIND' - will display the content of the Ada source file lines. - - The output will look like: - - [directory]MAIN.ADS:106:14: xyz <= declaration - procedure xyz; - [directory]MAIN.ADB:24:10: xyz <= body - procedure xyz is - [directory]FOO.ADS:45:23: xyz <= declaration - xyz : Integer; - - This can make it easier to find exactly the location your are - looking for. - - `GNAT FIND /REFERENCES "*x*":MAIN.ADS:123 FOO.ADB' - Find references to all entities containing an x that are - referenced on line 123 of MAIN.ADS. The references will be - searched only in MAIN.ADB and FOO.ADB. - - `GNAT FIND MAIN.ADS:123' - Find declarations and bodies for all entities that are referenced - on line 123 of MAIN.ADS. - - This is the same as `GNAT FIND "*":MAIN.ADB:123'. - - `GNAT FIND [mydir]MAIN.ADB:123:45' - Find the declaration for the entity referenced at column 45 in - line 123 of file MAIN.ADB in directory mydir. Note that it is - usual to omit the identifier name when the column is given, since - the column position identifies a unique reference. - - The column has to be the beginning of the identifier, and should - not point to any character in the middle of the identifier. - -  - File: gnat_ug_vms.info, Node: File Name Krunching Using GNAT KRUNCH, Next: Preprocessing Using GNAT PREPROCESS, Prev: The Cross-Referencing Tools GNAT XREF and GNAT FIND, Up: Top - - File Name Krunching Using `GNAT KRUNCH' - *************************************** - - This chapter discusses the method used by the compiler to shorten the - default file names chosen for Ada units so that they do not exceed the - maximum length permitted. It also describes the `GNAT KRUNCH' utility - that can be used to determine the result of applying this shortening. - - * Menu: - - * About GNAT KRUNCH:: - * Using GNAT KRUNCH:: - * Krunching Method:: - * Examples of GNAT KRUNCH Usage:: - -  - File: gnat_ug_vms.info, Node: About GNAT KRUNCH, Next: Using GNAT KRUNCH, Up: File Name Krunching Using GNAT KRUNCH - - About `GNAT KRUNCH' - =================== - - The default file naming rule in GNAT is that the file name must be - derived from the unit name. The exact default rule is as follows: - * Take the unit name and replace all dots by hyphens. - - * If such a replacement occurs in the second character position of a - name, and the first character is A, G, S, or I then replace the - dot by the character $ (dollar sign) instead of a minus. - The reason for this exception is to avoid clashes with the standard - names for children of System, Ada, Interfaces, and GNAT, which use the - prefixes S- A- I- and G- respectively. - - The `/FILE_NAME_MAX_LENGTH=NN' qualifier of the compiler activates a - "krunching" circuit that limits file names to nn characters (where nn - is a decimal integer). For example, using OpenVMS, where the maximum - file name length is 39, the value of nn is usually set to 39, but if - you want to generate a set of files that would be usable if ported to a - system with some different maximum file length, then a different value - can be specified. The default value of 39 for OpenVMS need not be - specified. - - The `GNAT KRUNCH' utility can be used to determine the krunched name - for a given file, when krunched to a specified maximum length. - -  - File: gnat_ug_vms.info, Node: Using GNAT KRUNCH, Next: Krunching Method, Prev: About GNAT KRUNCH, Up: File Name Krunching Using GNAT KRUNCH - - Using `GNAT KRUNCH' - =================== - - The `GNAT KRUNCH' command has the form - - $ GNAT KRUNCH NAME /COUNT=nn - - NAME can be an Ada name with dots or the GNAT name of the unit, where - the dots representing child units or subunit are replaced by hyphens. - The only confusion arises if a name ends in `.ADS' or `.ADB'. `GNAT - KRUNCH' takes this to be an extension if there are no other dots in the - name. - - LENGTH represents the length of the krunched name. The default when - no argument is given is 39 characters. A length of zero stands for - unlimited, in other words do not chop except for system files which are - always 39. - - The output is the krunched name. The output has an extension only if the - original argument was a file name with an extension. - -  - File: gnat_ug_vms.info, Node: Krunching Method, Next: Examples of GNAT KRUNCH Usage, Prev: Using GNAT KRUNCH, Up: File Name Krunching Using GNAT KRUNCH - - Krunching Method - ================ - - The initial file name is determined by the name of the unit that the - file contains. The name is formed by taking the full expanded name of - the unit and replacing the separating dots with hyphens and using - uppercase for all letters, except that a hyphen in the second character - position is replaced by a dollar sign if the first character is A, I, - G, or S. The extension is `.ADS' for a specification and `.ADB' for a - body. Krunching does not affect the extension, but the file name is - shortened to the specified length by following these rules: - - * The name is divided into segments separated by hyphens, tildes or - underscores and all hyphens, tildes, and underscores are - eliminated. If this leaves the name short enough, we are done. - - * If the name is too long, the longest segment is located (left-most - if there are two of equal length), and shortened by dropping its - last character. This is repeated until the name is short enough. - - As an example, consider the krunching of - `OUR-STRINGS-WIDE_FIXED.ADB' to fit the name into 8 characters as - required by some operating systems. - - our-strings-wide_fixed 22 - our strings wide fixed 19 - our string wide fixed 18 - our strin wide fixed 17 - our stri wide fixed 16 - our stri wide fixe 15 - our str wide fixe 14 - our str wid fixe 13 - our str wid fix 12 - ou str wid fix 11 - ou st wid fix 10 - ou st wi fix 9 - ou st wi fi 8 - Final file name: OUSTWIFI.ADB - - * The file names for all predefined units are always krunched to - eight characters. The krunching of these predefined units uses the - following special prefix replacements: - - `ada-' - replaced by `A-' - - `gnat-' - replaced by `G-' - - `interfaces-' - replaced by `I-' - - `system-' - replaced by `S-' - - These system files have a hyphen in the second character position. - That is why normal user files replace such a character with a - dollar sign, to avoid confusion with system file names. - - As an example of this special rule, consider - `ADA-STRINGS-WIDE_FIXED.ADB', which gets krunched as follows: - - ada-strings-wide_fixed 22 - a- strings wide fixed 18 - a- string wide fixed 17 - a- strin wide fixed 16 - a- stri wide fixed 15 - a- stri wide fixe 14 - a- str wide fixe 13 - a- str wid fixe 12 - a- str wid fix 11 - a- st wid fix 10 - a- st wi fix 9 - a- st wi fi 8 - Final file name: A-STWIFI.ADB - - Of course no file shortening algorithm can guarantee uniqueness over - all possible unit names, and if file name krunching is used then it is - your responsibility to ensure that no name clashes occur. The utility - program `GNAT KRUNCH' is supplied for conveniently determining the - krunched name of a file. - -  - File: gnat_ug_vms.info, Node: Examples of GNAT KRUNCH Usage, Prev: Krunching Method, Up: File Name Krunching Using GNAT KRUNCH - - Examples of `GNAT KRUNCH' Usage - =============================== - - $ GNAT KRUNCH VERY_LONG_UNIT_NAME.ADS/count=6 --> VLUNNA.ADS - $ GNAT KRUNCH VERY_LONG_UNIT_NAME.ADS/count=0 --> VERY_LONG_UNIT_NAME.ADS - -  - File: gnat_ug_vms.info, Node: Preprocessing Using GNAT PREPROCESS, Next: The GNAT Run-Time Library Builder GNAT LIBRARY, Prev: File Name Krunching Using GNAT KRUNCH, Up: Top - - Preprocessing Using `GNAT PREPROCESS' - ************************************* - - The `GNAT PREPROCESS' utility provides a simple preprocessing - capability for Ada programs. It is designed for use with GNAT, but is - not dependent on any special features of GNAT. - - * Menu: - - * Using GNAT PREPROCESS:: - * Qualifiers for GNAT PREPROCESS:: - * Form of Definitions File:: - * Form of Input Text for GNAT PREPROCESS:: - -  - File: gnat_ug_vms.info, Node: Using GNAT PREPROCESS, Next: Qualifiers for GNAT PREPROCESS, Up: Preprocessing Using GNAT PREPROCESS - - Using `GNAT PREPROCESS' - ======================= - - To call `GNAT PREPROCESS' use - - $ GNAT PREPROCESS [-bcrsu] [-Dsymbol=value] infile outfile [deffile] - - where - `infile' - is the full name of the input file, which is an Ada source file - containing preprocessor directives. - - `outfile' - is the full name of the output file, which is an Ada source in - standard Ada form. When used with GNAT, this file name will - normally have an ads or adb suffix. - - `deffile' - is the full name of a text file containing definitions of symbols - to be referenced by the preprocessor. This argument is optional, - and can be replaced by the use of the `-D' qualifier. - - `qualifiers' - is an optional sequence of qualifiers as described in the next - section. - -  - File: gnat_ug_vms.info, Node: Qualifiers for GNAT PREPROCESS, Next: Form of Definitions File, Prev: Using GNAT PREPROCESS, Up: Preprocessing Using GNAT PREPROCESS - - Qualifiers for `GNAT PREPROCESS' - ================================ - - `/BLANK_LINES' - Causes both preprocessor lines and the lines deleted by - preprocessing to be replaced by blank lines in the output source - file, preserving line numbers in the output file. - - `/COMMENTS' - Causes both preprocessor lines and the lines deleted by - preprocessing to be retained in the output source as comments - marked with the special string "-! ". This option will result in - line numbers being preserved in the output file. - - `-Dsymbol=value' - Defines a new symbol, associated with value. If no value is given - on the command line, then symbol is considered to be `True'. This - qualifier can be used in place of a definition file. - - `/REMOVE (default)' - This is the default setting which causes lines deleted by - preprocessing to be entirely removed from the output file. - - `/REFERENCE' - Causes a `Source_Reference' pragma to be generated that references - the original input file, so that error messages will use the file - name of this original file. The use of this qualifier implies that - preprocessor lines are not to be removed from the file, so its use - will force `/BLANK_LINES' mode if `/COMMENTS' has not been - specified explicitly. - - Note that if the file to be preprocessed contains multiple units, - then it will be necessary to `GNAT CHOP' the output file from - `GNAT PREPROCESS'. If a `Source_Reference' pragma is present in - the preprocessed file, it will be respected by `GNAT CHOP - /REFERENCE' so that the final chopped files will correctly refer - to the original input source file for `GNAT PREPROCESS'. - - `/SYMBOLS' - Causes a sorted list of symbol names and values to be listed on - the standard output file. - - `/UNDEFINED' - Causes undefined symbols to be treated as having the value FALSE - in the context of a preprocessor test. In the absence of this - option, an undefined symbol in a `#if' or `#elsif' test will be - treated as an error. - -  - File: gnat_ug_vms.info, Node: Form of Definitions File, Next: Form of Input Text for GNAT PREPROCESS, Prev: Qualifiers for GNAT PREPROCESS, Up: Preprocessing Using GNAT PREPROCESS - - Form of Definitions File - ======================== - - The definitions file contains lines of the form - - symbol := value - - where symbol is an identifier, following normal Ada (case-insensitive) - rules for its syntax, and value is one of the following: - - * Empty, corresponding to a null substitution - - * A string literal using normal Ada syntax - - * Any sequence of characters from the set (letters, digits, period, - underline). - - Comment lines may also appear in the definitions file, starting with - the usual `--', and comments may be added to the definitions lines. - -  - File: gnat_ug_vms.info, Node: Form of Input Text for GNAT PREPROCESS, Prev: Form of Definitions File, Up: Preprocessing Using GNAT PREPROCESS - - Form of Input Text for `GNAT PREPROCESS' - ======================================== - - The input text may contain preprocessor conditional inclusion lines, as - well as general symbol substitution sequences. - - The preprocessor conditional inclusion commands have the form - - #if expression [then] - lines - #elsif expression [then] - lines - #elsif expression [then] - lines - ... - #else - lines - #end if; - - In this example, expression is defined by the following grammar: - expression ::= - expression ::= = "" - expression ::= = - expression ::= 'Defined - expression ::= not expression - expression ::= expression and expression - expression ::= expression or expression - expression ::= expression and then expression - expression ::= expression or else expression - expression ::= ( expression ) - - For the first test (expression ::= ) the symbol must have - either the value true or false, that is to say the right-hand of the - symbol definition must be one of the (case-insensitive) literals `True' - or `False'. If the value is true, then the corresponding lines are - included, and if the value is false, they are excluded. - - The test (expression ::= `'Defined') is true only if the - symbol has been defined in the definition file or by a `-D' qualifier - on the command line. Otherwise, the test is false. - - The equality tests are case insensitive, as are all the preprocessor - lines. - - If the symbol referenced is not defined in the symbol definitions - file, then the effect depends on whether or not qualifier `-u' is - specified. If so, then the symbol is treated as if it had the value - false and the test fails. If this qualifier is not specified, then it - is an error to reference an undefined symbol. It is also an error to - reference a symbol that is defined with a value other than `True' or - `False'. - - The use of the `not' operator inverts the sense of this logical - test, so that the lines are included only if the symbol is not defined. - The `then' keyword is optional as shown - - The `#' must be the first non-blank character on a line, but - otherwise the format is free form. Spaces or tabs may appear between - the `#' and the keyword. The keywords and the symbols are case - insensitive as in normal Ada code. Comments may be used on a - preprocessor line, but other than that, no other tokens may appear on a - preprocessor line. Any number of `elsif' clauses can be present, - including none at all. The `else' is optional, as in Ada. - - The `#' marking the start of a preprocessor line must be the first - non-blank character on the line, i.e. it must be preceded only by - spaces or horizontal tabs. - - Symbol substitution outside of preprocessor lines is obtained by - using the sequence - - $symbol - - anywhere within a source line, except in a comment or within a string - literal. The identifier following the `$' must match one of the symbols - defined in the symbol definition file, and the result is to substitute - the value of the symbol in place of `$symbol' in the output file. - - Note that although the substitution of strings within a string - literal is not possible, it is possible to have a symbol whose defined - value is a string literal. So instead of setting XYZ to `hello' and - writing: - - Header : String := "$XYZ"; - - you should set XYZ to `"hello"' and write: - - Header : String := $XYZ; - - and then the substitution will occur as desired. - -  - File: gnat_ug_vms.info, Node: The GNAT Run-Time Library Builder GNAT LIBRARY, Next: The GNAT Library Browser GNAT LIST, Prev: Preprocessing Using GNAT PREPROCESS, Up: Top - - The GNAT Run-Time Library Builder `GNAT LIBRARY' - ************************************************ - - `GNAT LIBRARY' is a tool for rebuilding the GNAT run time with user - supplied configuration pragmas. - - * Menu: - - * Running GNAT LIBRARY:: - * Qualifiers for GNAT LIBRARY:: - * Examples of GNAT LIBRARY Usage:: - -  - File: gnat_ug_vms.info, Node: Running GNAT LIBRARY, Next: Qualifiers for GNAT LIBRARY, Up: The GNAT Run-Time Library Builder GNAT LIBRARY - - Running `GNAT LIBRARY' - ====================== - - The `GNAT LIBRARY' command has the form - - $ GNAT LIBRARY /[CREATE | SET | DELETE]=directory [/CONFIG=file] - -  - File: gnat_ug_vms.info, Node: Qualifiers for GNAT LIBRARY, Next: Examples of GNAT LIBRARY Usage, Prev: Running GNAT LIBRARY, Up: The GNAT Run-Time Library Builder GNAT LIBRARY - - Qualifiers for `GNAT LIBRARY' - ============================= - - `GNAT LIBRARY' recognizes the following qualifiers: - - `/CREATE=directory' - Create the new run-time library in the specified directory. - - `/SET=directory' - Make the library in the specified directory the current run-time - library. - - `/DELETE=directory' - Delete the run-time library in the specified directory. - - `/CONFIG=file' - With /CREATE: Use the configuration pragmas in the specified - file when building the library. - - With /SET: Use the configuration pragmas in the specified - file when compiling. - -  - File: gnat_ug_vms.info, Node: Examples of GNAT LIBRARY Usage, Prev: Qualifiers for GNAT LIBRARY, Up: The GNAT Run-Time Library Builder GNAT LIBRARY - - Example of `GNAT LIBRARY' Usage - =============================== - - Contents of VAXFLOAT.ADC: - pragma Float_Representation (VAX_Float); - - $ GNAT LIBRARY /CREATE=[.VAXFLOAT] /CONFIG=VAXFLOAT.ADC - - GNAT LIBRARY rebuilds the run-time library in directory [.VAXFLOAT] - -  - File: gnat_ug_vms.info, Node: The GNAT Library Browser GNAT LIST, Next: Finding Memory Problems with GNAT Debug Pool, Prev: The GNAT Run-Time Library Builder GNAT LIBRARY, Up: Top - - The GNAT Library Browser `GNAT LIST' - ************************************ - - `GNAT LIST' is a tool that outputs information about compiled units. It - gives the relationship between objects, unit names and source files. It - can also be used to check the source dependencies of a unit as well as - various characteristics. - - * Menu: - - * Running GNAT LIST:: - * Qualifiers for GNAT LIST:: - * Examples of GNAT LIST Usage:: - -  - File: gnat_ug_vms.info, Node: Running GNAT LIST, Next: Qualifiers for GNAT LIST, Up: The GNAT Library Browser GNAT LIST - - Running `GNAT LIST' - =================== - - The `GNAT LIST' command has the form - - $ GNAT LIST qualifiers OBJECT_OR_ALI_FILE - - The main argument is the list of object or `ali' files (*note The Ada - Library Information Files::) for which information is requested. - - In normal mode, without additional option, `GNAT LIST' produces a - four-column listing. Each line represents information for a specific - object. The first column gives the full path of the object, the second - column gives the name of the principal unit in this object, the third - column gives the status of the source and the fourth column gives the - full path of the source representing this unit. Here is a simple - example of use: - - $ GNAT LIST *.OBJ - []DEMO1.OBJ demo1 DIF DEMO1.ADB - []DEMO2.OBJ demo2 OK DEMO2.ADB - []HELLO.OBJ h1 OK HELLO.ADB - []INSTR-CHILD.OBJ instr.child MOK INSTR-CHILD.ADB - []INSTR.OBJ instr OK INSTR.ADB - []TEF.OBJ tef DIF TEF.ADB - []TEXT_IO_EXAMPLE.OBJ text_io_example OK TEXT_IO_EXAMPLE.ADB - []TGEF.OBJ tgef DIF TGEF.ADB - - The first line can be interpreted as follows: the main unit which is - contained in object file `DEMO1.OBJ' is demo1, whose main source is in - `DEMO1.ADB'. Furthermore, the version of the source used for the - compilation of demo1 has been modified (DIF). Each source file has a - status qualifier which can be: - - `OK (unchanged)' - The version of the source file used for the compilation of the - specified unit corresponds exactly to the actual source file. - - `MOK (slightly modified)' - The version of the source file used for the compilation of the - specified unit differs from the actual source file but not enough - to require recompilation. If you use GNAT MAKE with the qualifier - `/MINIMAL_RECOMPILATION', a file marked MOK will not be recompiled. - - `DIF (modified)' - No version of the source found on the path corresponds to the - source used to build this object. - - `??? (file not found)' - No source file was found for this unit. - - `HID (hidden, unchanged version not first on PATH)' - The version of the source that corresponds exactly to the source - used for compilation has been found on the path but it is hidden - by another version of the same source that has been modified. - -  - File: gnat_ug_vms.info, Node: Qualifiers for GNAT LIST, Next: Examples of GNAT LIST Usage, Prev: Running GNAT LIST, Up: The GNAT Library Browser GNAT LIST - - Qualifiers for `GNAT LIST' - ========================== - - `GNAT LIST' recognizes the following qualifiers: - - `/ALL_UNITS' - Consider all units, including those of the predefined Ada library. - Especially useful with `/DEPENDENCIES'. - - `/DEPENDENCIES' - List sources from which specified units depend on. - - `/OUTPUT=OPTIONS' - Output the list of options. - - `/OUTPUT=OBJECTS' - Only output information about object files. - - `/OUTPUT=SOURCES' - Only output information about source files. - - `/OUTPUT=UNITS' - Only output information about compilation units. - - `/OBJECT_SEARCH=DIR' - `/SOURCE_SEARCH=DIR' - `/SEARCH=DIR' - `/NOCURRENT_DIRECTORY' - `/NOSTD_INCLUDES' - Source path manipulation. Same meaning as the equivalent `GNAT - MAKE' flags (see *Note Qualifiers for GNAT MAKE::). - - `/RUNTIME_SYSTEM=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `GNAT MAKE' flag (see *Note Qualifiers - for GNAT MAKE::). - - `/OUTPUT=VERBOSE' - Verbose mode. Output the complete source and object paths. Do not - use the default column layout but instead use long format giving - as much as information possible on each requested units, including - special characteristics such as: - - `Preelaborable' - The unit is preelaborable in the Ada 95 sense. - - `No_Elab_Code' - No elaboration code has been produced by the compiler for - this unit. - - `Pure' - The unit is pure in the Ada 95 sense. - - `Elaborate_Body' - The unit contains a pragma Elaborate_Body. - - `Remote_Types' - The unit contains a pragma Remote_Types. - - `Shared_Passive' - The unit contains a pragma Shared_Passive. - - `Predefined' - This unit is part of the predefined environment and cannot be - modified by the user. - - `Remote_Call_Interface' - The unit contains a pragma Remote_Call_Interface. - -  - File: gnat_ug_vms.info, Node: Examples of GNAT LIST Usage, Prev: Qualifiers for GNAT LIST, Up: The GNAT Library Browser GNAT LIST - - Example of `GNAT LIST' Usage - ============================ - - GNAT LIST /DEPENDENCIES /OUTPUT=SOURCES /ALL_UNITS DEMO1.ADB - - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]ADA.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]A-FINALI.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]A-FILICO.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]A-STREAM.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]A-TAGS.ADS - DEMO1.ADB - GEN_LIST.ADS - GEN_LIST.ADB - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]GNAT.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]G-IO.ADS - INSTR.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]SYSTEM.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-EXCTAB.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-FINIMP.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-FINROO.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-SECSTA.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-STALIB.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-STOELE.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-STRATT.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-TASOLI.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]S-UNSTYP.ADS - GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]UNCHCONV.ADS - -  - File: gnat_ug_vms.info, Node: Finding Memory Problems with GNAT Debug Pool, Next: Creating Sample Bodies Using GNAT STUB, Prev: The GNAT Library Browser GNAT LIST, Up: Top - - Finding Memory Problems with GNAT Debug Pool - ******************************************** - - The use of unchecked deallocation and unchecked conversion can easily - lead to incorrect memory references. The problems generated by such - references are usually difficult to tackle because the symptoms can be - very remote from the origin of the problem. In such cases, it is very - helpful to detect the problem as early as possible. This is the purpose - of the Storage Pool provided by `GNAT.Debug_Pools'. - - In order to use the GNAT specific debugging pool, the user must - associate a debug pool object with each of the access types that may be - related to suspected memory problems. See Ada Reference Manual 13.11. - type Ptr is access Some_Type; - Pool : GNAT.Debug_Pools.Debug_Pool; - for Ptr'Storage_Pool use Pool; - - `GNAT.Debug_Pools' is derived from of a GNAT-specific kind of pool: - the Checked_Pool. Such pools, like standard Ada storage pools, allow - the user to redefine allocation and deallocation strategies. They also - provide a checkpoint for each dereference, through the use of the - primitive operation `Dereference' which is implicitly called at each - dereference of an access value. - - Once an access type has been associated with a debug pool, - operations on values of the type may raise four distinct exceptions, - which correspond to four potential kinds of memory corruption: - * `GNAT.Debug_Pools.Accessing_Not_Allocated_Storage' - - * `GNAT.Debug_Pools.Accessing_Deallocated_Storage' - - * `GNAT.Debug_Pools.Freeing_Not_Allocated_Storage' - - * `GNAT.Debug_Pools.Freeing_Deallocated_Storage ' - - For types associated with a Debug_Pool, dynamic allocation is performed - using the standard GNAT allocation routine. References to all allocated - chunks of memory are kept in an internal dictionary. The deallocation - strategy consists in not releasing the memory to the underlying system - but rather to fill it with a memory pattern easily recognizable during - debugging sessions: The memory pattern is the old IBM hexadecimal - convention: 16#DEADBEEF#. Upon each dereference, a check is made that - the access value denotes a properly allocated memory location. Here is - a complete example of use of `Debug_Pools', that includes typical - instances of memory corruption: - with Gnat.Io; use Gnat.Io; - with Unchecked_Deallocation; - with Unchecked_Conversion; - with GNAT.Debug_Pools; - with System.Storage_Elements; - with Ada.Exceptions; use Ada.Exceptions; - procedure Debug_Pool_Test is - - type T is access Integer; - type U is access all T; - - P : GNAT.Debug_Pools.Debug_Pool; - for T'Storage_Pool use P; - - procedure Free is new Unchecked_Deallocation (Integer, T); - function UC is new Unchecked_Conversion (U, T); - A, B : aliased T; - - procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); - - begin - Info (P); - A := new Integer; - B := new Integer; - B := A; - Info (P); - Free (A); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - B := UC(A'Access); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - Info (P); - end Debug_Pool_Test; - - The debug pool mechanism provides the following precise diagnostics on - the execution of this erroneous program: - Debug Pool info: - Total allocated bytes : 0 - Total deallocated bytes : 0 - Current Water Mark: 0 - High Water Mark: 0 - - Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 0 - Current Water Mark: 8 - High Water Mark: 8 - - raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE - Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 4 - Current Water Mark: 4 - High Water Mark: 8 - -  - File: gnat_ug_vms.info, Node: Creating Sample Bodies Using GNAT STUB, Next: Reducing the Size of Ada Executables with GNAT ELIM, Prev: Finding Memory Problems with GNAT Debug Pool, Up: Top - - Creating Sample Bodies Using `GNAT STUB' - **************************************** - - `GNAT STUB' creates body stubs, that is, empty but compilable bodies - for library unit declarations. - - To create a body stub, `GNAT STUB' has to compile the library unit - declaration. Therefore, bodies can be created only for legal library - units. Moreover, if a library unit depends semantically upon units - located outside the current directory, you have to provide the source - search path when calling `GNAT STUB', see the description of `GNAT - STUB' qualifiers below. - - * Menu: - - * Running GNAT STUB:: - * Qualifiers for GNAT STUB:: - -  - File: gnat_ug_vms.info, Node: Running GNAT STUB, Next: Qualifiers for GNAT STUB, Up: Creating Sample Bodies Using GNAT STUB - - Running `GNAT STUB' - =================== - - `GNAT STUB' has the command-line interface of the form - - $ GNAT STUB [qualifiers] filename [directory] - - where - `filename' - is the name of the source file that contains a library unit - declaration for which a body must be created. This name should - follow the GNAT file name conventions. No crunching is allowed for - this file name. The file name may contain the path information. - - `directory' - indicates the directory to place a body stub (default is the - current directory) - - `qualifiers' - is an optional sequence of qualifiers as described in the next - section - -  - File: gnat_ug_vms.info, Node: Qualifiers for GNAT STUB, Prev: Running GNAT STUB, Up: Creating Sample Bodies Using GNAT STUB - - Qualifiers for `GNAT STUB' - ========================== - - `/FULL' - If the destination directory already contains a file with a name - of the body file for the argument spec file, replace it with the - generated body stub. - - `/HEADER=SPEC' - Put the comment header (i.e. all the comments preceding the - compilation unit) from the source of the library unit declaration - into the body stub. - - `/HEADER=GENERAL' - Put a sample comment header into the body stub. - - `/SEARCH=direc' - `/NOCURRENT_DIRECTORY' - These qualifiers have the same meaning as in calls to GNAT COMPILE. - They define the source search path in the call to GNAT COMPILE - issued by `GNAT STUB' to compile an argument source file. - - `/INDENTATION=N' - (N is a decimal natural number). Set the indentation level in the - generated body sample to n, '/INDENTATION=0' means "no - indentation", the default indentation is 3. - - `/TREE_FILE=SAVE' - Do not remove the tree file (i.e. the snapshot of the compiler - internal structures used by `GNAT STUB') after creating the body - stub. - - `/LINE_LENGTH=N' - (N is a decimal positive number) Set the maximum line length in the - body stub to n, the default is 78. - - `/QUIET' - Quiet mode: do not generate a confirmation when a body is - successfully created or a message when a body is not required for - an argument unit. - - `/TREE_FILE=REUSE' - Reuse the tree file (if it exists) instead of creating it: instead - of creating the tree file for the library unit declaration, GNAT - STUB tries to find it in the current directory and use it for - creating a body. If the tree file is not found, no body is - created. `/REUSE' also implies `/SAVE', whether or not `/SAVE' is - set explicitly. - - `/TREE_FILE=OVERWRITE' - Overwrite the existing tree file: if the current directory already - contains the file which, according to the GNAT file name rules - should be considered as a tree file for the argument source file, - GNAT STUB will refuse to create the tree file needed to create a - body sampler, unless `-t' option is set - - `/VERBOSE' - Verbose mode: generate version information. - -  - File: gnat_ug_vms.info, Node: Reducing the Size of Ada Executables with GNAT ELIM, Next: Other Utility Programs, Prev: Creating Sample Bodies Using GNAT STUB, Up: Top - - Reducing the Size of Ada Executables with `GNAT ELIM' - ***************************************************** - - * Menu: - - * About GNAT ELIM:: - * Eliminate Pragma:: - * Tree Files:: - * Preparing Tree and Bind Files for GNAT ELIM:: - * Running GNAT ELIM:: - * Correcting the List of Eliminate Pragmas:: - * Making Your Executables Smaller:: - * Summary of the GNAT ELIM Usage Cycle:: - -  - File: gnat_ug_vms.info, Node: About GNAT ELIM, Next: Eliminate Pragma, Up: Reducing the Size of Ada Executables with GNAT ELIM - - About `GNAT ELIM' - ================= - - When a program shares a set of Ada packages with other programs, it may - happen that this program uses only a fraction of the subprograms - defined in these packages. The code created for these unused - subprograms increases the size of the executable. - - `GNAT ELIM' tracks unused subprograms in an Ada program and outputs - a list of GNAT-specific `Eliminate' pragmas (see next section) marking - all the subprograms that are declared but never called. By placing the - list of `Eliminate' pragmas in the GNAT configuration file `GNAT.ADC' - and recompiling your program, you may decrease the size of its - executable, because the compiler will not generate the code for - 'eliminated' subprograms. - - `GNAT ELIM' needs as its input data a set of tree files (see *Note - Tree Files::) representing all the components of a program to process - and a bind file for a main subprogram (see *Note Preparing Tree and - Bind Files for GNAT ELIM::). - -  - File: gnat_ug_vms.info, Node: Eliminate Pragma, Next: Tree Files, Prev: About GNAT ELIM, Up: Reducing the Size of Ada Executables with GNAT ELIM - - `Eliminate' Pragma - ================== - - The simplified syntax of the Eliminate pragma used by `GNAT ELIM' is: - - pragma Eliminate (Library_Unit_Name, Subprogram_Name); - - where - `Library_Unit_Name' - full expanded Ada name of a library unit - - `Subprogram_Name' - a simple or expanded name of a subprogram declared within this - compilation unit - - The effect of an `Eliminate' pragma placed in the GNAT configuration - file `GNAT.ADC' is: - - * If the subprogram `Subprogram_Name' is declared within the library - unit `Library_Unit_Name', the compiler will not generate code for - this subprogram. This applies to all overloaded subprograms denoted - by `Subprogram_Name'. - - * If a subprogram marked by the pragma `Eliminate' is used (called) - in a program, the compiler will produce an error message in the - place where it is called. - -  - File: gnat_ug_vms.info, Node: Tree Files, Next: Preparing Tree and Bind Files for GNAT ELIM, Prev: Eliminate Pragma, Up: Reducing the Size of Ada Executables with GNAT ELIM - - Tree Files - ========== - - A tree file stores a snapshot of the compiler internal data structures - at the very end of a successful compilation. It contains all the - syntactic and semantic information for the compiled unit and all the - units upon which it depends semantically. To use tools that make use - of tree files, you need to first produce the right set of tree files. - - GNAT produces correct tree files when /TREE_OUTPUT /NOLOAD options - are set in a GNAT COMPILE call. The tree files have an .adt extension. - Therefore, to produce a tree file for the compilation unit contained in - a file named `FOO.ADB', you must use the command - - $ GNAT COMPILE /NOLOAD /TREE_OUTPUT FOO.ADB - - and you will get the tree file `foo.adt'. compilation. - -  - File: gnat_ug_vms.info, Node: Preparing Tree and Bind Files for GNAT ELIM, Next: Running GNAT ELIM, Prev: Tree Files, Up: Reducing the Size of Ada Executables with GNAT ELIM - - Preparing Tree and Bind Files for `GNAT ELIM' - ============================================= - - A set of tree files covering the program to be analyzed with `GNAT - ELIM' and the bind file for the main subprogram does not have to be in - the current directory. '-T' GNAT ELIM option may be used to provide - the search path for tree files, and '-b' option may be used to point to - the bind file to process (see *Note Running GNAT ELIM::) - - If you do not have the appropriate set of tree files and the right - bind file, you may create them in the current directory using the - following procedure. - - Let `Main_Prog' be the name of a main subprogram, and suppose this - subprogram is in a file named `MAIN_PROG.ADB'. - - To create a bind file for `GNAT ELIM', run `GNAT BIND' for the main - subprogram. `GNAT ELIM' can work with both Ada and C bind files; when - both are present, it uses the Ada bind file. The following commands - will build the program and create the bind file: - - $ GNAT MAKE /ACTIONS=COMPILE MAIN_PROG - $ GNAT BIND main_prog - - To create a minimal set of tree files covering the whole program, call - `GNAT MAKE' for this program as follows: - - $ GNAT MAKE /FORCE_COMPILE /ACTIONS=COMPILE /NOLOAD /TREE_OUTPUT MAIN_PROG - - The `/ACTIONS=COMPILE' GNAT MAKE option turns off the bind and link - steps, that are useless anyway because the sources are compiled with - `/NOLOAD' option which turns off code generation. - - The `/FORCE_COMPILE' GNAT MAKE option forces recompilation of all - the needed sources. - - This sequence of actions will create all the data needed by `GNAT - ELIM' from scratch and therefore guarantee its consistency. If you - would like to use some existing set of files as `GNAT ELIM' output, you - must make sure that the set of files is complete and consistent. You - can use the `-m' qualifier to check if there are missed tree files - - Note, that `GNAT ELIM' needs neither object nor ALI files. - -  - File: gnat_ug_vms.info, Node: Running GNAT ELIM, Next: Correcting the List of Eliminate Pragmas, Prev: Preparing Tree and Bind Files for GNAT ELIM, Up: Reducing the Size of Ada Executables with GNAT ELIM - - Running `GNAT ELIM' - =================== - - `GNAT ELIM' has the following command-line interface: - - $ GNAT ELIM [options] name - - `name' should be a full expanded Ada name of a main subprogram of a - program (partition). - - `GNAT ELIM' options: - - `/QUIET' - Quiet mode: by default `GNAT ELIM' generates to the standard error - stream a trace of the source file names of the compilation units - being processed. This option turns this trace off. - - `/VERBOSE' - Verbose mode: `GNAT ELIM' version information is printed as Ada - comments to the standard output stream. - - `/ALL' - Also look for subprograms from the GNAT run time that can be - eliminated. - - `/MISSED' - Check if any tree files are missing for an accurate result. - - `/TREE_DIRS=DIR' - When looking for tree files also look in directory DIR - - `/BIND_FILE=BIND_FILE' - Specifies BIND_FILE as the bind file to process. If not set, the - name of the bind file is computed from the full expanded Ada name - of a main subprogram. - - `-dX' - Activate internal debugging qualifiers. X is a letter or digit, or - string of letters or digits, which specifies the type of debugging - mode desired. Normally these are used only for internal - development or system debugging purposes. You can find full - documentation for these qualifiers in the body of the `GNAT - ELIM.Options' unit in the compiler source file - `GNATELIM-OPTIONS.ADB'. - - `GNAT ELIM' sends its output to the standard output stream, and all the - tracing and debug information is sent to the standard error stream. In - order to produce a proper GNAT configuration file `GNAT.ADC', - redirection must be used: - - $ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC - - In order to append the `GNAT ELIM' output to the existing contents of - `GNAT.ADC'. - -  - File: gnat_ug_vms.info, Node: Correcting the List of Eliminate Pragmas, Next: Making Your Executables Smaller, Prev: Running GNAT ELIM, Up: Reducing the Size of Ada Executables with GNAT ELIM - - Correcting the List of Eliminate Pragmas - ======================================== - - In some rare cases it may happen that `GNAT ELIM' will try to eliminate - subprograms which are actually called in the program. In this case, the - compiler will generate an error message of the form: - - FILE.ADB:106:07: cannot call eliminated subprogram "My_Prog" - - You will need to manually remove the wrong `Eliminate' pragmas from the - `GNAT.ADC' file. It is advised that you recompile your program from - scratch after that because you need a consistent `GNAT.ADC' file during - the entire compilation. - -  - File: gnat_ug_vms.info, Node: Making Your Executables Smaller, Next: Summary of the GNAT ELIM Usage Cycle, Prev: Correcting the List of Eliminate Pragmas, Up: Reducing the Size of Ada Executables with GNAT ELIM - - Making Your Executables Smaller - =============================== - - In order to get a smaller executable for your program you now have to - recompile the program completely with the new `GNAT.ADC' file created - by `GNAT ELIM' in your current directory: - - $ GNAT MAKE /FORCE_COMPILE MAIN_PROG - - (you will need `/FORCE_COMPILE' option for GNAT MAKE to recompile - everything with the set of pragmas `Eliminate' you have obtained with - `GNAT ELIM'). - - Be aware that the set of `Eliminate' pragmas is specific to each - program. It is not recommended to merge sets of `Eliminate' pragmas - created for different programs in one `GNAT.ADC' file. - -  - File: gnat_ug_vms.info, Node: Summary of the GNAT ELIM Usage Cycle, Prev: Making Your Executables Smaller, Up: Reducing the Size of Ada Executables with GNAT ELIM - - Summary of the GNAT ELIM Usage Cycle - ==================================== - - Here is a quick summary of the steps to be taken in order to reduce the - size of your executables with `GNAT ELIM'. You may use other GNAT - options to control the optimization level, to produce the debugging - information, to set search path, etc. - - 1. Produce a bind file and a set of tree files - - $ GNAT MAKE /ACTIONS=COMPILE MAIN_PROG - $ GNAT BIND main_prog - $ GNAT MAKE /FORCE_COMPILE /NO_LINK /NOLOAD /TREE_OUTPUT MAIN_PROG - - 2. Generate a list of `Eliminate' pragmas - $ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC - - 3. Recompile the application - - $ GNAT MAKE /FORCE_COMPILE MAIN_PROG - - -  - File: gnat_ug_vms.info, Node: Other Utility Programs, Next: Compatibility with DEC Ada, Prev: Reducing the Size of Ada Executables with GNAT ELIM, Up: Top - - Other Utility Programs - ********************** - - This chapter discusses some other utility programs available in the Ada - environment. - - * Menu: - - * Using Other Utility Programs with GNAT:: - * The GNAT STANDARD Utility Program:: - * The External Symbol Naming Scheme of GNAT:: - * Ada Mode for Glide:: - * Converting Ada Files to html with gnathtml:: - * Installing gnathtml:: - * LSE:: - * Profiling:: - -  - File: gnat_ug_vms.info, Node: Using Other Utility Programs with GNAT, Next: The GNAT STANDARD Utility Program, Up: Other Utility Programs - - Using Other Utility Programs with GNAT - ====================================== - - The object files generated by GNAT are in standard system format and in - particular the debugging information uses this format. This means - programs generated by GNAT can be used with existing utilities that - depend on these formats. - -  - File: gnat_ug_vms.info, Node: The GNAT STANDARD Utility Program, Next: The External Symbol Naming Scheme of GNAT, Prev: Using Other Utility Programs with GNAT, Up: Other Utility Programs - - The `GNAT STANDARD' Utility Program - =================================== - - Many of the definitions in package Standard are - implementation-dependent. However, the source of this package does not - exist as an Ada source file, so these values cannot be determined by - inspecting the source. They can be determined by examining in detail - the coding of `CSTAND.ADB' which creates the image of Standard in the - compiler, but this is awkward and requires a great deal of internal - knowledge about the system. - - The `GNAT STANDARD' utility is designed to deal with this situation. - It is an Ada program that dynamically determines the values of all the - relevant parameters in Standard, and prints them out in the form of an - Ada source listing for Standard, displaying all the values of interest. - This output is generated to `SYS$OUTPUT'. - - To determine the value of any parameter in package Standard, simply - run `GNAT STANDARD' with no qualifiers or arguments, and examine the - output. This is preferable to consulting documentation, because you - know that the values you are getting are the actual ones provided by - the executing system. - -  - File: gnat_ug_vms.info, Node: The External Symbol Naming Scheme of GNAT, Next: Ada Mode for Glide, Prev: The GNAT STANDARD Utility Program, Up: Other Utility Programs - - The External Symbol Naming Scheme of GNAT - ========================================= - - In order to interpret the output from GNAT, when using tools that are - originally intended for use with other languages, it is useful to - understand the conventions used to generate link names from the Ada - entity names. - - All link names are in all lowercase letters. With the exception of - library procedure names, the mechanism used is simply to use the full - expanded Ada name with dots replaced by double underscores. For - example, suppose we have the following package spec: - - package QRS is - MN : Integer; - end QRS; - - The variable `MN' has a full expanded Ada name of `QRS.MN', so the - corresponding link name is `qrs__mn'. Of course if a `pragma Export' - is used this may be overridden: - - package Exports is - Var1 : Integer; - pragma Export (Var1, C, External_Name => "var1_name"); - Var2 : Integer; - pragma Export (Var2, C, Link_Name => "var2_link_name"); - end Exports; - - In this case, the link name for VAR1 is whatever link name the C - compiler would assign for the C function VAR1_NAME. This typically - would be either VAR1_NAME or _VAR1_NAME, depending on operating system - conventions, but other possibilities exist. The link name for VAR2 is - VAR2_LINK_NAME, and this is not operating system dependent. - - One exception occurs for library level procedures. A potential - ambiguity arises between the required name `_main' for the C main - program, and the name we would otherwise assign to an Ada library level - procedure called `Main' (which might well not be the main program). - - To avoid this ambiguity, we attach the prefix `_ada_' to such names. - So if we have a library level procedure such as - - procedure Hello (S : String); - - the external name of this procedure will be _ADA_HELLO. - -  - File: gnat_ug_vms.info, Node: Ada Mode for Glide, Next: Converting Ada Files to html with gnathtml, Prev: The External Symbol Naming Scheme of GNAT, Up: Other Utility Programs - - Ada Mode for `Glide' - ==================== - - The Glide mode for programming in Ada (both, Ada83 and Ada95) helps the - user in understanding existing code and facilitates writing new code. It - furthermore provides some utility functions for easier integration of - standard EMACS features when programming in Ada. - - General Features: - ----------------- - - * Full Integrated Development Environment : - - * support of 'project files' for the configuration (directories, - compilation options,...) - - * compiling and stepping through error messages. - - * running and debugging your applications within Glide. - - * easy to use for beginners by pull-down menus, - - * user configurable by many user-option variables. - - Ada Mode Features That Help Understanding Code: - ----------------------------------------------- - - * functions for easy and quick stepping through Ada code, - - * getting cross reference information for identifiers (e.g. find the - defining place by a keystroke), - - * displaying an index menu of types and subprograms and move point to - the chosen one, - - * automatic color highlighting of the various entities in Ada code. - - Glide Support for Writing Ada Code: - ----------------------------------- - - * switching between spec and body files with possible autogeneration - of body files, - - * automatic formating of subprograms parameter lists. - - * automatic smart indentation according to Ada syntax, - - * automatic completion of identifiers, - - * automatic casing of identifiers, keywords, and attributes, - - * insertion of statement templates, - - * filling comment paragraphs like filling normal text, - - For more information, please refer to the online Glide documentation - available in the Glide -> Help Menu. - -  - File: gnat_ug_vms.info, Node: Converting Ada Files to html with gnathtml, Next: Installing gnathtml, Prev: Ada Mode for Glide, Up: Other Utility Programs - - Converting Ada Files to html with `gnathtml' - ============================================ - - This `Perl' script allows Ada source files to be browsed using standard - Web browsers. For installation procedure, see the section *Note - Installing gnathtml::. - - Ada reserved keywords are highlighted in a bold font and Ada - comments in a blue font. Unless your program was compiled with the GNAT - COMPILE `/XREF=SUPPRESS' qualifier to suppress the generation of - cross-referencing information, user defined variables and types will - appear in a different color; you will be able to click on any - identifier and go to its declaration. - - The command line is as follow: - $ perl gnathtml.pl [qualifiers] ada-files - - You can pass it as many Ada files as you want. `gnathtml' will - generate an html file for every ada file, and a global file called - `index.htm'. This file is an index of every identifier defined in the - files. - - The available qualifiers are the following ones : - - `-83' - Only the subset on the Ada 83 keywords will be highlighted, not - the full Ada 95 keywords set. - - `-cc COLOR' - This option allows you to change the color used for comments. The - default value is green. The color argument can be any name - accepted by html. - - `-d' - If the ada files depend on some other files (using for instance the - `with' command, the latter will also be converted to html. Only - the files in the user project will be converted to html, not the - files in the run-time library itself. - - `-D' - This command is the same as -d above, but `gnathtml' will also look - for files in the run-time library, and generate html files for - them. - - `-f' - By default, gnathtml will generate html links only for global - entities ('with'ed units, global variables and types,...). If you - specify the `-f' on the command line, then links will be generated - for local entities too. - - `-l NUMBER' - If this qualifier is provided and NUMBER is not 0, then `gnathtml' - will number the html files every NUMBER line. - - `-I DIR' - Specify a directory to search for library files (`.ALI' files) and - source files. You can provide several -I qualifiers on the command - line, and the directories will be parsed in the order of the - command line. - - `-o DIR' - Specify the output directory for html files. By default, gnathtml - will saved the generated html files in a subdirectory named - `html/'. - - `-p FILE' - If you are using EMACS and the most recent EMACS Ada mode, which - provides a full Integrated Development Environment for compiling, - checking, running and debugging applications, you may be using - `.adp' files to give the directories where EMACS can find sources - and object files. - - Using this qualifier, you can tell gnathtml to use these files. - This allows you to get an html version of your application, even - if it is spread over multiple directories. - - `-sc COLOR' - This option allows you to change the color used for symbol - definitions. The default value is red. The color argument can be - any name accepted by html. - - `-t FILE' - This qualifier provides the name of a file. This file contains a - list of file names to be converted, and the effect is exactly as - though they had appeared explicitly on the command line. This is - the recommended way to work around the command line length limit - on some systems. - -  - File: gnat_ug_vms.info, Node: Installing gnathtml, Next: LSE, Prev: Converting Ada Files to html with gnathtml, Up: Other Utility Programs - - Installing `gnathtml' - ===================== - - `Perl' needs to be installed on your machine to run this script. - `Perl' is freely available for almost every architecture and Operating - System via the Internet. - - On Unix systems, you may want to modify the first line of the - script `gnathtml', to explicitly tell the Operating system where - Perl is. The syntax of this line is : - #!full_path_name_to_perl - - Alternatively, you may run the script using the following command line: - - $ perl gnathtml.pl [qualifiers] files - -  - File: gnat_ug_vms.info, Node: LSE, Next: Profiling, Prev: Installing gnathtml, Up: Other Utility Programs - - LSE - === - - The GNAT distribution provides an Ada 95 template for the Digital - Language Sensitive Editor (LSE), a component of DECset. In order to - access it, invoke LSE with the qualifier - /ENVIRONMENT=GNU:[LIB]ADA95.ENV. - -  - File: gnat_ug_vms.info, Node: Profiling, Prev: LSE, Up: Other Utility Programs - - Profiling - ========= - - GNAT supports The Digital Performance Coverage Analyzer (PCA), a - component of DECset. To use it proceed as outlined under "HELP PCA", - except for running the collection phase with the /DEBUG qualifier. - - $ GNAT MAKE /DEBUG - $ DEFINE LIB$DEBUG PCA$COLLECTOR - $ RUN/DEBUG - -  - File: gnat_ug_vms.info, Node: Running and Debugging Ada Programs, Next: Inline Assembler, Prev: Compatibility with DEC Ada, Up: Top - - Running and Debugging Ada Programs - ********************************** - - This chapter discusses how to debug Ada programs. An incorrect Ada - program may be handled in three ways by the GNAT compiler: - - 1. The illegality may be a violation of the static semantics of Ada. - In that case GNAT diagnoses the constructs in the program that are - illegal. It is then a straightforward matter for the user to - modify those parts of the program. - - 2. The illegality may be a violation of the dynamic semantics of Ada. - In that case the program compiles and executes, but may generate - incorrect results, or may terminate abnormally with some exception. - - 3. When presented with a program that contains convoluted errors, GNAT - itself may terminate abnormally without providing full diagnostics - on the incorrect user program. - - * Menu: - - * The GNAT Debugger GDB:: - * Running GDB:: - * Introduction to GDB Commands:: - * Using Ada Expressions:: - * Calling User-Defined Subprograms:: - * Using the Next Command in a Function:: - * Ada Exceptions:: - * Ada Tasks:: - * Debugging Generic Units:: - * GNAT Abnormal Termination or Failure to Terminate:: - * Naming Conventions for GNAT Source Files:: - * Getting Internal Debugging Information:: - * Stack Traceback:: - -  - File: gnat_ug_vms.info, Node: The GNAT Debugger GDB, Next: Running GDB, Up: Running and Debugging Ada Programs - - The GNAT Debugger GDB - ===================== - - `GDB' is a general purpose, platform-independent debugger that can be - used to debug mixed-language programs compiled with `GCC', and in - particular is capable of debugging Ada programs compiled with GNAT. The - latest versions of `GDB' are Ada-aware and can handle complex Ada data - structures. - - The manual `Debugging with GDB' , located in the GNU:[DOCS] - directory, contains full details on the usage of `GDB', including a - section on its usage on programs. This manual should be consulted for - full details. The section that follows is a brief introduction to the - philosophy and use of `GDB'. - - When GNAT programs are compiled, the compiler optionally writes - debugging information into the generated object file, including - information on line numbers, and on declared types and variables. This - information is separate from the generated code. It makes the object - files considerably larger, but it does not add to the size of the - actual executable that will be loaded into memory, and has no impact on - run-time performance. The generation of debug information is triggered - by the use of the /DEBUG qualifier in the GNAT COMPILE or GNAT MAKE - command used to carry out the compilations. It is important to - emphasize that the use of these options does not change the generated - code. - - The debugging information is written in standard system formats that - are used by many tools, including debuggers and profilers. The format - of the information is typically designed to describe C types and - semantics, but GNAT implements a translation scheme which allows full - details about Ada types and variables to be encoded into these standard - C formats. Details of this encoding scheme may be found in the file - EXP_DBUG.ADS in the GNAT source distribution. However, the details of - this encoding are, in general, of no interest to a user, since `GDB' - automatically performs the necessary decoding. - - When a program is bound and linked, the debugging information is - collected from the object files, and stored in the executable image of - the program. Again, this process significantly increases the size of - the generated executable file, but it does not increase the size of the - executable program itself. Furthermore, if this program is run in the - normal manner, it runs exactly as if the debug information were not - present, and takes no more actual memory. - - However, if the program is run under control of `GDB', the debugger - is activated. The image of the program is loaded, at which point it is - ready to run. If a run command is given, then the program will run - exactly as it would have if `GDB' were not present. This is a crucial - part of the `GDB' design philosophy. `GDB' is entirely non-intrusive - until a breakpoint is encountered. If no breakpoint is ever hit, the - program will run exactly as it would if no debugger were present. When - a breakpoint is hit, `GDB' accesses the debugging information and can - respond to user commands to inspect variables, and more generally to - report on the state of execution. - -  - File: gnat_ug_vms.info, Node: Running GDB, Next: Introduction to GDB Commands, Prev: The GNAT Debugger GDB, Up: Running and Debugging Ada Programs - - Running GDB - =========== - - The debugger can be launched directly and simply from `glide' or - through its graphical interface: `gvd'. It can also be used directly in - text mode. Here is described the basic use of `GDB' in text mode. All - the commands described below can be used in the `gvd' console window - eventhough there is usually other more graphical ways to achieve the - same goals. - - The command to run `GDB' in text mode is - - $ $ GDB PROGRAM - - where `PROGRAM' is the name of the executable file. This activates the - debugger and results in a prompt for debugger commands. The simplest - command is simply `run', which causes the program to run exactly as if - the debugger were not present. The following section describes some of - the additional commands that can be given to `GDB'. - -  - File: gnat_ug_vms.info, Node: Introduction to GDB Commands, Next: Using Ada Expressions, Prev: Running GDB, Up: Running and Debugging Ada Programs - - Introduction to GDB Commands - ============================ - - `GDB' contains a large repertoire of commands. The manual `Debugging - with GDB' , located in the GNU:[DOCS] directory, includes extensive - documentation on the use of these commands, together with examples of - their use. Furthermore, the command HELP invoked from within `GDB' - activates a simple help facility which summarizes the available - commands and their options. In this section we summarize a few of the - most commonly used commands to give an idea of what `GDB' is about. You - should create a simple program with debugging information and - experiment with the use of these `GDB' commands on the program as you - read through the following section. - - `set args ARGUMENTS' - The ARGUMENTS list above is a list of arguments to be passed to - the program on a subsequent run command, just as though the - arguments had been entered on a normal invocation of the program. - The `set args' command is not needed if the program does not - require arguments. - - `run' - The `run' command causes execution of the program to start from - the beginning. If the program is already running, that is to say if - you are currently positioned at a breakpoint, then a prompt will - ask for confirmation that you want to abandon the current - execution and restart. - - `breakpoint LOCATION' - The breakpoint command sets a breakpoint, that is to say a point - at which execution will halt and `GDB' will await further - commands. LOCATION is either a line number within a file, given in - the format `file:linenumber', or it is the name of a subprogram. - If you request that a breakpoint be set on a subprogram that is - overloaded, a prompt will ask you to specify on which of those - subprograms you want to breakpoint. You can also specify that all - of them should be breakpointed. If the program is run and - execution encounters the breakpoint, then the program stops and - `GDB' signals that the breakpoint was encountered by printing the - line of code before which the program is halted. - - `breakpoint exception NAME' - A special form of the breakpoint command which breakpoints whenever - exception NAME is raised. If NAME is omitted, then a breakpoint - will occur when any exception is raised. - - `print EXPRESSION' - This will print the value of the given expression. Most simple Ada - expression formats are properly handled by `GDB', so the expression - can contain function calls, variables, operators, and attribute - references. - - `continue' - Continues execution following a breakpoint, until the next - breakpoint or the termination of the program. - - `step' - Executes a single line after a breakpoint. If the next statement - is a subprogram call, execution continues into (the first - statement of) the called subprogram. - - `next' - Executes a single line. If this line is a subprogram call, - executes and returns from the call. - - `list' - Lists a few lines around the current source location. In practice, - it is usually more convenient to have a separate edit window open - with the relevant source file displayed. Successive applications - of this command print subsequent lines. The command can be given - an argument which is a line number, in which case it displays a - few lines around the specified one. - - `backtrace' - Displays a backtrace of the call chain. This command is typically - used after a breakpoint has occurred, to examine the sequence of - calls that leads to the current breakpoint. The display includes - one line for each activation record (frame) corresponding to an - active subprogram. - - `up' - At a breakpoint, `GDB' can display the values of variables local - to the current frame. The command `up' can be used to examine the - contents of other active frames, by moving the focus up the stack, - that is to say from callee to caller, one frame at a time. - - `down' - Moves the focus of `GDB' down from the frame currently being - examined to the frame of its callee (the reverse of the previous - command), - - `frame N' - Inspect the frame with the given number. The value 0 denotes the - frame of the current breakpoint, that is to say the top of the - call stack. - - The above list is a very short introduction to the commands that - `GDB' provides. Important additional capabilities, including conditional - breakpoints, the ability to execute command sequences on a breakpoint, - the ability to debug at the machine instruction level and many other - features are described in detail in `Debugging with GDB'. Note that - most commands can be abbreviated (for example, c for continue, bt for - backtrace). - -  - File: gnat_ug_vms.info, Node: Using Ada Expressions, Next: Calling User-Defined Subprograms, Prev: Introduction to GDB Commands, Up: Running and Debugging Ada Programs - - Using Ada Expressions - ===================== - - `GDB' supports a fairly large subset of Ada expression syntax, with some - extensions. The philosophy behind the design of this subset is - - * That `GDB' should provide basic literals and access to operations - for arithmetic, dereferencing, field selection, indexing, and - subprogram calls, leaving more sophisticated computations to - subprograms written into the program (which therefore may be - called from `GDB'). - - * That type safety and strict adherence to Ada language restrictions - are not particularly important to the `GDB' user. - - * That brevity is important to the `GDB' user. - - Thus, for brevity, the debugger acts as if there were implicit - `with' and `use' clauses in effect for all user-written packages, thus - making it unnecessary to fully qualify most names with their packages, - regardless of context. Where this causes ambiguity, `GDB' asks the - user's intent. - - For details on the supported Ada syntax, see `Debugging with GDB'. - -  - File: gnat_ug_vms.info, Node: Calling User-Defined Subprograms, Next: Using the Next Command in a Function, Prev: Using Ada Expressions, Up: Running and Debugging Ada Programs - - Calling User-Defined Subprograms - ================================ - - An important capability of `GDB' is the ability to call user-defined - subprograms while debugging. This is achieved simply by entering a - subprogram call statement in the form: - - call subprogram-name (parameters) - - The keyword `call' can be omitted in the normal case where the - `subprogram-name' does not coincide with any of the predefined `GDB' - commands. - - The effect is to invoke the given subprogram, passing it the list of - parameters that is supplied. The parameters can be expressions and can - include variables from the program being debugged. The subprogram must - be defined at the library level within your program, and `GDB' will - call the subprogram within the environment of your program execution - (which means that the subprogram is free to access or even modify - variables within your program). - - The most important use of this facility is in allowing the inclusion - of debugging routines that are tailored to particular data structures - in your program. Such debugging routines can be written to provide a - suitably high-level description of an abstract type, rather than a - low-level dump of its physical layout. After all, the standard `GDB - print' command only knows the physical layout of your types, not their - abstract meaning. Debugging routines can provide information at the - desired semantic level and are thus enormously useful. - - For example, when debugging GNAT itself, it is crucial to have - access to the contents of the tree nodes used to represent the program - internally. But tree nodes are represented simply by an integer value - (which in turn is an index into a table of nodes). Using the `print' - command on a tree node would simply print this integer value, which is - not very useful. But the PN routine (defined in file TREEPR.ADB in the - GNAT sources) takes a tree node as input, and displays a useful high - level representation of the tree node, which includes the syntactic - category of the node, its position in the source, the integers that - denote descendant nodes and parent node, as well as varied semantic - information. To study this example in more detail, you might want to - look at the body of the PN procedure in the stated file. - -  - File: gnat_ug_vms.info, Node: Using the Next Command in a Function, Next: Ada Exceptions, Prev: Calling User-Defined Subprograms, Up: Running and Debugging Ada Programs - - Using the Next Command in a Function - ==================================== - - When you use the `next' command in a function, the current source - location will advance to the next statement as usual. A special case - arises in the case of a `return' statement. - - Part of the code for a return statement is the "epilog" of the - function. This is the code that returns to the caller. There is only - one copy of this epilog code, and it is typically associated with the - last return statement in the function if there is more than one return. - In some implementations, this epilog is associated with the first - statement of the function. - - The result is that if you use the `next' command from a return - statement that is not the last return statement of the function you may - see a strange apparent jump to the last return statement or to the - start of the function. You should simply ignore this odd jump. The - value returned is always that from the first return statement that was - stepped through. - -  - File: gnat_ug_vms.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Using the Next Command in a Function, Up: Running and Debugging Ada Programs - - Breaking on Ada Exceptions - ========================== - - You can set breakpoints that trip when your program raises selected - exceptions. - - `break exception' - Set a breakpoint that trips whenever (any task in the) program - raises any exception. - - `break exception NAME' - Set a breakpoint that trips whenever (any task in the) program - raises the exception NAME. - - `break exception unhandled' - Set a breakpoint that trips whenever (any task in the) program - raises an exception for which there is no handler. - - `info exceptions' - `info exceptions REGEXP' - The `info exceptions' command permits the user to examine all - defined exceptions within Ada programs. With a regular expression, - REGEXP, as argument, prints out only those exceptions whose name - matches REGEXP. - -  - File: gnat_ug_vms.info, Node: Ada Tasks, Next: Debugging Generic Units, Prev: Ada Exceptions, Up: Running and Debugging Ada Programs - - Ada Tasks - ========= - - `GDB' allows the following task-related commands: - - `info tasks' - This command shows a list of current Ada tasks, as in the - following example: - - (GDB) info tasks - ID TID P-ID Thread Pri State Name - 1 8088000 0 807e000 15 Child Activation Wait main_task - 2 80a4000 1 80ae000 15 Accept/Select Wait b - 3 809a800 1 80a4800 15 Child Activation Wait a - * 4 80ae800 3 80b8000 15 Running c - - In this listing, the asterisk before the first task indicates it - to be the currently running task. The first column lists the task - ID that is used to refer to tasks in the following commands. - - `break LINESPEC task TASKID' - `break LINESPEC task TASKID if ...' - These commands are like the `break ... thread ...'. LINESPEC - specifies source lines. - - Use the qualifier `task TASKID' with a breakpoint command to - specify that you only want `GDB' to stop the program when a - particular Ada task reaches this breakpoint. TASKID is one of the - numeric task identifiers assigned by `GDB', shown in the first - column of the `info tasks' display. - - If you do not specify `task TASKID' when you set a breakpoint, the - breakpoint applies to _all_ tasks of your program. - - You can use the `task' qualifier on conditional breakpoints as - well; in this case, place `task TASKID' before the breakpoint - condition (before the `if'). - - `task TASKNO' - This command allows to qualifier to the task referred by TASKNO. In - particular, This allows to browse the backtrace of the specified - task. It is advised to qualifier back to the original task before - continuing execution otherwise the scheduling of the program may be - perturbated. - - For more detailed information on the tasking support, see `Debugging - with GDB'. - -  - File: gnat_ug_vms.info, Node: Debugging Generic Units, Next: GNAT Abnormal Termination or Failure to Terminate, Prev: Ada Tasks, Up: Running and Debugging Ada Programs - - Debugging Generic Units - ======================= - - GNAT always uses code expansion for generic instantiation. This means - that each time an instantiation occurs, a complete copy of the original - code is made, with appropriate substitutions of formals by actuals. - - It is not possible to refer to the original generic entities in - `GDB', but it is always possible to debug a particular instance of a - generic, by using the appropriate expanded names. For example, if we - have - - procedure g is - - generic package k is - procedure kp (v1 : in out integer); - end k; - - package body k is - procedure kp (v1 : in out integer) is - begin - v1 := v1 + 1; - end kp; - end k; - - package k1 is new k; - package k2 is new k; - - var : integer := 1; - - begin - k1.kp (var); - k2.kp (var); - k1.kp (var); - k2.kp (var); - end; - - Then to break on a call to procedure kp in the k2 instance, simply use - the command: - - (GDB) break g.k2.kp - - When the breakpoint occurs, you can step through the code of the - instance in the normal manner and examine the values of local - variables, as for other units. - -  - File: gnat_ug_vms.info, Node: GNAT Abnormal Termination or Failure to Terminate, Next: Naming Conventions for GNAT Source Files, Prev: Debugging Generic Units, Up: Running and Debugging Ada Programs - - GNAT Abnormal Termination or Failure to Terminate - ================================================= - - When presented with programs that contain serious errors in syntax or - semantics, GNAT may on rare occasions experience problems in - operation, such as aborting with a segmentation fault or illegal memory - access, raising an internal exception, terminating abnormally, or - failing to terminate at all. In such cases, you can activate various - features of GNAT that can help you pinpoint the construct in your - program that is the likely source of the problem. - - The following strategies are presented in increasing order of - difficulty, corresponding to your experience in using GNAT and your - familiarity with compiler internals. - - 1. Run `GNAT COMPILE' with the `/REPORT_ERRORS=FULL'. This first - qualifier causes all errors on a given line to be reported. In its - absence, only the first error on a line is displayed. - - The `/REPORT_ERRORS=IMMEDIATE' qualifier causes errors to be - displayed as soon as they are encountered, rather than after - compilation is terminated. If GNAT terminates prematurely or goes - into an infinite loop, the last error message displayed may help - to pinpoint the culprit. - - 2. Run `GNAT COMPILE' with the `/VERBOSE' qualifier. In this mode, - `GNAT COMPILE' produces ongoing information about the progress of - the compilation and provides the name of each procedure as code is - generated. This qualifier allows you to find which Ada procedure - was being compiled when it encountered a code generation problem. - - 3. Run `GNAT COMPILE' with the `/TRACE_UNITS' qualifier. This is a - GNAT specific qualifier that does for the front-end what `VERBOSE' - does for the back end. The system prints the name of each unit, - either a compilation unit or nested unit, as it is being analyzed. - - 4. Finally, you can start `GDB' directly on the `GNAT1' executable. - `GNAT1' is the front-end of GNAT, and can be run independently - (normally it is just called from `GNAT COMPILE'). You can use - `GDB' on `GNAT1' as you would on a C program (but *note The GNAT - Debugger GDB:: for caveats). The `where' command is the first line - of attack; the variable `lineno' (seen by `print lineno'), used by - the second phase of `GNAT1' and by the `GNAT COMPILE' backend, - indicates the source line at which the execution stopped, and - `input_file name' indicates the name of the source file. - -  - File: gnat_ug_vms.info, Node: Naming Conventions for GNAT Source Files, Next: Getting Internal Debugging Information, Prev: GNAT Abnormal Termination or Failure to Terminate, Up: Running and Debugging Ada Programs - - Naming Conventions for GNAT Source Files - ======================================== - - In order to examine the workings of the GNAT system, the following - brief description of its organization may be helpful: - - * Files with prefix `SC' contain the lexical scanner. - - * All files prefixed with `PAR' are components of the parser. The - numbers correspond to chapters of the Ada 95 Reference Manual. For - example, parsing of select statements can be found in - `PAR-CH9.ADB'. - - * All files prefixed with `SEM' perform semantic analysis. The - numbers correspond to chapters of the Ada standard. For example, - all issues involving context clauses can be found in - `SEM_CH10.ADB'. In addition, some features of the language require - sufficient special processing to justify their own semantic files: - sem_aggr for aggregates, sem_disp for dynamic dispatching, etc. - - * All files prefixed with `EXP' perform normalization and expansion - of the intermediate representation (abstract syntax tree, or AST). - these files use the same numbering scheme as the parser and - semantics files. For example, the construction of record - initialization procedures is done in `EXP_CH3.ADB'. - - * The files prefixed with `BIND' implement the binder, which - verifies the consistency of the compilation, determines an order of - elaboration, and generates the bind file. - - * The files `ATREE.ADS' and `ATREE.ADB' detail the low-level data - structures used by the front-end. - - * The files `SINFO.ADS' and `SINFO.ADB' detail the structure of the - abstract syntax tree as produced by the parser. - - * The files `EINFO.ADS' and `EINFO.ADB' detail the attributes of all - entities, computed during semantic analysis. - - * Library management issues are dealt with in files with prefix - `LIB'. - - * Ada files with the prefix `A-' are children of `Ada', as defined - in Annex A. - - * Files with prefix `I-' are children of `Interfaces', as defined in - Annex B. - - * Files with prefix `S-' are children of `System'. This includes - both language-defined children and GNAT run-time routines. - - * Files with prefix `G-' are children of `GNAT'. These are useful - general-purpose packages, fully documented in their - specifications. All the other `.C' files are modifications of - common `GNAT COMPILE' files. - -  - File: gnat_ug_vms.info, Node: Getting Internal Debugging Information, Next: Stack Traceback, Prev: Naming Conventions for GNAT Source Files, Up: Running and Debugging Ada Programs - - Getting Internal Debugging Information - ====================================== - - Most compilers have internal debugging qualifiers and modes. GNAT does - also, except GNAT internal debugging qualifiers and modes are not - secret. A summary and full description of all the compiler and binder - debug flags are in the file `DEBUG.ADB'. You must obtain the sources of - the compiler to see the full detailed effects of these flags. - - The qualifiers that print the source of the program (reconstructed - from the internal tree) are of general interest for user programs, as - are the options to print the full internal tree, and the entity table - (the symbol table information). The reconstructed source provides a - readable version of the program after the front-end has completed - analysis and expansion, and is useful when studying the performance of - specific constructs. For example, constraint checks are indicated, - complex aggregates are replaced with loops and assignments, and tasking - primitives are replaced with run-time calls. - -  - File: gnat_ug_vms.info, Node: Stack Traceback, Prev: Getting Internal Debugging Information, Up: Running and Debugging Ada Programs - - Stack Traceback - =============== - - Traceback is a mechanism to display the sequence of subprogram calls - that leads to a specified execution point in a program. Often (but not - always) the execution point is an instruction at which an exception has - been raised. This mechanism is also known as stack unwinding because - it obtains its information by scanning the run-time stack and - recovering the activation records of all active subprograms. Stack - unwinding is one of the most important tools for program debugging. - - The first entry stored in traceback corresponds to the deepest calling - level, that is to say the subprogram currently executing the instruction - from which we want to obtain the traceback. - - Note that there is no runtime performance penalty when stack traceback - is enabled and no exception are raised during program execution. - - * Menu: - - * Non-Symbolic Traceback:: - * Symbolic Traceback:: - -  - File: gnat_ug_vms.info, Node: Non-Symbolic Traceback, Next: Symbolic Traceback, Up: Stack Traceback - - Non-Symbolic Traceback - ---------------------- - - Note: this feature is not supported on all platforms. See - `GNAT.Traceback spec in G-TRACEB.ADS' for a complete list of supported - platforms. - - * Menu: - - * Tracebacks From an Unhandled Exception:: - * Tracebacks From Exception Occurrences (non-symbolic):: - * Tracebacks From Anywhere in a Program (non-symbolic):: - -  - File: gnat_ug_vms.info, Node: Tracebacks From an Unhandled Exception, Next: Tracebacks From Exception Occurrences (non-symbolic), Up: Non-Symbolic Traceback - - Tracebacks From an Unhandled Exception - ...................................... - - A runtime non-symbolic traceback is a list of addresses of call - instructions. To enable this feature you must use the `-E' `GNAT - BIND''s option. With this option a stack traceback is stored as part of - exception information. It is possible to retrieve this information - using the standard `Ada.Exception.Exception_Information' routine. - - Let's have a look at a simple example: - - procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - $ GNAT MAKE stb /BINDER_QUALIFIERS -E - $ stb - - Execution terminated by unhandled exception - Exception name: CONSTRAINT_ERROR - Message: STB.ADB:5 - Call stack traceback locations: - 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - - As we see the traceback lists a sequence of addresses for the unhandled - exception `CONSTAINT_ERROR' raised in procedure P1. It is easy to guess - that this exception come from procedure P1. To translate these - addresses into the source lines where the calls appear, the `addr2line' - tool, described below, is invaluable. The use of this tool requires the - program to be compiled with debug information. - - $ GNAT MAKE -g stb /BINDER_QUALIFIERS -E - $ stb - - Execution terminated by unhandled exception - Exception name: CONSTRAINT_ERROR - Message: STB.ADB:5 - Call stack traceback locations: - 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - - $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 - 0x4011f1 0x77e892a4 - - 00401373 at d:/stb/STB.ADB:5 - 0040138B at d:/stb/STB.ADB:10 - 0040139C at d:/stb/STB.ADB:14 - 00401335 at d:/stb/B~STB.ADB:104 - 004011C4 at /build/.../CRT1.C:200 - 004011F1 at /build/.../CRT1.C:222 - 77E892A4 in ?? at ??:0 - - `addr2line' has a number of other useful options: - - `--functions' - to get the function name corresponding to any location - - `--demangle=gnat' - to use the gnat decoding mode for the function names. Note that - for binutils version 2.9.x the option is simply `--demangle'. - - $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b - 0x40139c 0x401335 0x4011c4 0x4011f1 - - 00401373 in stb.p1 at d:/stb/STB.ADB:5 - 0040138B in stb.p2 at d:/stb/STB.ADB:10 - 0040139C in stb at d:/stb/STB.ADB:14 - 00401335 in main at d:/stb/B~STB.ADB:104 - 004011C4 in <__mingw_CRTStartup> at /build/.../CRT1.C:200 - 004011F1 in at /build/.../CRT1.C:222 - - From this traceback we can see that the exception was raised in - `STB.ADB' at line 5, which was reached from a procedure call in - `STB.ADB' at line 10, and so on. The `B~STD.ADB' is the binder file, - which contains the call to the main program. *note Running GNAT - BIND::. The remaining entries are assorted runtime routines, and the - output will vary from platform to platform. - - It is also possible to use `GDB' with these traceback addresses to debug - the program. For example, we can break at a given code location, as - reported in the stack traceback: - - $ GDB -nw stb - - (GDB) break *0x401373 - Breakpoint 1 at 0x401373: file STB.ADB, line 5. - - It is important to note that the stack traceback addresses do not - change when debug information is included. This is particularly useful - because it makes it possible to release software without debug - information (to minimize object size), get a field report that includes - a stack traceback whenever an internal bug occurs, and then be able to - retrieve the sequence of calls with the same program compiled with - debug information. - -  - File: gnat_ug_vms.info, Node: Tracebacks From Exception Occurrences (non-symbolic), Next: Tracebacks From Anywhere in a Program (non-symbolic), Prev: Tracebacks From an Unhandled Exception, Up: Non-Symbolic Traceback - - Tracebacks From Exception Occurrences - ..................................... - - Non-symbolic tracebacks are obtained by using the `-E' binder argument. - The stack traceback is attached to the exception information string, - and can be retrieved in an exception handler within the Ada program, by - means of the Ada95 facilities defined in `Ada.Exceptions'. Here is a - simple example: - - with Ada.Text_IO; - with Ada.Exceptions; - - procedure STB is - - use Ada; - use Ada.Exceptions; - - procedure P1 is - K : Positive := 1; - begin - K := K - 1; - exception - when E : others => - Text_IO.Put_Line (Exception_Information (E)); - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - This program will output: - - $ stb - - Exception name: CONSTRAINT_ERROR - Message: STB.ADB:12 - Call stack traceback locations: - 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 - -  - File: gnat_ug_vms.info, Node: Tracebacks From Anywhere in a Program (non-symbolic), Prev: Tracebacks From Exception Occurrences (non-symbolic), Up: Non-Symbolic Traceback - - Tracebacks From Anywhere in a Program - ..................................... - - It is also possible to retrieve a stack traceback from anywhere in a - program. For this you need to use the `GNAT.Traceback' API. This - package includes a procedure called `Call_Chain' that computes a - complete stack traceback, as well as useful display procedures - described below. It is not necessary to use the `-E GNAT BIND' option - in this case, because the stack traceback mechanism is invoked - explicitly. - - In the following example we compute a traceback at a specific location - in the program, and we display it using `GNAT.Debug_Utilities.Image' to - convert addresses to strings: - - with Ada.Text_IO; - with GNAT.Traceback; - with GNAT.Debug_Utilities; - - procedure STB is - - use Ada; - use GNAT; - use GNAT.Traceback; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - - Text_IO.Put ("In STB.P1 : "); - - for K in 1 .. Len loop - Text_IO.Put (Debug_Utilities.Image (TB (K))); - Text_IO.Put (' '); - end loop; - - Text_IO.New_Line; - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - $ GNAT MAKE stb - $ stb - - In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# - 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# - -  - File: gnat_ug_vms.info, Node: Symbolic Traceback, Prev: Non-Symbolic Traceback, Up: Stack Traceback - - Symbolic Traceback - ------------------ - - A symbolic traceback is a stack traceback in which procedure names are - associated with each code location. - - Note that this feature is not supported on all platforms. See - `GNAT.Traceback.Symbolic spec in G-TRASYM.ADS' for a complete list of - currently supported platforms. - - Note that the symbolic traceback requires that the program be compiled - with debug information. If it is not compiled with debug information - only the non-symbolic information will be valid. - - * Menu: - - * Tracebacks From Exception Occurrences (symbolic):: - * Tracebacks From Anywhere in a Program (symbolic):: - -  - File: gnat_ug_vms.info, Node: Tracebacks From Exception Occurrences (symbolic), Next: Tracebacks From Anywhere in a Program (symbolic), Up: Symbolic Traceback - - Tracebacks From Exception Occurrences - ..................................... - - with Ada.Text_IO; - with GNAT.Traceback.Symbolic; - - procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - procedure P3 is - begin - P2; - end P3; - - begin - P3; - exception - when E : others => - Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); - end STB; - - $ GNAT MAKE -g stb /BINDER_QUALIFIERS -E /LINKER_QUALIFIERS -lgnat -laddr2line -lintl - $ stb - - 0040149F in stb.p1 at STB.ADB:8 - 004014B7 in stb.p2 at STB.ADB:13 - 004014CF in stb.p3 at STB.ADB:18 - 004015DD in ada.stb at STB.ADB:22 - 00401461 in main at B~STB.ADB:168 - 004011C4 in __mingw_CRTStartup at CRT1.C:200 - 004011F1 in mainCRTStartup at CRT1.C:222 - 77E892A4 in ?? at ??:0 - - The exact sequence of linker options may vary from platform to platform. - The above `/LINKER_QUALIFIERS' section is for Windows platforms. By - contrast, under Unix there is no need for the `/LINKER_QUALIFIERS' - section. Differences across platforms are due to details of linker - implementation. - -  - File: gnat_ug_vms.info, Node: Tracebacks From Anywhere in a Program (symbolic), Prev: Tracebacks From Exception Occurrences (symbolic), Up: Symbolic Traceback - - Tracebacks From Anywhere in a Program - ..................................... - - It is possible to get a symbolic stack traceback from anywhere in a - program, just as for non-symbolic tracebacks. The first step is to - obtain a non-symbolic traceback, and then call `Symbolic_Traceback' to - compute the symbolic information. Here is an example: - - with Ada.Text_IO; - with GNAT.Traceback; - with GNAT.Traceback.Symbolic; - - procedure STB is - - use Ada; - use GNAT.Traceback; - use GNAT.Traceback.Symbolic; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - -  - File: gnat_ug_vms.info, Node: Compatibility with DEC Ada, Next: Running and Debugging Ada Programs, Prev: Other Utility Programs, Up: Top - - Compatibility with DEC Ada - ************************** - - This section of the manual compares DEC Ada for OpenVMS Alpha and GNAT - OpenVMS Alpha. GNAT achieves a high level of compatibility with DEC - Ada, and it should generally be straightforward to port code from the - DEC Ada environment to GNAT. However, there are a few language and - implementation differences of which the user must be aware. These - differences are discussed in this section. In addition, the operating - environment and command structure for the compiler are different, and - these differences are also discussed. - - Note that this discussion addresses specifically the implementation - of Ada 83 for DIGITAL OpenVMS Alpha Systems. In cases where the - implementation of DEC Ada differs between OpenVMS Alpha Systems and - OpenVMS VAX Systems, GNAT always follows the Alpha implementation. - - * Menu: - - * Ada 95 Compatibility:: - * Differences in the Definition of Package System:: - * Language-Related Features:: - * The Package STANDARD:: - * The Package SYSTEM:: - * Tasking and Task-Related Features:: - * Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems:: - * Pragmas and Pragma-Related Features:: - * Library of Predefined Units:: - * Bindings:: - * Main Program Definition:: - * Implementation-Defined Attributes:: - * Compiler and Run-Time Interfacing:: - * Program Compilation and Library Management:: - * Input-Output:: - * Implementation Limits:: - * Tools:: - -  - File: gnat_ug_vms.info, Node: Ada 95 Compatibility, Next: Differences in the Definition of Package System, Up: Compatibility with DEC Ada - - Ada 95 Compatibility - ==================== - - GNAT is an Ada 95 compiler, and DEC Ada is an Ada 83 compiler. Ada 95 - is almost completely upwards compatible with Ada 83, and therefore Ada - 83 programs will compile and run under GNAT with no changes or only - minor changes. The Ada 95 Reference Manual (ANSI/ISO/IEC-8652:1995) - provides details on specific incompatibilities. - - GNAT provides the qualifier /83 on the GNAT COMPILE command, as well - as the pragma ADA_83, to force the compiler to operate in Ada 83 mode. - This mode does not guarantee complete conformance to Ada 83, but in - practice is sufficient to eliminate most sources of incompatibilities. - In particular, it eliminates the recognition of the additional Ada 95 - keywords, so that their use as identifiers in Ada83 program is legal, - and handles the cases of packages with optional bodies, and generics - that instantiate unconstrained types without the use of `(<>)'. - -  - File: gnat_ug_vms.info, Node: Differences in the Definition of Package System, Next: Language-Related Features, Prev: Ada 95 Compatibility, Up: Compatibility with DEC Ada - - Differences in the Definition of Package System - =============================================== - - Both the Ada 95 and Ada 83 reference manuals permit a compiler to add - implementation-dependent declarations to package System. In normal mode, - GNAT does not take advantage of this permission, and the version of - System provided by GNAT exactly matches that in the Ada 95 Reference - Manual. - - However, DEC Ada adds an extensive set of declarations to package - System, as fully documented in the DEC Ada manuals. To minimize changes - required for programs that make use of these extensions, GNAT provides - the pragma Extend_System for extending the definition of package - System. By using: - - pragma Extend_System (Aux_DEC); - - The set of definitions in System is extended to include those in package - `System.Aux_DEC'. These definitions are incorporated directly into - package System, as though they had been declared there in the first - place. For a list of the declarations added, see the specification of - this package, which can be found in the file `S-AUXDEC.ADS' in the GNAT - library. The pragma Extend_System is a configuration pragma, which - means that it can be placed in the file `GNAT.ADC', so that it will - automatically apply to all subsequent compilations. See the section on - Configuration Pragmas for further details. - - An alternative approach that avoids the use of the non-standard - Extend_System pragma is to add a context clause to the unit that - references these facilities: - - with System.Aux_DEC; - use System.Aux_DEC; - - The effect is not quite semantically identical to incorporating the - declarations directly into package `System', but most programs will not - notice a difference unless they use prefix notation (e.g. - `System.Integer_8') to reference the entities directly in package - `System'. For units containing such references, the prefixes must - either be removed, or the pragma `Extend_System' must be used. - -  - File: gnat_ug_vms.info, Node: Language-Related Features, Next: The Package STANDARD, Prev: Differences in the Definition of Package System, Up: Compatibility with DEC Ada - - Language-Related Features - ========================= - - The following sections highlight differences in types, representations - of types, operations, alignment, and related topics. - - * Menu: - - * Integer Types and Representations:: - * Floating-Point Types and Representations:: - * Pragmas Float_Representation and Long_Float:: - * Fixed-Point Types and Representations:: - * Record and Array Component Alignment:: - * Address Clauses:: - * Other Representation Clauses:: - -  - File: gnat_ug_vms.info, Node: Integer Types and Representations, Next: Floating-Point Types and Representations, Up: Language-Related Features - - Integer Types and Representations - --------------------------------- - - The set of predefined integer types is identical in DEC Ada and GNAT. - Furthermore the representation of these integer types is also identical, - including the capability of size clauses forcing biased representation. - - In addition, DEC Ada for OpenVMS Alpha systems has defined the - following additional integer types in package System: - - * INTEGER_8 - - * INTEGER_16 - - * INTEGER_32 - - * INTEGER_64 - - * LARGEST_INTEGER - - When using GNAT, the first four of these types may be obtained from the - standard Ada 95 package `Interfaces'. Alternatively, by use of the - pragma `Extend_System', identical declarations can be referenced - directly in package `System'. On both GNAT and DEC Ada, the maximum - integer size is 64 bits. - -  - File: gnat_ug_vms.info, Node: Floating-Point Types and Representations, Next: Pragmas Float_Representation and Long_Float, Prev: Integer Types and Representations, Up: Language-Related Features - - Floating-Point Types and Representations - ---------------------------------------- - - The set of predefined floating-point types is identical in DEC Ada and - GNAT. Furthermore the representation of these floating-point types is - also identical. One important difference is that the default - representation for DEC Ada is VAX_Float, but the default representation - for GNAT is IEEE. - - Specific types may be declared to be VAX_Float or IEEE, using the - pragma `Float_Representation' as described in the DEC Ada documentation. - For example, the declarations: - - type F_Float is digits 6; - pragma Float_Representation (VAX_Float, F_Float); - - declare a type F_Float that will be represented in VAX_Float format. - This set of declarations actually appears in System.Aux_DEC, which - provides the full set of additional floating-point declarations - provided in the DEC Ada version of package System. This and similar - declarations may be accessed in a user program by using pragma - `Extend_System'. The use of this pragma, and the related pragma - `Long_Float' is described in further detail in the following section. - -  - File: gnat_ug_vms.info, Node: Pragmas Float_Representation and Long_Float, Next: Fixed-Point Types and Representations, Prev: Floating-Point Types and Representations, Up: Language-Related Features - - Pragmas Float_Representation and Long_Float - ------------------------------------------- - - DEC Ada provides the pragma `Float_Representation', which acts as a - program library qualifier to allow control over the internal - representation chosen for the predefined floating-point types declared - in the package `Standard'. The format of this pragma is as follows: - - pragma `Float_Representation'(VAX_Float | IEEE_Float); - - This pragma controls the representation of floating-point types as - follows: - - * `VAX_Float' specifies that floating-point types are represented by - default with the VAX hardware types F-floating, D-floating, - G-floating. Note that the H-floating type is available only on - DIGITAL Vax systems, and is not available in either DEC Ada or - GNAT for Alpha systems. - - * `IEEE_Float' specifies that floating-point types are represented - by default with the IEEE single and double floating-point types. - - GNAT provides an identical implementation of the pragma - `Float_Representation', except that it functions as a configuration - pragma, as defined by Ada 95. Note that the notion of configuration - pragma corresponds closely to the DEC Ada notion of a program library - qualifier. - - When no pragma is used in GNAT, the default is IEEE_Float, which is - different from DEC Ada 83, where the default is VAX_Float. In addition, - the predefined libraries in GNAT are built using IEEE_Float, so it is - not advisable to change the format of numbers passed to standard library - routines, and if necessary explicit type conversions may be needed. - - The use of IEEE_Float is recommended in GNAT since it is more - efficient, and (given that it conforms to an international standard) - potentially more portable. The situation in which VAX_Float may be - useful is in interfacing to existing code and data that expects the use - of VAX_Float. There are two possibilities here. If the requirement for - the use of VAX_Float is localized, then the best approach is to use the - predefined VAX_Float types in package `System', as extended by - `Extend_System'. For example, use `System.F_Float' to specify the - 32-bit `F-Float' format. - - Alternatively, if an entire program depends heavily on the use of - the `VAX_Float' and in particular assumes that the types in package - `Standard' are in `Vax_Float' format, then it may be desirable to - reconfigure GNAT to assume Vax_Float by default. This is done by using - the GNAT LIBRARY command to rebuild the library, and then using the - general form of the `Float_Representation' pragma to ensure that this - default format is used throughout. The form of the GNAT LIBRARY - command is: - - GNAT LIBRARY /CONFIG=file /CREATE=directory - - where file contains the new configuration pragmas and directory is the - directory to be created to contain the new library. - - On OpenVMS systems, DEC Ada provides the pragma `Long_Float' to allow - control over the internal representation chosen for the predefined type - `Long_Float' and for floating-point type declarations with digits - specified in the range 7 .. 15. The format of this pragma is as - follows: - - pragma Long_Float (D_FLOAT | G_FLOAT); - -  - File: gnat_ug_vms.info, Node: Fixed-Point Types and Representations, Next: Record and Array Component Alignment, Prev: Pragmas Float_Representation and Long_Float, Up: Language-Related Features - - Fixed-Point Types and Representations - ------------------------------------- - - On DEC Ada for OpenVMS Alpha systems, rounding is away from zero for - both positive and negative numbers. Therefore, +0.5 rounds to 1 and - -0.5 rounds to -1. - - On GNAT for OpenVMS Alpha, the results of operations on fixed-point - types are in accordance with the Ada 95 rules. In particular, results - of operations on decimal fixed-point types are truncated. - -  - File: gnat_ug_vms.info, Node: Record and Array Component Alignment, Next: Address Clauses, Prev: Fixed-Point Types and Representations, Up: Language-Related Features - - Record and Array Component Alignment - ------------------------------------ - - On DEC Ada for OpenVMS Alpha, all non composite components are aligned - on natural boundaries. For example, 1-byte components are aligned on - byte boundaries, 2-byte components on 2-byte boundaries, 4-byte - components on 4-byte byte boundaries, and so on. The OpenVMS Alpha - hardware runs more efficiently with naturally aligned data. - - ON GNAT for OpenVMS Alpha, alignment rules are compatible with DEC - Ada for OpenVMS Alpha. - -  - File: gnat_ug_vms.info, Node: Address Clauses, Next: Other Representation Clauses, Prev: Record and Array Component Alignment, Up: Language-Related Features - - Address Clauses - --------------- - - In DEC Ada and GNAT, address clauses are supported for objects and - imported subprograms. The predefined type `System.Address' is a - private type in both compilers, with the same representation (it is - simply a machine pointer). Addition, subtraction, and comparison - operations are available in the standard Ada 95 package - `System.Storage_Elements', or in package `System' if it is extended to - include `System.Aux_DEC' using a pragma `Extend_System' as previously - described. - - Note that code that with's both this extended package `System' and - the package `System.Storage_Elements' should not `use' both packages, - or ambiguities will result. In general it is better not to mix these - two sets of facilities. The Ada 95 package was designed specifically to - provide the kind of features that DEC Ada adds directly to package - `System'. - - GNAT is compatible with DEC Ada in its handling of address clauses, - except for some limitations in the form of address clauses for - composite objects with initialization. Such address clauses are easily - replaced by the use of an explicitly-defined constant as described in - the Ada 95 Reference Manual (13.1(22)). For example, the sequence of - declarations: - - X, Y : Integer := Init_Func; - Q : String (X .. Y) := "abc"; - ... - for Q'Address use Compute_Address; - - will be rejected by GNAT, since the address cannot be computed at the - time that Q is declared. To achieve the intended effect, write instead: - - X, Y : Integer := Init_Func; - Q_Address : constant Address := Compute_Address; - Q : String (X .. Y) := "abc"; - ... - for Q'Address use Q_Address; - - which will be accepted by GNAT (and other Ada 95 compilers), and is also - backwards compatible with Ada 83. A fuller description of the - restrictions on address specifications is found in the GNAT Reference - Manual. - -  - File: gnat_ug_vms.info, Node: Other Representation Clauses, Prev: Address Clauses, Up: Language-Related Features - - Other Representation Clauses - ---------------------------- - - GNAT supports in a compatible manner all the representation clauses - supported by DEC Ada. In addition, it supports representation clause - forms that are new in Ada 95 including COMPONENT_SIZE and SIZE clauses - for objects. - -  - File: gnat_ug_vms.info, Node: The Package STANDARD, Next: The Package SYSTEM, Prev: Language-Related Features, Up: Compatibility with DEC Ada - - The Package STANDARD - ==================== - - The package STANDARD, as implemented by DEC Ada, is fully described in - the Reference Manual for the Ada Programming Language - (ANSI/MIL-STD-1815A-1983) and in the DEC Ada Language Reference Manual. - As implemented by GNAT, the package STANDARD is described in the Ada 95 - Reference Manual. - - In addition, DEC Ada supports the Latin-1 character set in the type - CHARACTER. GNAT supports the Latin-1 character set in the type - CHARACTER and also Unicode (ISO 10646 BMP) in the type WIDE_CHARACTER. - - The floating-point types supported by GNAT are those supported by - DEC Ada, but defaults are different, and are controlled by pragmas. See - *note Floating-Point Types and Representations:: for details. - -  - File: gnat_ug_vms.info, Node: The Package SYSTEM, Next: Tasking and Task-Related Features, Prev: The Package STANDARD, Up: Compatibility with DEC Ada - - The Package SYSTEM - ================== - - DEC Ada provides a system-specific version of the package SYSTEM for - each platform on which the language ships. For the complete - specification of the package SYSTEM, see Appendix F of the DEC Ada - Language Reference Manual. - - On DEC Ada, the package SYSTEM includes the following conversion - functions: - * TO_ADDRESS(INTEGER) - - * TO_ADDRESS(UNSIGNED_LONGWORD) - - * TO_ADDRESS(universal_integer) - - * TO_INTEGER(ADDRESS) - - * TO_UNSIGNED_LONGWORD(ADDRESS) - - * Function IMPORT_VALUE return UNSIGNED_LONGWORD and the - functions IMPORT_ADDRESS and IMPORT_LARGEST_VALUE - - By default, GNAT supplies a version of SYSTEM that matches the - definition given in the Ada 95 Reference Manual. This is a subset of - the DIGITAL system definitions, which is as close as possible to the - original definitions. The only difference is that the definition of - SYSTEM_NAME is different: - - type Name is (SYSTEM_NAME_GNAT); - System_Name : constant Name := SYSTEM_NAME_GNAT; - - Also, GNAT adds the new Ada 95 declarations for BIT_ORDER and - DEFAULT_BIT_ORDER. - - However, the use of the following pragma causes GNAT to extend the - definition of package SYSTEM so that it encompasses the full set of - DIGITAL-specific extensions, including the functions listed above: - - pragma Extend_System (Aux_DEC); - - The pragma Extend_System is a configuration pragma that is most - conveniently placed in the `GNAT.ADC' file. See the GNAT Reference - Manual for further details. - - DEC Ada does not allow the recompilation of the package SYSTEM. - Instead DEC Ada provides several pragmas (SYSTEM_ NAME, STORAGE_UNIT, - and MEMORY_SIZE) to modify values in the package SYSTEM. On OpenVMS - Alpha systems, the pragma SYSTEM_NAME takes the enumeration literal - OPENVMS_AXP as its single argument. - - GNAT does permit the recompilation of package SYSTEM using a special - qualifier (/STYLE=GNAT) and this qualifier can be used if it is - necessary to change constants in SYSTEM. GNAT does not permit the - specification of SYSTEM_NAME, STORAGE_UNIT or MEMORY_SIZE by any other - means. - - On GNAT systems, the pragma SYSTEM_NAME takes the enumeration - literal SYSTEM_NAME_GNAT. - - The definitions provided by the use of - - pragma Extend_System (AUX_Dec); - - are virtually identical to those provided by the DEC Ada 83 package - System. One important difference is that the name of the TO_ADDRESS - function for type UNSIGNED_LONGWORD is changed to TO_ADDRESS_LONG. See - the GNAT Reference manual for a discussion of why this change was - necessary. - - The version of TO_ADDRESS taking a universal integer argument is in fact - an extension to Ada 83 not strictly compatible with the reference - manual. In GNAT, we are constrained to be exactly compatible with the - standard, and this means we cannot provide this capability. In DEC Ada - 83, the point of this definition is to deal with a call like: - - TO_ADDRESS (16#12777#); - - Normally, according to the Ada 83 standard, one would expect this to be - ambiguous, since it matches both the INTEGER and UNSIGNED_LONGWORD forms - of TO_ADDRESS. However, in DEC Ada 83, there is no ambiguity, since the - definition using universal_integer takes precedence. - - In GNAT, since the version with universal_integer cannot be - supplied, it is not possible to be 100% compatible. Since there are - many programs using numeric constants for the argument to TO_ADDRESS, - the decision in GNAT was to change the name of the function in the - UNSIGNED_LONGWORD case, so the declarations provided in the GNAT - version of AUX_Dec are: - - function To_Address (X : Integer) return Address; - pragma Pure_Function (To_Address); - - function To_Address_Long (X : Unsigned_Longword) return Address; - pragma Pure_Function (To_Address_Long); - - This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must - change the name to TO_ADDRESS_LONG. - -  - File: gnat_ug_vms.info, Node: Tasking and Task-Related Features, Next: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems, Prev: The Package SYSTEM, Up: Compatibility with DEC Ada - - Tasking and Task-Related Features - ================================= - - The concepts relevant to a comparison of tasking on GNAT and on DEC Ada - for OpenVMS Alpha systems are discussed in the following sections. - - For detailed information on concepts related to tasking in DEC Ada, - see the DEC Ada Language Reference Manual and the relevant run-time - reference manual. - -  - File: gnat_ug_vms.info, Node: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems, Next: Pragmas and Pragma-Related Features, Prev: Tasking and Task-Related Features, Up: Compatibility with DEC Ada - - Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems - ============================================================ - - On OpenVMS Alpha systems, each Ada task (except a passive task) is - implemented as a single stream of execution that is created and managed - by the kernel. On these systems, DEC Ada tasking support is based on - DECthreads, an implementation of the POSIX standard for threads. - - Although tasks are implemented as threads, all tasks in an Ada - program are part of the same process. As a result, resources such as - open files and virtual memory can be shared easily among tasks. Having - all tasks in one process allows better integration with the programming - environment (the shell and the debugger, for example). - - Also, on OpenVMS Alpha systems, DEC Ada tasks and foreign code that - calls DECthreads routines can be used together. The interaction - between Ada tasks and DECthreads routines can have some benefits. For - example when on OpenVMS Alpha, DEC Ada can call C code that is already - threaded. GNAT on OpenVMS Alpha uses the facilities of DECthreads, and - Ada tasks are mapped to threads. - - * Menu: - - * Assigning Task IDs:: - * Task IDs and Delays:: - * Task-Related Pragmas:: - * Scheduling and Task Priority:: - * The Task Stack:: - * External Interrupts:: - -  - File: gnat_ug_vms.info, Node: Assigning Task IDs, Next: Task IDs and Delays, Up: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems - - Assigning Task IDs - ------------------ - - The DEC Ada Run-Time Library always assigns %TASK 1 to the environment - task that executes the main program. On OpenVMS Alpha systems, %TASK 0 - is often used for tasks that have been created but are not yet - activated. - - On OpenVMS Alpha systems, task IDs are assigned at activation. On - GNAT systems, task IDs are also assigned at task creation but do not - have the same form or values as task ID values in DEC Ada. There is no - null task, and the environment task does not have a specific task ID - value. - -  - File: gnat_ug_vms.info, Node: Task IDs and Delays, Next: Task-Related Pragmas, Prev: Assigning Task IDs, Up: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems - - Task IDs and Delays - ------------------- - - On OpenVMS Alpha systems, tasking delays are implemented using Timer - System Services. The Task ID is used for the identification of the - timer request (the REQIDT parameter). If Timers are used in the - application take care not to use 0 for the identification, because - cancelling such a timer will cancel all timers and may lead to - unpredictable results. - -  - File: gnat_ug_vms.info, Node: Task-Related Pragmas, Next: Scheduling and Task Priority, Prev: Task IDs and Delays, Up: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems - - Task-Related Pragmas - -------------------- - - Ada supplies the pragma TASK_STORAGE, which allows specification of the - size of the guard area for a task stack. (The guard area forms an area - of memory that has no read or write access and thus helps in the - detection of stack overflow.) On OpenVMS Alpha systems, if the pragma - TASK_STORAGE specifies a value of zero, a minimal guard area is - created. In the absence of a pragma TASK_STORAGE, a default guard area - is created. - - GNAT supplies the following task-related pragmas: - - * TASK_INFO - - This pragma appears within a task definition and - applies to the task in which it appears. The argument - must be of type SYSTEM.TASK_INFO.TASK_INFO_TYPE. - - * TASK_STORAGE - - GNAT implements pragma TASK_STORAGE in the same way as - DEC Ada. Both DEC Ada and GNAT supply the pragmas - PASSIVE, SUPPRESS, and VOLATILE. - -  - File: gnat_ug_vms.info, Node: Scheduling and Task Priority, Next: The Task Stack, Prev: Task-Related Pragmas, Up: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems - - Scheduling and Task Priority - ---------------------------- - - DEC Ada implements the Ada language requirement that when two tasks are - eligible for execution and they have different priorities, the lower - priority task does not execute while the higher priority task is - waiting. The DEC Ada Run-Time Library keeps a task running until either - the task is suspended or a higher priority task becomes ready. - - On OpenVMS Alpha systems, the default strategy is round- robin with - preemption. Tasks of equal priority take turns at the processor. A task - is run for a certain period of time and then placed at the rear of the - ready queue for its priority level. - - DEC Ada provides the implementation-defined pragma TIME_SLICE, which - can be used to enable or disable round-robin scheduling of tasks with - the same priority. See the relevant DEC Ada run-time reference manual - for information on using the pragmas to control DEC Ada task scheduling. - - GNAT follows the scheduling rules of Annex D (real-time Annex) of - the Ada 95 Reference Manual. In general, this scheduling strategy is - fully compatible with DEC Ada although it provides some additional - constraints (as fully documented in Annex D). GNAT implements time - slicing control in a manner compatible with DEC Ada 83, by means of the - pragma Time_Slice, whose semantics are identical to the DEC Ada 83 - pragma of the same name. Note that it is not possible to mix GNAT - tasking and DEC Ada 83 tasking in the same program, since the two run - times are not compatible. - -  - File: gnat_ug_vms.info, Node: The Task Stack, Next: External Interrupts, Prev: Scheduling and Task Priority, Up: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems - - The Task Stack - -------------- - - In DEC Ada, a task stack is allocated each time a non passive task is - activated. As soon as the task is terminated, the storage for the task - stack is deallocated. If you specify a size of zero (bytes) with - T'STORAGE_SIZE, a default stack size is used. Also, regardless of the - size specified, some additional space is allocated for task management - purposes. On OpenVMS Alpha systems, at least one page is allocated. - - GNAT handles task stacks in a similar manner. According to the Ada - 95 rules, it provides the pragma STORAGE_SIZE as an alternative method - for controlling the task stack size. The specification of the - attribute T'STORAGE_SIZE is also supported in a manner compatible with - DEC Ada. - -  - File: gnat_ug_vms.info, Node: External Interrupts, Prev: The Task Stack, Up: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems - - External Interrupts - ------------------- - - On DEC Ada, external interrupts can be associated with task entries. - GNAT is compatible with DEC Ada in its handling of external interrupts. - -  - File: gnat_ug_vms.info, Node: Pragmas and Pragma-Related Features, Next: Library of Predefined Units, Prev: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems, Up: Compatibility with DEC Ada - - Pragmas and Pragma-Related Features - =================================== - - Both DEC Ada and GNAT supply all language-defined pragmas as specified - by the Ada 83 standard. GNAT also supplies all language-defined pragmas - specified in the Ada 95 Reference Manual. In addition, GNAT implements - the implementation-defined pragmas from DEC Ada 83. - - * AST_ENTRY - - * COMMON_OBJECT - - * COMPONENT_ALIGNMENT - - * EXPORT_EXCEPTION - - * EXPORT_FUNCTION - - * EXPORT_OBJECT - - * EXPORT_PROCEDURE - - * EXPORT_VALUED_PROCEDURE - - * FLOAT_REPRESENTATION - - * IDENT - - * IMPORT_EXCEPTION - - * IMPORT_FUNCTION - - * IMPORT_OBJECT - - * IMPORT_PROCEDURE - - * IMPORT_VALUED_PROCEDURE - - * INLINE_GENERIC - - * INTERFACE_NAME - - * LONG_FLOAT - - * MAIN_STORAGE - - * PASSIVE - - * PSET_OBJECT - - * SHARE_GENERIC - - * SUPPRESS_ALL - - * TASK_STORAGE - - * TIME_SLICE - - * TITLE - - These pragmas are all fully implemented, with the exception of `Title', - `Passive', and `Share_Generic', which are recognized, but which have no - effect in GNAT. The effect of `Passive' may be obtained by the use of - protected objects in Ada 95. In GNAT, all generics are inlined. - - Unlike DEC Ada, the GNAT 'EXPORT_subprogram' pragmas require a - separate subprogram specification which must appear before the - subprogram body. - - GNAT also supplies a number of implementation-defined pragmas as - follows: - * C_PASS_BY_COPY - - * EXTEND_SYSTEM - - * SOURCE_FILE_NAME - - * UNSUPPRESS - - * WARNINGS - - * ABORT_DEFER - - * ADA_83 - - * ADA_95 - - * ANNOTATE - - * ASSERT - - * CPP_CLASS - - * CPP_CONSTRUCTOR - - * CPP_DESTRUCTOR - - * CPP_VIRTUAL - - * CP_VTABLE - - * DEBUG - - * LINKER_ALIAS - - * LINKER_SECTION - - * MACHINE_ATTRIBUTE - - * NO_RETURN - - * PURE_FUNCTION - - * SOURCE_REFERENCE - - * TASK_INFO - - * UNCHECKED_UNION - - * UNIMPLEMENTED_UNIT - - * WEAK_EXTERNAL - - For full details on these GNAT implementation-defined pragmas, see the - GNAT Reference Manual. - - * Menu: - - * Restrictions on the Pragma INLINE:: - * Restrictions on the Pragma INTERFACE:: - * Restrictions on the Pragma SYSTEM_NAME:: - -  - File: gnat_ug_vms.info, Node: Restrictions on the Pragma INLINE, Next: Restrictions on the Pragma INTERFACE, Up: Pragmas and Pragma-Related Features - - Restrictions on the Pragma INLINE - --------------------------------- - - DEC Ada applies the following restrictions to the pragma INLINE: - * Parameters cannot be a task type. - - * Function results cannot be task types, unconstrained array types, - or unconstrained types with discriminants. - - * Bodies cannot declare the following: - * Subprogram body or stub (imported subprogram is allowed) - - * Tasks - - * Generic declarations - - * Instantiations - - * Exceptions - - * Access types (types derived from access types allowed) - - * Array or record types - - * Dependent tasks - - * Direct recursive calls of subprogram or containing - subprogram, directly or via a renaming - - - In GNAT, the only restriction on pragma INLINE is that the body must - occur before the call if both are in the same unit, and the size must - be appropriately small. There are no other specific restrictions which - cause subprograms to be incapable of being inlined. - -  - File: gnat_ug_vms.info, Node: Restrictions on the Pragma INTERFACE, Next: Restrictions on the Pragma SYSTEM_NAME, Prev: Restrictions on the Pragma INLINE, Up: Pragmas and Pragma-Related Features - - Restrictions on the Pragma INTERFACE - ------------------------------------ - - The following lists and describes the restrictions on the pragma - INTERFACE on DEC Ada and GNAT: - * Languages accepted: Ada, Bliss, C, Fortran, Default. Default is - the default on OpenVMS Alpha systems. - - * Parameter passing: Language specifies default mechanisms but can - be overridden with an EXPORT pragma. - - * Ada: Use internal Ada rules. - - * Bliss, C: Parameters must be mode `in'; cannot be record or - task type. Result cannot be a string, an array, or a record. - - * Fortran: Parameters cannot be a task. Result cannot be a - string, an array, or a record. - - GNAT is entirely upwards compatible with DEC Ada, and in addition allows - record parameters for all languages. - -  - File: gnat_ug_vms.info, Node: Restrictions on the Pragma SYSTEM_NAME, Prev: Restrictions on the Pragma INTERFACE, Up: Pragmas and Pragma-Related Features - - Restrictions on the Pragma SYSTEM_NAME - -------------------------------------- - - For DEC Ada for OpenVMS Alpha, the enumeration literal for the type - NAME is OPENVMS_AXP. In GNAT, the enumeration literal for the type NAME - is SYSTEM_NAME_GNAT. - -  - File: gnat_ug_vms.info, Node: Library of Predefined Units, Next: Bindings, Prev: Pragmas and Pragma-Related Features, Up: Compatibility with DEC Ada - - Library of Predefined Units - =========================== - - A library of predefined units is provided as part of the DEC Ada and - GNAT implementations. DEC Ada does not provide the package MACHINE_CODE - but instead recommends importing assembler code. - - The GNAT versions of the DEC Ada Run-Time Library (ADA$PREDEFINED:) - units are taken from the OpenVMS Alpha version, not the OpenVMS VAX - version. During GNAT installation, the DEC Ada Predefined Library units - are copied into the GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] (aka DECLIB) - directory and patched to remove Ada 95 incompatibilities and to make - them interoperable with GNAT, *note Changes to DECLIB:: for details. - - The GNAT RTL is contained in the GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB] - (aka ADALIB) directory and the default search path is set up to find - DECLIB units in preference to ADALIB units with the same name (TEXT_IO, - SEQUENTIAL_IO, and DIRECT_IO, for example). - - However, it is possible to change the default so that the reverse is - true, or even to mix them using child package notation. The DEC Ada 83 - units are available as DEC.xxx where xxx is the package name, and the - Ada units are available in the standard manner defined for Ada 95, that - is to say as Ada.xxx. To change the default, set ADA_INCLUDE_PATH and - ADA_OBJECTS_PATH appropriately. For example, to change the default to - use the Ada95 versions do: - - $ DEFINE ADA_INCLUDE_PATH GNU:[LIB.OPENVMS7_1.2_8_1.ADAINCLUDE],- - GNU:[LIB.OPENVMS7_1.2_8_1.DECLIB] - $ DEFINE ADA_OBJECTS_PATH GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB],- - GNU:[LIB.OPENVMS7_1.2_8_1.DECLIB] - - * Menu: - - * Changes to DECLIB:: - -  - File: gnat_ug_vms.info, Node: Changes to DECLIB, Up: Library of Predefined Units - - Changes to DECLIB - ----------------- - - The changes made to the DEC Ada predefined library for GNAT and Ada 95 - compatibility are minor and include the following: - - * Adjusting the location of pragmas and record representation - clauses to obey Ada 95 rules - - * Adding the proper notation to generic formal parameters that take - unconstrained types in instantiation - - * Adding pragma ELABORATE_BODY to package specifications that have - package bodies not otherwise allowed - - * Occurrences of the identifier "PROTECTED" are renamed to - "PROTECTD". Currently these are found only in the STARLET package - spec. - - None of the above changes is visible to users. - -  - File: gnat_ug_vms.info, Node: Bindings, Next: Main Program Definition, Prev: Library of Predefined Units, Up: Compatibility with DEC Ada - - Bindings - ======== - - On OpenVMS Alpha, DEC Ada provides the following strongly-typed - bindings: - * Command Language Interpreter (CLI interface) - - * DECtalk Run-Time Library (DTK interface) - - * Librarian utility routines (LBR interface) - - * General Purpose Run-Time Library (LIB interface) - - * Math Run-Time Library (MTH interface) - - * National Character Set Run-Time Library (NCS interface) - - * Compiled Code Support Run-Time Library (OTS interface) - - * Parallel Processing Run-Time Library (PPL interface) - - * Screen Management Run-Time Library (SMG interface) - - * Sort Run-Time Library (SOR interface) - - * String Run-Time Library (STR interface) - - * STARLET System Library - - * X Window System Version 11R4 and 11R5 (X, XLIB interface) - - * X Windows Toolkit (XT interface) - - * X/Motif Version 1.1.3 and 1.2 (XM interface) - - GNAT provides implementations of these DEC bindings in the DECLIB - directory. - - The X/Motif bindings used to build DECLIB are whatever versions are - in the DEC Ada ADA$PREDEFINED directory with extension .ADC. The build - script will automatically add a pragma Linker_Options to packages Xm, - Xt, and X_Lib causing the default X/Motif shareable image libraries to - be linked in. This is done via options files named xm.opt, xt.opt, and - x_lib.opt (also located in the DECLIB directory). - - It may be necessary to edit these options files to update or correct - the library names if, for example, the newer X/Motif bindings from - ADA$EXAMPLES had been (previous to installing GNAT) copied and renamed - to superseded the default ADA$PREDEFINED versions. - - * Menu: - - * Shared Libraries and Options Files:: - * Interfaces to C:: - -  - File: gnat_ug_vms.info, Node: Shared Libraries and Options Files, Next: Interfaces to C, Up: Bindings - - Shared Libraries and Options Files - ---------------------------------- - - When using the DEC Ada predefined X and Motif bindings, the linking - with their shareable images is done automatically by GNAT LINK. When - using other X and Motif bindings, it is necessary to add the - corresponding shareable images to the command line for GNAT LINK. When - linking with shared libraries, or with .OPT files, it is also necessary - to add them to the command line for GNAT LINK. - - A shared library to be used with GNAT is built in the same way as - other libraries under VMS. The VMS Link command can be used in standard - fashion. - -  - File: gnat_ug_vms.info, Node: Interfaces to C, Prev: Shared Libraries and Options Files, Up: Bindings - - Interfaces to C - --------------- - - DEC Ada provides the following Ada types and operations: - - * C types package (C_TYPES) - - * C strings (C_TYPES.NULL_TERMINATED) - - * Other_types (SHORT_INT) - - Interfacing to C with GNAT, one can use the above approach described - for DEC Ada or the facilities of Annex B of the Ada 95 Reference Manual - (packages INTERFACES.C, INTERFACES.C.STRINGS and - INTERFACES.C.POINTERS). For more information, see the section - "Interfacing to C" in the GNAT Reference Manual. - - The `/UPPERCASE_EXTERNALS' qualifier forces default and explicit - `External_Name' parameters in pragmas Import and Export to be - uppercased for compatibility with the default behavior of DEC C. The - qualifier has no effect on `Link_Name' parameters. - -  - File: gnat_ug_vms.info, Node: Main Program Definition, Next: Implementation-Defined Attributes, Prev: Bindings, Up: Compatibility with DEC Ada - - Main Program Definition - ======================= - - The following section discusses differences in the definition of main - programs on DEC Ada and GNAT. On DEC Ada, main programs are defined to - meet the following conditions: - * Procedure with no formal parameters (returns 0 upon normal - completion) - - * Procedure with no formal parameters (returns 42 when - unhandled exceptions are raised) - - * Function with no formal parameters whose returned value is - of a discrete type - - * Procedure with one OUT formal of a discrete type for which - a specification of pragma EXPORT_VALUED_PROCEDURE is given. - - - When declared with the pragma EXPORT_VALUED_PROCEDURE, a main function - or main procedure returns a discrete value whose size is less than 64 - bits (32 on VAX systems), the value is zero- or sign-extended as - appropriate. On GNAT, main programs are defined as follows: - * Must be a non-generic, parameter-less subprogram that is either a - procedure or function returning an Ada STANDARD.INTEGER (the - predefined type) - - * Cannot be a generic subprogram or an instantiation of a generic - subprogram - -  - File: gnat_ug_vms.info, Node: Implementation-Defined Attributes, Next: Compiler and Run-Time Interfacing, Prev: Main Program Definition, Up: Compatibility with DEC Ada - - Implementation-Defined Attributes - ================================= - - GNAT provides all DEC Ada implementation-defined attributes. - -  - File: gnat_ug_vms.info, Node: Compiler and Run-Time Interfacing, Next: Program Compilation and Library Management, Prev: Implementation-Defined Attributes, Up: Compatibility with DEC Ada - - Compiler and Run-Time Interfacing - ================================= - - DEC Ada provides the following ways to pass options to the linker (ACS - LINK): - * /WAIT and /SUBMIT qualifiers - - * /COMMAND qualifier - - * /[NO]MAP qualifier - - * /OUTPUT=file-spec - - * /[NO]DEBUG and /[NO]TRACEBACK qualifiers - - To pass options to the linker, GNAT provides the following qualifiers: - - * /EXECUTABLE=exec-name - - * /VERBOSE qualifier - - * /[NO]DEBUG and /[NO]TRACEBACK qualifiers - - For more information on these qualifiers, see the section "Qualifiers - for GNAT LINK" in the corresponding section of this Guide. In DEC Ada, - the command-line qualifier /OPTIMIZE is available to control - optimization. DEC Ada also supplies the following pragmas: - * OPTIMIZE - - * INLINE - - * INLINE_GENERIC - - * SUPPRESS_ALL - - * PASSIVE - - In GNAT, optimization is controlled strictly by command line - parameters, as described in the corresponding section of this guide. - The DIGITAL pragmas for control of optimization are recognized but - ignored. - - Note that in GNAT, the default is optimization off, whereas in DEC - Ada 83, the default is that optimization is turned on. - -  - File: gnat_ug_vms.info, Node: Program Compilation and Library Management, Next: Input-Output, Prev: Compiler and Run-Time Interfacing, Up: Compatibility with DEC Ada - - Program Compilation and Library Management - ========================================== - - DEC Ada and GNAT provide a comparable set of commands to build - programs. DEC Ada also provides a program library, which is a concept - that does not exist on GNAT. Instead, GNAT provides directories of - sources that are compiled as needed. - - The following table summarizes the DEC Ada commands and provides - equivalent GNAT commands. In this table, some GNAT equivalents reflect - the fact that GNAT does not use the concept of a program library. - Instead, it uses a model in which collections of source and object - files are used in a manner consistent with other languages like C and - Fortran. Therefore, standard system file commands are used to - manipulate these elements. Those GNAT commands are marked with an - asterisk in the table that follows. Note that, unlike DEC Ada, none - of the GNAT commands accepts wild cards. - - *DEC_Ada_Command* *GNAT_Equivalent* *Description* - ADA GNAT COMPILE Invokes the compiler to - compile one or more Ada - source files. - ACS ATTACH No equivalent Qualifiers control of - terminal from current - process running the program - library - manager. - ACS CHECK GNAT MAKE Forms the execution closure - /DEPENDENCY_LIST of one or more - compiled units and checks - completeness and currency. - ACS COMPILE GNAT MAKE Forms the execution closure - /ACTIONS=COMPILE of one or more - specified units, checks - completeness and currency, - identifies units - that have revised source - files, compiles same, - and recompiles units - that are or will become - obsolete. Also - completes incomplete - generic instantiations. - ACS COPY FOREIGN Copy (*) Copies a foreign object - file into the program - library as a - library unit body. - ACS COPY UNIT Copy (*) Copies a compiled unit from - one program library to - another. - ACS CREATE LIBRARY Create /directory (*) Creates a program library. - ACS CREATE SUBLIBRARY Create /directory (*) Creates a program - sublibrary. - ACS DELETE LIBRARY Deletes a program library - and its contents. - ACS DELETE SUBLIBRARY Deletes a program - sublibrary and its contents. - ACS DELETE UNIT Delete file (*) On OpenVMS systems, deletes - one or more compiled units - from the current - program library. - ACS DIRECTORY Directory (*) On OpenVMS systems, lists - units contained in the - current program - library. - ACS ENTER FOREIGN Copy (*) Allows the import of a - foreign body as an Ada - library - specification and enters a - reference to a pointer. - ACS ENTER UNIT Copy (*) Enters a reference - (pointer) from the current - program library to - a unit compiled into - another program library. - ACS EXIT No equivalent Exits from the program - library manager. - ACS EXPORT Copy (*) Creates an object file that - contains system-specific - object code for - one or more units. With - GNAT, object files can - simply be copied - into the desired directory. - ACS EXTRACT SOURCE Copy (*) Allows access to the copied - source file for each Ada - compilation unit - ACS HELP HELP GNAT Provides online help. - ACS LINK GNAT LINK Links an object file - containing Ada units into - an executable - file. - ACS LOAD Copy (*) Loads (partially compiles) - Ada units into the program - library. Allows - loading a program from a - collection of files into a - library without - knowing the relationship - among units. - ACS MERGE Copy (*) Merges into the current - program library, one or - more units from - another library where they - were modified. - ACS RECOMPILE GNAT MAKE Recompiles from external - /ACTIONS=COMPILE or copied source files any - obsolete unit in - the closure. Also, - completes any incomplete - generic - instantiations. - ACS REENTER GNAT MAKE Reenters current references - to units compiled after - last entered - with the ACS ENTER UNIT - command. - ACS SET LIBRARY Set default (*) Defines a program library - to be the compilation - context as well - as the target library for - compiler output and - commands in general. - ACS SET PRAGMA Edit GNAT.ADC (*) Redefines specified values - of the library - characteristics - LONG_ FLOAT, MEMORY_SIZE, - SYSTEM_NAME, and - `Float_Representation'. - ACS SET SOURCE define Defines the source file - ADA_INCLUDE_PATH path search list for the ACS - (*) COMPILE command. - ACS SHOW LIBRARY Directory (*) Lists information about one - or more program libraries. - ACS SHOW PROGRAM No equivalent Lists information about the - execution closure of one or - more units in - the program library. - ACS SHOW SOURCE Show logical Shows the source file - ADA_INCLUDE_PATH search used when compiling - units. - ACS SHOW VERSION Compile with VERBOSE Displays the version number - option of the compiler and program - library manager - used. - ACS SPAWN No equivalent Creates a subprocess of the - current process (same as - DCL SPAWN - command). - ACS VERIFY No equivalent Performs a series of - consistency checks on a - program library to - determine whether the - library structure and - library files are in - valid_form. - -  - File: gnat_ug_vms.info, Node: Input-Output, Next: Implementation Limits, Prev: Program Compilation and Library Management, Up: Compatibility with DEC Ada - - Input-Output - ============ - - On OpenVMS Alpha systems, DEC Ada uses OpenVMS Record Management - Services (RMS) to perform operations on external files. - - DEC Ada and GNAT predefine an identical set of input- output packages. - To make the use of the generic TEXT_IO operations more convenient, DEC - Ada provides predefined library packages that instantiate the integer - and floating-point operations for the predefined integer and - floating-point types as shown in the following table. - - `Package_Name' - Instantiation - - `INTEGER_TEXT_IO' - INTEGER_IO(INTEGER) - - `SHORT_INTEGER_TEXT_IO' - INTEGER_IO(SHORT_INTEGER) - - `SHORT_SHORT_INTEGER_TEXT_IO' - INTEGER_IO(SHORT_SHORT_ INTEGER) - - `FLOAT_TEXT_IO' - FLOAT_IO(FLOAT) - - `LONG_FLOAT_TEXT_IO' - FLOAT_IO(LONG_FLOAT) - - The DEC Ada predefined packages and their operations are implemented - using OpenVMS Alpha files and input- output facilities. DEC Ada - supports asynchronous input- output on OpenVMS Alpha. Familiarity with - the following is recommended: - * RMS file organizations and access methods - - * OpenVMS file specifications and directories - - * OpenVMS File Definition Language (FDL) - - GNAT provides I/O facilities that are completely compatible with DEC - Ada. The distribution includes the standard DEC Ada versions of all I/O - packages, operating in a manner compatible with DEC Ada. In particular, - the following packages are by default the DEC Ada (Ada 83) versions of - these packages rather than the renamings suggested in annex J of the - Ada 95 Reference Manual: - * TEXT_IO - - * SEQUENTIAL_IO - - * DIRECT_IO - - The use of the standard Ada 95 syntax for child packages (for example, - ADA.TEXT_IO) retrieves the Ada 95 versions of these packages, as - defined in the Ada 95 Reference Manual. GNAT provides - DIGITAL-compatible predefined instantiations of the TEXT_IO packages, - and also provides the standard predefined instantiations required by - the Ada 95 Reference Manual. - - For further information on how GNAT interfaces to the file system or - how I/O is implemented in programs written in mixed languages, see the - chapter "Implementation of the Standard I/O" in the GNAT Reference - Manual. This chapter covers the following: - * Standard I/O packages - - * FORM strings - - * DIRECT_IO - - * SEQUENTIAL_IO - - * TEXT_IO - - * Stream pointer positioning - - * Reading and writing non-regular files - - * GET_IMMEDIATE - - * Treating TEXT_IO files as streams - - * Shared files - - * Open modes - -  - File: gnat_ug_vms.info, Node: Implementation Limits, Next: Tools, Prev: Input-Output, Up: Compatibility with DEC Ada - - Implementation Limits - ===================== - - The following table lists implementation limits for DEC Ada and GNAT - systems. - Compilation Parameter DEC Ada GNAT - In a subprogram or entry declaration, 32 No set limit - maximum number of formal parameters - that are of an unconstrained record type - Maximum identifier length (number of 255 255 - characters) - Maximum number of characters in a source 255 255 - line - Maximum collection size (number of bytes) 2**31-1 2**31-1 - Maximum number of discriminants for a 245 No set limit - record type - Maximum number of formal parameters in an 246 No set limit - entry or subprogram declaration - Maximum number of dimensions in an array 255 No set limit - type - Maximum number of library units and 4095 No set limit - subunits in a compilation. - Maximum number of library units and 16383 No set limit - subunits in an execution. - Maximum number of objects declared with 32757 No set limit - the pragma COMMON_OBJECT or - PSECT_OBJECT - Maximum number of enumeration literals in 65535 No set limit - an enumeration type definition - Maximum number of lines in a source file 65534 No set limit - Maximum number of bits in any object 2**31-1 2**31-1 - Maximum size of the static portion of a 2**31-1 2**31-1 - stack frame (approximate) - -  - File: gnat_ug_vms.info, Node: Tools, Prev: Implementation Limits, Up: Compatibility with DEC Ada - - Tools - ===== - -  - File: gnat_ug_vms.info, Node: Inline Assembler, Next: Performance Considerations, Prev: Running and Debugging Ada Programs, Up: Top - - Inline Assembler - **************** - - If you need to write low-level software that interacts directly with - the hardware, Ada provides two ways to incorporate assembly language - code into your program. First, you can import and invoke external - routines written in assembly language, an Ada feature fully supported - by GNAT. However, for small sections of code it may be simpler or more - efficient to include assembly language statements directly in your Ada - source program, using the facilities of the implementation-defined - package `System.Machine_Code', which incorporates the GNAT COMPILE - Inline Assembler. The Inline Assembler approach offers a number of - advantages, including the following: - - * No need to use non-Ada tools - - * Consistent interface over different targets - - * Automatic usage of the proper calling conventions - - * Access to Ada constants and variables - - * Definition of intrinsic routines - - * Possibility of inlining a subprogram comprising assembler code - - * Code optimizer can take Inline Assembler code into account - - This chapter presents a series of examples to show you how to use - the Inline Assembler. Although it focuses on the Intel x86, the - general approach applies also to other processors. It is assumed that - you are familiar with Ada and with assembly language programming. - - * Menu: - - * Basic Assembler Syntax:: - * A Simple Example of Inline Assembler:: - * Output Variables in Inline Assembler:: - * Input Variables in Inline Assembler:: - * Inlining Inline Assembler Code:: - * Other Asm Functionality:: - * A Complete Example:: - -  - File: gnat_ug_vms.info, Node: Basic Assembler Syntax, Next: A Simple Example of Inline Assembler, Up: Inline Assembler - - Basic Assembler Syntax - ====================== - - The assembler used by GNAT and GNAT COMPILE is based not on the Intel - assembly language, but rather on a language that descends from the AT&T - Unix assembler _as_ (and which is often referred to as "AT&T syntax"). - The following table summarizes the main features of _as_ syntax and - points out the differences from the Intel conventions. See the GNAT - COMPILE _as_ and _gas_ (an _as_ macro pre-processor) documentation for - further information. - - Register names - GNAT COMPILE / _as_: Prefix with "%"; for example `%eax' - Intel: No extra punctuation; for example `eax' - - Immediate operand - GNAT COMPILE / _as_: Prefix with "$"; for example `$4' - Intel: No extra punctuation; for example `4' - - Address - GNAT COMPILE / _as_: Prefix with "$"; for example `$loc' - Intel: No extra punctuation; for example `loc' - - Memory contents - GNAT COMPILE / _as_: No extra punctuation; for example `loc' - Intel: Square brackets; for example `[loc]' - - Register contents - GNAT COMPILE / _as_: Parentheses; for example `(%eax)' - Intel: Square brackets; for example `[eax]' - - Hexadecimal numbers - GNAT COMPILE / _as_: Leading "0x" (C language syntax); for example - `0xA0' - Intel: Trailing "h"; for example `A0h' - - Operand size - GNAT COMPILE / _as_: Explicit in op code; for example `movw' to - move a 16-bit word - Intel: Implicit, deduced by assembler; for example `mov' - - Instruction repetition - GNAT COMPILE / _as_: Split into two lines; for example - `rep' - `stosl' - Intel: Keep on one line; for example `rep stosl' - - Order of operands - GNAT COMPILE / _as_: Source first; for example `movw $4, %eax' - Intel: Destination first; for example `mov eax, 4' - -  - File: gnat_ug_vms.info, Node: A Simple Example of Inline Assembler, Next: Output Variables in Inline Assembler, Prev: Basic Assembler Syntax, Up: Inline Assembler - - A Simple Example of Inline Assembler - ==================================== - - The following example will generate a single assembly language - statement, `nop', which does nothing. Despite its lack of run-time - effect, the example will be useful in illustrating the basics of the - Inline Assembler facility. - - with System.Machine_Code; use System.Machine_Code; - procedure Nothing is - begin - Asm ("nop"); - end Nothing; - - `Asm' is a procedure declared in package `System.Machine_Code'; here - it takes one parameter, a _template string_ that must be a static - expression and that will form the generated instruction. `Asm' may be - regarded as a compile-time procedure that parses the template string - and additional parameters (none here), from which it generates a - sequence of assembly language instructions. - - The examples in this chapter will illustrate several of the forms - for invoking `Asm'; a complete specification of the syntax is found in - the `GNAT Reference Manual'. - - Under the standard GNAT conventions, the `Nothing' procedure should - be in a file named `NOTHING.ADB'. You can build the executable in the - usual way: - GNAT MAKE nothing - However, the interesting aspect of this example is not its run-time - behavior but rather the generated assembly code. To see this output, - invoke the compiler as follows: - GNAT COMPILE -S -fomit-frame-pointer /CHECKS=SUPPRESS_ALL `NOTHING.ADB' - where the options are: - - `-c' - compile only (no bind or link) - - `-S' - generate assembler listing - - `-fomit-frame-pointer' - do not set up separate stack frames - - `/CHECKS=SUPPRESS_ALL' - do not add runtime checks - - This gives a human-readable assembler version of the code. The - resulting file will have the same name as the Ada source file, but with - a `.s' extension. In our example, the file `nothing.s' has the - following contents: - - .file "NOTHING.ADB" - gcc2_compiled.: - ___gnu_compiled_ada: - .text - .align 4 - .globl __ada_nothing - __ada_nothing: - #APP - nop - #NO_APP - jmp L1 - .align 2,0x90 - L1: - ret - - The assembly code you included is clearly indicated by the compiler, - between the `#APP' and `#NO_APP' delimiters. The character before the - 'APP' and 'NOAPP' can differ on different targets. For example, Linux - uses '#APP' while on NT you will see '/APP'. - - If you make a mistake in your assembler code (such as using the - wrong size modifier, or using a wrong operand for the instruction) GNAT - will report this error in a temporary file, which will be deleted when - the compilation is finished. Generating an assembler file will help in - such cases, since you can assemble this file separately using the _as_ - assembler that comes with GNAT COMPILE. - - Assembling the file using the command - - as `nothing.s' - - will give you error messages whose lines correspond to the assembler - input file, so you can easily find and correct any mistakes you made. - If there are no errors, _as_ will generate an object file `nothing.out'. - -  - File: gnat_ug_vms.info, Node: Output Variables in Inline Assembler, Next: Input Variables in Inline Assembler, Prev: A Simple Example of Inline Assembler, Up: Inline Assembler - - Output Variables in Inline Assembler - ==================================== - - The examples in this section, showing how to access the processor - flags, illustrate how to specify the destination operands for assembly - language statements. - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags; - - In order to have a nicely aligned assembly listing, we have separated - multiple assembler statements in the Asm template string with linefeed - (ASCII.LF) and horizontal tab (ASCII.HT) characters. The resulting - section of the assembly output file is: - - #APP - pushfl - popl %eax - movl %eax, -40(%ebp) - #NO_APP - - It would have been legal to write the Asm invocation as: - - Asm ("pushfl popl %%eax movl %%eax, %0") - - but in the generated assembler file, this would come out as: - - #APP - pushfl popl %eax movl %eax, -40(%ebp) - #NO_APP - - which is not so convenient for the human reader. - - We use Ada comments at the end of each line to explain what the - assembler instructions actually do. This is a useful convention. - - When writing Inline Assembler instructions, you need to precede each - register and variable name with a percent sign. Since the assembler - already requires a percent sign at the beginning of a register name, - you need two consecutive percent signs for such names in the Asm - template string, thus `%%eax'. In the generated assembly code, one of - the percent signs will be stripped off. - - Names such as `%0', `%1', `%2', etc., denote input or output - variables: operands you later define using `Input' or `Output' - parameters to `Asm'. An output variable is illustrated in the third - statement in the Asm template string: - movl %%eax, %0 - The intent is to store the contents of the eax register in a - variable that can be accessed in Ada. Simply writing `movl %%eax, - Flags' would not necessarily work, since the compiler might optimize by - using a register to hold Flags, and the expansion of the `movl' - instruction would not be aware of this optimization. The solution is - not to store the result directly but rather to advise the compiler to - choose the correct operand form; that is the purpose of the `%0' output - variable. - - Information about the output variable is supplied in the `Outputs' - parameter to `Asm': - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - - The output is defined by the `Asm_Output' attribute of the target - type; the general format is - Type'Asm_Output (constraint_string, variable_name) - - The constraint string directs the compiler how to store/access the - associated variable. In the example - Unsigned_32'Asm_Output ("=m", Flags); - the `"m"' (memory) constraint tells the compiler that the variable - `Flags' should be stored in a memory variable, thus preventing the - optimizer from keeping it in a register. In contrast, - Unsigned_32'Asm_Output ("=r", Flags); - uses the `"r"' (register) constraint, telling the compiler to store - the variable in a register. - - If the constraint is preceded by the equal character (*=*), it tells - the compiler that the variable will be used to store data into it. - - In the `Get_Flags' example, we used the "g" (global) constraint, - allowing the optimizer to choose whatever it deems best. - - There are a fairly large number of constraints, but the ones that - are most useful (for the Intel x86 processor) are the following: - - `=' - output constraint - - `g' - global (i.e. can be stored anywhere) - - `m' - in memory - - `I' - a constant - - `a' - use eax - - `b' - use ebx - - `c' - use ecx - - `d' - use edx - - `S' - use esi - - `D' - use edi - - `r' - use one of eax, ebx, ecx or edx - - `q' - use one of eax, ebx, ecx, edx, esi or edi - - The full set of constraints is described in the GNAT COMPILE and - _as_ documentation; note that it is possible to combine certain - constraints in one constraint string. - - You specify the association of an output variable with an assembler - operand through the `%'_n_ notation, where _n_ is a non-negative - integer. Thus in - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - - `%0' will be replaced in the expanded code by the appropriate operand, - whatever the compiler decided for the `Flags' variable. - - In general, you may have any number of output variables: - * Count the operands starting at 0; thus `%0', `%1', etc. - - * Specify the `Outputs' parameter as a parenthesized comma-separated - list of `Asm_Output' attributes - - For example: - Asm ("movl %%eax, %0" & LF & HT & - "movl %%ebx, %1" & LF & HT & - "movl %%ecx, %2", - Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A - Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B - Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C - - where `Var_A', `Var_B', and `Var_C' are variables in the Ada program. - - As a variation on the `Get_Flags' example, we can use the - constraints string to direct the compiler to store the eax register - into the `Flags' variable, instead of including the store instruction - explicitly in the `Asm' template string: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags_2 is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax", -- save flags in eax - Outputs => Unsigned_32'Asm_Output ("=a", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags_2; - - The `"a"' constraint tells the compiler that the `Flags' variable will - come from the eax register. Here is the resulting code: - - #APP - pushfl - popl %eax - #NO_APP - movl %eax,-40(%ebp) - - The compiler generated the store of eax into Flags after expanding the - assembler code. - - Actually, there was no need to pop the flags into the eax register; - more simply, we could just pop the flags directly into the program - variable: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags_3 is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "pop %0", -- save flags in Flags - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags_3; - -  - File: gnat_ug_vms.info, Node: Input Variables in Inline Assembler, Next: Inlining Inline Assembler Code, Prev: Output Variables in Inline Assembler, Up: Inline Assembler - - Input Variables in Inline Assembler - =================================== - - The example in this section illustrates how to specify the source - operands for assembly language statements. The program simply - increments its input value by 1: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Increment is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Inputs => Unsigned_32'Asm_Input ("a", Value), - Outputs => Unsigned_32'Asm_Output ("=a", Result)); - return Result; - end Incr; - - Value : Unsigned_32; - - begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Incr (Value); - Put_Line ("Value after is" & Value'Img); - end Increment; - - The `Outputs' parameter to `Asm' specifies that the result will be - in the eax register and that it is to be stored in the `Result' - variable. - - The `Inputs' parameter looks much like the `Outputs' parameter, but - with an `Asm_Input' attribute. The `"="' constraint, indicating an - output value, is not present. - - You can have multiple input variables, in the same way that you can - have more than one output variable. - - The parameter count (%0, %1) etc, now starts at the first input - statement, and continues with the output statements. When both - parameters use the same variable, the compiler will treat them as the - same %n operand, which is the case here. - - Just as the `Outputs' parameter causes the register to be stored - into the target variable after execution of the assembler statements, - so does the `Inputs' parameter cause its variable to be loaded into the - register before execution of the assembler statements. - - Thus the effect of the `Asm' invocation is: - 1. load the 32-bit value of `Value' into eax - - 2. execute the `incl %eax' instruction - - 3. store the contents of eax into the `Result' variable - - The resulting assembler file (with `/OPTIMIZE=ALL' optimization) - contains: - _increment__incr.1: - subl $4,%esp - movl 8(%esp),%eax - #APP - incl %eax - #NO_APP - movl %eax,%edx - movl %ecx,(%esp) - addl $4,%esp - ret - -  - File: gnat_ug_vms.info, Node: Inlining Inline Assembler Code, Next: Other Asm Functionality, Prev: Input Variables in Inline Assembler, Up: Inline Assembler - - Inlining Inline Assembler Code - ============================== - - For a short subprogram such as the `Incr' function in the previous - section, the overhead of the call and return (creating / deleting the - stack frame) can be significant, compared to the amount of code in the - subprogram body. A solution is to apply Ada's `Inline' pragma to the - subprogram, which directs the compiler to expand invocations of the - subprogram at the point(s) of call, instead of setting up a stack frame - for out-of-line calls. Here is the resulting program: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Increment_2 is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Inputs => Unsigned_32'Asm_Input ("a", Value), - Outputs => Unsigned_32'Asm_Output ("=a", Result)); - return Result; - end Incr; - pragma Inline (Increment); - - Value : Unsigned_32; - - begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Increment (Value); - Put_Line ("Value after is" & Value'Img); - end Increment_2; - - Compile the program with both optimization (`/OPTIMIZE=ALL') and - inlining enabled (`-gnatpn' instead of `/CHECKS=SUPPRESS_ALL'). - - The `Incr' function is still compiled as usual, but at the point in - `Increment' where our function used to be called: - - pushl %edi - call _increment__incr.1 - - the code for the function body directly appears: - - movl %esi,%eax - #APP - incl %eax - #NO_APP - movl %eax,%edx - - thus saving the overhead of stack frame setup and an out-of-line call. - -  - File: gnat_ug_vms.info, Node: Other Asm Functionality, Next: A Complete Example, Prev: Inlining Inline Assembler Code, Up: Inline Assembler - - Other `Asm' Functionality - ========================= - - This section describes two important parameters to the `Asm' procedure: - `Clobber', which identifies register usage; and `Volatile', which - inhibits unwanted optimizations. - - * Menu: - - * The Clobber Parameter:: - * The Volatile Parameter:: - -  - File: gnat_ug_vms.info, Node: The Clobber Parameter, Next: The Volatile Parameter, Up: Other Asm Functionality - - The `Clobber' Parameter - ----------------------- - - One of the dangers of intermixing assembly language and a compiled - language such as Ada is that the compiler needs to be aware of which - registers are being used by the assembly code. In some cases, such as - the earlier examples, the constraint string is sufficient to indicate - register usage (e.g. "a" for the eax register). But more generally, the - compiler needs an explicit identification of the registers that are - used by the Inline Assembly statements. - - Using a register that the compiler doesn't know about could be a - side effect of an instruction (like `mull' storing its result in both - eax and edx). It can also arise from explicit register usage in your - assembly code; for example: - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out)); - - where the compiler (since it does not analyze the `Asm' template string) - does not know you are using the ebx register. - - In such cases you need to supply the `Clobber' parameter to `Asm', - to identify the registers that will be used by your assembly code: - - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Clobber => "ebx"); - - The Clobber parameter is a static string expression specifying the - register(s) you are using. Note that register names are _not_ prefixed - by a percent sign. Also, if more than one register is used then their - names are separated by commas; e.g., `"eax, ebx"' - - The `Clobber' parameter has several additional uses: - 1. Use the "register" name `cc' to indicate that flags might have - changed - - 2. Use the "register" name `memory' if you changed a memory location - -  - File: gnat_ug_vms.info, Node: The Volatile Parameter, Prev: The Clobber Parameter, Up: Other Asm Functionality - - The `Volatile' Parameter - ------------------------ - - Compiler optimizations in the presence of Inline Assembler may - sometimes have unwanted effects. For example, when an `Asm' invocation - with an input variable is inside a loop, the compiler might move the - loading of the input variable outside the loop, regarding it as a - one-time initialization. - - If this effect is not desired, you can disable such optimizations by - setting the `Volatile' parameter to `True'; for example: - - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Clobber => "ebx", - Volatile => True); - - By default, `Volatile' is set to `False' unless there is no `Outputs' - parameter. - - Although setting `Volatile' to `True' prevents unwanted - optimizations, it will also disable other optimizations that might be - important for efficiency. In general, you should set `Volatile' to - `True' only if the compiler's optimizations have created problems. - -  - File: gnat_ug_vms.info, Node: A Complete Example, Prev: Other Asm Functionality, Up: Inline Assembler - - A Complete Example - ================== - - This section contains a complete program illustrating a realistic usage - of GNAT's Inline Assembler capabilities. It comprises a main procedure - `Check_CPU' and a package `Intel_CPU'. The package declares a - collection of functions that detect the properties of the 32-bit x86 - processor that is running the program. The main procedure invokes - these functions and displays the information. - - The Intel_CPU package could be enhanced by adding functions to - detect the type of x386 co-processor, the processor caching options and - special operations such as the SIMD extensions. - - Although the Intel_CPU package has been written for 32-bit Intel - compatible CPUs, it is OS neutral. It has been tested on DOS, - Windows/NT and Linux. - - * Menu: - - * Check_CPU Procedure:: - * Intel_CPU Package Specification:: - * Intel_CPU Package Body:: - -  - File: gnat_ug_vms.info, Node: Check_CPU Procedure, Next: Intel_CPU Package Specification, Up: A Complete Example - - `Check_CPU' Procedure - --------------------- - - --------------------------------------------------------------------- - -- -- - -- Uses the Intel_CPU package to identify the CPU the program is -- - -- running on, and some of the features it supports. -- - -- -- - --------------------------------------------------------------------- - - with Intel_CPU; -- Intel CPU detection functions - with Ada.Text_IO; -- Standard text I/O - with Ada.Command_Line; -- To set the exit status - - procedure Check_CPU is - - Type_Found : Boolean := False; - -- Flag to indicate that processor was identified - - Features : Intel_CPU.Processor_Features; - -- The processor features - - Signature : Intel_CPU.Processor_Signature; - -- The processor type signature - - begin - - ----------------------------------- - -- Display the program banner. -- - ----------------------------------- - - Ada.Text_IO.Put_Line (Ada.Command_Line.Command_Name & - ": check Intel CPU version and features, v1.0"); - Ada.Text_IO.Put_Line ("distribute freely, but no warranty whatsoever"); - Ada.Text_IO.New_Line; - - ----------------------------------------------------------------------- - -- We can safely start with the assumption that we are on at least -- - -- a x386 processor. If the CPUID instruction is present, then we -- - -- have a later processor type. -- - ----------------------------------------------------------------------- - - if Intel_CPU.Has_CPUID = False then - - -- No CPUID instruction, so we assume this is indeed a x386 - -- processor. We can still check if it has a FP co-processor. - if Intel_CPU.Has_FPU then - Ada.Text_IO.Put_Line - ("x386-type processor with a FP co-processor"); - else - Ada.Text_IO.Put_Line - ("x386-type processor without a FP co-processor"); - end if; -- check for FPU - - -- Program done - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - return; - - end if; -- check for CPUID - - ----------------------------------------------------------------------- - -- If CPUID is supported, check if this is a true Intel processor, -- - -- if it is not, display a warning. -- - ----------------------------------------------------------------------- - - if Intel_CPU.Vendor_ID /= Intel_CPU.Intel_Processor then - Ada.Text_IO.Put_Line ("*** This is a Intel compatible processor"); - Ada.Text_IO.Put_Line ("*** Some information may be incorrect"); - end if; -- check if Intel - - ---------------------------------------------------------------------- - -- With the CPUID instruction present, we can assume at least a -- - -- x486 processor. If the CPUID support level is < 1 then we have -- - -- to leave it at that. -- - ---------------------------------------------------------------------- - - if Intel_CPU.CPUID_Level < 1 then - - -- Ok, this is a x486 processor. we still can get the Vendor ID - Ada.Text_IO.Put_Line ("x486-type processor"); - Ada.Text_IO.Put_Line ("Vendor ID is " & Intel_CPU.Vendor_ID); - - -- We can also check if there is a FPU present - if Intel_CPU.Has_FPU then - Ada.Text_IO.Put_Line ("Floating-Point support"); - else - Ada.Text_IO.Put_Line ("No Floating-Point support"); - end if; -- check for FPU - - -- Program done - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - return; - - end if; -- check CPUID level - - --------------------------------------------------------------------- - -- With a CPUID level of 1 we can use the processor signature to -- - -- determine it's exact type. -- - --------------------------------------------------------------------- - - Signature := Intel_CPU.Signature; - - ---------------------------------------------------------------------- - -- Ok, now we go into a lot of messy comparisons to get the -- - -- processor type. For clarity, no attememt to try to optimize the -- - -- comparisons has been made. Note that since Intel_CPU does not -- - -- support getting cache info, we cannot distinguish between P5 -- - -- and Celeron types yet. -- - ---------------------------------------------------------------------- - - -- x486SL - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486SL processor"); - end if; - - -- x486DX2 Write-Back - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#0111# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Write-Back Enhanced x486DX2 processor"); - end if; - - -- x486DX4 - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#1000# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486DX4 processor"); - end if; - - -- x486DX4 Overdrive - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0100# and - Signature.Model = 2#1000# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486DX4 OverDrive processor"); - end if; - - -- Pentium (60, 66) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium processor (60, 66)"); - end if; - - -- Pentium (75, 90, 100, 120, 133, 150, 166, 200) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0010# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium processor (75, 90, 100, 120, 133, 150, 166, 200)"); - end if; - - -- Pentium OverDrive (60, 66) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium OverDrive processor (60, 66)"); - end if; - - -- Pentium OverDrive (75, 90, 100, 120, 133, 150, 166, 200) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0010# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive cpu (75, 90, 100, 120, 133, 150, 166, 200)"); - end if; - - -- Pentium OverDrive processor for x486 processor-based systems - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive processor for x486 processor-based systems"); - end if; - - -- Pentium processor with MMX technology (166, 200) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium processor with MMX technology (166, 200)"); - end if; - - -- Pentium OverDrive with MMX for Pentium (75, 90, 100, 120, 133) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive processor with MMX " & - "technology for Pentium processor (75, 90, 100, 120, 133)"); - end if; - - -- Pentium Pro processor - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium Pro processor"); - end if; - - -- Pentium II processor, model 3 - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium II processor, model 3"); - end if; - - -- Pentium II processor, model 5 or Celeron processor - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0101# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium II processor, model 5 or Celeron processor"); - end if; - - -- Pentium Pro OverDrive processor - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0110# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium Pro OverDrive processor"); - end if; - - -- If no type recognized, we have an unknown. Display what - -- we _do_ know - if Type_Found = False then - Ada.Text_IO.Put_Line ("Unknown processor"); - end if; - - ----------------------------------------- - -- Display processor stepping level. -- - ----------------------------------------- - - Ada.Text_IO.Put_Line ("Stepping level:" & Signature.Stepping'Img); - - --------------------------------- - -- Display vendor ID string. -- - --------------------------------- - - Ada.Text_IO.Put_Line ("Vendor ID: " & Intel_CPU.Vendor_ID); - - ------------------------------------ - -- Get the processors features. -- - ------------------------------------ - - Features := Intel_CPU.Features; - - ----------------------------- - -- Check for a FPU unit. -- - ----------------------------- - - if Features.FPU = True then - Ada.Text_IO.Put_Line ("Floating-Point unit available"); - else - Ada.Text_IO.Put_Line ("no Floating-Point unit"); - end if; -- check for FPU - - -------------------------------- - -- List processor features. -- - -------------------------------- - - Ada.Text_IO.Put_Line ("Supported features: "); - - -- Virtual Mode Extension - if Features.VME = True then - Ada.Text_IO.Put_Line (" VME - Virtual Mode Extension"); - end if; - - -- Debugging Extension - if Features.DE = True then - Ada.Text_IO.Put_Line (" DE - Debugging Extension"); - end if; - - -- Page Size Extension - if Features.PSE = True then - Ada.Text_IO.Put_Line (" PSE - Page Size Extension"); - end if; - - -- Time Stamp Counter - if Features.TSC = True then - Ada.Text_IO.Put_Line (" TSC - Time Stamp Counter"); - end if; - - -- Model Specific Registers - if Features.MSR = True then - Ada.Text_IO.Put_Line (" MSR - Model Specific Registers"); - end if; - - -- Physical Address Extension - if Features.PAE = True then - Ada.Text_IO.Put_Line (" PAE - Physical Address Extension"); - end if; - - -- Machine Check Extension - if Features.MCE = True then - Ada.Text_IO.Put_Line (" MCE - Machine Check Extension"); - end if; - - -- CMPXCHG8 instruction supported - if Features.CX8 = True then - Ada.Text_IO.Put_Line (" CX8 - CMPXCHG8 instruction"); - end if; - - -- on-chip APIC hardware support - if Features.APIC = True then - Ada.Text_IO.Put_Line (" APIC - on-chip APIC hardware support"); - end if; - - -- Fast System Call - if Features.SEP = True then - Ada.Text_IO.Put_Line (" SEP - Fast System Call"); - end if; - - -- Memory Type Range Registers - if Features.MTRR = True then - Ada.Text_IO.Put_Line (" MTTR - Memory Type Range Registers"); - end if; - - -- Page Global Enable - if Features.PGE = True then - Ada.Text_IO.Put_Line (" PGE - Page Global Enable"); - end if; - - -- Machine Check Architecture - if Features.MCA = True then - Ada.Text_IO.Put_Line (" MCA - Machine Check Architecture"); - end if; - - -- Conditional Move Instruction Supported - if Features.CMOV = True then - Ada.Text_IO.Put_Line - (" CMOV - Conditional Move Instruction Supported"); - end if; - - -- Page Attribute Table - if Features.PAT = True then - Ada.Text_IO.Put_Line (" PAT - Page Attribute Table"); - end if; - - -- 36-bit Page Size Extension - if Features.PSE_36 = True then - Ada.Text_IO.Put_Line (" PSE_36 - 36-bit Page Size Extension"); - end if; - - -- MMX technology supported - if Features.MMX = True then - Ada.Text_IO.Put_Line (" MMX - MMX technology supported"); - end if; - - -- Fast FP Save and Restore - if Features.FXSR = True then - Ada.Text_IO.Put_Line (" FXSR - Fast FP Save and Restore"); - end if; - - --------------------- - -- Program done. -- - --------------------- - - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - - exception - - when others => - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Failure); - raise; - - end Check_CPU; - -  - File: gnat_ug_vms.info, Node: Intel_CPU Package Specification, Next: Intel_CPU Package Body, Prev: Check_CPU Procedure, Up: A Complete Example - - `Intel_CPU' Package Specification - --------------------------------- - - ------------------------------------------------------------------------- - -- -- - -- file: INTEL_CPU.ADS -- - -- -- - -- ********************************************* -- - -- * WARNING: for 32-bit Intel processors only * -- - -- ********************************************* -- - -- -- - -- This package contains a number of subprograms that are useful in -- - -- determining the Intel x86 CPU (and the features it supports) on -- - -- which the program is running. -- - -- -- - -- The package is based upon the information given in the Intel -- - -- Application Note AP-485: "Intel Processor Identification and the -- - -- CPUID Instruction" as of April 1998. This application note can be -- - -- found on www.intel.com. -- - -- -- - -- It currently deals with 32-bit processors only, will not detect -- - -- features added after april 1998, and does not guarantee proper -- - -- results on Intel-compatible processors. -- - -- -- - -- Cache info and x386 fpu type detection are not supported. -- - -- -- - -- This package does not use any privileged instructions, so should -- - -- work on any OS running on a 32-bit Intel processor. -- - -- -- - ------------------------------------------------------------------------- - - with Interfaces; use Interfaces; - -- for using unsigned types - - with System.Machine_Code; use System.Machine_Code; - -- for using inline assembler code - - with Ada.Characters.Latin_1; use Ada.Characters.Latin_1; - -- for inserting control characters - - package Intel_CPU is - - ---------------------- - -- Processor bits -- - ---------------------- - - subtype Num_Bits is Natural range 0 .. 31; - -- the number of processor bits (32) - - -------------------------- - -- Processor register -- - -------------------------- - - -- define a processor register type for easy access to - -- the individual bits - - type Processor_Register is array (Num_Bits) of Boolean; - pragma Pack (Processor_Register); - for Processor_Register'Size use 32; - - ------------------------- - -- Unsigned register -- - ------------------------- - - -- define a processor register type for easy access to - -- the individual bytes - - type Unsigned_Register is - record - L1 : Unsigned_8; - H1 : Unsigned_8; - L2 : Unsigned_8; - H2 : Unsigned_8; - end record; - - for Unsigned_Register use - record - L1 at 0 range 0 .. 7; - H1 at 0 range 8 .. 15; - L2 at 0 range 16 .. 23; - H2 at 0 range 24 .. 31; - end record; - - for Unsigned_Register'Size use 32; - - --------------------------------- - -- Intel processor vendor ID -- - --------------------------------- - - Intel_Processor : constant String (1 .. 12) := "GenuineIntel"; - -- indicates an Intel manufactured processor - - ------------------------------------ - -- Processor signature register -- - ------------------------------------ - - -- a register type to hold the processor signature - - type Processor_Signature is - record - Stepping : Natural range 0 .. 15; - Model : Natural range 0 .. 15; - Family : Natural range 0 .. 15; - Processor_Type : Natural range 0 .. 3; - Reserved : Natural range 0 .. 262143; - end record; - - for Processor_Signature use - record - Stepping at 0 range 0 .. 3; - Model at 0 range 4 .. 7; - Family at 0 range 8 .. 11; - Processor_Type at 0 range 12 .. 13; - Reserved at 0 range 14 .. 31; - end record; - - for Processor_Signature'Size use 32; - - ----------------------------------- - -- Processor features register -- - ----------------------------------- - - -- a processor register to hold the processor feature flags - - type Processor_Features is - record - FPU : Boolean; -- floating point unit on chip - VME : Boolean; -- virtual mode extension - DE : Boolean; -- debugging extension - PSE : Boolean; -- page size extension - TSC : Boolean; -- time stamp counter - MSR : Boolean; -- model specific registers - PAE : Boolean; -- physical address extension - MCE : Boolean; -- machine check extension - CX8 : Boolean; -- cmpxchg8 instruction - APIC : Boolean; -- on-chip apic hardware - Res_1 : Boolean; -- reserved for extensions - SEP : Boolean; -- fast system call - MTRR : Boolean; -- memory type range registers - PGE : Boolean; -- page global enable - MCA : Boolean; -- machine check architecture - CMOV : Boolean; -- conditional move supported - PAT : Boolean; -- page attribute table - PSE_36 : Boolean; -- 36-bit page size extension - Res_2 : Natural range 0 .. 31; -- reserved for extensions - MMX : Boolean; -- MMX technology supported - FXSR : Boolean; -- fast FP save and restore - Res_3 : Natural range 0 .. 127; -- reserved for extensions - end record; - - for Processor_Features use - record - FPU at 0 range 0 .. 0; - VME at 0 range 1 .. 1; - DE at 0 range 2 .. 2; - PSE at 0 range 3 .. 3; - TSC at 0 range 4 .. 4; - MSR at 0 range 5 .. 5; - PAE at 0 range 6 .. 6; - MCE at 0 range 7 .. 7; - CX8 at 0 range 8 .. 8; - APIC at 0 range 9 .. 9; - Res_1 at 0 range 10 .. 10; - SEP at 0 range 11 .. 11; - MTRR at 0 range 12 .. 12; - PGE at 0 range 13 .. 13; - MCA at 0 range 14 .. 14; - CMOV at 0 range 15 .. 15; - PAT at 0 range 16 .. 16; - PSE_36 at 0 range 17 .. 17; - Res_2 at 0 range 18 .. 22; - MMX at 0 range 23 .. 23; - FXSR at 0 range 24 .. 24; - Res_3 at 0 range 25 .. 31; - end record; - - for Processor_Features'Size use 32; - - ------------------- - -- Subprograms -- - ------------------- - - function Has_FPU return Boolean; - -- return True if a FPU is found - -- use only if CPUID is not supported - - function Has_CPUID return Boolean; - -- return True if the processor supports the CPUID instruction - - function CPUID_Level return Natural; - -- return the CPUID support level (0, 1 or 2) - -- can only be called if the CPUID instruction is supported - - function Vendor_ID return String; - -- return the processor vendor identification string - -- can only be called if the CPUID instruction is supported - - function Signature return Processor_Signature; - -- return the processor signature - -- can only be called if the CPUID instruction is supported - - function Features return Processor_Features; - -- return the processors features - -- can only be called if the CPUID instruction is supported - - private - - ------------------------ - -- EFLAGS bit names -- - ------------------------ - - ID_Flag : constant Num_Bits := 21; - -- ID flag bit - - end Intel_CPU; - -  - File: gnat_ug_vms.info, Node: Intel_CPU Package Body, Prev: Intel_CPU Package Specification, Up: A Complete Example - - `Intel_CPU' Package Body - ------------------------ - - package body Intel_CPU is - - --------------------------- - -- Detect FPU presence -- - --------------------------- - - -- There is a FPU present if we can set values to the FPU Status - -- and Control Words. - - function Has_FPU return Boolean is - - Register : Unsigned_16; - -- processor register to store a word - - begin - - -- check if we can change the status word - Asm ( - - -- the assembler code - "finit" & LF & HT & -- reset status word - "movw $0x5A5A, %%ax" & LF & HT & -- set value status word - "fnstsw %0" & LF & HT & -- save status word - "movw %%ax, %0", -- store status word - - -- output stored in Register - -- register must be a memory location - Outputs => Unsigned_16'Asm_output ("=m", Register), - - -- tell compiler that we used eax - Clobber => "eax"); - - -- if the status word is zero, there is no FPU - if Register = 0 then - return False; -- no status word - end if; -- check status word value - - -- check if we can get the control word - Asm ( - - -- the assembler code - "fnstcw %0", -- save the control word - - -- output into Register - -- register must be a memory location - Outputs => Unsigned_16'Asm_output ("=m", Register)); - - -- check the relevant bits - if (Register and 16#103F#) /= 16#003F# then - return False; -- no control word - end if; -- check control word value - - -- FPU found - return True; - - end Has_FPU; - - -------------------------------- - -- Detect CPUID instruction -- - -------------------------------- - - -- The processor supports the CPUID instruction if it is possible - -- to change the value of ID flag bit in the EFLAGS register. - - function Has_CPUID return Boolean is - - Original_Flags, Modified_Flags : Processor_Register; - -- EFLAG contents before and after changing the ID flag - - begin - - -- try flipping the ID flag in the EFLAGS register - Asm ( - - -- the assembler code - "pushfl" & LF & HT & -- push EFLAGS on stack - "pop %%eax" & LF & HT & -- pop EFLAGS into eax - "movl %%eax, %0" & LF & HT & -- save EFLAGS content - "xor $0x200000, %%eax" & LF & HT & -- flip ID flag - "push %%eax" & LF & HT & -- push EFLAGS on stack - "popfl" & LF & HT & -- load EFLAGS register - "pushfl" & LF & HT & -- push EFLAGS on stack - "pop %1", -- save EFLAGS content - - -- output values, may be anything - -- Original_Flags is %0 - -- Modified_Flags is %1 - Outputs => - (Processor_Register'Asm_output ("=g", Original_Flags), - Processor_Register'Asm_output ("=g", Modified_Flags)), - - -- tell compiler eax is destroyed - Clobber => "eax"); - - -- check if CPUID is supported - if Original_Flags(ID_Flag) /= Modified_Flags(ID_Flag) then - return True; -- ID flag was modified - else - return False; -- ID flag unchanged - end if; -- check for CPUID - - end Has_CPUID; - - ------------------------------- - -- Get CPUID support level -- - ------------------------------- - - function CPUID_Level return Natural is - - Level : Unsigned_32; - -- returned support level - - begin - - -- execute CPUID, storing the results in the Level register - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- zero is stored in eax - -- returning the support level in eax - Inputs => Unsigned_32'Asm_input ("a", 0), - - -- eax is stored in Level - Outputs => Unsigned_32'Asm_output ("=a", Level), - - -- tell compiler ebx, ecx and edx registers are destroyed - Clobber => "ebx, ecx, edx"); - - -- return the support level - return Natural (Level); - - end CPUID_Level; - - -------------------------------- - -- Get CPU Vendor ID String -- - -------------------------------- - - -- The vendor ID string is returned in the ebx, ecx and edx register - -- after executing the CPUID instruction with eax set to zero. - -- In case of a true Intel processor the string returned is - -- "GenuineIntel" - - function Vendor_ID return String is - - Ebx, Ecx, Edx : Unsigned_Register; - -- registers containing the vendor ID string - - Vendor_ID : String (1 .. 12); - -- the vendor ID string - - begin - - -- execute CPUID, storing the results in the processor registers - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- zero stored in eax - -- vendor ID string returned in ebx, ecx and edx - Inputs => Unsigned_32'Asm_input ("a", 0), - - -- ebx is stored in Ebx - -- ecx is stored in Ecx - -- edx is stored in Edx - Outputs => (Unsigned_Register'Asm_output ("=b", Ebx), - Unsigned_Register'Asm_output ("=c", Ecx), - Unsigned_Register'Asm_output ("=d", Edx))); - - -- now build the vendor ID string - Vendor_ID( 1) := Character'Val (Ebx.L1); - Vendor_ID( 2) := Character'Val (Ebx.H1); - Vendor_ID( 3) := Character'Val (Ebx.L2); - Vendor_ID( 4) := Character'Val (Ebx.H2); - Vendor_ID( 5) := Character'Val (Edx.L1); - Vendor_ID( 6) := Character'Val (Edx.H1); - Vendor_ID( 7) := Character'Val (Edx.L2); - Vendor_ID( 8) := Character'Val (Edx.H2); - Vendor_ID( 9) := Character'Val (Ecx.L1); - Vendor_ID(10) := Character'Val (Ecx.H1); - Vendor_ID(11) := Character'Val (Ecx.L2); - Vendor_ID(12) := Character'Val (Ecx.H2); - - -- return string - return Vendor_ID; - - end Vendor_ID; - - ------------------------------- - -- Get processor signature -- - ------------------------------- - - function Signature return Processor_Signature is - - Result : Processor_Signature; - -- processor signature returned - - begin - - -- execute CPUID, storing the results in the Result variable - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- one is stored in eax - -- processor signature returned in eax - Inputs => Unsigned_32'Asm_input ("a", 1), - - -- eax is stored in Result - Outputs => Processor_Signature'Asm_output ("=a", Result), - - -- tell compiler that ebx, ecx and edx are also destroyed - Clobber => "ebx, ecx, edx"); - - -- return processor signature - return Result; - - end Signature; - - ------------------------------ - -- Get processor features -- - ------------------------------ - - function Features return Processor_Features is - - Result : Processor_Features; - -- processor features returned - - begin - - -- execute CPUID, storing the results in the Result variable - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- one stored in eax - -- processor features returned in edx - Inputs => Unsigned_32'Asm_input ("a", 1), - - -- edx is stored in Result - Outputs => Processor_Features'Asm_output ("=d", Result), - - -- tell compiler that ebx and ecx are also destroyed - Clobber => "ebx, ecx"); - - -- return processor signature - return Result; - - end Features; - - end Intel_CPU; - -  - File: gnat_ug_vms.info, Node: Performance Considerations, Next: GNU Free Documentation License, Prev: Inline Assembler, Up: Top - - Performance Considerations - ************************** - - The GNAT system provides a number of options that allow a trade-off - between - - * performance of the generated code - - * speed of compilation - - * minimization of dependences and recompilation - - * the degree of run-time checking. - - The defaults (if no options are selected) aim at improving the speed of - compilation and minimizing dependences, at the expense of performance - of the generated code: - - * no optimization - - * no inlining of subprogram calls - - * all run-time checks enabled except overflow and elaboration checks - - These options are suitable for most program development purposes. This - chapter describes how you can modify these choices, and also provides - some guidelines on debugging optimized code. - - * Menu: - - * Controlling Run-Time Checks:: - * Optimization Levels:: - * Debugging Optimized Code:: - * Inlining of Subprograms:: - * Coverage Analysis:: - -  - File: gnat_ug_vms.info, Node: Controlling Run-Time Checks, Next: Optimization Levels, Up: Performance Considerations - - Controlling Run-Time Checks - =========================== - - By default, GNAT generates all run-time checks, except arithmetic - overflow checking for integer operations and checks for access before - elaboration on subprogram calls. The latter are not required in default - mode, because all necessary checking is done at compile time. Two gnat - qualifiers, `/CHECKS=SUPPRESS_ALL' and `/CHECKS=OVERFLOW' allow this - default to be modified. *Note Run-Time Checks::. - - Our experience is that the default is suitable for most development - purposes. - - We treat integer overflow specially because these are quite - expensive and in our experience are not as important as other run-time - checks in the development process. Note that division by zero is not - considered an overflow check, and divide by zero checks are generated - where required by default. - - Elaboration checks are off by default, and also not needed by - default, since GNAT uses a static elaboration analysis approach that - avoids the need for run-time checking. This manual contains a full - chapter discussing the issue of elaboration checks, and if the default - is not satisfactory for your use, you should read this chapter. - - For validity checks, the minimal checks required by the Ada Reference - Manual (for case statements and assignments to array elements) are on - by default. These can be suppressed by use of the `-gnatVn' qualifier. - Note that in Ada 83, there were no validity checks, so if the Ada 83 - mode is acceptable (or when comparing GNAT performance with an Ada 83 - compiler), it may be reasonable to routinely use `-gnatVn'. Validity - checks are also suppressed entirely if `/CHECKS=SUPPRESS_ALL' is used. - - Note that the setting of the qualifiers controls the default setting - of the checks. They may be modified using either `pragma Suppress' (to - remove checks) or `pragma Unsuppress' (to add back suppressed checks) - in the program source. - -  - File: gnat_ug_vms.info, Node: Optimization Levels, Next: Debugging Optimized Code, Prev: Controlling Run-Time Checks, Up: Performance Considerations - - Optimization Levels - =================== - - The default is optimization off. This results in the fastest compile - times, but GNAT makes absolutely no attempt to optimize, and the - generated programs are considerably larger and slower than when - optimization is enabled. You can use the `/OPTIMIZE' on the `GNAT - COMPILE' command line to control the optimization level: - - `/OPTIMIZE=NONE' - no optimization (the default) - - `/OPTIMIZE=SOME' - medium level optimization - - `/OPTIMIZE=ALL' - full optimization - - `/OPTIMIZE=INLINING' - full optimization, and also attempt automatic inlining of small - subprograms within a unit (*note Inlining of Subprograms::). - - Higher optimization levels perform more global transformations on the - program and apply more expensive analysis algorithms in order to - generate faster and more compact code. The price in compilation time, - and the resulting improvement in execution time, both depend on the - particular application and the hardware environment. You should - experiment to find the best level for your application. - - Note: Unlike some other compilation systems, `GNAT COMPILE' has been - tested extensively at all optimization levels. There are some bugs - which appear only with optimization turned on, but there have also been - bugs which show up only in _unoptimized_ code. Selecting a lower level - of optimization does not improve the reliability of the code generator, - which in practice is highly reliable at all optimization levels. - - Note regarding the use of `/OPTIMIZE=INLINING': The use of this - optimization level is generally discouraged with GNAT, since it often - results in larger executables which run more slowly. See further - discussion of this point in *note Inlining of Subprograms::. - -  - File: gnat_ug_vms.info, Node: Debugging Optimized Code, Next: Inlining of Subprograms, Prev: Optimization Levels, Up: Performance Considerations - - Debugging Optimized Code - ======================== - - Since the compiler generates debugging tables for a compilation unit - before it performs optimizations, the optimizing transformations may - invalidate some of the debugging data. You therefore need to - anticipate certain anomalous situations that may arise while debugging - optimized code. This section describes the most common cases. - - 1. The "hopping Program Counter": Repeated 'step' or 'next' commands - show the PC bouncing back and forth in the code. This may result - from any of the following optimizations: - - * Common subexpression elimination: using a single instance of - code for a quantity that the source computes several times. - As a result you may not be able to stop on what looks like a - statement. - - * Invariant code motion: moving an expression that does not - change within a loop, to the beginning of the loop. - - * Instruction scheduling: moving instructions so as to overlap - loads and stores (typically) with other code, or in general - to move computations of values closer to their uses. Often - this causes you to pass an assignment statement without the - assignment happening and then later bounce back to the - statement when the value is actually needed. Placing a - breakpoint on a line of code and then stepping over it may, - therefore, not always cause all the expected side-effects. - - 2. The "big leap": More commonly known as cross-jumping, in which two - identical pieces of code are merged and the program counter - suddenly jumps to a statement that is not supposed to be executed, - simply because it (and the code following) translates to the same - thing as the code that _was_ supposed to be executed. This effect - is typically seen in sequences that end in a jump, such as a - `goto', a `return', or a `break' in a C `qualifier' statement. - - 3. The "roving variable": The symptom is an unexpected value in a - variable. There are various reasons for this effect: - - * In a subprogram prologue, a parameter may not yet have been - moved to its "home". - - * A variable may be dead, and its register re-used. This is - probably the most common cause. - - * As mentioned above, the assignment of a value to a variable - may have been moved. - - * A variable may be eliminated entirely by value propagation or - other means. In this case, GCC may incorrectly generate - debugging information for the variable - - In general, when an unexpected value appears for a local variable - or parameter you should first ascertain if that value was actually - computed by your program, as opposed to being incorrectly reported - by the debugger. Record fields or array elements in an object - designated by an access value are generally less of a problem, - once you have ascertained that the access value is sensible. - Typically, this means checking variables in the preceding code and - in the calling subprogram to verify that the value observed is - explainable from other values (one must apply the procedure - recursively to those other values); or re-running the code and - stopping a little earlier (perhaps before the call) and stepping - to better see how the variable obtained the value in question; or - continuing to step _from_ the point of the strange value to see if - code motion had simply moved the variable's assignments later. - -  - File: gnat_ug_vms.info, Node: Inlining of Subprograms, Next: Coverage Analysis, Prev: Debugging Optimized Code, Up: Performance Considerations - - Inlining of Subprograms - ======================= - - A call to a subprogram in the current unit is inlined if all the - following conditions are met: - - * The optimization level is at least `/OPTIMIZE=SOME'. - - * The called subprogram is suitable for inlining: It must be small - enough and not contain nested subprograms or anything else that - `GNAT COMPILE' cannot support in inlined subprograms. - - * The call occurs after the definition of the body of the subprogram. - - * Either `pragma Inline' applies to the subprogram or it is small - and automatic inlining (optimization level `/OPTIMIZE=INLINING') is - specified. - - Calls to subprograms in `with''ed units are normally not inlined. To - achieve this level of inlining, the following conditions must all be - true: - - * The optimization level is at least `/OPTIMIZE=SOME'. - - * The called subprogram is suitable for inlining: It must be small - enough and not contain nested subprograms or anything else `GNAT - COMPILE' cannot support in inlined subprograms. - - * The call appears in a body (not in a package spec). - - * There is a `pragma Inline' for the subprogram. - - * The `/INLINE' qualifier is used in the `GNAT COMPILE' command line - - Note that specifying the `/INLINE=PRAGMA' qualifier causes additional - compilation dependencies. Consider the following: - - package R is - procedure Q; - pragma Inline (Q); - end R; - package body R is - ... - end R; - - with R; - procedure Main is - begin - ... - R.Q; - end Main; - - With the default behavior (no `/INLINE=PRAGMA' qualifier specified), the - compilation of the `Main' procedure depends only on its own source, - `MAIN.ADB', and the spec of the package in file `R.ADS'. This means - that editing the body of `R' does not require recompiling `Main'. - - On the other hand, the call `R.Q' is not inlined under these - circumstances. If the `/INLINE=PRAGMA' qualifier is present when `Main' - is compiled, the call will be inlined if the body of `Q' is small - enough, but now `Main' depends on the body of `R' in `R.ADB' as well as - on the spec. This means that if this body is edited, the main program - must be recompiled. Note that this extra dependency occurs whether or - not the call is in fact inlined by `GNAT COMPILE'. - - The use of front end inlining with `-gnatN' generates similar - additional dependencies. - - Note: The `/INLINE=SUPPRESS' qualifier can be used to prevent all - inlining. This qualifier overrides all other conditions and ensures - that no inlining occurs. The extra dependences resulting from - `/INLINE=PRAGMA' will still be active, even if this qualifier is used - to suppress the resulting inlining actions. - - Note regarding the use of `/OPTIMIZE=INLINING': There is no - difference in inlining behavior between `/OPTIMIZE=ALL' and - `/OPTIMIZE=INLINING' for subprograms with an explicit pragma `Inline' - assuming the use of `/INLINE=PRAGMA' or `-gnatN' (the qualifiers that - activate inlining). If you have used pragma `Inline' in appropriate - cases, then it is usually much better to use `/OPTIMIZE=ALL' and - `/INLINE=PRAGMA' and avoid the use of `/OPTIMIZE=INLINING' which in - this case only has the effect of inlining subprograms you did not think - should be inlined. We often find that the use of `/OPTIMIZE=INLINING' - slows down code by performing excessive inlining, leading to increased - instruction cache pressure from the increased code size. So the bottom - line here is that you should not automatically assume that - `/OPTIMIZE=INLINING' is better than `/OPTIMIZE=ALL', and indeed you - should use `/OPTIMIZE=INLINING' only if tests show that it actually - improves performance. - -  - File: gnat_ug_vms.info, Node: Coverage Analysis, Prev: Inlining of Subprograms, Up: Performance Considerations - - Coverage Analysis - ================= - - GNAT supports the Digital Performance Coverage Analyzer (PCA), which - allows the user to determine the distribution of execution time across - a program, *note Profiling:: for details of usage. - -  - File: gnat_ug_vms.info, Node: GNU Free Documentation License, Next: Index, Prev: Performance Considerations, Up: Top - - GNU Free Documentation License - ****************************** - - Version 1.2, November 2002 - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warrany Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - - ADDENDUM: How to use this License for your documents - ==================================================== - - To use this License in a document you have written, include a copy of - the License in the document and put the following copyright and license - notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover - Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other - combination of the three, merge those two alternatives to suit the - situation. - - If your document contains nontrivial examples of program code, we - recommend releasing these examples in parallel under your choice of - free software license, such as the GNU General Public License, to - permit their use in free software. - -  - File: gnat_ug_vms.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - - Index - ***** - - * Menu: - - * -83 (gnathtml): Converting Ada Files to html with gnathtml. - * -c (gnatname): Qualifiers for gnatname. - * -d (gnathtml): Converting Ada Files to html with gnathtml. - * -D (gnatname): Qualifiers for gnatname. - * -d (gnatname): Qualifiers for gnatname. - * -f (GNAT LINK): Qualifiers for GNAT LINK. - * -f (gnathtml): Converting Ada Files to html with gnathtml. - * -fstack-check: Stack Overflow Checking. - * -gnatem (GNAT COMPILE): Units to Sources Mapping Files. - * -gnatN (GNAT COMPILE): Subprogram Inlining Control. - * -gnatN qualifier: Source Dependencies. - * -gnatT (GNAT COMPILE): Run-Time Control. - * -gnatwP (GNAT COMPILE): Output and Error Message Control. - * -gnatwp (GNAT COMPILE): Output and Error Message Control. - * -h (gnatname): Qualifiers for gnatname. - * -I (gnathtml): Converting Ada Files to html with gnathtml. - * -l (gnathtml): Converting Ada Files to html with gnathtml. - * -o (gnathtml): Converting Ada Files to html with gnathtml. - * -p (gnathtml): Converting Ada Files to html with gnathtml. - * -P (gnatname): Qualifiers for gnatname. - * -sc (gnathtml): Converting Ada Files to html with gnathtml. - * -t (gnathtml): Converting Ada Files to html with gnathtml. - * -v (gnatname): Qualifiers for gnatname. - * -w: Output and Error Message Control. - * /83 (GNAT COMPILE): Compiling Ada 83 Programs. - * /ACTIONS=BIND (GNAT MAKE): Qualifiers for GNAT MAKE. - * /ACTIONS=COMPILE (GNAT MAKE): Qualifiers for GNAT MAKE. - * /ACTIONS=LINK (GNAT MAKE): Qualifiers for GNAT MAKE. - * /ALL_FILES (GNAT MAKE): Qualifiers for GNAT MAKE. - * /ALL_UNITS (GNAT LIST): Qualifiers for GNAT LIST. - * /ASM (GNAT COMPILE): Qualifiers for GNAT COMPILE. - * /BIND_FILE=ADA (GNAT BIND): Output Control. - * /BIND_FILE=ADA (GNAT LINK): Qualifiers for GNAT LINK. - * /BIND_FILE=C (GNAT BIND): Output Control. - * /BIND_FILE=C (GNAT LINK): Qualifiers for GNAT LINK. - * /BINDER_QUALIFIERS (GNAT MAKE): Mode Qualifiers for GNAT MAKE. - * /CHECKS=ASSERTIONS (GNAT COMPILE): Debugging and Assertion Control. - * /CHECKS=ELABORATION (GNAT COMPILE) <1>: Debugging Control. - * /CHECKS=ELABORATION (GNAT COMPILE): Run-Time Checks. - * /CHECKS=OVERFLOW (GNAT COMPILE) <1>: Controlling Run-Time Checks. - * /CHECKS=OVERFLOW (GNAT COMPILE): Run-Time Checks. - * /CHECKS=SUPPRESS_ALL (GNAT COMPILE) <1>: Controlling Run-Time Checks. - * /CHECKS=SUPPRESS_ALL (GNAT COMPILE): Run-Time Checks. - * /COMPILATION (GNAT CHOP): Qualifiers for GNAT CHOP. - * /COMPILER_QUALIFIERS (GNAT MAKE): Mode Qualifiers for GNAT MAKE. - * /CONDITIONAL_SOURCE_SEARCH (GNAT MAKE): Qualifiers for GNAT MAKE. - * /CONFIG=file (GNAT LIBRARY): Qualifiers for GNAT LIBRARY. - * /CONTINUE_ON_ERROR (GNAT MAKE): Qualifiers for GNAT MAKE. - * /CREATE=directory (GNAT LIBRARY): Qualifiers for GNAT LIBRARY. - * /DEBUG (GNAT COMPILE): Qualifiers for GNAT COMPILE. - * /DEBUG (GNAT LINK): Qualifiers for GNAT LINK. - * /DEBUG=TRACEBACK (GNAT LINK): Qualifiers for GNAT LINK. - * /DELETE=directory (GNAT LIBRARY): Qualifiers for GNAT LIBRARY. - * /DEPENDENCIES (GNAT LIST): Qualifiers for GNAT LIST. - * /DEPENDENCIES_LIST (GNAT MAKE): Qualifiers for GNAT MAKE. - * /DO_OBJECT_CHECK (GNAT MAKE): Qualifiers for GNAT MAKE. - * /ELABORATION_DEPENDENCIES (GNAT BIND): Output Control. - * /ERROR_LIMIT (GNAT COMPILE): Output and Error Message Control. - * /EXECUTABLE (GNAT LINK): Qualifiers for GNAT LINK. - * /EXECUTABLE (GNAT MAKE): Qualifiers for GNAT MAKE. - * /EXPAND_SOURCE (GNAT COMPILE): Debugging Control. - * /FILE_NAME_MAX_LENGTH (GNAT CHOP): Qualifiers for GNAT CHOP. - * /FILE_NAME_MAX_LENGTH (GNAT COMPILE): File Naming Control. - * /FORCE_COMPILE (GNAT MAKE): Qualifiers for GNAT MAKE. - * /HELP (GNAT BIND): Output Control. - * /IDENTIFIER_CHARACTER_SET (GNAT COMPILE): Character Set Control. - * /IN_PLACE (GNAT MAKE): Qualifiers for GNAT MAKE. - * /INLINE=PRAGMA (GNAT COMPILE) <1>: Inlining of Subprograms. - * /INLINE=PRAGMA (GNAT COMPILE): Subprogram Inlining Control. - * /INLINE=PRAGMA qualifier: Source Dependencies. - * /INLINE=SUPPRESS (GNAT COMPILE): Inlining of Subprograms. - * /LIBRARY_SEARCH (GNAT MAKE): Qualifiers for GNAT MAKE. - * /LINKER_OPTION_LIST (GNAT BIND): Output Control. - * /LINKER_QUALIFIERS (GNAT MAKE): Mode Qualifiers for GNAT MAKE. - * /LIST (GNAT COMPILE): Output and Error Message Control. - * /MAPPING (GNAT MAKE): Qualifiers for GNAT MAKE. - * /MINIMAL_RECOMPILATION (GNAT MAKE): Qualifiers for GNAT MAKE. - * /NOCURRENT_DIRECTORY (GNAT COMPILE): Qualifiers for GNAT COMPILE. - * /NOCURRENT_DIRECTORY (GNAT MAKE): Qualifiers for GNAT MAKE. - * /NOLOAD (GNAT COMPILE): Using GNAT COMPILE for Semantic Checking. - * /NOMAIN (GNAT BIND): Binding with Non-Ada Main Programs. - * /NOMAIN (GNAT MAKE): Qualifiers for GNAT MAKE. - * /NOOUTPUT (GNAT BIND): Output Control. - * /NOSTD_INCLUDES (GNAT MAKE): Qualifiers for GNAT MAKE. - * /NOSTD_LIBRARIES (GNAT MAKE): Qualifiers for GNAT MAKE. - * /NOTIME_STAMP_CHECK (GNAT BIND): Binder Error Message Control. - * /OBJECT_LIST (GNAT BIND): Output Control. - * /OBJECT_SEARCH (GNAT MAKE): Qualifiers for GNAT MAKE. - * /OPTIMIZE (GNAT COMPILE): Optimization Levels. - * /ORDER_OF_ELABORATION (GNAT BIND): Output Control. - * /OUTPUT (GNAT BIND): Output Control. - * /OUTPUT=OBJECTS (GNAT LIST): Qualifiers for GNAT LIST. - * /OUTPUT=OPTIONS (GNAT LIST): Qualifiers for GNAT LIST. - * /OUTPUT=SOURCES (GNAT LIST): Qualifiers for GNAT LIST. - * /OUTPUT=UNITS (GNAT LIST): Qualifiers for GNAT LIST. - * /OUTPUT=VERBOSE (GNAT LIST): Qualifiers for GNAT LIST. - * /OVERWRITE (GNAT CHOP): Qualifiers for GNAT CHOP. - * /PESSIMISTIC_ELABORATION (GNAT BIND): Elaboration Control. - * /PRESERVE (GNAT CHOP): Qualifiers for GNAT CHOP. - * /PROCESSES (GNAT MAKE): Qualifiers for GNAT MAKE. - * /QUIET (GNAT CHOP): Qualifiers for GNAT CHOP. - * /QUIET (GNAT MAKE): Qualifiers for GNAT MAKE. - * /READ_SOURCES=ALL (GNAT BIND): Consistency-Checking Modes. - * /READ_SOURCES=NONE (GNAT BIND): Consistency-Checking Modes. - * /REASONS (GNAT MAKE): Qualifiers for GNAT MAKE. - * /REFERENCE (GNAT CHOP): Qualifiers for GNAT CHOP. - * /REPORT_ERRORS=BRIEF (GNAT BIND): Binder Error Message Control. - * /REPORT_ERRORS=FULL (GNAT COMPILE): Output and Error Message Control. - * /REPORT_ERRORS=VERBOSE (GNAT BIND): Binder Error Message Control. - * /REPORT_ERRORS=VERBOSE (GNAT COMPILE): Output and Error Message Control. - * /REPRESENTATION_INFO (GNAT COMPILE): Debugging Control. - * /RESTRICTION_LIST (GNAT BIND): Output Control. - * /RUNTIME_SYSTEM (GNAT BIND): Summary of Binder Qualifiers. - * /RUNTIME_SYSTEM (GNAT COMPILE): Qualifiers for GNAT COMPILE. - * /RUNTIME_SYSTEM (GNAT FIND): GNAT FIND Qualifiers. - * /RUNTIME_SYSTEM (GNAT LIST): Qualifiers for GNAT LIST. - * /RUNTIME_SYSTEM (GNAT MAKE): Qualifiers for GNAT MAKE. - * /RUNTIME_SYSTEM (GNAT XREF): GNAT XREF Qualifiers. - * /SEARCH (GNAT COMPILE): Qualifiers for GNAT COMPILE. - * /SEARCH (GNAT MAKE): Qualifiers for GNAT MAKE. - * /SET=directory (GNAT LIBRARY): Qualifiers for GNAT LIBRARY. - * /SKIP_MISSING (GNAT MAKE): Qualifiers for GNAT MAKE. - * /SOURCE_SEARCH (GNAT MAKE): Qualifiers for GNAT MAKE. - * /SWITCH_CHECK (GNAT MAKE): Qualifiers for GNAT MAKE. - * /SYNTAX_ONLY (GNAT COMPILE): Using GNAT COMPILE for Syntax Checking. - * /TRACE_UNITS qualifier: GNAT Abnormal Termination or Failure to Terminate. - * /TREE_OUTPUT (GNAT COMPILE): Auxiliary Output Control. - * /TRY_SEMANTICS (GNAT COMPILE): Output and Error Message Control. - * /UNIQUE (GNAT MAKE): Qualifiers for GNAT MAKE. - * /UNIQUE_ERROR_TAG (GNAT COMPILE): Output and Error Message Control. - * /UNITS_LIST (GNAT COMPILE): Auxiliary Output Control. - * /VERBOSE (GNAT CHOP): Qualifiers for GNAT CHOP. - * /VERBOSE (GNAT COMPILE): Qualifiers for GNAT COMPILE. - * /VERBOSE (GNAT LINK): Qualifiers for GNAT LINK. - * /WARNINGS=BIASED_ROUNDING (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=BRIEF (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=CONDITIONALS (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=ELABORATION (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=ERROR (GNAT BIND): Binder Error Message Control. - * /WARNINGS=ERROR (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=HIDING (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=IMPLEMENTATION (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=IMPLICIT_DEREFERENCE (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOBIASED_ROUNDING (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOCONDITIONALS (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOELABORATION (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOHIDING (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOIMPLEMENTATION (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOIMPLICIT_DEREFERENCE (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOOPTIONAL (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOOVERLAYS (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOREDUNDANT (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOUNREFERENCED_FORMALS (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=NOUNUSED (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=OPTIONAL (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=OVERLAYS (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=REDUNDANT (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=SUPPRESS (GNAT BIND): Binder Error Message Control. - * /WARNINGS=SUPPRESS (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=UNREFERENCED_FORMALS (GNAT COMPILE): Output and Error Message Control. - * /WARNINGS=UNUSED (GNAT COMPILE): Output and Error Message Control. - * /WIDE_CHARACTER_ENCODING (GNAT COMPILE): Character Set Control. - * /XDEBUG (GNAT COMPILE): Debugging Control. - * /XREF=SUPPRESS (GNAT COMPILE): Debugging Control. - * /ZERO_MAIN (GNAT BIND): Binding Programs with No Main Subprogram. - * __gnat_finalize: Running GNAT BIND. - * __gnat_initialize: Running GNAT BIND. - * __gnat_set_globals: Running GNAT BIND. - * _main: The External Symbol Naming Scheme of GNAT. - * Access before elaboration: Run-Time Checks. - * Access-to-subprogram: Elaboration for Access-to-Subprogram Values. - * ACVC, Ada 83 tests: Compiling Ada 83 Programs. - * Ada <1>: Naming Conventions for GNAT Source Files. - * Ada: Search Paths for GNAT BIND. - * Ada 83 compatibility: Compiling Ada 83 Programs. - * Ada 95 Language Reference Manual: What You Should Know before Reading This Guide. - * Ada expressions: Using Ada Expressions. - * Ada Library Information files: The Ada Library Information Files. - * Ada.Characters.Latin_1: Latin-1. - * ADA_INCLUDE_PATH: Search Paths and the Run-Time Library (RTL). - * ADA_OBJECTS_PATH: Search Paths for GNAT BIND. - * adafinal <1>: Binding with Non-Ada Main Programs. - * adafinal: Running GNAT BIND. - * adainit <1>: Binding with Non-Ada Main Programs. - * adainit: Running GNAT BIND. - * Address Clauses, warnings: Output and Error Message Control. - * ali files: The Ada Library Information Files. - * Annex A: Naming Conventions for GNAT Source Files. - * Annex B: Naming Conventions for GNAT Source Files. - * Arbitrary File Naming Conventions: Handling Arbitrary File Naming Conventions Using gnatname. - * Asm: Calling Conventions. - * Assert: Debugging and Assertion Control. - * Assertions: Debugging and Assertion Control. - * Biased rounding: Output and Error Message Control. - * Binder consistency checks: Binder Error Message Control. - * Binder output file: Interfacing to C. - * Binder, multiple input files: Binding with Non-Ada Main Programs. - * Breakpoints and tasks: Ada Tasks. - * C: Calling Conventions. - * C++: Calling Conventions. - * Calling Conventions: Calling Conventions. - * Check, elaboration: Run-Time Checks. - * Check, overflow: Run-Time Checks. - * Check_CPU procedure: Check_CPU Procedure. - * Checks, access before elaboration: Run-Time Checks. - * Checks, division by zero: Run-Time Checks. - * Checks, elaboration: Checking the Elaboration Order in Ada 95. - * Checks, overflow: Controlling Run-Time Checks. - * Checks, suppressing: Run-Time Checks. - * COBOL: Calling Conventions. - * code page 437: Other 8-Bit Codes. - * code page 850: Other 8-Bit Codes. - * Command line length: Qualifiers for GNAT LINK. - * Compatibility: Compatibility with DEC Ada. - * Compilation model: The GNAT Compilation Model. - * Conditionals, constant: Output and Error Message Control. - * Configuration pragmas: Configuration Pragmas. - * Consistency checks, in binder: Binder Error Message Control. - * Convention Ada: Calling Conventions. - * Convention Asm: Calling Conventions. - * Convention Assembler: Calling Conventions. - * Convention C: Calling Conventions. - * Convention C++: Calling Conventions. - * Convention COBOL: Calling Conventions. - * Convention Default: Calling Conventions. - * Convention DLL: Calling Conventions. - * Convention External: Calling Conventions. - * Convention Fortran: Calling Conventions. - * Convention Stdcall: Calling Conventions. - * Convention Stubbed: Calling Conventions. - * Convention Win32: Calling Conventions. - * Conventions: Conventions. - * CR: Source Representation. - * Cyrillic: Other 8-Bit Codes. - * Debug: Debugging and Assertion Control. - * Debug Pool: Finding Memory Problems with GNAT Debug Pool. - * Debugger: Running and Debugging Ada Programs. - * Debugging: Running and Debugging Ada Programs. - * Debugging Generic Units: Debugging Generic Units. - * Debugging information, including: Qualifiers for GNAT LINK. - * Debugging options: Debugging Control. - * Default: Calling Conventions. - * Dependencies, producing list: Qualifiers for GNAT MAKE. - * Dependency rules: The GNAT Make Program GNAT MAKE. - * Dereferencing, implicit: Output and Error Message Control. - * Division by zero: Run-Time Checks. - * DLL: Calling Conventions. - * Elaborate: Controlling the Elaboration Order in Ada 95. - * Elaborate_All: Controlling the Elaboration Order in Ada 95. - * Elaborate_Body: Controlling the Elaboration Order in Ada 95. - * Elaboration checks <1>: Checking the Elaboration Order in Ada 95. - * Elaboration checks: Run-Time Checks. - * Elaboration control <1>: Summary of Procedures for Elaboration Control. - * Elaboration control: Elaboration Order Handling in GNAT. - * Elaboration of library tasks: Elaboration Issues for Library Tasks. - * Elaboration order control: Comparison between GNAT and C/C++ Compilation Models. - * Elaboration, warnings: Output and Error Message Control. - * Eliminate: Eliminate Pragma. - * EMACS: Editing with EMACS. - * End of source file: Source Representation. - * Error messages, suppressing: Output and Error Message Control. - * EUC Coding: Wide Character Encodings. - * Exceptions: Ada Exceptions. - * Export: The External Symbol Naming Scheme of GNAT. - * External: Calling Conventions. - * FDL, GNU Free Documentation License: GNU Free Documentation License. - * FF: Source Representation. - * File names <1>: Alternative File Naming Schemes. - * File names: Using Other File Names. - * File naming schemes, alternative: Alternative File Naming Schemes. - * Floating-Point types: Floating-Point Types and Representations. - * Foreign Languages: Calling Conventions. - * Formals, unreferenced: Output and Error Message Control. - * Fortran: Calling Conventions. - * GDB: Running and Debugging Ada Programs. - * Generic formal parameters: Compiling Ada 83 Programs. - * Generics <1>: Debugging Generic Units. - * Generics: Generating Object Files. - * GNAT <1>: Naming Conventions for GNAT Source Files. - * GNAT: Search Paths for GNAT BIND. - * GNAT Abnormal Termination or Failure to Terminate: GNAT Abnormal Termination or Failure to Terminate. - * GNAT BIND: Binding Using GNAT BIND. - * GNAT CHOP: Renaming Files Using GNAT CHOP. - * GNAT compilation model: The GNAT Compilation Model. - * GNAT ELIM: Reducing the Size of Ada Executables with GNAT ELIM. - * GNAT FIND: The Cross-Referencing Tools GNAT XREF and GNAT FIND. - * GNAT KRUNCH: File Name Krunching Using GNAT KRUNCH. - * GNAT LIBRARY: The GNAT Run-Time Library Builder GNAT LIBRARY. - * GNAT library: Comparison between GNAT and Conventional Ada Library Models. - * GNAT LINK: Linking Using GNAT LINK. - * GNAT LIST: The GNAT Library Browser GNAT LIST. - * GNAT MAKE: The GNAT Make Program GNAT MAKE. - * GNAT PREPROCESS: Preprocessing Using GNAT PREPROCESS. - * GNAT STUB: Creating Sample Bodies Using GNAT STUB. - * GNAT XREF: The Cross-Referencing Tools GNAT XREF and GNAT FIND. - * GNAT.ADC <1>: The Configuration Pragmas Files. - * GNAT.ADC: Using Other File Names. - * GNAT1: Compiling Programs. - * gnat_argc: Command-Line Access. - * gnat_argv: Command-Line Access. - * GNAT_STACK_LIMIT: Stack Overflow Checking. - * Hiding of Declarations: Output and Error Message Control. - * HT: Source Representation. - * Implicit dereferencing: Output and Error Message Control. - * Inline <1>: Inlining of Subprograms. - * Inline: Source Dependencies. - * Inlining: Comparison between GNAT and Conventional Ada Library Models. - * Inlining, warnings: Output and Error Message Control. - * Intel_CPU package body: Intel_CPU Package Body. - * Intel_CPU package specification: Intel_CPU Package Specification. - * Interfaces <1>: Naming Conventions for GNAT Source Files. - * Interfaces: Search Paths for GNAT BIND. - * Interfacing to Ada: Calling Conventions. - * Interfacing to Assembly: Calling Conventions. - * Interfacing to C: Calling Conventions. - * Interfacing to C++: Calling Conventions. - * Interfacing to COBOL: Calling Conventions. - * Interfacing to Fortran: Calling Conventions. - * Internal trees, writing to file: Auxiliary Output Control. - * Latin-1 <1>: Latin-1. - * Latin-1: Source Representation. - * Latin-2: Other 8-Bit Codes. - * Latin-3: Other 8-Bit Codes. - * Latin-4: Other 8-Bit Codes. - * Latin-5: Other 8-Bit Codes. - * LF: Source Representation. - * Library browser: The GNAT Library Browser GNAT LIST. - * Library builder: The GNAT Run-Time Library Builder GNAT LIBRARY. - * Library tasks, elaboration issues: Elaboration Issues for Library Tasks. - * Linker libraries: Qualifiers for GNAT MAKE. - * LSE: LSE. - * Machine_Overflows: Run-Time Checks. - * Main Program: Running GNAT BIND. - * Mixed Language Programming: Mixed Language Programming. - * Multiple units, syntax checking: Using GNAT COMPILE for Syntax Checking. - * No code generated: Compiling Programs. - * No_Entry_Calls_In_Elaboration_Code: Elaboration Issues for Library Tasks. - * Object file list: Running GNAT BIND. - * Order of elaboration: Elaboration Order Handling in GNAT. - * Other Ada compilers: Calling Conventions. - * Overflow checks <1>: Controlling Run-Time Checks. - * Overflow checks: Run-Time Checks. - * Parallel make: Qualifiers for GNAT MAKE. - * PCA: Profiling. - * Performance: Performance Considerations. - * pragma Elaborate: Controlling the Elaboration Order in Ada 95. - * pragma Elaborate_All: Controlling the Elaboration Order in Ada 95. - * pragma Elaborate_Body: Controlling the Elaboration Order in Ada 95. - * pragma Inline: Inlining of Subprograms. - * pragma Preelaborate: Controlling the Elaboration Order in Ada 95. - * pragma Pure: Controlling the Elaboration Order in Ada 95. - * pragma Suppress: Controlling Run-Time Checks. - * pragma Unsuppress: Controlling Run-Time Checks. - * Pragmas, configuration: Configuration Pragmas. - * Preelaborate: Controlling the Elaboration Order in Ada 95. - * Pure: Controlling the Elaboration Order in Ada 95. - * Recompilation, by GNAT MAKE: Notes on the Command Line. - * Rounding, biased: Output and Error Message Control. - * RTL: Qualifiers for GNAT COMPILE. - * SDP_Table_Build: Running GNAT BIND. - * Search paths, for GNAT MAKE: Qualifiers for GNAT MAKE. - * Shift JIS Coding: Wide Character Encodings. - * Source file, end: Source Representation. - * Source files, suppressing search: Qualifiers for GNAT MAKE. - * Source files, use by binder: Running GNAT BIND. - * Source_File_Name pragma <1>: Alternative File Naming Schemes. - * Source_File_Name pragma: Using Other File Names. - * Source_Reference: Qualifiers for GNAT CHOP. - * Stack Overflow Checking: Stack Overflow Checking. - * stack traceback: Stack Traceback. - * stack unwinding: Stack Traceback. - * Starlet: Bindings. - * Stdcall: Calling Conventions. - * storage, pool, memory corruption: Finding Memory Problems with GNAT Debug Pool. - * Stubbed: Calling Conventions. - * Style checking: Style Checking. - * SUB: Source Representation. - * Subunits: Generating Object Files. - * Suppress <1>: Controlling Run-Time Checks. - * Suppress: Run-Time Checks. - * Suppressing checks: Run-Time Checks. - * SYS$ERROR: Output and Error Message Control. - * SYS$OUTPUT: Output and Error Message Control. - * System <1>: Naming Conventions for GNAT Source Files. - * System: Search Paths for GNAT BIND. - * System.IO: Search Paths and the Run-Time Library (RTL). - * Task switching: Ada Tasks. - * Tasks: Ada Tasks. - * Time Slicing: Run-Time Control. - * Time stamp checks, in binder: Binder Error Message Control. - * traceback: Stack Traceback. - * traceback, non-symbolic: Non-Symbolic Traceback. - * traceback, symbolic: Symbolic Traceback. - * Tree file: Tree Files. - * Typographical conventions: Conventions. - * Unsuppress <1>: Controlling Run-Time Checks. - * Unsuppress: Run-Time Checks. - * Upper-Half Coding: Wide Character Encodings. - * Validity Checking: Validity Checking. - * Version skew (avoided by GNAT MAKE): Running a Simple Ada Program. - * Volatile parameter: The Volatile Parameter. - * VT: Source Representation. - * Warning messages: Output and Error Message Control. - * Warnings: Binder Error Message Control. - * Warnings, treat as error: Output and Error Message Control. - * Win32: Calling Conventions. - * Writing internal trees: Auxiliary Output Control. - * Zero Cost Exceptions: Running GNAT BIND. - - -  - Tag Table: - Node: Top91 - Node: About This Guide10020 - Node: What This Guide Contains10554 - Node: What You Should Know before Reading This Guide14536 - Node: Related Information14944 - Node: Conventions15780 - Node: Getting Started with GNAT16674 - Node: Running GNAT17105 - Node: Running a Simple Ada Program17708 - Node: Running a Program with Multiple Units20869 - Node: Using the GNAT MAKE Utility23129 - Node: Editing with EMACS25543 - Node: The GNAT Compilation Model26707 - Node: Source Representation28046 - Node: Foreign Language Representation29832 - Node: Latin-130318 - Node: Other 8-Bit Codes31184 - Node: Wide Character Encodings33277 - Node: File Naming Rules37083 - Node: Using Other File Names39385 - Node: Alternative File Naming Schemes41314 - Node: Generating Object Files46546 - Node: Source Dependencies49266 - Node: The Ada Library Information Files52820 - Node: Binding an Ada Program54971 - Node: Mixed Language Programming56819 - Node: Interfacing to C57096 - Node: Calling Conventions59705 - Node: Building Mixed Ada & C++ Programs65629 - Node: Interfacing to C++66710 - Node: Linking a Mixed C++ & Ada Program67750 - Node: A Simple Example70836 - Node: Adapting the Run Time to a New C++ Compiler73755 - Node: Comparison between GNAT and C/C++ Compilation Models74771 - Node: Comparison between GNAT and Conventional Ada Library Models76501 - Node: Compiling Using GNAT COMPILE79152 - Node: Compiling Programs79697 - Node: Qualifiers for GNAT COMPILE82589 - Node: Output and Error Message Control91042 - Node: Debugging and Assertion Control109943 - Node: Validity Checking111955 - Node: Style Checking118232 - Node: Run-Time Checks129939 - Node: Stack Overflow Checking134103 - Node: Run-Time Control136225 - Node: Using GNAT COMPILE for Syntax Checking137153 - Node: Using GNAT COMPILE for Semantic Checking138548 - Node: Compiling Ada 83 Programs140047 - Node: Character Set Control141497 - Node: File Naming Control144580 - Node: Subprogram Inlining Control145115 - Node: Auxiliary Output Control146417 - Node: Debugging Control147160 - Node: Units to Sources Mapping Files154487 - Node: Search Paths and the Run-Time Library (RTL)155897 - Node: Order of Compilation Issues159487 - Node: Examples161197 - Node: Binding Using GNAT BIND161815 - Node: Running GNAT BIND163699 - Node: Generating the Binder Program in C194503 - Node: Consistency-Checking Modes211963 - Node: Binder Error Message Control213659 - Node: Elaboration Control215819 - Node: Output Control217091 - Node: Binding with Non-Ada Main Programs219685 - Node: Binding Programs with No Main Subprogram222852 - Node: Summary of Binder Qualifiers223692 - Node: Command-Line Access227329 - Node: Search Paths for GNAT BIND228354 - Node: Examples of GNAT BIND Usage231584 - Node: Linking Using GNAT LINK233204 - Node: Running GNAT LINK233965 - Node: Qualifiers for GNAT LINK236227 - Node: Setting Stack Size from GNAT LINK239053 - Node: Setting Heap Size from GNAT LINK239918 - Node: The GNAT Make Program GNAT MAKE240741 - Node: Running GNAT MAKE242208 - Node: Qualifiers for GNAT MAKE243930 - Node: Mode Qualifiers for GNAT MAKE256186 - Node: Notes on the Command Line257474 - Node: How GNAT MAKE Works260493 - Node: Examples of GNAT MAKE Usage262676 - Node: Renaming Files Using GNAT CHOP263887 - Node: Handling Files with Multiple Units264487 - Node: Operating GNAT CHOP in Compilation Mode265814 - Node: Command Line for GNAT CHOP269152 - Node: Qualifiers for GNAT CHOP270632 - Node: Examples of GNAT CHOP Usage273948 - Node: Configuration Pragmas275350 - Node: Handling of Configuration Pragmas276903 - Node: The Configuration Pragmas Files277764 - Node: Handling Arbitrary File Naming Conventions Using gnatname279478 - Node: Arbitrary File Naming Conventions279888 - Node: Running gnatname281149 - Node: Qualifiers for gnatname282614 - Node: Examples of gnatname Usage285820 - Node: GNAT Project Manager286627 - Node: Introduction287291 - Node: Project Files288401 - Node: Examples of Project Files291625 - Node: Common Sources with Different Qualifiers and Different Output Directories292101 - Node: Source Files295314 - Node: Specifying the Object Directory295792 - Node: Specifying the Exec Directory296726 - Node: Project File Packages297496 - Node: Specifying Qualifier Settings298511 - Node: Main Subprograms300510 - Node: Source File Naming Conventions301181 - Node: Source Language(s)301683 - Node: Using External Variables302126 - Node: Importing Other Projects305031 - Node: Extending a Project308143 - Node: Project File Syntax310614 - Node: Basic Syntax311976 - Node: Packages312984 - Node: Expressions314141 - Node: String Types316039 - Node: Variables317342 - Node: Attributes320376 - Node: Associative Array Attributes325813 - Node: case Constructions326680 - Node: Objects and Sources in Project Files328490 - Node: Object Directory329070 - Node: Exec Directory330061 - Node: Source Directories330890 - Node: Source File Names332257 - Node: Importing Projects334594 - Node: Project Extension337373 - Node: External References in Project Files339054 - Node: Packages in Project Files340800 - Node: Variables from Imported Projects343218 - Node: Naming Schemes344916 - Node: Library Projects348889 - Node: Qualifiers Related to Project Files351787 - Node: Tools Supporting Project Files353517 - Node: GNAT MAKE and Project Files353824 - Node: Qualifiers and Project Files354286 - Node: Project Files and Main Subprograms360361 - Node: The GNAT Driver and Project Files362309 - Node: An Extended Example366049 - Node: Project File Complete Syntax369063 - Node: Elaboration Order Handling in GNAT371855 - Node: Elaboration Code in Ada 95372877 - Node: Checking the Elaboration Order in Ada 95377523 - Node: Controlling the Elaboration Order in Ada 95381524 - Node: Controlling Elaboration in GNAT - Internal Calls389841 - Node: Controlling Elaboration in GNAT - External Calls395562 - Node: Default Behavior in GNAT - Ensuring Safety399296 - Node: Elaboration Issues for Library Tasks403439 - Node: Mixing Elaboration Models416676 - Node: What to Do If the Default Elaboration Behavior Fails419197 - Node: Elaboration for Access-to-Subprogram Values429623 - Node: Summary of Procedures for Elaboration Control431447 - Node: Other Elaboration Order Considerations432645 - Node: The Cross-Referencing Tools GNAT XREF and GNAT FIND437920 - Node: GNAT XREF Qualifiers439634 - Node: GNAT FIND Qualifiers443018 - Node: Project Files for GNAT XREF and GNAT FIND448927 - Node: Regular Expressions in GNAT FIND and GNAT XREF452172 - Node: Examples of GNAT XREF Usage454963 - Node: Examples of GNAT FIND Usage458168 - Node: File Name Krunching Using GNAT KRUNCH460455 - Node: About GNAT KRUNCH461113 - Node: Using GNAT KRUNCH462490 - Node: Krunching Method463389 - Node: Examples of GNAT KRUNCH Usage466660 - Node: Preprocessing Using GNAT PREPROCESS467004 - Node: Using GNAT PREPROCESS467586 - Node: Qualifiers for GNAT PREPROCESS468496 - Node: Form of Definitions File470719 - Node: Form of Input Text for GNAT PREPROCESS471481 - Node: The GNAT Run-Time Library Builder GNAT LIBRARY475137 - Node: Running GNAT LIBRARY475617 - Node: Qualifiers for GNAT LIBRARY475920 - Node: Examples of GNAT LIBRARY Usage476713 - Node: The GNAT Library Browser GNAT LIST477156 - Node: Running GNAT LIST477752 - Node: Qualifiers for GNAT LIST480305 - Node: Examples of GNAT LIST Usage482393 - Node: Finding Memory Problems with GNAT Debug Pool483628 - Node: Creating Sample Bodies Using GNAT STUB488331 - Node: Running GNAT STUB489140 - Node: Qualifiers for GNAT STUB489909 - Node: Reducing the Size of Ada Executables with GNAT ELIM492222 - Node: About GNAT ELIM492763 - Node: Eliminate Pragma493858 - Node: Tree Files494869 - Node: Preparing Tree and Bind Files for GNAT ELIM495788 - Node: Running GNAT ELIM497887 - Node: Correcting the List of Eliminate Pragmas499897 - Node: Making Your Executables Smaller500681 - Node: Summary of the GNAT ELIM Usage Cycle501533 - Node: Other Utility Programs502405 - Node: Using Other Utility Programs with GNAT502953 - Node: The GNAT STANDARD Utility Program503408 - Node: The External Symbol Naming Scheme of GNAT504730 - Node: Ada Mode for Glide506732 - Node: Converting Ada Files to html with gnathtml508683 - Node: Installing gnathtml512291 - Node: LSE512969 - Node: Profiling513300 - Node: Running and Debugging Ada Programs513718 - Node: The GNAT Debugger GDB515116 - Node: Running GDB518290 - Node: Introduction to GDB Commands519227 - Node: Using Ada Expressions524131 - Node: Calling User-Defined Subprograms525325 - Node: Using the Next Command in a Function527745 - Node: Ada Exceptions528910 - Node: Ada Tasks529864 - Node: Debugging Generic Units531933 - Node: GNAT Abnormal Termination or Failure to Terminate533336 - Node: Naming Conventions for GNAT Source Files536029 - Node: Getting Internal Debugging Information538629 - Node: Stack Traceback539838 - Node: Non-Symbolic Traceback540875 - Node: Tracebacks From an Unhandled Exception541336 - Node: Tracebacks From Exception Occurrences (non-symbolic)545301 - Node: Tracebacks From Anywhere in a Program (non-symbolic)546584 - Node: Symbolic Traceback548429 - Node: Tracebacks From Exception Occurrences (symbolic)549152 - Node: Tracebacks From Anywhere in a Program (symbolic)550610 - Node: Compatibility with DEC Ada551802 - Node: Ada 95 Compatibility553351 - Node: Differences in the Definition of Package System554420 - Node: Language-Related Features556530 - Node: Integer Types and Representations557163 - Node: Floating-Point Types and Representations558107 - Node: Pragmas Float_Representation and Long_Float559412 - Node: Fixed-Point Types and Representations562751 - Node: Record and Array Component Alignment563387 - Node: Address Clauses564061 - Node: Other Representation Clauses566093 - Node: The Package STANDARD566493 - Node: The Package SYSTEM567383 - Node: Tasking and Task-Related Features571415 - Node: Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems571979 - Node: Assigning Task IDs573465 - Node: Task IDs and Delays574155 - Node: Task-Related Pragmas574728 - Node: Scheduling and Task Priority575825 - Node: The Task Stack577522 - Node: External Interrupts578436 - Node: Pragmas and Pragma-Related Features578763 - Node: Restrictions on the Pragma INLINE581055 - Node: Restrictions on the Pragma INTERFACE582212 - Node: Restrictions on the Pragma SYSTEM_NAME583214 - Node: Library of Predefined Units583615 - Node: Changes to DECLIB585446 - Node: Bindings586213 - Node: Shared Libraries and Options Files588022 - Node: Interfaces to C588741 - Node: Main Program Definition589597 - Node: Implementation-Defined Attributes590902 - Node: Compiler and Run-Time Interfacing591208 - Node: Program Compilation and Library Management592554 - Node: Input-Output603019 - Node: Implementation Limits605636 - Node: Tools607703 - Node: Inline Assembler607819 - Node: Basic Assembler Syntax609526 - Node: A Simple Example of Inline Assembler611406 - Node: Output Variables in Inline Assembler614617 - Node: Input Variables in Inline Assembler622006 - Node: Inlining Inline Assembler Code624524 - Node: Other Asm Functionality626482 - Node: The Clobber Parameter626917 - Node: The Volatile Parameter628916 - Node: A Complete Example630108 - Node: Check_CPU Procedure631082 - Node: Intel_CPU Package Specification646129 - Node: Intel_CPU Package Body655557 - Node: Performance Considerations664715 - Node: Controlling Run-Time Checks665771 - Node: Optimization Levels667801 - Node: Debugging Optimized Code669701 - Node: Inlining of Subprograms673437 - Node: Coverage Analysis677262 - Node: GNU Free Documentation License677608 - Node: Index700037 -  - End Tag Table --- 0 ---- diff -Nrc3pad gcc-3.3.2/gcc/ada/gnat_ug_vxw.info gcc-3.3.3/gcc/ada/gnat_ug_vxw.info *** gcc-3.3.2/gcc/ada/gnat_ug_vxw.info Thu Oct 16 20:24:02 2003 --- gcc-3.3.3/gcc/ada/gnat_ug_vxw.info Thu Jan 1 00:00:00 1970 *************** *** 1,18960 **** - This is ada/gnat_ug_vxw.info, produced by makeinfo version 4.2 from - ada/gnat_ug_vxw.texi. - - Copyright (C) 1995-2002, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT User's Guide for Cross Platforms", and - with no Back-Cover Texts. A copy of the license is included in the - section entitled "GNU Free Documentation License". -  - File: gnat_ug_vxw.info, Node: Top, Next: About This Guide, Prev: (dir), Up: (dir) - - GNAT User's Guide - ***************** - - GNAT User's Guide for Cross Platforms - - GNAT, The GNU Ada 95 Compiler - - GNAT Version for GCC 3.3.2 - - Ada Core Technologies, Inc. - - Copyright (C) 1995-2002, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT User's Guide for Cross Platforms", and - with no Back-Cover Texts. A copy of the license is included in the - section entitled "GNU Free Documentation License". - * Menu: - - * About This Guide:: - * Preliminary Note for Cross Platform Users:: - * Getting Started with GNAT:: - * The GNAT Compilation Model:: - * Compiling Using gcc:: - * Binding Using gnatbind:: - * Linking Using gnatlink:: - * The GNAT Make Program gnatmake:: - * Renaming Files Using gnatchop:: - * Configuration Pragmas:: - * Handling Arbitrary File Naming Conventions Using gnatname:: - * GNAT Project Manager:: - * Elaboration Order Handling in GNAT:: - * The Cross-Referencing Tools gnatxref and gnatfind:: - * File Name Krunching Using gnatkr:: - * Preprocessing Using gnatprep:: - * The GNAT Library Browser gnatls:: - * GNAT and Libraries:: - * Using the GNU make Utility:: - * Finding Memory Problems with GNAT Debug Pool:: - * Creating Sample Bodies Using gnatstub:: - * Reducing the Size of Ada Executables with gnatelim:: - * Other Utility Programs:: - * Running and Debugging Ada Programs:: - * Inline Assembler:: - * VxWorks Topics:: - * LynxOS Topics:: - * Performance Considerations:: - * GNU Free Documentation License:: - * Index:: - - --- The Detailed Node Listing --- - - About This Guide - - * What This Guide Contains:: - * What You Should Know before Reading This Guide:: - * Related Information:: - * Conventions:: - - Preliminary Note for Cross Platform Users:: - - Getting Started with GNAT - - * Running GNAT:: - * Building a Simple Ada Program:: - * Executing a Program on VxWorks:: - * Running a Program with Multiple Units:: - * Using the gnatmake Utility:: - - The GNAT Compilation Model - - * Source Representation:: - * Foreign Language Representation:: - * File Naming Rules:: - * Using Other File Names:: - * Alternative File Naming Schemes:: - * Generating Object Files:: - * Source Dependencies:: - * The Ada Library Information Files:: - * Binding an Ada Program:: - * Mixed Language Programming:: - * Building Mixed Ada & C++ Programs:: - * Comparison between GNAT and C/C++ Compilation Models:: - * Comparison between GNAT and Conventional Ada Library Models:: - - Foreign Language Representation - - * Latin-1:: - * Other 8-Bit Codes:: - * Wide Character Encodings:: - - Compiling Ada Programs With gcc - - * Compiling Programs:: - * Switches for gcc:: - * Search Paths and the Run-Time Library (RTL):: - * Order of Compilation Issues:: - * Examples:: - - Switches for gcc - - * Output and Error Message Control:: - * Debugging and Assertion Control:: - * Run-Time Checks:: - * Stack Overflow Checking:: - * Run-Time Control:: - * Validity Checking:: - * Style Checking:: - * Using gcc for Syntax Checking:: - * Using gcc for Semantic Checking:: - * Compiling Ada 83 Programs:: - * Character Set Control:: - * File Naming Control:: - * Subprogram Inlining Control:: - * Auxiliary Output Control:: - * Debugging Control:: - * Units to Sources Mapping Files:: - - Binding Ada Programs With gnatbind - - * Running gnatbind:: - * Generating the Binder Program in C:: - * Consistency-Checking Modes:: - * Binder Error Message Control:: - * Elaboration Control:: - * Output Control:: - * Binding with Non-Ada Main Programs:: - * Binding Programs with No Main Subprogram:: - * Summary of Binder Switches:: - * Command-Line Access:: - * Search Paths for gnatbind:: - * Examples of gnatbind Usage:: - - Linking Using gnatlink - - * Running gnatlink:: - * Switches for gnatlink:: - * Setting Stack Size from gnatlink:: - * Setting Heap Size from gnatlink:: - - The GNAT Make Program gnatmake - - * Running gnatmake:: - * Switches for gnatmake:: - * Mode Switches for gnatmake:: - * Notes on the Command Line:: - * How gnatmake Works:: - * Examples of gnatmake Usage:: - - Renaming Files Using gnatchop - - * Handling Files with Multiple Units:: - * Operating gnatchop in Compilation Mode:: - * Command Line for gnatchop:: - * Switches for gnatchop:: - * Examples of gnatchop Usage:: - - Configuration Pragmas - - * Handling of Configuration Pragmas:: - * The Configuration Pragmas Files:: - - Handling Arbitrary File Naming Conventions Using gnatname - - * Arbitrary File Naming Conventions:: - * Running gnatname:: - * Switches for gnatname:: - * Examples of gnatname Usage:: - - GNAT Project Manager - - * Introduction:: - * Examples of Project Files:: - * Project File Syntax:: - * Objects and Sources in Project Files:: - * Importing Projects:: - * Project Extension:: - * External References in Project Files:: - * Packages in Project Files:: - * Variables from Imported Projects:: - * Naming Schemes:: - * Library Projects:: - * Switches Related to Project Files:: - * Tools Supporting Project Files:: - * An Extended Example:: - * Project File Complete Syntax:: - - Elaboration Order Handling in GNAT - - * Elaboration Code in Ada 95:: - * Checking the Elaboration Order in Ada 95:: - * Controlling the Elaboration Order in Ada 95:: - * Controlling Elaboration in GNAT - Internal Calls:: - * Controlling Elaboration in GNAT - External Calls:: - * Default Behavior in GNAT - Ensuring Safety:: - * Elaboration Issues for Library Tasks:: - * Mixing Elaboration Models:: - * What to Do If the Default Elaboration Behavior Fails:: - * Elaboration for Access-to-Subprogram Values:: - * Summary of Procedures for Elaboration Control:: - * Other Elaboration Order Considerations:: - - The Cross-Referencing Tools gnatxref and gnatfind - - * gnatxref Switches:: - * gnatfind Switches:: - * Project Files for gnatxref and gnatfind:: - * Regular Expressions in gnatfind and gnatxref:: - * Examples of gnatxref Usage:: - * Examples of gnatfind Usage:: - - File Name Krunching Using gnatkr - - * About gnatkr:: - * Using gnatkr:: - * Krunching Method:: - * Examples of gnatkr Usage:: - - Preprocessing Using gnatprep - - * Using gnatprep:: - * Switches for gnatprep:: - * Form of Definitions File:: - * Form of Input Text for gnatprep:: - - - The GNAT Library Browser gnatls - - * Running gnatls:: - * Switches for gnatls:: - * Examples of gnatls Usage:: - - - GNAT and Libraries - - * Creating an Ada Library:: - * Installing an Ada Library:: - * Using an Ada Library:: - * Creating an Ada Library to be Used in a Non-Ada Context:: - * Rebuilding the GNAT Run-Time Library:: - - Using the GNU make Utility - - * Using gnatmake in a Makefile:: - * Automatically Creating a List of Directories:: - * Generating the Command Line Switches:: - * Overcoming Command Line Length Limits:: - - - Finding Memory Problems with GNAT Debug Pool - - Creating Sample Bodies Using gnatstub - - * Running gnatstub:: - * Switches for gnatstub:: - - Reducing the Size of Ada Executables with gnatelim - - * About gnatelim:: - * Eliminate Pragma:: - * Tree Files:: - * Preparing Tree and Bind Files for gnatelim:: - * Running gnatelim:: - * Correcting the List of Eliminate Pragmas:: - * Making Your Executables Smaller:: - * Summary of the gnatelim Usage Cycle:: - - Other Utility Programs - - * Using Other Utility Programs with GNAT:: - * The gnatpsta Utility Program:: - * The External Symbol Naming Scheme of GNAT:: - * Ada Mode for Glide:: - * Converting Ada Files to html with gnathtml:: - - - Running and Debugging Ada Programs - - * The GNAT Debugger GDB:: - * Running GDB:: - * Introduction to GDB Commands:: - * Using Ada Expressions:: - * Calling User-Defined Subprograms:: - * Using the Next Command in a Function:: - * Ada Exceptions:: - * Ada Tasks:: - * Debugging Generic Units:: - * GNAT Abnormal Termination or Failure to Terminate:: - * Naming Conventions for GNAT Source Files:: - * Getting Internal Debugging Information:: - * Stack Traceback:: - - Inline Assembler - - * Basic Assembler Syntax:: - * A Simple Example of Inline Assembler:: - * Output Variables in Inline Assembler:: - * Input Variables in Inline Assembler:: - * Inlining Inline Assembler Code:: - * Other Asm Functionality:: - * A Complete Example:: - - - VxWorks Topics - - * Kernel Configuration for VxWorks:: - * Kernel Compilation Issues for VxWorks:: - * Handling Relocation Issues for PowerPc Targets:: - * Support for Software Floating Point on PowerPC Processors:: - * Interrupt Handling for VxWorks:: - * Simulating Command Line Arguments for VxWorks:: - * Debugging Issues for VxWorks:: - * Using GNAT from the Tornado 2 Project Facility:: - * Frequently Asked Questions for VxWorks:: - - LynxOS Topics - - * Getting Started with GNAT on LynxOS:: - * Kernel Configuration for LynxOS:: - * Patch Level Issues for LynxOS:: - * Debugging Issues for LynxOS:: - * An Example Debugging Session for LynxOS:: - - Performance Considerations - - * Controlling Run-Time Checks:: - * Optimization Levels:: - * Debugging Optimized Code:: - * Inlining of Subprograms:: - - * Index:: - -  - File: gnat_ug_vxw.info, Node: About This Guide, Next: Preliminary Note for Cross Platform Users, Prev: Top, Up: Top - - About This Guide - **************** - - This guide describes the use of GNAT, a compiler and software - development toolset for the full Ada 95 programming language. It - describes the features of the compiler and tools, and details how to - use them to build Ada 95 applications. - - * Menu: - - * What This Guide Contains:: - * What You Should Know before Reading This Guide:: - * Related Information:: - * Conventions:: - -  - File: gnat_ug_vxw.info, Node: What This Guide Contains, Next: What You Should Know before Reading This Guide, Up: About This Guide - - What This Guide Contains - ======================== - - This guide contains the following chapters: - * *Note Preliminary Note for Cross Platform Users::, describes the - basic differences between the cross and native versions of GNAT. - - * *Note Getting Started with GNAT::, describes how to get started - compiling and running Ada programs with the GNAT Ada programming - environment. - - * *Note The GNAT Compilation Model::, describes the compilation - model used by GNAT. - - * *Note Compiling Using gcc::, describes how to compile Ada programs - with `gcc', the Ada compiler. - - * *Note Binding Using gnatbind::, describes how to perform binding - of Ada programs with `gnatbind', the GNAT binding utility. - - * *Note Linking Using gnatlink::, describes `gnatlink', a program - that provides for linking using the GNAT run-time library to - construct a program. `gnatlink' can also incorporate foreign - language object units into the executable. - - * *Note The GNAT Make Program gnatmake::, describes `gnatmake', a - utility that automatically determines the set of sources needed by - an Ada compilation unit, and executes the necessary compilations - binding and link. - - * *Note Renaming Files Using gnatchop::, describes `gnatchop', a - utility that allows you to preprocess a file that contains Ada - source code, and split it into one or more new files, one for each - compilation unit. - - * *Note Configuration Pragmas::, describes the configuration pragmas - handled by GNAT. - - * *Note Handling Arbitrary File Naming Conventions Using gnatname::, - shows how to override the default GNAT file naming conventions, - either for an individual unit or globally. - - * *Note GNAT Project Manager::, describes how to use project files - to organize large projects. - - * *Note Elaboration Order Handling in GNAT::, describes how GNAT - helps you deal with elaboration order issues. - - * *Note The Cross-Referencing Tools gnatxref and gnatfind::, - discusses `gnatxref' and `gnatfind', two tools that provide an easy - way to navigate through sources. - - * *Note File Name Krunching Using gnatkr::, describes the `gnatkr' - file name krunching utility, used to handle shortened file names - on operating systems with a limit on the length of names. - - * *Note Preprocessing Using gnatprep::, describes `gnatprep', a - preprocessor utility that allows a single source file to be used to - generate multiple or parameterized source files, by means of macro - substitution. - - * *Note The GNAT Library Browser gnatls::, describes `gnatls', a - utility that displays information about compiled units, including - dependences on the corresponding sources files, and consistency of - compilations. - - * *Note GNAT and Libraries::, describes the process of creating and - using Libraries with GNAT. It also describes how to recompile the - GNAT run-time library. - - * *Note Using the GNU make Utility::, describes some techniques for - using the GNAT toolset in Makefiles. - - * *Note Finding Memory Problems with GNAT Debug Pool::, describes - how to use the GNAT-specific Debug Pool in order to detect as - early as possible the use of incorrect memory references. - - * *Note Creating Sample Bodies Using gnatstub::, discusses - `gnatstub', a utility that generates empty but compilable bodies - for library units. - - * *Note Reducing the Size of Ada Executables with gnatelim::, - describes `gnatelim', a tool which detects unused subprograms and - helps the compiler to create a smaller executable for the program. - - * *Note Other Utility Programs::, discusses several other GNAT - utilities, including `gnatpsta'. - - * *Note Running and Debugging Ada Programs::, describes how to run - and debug Ada programs. - - * *Note Inline Assembler::, shows how to use the inline assembly - facility in an Ada program. - - * *Note VxWorks Topics::, presents information relevant to the - VxWorks target for cross-compilation configurations. - - * *Note LynxOS Topics::, presents information relevant to the LynxOS - target for cross-compilation configurations. - - * *Note Performance Considerations::, reviews the trade offs between - using defaults or options in program development. - -  - File: gnat_ug_vxw.info, Node: What You Should Know before Reading This Guide, Next: Related Information, Prev: What This Guide Contains, Up: About This Guide - - What You Should Know before Reading This Guide - ============================================== - - This user's guide assumes that you are familiar with Ada 95 language, as - described in the International Standard ANSI/ISO/IEC-8652:1995, Jan - 1995. - -  - File: gnat_ug_vxw.info, Node: Related Information, Next: Conventions, Prev: What You Should Know before Reading This Guide, Up: About This Guide - - Related Information - =================== - - For further information about related tools, refer to the following - documents: - - * `GNAT Reference Manual', which contains all reference material for - the GNAT implementation of Ada 95. - - * `Ada 95 Language Reference Manual', which contains all reference - material for the Ada 95 programming language. - - * `Debugging with GDB' contains all details on the use of the GNU - source-level debugger. - - * `GNU Emacs Manual' contains full information on the extensible - editor and programming environment Emacs. - - -  - File: gnat_ug_vxw.info, Node: Conventions, Prev: Related Information, Up: About This Guide - - Conventions - =========== - - Following are examples of the typographical and graphic conventions used - in this guide: - - * `Functions', `utility program names', `standard names', and - `classes'. - - * `Option flags' - - * `File Names', `button names', and `field names'. - - * VARIABLES. - - * _Emphasis_. - - * [optional information or parameters] - - * Examples are described by text - and then shown this way. - - Commands that are entered by the user are preceded in this manual by the - characters "`$ '" (dollar sign followed by space). If your system uses - this sequence as a prompt, then the commands will appear exactly as you - see them in the manual. If your system uses some other prompt, then the - command will appear with the `$' replaced by whatever prompt character - you are using. - -  - File: gnat_ug_vxw.info, Node: Preliminary Note for Cross Platform Users, Next: Getting Started with GNAT, Prev: About This Guide, Up: Top - - Preliminary Note for Cross Platform Users - ***************************************** - - The use of GNAT in a cross environment is very similar to its use in a - native environment. Most of the tools described in this manual have - similar functions and options in both modes. The major difference is - that the name of the cross tools includes the target for which the - cross compiler is configured. For instance, the cross `gnatmake' tool - is called `target-gnatmake' where `target' stands for the name of the - cross target. Thus, in an environment configured for the target - `powerpc-wrs-vxworks', the `gnatmake' command is - `powerpc-wrs-vxworks-gnatmake'. This convention allows the installation - of a native and one or several cross development environments at the - same location. - - The tools that are most relevant in a cross environment are: - `target-gcc', `target-gnatmake', `target-gnatbind', `target-gnatlink' - to build cross applications and `target-gnatls' for cross library - browsing. `target-gdb' is also usually available for cross debugging in - text mode. The graphical debugger interface `gvd' is always a native - tool but it can be configured to drive the above mentioned cross - debugger, thus allowing graphical cross debugging sessions. Some other - tools such as `target-gnatchop', `target-gnatkr', `target-gnatprep', - `target-gnatpsta', `target-gnatxref', `target-gnatfind' and - `target-gnatname' are also provided for completeness even though they - do not differ greatly from their native counterpart. - - In the rest of this manual, the tools are sometimes designated with - their full cross name, and sometimes with their simplified native name. - -  - File: gnat_ug_vxw.info, Node: Getting Started with GNAT, Next: The GNAT Compilation Model, Prev: Preliminary Note for Cross Platform Users, Up: Top - - Getting Started with GNAT - ************************* - - This introduction is a starting point for using GNAT to develop and - execute Ada 95 programs in a cross environment. It provides some - specifics about the GNAT toolchain targeted to the Wind River Sytems' - VxWorks/Tornado platform; for other targets please refer to the - corresponding chapter later in this manual. - - Basic familiarity with use of GNAT in a native environment is - presumed. For the VxWorks specific part, a knowledge of how to start - Tornado's `windsh' tool is also presumed. - - * Menu: - - * Running GNAT:: - * Building a Simple Ada Program:: - * Executing a Program on VxWorks:: - - * Running a Program with Multiple Units:: - - * Using the gnatmake Utility:: - * Introduction to Glide and GVD:: - -  - File: gnat_ug_vxw.info, Node: Running GNAT, Next: Building a Simple Ada Program, Up: Getting Started with GNAT - - Running GNAT - ============ - - Three steps are needed to create an executable file from an Ada source - file: - - 1. The source file(s) must be compiled. - - 2. The file(s) must be bound using the GNAT binder. - - 3. All appropriate object files must be linked to produce a loadable - module. - - All three steps are most commonly handled by using the `gnatmake' - utility program that, given the name of the main program, automatically - performs the necessary compilation, binding and linking steps. - -  - File: gnat_ug_vxw.info, Node: Building a Simple Ada Program, Next: Executing a Program on VxWorks, Prev: Running GNAT, Up: Getting Started with GNAT - - Building a Simple Ada Program - ============================= - - Any text editor may be used to prepare an Ada program. If `Glide' is - used, the optional Ada mode may be helpful in laying out the program. - The program text is a normal text file. We will suppose in our initial - example that you have used your editor to prepare the following - standard format text file: - - with Ada.Text_IO; use Ada.Text_IO; - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - This file should be named `hello.adb'. With the normal default file - naming conventions, GNAT requires that each file contain a single - compilation unit whose file name is the unit name, with periods - replaced by hyphens; the extension is `ads' for a spec and `adb' for a - body. You can override this default file naming convention by use of - the special pragma `Source_File_Name' (*note Using Other File Names::). - Alternatively, if you want to rename your files according to this - default convention, which is probably more convenient if you will be - using GNAT for all your compilations, then the `gnatchop' utility can - be used to generate correctly-named source files (*note Renaming Files - Using gnatchop::). - - You can compile the program using the following command (`$' is used - as the command prompt in the examples in this document): - - $ target-gcc -c hello.adb - - `gcc' is the command used to run the compiler. This compiler is capable - of compiling programs in several languages, including Ada 95 and C. It - assumes that you have given it an Ada program if the file extension is - either `.ads' or `.adb', and it will then call the GNAT compiler to - compile the specified file. - - The `-c' switch is required. It tells `gcc' to only do a - compilation. (For C programs, `gcc' can also do linking, but this - capability is not used directly for Ada programs, so the `-c' switch - must always be present.) - - This compile command generates a file `hello.o', which is the object - file corresponding to your Ada program. It also generates an "Ada - Library Information" file `hello.ali', which contains additional - information used to check that an Ada program is consistent. To build - a downloadable module, use `gnatbind' to bind the program and - `gnatlink' to link it. The argument to both `gnatbind' and `gnatlink' - is the name of the `ali' file, but the default extension of `.ali' can - be omitted. This means that in the most common case, the argument is - simply the name of the main program: - - $ target-gnatbind hello - $ target-gnatlink hello - - A simpler method of carrying out these steps is to use `gnatmake', a - master program that invokes all the required compilation, binding and - linking tools in the correct order. In particular, `gnatmake' - automatically recompiles any sources that have been modified since they - were last compiled, or sources that depend on such modified sources, so - that "version skew" is avoided. - - $ target-gnatmake hello.adb - - The result is a relocatable object called `hello'. - - _Technical note:_ the result of the linking stage is a relocatable - partially-linked object containing all the relevant GNAT run-time - units, in contrast with the executable-format object file found in - native environments. - -  - File: gnat_ug_vxw.info, Node: Executing a Program on VxWorks, Next: Running a Program with Multiple Units, Prev: Building a Simple Ada Program, Up: Getting Started with GNAT - - Executing a Program on VxWorks - ============================== - - Getting a program to execute involves loading it onto the target, - running it, and then (if re-execution is needed) unloading it. - - * Menu: - - * Loading and Running the Program:: - * Unloading the Program:: - -  - File: gnat_ug_vxw.info, Node: Loading and Running the Program, Next: Unloading the Program, Up: Executing a Program on VxWorks - - Loading and Running the Program - ------------------------------- - - An Ada program is loaded and run in the same way as a C program. - Details may be found in the `Tornado User's Guide'. - - In order to load and run our simple "Hello World" example, we assume - that the target has access to the disk of the host containing this - object and that its working directory has been set to the directory - containing this object. The commands are typed in Tornado's Windshell. - The `windsh' prompt is the `->' sequence. - - -> vf0=open("/vio/0",2,0) - new symbol "vf0" added to symbol table. - vf0 = 0x2cab48: value = 12 = 0xc - -> ioGlobalStdSet(1,vf0) - value = 1 = 0x1 - -> ld < hello - value = 665408 = 0xa2740 - -> hello - Hello World - value = 0 = 0x0 - -> - - The first two commands redirect output to the shell window. They are - only needed if the target server was started without the `-C' option. - The third command loads the module, which is the file `hello' created - previously by the `target-gnatmake' command. Note that for Tornado AE, - the `ml' command replaces `ld'." - - The "Hello World" program comprises a procedure named `hello', and - this is the name entered for the procedure in the target server's - symbol table when the module is loaded. To execute the procedure, type - the symbol name `hello' into `windsh' as shown in the last command - above. - - Note that by default the entry point of an Ada program is the name - of the main Ada subprogram in a VxWorks environment. It is possible to - use an alternative name; see the description of `gnatbind' options for - details. - -  - File: gnat_ug_vxw.info, Node: Unloading the Program, Prev: Loading and Running the Program, Up: Executing a Program on VxWorks - - Unloading the Program - --------------------- - - It is important to remember that you must unload a program once you - have run it. You cannot load it once and run it several times. If you - don't follow this rule, your program's behavior can be unpredictable, - and will most probably crash. - - This effect is due to the implementation of Ada 95's _elaboration_ - semantics. The unit elaboration phase comprises a _static_ elaboration - and a _dynamic_ elaboration. On a native platform they both take place - when the program is run. Thus rerunning the program will repeat the - complete elaboration phase, and the program will run correctly. - - On VxWorks, the process is a bit different. The static elaboration - phase is handled by the loader (typically when you type `ld < - program_name' in `windsh'). The dynamic phase takes place when the - program is run. If the program is run twice and has not been unloaded - and then reloaded, the second time it is run, the static elaboration - phase is skipped. Variables initialized during the static elaboration - phase may have been modified during the first execution of the program. - Thus the second execution isn't performed on a completely initialized - environment. - - Note that in C programs, elaboration isn't systematic. Multiple runs - without reload might work, but, even with C programs, if there is an - elaboration phase, you will have to unload your program before - re-running it. - -  - File: gnat_ug_vxw.info, Node: Running a Program with Multiple Units, Next: Using the gnatmake Utility, Prev: Executing a Program on VxWorks, Up: Getting Started with GNAT - - Running a Program with Multiple Units - ===================================== - - Consider a slightly more complicated example that has three files: a - main program, and the spec and body of a package: - - package Greetings is - procedure Hello; - procedure Goodbye; - end Greetings; - - with Ada.Text_IO; use Ada.Text_IO; - package body Greetings is - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - procedure Goodbye is - begin - Put_Line ("Goodbye WORLD!"); - end Goodbye; - end Greetings; - - with Greetings; - procedure Gmain is - begin - Greetings.Hello; - Greetings.Goodbye; - end Gmain; - - Following the one-unit-per-file rule, place this program in the - following three separate files: - - `greetings.ads' - spec of package `Greetings' - - `greetings.adb' - body of package `Greetings' - - `gmain.adb' - body of main program - - To build an executable version of this program, we could use four - separate steps to compile, bind, and link the program, as follows: - - $ target-gcc -c gmain.adb - $ target-gcc -c greetings.adb - $ target-gnatbind gmain - $ target-gnatlink gmain - - Note that there is no required order of compilation when using GNAT. - In particular it is perfectly fine to compile the main program first. - Also, it is not necessary to compile package specs in the case where - there is an accompanying body; you only need to compile the body. If - you want to submit these files to the compiler for semantic checking - and not code generation, then use the `-gnatc' switch: - - $ target-gcc -c greetings.ads -gnatc - - Although the compilation can be done in separate steps as in the above - example, in practice it is almost always more convenient to use the - `gnatmake' tool. All you need to know in this case is the name of the - main program's source file. The effect of the above four commands can - be achieved with a single one: - - $ target-gnatmake gmain.adb - - In the next section we discuss the advantages of using `gnatmake' in - more detail. - -  - File: gnat_ug_vxw.info, Node: Using the gnatmake Utility, Next: Introduction to Glide and GVD, Prev: Running a Program with Multiple Units, Up: Getting Started with GNAT - - Using the `gnatmake' Utility - ============================ - - If you work on a program by compiling single components at a time using - `gcc', you typically keep track of the units you modify. In order to - build a consistent system, you compile not only these units, but also - any units that depend on the units you have modified. For example, in - the preceding case, if you edit `gmain.adb', you only need to recompile - that file. But if you edit `greetings.ads', you must recompile both - `greetings.adb' and `gmain.adb', because both files contain units that - depend on `greetings.ads'. - - `gnatbind' will warn you if you forget one of these compilation - steps, so that it is impossible to generate an inconsistent program as a - result of forgetting to do a compilation. Nevertheless it is tedious and - error-prone to keep track of dependencies among units. One approach to - handle the dependency-bookkeeping is to use a makefile. However, - makefiles present maintenance problems of their own: if the - dependencies change as you change the program, you must make sure that - the makefile is kept up-to-date manually, which is also an error-prone - process. - - The `gnatmake' utility takes care of these details automatically. - Invoke it using either one of the following forms: - - $ target-gnatmake gmain.adb - $ target-gnatmake gmain - - The argument is the name of the file containing the main program; you - may omit the extension. `gnatmake' examines the environment, - automatically recompiles any files that need recompiling, and binds and - links the resulting set of object files, generating the executable - file, `gmain'. In a large program, it can be extremely helpful to use - `gnatmake', because working out by hand what needs to be recompiled can - be difficult. - - Note that `gnatmake' takes into account all the Ada 95 rules that - establish dependencies among units. These include dependencies that - result from inlining subprogram bodies, and from generic instantiation. - Unlike some other Ada make tools, `gnatmake' does not rely on the - dependencies that were found by the compiler on a previous compilation, - which may possibly be wrong when sources change. `gnatmake' determines - the exact set of dependencies from scratch each time it is run. - -  - File: gnat_ug_vxw.info, Node: Introduction to Glide and GVD, Prev: Using the gnatmake Utility, Up: Getting Started with GNAT - - Introduction to Glide and GVD - ============================= - - Although it is possible to develop programs using only the command line - interface (`gnatmake', etc.) a graphical Interactive Development - Environment can make it easier for you to compose, navigate, and debug - programs. This section describes the main features of Glide, the GNAT - graphical IDE, and also shows how to use the basic commands in GVD, the - GNU Visual Debugger. Additional information may be found in the - on-line help for these tools. - - * Menu: - - * Building a New Program with Glide:: - * Simple Debugging with GVD:: - * Other Glide Features:: - -  - File: gnat_ug_vxw.info, Node: Building a New Program with Glide, Next: Simple Debugging with GVD, Up: Introduction to Glide and GVD - - Building a New Program with Glide - --------------------------------- - - The simplest way to invoke Glide is to enter `glide' at the command - prompt. It will generally be useful to issue this as a background - command, thus allowing you to continue using your command window for - other purposes while Glide is running: - - $ glide& - - Glide will start up with an initial screen displaying the top-level - menu items as well as some other information. The menu selections are - as follows - * `Buffers' - - * `Files' - - * `Tools' - - * `Edit' - - * `Search' - - * `Mule' - - * `Glide' - - * `Help' - - For this introductory example, you will need to create a new Ada source - file. First, select the `Files' menu. This will pop open a menu with - around a dozen or so items. To create a file, select the `Open - file...' choice. Depending on the platform, you may see a pop-up - window where you can browse to an appropriate directory and then enter - the file name, or else simply see a line at the bottom of the Glide - window where you can likewise enter the file name. Note that in Glide, - when you attempt to open a non-existent file, the effect is to create a - file with that name. For this example enter `hello.adb' as the name of - the file. - - A new buffer will now appear, occupying the entire Glide window, - with the file name at the top. The menu selections are slightly - different from the ones you saw on the opening screen; there is an - `Entities' item, and in place of `Glide' there is now an `Ada' item. - Glide uses the file extension to identify the source language, so `adb' - indicates an Ada source file. - - You will enter some of the source program lines explicitly, and use - the syntax-oriented template mechanism to enter other lines. First, - type the following text: - with Ada.Text_IO; use Ada.Text_IO; - procedure Hello is - begin - - Observe that Glide uses different colors to distinguish reserved words - from identifiers. Also, after the `procedure Hello is' line, the - cursor is automatically indented in anticipation of declarations. When - you enter `begin', Glide recognizes that there are no declarations and - thus places `begin' flush left. But after the `begin' line the cursor - is again indented, where the statement(s) will be placed. - - The main part of the program will be a `for' loop. Instead of - entering the text explicitly, however, use a statement template. - Select the `Ada' item on the top menu bar, move the mouse to the - `Statements' item, and you will see a large selection of alternatives. - Choose `for loop'. You will be prompted (at the bottom of the buffer) - for a loop name; simply press the key since a loop name is not - needed. You should see the beginning of a `for' loop appear in the - source program window. You will now be prompted for the name of the - loop variable; enter a line with the identifier `ind' (lower case). - Note that, by default, Glide capitalizes the name (you can override - such behavior if you wish, although this is outside the scope of this - introduction). Next, Glide prompts you for the loop range; enter a - line containing `1..5' and you will see this also appear in the source - program, together with the remaining elements of the `for' loop syntax. - - Next enter the statement (with an intentional error, a missing - semicolon) that will form the body of the loop: - Put_Line("Hello, World" & Integer'Image(I)) - - Finally, type `end Hello;' as the last line in the program. Now save - the file: choose the `File' menu item, and then the `Save buffer' - selection. You will see a message at the bottom of the buffer - confirming that the file has been saved. - - You are now ready to attempt to build the program. Select the `Ada' - item from the top menu bar. Although we could choose simply to compile - the file, we will instead attempt to do a build (which invokes - `gnatmake') since, if the compile is successful, we want to build an - executable. Thus select `Ada build'. This will fail because of the - compilation error, and you will notice that the Glide window has been - split: the top window contains the source file, and the bottom window - contains the output from the GNAT tools. Glide allows you to navigate - from a compilation error to the source file position corresponding to - the error: click the middle mouse button (or simultaneously press the - left and right buttons, on a two-button mouse) on the diagnostic line - in the tool window. The focus will shift to the source window, and the - cursor will be positioned on the character at which the error was - detected. - - Correct the error: type in a semicolon to terminate the statement. - Although you can again save the file explicitly, you can also simply - invoke `Ada' => `Build' and you will be prompted to save the file. - This time the build will succeed; the tool output window shows you the - options that are supplied by default. The GNAT tools' output (e.g., - object and ALI files, executable) will go in the directory from which - Glide was launched. - - To execute the program, choose `Ada' and then `Run'. You should see - the program's output displayed in the bottom window: - - Hello, world 1 - Hello, world 2 - Hello, world 3 - Hello, world 4 - Hello, world 5 - -  - File: gnat_ug_vxw.info, Node: Simple Debugging with GVD, Next: Other Glide Features, Prev: Building a New Program with Glide, Up: Introduction to Glide and GVD - - Simple Debugging with GVD - ------------------------- - - This section describes how to set breakpoints, examine/modify - variables, and step through execution. - - In order to enable debugging, you need to pass the `-g' switch to - both the compiler and to `gnatlink'. If you are using the command - line, passing `-g' to `gnatmake' will have this effect. You can then - launch GVD, e.g. on the `hello' program, by issuing the command: - - $ gvd hello - - If you are using Glide, then `-g' is passed to the relevant tools by - default when you do a build. Start the debugger by selecting the `Ada' - menu item, and then `Debug'. - - GVD comes up in a multi-part window. One pane shows the names of - files comprising your executable; another pane shows the source code of - the current unit (initially your main subprogram), another pane shows - the debugger output and user interactions, and the fourth pane (the - data canvas at the top of the window) displays data objects that you - have selected. - - To the left of the source file pane, you will notice green dots - adjacent to some lines. These are lines for which object code exists - and where breakpoints can thus be set. You set/reset a breakpoint by - clicking the green dot. When a breakpoint is set, the dot is replaced - by an `X' in a red circle. Clicking the circle toggles the breakpoint - off, and the red circle is replaced by the green dot. - - For this example, set a breakpoint at the statement where `Put_Line' - is invoked. - - Start program execution by selecting the `Run' button on the top - menu bar. (The `Start' button will also start your program, but it - will cause program execution to break at the entry to your main - subprogram.) Evidence of reaching the breakpoint will appear: the - source file line will be highlighted, and the debugger interactions - pane will display a relevant message. - - You can examine the values of variables in several ways. Move the - mouse over an occurrence of `Ind' in the `for' loop, and you will see - the value (now `1') displayed. Alternatively, right-click on `Ind' and - select `Display Ind'; a box showing the variable's name and value will - appear in the data canvas. - - Although a loop index is a constant with respect to Ada semantics, - you can change its value in the debugger. Right-click in the box for - `Ind', and select the `Set Value of Ind' item. Enter `2' as the new - value, and press `OK'. The box for `Ind' shows the update. - - Press the `Step' button on the top menu bar; this will step through - one line of program text (the invocation of `Put_Line'), and you can - observe the effect of having modified `Ind' since the value displayed - is `2'. - - Remove the breakpoint, and resume execution by selecting the `Cont' - button. You will see the remaining output lines displayed in the - debugger interaction window, along with a message confirming normal - program termination. - -  - File: gnat_ug_vxw.info, Node: Other Glide Features, Prev: Simple Debugging with GVD, Up: Introduction to Glide and GVD - - Other Glide Features - -------------------- - - You may have observed that some of the menu selections contain - abbreviations; e.g., `(C-x C-f)' for `Open file...' in the `Files' - menu. These are _shortcut keys_ that you can use instead of selecting - menu items. The stands for ; thus `(C-x C-f)' means - followed by , and this sequence can be used instead of - selecting `Files' and then `Open file...'. - - To abort a Glide command, type . - - If you want Glide to start with an existing source file, you can - either launch Glide as above and then open the file via `Files' => - `Open file...', or else simply pass the name of the source file on the - command line: - - $ glide hello.adb& - - While you are using Glide, a number of _buffers_ exist. You create - some explicitly; e.g., when you open/create a file. Others arise as an - effect of the commands that you issue; e.g., the buffer containing the - output of the tools invoked during a build. If a buffer is hidden, you - can bring it into a visible window by first opening the `Buffers' menu - and then selecting the desired entry. - - If a buffer occupies only part of the Glide screen and you want to - expand it to fill the entire screen, then click in the buffer and then - select `Files' => `One Window'. - - If a window is occupied by one buffer and you want to split the - window to bring up a second buffer, perform the following steps: - * Select `Files' => `Split Window'; this will produce two windows - each of which holds the original buffer (these are not copies, but - rather different views of the same buffer contents) - - * With the focus in one of the windows, select the desired buffer - from the `Buffers' menu - - To exit from Glide, choose `Files' => `Exit'. - -  - File: gnat_ug_vxw.info, Node: The GNAT Compilation Model, Next: Compiling Using gcc, Prev: Getting Started with GNAT, Up: Top - - The GNAT Compilation Model - ************************** - - * Menu: - - * Source Representation:: - * Foreign Language Representation:: - * File Naming Rules:: - * Using Other File Names:: - * Alternative File Naming Schemes:: - * Generating Object Files:: - * Source Dependencies:: - * The Ada Library Information Files:: - * Binding an Ada Program:: - * Mixed Language Programming:: - * Building Mixed Ada & C++ Programs:: - * Comparison between GNAT and C/C++ Compilation Models:: - * Comparison between GNAT and Conventional Ada Library Models:: - - This chapter describes the compilation model used by GNAT. Although - similar to that used by other languages, such as C and C++, this model - is substantially different from the traditional Ada compilation models, - which are based on a library. The model is initially described without - reference to the library-based model. If you have not previously used an - Ada compiler, you need only read the first part of this chapter. The - last section describes and discusses the differences between the GNAT - model and the traditional Ada compiler models. If you have used other - Ada compilers, this section will help you to understand those - differences, and the advantages of the GNAT model. - -  - File: gnat_ug_vxw.info, Node: Source Representation, Next: Foreign Language Representation, Up: The GNAT Compilation Model - - Source Representation - ===================== - - Ada source programs are represented in standard text files, using - Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar - 7-bit ASCII set, plus additional characters used for representing - foreign languages (*note Foreign Language Representation:: for support - of non-USA character sets). The format effector characters are - represented using their standard ASCII encodings, as follows: - - `VT' - Vertical tab, `16#0B#' - - `HT' - Horizontal tab, `16#09#' - - `CR' - Carriage return, `16#0D#' - - `LF' - Line feed, `16#0A#' - - `FF' - Form feed, `16#0C#' - - Source files are in standard text file format. In addition, GNAT will - recognize a wide variety of stream formats, in which the end of physical - physical lines is marked by any of the following sequences: `LF', `CR', - `CR-LF', or `LF-CR'. This is useful in accommodating files that are - imported from other operating systems. - - The end of a source file is normally represented by the physical end - of file. However, the control character `16#1A#' (`SUB') is also - recognized as signalling the end of the source file. Again, this is - provided for compatibility with other operating systems where this code - is used to represent the end of file. - - Each file contains a single Ada compilation unit, including any - pragmas associated with the unit. For example, this means you must - place a package declaration (a package "spec") and the corresponding - body in separate files. An Ada "compilation" (which is a sequence of - compilation units) is represented using a sequence of files. Similarly, - you will place each subunit or child unit in a separate file. - -  - File: gnat_ug_vxw.info, Node: Foreign Language Representation, Next: File Naming Rules, Prev: Source Representation, Up: The GNAT Compilation Model - - Foreign Language Representation - =============================== - - GNAT supports the standard character sets defined in Ada 95 as well as - several other non-standard character sets for use in localized versions - of the compiler (*note Character Set Control::). - - * Menu: - - * Latin-1:: - * Other 8-Bit Codes:: - * Wide Character Encodings:: - -  - File: gnat_ug_vxw.info, Node: Latin-1, Next: Other 8-Bit Codes, Up: Foreign Language Representation - - Latin-1 - ------- - - The basic character set is Latin-1. This character set is defined by ISO - standard 8859, part 1. The lower half (character codes `16#00#' ... - `16#7F#)' is identical to standard ASCII coding, but the upper half is - used to represent additional characters. These include extended letters - used by European languages, such as French accents, the vowels with - umlauts used in German, and the extra letter A-ring used in Swedish. - - For a complete list of Latin-1 codes and their encodings, see the - source file of library unit `Ada.Characters.Latin_1' in file - `a-chlat1.ads'. You may use any of these extended characters freely in - character or string literals. In addition, the extended characters that - represent letters can be used in identifiers. - -  - File: gnat_ug_vxw.info, Node: Other 8-Bit Codes, Next: Wide Character Encodings, Prev: Latin-1, Up: Foreign Language Representation - - Other 8-Bit Codes - ----------------- - - GNAT also supports several other 8-bit coding schemes: - - Latin-2 - Latin-2 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-3 - Latin-3 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-4 - Latin-4 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-5 - Latin-4 letters (Cyrillic) allowed in identifiers, with uppercase - and lowercase equivalence. - - IBM PC (code page 437) - This code page is the normal default for PCs in the U.S. It - corresponds to the original IBM PC character set. This set has - some, but not all, of the extended Latin-1 letters, but these - letters do not have the same encoding as Latin-1. In this mode, - these letters are allowed in identifiers with uppercase and - lowercase equivalence. - - IBM PC (code page 850) - This code page is a modification of 437 extended to include all the - Latin-1 letters, but still not with the usual Latin-1 encoding. In - this mode, all these letters are allowed in identifiers with - uppercase and lowercase equivalence. - - Full Upper 8-bit - Any character in the range 80-FF allowed in identifiers, and all - are considered distinct. In other words, there are no uppercase - and lowercase equivalences in this range. This is useful in - conjunction with certain encoding schemes used for some foreign - character sets (e.g. the typical method of representing Chinese - characters on the PC). - - No Upper-Half - No upper-half characters in the range 80-FF are allowed in - identifiers. This gives Ada 83 compatibility for identifier names. - - For precise data on the encodings permitted, and the uppercase and - lowercase equivalences that are recognized, see the file `csets.adb' in - the GNAT compiler sources. You will need to obtain a full source release - of GNAT to obtain this file. - -  - File: gnat_ug_vxw.info, Node: Wide Character Encodings, Prev: Other 8-Bit Codes, Up: Foreign Language Representation - - Wide Character Encodings - ------------------------ - - GNAT allows wide character codes to appear in character and string - literals, and also optionally in identifiers, by means of the following - possible encoding schemes: - - Hex Coding - In this encoding, a wide character is represented by the following - five character sequence: - - ESC a b c d - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For example, - ESC A345 is used to represent the wide character with code - `16#A345#'. This scheme is compatible with use of the full - Wide_Character set. - - Upper-Half Coding - The wide character with encoding `16#abcd#' where the upper bit is - on (in other words, "a" is in the range 8-F) is represented as two - bytes, `16#ab#' and `16#cd#'. The second byte cannot be a format - control character, but is not required to be in the upper half. - This method can be also used for shift-JIS or EUC, where the - internal coding matches the external coding. - - Shift JIS Coding - A wide character is represented by a two-character sequence, - `16#ab#' and `16#cd#', with the restrictions described for - upper-half encoding as described above. The internal character - code is the corresponding JIS character according to the standard - algorithm for Shift-JIS conversion. Only characters defined in the - JIS code set table can be used with this encoding method. - - EUC Coding - A wide character is represented by a two-character sequence - `16#ab#' and `16#cd#', with both characters being in the upper - half. The internal character code is the corresponding JIS - character according to the EUC encoding algorithm. Only characters - defined in the JIS code set table can be used with this encoding - method. - - UTF-8 Coding - A wide character is represented using UCS Transformation Format 8 - (UTF-8) as defined in Annex R of ISO 10646-1/Am.2. Depending on - the character value, the representation is a one, two, or three - byte sequence: - 16#0000#-16#007f#: 2#0xxxxxxx# - 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# - 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# - - where the xxx bits correspond to the left-padded bits of the - 16-bit character value. Note that all lower half ASCII characters - are represented as ASCII bytes and all upper half characters and - other wide characters are represented as sequences of upper-half - (The full UTF-8 scheme allows for encoding 31-bit characters as - 6-byte sequences, but in this implementation, all UTF-8 sequences - of four or more bytes length will be treated as illegal). - - Brackets Coding - In this encoding, a wide character is represented by the following - eight character sequence: - - [ " a b c d " ] - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For example, - ["A345"] is used to represent the wide character with code - `16#A345#'. It is also possible (though not required) to use the - Brackets coding for upper half characters. For example, the code - `16#A3#' can be represented as `["A3"]'. - - This scheme is compatible with use of the full Wide_Character set, - and is also the method used for wide character encoding in the - standard ACVC (Ada Compiler Validation Capability) test suite - distributions. - - Note: Some of these coding schemes do not permit the full use of the - Ada 95 character set. For example, neither Shift JIS, nor EUC allow the - use of the upper half of the Latin-1 set. - -  - File: gnat_ug_vxw.info, Node: File Naming Rules, Next: Using Other File Names, Prev: Foreign Language Representation, Up: The GNAT Compilation Model - - File Naming Rules - ================= - - The default file name is determined by the name of the unit that the - file contains. The name is formed by taking the full expanded name of - the unit and replacing the separating dots with hyphens and using - lowercase for all letters. - - An exception arises if the file name generated by the above rules - starts with one of the characters a,g,i, or s, and the second character - is a minus. In this case, the character tilde is used in place of the - minus. The reason for this special rule is to avoid clashes with the - standard names for child units of the packages System, Ada, Interfaces, - and GNAT, which use the prefixes s- a- i- and g- respectively. - - The file extension is `.ads' for a spec and `.adb' for a body. The - following list shows some examples of these rules. - - `main.ads' - Main (spec) - - `main.adb' - Main (body) - - `arith_functions.ads' - Arith_Functions (package spec) - - `arith_functions.adb' - Arith_Functions (package body) - - `func-spec.ads' - Func.Spec (child package spec) - - `func-spec.adb' - Func.Spec (child package body) - - `main-sub.adb' - Sub (subunit of Main) - - `a~bad.adb' - A.Bad (child package body) - - Following these rules can result in excessively long file names if - corresponding unit names are long (for example, if child units or - subunits are heavily nested). An option is available to shorten such - long file names (called file name "krunching"). This may be - particularly useful when programs being developed with GNAT are to be - used on operating systems with limited file name lengths. *Note Using - gnatkr::. - - Of course, no file shortening algorithm can guarantee uniqueness over - all possible unit names; if file name krunching is used, it is your - responsibility to ensure no name clashes occur. Alternatively you can - specify the exact file names that you want used, as described in the - next section. Finally, if your Ada programs are migrating from a - compiler with a different naming convention, you can use the gnatchop - utility to produce source files that follow the GNAT naming conventions. - (For details *note Renaming Files Using gnatchop::.) - -  - File: gnat_ug_vxw.info, Node: Using Other File Names, Next: Alternative File Naming Schemes, Prev: File Naming Rules, Up: The GNAT Compilation Model - - Using Other File Names - ====================== - - In the previous section, we have described the default rules used by - GNAT to determine the file name in which a given unit resides. It is - often convenient to follow these default rules, and if you follow them, - the compiler knows without being explicitly told where to find all the - files it needs. - - However, in some cases, particularly when a program is imported from - another Ada compiler environment, it may be more convenient for the - programmer to specify which file names contain which units. GNAT allows - arbitrary file names to be used by means of the Source_File_Name pragma. - The form of this pragma is as shown in the following examples: - - pragma Source_File_Name (My_Utilities.Stacks, - Spec_File_Name => "myutilst_a.ada"); - pragma Source_File_name (My_Utilities.Stacks, - Body_File_Name => "myutilst.ada"); - - As shown in this example, the first argument for the pragma is the unit - name (in this example a child unit). The second argument has the form - of a named association. The identifier indicates whether the file name - is for a spec or a body; the file name itself is given by a string - literal. - - The source file name pragma is a configuration pragma, which means - that normally it will be placed in the `gnat.adc' file used to hold - configuration pragmas that apply to a complete compilation environment. - For more details on how the `gnat.adc' file is created and used *note - Handling of Configuration Pragmas:: - - GNAT allows completely arbitrary file names to be specified using the - source file name pragma. However, if the file name specified has an - extension other than `.ads' or `.adb' it is necessary to use a special - syntax when compiling the file. The name in this case must be preceded - by the special sequence `-x' followed by a space and the name of the - language, here `ada', as in: - - $ gcc -c -x ada peculiar_file_name.sim - - `gnatmake' handles non-standard file names in the usual manner (the - non-standard file name for the main program is simply used as the - argument to gnatmake). Note that if the extension is also non-standard, - then it must be included in the gnatmake command, it may not be omitted. - -  - File: gnat_ug_vxw.info, Node: Alternative File Naming Schemes, Next: Generating Object Files, Prev: Using Other File Names, Up: The GNAT Compilation Model - - Alternative File Naming Schemes - =============================== - - In the previous section, we described the use of the - `Source_File_Name' pragma to allow arbitrary names to be assigned to - individual source files. However, this approach requires one pragma - for each file, and especially in large systems can result in very long - `gnat.adc' files, and also create a maintenance problem. - - GNAT also provides a facility for specifying systematic file naming - schemes other than the standard default naming scheme previously - described. An alternative scheme for naming is specified by the use of - `Source_File_Name' pragmas having the following format: - - pragma Source_File_Name ( - Spec_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name ( - Body_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name ( - Subunit_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - FILE_NAME_PATTERN ::= STRING_LITERAL - CASING_SPEC ::= Lowercase | Uppercase | Mixedcase - - The `FILE_NAME_PATTERN' string shows how the file name is constructed. - It contains a single asterisk character, and the unit name is - substituted systematically for this asterisk. The optional parameter - `Casing' indicates whether the unit name is to be all upper-case - letters, all lower-case letters, or mixed-case. If no `Casing' - parameter is used, then the default is all lower-case. - - The optional `Dot_Replacement' string is used to replace any periods - that occur in subunit or child unit names. If no `Dot_Replacement' - argument is used then separating dots appear unchanged in the resulting - file name. Although the above syntax indicates that the `Casing' - argument must appear before the `Dot_Replacement' argument, but it is - also permissible to write these arguments in the opposite order. - - As indicated, it is possible to specify different naming schemes for - bodies, specs, and subunits. Quite often the rule for subunits is the - same as the rule for bodies, in which case, there is no need to give a - separate `Subunit_File_Name' rule, and in this case the - `Body_File_name' rule is used for subunits as well. - - The separate rule for subunits can also be used to implement the - rather unusual case of a compilation environment (e.g. a single - directory) which contains a subunit and a child unit with the same unit - name. Although both units cannot appear in the same partition, the Ada - Reference Manual allows (but does not require) the possibility of the - two units coexisting in the same environment. - - The file name translation works in the following steps: - - * If there is a specific `Source_File_Name' pragma for the given - unit, then this is always used, and any general pattern rules are - ignored. - - * If there is a pattern type `Source_File_Name' pragma that applies - to the unit, then the resulting file name will be used if the file - exists. If more than one pattern matches, the latest one will be - tried first, and the first attempt resulting in a reference to a - file that exists will be used. - - * If no pattern type `Source_File_Name' pragma that applies to the - unit for which the corresponding file exists, then the standard - GNAT default naming rules are used. - - - As an example of the use of this mechanism, consider a commonly used - scheme in which file names are all lower case, with separating periods - copied unchanged to the resulting file name, and specs end with - ".1.ada", and bodies end with ".2.ada". GNAT will follow this scheme if - the following two pragmas appear: - - pragma Source_File_Name - (Spec_File_Name => "*.1.ada"); - pragma Source_File_Name - (Body_File_Name => "*.2.ada"); - - The default GNAT scheme is actually implemented by providing the - following default pragmas internally: - - pragma Source_File_Name - (Spec_File_Name => "*.ads", Dot_Replacement => "-"); - pragma Source_File_Name - (Body_File_Name => "*.adb", Dot_Replacement => "-"); - - Our final example implements a scheme typically used with one of the - Ada 83 compilers, where the separator character for subunits was "__" - (two underscores), specs were identified by adding `_.ADA', bodies by - adding `.ADA', and subunits by adding `.SEP'. All file names were upper - case. Child units were not present of course since this was an Ada 83 - compiler, but it seems reasonable to extend this scheme to use the same - double underscore separator for child units. - - pragma Source_File_Name - (Spec_File_Name => "*_.ADA", - Dot_Replacement => "__", - Casing = Uppercase); - pragma Source_File_Name - (Body_File_Name => "*.ADA", - Dot_Replacement => "__", - Casing = Uppercase); - pragma Source_File_Name - (Subunit_File_Name => "*.SEP", - Dot_Replacement => "__", - Casing = Uppercase); - -  - File: gnat_ug_vxw.info, Node: Generating Object Files, Next: Source Dependencies, Prev: Alternative File Naming Schemes, Up: The GNAT Compilation Model - - Generating Object Files - ======================= - - An Ada program consists of a set of source files, and the first step in - compiling the program is to generate the corresponding object files. - These are generated by compiling a subset of these source files. The - files you need to compile are the following: - - * If a package spec has no body, compile the package spec to produce - the object file for the package. - - * If a package has both a spec and a body, compile the body to - produce the object file for the package. The source file for the - package spec need not be compiled in this case because there is - only one object file, which contains the code for both the spec - and body of the package. - - * For a subprogram, compile the subprogram body to produce the - object file for the subprogram. The spec, if one is present, is as - usual in a separate file, and need not be compiled. - - * In the case of subunits, only compile the parent unit. A single - object file is generated for the entire subunit tree, which - includes all the subunits. - - * Compile child units independently of their parent units (though, - of course, the spec of all the ancestor unit must be present in - order to compile a child unit). - - * Compile generic units in the same manner as any other units. The - object files in this case are small dummy files that contain at - most the flag used for elaboration checking. This is because GNAT - always handles generic instantiation by means of macro expansion. - However, it is still necessary to compile generic units, for - dependency checking and elaboration purposes. - - The preceding rules describe the set of files that must be compiled to - generate the object files for a program. Each object file has the same - name as the corresponding source file, except that the extension is - `.o' as usual. - - You may wish to compile other files for the purpose of checking their - syntactic and semantic correctness. For example, in the case where a - package has a separate spec and body, you would not normally compile the - spec. However, it is convenient in practice to compile the spec to make - sure it is error-free before compiling clients of this spec, because - such compilations will fail if there is an error in the spec. - - GNAT provides an option for compiling such files purely for the - purposes of checking correctness; such compilations are not required as - part of the process of building a program. To compile a file in this - checking mode, use the `-gnatc' switch. - -  - File: gnat_ug_vxw.info, Node: Source Dependencies, Next: The Ada Library Information Files, Prev: Generating Object Files, Up: The GNAT Compilation Model - - Source Dependencies - =================== - - A given object file clearly depends on the source file which is compiled - to produce it. Here we are using "depends" in the sense of a typical - `make' utility; in other words, an object file depends on a source file - if changes to the source file require the object file to be recompiled. - In addition to this basic dependency, a given object may depend on - additional source files as follows: - - * If a file being compiled `with''s a unit X, the object file - depends on the file containing the spec of unit X. This includes - files that are `with''ed implicitly either because they are parents - of `with''ed child units or they are run-time units required by the - language constructs used in a particular unit. - - * If a file being compiled instantiates a library level generic - unit, the object file depends on both the spec and body files for - this generic unit. - - * If a file being compiled instantiates a generic unit defined - within a package, the object file depends on the body file for the - package as well as the spec file. - - * If a file being compiled contains a call to a subprogram for which - pragma `Inline' applies and inlining is activated with the - `-gnatn' switch, the object file depends on the file containing the - body of this subprogram as well as on the file containing the - spec. Note that for inlining to actually occur as a result of the - use of this switch, it is necessary to compile in optimizing mode. - - The use of `-gnatN' activates a more extensive inlining - optimization that is performed by the front end of the compiler. - This inlining does not require that the code generation be - optimized. Like `-gnatn', the use of this switch generates - additional dependencies. - - * If an object file O depends on the proper body of a subunit - through inlining or instantiation, it depends on the parent unit - of the subunit. This means that any modification of the parent - unit or one of its subunits affects the compilation of O. - - * The object file for a parent unit depends on all its subunit body - files. - - * The previous two rules meant that for purposes of computing - dependencies and recompilation, a body and all its subunits are - treated as an indivisible whole. - - These rules are applied transitively: if unit `A' `with''s unit - `B', whose elaboration calls an inlined procedure in package `C', - the object file for unit `A' will depend on the body of `C', in - file `c.adb'. - - The set of dependent files described by these rules includes all - the files on which the unit is semantically dependent, as - described in the Ada 95 Language Reference Manual. However, it is - a superset of what the ARM describes, because it includes generic, - inline, and subunit dependencies. - - An object file must be recreated by recompiling the corresponding - source file if any of the source files on which it depends are - modified. For example, if the `make' utility is used to control - compilation, the rule for an Ada object file must mention all the - source files on which the object file depends, according to the - above definition. The determination of the necessary - recompilations is done automatically when one uses `gnatmake'. - -  - File: gnat_ug_vxw.info, Node: The Ada Library Information Files, Next: Binding an Ada Program, Prev: Source Dependencies, Up: The GNAT Compilation Model - - The Ada Library Information Files - ================================= - - Each compilation actually generates two output files. The first of these - is the normal object file that has a `.o' extension. The second is a - text file containing full dependency information. It has the same name - as the source file, but an `.ali' extension. This file is known as the - Ada Library Information (`ali') file. The following information is - contained in the `ali' file. - - * Version information (indicates which version of GNAT was used to - compile the unit(s) in question) - - * Main program information (including priority and time slice - settings, as well as the wide character encoding used during - compilation). - - * List of arguments used in the `gcc' command for the compilation - - * Attributes of the unit, including configuration pragmas used, an - indication of whether the compilation was successful, exception - model used etc. - - * A list of relevant restrictions applying to the unit (used for - consistency) checking. - - * Categorization information (e.g. use of pragma `Pure'). - - * Information on all `with''ed units, including presence of - `Elaborate' or `Elaborate_All' pragmas. - - * Information from any `Linker_Options' pragmas used in the unit - - * Information on the use of `Body_Version' or `Version' attributes - in the unit. - - * Dependency information. This is a list of files, together with - time stamp and checksum information. These are files on which the - unit depends in the sense that recompilation is required if any of - these units are modified. - - * Cross-reference data. Contains information on all entities - referenced in the unit. Used by tools like `gnatxref' and - `gnatfind' to provide cross-reference information. - - - For a full detailed description of the format of the `ali' file, see - the source of the body of unit `Lib.Writ', contained in file - `lib-writ.adb' in the GNAT compiler sources. - -  - File: gnat_ug_vxw.info, Node: Binding an Ada Program, Next: Mixed Language Programming, Prev: The Ada Library Information Files, Up: The GNAT Compilation Model - - Binding an Ada Program - ====================== - - When using languages such as C and C++, once the source files have been - compiled the only remaining step in building an executable program is - linking the object modules together. This means that it is possible to - link an inconsistent version of a program, in which two units have - included different versions of the same header. - - The rules of Ada do not permit such an inconsistent program to be - built. For example, if two clients have different versions of the same - package, it is illegal to build a program containing these two clients. - These rules are enforced by the GNAT binder, which also determines an - elaboration order consistent with the Ada rules. - - The GNAT binder is run after all the object files for a program have - been created. It is given the name of the main program unit, and from - this it determines the set of units required by the program, by reading - the corresponding ALI files. It generates error messages if the program - is inconsistent or if no valid order of elaboration exists. - - If no errors are detected, the binder produces a main program, in - Ada by default, that contains calls to the elaboration procedures of - those compilation unit that require them, followed by a call to the - main program. This Ada program is compiled to generate the object file - for the main program. The name of the Ada file is `b~XXX.adb' (with the - corresponding spec `b~XXX.ads') where XXX is the name of the main - program unit. - - Finally, the linker is used to build the resulting executable - program, using the object from the main program from the bind step as - well as the object files for the Ada units of the program. - -  - File: gnat_ug_vxw.info, Node: Mixed Language Programming, Next: Building Mixed Ada & C++ Programs, Prev: Binding an Ada Program, Up: The GNAT Compilation Model - - Mixed Language Programming - ========================== - - * Menu: - - * Interfacing to C:: - * Calling Conventions:: - -  - File: gnat_ug_vxw.info, Node: Interfacing to C, Next: Calling Conventions, Up: Mixed Language Programming - - Interfacing to C - ---------------- - - There are two ways to build a program that contains some Ada files and - some other language files depending on whether the main program is in - Ada or not. If the main program is in Ada, you should proceed as - follows: - - 1. Compile the other language files to generate object files. For - instance: - gcc -c file1.c - gcc -c file2.c - - 2. Compile the Ada units to produce a set of object files and ALI - files. For instance: - gnatmake -c my_main.adb - - 3. Run the Ada binder on the Ada main program. For instance: - gnatbind my_main.ali - - 4. Link the Ada main program, the Ada objects and the other language - objects. For instance: - gnatlink my_main.ali file1.o file2.o - - The three last steps can be grouped in a single command: - gnatmake my_main.adb -largs file1.o file2.o - - If the main program is in some language other than Ada, Then you may - have more than one entry point in the Ada subsystem. You must use a - special option of the binder to generate callable routines to initialize - and finalize the Ada units (*note Binding with Non-Ada Main Programs::). - Calls to the initialization and finalization routines must be inserted - in the main program, or some other appropriate point in the code. The - call to initialize the Ada units must occur before the first Ada - subprogram is called, and the call to finalize the Ada units must occur - after the last Ada subprogram returns. You use the same procedure for - building the program as described previously. In this case, however, - the binder only places the initialization and finalization subprograms - into file `b~XXX.adb' instead of the main program. So, if the main - program is not in Ada, you should proceed as follows: - - 1. Compile the other language files to generate object files. For - instance: - gcc -c file1.c - gcc -c file2.c - - 2. Compile the Ada units to produce a set of object files and ALI - files. For instance: - gnatmake -c entry_point1.adb - gnatmake -c entry_point2.adb - - 3. Run the Ada binder on the Ada main program. For instance: - gnatbind -n entry_point1.ali entry_point2.ali - - 4. Link the Ada main program, the Ada objects and the other language - objects. You only need to give the last entry point here. For - instance: - gnatlink entry_point2.ali file1.o file2.o - -  - File: gnat_ug_vxw.info, Node: Calling Conventions, Prev: Interfacing to C, Up: Mixed Language Programming - - Calling Conventions - ------------------- - - GNAT follows standard calling sequence conventions and will thus - interface to any other language that also follows these conventions. - The following Convention identifiers are recognized by GNAT: - - * Ada. This indicates that the standard Ada calling sequence will be - used and all Ada data items may be passed without any limitations - in the case where GNAT is used to generate both the caller and - callee. It is also possible to mix GNAT generated code and code - generated by another Ada compiler. In this case, the data types - should be restricted to simple cases, including primitive types. - Whether complex data types can be passed depends on the situation. - Probably it is safe to pass simple arrays, such as arrays of - integers or floats. Records may or may not work, depending on - whether both compilers lay them out identically. Complex structures - involving variant records, access parameters, tasks, or protected - types, are unlikely to be able to be passed. - - Note that in the case of GNAT running on a platform that supports - DEC Ada 83, a higher degree of compatibility can be guaranteed, - and in particular records are layed out in an identical manner in - the two compilers. Note also that if output from two different - compilers is mixed, the program is responsible for dealing with - elaboration issues. Probably the safest approach is to write the - main program in the version of Ada other than GNAT, so that it - takes care of its own elaboration requirements, and then call the - GNAT-generated adainit procedure to ensure elaboration of the GNAT - components. Consult the documentation of the other Ada compiler - for further details on elaboration. - - However, it is not possible to mix the tasking run time of GNAT and - DEC Ada 83, All the tasking operations must either be entirely - within GNAT compiled sections of the program, or entirely within - DEC Ada 83 compiled sections of the program. - - * Assembler. Specifies assembler as the convention. In practice this - has the same effect as convention Ada (but is not equivalent in - the sense of being considered the same convention). - - * Asm. Equivalent to Assembler. - - * Asm. Equivalent to Assembly. - - * COBOL. Data will be passed according to the conventions described - in section B.4 of the Ada 95 Reference Manual. - - * C. Data will be passed according to the conventions described in - section B.3 of the Ada 95 Reference Manual. - - * Default. Equivalent to C. - - * External. Equivalent to C. - - * CPP. This stands for C++. For most purposes this is identical to C. - See the separate description of the specialized GNAT pragmas - relating to C++ interfacing for further details. - - * Fortran. Data will be passed according to the conventions described - in section B.5 of the Ada 95 Reference Manual. - - * Intrinsic. This applies to an intrinsic operation, as defined in - the Ada 95 Reference Manual. If a a pragma Import (Intrinsic) - applies to a subprogram, this means that the body of the - subprogram is provided by the compiler itself, usually by means of - an efficient code sequence, and that the user does not supply an - explicit body for it. In an application program, the pragma can - only be applied to the following two sets of names, which the GNAT - compiler recognizes. - * Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, - Shift_Right_- Arithmetic. The corresponding subprogram - declaration must have two formal parameters. The first one - must be a signed integer type or a modular type with a binary - modulus, and the second parameter must be of type Natural. - The return type must be the same as the type of the first - argument. The size of this type can only be 8, 16, 32, or 64. - - * binary arithmetic operators: "+", "-", "*", "/" The - corresponding operator declaration must have parameters and - result type that have the same root numeric type (for - example, all three are long_float types). This simplifies the - definition of operations that use type checking to perform - dimensional checks: - type Distance is new Long_Float; - type Time is new Long_Float; - type Velocity is new Long_Float; - function "/" (D : Distance; T : Time) - return Velocity; - pragma Import (Intrinsic, "/"); - - This common idiom is often programmed with a generic - definition and an explicit body. The pragma makes it simpler - to introduce such declarations. It incurs no overhead in - compilation time or code size, because it is implemented as a - single machine instruction. - - * Stdcall. This is relevant only to NT/Win95 implementations of GNAT, - and specifies that the Stdcall calling sequence will be used, as - defined by the NT API. - - * DLL. This is equivalent to Stdcall. - - * Win32. This is equivalent to Stdcall. - - * Stubbed. This is a special convention that indicates that the - compiler should provide a stub body that raises `Program_Error'. - - GNAT additionally provides a useful pragma `Convention_Identifier' that - can be used to parametrize conventions and allow additional synonyms to - be specified. For example if you have legacy code in which the - convention identifier Fortran77 was used for Fortran, you can use the - configuration pragma: - - pragma Convention_Identifier (Fortran77, Fortran); - - And from now on the identifier Fortran77 may be used as a convention - identifier (for example in an `Import' pragma) with the same meaning as - Fortran. - -  - File: gnat_ug_vxw.info, Node: Building Mixed Ada & C++ Programs, Next: Comparison between GNAT and C/C++ Compilation Models, Prev: Mixed Language Programming, Up: The GNAT Compilation Model - - Building Mixed Ada & C++ Programs - ================================= - - Building a mixed application containing both Ada and C++ code may be a - challenge for the unaware programmer. As a matter of fact, this - interfacing has not been standardized in the Ada 95 reference manual due - to the immaturity and lack of standard of C++ at the time. This section - gives a few hints that should make this task easier. In particular the - first section addresses the differences with interfacing with C. The - second section looks into the delicate problem of linking the complete - application from its Ada and C++ parts. The last section give some - hints on how the GNAT run time can be adapted in order to allow - inter-language dispatching with a new C++ compiler. - - * Menu: - - * Interfacing to C++:: - * Linking a Mixed C++ & Ada Program:: - * A Simple Example:: - * Adapting the Run Time to a New C++ Compiler:: - -  - File: gnat_ug_vxw.info, Node: Interfacing to C++, Next: Linking a Mixed C++ & Ada Program, Up: Building Mixed Ada & C++ Programs - - Interfacing to C++ - ------------------ - - GNAT supports interfacing with C++ compilers generating code that is - compatible with the standard Application Binary Interface of the given - platform. - - Interfacing can be done at 3 levels: simple data, subprograms and - classes. In the first 2 cases, GNAT offer a specific CONVENTION CPP - that behaves exactly like CONVENTION C. Usually C++ mangle names of - subprograms and currently GNAT does not provide any help to solve the - demangling problem. This problem can be addressed in 2 ways: - * by modifying the C++ code in order to force a C convention using - the EXTERN "C" syntax. - - * by figuring out the mangled name and use it as the Link_Name - argument of the pragma import. - - Interfacing at the class level can be achieved by using the GNAT - specific pragmas such as `CPP_Class' and `CPP_Virtual'. See the GNAT - Reference Manual for additional information. - -  - File: gnat_ug_vxw.info, Node: Linking a Mixed C++ & Ada Program, Next: A Simple Example, Prev: Interfacing to C++, Up: Building Mixed Ada & C++ Programs - - Linking a Mixed C++ & Ada Program - --------------------------------- - - Usually the linker of the C++ development system must be used to link - mixed applications because most C++ systems will resolve elaboration - issues (such as calling constructors on global class instances) - transparently during the link phase. GNAT has been adapted to ease the - use of a foreign linker for the last phase. Three cases can be - considered: - 1. Using GNAT and G++ (GNU C++ compiler) from the same GCC - installation. The c++ linker can simply be called by using the c++ - specific driver called `c++'. Note that this setup is not very - common because it may request recompiling the whole GCC tree from - sources and it does not allow to upgrade easily to a new version - of one compiler for one of the two languages without taking the - risk of destabilizing the other. - - $ c++ -c file1.C - $ c++ -c file2.C - $ gnatmake ada_unit -largs file1.o file2.o --LINK=c++ - - 2. Using GNAT and G++ from 2 different GCC installations. If both - compilers are on the PATH, the same method can be used. It is - important to be aware that environment variables such as - C_INCLUDE_PATH, GCC_EXEC_PREFIX, BINUTILS_ROOT or GCC_ROOT will - affect both compilers at the same time and thus may make one of - the 2 compilers operate improperly if they are set for the other. - In particular it is important that the link command has access to - the proper gcc library `libgcc.a', that is to say the one that is - part of the C++ compiler installation. The implicit link command - as suggested in the gnatmake command from the former example can - be replaced by an explicit link command with full verbosity in - order to verify which library is used: - $ gnatbind ada_unit - $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ - If there is a problem due to interfering environment variables, it - can be workaround by using an intermediate script. The following - example shows the proper script to use when GNAT has not been - installed at its default location and g++ has been installed at - its default location: - - $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script - $ cat ./my_script - #!/bin/sh - unset BINUTILS_ROOT - unset GCC_ROOT - c++ $* - - 3. Using a non GNU C++ compiler. The same set of command as previously - described can be used to insure that the c++ linker is used. - Nonetheless, you need to add the path to libgcc explicitely, since - some libraries needed by GNAT are located in this directory: - - - $ gnatlink ada_unit file1.o file2.o --LINK=./my_script - $ cat ./my_script - #!/bin/sh - CC $* `gcc -print-libgcc-file-name` - - Where CC is the name of the non GNU C++ compiler. - - -  - File: gnat_ug_vxw.info, Node: A Simple Example, Next: Adapting the Run Time to a New C++ Compiler, Prev: Linking a Mixed C++ & Ada Program, Up: Building Mixed Ada & C++ Programs - - A Simple Example - ---------------- - - The following example, provided as part of the GNAT examples, show how - to achieve procedural interfacing between Ada and C++ in both - directions. The C++ class A has 2 methods. The first method is exported - to Ada by the means of an extern C wrapper function. The second method - calls an Ada subprogram. On the Ada side, The C++ calls is modelized by - a limited record with a layout comparable to the C++ class. The Ada - subprogram, in turn, calls the c++ method. So from the C++ main program - the code goes back and forth between the 2 languages. - - Here are the compilation commands for a GNAT VxWorks/PowerPC - configuration: - $ powerpc-wrs-vxworks-gnatmake -c simple_cpp_interface - $ powerpc-wrs-vxworks-gnatbind -n simple_cpp_interface - $ gnatlink simple_cpp_interface -o ada_part - $ c++ppc -c -DCPU=PPC604 -I/usr/windppc/target/h cpp_main.C - $ c++ppc -c -DCPU=PPC604 -I/usr/windppc/target/h ex7.C - $ ldppc -r -o my_main my_main.o ex7.o ada_part - - Here are the corresponding sources: - - //cpp_main.C - - #include "ex7.h" - - extern "C" { - void adainit (void); - void adafinal (void); - void method1 (A *t); - } - - void method1 (A *t) - { - t->method1 (); - } - - int main () - { - A obj; - adainit (); - obj.method2 (3030); - adafinal (); - } - - //ex7.h - - class Origin { - public: - int o_value; - }; - class A : public Origin { - public: - void method1 (void); - virtual void method2 (int v); - A(); - int a_value; - }; - - //ex7.C - - #include "ex7.h" - #include - - extern "C" { void ada_method2 (A *t, int v);} - - void A::method1 (void) - { - a_value = 2020; - printf ("in A::method1, a_value = %d \n",a_value); - - } - - void A::method2 (int v) - { - ada_method2 (this, v); - printf ("in A::method2, a_value = %d \n",a_value); - - } - - A::A(void) - { - a_value = 1010; - printf ("in A::A, a_value = %d \n",a_value); - } - - -- Ada sources - package body Simple_Cpp_Interface is - - procedure Ada_Method2 (This : in out A; V : Integer) is - begin - Method1 (This); - This.A_Value := V; - end Ada_Method2; - - end Simple_Cpp_Interface; - - package Simple_Cpp_Interface is - type A is limited - record - O_Value : Integer; - A_Value : Integer; - end record; - pragma Convention (C, A); - - procedure Method1 (This : in out A); - pragma Import (C, Method1); - - procedure Ada_Method2 (This : in out A; V : Integer); - pragma Export (C, Ada_Method2); - - end Simple_Cpp_Interface; - -  - File: gnat_ug_vxw.info, Node: Adapting the Run Time to a New C++ Compiler, Prev: A Simple Example, Up: Building Mixed Ada & C++ Programs - - Adapting the Run Time to a New C++ Compiler - ------------------------------------------- - - GNAT offers the capability to derive Ada 95 tagged types directly from - preexisting C++ classes and . See "Interfacing with C++" in the GNAT - reference manual. The mechanism used by GNAT for achieving such a goal - has been made user configurable through a GNAT library unit - `Interfaces.CPP'. The default version of this file is adapted to the - GNU c++ compiler. Internal knowledge of the virtual table layout used - by the new C++ compiler is needed to configure properly this unit. The - Interface of this unit is known by the compiler and cannot be changed - except for the value of the constants defining the characteristics of - the virtual table: CPP_DT_Prologue_Size, CPP_DT_Entry_Size, - CPP_TSD_Prologue_Size, CPP_TSD_Entry_Size. Read comments in the source - of this unit for more details. - -  - File: gnat_ug_vxw.info, Node: Comparison between GNAT and C/C++ Compilation Models, Next: Comparison between GNAT and Conventional Ada Library Models, Prev: Building Mixed Ada & C++ Programs, Up: The GNAT Compilation Model - - Comparison between GNAT and C/C++ Compilation Models - ==================================================== - - The GNAT model of compilation is close to the C and C++ models. You can - think of Ada specs as corresponding to header files in C. As in C, you - don't need to compile specs; they are compiled when they are used. The - Ada `with' is similar in effect to the `#include' of a C header. - - One notable difference is that, in Ada, you may compile specs - separately to check them for semantic and syntactic accuracy. This is - not always possible with C headers because they are fragments of - programs that have less specific syntactic or semantic rules. - - The other major difference is the requirement for running the binder, - which performs two important functions. First, it checks for - consistency. In C or C++, the only defense against assembling - inconsistent programs lies outside the compiler, in a makefile, for - example. The binder satisfies the Ada requirement that it be impossible - to construct an inconsistent program when the compiler is used in normal - mode. - - The other important function of the binder is to deal with - elaboration issues. There are also elaboration issues in C++ that are - handled automatically. This automatic handling has the advantage of - being simpler to use, but the C++ programmer has no control over - elaboration. Where `gnatbind' might complain there was no valid order - of elaboration, a C++ compiler would simply construct a program that - malfunctioned at run time. - -  - File: gnat_ug_vxw.info, Node: Comparison between GNAT and Conventional Ada Library Models, Prev: Comparison between GNAT and C/C++ Compilation Models, Up: The GNAT Compilation Model - - Comparison between GNAT and Conventional Ada Library Models - =========================================================== - - This section is intended to be useful to Ada programmers who have - previously used an Ada compiler implementing the traditional Ada library - model, as described in the Ada 95 Language Reference Manual. If you - have not used such a system, please go on to the next section. - - In GNAT, there is no "library" in the normal sense. Instead, the set - of source files themselves acts as the library. Compiling Ada programs - does not generate any centralized information, but rather an object - file and a ALI file, which are of interest only to the binder and - linker. In a traditional system, the compiler reads information not - only from the source file being compiled, but also from the centralized - library. This means that the effect of a compilation depends on what - has been previously compiled. In particular: - - * When a unit is `with''ed, the unit seen by the compiler corresponds - to the version of the unit most recently compiled into the library. - - * Inlining is effective only if the necessary body has already been - compiled into the library. - - * Compiling a unit may obsolete other units in the library. - - In GNAT, compiling one unit never affects the compilation of any other - units because the compiler reads only source files. Only changes to - source files can affect the results of a compilation. In particular: - - * When a unit is `with''ed, the unit seen by the compiler corresponds - to the source version of the unit that is currently accessible to - the compiler. - - * Inlining requires the appropriate source files for the package or - subprogram bodies to be available to the compiler. Inlining is - always effective, independent of the order in which units are - complied. - - * Compiling a unit never affects any other compilations. The editing - of sources may cause previous compilations to be out of date if - they depended on the source file being modified. - - The most important result of these differences is that order of - compilation is never significant in GNAT. There is no situation in - which one is required to do one compilation before another. What shows - up as order of compilation requirements in the traditional Ada library - becomes, in GNAT, simple source dependencies; in other words, there is - only a set of rules saying what source files must be present when a - file is compiled. - -  - File: gnat_ug_vxw.info, Node: Compiling Using gcc, Next: Binding Using gnatbind, Prev: The GNAT Compilation Model, Up: Top - - Compiling Using `gcc' - ********************* - - This chapter discusses how to compile Ada programs using the `gcc' - command. It also describes the set of switches that can be used to - control the behavior of the compiler. - - * Menu: - - * Compiling Programs:: - * Switches for gcc:: - * Search Paths and the Run-Time Library (RTL):: - * Order of Compilation Issues:: - * Examples:: - -  - File: gnat_ug_vxw.info, Node: Compiling Programs, Next: Switches for gcc, Up: Compiling Using gcc - - Compiling Programs - ================== - - The first step in creating an executable program is to compile the units - of the program using the `gcc' command. You must compile the following - files: - - * the body file (`.adb') for a library level subprogram or generic - subprogram - - * the spec file (`.ads') for a library level package or generic - package that has no body - - * the body file (`.adb') for a library level package or generic - package that has a body - - - You need _not_ compile the following files - - * the spec of a library unit which has a body - - * subunits - - because they are compiled as part of compiling related units. GNAT - package specs when the corresponding body is compiled, and subunits - when the parent is compiled. If you attempt to compile any of these - files, you will get one of the following error messages (where fff is - the name of the file you compiled): - - No code generated for file FFF (PACKAGE SPEC) - No code generated for file FFF (SUBUNIT) - - The basic command for compiling a file containing an Ada unit is - - $ gcc -c [SWITCHES] `file name' - - where FILE NAME is the name of the Ada file (usually having an extension - `.ads' for a spec or `.adb' for a body). You specify the `-c' switch - to tell `gcc' to compile, but not link, the file. The result of a - successful compilation is an object file, which has the same name as - the source file but an extension of `.o' and an Ada Library Information - (ALI) file, which also has the same name as the source file, but with - `.ali' as the extension. GNAT creates these two output files in the - current directory, but you may specify a source file in any directory - using an absolute or relative path specification containing the - directory information. - - `gcc' is actually a driver program that looks at the extensions of - the file arguments and loads the appropriate compiler. For example, the - GNU C compiler is `cc1', and the Ada compiler is `gnat1'. These - programs are in directories known to the driver program (in some - configurations via environment variables you set), but need not be in - your path. The `gcc' driver also calls the assembler and any other - utilities needed to complete the generation of the required object - files. - - It is possible to supply several file names on the same `gcc' - command. This causes `gcc' to call the appropriate compiler for each - file. For example, the following command lists three separate files to - be compiled: - - $ gcc -c x.adb y.adb z.c - - calls `gnat1' (the Ada compiler) twice to compile `x.adb' and `y.adb', - and `cc1' (the C compiler) once to compile `z.c'. The compiler - generates three object files `x.o', `y.o' and `z.o' and the two ALI - files `x.ali' and `y.ali' from the Ada compilations. Any switches apply - to all the files listed, except for `-gnatX' switches, which apply only - to Ada compilations. - -  - File: gnat_ug_vxw.info, Node: Switches for gcc, Next: Search Paths and the Run-Time Library (RTL), Prev: Compiling Programs, Up: Compiling Using gcc - - Switches for `gcc' - ================== - - The `gcc' command accepts switches that control the compilation - process. These switches are fully described in this section. First we - briefly list all the switches, in alphabetical order, then we describe - the switches in more detail in functionally grouped sections. - - * Menu: - - * Output and Error Message Control:: - * Debugging and Assertion Control:: - * Run-Time Checks:: - * Stack Overflow Checking:: - * Run-Time Control:: - * Validity Checking:: - * Style Checking:: - * Using gcc for Syntax Checking:: - * Using gcc for Semantic Checking:: - * Compiling Ada 83 Programs:: - * Character Set Control:: - * File Naming Control:: - * Subprogram Inlining Control:: - * Auxiliary Output Control:: - * Debugging Control:: - * Units to Sources Mapping Files:: - - `-b TARGET' - Compile your program to run on TARGET, which is the name of a - system configuration. You must have a GNAT cross-compiler built if - TARGET is not the same as your host system. - - `-BDIR' - Load compiler executables (for example, `gnat1', the Ada compiler) - from DIR instead of the default location. Only use this switch - when multiple versions of the GNAT compiler are available. See the - `gcc' manual page for further details. You would normally use the - `-b' or `-V' switch instead. - - `-c' - Compile. Always use this switch when compiling Ada programs. - - Note: for some other languages when using `gcc', notably in the - case of C and C++, it is possible to use use `gcc' without a `-c' - switch to compile and link in one step. In the case of GNAT, you - cannot use this approach, because the binder must be run and `gcc' - cannot be used to run the GNAT binder. - - `-g' - Generate debugging information. This information is stored in the - object file and copied from there to the final executable file by - the linker, where it can be read by the debugger. You must use the - `-g' switch if you plan on using the debugger. - - `-IDIR' - Direct GNAT to search the DIR directory for source files needed by - the current compilation (*note Search Paths and the Run-Time - Library (RTL)::). - - `-I-' - Except for the source file named in the command line, do not look - for source files in the directory containing the source file named - in the command line (*note Search Paths and the Run-Time Library - (RTL)::). - - `-o FILE' - This switch is used in `gcc' to redirect the generated object file - and its associated ALI file. Beware of this switch with GNAT, - because it may cause the object file and ALI file to have - different names which in turn may confuse the binder and the - linker. - - `-O[N]' - N controls the optimization level. - - n = 0 - No optimization, the default setting if no `-O' appears - - n = 1 - Normal optimization, the default if you specify `-O' without - an operand. - - n = 2 - Extensive optimization - - n = 3 - Extensive optimization with automatic inlining. This applies - only to inlining within a unit. For details on control of - inter-unit inlining see *Note Subprogram Inlining Control::. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-S' - Used in place of `-c' to cause the assembler source file to be - generated, using `.s' as the extension, instead of the object file. - This may be useful if you need to examine the generated assembly - code. - - `-v' - Show commands generated by the `gcc' driver. Normally used only for - debugging purposes or if you need to be sure what version of the - compiler you are executing. - - `-V VER' - Execute VER version of the compiler. This is the `gcc' version, - not the GNAT version. - - `-gnata' - Assertions enabled. `Pragma Assert' and `pragma Debug' to be - activated. - - `-gnatA' - Avoid processing `gnat.adc'. If a gnat.adc file is present, it - will be ignored. - - `-gnatb' - Generate brief messages to `stderr' even if verbose mode set. - - `-gnatc' - Check syntax and semantics only (no code generation attempted). - - `-gnatC' - Compress debug information and external symbol name table entries. - - `-gnatD' - Output expanded source files for source level debugging. This - switch also suppress generation of cross-reference information - (see -gnatx). - - `-gnatecPATH' - Specify a configuration pragma file. (see *Note The Configuration - Pragmas Files::) - - `-gnatemPATH' - Specify a mapping file. (see *Note Units to Sources Mapping - Files::) - - `-gnatE' - Full dynamic elaboration checks. - - `-gnatf' - Full errors. Multiple errors per line, all undefined references. - - `-gnatF' - Externals names are folded to all uppercase. - - `-gnatg' - Internal GNAT implementation mode. This should not be used for - applications programs, it is intended only for use by the compiler - and its run-time library. For documentation, see the GNAT sources. - - `-gnatG' - List generated expanded code in source form. - - `-gnatiC' - Identifier character set (C=1/2/3/4/8/9/p/f/n/w). - - `-gnath' - Output usage information. The output is written to `stdout'. - - `-gnatkN' - Limit file names to N (1-999) characters (`k' = krunch). - - `-gnatl' - Output full source listing with embedded error messages. - - `-gnatmN' - Limit number of detected errors to N (1-999). - - `-gnatn' - Activate inlining across unit boundaries for subprograms for which - pragma `inline' is specified. - - `-gnatN' - Activate front end inlining. - - `-fno-inline' - Suppresses all inlining, even if other optimization or inlining - switches are set. - - `-fstack-check' - Activates stack checking. See separate section on stack checking - for details of the use of this option. - - `-gnato' - Enable numeric overflow checking (which is not normally enabled by - default). Not that division by zero is a separate check that is not - controlled by this switch (division by zero checking is on by - default). - - `-gnatp' - Suppress all checks. - - `-gnatq' - Don't quit; try semantics, even if parse errors. - - `-gnatQ' - Don't quit; generate `ali' and tree files even if illegalities. - - `-gnatP' - Enable polling. This is required on some systems (notably Windows - NT) to obtain asynchronous abort and asynchronous transfer of - control capability. See the description of pragma Polling in the - GNAT Reference Manual for full details. - - `-gnatR[0/1/2/3][s]' - Output representation information for declared types and objects. - - `-gnats' - Syntax check only. - - `-gnatt' - Tree output file to be generated. - - `-gnatT nnn' - Set time slice to specified number of microseconds - - `-gnatu' - List units for this compilation. - - `-gnatU' - Tag all error messages with the unique string "error:" - - `-gnatv' - Verbose mode. Full error output with source lines to `stdout'. - - `-gnatV' - Control level of validity checking. See separate section describing - this feature. - - `-gnatwxxxXXX' - Warning mode where XXX is a string of options describing the exact - warnings that are enabled or disabled. See separate section on - warning control. - - `-gnatWE' - Wide character encoding method (E=n/h/u/s/e/8). - - `-gnatx' - Suppress generation of cross-reference information. - - `-gnaty' - Enable built-in style checks. See separate section describing this - feature. - - `-gnatzM' - Distribution stub generation and compilation (M=r/c for - receiver/caller stubs). - - `-gnat83' - Enforce Ada 83 restrictions. - - `-pass-exit-codes' - Catch exit codes from the compiler and use the most meaningful as - exit status. - - You may combine a sequence of GNAT switches into a single switch. For - example, the combined switch - - -gnatofi3 - - is equivalent to specifying the following sequence of switches: - - -gnato -gnatf -gnati3 - - The following restrictions apply to the combination of switches in this - manner: - - * The switch `-gnatc' if combined with other switches must come - first in the string. - - * The switch `-gnats' if combined with other switches must come - first in the string. - - * Once a "y" appears in the string (that is a use of the `-gnaty' - switch), then all further characters in the switch are interpreted - as style modifiers (see description of `-gnaty'). - - * Once a "d" appears in the string (that is a use of the `-gnatd' - switch), then all further characters in the switch are interpreted - as debug flags (see description of `-gnatd'). - - * Once a "w" appears in the string (that is a use of the `-gnatw' - switch), then all further characters in the switch are interpreted - as warning mode modifiers (see description of `-gnatw'). - - * Once a "V" appears in the string (that is a use of the `-gnatV' - switch), then all further characters in the switch are interpreted - as validity checking options (see description of `-gnatV'). - - -  - File: gnat_ug_vxw.info, Node: Output and Error Message Control, Next: Debugging and Assertion Control, Up: Switches for gcc - - Output and Error Message Control - -------------------------------- - - The standard default format for error messages is called "brief format." - Brief format messages are written to `stderr' (the standard error file) - and have the following form: - - e.adb:3:04: Incorrect spelling of keyword "function" - e.adb:4:20: ";" should be "is" - - The first integer after the file name is the line number in the file, - and the second integer is the column number within the line. `glide' - can parse the error messages and point to the referenced character. - The following switches provide control over the error message format: - - `-gnatv' - The v stands for verbose. The effect of this setting is to write - long-format error messages to `stdout' (the standard output file. - The same program compiled with the `-gnatv' switch would generate: - - 3. funcion X (Q : Integer) - | - >>> Incorrect spelling of keyword "function" - 4. return Integer; - | - >>> ";" should be "is" - - The vertical bar indicates the location of the error, and the `>>>' - prefix can be used to search for error messages. When this switch - is used the only source lines output are those with errors. - - `-gnatl' - The `l' stands for list. This switch causes a full listing of the - file to be generated. The output might look as follows: - - 1. procedure E is - 2. V : Integer; - 3. funcion X (Q : Integer) - | - >>> Incorrect spelling of keyword "function" - 4. return Integer; - | - >>> ";" should be "is" - 5. begin - 6. return Q + Q; - 7. end; - 8. begin - 9. V := X + X; - 10.end E; - - When you specify the `-gnatv' or `-gnatl' switches and standard - output is redirected, a brief summary is written to `stderr' - (standard error) giving the number of error messages and warning - messages generated. - - `-gnatU' - This switch forces all error messages to be preceded by the unique - string "error:". This means that error messages take a few more - characters in space, but allows easy searching for and - identification of error messages. - - `-gnatb' - The `b' stands for brief. This switch causes GNAT to generate the - brief format error messages to `stderr' (the standard error file) - as well as the verbose format message or full listing (which as - usual is written to `stdout' (the standard output file). - - `-gnatmN' - The `m' stands for maximum. N is a decimal integer in the range - of 1 to 999 and limits the number of error messages to be - generated. For example, using `-gnatm2' might yield - - e.adb:3:04: Incorrect spelling of keyword "function" - e.adb:5:35: missing ".." - fatal error: maximum errors reached - compilation abandoned - - `-gnatf' - The `f' stands for full. Normally, the compiler suppresses error - messages that are likely to be redundant. This switch causes all - error messages to be generated. In particular, in the case of - references to undefined variables. If a given variable is - referenced several times, the normal format of messages is - e.adb:7:07: "V" is undefined (more references follow) - - where the parenthetical comment warns that there are additional - references to the variable `V'. Compiling the same program with the - `-gnatf' switch yields - - e.adb:7:07: "V" is undefined - e.adb:8:07: "V" is undefined - e.adb:8:12: "V" is undefined - e.adb:8:16: "V" is undefined - e.adb:9:07: "V" is undefined - e.adb:9:12: "V" is undefined - - `-gnatq' - The `q' stands for quit (really "don't quit"). In normal - operation mode, the compiler first parses the program and - determines if there are any syntax errors. If there are, - appropriate error messages are generated and compilation is - immediately terminated. This switch tells GNAT to continue with - semantic analysis even if syntax errors have been found. This may - enable the detection of more errors in a single run. On the other - hand, the semantic analyzer is more likely to encounter some - internal fatal error when given a syntactically invalid tree. - - `-gnatQ' - In normal operation mode, the `ali' file is not generated if any - illegalities are detected in the program. The use of `-gnatQ' - forces generation of the `ali' file. This file is marked as being - in error, so it cannot be used for binding purposes, but it does - contain reasonably complete cross-reference information, and thus - may be useful for use by tools (e.g. semantic browsing tools or - integrated development environments) that are driven from the - `ali' file. - - In addition, if `-gnatt' is also specified, then the tree file is - generated even if there are illegalities. It may be useful in this - case to also specify `-gnatq' to ensure that full semantic - processing occurs. The resulting tree file can be processed by - ASIS, for the purpose of providing partial information about - illegal units, but if the error causes the tree to be badly - malformed, then ASIS may crash during the analysis. - - In addition to error messages, which correspond to illegalities as - defined in the Ada 95 Reference Manual, the compiler detects two kinds - of warning situations. - - First, the compiler considers some constructs suspicious and - generates a warning message to alert you to a possible error. Second, - if the compiler detects a situation that is sure to raise an exception - at run time, it generates a warning message. The following shows an - example of warning messages: - e.adb:4:24: warning: creation of object may raise Storage_Error - e.adb:10:17: warning: static value out of range - e.adb:10:17: warning: "Constraint_Error" will be raised at run time - - GNAT considers a large number of situations as appropriate for the - generation of warning messages. As always, warnings are not definite - indications of errors. For example, if you do an out-of-range - assignment with the deliberate intention of raising a - `Constraint_Error' exception, then the warning that may be issued does - not indicate an error. Some of the situations for which GNAT issues - warnings (at least some of the time) are given in the following list, - which is not necessarily complete. - - * Possible infinitely recursive calls - - * Out-of-range values being assigned - - * Possible order of elaboration problems - - * Unreachable code - - * Fixed-point type declarations with a null range - - * Variables that are never assigned a value - - * Variables that are referenced before being initialized - - * Task entries with no corresponding accept statement - - * Duplicate accepts for the same task entry in a select - - * Objects that take too much storage - - * Unchecked conversion between types of differing sizes - - * Missing return statements along some execution paths in a function - - * Incorrect (unrecognized) pragmas - - * Incorrect external names - - * Allocation from empty storage pool - - * Potentially blocking operations in protected types - - * Suspicious parenthesization of expressions - - * Mismatching bounds in an aggregate - - * Attempt to return local value by reference - - * Unrecognized pragmas - - * Premature instantiation of a generic body - - * Attempt to pack aliased components - - * Out of bounds array subscripts - - * Wrong length on string assignment - - * Violations of style rules if style checking is enabled - - * Unused with clauses - - * Bit_Order usage that does not have any effect - - * Compile time biased rounding of floating-point constant - - * Standard.Duration used to resolve universal fixed expression - - * Dereference of possibly null value - - * Declaration that is likely to cause storage error - - * Internal GNAT unit with'ed by application unit - - * Values known to be out of range at compile time - - * Unreferenced labels and variables - - * Address overlays that could clobber memory - - * Unexpected initialization when address clause present - - * Bad alignment for address clause - - * Useless type conversions - - * Redundant assignment statements - - * Accidental hiding of name by child unit - - * Unreachable code - - * Access before elaboration detected at compile time - - * A range in a `for' loop that is known to be null or might be null - - - The following switches are available to control the handling of warning - messages: - - `-gnatwa (activate all optional errors)' - This switch activates most optional warning messages, see - remaining list in this section for details on optional warning - messages that can be individually controlled. The warnings that - are not turned on by this switch are `-gnatwb' (biased rounding), - `-gnatwd' (implicit dereferencing), and `-gnatwh' (hiding). All - other optional warnings are turned on. - - `-gnatwA (suppress all optional errors)' - This switch suppresses all optional warning messages, see - remaining list in this section for details on optional warning - messages that can be individually controlled. - - `-gnatwb (activate warnings on biased rounding)' - If a static floating-point expression has a value that is exactly - half way between two adjacent machine numbers, then the rules of - Ada (Ada Reference Manual, section 4.9(38)) require that this - rounding be done away from zero, even if the normal unbiased - rounding rules at run time would require rounding towards zero. - This warning message alerts you to such instances where - compile-time rounding and run-time rounding are not equivalent. If - it is important to get proper run-time rounding, then you can - force this by making one of the operands into a variable. The - default is that such warnings are not generated. Note that - `-gnatwa' does not affect the setting of this warning option. - - `-gnatwB (suppress warnings on biased rounding)' - This switch disables warnings on biased rounding. - - `-gnatwc (activate warnings on conditionals)' - This switch activates warnings for conditional expressions used in - tests that are known to be True or False at compile time. The - default is that such warnings are not generated. This warning can - also be turned on using `-gnatwa'. - - `-gnatwC (suppress warnings on conditionals)' - This switch suppresses warnings for conditional expressions used in - tests that are known to be True or False at compile time. - - `-gnatwd (activate warnings on implicit dereferencing)' - If this switch is set, then the use of a prefix of an access type - in an indexed component, slice, or selected component without an - explicit `.all' will generate a warning. With this warning - enabled, access checks occur only at points where an explicit - `.all' appears in the source code (assuming no warnings are - generated as a result of this switch). The default is that such - warnings are not generated. Note that `-gnatwa' does not affect - the setting of this warning option. - - `-gnatwD (suppress warnings on implicit dereferencing)' - This switch suppresses warnings for implicit deferences in indexed - components, slices, and selected components. - - `-gnatwe (treat warnings as errors)' - This switch causes warning messages to be treated as errors. The - warning string still appears, but the warning messages are counted - as errors, and prevent the generation of an object file. - - `-gnatwf (activate warnings on unreferenced formals)' - This switch causes a warning to be generated if a formal parameter - is not referenced in the body of the subprogram. This warning can - also be turned on using `-gnatwa' or `-gnatwu'. - - `-gnatwF (suppress warnings on unreferenced formals)' - This switch suppresses warnings for unreferenced formal - parameters. Note that the combination `-gnatwu' followed by - `-gnatwF' has the effect of warning on unreferenced entities other - than subprogram formals. - - `-gnatwh (activate warnings on hiding)' - This switch activates warnings on hiding declarations. A - declaration is considered hiding if it is for a non-overloadable - entity, and it declares an entity with the same name as some other - entity that is directly or use-visible. The default is that such - warnings are not generated. Note that `-gnatwa' does not affect - the setting of this warning option. - - `-gnatwH (suppress warnings on hiding)' - This switch suppresses warnings on hiding declarations. - - `-gnatwi (activate warnings on implementation units).' - This switch activates warnings for a `with' of an internal GNAT - implementation unit, defined as any unit from the `Ada', - `Interfaces', `GNAT', or `System' hierarchies that is not - documented in either the Ada Reference Manual or the GNAT - Programmer's Reference Manual. Such units are intended only for - internal implementation purposes and should not be `with''ed by - user programs. The default is that such warnings are generated - This warning can also be turned on using `-gnatwa'. - - `-gnatwI (disable warnings on implementation units).' - This switch disables warnings for a `with' of an internal GNAT - implementation unit. - - `-gnatwl (activate warnings on elaboration pragmas)' - This switch activates warnings on missing pragma Elaborate_All - statements. See the section in this guide on elaboration checking - for details on when such pragma should be used. The default is - that such warnings are not generated. This warning can also be - turned on using `-gnatwa'. - - `-gnatwL (suppress warnings on elaboration pragmas)' - This switch suppresses warnings on missing pragma Elaborate_All - statements. See the section in this guide on elaboration checking - for details on when such pragma should be used. - - `-gnatwo (activate warnings on address clause overlays)' - This switch activates warnings for possibly unintended - initialization effects of defining address clauses that cause one - variable to overlap another. The default is that such warnings are - generated. This warning can also be turned on using `-gnatwa'. - - `-gnatwO (suppress warnings on address clause overlays)' - This switch suppresses warnings on possibly unintended - initialization effects of defining address clauses that cause one - variable to overlap another. - - `-gnatwp (activate warnings on ineffective pragma Inlines)' - This switch activates warnings for failure of front end inlining - (activated by `-gnatN') to inline a particular call. There are - many reasons for not being able to inline a call, including most - commonly that the call is too complex to inline. This warning can - also be turned on using `-gnatwa'. - - `-gnatwP (suppress warnings on ineffective pragma Inlines)' - This switch suppresses warnings on ineffective pragma Inlines. If - the inlining mechanism cannot inline a call, it will simply ignore - the request silently. - - `-gnatwr (activate warnings on redundant constructs)' - This switch activates warnings for redundant constructs. The - following is the current list of constructs regarded as redundant: - This warning can also be turned on using `-gnatwa'. - - * Assignment of an item to itself. - - * Type conversion that converts an expression to its own type. - - * Use of the attribute `Base' where `typ'Base' is the same as - `typ'. - - * Use of pragma `Pack' when all components are placed by a - record representation clause. - - `-gnatwR (suppress warnings on redundant constructs)' - This switch suppresses warnings for redundant constructs. - - `-gnatws (suppress all warnings)' - This switch completely suppresses the output of all warning - messages from the GNAT front end. Note that it does not suppress - warnings from the `gcc' back end. To suppress these back end - warnings as well, use the switch `-w' in addition to `-gnatws'. - - `-gnatwu (activate warnings on unused entities)' - This switch activates warnings to be generated for entities that - are defined but not referenced, and for units that are `with''ed - and not referenced. In the case of packages, a warning is also - generated if no entities in the package are referenced. This means - that if the package is referenced but the only references are in - `use' clauses or `renames' declarations, a warning is still - generated. A warning is also generated for a generic package that - is `with''ed but never instantiated. In the case where a package - or subprogram body is compiled, and there is a `with' on the - corresponding spec that is only referenced in the body, a warning - is also generated, noting that the `with' can be moved to the - body. The default is that such warnings are not generated. This - switch also activates warnings on unreferenced formals (it is - includes the effect of `-gnatwf'). This warning can also be - turned on using `-gnatwa'. - - `-gnatwU (suppress warnings on unused entities)' - This switch suppresses warnings for unused entities and packages. - It also turns off warnings on unreferenced formals (and thus - includes the effect of `-gnatwF'). - - A string of warning parameters can be used in the same parameter. - For example: - - -gnatwaLe - - Would turn on all optional warnings except for elaboration pragma - warnings, and also specify that warnings should be treated as - errors. - - `-w' - This switch suppresses warnings from the `gcc' backend. It may be - used in conjunction with `-gnatws' to ensure that all warnings are - suppressed during the entire compilation process. - -  - File: gnat_ug_vxw.info, Node: Debugging and Assertion Control, Next: Run-Time Checks, Prev: Output and Error Message Control, Up: Switches for gcc - - Debugging and Assertion Control - ------------------------------- - - `-gnata' - The pragmas `Assert' and `Debug' normally have no effect and are - ignored. This switch, where `a' stands for assert, causes `Assert' - and `Debug' pragmas to be activated. - - The pragmas have the form: - - pragma Assert (BOOLEAN-EXPRESSION [, - STATIC-STRING-EXPRESSION]) - pragma Debug (PROCEDURE CALL) - - The `Assert' pragma causes BOOLEAN-EXPRESSION to be tested. If - the result is `True', the pragma has no effect (other than - possible side effects from evaluating the expression). If the - result is `False', the exception `Assert_Failure' declared in the - package `System.Assertions' is raised (passing - STATIC-STRING-EXPRESSION, if present, as the message associated - with the exception). If no string expression is given the default - is a string giving the file name and line number of the pragma. - - The `Debug' pragma causes PROCEDURE to be called. Note that - `pragma Debug' may appear within a declaration sequence, allowing - debugging procedures to be called between declarations. - -  - File: gnat_ug_vxw.info, Node: Validity Checking, Next: Style Checking, Prev: Run-Time Control, Up: Switches for gcc - - Validity Checking - ----------------- - - The Ada 95 Reference Manual has specific requirements for checking for - invalid values. In particular, RM 13.9.1 requires that the evaluation - of invalid values (for example from unchecked conversions), not result - in erroneous execution. In GNAT, the result of such an evaluation in - normal default mode is to either use the value unmodified, or to raise - Constraint_Error in those cases where use of the unmodified value would - cause erroneous execution. The cases where unmodified values might lead - to erroneous execution are case statements (where a wild jump might - result from an invalid value), and subscripts on the left hand side - (where memory corruption could occur as a result of an invalid value). - - The `-gnatVx' switch allows more control over the validity checking - mode. The `x' argument here is a string of letters which control which - validity checks are performed in addition to the default checks - described above. - - * `-gnatVc' Validity checks for copies - - The right hand side of assignments, and the initializing values of - object declarations are validity checked. - - * `-gnatVd' Default (RM) validity checks - - Some validity checks are done by default following normal Ada - semantics (RM 13.9.1 (9-11)). A check is done in case statements - that the expression is within the range of the subtype. If it is - not, Constraint_Error is raised. For assignments to array - components, a check is done that the expression used as index is - within the range. If it is not, Constraint_Error is raised. Both - these validity checks may be turned off using switch `-gnatVD'. - They are turned on by default. If `-gnatVD' is specified, a - subsequent switch `-gnatVd' will leave the checks turned on. - Switch `-gnatVD' should be used only if you are sure that all such - expressions have valid values. If you use this switch and invalid - values are present, then the program is erroneous, and wild jumps - or memory overwriting may occur. - - * `-gnatVi' Validity checks for `in' mode parameters - - Arguments for parameters of mode `in' are validity checked in - function and procedure calls at the point of call. - - * `-gnatVm' Validity checks for `in out' mode parameters - - Arguments for parameters of mode `in out' are validity checked in - procedure calls at the point of call. The `'m'' here stands for - modify, since this concerns parameters that can be modified by the - call. Note that there is no specific option to test `out' - parameters, but any reference within the subprogram will be tested - in the usual manner, and if an invalid value is copied back, any - reference to it will be subject to validity checking. - - * `-gnatVo' Validity checks for operator and attribute operands - - Arguments for predefined operators and attributes are validity - checked. This includes all operators in package `Standard', the - shift operators defined as intrinsic in package `Interfaces' and - operands for attributes such as `Pos'. - - * `-gnatVr' Validity checks for function returns - - The expression in `return' statements in functions is validity - checked. - - * `-gnatVs' Validity checks for subscripts - - All subscripts expressions are checked for validity, whether they - appear on the right side or left side (in default mode only left - side subscripts are validity checked). - - * `-gnatVt' Validity checks for tests - - Expressions used as conditions in `if', `while' or `exit' - statements are checked, as well as guard expressions in entry - calls. - - * `-gnatVf' Validity checks for floating-point values - - In the absence of this switch, validity checking occurs only for - discrete values. If `-gnatVf' is specified, then validity checking - also applies for floating-point values, and NaN's and infinities - are considered invalid, as well as out of range values for - constrained types. Note that this means that standard `IEEE' - infinity mode is not allowed. The exact contexts in which - floating-point values are checked depends on the setting of other - options. For example `-gnatVif' or `-gnatVfi' (the order does not - matter) specifies that floating-point parameters of mode `in' - should be validity checked. - - * `-gnatVa' All validity checks - - All the above validity checks are turned on. That is `-gnatVa' is - equivalent to `gnatVcdfimorst'. - - * `-gnatVn' No validity checks - - This switch turns off all validity checking, including the default - checking for case statements and left hand side subscripts. Note - that the use of the switch `-gnatp' supresses all run-time checks, - including validity checks, and thus implies `-gnatVn'. - - - The `-gnatV' switch may be followed by a string of letters to turn on - a series of validity checking options. For example, `-gnatVcr' specifies - that in addition to the default validity checking, copies and function - return expressions be validity checked. In order to make it easier to - specify a set of options, the upper case letters `CDFIMORST' may be - used to turn off the corresponding lower case option, so for example - `-gnatVaM' turns on all validity checking options except for checking - of `in out' procedure arguments. - - The specification of additional validity checking generates extra - code (and in the case of `-gnatva' the code expansion can be - substantial. However, these additional checks can be very useful in - smoking out cases of uninitialized variables, incorrect use of - unchecked conversion, and other errors leading to invalid values. The - use of pragma `Initialize_Scalars' is useful in conjunction with the - extra validity checking, since this ensures that wherever possible - uninitialized variables have invalid values. - - See also the pragma `Validity_Checks' which allows modification of - the validity checking mode at the program source level, and also allows - for temporary disabling of validity checks. - -  - File: gnat_ug_vxw.info, Node: Style Checking, Next: Using gcc for Syntax Checking, Prev: Validity Checking, Up: Switches for gcc - - Style Checking - -------------- - - The -gnatyX switch causes the compiler to enforce specified style - rules. A limited set of style rules has been used in writing the GNAT - sources themselves. This switch allows user programs to activate all or - some of these checks. If the source program fails a specified style - check, an appropriate warning message is given, preceded by the - character sequence "(style)". The string X is a sequence of letters or - digits indicating the particular style checks to be performed. The - following checks are defined: - - `1-9 (specify indentation level)' - If a digit from 1-9 appears in the string after `-gnaty' then - proper indentation is checked, with the digit indicating the - indentation level required. The general style of required - indentation is as specified by the examples in the Ada Reference - Manual. Full line comments must be aligned with the `--' starting - on a column that is a multiple of the alignment level. - - `a (check attribute casing)' - If the letter a appears in the string after `-gnaty' then - attribute names, including the case of keywords such as `digits' - used as attributes names, must be written in mixed case, that is, - the initial letter and any letter following an underscore must be - uppercase. All other letters must be lowercase. - - `b (blanks not allowed at statement end)' - If the letter b appears in the string after `-gnaty' then trailing - blanks are not allowed at the end of statements. The purpose of - this rule, together with h (no horizontal tabs), is to enforce a - canonical format for the use of blanks to separate source tokens. - - `c (check comments)' - If the letter c appears in the string after `-gnaty' then comments - must meet the following set of rules: - - * The "-" that starts the column must either start in column - one, or else at least one blank must precede this sequence. - - * Comments that follow other tokens on a line must have at - least one blank following the "-" at the start of the comment. - - * Full line comments must have two blanks following the "-" - that starts the comment, with the following exceptions. - - * A line consisting only of the "-" characters, possibly - preceded by blanks is permitted. - - * A comment starting with "-x" where x is a special character - is permitted. This alows proper processing of the output - generated by specialized tools including `gnatprep' (where -! - is used) and the SPARK annnotation language (where -# is - used). For the purposes of this rule, a special character is - defined as being in one of the ASCII ranges 16#21#..16#2F# or - 16#3A#..16#3F#. - - * A line consisting entirely of minus signs, possibly preceded - by blanks, is permitted. This allows the construction of box - comments where lines of minus signs are used to form the top - and bottom of the box. - - * If a comment starts and ends with "-" is permitted as long as - at least one blank follows the initial "-". Together with the - preceding rule, this allows the construction of box comments, - as shown in the following example: - --------------------------- - -- This is a box comment -- - -- with two text lines. -- - --------------------------- - - `e (check end/exit labels)' - If the letter e appears in the string after `-gnaty' then optional - labels on `end' statements ending subprograms and on `exit' - statements exiting named loops, are required to be present. - - `f (no form feeds or vertical tabs)' - If the letter f appears in the string after `-gnaty' then neither - form feeds nor vertical tab characters are not permitted in the - source text. - - `h (no horizontal tabs)' - If the letter h appears in the string after `-gnaty' then - horizontal tab characters are not permitted in the source text. - Together with the b (no blanks at end of line) check, this - enforces a canonical form for the use of blanks to separate source - tokens. - - `i (check if-then layout)' - If the letter i appears in the string after `-gnaty', then the - keyword `then' must appear either on the same line as - corresponding `if', or on a line on its own, lined up under the - `if' with at least one non-blank line in between containing all or - part of the condition to be tested. - - `k (check keyword casing)' - If the letter k appears in the string after `-gnaty' then all - keywords must be in lower case (with the exception of keywords - such as `digits' used as attribute names to which this check does - not apply). - - `l (check layout)' - If the letter l appears in the string after `-gnaty' then layout - of statement and declaration constructs must follow the - recommendations in the Ada Reference Manual, as indicated by the - form of the syntax rules. For example an `else' keyword must be - lined up with the corresponding `if' keyword. - - There are two respects in which the style rule enforced by this - check option are more liberal than those in the Ada Reference - Manual. First in the case of record declarations, it is - permissible to put the `record' keyword on the same line as the - `type' keyword, and then the `end' in `end record' must line up - under `type'. For example, either of the following two layouts is - acceptable: - - type q is record - a : integer; - b : integer; - end record; - - type q is - record - a : integer; - b : integer; - end record; - - Second, in the case of a block statement, a permitted alternative - is to put the block label on the same line as the `declare' or - `begin' keyword, and then line the `end' keyword up under the - block label. For example both the following are permitted: - - Block : declare - A : Integer := 3; - begin - Proc (A, A); - end Block; - - Block : - declare - A : Integer := 3; - begin - Proc (A, A); - end Block; - - The same alternative format is allowed for loops. For example, - both of the following are permitted: - - Clear : while J < 10 loop - A (J) := 0; - end loop Clear; - - Clear : - while J < 10 loop - A (J) := 0; - end loop Clear; - - `m (check maximum line length)' - If the letter m appears in the string after `-gnaty' then the - length of source lines must not exceed 79 characters, including - any trailing blanks. The value of 79 allows convenient display on - an 80 character wide device or window, allowing for possible - special treatment of 80 character lines. - - `Mnnn (set maximum line length)' - If the sequence Mnnn, where nnn is a decimal number, appears in - the string after `-gnaty' then the length of lines must not exceed - the given value. - - `n (check casing of entities in Standard)' - If the letter n appears in the string after `-gnaty' then any - identifier from Standard must be cased to match the presentation - in the Ada Reference Manual (for example, `Integer' and - `ASCII.NUL'). - - `o (check order of subprogram bodies)' - If the letter o appears in the string after `-gnaty' then all - subprogram bodies in a given scope (e.g. a package body) must be - in alphabetical order. The ordering rule uses normal Ada rules for - comparing strings, ignoring casing of letters, except that if - there is a trailing numeric suffix, then the value of this suffix - is used in the ordering (e.g. Junk2 comes before Junk10). - - `p (check pragma casing)' - If the letter p appears in the string after `-gnaty' then pragma - names must be written in mixed case, that is, the initial letter - and any letter following an underscore must be uppercase. All - other letters must be lowercase. - - `r (check references)' - If the letter r appears in the string after `-gnaty' then all - identifier references must be cased in the same way as the - corresponding declaration. No specific casing style is imposed on - identifiers. The only requirement is for consistency of references - with declarations. - - `s (check separate specs)' - If the letter s appears in the string after `-gnaty' then separate - declarations ("specs") are required for subprograms (a body is not - allowed to serve as its own declaration). The only exception is - that parameterless library level procedures are not required to - have a separate declaration. This exception covers the most - frequent form of main program procedures. - - `t (check token spacing)' - If the letter t appears in the string after `-gnaty' then the - following token spacing rules are enforced: - - * The keywords `abs' and `not' must be followed by a space. - - * The token `=>' must be surrounded by spaces. - - * The token `<>' must be preceded by a space or a left - parenthesis. - - * Binary operators other than `**' must be surrounded by spaces. - There is no restriction on the layout of the `**' binary - operator. - - * Colon must be surrounded by spaces. - - * Colon-equal (assignment) must be surrounded by spaces. - - * Comma must be the first non-blank character on the line, or be - immediately preceded by a non-blank character, and must be - followed by a space. - - * If the token preceding a left paren ends with a letter or - digit, then a space must separate the two tokens. - - * A right parenthesis must either be the first non-blank - character on a line, or it must be preceded by a non-blank - character. - - * A semicolon must not be preceded by a space, and must not be - followed by a non-blank character. - - * A unary plus or minus may not be followed by a space. - - * A vertical bar must be surrounded by spaces. - - In the above rules, appearing in column one is always permitted, - that is, counts as meeting either a requirement for a required - preceding space, or as meeting a requirement for no preceding - space. - - Appearing at the end of a line is also always permitted, that is, - counts as meeting either a requirement for a following space, or - as meeting a requirement for no following space. - - If any of these style rules is violated, a message is generated giving - details on the violation. The initial characters of such messages are - always "(style)". Note that these messages are treated as warning - messages, so they normally do not prevent the generation of an object - file. The `-gnatwe' switch can be used to treat warning messages, - including style messages, as fatal errors. - - The switch `-gnaty' on its own (that is not followed by any letters or - digits), is equivalent to `gnaty3abcefhiklmprst', that is all checking - options are enabled with the exception of -gnatyo, with an indentation - level of 3. This is the standard checking option that is used for the - GNAT sources. - -  - File: gnat_ug_vxw.info, Node: Run-Time Checks, Next: Stack Overflow Checking, Prev: Debugging and Assertion Control, Up: Switches for gcc - - Run-Time Checks - --------------- - - If you compile with the default options, GNAT will insert many run-time - checks into the compiled code, including code that performs range - checking against constraints, but not arithmetic overflow checking for - integer operations (including division by zero) or checks for access - before elaboration on subprogram calls. All other run-time checks, as - required by the Ada 95 Reference Manual, are generated by default. The - following `gcc' switches refine this default behavior: - - `-gnatp' - Suppress all run-time checks as though `pragma Suppress - (all_checks') had been present in the source. Validity checks are - also suppressed (in other words `-gnatp' also implies `-gnatVn'. - Use this switch to improve the performance of the code at the - expense of safety in the presence of invalid data or program bugs. - - `-gnato' - Enables overflow checking for integer operations. This causes - GNAT to generate slower and larger executable programs by adding - code to check for overflow (resulting in raising - `Constraint_Error' as required by standard Ada semantics). These - overflow checks correspond to situations in which the true value - of the result of an operation may be outside the base range of the - result type. The following example shows the distinction: - - X1 : Integer := Integer'Last; - X2 : Integer range 1 .. 5 := 5; - ... - X1 := X1 + 1; -- `-gnato' required to catch the Constraint_Error - X2 := X2 + 1; -- range check, `-gnato' has no effect here - - Here the first addition results in a value that is outside the - base range of Integer, and hence requires an overflow check for - detection of the constraint error. The second increment operation - results in a violation of the explicit range constraint, and such - range checks are always performed. Basically the compiler can - assume that in the absence of the `-gnato' switch that any value - of type `xxx' is in range of the base type of `xxx'. - - Note that the `-gnato' switch does not affect the code generated - for any floating-point operations; it applies only to integer - semantics). For floating-point, GNAT has the `Machine_Overflows' - attribute set to `False' and the normal mode of operation is to - generate IEEE NaN and infinite values on overflow or invalid - operations (such as dividing 0.0 by 0.0). - - The reason that we distinguish overflow checking from other kinds - of range constraint checking is that a failure of an overflow - check can generate an incorrect value, but cannot cause erroneous - behavior. This is unlike the situation with a constraint check on - an array subscript, where failure to perform the check can result - in random memory description, or the range check on a case - statement, where failure to perform the check can cause a wild - jump. - - Note again that `-gnato' is off by default, so overflow checking is - not performed in default mode. This means that out of the box, - with the default settings, GNAT does not do all the checks - expected from the language description in the Ada Reference - Manual. If you want all constraint checks to be performed, as - described in this Manual, then you must explicitly use the -gnato - switch either on the `gnatmake' or `gcc' command. - - `-gnatE' - Enables dynamic checks for access-before-elaboration on subprogram - calls and generic instantiations. For full details of the effect - and use of this switch, *Note Compiling Using gcc::. - - The setting of these switches only controls the default setting of the - checks. You may modify them using either `Suppress' (to remove checks) - or `Unsuppress' (to add back suppressed checks) pragmas in the program - source. - -  - File: gnat_ug_vxw.info, Node: Stack Overflow Checking, Next: Run-Time Control, Prev: Run-Time Checks, Up: Switches for gcc - - Stack Overflow Checking - ----------------------- - - For most operating systems, `gcc' does not perform stack overflow - checking by default. This means that if the main environment task or - some other task exceeds the available stack space, then unpredictable - behavior will occur. - - To activate stack checking, compile all units with the gcc option - `-fstack-check'. For example: - - gcc -c -fstack-check package1.adb - - Units compiled with this option will generate extra instructions to - check that any use of the stack (for procedure calls or for declaring - local variables in declare blocks) do not exceed the available stack - space. If the space is exceeded, then a `Storage_Error' exception is - raised. - - For declared tasks, the stack size is always controlled by the size - given in an applicable `Storage_Size' pragma (or is set to the default - size if no pragma is used. - - For the environment task, the stack size depends on system defaults - and is unknown to the compiler. The stack may even dynamically grow on - some systems, precluding the normal Ada semantics for stack overflow. - In the worst case, unbounded stack usage, causes unbounded stack - expansion resulting in the system running out of virtual memory. - - The stack checking may still work correctly if a fixed size stack is - allocated, but this cannot be guaranteed. To ensure that a clean - exception is signalled for stack overflow, set the environment variable - `GNAT_STACK_LIMIT' to indicate the maximum stack area that can be used, - as in: - - SET GNAT_STACK_LIMIT 1600 - - The limit is given in kilobytes, so the above declaration would set the - stack limit of the environment task to 1.6 megabytes. Note that the - only purpose of this usage is to limit the amount of stack used by the - environment task. If it is necessary to increase the amount of stack - for the environment task, then this is an operating systems issue, and - must be addressed with the appropriate operating systems commands. - -  - File: gnat_ug_vxw.info, Node: Run-Time Control, Next: Validity Checking, Prev: Stack Overflow Checking, Up: Switches for gcc - - Run-Time Control - ---------------- - - `-gnatT nnn' - The `gnatT' switch can be used to specify the time-slicing value - to be used for task switching between equal priority tasks. The - value `nnn' is given in microseconds as a decimal integer. - - Setting the time-slicing value is only effective if the underlying - thread control system can accommodate time slicing. Check the - documentation of your operating system for details. Note that the - time-slicing value can also be set by use of pragma `Time_Slice' - or by use of the `t' switch in the gnatbind step. The pragma - overrides a command line argument if both are present, and the `t' - switch for gnatbind overrides both the pragma and the `gcc' - command line switch. - -  - File: gnat_ug_vxw.info, Node: Using gcc for Syntax Checking, Next: Using gcc for Semantic Checking, Prev: Style Checking, Up: Switches for gcc - - Using `gcc' for Syntax Checking - ------------------------------- - - `-gnats' - The `s' stands for syntax. - - Run GNAT in syntax checking only mode. For example, the command - - $ gcc -c -gnats x.adb - - compiles file `x.adb' in syntax-check-only mode. You can check a - series of files in a single command , and can use wild cards to - specify such a group of files. Note that you must specify the - `-c' (compile only) flag in addition to the `-gnats' flag. . - - You may use other switches in conjunction with `-gnats'. In - particular, `-gnatl' and `-gnatv' are useful to control the format - of any generated error messages. - - The output is simply the error messages, if any. No object file or - ALI file is generated by a syntax-only compilation. Also, no units - other than the one specified are accessed. For example, if a unit - `X' `with''s a unit `Y', compiling unit `X' in syntax check only - mode does not access the source file containing unit `Y'. - - Normally, GNAT allows only a single unit in a source file. - However, this restriction does not apply in syntax-check-only - mode, and it is possible to check a file containing multiple - compilation units concatenated together. This is primarily used by - the `gnatchop' utility (*note Renaming Files Using gnatchop::). - -  - File: gnat_ug_vxw.info, Node: Using gcc for Semantic Checking, Next: Compiling Ada 83 Programs, Prev: Using gcc for Syntax Checking, Up: Switches for gcc - - Using `gcc' for Semantic Checking - --------------------------------- - - `-gnatc' - The `c' stands for check. Causes the compiler to operate in - semantic check mode, with full checking for all illegalities - specified in the Ada 95 Reference Manual, but without generation - of any object code (no object file is generated). - - Because dependent files must be accessed, you must follow the GNAT - semantic restrictions on file structuring to operate in this mode: - - * The needed source files must be accessible (*note Search - Paths and the Run-Time Library (RTL)::). - - * Each file must contain only one compilation unit. - - * The file name and unit name must match (*note File Naming - Rules::). - - The output consists of error messages as appropriate. No object - file is generated. An `ALI' file is generated for use in the - context of cross-reference tools, but this file is marked as not - being suitable for binding (since no object file is generated). - The checking corresponds exactly to the notion of legality in the - Ada 95 Reference Manual. - - Any unit can be compiled in semantics-checking-only mode, including - units that would not normally be compiled (subunits, and - specifications where a separate body is present). - -  - File: gnat_ug_vxw.info, Node: Compiling Ada 83 Programs, Next: Character Set Control, Prev: Using gcc for Semantic Checking, Up: Switches for gcc - - Compiling Ada 83 Programs - ------------------------- - - `-gnat83' - Although GNAT is primarily an Ada 95 compiler, it accepts this - switch to specify that an Ada 83 program is to be compiled in - Ada83 mode. If you specify this switch, GNAT rejects most Ada 95 - extensions and applies Ada 83 semantics where this can be done - easily. It is not possible to guarantee this switch does a perfect - job; for example, some subtle tests, such as are found in earlier - ACVC tests (that have been removed from the ACVC suite for Ada - 95), may not compile correctly. However, for most purposes, using - this switch should help to ensure that programs that compile - correctly under the `-gnat83' switch can be ported easily to an - Ada 83 compiler. This is the main use of the switch. - - With few exceptions (most notably the need to use `<>' on - unconstrained generic formal parameters, the use of the new Ada 95 - keywords, and the use of packages with optional bodies), it is not - necessary to use the `-gnat83' switch when compiling Ada 83 - programs, because, with rare exceptions, Ada 95 is upwardly - compatible with Ada 83. This means that a correct Ada 83 program - is usually also a correct Ada 95 program. - -  - File: gnat_ug_vxw.info, Node: Character Set Control, Next: File Naming Control, Prev: Compiling Ada 83 Programs, Up: Switches for gcc - - Character Set Control - --------------------- - - `-gnatiC' - Normally GNAT recognizes the Latin-1 character set in source - program identifiers, as described in the Ada 95 Reference Manual. - This switch causes GNAT to recognize alternate character sets in - identifiers. C is a single character indicating the character - set, as follows: - - `1' - Latin-1 identifiers - - `2' - Latin-2 letters allowed in identifiers - - `3' - Latin-3 letters allowed in identifiers - - `4' - Latin-4 letters allowed in identifiers - - `5' - Latin-5 (Cyrillic) letters allowed in identifiers - - `9' - Latin-9 letters allowed in identifiers - - `p' - IBM PC letters (code page 437) allowed in identifiers - - `8' - IBM PC letters (code page 850) allowed in identifiers - - `f' - Full upper-half codes allowed in identifiers - - `n' - No upper-half codes allowed in identifiers - - `w' - Wide-character codes (that is, codes greater than 255) - allowed in identifiers - - *Note Foreign Language Representation::, for full details on the - implementation of these character sets. - - `-gnatWE' - Specify the method of encoding for wide characters. E is one of - the following: - - `h' - Hex encoding (brackets coding also recognized) - - `u' - Upper half encoding (brackets encoding also recognized) - - `s' - Shift/JIS encoding (brackets encoding also recognized) - - `e' - EUC encoding (brackets encoding also recognized) - - `8' - UTF-8 encoding (brackets encoding also recognized) - - `b' - Brackets encoding only (default value) For full details on - the these encoding methods see *Note Wide Character Encodings::. - Note that brackets coding is always accepted, even if one of the - other options is specified, so for example `-gnatW8' specifies - that both brackets and `UTF-8' encodings will be recognized. The - units that are with'ed directly or indirectly will be scanned - using the specified representation scheme, and so if one of the - non-brackets scheme is used, it must be used consistently - throughout the program. However, since brackets encoding is always - recognized, it may be conveniently used in standard libraries, - allowing these libraries to be used with any of the available - coding schemes. scheme. If no `-gnatW?' parameter is present, - then the default representation is Brackets encoding only. - - Note that the wide character representation that is specified - (explicitly or by default) for the main program also acts as the - default encoding used for Wide_Text_IO files if not specifically - overridden by a WCEM form parameter. - -  - File: gnat_ug_vxw.info, Node: File Naming Control, Next: Subprogram Inlining Control, Prev: Character Set Control, Up: Switches for gcc - - File Naming Control - ------------------- - - `-gnatkN' - Activates file name "krunching". N, a decimal integer in the range - 1-999, indicates the maximum allowable length of a file name (not - including the `.ads' or `.adb' extension). The default is not to - enable file name krunching. - - For the source file naming rules, *Note File Naming Rules::. - -  - File: gnat_ug_vxw.info, Node: Subprogram Inlining Control, Next: Auxiliary Output Control, Prev: File Naming Control, Up: Switches for gcc - - Subprogram Inlining Control - --------------------------- - - `-gnatn' - The `n' here is intended to suggest the first syllable of the word - "inline". GNAT recognizes and processes `Inline' pragmas. - However, for the inlining to actually occur, optimization must be - enabled. To enable inlining across unit boundaries, this is, - inlining a call in one unit of a subprogram declared in a - `with''ed unit, you must also specify this switch. In the absence - of this switch, GNAT does not attempt inlining across units and - does not need to access the bodies of subprograms for which - `pragma Inline' is specified if they are not in the current unit. - - If you specify this switch the compiler will access these bodies, - creating an extra source dependency for the resulting object file, - and where possible, the call will be inlined. For further details - on when inlining is possible see *Note Inlining of Subprograms::. - - `-gnatN' - The front end inlining activated by this switch is generally more - extensive, and quite often more effective than the standard - `-gnatn' inlining mode. It will also generate additional - dependencies. - -  - File: gnat_ug_vxw.info, Node: Auxiliary Output Control, Next: Debugging Control, Prev: Subprogram Inlining Control, Up: Switches for gcc - - Auxiliary Output Control - ------------------------ - - `-gnatt' - Causes GNAT to write the internal tree for a unit to a file (with - the extension `.adt'. This not normally required, but is used by - separate analysis tools. Typically these tools do the necessary - compilations automatically, so you should not have to specify this - switch in normal operation. - - `-gnatu' - Print a list of units required by this compilation on `stdout'. - The listing includes all units on which the unit being compiled - depends either directly or indirectly. - - `-pass-exit-codes' - If this switch is not used, the exit code returned by `gcc' when - compiling multiple files indicates whether all source files have - been successfully used to generate object files or not. - - When `-pass-exit-codes' is used, `gcc' exits with an extended exit - status and allows an integrated development environment to better - react to a compilation failure. Those exit status are: - - 5 - There was an error in at least one source file. - - 3 - At least one source file did not generate an object file. - - 2 - The compiler died unexpectedly (internal error for example). - - 0 - An object file has been generated for every source file. - -  - File: gnat_ug_vxw.info, Node: Debugging Control, Next: Units to Sources Mapping Files, Prev: Auxiliary Output Control, Up: Switches for gcc - - Debugging Control - ----------------- - - `-gnatdX' - Activate internal debugging switches. X is a letter or digit, or - string of letters or digits, which specifies the type of debugging - outputs desired. Normally these are used only for internal - development or system debugging purposes. You can find full - documentation for these switches in the body of the `Debug' unit - in the compiler source file `debug.adb'. - - `-gnatG' - This switch causes the compiler to generate auxiliary output - containing a pseudo-source listing of the generated expanded code. - Like most Ada compilers, GNAT works by first transforming the high - level Ada code into lower level constructs. For example, tasking - operations are transformed into calls to the tasking run-time - routines. A unique capability of GNAT is to list this expanded - code in a form very close to normal Ada source. This is very - useful in understanding the implications of various Ada usage on - the efficiency of the generated code. There are many cases in Ada - (e.g. the use of controlled types), where simple Ada statements can - generate a lot of run-time code. By using `-gnatG' you can identify - these cases, and consider whether it may be desirable to modify - the coding approach to improve efficiency. - - The format of the output is very similar to standard Ada source, - and is easily understood by an Ada programmer. The following - special syntactic additions correspond to low level features used - in the generated code that do not have any exact analogies in pure - Ada source form. The following is a partial list of these special - constructions. See the specification of package `Sprint' in file - `sprint.ads' for a full list. - - `new XXX [storage_pool = YYY]' - Shows the storage pool being used for an allocator. - - `at end PROCEDURE-NAME;' - Shows the finalization (cleanup) procedure for a scope. - - `(if EXPR then EXPR else EXPR)' - Conditional expression equivalent to the `x?y:z' construction - in C. - - `TARGET^(SOURCE)' - A conversion with floating-point truncation instead of - rounding. - - `TARGET?(SOURCE)' - A conversion that bypasses normal Ada semantic checking. In - particular enumeration types and fixed-point types are - treated simply as integers. - - `TARGET?^(SOURCE)' - Combines the above two cases. - - `X #/ Y' - `X #mod Y' - `X #* Y' - `X #rem Y' - A division or multiplication of fixed-point values which are - treated as integers without any kind of scaling. - - `free EXPR [storage_pool = XXX]' - Shows the storage pool associated with a `free' statement. - - `freeze TYPENAME [ACTIONS]' - Shows the point at which TYPENAME is frozen, with possible - associated actions to be performed at the freeze point. - - `reference ITYPE' - Reference (and hence definition) to internal type ITYPE. - - `FUNCTION-NAME! (ARG, ARG, ARG)' - Intrinsic function call. - - `LABELNAME : label' - Declaration of label LABELNAME. - - `EXPR && EXPR && EXPR ... && EXPR' - A multiple concatenation (same effect as EXPR & EXPR & EXPR, - but handled more efficiently). - - `[constraint_error]' - Raise the `Constraint_Error' exception. - - `EXPRESSION'reference' - A pointer to the result of evaluating EXPRESSION. - - `TARGET-TYPE!(SOURCE-EXPRESSION)' - An unchecked conversion of SOURCE-EXPRESSION to TARGET-TYPE. - - `[NUMERATOR/DENOMINATOR]' - Used to represent internal real literals (that) have no exact - representation in base 2-16 (for example, the result of - compile time evaluation of the expression 1.0/27.0). - - `-gnatD' - This switch is used in conjunction with `-gnatG' to cause the - expanded source, as described above to be written to files - with names `xxx.dg', where `xxx' is the normal file name, for - example, if the source file name is `hello.adb', then a file - `hello.adb.dg' will be written. The debugging information - generated by the `gcc' `-g' switch will refer to the generated - `xxx.dg' file. This allows you to do source level debugging - using the generated code which is sometimes useful for - complex code, for example to find out exactly which part of a - complex construction raised an exception. This switch also - suppress generation of cross-reference information (see - -gnatx). - - `-gnatC' - In the generated debugging information, and also in the case - of long external names, the compiler uses a compression - mechanism if the name is very long. This compression method - uses a checksum, and avoids trouble on some operating systems - which have difficulty with very long names. The `-gnatC' - switch forces this compression approach to be used on all - external names and names in the debugging information tables. - This reduces the size of the generated executable, at the - expense of making the naming scheme more complex. The - compression only affects the qualification of the name. Thus - a name in the source: - - Very_Long_Package.Very_Long_Inner_Package.Var - - would normally appear in these tables as: - - very_long_package__very_long_inner_package__var - - but if the `-gnatC' switch is used, then the name appears as - - XCb7e0c705__var - - Here b7e0c705 is a compressed encoding of the qualification - prefix. The GNAT Ada aware version of GDB understands these - encoded prefixes, so if this debugger is used, the encoding - is largely hidden from the user of the compiler. - - `-gnatR[0|1|2|3][s]' - This switch controls output from the compiler of a listing showing - representation information for declared types and objects. For - `-gnatR0', no information is output (equivalent to omitting the - `-gnatR' switch). For `-gnatR1' (which is the default, so `-gnatR' - with no parameter has the same effect), size and alignment - information is listed for declared array and record types. For - `-gnatR2', size and alignment information is listed for all - expression information for values that are computed at run time for - variant records. These symbolic expressions have a mostly obvious - format with #n being used to represent the value of the n'th - discriminant. See source files `repinfo.ads/adb' in the `GNAT' - sources for full detalis on the format of `-gnatR3' output. If the - switch is followed by an s (e.g. `-gnatR2s'), then the output is - to a file with the name `file.rep' where file is the name of the - corresponding source file. - - `-gnatx' - Normally the compiler generates full cross-referencing information - in the `ALI' file. This information is used by a number of tools, - including `gnatfind' and `gnatxref'. The -gnatx switch suppresses - this information. This saves some space and may slightly speed up - compilation, but means that these tools cannot be used. - -  - File: gnat_ug_vxw.info, Node: Units to Sources Mapping Files, Prev: Debugging Control, Up: Switches for gcc - - Units to Sources Mapping Files - ------------------------------ - - `-gnatemPATH' - A mapping file is a way to communicate to the compiler two - mappings: from unit names to file names (without any directory - information) and from file names to path names (with full - directory information). These mappings are used by the compiler to - short-circuit the path search. - - A mapping file is a sequence of sets of three lines. In each set, - the first line is the unit name, in lower case, with "%s" appended - for specifications and "%b" appended for bodies; the second line - is the file name; and the third line is the path name. - - Example: - main%b - main.2.ada - /gnat/project1/sources/main.2.ada - - When the switch `-gnatem' is specified, the compiler will create - in memory the two mappings from the specified file. If there is - any problem (non existent file, truncated file or duplicate - entries), no mapping will be created. - - Several `-gnatem' switches may be specified; however, only the last - one on the command line will be taken into account. - - When using a project file, `gnatmake' create a temporary mapping - file and communicates it to the compiler using this switch. - -  - File: gnat_ug_vxw.info, Node: Search Paths and the Run-Time Library (RTL), Next: Order of Compilation Issues, Prev: Switches for gcc, Up: Compiling Using gcc - - Search Paths and the Run-Time Library (RTL) - =========================================== - - With the GNAT source-based library system, the compiler must be able to - find source files for units that are needed by the unit being compiled. - Search paths are used to guide this process. - - The compiler compiles one source file whose name must be given - explicitly on the command line. In other words, no searching is done - for this file. To find all other source files that are needed (the most - common being the specs of units), the compiler examines the following - directories, in the following order: - - 1. The directory containing the source file of the main unit being - compiled (the file name on the command line). - - 2. Each directory named by an `-I' switch given on the `gcc' command - line, in the order given. - - 3. Each of the directories listed in the value of the - `ADA_INCLUDE_PATH' environment variable. Construct this value - exactly as the `PATH' environment variable: a list of directory - names separated by colons (semicolons when working with the NT - version). - - 4. The content of the "ada_source_path" file which is part of the GNAT - installation tree and is used to store standard libraries such as - the GNAT Run Time Library (RTL) source files. *Note Installing an - Ada Library:: - - Specifying the switch `-I-' inhibits the use of the directory - containing the source file named in the command line. You can still - have this directory on your search path, but in this case it must be - explicitly requested with a `-I' switch. - - Specifying the switch `-nostdinc' inhibits the search of the default - location for the GNAT Run Time Library (RTL) source files. - - The compiler outputs its object files and ALI files in the current - working directory. Caution: The object file can be redirected with the - `-o' switch; however, `gcc' and `gnat1' have not been coordinated on - this so the ALI file will not go to the right place. Therefore, you - should avoid using the `-o' switch. - - The packages `Ada', `System', and `Interfaces' and their children - make up the GNAT RTL, together with the simple `System.IO' package used - in the "Hello World" example. The sources for these units are needed by - the compiler and are kept together in one directory. Not all of the - bodies are needed, but all of the sources are kept together anyway. In - a normal installation, you need not specify these directory names when - compiling or binding. Either the environment variables or the built-in - defaults cause these files to be found. - - In addition to the language-defined hierarchies (System, Ada and - Interfaces), the GNAT distribution provides a fourth hierarchy, - consisting of child units of GNAT. This is a collection of generally - useful routines. See the GNAT Reference Manual for further details. - - Besides simplifying access to the RTL, a major use of search paths is - in compiling sources from multiple directories. This can make - development environments much more flexible. - -  - File: gnat_ug_vxw.info, Node: Order of Compilation Issues, Next: Examples, Prev: Search Paths and the Run-Time Library (RTL), Up: Compiling Using gcc - - Order of Compilation Issues - =========================== - - If, in our earlier example, there was a spec for the `hello' procedure, - it would be contained in the file `hello.ads'; yet this file would not - have to be explicitly compiled. This is the result of the model we - chose to implement library management. Some of the consequences of this - model are as follows: - - * There is no point in compiling specs (except for package specs - with no bodies) because these are compiled as needed by clients. If - you attempt a useless compilation, you will receive an error - message. It is also useless to compile subunits because they are - compiled as needed by the parent. - - * There are no order of compilation requirements: performing a - compilation never obsoletes anything. The only way you can obsolete - something and require recompilations is to modify one of the - source files on which it depends. - - * There is no library as such, apart from the ALI files (*note The - Ada Library Information Files::, for information on the format of - these files). For now we find it convenient to create separate ALI - files, but eventually the information therein may be incorporated - into the object file directly. - - * When you compile a unit, the source files for the specs of all - units that it `with''s, all its subunits, and the bodies of any - generics it instantiates must be available (reachable by the - search-paths mechanism described above), or you will receive a - fatal error message. - -  - File: gnat_ug_vxw.info, Node: Examples, Prev: Order of Compilation Issues, Up: Compiling Using gcc - - Examples - ======== - - The following are some typical Ada compilation command line examples: - - `$ gcc -c xyz.adb' - Compile body in file `xyz.adb' with all default options. - - `$ gcc -c -O2 -gnata xyz-def.adb' - Compile the child unit package in file `xyz-def.adb' with extensive - optimizations, and pragma `Assert'/`Debug' statements enabled. - - `$ gcc -c -gnatc abc-def.adb' - Compile the subunit in file `abc-def.adb' in semantic-checking-only - mode. - -  - File: gnat_ug_vxw.info, Node: Binding Using gnatbind, Next: Linking Using gnatlink, Prev: Compiling Using gcc, Up: Top - - Binding Using `gnatbind' - ************************ - - * Menu: - - * Running gnatbind:: - * Generating the Binder Program in C:: - * Consistency-Checking Modes:: - * Binder Error Message Control:: - * Elaboration Control:: - * Output Control:: - * Binding with Non-Ada Main Programs:: - * Binding Programs with No Main Subprogram:: - * Summary of Binder Switches:: - * Command-Line Access:: - * Search Paths for gnatbind:: - * Examples of gnatbind Usage:: - - This chapter describes the GNAT binder, `gnatbind', which is used to - bind compiled GNAT objects. The `gnatbind' program performs four - separate functions: - - 1. Checks that a program is consistent, in accordance with the rules - in Chapter 10 of the Ada 95 Reference Manual. In particular, error - messages are generated if a program uses inconsistent versions of a - given unit. - - 2. Checks that an acceptable order of elaboration exists for the - program and issues an error message if it cannot find an order of - elaboration that satisfies the rules in Chapter 10 of the Ada 95 - Language Manual. - - 3. Generates a main program incorporating the given elaboration order. - This program is a small Ada package (body and spec) that must be - subsequently compiled using the GNAT compiler. The necessary - compilation step is usually performed automatically by `gnatlink'. - The two most important functions of this program are to call the - elaboration routines of units in an appropriate order and to call - the main program. - - 4. Determines the set of object files required by the given main - program. This information is output in the forms of comments in - the generated program, to be read by the `gnatlink' utility used - to link the Ada application. - -  - File: gnat_ug_vxw.info, Node: Running gnatbind, Next: Generating the Binder Program in C, Up: Binding Using gnatbind - - Running `gnatbind' - ================== - - The form of the `gnatbind' command is - - $ gnatbind [SWITCHES] MAINPROG[.ali] [SWITCHES] - - where MAINPROG.adb is the Ada file containing the main program unit - body. If no switches are specified, `gnatbind' constructs an Ada - package in two files which names are `b~ADA_MAIN.ads', and - `b~ADA_MAIN.adb'. For example, if given the parameter `hello.ali', for - a main program contained in file `hello.adb', the binder output files - would be `b~hello.ads' and `b~hello.adb'. - - When doing consistency checking, the binder takes into consideration - any source files it can locate. For example, if the binder determines - that the given main program requires the package `Pack', whose `.ali' - file is `pack.ali' and whose corresponding source spec file is - `pack.ads', it attempts to locate the source file `pack.ads' (using the - same search path conventions as previously described for the `gcc' - command). If it can locate this source file, it checks that the time - stamps or source checksums of the source and its references to in `ali' - files match. In other words, any `ali' files that mentions this spec - must have resulted from compiling this version of the source file (or - in the case where the source checksums match, a version close enough - that the difference does not matter). - - The effect of this consistency checking, which includes source - files, is that the binder ensures that the program is consistent with - the latest version of the source files that can be located at bind - time. Editing a source file without compiling files that depend on the - source file cause error messages to be generated by the binder. - - For example, suppose you have a main program `hello.adb' and a - package `P', from file `p.ads' and you perform the following steps: - - 1. Enter `gcc -c hello.adb' to compile the main program. - - 2. Enter `gcc -c p.ads' to compile package `P'. - - 3. Edit file `p.ads'. - - 4. Enter `gnatbind hello'. - - At this point, the file `p.ali' contains an out-of-date time stamp - because the file `p.ads' has been edited. The attempt at binding fails, - and the binder generates the following error messages: - - error: "hello.adb" must be recompiled ("p.ads" has been modified) - error: "p.ads" has been modified and must be recompiled - - Now both files must be recompiled as indicated, and then the bind can - succeed, generating a main program. You need not normally be concerned - with the contents of this file, but it is similar to the following which - is the binder file generated for a simple "hello world" program. - - -- The package is called Ada_Main unless this name is actually used - -- as a unit name in the partition, in which case some other unique - -- name is used. - - with System; - package ada_main is - - Elab_Final_Code : Integer; - pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code"); - - -- The main program saves the parameters (argument count, - -- argument values, environment pointer) in global variables - -- for later access by other units including - -- Ada.Command_Line. - - gnat_argc : Integer; - gnat_argv : System.Address; - gnat_envp : System.Address; - - -- The actual variables are stored in a library routine. This - -- is useful for some shared library situations, where there - -- are problems if variables are not in the library. - - pragma Import (C, gnat_argc); - pragma Import (C, gnat_argv); - pragma Import (C, gnat_envp); - - -- The exit status is similarly an external location - - gnat_exit_status : Integer; - pragma Import (C, gnat_exit_status); - - GNAT_Version : constant String := - "GNAT Version: 3.15w (20010315)"; - pragma Export (C, GNAT_Version, "__gnat_version"); - - -- This is the generated adafinal routine that performs - -- finalization at the end of execution. In the case where - -- Ada is the main program, this main program makes a call - -- to adafinal at program termination. - - procedure adafinal; - pragma Export (C, adafinal, "adafinal"); - - -- This is the generated adainit routine that performs - -- initialization at the start of execution. In the case - -- where Ada is the main program, this main program makes - -- a call to adainit at program startup. - - procedure adainit; - pragma Export (C, adainit, "adainit"); - - -- This routine is called at the start of execution. It is - -- a dummy routine that is used by the debugger to breakpoint - -- at the start of execution. - - procedure Break_Start; - pragma Import (C, Break_Start, "__gnat_break_start"); - - -- This is the actual generated main program (it would be - -- suppressed if the no main program switch were used). As - -- required by standard system conventions, this program has - -- the external name main. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer; - pragma Export (C, main, "main"); - - -- The following set of constants give the version - -- identification values for every unit in the bound - -- partition. This identification is computed from all - -- dependent semantic units, and corresponds to the - -- string that would be returned by use of the - -- Body_Version or Version attributes. - - type Version_32 is mod 2 ** 32; - u00001 : constant Version_32 := 16#7880BEB3#; - u00002 : constant Version_32 := 16#0D24CBD0#; - u00003 : constant Version_32 := 16#3283DBEB#; - u00004 : constant Version_32 := 16#2359F9ED#; - u00005 : constant Version_32 := 16#664FB847#; - u00006 : constant Version_32 := 16#68E803DF#; - u00007 : constant Version_32 := 16#5572E604#; - u00008 : constant Version_32 := 16#46B173D8#; - u00009 : constant Version_32 := 16#156A40CF#; - u00010 : constant Version_32 := 16#033DABE0#; - u00011 : constant Version_32 := 16#6AB38FEA#; - u00012 : constant Version_32 := 16#22B6217D#; - u00013 : constant Version_32 := 16#68A22947#; - u00014 : constant Version_32 := 16#18CC4A56#; - u00015 : constant Version_32 := 16#08258E1B#; - u00016 : constant Version_32 := 16#367D5222#; - u00017 : constant Version_32 := 16#20C9ECA4#; - u00018 : constant Version_32 := 16#50D32CB6#; - u00019 : constant Version_32 := 16#39A8BB77#; - u00020 : constant Version_32 := 16#5CF8FA2B#; - u00021 : constant Version_32 := 16#2F1EB794#; - u00022 : constant Version_32 := 16#31AB6444#; - u00023 : constant Version_32 := 16#1574B6E9#; - u00024 : constant Version_32 := 16#5109C189#; - u00025 : constant Version_32 := 16#56D770CD#; - u00026 : constant Version_32 := 16#02F9DE3D#; - u00027 : constant Version_32 := 16#08AB6B2C#; - u00028 : constant Version_32 := 16#3FA37670#; - u00029 : constant Version_32 := 16#476457A0#; - u00030 : constant Version_32 := 16#731E1B6E#; - u00031 : constant Version_32 := 16#23C2E789#; - u00032 : constant Version_32 := 16#0F1BD6A1#; - u00033 : constant Version_32 := 16#7C25DE96#; - u00034 : constant Version_32 := 16#39ADFFA2#; - u00035 : constant Version_32 := 16#571DE3E7#; - u00036 : constant Version_32 := 16#5EB646AB#; - u00037 : constant Version_32 := 16#4249379B#; - u00038 : constant Version_32 := 16#0357E00A#; - u00039 : constant Version_32 := 16#3784FB72#; - u00040 : constant Version_32 := 16#2E723019#; - u00041 : constant Version_32 := 16#623358EA#; - u00042 : constant Version_32 := 16#107F9465#; - u00043 : constant Version_32 := 16#6843F68A#; - u00044 : constant Version_32 := 16#63305874#; - u00045 : constant Version_32 := 16#31E56CE1#; - u00046 : constant Version_32 := 16#02917970#; - u00047 : constant Version_32 := 16#6CCBA70E#; - u00048 : constant Version_32 := 16#41CD4204#; - u00049 : constant Version_32 := 16#572E3F58#; - u00050 : constant Version_32 := 16#20729FF5#; - u00051 : constant Version_32 := 16#1D4F93E8#; - u00052 : constant Version_32 := 16#30B2EC3D#; - u00053 : constant Version_32 := 16#34054F96#; - u00054 : constant Version_32 := 16#5A199860#; - u00055 : constant Version_32 := 16#0E7F912B#; - u00056 : constant Version_32 := 16#5760634A#; - u00057 : constant Version_32 := 16#5D851835#; - - -- The following Export pragmas export the version numbers - -- with symbolic names ending in B (for body) or S - -- (for spec) so that they can be located in a link. The - -- information provided here is sufficient to track down - -- the exact versions of units used in a given build. - - pragma Export (C, u00001, "helloB"); - pragma Export (C, u00002, "system__standard_libraryB"); - pragma Export (C, u00003, "system__standard_libraryS"); - pragma Export (C, u00004, "adaS"); - pragma Export (C, u00005, "ada__text_ioB"); - pragma Export (C, u00006, "ada__text_ioS"); - pragma Export (C, u00007, "ada__exceptionsB"); - pragma Export (C, u00008, "ada__exceptionsS"); - pragma Export (C, u00009, "gnatS"); - pragma Export (C, u00010, "gnat__heap_sort_aB"); - pragma Export (C, u00011, "gnat__heap_sort_aS"); - pragma Export (C, u00012, "systemS"); - pragma Export (C, u00013, "system__exception_tableB"); - pragma Export (C, u00014, "system__exception_tableS"); - pragma Export (C, u00015, "gnat__htableB"); - pragma Export (C, u00016, "gnat__htableS"); - pragma Export (C, u00017, "system__exceptionsS"); - pragma Export (C, u00018, "system__machine_state_operationsB"); - pragma Export (C, u00019, "system__machine_state_operationsS"); - pragma Export (C, u00020, "system__machine_codeS"); - pragma Export (C, u00021, "system__storage_elementsB"); - pragma Export (C, u00022, "system__storage_elementsS"); - pragma Export (C, u00023, "system__secondary_stackB"); - pragma Export (C, u00024, "system__secondary_stackS"); - pragma Export (C, u00025, "system__parametersB"); - pragma Export (C, u00026, "system__parametersS"); - pragma Export (C, u00027, "system__soft_linksB"); - pragma Export (C, u00028, "system__soft_linksS"); - pragma Export (C, u00029, "system__stack_checkingB"); - pragma Export (C, u00030, "system__stack_checkingS"); - pragma Export (C, u00031, "system__tracebackB"); - pragma Export (C, u00032, "system__tracebackS"); - pragma Export (C, u00033, "ada__streamsS"); - pragma Export (C, u00034, "ada__tagsB"); - pragma Export (C, u00035, "ada__tagsS"); - pragma Export (C, u00036, "system__string_opsB"); - pragma Export (C, u00037, "system__string_opsS"); - pragma Export (C, u00038, "interfacesS"); - pragma Export (C, u00039, "interfaces__c_streamsB"); - pragma Export (C, u00040, "interfaces__c_streamsS"); - pragma Export (C, u00041, "system__file_ioB"); - pragma Export (C, u00042, "system__file_ioS"); - pragma Export (C, u00043, "ada__finalizationB"); - pragma Export (C, u00044, "ada__finalizationS"); - pragma Export (C, u00045, "system__finalization_rootB"); - pragma Export (C, u00046, "system__finalization_rootS"); - pragma Export (C, u00047, "system__finalization_implementationB"); - pragma Export (C, u00048, "system__finalization_implementationS"); - pragma Export (C, u00049, "system__string_ops_concat_3B"); - pragma Export (C, u00050, "system__string_ops_concat_3S"); - pragma Export (C, u00051, "system__stream_attributesB"); - pragma Export (C, u00052, "system__stream_attributesS"); - pragma Export (C, u00053, "ada__io_exceptionsS"); - pragma Export (C, u00054, "system__unsigned_typesS"); - pragma Export (C, u00055, "system__file_control_blockS"); - pragma Export (C, u00056, "ada__finalization__list_controllerB"); - pragma Export (C, u00057, "ada__finalization__list_controllerS"); - - -- BEGIN ELABORATION ORDER - -- ada (spec) - -- gnat (spec) - -- gnat.heap_sort_a (spec) - -- gnat.heap_sort_a (body) - -- gnat.htable (spec) - -- gnat.htable (body) - -- interfaces (spec) - -- system (spec) - -- system.machine_code (spec) - -- system.parameters (spec) - -- system.parameters (body) - -- interfaces.c_streams (spec) - -- interfaces.c_streams (body) - -- system.standard_library (spec) - -- ada.exceptions (spec) - -- system.exception_table (spec) - -- system.exception_table (body) - -- ada.io_exceptions (spec) - -- system.exceptions (spec) - -- system.storage_elements (spec) - -- system.storage_elements (body) - -- system.machine_state_operations (spec) - -- system.machine_state_operations (body) - -- system.secondary_stack (spec) - -- system.stack_checking (spec) - -- system.soft_links (spec) - -- system.soft_links (body) - -- system.stack_checking (body) - -- system.secondary_stack (body) - -- system.standard_library (body) - -- system.string_ops (spec) - -- system.string_ops (body) - -- ada.tags (spec) - -- ada.tags (body) - -- ada.streams (spec) - -- system.finalization_root (spec) - -- system.finalization_root (body) - -- system.string_ops_concat_3 (spec) - -- system.string_ops_concat_3 (body) - -- system.traceback (spec) - -- system.traceback (body) - -- ada.exceptions (body) - -- system.unsigned_types (spec) - -- system.stream_attributes (spec) - -- system.stream_attributes (body) - -- system.finalization_implementation (spec) - -- system.finalization_implementation (body) - -- ada.finalization (spec) - -- ada.finalization (body) - -- ada.finalization.list_controller (spec) - -- ada.finalization.list_controller (body) - -- system.file_control_block (spec) - -- system.file_io (spec) - -- system.file_io (body) - -- ada.text_io (spec) - -- ada.text_io (body) - -- hello (body) - -- END ELABORATION ORDER - - end ada_main; - - -- The following source file name pragmas allow the generated file - -- names to be unique for different main programs. They are needed - -- since the package name will always be Ada_Main. - - pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads"); - pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb"); - - -- Generated package body for Ada_Main starts here - - package body ada_main is - - -- The actual finalization is performed by calling the - -- library routine in System.Standard_Library.Adafinal - - procedure Do_Finalize; - pragma Import (C, Do_Finalize, "system__standard_library__adafinal"); - - ------------- - -- adainit -- - ------------- - - procedure adainit is - - -- These booleans are set to True once the associated unit has - -- been elaborated. It is also used to avoid elaborating the - -- same unit twice. - - E040 : Boolean; pragma Import (Ada, E040, "interfaces__c_streams_E"); - E008 : Boolean; pragma Import (Ada, E008, "ada__exceptions_E"); - E014 : Boolean; pragma Import (Ada, E014, "system__exception_table_E"); - E053 : Boolean; pragma Import (Ada, E053, "ada__io_exceptions_E"); - E017 : Boolean; pragma Import (Ada, E017, "system__exceptions_E"); - E024 : Boolean; pragma Import (Ada, E024, "system__secondary_stack_E"); - E030 : Boolean; pragma Import (Ada, E030, "system__stack_checking_E"); - E028 : Boolean; pragma Import (Ada, E028, "system__soft_links_E"); - E035 : Boolean; pragma Import (Ada, E035, "ada__tags_E"); - E033 : Boolean; pragma Import (Ada, E033, "ada__streams_E"); - E046 : Boolean; pragma Import (Ada, E046, "system__finalization_root_E"); - E048 : Boolean; pragma Import (Ada, E048, "system__finalization_implementation_E"); - E044 : Boolean; pragma Import (Ada, E044, "ada__finalization_E"); - E057 : Boolean; pragma Import (Ada, E057, "ada__finalization__list_controller_E"); - E055 : Boolean; pragma Import (Ada, E055, "system__file_control_block_E"); - E042 : Boolean; pragma Import (Ada, E042, "system__file_io_E"); - E006 : Boolean; pragma Import (Ada, E006, "ada__text_io_E"); - - -- Set_Globals is a library routine that stores away the - -- value of the indicated set of global values in global - -- variables within the library. - - procedure Set_Globals - (Main_Priority : Integer; - Time_Slice_Value : Integer; - WC_Encoding : Character; - Locking_Policy : Character; - Queuing_Policy : Character; - Task_Dispatching_Policy : Character; - Adafinal : System.Address; - Unreserve_All_Interrupts : Integer; - Exception_Tracebacks : Integer); - pragma Import (C, Set_Globals, "__gnat_set_globals"); - - -- SDP_Table_Build is a library routine used to build the - -- exception tables. See unit Ada.Exceptions in files - -- a-except.ads/adb for full details of how zero cost - -- exception handling works. This procedure, the call to - -- it, and the two following tables are all omitted if the - -- build is in longjmp/setjump exception mode. - - procedure SDP_Table_Build - (SDP_Addresses : System.Address; - SDP_Count : Natural; - Elab_Addresses : System.Address; - Elab_Addr_Count : Natural); - pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build"); - - -- Table of Unit_Exception_Table addresses. Used for zero - -- cost exception handling to build the top level table. - - ST : aliased constant array (1 .. 23) of System.Address := ( - Hello'UET_Address, - Ada.Text_Io'UET_Address, - Ada.Exceptions'UET_Address, - Gnat.Heap_Sort_A'UET_Address, - System.Exception_Table'UET_Address, - System.Machine_State_Operations'UET_Address, - System.Secondary_Stack'UET_Address, - System.Parameters'UET_Address, - System.Soft_Links'UET_Address, - System.Stack_Checking'UET_Address, - System.Traceback'UET_Address, - Ada.Streams'UET_Address, - Ada.Tags'UET_Address, - System.String_Ops'UET_Address, - Interfaces.C_Streams'UET_Address, - System.File_Io'UET_Address, - Ada.Finalization'UET_Address, - System.Finalization_Root'UET_Address, - System.Finalization_Implementation'UET_Address, - System.String_Ops_Concat_3'UET_Address, - System.Stream_Attributes'UET_Address, - System.File_Control_Block'UET_Address, - Ada.Finalization.List_Controller'UET_Address); - - -- Table of addresses of elaboration routines. Used for - -- zero cost exception handling to make sure these - -- addresses are included in the top level procedure - -- address table. - - EA : aliased constant array (1 .. 23) of System.Address := ( - adainit'Code_Address, - Do_Finalize'Code_Address, - Ada.Exceptions'Elab_Spec'Address, - System.Exceptions'Elab_Spec'Address, - Interfaces.C_Streams'Elab_Spec'Address, - System.Exception_Table'Elab_Body'Address, - Ada.Io_Exceptions'Elab_Spec'Address, - System.Stack_Checking'Elab_Spec'Address, - System.Soft_Links'Elab_Body'Address, - System.Secondary_Stack'Elab_Body'Address, - Ada.Tags'Elab_Spec'Address, - Ada.Tags'Elab_Body'Address, - Ada.Streams'Elab_Spec'Address, - System.Finalization_Root'Elab_Spec'Address, - Ada.Exceptions'Elab_Body'Address, - System.Finalization_Implementation'Elab_Spec'Address, - System.Finalization_Implementation'Elab_Body'Address, - Ada.Finalization'Elab_Spec'Address, - Ada.Finalization.List_Controller'Elab_Spec'Address, - System.File_Control_Block'Elab_Spec'Address, - System.File_Io'Elab_Body'Address, - Ada.Text_Io'Elab_Spec'Address, - Ada.Text_Io'Elab_Body'Address); - - -- Start of processing for adainit - - begin - - -- Call SDP_Table_Build to build the top level procedure - -- table for zero cost exception handling (omitted in - -- longjmp/setjump mode). - - SDP_Table_Build (ST'Address, 23, EA'Address, 23); - - -- Call Set_Globals to record various information for - -- this partition. The values are derived by the binder - -- from information stored in the ali files by the compiler. - - Set_Globals - (Main_Priority => -1, - -- Priority of main program, -1 if no pragma Priority used - - Time_Slice_Value => -1, - -- Time slice from Time_Slice pragma, -1 if none used - - WC_Encoding => 'b', - -- Wide_Character encoding used, default is brackets - - Locking_Policy => ' ', - -- Locking_Policy used, default of space means not - -- specified, otherwise it is the first character of - -- the policy name. - - Queuing_Policy => ' ', - -- Queuing_Policy used, default of space means not - -- specified, otherwise it is the first character of - -- the policy name. - - Task_Dispatching_Policy => ' ', - -- Task_Dispatching_Policy used, default of space means - -- not specified, otherwise first character of the - -- policy name. - - Adafinal => System.Null_Address, - -- Address of Adafinal routine, not used anymore - - Unreserve_All_Interrupts => 0, - -- Set true if pragma Unreserve_All_Interrupts was used - - Exception_Tracebacks => 0); - -- Indicates if exception tracebacks are enabled - - Elab_Final_Code := 1; - - -- Now we have the elaboration calls for all units in the partition. - -- The Elab_Spec and Elab_Body attributes generate references to the - -- implicit elaboration procedures generated by the compiler for - -- each unit that requires elaboration. - - if not E040 then - Interfaces.C_Streams'Elab_Spec; - end if; - E040 := True; - if not E008 then - Ada.Exceptions'Elab_Spec; - end if; - if not E014 then - System.Exception_Table'Elab_Body; - E014 := True; - end if; - if not E053 then - Ada.Io_Exceptions'Elab_Spec; - E053 := True; - end if; - if not E017 then - System.Exceptions'Elab_Spec; - E017 := True; - end if; - if not E030 then - System.Stack_Checking'Elab_Spec; - end if; - if not E028 then - System.Soft_Links'Elab_Body; - E028 := True; - end if; - E030 := True; - if not E024 then - System.Secondary_Stack'Elab_Body; - E024 := True; - end if; - if not E035 then - Ada.Tags'Elab_Spec; - end if; - if not E035 then - Ada.Tags'Elab_Body; - E035 := True; - end if; - if not E033 then - Ada.Streams'Elab_Spec; - E033 := True; - end if; - if not E046 then - System.Finalization_Root'Elab_Spec; - end if; - E046 := True; - if not E008 then - Ada.Exceptions'Elab_Body; - E008 := True; - end if; - if not E048 then - System.Finalization_Implementation'Elab_Spec; - end if; - if not E048 then - System.Finalization_Implementation'Elab_Body; - E048 := True; - end if; - if not E044 then - Ada.Finalization'Elab_Spec; - end if; - E044 := True; - if not E057 then - Ada.Finalization.List_Controller'Elab_Spec; - end if; - E057 := True; - if not E055 then - System.File_Control_Block'Elab_Spec; - E055 := True; - end if; - if not E042 then - System.File_Io'Elab_Body; - E042 := True; - end if; - if not E006 then - Ada.Text_Io'Elab_Spec; - end if; - if not E006 then - Ada.Text_Io'Elab_Body; - E006 := True; - end if; - - Elab_Final_Code := 0; - end adainit; - - -------------- - -- adafinal -- - -------------- - - procedure adafinal is - begin - Do_Finalize; - end adafinal; - - ---------- - -- main -- - ---------- - - -- main is actually a function, as in the ANSI C standard, - -- defined to return the exit status. The three parameters - -- are the argument count, argument values and environment - -- pointer. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer - is - -- The initialize routine performs low level system - -- initialization using a standard library routine which - -- sets up signal handling and performs any other - -- required setup. The routine can be found in file - -- a-init.c. - - procedure initialize; - pragma Import (C, initialize, "__gnat_initialize"); - - -- The finalize routine performs low level system - -- finalization using a standard library routine. The - -- routine is found in file a-final.c and in the standard - -- distribution is a dummy routine that does nothing, so - -- really this is a hook for special user finalization. - - procedure finalize; - pragma Import (C, finalize, "__gnat_finalize"); - - -- We get to the main program of the partition by using - -- pragma Import because if we try to with the unit and - -- call it Ada style, then not only do we waste time - -- recompiling it, but also, we don't really know the right - -- switches (e.g. identifier character set) to be used - -- to compile it. - - procedure Ada_Main_Program; - pragma Import (Ada, Ada_Main_Program, "_ada_hello"); - - -- Start of processing for main - - begin - -- Save global variables - - gnat_argc := argc; - gnat_argv := argv; - gnat_envp := envp; - - -- Call low level system initialization - - Initialize; - - -- Call our generated Ada initialization routine - - adainit; - - -- This is the point at which we want the debugger to get - -- control - - Break_Start; - - -- Now we call the main program of the partition - - Ada_Main_Program; - - -- Perform Ada finalization - - adafinal; - - -- Perform low level system finalization - - Finalize; - - -- Return the proper exit status - return (gnat_exit_status); - end; - - -- This section is entirely comments, so it has no effect on the - -- compilation of the Ada_Main package. It provides the list of - -- object files and linker options, as well as some standard - -- libraries needed for the link. The gnatlink utility parses - -- this b~hello.adb file to read these comment lines to generate - -- the appropriate command line arguments for the call to the - -- system linker. The BEGIN/END lines are used for sentinels for - -- this parsing operation. - - -- The exact file names will of course depend on the environment, - -- host/target and location of files on the host system. - - -- BEGIN Object file/option list - -- ./hello.o - -- -L./ - -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/ - -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a - -- END Object file/option list - - end ada_main; - - The Ada code in the above example is exactly what is generated by the - binder. We have added comments to more clearly indicate the function of - each part of the generated `Ada_Main' package. - - The code is standard Ada in all respects, and can be processed by any - tools that handle Ada. In particular, it is possible to use the debugger - in Ada mode to debug the generated Ada_Main package. For example, - suppose that for reasons that you do not understand, your program is - blowing up during elaboration of the body of `Ada.Text_IO'. To chase - this bug down, you can place a breakpoint on the call: - - Ada.Text_Io'Elab_Body; - - and trace the elaboration routine for this package to find out where - the problem might be (more usually of course you would be debugging - elaboration code in your own application). - -  - File: gnat_ug_vxw.info, Node: Generating the Binder Program in C, Next: Consistency-Checking Modes, Prev: Running gnatbind, Up: Binding Using gnatbind - - Generating the Binder Program in C - ================================== - - In most normal usage, the default mode of `gnatbind' which is to - generate the main package in Ada, as described in the previous section. - In particular, this means that any Ada programmer can read and - understand the generated main program. It can also be debugged just - like any other Ada code provided the `-g' switch is used for `gnatbind' - and `gnatlink'. - - However for some purposes it may be convenient to generate the main - program in C rather than Ada. This may for example be helpful when you - are generating a mixed language program with the main program in C. The - GNAT compiler itself is an example. The use of the `-C' switch for both - `gnatbind' and `gnatlink' will cause the program to be generated in C - (and compiled using the gnu C compiler). The following shows the C code - generated for the same "Hello World" program: - - - #ifdef __STDC__ - #define PARAMS(paramlist) paramlist - #else - #define PARAMS(paramlist) () - #endif - - extern void __gnat_set_globals - PARAMS ((int, int, int, int, int, int, - void (*) PARAMS ((void)), int, int)); - extern void adafinal PARAMS ((void)); - extern void adainit PARAMS ((void)); - extern void system__standard_library__adafinal PARAMS ((void)); - extern int main PARAMS ((int, char **, char **)); - extern void exit PARAMS ((int)); - extern void __gnat_break_start PARAMS ((void)); - extern void _ada_hello PARAMS ((void)); - extern void __gnat_initialize PARAMS ((void)); - extern void __gnat_finalize PARAMS ((void)); - - extern void ada__exceptions___elabs PARAMS ((void)); - extern void system__exceptions___elabs PARAMS ((void)); - extern void interfaces__c_streams___elabs PARAMS ((void)); - extern void system__exception_table___elabb PARAMS ((void)); - extern void ada__io_exceptions___elabs PARAMS ((void)); - extern void system__stack_checking___elabs PARAMS ((void)); - extern void system__soft_links___elabb PARAMS ((void)); - extern void system__secondary_stack___elabb PARAMS ((void)); - extern void ada__tags___elabs PARAMS ((void)); - extern void ada__tags___elabb PARAMS ((void)); - extern void ada__streams___elabs PARAMS ((void)); - extern void system__finalization_root___elabs PARAMS ((void)); - extern void ada__exceptions___elabb PARAMS ((void)); - extern void system__finalization_implementation___elabs PARAMS ((void)); - extern void system__finalization_implementation___elabb PARAMS ((void)); - extern void ada__finalization___elabs PARAMS ((void)); - extern void ada__finalization__list_controller___elabs PARAMS ((void)); - extern void system__file_control_block___elabs PARAMS ((void)); - extern void system__file_io___elabb PARAMS ((void)); - extern void ada__text_io___elabs PARAMS ((void)); - extern void ada__text_io___elabb PARAMS ((void)); - - extern int __gnat_inside_elab_final_code; - - extern int gnat_argc; - extern char **gnat_argv; - extern char **gnat_envp; - extern int gnat_exit_status; - - char __gnat_version[] = "GNAT Version: 3.15w (20010315)"; - void adafinal () { - system__standard_library__adafinal (); - } - - void adainit () - { - extern char ada__exceptions_E; - extern char system__exceptions_E; - extern char interfaces__c_streams_E; - extern char system__exception_table_E; - extern char ada__io_exceptions_E; - extern char system__secondary_stack_E; - extern char system__stack_checking_E; - extern char system__soft_links_E; - extern char ada__tags_E; - extern char ada__streams_E; - extern char system__finalization_root_E; - extern char system__finalization_implementation_E; - extern char ada__finalization_E; - extern char ada__finalization__list_controller_E; - extern char system__file_control_block_E; - extern char system__file_io_E; - extern char ada__text_io_E; - - extern void *__gnat_hello__SDP; - extern void *__gnat_ada__text_io__SDP; - extern void *__gnat_ada__exceptions__SDP; - extern void *__gnat_gnat__heap_sort_a__SDP; - extern void *__gnat_system__exception_table__SDP; - extern void *__gnat_system__machine_state_operations__SDP; - extern void *__gnat_system__secondary_stack__SDP; - extern void *__gnat_system__parameters__SDP; - extern void *__gnat_system__soft_links__SDP; - extern void *__gnat_system__stack_checking__SDP; - extern void *__gnat_system__traceback__SDP; - extern void *__gnat_ada__streams__SDP; - extern void *__gnat_ada__tags__SDP; - extern void *__gnat_system__string_ops__SDP; - extern void *__gnat_interfaces__c_streams__SDP; - extern void *__gnat_system__file_io__SDP; - extern void *__gnat_ada__finalization__SDP; - extern void *__gnat_system__finalization_root__SDP; - extern void *__gnat_system__finalization_implementation__SDP; - extern void *__gnat_system__string_ops_concat_3__SDP; - extern void *__gnat_system__stream_attributes__SDP; - extern void *__gnat_system__file_control_block__SDP; - extern void *__gnat_ada__finalization__list_controller__SDP; - - void **st[23] = { - &__gnat_hello__SDP, - &__gnat_ada__text_io__SDP, - &__gnat_ada__exceptions__SDP, - &__gnat_gnat__heap_sort_a__SDP, - &__gnat_system__exception_table__SDP, - &__gnat_system__machine_state_operations__SDP, - &__gnat_system__secondary_stack__SDP, - &__gnat_system__parameters__SDP, - &__gnat_system__soft_links__SDP, - &__gnat_system__stack_checking__SDP, - &__gnat_system__traceback__SDP, - &__gnat_ada__streams__SDP, - &__gnat_ada__tags__SDP, - &__gnat_system__string_ops__SDP, - &__gnat_interfaces__c_streams__SDP, - &__gnat_system__file_io__SDP, - &__gnat_ada__finalization__SDP, - &__gnat_system__finalization_root__SDP, - &__gnat_system__finalization_implementation__SDP, - &__gnat_system__string_ops_concat_3__SDP, - &__gnat_system__stream_attributes__SDP, - &__gnat_system__file_control_block__SDP, - &__gnat_ada__finalization__list_controller__SDP}; - - extern void ada__exceptions___elabs (); - extern void system__exceptions___elabs (); - extern void interfaces__c_streams___elabs (); - extern void system__exception_table___elabb (); - extern void ada__io_exceptions___elabs (); - extern void system__stack_checking___elabs (); - extern void system__soft_links___elabb (); - extern void system__secondary_stack___elabb (); - extern void ada__tags___elabs (); - extern void ada__tags___elabb (); - extern void ada__streams___elabs (); - extern void system__finalization_root___elabs (); - extern void ada__exceptions___elabb (); - extern void system__finalization_implementation___elabs (); - extern void system__finalization_implementation___elabb (); - extern void ada__finalization___elabs (); - extern void ada__finalization__list_controller___elabs (); - extern void system__file_control_block___elabs (); - extern void system__file_io___elabb (); - extern void ada__text_io___elabs (); - extern void ada__text_io___elabb (); - - void (*ea[23]) () = { - adainit, - system__standard_library__adafinal, - ada__exceptions___elabs, - system__exceptions___elabs, - interfaces__c_streams___elabs, - system__exception_table___elabb, - ada__io_exceptions___elabs, - system__stack_checking___elabs, - system__soft_links___elabb, - system__secondary_stack___elabb, - ada__tags___elabs, - ada__tags___elabb, - ada__streams___elabs, - system__finalization_root___elabs, - ada__exceptions___elabb, - system__finalization_implementation___elabs, - system__finalization_implementation___elabb, - ada__finalization___elabs, - ada__finalization__list_controller___elabs, - system__file_control_block___elabs, - system__file_io___elabb, - ada__text_io___elabs, - ada__text_io___elabb}; - - __gnat_SDP_Table_Build (&st, 23, ea, 23); - __gnat_set_globals ( - -1, /* Main_Priority */ - -1, /* Time_Slice_Value */ - 'b', /* WC_Encoding */ - ' ', /* Locking_Policy */ - ' ', /* Queuing_Policy */ - ' ', /* Tasking_Dispatching_Policy */ - 0, /* Finalization routine address, not used anymore */ - 0, /* Unreserve_All_Interrupts */ - 0); /* Exception_Tracebacks */ - - __gnat_inside_elab_final_code = 1; - - if (ada__exceptions_E == 0) { - ada__exceptions___elabs (); - } - if (system__exceptions_E == 0) { - system__exceptions___elabs (); - system__exceptions_E++; - } - if (interfaces__c_streams_E == 0) { - interfaces__c_streams___elabs (); - } - interfaces__c_streams_E = 1; - if (system__exception_table_E == 0) { - system__exception_table___elabb (); - system__exception_table_E++; - } - if (ada__io_exceptions_E == 0) { - ada__io_exceptions___elabs (); - ada__io_exceptions_E++; - } - if (system__stack_checking_E == 0) { - system__stack_checking___elabs (); - } - if (system__soft_links_E == 0) { - system__soft_links___elabb (); - system__soft_links_E++; - } - system__stack_checking_E = 1; - if (system__secondary_stack_E == 0) { - system__secondary_stack___elabb (); - system__secondary_stack_E++; - } - if (ada__tags_E == 0) { - ada__tags___elabs (); - } - if (ada__tags_E == 0) { - ada__tags___elabb (); - ada__tags_E++; - } - if (ada__streams_E == 0) { - ada__streams___elabs (); - ada__streams_E++; - } - if (system__finalization_root_E == 0) { - system__finalization_root___elabs (); - } - system__finalization_root_E = 1; - if (ada__exceptions_E == 0) { - ada__exceptions___elabb (); - ada__exceptions_E++; - } - if (system__finalization_implementation_E == 0) { - system__finalization_implementation___elabs (); - } - if (system__finalization_implementation_E == 0) { - system__finalization_implementation___elabb (); - system__finalization_implementation_E++; - } - if (ada__finalization_E == 0) { - ada__finalization___elabs (); - } - ada__finalization_E = 1; - if (ada__finalization__list_controller_E == 0) { - ada__finalization__list_controller___elabs (); - } - ada__finalization__list_controller_E = 1; - if (system__file_control_block_E == 0) { - system__file_control_block___elabs (); - system__file_control_block_E++; - } - if (system__file_io_E == 0) { - system__file_io___elabb (); - system__file_io_E++; - } - if (ada__text_io_E == 0) { - ada__text_io___elabs (); - } - if (ada__text_io_E == 0) { - ada__text_io___elabb (); - ada__text_io_E++; - } - - __gnat_inside_elab_final_code = 0; - } - int main (argc, argv, envp) - int argc; - char **argv; - char **envp; - { - gnat_argc = argc; - gnat_argv = argv; - gnat_envp = envp; - - __gnat_initialize (); - adainit (); - __gnat_break_start (); - - _ada_hello (); - - system__standard_library__adafinal (); - __gnat_finalize (); - exit (gnat_exit_status); - } - unsigned helloB = 0x7880BEB3; - unsigned system__standard_libraryB = 0x0D24CBD0; - unsigned system__standard_libraryS = 0x3283DBEB; - unsigned adaS = 0x2359F9ED; - unsigned ada__text_ioB = 0x47C85FC4; - unsigned ada__text_ioS = 0x496FE45C; - unsigned ada__exceptionsB = 0x74F50187; - unsigned ada__exceptionsS = 0x6736945B; - unsigned gnatS = 0x156A40CF; - unsigned gnat__heap_sort_aB = 0x033DABE0; - unsigned gnat__heap_sort_aS = 0x6AB38FEA; - unsigned systemS = 0x0331C6FE; - unsigned system__exceptionsS = 0x20C9ECA4; - unsigned system__exception_tableB = 0x68A22947; - unsigned system__exception_tableS = 0x394BADD5; - unsigned gnat__htableB = 0x08258E1B; - unsigned gnat__htableS = 0x367D5222; - unsigned system__machine_state_operationsB = 0x4F3B7492; - unsigned system__machine_state_operationsS = 0x182F5CF4; - unsigned system__storage_elementsB = 0x2F1EB794; - unsigned system__storage_elementsS = 0x102C83C7; - unsigned system__secondary_stackB = 0x1574B6E9; - unsigned system__secondary_stackS = 0x708E260A; - unsigned system__parametersB = 0x56D770CD; - unsigned system__parametersS = 0x237E39BE; - unsigned system__soft_linksB = 0x08AB6B2C; - unsigned system__soft_linksS = 0x1E2491F3; - unsigned system__stack_checkingB = 0x476457A0; - unsigned system__stack_checkingS = 0x5299FCED; - unsigned system__tracebackB = 0x2971EBDE; - unsigned system__tracebackS = 0x2E9C3122; - unsigned ada__streamsS = 0x7C25DE96; - unsigned ada__tagsB = 0x39ADFFA2; - unsigned ada__tagsS = 0x769A0464; - unsigned system__string_opsB = 0x5EB646AB; - unsigned system__string_opsS = 0x63CED018; - unsigned interfacesS = 0x0357E00A; - unsigned interfaces__c_streamsB = 0x3784FB72; - unsigned interfaces__c_streamsS = 0x2E723019; - unsigned system__file_ioB = 0x623358EA; - unsigned system__file_ioS = 0x31F873E6; - unsigned ada__finalizationB = 0x6843F68A; - unsigned ada__finalizationS = 0x63305874; - unsigned system__finalization_rootB = 0x31E56CE1; - unsigned system__finalization_rootS = 0x23169EF3; - unsigned system__finalization_implementationB = 0x6CCBA70E; - unsigned system__finalization_implementationS = 0x604AA587; - unsigned system__string_ops_concat_3B = 0x572E3F58; - unsigned system__string_ops_concat_3S = 0x01F57876; - unsigned system__stream_attributesB = 0x1D4F93E8; - unsigned system__stream_attributesS = 0x30B2EC3D; - unsigned ada__io_exceptionsS = 0x34054F96; - unsigned system__unsigned_typesS = 0x7B9E7FE3; - unsigned system__file_control_blockS = 0x2FF876A8; - unsigned ada__finalization__list_controllerB = 0x5760634A; - unsigned ada__finalization__list_controllerS = 0x5D851835; - - /* BEGIN ELABORATION ORDER - ada (spec) - gnat (spec) - gnat.heap_sort_a (spec) - gnat.htable (spec) - gnat.htable (body) - interfaces (spec) - system (spec) - system.parameters (spec) - system.standard_library (spec) - ada.exceptions (spec) - system.exceptions (spec) - system.parameters (body) - gnat.heap_sort_a (body) - interfaces.c_streams (spec) - interfaces.c_streams (body) - system.exception_table (spec) - system.exception_table (body) - ada.io_exceptions (spec) - system.storage_elements (spec) - system.storage_elements (body) - system.machine_state_operations (spec) - system.machine_state_operations (body) - system.secondary_stack (spec) - system.stack_checking (spec) - system.soft_links (spec) - system.soft_links (body) - system.stack_checking (body) - system.secondary_stack (body) - system.standard_library (body) - system.string_ops (spec) - system.string_ops (body) - ada.tags (spec) - ada.tags (body) - ada.streams (spec) - system.finalization_root (spec) - system.finalization_root (body) - system.string_ops_concat_3 (spec) - system.string_ops_concat_3 (body) - system.traceback (spec) - system.traceback (body) - ada.exceptions (body) - system.unsigned_types (spec) - system.stream_attributes (spec) - system.stream_attributes (body) - system.finalization_implementation (spec) - system.finalization_implementation (body) - ada.finalization (spec) - ada.finalization (body) - ada.finalization.list_controller (spec) - ada.finalization.list_controller (body) - system.file_control_block (spec) - system.file_io (spec) - system.file_io (body) - ada.text_io (spec) - ada.text_io (body) - hello (body) - END ELABORATION ORDER */ - - /* BEGIN Object file/option list - ./hello.o - -L./ - -L/usr/local/gnat/lib/gcc-lib/alpha-dec-osf5.1/2.8.1/adalib/ - /usr/local/gnat/lib/gcc-lib/alpha-dec-osf5.1/2.8.1/adalib/libgnat.a - -lexc - END Object file/option list */ - - Here again, the C code is exactly what is generated by the binder. The - functions of the various parts of this code correspond in an obvious - manner with the commented Ada code shown in the example in the previous - section. - -  - File: gnat_ug_vxw.info, Node: Consistency-Checking Modes, Next: Binder Error Message Control, Prev: Generating the Binder Program in C, Up: Binding Using gnatbind - - Consistency-Checking Modes - ========================== - - As described in the previous section, by default `gnatbind' checks that - object files are consistent with one another and are consistent with - any source files it can locate. The following switches control binder - access to sources. - - `-s' - Require source files to be present. In this mode, the binder must - be able to locate all source files that are referenced, in order - to check their consistency. In normal mode, if a source file - cannot be located it is simply ignored. If you specify this - switch, a missing source file is an error. - - `-x' - Exclude source files. In this mode, the binder only checks that ALI - files are consistent with one another. Source files are not - accessed. The binder runs faster in this mode, and there is still - a guarantee that the resulting program is self-consistent. If a - source file has been edited since it was last compiled, and you - specify this switch, the binder will not detect that the object - file is out of date with respect to the source file. Note that - this is the mode that is automatically used by `gnatmake' because - in this case the checking against sources has already been - performed by `gnatmake' in the course of compilation (i.e. before - binding). - -  - File: gnat_ug_vxw.info, Node: Binder Error Message Control, Next: Elaboration Control, Prev: Consistency-Checking Modes, Up: Binding Using gnatbind - - Binder Error Message Control - ============================ - - The following switches provide control over the generation of error - messages from the binder: - - `-v' - Verbose mode. In the normal mode, brief error messages are - generated to `stderr'. If this switch is present, a header is - written to `stdout' and any error messages are directed to - `stdout'. All that is written to `stderr' is a brief summary - message. - - `-b' - Generate brief error messages to `stderr' even if verbose mode is - specified. This is relevant only when used with the `-v' switch. - - `-mN' - Limits the number of error messages to N, a decimal integer in the - range 1-999. The binder terminates immediately if this limit is - reached. - - `-MXXX' - Renames the generated main program from `main' to `xxx'. This is - useful in the case of some cross-building environments, where the - actual main program is separate from the one generated by - `gnatbind'. - - `-ws' - Suppress all warning messages. - - `-we' - Treat any warning messages as fatal errors. - - `-t' - The binder performs a number of consistency checks including: - - * Check that time stamps of a given source unit are consistent - - * Check that checksums of a given source unit are consistent - - * Check that consistent versions of `GNAT' were used for - compilation - - * Check consistency of configuration pragmas as required - - Normally failure of such checks, in accordance with the consistency - requirements of the Ada Reference Manual, causes error messages to - be generated which abort the binder and prevent the output of a - binder file and subsequent link to obtain an executable. - - The `-t' switch converts these error messages into warnings, so - that binding and linking can continue to completion even in the - presence of such errors. The result may be a failed link (due to - missing symbols), or a non-functional executable which has - undefined semantics. _This means that `-t' should be used only in - unusual situations, with extreme care._ - -  - File: gnat_ug_vxw.info, Node: Elaboration Control, Next: Output Control, Prev: Binder Error Message Control, Up: Binding Using gnatbind - - Elaboration Control - =================== - - The following switches provide additional control over the elaboration - order. For full details see *Note Elaboration Order Handling in GNAT::. - - `-p' - Normally the binder attempts to choose an elaboration order that is - likely to minimize the likelihood of an elaboration order error - resulting in raising a `Program_Error' exception. This switch - reverses the action of the binder, and requests that it - deliberately choose an order that is likely to maximize the - likelihood of an elaboration error. This is useful in ensuring - portability and avoiding dependence on accidental fortuitous - elaboration ordering. - - Normally it only makes sense to use the `-p' switch if dynamic - elaboration checking is used (`-gnatE' switch used for - compilation). This is because in the default static elaboration - mode, all necessary `Elaborate_All' pragmas are implicitly - inserted. These implicit pragmas are still respected by the binder - in `-p' mode, so a safe elaboration order is assured. - -  - File: gnat_ug_vxw.info, Node: Output Control, Next: Binding with Non-Ada Main Programs, Prev: Elaboration Control, Up: Binding Using gnatbind - - Output Control - ============== - - The following switches allow additional control over the output - generated by the binder. - - `-A' - Generate binder program in Ada (default). The binder program is - named `b~MAINPROG.adb' by default. This can be changed with `-o' - `gnatbind' option. - - `-c' - Check only. Do not generate the binder output file. In this mode - the binder performs all error checks but does not generate an - output file. - - `-C' - Generate binder program in C. The binder program is named - `b_MAINPROG.c'. This can be changed with `-o' `gnatbind' option. - - `-e' - Output complete list of elaboration-order dependencies, showing the - reason for each dependency. This output can be rather extensive - but may be useful in diagnosing problems with elaboration order. - The output is written to `stdout'. - - `-h' - Output usage information. The output is written to `stdout'. - - `-K' - Output linker options to `stdout'. Includes library search paths, - contents of pragmas Ident and Linker_Options, and libraries added - by `gnatbind'. - - `-l' - Output chosen elaboration order. The output is written to `stdout'. - - `-O' - Output full names of all the object files that must be linked to - provide the Ada component of the program. The output is written to - `stdout'. This list includes the files explicitly supplied and - referenced by the user as well as implicitly referenced run-time - unit files. The latter are omitted if the corresponding units - reside in shared libraries. The directory names for the run-time - units depend on the system configuration. - - `-o FILE' - Set name of output file to FILE instead of the normal - `b~MAINPROG.adb' default. Note that FILE denote the Ada binder - generated body filename. In C mode you would normally give FILE an - extension of `.c' because it will be a C source program. Note - that if this option is used, then linking must be done manually. - It is not possible to use gnatlink in this case, since it cannot - locate the binder file. - - `-r' - Generate list of `pragma Rerstrictions' that could be applied to - the current unit. This is useful for code audit purposes, and also - may be used to improve code generation in some cases. - -  - File: gnat_ug_vxw.info, Node: Binding with Non-Ada Main Programs, Next: Binding Programs with No Main Subprogram, Prev: Output Control, Up: Binding Using gnatbind - - Binding with Non-Ada Main Programs - ================================== - - In our description so far we have assumed that the main program is in - Ada, and that the task of the binder is to generate a corresponding - function `main' that invokes this Ada main program. GNAT also supports - the building of executable programs where the main program is not in - Ada, but some of the called routines are written in Ada and compiled - using GNAT (*note Mixed Language Programming::). The following switch - is used in this situation: - - `-n' - No main program. The main program is not in Ada. - - In this case, most of the functions of the binder are still required, - but instead of generating a main program, the binder generates a file - containing the following callable routines: - - `adainit' - You must call this routine to initialize the Ada part of the - program by calling the necessary elaboration routines. A call to - `adainit' is required before the first call to an Ada subprogram. - - Note that it is assumed that the basic execution environment must - be setup to be appropriate for Ada execution at the point where - the first Ada subprogram is called. In particular, if the Ada code - will do any floating-point operations, then the FPU must be setup - in an appropriate manner. For the case of the x86, for example, - full precision mode is required. The procedure - GNAT.Float_Control.Reset may be used to ensure that the FPU is in - the right state. - - `adafinal' - You must call this routine to perform any library-level - finalization required by the Ada subprograms. A call to `adafinal' - is required after the last call to an Ada subprogram, and before - the program terminates. - - If the `-n' switch is given, more than one ALI file may appear on the - command line for `gnatbind'. The normal "closure" calculation is - performed for each of the specified units. Calculating the closure - means finding out the set of units involved by tracing `with' - references. The reason it is necessary to be able to specify more than - one ALI file is that a given program may invoke two or more quite - separate groups of Ada units. - - The binder takes the name of its output file from the last specified - ALI file, unless overridden by the use of the `-o file'. The output is - an Ada unit in source form that can be compiled with GNAT unless the -C - switch is used in which case the output is a C source file, which must - be compiled using the C compiler. This compilation occurs - automatically as part of the `gnatlink' processing. - - Currently the GNAT run time requires a FPU using 80 bits mode - precision. Under targets where this is not the default it is required to - call GNAT.Float_Control.Reset before using floating point numbers (this - include float computation, float input and output) in the Ada code. A - side effect is that this could be the wrong mode for the foreign code - where floating point computation could be broken after this call. - -  - File: gnat_ug_vxw.info, Node: Binding Programs with No Main Subprogram, Next: Summary of Binder Switches, Prev: Binding with Non-Ada Main Programs, Up: Binding Using gnatbind - - Binding Programs with No Main Subprogram - ======================================== - - It is possible to have an Ada program which does not have a main - subprogram. This program will call the elaboration routines of all the - packages, then the finalization routines. - - The following switch is used to bind programs organized in this - manner: - - `-z' - Normally the binder checks that the unit name given on the command - line corresponds to a suitable main subprogram. When this switch - is used, a list of ALI files can be given, and the execution of - the program consists of elaboration of these units in an - appropriate order. - -  - File: gnat_ug_vxw.info, Node: Summary of Binder Switches, Next: Command-Line Access, Prev: Binding Programs with No Main Subprogram, Up: Binding Using gnatbind - - Summary of Binder Switches - ========================== - - The following are the switches available with `gnatbind': - - `-aO' - Specify directory to be searched for ALI files. - - `-aI' - Specify directory to be searched for source file. - - `-A' - Generate binder program in Ada (default) - - `-b' - Generate brief messages to `stderr' even if verbose mode set. - - `-c' - Check only, no generation of binder output file. - - `-C' - Generate binder program in C - - `-e' - Output complete list of elaboration-order dependencies. - - `-E' - Store tracebacks in exception occurrences when the target supports - it. This is the default with the zero cost exception mechanism. - This option is currently supported on the following targets: all - x86 ports, Solaris, Windows, HP-UX, AIX, PowerPC VxWorks and Alpha - VxWorks. See also the packages `GNAT.Traceback' and - `GNAT.Traceback.Symbolic' for more information. Note that on x86 - ports, you must not use `-fomit-frame-pointer' `gcc' option. - - `-h' - Output usage (help) information - - `-I' - Specify directory to be searched for source and ALI files. - - `-I-' - Do not look for sources in the current directory where `gnatbind' - was invoked, and do not look for ALI files in the directory - containing the ALI file named in the `gnatbind' command line. - - `-l' - Output chosen elaboration order. - - `-Lxxx' - Binds the units for library building. In this case the adainit and - adafinal procedures (See *note Binding with Non-Ada Main - Programs::) are renamed to xxxinit and xxxfinal. Implies -n. See - *note GNAT and Libraries:: for more details. - - `-Mxyz' - Rename generated main program from main to xyz - - `-mN' - Limit number of detected errors to N (1-999). - - `-n' - No main program. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-o FILE' - Name the output file FILE (default is `b~XXX.adb'). Note that if - this option is used, then linking must be done manually, gnatlink - cannot be used. - - `-O' - Output object list. - - `-p' - Pessimistic (worst-case) elaboration order - - `-s' - Require all source files to be present. - - `-static' - Link against a static GNAT run time. - - `-shared' - Link against a shared GNAT run time when available. - - `-t' - Tolerate time stamp and other consistency errors - - `-TN' - Set the time slice value to n microseconds. A value of zero means - no time slicing and also indicates to the tasking run time to - match as close as possible to the annex D requirements of the RM. - - `-v' - Verbose mode. Write error messages, header, summary output to - `stdout'. - - `-wX' - Warning mode (X=s/e for suppress/treat as error) - - `-x' - Exclude source files (check object consistency only). - - `-z' - No main subprogram. - - You may obtain this listing by running the program `gnatbind' with - no arguments. - -  - File: gnat_ug_vxw.info, Node: Command-Line Access, Next: Search Paths for gnatbind, Prev: Summary of Binder Switches, Up: Binding Using gnatbind - - Command-Line Access - =================== - - The package `Ada.Command_Line' provides access to the command-line - arguments and program name. In order for this interface to operate - correctly, the two variables - - int gnat_argc; - char **gnat_argv; - - are declared in one of the GNAT library routines. These variables must - be set from the actual `argc' and `argv' values passed to the main - program. With no `n' present, `gnatbind' generates the C main program - to automatically set these variables. If the `n' switch is used, there - is no automatic way to set these variables. If they are not set, the - procedures in `Ada.Command_Line' will not be available, and any attempt - to use them will raise `Constraint_Error'. If command line access is - required, your main program must set `gnat_argc' and `gnat_argv' from - the `argc' and `argv' values passed to it. - -  - File: gnat_ug_vxw.info, Node: Search Paths for gnatbind, Next: Examples of gnatbind Usage, Prev: Command-Line Access, Up: Binding Using gnatbind - - Search Paths for `gnatbind' - =========================== - - The binder takes the name of an ALI file as its argument and needs to - locate source files as well as other ALI files to verify object - consistency. - - For source files, it follows exactly the same search rules as `gcc' - (*note Search Paths and the Run-Time Library (RTL)::). For ALI files the - directories searched are: - - 1. The directory containing the ALI file named in the command line, - unless the switch `-I-' is specified. - - 2. All directories specified by `-I' switches on the `gnatbind' - command line, in the order given. - - 3. Each of the directories listed in the value of the - `ADA_OBJECTS_PATH' environment variable. Construct this value - exactly as the `PATH' environment variable: a list of directory - names separated by colons (semicolons when working with the NT - version of GNAT). - - 4. The content of the "ada_object_path" file which is part of the GNAT - installation tree and is used to store standard libraries such as - the GNAT Run Time Library (RTL) unless the switch `-nostdlib' is - specified. *Note Installing an Ada Library:: - - In the binder the switch `-I' is used to specify both source and - library file paths. Use `-aI' instead if you want to specify source - paths only, and `-aO' if you want to specify library paths only. This - means that for the binder `-I'DIR is equivalent to `-aI'DIR `-aO'DIR. - The binder generates the bind file (a C language source file) in the - current working directory. - - The packages `Ada', `System', and `Interfaces' and their children - make up the GNAT Run-Time Library, together with the package GNAT and - its children, which contain a set of useful additional library - functions provided by GNAT. The sources for these units are needed by - the compiler and are kept together in one directory. The ALI files and - object files generated by compiling the RTL are needed by the binder - and the linker and are kept together in one directory, typically - different from the directory containing the sources. In a normal - installation, you need not specify these directory names when compiling - or binding. Either the environment variables or the built-in defaults - cause these files to be found. - - Besides simplifying access to the RTL, a major use of search paths is - in compiling sources from multiple directories. This can make - development environments much more flexible. - -  - File: gnat_ug_vxw.info, Node: Examples of gnatbind Usage, Prev: Search Paths for gnatbind, Up: Binding Using gnatbind - - Examples of `gnatbind' Usage - ============================ - - This section contains a number of examples of using the GNAT binding - utility `gnatbind'. - - `gnatbind hello' - The main program `Hello' (source program in `hello.adb') is bound - using the standard switch settings. The generated main program is - `b~hello.adb'. This is the normal, default use of the binder. - - `gnatbind hello -o mainprog.adb' - The main program `Hello' (source program in `hello.adb') is bound - using the standard switch settings. The generated main program is - `mainprog.adb' with the associated spec in `mainprog.ads'. Note - that you must specify the body here not the spec, in the case - where the output is in Ada. Note that if this option is used, then - linking must be done manually, since gnatlink will not be able to - find the generated file. - - `gnatbind main -C -o mainprog.c -x' - The main program `Main' (source program in `main.adb') is bound, - excluding source files from the consistency checking, generating - the file `mainprog.c'. - - `gnatbind -x main_program -C -o mainprog.c' - This command is exactly the same as the previous example. Switches - may appear anywhere in the command line, and single letter - switches may be combined into a single switch. - - `gnatbind -n math dbase -C -o ada-control.c' - The main program is in a language other than Ada, but calls to - subprograms in packages `Math' and `Dbase' appear. This call to - `gnatbind' generates the file `ada-control.c' containing the - `adainit' and `adafinal' routines to be called before and after - accessing the Ada units. - -  - File: gnat_ug_vxw.info, Node: Linking Using gnatlink, Next: The GNAT Make Program gnatmake, Prev: Binding Using gnatbind, Up: Top - - Linking Using `gnatlink' - ************************ - - This chapter discusses `gnatlink', a utility program used to link Ada - programs and build an executable file. This is a simple program that - invokes the Unix linker (via the `gcc' command) with a correct list of - object files and library references. `gnatlink' automatically - determines the list of files and references for the Ada part of a - program. It uses the binder file generated by the binder to determine - this list. - - * Menu: - - * Running gnatlink:: - * Switches for gnatlink:: - * Setting Stack Size from gnatlink:: - * Setting Heap Size from gnatlink:: - -  - File: gnat_ug_vxw.info, Node: Running gnatlink, Next: Switches for gnatlink, Up: Linking Using gnatlink - - Running `gnatlink' - ================== - - The form of the `gnatlink' command is - - $ gnatlink [SWITCHES] MAINPROG[.ali] [NON-ADA OBJECTS] - [LINKER OPTIONS] - - `MAINPROG.ali' references the ALI file of the main program. The `.ali' - extension of this file can be omitted. From this reference, `gnatlink' - locates the corresponding binder file `b~MAINPROG.adb' and, using the - information in this file along with the list of non-Ada objects and - linker options, constructs a Unix linker command file to create the - executable. - - The arguments following `MAINPROG.ali' are passed to the linker - uninterpreted. They typically include the names of object files for - units written in other languages than Ada and any library references - required to resolve references in any of these foreign language units, - or in `pragma Import' statements in any Ada units. - - LINKER OPTIONS is an optional list of linker specific switches. The - default linker called by gnatlink is GCC which in turn calls the - appropriate system linker usually called LD. Standard options for the - linker such as `-lmy_lib' or `-Ldir' can be added as is. For options - that are not recognized by GCC as linker options, the GCC switches - `-Xlinker' or `-Wl,' shall be used. Refer to the GCC documentation for - details. Here is an example showing how to generate a linker map - assuming that the underlying linker is GNU ld: - - $ gnatlink my_prog -Wl,-Map,MAPFILE - - Using LINKER OPTIONS it is possible to set the program stack and - heap size. See *note Setting Stack Size from gnatlink:: and *note - Setting Heap Size from gnatlink::. - - `gnatlink' determines the list of objects required by the Ada - program and prepends them to the list of objects passed to the linker. - `gnatlink' also gathers any arguments set by the use of `pragma - Linker_Options' and adds them to the list of arguments presented to the - linker. - -  - File: gnat_ug_vxw.info, Node: Switches for gnatlink, Next: Setting Stack Size from gnatlink, Prev: Running gnatlink, Up: Linking Using gnatlink - - Switches for `gnatlink' - ======================= - - The following switches are available with the `gnatlink' utility: - - `-A' - The binder has generated code in Ada. This is the default. - - `-C' - If instead of generating a file in Ada, the binder has generated - one in C, then the linker needs to know about it. Use this switch - to signal to `gnatlink' that the binder has generated C code - rather than Ada code. - - `-f' - On some targets, the command line length is limited, and `gnatlink' - will generate a separate file for the linker if the list of object - files is too long. The `-f' flag forces this file to be generated - even if the limit is not exceeded. This is useful in some cases to - deal with special situations where the command line length is - exceeded. - - `-g' - The option to include debugging information causes the Ada bind - file (in other words, `b~MAINPROG.adb') to be compiled with `-g'. - In addition, the binder does not delete the `b~MAINPROG.adb', - `b~MAINPROG.o' and `b~MAINPROG.ali' files. Without `-g', the - binder removes these files by default. The same procedure apply if - a C bind file was generated using `-C' `gnatbind' option, in this - case the filenames are `b_MAINPROG.c' and `b_MAINPROG.o'. - - `-n' - Do not compile the file generated by the binder. This may be used - when a link is rerun with different options, but there is no need - to recompile the binder file. - - `-v' - Causes additional information to be output, including a full list - of the included object files. This switch option is most useful - when you want to see what set of object files are being used in - the link step. - - `-v -v' - Very verbose mode. Requests that the compiler operate in verbose - mode when it compiles the binder file, and that the system linker - run in verbose mode. - - `-o EXEC-NAME' - EXEC-NAME specifies an alternate name for the generated executable - program. If this switch is omitted, the executable has the same - name as the main unit. For example, `gnatlink try.ali' creates an - executable called `try'. - - `-b TARGET' - Compile your program to run on TARGET, which is the name of a - system configuration. You must have a GNAT cross-compiler built if - TARGET is not the same as your host system. - - `-BDIR' - Load compiler executables (for example, `gnat1', the Ada compiler) - from DIR instead of the default location. Only use this switch - when multiple versions of the GNAT compiler are available. See the - `gcc' manual page for further details. You would normally use the - `-b' or `-V' switch instead. - - `--GCC=COMPILER_NAME' - Program used for compiling the binder file. The default is - ``gcc''. You need to use quotes around COMPILER_NAME if - `compiler_name' contains spaces or other separator characters. As - an example `--GCC="foo -x -y"' will instruct `gnatlink' to use - `foo -x -y' as your compiler. Note that switch `-c' is always - inserted after your command name. Thus in the above example the - compiler command that will be used by `gnatlink' will be `foo -c - -x -y'. If several `--GCC=compiler_name' are used, only the last - COMPILER_NAME is taken into account. However, all the additional - switches are also taken into account. Thus, `--GCC="foo -x -y" - --GCC="bar -z -t"' is equivalent to `--GCC="bar -x -y -z -t"'. - - `--LINK=NAME' - NAME is the name of the linker to be invoked. This is especially - useful in mixed language programs since languages such as c++ - require their own linker to be used. When this switch is omitted, - the default name for the linker is (`gcc'). When this switch is - used, the specified linker is called instead of (`gcc') with - exactly the same parameters that would have been passed to (`gcc') - so if the desired linker requires different parameters it is - necessary to use a wrapper script that massages the parameters - before invoking the real linker. It may be useful to control the - exact invocation by using the verbose switch. - -  - File: gnat_ug_vxw.info, Node: Setting Stack Size from gnatlink, Next: Setting Heap Size from gnatlink, Prev: Switches for gnatlink, Up: Linking Using gnatlink - - Setting Stack Size from `gnatlink' - ================================== - - It is possible to specify the program stack size from `gnatlink'. - Assuming that the underlying linker is GNU ld there is two ways to do - so: - - * using `-Xlinker' linker option - - $ gnatlink hello -Xlinker --stack=0x10000,0x1000 - - This set the stack reserve size to 0x10000 bytes and the stack - commit size to 0x1000 bytes. - - * using `-Wl' linker option - - $ gnatlink hello -Wl,--stack=0x1000000 - - This set the stack reserve size to 0x1000000 bytes. Note that with - `-Wl' option it is not possible to set the stack commit size - because the coma is a separator for this option. - - -  - File: gnat_ug_vxw.info, Node: Setting Heap Size from gnatlink, Prev: Setting Stack Size from gnatlink, Up: Linking Using gnatlink - - Setting Heap Size from `gnatlink' - ================================= - - It is possible to specify the program heap size from `gnatlink'. - Assuming that the underlying linker is GNU ld there is two ways to do - so: - - * using `-Xlinker' linker option - - $ gnatlink hello -Xlinker --heap=0x10000,0x1000 - - This set the heap reserve size to 0x10000 bytes and the heap commit - size to 0x1000 bytes. - - * using `-Wl' linker option - - $ gnatlink hello -Wl,--heap=0x1000000 - - This set the heap reserve size to 0x1000000 bytes. Note that with - `-Wl' option it is not possible to set the heap commit size - because the coma is a separator for this option. - - -  - File: gnat_ug_vxw.info, Node: The GNAT Make Program gnatmake, Next: Renaming Files Using gnatchop, Prev: Linking Using gnatlink, Up: Top - - The GNAT Make Program `gnatmake' - ******************************** - - * Menu: - - * Running gnatmake:: - * Switches for gnatmake:: - * Mode Switches for gnatmake:: - * Notes on the Command Line:: - * How gnatmake Works:: - * Examples of gnatmake Usage:: - - A typical development cycle when working on an Ada program consists of - the following steps: - - 1. Edit some sources to fix bugs. - - 2. Add enhancements. - - 3. Compile all sources affected. - - 4. Rebind and relink. - - 5. Test. - - The third step can be tricky, because not only do the modified files - have to be compiled, but any files depending on these files must also be - recompiled. The dependency rules in Ada can be quite complex, especially - in the presence of overloading, `use' clauses, generics and inlined - subprograms. - - `gnatmake' automatically takes care of the third and fourth steps of - this process. It determines which sources need to be compiled, compiles - them, and binds and links the resulting object files. - - Unlike some other Ada make programs, the dependencies are always - accurately recomputed from the new sources. The source based approach of - the GNAT compilation model makes this possible. This means that if - changes to the source program cause corresponding changes in - dependencies, they will always be tracked exactly correctly by - `gnatmake'. - -  - File: gnat_ug_vxw.info, Node: Running gnatmake, Next: Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Running `gnatmake' - ================== - - The usual form of the `gnatmake' command is - - $ gnatmake [SWITCHES] FILE_NAME [FILE_NAMES] [MODE_SWITCHES] - - The only required argument is one FILE_NAME, which specifies a - compilation unit that is a main program. Several FILE_NAMES can be - specified: this will result in several executables being built. If - `switches' are present, they can be placed before the first FILE_NAME, - between FILE_NAMES or after the last FILE_NAME. If MODE_SWITCHES are - present, they must always be placed after the last FILE_NAME and all - `switches'. - - If you are using standard file extensions (.adb and .ads), then the - extension may be omitted from the FILE_NAME arguments. However, if you - are using non-standard extensions, then it is required that the - extension be given. A relative or absolute directory path can be - specified in a FILE_NAME, in which case, the input source file will be - searched for in the specified directory only. Otherwise, the input - source file will first be searched in the directory where `gnatmake' - was invoked and if it is not found, it will be search on the source - path of the compiler as described in *Note Search Paths and the - Run-Time Library (RTL)::. - - When several FILE_NAMES are specified, if an executable needs to be - rebuilt and relinked, all subsequent executables will be rebuilt and - relinked, even if this would not be absolutely necessary. - - All `gnatmake' output (except when you specify `-M') is to `stderr'. - The output produced by the `-M' switch is send to `stdout'. - -  - File: gnat_ug_vxw.info, Node: Switches for gnatmake, Next: Mode Switches for gnatmake, Prev: Running gnatmake, Up: The GNAT Make Program gnatmake - - Switches for `gnatmake' - ======================= - - You may specify any of the following switches to `gnatmake': - - `--GCC=COMPILER_NAME' - Program used for compiling. The default is ``gcc''. You need to use - quotes around COMPILER_NAME if `compiler_name' contains spaces or - other separator characters. As an example `--GCC="foo -x -y"' will - instruct `gnatmake' to use `foo -x -y' as your compiler. Note that - switch `-c' is always inserted after your command name. Thus in - the above example the compiler command that will be used by - `gnatmake' will be `foo -c -x -y'. If several - `--GCC=compiler_name' are used, only the last COMPILER_NAME is - taken into account. However, all the additional switches are also - taken into account. Thus, `--GCC="foo -x -y" --GCC="bar -z -t"' is - equivalent to `--GCC="bar -x -y -z -t"'. - - `--GNATBIND=BINDER_NAME' - Program used for binding. The default is ``gnatbind''. You need to - use quotes around BINDER_NAME if BINDER_NAME contains spaces or - other separator characters. As an example `--GNATBIND="bar -x -y"' - will instruct `gnatmake' to use `bar -x -y' as your binder. Binder - switches that are normally appended by `gnatmake' to ``gnatbind'' - are now appended to the end of `bar -x -y'. - - `--GNATLINK=LINKER_NAME' - Program used for linking. The default is ``gnatlink''. You need to - use quotes around LINKER_NAME if LINKER_NAME contains spaces or - other separator characters. As an example `--GNATLINK="lan -x -y"' - will instruct `gnatmake' to use `lan -x -y' as your linker. Linker - switches that are normally appended by `gnatmake' to ``gnatlink'' - are now appended to the end of `lan -x -y'. - - `-a' - Consider all files in the make process, even the GNAT internal - system files (for example, the predefined Ada library files), as - well as any locked files. Locked files are files whose ALI file is - write-protected. By default, `gnatmake' does not check these - files, because the assumption is that the GNAT internal files are - properly up to date, and also that any write protected ALI files - have been properly installed. Note that if there is an - installation problem, such that one of these files is not up to - date, it will be properly caught by the binder. You may have to - specify this switch if you are working on GNAT itself. `-a' is - also useful in conjunction with `-f' if you need to recompile an - entire application, including run-time files, using special - configuration pragma settings, such as a non-standard - `Float_Representation' pragma. By default `gnatmake -a' compiles - all GNAT internal files with `gcc -c -gnatpg' rather than `gcc -c'. - - `-b' - Bind only. Can be combined with `-c' to do compilation and - binding, but no link. Can be combined with `-l' to do binding and - linking. When not combined with `-c' all the units in the closure - of the main program must have been previously compiled and must be - up to date. The root unit specified by FILE_NAME may be given - without extension, with the source extension or, if no GNAT - Project File is specified, with the ALI file extension. - - `-c' - Compile only. Do not perform binding, except when `-b' is also - specified. Do not perform linking, except if both `-b' and `-l' - are also specified. If the root unit specified by FILE_NAME is - not a main unit, this is the default. Otherwise `gnatmake' will - attempt binding and linking unless all objects are up to date and - the executable is more recent than the objects. - - `-C' - Use a mapping file. A mapping file is a way to communicate to the - compiler two mappings: from unit names to file names (without any - directory information) and from file names to path names (with - full directory information). These mappings are used by the - compiler to short-circuit the path search. When `gnatmake' is - invoked with this switch, it will create a mapping file, initially - populated by the project manager, if `-P' is used, otherwise - initially empty. Each invocation of the compiler will add the newly - accessed sources to the mapping file. This will improve the source - search during the next invocation of the compiler. - - `-f' - Force recompilations. Recompile all sources, even though some - object files may be up to date, but don't recompile predefined or - GNAT internal files or locked files (files with a write-protected - ALI file), unless the `-a' switch is also specified. - - `' - - `-i' - In normal mode, `gnatmake' compiles all object files and ALI files - into the current directory. If the `-i' switch is used, then - instead object files and ALI files that already exist are - overwritten in place. This means that once a large project is - organized into separate directories in the desired manner, then - `gnatmake' will automatically maintain and update this - organization. If no ALI files are found on the Ada object path - (*Note Search Paths and the Run-Time Library (RTL)::), the new - object and ALI files are created in the directory containing the - source being compiled. If another organization is desired, where - objects and sources are kept in different directories, a useful - technique is to create dummy ALI files in the desired directories. - When detecting such a dummy file, `gnatmake' will be forced to - recompile the corresponding source file, and it will be put the - resulting object and ALI files in the directory where it found the - dummy file. - - `-jN' - Use N processes to carry out the (re)compilations. On a - multiprocessor machine compilations will occur in parallel. In the - event of compilation errors, messages from various compilations - might get interspersed (but `gnatmake' will give you the full - ordered list of failing compiles at the end). If this is - problematic, rerun the make process with n set to 1 to get a clean - list of messages. - - `-k' - Keep going. Continue as much as possible after a compilation - error. To ease the programmer's task in case of compilation - errors, the list of sources for which the compile fails is given - when `gnatmake' terminates. - - If `gnatmake' is invoked with several `file_names' and with this - switch, if there are compilation errors when building an - executable, `gnatmake' will not attempt to build the following - executables. - - `-l' - Link only. Can be combined with `-b' to binding and linking. - Linking will not be performed if combined with `-c' but not with - `-b'. When not combined with `-b' all the units in the closure of - the main program must have been previously compiled and must be up - to date, and the main program need to have been bound. The root - unit specified by FILE_NAME may be given without extension, with - the source extension or, if no GNAT Project File is specified, - with the ALI file extension. - - `-m' - Specifies that the minimum necessary amount of recompilations be - performed. In this mode `gnatmake' ignores time stamp differences - when the only modifications to a source file consist in - adding/removing comments, empty lines, spaces or tabs. This means - that if you have changed the comments in a source file or have - simply reformatted it, using this switch will tell gnatmake not to - recompile files that depend on it (provided other sources on which - these files depend have undergone no semantic modifications). Note - that the debugging information may be out of date with respect to - the sources if the `-m' switch causes a compilation to be - switched, so the use of this switch represents a trade-off between - compilation time and accurate debugging information. - - `-M' - Check if all objects are up to date. If they are, output the object - dependences to `stdout' in a form that can be directly exploited in - a `Makefile'. By default, each source file is prefixed with its - (relative or absolute) directory name. This name is whatever you - specified in the various `-aI' and `-I' switches. If you use - `gnatmake -M' `-q' (see below), only the source file names, - without relative paths, are output. If you just specify the `-M' - switch, dependencies of the GNAT internal system files are - omitted. This is typically what you want. If you also specify the - `-a' switch, dependencies of the GNAT internal files are also - listed. Note that dependencies of the objects in external Ada - libraries (see switch `-aL'DIR in the following list) are never - reported. - - `-n' - Don't compile, bind, or link. Checks if all objects are up to date. - If they are not, the full name of the first file that needs to be - recompiled is printed. Repeated use of this option, followed by - compiling the indicated source file, will eventually result in - recompiling all required units. - - `-o EXEC_NAME' - Output executable name. The name of the final executable program - will be EXEC_NAME. If the `-o' switch is omitted the default name - for the executable will be the name of the input file in - appropriate form for an executable file on the host system. - - This switch cannot be used when invoking `gnatmake' with several - `file_names'. - - `-q' - Quiet. When this flag is not set, the commands carried out by - `gnatmake' are displayed. - - `-s' - Recompile if compiler switches have changed since last compilation. - All compiler switches but -I and -o are taken into account in the - following way: orders between different "first letter" switches - are ignored, but orders between same switches are taken into - account. For example, `-O -O2' is different than `-O2 -O', but `-g - -O' is equivalent to `-O -g'. - - `-u' - Unique. Recompile at most the main file. It implies -c. Combined - with -f, it is equivalent to calling the compiler directly. - - `-v' - Verbose. Displays the reason for all recompilations `gnatmake' - decides are necessary. - - `-z' - No main subprogram. Bind and link the program even if the unit name - given on the command line is a package name. The resulting - executable will execute the elaboration routines of the package - and its closure, then the finalization routines. - - ``gcc' switches' - The switch `-g' or any uppercase switch (other than `-A', `-L' or - `-S') or any switch that is more than one character is passed to - `gcc' (e.g. `-O', `-gnato,' etc.) - - Source and library search path switches: - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source files search is undertaken is described in - *Note Search Paths and the Run-Time Library (RTL)::. - - `-aLDIR' - Consider DIR as being an externally provided Ada library. - Instructs `gnatmake' to skip compilation units whose `.ali' files - have been located in directory DIR. This allows you to have - missing bodies for the units in DIR and to ignore out of date - bodies for the same units. You still need to specify the location - of the specs for these units by using the switches `-aIDIR' or - `-IDIR'. Note: this switch is provided for compatibility with - previous versions of `gnatmake'. The easier method of causing - standard libraries to be excluded from consideration is to - write-protect the corresponding ALI files. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is described in - *Note Search Paths for gnatbind::. - - `-ADIR' - Equivalent to `-aLDIR -aIDIR'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-I-' - Do not look for source files in the directory containing the source - file named in the command line. Do not look for ALI or object - files in the directory where `gnatmake' was invoked. - - `-LDIR' - Add directory DIR to the list of directories in which the linker - will search for libraries. This is equivalent to `-largs -L'DIR. - - `-nostdinc' - Do not look for source files in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. We look for - the runtime in the following directories, and stop as soon as a - valid runtime is found ("adainclude" or "ada_source_path", and - "adalib" or "ada_object_path" present): - - * /$rts_path - - * /$rts_path - - * /rts-$rts_path - - The selected path is handled like a normal RTS path. - -  - File: gnat_ug_vxw.info, Node: Mode Switches for gnatmake, Next: Notes on the Command Line, Prev: Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Mode Switches for `gnatmake' - ============================ - - The mode switches (referred to as `mode_switches') allow the inclusion - of switches that are to be passed to the compiler itself, the binder or - the linker. The effect of a mode switch is to cause all subsequent - switches up to the end of the switch list, or up to the next mode - switch, to be interpreted as switches to be passed on to the designated - component of GNAT. - - `-cargs SWITCHES' - Compiler switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all compile - steps performed by `gnatmake'. - - `-bargs SWITCHES' - Binder switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all bind steps - performed by `gnatmake'. - - `-largs SWITCHES' - Linker switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all link steps - performed by `gnatmake'. - -  - File: gnat_ug_vxw.info, Node: Notes on the Command Line, Next: How gnatmake Works, Prev: Mode Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Notes on the Command Line - ========================= - - This section contains some additional useful notes on the operation of - the `gnatmake' command. - - * If `gnatmake' finds no ALI files, it recompiles the main program - and all other units required by the main program. This means that - `gnatmake' can be used for the initial compile, as well as during - subsequent steps of the development cycle. - - * If you enter `gnatmake FILE.adb', where `FILE.adb' is a subunit or - body of a generic unit, `gnatmake' recompiles `FILE.adb' (because - it finds no ALI) and stops, issuing a warning. - - * In `gnatmake' the switch `-I' is used to specify both source and - library file paths. Use `-aI' instead if you just want to specify - source paths only and `-aO' if you want to specify library paths - only. - - * `gnatmake' examines both an ALI file and its corresponding object - file for consistency. If an ALI is more recent than its - corresponding object, or if the object file is missing, the - corresponding source will be recompiled. Note that `gnatmake' - expects an ALI and the corresponding object file to be in the same - directory. - - * `gnatmake' will ignore any files whose ALI file is write-protected. - This may conveniently be used to exclude standard libraries from - consideration and in particular it means that the use of the `-f' - switch will not recompile these files unless `-a' is also - specified. - - * `gnatmake' has been designed to make the use of Ada libraries - particularly convenient. Assume you have an Ada library organized - as follows: OBJ-DIR contains the objects and ALI files for of your - Ada compilation units, whereas INCLUDE-DIR contains the specs of - these units, but no bodies. Then to compile a unit stored in - `main.adb', which uses this Ada library you would just type - - $ gnatmake -aIINCLUDE-DIR -aLOBJ-DIR main - - * Using `gnatmake' along with the `-m (minimal recompilation)' - switch provides a mechanism for avoiding unnecessary - rcompilations. Using this switch, you can update the - comments/format of your source files without having to recompile - everything. Note, however, that adding or deleting lines in a - source files may render its debugging info obsolete. If the file - in question is a spec, the impact is rather limited, as that - debugging info will only be useful during the elaboration phase of - your program. For bodies the impact can be more significant. In - all events, your debugger will warn you if a source file is more - recent than the corresponding object, and alert you to the fact - that the debugging information may be out of date. - -  - File: gnat_ug_vxw.info, Node: How gnatmake Works, Next: Examples of gnatmake Usage, Prev: Notes on the Command Line, Up: The GNAT Make Program gnatmake - - How `gnatmake' Works - ==================== - - Generally `gnatmake' automatically performs all necessary - recompilations and you don't need to worry about how it works. However, - it may be useful to have some basic understanding of the `gnatmake' - approach and in particular to understand how it uses the results of - previous compilations without incorrectly depending on them. - - First a definition: an object file is considered "up to date" if the - corresponding ALI file exists and its time stamp predates that of the - object file and if all the source files listed in the dependency - section of this ALI file have time stamps matching those in the ALI - file. This means that neither the source file itself nor any files that - it depends on have been modified, and hence there is no need to - recompile this file. - - `gnatmake' works by first checking if the specified main unit is up - to date. If so, no compilations are required for the main unit. If not, - `gnatmake' compiles the main program to build a new ALI file that - reflects the latest sources. Then the ALI file of the main unit is - examined to find all the source files on which the main program depends, - and `gnatmake' recursively applies the above procedure on all these - files. - - This process ensures that `gnatmake' only trusts the dependencies in - an existing ALI file if they are known to be correct. Otherwise it - always recompiles to determine a new, guaranteed accurate set of - dependencies. As a result the program is compiled "upside down" from - what may be more familiar as the required order of compilation in some - other Ada systems. In particular, clients are compiled before the units - on which they depend. The ability of GNAT to compile in any order is - critical in allowing an order of compilation to be chosen that - guarantees that `gnatmake' will recompute a correct set of new - dependencies if necessary. - - When invoking `gnatmake' with several FILE_NAMES, if a unit is - imported by several of the executables, it will be recompiled at most - once. - -  - File: gnat_ug_vxw.info, Node: Examples of gnatmake Usage, Prev: How gnatmake Works, Up: The GNAT Make Program gnatmake - - Examples of `gnatmake' Usage - ============================ - - `gnatmake hello.adb' - Compile all files necessary to bind and link the main program - `hello.adb' (containing unit `Hello') and bind and link the - resulting object files to generate an executable file `hello'. - - `gnatmake main1 main2 main3' - Compile all files necessary to bind and link the main programs - `main1.adb' (containing unit `Main1'), `main2.adb' (containing - unit `Main2') and `main3.adb' (containing unit `Main3') and bind - and link the resulting object files to generate three executable - files `main1', `main2' and `main3'. - - `gnatmake -q Main_Unit -cargs -O2 -bargs -l' - Compile all files necessary to bind and link the main program unit - `Main_Unit' (from file `main_unit.adb'). All compilations will be - done with optimization level 2 and the order of elaboration will be - listed by the binder. `gnatmake' will operate in quiet mode, not - displaying commands it is executing. - -  - File: gnat_ug_vxw.info, Node: Renaming Files Using gnatchop, Next: Configuration Pragmas, Prev: The GNAT Make Program gnatmake, Up: Top - - Renaming Files Using `gnatchop' - ******************************* - - This chapter discusses how to handle files with multiple units by using - the `gnatchop' utility. This utility is also useful in renaming files - to meet the standard GNAT default file naming conventions. - - * Menu: - - * Handling Files with Multiple Units:: - * Operating gnatchop in Compilation Mode:: - * Command Line for gnatchop:: - * Switches for gnatchop:: - * Examples of gnatchop Usage:: - -  - File: gnat_ug_vxw.info, Node: Handling Files with Multiple Units, Next: Operating gnatchop in Compilation Mode, Up: Renaming Files Using gnatchop - - Handling Files with Multiple Units - ================================== - - The basic compilation model of GNAT requires that a file submitted to - the compiler have only one unit and there be a strict correspondence - between the file name and the unit name. - - The `gnatchop' utility allows both of these rules to be relaxed, - allowing GNAT to process files which contain multiple compilation units - and files with arbitrary file names. `gnatchop' reads the specified - file and generates one or more output files, containing one unit per - file. The unit and the file name correspond, as required by GNAT. - - If you want to permanently restructure a set of "foreign" files so - that they match the GNAT rules, and do the remaining development using - the GNAT structure, you can simply use `gnatchop' once, generate the - new set of files and work with them from that point on. - - Alternatively, if you want to keep your files in the "foreign" - format, perhaps to maintain compatibility with some other Ada - compilation system, you can set up a procedure where you use `gnatchop' - each time you compile, regarding the source files that it writes as - temporary files that you throw away. - -  - File: gnat_ug_vxw.info, Node: Operating gnatchop in Compilation Mode, Next: Command Line for gnatchop, Prev: Handling Files with Multiple Units, Up: Renaming Files Using gnatchop - - Operating gnatchop in Compilation Mode - ====================================== - - The basic function of `gnatchop' is to take a file with multiple units - and split it into separate files. The boundary between files is - reasonably clear, except for the issue of comments and pragmas. In - default mode, the rule is that any pragmas between units belong to the - previous unit, except that configuration pragmas always belong to the - following unit. Any comments belong to the following unit. These rules - almost always result in the right choice of the split point without - needing to mark it explicitly and most users will find this default to - be what they want. In this default mode it is incorrect to submit a - file containing only configuration pragmas, or one that ends in - configuration pragmas, to `gnatchop'. - - However, using a special option to activate "compilation mode", - `gnatchop' can perform another function, which is to provide exactly - the semantics required by the RM for handling of configuration pragmas - in a compilation. In the absence of configuration pragmas (at the main - file level), this option has no effect, but it causes such - configuration pragmas to be handled in a quite different manner. - - First, in compilation mode, if `gnatchop' is given a file that - consists of only configuration pragmas, then this file is appended to - the `gnat.adc' file in the current directory. This behavior provides - the required behavior described in the RM for the actions to be taken - on submitting such a file to the compiler, namely that these pragmas - should apply to all subsequent compilations in the same compilation - environment. Using GNAT, the current directory, possibly containing a - `gnat.adc' file is the representation of a compilation environment. For - more information on the `gnat.adc' file, see the section on handling of - configuration pragmas *note Handling of Configuration Pragmas::. - - Second, in compilation mode, if `gnatchop' is given a file that - starts with configuration pragmas, and contains one or more units, then - these configuration pragmas are prepended to each of the chopped files. - This behavior provides the required behavior described in the RM for the - actions to be taken on compiling such a file, namely that the pragmas - apply to all units in the compilation, but not to subsequently compiled - units. - - Finally, if configuration pragmas appear between units, they are - appended to the previous unit. This results in the previous unit being - illegal, since the compiler does not accept configuration pragmas that - follow a unit. This provides the required RM behavior that forbids - configuration pragmas other than those preceding the first compilation - unit of a compilation. - - For most purposes, `gnatchop' will be used in default mode. The - compilation mode described above is used only if you need exactly - accurate behavior with respect to compilations, and you have files that - contain multiple units and configuration pragmas. In this circumstance - the use of `gnatchop' with the compilation mode switch provides the - required behavior, and is for example the mode in which GNAT processes - the ACVC tests. - -  - File: gnat_ug_vxw.info, Node: Command Line for gnatchop, Next: Switches for gnatchop, Prev: Operating gnatchop in Compilation Mode, Up: Renaming Files Using gnatchop - - Command Line for `gnatchop' - =========================== - - The `gnatchop' command has the form: - - $ gnatchop switches FILE NAME [FILE NAME FILE NAME ...] - [DIRECTORY] - - The only required argument is the file name of the file to be chopped. - There are no restrictions on the form of this file name. The file itself - contains one or more Ada units, in normal GNAT format, concatenated - together. As shown, more than one file may be presented to be chopped. - - When run in default mode, `gnatchop' generates one output file in - the current directory for each unit in each of the files. - - DIRECTORY, if specified, gives the name of the directory to which - the output files will be written. If it is not specified, all files are - written to the current directory. - - For example, given a file called `hellofiles' containing - - procedure hello; - - with Text_IO; use Text_IO; - procedure hello is - begin - Put_Line ("Hello"); - end hello; - - the command - - $ gnatchop hellofiles - - generates two files in the current directory, one called `hello.ads' - containing the single line that is the procedure spec, and the other - called `hello.adb' containing the remaining text. The original file is - not affected. The generated files can be compiled in the normal manner. - -  - File: gnat_ug_vxw.info, Node: Switches for gnatchop, Next: Examples of gnatchop Usage, Prev: Command Line for gnatchop, Up: Renaming Files Using gnatchop - - Switches for `gnatchop' - ======================= - - `gnatchop' recognizes the following switches: - - `-c' - Causes `gnatchop' to operate in compilation mode, in which - configuration pragmas are handled according to strict RM rules. See - previous section for a full description of this mode. - - `-gnatxxx' - This passes the given `-gnatxxx' switch to `gnat' which is used to - parse the given file. Not all `xxx' options make sense, but for - example, the use of `-gnati2' allows `gnatchop' to process a - source file that uses Latin-2 coding for identifiers. - - `-h' - Causes `gnatchop' to generate a brief help summary to the standard - output file showing usage information. - - `-kMM' - Limit generated file names to the specified number `mm' of - characters. This is useful if the resulting set of files is - required to be interoperable with systems which limit the length - of file names. No space is allowed between the `-k' and the - numeric value. The numeric value may be omitted in which case a - default of `-k8', suitable for use with DOS-like file systems, is - used. If no `-k' switch is present then there is no limit on the - length of file names. - - `-p' - Causes the file modification time stamp of the input file to be - preserved and used for the time stamp of the output file(s). This - may be useful for preserving coherency of time stamps in an - enviroment where `gnatchop' is used as part of a standard build - process. - - `-q' - Causes output of informational messages indicating the set of - generated files to be suppressed. Warnings and error messages are - unaffected. - - `-r' - Generate `Source_Reference' pragmas. Use this switch if the output - files are regarded as temporary and development is to be done in - terms of the original unchopped file. This switch causes - `Source_Reference' pragmas to be inserted into each of the - generated files to refers back to the original file name and line - number. The result is that all error messages refer back to the - original unchopped file. In addition, the debugging information - placed into the object file (when the `-g' switch of `gcc' or - `gnatmake' is specified) also refers back to this original file so - that tools like profilers and debuggers will give information in - terms of the original unchopped file. - - If the original file to be chopped itself contains a - `Source_Reference' pragma referencing a third file, then gnatchop - respects this pragma, and the generated `Source_Reference' pragmas - in the chopped file refer to the original file, with appropriate - line numbers. This is particularly useful when `gnatchop' is used - in conjunction with `gnatprep' to compile files that contain - preprocessing statements and multiple units. - - `-v' - Causes `gnatchop' to operate in verbose mode. The version number - and copyright notice are output, as well as exact copies of the - gnat1 commands spawned to obtain the chop control information. - - `-w' - Overwrite existing file names. Normally `gnatchop' regards it as a - fatal error if there is already a file with the same name as a - file it would otherwise output, in other words if the files to be - chopped contain duplicated units. This switch bypasses this check, - and causes all but the last instance of such duplicated units to - be skipped. - - `--GCC=xxxx' - Specify the path of the GNAT parser to be used. When this switch - is used, no attempt is made to add the prefix to the GNAT parser - executable. - -  - File: gnat_ug_vxw.info, Node: Examples of gnatchop Usage, Prev: Switches for gnatchop, Up: Renaming Files Using gnatchop - - Examples of `gnatchop' Usage - ============================ - - `gnatchop -w hello_s.ada ichbiah/files' - Chops the source file `hello_s.ada'. The output files will be - placed in the directory `ichbiah/files', overwriting any files - with matching names in that directory (no files in the current - directory are modified). - - `gnatchop archive' - Chops the source file `archive' into the current directory. One - useful application of `gnatchop' is in sending sets of sources - around, for example in email messages. The required sources are - simply concatenated (for example, using a Unix `cat' command), and - then `gnatchop' is used at the other end to reconstitute the - original file names. - - `gnatchop file1 file2 file3 direc' - Chops all units in files `file1', `file2', `file3', placing the - resulting files in the directory `direc'. Note that if any units - occur more than once anywhere within this set of files, an error - message is generated, and no files are written. To override this - check, use the `-w' switch, in which case the last occurrence in - the last file will be the one that is output, and earlier - duplicate occurrences for a given unit will be skipped. - -  - File: gnat_ug_vxw.info, Node: Configuration Pragmas, Next: Handling Arbitrary File Naming Conventions Using gnatname, Prev: Renaming Files Using gnatchop, Up: Top - - Configuration Pragmas - ********************* - - In Ada 95, configuration pragmas include those pragmas described as - such in the Ada 95 Reference Manual, as well as - implementation-dependent pragmas that are configuration pragmas. See the - individual descriptions of pragmas in the GNAT Reference Manual for - details on these additional GNAT-specific configuration pragmas. Most - notably, the pragma `Source_File_Name', which allows specifying - non-default names for source files, is a configuration pragma. The - following is a complete list of configuration pragmas recognized by - `GNAT': - - Ada_83 - Ada_95 - C_Pass_By_Copy - Component_Alignment - Discard_Names - Elaboration_Checks - Eliminate - Extend_System - Extensions_Allowed - External_Name_Casing - Float_Representation - Initialize_Scalars - License - Locking_Policy - Long_Float - No_Run_Time - Normalize_Scalars - Polling - Propagate_Exceptions - Queuing_Policy - Ravenscar - Restricted_Run_Time - Restrictions - Reviewable - Source_File_Name - Style_Checks - Suppress - Task_Dispatching_Policy - Unsuppress - Use_VADS_Size - Warnings - Validity_Checks - - * Menu: - - * Handling of Configuration Pragmas:: - * The Configuration Pragmas Files:: - -  - File: gnat_ug_vxw.info, Node: Handling of Configuration Pragmas, Next: The Configuration Pragmas Files, Up: Configuration Pragmas - - Handling of Configuration Pragmas - ================================= - - Configuration pragmas may either appear at the start of a compilation - unit, in which case they apply only to that unit, or they may apply to - all compilations performed in a given compilation environment. - - GNAT also provides the `gnatchop' utility to provide an automatic - way to handle configuration pragmas following the semantics for - compilations (that is, files with multiple units), described in the RM. - See section *note Operating gnatchop in Compilation Mode:: for details. - However, for most purposes, it will be more convenient to edit the - `gnat.adc' file that contains configuration pragmas directly, as - described in the following section. - -  - File: gnat_ug_vxw.info, Node: The Configuration Pragmas Files, Prev: Handling of Configuration Pragmas, Up: Configuration Pragmas - - The Configuration Pragmas Files - =============================== - - In GNAT a compilation environment is defined by the current directory - at the time that a compile command is given. This current directory is - searched for a file whose name is `gnat.adc'. If this file is present, - it is expected to contain one or more configuration pragmas that will - be applied to the current compilation. However, if the switch `-gnatA' - is used, `gnat.adc' is not considered. - - Configuration pragmas may be entered into the `gnat.adc' file either - by running `gnatchop' on a source file that consists only of - configuration pragmas, or more conveniently by direct editing of the - `gnat.adc' file, which is a standard format source file. - - In addition to `gnat.adc', one additional file containing - configuration pragmas may be applied to the current compilation using - the switch `-gnatec'PATH. PATH must designate an existing file that - contains only configuration pragmas. These configuration pragmas are in - addition to those found in `gnat.adc' (provided `gnat.adc' is present - and switch `-gnatA' is not used). - - It is allowed to specify several switches `-gnatec', however only - the last one on the command line will be taken into account. - -  - File: gnat_ug_vxw.info, Node: Handling Arbitrary File Naming Conventions Using gnatname, Next: GNAT Project Manager, Prev: Configuration Pragmas, Up: Top - - Handling Arbitrary File Naming Conventions Using `gnatname' - *********************************************************** - - * Menu: - - * Arbitrary File Naming Conventions:: - * Running gnatname:: - * Switches for gnatname:: - * Examples of gnatname Usage:: - -  - File: gnat_ug_vxw.info, Node: Arbitrary File Naming Conventions, Next: Running gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Arbitrary File Naming Conventions - ================================= - - The GNAT compiler must be able to know the source file name of a - compilation unit. When using the standard GNAT default file naming - conventions (`.ads' for specs, `.adb' for bodies), the GNAT compiler - does not need additional information. - - When the source file names do not follow the standard GNAT default file - naming conventions, the GNAT compiler must be given additional - information through a configuration pragmas file (see *Note - Configuration Pragmas::) or a project file. When the non standard file - naming conventions are well-defined, a small number of pragmas - `Source_File_Name' specifying a naming pattern (see *Note Alternative - File Naming Schemes::) may be sufficient. However, if the file naming - conventions are irregular or arbitrary, a number of pragma - `Source_File_Name' for individual compilation units must be defined. - To help maintain the correspondence between compilation unit names and - source file names within the compiler, GNAT provides a tool `gnatname' - to generate the required pragmas for a set of files. - -  - File: gnat_ug_vxw.info, Node: Running gnatname, Next: Switches for gnatname, Prev: Arbitrary File Naming Conventions, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Running `gnatname' - ================== - - The usual form of the `gnatname' command is - - $ gnatname [SWITCHES] NAMING_PATTERN [NAMING_PATTERNS] - - All of the arguments are optional. If invoked without any argument, - `gnatname' will display its usage. - - When used with at least one naming pattern, `gnatname' will attempt to - find all the compilation units in files that follow at least one of the - naming patterns. To find these compilation units, `gnatname' will use - the GNAT compiler in syntax-check-only mode on all regular files. - - One or several Naming Patterns may be given as arguments to `gnatname'. - Each Naming Pattern is enclosed between double quotes. A Naming - Pattern is a regular expression similar to the wildcard patterns used - in file names by the Unix shells or the DOS prompt. - - Examples of Naming Patterns are - - "*.[12].ada" - "*.ad[sb]*" - "body_*" "spec_*" - - For a more complete description of the syntax of Naming Patterns, see - the second kind of regular expressions described in `g-regexp.ads' (the - "Glob" regular expressions). - - When invoked with no switches, `gnatname' will create a configuration - pragmas file `gnat.adc' in the current working directory, with pragmas - `Source_File_Name' for each file that contains a valid Ada unit. - -  - File: gnat_ug_vxw.info, Node: Switches for gnatname, Next: Examples of gnatname Usage, Prev: Running gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Switches for `gnatname' - ======================= - - Switches for `gnatname' must precede any specified Naming Pattern. - - You may specify any of the following switches to `gnatname': - - `-c`file'' - Create a configuration pragmas file `file' (instead of the default - `gnat.adc'). There may be zero, one or more space between `-c' and - `file'. `file' may include directory information. `file' must be - writeable. There may be only one switch `-c'. When a switch `-c' is - specified, no switch `-P' may be specified (see below). - - `-d`dir'' - Look for source files in directory `dir'. There may be zero, one - or more spaces between `-d' and `dir'. When a switch `-d' is - specified, the current working directory will not be searched for - source files, unless it is explictly specified with a `-d' or `-D' - switch. Several switches `-d' may be specified. If `dir' is a - relative path, it is relative to the directory of the - configuration pragmas file specified with switch `-c', or to the - directory of the project file specified with switch `-P' or, if - neither switch `-c' nor switch `-P' are specified, it is relative - to the current working directory. The directory specified with - switch `-c' must exist and be readable. - - `-D`file'' - Look for source files in all directories listed in text file - `file'. There may be zero, one or more spaces between `-d' and - `dir'. `file' must be an existing, readable text file. Each non - empty line in `file' must be a directory. Specifying switch `-D' - is equivalent to specifying as many switches `-d' as there are non - empty lines in `file'. - - `-h' - Output usage (help) information. The output is written to `stdout'. - - `-P`proj'' - Create or update project file `proj'. There may be zero, one or - more space between `-P' and `proj'. `proj' may include directory - information. `proj' must be writeable. There may be only one - switch `-P'. When a switch `-P' is specified, no switch `-c' may - be specified. - - `-v' - Verbose mode. Output detailed explanation of behavior to `stdout'. - This includes name of the file written, the name of the - directories to search and, for each file in those directories - whose name matches at least one of the Naming Patterns, an - indication of whether the file contains a unit, and if so the name - of the unit. - - `-v -v' - Very Verbose mode. In addition to the output produced in verbose - mode, for each file in the searched directories whose name matches - none of the Naming Patterns, an indication is given that there is - no match. - - `-x`pattern'' - Excluded patterns. Using this switch, it is possible to exclude - some files that would match the name patterns. For example, - `"gnatname -x "*_nt.ada" "*.ada"' will look for Ada units in all - files with the `.ada' extension, except those whose names end with - `_nt.ada'. - -  - File: gnat_ug_vxw.info, Node: Examples of gnatname Usage, Prev: Switches for gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Examples of `gnatname' Usage - ============================ - - $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" - - In this example, the directory `/home/me' must already exist and be - writeable. In addition, the directory `/home/me/sources' (specified by - `-d sources') must exist and be readable. Note the optional spaces after - `-c' and `-d'. - - $ gnatname -P/home/me/proj -x "*_nt_body.ada" -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" - - Note that several switches `-d' may be used, even in conjunction - with one or several switches `-D'. Several Naming Patterns and one - excluded pattern are used in this example. - -  - File: gnat_ug_vxw.info, Node: GNAT Project Manager, Next: Elaboration Order Handling in GNAT, Prev: Handling Arbitrary File Naming Conventions Using gnatname, Up: Top - - GNAT Project Manager - ******************** - - * Menu: - - * Introduction:: - * Examples of Project Files:: - * Project File Syntax:: - * Objects and Sources in Project Files:: - * Importing Projects:: - * Project Extension:: - * External References in Project Files:: - * Packages in Project Files:: - * Variables from Imported Projects:: - * Naming Schemes:: - * Library Projects:: - * Switches Related to Project Files:: - * Tools Supporting Project Files:: - * An Extended Example:: - * Project File Complete Syntax:: - -  - File: gnat_ug_vxw.info, Node: Introduction, Next: Examples of Project Files, Up: GNAT Project Manager - - Introduction - ============ - - This chapter describes GNAT's _Project Manager_, a facility that lets - you configure various properties for a collection of source files. In - particular, you can specify: - * The directory or set of directories containing the source files, - and/or the names of the specific source files themselves - - * The directory in which the compiler's output (`ALI' files, object - files, tree files) will be placed - - * The directory in which the executable programs will be placed - - * Switch settings for any of the project-enabled tools (`gnatmake', - compiler, binder, linker, `gnatls', `gnatxref', `gnatfind'); you - can apply these settings either globally or to individual units - - * The source files containing the main subprogram(s) to be built - - * The source programming language(s) (currently Ada and/or C) - - * Source file naming conventions; you can specify these either - globally or for individual units - - * Menu: - - * Project Files:: - -  - File: gnat_ug_vxw.info, Node: Project Files, Up: Introduction - - Project Files - ------------- - - A "project" is a specific set of values for these properties. You can - define a project's settings in a "project file", a text file with an - Ada-like syntax; a property value is either a string or a list of - strings. Properties that are not explicitly set receive default - values. A project file may interrogate the values of "external - variables" (user-defined command-line switches or environment - variables), and it may specify property settings conditionally, based - on the value of such variables. - - In simple cases, a project's source files depend only on other - source files in the same project, or on the predefined libraries. - ("Dependence" is in the technical sense; for example, one Ada unit - "with"ing another.) However, the Project Manager also allows much more - sophisticated arrangements, with the source files in one project - depending on source files in other projects: - * One project can _import_ other projects containing needed source - files. - - * You can organize GNAT projects in a hierarchy: a _child_ project - can extend a _parent_ project, inheriting the parent's source - files and optionally overriding any of them with alternative - versions - - More generally, the Project Manager lets you structure large development - efforts into hierarchical subsystems, with build decisions deferred to - the subsystem level and thus different compilation environments (switch - settings) used for different subsystems. - - The Project Manager is invoked through the `-P_projectfile_' switch - to `gnatmake' or to the `gnat' front driver. If you want to define (on - the command line) an external variable that is queried by the project - file, additionally use the `-X_vbl_=_value_' switch. The Project - Manager parses and interprets the project file, and drives the invoked - tool based on the project settings. - - The Project Manager supports a wide range of development strategies, - for systems of all sizes. Some typical practices that are easily - handled: - * Using a common set of source files, but generating object files in - different directories via different switch settings - - * Using a mostly-shared set of source files, but with different - versions of some unit or units - - The destination of an executable can be controlled inside a project file - using the `-o' switch. In the absence of such a switch either inside - the project file or on the command line, any executable files generated - by `gnatmake' will be placed in the directory `Exec_Dir' specified in - the project file. If no `Exec_Dir' is specified, they will be placed in - the object directory of the project. - - You can use project files to achieve some of the effects of a source - versioning system (for example, defining separate projects for the - different sets of sources that comprise different releases) but the - Project Manager is independent of any source configuration management - tools that might be used by the developers. - - The next section introduces the main features of GNAT's project - facility through a sequence of examples; subsequent sections will - present the syntax and semantics in more detail. - -  - File: gnat_ug_vxw.info, Node: Examples of Project Files, Next: Project File Syntax, Prev: Introduction, Up: GNAT Project Manager - - Examples of Project Files - ========================= - - This section illustrates some of the typical uses of project files and - explains their basic structure and behavior. - - * Menu: - - * Common Sources with Different Switches and Different Output Directories:: - * Using External Variables:: - * Importing Other Projects:: - * Extending a Project:: - -  - File: gnat_ug_vxw.info, Node: Common Sources with Different Switches and Different Output Directories, Next: Using External Variables, Up: Examples of Project Files - - Common Sources with Different Switches and Different Output Directories - ----------------------------------------------------------------------- - - * Menu: - - * Source Files:: - * Specifying the Object Directory:: - * Specifying the Exec Directory:: - * Project File Packages:: - * Specifying Switch Settings:: - * Main Subprograms:: - * Source File Naming Conventions:: - * Source Language(s):: - - Assume that the Ada source files `pack.ads', `pack.adb', and `proc.adb' - are in the `/common' directory. The file `proc.adb' contains an Ada - main subprogram `Proc' that "with"s package `Pack'. We want to compile - these source files under two sets of switches: - * When debugging, we want to pass the `-g' switch to `gnatmake', and - the `-gnata', `-gnato', and `-gnatE' switches to the compiler; the - compiler's output is to appear in `/common/debug' - - * When preparing a release version, we want to pass the `-O2' switch - to the compiler; the compiler's output is to appear in - `/common/release' - - The GNAT project files shown below, respectively `debug.gpr' and - `release.gpr' in the `/common' directory, achieve these effects. - - Diagrammatically: - /common - debug.gpr - release.gpr - pack.ads - pack.adb - proc.adb - /common/debug {-g, -gnata, -gnato, -gnatE} - proc.ali, proc.o - pack.ali, pack.o - /common/release {-O2} - proc.ali, proc.o - pack.ali, pack.o - Here are the project files: - project Debug is - for Object_Dir use "debug"; - for Main use ("proc"); - - package Builder is - for Default_Switches ("Ada") use ("-g"); - end Builder; - - package Compiler is - for Default_Switches ("Ada") - use ("-fstack-check", "-gnata", "-gnato", "-gnatE"); - end Compiler; - end Debug; - - project Release is - for Object_Dir use "release"; - for Exec_Dir use "."; - for Main use ("proc"); - - package Compiler is - for Default_Switches ("Ada") use ("-O2"); - end Compiler; - end Release; - - The name of the project defined by `debug.gpr' is `"Debug"' (case - insensitive), and analogously the project defined by `release.gpr' is - `"Release"'. For consistency the file should have the same name as the - project, and the project file's extension should be `"gpr"'. These - conventions are not required, but a warning is issued if they are not - followed. - - If the current directory is `/temp', then the command - gnatmake -P/common/debug.gpr - - generates object and ALI files in `/common/debug', and the `proc' - executable also in `/common/debug', using the switch settings defined in - the project file. - - Likewise, the command - gnatmake -P/common/release.gpr - - generates object and ALI files in `/common/release', and the `proc' - executable in `/common', using the switch settings from the project - file. - -  - File: gnat_ug_vxw.info, Node: Source Files, Next: Specifying the Object Directory, Up: Common Sources with Different Switches and Different Output Directories - - Source Files - ............ - - If a project file does not explicitly specify a set of source - directories or a set of source files, then by default the project's - source files are the Ada source files in the project file directory. - Thus `pack.ads', `pack.adb', and `proc.adb' are the source files for - both projects. - -  - File: gnat_ug_vxw.info, Node: Specifying the Object Directory, Next: Specifying the Exec Directory, Prev: Source Files, Up: Common Sources with Different Switches and Different Output Directories - - Specifying the Object Directory - ............................... - - Several project properties are modeled by Ada-style _attributes_; you - define the property by supplying the equivalent of an Ada attribute - definition clause in the project file. A project's object directory is - such a property; the corresponding attribute is `Object_Dir', and its - value is a string expression. A directory may be specified either as - absolute or as relative; in the latter case, it is relative to the - project file directory. Thus the compiler's output is directed to - `/common/debug' (for the `Debug' project) and to `/common/release' (for - the `Release' project). If `Object_Dir' is not specified, then the - default is the project file directory. - -  - File: gnat_ug_vxw.info, Node: Specifying the Exec Directory, Next: Project File Packages, Prev: Specifying the Object Directory, Up: Common Sources with Different Switches and Different Output Directories - - Specifying the Exec Directory - ............................. - - A project's exec directory is another property; the corresponding - attribute is `Exec_Dir', and its value is also a string expression, - either specified as relative or absolute. If `Exec_Dir' is not - specified, then the default is the object directory (which may also be - the project file directory if attribute `Object_Dir' is not specified). - Thus the executable is placed in `/common/debug' for the `Debug' - project (attribute `Exec_Dir' not specified) and in `/common' for the - `Release' project. - -  - File: gnat_ug_vxw.info, Node: Project File Packages, Next: Specifying Switch Settings, Prev: Specifying the Exec Directory, Up: Common Sources with Different Switches and Different Output Directories - - Project File Packages - ..................... - - A GNAT tool integrated with the Project Manager is modeled by a - corresponding package in the project file. The `Debug' project defines - the packages `Builder' (for `gnatmake') and `Compiler'; the `Release' - project defines only the `Compiler' package. - - The Ada package syntax is not to be taken literally. Although - packages in project files bear a surface resemblance to packages in Ada - source code, the notation is simply a way to convey a grouping of - properties for a named entity. Indeed, the package names permitted in - project files are restricted to a predefined set, corresponding to the - project-aware tools, and the contents of packages are limited to a - small set of constructs. The packages in the example above contain - attribute definitions. - -  - File: gnat_ug_vxw.info, Node: Specifying Switch Settings, Next: Main Subprograms, Prev: Project File Packages, Up: Common Sources with Different Switches and Different Output Directories - - Specifying Switch Settings - .......................... - - Switch settings for a project-aware tool can be specified through - attributes in the package corresponding to the tool. The example above - illustrates one of the relevant attributes, `Default_Switches', defined - in the packages in both project files. Unlike simple attributes like - `Source_Dirs', `Default_Switches' is known as an _associative array_. - When you define this attribute, you must supply an "index" (a literal - string), and the effect of the attribute definition is to set the value - of the "array" at the specified "index". For the `Default_Switches' - attribute, the index is a programming language (in our case, Ada) , and - the value specified (after `use') must be a list of string expressions. - - The attributes permitted in project files are restricted to a - predefined set. Some may appear at project level, others in packages. - For any attribute that is an associate array, the index must always be a - literal string, but the restrictions on this string (e.g., a file name - or a language name) depend on the individual attribute. Also depending - on the attribute, its specified value will need to be either a string - or a string list. - - In the `Debug' project, we set the switches for two tools, - `gnatmake' and the compiler, and thus we include corresponding - packages, with each package defining the `Default_Switches' attribute - with index `"Ada"'. Note that the package corresponding to `gnatmake' - is named `Builder'. The `Release' project is similar, but with just - the `Compiler' package. - - In project `Debug' above the switches starting with `-gnat' that are - specified in package `Compiler' could have been placed in package - `Builder', since `gnatmake' transmits all such switches to the compiler. - -  - File: gnat_ug_vxw.info, Node: Main Subprograms, Next: Source File Naming Conventions, Prev: Specifying Switch Settings, Up: Common Sources with Different Switches and Different Output Directories - - Main Subprograms - ................ - - One of the properties of a project is its list of main subprograms - (actually a list of names of source files containing main subprograms, - with the file extension optional. This property is captured in the - `Main' attribute, whose value is a list of strings. If a project - defines the `Main' attribute, then you do not need to identify the main - subprogram(s) when invoking `gnatmake' (see *Note gnatmake and Project - Files::). - -  - File: gnat_ug_vxw.info, Node: Source File Naming Conventions, Next: Source Language(s), Prev: Main Subprograms, Up: Common Sources with Different Switches and Different Output Directories - - Source File Naming Conventions - .............................. - - Since the project files do not specify any source file naming - conventions, the GNAT defaults are used. The mechanism for defining - source file naming conventions - a package named `Naming' - will be - described below (*note Naming Schemes::). - -  - File: gnat_ug_vxw.info, Node: Source Language(s), Prev: Source File Naming Conventions, Up: Common Sources with Different Switches and Different Output Directories - - Source Language(s) - .................. - - Since the project files do not specify a `Languages' attribute, by - default the GNAT tools assume that the language of the project file is - Ada. More generally, a project can comprise source files in Ada, C, - and/or other languages. - -  - File: gnat_ug_vxw.info, Node: Using External Variables, Next: Importing Other Projects, Prev: Common Sources with Different Switches and Different Output Directories, Up: Examples of Project Files - - Using External Variables - ------------------------ - - Instead of supplying different project files for debug and release, we - can define a single project file that queries an external variable (set - either on the command line or via an environment variable) in order to - conditionally define the appropriate settings. Again, assume that the - source files `pack.ads', `pack.adb', and `proc.adb' are located in - directory `/common'. The following project file, `build.gpr', queries - the external variable named `STYLE' and defines an object directory and - switch settings based on whether the value is `"deb"' (debug) or - `"rel"' (release), where the default is `"deb"'. - - project Build is - for Main use ("proc"); - - type Style_Type is ("deb", "rel"); - Style : Style_Type := external ("STYLE", "deb"); - - case Style is - when "deb" => - for Object_Dir use "debug"; - - when "rel" => - for Object_Dir use "release"; - for Exec_Dir use "."; - end case; - - package Builder is - - case Style is - when "deb" => - for Default_Switches ("Ada") use ("-g"); - end case; - - end Builder; - - package Compiler is - - case Style is - when "deb" => - for Default_Switches ("Ada") use ("-gnata", "-gnato", "-gnatE"); - - when "rel" => - for Default_Switches ("Ada") use ("-O2"); - end case; - - end Compiler; - - end Build; - - `Style_Type' is an example of a _string type_, which is the project - file analog of an Ada enumeration type but containing string literals - rather than identifiers. `Style' is declared as a variable of this - type. - - The form `external("STYLE", "deb")' is known as an _external - reference_; its first argument is the name of an _external variable_, - and the second argument is a default value to be used if the external - variable doesn't exist. You can define an external variable on the - command line via the `-X' switch, or you can use an environment - variable as an external variable. - - Each `case' construct is expanded by the Project Manager based on the - value of `Style'. Thus the command - gnatmake -P/common/build.gpr -XSTYLE=deb - - is equivalent to the `gnatmake' invocation using the project file - `debug.gpr' in the earlier example. So is the command - gnatmake -P/common/build.gpr - - since `"deb"' is the default for `STYLE'. - - Analogously, - gnatmake -P/common/build.gpr -XSTYLE=rel - - is equivalent to the `gnatmake' invocation using the project file - `release.gpr' in the earlier example. - -  - File: gnat_ug_vxw.info, Node: Importing Other Projects, Next: Extending a Project, Prev: Using External Variables, Up: Examples of Project Files - - Importing Other Projects - ------------------------ - - A compilation unit in a source file in one project may depend on - compilation units in source files in other projects. To obtain this - behavior, the dependent project must _import_ the projects containing - the needed source files. This effect is embodied in syntax similar to - an Ada `with' clause, but the "with"ed entities are strings denoting - project files. - - As an example, suppose that the two projects `GUI_Proj' and - `Comm_Proj' are defined in the project files `gui_proj.gpr' and - `comm_proj.gpr' in directories `/gui' and `/comm', respectively. - Assume that the source files for `GUI_Proj' are `gui.ads' and - `gui.adb', and that the source files for `Comm_Proj' are `comm.ads' and - `comm.adb', with each set of files located in its respective project - file directory. Diagrammatically: - - /gui - gui_proj.gpr - gui.ads - gui.adb - - /comm - comm_proj.gpr - comm.ads - comm.adb - - We want to develop an application in directory `/app' that "with"s the - packages `GUI' and `Comm', using the properties of the corresponding - project files (e.g. the switch settings and object directory). - Skeletal code for a main procedure might be something like the - following: - - with GUI, Comm; - procedure App_Main is - ... - begin - ... - end App_Main; - - Here is a project file, `app_proj.gpr', that achieves the desired - effect: - - with "/gui/gui_proj", "/comm/comm_proj"; - project App_Proj is - for Main use ("app_main"); - end App_Proj; - - Building an executable is achieved through the command: - gnatmake -P/app/app_proj - - which will generate the `app_main' executable in the directory where - `app_proj.gpr' resides. - - If an imported project file uses the standard extension (`gpr') then - (as illustrated above) the `with' clause can omit the extension. - - Our example specified an absolute path for each imported project - file. Alternatively, you can omit the directory if either - * The imported project file is in the same directory as the - importing project file, or - - * You have defined an environment variable `ADA_PROJECT_PATH' that - includes the directory containing the needed project file. - - Thus, if we define `ADA_PROJECT_PATH' to include `/gui' and `/comm', - then our project file `app_proj.gpr' could be written as follows: - - with "gui_proj", "comm_proj"; - project App_Proj is - for Main use ("app_main"); - end App_Proj; - - Importing other projects raises the possibility of ambiguities. For - example, the same unit might be present in different imported projects, - or it might be present in both the importing project and an imported - project. Both of these conditions are errors. Note that in the - current version of the Project Manager, it is illegal to have an - ambiguous unit even if the unit is never referenced by the importing - project. This restriction may be relaxed in a future release. - -  - File: gnat_ug_vxw.info, Node: Extending a Project, Prev: Importing Other Projects, Up: Examples of Project Files - - Extending a Project - ------------------- - - A common situation in large software systems is to have multiple - implementations for a common interface; in Ada terms, multiple versions - of a package body for the same specification. For example, one - implementation might be safe for use in tasking programs, while another - might only be used in sequential applications. This can be modeled in - GNAT using the concept of _project extension_. If one project (the - "child") _extends_ another project (the "parent") then by default all - source files of the parent project are inherited by the child, but the - child project can override any of the parent's source files with new - versions, and can also add new files. This facility is the project - analog of extension in Object-Oriented Programming. Project - hierarchies are permitted (a child project may be the parent of yet - another project), and a project that inherits one project can also - import other projects. - - As an example, suppose that directory `/seq' contains the project - file `seq_proj.gpr' and the source files `pack.ads', `pack.adb', and - `proc.adb': - - /seq - pack.ads - pack.adb - proc.adb - seq_proj.gpr - - Note that the project file can simply be empty (that is, no attribute or - package is defined): - - project Seq_Proj is - end Seq_Proj; - - implying that its source files are all the Ada source files in the - project directory. - - Suppose we want to supply an alternate version of `pack.adb', in - directory `/tasking', but use the existing versions of `pack.ads' and - `proc.adb'. We can define a project `Tasking_Proj' that inherits - `Seq_Proj': - - /tasking - pack.adb - tasking_proj.gpr - - project Tasking_Proj extends "/seq/seq_proj" is - end Tasking_Proj; - - The version of `pack.adb' used in a build depends on which project file - is specified. - - Note that we could have designed this using project import rather - than project inheritance; a `base' project would contain the sources for - `pack.ads' and `proc.adb', a sequential project would import `base' and - add `pack.adb', and likewise a tasking project would import `base' and - add a different version of `pack.adb'. The choice depends on whether - other sources in the original project need to be overridden. If they - do, then project extension is necessary, otherwise, importing is - sufficient. - -  - File: gnat_ug_vxw.info, Node: Project File Syntax, Next: Objects and Sources in Project Files, Prev: Examples of Project Files, Up: GNAT Project Manager - - Project File Syntax - =================== - - * Menu: - - * Basic Syntax:: - * Packages:: - * Expressions:: - * String Types:: - * Variables:: - * Attributes:: - * Associative Array Attributes:: - * case Constructions:: - - This section describes the structure of project files. - - A project may be an _independent project_, entirely defined by a - single project file. Any Ada source file in an independent project - depends only on the predefined library and other Ada source files in - the same project. - - A project may also "depend on" other projects, in either or both of the - following ways: - * It may import any number of projects - - * It may extend at most one other project - - The dependence relation is a directed acyclic graph (the subgraph - reflecting the "extends" relation is a tree). - - A project's "immediate sources" are the source files directly - defined by that project, either implicitly by residing in the project - file's directory, or explicitly through any of the source-related - attributes described below. More generally, a project PROJ's "sources" - are the immediate sources of PROJ together with the immediate sources - (unless overridden) of any project on which PROJ depends (either - directly or indirectly). - -  - File: gnat_ug_vxw.info, Node: Basic Syntax, Next: Packages, Up: Project File Syntax - - Basic Syntax - ------------ - - As seen in the earlier examples, project files have an Ada-like syntax. - The minimal project file is: - project Empty is - - end Empty; - - The identifier `Empty' is the name of the project. This project name - must be present after the reserved word `end' at the end of the project - file, followed by a semi-colon. - - Any name in a project file, such as the project name or a variable - name, has the same syntax as an Ada identifier. - - The reserved words of project files are the Ada reserved words plus - `extends', `external', and `project'. Note that the only Ada reserved - words currently used in project file syntax are: - - * `case' - - * `end' - - * `for' - - * `is' - - * `others' - - * `package' - - * `renames' - - * `type' - - * `use' - - * `when' - - * `with' - - Comments in project files have the same syntax as in Ada, two - consecutives hyphens through the end of the line. - -  - File: gnat_ug_vxw.info, Node: Packages, Next: Expressions, Prev: Basic Syntax, Up: Project File Syntax - - Packages - -------- - - A project file may contain _packages_. The name of a package must be one - of the identifiers (case insensitive) from a predefined list, and a - package with a given name may only appear once in a project file. The - predefined list includes the following packages: - - * `Naming' - - * `Builder' - - * `Compiler' - - * `Binder' - - * `Linker' - - * `Finder' - - * `Cross_Reference' - - * `gnatls' - - (The complete list of the package names and their attributes can be - found in file `prj-attr.adb'). - - In its simplest form, a package may be empty: - - project Simple is - package Builder is - end Builder; - end Simple; - - A package may contain _attribute declarations_, _variable declarations_ - and _case constructions_, as will be described below. - - When there is ambiguity between a project name and a package name, - the name always designates the project. To avoid possible confusion, it - is always a good idea to avoid naming a project with one of the names - allowed for packages or any name that starts with `gnat'. - -  - File: gnat_ug_vxw.info, Node: Expressions, Next: String Types, Prev: Packages, Up: Project File Syntax - - Expressions - ----------- - - An _expression_ is either a _string expression_ or a _string list - expression_. - - A _string expression_ is either a _simple string expression_ or a - _compound string expression_. - - A _simple string expression_ is one of the following: - * A literal string; e.g.`"comm/my_proj.gpr"' - - * A string-valued variable reference (see *Note Variables::) - - * A string-valued attribute reference (see *Note Attributes::) - - * An external reference (see *Note External References in Project - Files::) - - A _compound string expression_ is a concatenation of string expressions, - using `"&"' - Path & "/" & File_Name & ".ads" - - A _string list expression_ is either a _simple string list expression_ - or a _compound string list expression_. - - A _simple string list expression_ is one of the following: - * A parenthesized list of zero or more string expressions, separated - by commas - File_Names := (File_Name, "gnat.adc", File_Name & ".orig"); - Empty_List := (); - - * A string list-valued variable reference - - * A string list-valued attribute reference - - A _compound string list expression_ is the concatenation (using `"&"') - of a simple string list expression and an expression. Note that each - term in a compound string list expression, except the first, may be - either a string expression or a string list expression. - - File_Name_List := () & File_Name; -- One string in this list - Extended_File_Name_List := File_Name_List & (File_Name & ".orig"); - -- Two strings - Big_List := File_Name_List & Extended_File_Name_List; - -- Concatenation of two string lists: three strings - Illegal_List := "gnat.adc" & Extended_File_Name_List; - -- Illegal: must start with a string list - -  - File: gnat_ug_vxw.info, Node: String Types, Next: Variables, Prev: Expressions, Up: Project File Syntax - - String Types - ------------ - - The value of a variable may be restricted to a list of string literals. - The restricted list of string literals is given in a _string type - declaration_. - - Here is an example of a string type declaration: - - type OS is ("NT, "nt", "Unix", "Linux", "other OS"); - - Variables of a string type are called _typed variables_; all other - variables are called _untyped variables_. Typed variables are - particularly useful in `case' constructions (see *Note case - Constructions::). - - A string type declaration starts with the reserved word `type', - followed by the name of the string type (case-insensitive), followed by - the reserved word `is', followed by a parenthesized list of one or more - string literals separated by commas, followed by a semicolon. - - The string literals in the list are case sensitive and must all be - different. They may include any graphic characters allowed in Ada, - including spaces. - - A string type may only be declared at the project level, not inside - a package. - - A string type may be referenced by its name if it has been declared - in the same project file, or by its project name, followed by a dot, - followed by the string type name. - -  - File: gnat_ug_vxw.info, Node: Variables, Next: Attributes, Prev: String Types, Up: Project File Syntax - - Variables - --------- - - A variable may be declared at the project file level, or in a package. - Here are some examples of variable declarations: - - This_OS : OS := external ("OS"); -- a typed variable declaration - That_OS := "Linux"; -- an untyped variable declaration - - A _typed variable declaration_ includes the variable name, followed by - a colon, followed by the name of a string type, followed by `:=', - followed by a simple string expression. - - An _untyped variable declaration_ includes the variable name, - followed by `:=', followed by an expression. Note that, despite the - terminology, this form of "declaration" resembles more an assignment - than a declaration in Ada. It is a declaration in several senses: - * The variable name does not need to be defined previously - - * The declaration establishes the _kind_ (string versus string list) - of the variable, and later declarations of the same variable need - to be consistent with this - - A string variable declaration (typed or untyped) declares a variable - whose value is a string. This variable may be used as a string - expression. - File_Name := "readme.txt"; - Saved_File_Name := File_Name & ".saved"; - - A string list variable declaration declares a variable whose value is a - list of strings. The list may contain any number (zero or more) of - strings. - - Empty_List := (); - List_With_One_Element := ("-gnaty"); - List_With_Two_Elements := List_With_One_Element & "-gnatg"; - Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada" - "pack2.ada", "util_.ada", "util.ada"); - - The same typed variable may not be declared more than once at project - level, and it may not be declared more than once in any package; it is - in effect a constant or a readonly variable. - - The same untyped variable may be declared several times. In this - case, the new value replaces the old one, and any subsequent reference - to the variable uses the new value. However, as noted above, if a - variable has been declared as a string, all subsequent declarations - must give it a string value. Similarly, if a variable has been declared - as a string list, all subsequent declarations must give it a string - list value. - - A _variable reference_ may take several forms: - - * The simple variable name, for a variable in the current package - (if any) or in the current project - - * A context name, followed by a dot, followed by the variable name. - - A _context_ may be one of the following: - - * The name of an existing package in the current project - - * The name of an imported project of the current project - - * The name of an ancestor project (i.e., a project extended by the - current project, either directly or indirectly) - - * An imported/parent project name, followed by a dot, followed by a - package name - - A variable reference may be used in an expression. - -  - File: gnat_ug_vxw.info, Node: Attributes, Next: Associative Array Attributes, Prev: Variables, Up: Project File Syntax - - Attributes - ---------- - - A project (and its packages) may have _attributes_ that define the - project's properties. Some attributes have values that are strings; - others have values that are string lists. - - There are two categories of attributes: _simple attributes_ and - _associative arrays_ (see *Note Associative Array Attributes::). - - The names of the attributes are restricted; there is a list of - project attributes, and a list of package attributes for each package. - The names are not case sensitive. - - The project attributes are as follows (all are simple attributes): - - _Attribute Name_ _Value_ - `Source_Files' string list - `Source_Dirs' string list - `Source_List_File' string - `Object_Dir' string - `Exec_Dir' string - `Main' string list - `Languages' string list - `Library_Dir' string - `Library_Name' string - `Library_Kind' string - `Library_Elaboration' string - `Library_Version' string - - The attributes for package `Naming' are as follows (see *Note Naming - Schemes::): - - Attribute Name Category Index Value - `Specification_Suffix' associative language name string - array - `Implementation_Suffix' associative language name string - array - `Separate_Suffix' simple n/a string - attribute - `Casing' simple n/a string - attribute - `Dot_Replacement' simple n/a string - attribute - `Specification' associative Ada unit name string - array - `Implementation' associative Ada unit name string - array - `Specification_Exceptions' associative language name string list - array - `Implementation_Exceptions' associative language name string list - array - - The attributes for package `Builder', `Compiler', `Binder', `Linker', - `Cross_Reference', and `Finder' are as follows (see *Note Switches and - Project Files::). - - Attribute Name Category Index Value - `Default_Switches' associative language name string list - array - `Switches' associative file name string list - array - - In addition, package `Builder' has a single string attribute - `Local_Configuration_Pragmas' and package `Builder' has a single string - attribute `Global_Configuration_Pragmas'. - - The attribute for package `Glide' are not documented: they are for - internal use only. - - Each simple attribute has a default value: the empty string (for - string-valued attributes) and the empty list (for string list-valued - attributes). - - Similar to variable declarations, an attribute declaration defines a - new value for an attribute. - - Examples of simple attribute declarations: - - for Object_Dir use "objects"; - for Source_Dirs use ("units", "test/drivers"); - - A "simple attribute declaration" starts with the reserved word `for', - followed by the name of the attribute, followed by the reserved word - `use', followed by an expression (whose kind depends on the attribute), - followed by a semicolon. - - Attributes may be referenced in expressions. The general form for - such a reference is `'': the entity for which the - attribute is defined, followed by an apostrophe, followed by the name - of the attribute. For associative array attributes, a litteral string - between parentheses need to be supplied as index. - - Examples are: - - project'Object_Dir - Naming'Dot_Replacement - Imported_Project'Source_Dirs - Imported_Project.Naming'Casing - Builder'Default_Switches("Ada") - - The entity may be: - * `project' for an attribute of the current project - - * The name of an existing package of the current project - - * The name of an imported project - - * The name of a parent project (extended by the current project) - - * An imported/parent project name, followed by a dot, followed - by a package name - - Example: - project Prj is - for Source_Dirs use project'Source_Dirs & "units"; - for Source_Dirs use project'Source_Dirs & "test/drivers" - end Prj; - - In the first attribute declaration, initially the attribute - `Source_Dirs' has the default value: an empty string list. After this - declaration, `Source_Dirs' is a string list of one element: "units". - After the second attribute declaration `Source_Dirs' is a string list of - two elements: "units" and "test/drivers". - - Note: this example is for illustration only. In practice, the - project file would contain only one attribute declaration: - - for Source_Dirs use ("units", "test/drivers"); - -  - File: gnat_ug_vxw.info, Node: Associative Array Attributes, Next: case Constructions, Prev: Attributes, Up: Project File Syntax - - Associative Array Attributes - ---------------------------- - - Some attributes are defined as _associative arrays_. An associative - array may be regarded as a function that takes a string as a parameter - and delivers a string or string list value as its result. - - Here are some examples of associative array attribute declarations: - - for Implementation ("main") use "Main.ada"; - for Switches ("main.ada") use ("-v", "-gnatv"); - for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g"; - - Like untyped variables and simple attributes, associative array - attributes may be declared several times. Each declaration supplies a - new value for the attribute, replacing the previous setting. - -  - File: gnat_ug_vxw.info, Node: case Constructions, Prev: Associative Array Attributes, Up: Project File Syntax - - `case' Constructions - -------------------- - - A `case' construction is used in a project file to effect conditional - behavior. Here is a typical example: - - project MyProj is - type OS_Type is ("Linux", "Unix", "NT", "VMS"); - - OS : OS_Type := external ("OS", "Linux"); - - package Compiler is - case OS is - when "Linux" | "Unix" => - for Default_Switches ("Ada") use ("-gnath"); - when "NT" => - for Default_Switches ("Ada") use ("-gnatP"); - when others => - end case; - end Compiler; - end MyProj; - - The syntax of a `case' construction is based on the Ada case statement - (although there is no `null' construction for empty alternatives). - - Following the reserved word `case' there is the case variable (a - typed string variable), the reserved word `is', and then a sequence of - one or more alternatives. Each alternative comprises the reserved word - `when', either a list of literal strings separated by the `"|"' - character or the reserved word `others', and the `"=>"' token. Each - literal string must belong to the string type that is the type of the - case variable. An `others' alternative, if present, must occur last. - The `end case;' sequence terminates the case construction. - - After each `=>', there are zero or more constructions. The only - constructions allowed in a case construction are other case - constructions and attribute declarations. String type declarations, - variable declarations and package declarations are not allowed. - - The value of the case variable is often given by an external - reference (see *Note External References in Project Files::). - -  - File: gnat_ug_vxw.info, Node: Objects and Sources in Project Files, Next: Importing Projects, Prev: Project File Syntax, Up: GNAT Project Manager - - Objects and Sources in Project Files - ==================================== - - * Menu: - - * Object Directory:: - * Exec Directory:: - * Source Directories:: - * Source File Names:: - - Each project has exactly one object directory and one or more source - directories. The source directories must contain at least one source - file, unless the project file explicitly specifies that no source - files are present (see *Note Source File Names::). - -  - File: gnat_ug_vxw.info, Node: Object Directory, Next: Exec Directory, Up: Objects and Sources in Project Files - - Object Directory - ---------------- - - The object directory for a project is the directory containing the - compiler's output (such as `ALI' files and object files) for the - project's immediate sources. Note that for inherited sources (when - extending a parent project) the parent project's object directory is - used. - - The object directory is given by the value of the attribute - `Object_Dir' in the project file. - - for Object_Dir use "objects"; - - The attribute OBJECT_DIR has a string value, the path name of the object - directory. The path name may be absolute or relative to the directory - of the project file. This directory must already exist, and be readable - and writable. - - By default, when the attribute `Object_Dir' is not given an explicit - value or when its value is the empty string, the object directory is - the same as the directory containing the project file. - -  - File: gnat_ug_vxw.info, Node: Exec Directory, Next: Source Directories, Prev: Object Directory, Up: Objects and Sources in Project Files - - Exec Directory - -------------- - - The exec directory for a project is the directory containing the - executables for the project's main subprograms. - - The exec directory is given by the value of the attribute `Exec_Dir' - in the project file. - - for Exec_Dir use "executables"; - - The attribute EXEC_DIR has a string value, the path name of the exec - directory. The path name may be absolute or relative to the directory - of the project file. This directory must already exist, and be writable. - - By default, when the attribute `Exec_Dir' is not given an explicit - value or when its value is the empty string, the exec directory is the - same as the object directory of the project file. - -  - File: gnat_ug_vxw.info, Node: Source Directories, Next: Source File Names, Prev: Exec Directory, Up: Objects and Sources in Project Files - - Source Directories - ------------------ - - The source directories of a project are specified by the project file - attribute `Source_Dirs'. - - This attribute's value is a string list. If the attribute is not - given an explicit value, then there is only one source directory, the - one where the project file resides. - - A `Source_Dirs' attribute that is explicitly defined to be the empty - list, as in - - for Source_Dirs use (); - - indicates that the project contains no source files. - - Otherwise, each string in the string list designates one or more - source directories. - - for Source_Dirs use ("sources", "test/drivers"); - - If a string in the list ends with `"/**"', then the directory whose - path name precedes the two asterisks, as well as all its subdirectories - (recursively), are source directories. - - for Source_Dirs use ("/system/sources/**"); - - Here the directory `/system/sources' and all of its subdirectories - (recursively) are source directories. - - To specify that the source directories are the directory of the - project file and all of its subdirectories, you can declare - `Source_Dirs' as follows: - for Source_Dirs use ("./**"); - - Each of the source directories must exist and be readable. - -  - File: gnat_ug_vxw.info, Node: Source File Names, Prev: Source Directories, Up: Objects and Sources in Project Files - - Source File Names - ----------------- - - In a project that contains source files, their names may be specified - by the attributes `Source_Files' (a string list) or `Source_List_File' - (a string). Source file names never include any directory information. - - If the attribute `Source_Files' is given an explicit value, then each - element of the list is a source file name. - - for Source_Files use ("main.adb"); - for Source_Files use ("main.adb", "pack1.ads", "pack2.adb"); - - If the attribute `Source_Files' is not given an explicit value, but the - attribute `Source_List_File' is given a string value, then the source - file names are contained in the text file whose path name (absolute or - relative to the directory of the project file) is the value of the - attribute `Source_List_File'. - - Each line in the file that is not empty or is not a comment contains - a source file name. A comment line starts with two hyphens. - - for Source_List_File use "source_list.txt"; - - By default, if neither the attribute `Source_Files' nor the attribute - `Source_List_File' is given an explicit value, then each file in the - source directories that conforms to the project's naming scheme (see - *Note Naming Schemes::) is an immediate source of the project. - - A warning is issued if both attributes `Source_Files' and - `Source_List_File' are given explicit values. In this case, the - attribute `Source_Files' prevails. - - Each source file name must be the name of one and only one existing - source file in one of the source directories. - - A `Source_Files' attribute defined with an empty list as its value - indicates that there are no source files in the project. - - Except for projects that are clearly specified as containing no Ada - source files (`Source_Dirs' or `Source_Files' specified as an empty - list, or `Languages' specified without `"Ada"' in the list) - for Source_Dirs use (); - for Source_Files use (); - for Languages use ("C", "C++"); - - a project must contain at least one immediate source. - - Projects with no source files are useful as template packages (see - *Note Packages in Project Files::) for other projects; in particular to - define a package `Naming' (see *Note Naming Schemes::). - -  - File: gnat_ug_vxw.info, Node: Importing Projects, Next: Project Extension, Prev: Objects and Sources in Project Files, Up: GNAT Project Manager - - Importing Projects - ================== - - An immediate source of a project P may depend on source files that are - neither immediate sources of P nor in the predefined library. To get - this effect, P must _import_ the projects that contain the needed - source files. - - with "project1", "utilities.gpr"; - with "/namings/apex.gpr"; - project Main is - ... - - As can be seen in this example, the syntax for importing projects is - similar to the syntax for importing compilation units in Ada. However, - project files use literal strings instead of names, and the `with' - clause identifies project files rather than packages. - - Each literal string is the file name or path name (absolute or - relative) of a project file. If a string is simply a file name, with no - path, then its location is determined by the _project path_: - - * If the environment variable `ADA_PROJECT_PATH' exists, then the - project path includes all the directories in this environment - variable, plus the directory of the project file. - - * If the environment variable `ADA_PROJECT_PATH' does not exist, - then the project path contains only one directory, namely the one - where the project file is located. - - If a relative pathname is used as in - - with "tests/proj"; - - then the path is relative to the directory where the importing project - file is located. Any symbolic link will be fully resolved in the - directory of the importing project file before the imported project - file is looked up. - - When the `with''ed project file name does not have an extension, the - default is `.gpr'. If a file with this extension is not found, then the - file name as specified in the `with' clause (no extension) will be - used. In the above example, if a file `project1.gpr' is found, then it - will be used; otherwise, if a file `project1' exists then it will be - used; if neither file exists, this is an error. - - A warning is issued if the name of the project file does not match - the name of the project; this check is case insensitive. - - Any source file that is an immediate source of the imported project - can be used by the immediate sources of the importing project, and - recursively. Thus if `A' imports `B', and `B' imports `C', the immediate - sources of `A' may depend on the immediate sources of `C', even if `A' - does not import `C' explicitly. However, this is not recommended, - because if and when `B' ceases to import `C', some sources in `A' will - no longer compile. - - A side effect of this capability is that cyclic dependences are not - permitted: if `A' imports `B' (directly or indirectly) then `B' is not - allowed to import `A'. - -  - File: gnat_ug_vxw.info, Node: Project Extension, Next: External References in Project Files, Prev: Importing Projects, Up: GNAT Project Manager - - Project Extension - ================= - - During development of a large system, it is sometimes necessary to use - modified versions of some of the source files without changing the - original sources. This can be achieved through a facility known as - _project extension_. - - project Modified_Utilities extends "/baseline/utilities.gpr" is ... - - The project file for the project being extended (the _parent_) is - identified by the literal string that follows the reserved word - `extends', which itself follows the name of the extending project (the - _child_). - - By default, a child project inherits all the sources of its parent. - However, inherited sources can be overridden: a unit with the same name - as one in the parent will hide the original unit. Inherited sources - are considered to be sources (but not immediate sources) of the child - project; see *Note Project File Syntax::. - - An inherited source file retains any switches specified in the - parent project. - - For example if the project `Utilities' contains the specification - and the body of an Ada package `Util_IO', then the project - `Modified_Utilities' can contain a new body for package `Util_IO'. The - original body of `Util_IO' will not be considered in program builds. - However, the package specification will still be found in the project - `Utilities'. - - A child project can have only one parent but it may import any - number of other projects. - - A project is not allowed to import directly or indirectly at the - same time a child project and any of its ancestors. - -  - File: gnat_ug_vxw.info, Node: External References in Project Files, Next: Packages in Project Files, Prev: Project Extension, Up: GNAT Project Manager - - External References in Project Files - ==================================== - - A project file may contain references to external variables; such - references are called _external references_. - - An external variable is either defined as part of the environment (an - environment variable in Unix, for example) or else specified on the - command line via the `-X_vbl_=_value_' switch. If both, then the - command line value is used. - - An external reference is denoted by the built-in function - `external', which returns a string value. This function has two forms: - * `external (external_variable_name)' - - * `external (external_variable_name, default_value)' - - Each parameter must be a string literal. For example: - - external ("USER") - external ("OS", "Linux") - - In the form with one parameter, the function returns the value of the - external variable given as parameter. If this name is not present in the - environment, then the returned value is an empty string. - - In the form with two string parameters, the second parameter is the - value returned when the variable given as the first parameter is not - present in the environment. In the example above, if `"OS"' is not the - name of an environment variable and is not passed on the command line, - then the returned value will be `"Linux"'. - - An external reference may be part of a string expression or of a - string list expression, to define variables or attributes. - - type Mode_Type is ("Debug", "Release"); - Mode : Mode_Type := external ("MODE"); - case Mode is - when "Debug" => - ... - -  - File: gnat_ug_vxw.info, Node: Packages in Project Files, Next: Variables from Imported Projects, Prev: External References in Project Files, Up: GNAT Project Manager - - Packages in Project Files - ========================= - - The _package_ is the project file feature that defines the settings for - project-aware tools. For each such tool you can declare a - corresponding package; the names for these packages are preset (see - *Note Packages::) but are not case sensitive. A package may contain - variable declarations, attribute declarations, and case constructions. - - project Proj is - package Builder is -- used by gnatmake - for Default_Switches ("Ada") use ("-v", "-g"); - end Builder; - end Proj; - - A package declaration starts with the reserved word `package', followed - by the package name (case insensitive), followed by the reserved word - `is'. It ends with the reserved word `end', followed by the package - name, finally followed by a semi-colon. - - Most of the packages have an attribute `Default_Switches'. This - attribute is an associative array, and its value is a string list. The - index of the associative array is the name of a programming language - (case insensitive). This attribute indicates the switch or switches to - be used with the corresponding tool. - - Some packages also have another attribute, `Switches', an associative - array whose value is a string list. The index is the name of a source - file. This attribute indicates the switch or switches to be used by - the corresponding tool when dealing with this specific file. - - Further information on these switch-related attributes is found in - *Note Switches and Project Files::. - - A package may be declared as a _renaming_ of another package; e.g., - from the project file for an imported project. - - with "/global/apex.gpr"; - project Example is - package Naming renames Apex.Naming; - ... - end Example; - - Packages that are renamed in other project files often come from - project files that have no sources: they are just used as templates. - Any modification in the template will be reflected automatically in all - the project files that rename a package from the template. - - In addition to the tool-oriented packages, you can also declare a - package named `Naming' to establish specialized source file naming - conventions (see *Note Naming Schemes::). - -  - File: gnat_ug_vxw.info, Node: Variables from Imported Projects, Next: Naming Schemes, Prev: Packages in Project Files, Up: GNAT Project Manager - - Variables from Imported Projects - ================================ - - An attribute or variable defined in an imported or parent project can - be used in expressions in the importing / extending project. Such an - attribute or variable is prefixed with the name of the project and (if - relevant) the name of package where it is defined. - - with "imported"; - project Main extends "base" is - Var1 := Imported.Var; - Var2 := Base.Var & ".new"; - - package Builder is - for Default_Switches ("Ada") use Imported.Builder.Ada_Switches & - "-gnatg" & "-v"; - end Builder; - - package Compiler is - for Default_Switches ("Ada") use Base.Compiler.Ada_Switches; - end Compiler; - end Main; - - In this example: - - * `Var1' is a copy of the variable `Var' defined in the project file - `"imported.gpr"' - - * the value of `Var2' is a copy of the value of variable `Var' - defined in the project file `base.gpr', concatenated with `".new"' - - * attribute `Default_Switches ("Ada")' in package `Builder' is a - string list that includes in its value a copy of variable - `Ada_Switches' defined in the `Builder' package in project file - `imported.gpr' plus two new elements: `"-gnatg"' and `"-v"'; - - * attribute `Default_Switches ("Ada")' in package `Compiler' is a - copy of the variable `Ada_Switches' defined in the `Compiler' - package in project file `base.gpr', the project being extended. - -  - File: gnat_ug_vxw.info, Node: Naming Schemes, Next: Library Projects, Prev: Variables from Imported Projects, Up: GNAT Project Manager - - Naming Schemes - ============== - - Sometimes an Ada software system is ported from a foreign compilation - environment to GNAT, with file names that do not use the default GNAT - conventions. Instead of changing all the file names (which for a - variety of reasons might not be possible), you can define the relevant - file naming scheme in the `Naming' package in your project file. For - example, the following package models the Apex file naming rules: - - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "."; - for Specification_Suffix ("Ada") use ".1.ada"; - for Implementation_Suffix ("Ada") use ".2.ada"; - end Naming; - - You can define the following attributes in package `Naming': - - `CASING' - This must be a string with one of the three values `"lowercase"', - `"uppercase"' or `"mixedcase"'; these strings are case insensitive. - - If CASING is not specified, then the default is `"lowercase"'. - - `DOT_REPLACEMENT' - This must be a string whose value satisfies the following - conditions: - - * It must not be empty - - * It cannot start or end with an alphanumeric character - - * It cannot be a single underscore - - * It cannot start with an underscore followed by an alphanumeric - - * It cannot contain a dot `'.'' except if it the entire string - is `"."' - - If `Dot_Replacement' is not specified, then the default is `"-"'. - - `SPECIFICATION_SUFFIX' - This is an associative array (indexed by the programming language - name, case insensitive) whose value is a string that must satisfy - the following conditions: - - * It must not be empty - - * It cannot start with an alphanumeric character - - * It cannot start with an underscore followed by an - alphanumeric character - - If `Specification_Suffix ("Ada")' is not specified, then the - default is `".ads"'. - - `IMPLEMENTATION_SUFFIX' - This is an associative array (indexed by the programming language - name, case insensitive) whose value is a string that must satisfy - the following conditions: - - * It must not be empty - - * It cannot start with an alphanumeric character - - * It cannot start with an underscore followed by an - alphanumeric character - - * It cannot be a suffix of `Specification_Suffix' - - If `Implementation_Suffix ("Ada")' is not specified, then the - default is `".adb"'. - - `SEPARATE_SUFFIX' - This must be a string whose value satisfies the same conditions as - `Implementation_Suffix'. - - If `Separate_Suffix ("Ada")' is not specified, then it defaults to - same value as `Implementation_Suffix ("Ada")'. - - `SPECIFICATION' - You can use the `Specification' attribute, an associative array, - to define the source file name for an individual Ada compilation - unit's spec. The array index must be a string literal that - identifies the Ada unit (case insensitive). The value of this - attribute must be a string that identifies the file that contains - this unit's spec (case sensitive or insensitive depending on the - operating system). - - for Specification ("MyPack.MyChild") use "mypack.mychild.spec"; - - `IMPLEMENTATION' - You can use the `Implementation' attribute, an associative array, - to define the source file name for an individual Ada compilation - unit's body (possibly a subunit). The array index must be a - string literal that identifies the Ada unit (case insensitive). - The value of this attribute must be a string that identifies the - file that contains this unit's body or subunit (case sensitive or - insensitive depending on the operating system). - - for Implementation ("MyPack.MyChild") use "mypack.mychild.body"; - -  - File: gnat_ug_vxw.info, Node: Library Projects, Next: Switches Related to Project Files, Prev: Naming Schemes, Up: GNAT Project Manager - - Library Projects - ================ - - _Library projects_ are projects whose object code is placed in a - library. (Note that this facility is not yet supported on all - platforms) - - To create a library project, you need to define in its project file - two project-level attributes: `Library_Name' and `Library_Dir'. - Additionally, you may define the library-related attributes - `Library_Kind', `Library_Version' and `Library_Elaboration'. - - The `Library_Name' attribute has a string value that must start with - a letter and include only letters and digits. - - The `Library_Dir' attribute has a string value that designates the - path (absolute or relative) of the directory where the library will - reside. It must designate an existing directory, and this directory - needs to be different from the project's object directory. It also - needs to be writable. - - If both `Library_Name' and `Library_Dir' are specified and are - legal, then the project file defines a library project. The optional - library-related attributes are checked only for such project files. - - The `Library_Kind' attribute has a string value that must be one of - the following (case insensitive): `"static"', `"dynamic"' or - `"relocatable"'. If this attribute is not specified, the library is a - static library. Otherwise, the library may be dynamic or relocatable. - Depending on the operating system, there may or may not be a distinction - between dynamic and relocatable libraries. For example, on Unix there - is no such distinction. - - The `Library_Version' attribute has a string value whose - interpretation is platform dependent. On Unix, it is used only for - dynamic/relocatable libraries as the internal name of the library (the - `"soname"'). If the library file name (built from the `Library_Name') - is different from the `Library_Version', then the library file will be - a symbolic link to the actual file whose name will be `Library_Version'. - - Example (on Unix): - - project Plib is - - Version := "1"; - - for Library_Dir use "lib_dir"; - for Library_Name use "dummy"; - for Library_Kind use "relocatable"; - for Library_Version use "libdummy.so." & Version; - - end Plib; - - Directory `lib_dir' will contain the internal library file whose name - will be `libdummy.so.1', and `libdummy.so' will be a symbolic link to - `libdummy.so.1'. - - When `gnatmake' detects that a project file (not the main project - file) is a library project file, it will check all immediate sources of - the project and rebuild the library if any of the sources have been - recompiled. All `ALI' files will also be copied from the object - directory to the library directory. To build executables, `gnatmake' - will use the library rather than the individual object files. - -  - File: gnat_ug_vxw.info, Node: Switches Related to Project Files, Next: Tools Supporting Project Files, Prev: Library Projects, Up: GNAT Project Manager - - Switches Related to Project Files - ================================= - - The following switches are used by GNAT tools that support project - files: - - ``-PPROJECT'' - Indicates the name of a project file. This project file will be - parsed with the verbosity indicated by `-vP_x_', if any, and using - the external references indicated by `-X' switches, if any. - - There must be only one `-P' switch on the command line. - - Since the Project Manager parses the project file only after all - the switches on the command line are checked, the order of the - switches `-P', `-Vp_x_' or `-X' is not significant. - - ``-XNAME=VALUE'' - Indicates that external variable NAME has the value VALUE. The - Project Manager will use this value for occurrences of - `external(name)' when parsing the project file. - - If NAME or VALUE includes a space, then NAME=VALUE should be put - between quotes. - -XOS=NT - -X"user=John Doe" - - Several `-X' switches can be used simultaneously. If several `-X' - switches specify the same NAME, only the last one is used. - - An external variable specified with a `-X' switch takes precedence - over the value of the same name in the environment. - - ``-vP_x_'' - Indicates the verbosity of the parsing of GNAT project files. - `-vP0' means Default (no output for syntactically correct project - files); `-vP1' means Medium; `-vP2' means High. - - The default is Default. - - If several `-vP_x_' switches are present, only the last one is - used. - -  - File: gnat_ug_vxw.info, Node: Tools Supporting Project Files, Next: An Extended Example, Prev: Switches Related to Project Files, Up: GNAT Project Manager - - Tools Supporting Project Files - ============================== - - * Menu: - - * gnatmake and Project Files:: - * The GNAT Driver and Project Files:: - * Glide and Project Files:: - -  - File: gnat_ug_vxw.info, Node: gnatmake and Project Files, Next: The GNAT Driver and Project Files, Up: Tools Supporting Project Files - - gnatmake and Project Files - -------------------------- - - This section covers two topics related to `gnatmake' and project files: - defining switches for `gnatmake' and for the tools that it invokes; and - the use of the `Main' attribute. - - * Menu: - - * Switches and Project Files:: - * Project Files and Main Subprograms:: - -  - File: gnat_ug_vxw.info, Node: Switches and Project Files, Next: Project Files and Main Subprograms, Up: gnatmake and Project Files - - Switches and Project Files - .......................... - - For each of the packages `Builder', `Compiler', `Binder', and `Linker', - you can specify a `Default_Switches' attribute, a `Switches' attribute, - or both; as their names imply, these switch-related attributes affect - which switches are used for which files when `gnatmake' is invoked. As - will be explained below, these package-contributed switches precede the - switches passed on the `gnatmake' command line. - - The `Default_Switches' attribute is an associative array indexed by - language name (case insensitive) and returning a string list. For - example: - - package Compiler is - for Default_Switches ("Ada") use ("-gnaty", "-v"); - end Compiler; - - The `Switches' attribute is also an associative array, indexed by a file - name (which may or may not be case sensitive, depending on the operating - system) and returning a string list. For example: - - package Builder is - for Switches ("main1.adb") use ("-O2"); - for Switches ("main2.adb") use ("-g"); - end Builder; - - For the `Builder' package, the file names should designate source files - for main subprograms. For the `Binder' and `Linker' packages, the file - names should designate `ALI' or source files for main subprograms. In - each case just the file name (without explicit extension) is acceptable. - - For each tool used in a program build (`gnatmake', the compiler, the - binder, and the linker), its corresponding package "contributes" a set - of switches for each file on which the tool is invoked, based on the - switch-related attributes defined in the package. In particular, the - switches that each of these packages contributes for a given file F - comprise: - - * the value of attribute `Switches (F)', if it is specified in the - package for the given file, - - * otherwise, the value of `Default_Switches ("Ada")', if it is - specified in the package. - - If neither of these attributes is defined in the package, then the - package does not contribute any switches for the given file. - - When `gnatmake' is invoked on a file, the switches comprise two sets, - in the following order: those contributed for the file by the `Builder' - package; and the switches passed on the command line. - - When `gnatmake' invokes a tool (compiler, binder, linker) on a file, - the switches passed to the tool comprise three sets, in the following - order: - - 1. the applicable switches contributed for the file by the `Builder' - package in the project file supplied on the command line; - - 2. those contributed for the file by the package (in the relevant - project file - see below) corresponding to the tool; and - - 3. the applicable switches passed on the command line. - - The term _applicable switches_ reflects the fact that `gnatmake' - switches may or may not be passed to individual tools, depending on the - individual switch. - - `gnatmake' may invoke the compiler on source files from different - projects. The Project Manager will use the appropriate project file to - determine the `Compiler' package for each source file being compiled. - Likewise for the `Binder' and `Linker' packages. - - As an example, consider the following package in a project file: - - project Proj1 is - package Compiler is - for Default_Switches ("Ada") use ("-g"); - for Switches ("a.adb") use ("-O1"); - for Switches ("b.adb") use ("-O2", "-gnaty"); - end Compiler; - end Proj1; - - If `gnatmake' is invoked with this project file, and it needs to - compile, say, the files `a.adb', `b.adb', and `c.adb', then `a.adb' - will be compiled with the switch `-O1', `b.adb' with switches `-O2' and - `-gnaty', and `c.adb' with `-g'. - - Another example illustrates the ordering of the switches contributed - by different packages: - - project Proj2 is - package Builder is - for Switches ("main.adb") use ("-g", "-O1", "-f"); - end Builder; - - package Compiler is - for Switches ("main.adb") use ("-O2"); - end Compiler; - end Proj2; - - If you issue the command: - - gnatmake -PProj2 -O0 main - - then the compiler will be invoked on `main.adb' with the following - sequence of switches - - -g -O1 -O2 -O0 - - with the last `-O' switch having precedence over the earlier ones; - several other switches (such as `-c') are added implicitly. - - The switches `-g' and `-O1' are contributed by package `Builder', - `-O2' is contributed by the package `Compiler' and `-O0' comes from the - command line. - - The `-g' switch will also be passed in the invocation of `gnatlink.' - - A final example illustrates switch contributions from packages in - different project files: - - project Proj3 is - for Source_Files use ("pack.ads", "pack.adb"); - package Compiler is - for Default_Switches ("Ada") use ("-gnata"); - end Compiler; - end Proj3; - - with "Proj3"; - project Proj4 is - for Source_Files use ("foo_main.adb", "bar_main.adb"); - package Builder is - for Switches ("foo_main.adb") use ("-s", "-g"); - end Builder; - end Proj4; - - -- Ada source file: - with Pack; - procedure Foo_Main is - ... - end Foo_Main; - - If the command is - gnatmake -PProj4 foo_main.adb -cargs -gnato - - then the switches passed to the compiler for `foo_main.adb' are `-g' - (contributed by the package `Proj4.Builder') and `-gnato' (passed on - the command line). When the imported package `Pack' is compiled, the - switches used are `-g' from `Proj4.Builder', `-gnata' (contributed from - package `Proj3.Compiler', and `-gnato' from the command line. - -  - File: gnat_ug_vxw.info, Node: Project Files and Main Subprograms, Prev: Switches and Project Files, Up: gnatmake and Project Files - - Project Files and Main Subprograms - .................................. - - When using a project file, you can invoke `gnatmake' with several main - subprograms, by specifying their source files on the command line. - Each of these needs to be an immediate source file of the project. - - gnatmake -Pprj main1 main2 main3 - - When using a project file, you can also invoke `gnatmake' without - explicitly specifying any main, and the effect depends on whether you - have defined the `Main' attribute. This attribute has a string list - value, where each element in the list is the name of a source file (the - file extension is optional) containing a main subprogram. - - If the `Main' attribute is defined in a project file as a non-empty - string list and the switch `-u' is not used on the command line, then - invoking `gnatmake' with this project file but without any main on the - command line is equivalent to invoking `gnatmake' with all the file - names in the `Main' attribute on the command line. - - Example: - project Prj is - for Main use ("main1", "main2", "main3"); - end Prj; - - With this project file, `"gnatmake -Pprj"' is equivalent to `"gnatmake - -Pprj main1 main2 main3"'. - - When the project attribute `Main' is not specified, or is specified - as an empty string list, or when the switch `-u' is used on the command - line, then invoking `gnatmake' with no main on the command line will - result in all immediate sources of the project file being checked, and - potentially recompiled. Depending on the presence of the switch `-u', - sources from other project files on which the immediate sources of the - main project file depend are also checked and potentially recompiled. - In other words, the `-u' switch is applied to all of the immediate - sources of themain project file. - -  - File: gnat_ug_vxw.info, Node: The GNAT Driver and Project Files, Next: Glide and Project Files, Prev: gnatmake and Project Files, Up: Tools Supporting Project Files - - The GNAT Driver and Project Files - --------------------------------- - - A number of GNAT tools, other than `gnatmake' are project-aware: - `gnatbind', `gnatfind', `gnatlink', `gnatls' and `gnatxref'. However, - none of these tools can be invoked directly with a project file switch - (`-P'). They need to be invoke through the `gnat' driver. - - The `gnat' driver is a front-end that accepts a number of commands - and call the corresponding tool. It has been designed initially for VMS - to convert VMS style qualifiers to Unix style switches, but it is now - available to all the GNAT supported platforms. - - On non VMS platforms, the `gnat' driver accepts the following - commands (case insensitive): - - * BIND to invoke `gnatbind' - - * CHOP to invoke `gnatchop' - - * COMP or COMPILE to invoke the compiler - - * ELIM to invoke `gnatelim' - - * FIND to invoke `gnatfind' - - * KR or KRUNCH to invoke `gnatkr' - - * LINK to invoke `gnatlink' - - * LS or LIST to invoke `gnatls' - - * MAKE to invoke `gnatmake' - - * NAME to invoke `gnatname' - - * PREP or PREPROCESS to invoke `gnatprep' - - * PSTA or STANDARD to invoke `gnatpsta' - - * STUB to invoke `gnatstub' - - * XREF to invoke `gnatxref' - - Note that the compiler is invoked using the command `gnatmake -f -u'. - - Following the command, you may put switches and arguments for the - invoked tool. - - gnat bind -C main.ali - gnat ls -a main - gnat chop foo.txt - - In addition, for command BIND, FIND, LS or LIST, LINK and XREF, the - project file related switches (`-P', `-X' and `-vPx') may be used in - addition to the switches of the invoking tool. - - For each of these command, there is possibly a package in the main - project that corresponds to the invoked tool. - - * package `Binder' for command BIND (invoking `gnatbind') - - * package `Finder' for command FIND (invoking `gnatfind') - - * package `Gnatls' for command LS or LIST (invoking `gnatls') - - * package `Linker' for command LINK (invoking `gnatlink') - - * package `Cross_Reference' for command XREF (invoking `gnatlink') - - - Package `Gnatls' has a unique attribute `Switches', a simple variable - with a string list value. It contains switches for the invocation of - `gnatls'. - - project Proj1 is - package gnatls is - for Switches use ("-a", "-v"); - end gnatls; - end Proj1; - - All other packages contains a switch `Default_Switches', an associative - array, indexed by the programming language (case insensitive) and - having a string list value. `Default_Switches ("Ada")' contains the - switches for the invocation of the tool corresponding to the package. - - project Proj is - - for Source_Dirs use ("./**"); - - package gnatls is - for Switches use ("-a", "-v"); - end gnatls; - - package Binder is - for Default_Switches ("Ada") use ("-C", "-e"); - end Binder; - - package Linker is - for Default_Switches ("Ada") use ("-C"); - end Linker; - - package Finder is - for Default_Switches ("Ada") use ("-a", "-f"); - end Finder; - - package Cross_Reference is - for Default_Switches ("Ada") use ("-a", "-f", "-d", "-u"); - end Cross_Reference; - end Proj; - - With the above project file, commands such as - - gnat ls -Pproj main - gnat xref -Pproj main - gnat bind -Pproj main.ali - - will set up the environment properly and invoke the tool with the - switches found in the package corresponding to the tool. - -  - File: gnat_ug_vxw.info, Node: Glide and Project Files, Prev: The GNAT Driver and Project Files, Up: Tools Supporting Project Files - - Glide and Project Files - ----------------------- - - Glide will automatically recognize the `.gpr' extension for project - files, and will convert them to its own internal format automatically. - However, it doesn't provide a syntax-oriented editor for modifying these - files. The project file will be loaded as text when you select the - menu item `Ada' => `Project' => `Edit'. You can edit this text and - save the `gpr' file; when you next select this project file in Glide it - will be automatically reloaded. - - Glide uses the `gnatlist' attribute in the `Ide' package, whose value - is something like `powerpc-wrs-vxworks-gnatls', to compute the - cross-prefix. From this information the correct location for the GNAT - runtime, and thus also the correct cross-references, can be determined. - -  - File: gnat_ug_vxw.info, Node: An Extended Example, Next: Project File Complete Syntax, Prev: Tools Supporting Project Files, Up: GNAT Project Manager - - An Extended Example - =================== - - Suppose that we have two programs, PROG1 and PROG2, with the sources in - the respective directories. We would like to build them with a single - `gnatmake' command, and we would like to place their object files into - `.build' subdirectories of the source directories. Furthermore, we would - like to have to have two separate subdirectories in `.build' - - `release' and `debug' - which will contain the object files compiled - with different set of compilation flags. - - In other words, we have the following structure: - - main - |- prog1 - | |- .build - | | debug - | | release - |- prog2 - |- .build - | debug - | release - - Here are the project files that we need to create in a directory `main' - to maintain this structure: - - 1. We create a `Common' project with a package `Compiler' that - specifies the compilation switches: - - File "common.gpr": - project Common is - - for Source_Dirs use (); -- No source files - - type Build_Type is ("release", "debug"); - Build : Build_Type := External ("BUILD", "debug"); - package Compiler is - case Build is - when "release" => - for Default_Switches ("Ada") use ("-O2"); - when "debug" => - for Default_Switches ("Ada") use ("-g"); - end case; - end Compiler; - - end Common; - - 2. We create separate projects for the two programs: - - File "prog1.gpr": - - with "common"; - project Prog1 is - - for Source_Dirs use ("prog1"); - for Object_Dir use "prog1/.build/" & Common.Build; - - package Compiler renames Common.Compiler; - - end Prog1; - - File "prog2.gpr": - - with "common"; - project Prog2 is - - for Source_Dirs use ("prog2"); - for Object_Dir use "prog2/.build/" & Common.Build; - - package Compiler renames Common.Compiler; - end Prog2; - - 3. We create a wrapping project MAIN: - - File "main.gpr": - - with "common"; - with "prog1"; - with "prog2"; - project Main is - - package Compiler renames Common.Compiler; - - end Main; - - 4. Finally we need to create a dummy procedure that `with's (either - explicitly or implicitly) all the sources of our two programs. - - - Now we can build the programs using the command - - gnatmake -Pmain dummy - - for the Debug mode, or - - gnatmake -Pmain -XBUILD=release - - for the Release mode. - -  - File: gnat_ug_vxw.info, Node: Project File Complete Syntax, Prev: An Extended Example, Up: GNAT Project Manager - - Project File Complete Syntax - ============================ - - project ::= - context_clause project_declaration - - context_clause ::= - {with_clause} - - with_clause ::= - with literal_string { , literal_string } ; - - project_declaration ::= - project simple_name [ extends literal_string ] is - {declarative_item} - end simple_name; - - declarative_item ::= - package_declaration | - typed_string_declaration | - other_declarative_item - - package_declaration ::= - package simple_name package_completion - - package_completion ::= - package_body | package_renaming - - package body ::= - is - {other_declarative_item} - end simple_name ; - - package_renaming ::== - renames simple_name.simple_name ; - - typed_string_declaration ::= - type _simple_name is - ( literal_string {, literal_string} ); - - other_declarative_item ::= - attribute_declaration | - typed_variable_declaration | - variable_declaration | - case_construction - - attribute_declaration ::= - for attribute use expression ; - - attribute ::= - simple_name | - simple_name ( literal_string ) - - typed_variable_declaration ::= - simple_name : name := string_expression ; - - variable_declaration ::= - simple_name := expression; - - expression ::= - term {& term} - - term ::= - literal_string | - string_list | - name | - external_value | - attribute_reference - - literal_string ::= - (same as Ada) - - string_list ::= - ( expression { , expression } ) - - external_value ::= - external ( literal_string [, literal_string] ) - - attribute_reference ::= - attribute_parent ' simple_name [ ( literal_string ) ] - - attribute_parent ::= - project | - simple_name | - simple_name . simple_name - - case_construction ::= - case name is - {case_item} - end case ; - - case_item ::= - when discrete_choice_list => {case_construction | attribute_declaration} - - discrete_choice_list ::= - literal_string {| literal_string} - - name ::= - simple_name {. simple_name} - - simple_name ::= - identifier (same as Ada) - -  - File: gnat_ug_vxw.info, Node: Elaboration Order Handling in GNAT, Next: The Cross-Referencing Tools gnatxref and gnatfind, Prev: GNAT Project Manager, Up: Top - - Elaboration Order Handling in GNAT - ********************************** - - * Menu: - - * Elaboration Code in Ada 95:: - * Checking the Elaboration Order in Ada 95:: - * Controlling the Elaboration Order in Ada 95:: - * Controlling Elaboration in GNAT - Internal Calls:: - * Controlling Elaboration in GNAT - External Calls:: - * Default Behavior in GNAT - Ensuring Safety:: - * Elaboration Issues for Library Tasks:: - * Mixing Elaboration Models:: - * What to Do If the Default Elaboration Behavior Fails:: - * Elaboration for Access-to-Subprogram Values:: - * Summary of Procedures for Elaboration Control:: - * Other Elaboration Order Considerations:: - - This chapter describes the handling of elaboration code in Ada 95 and - in GNAT, and discusses how the order of elaboration of program units can - be controlled in GNAT, either automatically or with explicit programming - features. - -  - File: gnat_ug_vxw.info, Node: Elaboration Code in Ada 95, Next: Checking the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Elaboration Code in Ada 95 - ========================== - - Ada 95 provides rather general mechanisms for executing code at - elaboration time, that is to say before the main program starts - executing. Such code arises in three contexts: - - Initializers for variables. - Variables declared at the library level, in package specs or - bodies, can require initialization that is performed at - elaboration time, as in: - Sqrt_Half : Float := Sqrt (0.5); - - Package initialization code - Code in a `BEGIN-END' section at the outer level of a package body - is executed as part of the package body elaboration code. - - Library level task allocators - Tasks that are declared using task allocators at the library level - start executing immediately and hence can execute at elaboration - time. - - Subprogram calls are possible in any of these contexts, which means that - any arbitrary part of the program may be executed as part of the - elaboration code. It is even possible to write a program which does all - its work at elaboration time, with a null main program, although - stylistically this would usually be considered an inappropriate way to - structure a program. - - An important concern arises in the context of elaboration code: we - have to be sure that it is executed in an appropriate order. What we - have is a series of elaboration code sections, potentially one section - for each unit in the program. It is important that these execute in the - correct order. Correctness here means that, taking the above example of - the declaration of `Sqrt_Half', if some other piece of elaboration code - references `Sqrt_Half', then it must run after the section of - elaboration code that contains the declaration of `Sqrt_Half'. - - There would never be any order of elaboration problem if we made a - rule that whenever you `with' a unit, you must elaborate both the spec - and body of that unit before elaborating the unit doing the `with''ing: - - with Unit_1; - package Unit_2 is ... - - would require that both the body and spec of `Unit_1' be elaborated - before the spec of `Unit_2'. However, a rule like that would be far too - restrictive. In particular, it would make it impossible to have routines - in separate packages that were mutually recursive. - - You might think that a clever enough compiler could look at the - actual elaboration code and determine an appropriate correct order of - elaboration, but in the general case, this is not possible. Consider - the following example. - - In the body of `Unit_1', we have a procedure `Func_1' that references - the variable `Sqrt_1', which is declared in the elaboration code of the - body of `Unit_1': - - Sqrt_1 : Float := Sqrt (0.1); - - The elaboration code of the body of `Unit_1' also contains: - - if expression_1 = 1 then - Q := Unit_2.Func_2; - end if; - - `Unit_2' is exactly parallel, it has a procedure `Func_2' that - references the variable `Sqrt_2', which is declared in the elaboration - code of the body `Unit_2': - - Sqrt_2 : Float := Sqrt (0.1); - - The elaboration code of the body of `Unit_2' also contains: - - if expression_2 = 2 then - Q := Unit_1.Func_1; - end if; - - Now the question is, which of the following orders of elaboration is - acceptable: - - Spec of Unit_1 - Spec of Unit_2 - Body of Unit_1 - Body of Unit_2 - - or - - Spec of Unit_2 - Spec of Unit_1 - Body of Unit_2 - Body of Unit_1 - - If you carefully analyze the flow here, you will see that you cannot - tell at compile time the answer to this question. If `expression_1' is - not equal to 1, and `expression_2' is not equal to 2, then either order - is acceptable, because neither of the function calls is executed. If - both tests evaluate to true, then neither order is acceptable and in - fact there is no correct order. - - If one of the two expressions is true, and the other is false, then - one of the above orders is correct, and the other is incorrect. For - example, if `expression_1' = 1 and `expression_2' /= 2, then the call - to `Func_2' will occur, but not the call to `Func_1.' This means that - it is essential to elaborate the body of `Unit_1' before the body of - `Unit_2', so the first order of elaboration is correct and the second - is wrong. - - By making `expression_1' and `expression_2' depend on input data, or - perhaps the time of day, we can make it impossible for the compiler or - binder to figure out which of these expressions will be true, and hence - it is impossible to guarantee a safe order of elaboration at run time. - -  - File: gnat_ug_vxw.info, Node: Checking the Elaboration Order in Ada 95, Next: Controlling the Elaboration Order in Ada 95, Prev: Elaboration Code in Ada 95, Up: Elaboration Order Handling in GNAT - - Checking the Elaboration Order in Ada 95 - ======================================== - - In some languages that involve the same kind of elaboration problems, - e.g. Java and C++, the programmer is expected to worry about these - ordering problems himself, and it is common to write a program in which - an incorrect elaboration order gives surprising results, because it - references variables before they are initialized. Ada 95 is designed - to be a safe language, and a programmer-beware approach is clearly not - sufficient. Consequently, the language provides three lines of defense: - - Standard rules - Some standard rules restrict the possible choice of elaboration - order. In particular, if you `with' a unit, then its spec is always - elaborated before the unit doing the `with'. Similarly, a parent - spec is always elaborated before the child spec, and finally a - spec is always elaborated before its corresponding body. - - Dynamic elaboration checks - Dynamic checks are made at run time, so that if some entity is - accessed before it is elaborated (typically by means of a - subprogram call) then the exception (`Program_Error') is raised. - - Elaboration control - Facilities are provided for the programmer to specify the desired - order of elaboration. - - Let's look at these facilities in more detail. First, the rules for - dynamic checking. One possible rule would be simply to say that the - exception is raised if you access a variable which has not yet been - elaborated. The trouble with this approach is that it could require - expensive checks on every variable reference. Instead Ada 95 has two - rules which are a little more restrictive, but easier to check, and - easier to state: - - Restrictions on calls - A subprogram can only be called at elaboration time if its body - has been elaborated. The rules for elaboration given above - guarantee that the spec of the subprogram has been elaborated - before the call, but not the body. If this rule is violated, then - the exception `Program_Error' is raised. - - Restrictions on instantiations - A generic unit can only be instantiated if the body of the generic - unit has been elaborated. Again, the rules for elaboration given - above guarantee that the spec of the generic unit has been - elaborated before the instantiation, but not the body. If this - rule is violated, then the exception `Program_Error' is raised. - - The idea is that if the body has been elaborated, then any variables it - references must have been elaborated; by checking for the body being - elaborated we guarantee that none of its references causes any trouble. - As we noted above, this is a little too restrictive, because a - subprogram that has no non-local references in its body may in fact be - safe to call. However, it really would be unsafe to rely on this, - because it would mean that the caller was aware of details of the - implementation in the body. This goes against the basic tenets of Ada. - - A plausible implementation can be described as follows. A Boolean - variable is associated with each subprogram and each generic unit. This - variable is initialized to False, and is set to True at the point body - is elaborated. Every call or instantiation checks the variable, and - raises `Program_Error' if the variable is False. - - Note that one might think that it would be good enough to have one - Boolean variable for each package, but that would not deal with cases - of trying to call a body in the same package as the call that has not - been elaborated yet. Of course a compiler may be able to do enough - analysis to optimize away some of the Boolean variables as unnecessary, - and `GNAT' indeed does such optimizations, but still the easiest - conceptual model is to think of there being one variable per subprogram. - -  - File: gnat_ug_vxw.info, Node: Controlling the Elaboration Order in Ada 95, Next: Controlling Elaboration in GNAT - Internal Calls, Prev: Checking the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Controlling the Elaboration Order in Ada 95 - =========================================== - - In the previous section we discussed the rules in Ada 95 which ensure - that `Program_Error' is raised if an incorrect elaboration order is - chosen. This prevents erroneous executions, but we need mechanisms to - specify a correct execution and avoid the exception altogether. To - achieve this, Ada 95 provides a number of features for controlling the - order of elaboration. We discuss these features in this section. - - First, there are several ways of indicating to the compiler that a - given unit has no elaboration problems: - - packages that do not require a body - In Ada 95, a library package that does not require a body does not - permit a body. This means that if we have a such a package, as in: - - package Definitions is - generic - type m is new integer; - package Subp is - type a is array (1 .. 10) of m; - type b is array (1 .. 20) of m; - end Subp; - end Definitions; - - A package that `with''s `Definitions' may safely instantiate - `Definitions.Subp' because the compiler can determine that there - definitely is no package body to worry about in this case - - pragma Pure - Places sufficient restrictions on a unit to guarantee that no call - to any subprogram in the unit can result in an elaboration - problem. This means that the compiler does not need to worry about - the point of elaboration of such units, and in particular, does - not need to check any calls to any subprograms in this unit. - - pragma Preelaborate - This pragma places slightly less stringent restrictions on a unit - than does pragma Pure, but these restrictions are still sufficient - to ensure that there are no elaboration problems with any calls to - the unit. - - pragma Elaborate_Body - This pragma requires that the body of a unit be elaborated - immediately after its spec. Suppose a unit `A' has such a pragma, - and unit `B' does a `with' of unit `A'. Recall that the standard - rules require the spec of unit `A' to be elaborated before the - `with''ing unit; given the pragma in `A', we also know that the - body of `A' will be elaborated before `B', so that calls to `A' - are safe and do not need a check. - - Note that, unlike pragma `Pure' and pragma `Preelaborate', the use of - `Elaborate_Body' does not guarantee that the program is free of - elaboration problems, because it may not be possible to satisfy the - requested elaboration order. Let's go back to the example with - `Unit_1' and `Unit_2'. If a programmer marks `Unit_1' as - `Elaborate_Body', and not `Unit_2,' then the order of elaboration will - be: - - Spec of Unit_2 - Spec of Unit_1 - Body of Unit_1 - Body of Unit_2 - - Now that means that the call to `Func_1' in `Unit_2' need not be - checked, it must be safe. But the call to `Func_2' in `Unit_1' may - still fail if `Expression_1' is equal to 1, and the programmer must - still take responsibility for this not being the case. - - If all units carry a pragma `Elaborate_Body', then all problems are - eliminated, except for calls entirely within a body, which are in any - case fully under programmer control. However, using the pragma - everywhere is not always possible. In particular, for our - `Unit_1'/`Unit_2' example, if we marked both of them as having pragma - `Elaborate_Body', then clearly there would be no possible elaboration - order. - - The above pragmas allow a server to guarantee safe use by clients, - and clearly this is the preferable approach. Consequently a good rule in - Ada 95 is to mark units as `Pure' or `Preelaborate' if possible, and if - this is not possible, mark them as `Elaborate_Body' if possible. As we - have seen, there are situations where neither of these three pragmas - can be used. So we also provide methods for clients to control the - order of elaboration of the servers on which they depend: - - pragma Elaborate (unit) - This pragma is placed in the context clause, after a `with' clause, - and it requires that the body of the named unit be elaborated - before the unit in which the pragma occurs. The idea is to use - this pragma if the current unit calls at elaboration time, - directly or indirectly, some subprogram in the named unit. - - pragma Elaborate_All (unit) - This is a stronger version of the Elaborate pragma. Consider the - following example: - - Unit A `with''s unit B and calls B.Func in elab code - Unit B `with''s unit C, and B.Func calls C.Func - - Now if we put a pragma `Elaborate (B)' in unit `A', this ensures - that the body of `B' is elaborated before the call, but not the - body of `C', so the call to `C.Func' could still cause - `Program_Error' to be raised. - - The effect of a pragma `Elaborate_All' is stronger, it requires - not only that the body of the named unit be elaborated before the - unit doing the `with', but also the bodies of all units that the - named unit uses, following `with' links transitively. For example, - if we put a pragma `Elaborate_All (B)' in unit `A', then it - requires not only that the body of `B' be elaborated before `A', - but also the body of `C', because `B' `with''s `C'. - - We are now in a position to give a usage rule in Ada 95 for avoiding - elaboration problems, at least if dynamic dispatching and access to - subprogram values are not used. We will handle these cases separately - later. - - The rule is simple. If a unit has elaboration code that can directly - or indirectly make a call to a subprogram in a `with''ed unit, or - instantiate a generic unit in a `with''ed unit, then if the `with''ed - unit does not have pragma `Pure' or `Preelaborate', then the client - should have a pragma `Elaborate_All' for the `with''ed unit. By - following this rule a client is assured that calls can be made without - risk of an exception. If this rule is not followed, then a program may - be in one of four states: - - No order exists - No order of elaboration exists which follows the rules, taking into - account any `Elaborate', `Elaborate_All', or `Elaborate_Body' - pragmas. In this case, an Ada 95 compiler must diagnose the - situation at bind time, and refuse to build an executable program. - - One or more orders exist, all incorrect - One or more acceptable elaboration orders exists, and all of them - generate an elaboration order problem. In this case, the binder - can build an executable program, but `Program_Error' will be raised - when the program is run. - - Several orders exist, some right, some incorrect - One or more acceptable elaboration orders exists, and some of them - work, and some do not. The programmer has not controlled the order - of elaboration, so the binder may or may not pick one of the - correct orders, and the program may or may not raise an exception - when it is run. This is the worst case, because it means that the - program may fail when moved to another compiler, or even another - version of the same compiler. - - One or more orders exists, all correct - One ore more acceptable elaboration orders exist, and all of them - work. In this case the program runs successfully. This state of - affairs can be guaranteed by following the rule we gave above, but - may be true even if the rule is not followed. - - Note that one additional advantage of following our Elaborate_All rule - is that the program continues to stay in the ideal (all orders OK) state - even if maintenance changes some bodies of some subprograms. - Conversely, if a program that does not follow this rule happens to be - safe at some point, this state of affairs may deteriorate silently as a - result of maintenance changes. - - You may have noticed that the above discussion did not mention the - use of `Elaborate_Body'. This was a deliberate omission. If you `with' - an `Elaborate_Body' unit, it still may be the case that code in the - body makes calls to some other unit, so it is still necessary to use - `Elaborate_All' on such units. - -  - File: gnat_ug_vxw.info, Node: Controlling Elaboration in GNAT - Internal Calls, Next: Controlling Elaboration in GNAT - External Calls, Prev: Controlling the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Controlling Elaboration in GNAT - Internal Calls - ================================================ - - In the case of internal calls, i.e. calls within a single package, the - programmer has full control over the order of elaboration, and it is up - to the programmer to elaborate declarations in an appropriate order. For - example writing: - - function One return Float; - - Q : Float := One; - - function One return Float is - begin - return 1.0; - end One; - - will obviously raise `Program_Error' at run time, because function One - will be called before its body is elaborated. In this case GNAT will - generate a warning that the call will raise `Program_Error': - - 1. procedure y is - 2. function One return Float; - 3. - 4. Q : Float := One; - | - >>> warning: cannot call "One" before body is elaborated - >>> warning: Program_Error will be raised at run time - - 5. - 6. function One return Float is - 7. begin - 8. return 1.0; - 9. end One; - 10. - 11. begin - 12. null; - 13. end; - - Note that in this particular case, it is likely that the call is safe, - because the function `One' does not access any global variables. - Nevertheless in Ada 95, we do not want the validity of the check to - depend on the contents of the body (think about the separate - compilation case), so this is still wrong, as we discussed in the - previous sections. - - The error is easily corrected by rearranging the declarations so - that the body of One appears before the declaration containing the call - (note that in Ada 95, declarations can appear in any order, so there is - no restriction that would prevent this reordering, and if we write: - - function One return Float; - - function One return Float is - begin - return 1.0; - end One; - - Q : Float := One; - - then all is well, no warning is generated, and no `Program_Error' - exception will be raised. Things are more complicated when a chain of - subprograms is executed: - - function A return Integer; - function B return Integer; - function C return Integer; - - function B return Integer is begin return A; end; - function C return Integer is begin return B; end; - - X : Integer := C; - - function A return Integer is begin return 1; end; - - Now the call to `C' at elaboration time in the declaration of `X' is - correct, because the body of `C' is already elaborated, and the call to - `B' within the body of `C' is correct, but the call to `A' within the - body of `B' is incorrect, because the body of `A' has not been - elaborated, so `Program_Error' will be raised on the call to `A'. In - this case GNAT will generate a warning that `Program_Error' may be - raised at the point of the call. Let's look at the warning: - - 1. procedure x is - 2. function A return Integer; - 3. function B return Integer; - 4. function C return Integer; - 5. - 6. function B return Integer is begin return A; end; - | - >>> warning: call to "A" before body is elaborated may - raise Program_Error - >>> warning: "B" called at line 7 - >>> warning: "C" called at line 9 - - 7. function C return Integer is begin return B; end; - 8. - 9. X : Integer := C; - 10. - 11. function A return Integer is begin return 1; end; - 12. - 13. begin - 14. null; - 15. end; - - Note that the message here says "may raise", instead of the direct case, - where the message says "will be raised". That's because whether `A' is - actually called depends in general on run-time flow of control. For - example, if the body of `B' said - - function B return Integer is - begin - if some-condition-depending-on-input-data then - return A; - else - return 1; - end if; - end B; - - then we could not know until run time whether the incorrect call to A - would actually occur, so `Program_Error' might or might not be raised. - It is possible for a compiler to do a better job of analyzing bodies, to - determine whether or not `Program_Error' might be raised, but it - certainly couldn't do a perfect job (that would require solving the - halting problem and is provably impossible), and because this is a - warning anyway, it does not seem worth the effort to do the analysis. - Cases in which it would be relevant are rare. - - In practice, warnings of either of the forms given above will - usually correspond to real errors, and should be examined carefully and - eliminated. In the rare case where a warning is bogus, it can be - suppressed by any of the following methods: - - * Compile with the `-gnatws' switch set - - * Suppress `Elaboration_Checks' for the called subprogram - - * Use pragma `Warnings_Off' to turn warnings off for the call - - For the internal elaboration check case, GNAT by default generates the - necessary run-time checks to ensure that `Program_Error' is raised if - any call fails an elaboration check. Of course this can only happen if a - warning has been issued as described above. The use of pragma `Suppress - (Elaboration_Checks)' may (but is not guaranteed to) suppress some of - these checks, meaning that it may be possible (but is not guaranteed) - for a program to be able to call a subprogram whose body is not yet - elaborated, without raising a `Program_Error' exception. - -  - File: gnat_ug_vxw.info, Node: Controlling Elaboration in GNAT - External Calls, Next: Default Behavior in GNAT - Ensuring Safety, Prev: Controlling Elaboration in GNAT - Internal Calls, Up: Elaboration Order Handling in GNAT - - Controlling Elaboration in GNAT - External Calls - ================================================ - - The previous section discussed the case in which the execution of a - particular thread of elaboration code occurred entirely within a single - unit. This is the easy case to handle, because a programmer has direct - and total control over the order of elaboration, and furthermore, - checks need only be generated in cases which are rare and which the - compiler can easily detect. The situation is more complex when - separate compilation is taken into account. Consider the following: - - package Math is - function Sqrt (Arg : Float) return Float; - end Math; - - package body Math is - function Sqrt (Arg : Float) return Float is - begin - ... - end Sqrt; - end Math; - - with Math; - package Stuff is - X : Float := Math.Sqrt (0.5); - end Stuff; - - with Stuff; - procedure Main is - begin - ... - end Main; - - where `Main' is the main program. When this program is executed, the - elaboration code must first be executed, and one of the jobs of the - binder is to determine the order in which the units of a program are to - be elaborated. In this case we have four units: the spec and body of - `Math', the spec of `Stuff' and the body of `Main'). In what order - should the four separate sections of elaboration code be executed? - - There are some restrictions in the order of elaboration that the - binder can choose. In particular, if unit U has a `with' for a package - `X', then you are assured that the spec of `X' is elaborated before U , - but you are not assured that the body of `X' is elaborated before U. - This means that in the above case, the binder is allowed to choose the - order: - - spec of Math - spec of Stuff - body of Math - body of Main - - but that's not good, because now the call to `Math.Sqrt' that happens - during the elaboration of the `Stuff' spec happens before the body of - `Math.Sqrt' is elaborated, and hence causes `Program_Error' exception - to be raised. At first glance, one might say that the binder is - misbehaving, because obviously you want to elaborate the body of - something you `with' first, but that is not a general rule that can be - followed in all cases. Consider - - package X is ... - - package Y is ... - - with X; - package body Y is ... - - with Y; - package body X is ... - - This is a common arrangement, and, apart from the order of elaboration - problems that might arise in connection with elaboration code, this - works fine. A rule that says that you must first elaborate the body of - anything you `with' cannot work in this case: the body of `X' `with''s - `Y', which means you would have to elaborate the body of `Y' first, but - that `with''s `X', which means you have to elaborate the body of `X' - first, but ... and we have a loop that cannot be broken. - - It is true that the binder can in many cases guess an order of - elaboration that is unlikely to cause a `Program_Error' exception to be - raised, and it tries to do so (in the above example of - `Math/Stuff/Spec', the GNAT binder will by default elaborate the body - of `Math' right after its spec, so all will be well). - - However, a program that blindly relies on the binder to be helpful - can get into trouble, as we discussed in the previous sections, so GNAT - provides a number of facilities for assisting the programmer in - developing programs that are robust with respect to elaboration order. - -  - File: gnat_ug_vxw.info, Node: Default Behavior in GNAT - Ensuring Safety, Next: Elaboration Issues for Library Tasks, Prev: Controlling Elaboration in GNAT - External Calls, Up: Elaboration Order Handling in GNAT - - Default Behavior in GNAT - Ensuring Safety - ========================================== - - The default behavior in GNAT ensures elaboration safety. In its default - mode GNAT implements the rule we previously described as the right - approach. Let's restate it: - - * _If a unit has elaboration code that can directly or indirectly - make a call to a subprogram in a `with''ed unit, or instantiate a - generic unit in a `with''ed unit, then if the `with''ed unit does - not have pragma `Pure' or `Preelaborate', then the client should - have an `Elaborate_All' for the `with''ed unit._ - - By following this rule a client is assured that calls and - instantiations can be made without risk of an exception. - - In this mode GNAT traces all calls that are potentially made from - elaboration code, and puts in any missing implicit `Elaborate_All' - pragmas. The advantage of this approach is that no elaboration problems - are possible if the binder can find an elaboration order that is - consistent with these implicit `Elaborate_All' pragmas. The - disadvantage of this approach is that no such order may exist. - - If the binder does not generate any diagnostics, then it means that - it has found an elaboration order that is guaranteed to be safe. - However, the binder may still be relying on implicitly generated - `Elaborate_All' pragmas so portability to other compilers than GNAT is - not guaranteed. - - If it is important to guarantee portability, then the compilations - should use the `-gnatwl' (warn on elaboration problems) switch. This - will cause warning messages to be generated indicating the missing - `Elaborate_All' pragmas. Consider the following source program: - - with k; - package j is - m : integer := k.r; - end; - - where it is clear that there should be a pragma `Elaborate_All' for - unit `k'. An implicit pragma will be generated, and it is likely that - the binder will be able to honor it. However, it is safer to include - the pragma explicitly in the source. If this unit is compiled with the - `-gnatwl' switch, then the compiler outputs a warning: - - 1. with k; - 2. package j is - 3. m : integer := k.r; - | - >>> warning: call to "r" may raise Program_Error - >>> warning: missing pragma Elaborate_All for "k" - - 4. end; - - and these warnings can be used as a guide for supplying manually the - missing pragmas. - - This default mode is more restrictive than the Ada Reference Manual, - and it is possible to construct programs which will compile using the - dynamic model described there, but will run into a circularity using - the safer static model we have described. - - Of course any Ada compiler must be able to operate in a mode - consistent with the requirements of the Ada Reference Manual, and in - particular must have the capability of implementing the standard - dynamic model of elaboration with run-time checks. - - In GNAT, this standard mode can be achieved either by the use of the - `-gnatE' switch on the compiler (`gcc' or `gnatmake') command, or by - the use of the configuration pragma: - - pragma Elaboration_Checks (RM); - - Either approach will cause the unit affected to be compiled using the - standard dynamic run-time elaboration checks described in the Ada - Reference Manual. The static model is generally preferable, since it is - clearly safer to rely on compile and link time checks rather than - run-time checks. However, in the case of legacy code, it may be - difficult to meet the requirements of the static model. This issue is - further discussed in *Note What to Do If the Default Elaboration - Behavior Fails::. - - Note that the static model provides a strict subset of the allowed - behavior and programs of the Ada Reference Manual, so if you do adhere - to the static model and no circularities exist, then you are assured - that your program will work using the dynamic model. - -  - File: gnat_ug_vxw.info, Node: Elaboration Issues for Library Tasks, Next: Mixing Elaboration Models, Prev: Default Behavior in GNAT - Ensuring Safety, Up: Elaboration Order Handling in GNAT - - Elaboration Issues for Library Tasks - ==================================== - - In this section we examine special elaboration issues that arise for - programs that declare library level tasks. - - Generally the model of execution of an Ada program is that all units - are elaborated, and then execution of the program starts. However, the - declaration of library tasks definitely does not fit this model. The - reason for this is that library tasks start as soon as they are declared - (more precisely, as soon as the statement part of the enclosing package - body is reached), that is to say before elaboration of the program is - complete. This means that if such a task calls a subprogram, or an - entry in another task, the callee may or may not be elaborated yet, and - in the standard Reference Manual model of dynamic elaboration checks, - you can even get timing dependent Program_Error exceptions, since there - can be a race between the elaboration code and the task code. - - The static model of elaboration in GNAT seeks to avoid all such - dynamic behavior, by being conservative, and the conservative approach - in this particular case is to assume that all the code in a task body - is potentially executed at elaboration time if a task is declared at - the library level. - - This can definitely result in unexpected circularities. Consider the - following example - - package Decls is - task Lib_Task is - entry Start; - end Lib_Task; - - type My_Int is new Integer; - - function Ident (M : My_Int) return My_Int; - end Decls; - - with Utils; - package body Decls is - task body Lib_Task is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task; - - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls; - - with Decls; - package Utils is - procedure Put_Val (Arg : Decls.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls.My_Int) is - begin - Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls; - procedure Main is - begin - Decls.Lib_Task.Start; - end; - - If the above example is compiled in the default static elaboration - mode, then a circularity occurs. The circularity comes from the call - `Utils.Put_Val' in the task body of `Decls.Lib_Task'. Since this call - occurs in elaboration code, we need an implicit pragma `Elaborate_All' - for `Utils'. This means that not only must the spec and body of `Utils' - be elaborated before the body of `Decls', but also the spec and body of - any unit that is `with'ed' by the body of `Utils' must also be - elaborated before the body of `Decls'. This is the transitive - implication of pragma `Elaborate_All' and it makes sense, because in - general the body of `Put_Val' might have a call to something in a - `with'ed' unit. - - In this case, the body of Utils (actually its spec) `with's' - `Decls'. Unfortunately this means that the body of `Decls' must be - elaborated before itself, in case there is a call from the body of - `Utils'. - - Here is the exact chain of events we are worrying about: - - 1. In the body of `Decls' a call is made from within the body of a - library task to a subprogram in the package `Utils'. Since this - call may occur at elaboration time (given that the task is - activated at elaboration time), we have to assume the worst, i.e. - that the call does happen at elaboration time. - - 2. This means that the body and spec of `Util' must be elaborated - before the body of `Decls' so that this call does not cause an - access before elaboration. - - 3. Within the body of `Util', specifically within the body of - `Util.Put_Val' there may be calls to any unit `with''ed by this - package. - - 4. One such `with''ed package is package `Decls', so there might be a - call to a subprogram in `Decls' in `Put_Val'. In fact there is - such a call in this example, but we would have to assume that - there was such a call even if it were not there, since we are not - supposed to write the body of `Decls' knowing what is in the body - of `Utils'; certainly in the case of the static elaboration model, - the compiler does not know what is in other bodies and must assume - the worst. - - 5. This means that the spec and body of `Decls' must also be - elaborated before we elaborate the unit containing the call, but - that unit is `Decls'! This means that the body of `Decls' must be - elaborated before itself, and that's a circularity. - - Indeed, if you add an explicit pragma Elaborate_All for `Utils' in the - body of `Decls' you will get a true Ada Reference Manual circularity - that makes the program illegal. - - In practice, we have found that problems with the static model of - elaboration in existing code often arise from library tasks, so we must - address this particular situation. - - Note that if we compile and run the program above, using the dynamic - model of elaboration (that is to say use the `-gnatE' switch), then it - compiles, binds, links, and runs, printing the expected result of 2. - Therefore in some sense the circularity here is only apparent, and we - need to capture the properties of this program that distinguish it - from other library-level tasks that have real elaboration problems. - - We have four possible answers to this question: - - * Use the dynamic model of elaboration. - - If we use the `-gnatE' switch, then as noted above, the program - works. Why is this? If we examine the task body, it is apparent - that the task cannot proceed past the `accept' statement until - after elaboration has been completed, because the corresponding - entry call comes from the main program, not earlier. This is why - the dynamic model works here. But that's really giving up on a - precise analysis, and we prefer to take this approach only if we - cannot solve the problem in any other manner. So let us examine - two ways to reorganize the program to avoid the potential - elaboration problem. - - * Split library tasks into separate packages. - - Write separate packages, so that library tasks are isolated from - other declarations as much as possible. Let us look at a variation - on the above program. - - package Decls1 is - task Lib_Task is - entry Start; - end Lib_Task; - end Decls1; - - with Utils; - package body Decls1 is - task body Lib_Task is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task; - end Decls1; - - package Decls2 is - type My_Int is new Integer; - function Ident (M : My_Int) return My_Int; - end Decls2; - - with Utils; - package body Decls2 is - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls2; - - with Decls2; - package Utils is - procedure Put_Val (Arg : Decls2.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls2.My_Int) is - begin - Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls1; - procedure Main is - begin - Decls1.Lib_Task.Start; - end; - - All we have done is to split `Decls' into two packages, one - containing the library task, and one containing everything else. - Now there is no cycle, and the program compiles, binds, links and - executes using the default static model of elaboration. - - * Declare separate task types. - - A significant part of the problem arises because of the use of the - single task declaration form. This means that the elaboration of - the task type, and the elaboration of the task itself (i.e. the - creation of the task) happen at the same time. A good rule of - style in Ada 95 is to always create explicit task types. By - following the additional step of placing task objects in separate - packages from the task type declaration, many elaboration problems - are avoided. Here is another modified example of the example - program: - - package Decls is - task type Lib_Task_Type is - entry Start; - end Lib_Task_Type; - - type My_Int is new Integer; - - function Ident (M : My_Int) return My_Int; - end Decls; - - with Utils; - package body Decls is - task body Lib_Task_Type is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task_Type; - - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls; - - with Decls; - package Utils is - procedure Put_Val (Arg : Decls.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls.My_Int) is - begin - Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls; - package Declst is - Lib_Task : Decls.Lib_Task_Type; - end Declst; - - with Declst; - procedure Main is - begin - Declst.Lib_Task.Start; - end; - - What we have done here is to replace the `task' declaration in - package `Decls' with a `task type' declaration. Then we introduce - a separate package `Declst' to contain the actual task object. - This separates the elaboration issues for the `task type' - declaration, which causes no trouble, from the elaboration issues - of the task object, which is also unproblematic, since it is now - independent of the elaboration of `Utils'. This separation of - concerns also corresponds to a generally sound engineering - principle of separating declarations from instances. This version - of the program also compiles, binds, links, and executes, - generating the expected output. - - * Use No_Entry_Calls_In_Elaboration_Code restriction. - - The previous two approaches described how a program can be - restructured to avoid the special problems caused by library task - bodies. in practice, however, such restructuring may be difficult - to apply to existing legacy code, so we must consider solutions - that do not require massive rewriting. - - Let us consider more carefully why our original sample program - works under the dynamic model of elaboration. The reason is that - the code in the task body blocks immediately on the `accept' - statement. Now of course there is nothing to prohibit elaboration - code from making entry calls (for example from another library - level task), so we cannot tell in isolation that the task will not - execute the accept statement during elaboration. - - However, in practice it is very unusual to see elaboration code - make any entry calls, and the pattern of tasks starting at - elaboration time and then immediately blocking on `accept' or - `select' statements is very common. What this means is that the - compiler is being too pessimistic when it analyzes the whole - package body as though it might be executed at elaboration time. - - If we know that the elaboration code contains no entry calls, (a - very safe assumption most of the time, that could almost be made - the default behavior), then we can compile all units of the - program under control of the following configuration pragma: - - pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); - - This pragma can be placed in the `gnat.adc' file in the usual - manner. If we take our original unmodified program and compile it - in the presence of a `gnat.adc' containing the above pragma, then - once again, we can compile, bind, link, and execute, obtaining the - expected result. In the presence of this pragma, the compiler does - not trace calls in a task body, that appear after the first - `accept' or `select' statement, and therefore does not report a - potential circularity in the original program. - - The compiler will check to the extent it can that the above - restriction is not violated, but it is not always possible to do a - complete check at compile time, so it is important to use this - pragma only if the stated restriction is in fact met, that is to - say no task receives an entry call before elaboration of all units - is completed. - - -  - File: gnat_ug_vxw.info, Node: Mixing Elaboration Models, Next: What to Do If the Default Elaboration Behavior Fails, Prev: Elaboration Issues for Library Tasks, Up: Elaboration Order Handling in GNAT - - Mixing Elaboration Models - ========================= - - So far, we have assumed that the entire program is either compiled - using the dynamic model or static model, ensuring consistency. It is - possible to mix the two models, but rules have to be followed if this - mixing is done to ensure that elaboration checks are not omitted. - - The basic rule is that _a unit compiled with the static model cannot - be `with'ed' by a unit compiled with the dynamic model_. The reason for - this is that in the static model, a unit assumes that its clients - guarantee to use (the equivalent of) pragma `Elaborate_All' so that no - elaboration checks are required in inner subprograms, and this - assumption is violated if the client is compiled with dynamic checks. - - The precise rule is as follows. A unit that is compiled with dynamic - checks can only `with' a unit that meets at least one of the following - criteria: - - * The `with'ed' unit is itself compiled with dynamic elaboration - checks (that is with the `-gnatE' switch. - - * The `with'ed' unit is an internal GNAT implementation unit from - the System, Interfaces, Ada, or GNAT hierarchies. - - * The `with'ed' unit has pragma Preelaborate or pragma Pure. - - * The `with'ing' unit (that is the client) has an explicit pragma - `Elaborate_All' for the `with'ed' unit. - - - If this rule is violated, that is if a unit with dynamic elaboration - checks `with's' a unit that does not meet one of the above four - criteria, then the binder (`gnatbind') will issue a warning similar to - that in the following example: - - warning: "x.ads" has dynamic elaboration checks and with's - warning: "y.ads" which has static elaboration checks - - These warnings indicate that the rule has been violated, and that as a - result elaboration checks may be missed in the resulting executable - file. This warning may be suppressed using the `-ws' binder switch in - the usual manner. - - One useful application of this mixing rule is in the case of a - subsystem which does not itself `with' units from the remainder of the - application. In this case, the entire subsystem can be compiled with - dynamic checks to resolve a circularity in the subsystem, while - allowing the main application that uses this subsystem to be compiled - using the more reliable default static model. - -  - File: gnat_ug_vxw.info, Node: What to Do If the Default Elaboration Behavior Fails, Next: Elaboration for Access-to-Subprogram Values, Prev: Mixing Elaboration Models, Up: Elaboration Order Handling in GNAT - - What to Do If the Default Elaboration Behavior Fails - ==================================================== - - If the binder cannot find an acceptable order, it outputs detailed - diagnostics. For example: - error: elaboration circularity detected - info: "proc (body)" must be elaborated before "pack (body)" - info: reason: Elaborate_All probably needed in unit "pack (body)" - info: recompile "pack (body)" with -gnatwl - info: for full details - info: "proc (body)" - info: is needed by its spec: - info: "proc (spec)" - info: which is withed by: - info: "pack (body)" - info: "pack (body)" must be elaborated before "proc (body)" - info: reason: pragma Elaborate in unit "proc (body)" - - - In this case we have a cycle that the binder cannot break. On the one - hand, there is an explicit pragma Elaborate in `proc' for `pack'. This - means that the body of `pack' must be elaborated before the body of - `proc'. On the other hand, there is elaboration code in `pack' that - calls a subprogram in `proc'. This means that for maximum safety, there - should really be a pragma Elaborate_All in `pack' for `proc' which - would require that the body of `proc' be elaborated before the body of - `pack'. Clearly both requirements cannot be satisfied. Faced with a - circularity of this kind, you have three different options. - - Fix the program - The most desirable option from the point of view of long-term - maintenance is to rearrange the program so that the elaboration - problems are avoided. One useful technique is to place the - elaboration code into separate child packages. Another is to move - some of the initialization code to explicitly called subprograms, - where the program controls the order of initialization explicitly. - Although this is the most desirable option, it may be impractical - and involve too much modification, especially in the case of - complex legacy code. - - Perform dynamic checks - If the compilations are done using the `-gnatE' (dynamic - elaboration check) switch, then GNAT behaves in a quite different - manner. Dynamic checks are generated for all calls that could - possibly result in raising an exception. With this switch, the - compiler does not generate implicit `Elaborate_All' pragmas. The - behavior then is exactly as specified in the Ada 95 Reference - Manual. The binder will generate an executable program that may - or may not raise `Program_Error', and then it is the programmer's - job to ensure that it does not raise an exception. Note that it is - important to compile all units with the switch, it cannot be used - selectively. - - Suppress checks - The drawback of dynamic checks is that they generate a significant - overhead at run time, both in space and time. If you are - absolutely sure that your program cannot raise any elaboration - exceptions, and you still want to use the dynamic elaboration - model, then you can use the configuration pragma `Suppress - (Elaboration_Checks)' to suppress all such checks. For example - this pragma could be placed in the `gnat.adc' file. - - Suppress checks selectively - When you know that certain calls in elaboration code cannot - possibly lead to an elaboration error, and the binder nevertheless - generates warnings on those calls and inserts Elaborate_All - pragmas that lead to elaboration circularities, it is possible to - remove those warnings locally and obtain a program that will bind. - Clearly this can be unsafe, and it is the responsibility of the - programmer to make sure that the resulting program has no - elaboration anomalies. The pragma `Suppress (Elaboration_Check)' - can be used with different granularity to suppress warnings and - break elaboration circularities: - - * Place the pragma that names the called subprogram in the - declarative part that contains the call. - - * Place the pragma in the declarative part, without naming an - entity. This disables warnings on all calls in the - corresponding declarative region. - - * Place the pragma in the package spec that declares the called - subprogram, and name the subprogram. This disables warnings - on all elaboration calls to that subprogram. - - * Place the pragma in the package spec that declares the called - subprogram, without naming any entity. This disables warnings - on all elaboration calls to all subprograms declared in this - spec. - - These four cases are listed in order of decreasing safety, and - therefore require increasing programmer care in their application. - Consider the following program: - - package Pack1 is - function F1 return Integer; - X1 : Integer; - end Pack1; - - package Pack2 is - function F2 return Integer; - function Pure (x : integer) return integer; - -- pragma Suppress (Elaboration_Check, On => Pure); -- (3) - -- pragma Suppress (Elaboration_Check); -- (4) - end Pack2; - - with Pack2; - package body Pack1 is - function F1 return Integer is - begin - return 100; - end F1; - Val : integer := Pack2.Pure (11); -- Elab. call (1) - begin - declare - -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1) - -- pragma Suppress(Elaboration_Check); -- (2) - begin - X1 := Pack2.F2 + 1; -- Elab. call (2) - end; - end Pack1; - - with Pack1; - package body Pack2 is - function F2 return Integer is - begin - return Pack1.F1; - end F2; - function Pure (x : integer) return integer is - begin - return x ** 3 - 3 * x; - end; - end Pack2; - - with Pack1, Ada.Text_IO; - procedure Proc3 is - begin - Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 - end Proc3; - In the absence of any pragmas, an attempt to bind this program - produces the following diagnostics: - error: elaboration circularity detected - info: "pack1 (body)" must be elaborated before "pack1 (body)" - info: reason: Elaborate_All probably needed in unit "pack1 (body)" - info: recompile "pack1 (body)" with -gnatwl for full details - info: "pack1 (body)" - info: must be elaborated along with its spec: - info: "pack1 (spec)" - info: which is withed by: - info: "pack2 (body)" - info: which must be elaborated along with its spec: - info: "pack2 (spec)" - info: which is withed by: - info: "pack1 (body)" - The sources of the circularity are the two calls to - `Pack2.Pure' and `Pack2.F2' in the body of `Pack1'. We can see - that the call to F2 is safe, even though F2 calls F1, because the - call appears after the elaboration of the body of F1. Therefore - the pragma (1) is safe, and will remove the warning on the call. - It is also possible to use pragma (2) because there are no other - potentially unsafe calls in the block. - - The call to `Pure' is safe because this function does not depend - on the state of `Pack2'. Therefore any call to this function is - safe, and it is correct to place pragma (3) in the corresponding - package spec. - - Finally, we could place pragma (4) in the spec of `Pack2' to - disable warnings on all calls to functions declared therein. Note - that this is not necessarily safe, and requires more detailed - examination of the subprogram bodies involved. In particular, a - call to `F2' requires that `F1' be already elaborated. - - It is hard to generalize on which of these four approaches should be - taken. Obviously if it is possible to fix the program so that the - default treatment works, this is preferable, but this may not always be - practical. It is certainly simple enough to use `-gnatE' but the - danger in this case is that, even if the GNAT binder finds a correct - elaboration order, it may not always do so, and certainly a binder from - another Ada compiler might not. A combination of testing and analysis - (for which the warnings generated with the `-gnatwl' switch can be - useful) must be used to ensure that the program is free of errors. One - switch that is useful in this testing is the `-p (pessimistic - elaboration order)' switch for `gnatbind'. Normally the binder tries - to find an order that has the best chance of of avoiding elaboration - problems. With this switch, the binder plays a devil's advocate role, - and tries to choose the order that has the best chance of failing. If - your program works even with this switch, then it has a better chance - of being error free, but this is still not a guarantee. - - For an example of this approach in action, consider the C-tests - (executable tests) from the ACVC suite. If these are compiled and run - with the default treatment, then all but one of them succeed without - generating any error diagnostics from the binder. However, there is one - test that fails, and this is not surprising, because the whole point of - this test is to ensure that the compiler can handle cases where it is - impossible to determine a correct order statically, and it checks that - an exception is indeed raised at run time. - - This one test must be compiled and run using the `-gnatE' switch, - and then it passes. Alternatively, the entire suite can be run using - this switch. It is never wrong to run with the dynamic elaboration - switch if your code is correct, and we assume that the C-tests are - indeed correct (it is less efficient, but efficiency is not a factor in - running the ACVC tests.) - -  - File: gnat_ug_vxw.info, Node: Elaboration for Access-to-Subprogram Values, Next: Summary of Procedures for Elaboration Control, Prev: What to Do If the Default Elaboration Behavior Fails, Up: Elaboration Order Handling in GNAT - - Elaboration for Access-to-Subprogram Values - =========================================== - - The introduction of access-to-subprogram types in Ada 95 complicates - the handling of elaboration. The trouble is that it becomes impossible - to tell at compile time which procedure is being called. This means - that it is not possible for the binder to analyze the elaboration - requirements in this case. - - If at the point at which the access value is created (i.e., the - evaluation of `P'Access' for a subprogram `P'), the body of the - subprogram is known to have been elaborated, then the access value is - safe, and its use does not require a check. This may be achieved by - appropriate arrangement of the order of declarations if the subprogram - is in the current unit, or, if the subprogram is in another unit, by - using pragma `Pure', `Preelaborate', or `Elaborate_Body' on the - referenced unit. - - If the referenced body is not known to have been elaborated at the - point the access value is created, then any use of the access value - must do a dynamic check, and this dynamic check will fail and raise a - `Program_Error' exception if the body has not been elaborated yet. - GNAT will generate the necessary checks, and in addition, if the - `-gnatwl' switch is set, will generate warnings that such checks are - required. - - The use of dynamic dispatching for tagged types similarly generates - a requirement for dynamic checks, and premature calls to any primitive - operation of a tagged type before the body of the operation has been - elaborated, will result in the raising of `Program_Error'. - -  - File: gnat_ug_vxw.info, Node: Summary of Procedures for Elaboration Control, Next: Other Elaboration Order Considerations, Prev: Elaboration for Access-to-Subprogram Values, Up: Elaboration Order Handling in GNAT - - Summary of Procedures for Elaboration Control - ============================================= - - First, compile your program with the default options, using none of the - special elaboration control switches. If the binder successfully binds - your program, then you can be confident that, apart from issues raised - by the use of access-to-subprogram types and dynamic dispatching, the - program is free of elaboration errors. If it is important that the - program be portable, then use the `-gnatwl' switch to generate warnings - about missing `Elaborate_All' pragmas, and supply the missing pragmas. - - If the program fails to bind using the default static elaboration - handling, then you can fix the program to eliminate the binder message, - or recompile the entire program with the `-gnatE' switch to generate - dynamic elaboration checks, and, if you are sure there really are no - elaboration problems, use a global pragma `Suppress - (Elaboration_Checks)'. - -  - File: gnat_ug_vxw.info, Node: Other Elaboration Order Considerations, Prev: Summary of Procedures for Elaboration Control, Up: Elaboration Order Handling in GNAT - - Other Elaboration Order Considerations - ====================================== - - This section has been entirely concerned with the issue of finding a - valid elaboration order, as defined by the Ada Reference Manual. In a - case where several elaboration orders are valid, the task is to find one - of the possible valid elaboration orders (and the static model in GNAT - will ensure that this is achieved). - - The purpose of the elaboration rules in the Ada Reference Manual is - to make sure that no entity is accessed before it has been elaborated. - For a subprogram, this means that the spec and body must have been - elaborated before the subprogram is called. For an object, this means - that the object must have been elaborated before its value is read or - written. A violation of either of these two requirements is an access - before elaboration order, and this section has been all about avoiding - such errors. - - In the case where more than one order of elaboration is possible, in - the sense that access before elaboration errors are avoided, then any - one of the orders is "correct" in the sense that it meets the - requirements of the Ada Reference Manual, and no such error occurs. - - However, it may be the case for a given program, that there are - constraints on the order of elaboration that come not from consideration - of avoiding elaboration errors, but rather from extra-lingual logic - requirements. Consider this example: - - with Init_Constants; - package Constants is - X : Integer := 0; - Y : Integer := 0; - end Constants; - - package Init_Constants is - procedure Calc; - end Init_Constants; - - with Constants; - package body Init_Constants is - procedure Calc is begin null; end; - begin - Constants.X := 3; - Constants.Y := 4; - end Init_Constants; - - with Constants; - package Calc is - Z : Integer := Constants.X + Constants.Y; - end Calc; - - with Calc; - with Text_IO; use Text_IO; - procedure Main is - begin - Put_Line (Calc.Z'Img); - end Main; - - In this example, there is more than one valid order of elaboration. For - example both the following are correct orders: - - Init_Constants spec - Constants spec - Calc spec - Main body - Init_Constants body - - and - - Init_Constants spec - Init_Constants body - Constants spec - Calc spec - Main body - - There is no language rule to prefer one or the other, both are correct - from an order of elaboration point of view. But the programmatic effects - of the two orders are very different. In the first, the elaboration - routine of `Calc' initializes `Z' to zero, and then the main program - runs with this value of zero. But in the second order, the elaboration - routine of `Calc' runs after the body of Init_Constants has set `X' and - `Y' and thus `Z' is set to 7 before `Main' runs. - - One could perhaps by applying pretty clever non-artificial - intelligence to the situation guess that it is more likely that the - second order of elaboration is the one desired, but there is no formal - linguistic reason to prefer one over the other. In fact in this - particular case, GNAT will prefer the second order, because of the rule - that bodies are elaborated as soon as possible, but it's just luck that - this is what was wanted (if indeed the second order was preferred). - - If the program cares about the order of elaboration routines in a - case like this, it is important to specify the order required. In this - particular case, that could have been achieved by adding to the spec of - Calc: - - pragma Elaborate_All (Constants); - - which requires that the body (if any) and spec of `Constants', as well - as the body and spec of any unit `with''ed by `Constants' be elaborated - before `Calc' is elaborated. - - Clearly no automatic method can always guess which alternative you - require, and if you are working with legacy code that had constraints - of this kind which were not properly specified by adding `Elaborate' or - `Elaborate_All' pragmas, then indeed it is possible that two different - compilers can choose different orders. - - The `gnatbind' `-p' switch may be useful in smoking out problems. - This switch causes bodies to be elaborated as late as possible instead - of as early as possible. In the example above, it would have forced the - choice of the first elaboration order. If you get different results - when using this switch, and particularly if one set of results is right, - and one is wrong as far as you are concerned, it shows that you have - some missing `Elaborate' pragmas. For the example above, we have the - following output: - - gnatmake -f -q main - main - 7 - gnatmake -f -q main -bargs -p - main - 0 - - It is of course quite unlikely that both these results are correct, so - it is up to you in a case like this to investigate the source of the - difference, by looking at the two elaboration orders that are chosen, - and figuring out which is correct, and then adding the necessary - `Elaborate_All' pragmas to ensure the desired order. - -  - File: gnat_ug_vxw.info, Node: The Cross-Referencing Tools gnatxref and gnatfind, Next: File Name Krunching Using gnatkr, Prev: Elaboration Order Handling in GNAT, Up: Top - - The Cross-Referencing Tools `gnatxref' and `gnatfind' - ***************************************************** - - The compiler generates cross-referencing information (unless you set - the `-gnatx' switch), which are saved in the `.ali' files. This - information indicates where in the source each entity is declared and - referenced. Note that entities in package Standard are not included, but - entities in all other predefined units are included in the output. - - Before using any of these two tools, you need to compile - successfully your application, so that GNAT gets a chance to generate - the cross-referencing information. - - The two tools `gnatxref' and `gnatfind' take advantage of this - information to provide the user with the capability to easily locate the - declaration and references to an entity. These tools are quite similar, - the difference being that `gnatfind' is intended for locating - definitions and/or references to a specified entity or entities, whereas - `gnatxref' is oriented to generating a full report of all - cross-references. - - To use these tools, you must not compile your application using the - `-gnatx' switch on the `gnatmake' command line (*note (gnat_ug)The GNAT - Make Program gnatmake::). Otherwise, cross-referencing information will - not be generated. - - * Menu: - - * gnatxref Switches:: - * gnatfind Switches:: - * Project Files for gnatxref and gnatfind:: - * Regular Expressions in gnatfind and gnatxref:: - * Examples of gnatxref Usage:: - * Examples of gnatfind Usage:: - -  - File: gnat_ug_vxw.info, Node: gnatxref Switches, Next: gnatfind Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - `gnatxref' Switches - =================== - - The command lines for `gnatxref' is: - $ gnatxref [switches] sourcefile1 [sourcefile2 ...] - - where - - `sourcefile1, sourcefile2' - identifies the source files for which a report is to be generated. - The 'with'ed units will be processed too. You must provide at - least one file. - - These file names are considered to be regular expressions, so for - instance specifying 'source*.adb' is the same as giving every file - in the current directory whose name starts with 'source' and whose - extension is 'adb'. - - The switches can be : - `-a' - If this switch is present, `gnatfind' and `gnatxref' will parse - the read-only files found in the library search path. Otherwise, - these files will be ignored. This option can be used to protect - Gnat sources or your own libraries from being parsed, thus making - `gnatfind' and `gnatxref' much faster, and their output much - smaller. - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source file search is undertaken is the same as for - `gnatmake'. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is the same as - for `gnatmake'. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-d' - If this switch is set `gnatxref' will output the parent type - reference for each matching derived types. - - `-f' - If this switch is set, the output file names will be preceded by - their directory (if the file was found in the search path). If - this switch is not set, the directory will not be printed. - - `-g' - If this switch is set, information is output only for library-level - entities, ignoring local entities. The use of this switch may - accelerate `gnatfind' and `gnatxref'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-pFILE' - Specify a project file to use *Note Project Files::. By default, - `gnatxref' and `gnatfind' will try to locate a project file in the - current directory. - - If a project file is either specified or found by the tools, then - the content of the source directory and object directory lines are - added as if they had been specified respectively by `-aI' and - `-aO'. - - `-u' - Output only unused symbols. This may be really useful if you give - your main compilation unit on the command line, as `gnatxref' will - then display every unused entity and 'with'ed package. - - `-v' - Instead of producing the default output, `gnatxref' will generate a - `tags' file that can be used by vi. For examples how to use this - feature, see *Note Examples of gnatxref Usage::. The tags file is - output to the standard output, thus you will have to redirect it - to a file. - - All these switches may be in any order on the command line, and may - even appear after the file names. They need not be separated by spaces, - thus you can say `gnatxref -ag' instead of `gnatxref -a -g'. - -  - File: gnat_ug_vxw.info, Node: gnatfind Switches, Next: Project Files for gnatxref and gnatfind, Prev: gnatxref Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - `gnatfind' Switches - =================== - - The command line for `gnatfind' is: - - $ gnatfind [switches] pattern[:sourcefile[:line[:column]]] - [file1 file2 ...] - - where - - `pattern' - An entity will be output only if it matches the regular expression - found in `pattern', see *Note Regular Expressions in gnatfind and - gnatxref::. - - Omitting the pattern is equivalent to specifying `*', which will - match any entity. Note that if you do not provide a pattern, you - have to provide both a sourcefile and a line. - - Entity names are given in Latin-1, with uppercase/lowercase - equivalence for matching purposes. At the current time there is no - support for 8-bit codes other than Latin-1, or for wide characters - in identifiers. - - `sourcefile' - `gnatfind' will look for references, bodies or declarations of - symbols referenced in `sourcefile', at line `line' and column - `column'. See *note Examples of gnatfind Usage:: for syntax - examples. - - `line' - is a decimal integer identifying the line number containing the - reference to the entity (or entities) to be located. - - `column' - is a decimal integer identifying the exact location on the line of - the first character of the identifier for the entity reference. - Columns are numbered from 1. - - `file1 file2 ...' - The search will be restricted to these files. If none are given, - then the search will be done for every library file in the search - path. These file must appear only after the pattern or sourcefile. - - These file names are considered to be regular expressions, so for - instance specifying 'source*.adb' is the same as giving every file - in the current directory whose name starts with 'source' and whose - extension is 'adb'. - - Not that if you specify at least one file in this part, `gnatfind' - may sometimes not be able to find the body of the subprograms... - - At least one of 'sourcefile' or 'pattern' has to be present on the - command line. - - The following switches are available: - `-a' - If this switch is present, `gnatfind' and `gnatxref' will parse - the read-only files found in the library search path. Otherwise, - these files will be ignored. This option can be used to protect - Gnat sources or your own libraries from being parsed, thus making - `gnatfind' and `gnatxref' much faster, and their output much - smaller. - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source file search is undertaken is the same as for - `gnatmake'. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is the same as - for `gnatmake'. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-d' - If this switch is set, then `gnatfind' will output the parent type - reference for each matching derived types. - - `-e' - By default, `gnatfind' accept the simple regular expression set for - `pattern'. If this switch is set, then the pattern will be - considered as full Unix-style regular expression. - - `-f' - If this switch is set, the output file names will be preceded by - their directory (if the file was found in the search path). If - this switch is not set, the directory will not be printed. - - `-g' - If this switch is set, information is output only for library-level - entities, ignoring local entities. The use of this switch may - accelerate `gnatfind' and `gnatxref'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-pFILE' - Specify a project file (*note Project Files::) to use. By - default, `gnatxref' and `gnatfind' will try to locate a project - file in the current directory. - - If a project file is either specified or found by the tools, then - the content of the source directory and object directory lines are - added as if they had been specified respectively by `-aI' and - `-aO'. - - `-r' - By default, `gnatfind' will output only the information about the - declaration, body or type completion of the entities. If this - switch is set, the `gnatfind' will locate every reference to the - entities in the files specified on the command line (or in every - file in the search path if no file is given on the command line). - - `-s' - If this switch is set, then `gnatfind' will output the content of - the Ada source file lines were the entity was found. - - `-t' - If this switch is set, then `gnatfind' will output the type - hierarchy for the specified type. It act like -d option but - recursively from parent type to parent type. When this switch is - set it is not possible to specify more than one file. - - All these switches may be in any order on the command line, and may - even appear after the file names. They need not be separated by spaces, - thus you can say `gnatxref -ag' instead of `gnatxref -a -g'. - - As stated previously, gnatfind will search in every directory in the - search path. You can force it to look only in the current directory if - you specify `*' at the end of the command line. - -  - File: gnat_ug_vxw.info, Node: Project Files for gnatxref and gnatfind, Next: Regular Expressions in gnatfind and gnatxref, Prev: gnatfind Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Project Files for `gnatxref' and `gnatfind' - =========================================== - - Project files allow a programmer to specify how to compile its - application, where to find sources,... These files are used primarily by - the Glide Ada mode, but they can also be used by the two tools - `gnatxref' and `gnatfind'. - - A project file name must end with `.adp'. If a single one is present - in the current directory, then `gnatxref' and `gnatfind' will extract - the information from it. If multiple project files are found, none of - them is read, and you have to use the `-p' switch to specify the one - you want to use. - - The following lines can be included, even though most of them have - default values which can be used in most cases. The lines can be - entered in any order in the file. Except for `src_dir' and `obj_dir', - you can only have one instance of each line. If you have multiple - instances, only the last one is taken into account. - - `src_dir=DIR [default: "./"]' - specifies a directory where to look for source files. Multiple - src_dir lines can be specified and they will be searched in the - order they are specified. - - `obj_dir=DIR [default: "./"]' - specifies a directory where to look for object and library files. - Multiple obj_dir lines can be specified and they will be searched - in the order they are specified - - `comp_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${comp_opt}' notation. This is intended to store the default - switches given to `gnatmake' and `gcc'. - - `bind_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${bind_opt}' notation. This is intended to store the default - switches given to `gnatbind'. - - `link_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${link_opt}' notation. This is intended to store the default - switches given to `gnatlink'. - - `main=EXECUTABLE [default: ""]' - specifies the name of the executable for the application. This - variable can be referred to in the following lines by using the - `${main}' notation. - - `comp_cmd=COMMAND [default: "gcc -c -I${src_dir} -g -gnatq"]' - specifies the command used to compile a single file in the - application. - - `make_cmd=COMMAND [default: "gnatmake ${main} -aI${src_dir} -aO${obj_dir} -g -gnatq -cargs ${comp_opt} -bargs ${bind_opt} -largs ${link_opt}"]' - specifies the command used to recompile the whole application. - - `run_cmd=COMMAND [default: "${main}"]' - specifies the command used to run the application. - - `debug_cmd=COMMAND [default: "gdb ${main}"]' - specifies the command used to debug the application - - `gnatxref' and `gnatfind' only take into account the `src_dir' and - `obj_dir' lines, and ignore the others. - -  - File: gnat_ug_vxw.info, Node: Regular Expressions in gnatfind and gnatxref, Next: Examples of gnatxref Usage, Prev: Project Files for gnatxref and gnatfind, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Regular Expressions in `gnatfind' and `gnatxref' - ================================================ - - As specified in the section about `gnatfind', the pattern can be a - regular expression. Actually, there are to set of regular expressions - which are recognized by the program : - - `globbing patterns' - These are the most usual regular expression. They are the same - that you generally used in a Unix shell command line, or in a DOS - session. - - Here is a more formal grammar : - regexp ::= term - term ::= elmt -- matches elmt - term ::= elmt elmt -- concatenation (elmt then elmt) - term ::= * -- any string of 0 or more characters - term ::= ? -- matches any character - term ::= [char {char}] -- matches any character listed - term ::= [char - char] -- matches any character in range - - `full regular expression' - The second set of regular expressions is much more powerful. This - is the type of regular expressions recognized by utilities such a - `grep'. - - The following is the form of a regular expression, expressed in Ada - reference manual style BNF is as follows - - regexp ::= term {| term} -- alternation (term or term ...) - - term ::= item {item} -- concatenation (item then item) - - item ::= elmt -- match elmt - item ::= elmt * -- zero or more elmt's - item ::= elmt + -- one or more elmt's - item ::= elmt ? -- matches elmt or nothing - elmt ::= nschar -- matches given character - elmt ::= [nschar {nschar}] -- matches any character listed - elmt ::= [^ nschar {nschar}] -- matches any character not listed - elmt ::= [char - char] -- matches chars in given range - elmt ::= \ char -- matches given character - elmt ::= . -- matches any single character - elmt ::= ( regexp ) -- parens used for grouping - - char ::= any character, including special characters - nschar ::= any character except ()[].*+?^ - - Following are a few examples : - - `abcde|fghi' - will match any of the two strings 'abcde' and 'fghi'. - - `abc*d' - will match any string like 'abd', 'abcd', 'abccd', 'abcccd', - and so on - - `[a-z]+' - will match any string which has only lowercase characters in - it (and at least one character - -  - File: gnat_ug_vxw.info, Node: Examples of gnatxref Usage, Next: Examples of gnatfind Usage, Prev: Regular Expressions in gnatfind and gnatxref, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Examples of `gnatxref' Usage - ============================ - - General Usage - ------------- - - For the following examples, we will consider the following units : - - main.ads: - 1: with Bar; - 2: package Main is - 3: procedure Foo (B : in Integer); - 4: C : Integer; - 5: private - 6: D : Integer; - 7: end Main; - - main.adb: - 1: package body Main is - 2: procedure Foo (B : in Integer) is - 3: begin - 4: C := B; - 5: D := B; - 6: Bar.Print (B); - 7: Bar.Print (C); - 8: end Foo; - 9: end Main; - - bar.ads: - 1: package Bar is - 2: procedure Print (B : Integer); - 3: end bar; - - The first thing to do is to recompile your application (for - instance, in that case just by doing a `gnatmake main', so that - GNAT generates the cross-referencing information. You can then - issue any of the following commands: - - `gnatxref main.adb' - `gnatxref' generates cross-reference information for main.adb and - every unit 'with'ed by main.adb. - - The output would be: - B Type: Integer - Decl: bar.ads 2:22 - B Type: Integer - Decl: main.ads 3:20 - Body: main.adb 2:20 - Ref: main.adb 4:13 5:13 6:19 - Bar Type: Unit - Decl: bar.ads 1:9 - Ref: main.adb 6:8 7:8 - main.ads 1:6 - C Type: Integer - Decl: main.ads 4:5 - Modi: main.adb 4:8 - Ref: main.adb 7:19 - D Type: Integer - Decl: main.ads 6:5 - Modi: main.adb 5:8 - Foo Type: Unit - Decl: main.ads 3:15 - Body: main.adb 2:15 - Main Type: Unit - Decl: main.ads 2:9 - Body: main.adb 1:14 - Print Type: Unit - Decl: bar.ads 2:15 - Ref: main.adb 6:12 7:12 - - that is the entity `Main' is declared in main.ads, line 2, column - 9, its body is in main.adb, line 1, column 14 and is not - referenced any where. - - The entity `Print' is declared in bar.ads, line 2, column 15 and it - it referenced in main.adb, line 6 column 12 and line 7 column 12. - - `gnatxref package1.adb package2.ads' - `gnatxref' will generates cross-reference information for - package1.adb, package2.ads and any other package 'with'ed by any - of these. - - Using gnatxref with vi - ---------------------- - - `gnatxref' can generate a tags file output, which can be used - directly from `vi'. Note that the standard version of `vi' will not - work properly with overloaded symbols. Consider using another free - implementation of `vi', such as `vim'. - - $ gnatxref -v gnatfind.adb > tags - - will generate the tags file for `gnatfind' itself (if the sources are - in the search path!). - - From `vi', you can then use the command `:tag entity' (replacing - entity by whatever you are looking for), and vi will display a new file - with the corresponding declaration of entity. - -  - File: gnat_ug_vxw.info, Node: Examples of gnatfind Usage, Prev: Examples of gnatxref Usage, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Examples of `gnatfind' Usage - ============================ - - `gnatfind -f xyz:main.adb' - Find declarations for all entities xyz referenced at least once in - main.adb. The references are search in every library file in the - search path. - - The directories will be printed as well (as the `-f' switch is set) - - The output will look like: - directory/main.ads:106:14: xyz <= declaration - directory/main.adb:24:10: xyz <= body - directory/foo.ads:45:23: xyz <= declaration - - that is to say, one of the entities xyz found in main.adb is - declared at line 12 of main.ads (and its body is in main.adb), and - another one is declared at line 45 of foo.ads - - `gnatfind -fs xyz:main.adb' - This is the same command as the previous one, instead `gnatfind' - will display the content of the Ada source file lines. - - The output will look like: - - directory/main.ads:106:14: xyz <= declaration - procedure xyz; - directory/main.adb:24:10: xyz <= body - procedure xyz is - directory/foo.ads:45:23: xyz <= declaration - xyz : Integer; - - This can make it easier to find exactly the location your are - looking for. - - `gnatfind -r "*x*":main.ads:123 foo.adb' - Find references to all entities containing an x that are - referenced on line 123 of main.ads. The references will be - searched only in main.adb and foo.adb. - - `gnatfind main.ads:123' - Find declarations and bodies for all entities that are referenced - on line 123 of main.ads. - - This is the same as `gnatfind "*":main.adb:123'. - - `gnatfind mydir/main.adb:123:45' - Find the declaration for the entity referenced at column 45 in - line 123 of file main.adb in directory mydir. Note that it is - usual to omit the identifier name when the column is given, since - the column position identifies a unique reference. - - The column has to be the beginning of the identifier, and should - not point to any character in the middle of the identifier. - -  - File: gnat_ug_vxw.info, Node: File Name Krunching Using gnatkr, Next: Preprocessing Using gnatprep, Prev: The Cross-Referencing Tools gnatxref and gnatfind, Up: Top - - File Name Krunching Using `gnatkr' - ********************************** - - This chapter discusses the method used by the compiler to shorten the - default file names chosen for Ada units so that they do not exceed the - maximum length permitted. It also describes the `gnatkr' utility that - can be used to determine the result of applying this shortening. - - * Menu: - - * About gnatkr:: - * Using gnatkr:: - * Krunching Method:: - * Examples of gnatkr Usage:: - -  - File: gnat_ug_vxw.info, Node: About gnatkr, Next: Using gnatkr, Up: File Name Krunching Using gnatkr - - About `gnatkr' - ============== - - The default file naming rule in GNAT is that the file name must be - derived from the unit name. The exact default rule is as follows: - * Take the unit name and replace all dots by hyphens. - - * If such a replacement occurs in the second character position of a - name, and the first character is a, g, s, or i then replace the - dot by the character ~ (tilde) instead of a minus. - The reason for this exception is to avoid clashes with the standard - names for children of System, Ada, Interfaces, and GNAT, which use the - prefixes s- a- i- and g- respectively. - - The `-gnatkNN' switch of the compiler activates a "krunching" - circuit that limits file names to nn characters (where nn is a decimal - integer). For example, using OpenVMS, where the maximum file name - length is 39, the value of nn is usually set to 39, but if you want to - generate a set of files that would be usable if ported to a system with - some different maximum file length, then a different value can be - specified. The default value of 39 for OpenVMS need not be specified. - - The `gnatkr' utility can be used to determine the krunched name for - a given file, when krunched to a specified maximum length. - -  - File: gnat_ug_vxw.info, Node: Using gnatkr, Next: Krunching Method, Prev: About gnatkr, Up: File Name Krunching Using gnatkr - - Using `gnatkr' - ============== - - The `gnatkr' command has the form - - $ gnatkr NAME [LENGTH] - - NAME can be an Ada name with dots or the GNAT name of the unit, where - the dots representing child units or subunit are replaced by hyphens. - The only confusion arises if a name ends in `.ads' or `.adb'. `gnatkr' - takes this to be an extension if there are no other dots in the name - and the whole name is in lowercase. - - LENGTH represents the length of the krunched name. The default when - no argument is given is 8 characters. A length of zero stands for - unlimited, in other words do not chop except for system files which are - always 8. - - The output is the krunched name. The output has an extension only if the - original argument was a file name with an extension. - -  - File: gnat_ug_vxw.info, Node: Krunching Method, Next: Examples of gnatkr Usage, Prev: Using gnatkr, Up: File Name Krunching Using gnatkr - - Krunching Method - ================ - - The initial file name is determined by the name of the unit that the - file contains. The name is formed by taking the full expanded name of - the unit and replacing the separating dots with hyphens and using - lowercase for all letters, except that a hyphen in the second character - position is replaced by a tilde if the first character is a, i, g, or s. - The extension is `.ads' for a specification and `.adb' for a body. - Krunching does not affect the extension, but the file name is shortened - to the specified length by following these rules: - - * The name is divided into segments separated by hyphens, tildes or - underscores and all hyphens, tildes, and underscores are - eliminated. If this leaves the name short enough, we are done. - - * If the name is too long, the longest segment is located (left-most - if there are two of equal length), and shortened by dropping its - last character. This is repeated until the name is short enough. - - As an example, consider the krunching of - `our-strings-wide_fixed.adb' to fit the name into 8 characters as - required by some operating systems. - - our-strings-wide_fixed 22 - our strings wide fixed 19 - our string wide fixed 18 - our strin wide fixed 17 - our stri wide fixed 16 - our stri wide fixe 15 - our str wide fixe 14 - our str wid fixe 13 - our str wid fix 12 - ou str wid fix 11 - ou st wid fix 10 - ou st wi fix 9 - ou st wi fi 8 - Final file name: oustwifi.adb - - * The file names for all predefined units are always krunched to - eight characters. The krunching of these predefined units uses the - following special prefix replacements: - - `ada-' - replaced by `a-' - - `gnat-' - replaced by `g-' - - `interfaces-' - replaced by `i-' - - `system-' - replaced by `s-' - - These system files have a hyphen in the second character position. - That is why normal user files replace such a character with a - tilde, to avoid confusion with system file names. - - As an example of this special rule, consider - `ada-strings-wide_fixed.adb', which gets krunched as follows: - - ada-strings-wide_fixed 22 - a- strings wide fixed 18 - a- string wide fixed 17 - a- strin wide fixed 16 - a- stri wide fixed 15 - a- stri wide fixe 14 - a- str wide fixe 13 - a- str wid fixe 12 - a- str wid fix 11 - a- st wid fix 10 - a- st wi fix 9 - a- st wi fi 8 - Final file name: a-stwifi.adb - - Of course no file shortening algorithm can guarantee uniqueness over - all possible unit names, and if file name krunching is used then it is - your responsibility to ensure that no name clashes occur. The utility - program `gnatkr' is supplied for conveniently determining the krunched - name of a file. - -  - File: gnat_ug_vxw.info, Node: Examples of gnatkr Usage, Prev: Krunching Method, Up: File Name Krunching Using gnatkr - - Examples of `gnatkr' Usage - ========================== - - $ gnatkr very_long_unit_name.ads --> velounna.ads - $ gnatkr grandparent-parent-child.ads --> grparchi.ads - $ gnatkr Grandparent.Parent.Child --> grparchi - $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads - $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads - -  - File: gnat_ug_vxw.info, Node: Preprocessing Using gnatprep, Next: The GNAT Library Browser gnatls, Prev: File Name Krunching Using gnatkr, Up: Top - - Preprocessing Using `gnatprep' - ****************************** - - The `gnatprep' utility provides a simple preprocessing capability for - Ada programs. It is designed for use with GNAT, but is not dependent - on any special features of GNAT. - - * Menu: - - * Using gnatprep:: - * Switches for gnatprep:: - * Form of Definitions File:: - * Form of Input Text for gnatprep:: - -  - File: gnat_ug_vxw.info, Node: Using gnatprep, Next: Switches for gnatprep, Up: Preprocessing Using gnatprep - - Using `gnatprep' - ================ - - To call `gnatprep' use - - $ gnatprep [-bcrsu] [-Dsymbol=value] infile outfile [deffile] - - where - `infile' - is the full name of the input file, which is an Ada source file - containing preprocessor directives. - - `outfile' - is the full name of the output file, which is an Ada source in - standard Ada form. When used with GNAT, this file name will - normally have an ads or adb suffix. - - `deffile' - is the full name of a text file containing definitions of symbols - to be referenced by the preprocessor. This argument is optional, - and can be replaced by the use of the `-D' switch. - - `switches' - is an optional sequence of switches as described in the next - section. - -  - File: gnat_ug_vxw.info, Node: Switches for gnatprep, Next: Form of Definitions File, Prev: Using gnatprep, Up: Preprocessing Using gnatprep - - Switches for `gnatprep' - ======================= - - `-b' - Causes both preprocessor lines and the lines deleted by - preprocessing to be replaced by blank lines in the output source - file, preserving line numbers in the output file. - - `-c' - Causes both preprocessor lines and the lines deleted by - preprocessing to be retained in the output source as comments - marked with the special string "-! ". This option will result in - line numbers being preserved in the output file. - - `-Dsymbol=value' - Defines a new symbol, associated with value. If no value is given - on the command line, then symbol is considered to be `True'. This - switch can be used in place of a definition file. - - `-r' - Causes a `Source_Reference' pragma to be generated that references - the original input file, so that error messages will use the file - name of this original file. The use of this switch implies that - preprocessor lines are not to be removed from the file, so its use - will force `-b' mode if `-c' has not been specified explicitly. - - Note that if the file to be preprocessed contains multiple units, - then it will be necessary to `gnatchop' the output file from - `gnatprep'. If a `Source_Reference' pragma is present in the - preprocessed file, it will be respected by `gnatchop -r' so that - the final chopped files will correctly refer to the original input - source file for `gnatprep'. - - `-s' - Causes a sorted list of symbol names and values to be listed on - the standard output file. - - `-u' - Causes undefined symbols to be treated as having the value FALSE - in the context of a preprocessor test. In the absence of this - option, an undefined symbol in a `#if' or `#elsif' test will be - treated as an error. - - Note: if neither `-b' nor `-c' is present, then preprocessor lines and - deleted lines are completely removed from the output, unless -r is - specified, in which case -b is assumed. - -  - File: gnat_ug_vxw.info, Node: Form of Definitions File, Next: Form of Input Text for gnatprep, Prev: Switches for gnatprep, Up: Preprocessing Using gnatprep - - Form of Definitions File - ======================== - - The definitions file contains lines of the form - - symbol := value - - where symbol is an identifier, following normal Ada (case-insensitive) - rules for its syntax, and value is one of the following: - - * Empty, corresponding to a null substitution - - * A string literal using normal Ada syntax - - * Any sequence of characters from the set (letters, digits, period, - underline). - - Comment lines may also appear in the definitions file, starting with - the usual `--', and comments may be added to the definitions lines. - -  - File: gnat_ug_vxw.info, Node: Form of Input Text for gnatprep, Prev: Form of Definitions File, Up: Preprocessing Using gnatprep - - Form of Input Text for `gnatprep' - ================================= - - The input text may contain preprocessor conditional inclusion lines, as - well as general symbol substitution sequences. - - The preprocessor conditional inclusion commands have the form - - #if expression [then] - lines - #elsif expression [then] - lines - #elsif expression [then] - lines - ... - #else - lines - #end if; - - In this example, expression is defined by the following grammar: - expression ::= - expression ::= = "" - expression ::= = - expression ::= 'Defined - expression ::= not expression - expression ::= expression and expression - expression ::= expression or expression - expression ::= expression and then expression - expression ::= expression or else expression - expression ::= ( expression ) - - For the first test (expression ::= ) the symbol must have - either the value true or false, that is to say the right-hand of the - symbol definition must be one of the (case-insensitive) literals `True' - or `False'. If the value is true, then the corresponding lines are - included, and if the value is false, they are excluded. - - The test (expression ::= `'Defined') is true only if the - symbol has been defined in the definition file or by a `-D' switch on - the command line. Otherwise, the test is false. - - The equality tests are case insensitive, as are all the preprocessor - lines. - - If the symbol referenced is not defined in the symbol definitions - file, then the effect depends on whether or not switch `-u' is - specified. If so, then the symbol is treated as if it had the value - false and the test fails. If this switch is not specified, then it is - an error to reference an undefined symbol. It is also an error to - reference a symbol that is defined with a value other than `True' or - `False'. - - The use of the `not' operator inverts the sense of this logical - test, so that the lines are included only if the symbol is not defined. - The `then' keyword is optional as shown - - The `#' must be the first non-blank character on a line, but - otherwise the format is free form. Spaces or tabs may appear between - the `#' and the keyword. The keywords and the symbols are case - insensitive as in normal Ada code. Comments may be used on a - preprocessor line, but other than that, no other tokens may appear on a - preprocessor line. Any number of `elsif' clauses can be present, - including none at all. The `else' is optional, as in Ada. - - The `#' marking the start of a preprocessor line must be the first - non-blank character on the line, i.e. it must be preceded only by - spaces or horizontal tabs. - - Symbol substitution outside of preprocessor lines is obtained by - using the sequence - - $symbol - - anywhere within a source line, except in a comment or within a string - literal. The identifier following the `$' must match one of the symbols - defined in the symbol definition file, and the result is to substitute - the value of the symbol in place of `$symbol' in the output file. - - Note that although the substitution of strings within a string - literal is not possible, it is possible to have a symbol whose defined - value is a string literal. So instead of setting XYZ to `hello' and - writing: - - Header : String := "$XYZ"; - - you should set XYZ to `"hello"' and write: - - Header : String := $XYZ; - - and then the substitution will occur as desired. - -  - File: gnat_ug_vxw.info, Node: The GNAT Library Browser gnatls, Next: GNAT and Libraries, Prev: Preprocessing Using gnatprep, Up: Top - - The GNAT Library Browser `gnatls' - ********************************* - - `gnatls' is a tool that outputs information about compiled units. It - gives the relationship between objects, unit names and source files. It - can also be used to check the source dependencies of a unit as well as - various characteristics. - - * Menu: - - * Running gnatls:: - * Switches for gnatls:: - * Examples of gnatls Usage:: - -  - File: gnat_ug_vxw.info, Node: Running gnatls, Next: Switches for gnatls, Up: The GNAT Library Browser gnatls - - Running `gnatls' - ================ - - The `gnatls' command has the form - - $ gnatls switches OBJECT_OR_ALI_FILE - - The main argument is the list of object or `ali' files (*note The Ada - Library Information Files::) for which information is requested. - - In normal mode, without additional option, `gnatls' produces a - four-column listing. Each line represents information for a specific - object. The first column gives the full path of the object, the second - column gives the name of the principal unit in this object, the third - column gives the status of the source and the fourth column gives the - full path of the source representing this unit. Here is a simple - example of use: - - $ gnatls *.o - ./demo1.o demo1 DIF demo1.adb - ./demo2.o demo2 OK demo2.adb - ./hello.o h1 OK hello.adb - ./instr-child.o instr.child MOK instr-child.adb - ./instr.o instr OK instr.adb - ./tef.o tef DIF tef.adb - ./text_io_example.o text_io_example OK text_io_example.adb - ./tgef.o tgef DIF tgef.adb - - The first line can be interpreted as follows: the main unit which is - contained in object file `demo1.o' is demo1, whose main source is in - `demo1.adb'. Furthermore, the version of the source used for the - compilation of demo1 has been modified (DIF). Each source file has a - status qualifier which can be: - - `OK (unchanged)' - The version of the source file used for the compilation of the - specified unit corresponds exactly to the actual source file. - - `MOK (slightly modified)' - The version of the source file used for the compilation of the - specified unit differs from the actual source file but not enough - to require recompilation. If you use gnatmake with the qualifier - `-m (minimal recompilation)', a file marked MOK will not be - recompiled. - - `DIF (modified)' - No version of the source found on the path corresponds to the - source used to build this object. - - `??? (file not found)' - No source file was found for this unit. - - `HID (hidden, unchanged version not first on PATH)' - The version of the source that corresponds exactly to the source - used for compilation has been found on the path but it is hidden - by another version of the same source that has been modified. - -  - File: gnat_ug_vxw.info, Node: Switches for gnatls, Next: Examples of gnatls Usage, Prev: Running gnatls, Up: The GNAT Library Browser gnatls - - Switches for `gnatls' - ===================== - - `gnatls' recognizes the following switches: - - `-a' - Consider all units, including those of the predefined Ada library. - Especially useful with `-d'. - - `-d' - List sources from which specified units depend on. - - `-h' - Output the list of options. - - `-o' - Only output information about object files. - - `-s' - Only output information about source files. - - `-u' - Only output information about compilation units. - - `-aODIR' - `-aIDIR' - `-IDIR' - `-I-' - `-nostdinc' - Source path manipulation. Same meaning as the equivalent - `gnatmake' flags (see *Note Switches for gnatmake::). - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-v' - Verbose mode. Output the complete source and object paths. Do not - use the default column layout but instead use long format giving - as much as information possible on each requested units, including - special characteristics such as: - - `Preelaborable' - The unit is preelaborable in the Ada 95 sense. - - `No_Elab_Code' - No elaboration code has been produced by the compiler for - this unit. - - `Pure' - The unit is pure in the Ada 95 sense. - - `Elaborate_Body' - The unit contains a pragma Elaborate_Body. - - `Remote_Types' - The unit contains a pragma Remote_Types. - - `Shared_Passive' - The unit contains a pragma Shared_Passive. - - `Predefined' - This unit is part of the predefined environment and cannot be - modified by the user. - - `Remote_Call_Interface' - The unit contains a pragma Remote_Call_Interface. - -  - File: gnat_ug_vxw.info, Node: Examples of gnatls Usage, Prev: Switches for gnatls, Up: The GNAT Library Browser gnatls - - Example of `gnatls' Usage - ========================= - - Example of using the verbose switch. Note how the source and object - paths are affected by the -I switch. - - $ gnatls -v -I.. demo1.o - - GNATLS 3.10w (970212) Copyright 1999 Free Software Foundation, Inc. - - Source Search Path: - - ../ - /home/comar/local/adainclude/ - - Object Search Path: - - ../ - /home/comar/local/lib/gcc-lib/mips-sni-sysv4/2.7.2/adalib/ - - ./demo1.o - Unit => - Name => demo1 - Kind => subprogram body - Flags => No_Elab_Code - Source => demo1.adb modified - - The following is an example of use of the dependency list. Note the - use of the -s switch which gives a straight list of source files. This - can be useful for building specialized scripts. - - $ gnatls -d demo2.o - ./demo2.o demo2 OK demo2.adb - OK gen_list.ads - OK gen_list.adb - OK instr.ads - OK instr-child.ads - - $ gnatls -d -s -a demo1.o - demo1.adb - /home/comar/local/adainclude/ada.ads - /home/comar/local/adainclude/a-finali.ads - /home/comar/local/adainclude/a-filico.ads - /home/comar/local/adainclude/a-stream.ads - /home/comar/local/adainclude/a-tags.ads - gen_list.ads - gen_list.adb - /home/comar/local/adainclude/gnat.ads - /home/comar/local/adainclude/g-io.ads - instr.ads - /home/comar/local/adainclude/system.ads - /home/comar/local/adainclude/s-exctab.ads - /home/comar/local/adainclude/s-finimp.ads - /home/comar/local/adainclude/s-finroo.ads - /home/comar/local/adainclude/s-secsta.ads - /home/comar/local/adainclude/s-stalib.ads - /home/comar/local/adainclude/s-stoele.ads - /home/comar/local/adainclude/s-stratt.ads - /home/comar/local/adainclude/s-tasoli.ads - /home/comar/local/adainclude/s-unstyp.ads - /home/comar/local/adainclude/unchconv.ads - -  - File: gnat_ug_vxw.info, Node: GNAT and Libraries, Next: Using the GNU make Utility, Prev: The GNAT Library Browser gnatls, Up: Top - - GNAT and Libraries - ****************** - - This chapter addresses some of the issues related to building and using - a library with GNAT. It also shows how the GNAT run-time library can be - recompiled. - - * Menu: - - * Creating an Ada Library:: - * Installing an Ada Library:: - * Using an Ada Library:: - * Creating an Ada Library to be Used in a Non-Ada Context:: - * Rebuilding the GNAT Run-Time Library:: - -  - File: gnat_ug_vxw.info, Node: Creating an Ada Library, Next: Installing an Ada Library, Up: GNAT and Libraries - - Creating an Ada Library - ======================= - - In the GNAT environment, a library has two components: - * Source files. - - * Compiled code and Ali files. See *Note The Ada Library Information - Files::. - - In order to use other packages *Note The GNAT Compilation Model:: - requires a certain number of sources to be available to the compiler. - The minimal set of sources required includes the specs of all the - packages that make up the visible part of the library as well as all - the sources upon which they depend. The bodies of all visible generic - units must also be provided. - - Although it is not strictly mandatory, it is recommended that all - sources needed to recompile the library be provided, so that the user - can make full use of inter-unit inlining and source-level debugging. - This can also make the situation easier for users that need to upgrade - their compilation toolchain and thus need to recompile the library from - sources. - - The compiled code can be provided in different ways. The simplest way is - to provide directly the set of objects produced by the compiler during - the compilation of the library. It is also possible to group the objects - into an archive using whatever commands are provided by the operating - system. Finally, it is also possible to create a shared library (see - option -shared in the GCC manual). - - There are various possibilities for compiling the units that make up the - library: for example with a Makefile *Note Using the GNU make Utility::, - or with a conventional script. For simple libraries, it is also - possible to create a dummy main program which depends upon all the - packages that comprise the interface of the library. This dummy main - program can then be given to gnatmake, in order to build all the - necessary objects. Here is an example of such a dummy program and the - generic commands used to build an archive or a shared library. - - with My_Lib.Service1; - with My_Lib.Service2; - with My_Lib.Service3; - procedure My_Lib_Dummy is - begin - null; - end; - - # compiling the library - $ gnatmake -c my_lib_dummy.adb - - # we don't need the dummy object itself - $ rm my_lib_dummy.o my_lib_dummy.ali - - # create an archive with the remaining objects - $ ar rc libmy_lib.a *.o - # some systems may require "ranlib" to be run as well - - # or create a shared library - $ gcc -shared -o libmy_lib.so *.o - # some systems may require the code to have been compiled with -fPIC - - When the objects are grouped in an archive or a shared library, the user - needs to specify the desired library at link time, unless a pragma - linker_options has been used in one of the sources: - pragma Linker_Options ("-lmy_lib"); - -  - File: gnat_ug_vxw.info, Node: Installing an Ada Library, Next: Using an Ada Library, Prev: Creating an Ada Library, Up: GNAT and Libraries - - Installing an Ada Library - ========================= - - In the GNAT model, installing a library consists in copying into a - specific location the files that make up this library. It is possible - to install the sources in a different directory from the other files - (ALI, objects, archives) since the source path and the object path can - easily be specified separately. - - For general purpose libraries, it is possible for the system - administrator to put those libraries in the default compiler paths. To - achieve this, he must specify their location in the configuration files - "ada_source_path" and "ada_object_path" that must be located in the GNAT - installation tree at the same place as the gcc spec file. The location - of the gcc spec file can be determined as follows: - $ gcc -v - - The configuration files mentioned above have simple format: each line - in them must contain one unique directory name. Those names are added - to the corresponding path in their order of appearance in the file. The - names can be either absolute or relative, in the latter case, they are - relative to where theses files are located. - - "ada_source_path" and "ada_object_path" might actually not be present - in a GNAT installation, in which case, GNAT will look for its run-time - library in the directories "adainclude" for the sources and "adalib" - for the objects and ALI files. When the files exist, the compiler does - not look in "adainclude" and "adalib" at all, and thus the - "ada_source_path" file must contain the location for the GNAT run-time - sources (which can simply be "adainclude"). In the same way, the - "ada_object_path" file must contain the location for the GNAT run-time - objects (which can simply be "adalib"). - - You can also specify a new default path to the runtime library at - compilation time with the switch "-RTS=RTS-PATH". You can easily choose - and change the runtime you want your program to be compiled with. This - switch is recognized by gcc, gnatmake, gnatbind, gnatls, gnatfind and - gnatxref. - - It is possible to install a library before or after the standard GNAT - library, by reordering the lines in the configuration files. In - general, a library must be installed before the GNAT library if it - redefines any part of it. - -  - File: gnat_ug_vxw.info, Node: Using an Ada Library, Next: Creating an Ada Library to be Used in a Non-Ada Context, Prev: Installing an Ada Library, Up: GNAT and Libraries - - Using an Ada Library - ==================== - - In order to use a Ada library, you need to make sure that this library - is on both your source and object path *Note Search Paths and the - Run-Time Library (RTL):: and *Note Search Paths for gnatbind::. For - instance, you can use the library "mylib" installed in "/dir/my_lib_src" - and "/dir/my_lib_obj" with the following commands: - - $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \ - -largs -lmy_lib - - This can be simplified down to the following: - $ gnatmake my_appl - when the following conditions are met: - * "/dir/my_lib_src" has been added by the user to the environment - variable "ADA_INCLUDE_PATH", or by the administrator to the file - "ada_source_path" - - * "/dir/my_lib_obj" has been added by the user to the environment - variable "ADA_OBJECTS_PATH", or by the administrator to the file - "ada_object_path" - - * a pragma linker_options, as mentioned in *Note Creating an Ada - Library:: as been added to the sources. - -  - File: gnat_ug_vxw.info, Node: Creating an Ada Library to be Used in a Non-Ada Context, Next: Rebuilding the GNAT Run-Time Library, Prev: Using an Ada Library, Up: GNAT and Libraries - - Creating an Ada Library to be Used in a Non-Ada Context - ======================================================= - - The previous sections detailed how to create and install a library that - was usable from an Ada main program. Using this library in a non-Ada - context is not possible, because the elaboration of the library is - automatically done as part of the main program elaboration. - - GNAT also provides the ability to build libraries that can be used - both in an Ada and non-Ada context. This section describes how to - build such a library, and then how to use it from a C program. The - method for interfacing with the library from other languages such as - Fortran for instance remains the same. - - Creating the Library - -------------------- - - * Identify the units representing the interface of the library. - - Here is an example of simple library interface: - - package Interface is - - procedure Do_Something; - - procedure Do_Something_Else; - - end Interface; - - * Use `pragma Export' or `pragma Convention' for the exported - entities. - - Our package `Interface' is then updated as follow: - package Interface is - - procedure Do_Something; - pragma Export (C, Do_Something, "do_something"); - - procedure Do_Something_Else; - pragma Export (C, Do_Something_Else, "do_something_else"); - - end Interface; - - * Compile all the units composing the library. - - * Bind the library objects. - - This step is performed by invoking gnatbind with the `-L' - switch. `gnatbind' will then generate the library elaboration - procedure (named `init') and the run-time finalization - procedure (named `final'). - - # generate the binder file in Ada - $ gnatbind -Lmylib interface - - # generate the binder file in C - $ gnatbind -C -Lmylib interface - - * Compile the files generated by the binder - - $ gcc -c b~interface.adb - - * Create the library; - - The procedure is identical to the procedure explained in *Note - Creating an Ada Library::, except that `b~interface.o' needs to be - added to the list of objects. - - # create an archive file - $ ar cr libmylib.a b~interface.o - - # create a shared library - $ gcc -shared -o libmylib.so b~interface.o - - * Provide a "foreign" view of the library interface; - - The example below shows the content of `mylib_interface.h' (note - that there is no rule for the naming of this file, any name can be - used) - /* the library elaboration procedure */ - extern void mylibinit (void); - - /* the library finalization procedure */ - extern void mylibfinal (void); - - /* the interface exported by the library */ - extern void do_something (void); - extern void do_something_else (void); - - Using the Library - ----------------- - - Libraries built as explained above can be used from any program, - provided that the elaboration procedures (named `mylibinit' in the - previous example) are called before the library services are used. Any - number of libraries can be used simultaneously, as long as the - elaboration procedure of each library is called. - - Below is an example of C program that uses our `mylib' library. - - #include "mylib_interface.h" - - int - main (void) - { - /* First, elaborate the library before using it */ - mylibinit (); - - /* Main program, using the library exported entities */ - do_something (); - do_something_else (); - - /* Library finalization at the end of the program */ - mylibfinal (); - return 0; - } - - Note that this same library can be used from an equivalent Ada main - program. In addition, if the libraries are installed as detailed in - *Note Installing an Ada Library::, it is not necessary to invoke the - library elaboration and finalization routines. The binder will ensure - that this is done as part of the main program elaboration and - finalization phases. - - The Finalization Phase - ---------------------- - - Invoking any library finalization procedure generated by `gnatbind' - shuts down the Ada run time permanently. Consequently, the finalization - of all Ada libraries must be performed at the end of the program. No - call to these libraries nor the Ada run time should be made past the - finalization phase. - - Restrictions in Libraries - ------------------------- - - The pragmas listed below should be used with caution inside libraries, - as they can create incompatibilities with other Ada libraries: - * pragma `Locking_Policy' - - * pragma `Queuing_Policy' - - * pragma `Task_Dispatching_Policy' - - * pragma `Unreserve_All_Interrupts' - When using a library that contains such pragmas, the user must make - sure that all libraries use the same pragmas with the same values. - Otherwise, a `Program_Error' will be raised during the elaboration of - the conflicting libraries. The usage of these pragmas and its - consequences for the user should therefore be well documented. - - Similarly, the traceback in exception occurrences mechanism should be - enabled or disabled in a consistent manner across all libraries. - Otherwise, a Program_Error will be raised during the elaboration of the - conflicting libraries. - - If the `'Version' and `'Body_Version' attributes are used inside a - library, then it is necessary to perform a `gnatbind' step that - mentions all ali files in all libraries, so that version identifiers - can be properly computed. In practice these attributes are rarely - used, so this is unlikely to be a consideration. - -  - File: gnat_ug_vxw.info, Node: Rebuilding the GNAT Run-Time Library, Prev: Creating an Ada Library to be Used in a Non-Ada Context, Up: GNAT and Libraries - - Rebuilding the GNAT Run-Time Library - ==================================== - - It may be useful to recompile the GNAT library in various contexts, the - most important one being the use of partition-wide configuration pragmas - such as Normalize_Scalar. A special Makefile called `Makefile.adalib' - is provided to that effect and can be found in the directory containing - the GNAT library. The location of this directory depends on the way the - GNAT environment has been installed and can be determined by means of - the command: - - $ gnatls -v - - The last entry in the object search path usually contains the gnat - library. This Makefile contains its own documentation and in particular - the set of instructions needed to rebuild a new library and to use it. - -  - File: gnat_ug_vxw.info, Node: Using the GNU make Utility, Next: Finding Memory Problems with GNAT Debug Pool, Prev: GNAT and Libraries, Up: Top - - Using the GNU `make' Utility - **************************** - - This chapter offers some examples of makefiles that solve specific - problems. It does not explain how to write a makefile (see the GNU make - documentation), nor does it try to replace the `gnatmake' utility - (*note The GNAT Make Program gnatmake::). - - All the examples in this section are specific to the GNU version of - make. Although `make' is a standard utility, and the basic language is - the same, these examples use some advanced features found only in `GNU - make'. - - * Menu: - - * Using gnatmake in a Makefile:: - * Automatically Creating a List of Directories:: - * Generating the Command Line Switches:: - * Overcoming Command Line Length Limits:: - -  - File: gnat_ug_vxw.info, Node: Using gnatmake in a Makefile, Next: Automatically Creating a List of Directories, Up: Using the GNU make Utility - - Using gnatmake in a Makefile - ============================ - - Complex project organizations can be handled in a very powerful way by - using GNU make combined with gnatmake. For instance, here is a Makefile - which allows you to build each subsystem of a big project into a - separate shared library. Such a makefile allows you to significantly - reduce the link time of very big applications while maintaining full - coherence at each step of the build process. - - The list of dependencies are handled automatically by `gnatmake'. - The Makefile is simply used to call gnatmake in each of the appropriate - directories. - - Note that you should also read the example on how to automatically - create the list of directories (*note Automatically Creating a List of - Directories::) which might help you in case your project has a lot of - subdirectories. - - ## This Makefile is intended to be used with the following directory - ## configuration: - ## - The sources are split into a series of csc (computer software components) - ## Each of these csc is put in its own directory. - ## Their name are referenced by the directory names. - ## They will be compiled into shared library (although this would also work - ## with static libraries - ## - The main program (and possibly other packages that do not belong to any - ## csc is put in the top level directory (where the Makefile is). - ## toplevel_dir __ first_csc (sources) __ lib (will contain the library) - ## \_ second_csc (sources) __ lib (will contain the library) - ## \_ ... - ## Although this Makefile is build for shared library, it is easy to modify - ## to build partial link objects instead (modify the lines with -shared and - ## gnatlink below) - ## - ## With this makefile, you can change any file in the system or add any new - ## file, and everything will be recompiled correctly (only the relevant shared - ## objects will be recompiled, and the main program will be re-linked). - - # The list of computer software component for your project. This might be - # generated automatically. - CSC_LIST=aa bb cc - - # Name of the main program (no extension) - MAIN=main - - # If we need to build objects with -fPIC, uncomment the following line - #NEED_FPIC=-fPIC - - # The following variable should give the directory containing libgnat.so - # You can get this directory through 'gnatls -v'. This is usually the last - # directory in the Object_Path. - GLIB=... - - # The directories for the libraries - # (This macro expands the list of CSC to the list of shared libraries, you - # could simply use the expanded form : - # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so - LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so} - - ${MAIN}: objects ${LIB_DIR} - gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared - gnatlink ${MAIN} ${CSC_LIST:%=-l%} - - objects:: - # recompile the sources - gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%} - - # Note: In a future version of GNAT, the following commands will be simplified - # by a new tool, gnatmlib - ${LIB_DIR}: - mkdir -p ${dir $@ } - cd ${dir $@ }; gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat - cd ${dir $@ }; cp -f ../*.ali . - - # The dependencies for the modules - # Note that we have to force the expansion of *.o, since in some cases make won't - # be able to do it itself. - aa/lib/libaa.so: ${wildcard aa/*.o} - bb/lib/libbb.so: ${wildcard bb/*.o} - cc/lib/libcc.so: ${wildcard cc/*.o} - - # Make sure all of the shared libraries are in the path before starting the - # program - run:: - LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN} - - clean:: - ${RM} -rf ${CSC_LIST:%=%/lib} - ${RM} ${CSC_LIST:%=%/*.ali} - ${RM} ${CSC_LIST:%=%/*.o} - ${RM} *.o *.ali ${MAIN} - -  - File: gnat_ug_vxw.info, Node: Automatically Creating a List of Directories, Next: Generating the Command Line Switches, Prev: Using gnatmake in a Makefile, Up: Using the GNU make Utility - - Automatically Creating a List of Directories - ============================================ - - In most makefiles, you will have to specify a list of directories, and - store it in a variable. For small projects, it is often easier to - specify each of them by hand, since you then have full control over what - is the proper order for these directories, which ones should be - included... - - However, in larger projects, which might involve hundreds of - subdirectories, it might be more convenient to generate this list - automatically. - - The example below presents two methods. The first one, although less - general, gives you more control over the list. It involves wildcard - characters, that are automatically expanded by `make'. Its shortcoming - is that you need to explicitly specify some of the organization of your - project, such as for instance the directory tree depth, whether some - directories are found in a separate tree,... - - The second method is the most general one. It requires an external - program, called `find', which is standard on all Unix systems. All the - directories found under a given root directory will be added to the - list. - - # The examples below are based on the following directory hierarchy: - # All the directories can contain any number of files - # ROOT_DIRECTORY -> a -> aa -> aaa - # -> ab - # -> ac - # -> b -> ba -> baa - # -> bb - # -> bc - # This Makefile creates a variable called DIRS, that can be reused any time - # you need this list (see the other examples in this section) - - # The root of your project's directory hierarchy - ROOT_DIRECTORY=. - - #### - # First method: specify explicitly the list of directories - # This allows you to specify any subset of all the directories you need. - #### - - DIRS := a/aa/ a/ab/ b/ba/ - - #### - # Second method: use wildcards - # Note that the argument(s) to wildcard below should end with a '/'. - # Since wildcards also return file names, we have to filter them out - # to avoid duplicate directory names. - # We thus use make's `dir' and `sort' functions. - # It sets DIRs to the following value (note that the directories aaa and baa - # are not given, unless you change the arguments to wildcard). - # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ - #### - - DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/ ${ROOT_DIRECTORY}/*/*/}}} - - #### - # Third method: use an external program - # This command is much faster if run on local disks, avoiding NFS slowdowns. - # This is the most complete command: it sets DIRs to the following value: - # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc - #### - - DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print} - -  - File: gnat_ug_vxw.info, Node: Generating the Command Line Switches, Next: Overcoming Command Line Length Limits, Prev: Automatically Creating a List of Directories, Up: Using the GNU make Utility - - Generating the Command Line Switches - ==================================== - - Once you have created the list of directories as explained in the - previous section (*note Automatically Creating a List of Directories::), - you can easily generate the command line arguments to pass to gnatmake. - - For the sake of completeness, this example assumes that the source - path is not the same as the object path, and that you have two separate - lists of directories. - - # see "Automatically creating a list of directories" to create - # these variables - SOURCE_DIRS= - OBJECT_DIRS= - - GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}} - GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}} - - all: - gnatmake ${GNATMAKE_SWITCHES} main_unit - -  - File: gnat_ug_vxw.info, Node: Overcoming Command Line Length Limits, Prev: Generating the Command Line Switches, Up: Using the GNU make Utility - - Overcoming Command Line Length Limits - ===================================== - - One problem that might be encountered on big projects is that many - operating systems limit the length of the command line. It is thus hard - to give gnatmake the list of source and object directories. - - This example shows how you can set up environment variables, which - will make `gnatmake' behave exactly as if the directories had been - specified on the command line, but have a much higher length limit (or - even none on most systems). - - It assumes that you have created a list of directories in your - Makefile, using one of the methods presented in *Note Automatically - Creating a List of Directories::. For the sake of completeness, we - assume that the object path (where the ALI files are found) is - different from the sources patch. - - Note a small trick in the Makefile below: for efficiency reasons, we - create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are - expanded immediately by `make'. This way we overcome the standard make - behavior which is to expand the variables only when they are actually - used. - - # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH. - # This is the same thing as putting the -I arguments on the command line. - # (the equivalent of using -aI on the command line would be to define - # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECT_PATH). - # You can of course have different values for these variables. - # - # Note also that we need to keep the previous values of these variables, since - # they might have been set before running 'make' to specify where the GNAT - # library is installed. - - # see "Automatically creating a list of directories" to create these - # variables - SOURCE_DIRS= - OBJECT_DIRS= - - empty:= - space:=${empty} ${empty} - SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}} - OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}} - ADA_INCLUDE_PATH += ${SOURCE_LIST} - ADA_OBJECT_PATH += ${OBJECT_LIST} - export ADA_INCLUDE_PATH - export ADA_OBJECT_PATH - - all: - gnatmake main_unit - -  - File: gnat_ug_vxw.info, Node: Finding Memory Problems with GNAT Debug Pool, Next: Creating Sample Bodies Using gnatstub, Prev: Using the GNU make Utility, Up: Top - - Finding Memory Problems with GNAT Debug Pool - ******************************************** - - The use of unchecked deallocation and unchecked conversion can easily - lead to incorrect memory references. The problems generated by such - references are usually difficult to tackle because the symptoms can be - very remote from the origin of the problem. In such cases, it is very - helpful to detect the problem as early as possible. This is the purpose - of the Storage Pool provided by `GNAT.Debug_Pools'. - - In order to use the GNAT specific debugging pool, the user must - associate a debug pool object with each of the access types that may be - related to suspected memory problems. See Ada Reference Manual 13.11. - type Ptr is access Some_Type; - Pool : GNAT.Debug_Pools.Debug_Pool; - for Ptr'Storage_Pool use Pool; - - `GNAT.Debug_Pools' is derived from of a GNAT-specific kind of pool: - the Checked_Pool. Such pools, like standard Ada storage pools, allow - the user to redefine allocation and deallocation strategies. They also - provide a checkpoint for each dereference, through the use of the - primitive operation `Dereference' which is implicitly called at each - dereference of an access value. - - Once an access type has been associated with a debug pool, - operations on values of the type may raise four distinct exceptions, - which correspond to four potential kinds of memory corruption: - * `GNAT.Debug_Pools.Accessing_Not_Allocated_Storage' - - * `GNAT.Debug_Pools.Accessing_Deallocated_Storage' - - * `GNAT.Debug_Pools.Freeing_Not_Allocated_Storage' - - * `GNAT.Debug_Pools.Freeing_Deallocated_Storage ' - - For types associated with a Debug_Pool, dynamic allocation is performed - using the standard GNAT allocation routine. References to all allocated - chunks of memory are kept in an internal dictionary. The deallocation - strategy consists in not releasing the memory to the underlying system - but rather to fill it with a memory pattern easily recognizable during - debugging sessions: The memory pattern is the old IBM hexadecimal - convention: 16#DEADBEEF#. Upon each dereference, a check is made that - the access value denotes a properly allocated memory location. Here is - a complete example of use of `Debug_Pools', that includes typical - instances of memory corruption: - with Gnat.Io; use Gnat.Io; - with Unchecked_Deallocation; - with Unchecked_Conversion; - with GNAT.Debug_Pools; - with System.Storage_Elements; - with Ada.Exceptions; use Ada.Exceptions; - procedure Debug_Pool_Test is - - type T is access Integer; - type U is access all T; - - P : GNAT.Debug_Pools.Debug_Pool; - for T'Storage_Pool use P; - - procedure Free is new Unchecked_Deallocation (Integer, T); - function UC is new Unchecked_Conversion (U, T); - A, B : aliased T; - - procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); - - begin - Info (P); - A := new Integer; - B := new Integer; - B := A; - Info (P); - Free (A); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - B := UC(A'Access); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - Info (P); - end Debug_Pool_Test; - - The debug pool mechanism provides the following precise diagnostics on - the execution of this erroneous program: - Debug Pool info: - Total allocated bytes : 0 - Total deallocated bytes : 0 - Current Water Mark: 0 - High Water Mark: 0 - - Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 0 - Current Water Mark: 8 - High Water Mark: 8 - - raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE - Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 4 - Current Water Mark: 4 - High Water Mark: 8 - -  - File: gnat_ug_vxw.info, Node: Creating Sample Bodies Using gnatstub, Next: Reducing the Size of Ada Executables with gnatelim, Prev: Finding Memory Problems with GNAT Debug Pool, Up: Top - - Creating Sample Bodies Using `gnatstub' - *************************************** - - `gnatstub' creates body stubs, that is, empty but compilable bodies for - library unit declarations. - - To create a body stub, `gnatstub' has to compile the library unit - declaration. Therefore, bodies can be created only for legal library - units. Moreover, if a library unit depends semantically upon units - located outside the current directory, you have to provide the source - search path when calling `gnatstub', see the description of `gnatstub' - switches below. - - * Menu: - - * Running gnatstub:: - * Switches for gnatstub:: - -  - File: gnat_ug_vxw.info, Node: Running gnatstub, Next: Switches for gnatstub, Up: Creating Sample Bodies Using gnatstub - - Running `gnatstub' - ================== - - `gnatstub' has the command-line interface of the form - - $ gnatstub [switches] filename [directory] - - where - `filename' - is the name of the source file that contains a library unit - declaration for which a body must be created. This name should - follow the GNAT file name conventions. No crunching is allowed for - this file name. The file name may contain the path information. - - `directory' - indicates the directory to place a body stub (default is the - current directory) - - `switches' - is an optional sequence of switches as described in the next - section - -  - File: gnat_ug_vxw.info, Node: Switches for gnatstub, Prev: Running gnatstub, Up: Creating Sample Bodies Using gnatstub - - Switches for `gnatstub' - ======================= - - `-f' - If the destination directory already contains a file with a name - of the body file for the argument spec file, replace it with the - generated body stub. - - `-hs' - Put the comment header (i.e. all the comments preceding the - compilation unit) from the source of the library unit declaration - into the body stub. - - `-hg' - Put a sample comment header into the body stub. - - `-IDIR' - `-I-' - These switches have the same meaning as in calls to gcc. They - define the source search path in the call to gcc issued by - `gnatstub' to compile an argument source file. - - `-iN' - (N is a decimal natural number). Set the indentation level in the - generated body sample to n, '-i0' means "no indentation", the - default indentation is 3. - - `-k' - Do not remove the tree file (i.e. the snapshot of the compiler - internal structures used by `gnatstub') after creating the body - stub. - - `-lN' - (N is a decimal positive number) Set the maximum line length in the - body stub to n, the default is 78. - - `-q' - Quiet mode: do not generate a confirmation when a body is - successfully created or a message when a body is not required for - an argument unit. - - `-r' - Reuse the tree file (if it exists) instead of creating it: instead - of creating the tree file for the library unit declaration, - gnatstub tries to find it in the current directory and use it for - creating a body. If the tree file is not found, no body is - created. `-r' also implies `-k', whether or not `-k' is set - explicitly. - - `-t' - Overwrite the existing tree file: if the current directory already - contains the file which, according to the GNAT file name rules - should be considered as a tree file for the argument source file, - gnatstub will refuse to create the tree file needed to create a - body sampler, unless `-t' option is set - - `-v' - Verbose mode: generate version information. - -  - File: gnat_ug_vxw.info, Node: Reducing the Size of Ada Executables with gnatelim, Next: Other Utility Programs, Prev: Creating Sample Bodies Using gnatstub, Up: Top - - Reducing the Size of Ada Executables with `gnatelim' - **************************************************** - - * Menu: - - * About gnatelim:: - * Eliminate Pragma:: - * Tree Files:: - * Preparing Tree and Bind Files for gnatelim:: - * Running gnatelim:: - * Correcting the List of Eliminate Pragmas:: - * Making Your Executables Smaller:: - * Summary of the gnatelim Usage Cycle:: - -  - File: gnat_ug_vxw.info, Node: About gnatelim, Next: Eliminate Pragma, Up: Reducing the Size of Ada Executables with gnatelim - - About `gnatelim' - ================ - - When a program shares a set of Ada packages with other programs, it may - happen that this program uses only a fraction of the subprograms - defined in these packages. The code created for these unused - subprograms increases the size of the executable. - - `gnatelim' tracks unused subprograms in an Ada program and outputs a - list of GNAT-specific `Eliminate' pragmas (see next section) marking - all the subprograms that are declared but never called. By placing the - list of `Eliminate' pragmas in the GNAT configuration file `gnat.adc' - and recompiling your program, you may decrease the size of its - executable, because the compiler will not generate the code for - 'eliminated' subprograms. - - `gnatelim' needs as its input data a set of tree files (see *Note - Tree Files::) representing all the components of a program to process - and a bind file for a main subprogram (see *Note Preparing Tree and - Bind Files for gnatelim::). - -  - File: gnat_ug_vxw.info, Node: Eliminate Pragma, Next: Tree Files, Prev: About gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - `Eliminate' Pragma - ================== - - The simplified syntax of the Eliminate pragma used by `gnatelim' is: - - pragma Eliminate (Library_Unit_Name, Subprogram_Name); - - where - `Library_Unit_Name' - full expanded Ada name of a library unit - - `Subprogram_Name' - a simple or expanded name of a subprogram declared within this - compilation unit - - The effect of an `Eliminate' pragma placed in the GNAT configuration - file `gnat.adc' is: - - * If the subprogram `Subprogram_Name' is declared within the library - unit `Library_Unit_Name', the compiler will not generate code for - this subprogram. This applies to all overloaded subprograms denoted - by `Subprogram_Name'. - - * If a subprogram marked by the pragma `Eliminate' is used (called) - in a program, the compiler will produce an error message in the - place where it is called. - -  - File: gnat_ug_vxw.info, Node: Tree Files, Next: Preparing Tree and Bind Files for gnatelim, Prev: Eliminate Pragma, Up: Reducing the Size of Ada Executables with gnatelim - - Tree Files - ========== - - A tree file stores a snapshot of the compiler internal data structures - at the very end of a successful compilation. It contains all the - syntactic and semantic information for the compiled unit and all the - units upon which it depends semantically. To use tools that make use - of tree files, you need to first produce the right set of tree files. - - GNAT produces correct tree files when -gnatt -gnatc options are set - in a gcc call. The tree files have an .adt extension. Therefore, to - produce a tree file for the compilation unit contained in a file named - `foo.adb', you must use the command - - $ gcc -c -gnatc -gnatt foo.adb - - and you will get the tree file `foo.adt'. compilation. - -  - File: gnat_ug_vxw.info, Node: Preparing Tree and Bind Files for gnatelim, Next: Running gnatelim, Prev: Tree Files, Up: Reducing the Size of Ada Executables with gnatelim - - Preparing Tree and Bind Files for `gnatelim' - ============================================ - - A set of tree files covering the program to be analyzed with `gnatelim' - and the bind file for the main subprogram does not have to be in the - current directory. '-T' gnatelim option may be used to provide the - search path for tree files, and '-b' option may be used to point to the - bind file to process (see *Note Running gnatelim::) - - If you do not have the appropriate set of tree files and the right - bind file, you may create them in the current directory using the - following procedure. - - Let `Main_Prog' be the name of a main subprogram, and suppose this - subprogram is in a file named `main_prog.adb'. - - To create a bind file for `gnatelim', run `gnatbind' for the main - subprogram. `gnatelim' can work with both Ada and C bind files; when - both are present, it uses the Ada bind file. The following commands - will build the program and create the bind file: - - $ gnatmake -c Main_Prog - $ gnatbind main_prog - - To create a minimal set of tree files covering the whole program, call - `gnatmake' for this program as follows: - - $ gnatmake -f -c -gnatc -gnatt Main_Prog - - The `-c' gnatmake option turns off the bind and link steps, that are - useless anyway because the sources are compiled with `-gnatc' option - which turns off code generation. - - The `-f' gnatmake option forces recompilation of all the needed - sources. - - This sequence of actions will create all the data needed by - `gnatelim' from scratch and therefore guarantee its consistency. If you - would like to use some existing set of files as `gnatelim' output, you - must make sure that the set of files is complete and consistent. You - can use the `-m' switch to check if there are missed tree files - - Note, that `gnatelim' needs neither object nor ALI files. - -  - File: gnat_ug_vxw.info, Node: Running gnatelim, Next: Correcting the List of Eliminate Pragmas, Prev: Preparing Tree and Bind Files for gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - Running `gnatelim' - ================== - - `gnatelim' has the following command-line interface: - - $ gnatelim [options] name - - `name' should be a full expanded Ada name of a main subprogram of a - program (partition). - - `gnatelim' options: - - `-q' - Quiet mode: by default `gnatelim' generates to the standard error - stream a trace of the source file names of the compilation units - being processed. This option turns this trace off. - - `-v' - Verbose mode: `gnatelim' version information is printed as Ada - comments to the standard output stream. - - `-a' - Also look for subprograms from the GNAT run time that can be - eliminated. - - `-m' - Check if any tree files are missing for an accurate result. - - `-TDIR' - When looking for tree files also look in directory DIR - - `-bBIND_FILE' - Specifies BIND_FILE as the bind file to process. If not set, the - name of the bind file is computed from the full expanded Ada name - of a main subprogram. - - `-dX' - Activate internal debugging switches. X is a letter or digit, or - string of letters or digits, which specifies the type of debugging - mode desired. Normally these are used only for internal - development or system debugging purposes. You can find full - documentation for these switches in the body of the - `Gnatelim.Options' unit in the compiler source file - `gnatelim-options.adb'. - - `gnatelim' sends its output to the standard output stream, and all the - tracing and debug information is sent to the standard error stream. In - order to produce a proper GNAT configuration file `gnat.adc', - redirection must be used: - - $ gnatelim Main_Prog > gnat.adc - - or - - $ gnatelim Main_Prog >> gnat.adc - - In order to append the `gnatelim' output to the existing contents of - `gnat.adc'. - -  - File: gnat_ug_vxw.info, Node: Correcting the List of Eliminate Pragmas, Next: Making Your Executables Smaller, Prev: Running gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - Correcting the List of Eliminate Pragmas - ======================================== - - In some rare cases it may happen that `gnatelim' will try to eliminate - subprograms which are actually called in the program. In this case, the - compiler will generate an error message of the form: - - file.adb:106:07: cannot call eliminated subprogram "My_Prog" - - You will need to manually remove the wrong `Eliminate' pragmas from the - `gnat.adc' file. It is advised that you recompile your program from - scratch after that because you need a consistent `gnat.adc' file during - the entire compilation. - -  - File: gnat_ug_vxw.info, Node: Making Your Executables Smaller, Next: Summary of the gnatelim Usage Cycle, Prev: Correcting the List of Eliminate Pragmas, Up: Reducing the Size of Ada Executables with gnatelim - - Making Your Executables Smaller - =============================== - - In order to get a smaller executable for your program you now have to - recompile the program completely with the new `gnat.adc' file created - by `gnatelim' in your current directory: - - $ gnatmake -f Main_Prog - - (you will need `-f' option for gnatmake to recompile everything with - the set of pragmas `Eliminate' you have obtained with `gnatelim'). - - Be aware that the set of `Eliminate' pragmas is specific to each - program. It is not recommended to merge sets of `Eliminate' pragmas - created for different programs in one `gnat.adc' file. - -  - File: gnat_ug_vxw.info, Node: Summary of the gnatelim Usage Cycle, Prev: Making Your Executables Smaller, Up: Reducing the Size of Ada Executables with gnatelim - - Summary of the gnatelim Usage Cycle - =================================== - - Here is a quick summary of the steps to be taken in order to reduce the - size of your executables with `gnatelim'. You may use other GNAT - options to control the optimization level, to produce the debugging - information, to set search path, etc. - - 1. Produce a bind file and a set of tree files - - $ gnatmake -c Main_Prog - $ gnatbind main_prog - $ gnatmake -f -c -gnatc -gnatt Main_Prog - - 2. Generate a list of `Eliminate' pragmas - $ gnatelim Main_Prog >[>] gnat.adc - - 3. Recompile the application - - $ gnatmake -f Main_Prog - - -  - File: gnat_ug_vxw.info, Node: Other Utility Programs, Next: Running and Debugging Ada Programs, Prev: Reducing the Size of Ada Executables with gnatelim, Up: Top - - Other Utility Programs - ********************** - - This chapter discusses some other utility programs available in the Ada - environment. - - * Menu: - - * Using Other Utility Programs with GNAT:: - * The gnatpsta Utility Program:: - * The External Symbol Naming Scheme of GNAT:: - * Ada Mode for Glide:: - * Converting Ada Files to html with gnathtml:: - * Installing gnathtml:: - -  - File: gnat_ug_vxw.info, Node: Using Other Utility Programs with GNAT, Next: The gnatpsta Utility Program, Up: Other Utility Programs - - Using Other Utility Programs with GNAT - ====================================== - - The object files generated by GNAT are in standard system format and in - particular the debugging information uses this format. This means - programs generated by GNAT can be used with existing utilities that - depend on these formats. - - In general, any utility program that works with C will also often - work with Ada programs generated by GNAT. This includes software - utilities such as gprof (a profiling program), `gdb' (the FSF - debugger), and utilities such as Purify. - -  - File: gnat_ug_vxw.info, Node: The gnatpsta Utility Program, Next: The External Symbol Naming Scheme of GNAT, Prev: Using Other Utility Programs with GNAT, Up: Other Utility Programs - - The `gnatpsta' Utility Program - ============================== - - Many of the definitions in package Standard are - implementation-dependent. However, the source of this package does not - exist as an Ada source file, so these values cannot be determined by - inspecting the source. They can be determined by examining in detail - the coding of `cstand.adb' which creates the image of Standard in the - compiler, but this is awkward and requires a great deal of internal - knowledge about the system. - - The `gnatpsta' utility is designed to deal with this situation. It - is an Ada program that dynamically determines the values of all the - relevant parameters in Standard, and prints them out in the form of an - Ada source listing for Standard, displaying all the values of interest. - This output is generated to `stdout'. - - To determine the value of any parameter in package Standard, simply - run `gnatpsta' with no qualifiers or arguments, and examine the output. - This is preferable to consulting documentation, because you know that - the values you are getting are the actual ones provided by the - executing system. - -  - File: gnat_ug_vxw.info, Node: The External Symbol Naming Scheme of GNAT, Next: Ada Mode for Glide, Prev: The gnatpsta Utility Program, Up: Other Utility Programs - - The External Symbol Naming Scheme of GNAT - ========================================= - - In order to interpret the output from GNAT, when using tools that are - originally intended for use with other languages, it is useful to - understand the conventions used to generate link names from the Ada - entity names. - - All link names are in all lowercase letters. With the exception of - library procedure names, the mechanism used is simply to use the full - expanded Ada name with dots replaced by double underscores. For - example, suppose we have the following package spec: - - package QRS is - MN : Integer; - end QRS; - - The variable `MN' has a full expanded Ada name of `QRS.MN', so the - corresponding link name is `qrs__mn'. Of course if a `pragma Export' - is used this may be overridden: - - package Exports is - Var1 : Integer; - pragma Export (Var1, C, External_Name => "var1_name"); - Var2 : Integer; - pragma Export (Var2, C, Link_Name => "var2_link_name"); - end Exports; - - In this case, the link name for VAR1 is whatever link name the C - compiler would assign for the C function VAR1_NAME. This typically - would be either VAR1_NAME or _VAR1_NAME, depending on operating system - conventions, but other possibilities exist. The link name for VAR2 is - VAR2_LINK_NAME, and this is not operating system dependent. - - One exception occurs for library level procedures. A potential - ambiguity arises between the required name `_main' for the C main - program, and the name we would otherwise assign to an Ada library level - procedure called `Main' (which might well not be the main program). - - To avoid this ambiguity, we attach the prefix `_ada_' to such names. - So if we have a library level procedure such as - - procedure Hello (S : String); - - the external name of this procedure will be _ADA_HELLO. - -  - File: gnat_ug_vxw.info, Node: Ada Mode for Glide, Next: Converting Ada Files to html with gnathtml, Prev: The External Symbol Naming Scheme of GNAT, Up: Other Utility Programs - - Ada Mode for `Glide' - ==================== - - The Glide mode for programming in Ada (both, Ada83 and Ada95) helps the - user in understanding existing code and facilitates writing new code. It - furthermore provides some utility functions for easier integration of - standard Emacs features when programming in Ada. - - General Features: - ----------------- - - * Full Integrated Development Environment : - - * support of 'project files' for the configuration (directories, - compilation options,...) - - * compiling and stepping through error messages. - - * running and debugging your applications within Glide. - - * easy to use for beginners by pull-down menus, - - * user configurable by many user-option variables. - - Ada Mode Features That Help Understanding Code: - ----------------------------------------------- - - * functions for easy and quick stepping through Ada code, - - * getting cross reference information for identifiers (e.g. find the - defining place by a keystroke), - - * displaying an index menu of types and subprograms and move point to - the chosen one, - - * automatic color highlighting of the various entities in Ada code. - - Glide Support for Writing Ada Code: - ----------------------------------- - - * switching between spec and body files with possible autogeneration - of body files, - - * automatic formating of subprograms parameter lists. - - * automatic smart indentation according to Ada syntax, - - * automatic completion of identifiers, - - * automatic casing of identifiers, keywords, and attributes, - - * insertion of statement templates, - - * filling comment paragraphs like filling normal text, - - For more information, please refer to the online Glide documentation - available in the Glide -> Help Menu. - -  - File: gnat_ug_vxw.info, Node: Converting Ada Files to html with gnathtml, Next: Installing gnathtml, Prev: Ada Mode for Glide, Up: Other Utility Programs - - Converting Ada Files to html with `gnathtml' - ============================================ - - This `Perl' script allows Ada source files to be browsed using standard - Web browsers. For installation procedure, see the section *Note - Installing gnathtml::. - - Ada reserved keywords are highlighted in a bold font and Ada - comments in a blue font. Unless your program was compiled with the gcc - `-gnatx' switch to suppress the generation of cross-referencing - information, user defined variables and types will appear in a - different color; you will be able to click on any identifier and go to - its declaration. - - The command line is as follow: - $ perl gnathtml.pl [switches] ada-files - - You can pass it as many Ada files as you want. `gnathtml' will - generate an html file for every ada file, and a global file called - `index.htm'. This file is an index of every identifier defined in the - files. - - The available switches are the following ones : - - `-83' - Only the subset on the Ada 83 keywords will be highlighted, not - the full Ada 95 keywords set. - - `-cc COLOR' - This option allows you to change the color used for comments. The - default value is green. The color argument can be any name - accepted by html. - - `-d' - If the ada files depend on some other files (using for instance the - `with' command, the latter will also be converted to html. Only - the files in the user project will be converted to html, not the - files in the run-time library itself. - - `-D' - This command is the same as -d above, but `gnathtml' will also look - for files in the run-time library, and generate html files for - them. - - `-f' - By default, gnathtml will generate html links only for global - entities ('with'ed units, global variables and types,...). If you - specify the `-f' on the command line, then links will be generated - for local entities too. - - `-l NUMBER' - If this switch is provided and NUMBER is not 0, then `gnathtml' - will number the html files every NUMBER line. - - `-I DIR' - Specify a directory to search for library files (`.ali' files) and - source files. You can provide several -I switches on the command - line, and the directories will be parsed in the order of the - command line. - - `-o DIR' - Specify the output directory for html files. By default, gnathtml - will saved the generated html files in a subdirectory named - `html/'. - - `-p FILE' - If you are using Emacs and the most recent Emacs Ada mode, which - provides a full Integrated Development Environment for compiling, - checking, running and debugging applications, you may be using - `.adp' files to give the directories where Emacs can find sources - and object files. - - Using this switch, you can tell gnathtml to use these files. This - allows you to get an html version of your application, even if it - is spread over multiple directories. - - `-sc COLOR' - This option allows you to change the color used for symbol - definitions. The default value is red. The color argument can be - any name accepted by html. - - `-t FILE' - This switch provides the name of a file. This file contains a list - of file names to be converted, and the effect is exactly as though - they had appeared explicitly on the command line. This is the - recommended way to work around the command line length limit on - some systems. - -  - File: gnat_ug_vxw.info, Node: Installing gnathtml, Prev: Converting Ada Files to html with gnathtml, Up: Other Utility Programs - - Installing `gnathtml' - ===================== - - `Perl' needs to be installed on your machine to run this script. - `Perl' is freely available for almost every architecture and Operating - System via the Internet. - - On Unix systems, you may want to modify the first line of the - script `gnathtml', to explicitly tell the Operating system where - Perl is. The syntax of this line is : - #!full_path_name_to_perl - - Alternatively, you may run the script using the following command line: - - $ perl gnathtml.pl [switches] files - -  - File: gnat_ug_vxw.info, Node: Running and Debugging Ada Programs, Next: Inline Assembler, Prev: Other Utility Programs, Up: Top - - Running and Debugging Ada Programs - ********************************** - - This chapter discusses how to debug Ada programs. An incorrect Ada - program may be handled in three ways by the GNAT compiler: - - 1. The illegality may be a violation of the static semantics of Ada. - In that case GNAT diagnoses the constructs in the program that are - illegal. It is then a straightforward matter for the user to - modify those parts of the program. - - 2. The illegality may be a violation of the dynamic semantics of Ada. - In that case the program compiles and executes, but may generate - incorrect results, or may terminate abnormally with some exception. - - 3. When presented with a program that contains convoluted errors, GNAT - itself may terminate abnormally without providing full diagnostics - on the incorrect user program. - - * Menu: - - * The GNAT Debugger GDB:: - * Running GDB:: - * Introduction to GDB Commands:: - * Using Ada Expressions:: - * Calling User-Defined Subprograms:: - * Using the Next Command in a Function:: - * Ada Exceptions:: - * Ada Tasks:: - * Debugging Generic Units:: - * GNAT Abnormal Termination or Failure to Terminate:: - * Naming Conventions for GNAT Source Files:: - * Getting Internal Debugging Information:: - * Stack Traceback:: - -  - File: gnat_ug_vxw.info, Node: The GNAT Debugger GDB, Next: Running GDB, Up: Running and Debugging Ada Programs - - The GNAT Debugger GDB - ===================== - - `GDB' is a general purpose, platform-independent debugger that can be - used to debug mixed-language programs compiled with `GCC', and in - particular is capable of debugging Ada programs compiled with GNAT. The - latest versions of `GDB' are Ada-aware and can handle complex Ada data - structures. - - The manual `Debugging with GDB' contains full details on the usage - of `GDB', including a section on its usage on programs. This manual - should be consulted for full details. The section that follows is a - brief introduction to the philosophy and use of `GDB'. - - When GNAT programs are compiled, the compiler optionally writes - debugging information into the generated object file, including - information on line numbers, and on declared types and variables. This - information is separate from the generated code. It makes the object - files considerably larger, but it does not add to the size of the - actual executable that will be loaded into memory, and has no impact on - run-time performance. The generation of debug information is triggered - by the use of the -g switch in the gcc or gnatmake command used to - carry out the compilations. It is important to emphasize that the use - of these options does not change the generated code. - - The debugging information is written in standard system formats that - are used by many tools, including debuggers and profilers. The format - of the information is typically designed to describe C types and - semantics, but GNAT implements a translation scheme which allows full - details about Ada types and variables to be encoded into these standard - C formats. Details of this encoding scheme may be found in the file - exp_dbug.ads in the GNAT source distribution. However, the details of - this encoding are, in general, of no interest to a user, since `GDB' - automatically performs the necessary decoding. - - When a program is bound and linked, the debugging information is - collected from the object files, and stored in the executable image of - the program. Again, this process significantly increases the size of - the generated executable file, but it does not increase the size of the - executable program itself. Furthermore, if this program is run in the - normal manner, it runs exactly as if the debug information were not - present, and takes no more actual memory. - - However, if the program is run under control of `GDB', the debugger - is activated. The image of the program is loaded, at which point it is - ready to run. If a run command is given, then the program will run - exactly as it would have if `GDB' were not present. This is a crucial - part of the `GDB' design philosophy. `GDB' is entirely non-intrusive - until a breakpoint is encountered. If no breakpoint is ever hit, the - program will run exactly as it would if no debugger were present. When - a breakpoint is hit, `GDB' accesses the debugging information and can - respond to user commands to inspect variables, and more generally to - report on the state of execution. - -  - File: gnat_ug_vxw.info, Node: Running GDB, Next: Introduction to GDB Commands, Prev: The GNAT Debugger GDB, Up: Running and Debugging Ada Programs - - Running GDB - =========== - - Please refer to the debugging section of the chapter specific to your - cross environment at the end of this manual. - -  - File: gnat_ug_vxw.info, Node: Introduction to GDB Commands, Next: Using Ada Expressions, Prev: Running GDB, Up: Running and Debugging Ada Programs - - Introduction to GDB Commands - ============================ - - `GDB' contains a large repertoire of commands. The manual `Debugging - with GDB' includes extensive documentation on the use of these - commands, together with examples of their use. Furthermore, the command - HELP invoked from within `GDB' activates a simple help facility which - summarizes the available commands and their options. In this section - we summarize a few of the most commonly used commands to give an idea - of what `GDB' is about. You should create a simple program with - debugging information and experiment with the use of these `GDB' - commands on the program as you read through the following section. - - `set args ARGUMENTS' - The ARGUMENTS list above is a list of arguments to be passed to - the program on a subsequent run command, just as though the - arguments had been entered on a normal invocation of the program. - The `set args' command is not needed if the program does not - require arguments. - - `run' - The `run' command causes execution of the program to start from - the beginning. If the program is already running, that is to say if - you are currently positioned at a breakpoint, then a prompt will - ask for confirmation that you want to abandon the current - execution and restart. - - `breakpoint LOCATION' - The breakpoint command sets a breakpoint, that is to say a point - at which execution will halt and `GDB' will await further - commands. LOCATION is either a line number within a file, given in - the format `file:linenumber', or it is the name of a subprogram. - If you request that a breakpoint be set on a subprogram that is - overloaded, a prompt will ask you to specify on which of those - subprograms you want to breakpoint. You can also specify that all - of them should be breakpointed. If the program is run and - execution encounters the breakpoint, then the program stops and - `GDB' signals that the breakpoint was encountered by printing the - line of code before which the program is halted. - - `breakpoint exception NAME' - A special form of the breakpoint command which breakpoints whenever - exception NAME is raised. If NAME is omitted, then a breakpoint - will occur when any exception is raised. - - `print EXPRESSION' - This will print the value of the given expression. Most simple Ada - expression formats are properly handled by `GDB', so the expression - can contain function calls, variables, operators, and attribute - references. - - `continue' - Continues execution following a breakpoint, until the next - breakpoint or the termination of the program. - - `step' - Executes a single line after a breakpoint. If the next statement - is a subprogram call, execution continues into (the first - statement of) the called subprogram. - - `next' - Executes a single line. If this line is a subprogram call, - executes and returns from the call. - - `list' - Lists a few lines around the current source location. In practice, - it is usually more convenient to have a separate edit window open - with the relevant source file displayed. Successive applications - of this command print subsequent lines. The command can be given - an argument which is a line number, in which case it displays a - few lines around the specified one. - - `backtrace' - Displays a backtrace of the call chain. This command is typically - used after a breakpoint has occurred, to examine the sequence of - calls that leads to the current breakpoint. The display includes - one line for each activation record (frame) corresponding to an - active subprogram. - - `up' - At a breakpoint, `GDB' can display the values of variables local - to the current frame. The command `up' can be used to examine the - contents of other active frames, by moving the focus up the stack, - that is to say from callee to caller, one frame at a time. - - `down' - Moves the focus of `GDB' down from the frame currently being - examined to the frame of its callee (the reverse of the previous - command), - - `frame N' - Inspect the frame with the given number. The value 0 denotes the - frame of the current breakpoint, that is to say the top of the - call stack. - - The above list is a very short introduction to the commands that - `GDB' provides. Important additional capabilities, including conditional - breakpoints, the ability to execute command sequences on a breakpoint, - the ability to debug at the machine instruction level and many other - features are described in detail in `Debugging with GDB'. Note that - most commands can be abbreviated (for example, c for continue, bt for - backtrace). - -  - File: gnat_ug_vxw.info, Node: Using Ada Expressions, Next: Calling User-Defined Subprograms, Prev: Introduction to GDB Commands, Up: Running and Debugging Ada Programs - - Using Ada Expressions - ===================== - - `GDB' supports a fairly large subset of Ada expression syntax, with some - extensions. The philosophy behind the design of this subset is - - * That `GDB' should provide basic literals and access to operations - for arithmetic, dereferencing, field selection, indexing, and - subprogram calls, leaving more sophisticated computations to - subprograms written into the program (which therefore may be - called from `GDB'). - - * That type safety and strict adherence to Ada language restrictions - are not particularly important to the `GDB' user. - - * That brevity is important to the `GDB' user. - - Thus, for brevity, the debugger acts as if there were implicit - `with' and `use' clauses in effect for all user-written packages, thus - making it unnecessary to fully qualify most names with their packages, - regardless of context. Where this causes ambiguity, `GDB' asks the - user's intent. - - For details on the supported Ada syntax, see `Debugging with GDB'. - -  - File: gnat_ug_vxw.info, Node: Calling User-Defined Subprograms, Next: Using the Next Command in a Function, Prev: Using Ada Expressions, Up: Running and Debugging Ada Programs - - Calling User-Defined Subprograms - ================================ - - An important capability of `GDB' is the ability to call user-defined - subprograms while debugging. This is achieved simply by entering a - subprogram call statement in the form: - - call subprogram-name (parameters) - - The keyword `call' can be omitted in the normal case where the - `subprogram-name' does not coincide with any of the predefined `GDB' - commands. - - The effect is to invoke the given subprogram, passing it the list of - parameters that is supplied. The parameters can be expressions and can - include variables from the program being debugged. The subprogram must - be defined at the library level within your program, and `GDB' will - call the subprogram within the environment of your program execution - (which means that the subprogram is free to access or even modify - variables within your program). - - The most important use of this facility is in allowing the inclusion - of debugging routines that are tailored to particular data structures - in your program. Such debugging routines can be written to provide a - suitably high-level description of an abstract type, rather than a - low-level dump of its physical layout. After all, the standard `GDB - print' command only knows the physical layout of your types, not their - abstract meaning. Debugging routines can provide information at the - desired semantic level and are thus enormously useful. - - For example, when debugging GNAT itself, it is crucial to have - access to the contents of the tree nodes used to represent the program - internally. But tree nodes are represented simply by an integer value - (which in turn is an index into a table of nodes). Using the `print' - command on a tree node would simply print this integer value, which is - not very useful. But the PN routine (defined in file treepr.adb in the - GNAT sources) takes a tree node as input, and displays a useful high - level representation of the tree node, which includes the syntactic - category of the node, its position in the source, the integers that - denote descendant nodes and parent node, as well as varied semantic - information. To study this example in more detail, you might want to - look at the body of the PN procedure in the stated file. - -  - File: gnat_ug_vxw.info, Node: Using the Next Command in a Function, Next: Ada Exceptions, Prev: Calling User-Defined Subprograms, Up: Running and Debugging Ada Programs - - Using the Next Command in a Function - ==================================== - - When you use the `next' command in a function, the current source - location will advance to the next statement as usual. A special case - arises in the case of a `return' statement. - - Part of the code for a return statement is the "epilog" of the - function. This is the code that returns to the caller. There is only - one copy of this epilog code, and it is typically associated with the - last return statement in the function if there is more than one return. - In some implementations, this epilog is associated with the first - statement of the function. - - The result is that if you use the `next' command from a return - statement that is not the last return statement of the function you may - see a strange apparent jump to the last return statement or to the - start of the function. You should simply ignore this odd jump. The - value returned is always that from the first return statement that was - stepped through. - -  - File: gnat_ug_vxw.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Using the Next Command in a Function, Up: Running and Debugging Ada Programs - - Breaking on Ada Exceptions - ========================== - - You can set breakpoints that trip when your program raises selected - exceptions. - - `break exception' - Set a breakpoint that trips whenever (any task in the) program - raises any exception. - - `break exception NAME' - Set a breakpoint that trips whenever (any task in the) program - raises the exception NAME. - - `break exception unhandled' - Set a breakpoint that trips whenever (any task in the) program - raises an exception for which there is no handler. - - `info exceptions' - `info exceptions REGEXP' - The `info exceptions' command permits the user to examine all - defined exceptions within Ada programs. With a regular expression, - REGEXP, as argument, prints out only those exceptions whose name - matches REGEXP. - -  - File: gnat_ug_vxw.info, Node: Ada Tasks, Next: Debugging Generic Units, Prev: Ada Exceptions, Up: Running and Debugging Ada Programs - - Ada Tasks - ========= - - `GDB' allows the following task-related commands: - - `info tasks' - This command shows a list of current Ada tasks, as in the - following example: - - (gdb) info tasks - ID TID P-ID Thread Pri State Name - 1 8088000 0 807e000 15 Child Activation Wait main_task - 2 80a4000 1 80ae000 15 Accept/Select Wait b - 3 809a800 1 80a4800 15 Child Activation Wait a - * 4 80ae800 3 80b8000 15 Running c - - In this listing, the asterisk before the first task indicates it - to be the currently running task. The first column lists the task - ID that is used to refer to tasks in the following commands. - - `break LINESPEC task TASKID' - `break LINESPEC task TASKID if ...' - These commands are like the `break ... thread ...'. LINESPEC - specifies source lines. - - Use the qualifier `task TASKID' with a breakpoint command to - specify that you only want `GDB' to stop the program when a - particular Ada task reaches this breakpoint. TASKID is one of the - numeric task identifiers assigned by `GDB', shown in the first - column of the `info tasks' display. - - If you do not specify `task TASKID' when you set a breakpoint, the - breakpoint applies to _all_ tasks of your program. - - You can use the `task' qualifier on conditional breakpoints as - well; in this case, place `task TASKID' before the breakpoint - condition (before the `if'). - - `task TASKNO' - This command allows to switch to the task referred by TASKNO. In - particular, This allows to browse the backtrace of the specified - task. It is advised to switch back to the original task before - continuing execution otherwise the scheduling of the program may be - perturbated. - - For more detailed information on the tasking support, see `Debugging - with GDB'. - -  - File: gnat_ug_vxw.info, Node: Debugging Generic Units, Next: GNAT Abnormal Termination or Failure to Terminate, Prev: Ada Tasks, Up: Running and Debugging Ada Programs - - Debugging Generic Units - ======================= - - GNAT always uses code expansion for generic instantiation. This means - that each time an instantiation occurs, a complete copy of the original - code is made, with appropriate substitutions of formals by actuals. - - It is not possible to refer to the original generic entities in - `GDB', but it is always possible to debug a particular instance of a - generic, by using the appropriate expanded names. For example, if we - have - - procedure g is - - generic package k is - procedure kp (v1 : in out integer); - end k; - - package body k is - procedure kp (v1 : in out integer) is - begin - v1 := v1 + 1; - end kp; - end k; - - package k1 is new k; - package k2 is new k; - - var : integer := 1; - - begin - k1.kp (var); - k2.kp (var); - k1.kp (var); - k2.kp (var); - end; - - Then to break on a call to procedure kp in the k2 instance, simply use - the command: - - (gdb) break g.k2.kp - - When the breakpoint occurs, you can step through the code of the - instance in the normal manner and examine the values of local - variables, as for other units. - -  - File: gnat_ug_vxw.info, Node: GNAT Abnormal Termination or Failure to Terminate, Next: Naming Conventions for GNAT Source Files, Prev: Debugging Generic Units, Up: Running and Debugging Ada Programs - - GNAT Abnormal Termination or Failure to Terminate - ================================================= - - When presented with programs that contain serious errors in syntax or - semantics, GNAT may on rare occasions experience problems in - operation, such as aborting with a segmentation fault or illegal memory - access, raising an internal exception, terminating abnormally, or - failing to terminate at all. In such cases, you can activate various - features of GNAT that can help you pinpoint the construct in your - program that is the likely source of the problem. - - The following strategies are presented in increasing order of - difficulty, corresponding to your experience in using GNAT and your - familiarity with compiler internals. - - 1. Run `gcc' with the `-gnatf'. This first switch causes all errors - on a given line to be reported. In its absence, only the first - error on a line is displayed. - - The `-gnatdO' switch causes errors to be displayed as soon as they - are encountered, rather than after compilation is terminated. If - GNAT terminates prematurely or goes into an infinite loop, the - last error message displayed may help to pinpoint the culprit. - - 2. Run `gcc' with the `-v (verbose)' switch. In this mode, `gcc' - produces ongoing information about the progress of the compilation - and provides the name of each procedure as code is generated. This - switch allows you to find which Ada procedure was being compiled - when it encountered a code generation problem. - - 3. Run `gcc' with the `-gnatdc' switch. This is a GNAT specific - switch that does for the front-end what `-v' does for the back end. - The system prints the name of each unit, either a compilation unit - or nested unit, as it is being analyzed. - - 4. Finally, you can start `gdb' directly on the `gnat1' executable. - `gnat1' is the front-end of GNAT, and can be run independently - (normally it is just called from `gcc'). You can use `gdb' on - `gnat1' as you would on a C program (but *note The GNAT Debugger - GDB:: for caveats). The `where' command is the first line of - attack; the variable `lineno' (seen by `print lineno'), used by - the second phase of `gnat1' and by the `gcc' backend, indicates - the source line at which the execution stopped, and `input_file - name' indicates the name of the source file. - -  - File: gnat_ug_vxw.info, Node: Naming Conventions for GNAT Source Files, Next: Getting Internal Debugging Information, Prev: GNAT Abnormal Termination or Failure to Terminate, Up: Running and Debugging Ada Programs - - Naming Conventions for GNAT Source Files - ======================================== - - In order to examine the workings of the GNAT system, the following - brief description of its organization may be helpful: - - * Files with prefix `sc' contain the lexical scanner. - - * All files prefixed with `par' are components of the parser. The - numbers correspond to chapters of the Ada 95 Reference Manual. For - example, parsing of select statements can be found in - `par-ch9.adb'. - - * All files prefixed with `sem' perform semantic analysis. The - numbers correspond to chapters of the Ada standard. For example, - all issues involving context clauses can be found in - `sem_ch10.adb'. In addition, some features of the language require - sufficient special processing to justify their own semantic files: - sem_aggr for aggregates, sem_disp for dynamic dispatching, etc. - - * All files prefixed with `exp' perform normalization and expansion - of the intermediate representation (abstract syntax tree, or AST). - these files use the same numbering scheme as the parser and - semantics files. For example, the construction of record - initialization procedures is done in `exp_ch3.adb'. - - * The files prefixed with `bind' implement the binder, which - verifies the consistency of the compilation, determines an order of - elaboration, and generates the bind file. - - * The files `atree.ads' and `atree.adb' detail the low-level data - structures used by the front-end. - - * The files `sinfo.ads' and `sinfo.adb' detail the structure of the - abstract syntax tree as produced by the parser. - - * The files `einfo.ads' and `einfo.adb' detail the attributes of all - entities, computed during semantic analysis. - - * Library management issues are dealt with in files with prefix - `lib'. - - * Ada files with the prefix `a-' are children of `Ada', as defined - in Annex A. - - * Files with prefix `i-' are children of `Interfaces', as defined in - Annex B. - - * Files with prefix `s-' are children of `System'. This includes - both language-defined children and GNAT run-time routines. - - * Files with prefix `g-' are children of `GNAT'. These are useful - general-purpose packages, fully documented in their - specifications. All the other `.c' files are modifications of - common `gcc' files. - -  - File: gnat_ug_vxw.info, Node: Getting Internal Debugging Information, Next: Stack Traceback, Prev: Naming Conventions for GNAT Source Files, Up: Running and Debugging Ada Programs - - Getting Internal Debugging Information - ====================================== - - Most compilers have internal debugging switches and modes. GNAT does - also, except GNAT internal debugging switches and modes are not secret. - A summary and full description of all the compiler and binder debug - flags are in the file `debug.adb'. You must obtain the sources of the - compiler to see the full detailed effects of these flags. - - The switches that print the source of the program (reconstructed from - the internal tree) are of general interest for user programs, as are the - options to print the full internal tree, and the entity table (the - symbol table information). The reconstructed source provides a readable - version of the program after the front-end has completed analysis and - expansion, and is useful when studying the performance of specific - constructs. For example, constraint checks are indicated, complex - aggregates are replaced with loops and assignments, and tasking - primitives are replaced with run-time calls. - -  - File: gnat_ug_vxw.info, Node: Stack Traceback, Prev: Getting Internal Debugging Information, Up: Running and Debugging Ada Programs - - Stack Traceback - =============== - - Traceback is a mechanism to display the sequence of subprogram calls - that leads to a specified execution point in a program. Often (but not - always) the execution point is an instruction at which an exception has - been raised. This mechanism is also known as stack unwinding because - it obtains its information by scanning the run-time stack and - recovering the activation records of all active subprograms. Stack - unwinding is one of the most important tools for program debugging. - - The first entry stored in traceback corresponds to the deepest calling - level, that is to say the subprogram currently executing the instruction - from which we want to obtain the traceback. - - Note that there is no runtime performance penalty when stack traceback - is enabled and no exception are raised during program execution. - - * Menu: - - * Non-Symbolic Traceback:: - * Symbolic Traceback:: - -  - File: gnat_ug_vxw.info, Node: Non-Symbolic Traceback, Next: Symbolic Traceback, Up: Stack Traceback - - Non-Symbolic Traceback - ---------------------- - - Note: this feature is not supported on all platforms. See - `GNAT.Traceback spec in g-traceb.ads' for a complete list of supported - platforms. - - * Menu: - - * Tracebacks From an Unhandled Exception:: - * Tracebacks From Exception Occurrences (non-symbolic):: - * Tracebacks From Anywhere in a Program (non-symbolic):: - -  - File: gnat_ug_vxw.info, Node: Tracebacks From an Unhandled Exception, Next: Tracebacks From Exception Occurrences (non-symbolic), Up: Non-Symbolic Traceback - - Tracebacks From an Unhandled Exception - ...................................... - - A runtime non-symbolic traceback is a list of addresses of call - instructions. To enable this feature you must use the `-E' - `gnatbind''s option. With this option a stack traceback is stored as - part of exception information. It is possible to retrieve this - information using the standard `Ada.Exception.Exception_Information' - routine. - - Let's have a look at a simple example: - - procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - $ gnatmake stb -bargs -E - $ stb - - Execution terminated by unhandled exception - Exception name: CONSTRAINT_ERROR - Message: stb.adb:5 - Call stack traceback locations: - 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - - As we see the traceback lists a sequence of addresses for the unhandled - exception `CONSTAINT_ERROR' raised in procedure P1. It is easy to guess - that this exception come from procedure P1. To translate these - addresses into the source lines where the calls appear, the `addr2line' - tool, described below, is invaluable. The use of this tool requires the - program to be compiled with debug information. - - $ gnatmake -g stb -bargs -E - $ stb - - Execution terminated by unhandled exception - Exception name: CONSTRAINT_ERROR - Message: stb.adb:5 - Call stack traceback locations: - 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - - $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 - 0x4011f1 0x77e892a4 - - 00401373 at d:/stb/stb.adb:5 - 0040138B at d:/stb/stb.adb:10 - 0040139C at d:/stb/stb.adb:14 - 00401335 at d:/stb/b~stb.adb:104 - 004011C4 at /build/.../crt1.c:200 - 004011F1 at /build/.../crt1.c:222 - 77E892A4 in ?? at ??:0 - - `addr2line' has a number of other useful options: - - `--functions' - to get the function name corresponding to any location - - `--demangle=gnat' - to use the gnat decoding mode for the function names. Note that - for binutils version 2.9.x the option is simply `--demangle'. - - $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b - 0x40139c 0x401335 0x4011c4 0x4011f1 - - 00401373 in stb.p1 at d:/stb/stb.adb:5 - 0040138B in stb.p2 at d:/stb/stb.adb:10 - 0040139C in stb at d:/stb/stb.adb:14 - 00401335 in main at d:/stb/b~stb.adb:104 - 004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200 - 004011F1 in at /build/.../crt1.c:222 - - From this traceback we can see that the exception was raised in - `stb.adb' at line 5, which was reached from a procedure call in - `stb.adb' at line 10, and so on. The `b~std.adb' is the binder file, - which contains the call to the main program. *note Running gnatbind::. - The remaining entries are assorted runtime routines, and the output - will vary from platform to platform. - - It is also possible to use `GDB' with these traceback addresses to debug - the program. For example, we can break at a given code location, as - reported in the stack traceback: - - $ gdb -nw stb - - (gdb) break *0x401373 - Breakpoint 1 at 0x401373: file stb.adb, line 5. - - It is important to note that the stack traceback addresses do not - change when debug information is included. This is particularly useful - because it makes it possible to release software without debug - information (to minimize object size), get a field report that includes - a stack traceback whenever an internal bug occurs, and then be able to - retrieve the sequence of calls with the same program compiled with - debug information. - -  - File: gnat_ug_vxw.info, Node: Tracebacks From Exception Occurrences (non-symbolic), Next: Tracebacks From Anywhere in a Program (non-symbolic), Prev: Tracebacks From an Unhandled Exception, Up: Non-Symbolic Traceback - - Tracebacks From Exception Occurrences - ..................................... - - Non-symbolic tracebacks are obtained by using the `-E' binder argument. - The stack traceback is attached to the exception information string, - and can be retrieved in an exception handler within the Ada program, by - means of the Ada95 facilities defined in `Ada.Exceptions'. Here is a - simple example: - - with Ada.Text_IO; - with Ada.Exceptions; - - procedure STB is - - use Ada; - use Ada.Exceptions; - - procedure P1 is - K : Positive := 1; - begin - K := K - 1; - exception - when E : others => - Text_IO.Put_Line (Exception_Information (E)); - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - This program will output: - - $ stb - - Exception name: CONSTRAINT_ERROR - Message: stb.adb:12 - Call stack traceback locations: - 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 - -  - File: gnat_ug_vxw.info, Node: Tracebacks From Anywhere in a Program (non-symbolic), Prev: Tracebacks From Exception Occurrences (non-symbolic), Up: Non-Symbolic Traceback - - Tracebacks From Anywhere in a Program - ..................................... - - It is also possible to retrieve a stack traceback from anywhere in a - program. For this you need to use the `GNAT.Traceback' API. This - package includes a procedure called `Call_Chain' that computes a - complete stack traceback, as well as useful display procedures - described below. It is not necessary to use the `-E gnatbind' option in - this case, because the stack traceback mechanism is invoked explicitly. - - In the following example we compute a traceback at a specific location - in the program, and we display it using `GNAT.Debug_Utilities.Image' to - convert addresses to strings: - - with Ada.Text_IO; - with GNAT.Traceback; - with GNAT.Debug_Utilities; - - procedure STB is - - use Ada; - use GNAT; - use GNAT.Traceback; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - - Text_IO.Put ("In STB.P1 : "); - - for K in 1 .. Len loop - Text_IO.Put (Debug_Utilities.Image (TB (K))); - Text_IO.Put (' '); - end loop; - - Text_IO.New_Line; - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - $ gnatmake stb - $ stb - - In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# - 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# - -  - File: gnat_ug_vxw.info, Node: Symbolic Traceback, Prev: Non-Symbolic Traceback, Up: Stack Traceback - - Symbolic Traceback - ------------------ - - A symbolic traceback is a stack traceback in which procedure names are - associated with each code location. - - Note that this feature is not supported on all platforms. See - `GNAT.Traceback.Symbolic spec in g-trasym.ads' for a complete list of - currently supported platforms. - - Note that the symbolic traceback requires that the program be compiled - with debug information. If it is not compiled with debug information - only the non-symbolic information will be valid. - - * Menu: - - * Tracebacks From Exception Occurrences (symbolic):: - * Tracebacks From Anywhere in a Program (symbolic):: - -  - File: gnat_ug_vxw.info, Node: Tracebacks From Exception Occurrences (symbolic), Next: Tracebacks From Anywhere in a Program (symbolic), Up: Symbolic Traceback - - Tracebacks From Exception Occurrences - ..................................... - - with Ada.Text_IO; - with GNAT.Traceback.Symbolic; - - procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - procedure P3 is - begin - P2; - end P3; - - begin - P3; - exception - when E : others => - Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); - end STB; - - $ gnatmake -g stb -bargs -E -largs -lgnat -laddr2line -lintl - $ stb - - 0040149F in stb.p1 at stb.adb:8 - 004014B7 in stb.p2 at stb.adb:13 - 004014CF in stb.p3 at stb.adb:18 - 004015DD in ada.stb at stb.adb:22 - 00401461 in main at b~stb.adb:168 - 004011C4 in __mingw_CRTStartup at crt1.c:200 - 004011F1 in mainCRTStartup at crt1.c:222 - 77E892A4 in ?? at ??:0 - - The exact sequence of linker options may vary from platform to platform. - The above `-largs' section is for Windows platforms. By contrast, under - Unix there is no need for the `-largs' section. Differences across - platforms are due to details of linker implementation. - -  - File: gnat_ug_vxw.info, Node: Tracebacks From Anywhere in a Program (symbolic), Prev: Tracebacks From Exception Occurrences (symbolic), Up: Symbolic Traceback - - Tracebacks From Anywhere in a Program - ..................................... - - It is possible to get a symbolic stack traceback from anywhere in a - program, just as for non-symbolic tracebacks. The first step is to - obtain a non-symbolic traceback, and then call `Symbolic_Traceback' to - compute the symbolic information. Here is an example: - - with Ada.Text_IO; - with GNAT.Traceback; - with GNAT.Traceback.Symbolic; - - procedure STB is - - use Ada; - use GNAT.Traceback; - use GNAT.Traceback.Symbolic; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - -  - File: gnat_ug_vxw.info, Node: Inline Assembler, Next: VxWorks Topics, Prev: Running and Debugging Ada Programs, Up: Top - - Inline Assembler - **************** - - If you need to write low-level software that interacts directly with - the hardware, Ada provides two ways to incorporate assembly language - code into your program. First, you can import and invoke external - routines written in assembly language, an Ada feature fully supported - by GNAT. However, for small sections of code it may be simpler or more - efficient to include assembly language statements directly in your Ada - source program, using the facilities of the implementation-defined - package `System.Machine_Code', which incorporates the gcc Inline - Assembler. The Inline Assembler approach offers a number of - advantages, including the following: - - * No need to use non-Ada tools - - * Consistent interface over different targets - - * Automatic usage of the proper calling conventions - - * Access to Ada constants and variables - - * Definition of intrinsic routines - - * Possibility of inlining a subprogram comprising assembler code - - * Code optimizer can take Inline Assembler code into account - - This chapter presents a series of examples to show you how to use - the Inline Assembler. Although it focuses on the Intel x86, the - general approach applies also to other processors. It is assumed that - you are familiar with Ada and with assembly language programming. - - * Menu: - - * Basic Assembler Syntax:: - * A Simple Example of Inline Assembler:: - * Output Variables in Inline Assembler:: - * Input Variables in Inline Assembler:: - * Inlining Inline Assembler Code:: - * Other Asm Functionality:: - * A Complete Example:: - -  - File: gnat_ug_vxw.info, Node: Basic Assembler Syntax, Next: A Simple Example of Inline Assembler, Up: Inline Assembler - - Basic Assembler Syntax - ====================== - - The assembler used by GNAT and gcc is based not on the Intel assembly - language, but rather on a language that descends from the AT&T Unix - assembler _as_ (and which is often referred to as "AT&T syntax"). The - following table summarizes the main features of _as_ syntax and points - out the differences from the Intel conventions. See the gcc _as_ and - _gas_ (an _as_ macro pre-processor) documentation for further - information. - - Register names - gcc / _as_: Prefix with "%"; for example `%eax' - Intel: No extra punctuation; for example `eax' - - Immediate operand - gcc / _as_: Prefix with "$"; for example `$4' - Intel: No extra punctuation; for example `4' - - Address - gcc / _as_: Prefix with "$"; for example `$loc' - Intel: No extra punctuation; for example `loc' - - Memory contents - gcc / _as_: No extra punctuation; for example `loc' - Intel: Square brackets; for example `[loc]' - - Register contents - gcc / _as_: Parentheses; for example `(%eax)' - Intel: Square brackets; for example `[eax]' - - Hexadecimal numbers - gcc / _as_: Leading "0x" (C language syntax); for example `0xA0' - Intel: Trailing "h"; for example `A0h' - - Operand size - gcc / _as_: Explicit in op code; for example `movw' to move a - 16-bit word - Intel: Implicit, deduced by assembler; for example `mov' - - Instruction repetition - gcc / _as_: Split into two lines; for example - `rep' - `stosl' - Intel: Keep on one line; for example `rep stosl' - - Order of operands - gcc / _as_: Source first; for example `movw $4, %eax' - Intel: Destination first; for example `mov eax, 4' - -  - File: gnat_ug_vxw.info, Node: A Simple Example of Inline Assembler, Next: Output Variables in Inline Assembler, Prev: Basic Assembler Syntax, Up: Inline Assembler - - A Simple Example of Inline Assembler - ==================================== - - The following example will generate a single assembly language - statement, `nop', which does nothing. Despite its lack of run-time - effect, the example will be useful in illustrating the basics of the - Inline Assembler facility. - - with System.Machine_Code; use System.Machine_Code; - procedure Nothing is - begin - Asm ("nop"); - end Nothing; - - `Asm' is a procedure declared in package `System.Machine_Code'; here - it takes one parameter, a _template string_ that must be a static - expression and that will form the generated instruction. `Asm' may be - regarded as a compile-time procedure that parses the template string - and additional parameters (none here), from which it generates a - sequence of assembly language instructions. - - The examples in this chapter will illustrate several of the forms - for invoking `Asm'; a complete specification of the syntax is found in - the `GNAT Reference Manual'. - - Under the standard GNAT conventions, the `Nothing' procedure should - be in a file named `nothing.adb'. You can build the executable in the - usual way: - gnatmake nothing - However, the interesting aspect of this example is not its run-time - behavior but rather the generated assembly code. To see this output, - invoke the compiler as follows: - gcc -c -S -fomit-frame-pointer -gnatp `nothing.adb' - where the options are: - - `-c' - compile only (no bind or link) - - `-S' - generate assembler listing - - `-fomit-frame-pointer' - do not set up separate stack frames - - `-gnatp' - do not add runtime checks - - This gives a human-readable assembler version of the code. The - resulting file will have the same name as the Ada source file, but with - a `.s' extension. In our example, the file `nothing.s' has the - following contents: - - .file "nothing.adb" - gcc2_compiled.: - ___gnu_compiled_ada: - .text - .align 4 - .globl __ada_nothing - __ada_nothing: - #APP - nop - #NO_APP - jmp L1 - .align 2,0x90 - L1: - ret - - The assembly code you included is clearly indicated by the compiler, - between the `#APP' and `#NO_APP' delimiters. The character before the - 'APP' and 'NOAPP' can differ on different targets. For example, Linux - uses '#APP' while on NT you will see '/APP'. - - If you make a mistake in your assembler code (such as using the - wrong size modifier, or using a wrong operand for the instruction) GNAT - will report this error in a temporary file, which will be deleted when - the compilation is finished. Generating an assembler file will help in - such cases, since you can assemble this file separately using the _as_ - assembler that comes with gcc. - - Assembling the file using the command - - as `nothing.s' - - will give you error messages whose lines correspond to the assembler - input file, so you can easily find and correct any mistakes you made. - If there are no errors, _as_ will generate an object file `nothing.out'. - -  - File: gnat_ug_vxw.info, Node: Output Variables in Inline Assembler, Next: Input Variables in Inline Assembler, Prev: A Simple Example of Inline Assembler, Up: Inline Assembler - - Output Variables in Inline Assembler - ==================================== - - The examples in this section, showing how to access the processor - flags, illustrate how to specify the destination operands for assembly - language statements. - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags; - - In order to have a nicely aligned assembly listing, we have separated - multiple assembler statements in the Asm template string with linefeed - (ASCII.LF) and horizontal tab (ASCII.HT) characters. The resulting - section of the assembly output file is: - - #APP - pushfl - popl %eax - movl %eax, -40(%ebp) - #NO_APP - - It would have been legal to write the Asm invocation as: - - Asm ("pushfl popl %%eax movl %%eax, %0") - - but in the generated assembler file, this would come out as: - - #APP - pushfl popl %eax movl %eax, -40(%ebp) - #NO_APP - - which is not so convenient for the human reader. - - We use Ada comments at the end of each line to explain what the - assembler instructions actually do. This is a useful convention. - - When writing Inline Assembler instructions, you need to precede each - register and variable name with a percent sign. Since the assembler - already requires a percent sign at the beginning of a register name, - you need two consecutive percent signs for such names in the Asm - template string, thus `%%eax'. In the generated assembly code, one of - the percent signs will be stripped off. - - Names such as `%0', `%1', `%2', etc., denote input or output - variables: operands you later define using `Input' or `Output' - parameters to `Asm'. An output variable is illustrated in the third - statement in the Asm template string: - movl %%eax, %0 - The intent is to store the contents of the eax register in a - variable that can be accessed in Ada. Simply writing `movl %%eax, - Flags' would not necessarily work, since the compiler might optimize by - using a register to hold Flags, and the expansion of the `movl' - instruction would not be aware of this optimization. The solution is - not to store the result directly but rather to advise the compiler to - choose the correct operand form; that is the purpose of the `%0' output - variable. - - Information about the output variable is supplied in the `Outputs' - parameter to `Asm': - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - - The output is defined by the `Asm_Output' attribute of the target - type; the general format is - Type'Asm_Output (constraint_string, variable_name) - - The constraint string directs the compiler how to store/access the - associated variable. In the example - Unsigned_32'Asm_Output ("=m", Flags); - the `"m"' (memory) constraint tells the compiler that the variable - `Flags' should be stored in a memory variable, thus preventing the - optimizer from keeping it in a register. In contrast, - Unsigned_32'Asm_Output ("=r", Flags); - uses the `"r"' (register) constraint, telling the compiler to store - the variable in a register. - - If the constraint is preceded by the equal character (*=*), it tells - the compiler that the variable will be used to store data into it. - - In the `Get_Flags' example, we used the "g" (global) constraint, - allowing the optimizer to choose whatever it deems best. - - There are a fairly large number of constraints, but the ones that - are most useful (for the Intel x86 processor) are the following: - - `=' - output constraint - - `g' - global (i.e. can be stored anywhere) - - `m' - in memory - - `I' - a constant - - `a' - use eax - - `b' - use ebx - - `c' - use ecx - - `d' - use edx - - `S' - use esi - - `D' - use edi - - `r' - use one of eax, ebx, ecx or edx - - `q' - use one of eax, ebx, ecx, edx, esi or edi - - The full set of constraints is described in the gcc and _as_ - documentation; note that it is possible to combine certain constraints - in one constraint string. - - You specify the association of an output variable with an assembler - operand through the `%'_n_ notation, where _n_ is a non-negative - integer. Thus in - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - - `%0' will be replaced in the expanded code by the appropriate operand, - whatever the compiler decided for the `Flags' variable. - - In general, you may have any number of output variables: - * Count the operands starting at 0; thus `%0', `%1', etc. - - * Specify the `Outputs' parameter as a parenthesized comma-separated - list of `Asm_Output' attributes - - For example: - Asm ("movl %%eax, %0" & LF & HT & - "movl %%ebx, %1" & LF & HT & - "movl %%ecx, %2", - Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A - Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B - Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C - - where `Var_A', `Var_B', and `Var_C' are variables in the Ada program. - - As a variation on the `Get_Flags' example, we can use the - constraints string to direct the compiler to store the eax register - into the `Flags' variable, instead of including the store instruction - explicitly in the `Asm' template string: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags_2 is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax", -- save flags in eax - Outputs => Unsigned_32'Asm_Output ("=a", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags_2; - - The `"a"' constraint tells the compiler that the `Flags' variable will - come from the eax register. Here is the resulting code: - - #APP - pushfl - popl %eax - #NO_APP - movl %eax,-40(%ebp) - - The compiler generated the store of eax into Flags after expanding the - assembler code. - - Actually, there was no need to pop the flags into the eax register; - more simply, we could just pop the flags directly into the program - variable: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags_3 is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "pop %0", -- save flags in Flags - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags_3; - -  - File: gnat_ug_vxw.info, Node: Input Variables in Inline Assembler, Next: Inlining Inline Assembler Code, Prev: Output Variables in Inline Assembler, Up: Inline Assembler - - Input Variables in Inline Assembler - =================================== - - The example in this section illustrates how to specify the source - operands for assembly language statements. The program simply - increments its input value by 1: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Increment is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Inputs => Unsigned_32'Asm_Input ("a", Value), - Outputs => Unsigned_32'Asm_Output ("=a", Result)); - return Result; - end Incr; - - Value : Unsigned_32; - - begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Incr (Value); - Put_Line ("Value after is" & Value'Img); - end Increment; - - The `Outputs' parameter to `Asm' specifies that the result will be - in the eax register and that it is to be stored in the `Result' - variable. - - The `Inputs' parameter looks much like the `Outputs' parameter, but - with an `Asm_Input' attribute. The `"="' constraint, indicating an - output value, is not present. - - You can have multiple input variables, in the same way that you can - have more than one output variable. - - The parameter count (%0, %1) etc, now starts at the first input - statement, and continues with the output statements. When both - parameters use the same variable, the compiler will treat them as the - same %n operand, which is the case here. - - Just as the `Outputs' parameter causes the register to be stored - into the target variable after execution of the assembler statements, - so does the `Inputs' parameter cause its variable to be loaded into the - register before execution of the assembler statements. - - Thus the effect of the `Asm' invocation is: - 1. load the 32-bit value of `Value' into eax - - 2. execute the `incl %eax' instruction - - 3. store the contents of eax into the `Result' variable - - The resulting assembler file (with `-O2' optimization) contains: - _increment__incr.1: - subl $4,%esp - movl 8(%esp),%eax - #APP - incl %eax - #NO_APP - movl %eax,%edx - movl %ecx,(%esp) - addl $4,%esp - ret - -  - File: gnat_ug_vxw.info, Node: Inlining Inline Assembler Code, Next: Other Asm Functionality, Prev: Input Variables in Inline Assembler, Up: Inline Assembler - - Inlining Inline Assembler Code - ============================== - - For a short subprogram such as the `Incr' function in the previous - section, the overhead of the call and return (creating / deleting the - stack frame) can be significant, compared to the amount of code in the - subprogram body. A solution is to apply Ada's `Inline' pragma to the - subprogram, which directs the compiler to expand invocations of the - subprogram at the point(s) of call, instead of setting up a stack frame - for out-of-line calls. Here is the resulting program: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Increment_2 is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Inputs => Unsigned_32'Asm_Input ("a", Value), - Outputs => Unsigned_32'Asm_Output ("=a", Result)); - return Result; - end Incr; - pragma Inline (Increment); - - Value : Unsigned_32; - - begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Increment (Value); - Put_Line ("Value after is" & Value'Img); - end Increment_2; - - Compile the program with both optimization (`-O2') and inlining - enabled (`-gnatpn' instead of `-gnatp'). - - The `Incr' function is still compiled as usual, but at the point in - `Increment' where our function used to be called: - - pushl %edi - call _increment__incr.1 - - the code for the function body directly appears: - - movl %esi,%eax - #APP - incl %eax - #NO_APP - movl %eax,%edx - - thus saving the overhead of stack frame setup and an out-of-line call. - -  - File: gnat_ug_vxw.info, Node: Other Asm Functionality, Next: A Complete Example, Prev: Inlining Inline Assembler Code, Up: Inline Assembler - - Other `Asm' Functionality - ========================= - - This section describes two important parameters to the `Asm' procedure: - `Clobber', which identifies register usage; and `Volatile', which - inhibits unwanted optimizations. - - * Menu: - - * The Clobber Parameter:: - * The Volatile Parameter:: - -  - File: gnat_ug_vxw.info, Node: The Clobber Parameter, Next: The Volatile Parameter, Up: Other Asm Functionality - - The `Clobber' Parameter - ----------------------- - - One of the dangers of intermixing assembly language and a compiled - language such as Ada is that the compiler needs to be aware of which - registers are being used by the assembly code. In some cases, such as - the earlier examples, the constraint string is sufficient to indicate - register usage (e.g. "a" for the eax register). But more generally, the - compiler needs an explicit identification of the registers that are - used by the Inline Assembly statements. - - Using a register that the compiler doesn't know about could be a - side effect of an instruction (like `mull' storing its result in both - eax and edx). It can also arise from explicit register usage in your - assembly code; for example: - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out)); - - where the compiler (since it does not analyze the `Asm' template string) - does not know you are using the ebx register. - - In such cases you need to supply the `Clobber' parameter to `Asm', - to identify the registers that will be used by your assembly code: - - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Clobber => "ebx"); - - The Clobber parameter is a static string expression specifying the - register(s) you are using. Note that register names are _not_ prefixed - by a percent sign. Also, if more than one register is used then their - names are separated by commas; e.g., `"eax, ebx"' - - The `Clobber' parameter has several additional uses: - 1. Use the "register" name `cc' to indicate that flags might have - changed - - 2. Use the "register" name `memory' if you changed a memory location - -  - File: gnat_ug_vxw.info, Node: The Volatile Parameter, Prev: The Clobber Parameter, Up: Other Asm Functionality - - The `Volatile' Parameter - ------------------------ - - Compiler optimizations in the presence of Inline Assembler may - sometimes have unwanted effects. For example, when an `Asm' invocation - with an input variable is inside a loop, the compiler might move the - loading of the input variable outside the loop, regarding it as a - one-time initialization. - - If this effect is not desired, you can disable such optimizations by - setting the `Volatile' parameter to `True'; for example: - - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Clobber => "ebx", - Volatile => True); - - By default, `Volatile' is set to `False' unless there is no `Outputs' - parameter. - - Although setting `Volatile' to `True' prevents unwanted - optimizations, it will also disable other optimizations that might be - important for efficiency. In general, you should set `Volatile' to - `True' only if the compiler's optimizations have created problems. - -  - File: gnat_ug_vxw.info, Node: A Complete Example, Prev: Other Asm Functionality, Up: Inline Assembler - - A Complete Example - ================== - - This section contains a complete program illustrating a realistic usage - of GNAT's Inline Assembler capabilities. It comprises a main procedure - `Check_CPU' and a package `Intel_CPU'. The package declares a - collection of functions that detect the properties of the 32-bit x86 - processor that is running the program. The main procedure invokes - these functions and displays the information. - - The Intel_CPU package could be enhanced by adding functions to - detect the type of x386 co-processor, the processor caching options and - special operations such as the SIMD extensions. - - Although the Intel_CPU package has been written for 32-bit Intel - compatible CPUs, it is OS neutral. It has been tested on DOS, - Windows/NT and Linux. - - * Menu: - - * Check_CPU Procedure:: - * Intel_CPU Package Specification:: - * Intel_CPU Package Body:: - -  - File: gnat_ug_vxw.info, Node: Check_CPU Procedure, Next: Intel_CPU Package Specification, Up: A Complete Example - - `Check_CPU' Procedure - --------------------- - - --------------------------------------------------------------------- - -- -- - -- Uses the Intel_CPU package to identify the CPU the program is -- - -- running on, and some of the features it supports. -- - -- -- - --------------------------------------------------------------------- - - with Intel_CPU; -- Intel CPU detection functions - with Ada.Text_IO; -- Standard text I/O - with Ada.Command_Line; -- To set the exit status - - procedure Check_CPU is - - Type_Found : Boolean := False; - -- Flag to indicate that processor was identified - - Features : Intel_CPU.Processor_Features; - -- The processor features - - Signature : Intel_CPU.Processor_Signature; - -- The processor type signature - - begin - - ----------------------------------- - -- Display the program banner. -- - ----------------------------------- - - Ada.Text_IO.Put_Line (Ada.Command_Line.Command_Name & - ": check Intel CPU version and features, v1.0"); - Ada.Text_IO.Put_Line ("distribute freely, but no warranty whatsoever"); - Ada.Text_IO.New_Line; - - ----------------------------------------------------------------------- - -- We can safely start with the assumption that we are on at least -- - -- a x386 processor. If the CPUID instruction is present, then we -- - -- have a later processor type. -- - ----------------------------------------------------------------------- - - if Intel_CPU.Has_CPUID = False then - - -- No CPUID instruction, so we assume this is indeed a x386 - -- processor. We can still check if it has a FP co-processor. - if Intel_CPU.Has_FPU then - Ada.Text_IO.Put_Line - ("x386-type processor with a FP co-processor"); - else - Ada.Text_IO.Put_Line - ("x386-type processor without a FP co-processor"); - end if; -- check for FPU - - -- Program done - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - return; - - end if; -- check for CPUID - - ----------------------------------------------------------------------- - -- If CPUID is supported, check if this is a true Intel processor, -- - -- if it is not, display a warning. -- - ----------------------------------------------------------------------- - - if Intel_CPU.Vendor_ID /= Intel_CPU.Intel_Processor then - Ada.Text_IO.Put_Line ("*** This is a Intel compatible processor"); - Ada.Text_IO.Put_Line ("*** Some information may be incorrect"); - end if; -- check if Intel - - ---------------------------------------------------------------------- - -- With the CPUID instruction present, we can assume at least a -- - -- x486 processor. If the CPUID support level is < 1 then we have -- - -- to leave it at that. -- - ---------------------------------------------------------------------- - - if Intel_CPU.CPUID_Level < 1 then - - -- Ok, this is a x486 processor. we still can get the Vendor ID - Ada.Text_IO.Put_Line ("x486-type processor"); - Ada.Text_IO.Put_Line ("Vendor ID is " & Intel_CPU.Vendor_ID); - - -- We can also check if there is a FPU present - if Intel_CPU.Has_FPU then - Ada.Text_IO.Put_Line ("Floating-Point support"); - else - Ada.Text_IO.Put_Line ("No Floating-Point support"); - end if; -- check for FPU - - -- Program done - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - return; - - end if; -- check CPUID level - - --------------------------------------------------------------------- - -- With a CPUID level of 1 we can use the processor signature to -- - -- determine it's exact type. -- - --------------------------------------------------------------------- - - Signature := Intel_CPU.Signature; - - ---------------------------------------------------------------------- - -- Ok, now we go into a lot of messy comparisons to get the -- - -- processor type. For clarity, no attememt to try to optimize the -- - -- comparisons has been made. Note that since Intel_CPU does not -- - -- support getting cache info, we cannot distinguish between P5 -- - -- and Celeron types yet. -- - ---------------------------------------------------------------------- - - -- x486SL - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486SL processor"); - end if; - - -- x486DX2 Write-Back - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#0111# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Write-Back Enhanced x486DX2 processor"); - end if; - - -- x486DX4 - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#1000# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486DX4 processor"); - end if; - - -- x486DX4 Overdrive - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0100# and - Signature.Model = 2#1000# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486DX4 OverDrive processor"); - end if; - - -- Pentium (60, 66) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium processor (60, 66)"); - end if; - - -- Pentium (75, 90, 100, 120, 133, 150, 166, 200) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0010# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium processor (75, 90, 100, 120, 133, 150, 166, 200)"); - end if; - - -- Pentium OverDrive (60, 66) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium OverDrive processor (60, 66)"); - end if; - - -- Pentium OverDrive (75, 90, 100, 120, 133, 150, 166, 200) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0010# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive cpu (75, 90, 100, 120, 133, 150, 166, 200)"); - end if; - - -- Pentium OverDrive processor for x486 processor-based systems - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive processor for x486 processor-based systems"); - end if; - - -- Pentium processor with MMX technology (166, 200) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium processor with MMX technology (166, 200)"); - end if; - - -- Pentium OverDrive with MMX for Pentium (75, 90, 100, 120, 133) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive processor with MMX " & - "technology for Pentium processor (75, 90, 100, 120, 133)"); - end if; - - -- Pentium Pro processor - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium Pro processor"); - end if; - - -- Pentium II processor, model 3 - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium II processor, model 3"); - end if; - - -- Pentium II processor, model 5 or Celeron processor - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0101# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium II processor, model 5 or Celeron processor"); - end if; - - -- Pentium Pro OverDrive processor - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0110# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium Pro OverDrive processor"); - end if; - - -- If no type recognized, we have an unknown. Display what - -- we _do_ know - if Type_Found = False then - Ada.Text_IO.Put_Line ("Unknown processor"); - end if; - - ----------------------------------------- - -- Display processor stepping level. -- - ----------------------------------------- - - Ada.Text_IO.Put_Line ("Stepping level:" & Signature.Stepping'Img); - - --------------------------------- - -- Display vendor ID string. -- - --------------------------------- - - Ada.Text_IO.Put_Line ("Vendor ID: " & Intel_CPU.Vendor_ID); - - ------------------------------------ - -- Get the processors features. -- - ------------------------------------ - - Features := Intel_CPU.Features; - - ----------------------------- - -- Check for a FPU unit. -- - ----------------------------- - - if Features.FPU = True then - Ada.Text_IO.Put_Line ("Floating-Point unit available"); - else - Ada.Text_IO.Put_Line ("no Floating-Point unit"); - end if; -- check for FPU - - -------------------------------- - -- List processor features. -- - -------------------------------- - - Ada.Text_IO.Put_Line ("Supported features: "); - - -- Virtual Mode Extension - if Features.VME = True then - Ada.Text_IO.Put_Line (" VME - Virtual Mode Extension"); - end if; - - -- Debugging Extension - if Features.DE = True then - Ada.Text_IO.Put_Line (" DE - Debugging Extension"); - end if; - - -- Page Size Extension - if Features.PSE = True then - Ada.Text_IO.Put_Line (" PSE - Page Size Extension"); - end if; - - -- Time Stamp Counter - if Features.TSC = True then - Ada.Text_IO.Put_Line (" TSC - Time Stamp Counter"); - end if; - - -- Model Specific Registers - if Features.MSR = True then - Ada.Text_IO.Put_Line (" MSR - Model Specific Registers"); - end if; - - -- Physical Address Extension - if Features.PAE = True then - Ada.Text_IO.Put_Line (" PAE - Physical Address Extension"); - end if; - - -- Machine Check Extension - if Features.MCE = True then - Ada.Text_IO.Put_Line (" MCE - Machine Check Extension"); - end if; - - -- CMPXCHG8 instruction supported - if Features.CX8 = True then - Ada.Text_IO.Put_Line (" CX8 - CMPXCHG8 instruction"); - end if; - - -- on-chip APIC hardware support - if Features.APIC = True then - Ada.Text_IO.Put_Line (" APIC - on-chip APIC hardware support"); - end if; - - -- Fast System Call - if Features.SEP = True then - Ada.Text_IO.Put_Line (" SEP - Fast System Call"); - end if; - - -- Memory Type Range Registers - if Features.MTRR = True then - Ada.Text_IO.Put_Line (" MTTR - Memory Type Range Registers"); - end if; - - -- Page Global Enable - if Features.PGE = True then - Ada.Text_IO.Put_Line (" PGE - Page Global Enable"); - end if; - - -- Machine Check Architecture - if Features.MCA = True then - Ada.Text_IO.Put_Line (" MCA - Machine Check Architecture"); - end if; - - -- Conditional Move Instruction Supported - if Features.CMOV = True then - Ada.Text_IO.Put_Line - (" CMOV - Conditional Move Instruction Supported"); - end if; - - -- Page Attribute Table - if Features.PAT = True then - Ada.Text_IO.Put_Line (" PAT - Page Attribute Table"); - end if; - - -- 36-bit Page Size Extension - if Features.PSE_36 = True then - Ada.Text_IO.Put_Line (" PSE_36 - 36-bit Page Size Extension"); - end if; - - -- MMX technology supported - if Features.MMX = True then - Ada.Text_IO.Put_Line (" MMX - MMX technology supported"); - end if; - - -- Fast FP Save and Restore - if Features.FXSR = True then - Ada.Text_IO.Put_Line (" FXSR - Fast FP Save and Restore"); - end if; - - --------------------- - -- Program done. -- - --------------------- - - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - - exception - - when others => - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Failure); - raise; - - end Check_CPU; - -  - File: gnat_ug_vxw.info, Node: Intel_CPU Package Specification, Next: Intel_CPU Package Body, Prev: Check_CPU Procedure, Up: A Complete Example - - `Intel_CPU' Package Specification - --------------------------------- - - ------------------------------------------------------------------------- - -- -- - -- file: intel_cpu.ads -- - -- -- - -- ********************************************* -- - -- * WARNING: for 32-bit Intel processors only * -- - -- ********************************************* -- - -- -- - -- This package contains a number of subprograms that are useful in -- - -- determining the Intel x86 CPU (and the features it supports) on -- - -- which the program is running. -- - -- -- - -- The package is based upon the information given in the Intel -- - -- Application Note AP-485: "Intel Processor Identification and the -- - -- CPUID Instruction" as of April 1998. This application note can be -- - -- found on www.intel.com. -- - -- -- - -- It currently deals with 32-bit processors only, will not detect -- - -- features added after april 1998, and does not guarantee proper -- - -- results on Intel-compatible processors. -- - -- -- - -- Cache info and x386 fpu type detection are not supported. -- - -- -- - -- This package does not use any privileged instructions, so should -- - -- work on any OS running on a 32-bit Intel processor. -- - -- -- - ------------------------------------------------------------------------- - - with Interfaces; use Interfaces; - -- for using unsigned types - - with System.Machine_Code; use System.Machine_Code; - -- for using inline assembler code - - with Ada.Characters.Latin_1; use Ada.Characters.Latin_1; - -- for inserting control characters - - package Intel_CPU is - - ---------------------- - -- Processor bits -- - ---------------------- - - subtype Num_Bits is Natural range 0 .. 31; - -- the number of processor bits (32) - - -------------------------- - -- Processor register -- - -------------------------- - - -- define a processor register type for easy access to - -- the individual bits - - type Processor_Register is array (Num_Bits) of Boolean; - pragma Pack (Processor_Register); - for Processor_Register'Size use 32; - - ------------------------- - -- Unsigned register -- - ------------------------- - - -- define a processor register type for easy access to - -- the individual bytes - - type Unsigned_Register is - record - L1 : Unsigned_8; - H1 : Unsigned_8; - L2 : Unsigned_8; - H2 : Unsigned_8; - end record; - - for Unsigned_Register use - record - L1 at 0 range 0 .. 7; - H1 at 0 range 8 .. 15; - L2 at 0 range 16 .. 23; - H2 at 0 range 24 .. 31; - end record; - - for Unsigned_Register'Size use 32; - - --------------------------------- - -- Intel processor vendor ID -- - --------------------------------- - - Intel_Processor : constant String (1 .. 12) := "GenuineIntel"; - -- indicates an Intel manufactured processor - - ------------------------------------ - -- Processor signature register -- - ------------------------------------ - - -- a register type to hold the processor signature - - type Processor_Signature is - record - Stepping : Natural range 0 .. 15; - Model : Natural range 0 .. 15; - Family : Natural range 0 .. 15; - Processor_Type : Natural range 0 .. 3; - Reserved : Natural range 0 .. 262143; - end record; - - for Processor_Signature use - record - Stepping at 0 range 0 .. 3; - Model at 0 range 4 .. 7; - Family at 0 range 8 .. 11; - Processor_Type at 0 range 12 .. 13; - Reserved at 0 range 14 .. 31; - end record; - - for Processor_Signature'Size use 32; - - ----------------------------------- - -- Processor features register -- - ----------------------------------- - - -- a processor register to hold the processor feature flags - - type Processor_Features is - record - FPU : Boolean; -- floating point unit on chip - VME : Boolean; -- virtual mode extension - DE : Boolean; -- debugging extension - PSE : Boolean; -- page size extension - TSC : Boolean; -- time stamp counter - MSR : Boolean; -- model specific registers - PAE : Boolean; -- physical address extension - MCE : Boolean; -- machine check extension - CX8 : Boolean; -- cmpxchg8 instruction - APIC : Boolean; -- on-chip apic hardware - Res_1 : Boolean; -- reserved for extensions - SEP : Boolean; -- fast system call - MTRR : Boolean; -- memory type range registers - PGE : Boolean; -- page global enable - MCA : Boolean; -- machine check architecture - CMOV : Boolean; -- conditional move supported - PAT : Boolean; -- page attribute table - PSE_36 : Boolean; -- 36-bit page size extension - Res_2 : Natural range 0 .. 31; -- reserved for extensions - MMX : Boolean; -- MMX technology supported - FXSR : Boolean; -- fast FP save and restore - Res_3 : Natural range 0 .. 127; -- reserved for extensions - end record; - - for Processor_Features use - record - FPU at 0 range 0 .. 0; - VME at 0 range 1 .. 1; - DE at 0 range 2 .. 2; - PSE at 0 range 3 .. 3; - TSC at 0 range 4 .. 4; - MSR at 0 range 5 .. 5; - PAE at 0 range 6 .. 6; - MCE at 0 range 7 .. 7; - CX8 at 0 range 8 .. 8; - APIC at 0 range 9 .. 9; - Res_1 at 0 range 10 .. 10; - SEP at 0 range 11 .. 11; - MTRR at 0 range 12 .. 12; - PGE at 0 range 13 .. 13; - MCA at 0 range 14 .. 14; - CMOV at 0 range 15 .. 15; - PAT at 0 range 16 .. 16; - PSE_36 at 0 range 17 .. 17; - Res_2 at 0 range 18 .. 22; - MMX at 0 range 23 .. 23; - FXSR at 0 range 24 .. 24; - Res_3 at 0 range 25 .. 31; - end record; - - for Processor_Features'Size use 32; - - ------------------- - -- Subprograms -- - ------------------- - - function Has_FPU return Boolean; - -- return True if a FPU is found - -- use only if CPUID is not supported - - function Has_CPUID return Boolean; - -- return True if the processor supports the CPUID instruction - - function CPUID_Level return Natural; - -- return the CPUID support level (0, 1 or 2) - -- can only be called if the CPUID instruction is supported - - function Vendor_ID return String; - -- return the processor vendor identification string - -- can only be called if the CPUID instruction is supported - - function Signature return Processor_Signature; - -- return the processor signature - -- can only be called if the CPUID instruction is supported - - function Features return Processor_Features; - -- return the processors features - -- can only be called if the CPUID instruction is supported - - private - - ------------------------ - -- EFLAGS bit names -- - ------------------------ - - ID_Flag : constant Num_Bits := 21; - -- ID flag bit - - end Intel_CPU; - -  - File: gnat_ug_vxw.info, Node: Intel_CPU Package Body, Prev: Intel_CPU Package Specification, Up: A Complete Example - - `Intel_CPU' Package Body - ------------------------ - - package body Intel_CPU is - - --------------------------- - -- Detect FPU presence -- - --------------------------- - - -- There is a FPU present if we can set values to the FPU Status - -- and Control Words. - - function Has_FPU return Boolean is - - Register : Unsigned_16; - -- processor register to store a word - - begin - - -- check if we can change the status word - Asm ( - - -- the assembler code - "finit" & LF & HT & -- reset status word - "movw $0x5A5A, %%ax" & LF & HT & -- set value status word - "fnstsw %0" & LF & HT & -- save status word - "movw %%ax, %0", -- store status word - - -- output stored in Register - -- register must be a memory location - Outputs => Unsigned_16'Asm_output ("=m", Register), - - -- tell compiler that we used eax - Clobber => "eax"); - - -- if the status word is zero, there is no FPU - if Register = 0 then - return False; -- no status word - end if; -- check status word value - - -- check if we can get the control word - Asm ( - - -- the assembler code - "fnstcw %0", -- save the control word - - -- output into Register - -- register must be a memory location - Outputs => Unsigned_16'Asm_output ("=m", Register)); - - -- check the relevant bits - if (Register and 16#103F#) /= 16#003F# then - return False; -- no control word - end if; -- check control word value - - -- FPU found - return True; - - end Has_FPU; - - -------------------------------- - -- Detect CPUID instruction -- - -------------------------------- - - -- The processor supports the CPUID instruction if it is possible - -- to change the value of ID flag bit in the EFLAGS register. - - function Has_CPUID return Boolean is - - Original_Flags, Modified_Flags : Processor_Register; - -- EFLAG contents before and after changing the ID flag - - begin - - -- try flipping the ID flag in the EFLAGS register - Asm ( - - -- the assembler code - "pushfl" & LF & HT & -- push EFLAGS on stack - "pop %%eax" & LF & HT & -- pop EFLAGS into eax - "movl %%eax, %0" & LF & HT & -- save EFLAGS content - "xor $0x200000, %%eax" & LF & HT & -- flip ID flag - "push %%eax" & LF & HT & -- push EFLAGS on stack - "popfl" & LF & HT & -- load EFLAGS register - "pushfl" & LF & HT & -- push EFLAGS on stack - "pop %1", -- save EFLAGS content - - -- output values, may be anything - -- Original_Flags is %0 - -- Modified_Flags is %1 - Outputs => - (Processor_Register'Asm_output ("=g", Original_Flags), - Processor_Register'Asm_output ("=g", Modified_Flags)), - - -- tell compiler eax is destroyed - Clobber => "eax"); - - -- check if CPUID is supported - if Original_Flags(ID_Flag) /= Modified_Flags(ID_Flag) then - return True; -- ID flag was modified - else - return False; -- ID flag unchanged - end if; -- check for CPUID - - end Has_CPUID; - - ------------------------------- - -- Get CPUID support level -- - ------------------------------- - - function CPUID_Level return Natural is - - Level : Unsigned_32; - -- returned support level - - begin - - -- execute CPUID, storing the results in the Level register - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- zero is stored in eax - -- returning the support level in eax - Inputs => Unsigned_32'Asm_input ("a", 0), - - -- eax is stored in Level - Outputs => Unsigned_32'Asm_output ("=a", Level), - - -- tell compiler ebx, ecx and edx registers are destroyed - Clobber => "ebx, ecx, edx"); - - -- return the support level - return Natural (Level); - - end CPUID_Level; - - -------------------------------- - -- Get CPU Vendor ID String -- - -------------------------------- - - -- The vendor ID string is returned in the ebx, ecx and edx register - -- after executing the CPUID instruction with eax set to zero. - -- In case of a true Intel processor the string returned is - -- "GenuineIntel" - - function Vendor_ID return String is - - Ebx, Ecx, Edx : Unsigned_Register; - -- registers containing the vendor ID string - - Vendor_ID : String (1 .. 12); - -- the vendor ID string - - begin - - -- execute CPUID, storing the results in the processor registers - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- zero stored in eax - -- vendor ID string returned in ebx, ecx and edx - Inputs => Unsigned_32'Asm_input ("a", 0), - - -- ebx is stored in Ebx - -- ecx is stored in Ecx - -- edx is stored in Edx - Outputs => (Unsigned_Register'Asm_output ("=b", Ebx), - Unsigned_Register'Asm_output ("=c", Ecx), - Unsigned_Register'Asm_output ("=d", Edx))); - - -- now build the vendor ID string - Vendor_ID( 1) := Character'Val (Ebx.L1); - Vendor_ID( 2) := Character'Val (Ebx.H1); - Vendor_ID( 3) := Character'Val (Ebx.L2); - Vendor_ID( 4) := Character'Val (Ebx.H2); - Vendor_ID( 5) := Character'Val (Edx.L1); - Vendor_ID( 6) := Character'Val (Edx.H1); - Vendor_ID( 7) := Character'Val (Edx.L2); - Vendor_ID( 8) := Character'Val (Edx.H2); - Vendor_ID( 9) := Character'Val (Ecx.L1); - Vendor_ID(10) := Character'Val (Ecx.H1); - Vendor_ID(11) := Character'Val (Ecx.L2); - Vendor_ID(12) := Character'Val (Ecx.H2); - - -- return string - return Vendor_ID; - - end Vendor_ID; - - ------------------------------- - -- Get processor signature -- - ------------------------------- - - function Signature return Processor_Signature is - - Result : Processor_Signature; - -- processor signature returned - - begin - - -- execute CPUID, storing the results in the Result variable - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- one is stored in eax - -- processor signature returned in eax - Inputs => Unsigned_32'Asm_input ("a", 1), - - -- eax is stored in Result - Outputs => Processor_Signature'Asm_output ("=a", Result), - - -- tell compiler that ebx, ecx and edx are also destroyed - Clobber => "ebx, ecx, edx"); - - -- return processor signature - return Result; - - end Signature; - - ------------------------------ - -- Get processor features -- - ------------------------------ - - function Features return Processor_Features is - - Result : Processor_Features; - -- processor features returned - - begin - - -- execute CPUID, storing the results in the Result variable - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- one stored in eax - -- processor features returned in edx - Inputs => Unsigned_32'Asm_input ("a", 1), - - -- edx is stored in Result - Outputs => Processor_Features'Asm_output ("=d", Result), - - -- tell compiler that ebx and ecx are also destroyed - Clobber => "ebx, ecx"); - - -- return processor signature - return Result; - - end Features; - - end Intel_CPU; - -  - File: gnat_ug_vxw.info, Node: VxWorks Topics, Next: LynxOS Topics, Prev: Inline Assembler, Up: Top - - VxWorks Topics - ************** - - This chapter describes topics that are specific to the GNAT for VxWorks - configurations. - - * Menu: - - * Kernel Configuration for VxWorks:: - * Kernel Compilation Issues for VxWorks:: - * Handling Relocation Issues for PowerPc Targets:: - * Support for Software Floating Point on PowerPC Processors:: - * Interrupt Handling for VxWorks:: - * Simulating Command Line Arguments for VxWorks:: - * Debugging Issues for VxWorks:: - * Using GNAT from the Tornado 2 Project Facility:: - * Frequently Asked Questions for VxWorks:: - -  - File: gnat_ug_vxw.info, Node: Kernel Configuration for VxWorks, Next: Kernel Compilation Issues for VxWorks, Up: VxWorks Topics - - Kernel Configuration for VxWorks - ================================ - - When configuring your VxWorks kernel we recommend including the target - shell. If you omit it from the configuration, you may get undefined - symbols at load time, e.g. - - -> ld < hello.exe - Loading hello.exe - Undefined symbols: - mkdir - - Generally, such undefined symbols are harmless since these are used by - optional parts of the GNAT run time. However if running your application - generates a VxWorks exception or illegal instruction, you should - reconfigure your kernel to resolve these symbols. - -  - File: gnat_ug_vxw.info, Node: Kernel Compilation Issues for VxWorks, Next: Handling Relocation Issues for PowerPc Targets, Prev: Kernel Configuration for VxWorks, Up: VxWorks Topics - - Kernel Compilation Issues for VxWorks - ===================================== - - If you plan to link an Ada module with a Tornado 2 Kernel, follow these - steps. (Note that these recommendations apply to `cygnus-2.7.2-960126', - shipped with Tornado 2 as the C compiler toolchain.) - - * Compile your Ada module without linking it with the VxWorks - Library: - gnatmake foo.adb -largs -nostdlib - - * Edit your makefile and add on the `LIBS' line the exact path and - name of the GCC library file provided with GNAT. - LIBS = $(WIND_BASE)/target/lib/libPPC604gnuvx.a \ - /opt/gnu/gnat/lib/gcc-lib/powerpc-wrs-vxworks/2.8.1/libgcc.a - - To know the exact name and location of this file, type `-gcc - -print-libgcc-file-name' in a console. Note that this version of - GCC is the one provided with GNAT. - ~ >powerpc-wrs-vxworks-gcc -print-libgcc-file-name - /opt/gnu/gnat/lib/gcc-lib/powerpc-wrs-vxworks/2.8.1/libgcc.a - -  - File: gnat_ug_vxw.info, Node: Handling Relocation Issues for PowerPc Targets, Next: Support for Software Floating Point on PowerPC Processors, Prev: Kernel Compilation Issues for VxWorks, Up: VxWorks Topics - - Handling Relocation Issues for PowerPc Targets - ============================================== - - Under certain circumstances, loading a program onto a PowerPC board - will fail with the message _Relocation value does not fit in 24 bits_. - - For some background on this issue, please refer to WRS' SPRs 6040, - 20257, and 22767. In summary, VxWorks on the PowerPC follows the - variation of the SVR4 ABI known as the Embedded ABI (_EABI_). In order - to save space and time in embedded applications, the EABI specifies - that the default for subprogram calls should be the branch instruction - with relative addressing using an immediate operand. The immediate - operand to this instruction (relative address) is 24 bits wide. It is - sign extended and 2#00# is appended for the last 2 bits (all - instructions must be on a 4 byte boundary). The resulting 26 bit - offset means that the target of the branch must be within +/- 32 Mbytes - of the relative branch instruction. When VxWorks is loading a program - it completes the linking phase by resolving all of the unresolved - references in the object being loaded. When one of those references is - a relative address in a branch instruction, and the linker determines - that the target is more than 32 Mbytes away from the branch, the error - occurs. - - This only happens when the BSP is configured to use more than 32 - MBytes of memory. The VxWorks kernel is loaded into low memory - addresses, and the error usually occurs when the target loader is used - (because it loads objects into high memory, and thus calls from the - program to the VxWorks kernel can be too far). - - One way to solve this problem is to use the Tornado host loader; - this will place programs in low memory, close to the kernel. - - Another approach is to make use of the `-mlongcall' option to the - compiler; GNAT has incorporated WRS' gcc modification that implements - this option. If a subprogram call is compiled with the `-mlongcall' - option, then the generated code constructs an absolute address in a - register and uses a branch instruction with absolute addressing mode. - - Starting with release 3.15, the GNAT runtime libraries that are - distributed are compiled with the `-mlongcall' option. In many cases - the use of these libraries is sufficient to avoid the relocation - problem, since it is the runtime library that contains calls to the - VxWorks kernel that need to span the address space gap. If you are - using an earlier GNAT release or a manually-built runtime, you should - recompile the GNAT runtime library with `-mlongcall'; you can use the - `Makefile.adalib' file from the `adalib' directory. - - Application code may need to be compiled with `-mlongcall' if there - are calls directly to the kernel, the application is very large, or in - some specialized linking/loading scenarios. - - You can compile individual files with `-mlongcall' by placing this - option on the `gcc' command line (for brevity we are omitting the - `powerpc-wrs-vxworks-' prefix on the commands shown in this paragraph). - If you provide `-mlongcall' as an option for `gnatmake', it will be - passed to all invocations of `gcc' that `gnatmake' directly performs. - Note that one other compilation is made by `gnatlink', on the file - created by `gnatbind' for the elaboration package body (see *Note - Binding Using gnatbind::). Passing `-mlongcall' to `gnatlink', either - directly on the `gnatlink' command line or by including `-mlongcall' in - the `-largs' list of `gnatmake', will direct `gnatlink' to compile the - binder file with the `-mlongcall' option. - - To see the effect of `-mlongcall', consider the following small - example: - - procedure Proc is - procedure Imported_Proc; - pragma Import (Ada, Imported_Proc); - begin - Imported_Proc; - end; - - If you compile `Proc' with the default options (no `-mlongcall'), the - following code is generated: - - _ada_proc: - ... - bl imported_proc - ... - - In contrast, here is the result with the `-mlongcall' option: - - _ada_proc: - ... - addis 9,0,imported_proc@ha - addi 0,9,imported_proc@l - mtlr 0 - blrl - ... - -  - File: gnat_ug_vxw.info, Node: Support for Software Floating Point on PowerPC Processors, Next: Interrupt Handling for VxWorks, Prev: Handling Relocation Issues for PowerPc Targets, Up: VxWorks Topics - - Support for Software Floating Point on PowerPC Processors - ========================================================= - - The PowerPC 860 processor does not have hardware floating-point support. - In order to build and run GNAT modules properly, you need to install and - invoke software-emulated floating-point support as follows: - - * At installation time: - * Create a file `ada_object_path' under the directory - `BASE\lib\gcc-lib\powerpc-wrs-vxworks\2.8.1' (by default - `BASE'=`c:\gnatpro') containing the following line: - rts-soft-float\adalib - - * Create a file `ada_source_path' under the directory - `BASE\lib\gcc-lib\powerpc-wrs-vxworks\2.8.1' (by default - `BASE'=`c:\gnatpro') containing the following line: - rts-soft-float\adainclude - - * When using the compiler, specify `-msoft-float' as a compiler and - a linker option, e.g.: - $powerpc-wrs-vxworks-gnatmake -msoft-float module -largs -msoft-float - -  - File: gnat_ug_vxw.info, Node: Interrupt Handling for VxWorks, Next: Simulating Command Line Arguments for VxWorks, Prev: Support for Software Floating Point on PowerPC Processors, Up: VxWorks Topics - - Interrupt Handling for VxWorks - ============================== - - GNAT offers a range of options for hardware interrupt handling. In rough - order of latency and lack of restrictions: - - * Directly vectored interrupt procedure handlers - - * Directly vectored interrupt procedures that signal a task using a - suspension object - - * Ada 95 protected procedure handlers for interrupts - - * Ada 83 style interrupt entry handlers for interrupts - - In general, the range of possible solutions trades off latency versus - restrictions in the handler code. Restrictions in direct vectored - interrupt handlers are documented in the `VxWorks Programmer's Guide'. - Protected procedure handlers have only the restriction that no - potentially blocking operations are performed within the handler. - Interrupt entries have no restrictions. We recommend the use of the - protected procedure mechanism as providing the best balance of these - considerations for most applications. - - All handler types must explicitly perform any required hardware - cleanups, such as issuing an end-of-interrupt if necessary. - - For VxWorks/AE, applications that handle interrupts must be loaded - into the kernel protection domain. - - * Direct Vectored Interrupt Routines - - This approach provides the lowest interrupt latency, but has the - most restrictions on what VxWorks and Ada runtime calls can be - made, as well as on what Ada entities are accessible to the - handler code. Such handlers are most useful when there are - stringent latency requirements, and very little processing is to - be performed in the handler. Access to the necessary VxWorks - routines for setting up such handlers is provided in the package - `Interfaces.VxWorks'. - - VxWorks restrictions are described in the `VxWorks Programmer's - Manual'. Note in particular that floating point context is not - automatically saved and restored when interrupts are vectored to - the handler. If the handler is to execute floating point - instructions, the statements involved must be bracketed by a pair - of calls to `fppSave' and `fppRestore' defined in - `Interfaces.VxWorks'. - - In general, it is a good idea to save and restore the handler that - was installed prior to application startup. The routines - `intVecGet' and `intVecSet' are used for this purpose. The Ada - handler code is installed into the vector table using routine - `intConnect', which generates wrapper code to save and restore - registers. - - Example: - - with Interfaces.VxWorks; use Interfaces.VxWorks; - with System; - - package P is - - Count : Natural := 0; - pragma Atomic (Count); - - -- Interrupt level used by this example - Level : constant := 1; - - -- Be sure to use a reasonable interrupt number for the target - -- board! Refer to the BSP for details. - Interrupt : constant := 16#14#; - - procedure Handler (Parameter : System.Address); - - end P; - - package body P is - - procedure Handler (parameter : System.Address) is - S : Status; - begin - Count := Count + 1; - -- Acknowledge interrupt. Not necessary for all interrupts. - S := sysBusIntAck (intLevel => Level); - end Handler; - end P; - - with Interfaces.VxWorks; use Interfaces.VxWorks; - with Ada.Text_IO; use Ada.Text_IO; - - with P; use P; - procedure Useint is - task T; - - S : Status; - - task body T is - begin - for I in 1 .. 10 loop - Put_Line ("Generating an interrupt..."); - delay 1.0; - - -- Generate interrupt, using interrupt number - S := sysBusIntGen (Level, Interrupt); - end loop; - end T; - - -- Save old handler - Old_Handler : VOIDFUNCPTR := intVecGet (INUM_TO_IVEC (Interrupt)); - begin - S := intConnect (INUM_TO_IVEC (Interrupt), Handler'Access); - S := sysIntEnable (intLevel => Level); - - for I in 1 .. 10 loop - delay 2.0; - Put_Line ("value of count:" & P.Count'Img); - end loop; - - -- Restore previous handler - S := sysIntDisable (intLevel => Level); - intVecSet (INUM_TO_IVEC (Interrupt), Old_Handler); - end Useint; - - * Direct Vectored Interrupt Routines - - A variation on the direct vectored routine that allows for less - restrictive handler code is to separate the interrupt processing - into two levels. - - The first level is the same as in the previous section. Here we - perform simple hardware actions and signal a task pending on a - Suspension_Object (defined in `Ada.Synchronous_Task_Control') to - perform the more complex and time-consuming operations. The - routine `Set_True' signals a task whose body loops and pends on - the suspension object using `Suspend_Until_True'. The suspension - object is declared in a scope global to both the handler and the - task. This approach can be thought of as a slightly higher-level - application of the `C' example using a binary semaphore given in - the VxWorks Programmer's Manual. In fact, the implementation of - `Ada.Synchronous_Task_Control' is a very thin wrapper around a - VxWorks binary semaphore. - - This approach has a latency between the direct vectored approach - and the protected procedure approach. There are no restrictions - in the Ada task code, while the handler code has the same - restrictions as any other direct interrupt handler. - - Example: - - with System; - package Sem_Handler is - - Count : Natural := 0; - pragma Atomic (Count); - - -- Interrupt level used by this example - Level : constant := 1; - Interrupt : constant := 16#14#; - - -- Interrupt handler providing "immediate" handling - procedure Handler (Param : System.Address); - - -- Task whose body provides "deferred" handling - task Receiver is - pragma Interrupt_Priority - (System.Interrupt_Priority'First + Level + 1); - end Receiver; - - end Sem_Handler; - - with Ada.Synchronous_Task_Control; use Ada.Synchronous_Task_Control; - with Interfaces.VxWorks; use Interfaces.VxWorks; - package body Sema_Handler is - - SO : Suspension_Object; - - task body Receiver is - begin - loop - -- Wait for notification from immediate handler - Suspend_Until_True (SO); - - -- Interrupt processing - Count := Count + 1; - end loop; - end Receiver; - - procedure Handler (Param : System.Address) is - S : STATUS; - begin - -- Hardware cleanup, if necessary - S := sysBusIntAck (Level); - - -- Signal the task - Set_True (SO); - end Handler; - - end Sem_Handler; - - with Interfaces.VxWorks; use Interfaces.VxWorks; - with Ada.Text_IO; use Ada.Text_IO; - with Sem_Handler; use Sem_Handler; - procedure Useint is - - S : STATUS; - - task T; - - task body T is - begin - for I in 1 .. 10 loop - Put_Line ("Generating an interrupt..."); - delay 1.0; - - -- Generate interrupt, using interrupt number - S := sysBusIntGen (Level, Interrupt); - end loop; - end T; - - -- Save old handler - Old_Handler : VOIDFUNCPTR := intVecGet (INUM_TO_IVEC (Interrupt)); - begin - S := intConnect (INUM_TO_IVEC (Interrupt), Handler'Access); - S := sysIntEnable (intLevel => Level); - - for I in 1 .. 10 loop - delay 2.0; - Put_Line ("value of Count:" & Sem_Handler.Count'Img); - end loop; - - -- Restore handler - S := sysIntDisable (intLevel => Level); - intVecSet (INUM_TO_IVEC (Interrupt), Old_Handler); - abort Receiver; - end Useint; - - * Protected Procedure Handlers for Interrupts - - This is the recommended default mechanism for interrupt handling. - It essentially wraps the hybrid handler / task mechanism in a - higher-level abstraction, and provides a good balance between - latency and capability. - - Vectored interrupts are designated by their interrupt number, - starting from 0 and ranging to the number of entries in the - interrupt vector table - 1. - - In the GNAT VxWorks implementation, the following priority - mappings are used: - * Normal task priorities are in the range 0 .. 245. - - * Interrupt priority 246 is used by the GNAT `Interrupt_Manager' - task. - - * Interrupt priority 247 is used for vectored interrupts that - do not correspond to those generated via an interrupt - controller. - - * Interrupt priorities 248 .. 255 correspond to PIC interrupt - levels 0 .. 7. - - * Priority 256 is reserved to the VxWorks kernel. - - Except for reserved priorities, the above are recommendations for - setting the ceiling priority of a protected object that handles - interrupts, or the priority of a task with interrupt entries. - It's a very good idea to follow these recommendations for vectored - interrupts that come in through the PIC as it will determine the - priority of execution of the code in the protected procedure or - interrupt entry. - - No vectored interrupt numbers are reserved in this implementation, - because dedicated interrupts are determined by the board support - package. Obviously, careful consideration of the hardware is - necessary when handling interrupts. The VxWorks BSP for the board - is the definitive reference for interrupt assignments. - - Example: - - package PO_Handler is - - -- Interrupt level used by this example - Level : constant := 1; - - Interrupt : constant := 16#14#; - - protected Protected_Handler is - procedure Handler; - pragma Attach_Handler (Handler, Interrupt); - - function Count return Natural; - - pragma Interrupt_Priority (248); - private - The_Count : Natural := 0; - end Protected_Handler; - - end PO_Handler; - - with Interfaces.VxWorks; use Interfaces.VxWorks; - package body PO_Handler is - - protected body Protected_Handler is - - procedure Handler is - S : Status; - begin - -- Hardware cleanup if necessary - S := sysBusIntAck (Level); - - -- Interrupt processing - The_Count := The_Count + 1; - end Handler; - - function Count return Natural is - begin - return The_Count; - end Count; - end Protected_Handler; - - end PO_Handler; - - with Interfaces.VxWorks; use Interfaces.VxWorks; - with Ada.Text_IO; use Ada.Text_IO; - - with PO_Handler; use PO_Handler; - procedure Useint is - - task T; - - S : STATUS; - - task body T is - begin - for I in 1 .. 10 loop - Put_Line ("Generating an interrupt..."); - delay 1.0; - - -- Generate interrupt, using interrupt number - S := sysBusIntGen (Level, Interrupt); - end loop; - end T; - - begin - S := sysIntEnable (intLevel => Level); - - for I in 1 .. 10 loop - delay 2.0; - Put_Line ("value of count:" & Protected_Handler.Count'Img); - end loop; - - S := sysIntDisable (intLevel => Level); - end Useint; - - This is obviously significantly higher-level and easier to write - than the previous examples. - - * Ada 83 Style Interrupt Entries - - GNAT provides a full implementation of the Ada 83 interrupt entry - mechanism for vectored interrupts. However, due to latency issues, - we only recommend using these for backward compatibility. The - comments in the previous section regarding interrupt priorities - and reserved interrupts apply here. - - In order to associate an interrupt with an entry, GNAT provides the - standard Ada convenience routine `Ada.Interrupts.Reference'. It - is used as follows: - - Interrupt_Address : constant System.Address := - Ada.Interrupts.Reference (Int_Num); - - task Handler_Task is - pragma Interrupt_Priority (248); -- For instance - entry Handler; - for Handler'Address use Interrupt_Address; - end Handler_Task; - - Since there is no restriction within an interrupt entry on - blocking operations, be sure to perform any hardware interrupt - controller related operations before executing a call that could - block within the entry's accept statements. It is assumed that - interrupt entries are always open alternatives when they appear - within a selective wait statement. The presence of a guard gives - undefined behavior. - - Example: - - with Ada.Interrupts; - with System; - package Task_Handler is - - -- Interrupt level used by this example - Level : constant := 1; - - Interrupt : constant := 16#14#; - - Interrupt_Address : constant System.Address := - Ada.Interrupts.Reference (Int_Num); - - task Handler_Task is - pragma Interrupt_Priority (248); -- For instance - entry Handler; - for Handler'Address use Interrupt_Address; - - entry Count (Value : out Natural); - end Handler_Task; - end Task_Handler; - - with Interfaces.VxWorks; use Interfaces.VxWorks; - package body Task_Handler is - - task body Handler_Task is - The_Count : Natural := 0; - S : STATUS; - begin - loop - select - accept Handler do - -- Hardware cleanup if necessary - S := sysBusIntAck (Level); - - -- Interrupt processing - The_Count := The_Count + 1; - end Handler; - or - accept Count (Value : out Natural) do - Value := The_Count; - end Count; - end select; - end loop; - end Handler_Task; - - end Handler_Task; - - with Interfaces.VxWorks; use Interfaces.VxWorks; - with Ada.Text_IO; use Ada.Text_IO; - - with Handler_Task; use Handler_Task; - procedure Useint is - - task T; - - S : STATUS; - Current_Count : Natural := 0; - - task body T is - begin - for I in 1 .. 10 loop - Put_Line ("Generating an interrupt..."); - delay 1.0; - - -- Generate interrupt, using interrupt number - S := sysBusIntGen (Level, Interrupt); - end loop; - end T; - - begin - S := sysIntEnable (intLevel => Level); - - for I in 1 .. 10 loop - delay 2.0; - Handler_Task.Count (Current_Count); - Put_Line ("value of count:" & Current_Count'Img); - end loop; - - S := sysIntDisable (intLevel => Level); - abort Handler_Task; - end Useint; - -  - File: gnat_ug_vxw.info, Node: Simulating Command Line Arguments for VxWorks, Next: Debugging Issues for VxWorks, Prev: Interrupt Handling for VxWorks, Up: VxWorks Topics - - Simulating Command Line Arguments for VxWorks - ============================================= - - The GNAT implementation of `Ada.Command_Line' relies on the standard C - symbols `argv' and `argc'. The model for invoking "programs" under - VxWorks does not provide these symbols. The typical method for - invoking a program under VxWorks is to call the `sp' function in order - to spawn a thread in which to execute a designated function (in GNAT, - this is the implicit main generated by gnatbind. `sp' provides the - capability to push a variable number of arguments onto the stack when - the function is invoked. But this does not work for the implicit Ada - main, because it has no way of knowing how many arguments might be - required. This eliminates the possibility to use `Ada.Command_Line'. - - One way to solve this problem is to define symbols in the VxWorks - environment, then import them into the Ada application. For example, - we could define the following package that imports two symbols, one an - int and the other a string: - - with Interfaces.C.Strings; - use Interfaces.C.Strings; - package Args is - -- Define and import a variable for each argument - Int_Arg : Interfaces.C.Int; - String_Arg : Chars_Ptr; - private - pragma Import (C, Int_Arg, "intarg"); - pragma Import (C, String_Arg, "stringarg"); - end Args; - - An Ada unit could then use the two imported variables `Int_Arg' and - `String_Arg' as follows: - - with Args; use Args; - with Interfaces.C.Strings; - use Interfaces.C, Interfaces.C.Strings; - with Ada.Text_IO; use Ada.Text_IO; - procedure Argtest is - begin - Put_Line (Int'Image (Int_Arg)); - Put_Line (Value (String_Arg)); - end Argtest; - - When invoking the application from the shell, one will then set the - values to be imported, and spawn the application, as follows: - - -> intarg=10 - -> stringarg="Hello" - -> sp (argtest) - -  - File: gnat_ug_vxw.info, Node: Debugging Issues for VxWorks, Next: Using GNAT from the Tornado 2 Project Facility, Prev: Simulating Command Line Arguments for VxWorks, Up: VxWorks Topics - - Debugging Issues for VxWorks - ============================ - - The debugger can be launched directly from the Tornado environment or - from `glide' through its graphical interface: `gvd'. It can also be used - directly in text mode as shown below: - - The command to run `GDB' in text mode is - - $ target-gdb - - where target is the name of target of the cross GNAT compiler. In - contrast with native `gdb', it is not useful to give the name of the - program to debug on the command line. Before starting a debugging - session, one needs to connect to the VxWorks-configured board and load - the relocatable object produced by `gnatlink'. This can be achieved by - the following commands: - - (vxgdb) target wtx myboard - (vxgdb) load program - - where `myboard' is the host name or IP number of the target board, and - `wtx' is the name of debugging protocol used to communicate with the - VxWorks board. Early versions of VxWorks, up tp 5.2, only support the - `' protocol whereas starting with VxWorks 5.3 and Tornado, - another protocol called `' was made available. The choice of the - protocol can be made when configuring the VxWorks kernel itself. When - available, the `' is greatly preferable and actually the only - supported protocol with GNAT. When the debugger is launched directly - from Tornado, the proper `target' command is automatically generated by - the environment. - - The GNAT debugger can be used for debugging multitasking programs in - two different modes and some minimal understanding of these modes is - necessary in order to use the debugger effectively. The two modes are: - - * Monotask mode: attach to, and debug, a single task. This mode is - equivalent to the capabilities offered by CrossWind. The debugger - interacts with a single task, while not affecting other tasks - (insofar as possible). This is the DEFAULT mode. - - * Multitask mode: The debugger has control over all Ada tasks in an - application. It is possible to gather information about all - application tasks, and to switch from one to another within a - single debugging session. - - It is not advised to switch between the two modes within a debugging - session. A third mode called System mode is also available and can be - used in place of the Multitask mode. Consult the Tornado documentation - for this. - - Among the criteria for selecting the appropriate mode is the effect - of task synchronization on the application's behavior. Debugging a - tasking application affects the timing of the application; minimizing - such effects may be critical in certain situations. The two modes have - different effects: monotask mode only affects the attached task: others - will run normally (if possible). Multitask mode stops all tasks at each - breakpoint and restarts them on single-step, next, finish or continue; - this may help avoid deadlocks in the presence of task synchronization - despite the inherent latency of stopping and restarting the tasks. - - Using the debugger in monotask mode - ----------------------------------- - - There are two ways to begin your debugging session: - - * The program is already running on the board. - - The sequence of commands to use this mode is: - * Launch GVD (possibly from the Tornado menu) - - Verify that the debugger has access to the debug information - of both your program and the kernel. The Console window - should have a message "Looking for all loaded modules:" - followed by the names of the modules on the board and "ok". - If you have some error messages here instead of "ok", the - debugging session may not work as expected. - - * Attach to the desired task using - File --> Attach... - - This task is stopped by the debugger. Other tasks continue to - operate normally (unless they are blocked by synchronization - with the stopped task). The source window should display the - code on which the task has been stopped, and if the stack - display is enabled, it should reflect the stack of the task. - - * The program hasn't been loaded yet on the board - * Launch GVD (possibly from the Tornado menu) - - * Load your program to the board: - File --> Open Program... - - GVD should display: - Downloading your_program ...done. - Reading symbols from your_program...expanding to full symbols...done. - - * Set breakpoints in your program. - - WARNING: they must be set in the main task (if your program - runs several tasks) - - * Run your program using one of the three methods below: - * Click on button or - - * Menu - Program --> Run/Start - - * Type in GVD's Console window - (gdb) run your_program - - * Whichever method you chose to start your debugging session, you - can use the following commands at this point: - * Browse sources and set breakpoints - - * Examine the call stack (Data -> call stack) - - * Go "up" and "down" in the call stack ("up" & "down" buttons) - - * Examine data (Data -> Display local variables, or any of the - other methods for viewing data in GVD) - - * Continue/finish - - Next/step/finish will only work if the top frame in the call stack - has debug information. This is almost never the case when first - attaching to the task since the task is usually stopped by the - attach operation in the GNAT runtime. You can verify which frames - of the call stack have debug information by: - Data --> call stack - (contextual menu inside the call stack window) - add "file location" - - If the current frame does not have a "file location", then there - is no debug information for the frame. We strongly recommended - that you set breakpoints in the source where debug information can - be found and "continue" until a breakpoint is reached before using - "next/step". Another convenient possibility is to use the "continue - until" capability available from the contextual menu of the Source - window. - - You can also examine the state of other tasks using - Data -> tasks - - but you can't "switch" to another task by clicking on the elements - of the task list. If you try to, you will get an error message in - GVD's console: - "Task switching is not allowed when multi-tasks mode is not active" - - Once you have completed your debugging session on the attached - task, you can detach from the task: - File --> detach - - The task resumes normal execution at this stage. WARNING: when you - detach from a task, be sure that you are in a frame where there is - debug information. Otherwise, the task won't resume properly. You - can then start another attach/detach cycle if you wish. - - Note that it is possible to launch several GVD sessions and - simultaneously attach each to a distinct task in monotask mode: - File --> New Debugger... (uncheck the box: Replace Current Debugger) - File --> Attach... (in the new window) - File --> detach - - Using the debugger in Multitask mode - ------------------------------------ - - The steps are as follows - - * Launch GVD (possibly from the Tornado menu) - - There are two possibilities: - * If the program is already loaded on the target board, you - need only verify that debug information has been found by the - debugger as described above. - - * Otherwise, load the program on the board using - File --> Open program - - * Set breakpoints in the desired parts of the program - - * Start the program - - The simplest way to start the debugger in multitask mode is to use - the menu - Program --> Run/Start - - and check the box "enable vxWorks multi-tasks mode". You can also - use the following gdb commands in the console window - (gdb) set multi-tasks-mode on - (gdb) run your_program - - * Debug the stopped program - - Once stopped at a breakpoint (or if you pressed the "stop" - button), you can use all the standard commands listed for monotask - mode + task switching (using Data -> tasks). Using next/step under - this mode is possible with the same restrictions as for monotask - mode, but is not recommended because all tasks are restarted, - leading to the possibility that a different task hits a breakpoint - before the stepping operation has completed. Such an occurrence - can result in a confusing state for both the user and the - debugger. So we strongly suggest the use of only breakpoints and - "continue" in this mode. - - A final reminder: whatever the mode, whether you are debugging or - not, the program has to be reloaded before each new execution, so that - data initialized by the loader is set correctly. For instance, if you - wish to restart the same execution of the same program, you can use the - following sequence of gdb commands in the console window: - (gdb) detach - (gdb) unload your_program(.exe) - (gdb) load your_program(.exe) - (gdb) run your_program - -  - File: gnat_ug_vxw.info, Node: Using GNAT from the Tornado 2 Project Facility, Next: Frequently Asked Questions for VxWorks, Prev: Debugging Issues for VxWorks, Up: VxWorks Topics - - Using GNAT from the Tornado 2 Project Facility - ============================================== - - * Menu: - - * The GNAT Toolchain as Used from the Tornado 2 Project Facility:: - * Building a Simple Application:: - * Mixing C and Ada Code in a Tornado 2 Project:: - * Compilation Switches:: - * Autoscale and Minimal Kernel Configuration:: - * Adapting BSPs to GNAT:: - * Using GNAT Project Files in a Tornado 2 Project:: - - This section describes how to add an Ada module in a Tornado project - using the Tornado 2 Project facility described in `Tornado User's - Guide', Chapter 4. All recommendations apply for both 'Downloadable - Modules' and 'Kernel' project types. - -  - File: gnat_ug_vxw.info, Node: The GNAT Toolchain as Used from the Tornado 2 Project Facility, Next: Building a Simple Application, Up: Using GNAT from the Tornado 2 Project Facility - - The GNAT Toolchain as Used from the Tornado 2 Project Facility - -------------------------------------------------------------- - - Tornado 2 allows you to integrate third-party C toolchains. (`Tornado - 2 API Programmer's Guide', Chapter 7). Thus the GNAT toolchain will be - seen as a new C toolchain when used from the Tornado 2 Project - Facility. For each processor you can compile for, you will find a - gnat toolchain, e.g. PPC604gnat. These toolchains will allow you - to include Ada modules into your projects, and simply build them. - - The name of the so-called C compiler is _cc_gnat__, the name - of the 'linker' is _ld_gnat__, where is an architecture; - e.g., PPC. These scripts will call the correct executables during the - compilation or link processes, thus the C compiler, the C linker, or - the GNAT toolchain, depending on the context. - -  - File: gnat_ug_vxw.info, Node: Building a Simple Application, Next: Mixing C and Ada Code in a Tornado 2 Project, Prev: The GNAT Toolchain as Used from the Tornado 2 Project Facility, Up: Using GNAT from the Tornado 2 Project Facility - - Building a Simple Application - ----------------------------- - - First, create a new project, using one of the gnat toolchains. - - To add an Ada source file to the current project, just click on - `Project -> Add/Include', browse to the relevant file, and include it. - The Ada source file included should be the Ada entry point. Only one - Ada entry point is allowed in a project. Any other required Ada source - files will be automatically compiled and linked by the underlying tools. - - You can now compile the project, `Build->Rebuild all'. A log of the - compilation process can be found in the build directory, in - `gnatbuild.log'. It contains all the calls executed by the scripts, and - associated information. - -  - File: gnat_ug_vxw.info, Node: Mixing C and Ada Code in a Tornado 2 Project, Next: Compilation Switches, Prev: Building a Simple Application, Up: Using GNAT from the Tornado 2 Project Facility - - Mixing C and Ada Code in a Tornado 2 Project - -------------------------------------------- - - You can mix C and Ada code in your projects. Your source files and the - build options should comply with the recommendations from the section - `Interfacing to C'. This means that you can have several or no C - source files, and one or no Ada entry point in your Tornado 2 Project. - -  - File: gnat_ug_vxw.info, Node: Compilation Switches, Next: Autoscale and Minimal Kernel Configuration, Prev: Mixing C and Ada Code in a Tornado 2 Project, Up: Using GNAT from the Tornado 2 Project Facility - - Compilation Switches - -------------------- - - Once you have included all your source files, you may modify some - compilation and linking options. To pass specific options to the GNAT - toolchain, go to the Project's build settings, on the `C/C++ Compiler' - tab, and add your arguments in the input window. - - You must comply with several rules to pass arguments to GNAT. - Arguments to be passed should be - - * after any arguments passed to the C toolchain. - - * prefixed depending on the tool that uses them, with the following - syntax - - * `-cargs _gnatmake-options_' to pass arguments to gnatmake - - * `-bargs _gnatbind-options_' to pass arguments to gnatbind - - * `-largs _gnatlink-options_' to pass arguments to gnatlink - - You will find more information on the compilation process of Ada source - files in the section `The GNAT Compilation Model'. For a list of all - available switches, refer to the sections describing `gnatmake', - `gnatbind' and `gnatlink'. - - Here is an example that passes the option `-v' to the GNAT compiler : - -g -mstrict-align -prjtype $(PRJ_TYPE) -ansi -nostdinc -DRW_MULTI_THREAD -D_REENTRANT - -fvolatile -fno-builtin -fno-for-scope -I. -I/usr/windppc-2.0/target/h -DCPU=PPC604 - -cargs -v - - Here is an example that passes the option `-v' to the GNAT compiler, - binder and linker, and `-v' and `-g' to the compiler : - -g -mstrict-align -prjtype $(PRJ_TYPE) -ansi -nostdinc -DRW_MULTI_THREAD -D_REENTRANT - -fvolatile -fno-builtin -fno-for-scope -I. -I/usr/windppc-2.0/target/h -DCPU=PPC604 - -cargs -v -g -O2 -bargs -v -largs -v - - In both examples, the following arguments have been automatically added - by the Project Facility, and will be used by the C compiler. - -g -mstrict-align -prjtype $(PRJ_TYPE) -ansi -nostdinc -DRW_MULTI_THREAD -D_REENTRANT - -fvolatile -fno-builtin -fno-for-scope -I. -I/usr/windppc-2.0/target/h -DCPU=PPC604 - - Note: The `-prjtype $(PRJ_TYPE)' option present in a few input boxes is - used by the GNAT toolchain. It is required for the compilation process. - You should not remove it from any input box. - -  - File: gnat_ug_vxw.info, Node: Autoscale and Minimal Kernel Configuration, Next: Adapting BSPs to GNAT, Prev: Compilation Switches, Up: Using GNAT from the Tornado 2 Project Facility - - Autoscale and Minimal Kernel Configuration - ------------------------------------------ - - The Autoscale feature, present in the Project Facility can be used on - your VxWorks Kernel projects to determine the minimum set of components - required for your kernel to work. (Please refer to the `Tornado II - User's Guide' Section 4.4 for more details.) This feature is also - available for projects involving Ada code. Just click on - `Project->Autoscale' to launch a check and determine the minimal kernel - configuration. - -  - File: gnat_ug_vxw.info, Node: Adapting BSPs to GNAT, Next: Using GNAT Project Files in a Tornado 2 Project, Prev: Autoscale and Minimal Kernel Configuration, Up: Using GNAT from the Tornado 2 Project Facility - - Adapting BSPs to GNAT - --------------------- - - To use your Board Support Packages with the GNAT toolchain, you will - have to adapt them, either manually or using the `adaptbsp4gnat' script. - This procedure is described in the `Tornado API Programmer's Guide', - Chapter 7. Here is a summary of this setup, depending on the context. - - * To do the adaptation manually: - - * Copy your BSP directory contents into a new directory - - * Go to this directory - - * Edit the file `Makefile', - - * Set tool to gnat, `TOOL=gnat' - - * Reverse the order of the following lines - * `include $(TGT_DIR)/h/make/make.$(CPU)$(TOOL)' - - * `include $(TGT_DIR)/h/make/defs.$(WIND_HOST_TYPE)' - - - - * To do the adaptation automatically, you may use the `adaptbsp4gnat' - script. Its syntax is `adaptbsp4gnat '. - - This script follows the different steps described above to perform - the adaptation. The name of the new bsp is given after the - modification. By default, if `' is the name of your BSP, - `-gnat', will be the name of the BSP created. - -  - File: gnat_ug_vxw.info, Node: Using GNAT Project Files in a Tornado 2 Project, Prev: Adapting BSPs to GNAT, Up: Using GNAT from the Tornado 2 Project Facility - - Using GNAT Project Files in a Tornado 2 Project - ----------------------------------------------- - - You can use GNAT Project files to compile your Ada files. To do so, - you need to use the `-Pproject_file.gpr' option from `gnatmake'. The - path to the project file can be either absolute, or relative to the - build directory, i.e. where the executable will be placed (e.g. - `~/myproject/PPC604gnat'). Your project file should set the - `Object_Dir' variable to a specific value. - project Sample is - - Target := external ("TARGET_DIR"); - for Object_Dir use Target; - - end Sample; - -  - File: gnat_ug_vxw.info, Node: Frequently Asked Questions for VxWorks, Prev: Using GNAT from the Tornado 2 Project Facility, Up: VxWorks Topics - - Frequently Asked Questions for VxWorks - ====================================== - - * When I run my program twice on the board, it does not work, why? - - Usually, Ada programs require elaboration and finalization, so the - compiler creates a wrapper procedure whose name is the same as the - Ada name of the main subprogram, which takes care of calling the - elaboration and finalization routines before and after your - program. But the static part of the elaboration is taken care of - while loading the program itself and thus if you launch it twice - this part of the elaboration will not be performed. This affects - the proper elaboration of the GNAT runtime and thus it is - mandatory to reload your program before relaunching it. - - * Can I load a collection of subprograms rather than a standalone - program? - - It is possible to write Ada programs with multiple entry points - which can be called from the VxWorks shell; you just need to - consider your main program as the VxWorks shell itself and - generate an Ada subsystem callable from outside *Note Binding with - Non-Ada Main Programs::. If you use this method, you need to call - `adainit' manually before calling any Ada entry point. - - * When I use the `break exception' command, I get the message - `"exception" is not a function', why? - - You are not in the proper language mode. Issue the command: - (vxgdb) set language ada - - * When I load a large application from the VxWorks shell using the - "ld" command, the load hangs and never finishes. How can I load - large executables? - - This is a classic VxWorks problem when using the default "rsh" - communication method. Using NFS instead should work. Use the - `nfsShowMount' command to verify that your program is in a NFS - mounted directory. - - * When I load a large application from the debugger using the wtx - target connection, the load never finishes, why? - - Make sure that the memory cache size parameter of the target - server is large enough. (`target -m big_enough_size', or Memory - cache size box in GUI.) See `Tornado 1.01 API Programming Guide', - Section 3.6.2. - - * When I spawn my program under the VxWorks shell, interactive input - does not work, why? - - Only programs directly launched from the shell can have interactive - input. For a program spawned with the `sp' or `taskSpawn' command, - you need to have file redirection for input: - -> # here you can have interactive input - -> main - -> # here you cannot - -> sp main - -> # neither here - -> taskSpawn("ess",100,0,8000000,main) - -> # but you can input from a file: - -> taskSpawn("Bae",100,0,8000000,main) < input_file - -  - File: gnat_ug_vxw.info, Node: LynxOS Topics, Next: Performance Considerations, Prev: VxWorks Topics, Up: Top - - LynxOS Topics - ************* - - This chapter describes topics that are specific to the GNAT for LynxOS - cross configurations. - - * Menu: - - * Getting Started with GNAT on LynxOS:: - * Kernel Configuration for LynxOS:: - * Patch Level Issues for LynxOS:: - * Debugging Issues for LynxOS:: - * An Example Debugging Session for LynxOS:: - -  - File: gnat_ug_vxw.info, Node: Getting Started with GNAT on LynxOS, Next: Kernel Configuration for LynxOS, Up: LynxOS Topics - - Getting Started with GNAT on LynxOS - =================================== - - This section is a starting point for using GNAT to develop and execute - Ada 95 programs for LynuxWorks' LynxOS target environment from a Unix - host environment. We assume that you know how to use GNAT in a native - environment and how to start a telnet or other login session to connect - to your LynxOS board. - - To compile code for a LynxOS system running on a PowerPC board, the - basic compiler command is `powerpc-xcoff-lynxos-gcc'. - - With GNAT, the easiest way to build the basic `Hello World' program - is with `gnatmake'. For the LynxOS PowerPC target this would look like: - - $ powerpc-xcoff-lynxos-gnatmake hello - powerpc-xcoff-lynxos-gcc -c hello.adb - powerpc-xcoff-lynxos-gnatbind -x hello.ali - powerpc-xcoff-lynxos-gnatlink hello.ali - - (The first line is the command entered by the user - the subseqent three - are the programs run by `gnatmake'.) - - This creates the executable `hello'" which you then need to load on - the board (using ftp or an NFS directory for example) to run it. - -  - File: gnat_ug_vxw.info, Node: Kernel Configuration for LynxOS, Next: Patch Level Issues for LynxOS, Prev: Getting Started with GNAT on LynxOS, Up: LynxOS Topics - - Kernel Configuration for LynxOS - =============================== - - The appropriate configuration for your LynxOS kernel depends on the - target system and the requirements of your application. GNAT itself - adds no additional demands; however in some situations it may be - appropriate to increase the conservative resource assumptions made by - the default configuration. - - Kernel parameters limiting the maximum number of file descriptors, - kernel and user threads, synchronization objects, etc., may be set in - the file `uparam.h'. You may also wish to modify the file - `/etc/starttab', which places limits on data, stack, and core file - size. See the documentation provided by LynuxWorks for more information. - -  - File: gnat_ug_vxw.info, Node: Patch Level Issues for LynxOS, Next: Debugging Issues for LynxOS, Prev: Kernel Configuration for LynxOS, Up: LynxOS Topics - - Patch Level Issues for LynxOS - ============================= - - The GNAT runtime requires that your system run at patch level 040 or - later. Please see the file `PatchCompatibility.txt' from the - distribution for more information. - -  - File: gnat_ug_vxw.info, Node: Debugging Issues for LynxOS, Next: An Example Debugging Session for LynxOS, Prev: Patch Level Issues for LynxOS, Up: LynxOS Topics - - Debugging Issues for LynxOS - =========================== - - GNAT's debugger is based on the same GNU gdb technology as the debugger - provided by LynxOS, though with a great number of extensions and - enhancements to support the Ada language and GNAT. The LynxOS - documentation is relevant to understanding how to get the debugger - started if you run into difficulties. - - To demonstrate a debugging session, we will use a slightly more - complex program called `demo1.adb', which can be found in the `examples' - directory of the GNAT distribution. This program is compiled with - debugging information as follows: - - $ powerpc-xcoff-lynxos-gnatmake -g demo1 - powerpc-xcoff-lynxos-gcc -c -g demo1.adb - powerpc-xcoff-lynxos-gcc -c -g gen_list.adb - powerpc-xcoff-lynxos-gcc -c -g instr.adb - powerpc-xcoff-lynxos-gnatbind -x demo1.ali - powerpc-xcoff-lynxos-gnatlink -g demo1.ali - - Once the executable is created, copy it to your working directory on the - board. In this directory, you will have to launch the gdb server and - choose a free port number on your TCP/IP socket. Presuming the Internet - hostname of the board is `myboard' and the port chosen is 2345, issue - the following command: - - myboard> gdbserver myboard:2345 demo1 - - Then return to your host environment. - - The graphical debugger interface, `gvd', supports both native and - cross environments at the same time. `gvd' can be launched from `Glide' - (see `README.Glide' for more information on customizing `Glide' for - LynxOS) or it can be launched from the command line as follows: - - $ gvd --debugger powerpc-xcoff-lynxos-gdb - - Then to attach to the target, enter in `gvd''s command line window: - - (gdb) target remote myboard:2345 - - For more information see the GVD documentation. - - The comments below concern debugging directly from the command line - but they also apply to `gvd', though in most cases an equivalent - graphical command is also available. - - To run the cross debugger from the command line without the visual - interface use the command `powerpc-xcoff-lynxos-gdb'. - - You will see something like: - - GNU gdb 4.17.gnat.3.14a1 - Copyright 1998 Free Software Foundation, Inc. - GDB is free software, covered by the GNU General Public License, and you are - welcome to change it and/or distribute copies of it under certain conditions. - Type "show copying" to see the conditions. - There is absolutely no warranty for GDB. Type "show warranty" for details. - This GDB was configured as "--host=sparc-sun-solaris2.5.1 --target=powerpc-xc - off-lynxos". - (gdb) - - Where `(gdb)' is the debugger's prompt. The first thing to do at the - prompt from within `gdb' is to load the symbol table from the - executable: - - (gdb) file demo1 - Reading symbols from demo1...done. - (gdb) - - You then have to attach to the server running on the board. Issue the - command: - - (gdb) target remote myboard:2345 - - After the server has been started and attached from the host, the - program is running on the target but has halted execution at the very - beginning. The following commands set a breakpoint and continue - execution: - - (gdb) break demo1.adb:37 - Breakpoint 1 at 0x100064d0: file demo1.adb, line 37. - (gdb) cont - Continuing. - - Breakpoint 1, demo1 () at demo1.adb:37 - 37 Set_Name (Fuel, "Fuel"); - (gdb) - - Here the execution has stopped at the breakpoint set above. Now you can - use the standard `gdb' commands to examine the stack and program - variables. - - Note that once execution has completed, the server on the board must - be restarted before a new debugging session may begin. - -  - File: gnat_ug_vxw.info, Node: An Example Debugging Session for LynxOS, Prev: Debugging Issues for LynxOS, Up: LynxOS Topics - - An Example Debugging Session for LynxOS - ======================================= - - Carrying on a little further with the debugging session, the following - example illustrates some of the usual debugging commands for moving - around and seeing where you are: - - (gdb) next - 38 Set_Name (Water, "Water"); - (gdb) bt - #0 demo1 () at demo1.adb:38 - #1 0x10001218 in main (argc=1, argv=2147483640, envp=2147483520) at - b~demo1.adb:118 - #2 0x10017538 in runmainthread () - #3 0x10001048 in __start () - (gdb) up - #1 0x10001218 in main (argc=1, argv=2147483640, envp=2147483520) at - b~demo1.adb:118 - 118 Ada_Main_Program; - (gdb) down - #0 demo1 () at demo1.adb:38 - 38 Set_Name (Water, "Water"); - (gdb) - - To examine and modify variables (of a tagged type here): - - (gdb) print speed - $1 = (name => "Speed ", value => -286331154) - (gdb) ptype speed - type = new instr.instrument with record - value: instr.speed; - end record - (gdb) speed.value := 3 - $2 = 3 - (gdb) print speed - $3 = (name => "Speed ", value => 3) - (gdb) info local - speed = (name => "Speed ", value => 3) - fuel = (name => "Fuel ", value => -286331154) - oil = (name => ' ' , value => -286331154, size => 20, - fill => 42 '*', empty => 46 '.') - water = (name => ' ' , value => -286331154, size => 20, - fill => 42 '*', empty => 46 '.') - time = (name => ' ' , seconds => 0, minutes => 0, hours => - 0) - chrono = (name => ' ' , seconds => 0, minutes => 0, - hours => 0) - db = (access demo1.dash_board.internal) 0x0 - (gdb) - - And finally letting the program it run to completion: - - (gdb) c - Continuing. - - Program exited normally. - (gdb) - -  - File: gnat_ug_vxw.info, Node: Performance Considerations, Next: GNU Free Documentation License, Prev: LynxOS Topics, Up: Top - - Performance Considerations - ************************** - - The GNAT system provides a number of options that allow a trade-off - between - - * performance of the generated code - - * speed of compilation - - * minimization of dependences and recompilation - - * the degree of run-time checking. - - The defaults (if no options are selected) aim at improving the speed of - compilation and minimizing dependences, at the expense of performance - of the generated code: - - * no optimization - - * no inlining of subprogram calls - - * all run-time checks enabled except overflow and elaboration checks - - These options are suitable for most program development purposes. This - chapter describes how you can modify these choices, and also provides - some guidelines on debugging optimized code. - - * Menu: - - * Controlling Run-Time Checks:: - * Optimization Levels:: - * Debugging Optimized Code:: - * Inlining of Subprograms:: - -  - File: gnat_ug_vxw.info, Node: Controlling Run-Time Checks, Next: Optimization Levels, Up: Performance Considerations - - Controlling Run-Time Checks - =========================== - - By default, GNAT generates all run-time checks, except arithmetic - overflow checking for integer operations and checks for access before - elaboration on subprogram calls. The latter are not required in default - mode, because all necessary checking is done at compile time. Two gnat - switches, `-gnatp' and `-gnato' allow this default to be modified. - *Note Run-Time Checks::. - - Our experience is that the default is suitable for most development - purposes. - - We treat integer overflow specially because these are quite - expensive and in our experience are not as important as other run-time - checks in the development process. Note that division by zero is not - considered an overflow check, and divide by zero checks are generated - where required by default. - - Elaboration checks are off by default, and also not needed by - default, since GNAT uses a static elaboration analysis approach that - avoids the need for run-time checking. This manual contains a full - chapter discussing the issue of elaboration checks, and if the default - is not satisfactory for your use, you should read this chapter. - - For validity checks, the minimal checks required by the Ada Reference - Manual (for case statements and assignments to array elements) are on - by default. These can be suppressed by use of the `-gnatVn' switch. - Note that in Ada 83, there were no validity checks, so if the Ada 83 - mode is acceptable (or when comparing GNAT performance with an Ada 83 - compiler), it may be reasonable to routinely use `-gnatVn'. Validity - checks are also suppressed entirely if `-gnatp' is used. - - Note that the setting of the switches controls the default setting of - the checks. They may be modified using either `pragma Suppress' (to - remove checks) or `pragma Unsuppress' (to add back suppressed checks) - in the program source. - -  - File: gnat_ug_vxw.info, Node: Optimization Levels, Next: Debugging Optimized Code, Prev: Controlling Run-Time Checks, Up: Performance Considerations - - Optimization Levels - =================== - - The default is optimization off. This results in the fastest compile - times, but GNAT makes absolutely no attempt to optimize, and the - generated programs are considerably larger and slower than when - optimization is enabled. You can use the `-ON' switch, where N is an - integer from 0 to 3, on the `gcc' command line to control the - optimization level: - - `-O0' - no optimization (the default) - - `-O1' - medium level optimization - - `-O2' - full optimization - - `-O3' - full optimization, and also attempt automatic inlining of small - subprograms within a unit (*note Inlining of Subprograms::). - - Higher optimization levels perform more global transformations on the - program and apply more expensive analysis algorithms in order to - generate faster and more compact code. The price in compilation time, - and the resulting improvement in execution time, both depend on the - particular application and the hardware environment. You should - experiment to find the best level for your application. - - Note: Unlike some other compilation systems, `gcc' has been tested - extensively at all optimization levels. There are some bugs which - appear only with optimization turned on, but there have also been bugs - which show up only in _unoptimized_ code. Selecting a lower level of - optimization does not improve the reliability of the code generator, - which in practice is highly reliable at all optimization levels. - - Note regarding the use of `-O3': The use of this optimization level - is generally discouraged with GNAT, since it often results in larger - executables which run more slowly. See further discussion of this point - in *note Inlining of Subprograms::. - -  - File: gnat_ug_vxw.info, Node: Debugging Optimized Code, Next: Inlining of Subprograms, Prev: Optimization Levels, Up: Performance Considerations - - Debugging Optimized Code - ======================== - - Since the compiler generates debugging tables for a compilation unit - before it performs optimizations, the optimizing transformations may - invalidate some of the debugging data. You therefore need to - anticipate certain anomalous situations that may arise while debugging - optimized code. This section describes the most common cases. - - 1. The "hopping Program Counter": Repeated 'step' or 'next' commands - show the PC bouncing back and forth in the code. This may result - from any of the following optimizations: - - * Common subexpression elimination: using a single instance of - code for a quantity that the source computes several times. - As a result you may not be able to stop on what looks like a - statement. - - * Invariant code motion: moving an expression that does not - change within a loop, to the beginning of the loop. - - * Instruction scheduling: moving instructions so as to overlap - loads and stores (typically) with other code, or in general - to move computations of values closer to their uses. Often - this causes you to pass an assignment statement without the - assignment happening and then later bounce back to the - statement when the value is actually needed. Placing a - breakpoint on a line of code and then stepping over it may, - therefore, not always cause all the expected side-effects. - - 2. The "big leap": More commonly known as cross-jumping, in which two - identical pieces of code are merged and the program counter - suddenly jumps to a statement that is not supposed to be executed, - simply because it (and the code following) translates to the same - thing as the code that _was_ supposed to be executed. This effect - is typically seen in sequences that end in a jump, such as a - `goto', a `return', or a `break' in a C `switch' statement. - - 3. The "roving variable": The symptom is an unexpected value in a - variable. There are various reasons for this effect: - - * In a subprogram prologue, a parameter may not yet have been - moved to its "home". - - * A variable may be dead, and its register re-used. This is - probably the most common cause. - - * As mentioned above, the assignment of a value to a variable - may have been moved. - - * A variable may be eliminated entirely by value propagation or - other means. In this case, GCC may incorrectly generate - debugging information for the variable - - In general, when an unexpected value appears for a local variable - or parameter you should first ascertain if that value was actually - computed by your program, as opposed to being incorrectly reported - by the debugger. Record fields or array elements in an object - designated by an access value are generally less of a problem, - once you have ascertained that the access value is sensible. - Typically, this means checking variables in the preceding code and - in the calling subprogram to verify that the value observed is - explainable from other values (one must apply the procedure - recursively to those other values); or re-running the code and - stopping a little earlier (perhaps before the call) and stepping - to better see how the variable obtained the value in question; or - continuing to step _from_ the point of the strange value to see if - code motion had simply moved the variable's assignments later. - -  - File: gnat_ug_vxw.info, Node: Inlining of Subprograms, Prev: Debugging Optimized Code, Up: Performance Considerations - - Inlining of Subprograms - ======================= - - A call to a subprogram in the current unit is inlined if all the - following conditions are met: - - * The optimization level is at least `-O1'. - - * The called subprogram is suitable for inlining: It must be small - enough and not contain nested subprograms or anything else that - `gcc' cannot support in inlined subprograms. - - * The call occurs after the definition of the body of the subprogram. - - * Either `pragma Inline' applies to the subprogram or it is small - and automatic inlining (optimization level `-O3') is specified. - - Calls to subprograms in `with''ed units are normally not inlined. To - achieve this level of inlining, the following conditions must all be - true: - - * The optimization level is at least `-O1'. - - * The called subprogram is suitable for inlining: It must be small - enough and not contain nested subprograms or anything else `gcc' - cannot support in inlined subprograms. - - * The call appears in a body (not in a package spec). - - * There is a `pragma Inline' for the subprogram. - - * The `-gnatn' switch is used in the `gcc' command line - - Note that specifying the `-gnatn' switch causes additional - compilation dependencies. Consider the following: - - package R is - procedure Q; - pragma Inline (Q); - end R; - package body R is - ... - end R; - - with R; - procedure Main is - begin - ... - R.Q; - end Main; - - With the default behavior (no `-gnatn' switch specified), the - compilation of the `Main' procedure depends only on its own source, - `main.adb', and the spec of the package in file `r.ads'. This means - that editing the body of `R' does not require recompiling `Main'. - - On the other hand, the call `R.Q' is not inlined under these - circumstances. If the `-gnatn' switch is present when `Main' is - compiled, the call will be inlined if the body of `Q' is small enough, - but now `Main' depends on the body of `R' in `r.adb' as well as on the - spec. This means that if this body is edited, the main program must be - recompiled. Note that this extra dependency occurs whether or not the - call is in fact inlined by `gcc'. - - The use of front end inlining with `-gnatN' generates similar - additional dependencies. - - Note: The `-fno-inline' switch can be used to prevent all inlining. - This switch overrides all other conditions and ensures that no inlining - occurs. The extra dependences resulting from `-gnatn' will still be - active, even if this switch is used to suppress the resulting inlining - actions. - - Note regarding the use of `-O3': There is no difference in inlining - behavior between `-O2' and `-O3' for subprograms with an explicit - pragma `Inline' assuming the use of `-gnatn' or `-gnatN' (the switches - that activate inlining). If you have used pragma `Inline' in - appropriate cases, then it is usually much better to use `-O2' and - `-gnatn' and avoid the use of `-O3' which in this case only has the - effect of inlining subprograms you did not think should be inlined. We - often find that the use of `-O3' slows down code by performing - excessive inlining, leading to increased instruction cache pressure - from the increased code size. So the bottom line here is that you - should not automatically assume that `-O3' is better than `-O2', and - indeed you should use `-O3' only if tests show that it actually - improves performance. - -  - File: gnat_ug_vxw.info, Node: GNU Free Documentation License, Next: Index, Prev: Performance Considerations, Up: Top - - GNU Free Documentation License - ****************************** - - Version 1.2, November 2002 - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warrany Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - - ADDENDUM: How to use this License for your documents - ==================================================== - - To use this License in a document you have written, include a copy of - the License in the document and put the following copyright and license - notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover - Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other - combination of the three, merge those two alternatives to suit the - situation. - - If your document contains nontrivial examples of program code, we - recommend releasing these examples in parallel under your choice of - free software license, such as the GNU General Public License, to - permit their use in free software. - -  - File: gnat_ug_vxw.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - - Index - ***** - - * Menu: - - * --GCC= (gnatchop): Switches for gnatchop. - * --GCC=compiler_name (gnatlink): Switches for gnatlink. - * --GCC=compiler_name (gnatmake): Switches for gnatmake. - * --GNATBIND=binder_name (gnatmake): Switches for gnatmake. - * --GNATLINK=linker_name (gnatmake): Switches for gnatmake. - * --LINK= (gnatlink): Switches for gnatlink. - * --RTS (gcc): Switches for gcc. - * --RTS (gnatbind): Summary of Binder Switches. - * --RTS (gnatfind): gnatfind Switches. - * --RTS (gnatls): Switches for gnatls. - * --RTS (gnatmake): Switches for gnatmake. - * --RTS (gnatxref): gnatxref Switches. - * -83 (gnathtml): Converting Ada Files to html with gnathtml. - * -A (gnatbind): Output Control. - * -A (gnatlink): Switches for gnatlink. - * -a (gnatls): Switches for gnatls. - * -A (gnatmake): Switches for gnatmake. - * -a (gnatmake): Switches for gnatmake. - * -aI (gnatmake): Switches for gnatmake. - * -aL (gnatmake): Switches for gnatmake. - * -aO (gnatmake): Switches for gnatmake. - * -B (gcc): Switches for gcc. - * -b (gcc): Switches for gcc. - * -b (gnatbind): Binder Error Message Control. - * -B (gnatlink): Switches for gnatlink. - * -b (gnatlink): Switches for gnatlink. - * -b (gnatmake): Switches for gnatmake. - * -bargs (gnatmake): Mode Switches for gnatmake. - * -c (gcc): Switches for gcc. - * -C (gnatbind): Output Control. - * -c (gnatbind): Output Control. - * -c (gnatchop): Switches for gnatchop. - * -C (gnatlink): Switches for gnatlink. - * -C (gnatmake): Switches for gnatmake. - * -c (gnatmake): Switches for gnatmake. - * -c (gnatname): Switches for gnatname. - * -cargs (gnatmake): Mode Switches for gnatmake. - * -d (gnathtml): Converting Ada Files to html with gnathtml. - * -d (gnatls): Switches for gnatls. - * -D (gnatname): Switches for gnatname. - * -d (gnatname): Switches for gnatname. - * -e (gnatbind): Output Control. - * -f (gnathtml): Converting Ada Files to html with gnathtml. - * -f (gnatlink): Switches for gnatlink. - * -f (gnatmake): Switches for gnatmake. - * -fno-inline (gcc): Inlining of Subprograms. - * -fstack-check: Stack Overflow Checking. - * -g (gcc): Switches for gcc. - * -g (gnatlink): Switches for gnatlink. - * -gnat83 (gcc): Compiling Ada 83 Programs. - * -gnata (gcc): Debugging and Assertion Control. - * -gnatb (gcc): Output and Error Message Control. - * -gnatc (gcc): Using gcc for Semantic Checking. - * -gnatD (gcc): Debugging Control. - * -gnatdc switch: GNAT Abnormal Termination or Failure to Terminate. - * -gnatE (gcc) <1>: Debugging Control. - * -gnatE (gcc): Run-Time Checks. - * -gnatem (gcc): Units to Sources Mapping Files. - * -gnatf (gcc): Output and Error Message Control. - * -gnatG (gcc): Debugging Control. - * -gnati (gcc): Character Set Control. - * -gnatk (gcc): File Naming Control. - * -gnatl (gcc): Output and Error Message Control. - * -gnatm (gcc): Output and Error Message Control. - * -gnatn (gcc): Inlining of Subprograms. - * -gnatN (gcc): Subprogram Inlining Control. - * -gnatn (gcc): Subprogram Inlining Control. - * -gnatN switch: Source Dependencies. - * -gnatn switch: Source Dependencies. - * -gnato (gcc) <1>: Controlling Run-Time Checks. - * -gnato (gcc): Run-Time Checks. - * -gnatp (gcc) <1>: Controlling Run-Time Checks. - * -gnatp (gcc): Run-Time Checks. - * -gnatq (gcc): Output and Error Message Control. - * -gnatR (gcc): Debugging Control. - * -gnats (gcc): Using gcc for Syntax Checking. - * -gnatt (gcc): Auxiliary Output Control. - * -gnatT (gcc): Run-Time Control. - * -gnatu (gcc): Auxiliary Output Control. - * -gnatU (gcc): Output and Error Message Control. - * -gnatv (gcc): Output and Error Message Control. - * -gnatW (gcc): Character Set Control. - * -gnatwA (gcc): Output and Error Message Control. - * -gnatwa (gcc): Output and Error Message Control. - * -gnatwB (gcc): Output and Error Message Control. - * -gnatwb (gcc): Output and Error Message Control. - * -gnatwC (gcc): Output and Error Message Control. - * -gnatwc (gcc): Output and Error Message Control. - * -gnatwD (gcc): Output and Error Message Control. - * -gnatwd (gcc): Output and Error Message Control. - * -gnatwe (gcc): Output and Error Message Control. - * -gnatwF (gcc): Output and Error Message Control. - * -gnatwf (gcc): Output and Error Message Control. - * -gnatwH (gcc): Output and Error Message Control. - * -gnatwh (gcc): Output and Error Message Control. - * -gnatwI (gcc): Output and Error Message Control. - * -gnatwi (gcc): Output and Error Message Control. - * -gnatwL (gcc): Output and Error Message Control. - * -gnatwl (gcc): Output and Error Message Control. - * -gnatwO (gcc): Output and Error Message Control. - * -gnatwo (gcc): Output and Error Message Control. - * -gnatwP (gcc): Output and Error Message Control. - * -gnatwp (gcc): Output and Error Message Control. - * -gnatwR (gcc): Output and Error Message Control. - * -gnatwr (gcc): Output and Error Message Control. - * -gnatws (gcc): Output and Error Message Control. - * -gnatwU (gcc): Output and Error Message Control. - * -gnatwu (gcc): Output and Error Message Control. - * -gnatx (gcc): Debugging Control. - * -h (gnatbind) <1>: Output Control. - * -h (gnatbind): Elaboration Control. - * -h (gnatls): Switches for gnatls. - * -h (gnatname): Switches for gnatname. - * -I (gcc): Switches for gcc. - * -I (gnathtml): Converting Ada Files to html with gnathtml. - * -I (gnatmake): Switches for gnatmake. - * -i (gnatmake): Switches for gnatmake. - * -I- (gcc): Switches for gcc. - * -I- (gnatmake): Switches for gnatmake. - * -j (gnatmake): Switches for gnatmake. - * -K (gnatbind): Output Control. - * -k (gnatchop): Switches for gnatchop. - * -k (gnatmake): Switches for gnatmake. - * -l (gnatbind): Output Control. - * -l (gnathtml): Converting Ada Files to html with gnathtml. - * -L (gnatmake): Switches for gnatmake. - * -l (gnatmake): Switches for gnatmake. - * -largs (gnatmake): Mode Switches for gnatmake. - * -M (gnatbind): Binder Error Message Control. - * -m (gnatbind): Binder Error Message Control. - * -M (gnatmake): Switches for gnatmake. - * -m (gnatmake): Switches for gnatmake. - * -mlongcall (gcc): Handling Relocation Issues for PowerPc Targets. - * -n (gnatbind): Binding with Non-Ada Main Programs. - * -n (gnatlink): Switches for gnatlink. - * -n (gnatmake): Switches for gnatmake. - * -nostdinc (gnatmake): Switches for gnatmake. - * -nostdlib (gnatmake): Switches for gnatmake. - * -O (gcc) <1>: Optimization Levels. - * -O (gcc): Switches for gcc. - * -o (gcc): Switches for gcc. - * -o (gnatbind): Output Control. - * -O (gnatbind): Output Control. - * -o (gnathtml): Converting Ada Files to html with gnathtml. - * -o (gnatlink): Switches for gnatlink. - * -o (gnatls): Switches for gnatls. - * -o (gnatmake): Switches for gnatmake. - * -p (gnatchop): Switches for gnatchop. - * -p (gnathtml): Converting Ada Files to html with gnathtml. - * -P (gnatname): Switches for gnatname. - * -pass-exit-codes (gcc): Auxiliary Output Control. - * -q (gnatchop): Switches for gnatchop. - * -q (gnatmake): Switches for gnatmake. - * -r (gnatbind): Output Control. - * -r (gnatchop): Switches for gnatchop. - * -S (gcc): Switches for gcc. - * -s (gnatbind): Consistency-Checking Modes. - * -s (gnatls): Switches for gnatls. - * -s (gnatmake): Switches for gnatmake. - * -sc (gnathtml): Converting Ada Files to html with gnathtml. - * -t (gnatbind): Binder Error Message Control. - * -t (gnathtml): Converting Ada Files to html with gnathtml. - * -u (gnatls): Switches for gnatls. - * -u (gnatmake): Switches for gnatmake. - * -V (gcc): Switches for gcc. - * -v (gcc): Switches for gcc. - * -v (gnatbind): Binder Error Message Control. - * -v (gnatchop): Switches for gnatchop. - * -v (gnatlink): Switches for gnatlink. - * -v (gnatmake): Switches for gnatmake. - * -v (gnatname): Switches for gnatname. - * -v -v (gnatlink): Switches for gnatlink. - * -w: Output and Error Message Control. - * -w (gnatchop): Switches for gnatchop. - * -we (gnatbind): Binder Error Message Control. - * -ws (gnatbind): Binder Error Message Control. - * -x (gnatbind): Consistency-Checking Modes. - * -z (gnatbind): Binding Programs with No Main Subprogram. - * -z (gnatmake): Switches for gnatmake. - * __gnat_finalize: Running gnatbind. - * __gnat_initialize: Running gnatbind. - * __gnat_set_globals: Running gnatbind. - * _main: The External Symbol Naming Scheme of GNAT. - * Access before elaboration: Run-Time Checks. - * Access-to-subprogram: Elaboration for Access-to-Subprogram Values. - * ACVC, Ada 83 tests: Compiling Ada 83 Programs. - * Ada <1>: Naming Conventions for GNAT Source Files. - * Ada: Search Paths for gnatbind. - * Ada 83 compatibility: Compiling Ada 83 Programs. - * Ada 95 Language Reference Manual: What You Should Know before Reading This Guide. - * Ada expressions: Using Ada Expressions. - * Ada Library Information files: The Ada Library Information Files. - * Ada.Characters.Latin_1: Latin-1. - * ADA_INCLUDE_PATH: Search Paths and the Run-Time Library (RTL). - * ADA_OBJECTS_PATH: Search Paths for gnatbind. - * adafinal <1>: Binding with Non-Ada Main Programs. - * adafinal: Running gnatbind. - * adainit <1>: Binding with Non-Ada Main Programs. - * adainit: Running gnatbind. - * Address Clauses, warnings: Output and Error Message Control. - * ali files: The Ada Library Information Files. - * Annex A: Naming Conventions for GNAT Source Files. - * Annex B: Naming Conventions for GNAT Source Files. - * Arbitrary File Naming Conventions: Handling Arbitrary File Naming Conventions Using gnatname. - * Asm: Calling Conventions. - * Assert: Debugging and Assertion Control. - * Assertions: Debugging and Assertion Control. - * Biased rounding: Output and Error Message Control. - * Binder consistency checks: Binder Error Message Control. - * Binder output file: Interfacing to C. - * Binder, multiple input files: Binding with Non-Ada Main Programs. - * Breakpoints and tasks: Ada Tasks. - * C: Calling Conventions. - * C++: Calling Conventions. - * Calling Conventions: Calling Conventions. - * Check, elaboration: Run-Time Checks. - * Check, overflow: Run-Time Checks. - * Check_CPU procedure: Check_CPU Procedure. - * Checks, access before elaboration: Run-Time Checks. - * Checks, division by zero: Run-Time Checks. - * Checks, elaboration: Checking the Elaboration Order in Ada 95. - * Checks, overflow: Controlling Run-Time Checks. - * Checks, suppressing: Run-Time Checks. - * COBOL: Calling Conventions. - * code page 437: Other 8-Bit Codes. - * code page 850: Other 8-Bit Codes. - * Combining GNAT switches: Switches for gcc. - * Command line length: Switches for gnatlink. - * Compilation model: The GNAT Compilation Model. - * Conditionals, constant: Output and Error Message Control. - * Configuration pragmas: Configuration Pragmas. - * Consistency checks, in binder: Binder Error Message Control. - * Convention Ada: Calling Conventions. - * Convention Asm: Calling Conventions. - * Convention Assembler: Calling Conventions. - * Convention C: Calling Conventions. - * Convention C++: Calling Conventions. - * Convention COBOL: Calling Conventions. - * Convention Default: Calling Conventions. - * Convention DLL: Calling Conventions. - * Convention External: Calling Conventions. - * Convention Fortran: Calling Conventions. - * Convention Stdcall: Calling Conventions. - * Convention Stubbed: Calling Conventions. - * Convention Win32: Calling Conventions. - * Conventions: Conventions. - * CR: Source Representation. - * Cyrillic: Other 8-Bit Codes. - * Debug: Debugging and Assertion Control. - * Debug Pool: Finding Memory Problems with GNAT Debug Pool. - * Debugger: Running and Debugging Ada Programs. - * Debugging: Running and Debugging Ada Programs. - * Debugging Generic Units: Debugging Generic Units. - * Debugging information, including: Switches for gnatlink. - * Debugging options: Debugging Control. - * Default: Calling Conventions. - * Dependencies, producing list: Switches for gnatmake. - * Dependency rules: The GNAT Make Program gnatmake. - * Dereferencing, implicit: Output and Error Message Control. - * Division by zero: Run-Time Checks. - * DLL: Calling Conventions. - * EABI (for VxWorks on PowerPc): Handling Relocation Issues for PowerPc Targets. - * Elaborate: Controlling the Elaboration Order in Ada 95. - * Elaborate_All: Controlling the Elaboration Order in Ada 95. - * Elaborate_Body: Controlling the Elaboration Order in Ada 95. - * Elaboration checks <1>: Checking the Elaboration Order in Ada 95. - * Elaboration checks: Run-Time Checks. - * Elaboration control <1>: Summary of Procedures for Elaboration Control. - * Elaboration control: Elaboration Order Handling in GNAT. - * Elaboration of library tasks: Elaboration Issues for Library Tasks. - * Elaboration order control: Comparison between GNAT and C/C++ Compilation Models. - * Elaboration, warnings: Output and Error Message Control. - * Eliminate: Eliminate Pragma. - * Embedded ABI (for VxWorks on PowerPc): Handling Relocation Issues for PowerPc Targets. - * End of source file: Source Representation. - * Error messages, suppressing: Output and Error Message Control. - * EUC Coding: Wide Character Encodings. - * Exceptions: Ada Exceptions. - * Export: The External Symbol Naming Scheme of GNAT. - * External: Calling Conventions. - * FDL, GNU Free Documentation License: GNU Free Documentation License. - * FF: Source Representation. - * File names <1>: Alternative File Naming Schemes. - * File names: Using Other File Names. - * File naming schemes, alternative: Alternative File Naming Schemes. - * Foreign Languages: Calling Conventions. - * Formals, unreferenced: Output and Error Message Control. - * Fortran: Calling Conventions. - * gdb: Running and Debugging Ada Programs. - * Generic formal parameters: Compiling Ada 83 Programs. - * Generics <1>: Debugging Generic Units. - * Generics: Generating Object Files. - * Glide: Introduction to Glide and GVD. - * GNAT <1>: Naming Conventions for GNAT Source Files. - * GNAT: Search Paths for gnatbind. - * GNAT Abnormal Termination or Failure to Terminate: GNAT Abnormal Termination or Failure to Terminate. - * GNAT compilation model: The GNAT Compilation Model. - * GNAT library: Comparison between GNAT and Conventional Ada Library Models. - * gnat.adc <1>: The Configuration Pragmas Files. - * gnat.adc: Using Other File Names. - * gnat1: Compiling Programs. - * gnat_argc: Command-Line Access. - * gnat_argv: Command-Line Access. - * GNAT_STACK_LIMIT: Stack Overflow Checking. - * gnatbind: Binding Using gnatbind. - * gnatchop: Renaming Files Using gnatchop. - * gnatelim: Reducing the Size of Ada Executables with gnatelim. - * gnatfind: The Cross-Referencing Tools gnatxref and gnatfind. - * gnatkr: File Name Krunching Using gnatkr. - * gnatlink: Linking Using gnatlink. - * gnatls: The GNAT Library Browser gnatls. - * gnatmake: The GNAT Make Program gnatmake. - * gnatprep: Preprocessing Using gnatprep. - * gnatstub: Creating Sample Bodies Using gnatstub. - * gnatxref: The Cross-Referencing Tools gnatxref and gnatfind. - * GNU make: Using gnatmake in a Makefile. - * GVD: Introduction to Glide and GVD. - * Hiding of Declarations: Output and Error Message Control. - * HT: Source Representation. - * Implicit dereferencing: Output and Error Message Control. - * Inline <1>: Inlining of Subprograms. - * Inline: Source Dependencies. - * Inlining: Comparison between GNAT and Conventional Ada Library Models. - * Inlining, warnings: Output and Error Message Control. - * Intel_CPU package body: Intel_CPU Package Body. - * Intel_CPU package specification: Intel_CPU Package Specification. - * Interfaces <1>: Naming Conventions for GNAT Source Files. - * Interfaces: Search Paths for gnatbind. - * Interfacing to Ada: Calling Conventions. - * Interfacing to Assembly: Calling Conventions. - * Interfacing to C: Calling Conventions. - * Interfacing to C++: Calling Conventions. - * Interfacing to COBOL: Calling Conventions. - * Interfacing to Fortran: Calling Conventions. - * Internal trees, writing to file: Auxiliary Output Control. - * Latin-1 <1>: Latin-1. - * Latin-1: Source Representation. - * Latin-2: Other 8-Bit Codes. - * Latin-3: Other 8-Bit Codes. - * Latin-4: Other 8-Bit Codes. - * Latin-5: Other 8-Bit Codes. - * LF: Source Representation. - * Library browser: The GNAT Library Browser gnatls. - * Library tasks, elaboration issues: Elaboration Issues for Library Tasks. - * Library, building, installing: GNAT and Libraries. - * Linker libraries: Switches for gnatmake. - * Machine_Overflows: Run-Time Checks. - * Main Program: Running gnatbind. - * make: Using the GNU make Utility. - * makefile: Using gnatmake in a Makefile. - * Mixed Language Programming: Mixed Language Programming. - * Multiple units, syntax checking: Using gcc for Syntax Checking. - * No code generated: Compiling Programs. - * No_Entry_Calls_In_Elaboration_Code: Elaboration Issues for Library Tasks. - * Object file list: Running gnatbind. - * Order of elaboration: Elaboration Order Handling in GNAT. - * Other Ada compilers: Calling Conventions. - * Overflow checks <1>: Controlling Run-Time Checks. - * Overflow checks: Run-Time Checks. - * Parallel make: Switches for gnatmake. - * Performance: Performance Considerations. - * PowerPc VxWorks, relocation issues: Handling Relocation Issues for PowerPc Targets. - * pragma Elaborate: Controlling the Elaboration Order in Ada 95. - * pragma Elaborate_All: Controlling the Elaboration Order in Ada 95. - * pragma Elaborate_Body: Controlling the Elaboration Order in Ada 95. - * pragma Inline: Inlining of Subprograms. - * pragma Preelaborate: Controlling the Elaboration Order in Ada 95. - * pragma Pure: Controlling the Elaboration Order in Ada 95. - * pragma Suppress: Controlling Run-Time Checks. - * pragma Unsuppress: Controlling Run-Time Checks. - * Pragmas, configuration: Configuration Pragmas. - * Preelaborate: Controlling the Elaboration Order in Ada 95. - * Pure: Controlling the Elaboration Order in Ada 95. - * Recompilation, by gnatmake: Notes on the Command Line. - * Relocation issues for PowerPc VxWorks targets: Handling Relocation Issues for PowerPc Targets. - * Rounding, biased: Output and Error Message Control. - * RTL: Switches for gcc. - * SDP_Table_Build: Running gnatbind. - * Search paths, for gnatmake: Switches for gnatmake. - * Shift JIS Coding: Wide Character Encodings. - * Source file, end: Source Representation. - * Source files, suppressing search: Switches for gnatmake. - * Source files, use by binder: Running gnatbind. - * Source_File_Name pragma <1>: Alternative File Naming Schemes. - * Source_File_Name pragma: Using Other File Names. - * Source_Reference: Switches for gnatchop. - * Stack Overflow Checking: Stack Overflow Checking. - * stack traceback: Stack Traceback. - * stack unwinding: Stack Traceback. - * Stdcall: Calling Conventions. - * stderr: Output and Error Message Control. - * stdout: Output and Error Message Control. - * storage, pool, memory corruption: Finding Memory Problems with GNAT Debug Pool. - * Stubbed: Calling Conventions. - * Style checking: Style Checking. - * SUB: Source Representation. - * Subunits: Generating Object Files. - * Suppress <1>: Controlling Run-Time Checks. - * Suppress: Run-Time Checks. - * Suppressing checks: Run-Time Checks. - * System <1>: Naming Conventions for GNAT Source Files. - * System: Search Paths for gnatbind. - * System.IO: Search Paths and the Run-Time Library (RTL). - * Task switching: Ada Tasks. - * Tasks: Ada Tasks. - * Time Slicing: Run-Time Control. - * Time stamp checks, in binder: Binder Error Message Control. - * Tornado II Project: Using GNAT from the Tornado 2 Project Facility. - * traceback: Stack Traceback. - * traceback, non-symbolic: Non-Symbolic Traceback. - * traceback, symbolic: Symbolic Traceback. - * Tree file: Tree Files. - * Typographical conventions: Conventions. - * Unsuppress <1>: Controlling Run-Time Checks. - * Unsuppress: Run-Time Checks. - * Upper-Half Coding: Wide Character Encodings. - * Validity Checking: Validity Checking. - * Version skew (avoided by gnatmake): Building a Simple Ada Program. - * Volatile parameter: The Volatile Parameter. - * VT: Source Representation. - * VxWorks kernel (relocation issues on PowerPc): Handling Relocation Issues for PowerPc Targets. - * VxWorks PowerPc, relocation issues: Handling Relocation Issues for PowerPc Targets. - * Warning messages: Output and Error Message Control. - * Warnings: Binder Error Message Control. - * Warnings, treat as error: Output and Error Message Control. - * Win32: Calling Conventions. - * Writing internal trees: Auxiliary Output Control. - * Zero Cost Exceptions: Running gnatbind. - - -  - Tag Table: - Node: Top91 - Node: About This Guide9418 - Node: What This Guide Contains9943 - Node: What You Should Know before Reading This Guide14413 - Node: Related Information14821 - Node: Conventions15544 - Node: Preliminary Note for Cross Platform Users16438 - Node: Getting Started with GNAT18228 - Node: Running GNAT19131 - Node: Building a Simple Ada Program19738 - Node: Executing a Program on VxWorks23118 - Node: Loading and Running the Program23564 - Node: Unloading the Program25297 - Node: Running a Program with Multiple Units26846 - Node: Using the gnatmake Utility29118 - Node: Introduction to Glide and GVD31532 - Node: Building a New Program with Glide32274 - Node: Simple Debugging with GVD37612 - Node: Other Glide Features40649 - Node: The GNAT Compilation Model42532 - Node: Source Representation43862 - Node: Foreign Language Representation45648 - Node: Latin-146134 - Node: Other 8-Bit Codes47000 - Node: Wide Character Encodings49093 - Node: File Naming Rules52899 - Node: Using Other File Names55188 - Node: Alternative File Naming Schemes57541 - Node: Generating Object Files62773 - Node: Source Dependencies65487 - Node: The Ada Library Information Files69010 - Node: Binding an Ada Program71143 - Node: Mixed Language Programming72991 - Node: Interfacing to C73268 - Node: Calling Conventions75774 - Node: Building Mixed Ada & C++ Programs81698 - Node: Interfacing to C++82779 - Node: Linking a Mixed C++ & Ada Program83819 - Node: A Simple Example86853 - Node: Adapting the Run Time to a New C++ Compiler89899 - Node: Comparison between GNAT and C/C++ Compilation Models90915 - Node: Comparison between GNAT and Conventional Ada Library Models92644 - Node: Compiling Using gcc95295 - Node: Compiling Programs95790 - Node: Switches for gcc98740 - Node: Output and Error Message Control107924 - Node: Debugging and Assertion Control126010 - Node: Validity Checking127340 - Node: Style Checking133487 - Node: Run-Time Checks144960 - Node: Stack Overflow Checking148944 - Node: Run-Time Control151031 - Node: Using gcc for Syntax Checking151925 - Node: Using gcc for Semantic Checking153424 - Node: Compiling Ada 83 Programs154902 - Node: Character Set Control156323 - Node: File Naming Control159250 - Node: Subprogram Inlining Control159758 - Node: Auxiliary Output Control161099 - Node: Debugging Control162530 - Node: Units to Sources Mapping Files169970 - Node: Search Paths and the Run-Time Library (RTL)171360 - Node: Order of Compilation Issues174531 - Node: Examples176232 - Node: Binding Using gnatbind176800 - Node: Running gnatbind178662 - Node: Generating the Binder Program in C209423 - Node: Consistency-Checking Modes226868 - Node: Binder Error Message Control228363 - Node: Elaboration Control230629 - Node: Output Control231854 - Node: Binding with Non-Ada Main Programs234295 - Node: Binding Programs with No Main Subprogram237435 - Node: Summary of Binder Switches238258 - Node: Command-Line Access241581 - Node: Search Paths for gnatbind242586 - Node: Examples of gnatbind Usage245152 - Node: Linking Using gnatlink246923 - Node: Running gnatlink247662 - Node: Switches for gnatlink249647 - Node: Setting Stack Size from gnatlink253920 - Node: Setting Heap Size from gnatlink254774 - Node: The GNAT Make Program gnatmake255589 - Node: Running gnatmake257040 - Node: Switches for gnatmake258699 - Node: Mode Switches for gnatmake271663 - Node: Notes on the Command Line272821 - Node: How gnatmake Works275717 - Node: Examples of gnatmake Usage277887 - Node: Renaming Files Using gnatchop279014 - Node: Handling Files with Multiple Units279603 - Node: Operating gnatchop in Compilation Mode280924 - Node: Command Line for gnatchop284247 - Node: Switches for gnatchop285712 - Node: Examples of gnatchop Usage289493 - Node: Configuration Pragmas290852 - Node: Handling of Configuration Pragmas292404 - Node: The Configuration Pragmas Files293263 - Node: Handling Arbitrary File Naming Conventions Using gnatname294626 - Node: Arbitrary File Naming Conventions295034 - Node: Running gnatname296295 - Node: Switches for gnatname297754 - Node: Examples of gnatname Usage300888 - Node: GNAT Project Manager301689 - Node: Introduction302351 - Node: Project Files303447 - Node: Examples of Project Files306650 - Node: Common Sources with Different Switches and Different Output Directories307124 - Node: Source Files310155 - Node: Specifying the Object Directory310631 - Node: Specifying the Exec Directory311563 - Node: Project File Packages312331 - Node: Specifying Switch Settings313340 - Node: Main Subprograms315308 - Node: Source File Naming Conventions315972 - Node: Source Language(s)316472 - Node: Using External Variables316913 - Node: Importing Other Projects319754 - Node: Extending a Project322862 - Node: Project File Syntax325333 - Node: Basic Syntax326695 - Node: Packages327703 - Node: Expressions328857 - Node: String Types330755 - Node: Variables332058 - Node: Attributes335086 - Node: Associative Array Attributes340519 - Node: case Constructions341364 - Node: Objects and Sources in Project Files343161 - Node: Object Directory343741 - Node: Exec Directory344732 - Node: Source Directories345561 - Node: Source File Names346928 - Node: Importing Projects349265 - Node: Project Extension352044 - Node: External References in Project Files353723 - Node: Packages in Project Files355466 - Node: Variables from Imported Projects357862 - Node: Naming Schemes359534 - Node: Library Projects363507 - Node: Switches Related to Project Files366401 - Node: Tools Supporting Project Files368105 - Node: gnatmake and Project Files368437 - Node: Switches and Project Files368890 - Node: Project Files and Main Subprograms374634 - Node: The GNAT Driver and Project Files376559 - Node: Glide and Project Files380227 - Node: An Extended Example381146 - Node: Project File Complete Syntax384141 - Node: Elaboration Order Handling in GNAT386933 - Node: Elaboration Code in Ada 95387953 - Node: Checking the Elaboration Order in Ada 95392599 - Node: Controlling the Elaboration Order in Ada 95396600 - Node: Controlling Elaboration in GNAT - Internal Calls404917 - Node: Controlling Elaboration in GNAT - External Calls410624 - Node: Default Behavior in GNAT - Ensuring Safety414358 - Node: Elaboration Issues for Library Tasks418441 - Node: Mixing Elaboration Models431646 - Node: What to Do If the Default Elaboration Behavior Fails434147 - Node: Elaboration for Access-to-Subprogram Values444462 - Node: Summary of Procedures for Elaboration Control446269 - Node: Other Elaboration Order Considerations447432 - Node: The Cross-Referencing Tools gnatxref and gnatfind452661 - Node: gnatxref Switches454325 - Node: gnatfind Switches457764 - Node: Project Files for gnatxref and gnatfind463360 - Node: Regular Expressions in gnatfind and gnatxref466466 - Node: Examples of gnatxref Usage469245 - Node: Examples of gnatfind Usage473044 - Node: File Name Krunching Using gnatkr475247 - Node: About gnatkr475861 - Node: Using gnatkr477183 - Node: Krunching Method478074 - Node: Examples of gnatkr Usage481311 - Node: Preprocessing Using gnatprep481801 - Node: Using gnatprep482312 - Node: Switches for gnatprep483164 - Node: Form of Definitions File485286 - Node: Form of Input Text for gnatprep486025 - Node: The GNAT Library Browser gnatls489644 - Node: Running gnatls490173 - Node: Switches for gnatls492683 - Node: Examples of gnatls Usage494578 - Node: GNAT and Libraries496767 - Node: Creating an Ada Library497295 - Node: Installing an Ada Library500135 - Node: Using an Ada Library502492 - Node: Creating an Ada Library to be Used in a Non-Ada Context503683 - Node: Rebuilding the GNAT Run-Time Library509651 - Node: Using the GNU make Utility510558 - Node: Using gnatmake in a Makefile511412 - Node: Automatically Creating a List of Directories515620 - Node: Generating the Command Line Switches518758 - Node: Overcoming Command Line Length Limits519736 - Node: Finding Memory Problems with GNAT Debug Pool522041 - Node: Creating Sample Bodies Using gnatstub526735 - Node: Running gnatstub527530 - Node: Switches for gnatstub528284 - Node: Reducing the Size of Ada Executables with gnatelim530416 - Node: About gnatelim530949 - Node: Eliminate Pragma532037 - Node: Tree Files533045 - Node: Preparing Tree and Bind Files for gnatelim533934 - Node: Running gnatelim535936 - Node: Correcting the List of Eliminate Pragmas537931 - Node: Making Your Executables Smaller538712 - Node: Summary of the gnatelim Usage Cycle539534 - Node: Other Utility Programs540343 - Node: Using Other Utility Programs with GNAT540871 - Node: The gnatpsta Utility Program541559 - Node: The External Symbol Naming Scheme of GNAT542853 - Node: Ada Mode for Glide544850 - Node: Converting Ada Files to html with gnathtml546801 - Node: Installing gnathtml550374 - Node: Running and Debugging Ada Programs551038 - Node: The GNAT Debugger GDB552432 - Node: Running GDB555550 - Node: Introduction to GDB Commands555848 - Node: Using Ada Expressions560713 - Node: Calling User-Defined Subprograms561907 - Node: Using the Next Command in a Function564327 - Node: Ada Exceptions565492 - Node: Ada Tasks566446 - Node: Debugging Generic Units568509 - Node: GNAT Abnormal Termination or Failure to Terminate569912 - Node: Naming Conventions for GNAT Source Files572491 - Node: Getting Internal Debugging Information575082 - Node: Stack Traceback576284 - Node: Non-Symbolic Traceback577321 - Node: Tracebacks From an Unhandled Exception577782 - Node: Tracebacks From Exception Occurrences (non-symbolic)581719 - Node: Tracebacks From Anywhere in a Program (non-symbolic)583002 - Node: Symbolic Traceback584845 - Node: Tracebacks From Exception Occurrences (symbolic)585568 - Node: Tracebacks From Anywhere in a Program (symbolic)586977 - Node: Inline Assembler588169 - Node: Basic Assembler Syntax589855 - Node: A Simple Example of Inline Assembler591632 - Node: Output Variables in Inline Assembler594799 - Node: Input Variables in Inline Assembler602179 - Node: Inlining Inline Assembler Code604687 - Node: Other Asm Functionality606621 - Node: The Clobber Parameter607056 - Node: The Volatile Parameter609055 - Node: A Complete Example610247 - Node: Check_CPU Procedure611221 - Node: Intel_CPU Package Specification626268 - Node: Intel_CPU Package Body635696 - Node: VxWorks Topics644854 - Node: Kernel Configuration for VxWorks645494 - Node: Kernel Compilation Issues for VxWorks646204 - Node: Handling Relocation Issues for PowerPc Targets647376 - Node: Support for Software Floating Point on PowerPC Processors651803 - Node: Interrupt Handling for VxWorks653003 - Node: Simulating Command Line Arguments for VxWorks670248 - Node: Debugging Issues for VxWorks672353 - Node: Using GNAT from the Tornado 2 Project Facility681774 - Node: The GNAT Toolchain as Used from the Tornado 2 Project Facility682607 - Node: Building a Simple Application683658 - Node: Mixing C and Ada Code in a Tornado 2 Project684605 - Node: Compilation Switches685174 - Node: Autoscale and Minimal Kernel Configuration687485 - Node: Adapting BSPs to GNAT688184 - Node: Using GNAT Project Files in a Tornado 2 Project689537 - Node: Frequently Asked Questions for VxWorks690305 - Node: LynxOS Topics693270 - Node: Getting Started with GNAT on LynxOS693705 - Node: Kernel Configuration for LynxOS694913 - Node: Patch Level Issues for LynxOS695784 - Node: Debugging Issues for LynxOS696171 - Node: An Example Debugging Session for LynxOS699967 - Node: Performance Considerations701986 - Node: Controlling Run-Time Checks703017 - Node: Optimization Levels705002 - Node: Debugging Optimized Code706859 - Node: Inlining of Subprograms710592 - Node: GNU Free Documentation License714116 - Node: Index736545 -  - End Tag Table --- 0 ---- diff -Nrc3pad gcc-3.3.2/gcc/ada/gnat_ug_wnt.info gcc-3.3.3/gcc/ada/gnat_ug_wnt.info *** gcc-3.3.2/gcc/ada/gnat_ug_wnt.info Thu Oct 16 20:23:59 2003 --- gcc-3.3.3/gcc/ada/gnat_ug_wnt.info Thu Jan 1 00:00:00 1970 *************** *** 1,19316 **** - This is ada/gnat_ug_wnt.info, produced by makeinfo version 4.2 from - ada/gnat_ug_wnt.texi. - - Copyright (C) 1995-2002, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT User's Guide for Windows NT", and with no - Back-Cover Texts. A copy of the license is included in the section - entitled "GNU Free Documentation License". -  - File: gnat_ug_wnt.info, Node: Top, Next: About This Guide, Prev: (dir), Up: (dir) - - GNAT User's Guide - ***************** - - GNAT User's Guide for Windows NT - - GNAT, The GNU Ada 95 Compiler - - GNAT Version for GCC 3.3.2 - - Ada Core Technologies, Inc. - - Copyright (C) 1995-2002, Free Software Foundation - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 or - any later version published by the Free Software Foundation; with the - Invariant Sections being "GNU Free Documentation License", with the - Front-Cover Texts being "GNAT User's Guide for Windows NT", and with no - Back-Cover Texts. A copy of the license is included in the section - entitled "GNU Free Documentation License". - * Menu: - - * About This Guide:: - * Getting Started with GNAT:: - * The GNAT Compilation Model:: - * Compiling Using gcc:: - * Binding Using gnatbind:: - * Linking Using gnatlink:: - * The GNAT Make Program gnatmake:: - * Renaming Files Using gnatchop:: - * Configuration Pragmas:: - * Handling Arbitrary File Naming Conventions Using gnatname:: - * GNAT Project Manager:: - * Elaboration Order Handling in GNAT:: - * The Cross-Referencing Tools gnatxref and gnatfind:: - * File Name Krunching Using gnatkr:: - * Preprocessing Using gnatprep:: - * The GNAT Library Browser gnatls:: - * GNAT and Libraries:: - * Using the GNU make Utility:: - * Finding Memory Problems with gnatmem:: - * Finding Memory Problems with GNAT Debug Pool:: - * Creating Sample Bodies Using gnatstub:: - * Reducing the Size of Ada Executables with gnatelim:: - * Other Utility Programs:: - * Running and Debugging Ada Programs:: - * Inline Assembler:: - * Microsoft Windows Topics:: - * Performance Considerations:: - * GNU Free Documentation License:: - * Index:: - - --- The Detailed Node Listing --- - - About This Guide - - * What This Guide Contains:: - * What You Should Know before Reading This Guide:: - * Related Information:: - * Conventions:: - - - Getting Started with GNAT - - * Running GNAT:: - * Running a Simple Ada Program:: - * Running a Program with Multiple Units:: - * Using the gnatmake Utility:: - - The GNAT Compilation Model - - * Source Representation:: - * Foreign Language Representation:: - * File Naming Rules:: - * Using Other File Names:: - * Alternative File Naming Schemes:: - * Generating Object Files:: - * Source Dependencies:: - * The Ada Library Information Files:: - * Binding an Ada Program:: - * Mixed Language Programming:: - * Building Mixed Ada & C++ Programs:: - * Comparison between GNAT and C/C++ Compilation Models:: - * Comparison between GNAT and Conventional Ada Library Models:: - - Foreign Language Representation - - * Latin-1:: - * Other 8-Bit Codes:: - * Wide Character Encodings:: - - Compiling Ada Programs With gcc - - * Compiling Programs:: - * Switches for gcc:: - * Search Paths and the Run-Time Library (RTL):: - * Order of Compilation Issues:: - * Examples:: - - Switches for gcc - - * Output and Error Message Control:: - * Debugging and Assertion Control:: - * Run-Time Checks:: - * Stack Overflow Checking:: - * Run-Time Control:: - * Validity Checking:: - * Style Checking:: - * Using gcc for Syntax Checking:: - * Using gcc for Semantic Checking:: - * Compiling Ada 83 Programs:: - * Character Set Control:: - * File Naming Control:: - * Subprogram Inlining Control:: - * Auxiliary Output Control:: - * Debugging Control:: - * Units to Sources Mapping Files:: - - Binding Ada Programs With gnatbind - - * Running gnatbind:: - * Generating the Binder Program in C:: - * Consistency-Checking Modes:: - * Binder Error Message Control:: - * Elaboration Control:: - * Output Control:: - * Binding with Non-Ada Main Programs:: - * Binding Programs with No Main Subprogram:: - * Summary of Binder Switches:: - * Command-Line Access:: - * Search Paths for gnatbind:: - * Examples of gnatbind Usage:: - - Linking Using gnatlink - - * Running gnatlink:: - * Switches for gnatlink:: - * Setting Stack Size from gnatlink:: - * Setting Heap Size from gnatlink:: - - The GNAT Make Program gnatmake - - * Running gnatmake:: - * Switches for gnatmake:: - * Mode Switches for gnatmake:: - * Notes on the Command Line:: - * How gnatmake Works:: - * Examples of gnatmake Usage:: - - Renaming Files Using gnatchop - - * Handling Files with Multiple Units:: - * Operating gnatchop in Compilation Mode:: - * Command Line for gnatchop:: - * Switches for gnatchop:: - * Examples of gnatchop Usage:: - - Configuration Pragmas - - * Handling of Configuration Pragmas:: - * The Configuration Pragmas Files:: - - Handling Arbitrary File Naming Conventions Using gnatname - - * Arbitrary File Naming Conventions:: - * Running gnatname:: - * Switches for gnatname:: - * Examples of gnatname Usage:: - - GNAT Project Manager - - * Introduction:: - * Examples of Project Files:: - * Project File Syntax:: - * Objects and Sources in Project Files:: - * Importing Projects:: - * Project Extension:: - * External References in Project Files:: - * Packages in Project Files:: - * Variables from Imported Projects:: - * Naming Schemes:: - * Library Projects:: - * Switches Related to Project Files:: - * Tools Supporting Project Files:: - * An Extended Example:: - * Project File Complete Syntax:: - - Elaboration Order Handling in GNAT - - * Elaboration Code in Ada 95:: - * Checking the Elaboration Order in Ada 95:: - * Controlling the Elaboration Order in Ada 95:: - * Controlling Elaboration in GNAT - Internal Calls:: - * Controlling Elaboration in GNAT - External Calls:: - * Default Behavior in GNAT - Ensuring Safety:: - * Elaboration Issues for Library Tasks:: - * Mixing Elaboration Models:: - * What to Do If the Default Elaboration Behavior Fails:: - * Elaboration for Access-to-Subprogram Values:: - * Summary of Procedures for Elaboration Control:: - * Other Elaboration Order Considerations:: - - The Cross-Referencing Tools gnatxref and gnatfind - - * gnatxref Switches:: - * gnatfind Switches:: - * Project Files for gnatxref and gnatfind:: - * Regular Expressions in gnatfind and gnatxref:: - * Examples of gnatxref Usage:: - * Examples of gnatfind Usage:: - - File Name Krunching Using gnatkr - - * About gnatkr:: - * Using gnatkr:: - * Krunching Method:: - * Examples of gnatkr Usage:: - - Preprocessing Using gnatprep - - * Using gnatprep:: - * Switches for gnatprep:: - * Form of Definitions File:: - * Form of Input Text for gnatprep:: - - - The GNAT Library Browser gnatls - - * Running gnatls:: - * Switches for gnatls:: - * Examples of gnatls Usage:: - - - GNAT and Libraries - - * Creating an Ada Library:: - * Installing an Ada Library:: - * Using an Ada Library:: - * Creating an Ada Library to be Used in a Non-Ada Context:: - * Rebuilding the GNAT Run-Time Library:: - - Using the GNU make Utility - - * Using gnatmake in a Makefile:: - * Automatically Creating a List of Directories:: - * Generating the Command Line Switches:: - * Overcoming Command Line Length Limits:: - - Finding Memory Problems with gnatmem - - * Running gnatmem (GDB Mode):: - * Running gnatmem (GMEM Mode):: - * Switches for gnatmem:: - * Examples of gnatmem Usage:: - * GDB and GMEM Modes:: - * Implementation Note:: - - - Finding Memory Problems with GNAT Debug Pool - - Creating Sample Bodies Using gnatstub - - * Running gnatstub:: - * Switches for gnatstub:: - - Reducing the Size of Ada Executables with gnatelim - - * About gnatelim:: - * Eliminate Pragma:: - * Tree Files:: - * Preparing Tree and Bind Files for gnatelim:: - * Running gnatelim:: - * Correcting the List of Eliminate Pragmas:: - * Making Your Executables Smaller:: - * Summary of the gnatelim Usage Cycle:: - - Other Utility Programs - - * Using Other Utility Programs with GNAT:: - * The gnatpsta Utility Program:: - * The External Symbol Naming Scheme of GNAT:: - * Ada Mode for Glide:: - * Converting Ada Files to html with gnathtml:: - - - Running and Debugging Ada Programs - - * The GNAT Debugger GDB:: - * Running GDB:: - * Introduction to GDB Commands:: - * Using Ada Expressions:: - * Calling User-Defined Subprograms:: - * Using the Next Command in a Function:: - * Ada Exceptions:: - * Ada Tasks:: - * Debugging Generic Units:: - * GNAT Abnormal Termination or Failure to Terminate:: - * Naming Conventions for GNAT Source Files:: - * Getting Internal Debugging Information:: - * Stack Traceback:: - - Inline Assembler - - * Basic Assembler Syntax:: - * A Simple Example of Inline Assembler:: - * Output Variables in Inline Assembler:: - * Input Variables in Inline Assembler:: - * Inlining Inline Assembler Code:: - * Other Asm Functionality:: - * A Complete Example:: - - Microsoft Windows Topics - - * Using GNAT on Windows:: - * GNAT Setup Tool:: - * CONSOLE and WINDOWS subsystems:: - * Temporary Files:: - * Mixed-Language Programming on Windows:: - * Windows Calling Conventions:: - * Introduction to Dynamic Link Libraries (DLLs):: - * Using DLLs with GNAT:: - * Building DLLs with GNAT:: - * GNAT and Windows Resources:: - * GNAT and COM/DCOM Objects:: - - - Performance Considerations - - * Controlling Run-Time Checks:: - * Optimization Levels:: - * Debugging Optimized Code:: - * Inlining of Subprograms:: - - * Index:: - -  - File: gnat_ug_wnt.info, Node: About This Guide, Next: Getting Started with GNAT, Prev: Top, Up: Top - - About This Guide - **************** - - This guide describes the use of GNAT, a compiler and software - development toolset for the full Ada 95 programming language. It - describes the features of the compiler and tools, and details how to - use them to build Ada 95 applications. - - * Menu: - - * What This Guide Contains:: - * What You Should Know before Reading This Guide:: - * Related Information:: - * Conventions:: - -  - File: gnat_ug_wnt.info, Node: What This Guide Contains, Next: What You Should Know before Reading This Guide, Up: About This Guide - - What This Guide Contains - ======================== - - This guide contains the following chapters: - * *Note Getting Started with GNAT::, describes how to get started - compiling and running Ada programs with the GNAT Ada programming - environment. - - * *Note The GNAT Compilation Model::, describes the compilation - model used by GNAT. - - * *Note Compiling Using gcc::, describes how to compile Ada programs - with `gcc', the Ada compiler. - - * *Note Binding Using gnatbind::, describes how to perform binding - of Ada programs with `gnatbind', the GNAT binding utility. - - * *Note Linking Using gnatlink::, describes `gnatlink', a program - that provides for linking using the GNAT run-time library to - construct a program. `gnatlink' can also incorporate foreign - language object units into the executable. - - * *Note The GNAT Make Program gnatmake::, describes `gnatmake', a - utility that automatically determines the set of sources needed by - an Ada compilation unit, and executes the necessary compilations - binding and link. - - * *Note Renaming Files Using gnatchop::, describes `gnatchop', a - utility that allows you to preprocess a file that contains Ada - source code, and split it into one or more new files, one for each - compilation unit. - - * *Note Configuration Pragmas::, describes the configuration pragmas - handled by GNAT. - - * *Note Handling Arbitrary File Naming Conventions Using gnatname::, - shows how to override the default GNAT file naming conventions, - either for an individual unit or globally. - - * *Note GNAT Project Manager::, describes how to use project files - to organize large projects. - - * *Note Elaboration Order Handling in GNAT::, describes how GNAT - helps you deal with elaboration order issues. - - * *Note The Cross-Referencing Tools gnatxref and gnatfind::, - discusses `gnatxref' and `gnatfind', two tools that provide an easy - way to navigate through sources. - - * *Note File Name Krunching Using gnatkr::, describes the `gnatkr' - file name krunching utility, used to handle shortened file names - on operating systems with a limit on the length of names. - - * *Note Preprocessing Using gnatprep::, describes `gnatprep', a - preprocessor utility that allows a single source file to be used to - generate multiple or parameterized source files, by means of macro - substitution. - - * *Note The GNAT Library Browser gnatls::, describes `gnatls', a - utility that displays information about compiled units, including - dependences on the corresponding sources files, and consistency of - compilations. - - * *Note GNAT and Libraries::, describes the process of creating and - using Libraries with GNAT. It also describes how to recompile the - GNAT run-time library. - - * *Note Using the GNU make Utility::, describes some techniques for - using the GNAT toolset in Makefiles. - - * *Note Finding Memory Problems with gnatmem::, describes `gnatmem', - a utility that monitors dynamic allocation and deallocation - activity in a program, and displays information about incorrect - deallocations and sources of possible memory leaks. - - * *Note Finding Memory Problems with GNAT Debug Pool::, describes - how to use the GNAT-specific Debug Pool in order to detect as - early as possible the use of incorrect memory references. - - * *Note Creating Sample Bodies Using gnatstub::, discusses - `gnatstub', a utility that generates empty but compilable bodies - for library units. - - * *Note Reducing the Size of Ada Executables with gnatelim::, - describes `gnatelim', a tool which detects unused subprograms and - helps the compiler to create a smaller executable for the program. - - * *Note Other Utility Programs::, discusses several other GNAT - utilities, including `gnatpsta'. - - * *Note Running and Debugging Ada Programs::, describes how to run - and debug Ada programs. - - * *Note Inline Assembler::, shows how to use the inline assembly - facility in an Ada program. - - * *Note Performance Considerations::, reviews the trade offs between - using defaults or options in program development. - -  - File: gnat_ug_wnt.info, Node: What You Should Know before Reading This Guide, Next: Related Information, Prev: What This Guide Contains, Up: About This Guide - - What You Should Know before Reading This Guide - ============================================== - - This user's guide assumes that you are familiar with Ada 95 language, as - described in the International Standard ANSI/ISO/IEC-8652:1995, Jan - 1995. - -  - File: gnat_ug_wnt.info, Node: Related Information, Next: Conventions, Prev: What You Should Know before Reading This Guide, Up: About This Guide - - Related Information - =================== - - For further information about related tools, refer to the following - documents: - - * `GNAT Reference Manual', which contains all reference material for - the GNAT implementation of Ada 95. - - * `Ada 95 Language Reference Manual', which contains all reference - material for the Ada 95 programming language. - - * `Debugging with GDB' contains all details on the use of the GNU - source-level debugger. - - * `GNU Emacs Manual' contains full information on the extensible - editor and programming environment Emacs. - - -  - File: gnat_ug_wnt.info, Node: Conventions, Prev: Related Information, Up: About This Guide - - Conventions - =========== - - Following are examples of the typographical and graphic conventions used - in this guide: - - * `Functions', `utility program names', `standard names', and - `classes'. - - * `Option flags' - - * `File Names', `button names', and `field names'. - - * VARIABLES. - - * _Emphasis_. - - * [optional information or parameters] - - * Examples are described by text - and then shown this way. - - Commands that are entered by the user are preceded in this manual by the - characters "`$ '" (dollar sign followed by space). If your system uses - this sequence as a prompt, then the commands will appear exactly as you - see them in the manual. If your system uses some other prompt, then the - command will appear with the `$' replaced by whatever prompt character - you are using. - -  - File: gnat_ug_wnt.info, Node: Getting Started with GNAT, Next: The GNAT Compilation Model, Prev: About This Guide, Up: Top - - Getting Started with GNAT - ************************* - - This chapter describes some simple ways of using GNAT to build - executable Ada programs. - - * Menu: - - * Running GNAT:: - * Running a Simple Ada Program:: - - * Running a Program with Multiple Units:: - - * Using the gnatmake Utility:: - * Introduction to Glide and GVD:: - -  - File: gnat_ug_wnt.info, Node: Running GNAT, Next: Running a Simple Ada Program, Up: Getting Started with GNAT - - Running GNAT - ============ - - Three steps are needed to create an executable file from an Ada source - file: - - 1. The source file(s) must be compiled. - - 2. The file(s) must be bound using the GNAT binder. - - 3. All appropriate object files must be linked to produce an - executable. - - All three steps are most commonly handled by using the `gnatmake' - utility program that, given the name of the main program, automatically - performs the necessary compilation, binding and linking steps. - -  - File: gnat_ug_wnt.info, Node: Running a Simple Ada Program, Next: Running a Program with Multiple Units, Prev: Running GNAT, Up: Getting Started with GNAT - - Running a Simple Ada Program - ============================ - - Any text editor may be used to prepare an Ada program. If `Glide' is - used, the optional Ada mode may be helpful in laying out the program. - The program text is a normal text file. We will suppose in our initial - example that you have used your editor to prepare the following - standard format text file: - - with Ada.Text_IO; use Ada.Text_IO; - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - This file should be named `hello.adb'. With the normal default file - naming conventions, GNAT requires that each file contain a single - compilation unit whose file name is the unit name, with periods - replaced by hyphens; the extension is `ads' for a spec and `adb' for a - body. You can override this default file naming convention by use of - the special pragma `Source_File_Name' (*note Using Other File Names::). - Alternatively, if you want to rename your files according to this - default convention, which is probably more convenient if you will be - using GNAT for all your compilations, then the `gnatchop' utility can - be used to generate correctly-named source files (*note Renaming Files - Using gnatchop::). - - You can compile the program using the following command (`$' is used - as the command prompt in the examples in this document): - - $ gcc -c hello.adb - - `gcc' is the command used to run the compiler. This compiler is capable - of compiling programs in several languages, including Ada 95 and C. It - assumes that you have given it an Ada program if the file extension is - either `.ads' or `.adb', and it will then call the GNAT compiler to - compile the specified file. - - The `-c' switch is required. It tells `gcc' to only do a - compilation. (For C programs, `gcc' can also do linking, but this - capability is not used directly for Ada programs, so the `-c' switch - must always be present.) - - This compile command generates a file `hello.o', which is the object - file corresponding to your Ada program. It also generates an "Ada - Library Information" file `hello.ali', which contains additional - information used to check that an Ada program is consistent. To build - an executable file, use `gnatbind' to bind the program and `gnatlink' - to link it. The argument to both `gnatbind' and `gnatlink' is the name - of the `ali' file, but the default extension of `.ali' can be omitted. - This means that in the most common case, the argument is simply the - name of the main program: - - $ gnatbind hello - $ gnatlink hello - - A simpler method of carrying out these steps is to use `gnatmake', a - master program that invokes all the required compilation, binding and - linking tools in the correct order. In particular, `gnatmake' - automatically recompiles any sources that have been modified since they - were last compiled, or sources that depend on such modified sources, so - that "version skew" is avoided. - - $ gnatmake hello.adb - - The result is an executable program called `hello', which can be run by - entering: - - $ hello - - assuming that the current directory is on the search path for - executable programs. - - and, if all has gone well, you will see - - Hello WORLD! - - appear in response to this command. - -  - File: gnat_ug_wnt.info, Node: Running a Program with Multiple Units, Next: Using the gnatmake Utility, Prev: Running a Simple Ada Program, Up: Getting Started with GNAT - - Running a Program with Multiple Units - ===================================== - - Consider a slightly more complicated example that has three files: a - main program, and the spec and body of a package: - - package Greetings is - procedure Hello; - procedure Goodbye; - end Greetings; - - with Ada.Text_IO; use Ada.Text_IO; - package body Greetings is - procedure Hello is - begin - Put_Line ("Hello WORLD!"); - end Hello; - - procedure Goodbye is - begin - Put_Line ("Goodbye WORLD!"); - end Goodbye; - end Greetings; - - with Greetings; - procedure Gmain is - begin - Greetings.Hello; - Greetings.Goodbye; - end Gmain; - - Following the one-unit-per-file rule, place this program in the - following three separate files: - - `greetings.ads' - spec of package `Greetings' - - `greetings.adb' - body of package `Greetings' - - `gmain.adb' - body of main program - - To build an executable version of this program, we could use four - separate steps to compile, bind, and link the program, as follows: - - $ gcc -c gmain.adb - $ gcc -c greetings.adb - $ gnatbind gmain - $ gnatlink gmain - - Note that there is no required order of compilation when using GNAT. - In particular it is perfectly fine to compile the main program first. - Also, it is not necessary to compile package specs in the case where - there is an accompanying body; you only need to compile the body. If - you want to submit these files to the compiler for semantic checking - and not code generation, then use the `-gnatc' switch: - - $ gcc -c greetings.ads -gnatc - - Although the compilation can be done in separate steps as in the above - example, in practice it is almost always more convenient to use the - `gnatmake' tool. All you need to know in this case is the name of the - main program's source file. The effect of the above four commands can - be achieved with a single one: - - $ gnatmake gmain.adb - - In the next section we discuss the advantages of using `gnatmake' in - more detail. - -  - File: gnat_ug_wnt.info, Node: Using the gnatmake Utility, Next: Introduction to Glide and GVD, Prev: Running a Program with Multiple Units, Up: Getting Started with GNAT - - Using the `gnatmake' Utility - ============================ - - If you work on a program by compiling single components at a time using - `gcc', you typically keep track of the units you modify. In order to - build a consistent system, you compile not only these units, but also - any units that depend on the units you have modified. For example, in - the preceding case, if you edit `gmain.adb', you only need to recompile - that file. But if you edit `greetings.ads', you must recompile both - `greetings.adb' and `gmain.adb', because both files contain units that - depend on `greetings.ads'. - - `gnatbind' will warn you if you forget one of these compilation - steps, so that it is impossible to generate an inconsistent program as a - result of forgetting to do a compilation. Nevertheless it is tedious and - error-prone to keep track of dependencies among units. One approach to - handle the dependency-bookkeeping is to use a makefile. However, - makefiles present maintenance problems of their own: if the - dependencies change as you change the program, you must make sure that - the makefile is kept up-to-date manually, which is also an error-prone - process. - - The `gnatmake' utility takes care of these details automatically. - Invoke it using either one of the following forms: - - $ gnatmake gmain.adb - $ gnatmake gmain - - The argument is the name of the file containing the main program; you - may omit the extension. `gnatmake' examines the environment, - automatically recompiles any files that need recompiling, and binds and - links the resulting set of object files, generating the executable - file, `gmain'. In a large program, it can be extremely helpful to use - `gnatmake', because working out by hand what needs to be recompiled can - be difficult. - - Note that `gnatmake' takes into account all the Ada 95 rules that - establish dependencies among units. These include dependencies that - result from inlining subprogram bodies, and from generic instantiation. - Unlike some other Ada make tools, `gnatmake' does not rely on the - dependencies that were found by the compiler on a previous compilation, - which may possibly be wrong when sources change. `gnatmake' determines - the exact set of dependencies from scratch each time it is run. - -  - File: gnat_ug_wnt.info, Node: Introduction to Glide and GVD, Prev: Using the gnatmake Utility, Up: Getting Started with GNAT - - Introduction to Glide and GVD - ============================= - - Although it is possible to develop programs using only the command line - interface (`gnatmake', etc.) a graphical Interactive Development - Environment can make it easier for you to compose, navigate, and debug - programs. This section describes the main features of Glide, the GNAT - graphical IDE, and also shows how to use the basic commands in GVD, the - GNU Visual Debugger. Additional information may be found in the - on-line help for these tools. - - * Menu: - - * Building a New Program with Glide:: - * Simple Debugging with GVD:: - * Other Glide Features:: - -  - File: gnat_ug_wnt.info, Node: Building a New Program with Glide, Next: Simple Debugging with GVD, Up: Introduction to Glide and GVD - - Building a New Program with Glide - --------------------------------- - - The simplest way to invoke Glide is to enter `glide' at the command - prompt. It will generally be useful to issue this as a background - command, thus allowing you to continue using your command window for - other purposes while Glide is running: - - $ glide& - - Glide will start up with an initial screen displaying the top-level - menu items as well as some other information. The menu selections are - as follows - * `Buffers' - - * `Files' - - * `Tools' - - * `Edit' - - * `Search' - - * `Mule' - - * `Glide' - - * `Help' - - For this introductory example, you will need to create a new Ada source - file. First, select the `Files' menu. This will pop open a menu with - around a dozen or so items. To create a file, select the `Open - file...' choice. Depending on the platform, you may see a pop-up - window where you can browse to an appropriate directory and then enter - the file name, or else simply see a line at the bottom of the Glide - window where you can likewise enter the file name. Note that in Glide, - when you attempt to open a non-existent file, the effect is to create a - file with that name. For this example enter `hello.adb' as the name of - the file. - - A new buffer will now appear, occupying the entire Glide window, - with the file name at the top. The menu selections are slightly - different from the ones you saw on the opening screen; there is an - `Entities' item, and in place of `Glide' there is now an `Ada' item. - Glide uses the file extension to identify the source language, so `adb' - indicates an Ada source file. - - You will enter some of the source program lines explicitly, and use - the syntax-oriented template mechanism to enter other lines. First, - type the following text: - with Ada.Text_IO; use Ada.Text_IO; - procedure Hello is - begin - - Observe that Glide uses different colors to distinguish reserved words - from identifiers. Also, after the `procedure Hello is' line, the - cursor is automatically indented in anticipation of declarations. When - you enter `begin', Glide recognizes that there are no declarations and - thus places `begin' flush left. But after the `begin' line the cursor - is again indented, where the statement(s) will be placed. - - The main part of the program will be a `for' loop. Instead of - entering the text explicitly, however, use a statement template. - Select the `Ada' item on the top menu bar, move the mouse to the - `Statements' item, and you will see a large selection of alternatives. - Choose `for loop'. You will be prompted (at the bottom of the buffer) - for a loop name; simply press the key since a loop name is not - needed. You should see the beginning of a `for' loop appear in the - source program window. You will now be prompted for the name of the - loop variable; enter a line with the identifier `ind' (lower case). - Note that, by default, Glide capitalizes the name (you can override - such behavior if you wish, although this is outside the scope of this - introduction). Next, Glide prompts you for the loop range; enter a - line containing `1..5' and you will see this also appear in the source - program, together with the remaining elements of the `for' loop syntax. - - Next enter the statement (with an intentional error, a missing - semicolon) that will form the body of the loop: - Put_Line("Hello, World" & Integer'Image(I)) - - Finally, type `end Hello;' as the last line in the program. Now save - the file: choose the `File' menu item, and then the `Save buffer' - selection. You will see a message at the bottom of the buffer - confirming that the file has been saved. - - You are now ready to attempt to build the program. Select the `Ada' - item from the top menu bar. Although we could choose simply to compile - the file, we will instead attempt to do a build (which invokes - `gnatmake') since, if the compile is successful, we want to build an - executable. Thus select `Ada build'. This will fail because of the - compilation error, and you will notice that the Glide window has been - split: the top window contains the source file, and the bottom window - contains the output from the GNAT tools. Glide allows you to navigate - from a compilation error to the source file position corresponding to - the error: click the middle mouse button (or simultaneously press the - left and right buttons, on a two-button mouse) on the diagnostic line - in the tool window. The focus will shift to the source window, and the - cursor will be positioned on the character at which the error was - detected. - - Correct the error: type in a semicolon to terminate the statement. - Although you can again save the file explicitly, you can also simply - invoke `Ada' => `Build' and you will be prompted to save the file. - This time the build will succeed; the tool output window shows you the - options that are supplied by default. The GNAT tools' output (e.g., - object and ALI files, executable) will go in the directory from which - Glide was launched. - - To execute the program, choose `Ada' and then `Run'. You should see - the program's output displayed in the bottom window: - - Hello, world 1 - Hello, world 2 - Hello, world 3 - Hello, world 4 - Hello, world 5 - -  - File: gnat_ug_wnt.info, Node: Simple Debugging with GVD, Next: Other Glide Features, Prev: Building a New Program with Glide, Up: Introduction to Glide and GVD - - Simple Debugging with GVD - ------------------------- - - This section describes how to set breakpoints, examine/modify - variables, and step through execution. - - In order to enable debugging, you need to pass the `-g' switch to - both the compiler and to `gnatlink'. If you are using the command - line, passing `-g' to `gnatmake' will have this effect. You can then - launch GVD, e.g. on the `hello' program, by issuing the command: - - $ gvd hello - - If you are using Glide, then `-g' is passed to the relevant tools by - default when you do a build. Start the debugger by selecting the `Ada' - menu item, and then `Debug'. - - GVD comes up in a multi-part window. One pane shows the names of - files comprising your executable; another pane shows the source code of - the current unit (initially your main subprogram), another pane shows - the debugger output and user interactions, and the fourth pane (the - data canvas at the top of the window) displays data objects that you - have selected. - - To the left of the source file pane, you will notice green dots - adjacent to some lines. These are lines for which object code exists - and where breakpoints can thus be set. You set/reset a breakpoint by - clicking the green dot. When a breakpoint is set, the dot is replaced - by an `X' in a red circle. Clicking the circle toggles the breakpoint - off, and the red circle is replaced by the green dot. - - For this example, set a breakpoint at the statement where `Put_Line' - is invoked. - - Start program execution by selecting the `Run' button on the top - menu bar. (The `Start' button will also start your program, but it - will cause program execution to break at the entry to your main - subprogram.) Evidence of reaching the breakpoint will appear: the - source file line will be highlighted, and the debugger interactions - pane will display a relevant message. - - You can examine the values of variables in several ways. Move the - mouse over an occurrence of `Ind' in the `for' loop, and you will see - the value (now `1') displayed. Alternatively, right-click on `Ind' and - select `Display Ind'; a box showing the variable's name and value will - appear in the data canvas. - - Although a loop index is a constant with respect to Ada semantics, - you can change its value in the debugger. Right-click in the box for - `Ind', and select the `Set Value of Ind' item. Enter `2' as the new - value, and press `OK'. The box for `Ind' shows the update. - - Press the `Step' button on the top menu bar; this will step through - one line of program text (the invocation of `Put_Line'), and you can - observe the effect of having modified `Ind' since the value displayed - is `2'. - - Remove the breakpoint, and resume execution by selecting the `Cont' - button. You will see the remaining output lines displayed in the - debugger interaction window, along with a message confirming normal - program termination. - -  - File: gnat_ug_wnt.info, Node: Other Glide Features, Prev: Simple Debugging with GVD, Up: Introduction to Glide and GVD - - Other Glide Features - -------------------- - - You may have observed that some of the menu selections contain - abbreviations; e.g., `(C-x C-f)' for `Open file...' in the `Files' - menu. These are _shortcut keys_ that you can use instead of selecting - menu items. The stands for ; thus `(C-x C-f)' means - followed by , and this sequence can be used instead of - selecting `Files' and then `Open file...'. - - To abort a Glide command, type . - - If you want Glide to start with an existing source file, you can - either launch Glide as above and then open the file via `Files' => - `Open file...', or else simply pass the name of the source file on the - command line: - - $ glide hello.adb& - - While you are using Glide, a number of _buffers_ exist. You create - some explicitly; e.g., when you open/create a file. Others arise as an - effect of the commands that you issue; e.g., the buffer containing the - output of the tools invoked during a build. If a buffer is hidden, you - can bring it into a visible window by first opening the `Buffers' menu - and then selecting the desired entry. - - If a buffer occupies only part of the Glide screen and you want to - expand it to fill the entire screen, then click in the buffer and then - select `Files' => `One Window'. - - If a window is occupied by one buffer and you want to split the - window to bring up a second buffer, perform the following steps: - * Select `Files' => `Split Window'; this will produce two windows - each of which holds the original buffer (these are not copies, but - rather different views of the same buffer contents) - - * With the focus in one of the windows, select the desired buffer - from the `Buffers' menu - - To exit from Glide, choose `Files' => `Exit'. - -  - File: gnat_ug_wnt.info, Node: The GNAT Compilation Model, Next: Compiling Using gcc, Prev: Getting Started with GNAT, Up: Top - - The GNAT Compilation Model - ************************** - - * Menu: - - * Source Representation:: - * Foreign Language Representation:: - * File Naming Rules:: - * Using Other File Names:: - * Alternative File Naming Schemes:: - * Generating Object Files:: - * Source Dependencies:: - * The Ada Library Information Files:: - * Binding an Ada Program:: - * Mixed Language Programming:: - * Building Mixed Ada & C++ Programs:: - * Comparison between GNAT and C/C++ Compilation Models:: - * Comparison between GNAT and Conventional Ada Library Models:: - - This chapter describes the compilation model used by GNAT. Although - similar to that used by other languages, such as C and C++, this model - is substantially different from the traditional Ada compilation models, - which are based on a library. The model is initially described without - reference to the library-based model. If you have not previously used an - Ada compiler, you need only read the first part of this chapter. The - last section describes and discusses the differences between the GNAT - model and the traditional Ada compiler models. If you have used other - Ada compilers, this section will help you to understand those - differences, and the advantages of the GNAT model. - -  - File: gnat_ug_wnt.info, Node: Source Representation, Next: Foreign Language Representation, Up: The GNAT Compilation Model - - Source Representation - ===================== - - Ada source programs are represented in standard text files, using - Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar - 7-bit ASCII set, plus additional characters used for representing - foreign languages (*note Foreign Language Representation:: for support - of non-USA character sets). The format effector characters are - represented using their standard ASCII encodings, as follows: - - `VT' - Vertical tab, `16#0B#' - - `HT' - Horizontal tab, `16#09#' - - `CR' - Carriage return, `16#0D#' - - `LF' - Line feed, `16#0A#' - - `FF' - Form feed, `16#0C#' - - Source files are in standard text file format. In addition, GNAT will - recognize a wide variety of stream formats, in which the end of physical - physical lines is marked by any of the following sequences: `LF', `CR', - `CR-LF', or `LF-CR'. This is useful in accommodating files that are - imported from other operating systems. - - The end of a source file is normally represented by the physical end - of file. However, the control character `16#1A#' (`SUB') is also - recognized as signalling the end of the source file. Again, this is - provided for compatibility with other operating systems where this code - is used to represent the end of file. - - Each file contains a single Ada compilation unit, including any - pragmas associated with the unit. For example, this means you must - place a package declaration (a package "spec") and the corresponding - body in separate files. An Ada "compilation" (which is a sequence of - compilation units) is represented using a sequence of files. Similarly, - you will place each subunit or child unit in a separate file. - -  - File: gnat_ug_wnt.info, Node: Foreign Language Representation, Next: File Naming Rules, Prev: Source Representation, Up: The GNAT Compilation Model - - Foreign Language Representation - =============================== - - GNAT supports the standard character sets defined in Ada 95 as well as - several other non-standard character sets for use in localized versions - of the compiler (*note Character Set Control::). - - * Menu: - - * Latin-1:: - * Other 8-Bit Codes:: - * Wide Character Encodings:: - -  - File: gnat_ug_wnt.info, Node: Latin-1, Next: Other 8-Bit Codes, Up: Foreign Language Representation - - Latin-1 - ------- - - The basic character set is Latin-1. This character set is defined by ISO - standard 8859, part 1. The lower half (character codes `16#00#' ... - `16#7F#)' is identical to standard ASCII coding, but the upper half is - used to represent additional characters. These include extended letters - used by European languages, such as French accents, the vowels with - umlauts used in German, and the extra letter A-ring used in Swedish. - - For a complete list of Latin-1 codes and their encodings, see the - source file of library unit `Ada.Characters.Latin_1' in file - `a-chlat1.ads'. You may use any of these extended characters freely in - character or string literals. In addition, the extended characters that - represent letters can be used in identifiers. - -  - File: gnat_ug_wnt.info, Node: Other 8-Bit Codes, Next: Wide Character Encodings, Prev: Latin-1, Up: Foreign Language Representation - - Other 8-Bit Codes - ----------------- - - GNAT also supports several other 8-bit coding schemes: - - Latin-2 - Latin-2 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-3 - Latin-3 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-4 - Latin-4 letters allowed in identifiers, with uppercase and - lowercase equivalence. - - Latin-5 - Latin-4 letters (Cyrillic) allowed in identifiers, with uppercase - and lowercase equivalence. - - IBM PC (code page 437) - This code page is the normal default for PCs in the U.S. It - corresponds to the original IBM PC character set. This set has - some, but not all, of the extended Latin-1 letters, but these - letters do not have the same encoding as Latin-1. In this mode, - these letters are allowed in identifiers with uppercase and - lowercase equivalence. - - IBM PC (code page 850) - This code page is a modification of 437 extended to include all the - Latin-1 letters, but still not with the usual Latin-1 encoding. In - this mode, all these letters are allowed in identifiers with - uppercase and lowercase equivalence. - - Full Upper 8-bit - Any character in the range 80-FF allowed in identifiers, and all - are considered distinct. In other words, there are no uppercase - and lowercase equivalences in this range. This is useful in - conjunction with certain encoding schemes used for some foreign - character sets (e.g. the typical method of representing Chinese - characters on the PC). - - No Upper-Half - No upper-half characters in the range 80-FF are allowed in - identifiers. This gives Ada 83 compatibility for identifier names. - - For precise data on the encodings permitted, and the uppercase and - lowercase equivalences that are recognized, see the file `csets.adb' in - the GNAT compiler sources. You will need to obtain a full source release - of GNAT to obtain this file. - -  - File: gnat_ug_wnt.info, Node: Wide Character Encodings, Prev: Other 8-Bit Codes, Up: Foreign Language Representation - - Wide Character Encodings - ------------------------ - - GNAT allows wide character codes to appear in character and string - literals, and also optionally in identifiers, by means of the following - possible encoding schemes: - - Hex Coding - In this encoding, a wide character is represented by the following - five character sequence: - - ESC a b c d - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For example, - ESC A345 is used to represent the wide character with code - `16#A345#'. This scheme is compatible with use of the full - Wide_Character set. - - Upper-Half Coding - The wide character with encoding `16#abcd#' where the upper bit is - on (in other words, "a" is in the range 8-F) is represented as two - bytes, `16#ab#' and `16#cd#'. The second byte cannot be a format - control character, but is not required to be in the upper half. - This method can be also used for shift-JIS or EUC, where the - internal coding matches the external coding. - - Shift JIS Coding - A wide character is represented by a two-character sequence, - `16#ab#' and `16#cd#', with the restrictions described for - upper-half encoding as described above. The internal character - code is the corresponding JIS character according to the standard - algorithm for Shift-JIS conversion. Only characters defined in the - JIS code set table can be used with this encoding method. - - EUC Coding - A wide character is represented by a two-character sequence - `16#ab#' and `16#cd#', with both characters being in the upper - half. The internal character code is the corresponding JIS - character according to the EUC encoding algorithm. Only characters - defined in the JIS code set table can be used with this encoding - method. - - UTF-8 Coding - A wide character is represented using UCS Transformation Format 8 - (UTF-8) as defined in Annex R of ISO 10646-1/Am.2. Depending on - the character value, the representation is a one, two, or three - byte sequence: - 16#0000#-16#007f#: 2#0xxxxxxx# - 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# - 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# - - where the xxx bits correspond to the left-padded bits of the - 16-bit character value. Note that all lower half ASCII characters - are represented as ASCII bytes and all upper half characters and - other wide characters are represented as sequences of upper-half - (The full UTF-8 scheme allows for encoding 31-bit characters as - 6-byte sequences, but in this implementation, all UTF-8 sequences - of four or more bytes length will be treated as illegal). - - Brackets Coding - In this encoding, a wide character is represented by the following - eight character sequence: - - [ " a b c d " ] - - Where `a', `b', `c', `d' are the four hexadecimal characters - (using uppercase letters) of the wide character code. For example, - ["A345"] is used to represent the wide character with code - `16#A345#'. It is also possible (though not required) to use the - Brackets coding for upper half characters. For example, the code - `16#A3#' can be represented as `["A3"]'. - - This scheme is compatible with use of the full Wide_Character set, - and is also the method used for wide character encoding in the - standard ACVC (Ada Compiler Validation Capability) test suite - distributions. - - Note: Some of these coding schemes do not permit the full use of the - Ada 95 character set. For example, neither Shift JIS, nor EUC allow the - use of the upper half of the Latin-1 set. - -  - File: gnat_ug_wnt.info, Node: File Naming Rules, Next: Using Other File Names, Prev: Foreign Language Representation, Up: The GNAT Compilation Model - - File Naming Rules - ================= - - The default file name is determined by the name of the unit that the - file contains. The name is formed by taking the full expanded name of - the unit and replacing the separating dots with hyphens and using - lowercase for all letters. - - An exception arises if the file name generated by the above rules - starts with one of the characters a,g,i, or s, and the second character - is a minus. In this case, the character tilde is used in place of the - minus. The reason for this special rule is to avoid clashes with the - standard names for child units of the packages System, Ada, Interfaces, - and GNAT, which use the prefixes s- a- i- and g- respectively. - - The file extension is `.ads' for a spec and `.adb' for a body. The - following list shows some examples of these rules. - - `main.ads' - Main (spec) - - `main.adb' - Main (body) - - `arith_functions.ads' - Arith_Functions (package spec) - - `arith_functions.adb' - Arith_Functions (package body) - - `func-spec.ads' - Func.Spec (child package spec) - - `func-spec.adb' - Func.Spec (child package body) - - `main-sub.adb' - Sub (subunit of Main) - - `a~bad.adb' - A.Bad (child package body) - - Following these rules can result in excessively long file names if - corresponding unit names are long (for example, if child units or - subunits are heavily nested). An option is available to shorten such - long file names (called file name "krunching"). This may be - particularly useful when programs being developed with GNAT are to be - used on operating systems with limited file name lengths. *Note Using - gnatkr::. - - Of course, no file shortening algorithm can guarantee uniqueness over - all possible unit names; if file name krunching is used, it is your - responsibility to ensure no name clashes occur. Alternatively you can - specify the exact file names that you want used, as described in the - next section. Finally, if your Ada programs are migrating from a - compiler with a different naming convention, you can use the gnatchop - utility to produce source files that follow the GNAT naming conventions. - (For details *note Renaming Files Using gnatchop::.) - -  - File: gnat_ug_wnt.info, Node: Using Other File Names, Next: Alternative File Naming Schemes, Prev: File Naming Rules, Up: The GNAT Compilation Model - - Using Other File Names - ====================== - - In the previous section, we have described the default rules used by - GNAT to determine the file name in which a given unit resides. It is - often convenient to follow these default rules, and if you follow them, - the compiler knows without being explicitly told where to find all the - files it needs. - - However, in some cases, particularly when a program is imported from - another Ada compiler environment, it may be more convenient for the - programmer to specify which file names contain which units. GNAT allows - arbitrary file names to be used by means of the Source_File_Name pragma. - The form of this pragma is as shown in the following examples: - - pragma Source_File_Name (My_Utilities.Stacks, - Spec_File_Name => "myutilst_a.ada"); - pragma Source_File_name (My_Utilities.Stacks, - Body_File_Name => "myutilst.ada"); - - As shown in this example, the first argument for the pragma is the unit - name (in this example a child unit). The second argument has the form - of a named association. The identifier indicates whether the file name - is for a spec or a body; the file name itself is given by a string - literal. - - The source file name pragma is a configuration pragma, which means - that normally it will be placed in the `gnat.adc' file used to hold - configuration pragmas that apply to a complete compilation environment. - For more details on how the `gnat.adc' file is created and used *note - Handling of Configuration Pragmas:: - - GNAT allows completely arbitrary file names to be specified using the - source file name pragma. However, if the file name specified has an - extension other than `.ads' or `.adb' it is necessary to use a special - syntax when compiling the file. The name in this case must be preceded - by the special sequence `-x' followed by a space and the name of the - language, here `ada', as in: - - $ gcc -c -x ada peculiar_file_name.sim - - `gnatmake' handles non-standard file names in the usual manner (the - non-standard file name for the main program is simply used as the - argument to gnatmake). Note that if the extension is also non-standard, - then it must be included in the gnatmake command, it may not be omitted. - -  - File: gnat_ug_wnt.info, Node: Alternative File Naming Schemes, Next: Generating Object Files, Prev: Using Other File Names, Up: The GNAT Compilation Model - - Alternative File Naming Schemes - =============================== - - In the previous section, we described the use of the - `Source_File_Name' pragma to allow arbitrary names to be assigned to - individual source files. However, this approach requires one pragma - for each file, and especially in large systems can result in very long - `gnat.adc' files, and also create a maintenance problem. - - GNAT also provides a facility for specifying systematic file naming - schemes other than the standard default naming scheme previously - described. An alternative scheme for naming is specified by the use of - `Source_File_Name' pragmas having the following format: - - pragma Source_File_Name ( - Spec_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name ( - Body_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - pragma Source_File_Name ( - Subunit_File_Name => FILE_NAME_PATTERN - [,Casing => CASING_SPEC] - [,Dot_Replacement => STRING_LITERAL]); - - FILE_NAME_PATTERN ::= STRING_LITERAL - CASING_SPEC ::= Lowercase | Uppercase | Mixedcase - - The `FILE_NAME_PATTERN' string shows how the file name is constructed. - It contains a single asterisk character, and the unit name is - substituted systematically for this asterisk. The optional parameter - `Casing' indicates whether the unit name is to be all upper-case - letters, all lower-case letters, or mixed-case. If no `Casing' - parameter is used, then the default is all lower-case. - - The optional `Dot_Replacement' string is used to replace any periods - that occur in subunit or child unit names. If no `Dot_Replacement' - argument is used then separating dots appear unchanged in the resulting - file name. Although the above syntax indicates that the `Casing' - argument must appear before the `Dot_Replacement' argument, but it is - also permissible to write these arguments in the opposite order. - - As indicated, it is possible to specify different naming schemes for - bodies, specs, and subunits. Quite often the rule for subunits is the - same as the rule for bodies, in which case, there is no need to give a - separate `Subunit_File_Name' rule, and in this case the - `Body_File_name' rule is used for subunits as well. - - The separate rule for subunits can also be used to implement the - rather unusual case of a compilation environment (e.g. a single - directory) which contains a subunit and a child unit with the same unit - name. Although both units cannot appear in the same partition, the Ada - Reference Manual allows (but does not require) the possibility of the - two units coexisting in the same environment. - - The file name translation works in the following steps: - - * If there is a specific `Source_File_Name' pragma for the given - unit, then this is always used, and any general pattern rules are - ignored. - - * If there is a pattern type `Source_File_Name' pragma that applies - to the unit, then the resulting file name will be used if the file - exists. If more than one pattern matches, the latest one will be - tried first, and the first attempt resulting in a reference to a - file that exists will be used. - - * If no pattern type `Source_File_Name' pragma that applies to the - unit for which the corresponding file exists, then the standard - GNAT default naming rules are used. - - - As an example of the use of this mechanism, consider a commonly used - scheme in which file names are all lower case, with separating periods - copied unchanged to the resulting file name, and specs end with - ".1.ada", and bodies end with ".2.ada". GNAT will follow this scheme if - the following two pragmas appear: - - pragma Source_File_Name - (Spec_File_Name => "*.1.ada"); - pragma Source_File_Name - (Body_File_Name => "*.2.ada"); - - The default GNAT scheme is actually implemented by providing the - following default pragmas internally: - - pragma Source_File_Name - (Spec_File_Name => "*.ads", Dot_Replacement => "-"); - pragma Source_File_Name - (Body_File_Name => "*.adb", Dot_Replacement => "-"); - - Our final example implements a scheme typically used with one of the - Ada 83 compilers, where the separator character for subunits was "__" - (two underscores), specs were identified by adding `_.ADA', bodies by - adding `.ADA', and subunits by adding `.SEP'. All file names were upper - case. Child units were not present of course since this was an Ada 83 - compiler, but it seems reasonable to extend this scheme to use the same - double underscore separator for child units. - - pragma Source_File_Name - (Spec_File_Name => "*_.ADA", - Dot_Replacement => "__", - Casing = Uppercase); - pragma Source_File_Name - (Body_File_Name => "*.ADA", - Dot_Replacement => "__", - Casing = Uppercase); - pragma Source_File_Name - (Subunit_File_Name => "*.SEP", - Dot_Replacement => "__", - Casing = Uppercase); - -  - File: gnat_ug_wnt.info, Node: Generating Object Files, Next: Source Dependencies, Prev: Alternative File Naming Schemes, Up: The GNAT Compilation Model - - Generating Object Files - ======================= - - An Ada program consists of a set of source files, and the first step in - compiling the program is to generate the corresponding object files. - These are generated by compiling a subset of these source files. The - files you need to compile are the following: - - * If a package spec has no body, compile the package spec to produce - the object file for the package. - - * If a package has both a spec and a body, compile the body to - produce the object file for the package. The source file for the - package spec need not be compiled in this case because there is - only one object file, which contains the code for both the spec - and body of the package. - - * For a subprogram, compile the subprogram body to produce the - object file for the subprogram. The spec, if one is present, is as - usual in a separate file, and need not be compiled. - - * In the case of subunits, only compile the parent unit. A single - object file is generated for the entire subunit tree, which - includes all the subunits. - - * Compile child units independently of their parent units (though, - of course, the spec of all the ancestor unit must be present in - order to compile a child unit). - - * Compile generic units in the same manner as any other units. The - object files in this case are small dummy files that contain at - most the flag used for elaboration checking. This is because GNAT - always handles generic instantiation by means of macro expansion. - However, it is still necessary to compile generic units, for - dependency checking and elaboration purposes. - - The preceding rules describe the set of files that must be compiled to - generate the object files for a program. Each object file has the same - name as the corresponding source file, except that the extension is - `.o' as usual. - - You may wish to compile other files for the purpose of checking their - syntactic and semantic correctness. For example, in the case where a - package has a separate spec and body, you would not normally compile the - spec. However, it is convenient in practice to compile the spec to make - sure it is error-free before compiling clients of this spec, because - such compilations will fail if there is an error in the spec. - - GNAT provides an option for compiling such files purely for the - purposes of checking correctness; such compilations are not required as - part of the process of building a program. To compile a file in this - checking mode, use the `-gnatc' switch. - -  - File: gnat_ug_wnt.info, Node: Source Dependencies, Next: The Ada Library Information Files, Prev: Generating Object Files, Up: The GNAT Compilation Model - - Source Dependencies - =================== - - A given object file clearly depends on the source file which is compiled - to produce it. Here we are using "depends" in the sense of a typical - `make' utility; in other words, an object file depends on a source file - if changes to the source file require the object file to be recompiled. - In addition to this basic dependency, a given object may depend on - additional source files as follows: - - * If a file being compiled `with''s a unit X, the object file - depends on the file containing the spec of unit X. This includes - files that are `with''ed implicitly either because they are parents - of `with''ed child units or they are run-time units required by the - language constructs used in a particular unit. - - * If a file being compiled instantiates a library level generic - unit, the object file depends on both the spec and body files for - this generic unit. - - * If a file being compiled instantiates a generic unit defined - within a package, the object file depends on the body file for the - package as well as the spec file. - - * If a file being compiled contains a call to a subprogram for which - pragma `Inline' applies and inlining is activated with the - `-gnatn' switch, the object file depends on the file containing the - body of this subprogram as well as on the file containing the - spec. Note that for inlining to actually occur as a result of the - use of this switch, it is necessary to compile in optimizing mode. - - The use of `-gnatN' activates a more extensive inlining - optimization that is performed by the front end of the compiler. - This inlining does not require that the code generation be - optimized. Like `-gnatn', the use of this switch generates - additional dependencies. - - * If an object file O depends on the proper body of a subunit - through inlining or instantiation, it depends on the parent unit - of the subunit. This means that any modification of the parent - unit or one of its subunits affects the compilation of O. - - * The object file for a parent unit depends on all its subunit body - files. - - * The previous two rules meant that for purposes of computing - dependencies and recompilation, a body and all its subunits are - treated as an indivisible whole. - - These rules are applied transitively: if unit `A' `with''s unit - `B', whose elaboration calls an inlined procedure in package `C', - the object file for unit `A' will depend on the body of `C', in - file `c.adb'. - - The set of dependent files described by these rules includes all - the files on which the unit is semantically dependent, as - described in the Ada 95 Language Reference Manual. However, it is - a superset of what the ARM describes, because it includes generic, - inline, and subunit dependencies. - - An object file must be recreated by recompiling the corresponding - source file if any of the source files on which it depends are - modified. For example, if the `make' utility is used to control - compilation, the rule for an Ada object file must mention all the - source files on which the object file depends, according to the - above definition. The determination of the necessary - recompilations is done automatically when one uses `gnatmake'. - -  - File: gnat_ug_wnt.info, Node: The Ada Library Information Files, Next: Binding an Ada Program, Prev: Source Dependencies, Up: The GNAT Compilation Model - - The Ada Library Information Files - ================================= - - Each compilation actually generates two output files. The first of these - is the normal object file that has a `.o' extension. The second is a - text file containing full dependency information. It has the same name - as the source file, but an `.ali' extension. This file is known as the - Ada Library Information (`ali') file. The following information is - contained in the `ali' file. - - * Version information (indicates which version of GNAT was used to - compile the unit(s) in question) - - * Main program information (including priority and time slice - settings, as well as the wide character encoding used during - compilation). - - * List of arguments used in the `gcc' command for the compilation - - * Attributes of the unit, including configuration pragmas used, an - indication of whether the compilation was successful, exception - model used etc. - - * A list of relevant restrictions applying to the unit (used for - consistency) checking. - - * Categorization information (e.g. use of pragma `Pure'). - - * Information on all `with''ed units, including presence of - `Elaborate' or `Elaborate_All' pragmas. - - * Information from any `Linker_Options' pragmas used in the unit - - * Information on the use of `Body_Version' or `Version' attributes - in the unit. - - * Dependency information. This is a list of files, together with - time stamp and checksum information. These are files on which the - unit depends in the sense that recompilation is required if any of - these units are modified. - - * Cross-reference data. Contains information on all entities - referenced in the unit. Used by tools like `gnatxref' and - `gnatfind' to provide cross-reference information. - - - For a full detailed description of the format of the `ali' file, see - the source of the body of unit `Lib.Writ', contained in file - `lib-writ.adb' in the GNAT compiler sources. - -  - File: gnat_ug_wnt.info, Node: Binding an Ada Program, Next: Mixed Language Programming, Prev: The Ada Library Information Files, Up: The GNAT Compilation Model - - Binding an Ada Program - ====================== - - When using languages such as C and C++, once the source files have been - compiled the only remaining step in building an executable program is - linking the object modules together. This means that it is possible to - link an inconsistent version of a program, in which two units have - included different versions of the same header. - - The rules of Ada do not permit such an inconsistent program to be - built. For example, if two clients have different versions of the same - package, it is illegal to build a program containing these two clients. - These rules are enforced by the GNAT binder, which also determines an - elaboration order consistent with the Ada rules. - - The GNAT binder is run after all the object files for a program have - been created. It is given the name of the main program unit, and from - this it determines the set of units required by the program, by reading - the corresponding ALI files. It generates error messages if the program - is inconsistent or if no valid order of elaboration exists. - - If no errors are detected, the binder produces a main program, in - Ada by default, that contains calls to the elaboration procedures of - those compilation unit that require them, followed by a call to the - main program. This Ada program is compiled to generate the object file - for the main program. The name of the Ada file is `b~XXX.adb' (with the - corresponding spec `b~XXX.ads') where XXX is the name of the main - program unit. - - Finally, the linker is used to build the resulting executable - program, using the object from the main program from the bind step as - well as the object files for the Ada units of the program. - -  - File: gnat_ug_wnt.info, Node: Mixed Language Programming, Next: Building Mixed Ada & C++ Programs, Prev: Binding an Ada Program, Up: The GNAT Compilation Model - - Mixed Language Programming - ========================== - - * Menu: - - * Interfacing to C:: - * Calling Conventions:: - -  - File: gnat_ug_wnt.info, Node: Interfacing to C, Next: Calling Conventions, Up: Mixed Language Programming - - Interfacing to C - ---------------- - - There are two ways to build a program that contains some Ada files and - some other language files depending on whether the main program is in - Ada or not. If the main program is in Ada, you should proceed as - follows: - - 1. Compile the other language files to generate object files. For - instance: - gcc -c file1.c - gcc -c file2.c - - 2. Compile the Ada units to produce a set of object files and ALI - files. For instance: - gnatmake -c my_main.adb - - 3. Run the Ada binder on the Ada main program. For instance: - gnatbind my_main.ali - - 4. Link the Ada main program, the Ada objects and the other language - objects. For instance: - gnatlink my_main.ali file1.o file2.o - - The three last steps can be grouped in a single command: - gnatmake my_main.adb -largs file1.o file2.o - - If the main program is in some language other than Ada, Then you may - have more than one entry point in the Ada subsystem. You must use a - special option of the binder to generate callable routines to initialize - and finalize the Ada units (*note Binding with Non-Ada Main Programs::). - Calls to the initialization and finalization routines must be inserted - in the main program, or some other appropriate point in the code. The - call to initialize the Ada units must occur before the first Ada - subprogram is called, and the call to finalize the Ada units must occur - after the last Ada subprogram returns. You use the same procedure for - building the program as described previously. In this case, however, - the binder only places the initialization and finalization subprograms - into file `b~XXX.adb' instead of the main program. So, if the main - program is not in Ada, you should proceed as follows: - - 1. Compile the other language files to generate object files. For - instance: - gcc -c file1.c - gcc -c file2.c - - 2. Compile the Ada units to produce a set of object files and ALI - files. For instance: - gnatmake -c entry_point1.adb - gnatmake -c entry_point2.adb - - 3. Run the Ada binder on the Ada main program. For instance: - gnatbind -n entry_point1.ali entry_point2.ali - - 4. Link the Ada main program, the Ada objects and the other language - objects. You only need to give the last entry point here. For - instance: - gnatlink entry_point2.ali file1.o file2.o - -  - File: gnat_ug_wnt.info, Node: Calling Conventions, Prev: Interfacing to C, Up: Mixed Language Programming - - Calling Conventions - ------------------- - - GNAT follows standard calling sequence conventions and will thus - interface to any other language that also follows these conventions. - The following Convention identifiers are recognized by GNAT: - - * Ada. This indicates that the standard Ada calling sequence will be - used and all Ada data items may be passed without any limitations - in the case where GNAT is used to generate both the caller and - callee. It is also possible to mix GNAT generated code and code - generated by another Ada compiler. In this case, the data types - should be restricted to simple cases, including primitive types. - Whether complex data types can be passed depends on the situation. - Probably it is safe to pass simple arrays, such as arrays of - integers or floats. Records may or may not work, depending on - whether both compilers lay them out identically. Complex structures - involving variant records, access parameters, tasks, or protected - types, are unlikely to be able to be passed. - - Note that in the case of GNAT running on a platform that supports - DEC Ada 83, a higher degree of compatibility can be guaranteed, - and in particular records are layed out in an identical manner in - the two compilers. Note also that if output from two different - compilers is mixed, the program is responsible for dealing with - elaboration issues. Probably the safest approach is to write the - main program in the version of Ada other than GNAT, so that it - takes care of its own elaboration requirements, and then call the - GNAT-generated adainit procedure to ensure elaboration of the GNAT - components. Consult the documentation of the other Ada compiler - for further details on elaboration. - - However, it is not possible to mix the tasking run time of GNAT and - DEC Ada 83, All the tasking operations must either be entirely - within GNAT compiled sections of the program, or entirely within - DEC Ada 83 compiled sections of the program. - - * Assembler. Specifies assembler as the convention. In practice this - has the same effect as convention Ada (but is not equivalent in - the sense of being considered the same convention). - - * Asm. Equivalent to Assembler. - - * Asm. Equivalent to Assembly. - - * COBOL. Data will be passed according to the conventions described - in section B.4 of the Ada 95 Reference Manual. - - * C. Data will be passed according to the conventions described in - section B.3 of the Ada 95 Reference Manual. - - * Default. Equivalent to C. - - * External. Equivalent to C. - - * CPP. This stands for C++. For most purposes this is identical to C. - See the separate description of the specialized GNAT pragmas - relating to C++ interfacing for further details. - - * Fortran. Data will be passed according to the conventions described - in section B.5 of the Ada 95 Reference Manual. - - * Intrinsic. This applies to an intrinsic operation, as defined in - the Ada 95 Reference Manual. If a a pragma Import (Intrinsic) - applies to a subprogram, this means that the body of the - subprogram is provided by the compiler itself, usually by means of - an efficient code sequence, and that the user does not supply an - explicit body for it. In an application program, the pragma can - only be applied to the following two sets of names, which the GNAT - compiler recognizes. - * Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, - Shift_Right_- Arithmetic. The corresponding subprogram - declaration must have two formal parameters. The first one - must be a signed integer type or a modular type with a binary - modulus, and the second parameter must be of type Natural. - The return type must be the same as the type of the first - argument. The size of this type can only be 8, 16, 32, or 64. - - * binary arithmetic operators: "+", "-", "*", "/" The - corresponding operator declaration must have parameters and - result type that have the same root numeric type (for - example, all three are long_float types). This simplifies the - definition of operations that use type checking to perform - dimensional checks: - type Distance is new Long_Float; - type Time is new Long_Float; - type Velocity is new Long_Float; - function "/" (D : Distance; T : Time) - return Velocity; - pragma Import (Intrinsic, "/"); - - This common idiom is often programmed with a generic - definition and an explicit body. The pragma makes it simpler - to introduce such declarations. It incurs no overhead in - compilation time or code size, because it is implemented as a - single machine instruction. - - * Stdcall. This is relevant only to NT/Win95 implementations of GNAT, - and specifies that the Stdcall calling sequence will be used, as - defined by the NT API. - - * DLL. This is equivalent to Stdcall. - - * Win32. This is equivalent to Stdcall. - - * Stubbed. This is a special convention that indicates that the - compiler should provide a stub body that raises `Program_Error'. - - GNAT additionally provides a useful pragma `Convention_Identifier' that - can be used to parametrize conventions and allow additional synonyms to - be specified. For example if you have legacy code in which the - convention identifier Fortran77 was used for Fortran, you can use the - configuration pragma: - - pragma Convention_Identifier (Fortran77, Fortran); - - And from now on the identifier Fortran77 may be used as a convention - identifier (for example in an `Import' pragma) with the same meaning as - Fortran. - -  - File: gnat_ug_wnt.info, Node: Building Mixed Ada & C++ Programs, Next: Comparison between GNAT and C/C++ Compilation Models, Prev: Mixed Language Programming, Up: The GNAT Compilation Model - - Building Mixed Ada & C++ Programs - ================================= - - Building a mixed application containing both Ada and C++ code may be a - challenge for the unaware programmer. As a matter of fact, this - interfacing has not been standardized in the Ada 95 reference manual due - to the immaturity and lack of standard of C++ at the time. This section - gives a few hints that should make this task easier. In particular the - first section addresses the differences with interfacing with C. The - second section looks into the delicate problem of linking the complete - application from its Ada and C++ parts. The last section give some - hints on how the GNAT run time can be adapted in order to allow - inter-language dispatching with a new C++ compiler. - - * Menu: - - * Interfacing to C++:: - * Linking a Mixed C++ & Ada Program:: - * A Simple Example:: - * Adapting the Run Time to a New C++ Compiler:: - -  - File: gnat_ug_wnt.info, Node: Interfacing to C++, Next: Linking a Mixed C++ & Ada Program, Up: Building Mixed Ada & C++ Programs - - Interfacing to C++ - ------------------ - - GNAT supports interfacing with C++ compilers generating code that is - compatible with the standard Application Binary Interface of the given - platform. - - Interfacing can be done at 3 levels: simple data, subprograms and - classes. In the first 2 cases, GNAT offer a specific CONVENTION CPP - that behaves exactly like CONVENTION C. Usually C++ mangle names of - subprograms and currently GNAT does not provide any help to solve the - demangling problem. This problem can be addressed in 2 ways: - * by modifying the C++ code in order to force a C convention using - the EXTERN "C" syntax. - - * by figuring out the mangled name and use it as the Link_Name - argument of the pragma import. - - Interfacing at the class level can be achieved by using the GNAT - specific pragmas such as `CPP_Class' and `CPP_Virtual'. See the GNAT - Reference Manual for additional information. - -  - File: gnat_ug_wnt.info, Node: Linking a Mixed C++ & Ada Program, Next: A Simple Example, Prev: Interfacing to C++, Up: Building Mixed Ada & C++ Programs - - Linking a Mixed C++ & Ada Program - --------------------------------- - - Usually the linker of the C++ development system must be used to link - mixed applications because most C++ systems will resolve elaboration - issues (such as calling constructors on global class instances) - transparently during the link phase. GNAT has been adapted to ease the - use of a foreign linker for the last phase. Three cases can be - considered: - 1. Using GNAT and G++ (GNU C++ compiler) from the same GCC - installation. The c++ linker can simply be called by using the c++ - specific driver called `c++'. Note that this setup is not very - common because it may request recompiling the whole GCC tree from - sources and it does not allow to upgrade easily to a new version - of one compiler for one of the two languages without taking the - risk of destabilizing the other. - - $ c++ -c file1.C - $ c++ -c file2.C - $ gnatmake ada_unit -largs file1.o file2.o --LINK=c++ - - 2. Using GNAT and G++ from 2 different GCC installations. If both - compilers are on the PATH, the same method can be used. It is - important to be aware that environment variables such as - C_INCLUDE_PATH, GCC_EXEC_PREFIX, BINUTILS_ROOT or GCC_ROOT will - affect both compilers at the same time and thus may make one of - the 2 compilers operate improperly if they are set for the other. - In particular it is important that the link command has access to - the proper gcc library `libgcc.a', that is to say the one that is - part of the C++ compiler installation. The implicit link command - as suggested in the gnatmake command from the former example can - be replaced by an explicit link command with full verbosity in - order to verify which library is used: - $ gnatbind ada_unit - $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ - If there is a problem due to interfering environment variables, it - can be workaround by using an intermediate script. The following - example shows the proper script to use when GNAT has not been - installed at its default location and g++ has been installed at - its default location: - - $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script - $ cat ./my_script - #!/bin/sh - unset BINUTILS_ROOT - unset GCC_ROOT - c++ $* - - 3. Using a non GNU C++ compiler. The same set of command as previously - described can be used to insure that the c++ linker is used. - Nonetheless, you need to add the path to libgcc explicitely, since - some libraries needed by GNAT are located in this directory: - - - $ gnatlink ada_unit file1.o file2.o --LINK=./my_script - $ cat ./my_script - #!/bin/sh - CC $* `gcc -print-libgcc-file-name` - - Where CC is the name of the non GNU C++ compiler. - - -  - File: gnat_ug_wnt.info, Node: A Simple Example, Next: Adapting the Run Time to a New C++ Compiler, Prev: Linking a Mixed C++ & Ada Program, Up: Building Mixed Ada & C++ Programs - - A Simple Example - ---------------- - - The following example, provided as part of the GNAT examples, show how - to achieve procedural interfacing between Ada and C++ in both - directions. The C++ class A has 2 methods. The first method is exported - to Ada by the means of an extern C wrapper function. The second method - calls an Ada subprogram. On the Ada side, The C++ calls is modelized by - a limited record with a layout comparable to the C++ class. The Ada - subprogram, in turn, calls the c++ method. So from the C++ main program - the code goes back and forth between the 2 languages. - - Here are the compilation commands for native configurations: - $ gnatmake -c simple_cpp_interface - $ c++ -c cpp_main.C - $ c++ -c ex7.C - $ gnatbind -n simple_cpp_interface - $ gnatlink simple_cpp_interface -o cpp_main --LINK=$(CPLUSPLUS) - -lstdc++ ex7.o cpp_main.o - - Here are the corresponding sources: - - //cpp_main.C - - #include "ex7.h" - - extern "C" { - void adainit (void); - void adafinal (void); - void method1 (A *t); - } - - void method1 (A *t) - { - t->method1 (); - } - - int main () - { - A obj; - adainit (); - obj.method2 (3030); - adafinal (); - } - - //ex7.h - - class Origin { - public: - int o_value; - }; - class A : public Origin { - public: - void method1 (void); - virtual void method2 (int v); - A(); - int a_value; - }; - - //ex7.C - - #include "ex7.h" - #include - - extern "C" { void ada_method2 (A *t, int v);} - - void A::method1 (void) - { - a_value = 2020; - printf ("in A::method1, a_value = %d \n",a_value); - - } - - void A::method2 (int v) - { - ada_method2 (this, v); - printf ("in A::method2, a_value = %d \n",a_value); - - } - - A::A(void) - { - a_value = 1010; - printf ("in A::A, a_value = %d \n",a_value); - } - - -- Ada sources - package body Simple_Cpp_Interface is - - procedure Ada_Method2 (This : in out A; V : Integer) is - begin - Method1 (This); - This.A_Value := V; - end Ada_Method2; - - end Simple_Cpp_Interface; - - package Simple_Cpp_Interface is - type A is limited - record - O_Value : Integer; - A_Value : Integer; - end record; - pragma Convention (C, A); - - procedure Method1 (This : in out A); - pragma Import (C, Method1); - - procedure Ada_Method2 (This : in out A; V : Integer); - pragma Export (C, Ada_Method2); - - end Simple_Cpp_Interface; - -  - File: gnat_ug_wnt.info, Node: Adapting the Run Time to a New C++ Compiler, Prev: A Simple Example, Up: Building Mixed Ada & C++ Programs - - Adapting the Run Time to a New C++ Compiler - ------------------------------------------- - - GNAT offers the capability to derive Ada 95 tagged types directly from - preexisting C++ classes and . See "Interfacing with C++" in the GNAT - reference manual. The mechanism used by GNAT for achieving such a goal - has been made user configurable through a GNAT library unit - `Interfaces.CPP'. The default version of this file is adapted to the - GNU c++ compiler. Internal knowledge of the virtual table layout used - by the new C++ compiler is needed to configure properly this unit. The - Interface of this unit is known by the compiler and cannot be changed - except for the value of the constants defining the characteristics of - the virtual table: CPP_DT_Prologue_Size, CPP_DT_Entry_Size, - CPP_TSD_Prologue_Size, CPP_TSD_Entry_Size. Read comments in the source - of this unit for more details. - -  - File: gnat_ug_wnt.info, Node: Comparison between GNAT and C/C++ Compilation Models, Next: Comparison between GNAT and Conventional Ada Library Models, Prev: Building Mixed Ada & C++ Programs, Up: The GNAT Compilation Model - - Comparison between GNAT and C/C++ Compilation Models - ==================================================== - - The GNAT model of compilation is close to the C and C++ models. You can - think of Ada specs as corresponding to header files in C. As in C, you - don't need to compile specs; they are compiled when they are used. The - Ada `with' is similar in effect to the `#include' of a C header. - - One notable difference is that, in Ada, you may compile specs - separately to check them for semantic and syntactic accuracy. This is - not always possible with C headers because they are fragments of - programs that have less specific syntactic or semantic rules. - - The other major difference is the requirement for running the binder, - which performs two important functions. First, it checks for - consistency. In C or C++, the only defense against assembling - inconsistent programs lies outside the compiler, in a makefile, for - example. The binder satisfies the Ada requirement that it be impossible - to construct an inconsistent program when the compiler is used in normal - mode. - - The other important function of the binder is to deal with - elaboration issues. There are also elaboration issues in C++ that are - handled automatically. This automatic handling has the advantage of - being simpler to use, but the C++ programmer has no control over - elaboration. Where `gnatbind' might complain there was no valid order - of elaboration, a C++ compiler would simply construct a program that - malfunctioned at run time. - -  - File: gnat_ug_wnt.info, Node: Comparison between GNAT and Conventional Ada Library Models, Prev: Comparison between GNAT and C/C++ Compilation Models, Up: The GNAT Compilation Model - - Comparison between GNAT and Conventional Ada Library Models - =========================================================== - - This section is intended to be useful to Ada programmers who have - previously used an Ada compiler implementing the traditional Ada library - model, as described in the Ada 95 Language Reference Manual. If you - have not used such a system, please go on to the next section. - - In GNAT, there is no "library" in the normal sense. Instead, the set - of source files themselves acts as the library. Compiling Ada programs - does not generate any centralized information, but rather an object - file and a ALI file, which are of interest only to the binder and - linker. In a traditional system, the compiler reads information not - only from the source file being compiled, but also from the centralized - library. This means that the effect of a compilation depends on what - has been previously compiled. In particular: - - * When a unit is `with''ed, the unit seen by the compiler corresponds - to the version of the unit most recently compiled into the library. - - * Inlining is effective only if the necessary body has already been - compiled into the library. - - * Compiling a unit may obsolete other units in the library. - - In GNAT, compiling one unit never affects the compilation of any other - units because the compiler reads only source files. Only changes to - source files can affect the results of a compilation. In particular: - - * When a unit is `with''ed, the unit seen by the compiler corresponds - to the source version of the unit that is currently accessible to - the compiler. - - * Inlining requires the appropriate source files for the package or - subprogram bodies to be available to the compiler. Inlining is - always effective, independent of the order in which units are - complied. - - * Compiling a unit never affects any other compilations. The editing - of sources may cause previous compilations to be out of date if - they depended on the source file being modified. - - The most important result of these differences is that order of - compilation is never significant in GNAT. There is no situation in - which one is required to do one compilation before another. What shows - up as order of compilation requirements in the traditional Ada library - becomes, in GNAT, simple source dependencies; in other words, there is - only a set of rules saying what source files must be present when a - file is compiled. - -  - File: gnat_ug_wnt.info, Node: Compiling Using gcc, Next: Binding Using gnatbind, Prev: The GNAT Compilation Model, Up: Top - - Compiling Using `gcc' - ********************* - - This chapter discusses how to compile Ada programs using the `gcc' - command. It also describes the set of switches that can be used to - control the behavior of the compiler. - - * Menu: - - * Compiling Programs:: - * Switches for gcc:: - * Search Paths and the Run-Time Library (RTL):: - * Order of Compilation Issues:: - * Examples:: - -  - File: gnat_ug_wnt.info, Node: Compiling Programs, Next: Switches for gcc, Up: Compiling Using gcc - - Compiling Programs - ================== - - The first step in creating an executable program is to compile the units - of the program using the `gcc' command. You must compile the following - files: - - * the body file (`.adb') for a library level subprogram or generic - subprogram - - * the spec file (`.ads') for a library level package or generic - package that has no body - - * the body file (`.adb') for a library level package or generic - package that has a body - - - You need _not_ compile the following files - - * the spec of a library unit which has a body - - * subunits - - because they are compiled as part of compiling related units. GNAT - package specs when the corresponding body is compiled, and subunits - when the parent is compiled. If you attempt to compile any of these - files, you will get one of the following error messages (where fff is - the name of the file you compiled): - - No code generated for file FFF (PACKAGE SPEC) - No code generated for file FFF (SUBUNIT) - - The basic command for compiling a file containing an Ada unit is - - $ gcc -c [SWITCHES] `file name' - - where FILE NAME is the name of the Ada file (usually having an extension - `.ads' for a spec or `.adb' for a body). You specify the `-c' switch - to tell `gcc' to compile, but not link, the file. The result of a - successful compilation is an object file, which has the same name as - the source file but an extension of `.o' and an Ada Library Information - (ALI) file, which also has the same name as the source file, but with - `.ali' as the extension. GNAT creates these two output files in the - current directory, but you may specify a source file in any directory - using an absolute or relative path specification containing the - directory information. - - `gcc' is actually a driver program that looks at the extensions of - the file arguments and loads the appropriate compiler. For example, the - GNU C compiler is `cc1', and the Ada compiler is `gnat1'. These - programs are in directories known to the driver program (in some - configurations via environment variables you set), but need not be in - your path. The `gcc' driver also calls the assembler and any other - utilities needed to complete the generation of the required object - files. - - It is possible to supply several file names on the same `gcc' - command. This causes `gcc' to call the appropriate compiler for each - file. For example, the following command lists three separate files to - be compiled: - - $ gcc -c x.adb y.adb z.c - - calls `gnat1' (the Ada compiler) twice to compile `x.adb' and `y.adb', - and `cc1' (the C compiler) once to compile `z.c'. The compiler - generates three object files `x.o', `y.o' and `z.o' and the two ALI - files `x.ali' and `y.ali' from the Ada compilations. Any switches apply - to all the files listed, except for `-gnatX' switches, which apply only - to Ada compilations. - -  - File: gnat_ug_wnt.info, Node: Switches for gcc, Next: Search Paths and the Run-Time Library (RTL), Prev: Compiling Programs, Up: Compiling Using gcc - - Switches for `gcc' - ================== - - The `gcc' command accepts switches that control the compilation - process. These switches are fully described in this section. First we - briefly list all the switches, in alphabetical order, then we describe - the switches in more detail in functionally grouped sections. - - * Menu: - - * Output and Error Message Control:: - * Debugging and Assertion Control:: - * Run-Time Checks:: - * Stack Overflow Checking:: - * Run-Time Control:: - * Validity Checking:: - * Style Checking:: - * Using gcc for Syntax Checking:: - * Using gcc for Semantic Checking:: - * Compiling Ada 83 Programs:: - * Character Set Control:: - * File Naming Control:: - * Subprogram Inlining Control:: - * Auxiliary Output Control:: - * Debugging Control:: - * Units to Sources Mapping Files:: - - `-b TARGET' - Compile your program to run on TARGET, which is the name of a - system configuration. You must have a GNAT cross-compiler built if - TARGET is not the same as your host system. - - `-BDIR' - Load compiler executables (for example, `gnat1', the Ada compiler) - from DIR instead of the default location. Only use this switch - when multiple versions of the GNAT compiler are available. See the - `gcc' manual page for further details. You would normally use the - `-b' or `-V' switch instead. - - `-c' - Compile. Always use this switch when compiling Ada programs. - - Note: for some other languages when using `gcc', notably in the - case of C and C++, it is possible to use use `gcc' without a `-c' - switch to compile and link in one step. In the case of GNAT, you - cannot use this approach, because the binder must be run and `gcc' - cannot be used to run the GNAT binder. - - `-g' - Generate debugging information. This information is stored in the - object file and copied from there to the final executable file by - the linker, where it can be read by the debugger. You must use the - `-g' switch if you plan on using the debugger. - - `-IDIR' - Direct GNAT to search the DIR directory for source files needed by - the current compilation (*note Search Paths and the Run-Time - Library (RTL)::). - - `-I-' - Except for the source file named in the command line, do not look - for source files in the directory containing the source file named - in the command line (*note Search Paths and the Run-Time Library - (RTL)::). - - `-o FILE' - This switch is used in `gcc' to redirect the generated object file - and its associated ALI file. Beware of this switch with GNAT, - because it may cause the object file and ALI file to have - different names which in turn may confuse the binder and the - linker. - - `-O[N]' - N controls the optimization level. - - n = 0 - No optimization, the default setting if no `-O' appears - - n = 1 - Normal optimization, the default if you specify `-O' without - an operand. - - n = 2 - Extensive optimization - - n = 3 - Extensive optimization with automatic inlining. This applies - only to inlining within a unit. For details on control of - inter-unit inlining see *Note Subprogram Inlining Control::. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-S' - Used in place of `-c' to cause the assembler source file to be - generated, using `.s' as the extension, instead of the object file. - This may be useful if you need to examine the generated assembly - code. - - `-v' - Show commands generated by the `gcc' driver. Normally used only for - debugging purposes or if you need to be sure what version of the - compiler you are executing. - - `-V VER' - Execute VER version of the compiler. This is the `gcc' version, - not the GNAT version. - - `-gnata' - Assertions enabled. `Pragma Assert' and `pragma Debug' to be - activated. - - `-gnatA' - Avoid processing `gnat.adc'. If a gnat.adc file is present, it - will be ignored. - - `-gnatb' - Generate brief messages to `stderr' even if verbose mode set. - - `-gnatc' - Check syntax and semantics only (no code generation attempted). - - `-gnatC' - Compress debug information and external symbol name table entries. - - `-gnatD' - Output expanded source files for source level debugging. This - switch also suppress generation of cross-reference information - (see -gnatx). - - `-gnatecPATH' - Specify a configuration pragma file. (see *Note The Configuration - Pragmas Files::) - - `-gnatemPATH' - Specify a mapping file. (see *Note Units to Sources Mapping - Files::) - - `-gnatE' - Full dynamic elaboration checks. - - `-gnatf' - Full errors. Multiple errors per line, all undefined references. - - `-gnatF' - Externals names are folded to all uppercase. - - `-gnatg' - Internal GNAT implementation mode. This should not be used for - applications programs, it is intended only for use by the compiler - and its run-time library. For documentation, see the GNAT sources. - - `-gnatG' - List generated expanded code in source form. - - `-gnatiC' - Identifier character set (C=1/2/3/4/8/9/p/f/n/w). - - `-gnath' - Output usage information. The output is written to `stdout'. - - `-gnatkN' - Limit file names to N (1-999) characters (`k' = krunch). - - `-gnatl' - Output full source listing with embedded error messages. - - `-gnatmN' - Limit number of detected errors to N (1-999). - - `-gnatn' - Activate inlining across unit boundaries for subprograms for which - pragma `inline' is specified. - - `-gnatN' - Activate front end inlining. - - `-fno-inline' - Suppresses all inlining, even if other optimization or inlining - switches are set. - - `-fstack-check' - Activates stack checking. See separate section on stack checking - for details of the use of this option. - - `-gnato' - Enable numeric overflow checking (which is not normally enabled by - default). Not that division by zero is a separate check that is not - controlled by this switch (division by zero checking is on by - default). - - `-gnatp' - Suppress all checks. - - `-gnatq' - Don't quit; try semantics, even if parse errors. - - `-gnatQ' - Don't quit; generate `ali' and tree files even if illegalities. - - `-gnatP' - Enable polling. This is required on some systems (notably Windows - NT) to obtain asynchronous abort and asynchronous transfer of - control capability. See the description of pragma Polling in the - GNAT Reference Manual for full details. - - `-gnatR[0/1/2/3][s]' - Output representation information for declared types and objects. - - `-gnats' - Syntax check only. - - `-gnatt' - Tree output file to be generated. - - `-gnatT nnn' - Set time slice to specified number of microseconds - - `-gnatu' - List units for this compilation. - - `-gnatU' - Tag all error messages with the unique string "error:" - - `-gnatv' - Verbose mode. Full error output with source lines to `stdout'. - - `-gnatV' - Control level of validity checking. See separate section describing - this feature. - - `-gnatwxxxXXX' - Warning mode where XXX is a string of options describing the exact - warnings that are enabled or disabled. See separate section on - warning control. - - `-gnatWE' - Wide character encoding method (E=n/h/u/s/e/8). - - `-gnatx' - Suppress generation of cross-reference information. - - `-gnaty' - Enable built-in style checks. See separate section describing this - feature. - - `-gnatzM' - Distribution stub generation and compilation (M=r/c for - receiver/caller stubs). - - `-gnat83' - Enforce Ada 83 restrictions. - - `-pass-exit-codes' - Catch exit codes from the compiler and use the most meaningful as - exit status. - - You may combine a sequence of GNAT switches into a single switch. For - example, the combined switch - - -gnatofi3 - - is equivalent to specifying the following sequence of switches: - - -gnato -gnatf -gnati3 - - The following restrictions apply to the combination of switches in this - manner: - - * The switch `-gnatc' if combined with other switches must come - first in the string. - - * The switch `-gnats' if combined with other switches must come - first in the string. - - * Once a "y" appears in the string (that is a use of the `-gnaty' - switch), then all further characters in the switch are interpreted - as style modifiers (see description of `-gnaty'). - - * Once a "d" appears in the string (that is a use of the `-gnatd' - switch), then all further characters in the switch are interpreted - as debug flags (see description of `-gnatd'). - - * Once a "w" appears in the string (that is a use of the `-gnatw' - switch), then all further characters in the switch are interpreted - as warning mode modifiers (see description of `-gnatw'). - - * Once a "V" appears in the string (that is a use of the `-gnatV' - switch), then all further characters in the switch are interpreted - as validity checking options (see description of `-gnatV'). - - -  - File: gnat_ug_wnt.info, Node: Output and Error Message Control, Next: Debugging and Assertion Control, Up: Switches for gcc - - Output and Error Message Control - -------------------------------- - - The standard default format for error messages is called "brief format." - Brief format messages are written to `stderr' (the standard error file) - and have the following form: - - e.adb:3:04: Incorrect spelling of keyword "function" - e.adb:4:20: ";" should be "is" - - The first integer after the file name is the line number in the file, - and the second integer is the column number within the line. `glide' - can parse the error messages and point to the referenced character. - The following switches provide control over the error message format: - - `-gnatv' - The v stands for verbose. The effect of this setting is to write - long-format error messages to `stdout' (the standard output file. - The same program compiled with the `-gnatv' switch would generate: - - 3. funcion X (Q : Integer) - | - >>> Incorrect spelling of keyword "function" - 4. return Integer; - | - >>> ";" should be "is" - - The vertical bar indicates the location of the error, and the `>>>' - prefix can be used to search for error messages. When this switch - is used the only source lines output are those with errors. - - `-gnatl' - The `l' stands for list. This switch causes a full listing of the - file to be generated. The output might look as follows: - - 1. procedure E is - 2. V : Integer; - 3. funcion X (Q : Integer) - | - >>> Incorrect spelling of keyword "function" - 4. return Integer; - | - >>> ";" should be "is" - 5. begin - 6. return Q + Q; - 7. end; - 8. begin - 9. V := X + X; - 10.end E; - - When you specify the `-gnatv' or `-gnatl' switches and standard - output is redirected, a brief summary is written to `stderr' - (standard error) giving the number of error messages and warning - messages generated. - - `-gnatU' - This switch forces all error messages to be preceded by the unique - string "error:". This means that error messages take a few more - characters in space, but allows easy searching for and - identification of error messages. - - `-gnatb' - The `b' stands for brief. This switch causes GNAT to generate the - brief format error messages to `stderr' (the standard error file) - as well as the verbose format message or full listing (which as - usual is written to `stdout' (the standard output file). - - `-gnatmN' - The `m' stands for maximum. N is a decimal integer in the range - of 1 to 999 and limits the number of error messages to be - generated. For example, using `-gnatm2' might yield - - e.adb:3:04: Incorrect spelling of keyword "function" - e.adb:5:35: missing ".." - fatal error: maximum errors reached - compilation abandoned - - `-gnatf' - The `f' stands for full. Normally, the compiler suppresses error - messages that are likely to be redundant. This switch causes all - error messages to be generated. In particular, in the case of - references to undefined variables. If a given variable is - referenced several times, the normal format of messages is - e.adb:7:07: "V" is undefined (more references follow) - - where the parenthetical comment warns that there are additional - references to the variable `V'. Compiling the same program with the - `-gnatf' switch yields - - e.adb:7:07: "V" is undefined - e.adb:8:07: "V" is undefined - e.adb:8:12: "V" is undefined - e.adb:8:16: "V" is undefined - e.adb:9:07: "V" is undefined - e.adb:9:12: "V" is undefined - - `-gnatq' - The `q' stands for quit (really "don't quit"). In normal - operation mode, the compiler first parses the program and - determines if there are any syntax errors. If there are, - appropriate error messages are generated and compilation is - immediately terminated. This switch tells GNAT to continue with - semantic analysis even if syntax errors have been found. This may - enable the detection of more errors in a single run. On the other - hand, the semantic analyzer is more likely to encounter some - internal fatal error when given a syntactically invalid tree. - - `-gnatQ' - In normal operation mode, the `ali' file is not generated if any - illegalities are detected in the program. The use of `-gnatQ' - forces generation of the `ali' file. This file is marked as being - in error, so it cannot be used for binding purposes, but it does - contain reasonably complete cross-reference information, and thus - may be useful for use by tools (e.g. semantic browsing tools or - integrated development environments) that are driven from the - `ali' file. - - In addition, if `-gnatt' is also specified, then the tree file is - generated even if there are illegalities. It may be useful in this - case to also specify `-gnatq' to ensure that full semantic - processing occurs. The resulting tree file can be processed by - ASIS, for the purpose of providing partial information about - illegal units, but if the error causes the tree to be badly - malformed, then ASIS may crash during the analysis. - - In addition to error messages, which correspond to illegalities as - defined in the Ada 95 Reference Manual, the compiler detects two kinds - of warning situations. - - First, the compiler considers some constructs suspicious and - generates a warning message to alert you to a possible error. Second, - if the compiler detects a situation that is sure to raise an exception - at run time, it generates a warning message. The following shows an - example of warning messages: - e.adb:4:24: warning: creation of object may raise Storage_Error - e.adb:10:17: warning: static value out of range - e.adb:10:17: warning: "Constraint_Error" will be raised at run time - - GNAT considers a large number of situations as appropriate for the - generation of warning messages. As always, warnings are not definite - indications of errors. For example, if you do an out-of-range - assignment with the deliberate intention of raising a - `Constraint_Error' exception, then the warning that may be issued does - not indicate an error. Some of the situations for which GNAT issues - warnings (at least some of the time) are given in the following list, - which is not necessarily complete. - - * Possible infinitely recursive calls - - * Out-of-range values being assigned - - * Possible order of elaboration problems - - * Unreachable code - - * Fixed-point type declarations with a null range - - * Variables that are never assigned a value - - * Variables that are referenced before being initialized - - * Task entries with no corresponding accept statement - - * Duplicate accepts for the same task entry in a select - - * Objects that take too much storage - - * Unchecked conversion between types of differing sizes - - * Missing return statements along some execution paths in a function - - * Incorrect (unrecognized) pragmas - - * Incorrect external names - - * Allocation from empty storage pool - - * Potentially blocking operations in protected types - - * Suspicious parenthesization of expressions - - * Mismatching bounds in an aggregate - - * Attempt to return local value by reference - - * Unrecognized pragmas - - * Premature instantiation of a generic body - - * Attempt to pack aliased components - - * Out of bounds array subscripts - - * Wrong length on string assignment - - * Violations of style rules if style checking is enabled - - * Unused with clauses - - * Bit_Order usage that does not have any effect - - * Compile time biased rounding of floating-point constant - - * Standard.Duration used to resolve universal fixed expression - - * Dereference of possibly null value - - * Declaration that is likely to cause storage error - - * Internal GNAT unit with'ed by application unit - - * Values known to be out of range at compile time - - * Unreferenced labels and variables - - * Address overlays that could clobber memory - - * Unexpected initialization when address clause present - - * Bad alignment for address clause - - * Useless type conversions - - * Redundant assignment statements - - * Accidental hiding of name by child unit - - * Unreachable code - - * Access before elaboration detected at compile time - - * A range in a `for' loop that is known to be null or might be null - - - The following switches are available to control the handling of warning - messages: - - `-gnatwa (activate all optional errors)' - This switch activates most optional warning messages, see - remaining list in this section for details on optional warning - messages that can be individually controlled. The warnings that - are not turned on by this switch are `-gnatwb' (biased rounding), - `-gnatwd' (implicit dereferencing), and `-gnatwh' (hiding). All - other optional warnings are turned on. - - `-gnatwA (suppress all optional errors)' - This switch suppresses all optional warning messages, see - remaining list in this section for details on optional warning - messages that can be individually controlled. - - `-gnatwb (activate warnings on biased rounding)' - If a static floating-point expression has a value that is exactly - half way between two adjacent machine numbers, then the rules of - Ada (Ada Reference Manual, section 4.9(38)) require that this - rounding be done away from zero, even if the normal unbiased - rounding rules at run time would require rounding towards zero. - This warning message alerts you to such instances where - compile-time rounding and run-time rounding are not equivalent. If - it is important to get proper run-time rounding, then you can - force this by making one of the operands into a variable. The - default is that such warnings are not generated. Note that - `-gnatwa' does not affect the setting of this warning option. - - `-gnatwB (suppress warnings on biased rounding)' - This switch disables warnings on biased rounding. - - `-gnatwc (activate warnings on conditionals)' - This switch activates warnings for conditional expressions used in - tests that are known to be True or False at compile time. The - default is that such warnings are not generated. This warning can - also be turned on using `-gnatwa'. - - `-gnatwC (suppress warnings on conditionals)' - This switch suppresses warnings for conditional expressions used in - tests that are known to be True or False at compile time. - - `-gnatwd (activate warnings on implicit dereferencing)' - If this switch is set, then the use of a prefix of an access type - in an indexed component, slice, or selected component without an - explicit `.all' will generate a warning. With this warning - enabled, access checks occur only at points where an explicit - `.all' appears in the source code (assuming no warnings are - generated as a result of this switch). The default is that such - warnings are not generated. Note that `-gnatwa' does not affect - the setting of this warning option. - - `-gnatwD (suppress warnings on implicit dereferencing)' - This switch suppresses warnings for implicit deferences in indexed - components, slices, and selected components. - - `-gnatwe (treat warnings as errors)' - This switch causes warning messages to be treated as errors. The - warning string still appears, but the warning messages are counted - as errors, and prevent the generation of an object file. - - `-gnatwf (activate warnings on unreferenced formals)' - This switch causes a warning to be generated if a formal parameter - is not referenced in the body of the subprogram. This warning can - also be turned on using `-gnatwa' or `-gnatwu'. - - `-gnatwF (suppress warnings on unreferenced formals)' - This switch suppresses warnings for unreferenced formal - parameters. Note that the combination `-gnatwu' followed by - `-gnatwF' has the effect of warning on unreferenced entities other - than subprogram formals. - - `-gnatwh (activate warnings on hiding)' - This switch activates warnings on hiding declarations. A - declaration is considered hiding if it is for a non-overloadable - entity, and it declares an entity with the same name as some other - entity that is directly or use-visible. The default is that such - warnings are not generated. Note that `-gnatwa' does not affect - the setting of this warning option. - - `-gnatwH (suppress warnings on hiding)' - This switch suppresses warnings on hiding declarations. - - `-gnatwi (activate warnings on implementation units).' - This switch activates warnings for a `with' of an internal GNAT - implementation unit, defined as any unit from the `Ada', - `Interfaces', `GNAT', or `System' hierarchies that is not - documented in either the Ada Reference Manual or the GNAT - Programmer's Reference Manual. Such units are intended only for - internal implementation purposes and should not be `with''ed by - user programs. The default is that such warnings are generated - This warning can also be turned on using `-gnatwa'. - - `-gnatwI (disable warnings on implementation units).' - This switch disables warnings for a `with' of an internal GNAT - implementation unit. - - `-gnatwl (activate warnings on elaboration pragmas)' - This switch activates warnings on missing pragma Elaborate_All - statements. See the section in this guide on elaboration checking - for details on when such pragma should be used. The default is - that such warnings are not generated. This warning can also be - turned on using `-gnatwa'. - - `-gnatwL (suppress warnings on elaboration pragmas)' - This switch suppresses warnings on missing pragma Elaborate_All - statements. See the section in this guide on elaboration checking - for details on when such pragma should be used. - - `-gnatwo (activate warnings on address clause overlays)' - This switch activates warnings for possibly unintended - initialization effects of defining address clauses that cause one - variable to overlap another. The default is that such warnings are - generated. This warning can also be turned on using `-gnatwa'. - - `-gnatwO (suppress warnings on address clause overlays)' - This switch suppresses warnings on possibly unintended - initialization effects of defining address clauses that cause one - variable to overlap another. - - `-gnatwp (activate warnings on ineffective pragma Inlines)' - This switch activates warnings for failure of front end inlining - (activated by `-gnatN') to inline a particular call. There are - many reasons for not being able to inline a call, including most - commonly that the call is too complex to inline. This warning can - also be turned on using `-gnatwa'. - - `-gnatwP (suppress warnings on ineffective pragma Inlines)' - This switch suppresses warnings on ineffective pragma Inlines. If - the inlining mechanism cannot inline a call, it will simply ignore - the request silently. - - `-gnatwr (activate warnings on redundant constructs)' - This switch activates warnings for redundant constructs. The - following is the current list of constructs regarded as redundant: - This warning can also be turned on using `-gnatwa'. - - * Assignment of an item to itself. - - * Type conversion that converts an expression to its own type. - - * Use of the attribute `Base' where `typ'Base' is the same as - `typ'. - - * Use of pragma `Pack' when all components are placed by a - record representation clause. - - `-gnatwR (suppress warnings on redundant constructs)' - This switch suppresses warnings for redundant constructs. - - `-gnatws (suppress all warnings)' - This switch completely suppresses the output of all warning - messages from the GNAT front end. Note that it does not suppress - warnings from the `gcc' back end. To suppress these back end - warnings as well, use the switch `-w' in addition to `-gnatws'. - - `-gnatwu (activate warnings on unused entities)' - This switch activates warnings to be generated for entities that - are defined but not referenced, and for units that are `with''ed - and not referenced. In the case of packages, a warning is also - generated if no entities in the package are referenced. This means - that if the package is referenced but the only references are in - `use' clauses or `renames' declarations, a warning is still - generated. A warning is also generated for a generic package that - is `with''ed but never instantiated. In the case where a package - or subprogram body is compiled, and there is a `with' on the - corresponding spec that is only referenced in the body, a warning - is also generated, noting that the `with' can be moved to the - body. The default is that such warnings are not generated. This - switch also activates warnings on unreferenced formals (it is - includes the effect of `-gnatwf'). This warning can also be - turned on using `-gnatwa'. - - `-gnatwU (suppress warnings on unused entities)' - This switch suppresses warnings for unused entities and packages. - It also turns off warnings on unreferenced formals (and thus - includes the effect of `-gnatwF'). - - A string of warning parameters can be used in the same parameter. - For example: - - -gnatwaLe - - Would turn on all optional warnings except for elaboration pragma - warnings, and also specify that warnings should be treated as - errors. - - `-w' - This switch suppresses warnings from the `gcc' backend. It may be - used in conjunction with `-gnatws' to ensure that all warnings are - suppressed during the entire compilation process. - -  - File: gnat_ug_wnt.info, Node: Debugging and Assertion Control, Next: Run-Time Checks, Prev: Output and Error Message Control, Up: Switches for gcc - - Debugging and Assertion Control - ------------------------------- - - `-gnata' - The pragmas `Assert' and `Debug' normally have no effect and are - ignored. This switch, where `a' stands for assert, causes `Assert' - and `Debug' pragmas to be activated. - - The pragmas have the form: - - pragma Assert (BOOLEAN-EXPRESSION [, - STATIC-STRING-EXPRESSION]) - pragma Debug (PROCEDURE CALL) - - The `Assert' pragma causes BOOLEAN-EXPRESSION to be tested. If - the result is `True', the pragma has no effect (other than - possible side effects from evaluating the expression). If the - result is `False', the exception `Assert_Failure' declared in the - package `System.Assertions' is raised (passing - STATIC-STRING-EXPRESSION, if present, as the message associated - with the exception). If no string expression is given the default - is a string giving the file name and line number of the pragma. - - The `Debug' pragma causes PROCEDURE to be called. Note that - `pragma Debug' may appear within a declaration sequence, allowing - debugging procedures to be called between declarations. - -  - File: gnat_ug_wnt.info, Node: Validity Checking, Next: Style Checking, Prev: Run-Time Control, Up: Switches for gcc - - Validity Checking - ----------------- - - The Ada 95 Reference Manual has specific requirements for checking for - invalid values. In particular, RM 13.9.1 requires that the evaluation - of invalid values (for example from unchecked conversions), not result - in erroneous execution. In GNAT, the result of such an evaluation in - normal default mode is to either use the value unmodified, or to raise - Constraint_Error in those cases where use of the unmodified value would - cause erroneous execution. The cases where unmodified values might lead - to erroneous execution are case statements (where a wild jump might - result from an invalid value), and subscripts on the left hand side - (where memory corruption could occur as a result of an invalid value). - - The `-gnatVx' switch allows more control over the validity checking - mode. The `x' argument here is a string of letters which control which - validity checks are performed in addition to the default checks - described above. - - * `-gnatVc' Validity checks for copies - - The right hand side of assignments, and the initializing values of - object declarations are validity checked. - - * `-gnatVd' Default (RM) validity checks - - Some validity checks are done by default following normal Ada - semantics (RM 13.9.1 (9-11)). A check is done in case statements - that the expression is within the range of the subtype. If it is - not, Constraint_Error is raised. For assignments to array - components, a check is done that the expression used as index is - within the range. If it is not, Constraint_Error is raised. Both - these validity checks may be turned off using switch `-gnatVD'. - They are turned on by default. If `-gnatVD' is specified, a - subsequent switch `-gnatVd' will leave the checks turned on. - Switch `-gnatVD' should be used only if you are sure that all such - expressions have valid values. If you use this switch and invalid - values are present, then the program is erroneous, and wild jumps - or memory overwriting may occur. - - * `-gnatVi' Validity checks for `in' mode parameters - - Arguments for parameters of mode `in' are validity checked in - function and procedure calls at the point of call. - - * `-gnatVm' Validity checks for `in out' mode parameters - - Arguments for parameters of mode `in out' are validity checked in - procedure calls at the point of call. The `'m'' here stands for - modify, since this concerns parameters that can be modified by the - call. Note that there is no specific option to test `out' - parameters, but any reference within the subprogram will be tested - in the usual manner, and if an invalid value is copied back, any - reference to it will be subject to validity checking. - - * `-gnatVo' Validity checks for operator and attribute operands - - Arguments for predefined operators and attributes are validity - checked. This includes all operators in package `Standard', the - shift operators defined as intrinsic in package `Interfaces' and - operands for attributes such as `Pos'. - - * `-gnatVr' Validity checks for function returns - - The expression in `return' statements in functions is validity - checked. - - * `-gnatVs' Validity checks for subscripts - - All subscripts expressions are checked for validity, whether they - appear on the right side or left side (in default mode only left - side subscripts are validity checked). - - * `-gnatVt' Validity checks for tests - - Expressions used as conditions in `if', `while' or `exit' - statements are checked, as well as guard expressions in entry - calls. - - * `-gnatVf' Validity checks for floating-point values - - In the absence of this switch, validity checking occurs only for - discrete values. If `-gnatVf' is specified, then validity checking - also applies for floating-point values, and NaN's and infinities - are considered invalid, as well as out of range values for - constrained types. Note that this means that standard `IEEE' - infinity mode is not allowed. The exact contexts in which - floating-point values are checked depends on the setting of other - options. For example `-gnatVif' or `-gnatVfi' (the order does not - matter) specifies that floating-point parameters of mode `in' - should be validity checked. - - * `-gnatVa' All validity checks - - All the above validity checks are turned on. That is `-gnatVa' is - equivalent to `gnatVcdfimorst'. - - * `-gnatVn' No validity checks - - This switch turns off all validity checking, including the default - checking for case statements and left hand side subscripts. Note - that the use of the switch `-gnatp' supresses all run-time checks, - including validity checks, and thus implies `-gnatVn'. - - - The `-gnatV' switch may be followed by a string of letters to turn on - a series of validity checking options. For example, `-gnatVcr' specifies - that in addition to the default validity checking, copies and function - return expressions be validity checked. In order to make it easier to - specify a set of options, the upper case letters `CDFIMORST' may be - used to turn off the corresponding lower case option, so for example - `-gnatVaM' turns on all validity checking options except for checking - of `in out' procedure arguments. - - The specification of additional validity checking generates extra - code (and in the case of `-gnatva' the code expansion can be - substantial. However, these additional checks can be very useful in - smoking out cases of uninitialized variables, incorrect use of - unchecked conversion, and other errors leading to invalid values. The - use of pragma `Initialize_Scalars' is useful in conjunction with the - extra validity checking, since this ensures that wherever possible - uninitialized variables have invalid values. - - See also the pragma `Validity_Checks' which allows modification of - the validity checking mode at the program source level, and also allows - for temporary disabling of validity checks. - -  - File: gnat_ug_wnt.info, Node: Style Checking, Next: Using gcc for Syntax Checking, Prev: Validity Checking, Up: Switches for gcc - - Style Checking - -------------- - - The -gnatyX switch causes the compiler to enforce specified style - rules. A limited set of style rules has been used in writing the GNAT - sources themselves. This switch allows user programs to activate all or - some of these checks. If the source program fails a specified style - check, an appropriate warning message is given, preceded by the - character sequence "(style)". The string X is a sequence of letters or - digits indicating the particular style checks to be performed. The - following checks are defined: - - `1-9 (specify indentation level)' - If a digit from 1-9 appears in the string after `-gnaty' then - proper indentation is checked, with the digit indicating the - indentation level required. The general style of required - indentation is as specified by the examples in the Ada Reference - Manual. Full line comments must be aligned with the `--' starting - on a column that is a multiple of the alignment level. - - `a (check attribute casing)' - If the letter a appears in the string after `-gnaty' then - attribute names, including the case of keywords such as `digits' - used as attributes names, must be written in mixed case, that is, - the initial letter and any letter following an underscore must be - uppercase. All other letters must be lowercase. - - `b (blanks not allowed at statement end)' - If the letter b appears in the string after `-gnaty' then trailing - blanks are not allowed at the end of statements. The purpose of - this rule, together with h (no horizontal tabs), is to enforce a - canonical format for the use of blanks to separate source tokens. - - `c (check comments)' - If the letter c appears in the string after `-gnaty' then comments - must meet the following set of rules: - - * The "-" that starts the column must either start in column - one, or else at least one blank must precede this sequence. - - * Comments that follow other tokens on a line must have at - least one blank following the "-" at the start of the comment. - - * Full line comments must have two blanks following the "-" - that starts the comment, with the following exceptions. - - * A line consisting only of the "-" characters, possibly - preceded by blanks is permitted. - - * A comment starting with "-x" where x is a special character - is permitted. This alows proper processing of the output - generated by specialized tools including `gnatprep' (where -! - is used) and the SPARK annnotation language (where -# is - used). For the purposes of this rule, a special character is - defined as being in one of the ASCII ranges 16#21#..16#2F# or - 16#3A#..16#3F#. - - * A line consisting entirely of minus signs, possibly preceded - by blanks, is permitted. This allows the construction of box - comments where lines of minus signs are used to form the top - and bottom of the box. - - * If a comment starts and ends with "-" is permitted as long as - at least one blank follows the initial "-". Together with the - preceding rule, this allows the construction of box comments, - as shown in the following example: - --------------------------- - -- This is a box comment -- - -- with two text lines. -- - --------------------------- - - `e (check end/exit labels)' - If the letter e appears in the string after `-gnaty' then optional - labels on `end' statements ending subprograms and on `exit' - statements exiting named loops, are required to be present. - - `f (no form feeds or vertical tabs)' - If the letter f appears in the string after `-gnaty' then neither - form feeds nor vertical tab characters are not permitted in the - source text. - - `h (no horizontal tabs)' - If the letter h appears in the string after `-gnaty' then - horizontal tab characters are not permitted in the source text. - Together with the b (no blanks at end of line) check, this - enforces a canonical form for the use of blanks to separate source - tokens. - - `i (check if-then layout)' - If the letter i appears in the string after `-gnaty', then the - keyword `then' must appear either on the same line as - corresponding `if', or on a line on its own, lined up under the - `if' with at least one non-blank line in between containing all or - part of the condition to be tested. - - `k (check keyword casing)' - If the letter k appears in the string after `-gnaty' then all - keywords must be in lower case (with the exception of keywords - such as `digits' used as attribute names to which this check does - not apply). - - `l (check layout)' - If the letter l appears in the string after `-gnaty' then layout - of statement and declaration constructs must follow the - recommendations in the Ada Reference Manual, as indicated by the - form of the syntax rules. For example an `else' keyword must be - lined up with the corresponding `if' keyword. - - There are two respects in which the style rule enforced by this - check option are more liberal than those in the Ada Reference - Manual. First in the case of record declarations, it is - permissible to put the `record' keyword on the same line as the - `type' keyword, and then the `end' in `end record' must line up - under `type'. For example, either of the following two layouts is - acceptable: - - type q is record - a : integer; - b : integer; - end record; - - type q is - record - a : integer; - b : integer; - end record; - - Second, in the case of a block statement, a permitted alternative - is to put the block label on the same line as the `declare' or - `begin' keyword, and then line the `end' keyword up under the - block label. For example both the following are permitted: - - Block : declare - A : Integer := 3; - begin - Proc (A, A); - end Block; - - Block : - declare - A : Integer := 3; - begin - Proc (A, A); - end Block; - - The same alternative format is allowed for loops. For example, - both of the following are permitted: - - Clear : while J < 10 loop - A (J) := 0; - end loop Clear; - - Clear : - while J < 10 loop - A (J) := 0; - end loop Clear; - - `m (check maximum line length)' - If the letter m appears in the string after `-gnaty' then the - length of source lines must not exceed 79 characters, including - any trailing blanks. The value of 79 allows convenient display on - an 80 character wide device or window, allowing for possible - special treatment of 80 character lines. - - `Mnnn (set maximum line length)' - If the sequence Mnnn, where nnn is a decimal number, appears in - the string after `-gnaty' then the length of lines must not exceed - the given value. - - `n (check casing of entities in Standard)' - If the letter n appears in the string after `-gnaty' then any - identifier from Standard must be cased to match the presentation - in the Ada Reference Manual (for example, `Integer' and - `ASCII.NUL'). - - `o (check order of subprogram bodies)' - If the letter o appears in the string after `-gnaty' then all - subprogram bodies in a given scope (e.g. a package body) must be - in alphabetical order. The ordering rule uses normal Ada rules for - comparing strings, ignoring casing of letters, except that if - there is a trailing numeric suffix, then the value of this suffix - is used in the ordering (e.g. Junk2 comes before Junk10). - - `p (check pragma casing)' - If the letter p appears in the string after `-gnaty' then pragma - names must be written in mixed case, that is, the initial letter - and any letter following an underscore must be uppercase. All - other letters must be lowercase. - - `r (check references)' - If the letter r appears in the string after `-gnaty' then all - identifier references must be cased in the same way as the - corresponding declaration. No specific casing style is imposed on - identifiers. The only requirement is for consistency of references - with declarations. - - `s (check separate specs)' - If the letter s appears in the string after `-gnaty' then separate - declarations ("specs") are required for subprograms (a body is not - allowed to serve as its own declaration). The only exception is - that parameterless library level procedures are not required to - have a separate declaration. This exception covers the most - frequent form of main program procedures. - - `t (check token spacing)' - If the letter t appears in the string after `-gnaty' then the - following token spacing rules are enforced: - - * The keywords `abs' and `not' must be followed by a space. - - * The token `=>' must be surrounded by spaces. - - * The token `<>' must be preceded by a space or a left - parenthesis. - - * Binary operators other than `**' must be surrounded by spaces. - There is no restriction on the layout of the `**' binary - operator. - - * Colon must be surrounded by spaces. - - * Colon-equal (assignment) must be surrounded by spaces. - - * Comma must be the first non-blank character on the line, or be - immediately preceded by a non-blank character, and must be - followed by a space. - - * If the token preceding a left paren ends with a letter or - digit, then a space must separate the two tokens. - - * A right parenthesis must either be the first non-blank - character on a line, or it must be preceded by a non-blank - character. - - * A semicolon must not be preceded by a space, and must not be - followed by a non-blank character. - - * A unary plus or minus may not be followed by a space. - - * A vertical bar must be surrounded by spaces. - - In the above rules, appearing in column one is always permitted, - that is, counts as meeting either a requirement for a required - preceding space, or as meeting a requirement for no preceding - space. - - Appearing at the end of a line is also always permitted, that is, - counts as meeting either a requirement for a following space, or - as meeting a requirement for no following space. - - If any of these style rules is violated, a message is generated giving - details on the violation. The initial characters of such messages are - always "(style)". Note that these messages are treated as warning - messages, so they normally do not prevent the generation of an object - file. The `-gnatwe' switch can be used to treat warning messages, - including style messages, as fatal errors. - - The switch `-gnaty' on its own (that is not followed by any letters or - digits), is equivalent to `gnaty3abcefhiklmprst', that is all checking - options are enabled with the exception of -gnatyo, with an indentation - level of 3. This is the standard checking option that is used for the - GNAT sources. - -  - File: gnat_ug_wnt.info, Node: Run-Time Checks, Next: Stack Overflow Checking, Prev: Debugging and Assertion Control, Up: Switches for gcc - - Run-Time Checks - --------------- - - If you compile with the default options, GNAT will insert many run-time - checks into the compiled code, including code that performs range - checking against constraints, but not arithmetic overflow checking for - integer operations (including division by zero) or checks for access - before elaboration on subprogram calls. All other run-time checks, as - required by the Ada 95 Reference Manual, are generated by default. The - following `gcc' switches refine this default behavior: - - `-gnatp' - Suppress all run-time checks as though `pragma Suppress - (all_checks') had been present in the source. Validity checks are - also suppressed (in other words `-gnatp' also implies `-gnatVn'. - Use this switch to improve the performance of the code at the - expense of safety in the presence of invalid data or program bugs. - - `-gnato' - Enables overflow checking for integer operations. This causes - GNAT to generate slower and larger executable programs by adding - code to check for overflow (resulting in raising - `Constraint_Error' as required by standard Ada semantics). These - overflow checks correspond to situations in which the true value - of the result of an operation may be outside the base range of the - result type. The following example shows the distinction: - - X1 : Integer := Integer'Last; - X2 : Integer range 1 .. 5 := 5; - ... - X1 := X1 + 1; -- `-gnato' required to catch the Constraint_Error - X2 := X2 + 1; -- range check, `-gnato' has no effect here - - Here the first addition results in a value that is outside the - base range of Integer, and hence requires an overflow check for - detection of the constraint error. The second increment operation - results in a violation of the explicit range constraint, and such - range checks are always performed. Basically the compiler can - assume that in the absence of the `-gnato' switch that any value - of type `xxx' is in range of the base type of `xxx'. - - Note that the `-gnato' switch does not affect the code generated - for any floating-point operations; it applies only to integer - semantics). For floating-point, GNAT has the `Machine_Overflows' - attribute set to `False' and the normal mode of operation is to - generate IEEE NaN and infinite values on overflow or invalid - operations (such as dividing 0.0 by 0.0). - - The reason that we distinguish overflow checking from other kinds - of range constraint checking is that a failure of an overflow - check can generate an incorrect value, but cannot cause erroneous - behavior. This is unlike the situation with a constraint check on - an array subscript, where failure to perform the check can result - in random memory description, or the range check on a case - statement, where failure to perform the check can cause a wild - jump. - - Note again that `-gnato' is off by default, so overflow checking is - not performed in default mode. This means that out of the box, - with the default settings, GNAT does not do all the checks - expected from the language description in the Ada Reference - Manual. If you want all constraint checks to be performed, as - described in this Manual, then you must explicitly use the -gnato - switch either on the `gnatmake' or `gcc' command. - - `-gnatE' - Enables dynamic checks for access-before-elaboration on subprogram - calls and generic instantiations. For full details of the effect - and use of this switch, *Note Compiling Using gcc::. - - The setting of these switches only controls the default setting of the - checks. You may modify them using either `Suppress' (to remove checks) - or `Unsuppress' (to add back suppressed checks) pragmas in the program - source. - -  - File: gnat_ug_wnt.info, Node: Stack Overflow Checking, Next: Run-Time Control, Prev: Run-Time Checks, Up: Switches for gcc - - Stack Overflow Checking - ----------------------- - - For most operating systems, `gcc' does not perform stack overflow - checking by default. This means that if the main environment task or - some other task exceeds the available stack space, then unpredictable - behavior will occur. - - To activate stack checking, compile all units with the gcc option - `-fstack-check'. For example: - - gcc -c -fstack-check package1.adb - - Units compiled with this option will generate extra instructions to - check that any use of the stack (for procedure calls or for declaring - local variables in declare blocks) do not exceed the available stack - space. If the space is exceeded, then a `Storage_Error' exception is - raised. - - For declared tasks, the stack size is always controlled by the size - given in an applicable `Storage_Size' pragma (or is set to the default - size if no pragma is used. - - For the environment task, the stack size depends on system defaults - and is unknown to the compiler. The stack may even dynamically grow on - some systems, precluding the normal Ada semantics for stack overflow. - In the worst case, unbounded stack usage, causes unbounded stack - expansion resulting in the system running out of virtual memory. - - The stack checking may still work correctly if a fixed size stack is - allocated, but this cannot be guaranteed. To ensure that a clean - exception is signalled for stack overflow, set the environment variable - `GNAT_STACK_LIMIT' to indicate the maximum stack area that can be used, - as in: - - SET GNAT_STACK_LIMIT 1600 - - The limit is given in kilobytes, so the above declaration would set the - stack limit of the environment task to 1.6 megabytes. Note that the - only purpose of this usage is to limit the amount of stack used by the - environment task. If it is necessary to increase the amount of stack - for the environment task, then this is an operating systems issue, and - must be addressed with the appropriate operating systems commands. - -  - File: gnat_ug_wnt.info, Node: Run-Time Control, Next: Validity Checking, Prev: Stack Overflow Checking, Up: Switches for gcc - - Run-Time Control - ---------------- - - `-gnatT nnn' - The `gnatT' switch can be used to specify the time-slicing value - to be used for task switching between equal priority tasks. The - value `nnn' is given in microseconds as a decimal integer. - - Setting the time-slicing value is only effective if the underlying - thread control system can accommodate time slicing. Check the - documentation of your operating system for details. Note that the - time-slicing value can also be set by use of pragma `Time_Slice' - or by use of the `t' switch in the gnatbind step. The pragma - overrides a command line argument if both are present, and the `t' - switch for gnatbind overrides both the pragma and the `gcc' - command line switch. - -  - File: gnat_ug_wnt.info, Node: Using gcc for Syntax Checking, Next: Using gcc for Semantic Checking, Prev: Style Checking, Up: Switches for gcc - - Using `gcc' for Syntax Checking - ------------------------------- - - `-gnats' - The `s' stands for syntax. - - Run GNAT in syntax checking only mode. For example, the command - - $ gcc -c -gnats x.adb - - compiles file `x.adb' in syntax-check-only mode. You can check a - series of files in a single command , and can use wild cards to - specify such a group of files. Note that you must specify the - `-c' (compile only) flag in addition to the `-gnats' flag. . - - You may use other switches in conjunction with `-gnats'. In - particular, `-gnatl' and `-gnatv' are useful to control the format - of any generated error messages. - - The output is simply the error messages, if any. No object file or - ALI file is generated by a syntax-only compilation. Also, no units - other than the one specified are accessed. For example, if a unit - `X' `with''s a unit `Y', compiling unit `X' in syntax check only - mode does not access the source file containing unit `Y'. - - Normally, GNAT allows only a single unit in a source file. - However, this restriction does not apply in syntax-check-only - mode, and it is possible to check a file containing multiple - compilation units concatenated together. This is primarily used by - the `gnatchop' utility (*note Renaming Files Using gnatchop::). - -  - File: gnat_ug_wnt.info, Node: Using gcc for Semantic Checking, Next: Compiling Ada 83 Programs, Prev: Using gcc for Syntax Checking, Up: Switches for gcc - - Using `gcc' for Semantic Checking - --------------------------------- - - `-gnatc' - The `c' stands for check. Causes the compiler to operate in - semantic check mode, with full checking for all illegalities - specified in the Ada 95 Reference Manual, but without generation - of any object code (no object file is generated). - - Because dependent files must be accessed, you must follow the GNAT - semantic restrictions on file structuring to operate in this mode: - - * The needed source files must be accessible (*note Search - Paths and the Run-Time Library (RTL)::). - - * Each file must contain only one compilation unit. - - * The file name and unit name must match (*note File Naming - Rules::). - - The output consists of error messages as appropriate. No object - file is generated. An `ALI' file is generated for use in the - context of cross-reference tools, but this file is marked as not - being suitable for binding (since no object file is generated). - The checking corresponds exactly to the notion of legality in the - Ada 95 Reference Manual. - - Any unit can be compiled in semantics-checking-only mode, including - units that would not normally be compiled (subunits, and - specifications where a separate body is present). - -  - File: gnat_ug_wnt.info, Node: Compiling Ada 83 Programs, Next: Character Set Control, Prev: Using gcc for Semantic Checking, Up: Switches for gcc - - Compiling Ada 83 Programs - ------------------------- - - `-gnat83' - Although GNAT is primarily an Ada 95 compiler, it accepts this - switch to specify that an Ada 83 program is to be compiled in - Ada83 mode. If you specify this switch, GNAT rejects most Ada 95 - extensions and applies Ada 83 semantics where this can be done - easily. It is not possible to guarantee this switch does a perfect - job; for example, some subtle tests, such as are found in earlier - ACVC tests (that have been removed from the ACVC suite for Ada - 95), may not compile correctly. However, for most purposes, using - this switch should help to ensure that programs that compile - correctly under the `-gnat83' switch can be ported easily to an - Ada 83 compiler. This is the main use of the switch. - - With few exceptions (most notably the need to use `<>' on - unconstrained generic formal parameters, the use of the new Ada 95 - keywords, and the use of packages with optional bodies), it is not - necessary to use the `-gnat83' switch when compiling Ada 83 - programs, because, with rare exceptions, Ada 95 is upwardly - compatible with Ada 83. This means that a correct Ada 83 program - is usually also a correct Ada 95 program. - -  - File: gnat_ug_wnt.info, Node: Character Set Control, Next: File Naming Control, Prev: Compiling Ada 83 Programs, Up: Switches for gcc - - Character Set Control - --------------------- - - `-gnatiC' - Normally GNAT recognizes the Latin-1 character set in source - program identifiers, as described in the Ada 95 Reference Manual. - This switch causes GNAT to recognize alternate character sets in - identifiers. C is a single character indicating the character - set, as follows: - - `1' - Latin-1 identifiers - - `2' - Latin-2 letters allowed in identifiers - - `3' - Latin-3 letters allowed in identifiers - - `4' - Latin-4 letters allowed in identifiers - - `5' - Latin-5 (Cyrillic) letters allowed in identifiers - - `9' - Latin-9 letters allowed in identifiers - - `p' - IBM PC letters (code page 437) allowed in identifiers - - `8' - IBM PC letters (code page 850) allowed in identifiers - - `f' - Full upper-half codes allowed in identifiers - - `n' - No upper-half codes allowed in identifiers - - `w' - Wide-character codes (that is, codes greater than 255) - allowed in identifiers - - *Note Foreign Language Representation::, for full details on the - implementation of these character sets. - - `-gnatWE' - Specify the method of encoding for wide characters. E is one of - the following: - - `h' - Hex encoding (brackets coding also recognized) - - `u' - Upper half encoding (brackets encoding also recognized) - - `s' - Shift/JIS encoding (brackets encoding also recognized) - - `e' - EUC encoding (brackets encoding also recognized) - - `8' - UTF-8 encoding (brackets encoding also recognized) - - `b' - Brackets encoding only (default value) For full details on - the these encoding methods see *Note Wide Character Encodings::. - Note that brackets coding is always accepted, even if one of the - other options is specified, so for example `-gnatW8' specifies - that both brackets and `UTF-8' encodings will be recognized. The - units that are with'ed directly or indirectly will be scanned - using the specified representation scheme, and so if one of the - non-brackets scheme is used, it must be used consistently - throughout the program. However, since brackets encoding is always - recognized, it may be conveniently used in standard libraries, - allowing these libraries to be used with any of the available - coding schemes. scheme. If no `-gnatW?' parameter is present, - then the default representation is Brackets encoding only. - - Note that the wide character representation that is specified - (explicitly or by default) for the main program also acts as the - default encoding used for Wide_Text_IO files if not specifically - overridden by a WCEM form parameter. - -  - File: gnat_ug_wnt.info, Node: File Naming Control, Next: Subprogram Inlining Control, Prev: Character Set Control, Up: Switches for gcc - - File Naming Control - ------------------- - - `-gnatkN' - Activates file name "krunching". N, a decimal integer in the range - 1-999, indicates the maximum allowable length of a file name (not - including the `.ads' or `.adb' extension). The default is not to - enable file name krunching. - - For the source file naming rules, *Note File Naming Rules::. - -  - File: gnat_ug_wnt.info, Node: Subprogram Inlining Control, Next: Auxiliary Output Control, Prev: File Naming Control, Up: Switches for gcc - - Subprogram Inlining Control - --------------------------- - - `-gnatn' - The `n' here is intended to suggest the first syllable of the word - "inline". GNAT recognizes and processes `Inline' pragmas. - However, for the inlining to actually occur, optimization must be - enabled. To enable inlining across unit boundaries, this is, - inlining a call in one unit of a subprogram declared in a - `with''ed unit, you must also specify this switch. In the absence - of this switch, GNAT does not attempt inlining across units and - does not need to access the bodies of subprograms for which - `pragma Inline' is specified if they are not in the current unit. - - If you specify this switch the compiler will access these bodies, - creating an extra source dependency for the resulting object file, - and where possible, the call will be inlined. For further details - on when inlining is possible see *Note Inlining of Subprograms::. - - `-gnatN' - The front end inlining activated by this switch is generally more - extensive, and quite often more effective than the standard - `-gnatn' inlining mode. It will also generate additional - dependencies. - -  - File: gnat_ug_wnt.info, Node: Auxiliary Output Control, Next: Debugging Control, Prev: Subprogram Inlining Control, Up: Switches for gcc - - Auxiliary Output Control - ------------------------ - - `-gnatt' - Causes GNAT to write the internal tree for a unit to a file (with - the extension `.adt'. This not normally required, but is used by - separate analysis tools. Typically these tools do the necessary - compilations automatically, so you should not have to specify this - switch in normal operation. - - `-gnatu' - Print a list of units required by this compilation on `stdout'. - The listing includes all units on which the unit being compiled - depends either directly or indirectly. - - `-pass-exit-codes' - If this switch is not used, the exit code returned by `gcc' when - compiling multiple files indicates whether all source files have - been successfully used to generate object files or not. - - When `-pass-exit-codes' is used, `gcc' exits with an extended exit - status and allows an integrated development environment to better - react to a compilation failure. Those exit status are: - - 5 - There was an error in at least one source file. - - 3 - At least one source file did not generate an object file. - - 2 - The compiler died unexpectedly (internal error for example). - - 0 - An object file has been generated for every source file. - -  - File: gnat_ug_wnt.info, Node: Debugging Control, Next: Units to Sources Mapping Files, Prev: Auxiliary Output Control, Up: Switches for gcc - - Debugging Control - ----------------- - - `-gnatdX' - Activate internal debugging switches. X is a letter or digit, or - string of letters or digits, which specifies the type of debugging - outputs desired. Normally these are used only for internal - development or system debugging purposes. You can find full - documentation for these switches in the body of the `Debug' unit - in the compiler source file `debug.adb'. - - `-gnatG' - This switch causes the compiler to generate auxiliary output - containing a pseudo-source listing of the generated expanded code. - Like most Ada compilers, GNAT works by first transforming the high - level Ada code into lower level constructs. For example, tasking - operations are transformed into calls to the tasking run-time - routines. A unique capability of GNAT is to list this expanded - code in a form very close to normal Ada source. This is very - useful in understanding the implications of various Ada usage on - the efficiency of the generated code. There are many cases in Ada - (e.g. the use of controlled types), where simple Ada statements can - generate a lot of run-time code. By using `-gnatG' you can identify - these cases, and consider whether it may be desirable to modify - the coding approach to improve efficiency. - - The format of the output is very similar to standard Ada source, - and is easily understood by an Ada programmer. The following - special syntactic additions correspond to low level features used - in the generated code that do not have any exact analogies in pure - Ada source form. The following is a partial list of these special - constructions. See the specification of package `Sprint' in file - `sprint.ads' for a full list. - - `new XXX [storage_pool = YYY]' - Shows the storage pool being used for an allocator. - - `at end PROCEDURE-NAME;' - Shows the finalization (cleanup) procedure for a scope. - - `(if EXPR then EXPR else EXPR)' - Conditional expression equivalent to the `x?y:z' construction - in C. - - `TARGET^(SOURCE)' - A conversion with floating-point truncation instead of - rounding. - - `TARGET?(SOURCE)' - A conversion that bypasses normal Ada semantic checking. In - particular enumeration types and fixed-point types are - treated simply as integers. - - `TARGET?^(SOURCE)' - Combines the above two cases. - - `X #/ Y' - `X #mod Y' - `X #* Y' - `X #rem Y' - A division or multiplication of fixed-point values which are - treated as integers without any kind of scaling. - - `free EXPR [storage_pool = XXX]' - Shows the storage pool associated with a `free' statement. - - `freeze TYPENAME [ACTIONS]' - Shows the point at which TYPENAME is frozen, with possible - associated actions to be performed at the freeze point. - - `reference ITYPE' - Reference (and hence definition) to internal type ITYPE. - - `FUNCTION-NAME! (ARG, ARG, ARG)' - Intrinsic function call. - - `LABELNAME : label' - Declaration of label LABELNAME. - - `EXPR && EXPR && EXPR ... && EXPR' - A multiple concatenation (same effect as EXPR & EXPR & EXPR, - but handled more efficiently). - - `[constraint_error]' - Raise the `Constraint_Error' exception. - - `EXPRESSION'reference' - A pointer to the result of evaluating EXPRESSION. - - `TARGET-TYPE!(SOURCE-EXPRESSION)' - An unchecked conversion of SOURCE-EXPRESSION to TARGET-TYPE. - - `[NUMERATOR/DENOMINATOR]' - Used to represent internal real literals (that) have no exact - representation in base 2-16 (for example, the result of - compile time evaluation of the expression 1.0/27.0). - - `-gnatD' - This switch is used in conjunction with `-gnatG' to cause the - expanded source, as described above to be written to files - with names `xxx.dg', where `xxx' is the normal file name, for - example, if the source file name is `hello.adb', then a file - `hello.adb.dg' will be written. The debugging information - generated by the `gcc' `-g' switch will refer to the generated - `xxx.dg' file. This allows you to do source level debugging - using the generated code which is sometimes useful for - complex code, for example to find out exactly which part of a - complex construction raised an exception. This switch also - suppress generation of cross-reference information (see - -gnatx). - - `-gnatC' - In the generated debugging information, and also in the case - of long external names, the compiler uses a compression - mechanism if the name is very long. This compression method - uses a checksum, and avoids trouble on some operating systems - which have difficulty with very long names. The `-gnatC' - switch forces this compression approach to be used on all - external names and names in the debugging information tables. - This reduces the size of the generated executable, at the - expense of making the naming scheme more complex. The - compression only affects the qualification of the name. Thus - a name in the source: - - Very_Long_Package.Very_Long_Inner_Package.Var - - would normally appear in these tables as: - - very_long_package__very_long_inner_package__var - - but if the `-gnatC' switch is used, then the name appears as - - XCb7e0c705__var - - Here b7e0c705 is a compressed encoding of the qualification - prefix. The GNAT Ada aware version of GDB understands these - encoded prefixes, so if this debugger is used, the encoding - is largely hidden from the user of the compiler. - - `-gnatR[0|1|2|3][s]' - This switch controls output from the compiler of a listing showing - representation information for declared types and objects. For - `-gnatR0', no information is output (equivalent to omitting the - `-gnatR' switch). For `-gnatR1' (which is the default, so `-gnatR' - with no parameter has the same effect), size and alignment - information is listed for declared array and record types. For - `-gnatR2', size and alignment information is listed for all - expression information for values that are computed at run time for - variant records. These symbolic expressions have a mostly obvious - format with #n being used to represent the value of the n'th - discriminant. See source files `repinfo.ads/adb' in the `GNAT' - sources for full detalis on the format of `-gnatR3' output. If the - switch is followed by an s (e.g. `-gnatR2s'), then the output is - to a file with the name `file.rep' where file is the name of the - corresponding source file. - - `-gnatx' - Normally the compiler generates full cross-referencing information - in the `ALI' file. This information is used by a number of tools, - including `gnatfind' and `gnatxref'. The -gnatx switch suppresses - this information. This saves some space and may slightly speed up - compilation, but means that these tools cannot be used. - -  - File: gnat_ug_wnt.info, Node: Units to Sources Mapping Files, Prev: Debugging Control, Up: Switches for gcc - - Units to Sources Mapping Files - ------------------------------ - - `-gnatemPATH' - A mapping file is a way to communicate to the compiler two - mappings: from unit names to file names (without any directory - information) and from file names to path names (with full - directory information). These mappings are used by the compiler to - short-circuit the path search. - - A mapping file is a sequence of sets of three lines. In each set, - the first line is the unit name, in lower case, with "%s" appended - for specifications and "%b" appended for bodies; the second line - is the file name; and the third line is the path name. - - Example: - main%b - main.2.ada - /gnat/project1/sources/main.2.ada - - When the switch `-gnatem' is specified, the compiler will create - in memory the two mappings from the specified file. If there is - any problem (non existent file, truncated file or duplicate - entries), no mapping will be created. - - Several `-gnatem' switches may be specified; however, only the last - one on the command line will be taken into account. - - When using a project file, `gnatmake' create a temporary mapping - file and communicates it to the compiler using this switch. - -  - File: gnat_ug_wnt.info, Node: Search Paths and the Run-Time Library (RTL), Next: Order of Compilation Issues, Prev: Switches for gcc, Up: Compiling Using gcc - - Search Paths and the Run-Time Library (RTL) - =========================================== - - With the GNAT source-based library system, the compiler must be able to - find source files for units that are needed by the unit being compiled. - Search paths are used to guide this process. - - The compiler compiles one source file whose name must be given - explicitly on the command line. In other words, no searching is done - for this file. To find all other source files that are needed (the most - common being the specs of units), the compiler examines the following - directories, in the following order: - - 1. The directory containing the source file of the main unit being - compiled (the file name on the command line). - - 2. Each directory named by an `-I' switch given on the `gcc' command - line, in the order given. - - 3. Each of the directories listed in the value of the - `ADA_INCLUDE_PATH' environment variable. Construct this value - exactly as the `PATH' environment variable: a list of directory - names separated by colons (semicolons when working with the NT - version). - - 4. The content of the "ada_source_path" file which is part of the GNAT - installation tree and is used to store standard libraries such as - the GNAT Run Time Library (RTL) source files. *Note Installing an - Ada Library:: - - Specifying the switch `-I-' inhibits the use of the directory - containing the source file named in the command line. You can still - have this directory on your search path, but in this case it must be - explicitly requested with a `-I' switch. - - Specifying the switch `-nostdinc' inhibits the search of the default - location for the GNAT Run Time Library (RTL) source files. - - The compiler outputs its object files and ALI files in the current - working directory. Caution: The object file can be redirected with the - `-o' switch; however, `gcc' and `gnat1' have not been coordinated on - this so the ALI file will not go to the right place. Therefore, you - should avoid using the `-o' switch. - - The packages `Ada', `System', and `Interfaces' and their children - make up the GNAT RTL, together with the simple `System.IO' package used - in the "Hello World" example. The sources for these units are needed by - the compiler and are kept together in one directory. Not all of the - bodies are needed, but all of the sources are kept together anyway. In - a normal installation, you need not specify these directory names when - compiling or binding. Either the environment variables or the built-in - defaults cause these files to be found. - - In addition to the language-defined hierarchies (System, Ada and - Interfaces), the GNAT distribution provides a fourth hierarchy, - consisting of child units of GNAT. This is a collection of generally - useful routines. See the GNAT Reference Manual for further details. - - Besides simplifying access to the RTL, a major use of search paths is - in compiling sources from multiple directories. This can make - development environments much more flexible. - -  - File: gnat_ug_wnt.info, Node: Order of Compilation Issues, Next: Examples, Prev: Search Paths and the Run-Time Library (RTL), Up: Compiling Using gcc - - Order of Compilation Issues - =========================== - - If, in our earlier example, there was a spec for the `hello' procedure, - it would be contained in the file `hello.ads'; yet this file would not - have to be explicitly compiled. This is the result of the model we - chose to implement library management. Some of the consequences of this - model are as follows: - - * There is no point in compiling specs (except for package specs - with no bodies) because these are compiled as needed by clients. If - you attempt a useless compilation, you will receive an error - message. It is also useless to compile subunits because they are - compiled as needed by the parent. - - * There are no order of compilation requirements: performing a - compilation never obsoletes anything. The only way you can obsolete - something and require recompilations is to modify one of the - source files on which it depends. - - * There is no library as such, apart from the ALI files (*note The - Ada Library Information Files::, for information on the format of - these files). For now we find it convenient to create separate ALI - files, but eventually the information therein may be incorporated - into the object file directly. - - * When you compile a unit, the source files for the specs of all - units that it `with''s, all its subunits, and the bodies of any - generics it instantiates must be available (reachable by the - search-paths mechanism described above), or you will receive a - fatal error message. - -  - File: gnat_ug_wnt.info, Node: Examples, Prev: Order of Compilation Issues, Up: Compiling Using gcc - - Examples - ======== - - The following are some typical Ada compilation command line examples: - - `$ gcc -c xyz.adb' - Compile body in file `xyz.adb' with all default options. - - `$ gcc -c -O2 -gnata xyz-def.adb' - Compile the child unit package in file `xyz-def.adb' with extensive - optimizations, and pragma `Assert'/`Debug' statements enabled. - - `$ gcc -c -gnatc abc-def.adb' - Compile the subunit in file `abc-def.adb' in semantic-checking-only - mode. - -  - File: gnat_ug_wnt.info, Node: Binding Using gnatbind, Next: Linking Using gnatlink, Prev: Compiling Using gcc, Up: Top - - Binding Using `gnatbind' - ************************ - - * Menu: - - * Running gnatbind:: - * Generating the Binder Program in C:: - * Consistency-Checking Modes:: - * Binder Error Message Control:: - * Elaboration Control:: - * Output Control:: - * Binding with Non-Ada Main Programs:: - * Binding Programs with No Main Subprogram:: - * Summary of Binder Switches:: - * Command-Line Access:: - * Search Paths for gnatbind:: - * Examples of gnatbind Usage:: - - This chapter describes the GNAT binder, `gnatbind', which is used to - bind compiled GNAT objects. The `gnatbind' program performs four - separate functions: - - 1. Checks that a program is consistent, in accordance with the rules - in Chapter 10 of the Ada 95 Reference Manual. In particular, error - messages are generated if a program uses inconsistent versions of a - given unit. - - 2. Checks that an acceptable order of elaboration exists for the - program and issues an error message if it cannot find an order of - elaboration that satisfies the rules in Chapter 10 of the Ada 95 - Language Manual. - - 3. Generates a main program incorporating the given elaboration order. - This program is a small Ada package (body and spec) that must be - subsequently compiled using the GNAT compiler. The necessary - compilation step is usually performed automatically by `gnatlink'. - The two most important functions of this program are to call the - elaboration routines of units in an appropriate order and to call - the main program. - - 4. Determines the set of object files required by the given main - program. This information is output in the forms of comments in - the generated program, to be read by the `gnatlink' utility used - to link the Ada application. - -  - File: gnat_ug_wnt.info, Node: Running gnatbind, Next: Generating the Binder Program in C, Up: Binding Using gnatbind - - Running `gnatbind' - ================== - - The form of the `gnatbind' command is - - $ gnatbind [SWITCHES] MAINPROG[.ali] [SWITCHES] - - where MAINPROG.adb is the Ada file containing the main program unit - body. If no switches are specified, `gnatbind' constructs an Ada - package in two files which names are `b~ADA_MAIN.ads', and - `b~ADA_MAIN.adb'. For example, if given the parameter `hello.ali', for - a main program contained in file `hello.adb', the binder output files - would be `b~hello.ads' and `b~hello.adb'. - - When doing consistency checking, the binder takes into consideration - any source files it can locate. For example, if the binder determines - that the given main program requires the package `Pack', whose `.ali' - file is `pack.ali' and whose corresponding source spec file is - `pack.ads', it attempts to locate the source file `pack.ads' (using the - same search path conventions as previously described for the `gcc' - command). If it can locate this source file, it checks that the time - stamps or source checksums of the source and its references to in `ali' - files match. In other words, any `ali' files that mentions this spec - must have resulted from compiling this version of the source file (or - in the case where the source checksums match, a version close enough - that the difference does not matter). - - The effect of this consistency checking, which includes source - files, is that the binder ensures that the program is consistent with - the latest version of the source files that can be located at bind - time. Editing a source file without compiling files that depend on the - source file cause error messages to be generated by the binder. - - For example, suppose you have a main program `hello.adb' and a - package `P', from file `p.ads' and you perform the following steps: - - 1. Enter `gcc -c hello.adb' to compile the main program. - - 2. Enter `gcc -c p.ads' to compile package `P'. - - 3. Edit file `p.ads'. - - 4. Enter `gnatbind hello'. - - At this point, the file `p.ali' contains an out-of-date time stamp - because the file `p.ads' has been edited. The attempt at binding fails, - and the binder generates the following error messages: - - error: "hello.adb" must be recompiled ("p.ads" has been modified) - error: "p.ads" has been modified and must be recompiled - - Now both files must be recompiled as indicated, and then the bind can - succeed, generating a main program. You need not normally be concerned - with the contents of this file, but it is similar to the following which - is the binder file generated for a simple "hello world" program. - - -- The package is called Ada_Main unless this name is actually used - -- as a unit name in the partition, in which case some other unique - -- name is used. - - with System; - package ada_main is - - Elab_Final_Code : Integer; - pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code"); - - -- The main program saves the parameters (argument count, - -- argument values, environment pointer) in global variables - -- for later access by other units including - -- Ada.Command_Line. - - gnat_argc : Integer; - gnat_argv : System.Address; - gnat_envp : System.Address; - - -- The actual variables are stored in a library routine. This - -- is useful for some shared library situations, where there - -- are problems if variables are not in the library. - - pragma Import (C, gnat_argc); - pragma Import (C, gnat_argv); - pragma Import (C, gnat_envp); - - -- The exit status is similarly an external location - - gnat_exit_status : Integer; - pragma Import (C, gnat_exit_status); - - GNAT_Version : constant String := - "GNAT Version: 3.15w (20010315)"; - pragma Export (C, GNAT_Version, "__gnat_version"); - - -- This is the generated adafinal routine that performs - -- finalization at the end of execution. In the case where - -- Ada is the main program, this main program makes a call - -- to adafinal at program termination. - - procedure adafinal; - pragma Export (C, adafinal, "adafinal"); - - -- This is the generated adainit routine that performs - -- initialization at the start of execution. In the case - -- where Ada is the main program, this main program makes - -- a call to adainit at program startup. - - procedure adainit; - pragma Export (C, adainit, "adainit"); - - -- This routine is called at the start of execution. It is - -- a dummy routine that is used by the debugger to breakpoint - -- at the start of execution. - - procedure Break_Start; - pragma Import (C, Break_Start, "__gnat_break_start"); - - -- This is the actual generated main program (it would be - -- suppressed if the no main program switch were used). As - -- required by standard system conventions, this program has - -- the external name main. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer; - pragma Export (C, main, "main"); - - -- The following set of constants give the version - -- identification values for every unit in the bound - -- partition. This identification is computed from all - -- dependent semantic units, and corresponds to the - -- string that would be returned by use of the - -- Body_Version or Version attributes. - - type Version_32 is mod 2 ** 32; - u00001 : constant Version_32 := 16#7880BEB3#; - u00002 : constant Version_32 := 16#0D24CBD0#; - u00003 : constant Version_32 := 16#3283DBEB#; - u00004 : constant Version_32 := 16#2359F9ED#; - u00005 : constant Version_32 := 16#664FB847#; - u00006 : constant Version_32 := 16#68E803DF#; - u00007 : constant Version_32 := 16#5572E604#; - u00008 : constant Version_32 := 16#46B173D8#; - u00009 : constant Version_32 := 16#156A40CF#; - u00010 : constant Version_32 := 16#033DABE0#; - u00011 : constant Version_32 := 16#6AB38FEA#; - u00012 : constant Version_32 := 16#22B6217D#; - u00013 : constant Version_32 := 16#68A22947#; - u00014 : constant Version_32 := 16#18CC4A56#; - u00015 : constant Version_32 := 16#08258E1B#; - u00016 : constant Version_32 := 16#367D5222#; - u00017 : constant Version_32 := 16#20C9ECA4#; - u00018 : constant Version_32 := 16#50D32CB6#; - u00019 : constant Version_32 := 16#39A8BB77#; - u00020 : constant Version_32 := 16#5CF8FA2B#; - u00021 : constant Version_32 := 16#2F1EB794#; - u00022 : constant Version_32 := 16#31AB6444#; - u00023 : constant Version_32 := 16#1574B6E9#; - u00024 : constant Version_32 := 16#5109C189#; - u00025 : constant Version_32 := 16#56D770CD#; - u00026 : constant Version_32 := 16#02F9DE3D#; - u00027 : constant Version_32 := 16#08AB6B2C#; - u00028 : constant Version_32 := 16#3FA37670#; - u00029 : constant Version_32 := 16#476457A0#; - u00030 : constant Version_32 := 16#731E1B6E#; - u00031 : constant Version_32 := 16#23C2E789#; - u00032 : constant Version_32 := 16#0F1BD6A1#; - u00033 : constant Version_32 := 16#7C25DE96#; - u00034 : constant Version_32 := 16#39ADFFA2#; - u00035 : constant Version_32 := 16#571DE3E7#; - u00036 : constant Version_32 := 16#5EB646AB#; - u00037 : constant Version_32 := 16#4249379B#; - u00038 : constant Version_32 := 16#0357E00A#; - u00039 : constant Version_32 := 16#3784FB72#; - u00040 : constant Version_32 := 16#2E723019#; - u00041 : constant Version_32 := 16#623358EA#; - u00042 : constant Version_32 := 16#107F9465#; - u00043 : constant Version_32 := 16#6843F68A#; - u00044 : constant Version_32 := 16#63305874#; - u00045 : constant Version_32 := 16#31E56CE1#; - u00046 : constant Version_32 := 16#02917970#; - u00047 : constant Version_32 := 16#6CCBA70E#; - u00048 : constant Version_32 := 16#41CD4204#; - u00049 : constant Version_32 := 16#572E3F58#; - u00050 : constant Version_32 := 16#20729FF5#; - u00051 : constant Version_32 := 16#1D4F93E8#; - u00052 : constant Version_32 := 16#30B2EC3D#; - u00053 : constant Version_32 := 16#34054F96#; - u00054 : constant Version_32 := 16#5A199860#; - u00055 : constant Version_32 := 16#0E7F912B#; - u00056 : constant Version_32 := 16#5760634A#; - u00057 : constant Version_32 := 16#5D851835#; - - -- The following Export pragmas export the version numbers - -- with symbolic names ending in B (for body) or S - -- (for spec) so that they can be located in a link. The - -- information provided here is sufficient to track down - -- the exact versions of units used in a given build. - - pragma Export (C, u00001, "helloB"); - pragma Export (C, u00002, "system__standard_libraryB"); - pragma Export (C, u00003, "system__standard_libraryS"); - pragma Export (C, u00004, "adaS"); - pragma Export (C, u00005, "ada__text_ioB"); - pragma Export (C, u00006, "ada__text_ioS"); - pragma Export (C, u00007, "ada__exceptionsB"); - pragma Export (C, u00008, "ada__exceptionsS"); - pragma Export (C, u00009, "gnatS"); - pragma Export (C, u00010, "gnat__heap_sort_aB"); - pragma Export (C, u00011, "gnat__heap_sort_aS"); - pragma Export (C, u00012, "systemS"); - pragma Export (C, u00013, "system__exception_tableB"); - pragma Export (C, u00014, "system__exception_tableS"); - pragma Export (C, u00015, "gnat__htableB"); - pragma Export (C, u00016, "gnat__htableS"); - pragma Export (C, u00017, "system__exceptionsS"); - pragma Export (C, u00018, "system__machine_state_operationsB"); - pragma Export (C, u00019, "system__machine_state_operationsS"); - pragma Export (C, u00020, "system__machine_codeS"); - pragma Export (C, u00021, "system__storage_elementsB"); - pragma Export (C, u00022, "system__storage_elementsS"); - pragma Export (C, u00023, "system__secondary_stackB"); - pragma Export (C, u00024, "system__secondary_stackS"); - pragma Export (C, u00025, "system__parametersB"); - pragma Export (C, u00026, "system__parametersS"); - pragma Export (C, u00027, "system__soft_linksB"); - pragma Export (C, u00028, "system__soft_linksS"); - pragma Export (C, u00029, "system__stack_checkingB"); - pragma Export (C, u00030, "system__stack_checkingS"); - pragma Export (C, u00031, "system__tracebackB"); - pragma Export (C, u00032, "system__tracebackS"); - pragma Export (C, u00033, "ada__streamsS"); - pragma Export (C, u00034, "ada__tagsB"); - pragma Export (C, u00035, "ada__tagsS"); - pragma Export (C, u00036, "system__string_opsB"); - pragma Export (C, u00037, "system__string_opsS"); - pragma Export (C, u00038, "interfacesS"); - pragma Export (C, u00039, "interfaces__c_streamsB"); - pragma Export (C, u00040, "interfaces__c_streamsS"); - pragma Export (C, u00041, "system__file_ioB"); - pragma Export (C, u00042, "system__file_ioS"); - pragma Export (C, u00043, "ada__finalizationB"); - pragma Export (C, u00044, "ada__finalizationS"); - pragma Export (C, u00045, "system__finalization_rootB"); - pragma Export (C, u00046, "system__finalization_rootS"); - pragma Export (C, u00047, "system__finalization_implementationB"); - pragma Export (C, u00048, "system__finalization_implementationS"); - pragma Export (C, u00049, "system__string_ops_concat_3B"); - pragma Export (C, u00050, "system__string_ops_concat_3S"); - pragma Export (C, u00051, "system__stream_attributesB"); - pragma Export (C, u00052, "system__stream_attributesS"); - pragma Export (C, u00053, "ada__io_exceptionsS"); - pragma Export (C, u00054, "system__unsigned_typesS"); - pragma Export (C, u00055, "system__file_control_blockS"); - pragma Export (C, u00056, "ada__finalization__list_controllerB"); - pragma Export (C, u00057, "ada__finalization__list_controllerS"); - - -- BEGIN ELABORATION ORDER - -- ada (spec) - -- gnat (spec) - -- gnat.heap_sort_a (spec) - -- gnat.heap_sort_a (body) - -- gnat.htable (spec) - -- gnat.htable (body) - -- interfaces (spec) - -- system (spec) - -- system.machine_code (spec) - -- system.parameters (spec) - -- system.parameters (body) - -- interfaces.c_streams (spec) - -- interfaces.c_streams (body) - -- system.standard_library (spec) - -- ada.exceptions (spec) - -- system.exception_table (spec) - -- system.exception_table (body) - -- ada.io_exceptions (spec) - -- system.exceptions (spec) - -- system.storage_elements (spec) - -- system.storage_elements (body) - -- system.machine_state_operations (spec) - -- system.machine_state_operations (body) - -- system.secondary_stack (spec) - -- system.stack_checking (spec) - -- system.soft_links (spec) - -- system.soft_links (body) - -- system.stack_checking (body) - -- system.secondary_stack (body) - -- system.standard_library (body) - -- system.string_ops (spec) - -- system.string_ops (body) - -- ada.tags (spec) - -- ada.tags (body) - -- ada.streams (spec) - -- system.finalization_root (spec) - -- system.finalization_root (body) - -- system.string_ops_concat_3 (spec) - -- system.string_ops_concat_3 (body) - -- system.traceback (spec) - -- system.traceback (body) - -- ada.exceptions (body) - -- system.unsigned_types (spec) - -- system.stream_attributes (spec) - -- system.stream_attributes (body) - -- system.finalization_implementation (spec) - -- system.finalization_implementation (body) - -- ada.finalization (spec) - -- ada.finalization (body) - -- ada.finalization.list_controller (spec) - -- ada.finalization.list_controller (body) - -- system.file_control_block (spec) - -- system.file_io (spec) - -- system.file_io (body) - -- ada.text_io (spec) - -- ada.text_io (body) - -- hello (body) - -- END ELABORATION ORDER - - end ada_main; - - -- The following source file name pragmas allow the generated file - -- names to be unique for different main programs. They are needed - -- since the package name will always be Ada_Main. - - pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads"); - pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb"); - - -- Generated package body for Ada_Main starts here - - package body ada_main is - - -- The actual finalization is performed by calling the - -- library routine in System.Standard_Library.Adafinal - - procedure Do_Finalize; - pragma Import (C, Do_Finalize, "system__standard_library__adafinal"); - - ------------- - -- adainit -- - ------------- - - procedure adainit is - - -- These booleans are set to True once the associated unit has - -- been elaborated. It is also used to avoid elaborating the - -- same unit twice. - - E040 : Boolean; pragma Import (Ada, E040, "interfaces__c_streams_E"); - E008 : Boolean; pragma Import (Ada, E008, "ada__exceptions_E"); - E014 : Boolean; pragma Import (Ada, E014, "system__exception_table_E"); - E053 : Boolean; pragma Import (Ada, E053, "ada__io_exceptions_E"); - E017 : Boolean; pragma Import (Ada, E017, "system__exceptions_E"); - E024 : Boolean; pragma Import (Ada, E024, "system__secondary_stack_E"); - E030 : Boolean; pragma Import (Ada, E030, "system__stack_checking_E"); - E028 : Boolean; pragma Import (Ada, E028, "system__soft_links_E"); - E035 : Boolean; pragma Import (Ada, E035, "ada__tags_E"); - E033 : Boolean; pragma Import (Ada, E033, "ada__streams_E"); - E046 : Boolean; pragma Import (Ada, E046, "system__finalization_root_E"); - E048 : Boolean; pragma Import (Ada, E048, "system__finalization_implementation_E"); - E044 : Boolean; pragma Import (Ada, E044, "ada__finalization_E"); - E057 : Boolean; pragma Import (Ada, E057, "ada__finalization__list_controller_E"); - E055 : Boolean; pragma Import (Ada, E055, "system__file_control_block_E"); - E042 : Boolean; pragma Import (Ada, E042, "system__file_io_E"); - E006 : Boolean; pragma Import (Ada, E006, "ada__text_io_E"); - - -- Set_Globals is a library routine that stores away the - -- value of the indicated set of global values in global - -- variables within the library. - - procedure Set_Globals - (Main_Priority : Integer; - Time_Slice_Value : Integer; - WC_Encoding : Character; - Locking_Policy : Character; - Queuing_Policy : Character; - Task_Dispatching_Policy : Character; - Adafinal : System.Address; - Unreserve_All_Interrupts : Integer; - Exception_Tracebacks : Integer); - pragma Import (C, Set_Globals, "__gnat_set_globals"); - - -- SDP_Table_Build is a library routine used to build the - -- exception tables. See unit Ada.Exceptions in files - -- a-except.ads/adb for full details of how zero cost - -- exception handling works. This procedure, the call to - -- it, and the two following tables are all omitted if the - -- build is in longjmp/setjump exception mode. - - procedure SDP_Table_Build - (SDP_Addresses : System.Address; - SDP_Count : Natural; - Elab_Addresses : System.Address; - Elab_Addr_Count : Natural); - pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build"); - - -- Table of Unit_Exception_Table addresses. Used for zero - -- cost exception handling to build the top level table. - - ST : aliased constant array (1 .. 23) of System.Address := ( - Hello'UET_Address, - Ada.Text_Io'UET_Address, - Ada.Exceptions'UET_Address, - Gnat.Heap_Sort_A'UET_Address, - System.Exception_Table'UET_Address, - System.Machine_State_Operations'UET_Address, - System.Secondary_Stack'UET_Address, - System.Parameters'UET_Address, - System.Soft_Links'UET_Address, - System.Stack_Checking'UET_Address, - System.Traceback'UET_Address, - Ada.Streams'UET_Address, - Ada.Tags'UET_Address, - System.String_Ops'UET_Address, - Interfaces.C_Streams'UET_Address, - System.File_Io'UET_Address, - Ada.Finalization'UET_Address, - System.Finalization_Root'UET_Address, - System.Finalization_Implementation'UET_Address, - System.String_Ops_Concat_3'UET_Address, - System.Stream_Attributes'UET_Address, - System.File_Control_Block'UET_Address, - Ada.Finalization.List_Controller'UET_Address); - - -- Table of addresses of elaboration routines. Used for - -- zero cost exception handling to make sure these - -- addresses are included in the top level procedure - -- address table. - - EA : aliased constant array (1 .. 23) of System.Address := ( - adainit'Code_Address, - Do_Finalize'Code_Address, - Ada.Exceptions'Elab_Spec'Address, - System.Exceptions'Elab_Spec'Address, - Interfaces.C_Streams'Elab_Spec'Address, - System.Exception_Table'Elab_Body'Address, - Ada.Io_Exceptions'Elab_Spec'Address, - System.Stack_Checking'Elab_Spec'Address, - System.Soft_Links'Elab_Body'Address, - System.Secondary_Stack'Elab_Body'Address, - Ada.Tags'Elab_Spec'Address, - Ada.Tags'Elab_Body'Address, - Ada.Streams'Elab_Spec'Address, - System.Finalization_Root'Elab_Spec'Address, - Ada.Exceptions'Elab_Body'Address, - System.Finalization_Implementation'Elab_Spec'Address, - System.Finalization_Implementation'Elab_Body'Address, - Ada.Finalization'Elab_Spec'Address, - Ada.Finalization.List_Controller'Elab_Spec'Address, - System.File_Control_Block'Elab_Spec'Address, - System.File_Io'Elab_Body'Address, - Ada.Text_Io'Elab_Spec'Address, - Ada.Text_Io'Elab_Body'Address); - - -- Start of processing for adainit - - begin - - -- Call SDP_Table_Build to build the top level procedure - -- table for zero cost exception handling (omitted in - -- longjmp/setjump mode). - - SDP_Table_Build (ST'Address, 23, EA'Address, 23); - - -- Call Set_Globals to record various information for - -- this partition. The values are derived by the binder - -- from information stored in the ali files by the compiler. - - Set_Globals - (Main_Priority => -1, - -- Priority of main program, -1 if no pragma Priority used - - Time_Slice_Value => -1, - -- Time slice from Time_Slice pragma, -1 if none used - - WC_Encoding => 'b', - -- Wide_Character encoding used, default is brackets - - Locking_Policy => ' ', - -- Locking_Policy used, default of space means not - -- specified, otherwise it is the first character of - -- the policy name. - - Queuing_Policy => ' ', - -- Queuing_Policy used, default of space means not - -- specified, otherwise it is the first character of - -- the policy name. - - Task_Dispatching_Policy => ' ', - -- Task_Dispatching_Policy used, default of space means - -- not specified, otherwise first character of the - -- policy name. - - Adafinal => System.Null_Address, - -- Address of Adafinal routine, not used anymore - - Unreserve_All_Interrupts => 0, - -- Set true if pragma Unreserve_All_Interrupts was used - - Exception_Tracebacks => 0); - -- Indicates if exception tracebacks are enabled - - Elab_Final_Code := 1; - - -- Now we have the elaboration calls for all units in the partition. - -- The Elab_Spec and Elab_Body attributes generate references to the - -- implicit elaboration procedures generated by the compiler for - -- each unit that requires elaboration. - - if not E040 then - Interfaces.C_Streams'Elab_Spec; - end if; - E040 := True; - if not E008 then - Ada.Exceptions'Elab_Spec; - end if; - if not E014 then - System.Exception_Table'Elab_Body; - E014 := True; - end if; - if not E053 then - Ada.Io_Exceptions'Elab_Spec; - E053 := True; - end if; - if not E017 then - System.Exceptions'Elab_Spec; - E017 := True; - end if; - if not E030 then - System.Stack_Checking'Elab_Spec; - end if; - if not E028 then - System.Soft_Links'Elab_Body; - E028 := True; - end if; - E030 := True; - if not E024 then - System.Secondary_Stack'Elab_Body; - E024 := True; - end if; - if not E035 then - Ada.Tags'Elab_Spec; - end if; - if not E035 then - Ada.Tags'Elab_Body; - E035 := True; - end if; - if not E033 then - Ada.Streams'Elab_Spec; - E033 := True; - end if; - if not E046 then - System.Finalization_Root'Elab_Spec; - end if; - E046 := True; - if not E008 then - Ada.Exceptions'Elab_Body; - E008 := True; - end if; - if not E048 then - System.Finalization_Implementation'Elab_Spec; - end if; - if not E048 then - System.Finalization_Implementation'Elab_Body; - E048 := True; - end if; - if not E044 then - Ada.Finalization'Elab_Spec; - end if; - E044 := True; - if not E057 then - Ada.Finalization.List_Controller'Elab_Spec; - end if; - E057 := True; - if not E055 then - System.File_Control_Block'Elab_Spec; - E055 := True; - end if; - if not E042 then - System.File_Io'Elab_Body; - E042 := True; - end if; - if not E006 then - Ada.Text_Io'Elab_Spec; - end if; - if not E006 then - Ada.Text_Io'Elab_Body; - E006 := True; - end if; - - Elab_Final_Code := 0; - end adainit; - - -------------- - -- adafinal -- - -------------- - - procedure adafinal is - begin - Do_Finalize; - end adafinal; - - ---------- - -- main -- - ---------- - - -- main is actually a function, as in the ANSI C standard, - -- defined to return the exit status. The three parameters - -- are the argument count, argument values and environment - -- pointer. - - function main - (argc : Integer; - argv : System.Address; - envp : System.Address) - return Integer - is - -- The initialize routine performs low level system - -- initialization using a standard library routine which - -- sets up signal handling and performs any other - -- required setup. The routine can be found in file - -- a-init.c. - - procedure initialize; - pragma Import (C, initialize, "__gnat_initialize"); - - -- The finalize routine performs low level system - -- finalization using a standard library routine. The - -- routine is found in file a-final.c and in the standard - -- distribution is a dummy routine that does nothing, so - -- really this is a hook for special user finalization. - - procedure finalize; - pragma Import (C, finalize, "__gnat_finalize"); - - -- We get to the main program of the partition by using - -- pragma Import because if we try to with the unit and - -- call it Ada style, then not only do we waste time - -- recompiling it, but also, we don't really know the right - -- switches (e.g. identifier character set) to be used - -- to compile it. - - procedure Ada_Main_Program; - pragma Import (Ada, Ada_Main_Program, "_ada_hello"); - - -- Start of processing for main - - begin - -- Save global variables - - gnat_argc := argc; - gnat_argv := argv; - gnat_envp := envp; - - -- Call low level system initialization - - Initialize; - - -- Call our generated Ada initialization routine - - adainit; - - -- This is the point at which we want the debugger to get - -- control - - Break_Start; - - -- Now we call the main program of the partition - - Ada_Main_Program; - - -- Perform Ada finalization - - adafinal; - - -- Perform low level system finalization - - Finalize; - - -- Return the proper exit status - return (gnat_exit_status); - end; - - -- This section is entirely comments, so it has no effect on the - -- compilation of the Ada_Main package. It provides the list of - -- object files and linker options, as well as some standard - -- libraries needed for the link. The gnatlink utility parses - -- this b~hello.adb file to read these comment lines to generate - -- the appropriate command line arguments for the call to the - -- system linker. The BEGIN/END lines are used for sentinels for - -- this parsing operation. - - -- The exact file names will of course depend on the environment, - -- host/target and location of files on the host system. - - -- BEGIN Object file/option list - -- ./hello.o - -- -L./ - -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/ - -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a - -- END Object file/option list - - end ada_main; - - The Ada code in the above example is exactly what is generated by the - binder. We have added comments to more clearly indicate the function of - each part of the generated `Ada_Main' package. - - The code is standard Ada in all respects, and can be processed by any - tools that handle Ada. In particular, it is possible to use the debugger - in Ada mode to debug the generated Ada_Main package. For example, - suppose that for reasons that you do not understand, your program is - blowing up during elaboration of the body of `Ada.Text_IO'. To chase - this bug down, you can place a breakpoint on the call: - - Ada.Text_Io'Elab_Body; - - and trace the elaboration routine for this package to find out where - the problem might be (more usually of course you would be debugging - elaboration code in your own application). - -  - File: gnat_ug_wnt.info, Node: Generating the Binder Program in C, Next: Consistency-Checking Modes, Prev: Running gnatbind, Up: Binding Using gnatbind - - Generating the Binder Program in C - ================================== - - In most normal usage, the default mode of `gnatbind' which is to - generate the main package in Ada, as described in the previous section. - In particular, this means that any Ada programmer can read and - understand the generated main program. It can also be debugged just - like any other Ada code provided the `-g' switch is used for `gnatbind' - and `gnatlink'. - - However for some purposes it may be convenient to generate the main - program in C rather than Ada. This may for example be helpful when you - are generating a mixed language program with the main program in C. The - GNAT compiler itself is an example. The use of the `-C' switch for both - `gnatbind' and `gnatlink' will cause the program to be generated in C - (and compiled using the gnu C compiler). The following shows the C code - generated for the same "Hello World" program: - - - #ifdef __STDC__ - #define PARAMS(paramlist) paramlist - #else - #define PARAMS(paramlist) () - #endif - - extern void __gnat_set_globals - PARAMS ((int, int, int, int, int, int, - void (*) PARAMS ((void)), int, int)); - extern void adafinal PARAMS ((void)); - extern void adainit PARAMS ((void)); - extern void system__standard_library__adafinal PARAMS ((void)); - extern int main PARAMS ((int, char **, char **)); - extern void exit PARAMS ((int)); - extern void __gnat_break_start PARAMS ((void)); - extern void _ada_hello PARAMS ((void)); - extern void __gnat_initialize PARAMS ((void)); - extern void __gnat_finalize PARAMS ((void)); - - extern void ada__exceptions___elabs PARAMS ((void)); - extern void system__exceptions___elabs PARAMS ((void)); - extern void interfaces__c_streams___elabs PARAMS ((void)); - extern void system__exception_table___elabb PARAMS ((void)); - extern void ada__io_exceptions___elabs PARAMS ((void)); - extern void system__stack_checking___elabs PARAMS ((void)); - extern void system__soft_links___elabb PARAMS ((void)); - extern void system__secondary_stack___elabb PARAMS ((void)); - extern void ada__tags___elabs PARAMS ((void)); - extern void ada__tags___elabb PARAMS ((void)); - extern void ada__streams___elabs PARAMS ((void)); - extern void system__finalization_root___elabs PARAMS ((void)); - extern void ada__exceptions___elabb PARAMS ((void)); - extern void system__finalization_implementation___elabs PARAMS ((void)); - extern void system__finalization_implementation___elabb PARAMS ((void)); - extern void ada__finalization___elabs PARAMS ((void)); - extern void ada__finalization__list_controller___elabs PARAMS ((void)); - extern void system__file_control_block___elabs PARAMS ((void)); - extern void system__file_io___elabb PARAMS ((void)); - extern void ada__text_io___elabs PARAMS ((void)); - extern void ada__text_io___elabb PARAMS ((void)); - - extern int __gnat_inside_elab_final_code; - - extern int gnat_argc; - extern char **gnat_argv; - extern char **gnat_envp; - extern int gnat_exit_status; - - char __gnat_version[] = "GNAT Version: 3.15w (20010315)"; - void adafinal () { - system__standard_library__adafinal (); - } - - void adainit () - { - extern char ada__exceptions_E; - extern char system__exceptions_E; - extern char interfaces__c_streams_E; - extern char system__exception_table_E; - extern char ada__io_exceptions_E; - extern char system__secondary_stack_E; - extern char system__stack_checking_E; - extern char system__soft_links_E; - extern char ada__tags_E; - extern char ada__streams_E; - extern char system__finalization_root_E; - extern char system__finalization_implementation_E; - extern char ada__finalization_E; - extern char ada__finalization__list_controller_E; - extern char system__file_control_block_E; - extern char system__file_io_E; - extern char ada__text_io_E; - - extern void *__gnat_hello__SDP; - extern void *__gnat_ada__text_io__SDP; - extern void *__gnat_ada__exceptions__SDP; - extern void *__gnat_gnat__heap_sort_a__SDP; - extern void *__gnat_system__exception_table__SDP; - extern void *__gnat_system__machine_state_operations__SDP; - extern void *__gnat_system__secondary_stack__SDP; - extern void *__gnat_system__parameters__SDP; - extern void *__gnat_system__soft_links__SDP; - extern void *__gnat_system__stack_checking__SDP; - extern void *__gnat_system__traceback__SDP; - extern void *__gnat_ada__streams__SDP; - extern void *__gnat_ada__tags__SDP; - extern void *__gnat_system__string_ops__SDP; - extern void *__gnat_interfaces__c_streams__SDP; - extern void *__gnat_system__file_io__SDP; - extern void *__gnat_ada__finalization__SDP; - extern void *__gnat_system__finalization_root__SDP; - extern void *__gnat_system__finalization_implementation__SDP; - extern void *__gnat_system__string_ops_concat_3__SDP; - extern void *__gnat_system__stream_attributes__SDP; - extern void *__gnat_system__file_control_block__SDP; - extern void *__gnat_ada__finalization__list_controller__SDP; - - void **st[23] = { - &__gnat_hello__SDP, - &__gnat_ada__text_io__SDP, - &__gnat_ada__exceptions__SDP, - &__gnat_gnat__heap_sort_a__SDP, - &__gnat_system__exception_table__SDP, - &__gnat_system__machine_state_operations__SDP, - &__gnat_system__secondary_stack__SDP, - &__gnat_system__parameters__SDP, - &__gnat_system__soft_links__SDP, - &__gnat_system__stack_checking__SDP, - &__gnat_system__traceback__SDP, - &__gnat_ada__streams__SDP, - &__gnat_ada__tags__SDP, - &__gnat_system__string_ops__SDP, - &__gnat_interfaces__c_streams__SDP, - &__gnat_system__file_io__SDP, - &__gnat_ada__finalization__SDP, - &__gnat_system__finalization_root__SDP, - &__gnat_system__finalization_implementation__SDP, - &__gnat_system__string_ops_concat_3__SDP, - &__gnat_system__stream_attributes__SDP, - &__gnat_system__file_control_block__SDP, - &__gnat_ada__finalization__list_controller__SDP}; - - extern void ada__exceptions___elabs (); - extern void system__exceptions___elabs (); - extern void interfaces__c_streams___elabs (); - extern void system__exception_table___elabb (); - extern void ada__io_exceptions___elabs (); - extern void system__stack_checking___elabs (); - extern void system__soft_links___elabb (); - extern void system__secondary_stack___elabb (); - extern void ada__tags___elabs (); - extern void ada__tags___elabb (); - extern void ada__streams___elabs (); - extern void system__finalization_root___elabs (); - extern void ada__exceptions___elabb (); - extern void system__finalization_implementation___elabs (); - extern void system__finalization_implementation___elabb (); - extern void ada__finalization___elabs (); - extern void ada__finalization__list_controller___elabs (); - extern void system__file_control_block___elabs (); - extern void system__file_io___elabb (); - extern void ada__text_io___elabs (); - extern void ada__text_io___elabb (); - - void (*ea[23]) () = { - adainit, - system__standard_library__adafinal, - ada__exceptions___elabs, - system__exceptions___elabs, - interfaces__c_streams___elabs, - system__exception_table___elabb, - ada__io_exceptions___elabs, - system__stack_checking___elabs, - system__soft_links___elabb, - system__secondary_stack___elabb, - ada__tags___elabs, - ada__tags___elabb, - ada__streams___elabs, - system__finalization_root___elabs, - ada__exceptions___elabb, - system__finalization_implementation___elabs, - system__finalization_implementation___elabb, - ada__finalization___elabs, - ada__finalization__list_controller___elabs, - system__file_control_block___elabs, - system__file_io___elabb, - ada__text_io___elabs, - ada__text_io___elabb}; - - __gnat_SDP_Table_Build (&st, 23, ea, 23); - __gnat_set_globals ( - -1, /* Main_Priority */ - -1, /* Time_Slice_Value */ - 'b', /* WC_Encoding */ - ' ', /* Locking_Policy */ - ' ', /* Queuing_Policy */ - ' ', /* Tasking_Dispatching_Policy */ - 0, /* Finalization routine address, not used anymore */ - 0, /* Unreserve_All_Interrupts */ - 0); /* Exception_Tracebacks */ - - __gnat_inside_elab_final_code = 1; - - if (ada__exceptions_E == 0) { - ada__exceptions___elabs (); - } - if (system__exceptions_E == 0) { - system__exceptions___elabs (); - system__exceptions_E++; - } - if (interfaces__c_streams_E == 0) { - interfaces__c_streams___elabs (); - } - interfaces__c_streams_E = 1; - if (system__exception_table_E == 0) { - system__exception_table___elabb (); - system__exception_table_E++; - } - if (ada__io_exceptions_E == 0) { - ada__io_exceptions___elabs (); - ada__io_exceptions_E++; - } - if (system__stack_checking_E == 0) { - system__stack_checking___elabs (); - } - if (system__soft_links_E == 0) { - system__soft_links___elabb (); - system__soft_links_E++; - } - system__stack_checking_E = 1; - if (system__secondary_stack_E == 0) { - system__secondary_stack___elabb (); - system__secondary_stack_E++; - } - if (ada__tags_E == 0) { - ada__tags___elabs (); - } - if (ada__tags_E == 0) { - ada__tags___elabb (); - ada__tags_E++; - } - if (ada__streams_E == 0) { - ada__streams___elabs (); - ada__streams_E++; - } - if (system__finalization_root_E == 0) { - system__finalization_root___elabs (); - } - system__finalization_root_E = 1; - if (ada__exceptions_E == 0) { - ada__exceptions___elabb (); - ada__exceptions_E++; - } - if (system__finalization_implementation_E == 0) { - system__finalization_implementation___elabs (); - } - if (system__finalization_implementation_E == 0) { - system__finalization_implementation___elabb (); - system__finalization_implementation_E++; - } - if (ada__finalization_E == 0) { - ada__finalization___elabs (); - } - ada__finalization_E = 1; - if (ada__finalization__list_controller_E == 0) { - ada__finalization__list_controller___elabs (); - } - ada__finalization__list_controller_E = 1; - if (system__file_control_block_E == 0) { - system__file_control_block___elabs (); - system__file_control_block_E++; - } - if (system__file_io_E == 0) { - system__file_io___elabb (); - system__file_io_E++; - } - if (ada__text_io_E == 0) { - ada__text_io___elabs (); - } - if (ada__text_io_E == 0) { - ada__text_io___elabb (); - ada__text_io_E++; - } - - __gnat_inside_elab_final_code = 0; - } - int main (argc, argv, envp) - int argc; - char **argv; - char **envp; - { - gnat_argc = argc; - gnat_argv = argv; - gnat_envp = envp; - - __gnat_initialize (); - adainit (); - __gnat_break_start (); - - _ada_hello (); - - system__standard_library__adafinal (); - __gnat_finalize (); - exit (gnat_exit_status); - } - unsigned helloB = 0x7880BEB3; - unsigned system__standard_libraryB = 0x0D24CBD0; - unsigned system__standard_libraryS = 0x3283DBEB; - unsigned adaS = 0x2359F9ED; - unsigned ada__text_ioB = 0x47C85FC4; - unsigned ada__text_ioS = 0x496FE45C; - unsigned ada__exceptionsB = 0x74F50187; - unsigned ada__exceptionsS = 0x6736945B; - unsigned gnatS = 0x156A40CF; - unsigned gnat__heap_sort_aB = 0x033DABE0; - unsigned gnat__heap_sort_aS = 0x6AB38FEA; - unsigned systemS = 0x0331C6FE; - unsigned system__exceptionsS = 0x20C9ECA4; - unsigned system__exception_tableB = 0x68A22947; - unsigned system__exception_tableS = 0x394BADD5; - unsigned gnat__htableB = 0x08258E1B; - unsigned gnat__htableS = 0x367D5222; - unsigned system__machine_state_operationsB = 0x4F3B7492; - unsigned system__machine_state_operationsS = 0x182F5CF4; - unsigned system__storage_elementsB = 0x2F1EB794; - unsigned system__storage_elementsS = 0x102C83C7; - unsigned system__secondary_stackB = 0x1574B6E9; - unsigned system__secondary_stackS = 0x708E260A; - unsigned system__parametersB = 0x56D770CD; - unsigned system__parametersS = 0x237E39BE; - unsigned system__soft_linksB = 0x08AB6B2C; - unsigned system__soft_linksS = 0x1E2491F3; - unsigned system__stack_checkingB = 0x476457A0; - unsigned system__stack_checkingS = 0x5299FCED; - unsigned system__tracebackB = 0x2971EBDE; - unsigned system__tracebackS = 0x2E9C3122; - unsigned ada__streamsS = 0x7C25DE96; - unsigned ada__tagsB = 0x39ADFFA2; - unsigned ada__tagsS = 0x769A0464; - unsigned system__string_opsB = 0x5EB646AB; - unsigned system__string_opsS = 0x63CED018; - unsigned interfacesS = 0x0357E00A; - unsigned interfaces__c_streamsB = 0x3784FB72; - unsigned interfaces__c_streamsS = 0x2E723019; - unsigned system__file_ioB = 0x623358EA; - unsigned system__file_ioS = 0x31F873E6; - unsigned ada__finalizationB = 0x6843F68A; - unsigned ada__finalizationS = 0x63305874; - unsigned system__finalization_rootB = 0x31E56CE1; - unsigned system__finalization_rootS = 0x23169EF3; - unsigned system__finalization_implementationB = 0x6CCBA70E; - unsigned system__finalization_implementationS = 0x604AA587; - unsigned system__string_ops_concat_3B = 0x572E3F58; - unsigned system__string_ops_concat_3S = 0x01F57876; - unsigned system__stream_attributesB = 0x1D4F93E8; - unsigned system__stream_attributesS = 0x30B2EC3D; - unsigned ada__io_exceptionsS = 0x34054F96; - unsigned system__unsigned_typesS = 0x7B9E7FE3; - unsigned system__file_control_blockS = 0x2FF876A8; - unsigned ada__finalization__list_controllerB = 0x5760634A; - unsigned ada__finalization__list_controllerS = 0x5D851835; - - /* BEGIN ELABORATION ORDER - ada (spec) - gnat (spec) - gnat.heap_sort_a (spec) - gnat.htable (spec) - gnat.htable (body) - interfaces (spec) - system (spec) - system.parameters (spec) - system.standard_library (spec) - ada.exceptions (spec) - system.exceptions (spec) - system.parameters (body) - gnat.heap_sort_a (body) - interfaces.c_streams (spec) - interfaces.c_streams (body) - system.exception_table (spec) - system.exception_table (body) - ada.io_exceptions (spec) - system.storage_elements (spec) - system.storage_elements (body) - system.machine_state_operations (spec) - system.machine_state_operations (body) - system.secondary_stack (spec) - system.stack_checking (spec) - system.soft_links (spec) - system.soft_links (body) - system.stack_checking (body) - system.secondary_stack (body) - system.standard_library (body) - system.string_ops (spec) - system.string_ops (body) - ada.tags (spec) - ada.tags (body) - ada.streams (spec) - system.finalization_root (spec) - system.finalization_root (body) - system.string_ops_concat_3 (spec) - system.string_ops_concat_3 (body) - system.traceback (spec) - system.traceback (body) - ada.exceptions (body) - system.unsigned_types (spec) - system.stream_attributes (spec) - system.stream_attributes (body) - system.finalization_implementation (spec) - system.finalization_implementation (body) - ada.finalization (spec) - ada.finalization (body) - ada.finalization.list_controller (spec) - ada.finalization.list_controller (body) - system.file_control_block (spec) - system.file_io (spec) - system.file_io (body) - ada.text_io (spec) - ada.text_io (body) - hello (body) - END ELABORATION ORDER */ - - /* BEGIN Object file/option list - ./hello.o - -L./ - -L/usr/local/gnat/lib/gcc-lib/alpha-dec-osf5.1/2.8.1/adalib/ - /usr/local/gnat/lib/gcc-lib/alpha-dec-osf5.1/2.8.1/adalib/libgnat.a - -lexc - END Object file/option list */ - - Here again, the C code is exactly what is generated by the binder. The - functions of the various parts of this code correspond in an obvious - manner with the commented Ada code shown in the example in the previous - section. - -  - File: gnat_ug_wnt.info, Node: Consistency-Checking Modes, Next: Binder Error Message Control, Prev: Generating the Binder Program in C, Up: Binding Using gnatbind - - Consistency-Checking Modes - ========================== - - As described in the previous section, by default `gnatbind' checks that - object files are consistent with one another and are consistent with - any source files it can locate. The following switches control binder - access to sources. - - `-s' - Require source files to be present. In this mode, the binder must - be able to locate all source files that are referenced, in order - to check their consistency. In normal mode, if a source file - cannot be located it is simply ignored. If you specify this - switch, a missing source file is an error. - - `-x' - Exclude source files. In this mode, the binder only checks that ALI - files are consistent with one another. Source files are not - accessed. The binder runs faster in this mode, and there is still - a guarantee that the resulting program is self-consistent. If a - source file has been edited since it was last compiled, and you - specify this switch, the binder will not detect that the object - file is out of date with respect to the source file. Note that - this is the mode that is automatically used by `gnatmake' because - in this case the checking against sources has already been - performed by `gnatmake' in the course of compilation (i.e. before - binding). - -  - File: gnat_ug_wnt.info, Node: Binder Error Message Control, Next: Elaboration Control, Prev: Consistency-Checking Modes, Up: Binding Using gnatbind - - Binder Error Message Control - ============================ - - The following switches provide control over the generation of error - messages from the binder: - - `-v' - Verbose mode. In the normal mode, brief error messages are - generated to `stderr'. If this switch is present, a header is - written to `stdout' and any error messages are directed to - `stdout'. All that is written to `stderr' is a brief summary - message. - - `-b' - Generate brief error messages to `stderr' even if verbose mode is - specified. This is relevant only when used with the `-v' switch. - - `-mN' - Limits the number of error messages to N, a decimal integer in the - range 1-999. The binder terminates immediately if this limit is - reached. - - `-MXXX' - Renames the generated main program from `main' to `xxx'. This is - useful in the case of some cross-building environments, where the - actual main program is separate from the one generated by - `gnatbind'. - - `-ws' - Suppress all warning messages. - - `-we' - Treat any warning messages as fatal errors. - - `-t' - The binder performs a number of consistency checks including: - - * Check that time stamps of a given source unit are consistent - - * Check that checksums of a given source unit are consistent - - * Check that consistent versions of `GNAT' were used for - compilation - - * Check consistency of configuration pragmas as required - - Normally failure of such checks, in accordance with the consistency - requirements of the Ada Reference Manual, causes error messages to - be generated which abort the binder and prevent the output of a - binder file and subsequent link to obtain an executable. - - The `-t' switch converts these error messages into warnings, so - that binding and linking can continue to completion even in the - presence of such errors. The result may be a failed link (due to - missing symbols), or a non-functional executable which has - undefined semantics. _This means that `-t' should be used only in - unusual situations, with extreme care._ - -  - File: gnat_ug_wnt.info, Node: Elaboration Control, Next: Output Control, Prev: Binder Error Message Control, Up: Binding Using gnatbind - - Elaboration Control - =================== - - The following switches provide additional control over the elaboration - order. For full details see *Note Elaboration Order Handling in GNAT::. - - `-p' - Normally the binder attempts to choose an elaboration order that is - likely to minimize the likelihood of an elaboration order error - resulting in raising a `Program_Error' exception. This switch - reverses the action of the binder, and requests that it - deliberately choose an order that is likely to maximize the - likelihood of an elaboration error. This is useful in ensuring - portability and avoiding dependence on accidental fortuitous - elaboration ordering. - - Normally it only makes sense to use the `-p' switch if dynamic - elaboration checking is used (`-gnatE' switch used for - compilation). This is because in the default static elaboration - mode, all necessary `Elaborate_All' pragmas are implicitly - inserted. These implicit pragmas are still respected by the binder - in `-p' mode, so a safe elaboration order is assured. - -  - File: gnat_ug_wnt.info, Node: Output Control, Next: Binding with Non-Ada Main Programs, Prev: Elaboration Control, Up: Binding Using gnatbind - - Output Control - ============== - - The following switches allow additional control over the output - generated by the binder. - - `-A' - Generate binder program in Ada (default). The binder program is - named `b~MAINPROG.adb' by default. This can be changed with `-o' - `gnatbind' option. - - `-c' - Check only. Do not generate the binder output file. In this mode - the binder performs all error checks but does not generate an - output file. - - `-C' - Generate binder program in C. The binder program is named - `b_MAINPROG.c'. This can be changed with `-o' `gnatbind' option. - - `-e' - Output complete list of elaboration-order dependencies, showing the - reason for each dependency. This output can be rather extensive - but may be useful in diagnosing problems with elaboration order. - The output is written to `stdout'. - - `-h' - Output usage information. The output is written to `stdout'. - - `-K' - Output linker options to `stdout'. Includes library search paths, - contents of pragmas Ident and Linker_Options, and libraries added - by `gnatbind'. - - `-l' - Output chosen elaboration order. The output is written to `stdout'. - - `-O' - Output full names of all the object files that must be linked to - provide the Ada component of the program. The output is written to - `stdout'. This list includes the files explicitly supplied and - referenced by the user as well as implicitly referenced run-time - unit files. The latter are omitted if the corresponding units - reside in shared libraries. The directory names for the run-time - units depend on the system configuration. - - `-o FILE' - Set name of output file to FILE instead of the normal - `b~MAINPROG.adb' default. Note that FILE denote the Ada binder - generated body filename. In C mode you would normally give FILE an - extension of `.c' because it will be a C source program. Note - that if this option is used, then linking must be done manually. - It is not possible to use gnatlink in this case, since it cannot - locate the binder file. - - `-r' - Generate list of `pragma Rerstrictions' that could be applied to - the current unit. This is useful for code audit purposes, and also - may be used to improve code generation in some cases. - -  - File: gnat_ug_wnt.info, Node: Binding with Non-Ada Main Programs, Next: Binding Programs with No Main Subprogram, Prev: Output Control, Up: Binding Using gnatbind - - Binding with Non-Ada Main Programs - ================================== - - In our description so far we have assumed that the main program is in - Ada, and that the task of the binder is to generate a corresponding - function `main' that invokes this Ada main program. GNAT also supports - the building of executable programs where the main program is not in - Ada, but some of the called routines are written in Ada and compiled - using GNAT (*note Mixed Language Programming::). The following switch - is used in this situation: - - `-n' - No main program. The main program is not in Ada. - - In this case, most of the functions of the binder are still required, - but instead of generating a main program, the binder generates a file - containing the following callable routines: - - `adainit' - You must call this routine to initialize the Ada part of the - program by calling the necessary elaboration routines. A call to - `adainit' is required before the first call to an Ada subprogram. - - Note that it is assumed that the basic execution environment must - be setup to be appropriate for Ada execution at the point where - the first Ada subprogram is called. In particular, if the Ada code - will do any floating-point operations, then the FPU must be setup - in an appropriate manner. For the case of the x86, for example, - full precision mode is required. The procedure - GNAT.Float_Control.Reset may be used to ensure that the FPU is in - the right state. - - `adafinal' - You must call this routine to perform any library-level - finalization required by the Ada subprograms. A call to `adafinal' - is required after the last call to an Ada subprogram, and before - the program terminates. - - If the `-n' switch is given, more than one ALI file may appear on the - command line for `gnatbind'. The normal "closure" calculation is - performed for each of the specified units. Calculating the closure - means finding out the set of units involved by tracing `with' - references. The reason it is necessary to be able to specify more than - one ALI file is that a given program may invoke two or more quite - separate groups of Ada units. - - The binder takes the name of its output file from the last specified - ALI file, unless overridden by the use of the `-o file'. The output is - an Ada unit in source form that can be compiled with GNAT unless the -C - switch is used in which case the output is a C source file, which must - be compiled using the C compiler. This compilation occurs - automatically as part of the `gnatlink' processing. - - Currently the GNAT run time requires a FPU using 80 bits mode - precision. Under targets where this is not the default it is required to - call GNAT.Float_Control.Reset before using floating point numbers (this - include float computation, float input and output) in the Ada code. A - side effect is that this could be the wrong mode for the foreign code - where floating point computation could be broken after this call. - -  - File: gnat_ug_wnt.info, Node: Binding Programs with No Main Subprogram, Next: Summary of Binder Switches, Prev: Binding with Non-Ada Main Programs, Up: Binding Using gnatbind - - Binding Programs with No Main Subprogram - ======================================== - - It is possible to have an Ada program which does not have a main - subprogram. This program will call the elaboration routines of all the - packages, then the finalization routines. - - The following switch is used to bind programs organized in this - manner: - - `-z' - Normally the binder checks that the unit name given on the command - line corresponds to a suitable main subprogram. When this switch - is used, a list of ALI files can be given, and the execution of - the program consists of elaboration of these units in an - appropriate order. - -  - File: gnat_ug_wnt.info, Node: Summary of Binder Switches, Next: Command-Line Access, Prev: Binding Programs with No Main Subprogram, Up: Binding Using gnatbind - - Summary of Binder Switches - ========================== - - The following are the switches available with `gnatbind': - - `-aO' - Specify directory to be searched for ALI files. - - `-aI' - Specify directory to be searched for source file. - - `-A' - Generate binder program in Ada (default) - - `-b' - Generate brief messages to `stderr' even if verbose mode set. - - `-c' - Check only, no generation of binder output file. - - `-C' - Generate binder program in C - - `-e' - Output complete list of elaboration-order dependencies. - - `-E' - Store tracebacks in exception occurrences when the target supports - it. This is the default with the zero cost exception mechanism. - This option is currently supported on the following targets: all - x86 ports, Solaris, Windows, HP-UX, AIX, PowerPC VxWorks and Alpha - VxWorks. See also the packages `GNAT.Traceback' and - `GNAT.Traceback.Symbolic' for more information. Note that on x86 - ports, you must not use `-fomit-frame-pointer' `gcc' option. - - `-h' - Output usage (help) information - - `-I' - Specify directory to be searched for source and ALI files. - - `-I-' - Do not look for sources in the current directory where `gnatbind' - was invoked, and do not look for ALI files in the directory - containing the ALI file named in the `gnatbind' command line. - - `-l' - Output chosen elaboration order. - - `-Lxxx' - Binds the units for library building. In this case the adainit and - adafinal procedures (See *note Binding with Non-Ada Main - Programs::) are renamed to xxxinit and xxxfinal. Implies -n. See - *note GNAT and Libraries:: for more details. - - `-Mxyz' - Rename generated main program from main to xyz - - `-mN' - Limit number of detected errors to N (1-999). Furthermore, under - Windows, the sources pointed to by the libraries path set in the - registry are not searched for. - - `-n' - No main program. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-o FILE' - Name the output file FILE (default is `b~XXX.adb'). Note that if - this option is used, then linking must be done manually, gnatlink - cannot be used. - - `-O' - Output object list. - - `-p' - Pessimistic (worst-case) elaboration order - - `-s' - Require all source files to be present. - - `-static' - Link against a static GNAT run time. - - `-shared' - Link against a shared GNAT run time when available. - - `-t' - Tolerate time stamp and other consistency errors - - `-TN' - Set the time slice value to n microseconds. A value of zero means - no time slicing and also indicates to the tasking run time to - match as close as possible to the annex D requirements of the RM. - - `-v' - Verbose mode. Write error messages, header, summary output to - `stdout'. - - `-wX' - Warning mode (X=s/e for suppress/treat as error) - - `-x' - Exclude source files (check object consistency only). - - `-z' - No main subprogram. - - You may obtain this listing by running the program `gnatbind' with - no arguments. - -  - File: gnat_ug_wnt.info, Node: Command-Line Access, Next: Search Paths for gnatbind, Prev: Summary of Binder Switches, Up: Binding Using gnatbind - - Command-Line Access - =================== - - The package `Ada.Command_Line' provides access to the command-line - arguments and program name. In order for this interface to operate - correctly, the two variables - - int gnat_argc; - char **gnat_argv; - - are declared in one of the GNAT library routines. These variables must - be set from the actual `argc' and `argv' values passed to the main - program. With no `n' present, `gnatbind' generates the C main program - to automatically set these variables. If the `n' switch is used, there - is no automatic way to set these variables. If they are not set, the - procedures in `Ada.Command_Line' will not be available, and any attempt - to use them will raise `Constraint_Error'. If command line access is - required, your main program must set `gnat_argc' and `gnat_argv' from - the `argc' and `argv' values passed to it. - -  - File: gnat_ug_wnt.info, Node: Search Paths for gnatbind, Next: Examples of gnatbind Usage, Prev: Command-Line Access, Up: Binding Using gnatbind - - Search Paths for `gnatbind' - =========================== - - The binder takes the name of an ALI file as its argument and needs to - locate source files as well as other ALI files to verify object - consistency. - - For source files, it follows exactly the same search rules as `gcc' - (*note Search Paths and the Run-Time Library (RTL)::). For ALI files the - directories searched are: - - 1. The directory containing the ALI file named in the command line, - unless the switch `-I-' is specified. - - 2. All directories specified by `-I' switches on the `gnatbind' - command line, in the order given. - - 3. Each of the directories listed in the value of the - `ADA_OBJECTS_PATH' environment variable. Construct this value - exactly as the `PATH' environment variable: a list of directory - names separated by colons (semicolons when working with the NT - version of GNAT). - - 4. The content of the "ada_object_path" file which is part of the GNAT - installation tree and is used to store standard libraries such as - the GNAT Run Time Library (RTL) unless the switch `-nostdlib' is - specified. *Note Installing an Ada Library:: - - In the binder the switch `-I' is used to specify both source and - library file paths. Use `-aI' instead if you want to specify source - paths only, and `-aO' if you want to specify library paths only. This - means that for the binder `-I'DIR is equivalent to `-aI'DIR `-aO'DIR. - The binder generates the bind file (a C language source file) in the - current working directory. - - The packages `Ada', `System', and `Interfaces' and their children - make up the GNAT Run-Time Library, together with the package GNAT and - its children, which contain a set of useful additional library - functions provided by GNAT. The sources for these units are needed by - the compiler and are kept together in one directory. The ALI files and - object files generated by compiling the RTL are needed by the binder - and the linker and are kept together in one directory, typically - different from the directory containing the sources. In a normal - installation, you need not specify these directory names when compiling - or binding. Either the environment variables or the built-in defaults - cause these files to be found. - - Besides simplifying access to the RTL, a major use of search paths is - in compiling sources from multiple directories. This can make - development environments much more flexible. - -  - File: gnat_ug_wnt.info, Node: Examples of gnatbind Usage, Prev: Search Paths for gnatbind, Up: Binding Using gnatbind - - Examples of `gnatbind' Usage - ============================ - - This section contains a number of examples of using the GNAT binding - utility `gnatbind'. - - `gnatbind hello' - The main program `Hello' (source program in `hello.adb') is bound - using the standard switch settings. The generated main program is - `b~hello.adb'. This is the normal, default use of the binder. - - `gnatbind hello -o mainprog.adb' - The main program `Hello' (source program in `hello.adb') is bound - using the standard switch settings. The generated main program is - `mainprog.adb' with the associated spec in `mainprog.ads'. Note - that you must specify the body here not the spec, in the case - where the output is in Ada. Note that if this option is used, then - linking must be done manually, since gnatlink will not be able to - find the generated file. - - `gnatbind main -C -o mainprog.c -x' - The main program `Main' (source program in `main.adb') is bound, - excluding source files from the consistency checking, generating - the file `mainprog.c'. - - `gnatbind -x main_program -C -o mainprog.c' - This command is exactly the same as the previous example. Switches - may appear anywhere in the command line, and single letter - switches may be combined into a single switch. - - `gnatbind -n math dbase -C -o ada-control.c' - The main program is in a language other than Ada, but calls to - subprograms in packages `Math' and `Dbase' appear. This call to - `gnatbind' generates the file `ada-control.c' containing the - `adainit' and `adafinal' routines to be called before and after - accessing the Ada units. - -  - File: gnat_ug_wnt.info, Node: Linking Using gnatlink, Next: The GNAT Make Program gnatmake, Prev: Binding Using gnatbind, Up: Top - - Linking Using `gnatlink' - ************************ - - This chapter discusses `gnatlink', a utility program used to link Ada - programs and build an executable file. This is a simple program that - invokes the Unix linker (via the `gcc' command) with a correct list of - object files and library references. `gnatlink' automatically - determines the list of files and references for the Ada part of a - program. It uses the binder file generated by the binder to determine - this list. - - * Menu: - - * Running gnatlink:: - * Switches for gnatlink:: - * Setting Stack Size from gnatlink:: - * Setting Heap Size from gnatlink:: - -  - File: gnat_ug_wnt.info, Node: Running gnatlink, Next: Switches for gnatlink, Up: Linking Using gnatlink - - Running `gnatlink' - ================== - - The form of the `gnatlink' command is - - $ gnatlink [SWITCHES] MAINPROG[.ali] [NON-ADA OBJECTS] - [LINKER OPTIONS] - - `MAINPROG.ali' references the ALI file of the main program. The `.ali' - extension of this file can be omitted. From this reference, `gnatlink' - locates the corresponding binder file `b~MAINPROG.adb' and, using the - information in this file along with the list of non-Ada objects and - linker options, constructs a Unix linker command file to create the - executable. - - The arguments following `MAINPROG.ali' are passed to the linker - uninterpreted. They typically include the names of object files for - units written in other languages than Ada and any library references - required to resolve references in any of these foreign language units, - or in `pragma Import' statements in any Ada units. - - LINKER OPTIONS is an optional list of linker specific switches. The - default linker called by gnatlink is GCC which in turn calls the - appropriate system linker usually called LD. Standard options for the - linker such as `-lmy_lib' or `-Ldir' can be added as is. For options - that are not recognized by GCC as linker options, the GCC switches - `-Xlinker' or `-Wl,' shall be used. Refer to the GCC documentation for - details. Here is an example showing how to generate a linker map - assuming that the underlying linker is GNU ld: - - $ gnatlink my_prog -Wl,-Map,MAPFILE - - Using LINKER OPTIONS it is possible to set the program stack and - heap size. See *note Setting Stack Size from gnatlink:: and *note - Setting Heap Size from gnatlink::. - - `gnatlink' determines the list of objects required by the Ada - program and prepends them to the list of objects passed to the linker. - `gnatlink' also gathers any arguments set by the use of `pragma - Linker_Options' and adds them to the list of arguments presented to the - linker. - -  - File: gnat_ug_wnt.info, Node: Switches for gnatlink, Next: Setting Stack Size from gnatlink, Prev: Running gnatlink, Up: Linking Using gnatlink - - Switches for `gnatlink' - ======================= - - The following switches are available with the `gnatlink' utility: - - `-A' - The binder has generated code in Ada. This is the default. - - `-C' - If instead of generating a file in Ada, the binder has generated - one in C, then the linker needs to know about it. Use this switch - to signal to `gnatlink' that the binder has generated C code - rather than Ada code. - - `-f' - On some targets, the command line length is limited, and `gnatlink' - will generate a separate file for the linker if the list of object - files is too long. The `-f' flag forces this file to be generated - even if the limit is not exceeded. This is useful in some cases to - deal with special situations where the command line length is - exceeded. - - `-g' - The option to include debugging information causes the Ada bind - file (in other words, `b~MAINPROG.adb') to be compiled with `-g'. - In addition, the binder does not delete the `b~MAINPROG.adb', - `b~MAINPROG.o' and `b~MAINPROG.ali' files. Without `-g', the - binder removes these files by default. The same procedure apply if - a C bind file was generated using `-C' `gnatbind' option, in this - case the filenames are `b_MAINPROG.c' and `b_MAINPROG.o'. - - `-n' - Do not compile the file generated by the binder. This may be used - when a link is rerun with different options, but there is no need - to recompile the binder file. - - `-v' - Causes additional information to be output, including a full list - of the included object files. This switch option is most useful - when you want to see what set of object files are being used in - the link step. - - `-v -v' - Very verbose mode. Requests that the compiler operate in verbose - mode when it compiles the binder file, and that the system linker - run in verbose mode. - - `-o EXEC-NAME' - EXEC-NAME specifies an alternate name for the generated executable - program. If this switch is omitted, the executable has the same - name as the main unit. For example, `gnatlink try.ali' creates an - executable called `try'. - - `-b TARGET' - Compile your program to run on TARGET, which is the name of a - system configuration. You must have a GNAT cross-compiler built if - TARGET is not the same as your host system. - - `-BDIR' - Load compiler executables (for example, `gnat1', the Ada compiler) - from DIR instead of the default location. Only use this switch - when multiple versions of the GNAT compiler are available. See the - `gcc' manual page for further details. You would normally use the - `-b' or `-V' switch instead. - - `--GCC=COMPILER_NAME' - Program used for compiling the binder file. The default is - ``gcc''. You need to use quotes around COMPILER_NAME if - `compiler_name' contains spaces or other separator characters. As - an example `--GCC="foo -x -y"' will instruct `gnatlink' to use - `foo -x -y' as your compiler. Note that switch `-c' is always - inserted after your command name. Thus in the above example the - compiler command that will be used by `gnatlink' will be `foo -c - -x -y'. If several `--GCC=compiler_name' are used, only the last - COMPILER_NAME is taken into account. However, all the additional - switches are also taken into account. Thus, `--GCC="foo -x -y" - --GCC="bar -z -t"' is equivalent to `--GCC="bar -x -y -z -t"'. - - `--LINK=NAME' - NAME is the name of the linker to be invoked. This is especially - useful in mixed language programs since languages such as c++ - require their own linker to be used. When this switch is omitted, - the default name for the linker is (`gcc'). When this switch is - used, the specified linker is called instead of (`gcc') with - exactly the same parameters that would have been passed to (`gcc') - so if the desired linker requires different parameters it is - necessary to use a wrapper script that massages the parameters - before invoking the real linker. It may be useful to control the - exact invocation by using the verbose switch. - -  - File: gnat_ug_wnt.info, Node: Setting Stack Size from gnatlink, Next: Setting Heap Size from gnatlink, Prev: Switches for gnatlink, Up: Linking Using gnatlink - - Setting Stack Size from `gnatlink' - ================================== - - It is possible to specify the program stack size from `gnatlink'. - Assuming that the underlying linker is GNU ld there is two ways to do - so: - - * using `-Xlinker' linker option - - $ gnatlink hello -Xlinker --stack=0x10000,0x1000 - - This set the stack reserve size to 0x10000 bytes and the stack - commit size to 0x1000 bytes. - - * using `-Wl' linker option - - $ gnatlink hello -Wl,--stack=0x1000000 - - This set the stack reserve size to 0x1000000 bytes. Note that with - `-Wl' option it is not possible to set the stack commit size - because the coma is a separator for this option. - - -  - File: gnat_ug_wnt.info, Node: Setting Heap Size from gnatlink, Prev: Setting Stack Size from gnatlink, Up: Linking Using gnatlink - - Setting Heap Size from `gnatlink' - ================================= - - It is possible to specify the program heap size from `gnatlink'. - Assuming that the underlying linker is GNU ld there is two ways to do - so: - - * using `-Xlinker' linker option - - $ gnatlink hello -Xlinker --heap=0x10000,0x1000 - - This set the heap reserve size to 0x10000 bytes and the heap commit - size to 0x1000 bytes. - - * using `-Wl' linker option - - $ gnatlink hello -Wl,--heap=0x1000000 - - This set the heap reserve size to 0x1000000 bytes. Note that with - `-Wl' option it is not possible to set the heap commit size - because the coma is a separator for this option. - - -  - File: gnat_ug_wnt.info, Node: The GNAT Make Program gnatmake, Next: Renaming Files Using gnatchop, Prev: Linking Using gnatlink, Up: Top - - The GNAT Make Program `gnatmake' - ******************************** - - * Menu: - - * Running gnatmake:: - * Switches for gnatmake:: - * Mode Switches for gnatmake:: - * Notes on the Command Line:: - * How gnatmake Works:: - * Examples of gnatmake Usage:: - - A typical development cycle when working on an Ada program consists of - the following steps: - - 1. Edit some sources to fix bugs. - - 2. Add enhancements. - - 3. Compile all sources affected. - - 4. Rebind and relink. - - 5. Test. - - The third step can be tricky, because not only do the modified files - have to be compiled, but any files depending on these files must also be - recompiled. The dependency rules in Ada can be quite complex, especially - in the presence of overloading, `use' clauses, generics and inlined - subprograms. - - `gnatmake' automatically takes care of the third and fourth steps of - this process. It determines which sources need to be compiled, compiles - them, and binds and links the resulting object files. - - Unlike some other Ada make programs, the dependencies are always - accurately recomputed from the new sources. The source based approach of - the GNAT compilation model makes this possible. This means that if - changes to the source program cause corresponding changes in - dependencies, they will always be tracked exactly correctly by - `gnatmake'. - -  - File: gnat_ug_wnt.info, Node: Running gnatmake, Next: Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Running `gnatmake' - ================== - - The usual form of the `gnatmake' command is - - $ gnatmake [SWITCHES] FILE_NAME [FILE_NAMES] [MODE_SWITCHES] - - The only required argument is one FILE_NAME, which specifies a - compilation unit that is a main program. Several FILE_NAMES can be - specified: this will result in several executables being built. If - `switches' are present, they can be placed before the first FILE_NAME, - between FILE_NAMES or after the last FILE_NAME. If MODE_SWITCHES are - present, they must always be placed after the last FILE_NAME and all - `switches'. - - If you are using standard file extensions (.adb and .ads), then the - extension may be omitted from the FILE_NAME arguments. However, if you - are using non-standard extensions, then it is required that the - extension be given. A relative or absolute directory path can be - specified in a FILE_NAME, in which case, the input source file will be - searched for in the specified directory only. Otherwise, the input - source file will first be searched in the directory where `gnatmake' - was invoked and if it is not found, it will be search on the source - path of the compiler as described in *Note Search Paths and the - Run-Time Library (RTL)::. - - When several FILE_NAMES are specified, if an executable needs to be - rebuilt and relinked, all subsequent executables will be rebuilt and - relinked, even if this would not be absolutely necessary. - - All `gnatmake' output (except when you specify `-M') is to `stderr'. - The output produced by the `-M' switch is send to `stdout'. - -  - File: gnat_ug_wnt.info, Node: Switches for gnatmake, Next: Mode Switches for gnatmake, Prev: Running gnatmake, Up: The GNAT Make Program gnatmake - - Switches for `gnatmake' - ======================= - - You may specify any of the following switches to `gnatmake': - - `--GCC=COMPILER_NAME' - Program used for compiling. The default is ``gcc''. You need to use - quotes around COMPILER_NAME if `compiler_name' contains spaces or - other separator characters. As an example `--GCC="foo -x -y"' will - instruct `gnatmake' to use `foo -x -y' as your compiler. Note that - switch `-c' is always inserted after your command name. Thus in - the above example the compiler command that will be used by - `gnatmake' will be `foo -c -x -y'. If several - `--GCC=compiler_name' are used, only the last COMPILER_NAME is - taken into account. However, all the additional switches are also - taken into account. Thus, `--GCC="foo -x -y" --GCC="bar -z -t"' is - equivalent to `--GCC="bar -x -y -z -t"'. - - `--GNATBIND=BINDER_NAME' - Program used for binding. The default is ``gnatbind''. You need to - use quotes around BINDER_NAME if BINDER_NAME contains spaces or - other separator characters. As an example `--GNATBIND="bar -x -y"' - will instruct `gnatmake' to use `bar -x -y' as your binder. Binder - switches that are normally appended by `gnatmake' to ``gnatbind'' - are now appended to the end of `bar -x -y'. - - `--GNATLINK=LINKER_NAME' - Program used for linking. The default is ``gnatlink''. You need to - use quotes around LINKER_NAME if LINKER_NAME contains spaces or - other separator characters. As an example `--GNATLINK="lan -x -y"' - will instruct `gnatmake' to use `lan -x -y' as your linker. Linker - switches that are normally appended by `gnatmake' to ``gnatlink'' - are now appended to the end of `lan -x -y'. - - `-a' - Consider all files in the make process, even the GNAT internal - system files (for example, the predefined Ada library files), as - well as any locked files. Locked files are files whose ALI file is - write-protected. By default, `gnatmake' does not check these - files, because the assumption is that the GNAT internal files are - properly up to date, and also that any write protected ALI files - have been properly installed. Note that if there is an - installation problem, such that one of these files is not up to - date, it will be properly caught by the binder. You may have to - specify this switch if you are working on GNAT itself. `-a' is - also useful in conjunction with `-f' if you need to recompile an - entire application, including run-time files, using special - configuration pragma settings, such as a non-standard - `Float_Representation' pragma. By default `gnatmake -a' compiles - all GNAT internal files with `gcc -c -gnatpg' rather than `gcc -c'. - - `-b' - Bind only. Can be combined with `-c' to do compilation and - binding, but no link. Can be combined with `-l' to do binding and - linking. When not combined with `-c' all the units in the closure - of the main program must have been previously compiled and must be - up to date. The root unit specified by FILE_NAME may be given - without extension, with the source extension or, if no GNAT - Project File is specified, with the ALI file extension. - - `-c' - Compile only. Do not perform binding, except when `-b' is also - specified. Do not perform linking, except if both `-b' and `-l' - are also specified. If the root unit specified by FILE_NAME is - not a main unit, this is the default. Otherwise `gnatmake' will - attempt binding and linking unless all objects are up to date and - the executable is more recent than the objects. - - `-C' - Use a mapping file. A mapping file is a way to communicate to the - compiler two mappings: from unit names to file names (without any - directory information) and from file names to path names (with - full directory information). These mappings are used by the - compiler to short-circuit the path search. When `gnatmake' is - invoked with this switch, it will create a mapping file, initially - populated by the project manager, if `-P' is used, otherwise - initially empty. Each invocation of the compiler will add the newly - accessed sources to the mapping file. This will improve the source - search during the next invocation of the compiler. - - `-f' - Force recompilations. Recompile all sources, even though some - object files may be up to date, but don't recompile predefined or - GNAT internal files or locked files (files with a write-protected - ALI file), unless the `-a' switch is also specified. - - `' - - `-i' - In normal mode, `gnatmake' compiles all object files and ALI files - into the current directory. If the `-i' switch is used, then - instead object files and ALI files that already exist are - overwritten in place. This means that once a large project is - organized into separate directories in the desired manner, then - `gnatmake' will automatically maintain and update this - organization. If no ALI files are found on the Ada object path - (*Note Search Paths and the Run-Time Library (RTL)::), the new - object and ALI files are created in the directory containing the - source being compiled. If another organization is desired, where - objects and sources are kept in different directories, a useful - technique is to create dummy ALI files in the desired directories. - When detecting such a dummy file, `gnatmake' will be forced to - recompile the corresponding source file, and it will be put the - resulting object and ALI files in the directory where it found the - dummy file. - - `-jN' - Use N processes to carry out the (re)compilations. On a - multiprocessor machine compilations will occur in parallel. In the - event of compilation errors, messages from various compilations - might get interspersed (but `gnatmake' will give you the full - ordered list of failing compiles at the end). If this is - problematic, rerun the make process with n set to 1 to get a clean - list of messages. - - `-k' - Keep going. Continue as much as possible after a compilation - error. To ease the programmer's task in case of compilation - errors, the list of sources for which the compile fails is given - when `gnatmake' terminates. - - If `gnatmake' is invoked with several `file_names' and with this - switch, if there are compilation errors when building an - executable, `gnatmake' will not attempt to build the following - executables. - - `-l' - Link only. Can be combined with `-b' to binding and linking. - Linking will not be performed if combined with `-c' but not with - `-b'. When not combined with `-b' all the units in the closure of - the main program must have been previously compiled and must be up - to date, and the main program need to have been bound. The root - unit specified by FILE_NAME may be given without extension, with - the source extension or, if no GNAT Project File is specified, - with the ALI file extension. - - `-m' - Specifies that the minimum necessary amount of recompilations be - performed. In this mode `gnatmake' ignores time stamp differences - when the only modifications to a source file consist in - adding/removing comments, empty lines, spaces or tabs. This means - that if you have changed the comments in a source file or have - simply reformatted it, using this switch will tell gnatmake not to - recompile files that depend on it (provided other sources on which - these files depend have undergone no semantic modifications). Note - that the debugging information may be out of date with respect to - the sources if the `-m' switch causes a compilation to be - switched, so the use of this switch represents a trade-off between - compilation time and accurate debugging information. - - `-M' - Check if all objects are up to date. If they are, output the object - dependences to `stdout' in a form that can be directly exploited in - a `Makefile'. By default, each source file is prefixed with its - (relative or absolute) directory name. This name is whatever you - specified in the various `-aI' and `-I' switches. If you use - `gnatmake -M' `-q' (see below), only the source file names, - without relative paths, are output. If you just specify the `-M' - switch, dependencies of the GNAT internal system files are - omitted. This is typically what you want. If you also specify the - `-a' switch, dependencies of the GNAT internal files are also - listed. Note that dependencies of the objects in external Ada - libraries (see switch `-aL'DIR in the following list) are never - reported. - - `-n' - Don't compile, bind, or link. Checks if all objects are up to date. - If they are not, the full name of the first file that needs to be - recompiled is printed. Repeated use of this option, followed by - compiling the indicated source file, will eventually result in - recompiling all required units. - - `-o EXEC_NAME' - Output executable name. The name of the final executable program - will be EXEC_NAME. If the `-o' switch is omitted the default name - for the executable will be the name of the input file in - appropriate form for an executable file on the host system. - - This switch cannot be used when invoking `gnatmake' with several - `file_names'. - - `-q' - Quiet. When this flag is not set, the commands carried out by - `gnatmake' are displayed. - - `-s' - Recompile if compiler switches have changed since last compilation. - All compiler switches but -I and -o are taken into account in the - following way: orders between different "first letter" switches - are ignored, but orders between same switches are taken into - account. For example, `-O -O2' is different than `-O2 -O', but `-g - -O' is equivalent to `-O -g'. - - `-u' - Unique. Recompile at most the main file. It implies -c. Combined - with -f, it is equivalent to calling the compiler directly. - - `-v' - Verbose. Displays the reason for all recompilations `gnatmake' - decides are necessary. - - `-z' - No main subprogram. Bind and link the program even if the unit name - given on the command line is a package name. The resulting - executable will execute the elaboration routines of the package - and its closure, then the finalization routines. - - ``gcc' switches' - The switch `-g' or any uppercase switch (other than `-A', `-L' or - `-S') or any switch that is more than one character is passed to - `gcc' (e.g. `-O', `-gnato,' etc.) - - Source and library search path switches: - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source files search is undertaken is described in - *Note Search Paths and the Run-Time Library (RTL)::. - - `-aLDIR' - Consider DIR as being an externally provided Ada library. - Instructs `gnatmake' to skip compilation units whose `.ali' files - have been located in directory DIR. This allows you to have - missing bodies for the units in DIR and to ignore out of date - bodies for the same units. You still need to specify the location - of the specs for these units by using the switches `-aIDIR' or - `-IDIR'. Note: this switch is provided for compatibility with - previous versions of `gnatmake'. The easier method of causing - standard libraries to be excluded from consideration is to - write-protect the corresponding ALI files. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is described in - *Note Search Paths for gnatbind::. - - `-ADIR' - Equivalent to `-aLDIR -aIDIR'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-I-' - Do not look for source files in the directory containing the source - file named in the command line. Do not look for ALI or object - files in the directory where `gnatmake' was invoked. - - `-LDIR' - Add directory DIR to the list of directories in which the linker - Furthermore, under Windows, the sources pointed to by the - libraries path set in the registry are not searched for. will - search for libraries. This is equivalent to `-largs -L'DIR. - - `-nostdinc' - Do not look for source files in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. We look for - the runtime in the following directories, and stop as soon as a - valid runtime is found ("adainclude" or "ada_source_path", and - "adalib" or "ada_object_path" present): - - * /$rts_path - - * /$rts_path - - * /rts-$rts_path - - The selected path is handled like a normal RTS path. - -  - File: gnat_ug_wnt.info, Node: Mode Switches for gnatmake, Next: Notes on the Command Line, Prev: Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Mode Switches for `gnatmake' - ============================ - - The mode switches (referred to as `mode_switches') allow the inclusion - of switches that are to be passed to the compiler itself, the binder or - the linker. The effect of a mode switch is to cause all subsequent - switches up to the end of the switch list, or up to the next mode - switch, to be interpreted as switches to be passed on to the designated - component of GNAT. - - `-cargs SWITCHES' - Compiler switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all compile - steps performed by `gnatmake'. - - `-bargs SWITCHES' - Binder switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all bind steps - performed by `gnatmake'. - - `-largs SWITCHES' - Linker switches. Here SWITCHES is a list of switches that are - valid switches for `gcc'. They will be passed on to all link steps - performed by `gnatmake'. - -  - File: gnat_ug_wnt.info, Node: Notes on the Command Line, Next: How gnatmake Works, Prev: Mode Switches for gnatmake, Up: The GNAT Make Program gnatmake - - Notes on the Command Line - ========================= - - This section contains some additional useful notes on the operation of - the `gnatmake' command. - - * If `gnatmake' finds no ALI files, it recompiles the main program - and all other units required by the main program. This means that - `gnatmake' can be used for the initial compile, as well as during - subsequent steps of the development cycle. - - * If you enter `gnatmake FILE.adb', where `FILE.adb' is a subunit or - body of a generic unit, `gnatmake' recompiles `FILE.adb' (because - it finds no ALI) and stops, issuing a warning. - - * In `gnatmake' the switch `-I' is used to specify both source and - library file paths. Use `-aI' instead if you just want to specify - source paths only and `-aO' if you want to specify library paths - only. - - * `gnatmake' examines both an ALI file and its corresponding object - file for consistency. If an ALI is more recent than its - corresponding object, or if the object file is missing, the - corresponding source will be recompiled. Note that `gnatmake' - expects an ALI and the corresponding object file to be in the same - directory. - - * `gnatmake' will ignore any files whose ALI file is write-protected. - This may conveniently be used to exclude standard libraries from - consideration and in particular it means that the use of the `-f' - switch will not recompile these files unless `-a' is also - specified. - - * `gnatmake' has been designed to make the use of Ada libraries - particularly convenient. Assume you have an Ada library organized - as follows: OBJ-DIR contains the objects and ALI files for of your - Ada compilation units, whereas INCLUDE-DIR contains the specs of - these units, but no bodies. Then to compile a unit stored in - `main.adb', which uses this Ada library you would just type - - $ gnatmake -aIINCLUDE-DIR -aLOBJ-DIR main - - * Using `gnatmake' along with the `-m (minimal recompilation)' - switch provides a mechanism for avoiding unnecessary - rcompilations. Using this switch, you can update the - comments/format of your source files without having to recompile - everything. Note, however, that adding or deleting lines in a - source files may render its debugging info obsolete. If the file - in question is a spec, the impact is rather limited, as that - debugging info will only be useful during the elaboration phase of - your program. For bodies the impact can be more significant. In - all events, your debugger will warn you if a source file is more - recent than the corresponding object, and alert you to the fact - that the debugging information may be out of date. - -  - File: gnat_ug_wnt.info, Node: How gnatmake Works, Next: Examples of gnatmake Usage, Prev: Notes on the Command Line, Up: The GNAT Make Program gnatmake - - How `gnatmake' Works - ==================== - - Generally `gnatmake' automatically performs all necessary - recompilations and you don't need to worry about how it works. However, - it may be useful to have some basic understanding of the `gnatmake' - approach and in particular to understand how it uses the results of - previous compilations without incorrectly depending on them. - - First a definition: an object file is considered "up to date" if the - corresponding ALI file exists and its time stamp predates that of the - object file and if all the source files listed in the dependency - section of this ALI file have time stamps matching those in the ALI - file. This means that neither the source file itself nor any files that - it depends on have been modified, and hence there is no need to - recompile this file. - - `gnatmake' works by first checking if the specified main unit is up - to date. If so, no compilations are required for the main unit. If not, - `gnatmake' compiles the main program to build a new ALI file that - reflects the latest sources. Then the ALI file of the main unit is - examined to find all the source files on which the main program depends, - and `gnatmake' recursively applies the above procedure on all these - files. - - This process ensures that `gnatmake' only trusts the dependencies in - an existing ALI file if they are known to be correct. Otherwise it - always recompiles to determine a new, guaranteed accurate set of - dependencies. As a result the program is compiled "upside down" from - what may be more familiar as the required order of compilation in some - other Ada systems. In particular, clients are compiled before the units - on which they depend. The ability of GNAT to compile in any order is - critical in allowing an order of compilation to be chosen that - guarantees that `gnatmake' will recompute a correct set of new - dependencies if necessary. - - When invoking `gnatmake' with several FILE_NAMES, if a unit is - imported by several of the executables, it will be recompiled at most - once. - -  - File: gnat_ug_wnt.info, Node: Examples of gnatmake Usage, Prev: How gnatmake Works, Up: The GNAT Make Program gnatmake - - Examples of `gnatmake' Usage - ============================ - - `gnatmake hello.adb' - Compile all files necessary to bind and link the main program - `hello.adb' (containing unit `Hello') and bind and link the - resulting object files to generate an executable file `hello'. - - `gnatmake main1 main2 main3' - Compile all files necessary to bind and link the main programs - `main1.adb' (containing unit `Main1'), `main2.adb' (containing - unit `Main2') and `main3.adb' (containing unit `Main3') and bind - and link the resulting object files to generate three executable - files `main1', `main2' and `main3'. - - `gnatmake -q Main_Unit -cargs -O2 -bargs -l' - Compile all files necessary to bind and link the main program unit - `Main_Unit' (from file `main_unit.adb'). All compilations will be - done with optimization level 2 and the order of elaboration will be - listed by the binder. `gnatmake' will operate in quiet mode, not - displaying commands it is executing. - -  - File: gnat_ug_wnt.info, Node: Renaming Files Using gnatchop, Next: Configuration Pragmas, Prev: The GNAT Make Program gnatmake, Up: Top - - Renaming Files Using `gnatchop' - ******************************* - - This chapter discusses how to handle files with multiple units by using - the `gnatchop' utility. This utility is also useful in renaming files - to meet the standard GNAT default file naming conventions. - - * Menu: - - * Handling Files with Multiple Units:: - * Operating gnatchop in Compilation Mode:: - * Command Line for gnatchop:: - * Switches for gnatchop:: - * Examples of gnatchop Usage:: - -  - File: gnat_ug_wnt.info, Node: Handling Files with Multiple Units, Next: Operating gnatchop in Compilation Mode, Up: Renaming Files Using gnatchop - - Handling Files with Multiple Units - ================================== - - The basic compilation model of GNAT requires that a file submitted to - the compiler have only one unit and there be a strict correspondence - between the file name and the unit name. - - The `gnatchop' utility allows both of these rules to be relaxed, - allowing GNAT to process files which contain multiple compilation units - and files with arbitrary file names. `gnatchop' reads the specified - file and generates one or more output files, containing one unit per - file. The unit and the file name correspond, as required by GNAT. - - If you want to permanently restructure a set of "foreign" files so - that they match the GNAT rules, and do the remaining development using - the GNAT structure, you can simply use `gnatchop' once, generate the - new set of files and work with them from that point on. - - Alternatively, if you want to keep your files in the "foreign" - format, perhaps to maintain compatibility with some other Ada - compilation system, you can set up a procedure where you use `gnatchop' - each time you compile, regarding the source files that it writes as - temporary files that you throw away. - -  - File: gnat_ug_wnt.info, Node: Operating gnatchop in Compilation Mode, Next: Command Line for gnatchop, Prev: Handling Files with Multiple Units, Up: Renaming Files Using gnatchop - - Operating gnatchop in Compilation Mode - ====================================== - - The basic function of `gnatchop' is to take a file with multiple units - and split it into separate files. The boundary between files is - reasonably clear, except for the issue of comments and pragmas. In - default mode, the rule is that any pragmas between units belong to the - previous unit, except that configuration pragmas always belong to the - following unit. Any comments belong to the following unit. These rules - almost always result in the right choice of the split point without - needing to mark it explicitly and most users will find this default to - be what they want. In this default mode it is incorrect to submit a - file containing only configuration pragmas, or one that ends in - configuration pragmas, to `gnatchop'. - - However, using a special option to activate "compilation mode", - `gnatchop' can perform another function, which is to provide exactly - the semantics required by the RM for handling of configuration pragmas - in a compilation. In the absence of configuration pragmas (at the main - file level), this option has no effect, but it causes such - configuration pragmas to be handled in a quite different manner. - - First, in compilation mode, if `gnatchop' is given a file that - consists of only configuration pragmas, then this file is appended to - the `gnat.adc' file in the current directory. This behavior provides - the required behavior described in the RM for the actions to be taken - on submitting such a file to the compiler, namely that these pragmas - should apply to all subsequent compilations in the same compilation - environment. Using GNAT, the current directory, possibly containing a - `gnat.adc' file is the representation of a compilation environment. For - more information on the `gnat.adc' file, see the section on handling of - configuration pragmas *note Handling of Configuration Pragmas::. - - Second, in compilation mode, if `gnatchop' is given a file that - starts with configuration pragmas, and contains one or more units, then - these configuration pragmas are prepended to each of the chopped files. - This behavior provides the required behavior described in the RM for the - actions to be taken on compiling such a file, namely that the pragmas - apply to all units in the compilation, but not to subsequently compiled - units. - - Finally, if configuration pragmas appear between units, they are - appended to the previous unit. This results in the previous unit being - illegal, since the compiler does not accept configuration pragmas that - follow a unit. This provides the required RM behavior that forbids - configuration pragmas other than those preceding the first compilation - unit of a compilation. - - For most purposes, `gnatchop' will be used in default mode. The - compilation mode described above is used only if you need exactly - accurate behavior with respect to compilations, and you have files that - contain multiple units and configuration pragmas. In this circumstance - the use of `gnatchop' with the compilation mode switch provides the - required behavior, and is for example the mode in which GNAT processes - the ACVC tests. - -  - File: gnat_ug_wnt.info, Node: Command Line for gnatchop, Next: Switches for gnatchop, Prev: Operating gnatchop in Compilation Mode, Up: Renaming Files Using gnatchop - - Command Line for `gnatchop' - =========================== - - The `gnatchop' command has the form: - - $ gnatchop switches FILE NAME [FILE NAME FILE NAME ...] - [DIRECTORY] - - The only required argument is the file name of the file to be chopped. - There are no restrictions on the form of this file name. The file itself - contains one or more Ada units, in normal GNAT format, concatenated - together. As shown, more than one file may be presented to be chopped. - - When run in default mode, `gnatchop' generates one output file in - the current directory for each unit in each of the files. - - DIRECTORY, if specified, gives the name of the directory to which - the output files will be written. If it is not specified, all files are - written to the current directory. - - For example, given a file called `hellofiles' containing - - procedure hello; - - with Text_IO; use Text_IO; - procedure hello is - begin - Put_Line ("Hello"); - end hello; - - the command - - $ gnatchop hellofiles - - generates two files in the current directory, one called `hello.ads' - containing the single line that is the procedure spec, and the other - called `hello.adb' containing the remaining text. The original file is - not affected. The generated files can be compiled in the normal manner. - -  - File: gnat_ug_wnt.info, Node: Switches for gnatchop, Next: Examples of gnatchop Usage, Prev: Command Line for gnatchop, Up: Renaming Files Using gnatchop - - Switches for `gnatchop' - ======================= - - `gnatchop' recognizes the following switches: - - `-c' - Causes `gnatchop' to operate in compilation mode, in which - configuration pragmas are handled according to strict RM rules. See - previous section for a full description of this mode. - - `-gnatxxx' - This passes the given `-gnatxxx' switch to `gnat' which is used to - parse the given file. Not all `xxx' options make sense, but for - example, the use of `-gnati2' allows `gnatchop' to process a - source file that uses Latin-2 coding for identifiers. - - `-h' - Causes `gnatchop' to generate a brief help summary to the standard - output file showing usage information. - - `-kMM' - Limit generated file names to the specified number `mm' of - characters. This is useful if the resulting set of files is - required to be interoperable with systems which limit the length - of file names. No space is allowed between the `-k' and the - numeric value. The numeric value may be omitted in which case a - default of `-k8', suitable for use with DOS-like file systems, is - used. If no `-k' switch is present then there is no limit on the - length of file names. - - `-p' - Causes the file modification time stamp of the input file to be - preserved and used for the time stamp of the output file(s). This - may be useful for preserving coherency of time stamps in an - enviroment where `gnatchop' is used as part of a standard build - process. - - `-q' - Causes output of informational messages indicating the set of - generated files to be suppressed. Warnings and error messages are - unaffected. - - `-r' - Generate `Source_Reference' pragmas. Use this switch if the output - files are regarded as temporary and development is to be done in - terms of the original unchopped file. This switch causes - `Source_Reference' pragmas to be inserted into each of the - generated files to refers back to the original file name and line - number. The result is that all error messages refer back to the - original unchopped file. In addition, the debugging information - placed into the object file (when the `-g' switch of `gcc' or - `gnatmake' is specified) also refers back to this original file so - that tools like profilers and debuggers will give information in - terms of the original unchopped file. - - If the original file to be chopped itself contains a - `Source_Reference' pragma referencing a third file, then gnatchop - respects this pragma, and the generated `Source_Reference' pragmas - in the chopped file refer to the original file, with appropriate - line numbers. This is particularly useful when `gnatchop' is used - in conjunction with `gnatprep' to compile files that contain - preprocessing statements and multiple units. - - `-v' - Causes `gnatchop' to operate in verbose mode. The version number - and copyright notice are output, as well as exact copies of the - gnat1 commands spawned to obtain the chop control information. - - `-w' - Overwrite existing file names. Normally `gnatchop' regards it as a - fatal error if there is already a file with the same name as a - file it would otherwise output, in other words if the files to be - chopped contain duplicated units. This switch bypasses this check, - and causes all but the last instance of such duplicated units to - be skipped. - - `--GCC=xxxx' - Specify the path of the GNAT parser to be used. When this switch - is used, no attempt is made to add the prefix to the GNAT parser - executable. - -  - File: gnat_ug_wnt.info, Node: Examples of gnatchop Usage, Prev: Switches for gnatchop, Up: Renaming Files Using gnatchop - - Examples of `gnatchop' Usage - ============================ - - `gnatchop -w hello_s.ada ichbiah/files' - Chops the source file `hello_s.ada'. The output files will be - placed in the directory `ichbiah/files', overwriting any files - with matching names in that directory (no files in the current - directory are modified). - - `gnatchop archive' - Chops the source file `archive' into the current directory. One - useful application of `gnatchop' is in sending sets of sources - around, for example in email messages. The required sources are - simply concatenated (for example, using a Unix `cat' command), and - then `gnatchop' is used at the other end to reconstitute the - original file names. - - `gnatchop file1 file2 file3 direc' - Chops all units in files `file1', `file2', `file3', placing the - resulting files in the directory `direc'. Note that if any units - occur more than once anywhere within this set of files, an error - message is generated, and no files are written. To override this - check, use the `-w' switch, in which case the last occurrence in - the last file will be the one that is output, and earlier - duplicate occurrences for a given unit will be skipped. - -  - File: gnat_ug_wnt.info, Node: Configuration Pragmas, Next: Handling Arbitrary File Naming Conventions Using gnatname, Prev: Renaming Files Using gnatchop, Up: Top - - Configuration Pragmas - ********************* - - In Ada 95, configuration pragmas include those pragmas described as - such in the Ada 95 Reference Manual, as well as - implementation-dependent pragmas that are configuration pragmas. See the - individual descriptions of pragmas in the GNAT Reference Manual for - details on these additional GNAT-specific configuration pragmas. Most - notably, the pragma `Source_File_Name', which allows specifying - non-default names for source files, is a configuration pragma. The - following is a complete list of configuration pragmas recognized by - `GNAT': - - Ada_83 - Ada_95 - C_Pass_By_Copy - Component_Alignment - Discard_Names - Elaboration_Checks - Eliminate - Extend_System - Extensions_Allowed - External_Name_Casing - Float_Representation - Initialize_Scalars - License - Locking_Policy - Long_Float - No_Run_Time - Normalize_Scalars - Polling - Propagate_Exceptions - Queuing_Policy - Ravenscar - Restricted_Run_Time - Restrictions - Reviewable - Source_File_Name - Style_Checks - Suppress - Task_Dispatching_Policy - Unsuppress - Use_VADS_Size - Warnings - Validity_Checks - - * Menu: - - * Handling of Configuration Pragmas:: - * The Configuration Pragmas Files:: - -  - File: gnat_ug_wnt.info, Node: Handling of Configuration Pragmas, Next: The Configuration Pragmas Files, Up: Configuration Pragmas - - Handling of Configuration Pragmas - ================================= - - Configuration pragmas may either appear at the start of a compilation - unit, in which case they apply only to that unit, or they may apply to - all compilations performed in a given compilation environment. - - GNAT also provides the `gnatchop' utility to provide an automatic - way to handle configuration pragmas following the semantics for - compilations (that is, files with multiple units), described in the RM. - See section *note Operating gnatchop in Compilation Mode:: for details. - However, for most purposes, it will be more convenient to edit the - `gnat.adc' file that contains configuration pragmas directly, as - described in the following section. - -  - File: gnat_ug_wnt.info, Node: The Configuration Pragmas Files, Prev: Handling of Configuration Pragmas, Up: Configuration Pragmas - - The Configuration Pragmas Files - =============================== - - In GNAT a compilation environment is defined by the current directory - at the time that a compile command is given. This current directory is - searched for a file whose name is `gnat.adc'. If this file is present, - it is expected to contain one or more configuration pragmas that will - be applied to the current compilation. However, if the switch `-gnatA' - is used, `gnat.adc' is not considered. - - Configuration pragmas may be entered into the `gnat.adc' file either - by running `gnatchop' on a source file that consists only of - configuration pragmas, or more conveniently by direct editing of the - `gnat.adc' file, which is a standard format source file. - - In addition to `gnat.adc', one additional file containing - configuration pragmas may be applied to the current compilation using - the switch `-gnatec'PATH. PATH must designate an existing file that - contains only configuration pragmas. These configuration pragmas are in - addition to those found in `gnat.adc' (provided `gnat.adc' is present - and switch `-gnatA' is not used). - - It is allowed to specify several switches `-gnatec', however only - the last one on the command line will be taken into account. - -  - File: gnat_ug_wnt.info, Node: Handling Arbitrary File Naming Conventions Using gnatname, Next: GNAT Project Manager, Prev: Configuration Pragmas, Up: Top - - Handling Arbitrary File Naming Conventions Using `gnatname' - *********************************************************** - - * Menu: - - * Arbitrary File Naming Conventions:: - * Running gnatname:: - * Switches for gnatname:: - * Examples of gnatname Usage:: - -  - File: gnat_ug_wnt.info, Node: Arbitrary File Naming Conventions, Next: Running gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Arbitrary File Naming Conventions - ================================= - - The GNAT compiler must be able to know the source file name of a - compilation unit. When using the standard GNAT default file naming - conventions (`.ads' for specs, `.adb' for bodies), the GNAT compiler - does not need additional information. - - When the source file names do not follow the standard GNAT default file - naming conventions, the GNAT compiler must be given additional - information through a configuration pragmas file (see *Note - Configuration Pragmas::) or a project file. When the non standard file - naming conventions are well-defined, a small number of pragmas - `Source_File_Name' specifying a naming pattern (see *Note Alternative - File Naming Schemes::) may be sufficient. However, if the file naming - conventions are irregular or arbitrary, a number of pragma - `Source_File_Name' for individual compilation units must be defined. - To help maintain the correspondence between compilation unit names and - source file names within the compiler, GNAT provides a tool `gnatname' - to generate the required pragmas for a set of files. - -  - File: gnat_ug_wnt.info, Node: Running gnatname, Next: Switches for gnatname, Prev: Arbitrary File Naming Conventions, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Running `gnatname' - ================== - - The usual form of the `gnatname' command is - - $ gnatname [SWITCHES] NAMING_PATTERN [NAMING_PATTERNS] - - All of the arguments are optional. If invoked without any argument, - `gnatname' will display its usage. - - When used with at least one naming pattern, `gnatname' will attempt to - find all the compilation units in files that follow at least one of the - naming patterns. To find these compilation units, `gnatname' will use - the GNAT compiler in syntax-check-only mode on all regular files. - - One or several Naming Patterns may be given as arguments to `gnatname'. - Each Naming Pattern is enclosed between double quotes. A Naming - Pattern is a regular expression similar to the wildcard patterns used - in file names by the Unix shells or the DOS prompt. - - Examples of Naming Patterns are - - "*.[12].ada" - "*.ad[sb]*" - "body_*" "spec_*" - - For a more complete description of the syntax of Naming Patterns, see - the second kind of regular expressions described in `g-regexp.ads' (the - "Glob" regular expressions). - - When invoked with no switches, `gnatname' will create a configuration - pragmas file `gnat.adc' in the current working directory, with pragmas - `Source_File_Name' for each file that contains a valid Ada unit. - -  - File: gnat_ug_wnt.info, Node: Switches for gnatname, Next: Examples of gnatname Usage, Prev: Running gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Switches for `gnatname' - ======================= - - Switches for `gnatname' must precede any specified Naming Pattern. - - You may specify any of the following switches to `gnatname': - - `-c`file'' - Create a configuration pragmas file `file' (instead of the default - `gnat.adc'). There may be zero, one or more space between `-c' and - `file'. `file' may include directory information. `file' must be - writeable. There may be only one switch `-c'. When a switch `-c' is - specified, no switch `-P' may be specified (see below). - - `-d`dir'' - Look for source files in directory `dir'. There may be zero, one - or more spaces between `-d' and `dir'. When a switch `-d' is - specified, the current working directory will not be searched for - source files, unless it is explictly specified with a `-d' or `-D' - switch. Several switches `-d' may be specified. If `dir' is a - relative path, it is relative to the directory of the - configuration pragmas file specified with switch `-c', or to the - directory of the project file specified with switch `-P' or, if - neither switch `-c' nor switch `-P' are specified, it is relative - to the current working directory. The directory specified with - switch `-c' must exist and be readable. - - `-D`file'' - Look for source files in all directories listed in text file - `file'. There may be zero, one or more spaces between `-d' and - `dir'. `file' must be an existing, readable text file. Each non - empty line in `file' must be a directory. Specifying switch `-D' - is equivalent to specifying as many switches `-d' as there are non - empty lines in `file'. - - `-h' - Output usage (help) information. The output is written to `stdout'. - - `-P`proj'' - Create or update project file `proj'. There may be zero, one or - more space between `-P' and `proj'. `proj' may include directory - information. `proj' must be writeable. There may be only one - switch `-P'. When a switch `-P' is specified, no switch `-c' may - be specified. - - `-v' - Verbose mode. Output detailed explanation of behavior to `stdout'. - This includes name of the file written, the name of the - directories to search and, for each file in those directories - whose name matches at least one of the Naming Patterns, an - indication of whether the file contains a unit, and if so the name - of the unit. - - `-v -v' - Very Verbose mode. In addition to the output produced in verbose - mode, for each file in the searched directories whose name matches - none of the Naming Patterns, an indication is given that there is - no match. - - `-x`pattern'' - Excluded patterns. Using this switch, it is possible to exclude - some files that would match the name patterns. For example, - `"gnatname -x "*_nt.ada" "*.ada"' will look for Ada units in all - files with the `.ada' extension, except those whose names end with - `_nt.ada'. - -  - File: gnat_ug_wnt.info, Node: Examples of gnatname Usage, Prev: Switches for gnatname, Up: Handling Arbitrary File Naming Conventions Using gnatname - - Examples of `gnatname' Usage - ============================ - - $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" - - In this example, the directory `/home/me' must already exist and be - writeable. In addition, the directory `/home/me/sources' (specified by - `-d sources') must exist and be readable. Note the optional spaces after - `-c' and `-d'. - - $ gnatname -P/home/me/proj -x "*_nt_body.ada" -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" - - Note that several switches `-d' may be used, even in conjunction - with one or several switches `-D'. Several Naming Patterns and one - excluded pattern are used in this example. - -  - File: gnat_ug_wnt.info, Node: GNAT Project Manager, Next: Elaboration Order Handling in GNAT, Prev: Handling Arbitrary File Naming Conventions Using gnatname, Up: Top - - GNAT Project Manager - ******************** - - * Menu: - - * Introduction:: - * Examples of Project Files:: - * Project File Syntax:: - * Objects and Sources in Project Files:: - * Importing Projects:: - * Project Extension:: - * External References in Project Files:: - * Packages in Project Files:: - * Variables from Imported Projects:: - * Naming Schemes:: - * Library Projects:: - * Switches Related to Project Files:: - * Tools Supporting Project Files:: - * An Extended Example:: - * Project File Complete Syntax:: - -  - File: gnat_ug_wnt.info, Node: Introduction, Next: Examples of Project Files, Up: GNAT Project Manager - - Introduction - ============ - - This chapter describes GNAT's _Project Manager_, a facility that lets - you configure various properties for a collection of source files. In - particular, you can specify: - * The directory or set of directories containing the source files, - and/or the names of the specific source files themselves - - * The directory in which the compiler's output (`ALI' files, object - files, tree files) will be placed - - * The directory in which the executable programs will be placed - - * Switch settings for any of the project-enabled tools (`gnatmake', - compiler, binder, linker, `gnatls', `gnatxref', `gnatfind'); you - can apply these settings either globally or to individual units - - * The source files containing the main subprogram(s) to be built - - * The source programming language(s) (currently Ada and/or C) - - * Source file naming conventions; you can specify these either - globally or for individual units - - * Menu: - - * Project Files:: - -  - File: gnat_ug_wnt.info, Node: Project Files, Up: Introduction - - Project Files - ------------- - - A "project" is a specific set of values for these properties. You can - define a project's settings in a "project file", a text file with an - Ada-like syntax; a property value is either a string or a list of - strings. Properties that are not explicitly set receive default - values. A project file may interrogate the values of "external - variables" (user-defined command-line switches or environment - variables), and it may specify property settings conditionally, based - on the value of such variables. - - In simple cases, a project's source files depend only on other - source files in the same project, or on the predefined libraries. - ("Dependence" is in the technical sense; for example, one Ada unit - "with"ing another.) However, the Project Manager also allows much more - sophisticated arrangements, with the source files in one project - depending on source files in other projects: - * One project can _import_ other projects containing needed source - files. - - * You can organize GNAT projects in a hierarchy: a _child_ project - can extend a _parent_ project, inheriting the parent's source - files and optionally overriding any of them with alternative - versions - - More generally, the Project Manager lets you structure large development - efforts into hierarchical subsystems, with build decisions deferred to - the subsystem level and thus different compilation environments (switch - settings) used for different subsystems. - - The Project Manager is invoked through the `-P_projectfile_' switch - to `gnatmake' or to the `gnat' front driver. If you want to define (on - the command line) an external variable that is queried by the project - file, additionally use the `-X_vbl_=_value_' switch. The Project - Manager parses and interprets the project file, and drives the invoked - tool based on the project settings. - - The Project Manager supports a wide range of development strategies, - for systems of all sizes. Some typical practices that are easily - handled: - * Using a common set of source files, but generating object files in - different directories via different switch settings - - * Using a mostly-shared set of source files, but with different - versions of some unit or units - - The destination of an executable can be controlled inside a project file - using the `-o' switch. In the absence of such a switch either inside - the project file or on the command line, any executable files generated - by `gnatmake' will be placed in the directory `Exec_Dir' specified in - the project file. If no `Exec_Dir' is specified, they will be placed in - the object directory of the project. - - You can use project files to achieve some of the effects of a source - versioning system (for example, defining separate projects for the - different sets of sources that comprise different releases) but the - Project Manager is independent of any source configuration management - tools that might be used by the developers. - - The next section introduces the main features of GNAT's project - facility through a sequence of examples; subsequent sections will - present the syntax and semantics in more detail. - -  - File: gnat_ug_wnt.info, Node: Examples of Project Files, Next: Project File Syntax, Prev: Introduction, Up: GNAT Project Manager - - Examples of Project Files - ========================= - - This section illustrates some of the typical uses of project files and - explains their basic structure and behavior. - - * Menu: - - * Common Sources with Different Switches and Different Output Directories:: - * Using External Variables:: - * Importing Other Projects:: - * Extending a Project:: - -  - File: gnat_ug_wnt.info, Node: Common Sources with Different Switches and Different Output Directories, Next: Using External Variables, Up: Examples of Project Files - - Common Sources with Different Switches and Different Output Directories - ----------------------------------------------------------------------- - - * Menu: - - * Source Files:: - * Specifying the Object Directory:: - * Specifying the Exec Directory:: - * Project File Packages:: - * Specifying Switch Settings:: - * Main Subprograms:: - * Source File Naming Conventions:: - * Source Language(s):: - - Assume that the Ada source files `pack.ads', `pack.adb', and `proc.adb' - are in the `/common' directory. The file `proc.adb' contains an Ada - main subprogram `Proc' that "with"s package `Pack'. We want to compile - these source files under two sets of switches: - * When debugging, we want to pass the `-g' switch to `gnatmake', and - the `-gnata', `-gnato', and `-gnatE' switches to the compiler; the - compiler's output is to appear in `/common/debug' - - * When preparing a release version, we want to pass the `-O2' switch - to the compiler; the compiler's output is to appear in - `/common/release' - - The GNAT project files shown below, respectively `debug.gpr' and - `release.gpr' in the `/common' directory, achieve these effects. - - Diagrammatically: - /common - debug.gpr - release.gpr - pack.ads - pack.adb - proc.adb - /common/debug {-g, -gnata, -gnato, -gnatE} - proc.ali, proc.o - pack.ali, pack.o - /common/release {-O2} - proc.ali, proc.o - pack.ali, pack.o - Here are the project files: - project Debug is - for Object_Dir use "debug"; - for Main use ("proc"); - - package Builder is - for Default_Switches ("Ada") use ("-g"); - end Builder; - - package Compiler is - for Default_Switches ("Ada") - use ("-fstack-check", "-gnata", "-gnato", "-gnatE"); - end Compiler; - end Debug; - - project Release is - for Object_Dir use "release"; - for Exec_Dir use "."; - for Main use ("proc"); - - package Compiler is - for Default_Switches ("Ada") use ("-O2"); - end Compiler; - end Release; - - The name of the project defined by `debug.gpr' is `"Debug"' (case - insensitive), and analogously the project defined by `release.gpr' is - `"Release"'. For consistency the file should have the same name as the - project, and the project file's extension should be `"gpr"'. These - conventions are not required, but a warning is issued if they are not - followed. - - If the current directory is `/temp', then the command - gnatmake -P/common/debug.gpr - - generates object and ALI files in `/common/debug', and the `proc' - executable also in `/common/debug', using the switch settings defined in - the project file. - - Likewise, the command - gnatmake -P/common/release.gpr - - generates object and ALI files in `/common/release', and the `proc' - executable in `/common', using the switch settings from the project - file. - -  - File: gnat_ug_wnt.info, Node: Source Files, Next: Specifying the Object Directory, Up: Common Sources with Different Switches and Different Output Directories - - Source Files - ............ - - If a project file does not explicitly specify a set of source - directories or a set of source files, then by default the project's - source files are the Ada source files in the project file directory. - Thus `pack.ads', `pack.adb', and `proc.adb' are the source files for - both projects. - -  - File: gnat_ug_wnt.info, Node: Specifying the Object Directory, Next: Specifying the Exec Directory, Prev: Source Files, Up: Common Sources with Different Switches and Different Output Directories - - Specifying the Object Directory - ............................... - - Several project properties are modeled by Ada-style _attributes_; you - define the property by supplying the equivalent of an Ada attribute - definition clause in the project file. A project's object directory is - such a property; the corresponding attribute is `Object_Dir', and its - value is a string expression. A directory may be specified either as - absolute or as relative; in the latter case, it is relative to the - project file directory. Thus the compiler's output is directed to - `/common/debug' (for the `Debug' project) and to `/common/release' (for - the `Release' project). If `Object_Dir' is not specified, then the - default is the project file directory. - -  - File: gnat_ug_wnt.info, Node: Specifying the Exec Directory, Next: Project File Packages, Prev: Specifying the Object Directory, Up: Common Sources with Different Switches and Different Output Directories - - Specifying the Exec Directory - ............................. - - A project's exec directory is another property; the corresponding - attribute is `Exec_Dir', and its value is also a string expression, - either specified as relative or absolute. If `Exec_Dir' is not - specified, then the default is the object directory (which may also be - the project file directory if attribute `Object_Dir' is not specified). - Thus the executable is placed in `/common/debug' for the `Debug' - project (attribute `Exec_Dir' not specified) and in `/common' for the - `Release' project. - -  - File: gnat_ug_wnt.info, Node: Project File Packages, Next: Specifying Switch Settings, Prev: Specifying the Exec Directory, Up: Common Sources with Different Switches and Different Output Directories - - Project File Packages - ..................... - - A GNAT tool integrated with the Project Manager is modeled by a - corresponding package in the project file. The `Debug' project defines - the packages `Builder' (for `gnatmake') and `Compiler'; the `Release' - project defines only the `Compiler' package. - - The Ada package syntax is not to be taken literally. Although - packages in project files bear a surface resemblance to packages in Ada - source code, the notation is simply a way to convey a grouping of - properties for a named entity. Indeed, the package names permitted in - project files are restricted to a predefined set, corresponding to the - project-aware tools, and the contents of packages are limited to a - small set of constructs. The packages in the example above contain - attribute definitions. - -  - File: gnat_ug_wnt.info, Node: Specifying Switch Settings, Next: Main Subprograms, Prev: Project File Packages, Up: Common Sources with Different Switches and Different Output Directories - - Specifying Switch Settings - .......................... - - Switch settings for a project-aware tool can be specified through - attributes in the package corresponding to the tool. The example above - illustrates one of the relevant attributes, `Default_Switches', defined - in the packages in both project files. Unlike simple attributes like - `Source_Dirs', `Default_Switches' is known as an _associative array_. - When you define this attribute, you must supply an "index" (a literal - string), and the effect of the attribute definition is to set the value - of the "array" at the specified "index". For the `Default_Switches' - attribute, the index is a programming language (in our case, Ada) , and - the value specified (after `use') must be a list of string expressions. - - The attributes permitted in project files are restricted to a - predefined set. Some may appear at project level, others in packages. - For any attribute that is an associate array, the index must always be a - literal string, but the restrictions on this string (e.g., a file name - or a language name) depend on the individual attribute. Also depending - on the attribute, its specified value will need to be either a string - or a string list. - - In the `Debug' project, we set the switches for two tools, - `gnatmake' and the compiler, and thus we include corresponding - packages, with each package defining the `Default_Switches' attribute - with index `"Ada"'. Note that the package corresponding to `gnatmake' - is named `Builder'. The `Release' project is similar, but with just - the `Compiler' package. - - In project `Debug' above the switches starting with `-gnat' that are - specified in package `Compiler' could have been placed in package - `Builder', since `gnatmake' transmits all such switches to the compiler. - -  - File: gnat_ug_wnt.info, Node: Main Subprograms, Next: Source File Naming Conventions, Prev: Specifying Switch Settings, Up: Common Sources with Different Switches and Different Output Directories - - Main Subprograms - ................ - - One of the properties of a project is its list of main subprograms - (actually a list of names of source files containing main subprograms, - with the file extension optional. This property is captured in the - `Main' attribute, whose value is a list of strings. If a project - defines the `Main' attribute, then you do not need to identify the main - subprogram(s) when invoking `gnatmake' (see *Note gnatmake and Project - Files::). - -  - File: gnat_ug_wnt.info, Node: Source File Naming Conventions, Next: Source Language(s), Prev: Main Subprograms, Up: Common Sources with Different Switches and Different Output Directories - - Source File Naming Conventions - .............................. - - Since the project files do not specify any source file naming - conventions, the GNAT defaults are used. The mechanism for defining - source file naming conventions - a package named `Naming' - will be - described below (*note Naming Schemes::). - -  - File: gnat_ug_wnt.info, Node: Source Language(s), Prev: Source File Naming Conventions, Up: Common Sources with Different Switches and Different Output Directories - - Source Language(s) - .................. - - Since the project files do not specify a `Languages' attribute, by - default the GNAT tools assume that the language of the project file is - Ada. More generally, a project can comprise source files in Ada, C, - and/or other languages. - -  - File: gnat_ug_wnt.info, Node: Using External Variables, Next: Importing Other Projects, Prev: Common Sources with Different Switches and Different Output Directories, Up: Examples of Project Files - - Using External Variables - ------------------------ - - Instead of supplying different project files for debug and release, we - can define a single project file that queries an external variable (set - either on the command line or via an environment variable) in order to - conditionally define the appropriate settings. Again, assume that the - source files `pack.ads', `pack.adb', and `proc.adb' are located in - directory `/common'. The following project file, `build.gpr', queries - the external variable named `STYLE' and defines an object directory and - switch settings based on whether the value is `"deb"' (debug) or - `"rel"' (release), where the default is `"deb"'. - - project Build is - for Main use ("proc"); - - type Style_Type is ("deb", "rel"); - Style : Style_Type := external ("STYLE", "deb"); - - case Style is - when "deb" => - for Object_Dir use "debug"; - - when "rel" => - for Object_Dir use "release"; - for Exec_Dir use "."; - end case; - - package Builder is - - case Style is - when "deb" => - for Default_Switches ("Ada") use ("-g"); - end case; - - end Builder; - - package Compiler is - - case Style is - when "deb" => - for Default_Switches ("Ada") use ("-gnata", "-gnato", "-gnatE"); - - when "rel" => - for Default_Switches ("Ada") use ("-O2"); - end case; - - end Compiler; - - end Build; - - `Style_Type' is an example of a _string type_, which is the project - file analog of an Ada enumeration type but containing string literals - rather than identifiers. `Style' is declared as a variable of this - type. - - The form `external("STYLE", "deb")' is known as an _external - reference_; its first argument is the name of an _external variable_, - and the second argument is a default value to be used if the external - variable doesn't exist. You can define an external variable on the - command line via the `-X' switch, or you can use an environment - variable as an external variable. - - Each `case' construct is expanded by the Project Manager based on the - value of `Style'. Thus the command - gnatmake -P/common/build.gpr -XSTYLE=deb - - is equivalent to the `gnatmake' invocation using the project file - `debug.gpr' in the earlier example. So is the command - gnatmake -P/common/build.gpr - - since `"deb"' is the default for `STYLE'. - - Analogously, - gnatmake -P/common/build.gpr -XSTYLE=rel - - is equivalent to the `gnatmake' invocation using the project file - `release.gpr' in the earlier example. - -  - File: gnat_ug_wnt.info, Node: Importing Other Projects, Next: Extending a Project, Prev: Using External Variables, Up: Examples of Project Files - - Importing Other Projects - ------------------------ - - A compilation unit in a source file in one project may depend on - compilation units in source files in other projects. To obtain this - behavior, the dependent project must _import_ the projects containing - the needed source files. This effect is embodied in syntax similar to - an Ada `with' clause, but the "with"ed entities are strings denoting - project files. - - As an example, suppose that the two projects `GUI_Proj' and - `Comm_Proj' are defined in the project files `gui_proj.gpr' and - `comm_proj.gpr' in directories `/gui' and `/comm', respectively. - Assume that the source files for `GUI_Proj' are `gui.ads' and - `gui.adb', and that the source files for `Comm_Proj' are `comm.ads' and - `comm.adb', with each set of files located in its respective project - file directory. Diagrammatically: - - /gui - gui_proj.gpr - gui.ads - gui.adb - - /comm - comm_proj.gpr - comm.ads - comm.adb - - We want to develop an application in directory `/app' that "with"s the - packages `GUI' and `Comm', using the properties of the corresponding - project files (e.g. the switch settings and object directory). - Skeletal code for a main procedure might be something like the - following: - - with GUI, Comm; - procedure App_Main is - ... - begin - ... - end App_Main; - - Here is a project file, `app_proj.gpr', that achieves the desired - effect: - - with "/gui/gui_proj", "/comm/comm_proj"; - project App_Proj is - for Main use ("app_main"); - end App_Proj; - - Building an executable is achieved through the command: - gnatmake -P/app/app_proj - - which will generate the `app_main' executable in the directory where - `app_proj.gpr' resides. - - If an imported project file uses the standard extension (`gpr') then - (as illustrated above) the `with' clause can omit the extension. - - Our example specified an absolute path for each imported project - file. Alternatively, you can omit the directory if either - * The imported project file is in the same directory as the - importing project file, or - - * You have defined an environment variable `ADA_PROJECT_PATH' that - includes the directory containing the needed project file. - - Thus, if we define `ADA_PROJECT_PATH' to include `/gui' and `/comm', - then our project file `app_proj.gpr' could be written as follows: - - with "gui_proj", "comm_proj"; - project App_Proj is - for Main use ("app_main"); - end App_Proj; - - Importing other projects raises the possibility of ambiguities. For - example, the same unit might be present in different imported projects, - or it might be present in both the importing project and an imported - project. Both of these conditions are errors. Note that in the - current version of the Project Manager, it is illegal to have an - ambiguous unit even if the unit is never referenced by the importing - project. This restriction may be relaxed in a future release. - -  - File: gnat_ug_wnt.info, Node: Extending a Project, Prev: Importing Other Projects, Up: Examples of Project Files - - Extending a Project - ------------------- - - A common situation in large software systems is to have multiple - implementations for a common interface; in Ada terms, multiple versions - of a package body for the same specification. For example, one - implementation might be safe for use in tasking programs, while another - might only be used in sequential applications. This can be modeled in - GNAT using the concept of _project extension_. If one project (the - "child") _extends_ another project (the "parent") then by default all - source files of the parent project are inherited by the child, but the - child project can override any of the parent's source files with new - versions, and can also add new files. This facility is the project - analog of extension in Object-Oriented Programming. Project - hierarchies are permitted (a child project may be the parent of yet - another project), and a project that inherits one project can also - import other projects. - - As an example, suppose that directory `/seq' contains the project - file `seq_proj.gpr' and the source files `pack.ads', `pack.adb', and - `proc.adb': - - /seq - pack.ads - pack.adb - proc.adb - seq_proj.gpr - - Note that the project file can simply be empty (that is, no attribute or - package is defined): - - project Seq_Proj is - end Seq_Proj; - - implying that its source files are all the Ada source files in the - project directory. - - Suppose we want to supply an alternate version of `pack.adb', in - directory `/tasking', but use the existing versions of `pack.ads' and - `proc.adb'. We can define a project `Tasking_Proj' that inherits - `Seq_Proj': - - /tasking - pack.adb - tasking_proj.gpr - - project Tasking_Proj extends "/seq/seq_proj" is - end Tasking_Proj; - - The version of `pack.adb' used in a build depends on which project file - is specified. - - Note that we could have designed this using project import rather - than project inheritance; a `base' project would contain the sources for - `pack.ads' and `proc.adb', a sequential project would import `base' and - add `pack.adb', and likewise a tasking project would import `base' and - add a different version of `pack.adb'. The choice depends on whether - other sources in the original project need to be overridden. If they - do, then project extension is necessary, otherwise, importing is - sufficient. - -  - File: gnat_ug_wnt.info, Node: Project File Syntax, Next: Objects and Sources in Project Files, Prev: Examples of Project Files, Up: GNAT Project Manager - - Project File Syntax - =================== - - * Menu: - - * Basic Syntax:: - * Packages:: - * Expressions:: - * String Types:: - * Variables:: - * Attributes:: - * Associative Array Attributes:: - * case Constructions:: - - This section describes the structure of project files. - - A project may be an _independent project_, entirely defined by a - single project file. Any Ada source file in an independent project - depends only on the predefined library and other Ada source files in - the same project. - - A project may also "depend on" other projects, in either or both of the - following ways: - * It may import any number of projects - - * It may extend at most one other project - - The dependence relation is a directed acyclic graph (the subgraph - reflecting the "extends" relation is a tree). - - A project's "immediate sources" are the source files directly - defined by that project, either implicitly by residing in the project - file's directory, or explicitly through any of the source-related - attributes described below. More generally, a project PROJ's "sources" - are the immediate sources of PROJ together with the immediate sources - (unless overridden) of any project on which PROJ depends (either - directly or indirectly). - -  - File: gnat_ug_wnt.info, Node: Basic Syntax, Next: Packages, Up: Project File Syntax - - Basic Syntax - ------------ - - As seen in the earlier examples, project files have an Ada-like syntax. - The minimal project file is: - project Empty is - - end Empty; - - The identifier `Empty' is the name of the project. This project name - must be present after the reserved word `end' at the end of the project - file, followed by a semi-colon. - - Any name in a project file, such as the project name or a variable - name, has the same syntax as an Ada identifier. - - The reserved words of project files are the Ada reserved words plus - `extends', `external', and `project'. Note that the only Ada reserved - words currently used in project file syntax are: - - * `case' - - * `end' - - * `for' - - * `is' - - * `others' - - * `package' - - * `renames' - - * `type' - - * `use' - - * `when' - - * `with' - - Comments in project files have the same syntax as in Ada, two - consecutives hyphens through the end of the line. - -  - File: gnat_ug_wnt.info, Node: Packages, Next: Expressions, Prev: Basic Syntax, Up: Project File Syntax - - Packages - -------- - - A project file may contain _packages_. The name of a package must be one - of the identifiers (case insensitive) from a predefined list, and a - package with a given name may only appear once in a project file. The - predefined list includes the following packages: - - * `Naming' - - * `Builder' - - * `Compiler' - - * `Binder' - - * `Linker' - - * `Finder' - - * `Cross_Reference' - - * `gnatls' - - (The complete list of the package names and their attributes can be - found in file `prj-attr.adb'). - - In its simplest form, a package may be empty: - - project Simple is - package Builder is - end Builder; - end Simple; - - A package may contain _attribute declarations_, _variable declarations_ - and _case constructions_, as will be described below. - - When there is ambiguity between a project name and a package name, - the name always designates the project. To avoid possible confusion, it - is always a good idea to avoid naming a project with one of the names - allowed for packages or any name that starts with `gnat'. - -  - File: gnat_ug_wnt.info, Node: Expressions, Next: String Types, Prev: Packages, Up: Project File Syntax - - Expressions - ----------- - - An _expression_ is either a _string expression_ or a _string list - expression_. - - A _string expression_ is either a _simple string expression_ or a - _compound string expression_. - - A _simple string expression_ is one of the following: - * A literal string; e.g.`"comm/my_proj.gpr"' - - * A string-valued variable reference (see *Note Variables::) - - * A string-valued attribute reference (see *Note Attributes::) - - * An external reference (see *Note External References in Project - Files::) - - A _compound string expression_ is a concatenation of string expressions, - using `"&"' - Path & "/" & File_Name & ".ads" - - A _string list expression_ is either a _simple string list expression_ - or a _compound string list expression_. - - A _simple string list expression_ is one of the following: - * A parenthesized list of zero or more string expressions, separated - by commas - File_Names := (File_Name, "gnat.adc", File_Name & ".orig"); - Empty_List := (); - - * A string list-valued variable reference - - * A string list-valued attribute reference - - A _compound string list expression_ is the concatenation (using `"&"') - of a simple string list expression and an expression. Note that each - term in a compound string list expression, except the first, may be - either a string expression or a string list expression. - - File_Name_List := () & File_Name; -- One string in this list - Extended_File_Name_List := File_Name_List & (File_Name & ".orig"); - -- Two strings - Big_List := File_Name_List & Extended_File_Name_List; - -- Concatenation of two string lists: three strings - Illegal_List := "gnat.adc" & Extended_File_Name_List; - -- Illegal: must start with a string list - -  - File: gnat_ug_wnt.info, Node: String Types, Next: Variables, Prev: Expressions, Up: Project File Syntax - - String Types - ------------ - - The value of a variable may be restricted to a list of string literals. - The restricted list of string literals is given in a _string type - declaration_. - - Here is an example of a string type declaration: - - type OS is ("NT, "nt", "Unix", "Linux", "other OS"); - - Variables of a string type are called _typed variables_; all other - variables are called _untyped variables_. Typed variables are - particularly useful in `case' constructions (see *Note case - Constructions::). - - A string type declaration starts with the reserved word `type', - followed by the name of the string type (case-insensitive), followed by - the reserved word `is', followed by a parenthesized list of one or more - string literals separated by commas, followed by a semicolon. - - The string literals in the list are case sensitive and must all be - different. They may include any graphic characters allowed in Ada, - including spaces. - - A string type may only be declared at the project level, not inside - a package. - - A string type may be referenced by its name if it has been declared - in the same project file, or by its project name, followed by a dot, - followed by the string type name. - -  - File: gnat_ug_wnt.info, Node: Variables, Next: Attributes, Prev: String Types, Up: Project File Syntax - - Variables - --------- - - A variable may be declared at the project file level, or in a package. - Here are some examples of variable declarations: - - This_OS : OS := external ("OS"); -- a typed variable declaration - That_OS := "Linux"; -- an untyped variable declaration - - A _typed variable declaration_ includes the variable name, followed by - a colon, followed by the name of a string type, followed by `:=', - followed by a simple string expression. - - An _untyped variable declaration_ includes the variable name, - followed by `:=', followed by an expression. Note that, despite the - terminology, this form of "declaration" resembles more an assignment - than a declaration in Ada. It is a declaration in several senses: - * The variable name does not need to be defined previously - - * The declaration establishes the _kind_ (string versus string list) - of the variable, and later declarations of the same variable need - to be consistent with this - - A string variable declaration (typed or untyped) declares a variable - whose value is a string. This variable may be used as a string - expression. - File_Name := "readme.txt"; - Saved_File_Name := File_Name & ".saved"; - - A string list variable declaration declares a variable whose value is a - list of strings. The list may contain any number (zero or more) of - strings. - - Empty_List := (); - List_With_One_Element := ("-gnaty"); - List_With_Two_Elements := List_With_One_Element & "-gnatg"; - Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada" - "pack2.ada", "util_.ada", "util.ada"); - - The same typed variable may not be declared more than once at project - level, and it may not be declared more than once in any package; it is - in effect a constant or a readonly variable. - - The same untyped variable may be declared several times. In this - case, the new value replaces the old one, and any subsequent reference - to the variable uses the new value. However, as noted above, if a - variable has been declared as a string, all subsequent declarations - must give it a string value. Similarly, if a variable has been declared - as a string list, all subsequent declarations must give it a string - list value. - - A _variable reference_ may take several forms: - - * The simple variable name, for a variable in the current package - (if any) or in the current project - - * A context name, followed by a dot, followed by the variable name. - - A _context_ may be one of the following: - - * The name of an existing package in the current project - - * The name of an imported project of the current project - - * The name of an ancestor project (i.e., a project extended by the - current project, either directly or indirectly) - - * An imported/parent project name, followed by a dot, followed by a - package name - - A variable reference may be used in an expression. - -  - File: gnat_ug_wnt.info, Node: Attributes, Next: Associative Array Attributes, Prev: Variables, Up: Project File Syntax - - Attributes - ---------- - - A project (and its packages) may have _attributes_ that define the - project's properties. Some attributes have values that are strings; - others have values that are string lists. - - There are two categories of attributes: _simple attributes_ and - _associative arrays_ (see *Note Associative Array Attributes::). - - The names of the attributes are restricted; there is a list of - project attributes, and a list of package attributes for each package. - The names are not case sensitive. - - The project attributes are as follows (all are simple attributes): - - _Attribute Name_ _Value_ - `Source_Files' string list - `Source_Dirs' string list - `Source_List_File' string - `Object_Dir' string - `Exec_Dir' string - `Main' string list - `Languages' string list - `Library_Dir' string - `Library_Name' string - `Library_Kind' string - `Library_Elaboration' string - `Library_Version' string - - The attributes for package `Naming' are as follows (see *Note Naming - Schemes::): - - Attribute Name Category Index Value - `Specification_Suffix' associative language name string - array - `Implementation_Suffix' associative language name string - array - `Separate_Suffix' simple n/a string - attribute - `Casing' simple n/a string - attribute - `Dot_Replacement' simple n/a string - attribute - `Specification' associative Ada unit name string - array - `Implementation' associative Ada unit name string - array - `Specification_Exceptions' associative language name string list - array - `Implementation_Exceptions' associative language name string list - array - - The attributes for package `Builder', `Compiler', `Binder', `Linker', - `Cross_Reference', and `Finder' are as follows (see *Note Switches and - Project Files::). - - Attribute Name Category Index Value - `Default_Switches' associative language name string list - array - `Switches' associative file name string list - array - - In addition, package `Builder' has a single string attribute - `Local_Configuration_Pragmas' and package `Builder' has a single string - attribute `Global_Configuration_Pragmas'. - - The attribute for package `Glide' are not documented: they are for - internal use only. - - Each simple attribute has a default value: the empty string (for - string-valued attributes) and the empty list (for string list-valued - attributes). - - Similar to variable declarations, an attribute declaration defines a - new value for an attribute. - - Examples of simple attribute declarations: - - for Object_Dir use "objects"; - for Source_Dirs use ("units", "test/drivers"); - - A "simple attribute declaration" starts with the reserved word `for', - followed by the name of the attribute, followed by the reserved word - `use', followed by an expression (whose kind depends on the attribute), - followed by a semicolon. - - Attributes may be referenced in expressions. The general form for - such a reference is `'': the entity for which the - attribute is defined, followed by an apostrophe, followed by the name - of the attribute. For associative array attributes, a litteral string - between parentheses need to be supplied as index. - - Examples are: - - project'Object_Dir - Naming'Dot_Replacement - Imported_Project'Source_Dirs - Imported_Project.Naming'Casing - Builder'Default_Switches("Ada") - - The entity may be: - * `project' for an attribute of the current project - - * The name of an existing package of the current project - - * The name of an imported project - - * The name of a parent project (extended by the current project) - - * An imported/parent project name, followed by a dot, followed - by a package name - - Example: - project Prj is - for Source_Dirs use project'Source_Dirs & "units"; - for Source_Dirs use project'Source_Dirs & "test/drivers" - end Prj; - - In the first attribute declaration, initially the attribute - `Source_Dirs' has the default value: an empty string list. After this - declaration, `Source_Dirs' is a string list of one element: "units". - After the second attribute declaration `Source_Dirs' is a string list of - two elements: "units" and "test/drivers". - - Note: this example is for illustration only. In practice, the - project file would contain only one attribute declaration: - - for Source_Dirs use ("units", "test/drivers"); - -  - File: gnat_ug_wnt.info, Node: Associative Array Attributes, Next: case Constructions, Prev: Attributes, Up: Project File Syntax - - Associative Array Attributes - ---------------------------- - - Some attributes are defined as _associative arrays_. An associative - array may be regarded as a function that takes a string as a parameter - and delivers a string or string list value as its result. - - Here are some examples of associative array attribute declarations: - - for Implementation ("main") use "Main.ada"; - for Switches ("main.ada") use ("-v", "-gnatv"); - for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g"; - - Like untyped variables and simple attributes, associative array - attributes may be declared several times. Each declaration supplies a - new value for the attribute, replacing the previous setting. - -  - File: gnat_ug_wnt.info, Node: case Constructions, Prev: Associative Array Attributes, Up: Project File Syntax - - `case' Constructions - -------------------- - - A `case' construction is used in a project file to effect conditional - behavior. Here is a typical example: - - project MyProj is - type OS_Type is ("Linux", "Unix", "NT", "VMS"); - - OS : OS_Type := external ("OS", "Linux"); - - package Compiler is - case OS is - when "Linux" | "Unix" => - for Default_Switches ("Ada") use ("-gnath"); - when "NT" => - for Default_Switches ("Ada") use ("-gnatP"); - when others => - end case; - end Compiler; - end MyProj; - - The syntax of a `case' construction is based on the Ada case statement - (although there is no `null' construction for empty alternatives). - - Following the reserved word `case' there is the case variable (a - typed string variable), the reserved word `is', and then a sequence of - one or more alternatives. Each alternative comprises the reserved word - `when', either a list of literal strings separated by the `"|"' - character or the reserved word `others', and the `"=>"' token. Each - literal string must belong to the string type that is the type of the - case variable. An `others' alternative, if present, must occur last. - The `end case;' sequence terminates the case construction. - - After each `=>', there are zero or more constructions. The only - constructions allowed in a case construction are other case - constructions and attribute declarations. String type declarations, - variable declarations and package declarations are not allowed. - - The value of the case variable is often given by an external - reference (see *Note External References in Project Files::). - -  - File: gnat_ug_wnt.info, Node: Objects and Sources in Project Files, Next: Importing Projects, Prev: Project File Syntax, Up: GNAT Project Manager - - Objects and Sources in Project Files - ==================================== - - * Menu: - - * Object Directory:: - * Exec Directory:: - * Source Directories:: - * Source File Names:: - - Each project has exactly one object directory and one or more source - directories. The source directories must contain at least one source - file, unless the project file explicitly specifies that no source - files are present (see *Note Source File Names::). - -  - File: gnat_ug_wnt.info, Node: Object Directory, Next: Exec Directory, Up: Objects and Sources in Project Files - - Object Directory - ---------------- - - The object directory for a project is the directory containing the - compiler's output (such as `ALI' files and object files) for the - project's immediate sources. Note that for inherited sources (when - extending a parent project) the parent project's object directory is - used. - - The object directory is given by the value of the attribute - `Object_Dir' in the project file. - - for Object_Dir use "objects"; - - The attribute OBJECT_DIR has a string value, the path name of the object - directory. The path name may be absolute or relative to the directory - of the project file. This directory must already exist, and be readable - and writable. - - By default, when the attribute `Object_Dir' is not given an explicit - value or when its value is the empty string, the object directory is - the same as the directory containing the project file. - -  - File: gnat_ug_wnt.info, Node: Exec Directory, Next: Source Directories, Prev: Object Directory, Up: Objects and Sources in Project Files - - Exec Directory - -------------- - - The exec directory for a project is the directory containing the - executables for the project's main subprograms. - - The exec directory is given by the value of the attribute `Exec_Dir' - in the project file. - - for Exec_Dir use "executables"; - - The attribute EXEC_DIR has a string value, the path name of the exec - directory. The path name may be absolute or relative to the directory - of the project file. This directory must already exist, and be writable. - - By default, when the attribute `Exec_Dir' is not given an explicit - value or when its value is the empty string, the exec directory is the - same as the object directory of the project file. - -  - File: gnat_ug_wnt.info, Node: Source Directories, Next: Source File Names, Prev: Exec Directory, Up: Objects and Sources in Project Files - - Source Directories - ------------------ - - The source directories of a project are specified by the project file - attribute `Source_Dirs'. - - This attribute's value is a string list. If the attribute is not - given an explicit value, then there is only one source directory, the - one where the project file resides. - - A `Source_Dirs' attribute that is explicitly defined to be the empty - list, as in - - for Source_Dirs use (); - - indicates that the project contains no source files. - - Otherwise, each string in the string list designates one or more - source directories. - - for Source_Dirs use ("sources", "test/drivers"); - - If a string in the list ends with `"/**"', then the directory whose - path name precedes the two asterisks, as well as all its subdirectories - (recursively), are source directories. - - for Source_Dirs use ("/system/sources/**"); - - Here the directory `/system/sources' and all of its subdirectories - (recursively) are source directories. - - To specify that the source directories are the directory of the - project file and all of its subdirectories, you can declare - `Source_Dirs' as follows: - for Source_Dirs use ("./**"); - - Each of the source directories must exist and be readable. - -  - File: gnat_ug_wnt.info, Node: Source File Names, Prev: Source Directories, Up: Objects and Sources in Project Files - - Source File Names - ----------------- - - In a project that contains source files, their names may be specified - by the attributes `Source_Files' (a string list) or `Source_List_File' - (a string). Source file names never include any directory information. - - If the attribute `Source_Files' is given an explicit value, then each - element of the list is a source file name. - - for Source_Files use ("main.adb"); - for Source_Files use ("main.adb", "pack1.ads", "pack2.adb"); - - If the attribute `Source_Files' is not given an explicit value, but the - attribute `Source_List_File' is given a string value, then the source - file names are contained in the text file whose path name (absolute or - relative to the directory of the project file) is the value of the - attribute `Source_List_File'. - - Each line in the file that is not empty or is not a comment contains - a source file name. A comment line starts with two hyphens. - - for Source_List_File use "source_list.txt"; - - By default, if neither the attribute `Source_Files' nor the attribute - `Source_List_File' is given an explicit value, then each file in the - source directories that conforms to the project's naming scheme (see - *Note Naming Schemes::) is an immediate source of the project. - - A warning is issued if both attributes `Source_Files' and - `Source_List_File' are given explicit values. In this case, the - attribute `Source_Files' prevails. - - Each source file name must be the name of one and only one existing - source file in one of the source directories. - - A `Source_Files' attribute defined with an empty list as its value - indicates that there are no source files in the project. - - Except for projects that are clearly specified as containing no Ada - source files (`Source_Dirs' or `Source_Files' specified as an empty - list, or `Languages' specified without `"Ada"' in the list) - for Source_Dirs use (); - for Source_Files use (); - for Languages use ("C", "C++"); - - a project must contain at least one immediate source. - - Projects with no source files are useful as template packages (see - *Note Packages in Project Files::) for other projects; in particular to - define a package `Naming' (see *Note Naming Schemes::). - -  - File: gnat_ug_wnt.info, Node: Importing Projects, Next: Project Extension, Prev: Objects and Sources in Project Files, Up: GNAT Project Manager - - Importing Projects - ================== - - An immediate source of a project P may depend on source files that are - neither immediate sources of P nor in the predefined library. To get - this effect, P must _import_ the projects that contain the needed - source files. - - with "project1", "utilities.gpr"; - with "/namings/apex.gpr"; - project Main is - ... - - As can be seen in this example, the syntax for importing projects is - similar to the syntax for importing compilation units in Ada. However, - project files use literal strings instead of names, and the `with' - clause identifies project files rather than packages. - - Each literal string is the file name or path name (absolute or - relative) of a project file. If a string is simply a file name, with no - path, then its location is determined by the _project path_: - - * If the environment variable `ADA_PROJECT_PATH' exists, then the - project path includes all the directories in this environment - variable, plus the directory of the project file. - - * If the environment variable `ADA_PROJECT_PATH' does not exist, - then the project path contains only one directory, namely the one - where the project file is located. - - If a relative pathname is used as in - - with "tests/proj"; - - then the path is relative to the directory where the importing project - file is located. Any symbolic link will be fully resolved in the - directory of the importing project file before the imported project - file is looked up. - - When the `with''ed project file name does not have an extension, the - default is `.gpr'. If a file with this extension is not found, then the - file name as specified in the `with' clause (no extension) will be - used. In the above example, if a file `project1.gpr' is found, then it - will be used; otherwise, if a file `project1' exists then it will be - used; if neither file exists, this is an error. - - A warning is issued if the name of the project file does not match - the name of the project; this check is case insensitive. - - Any source file that is an immediate source of the imported project - can be used by the immediate sources of the importing project, and - recursively. Thus if `A' imports `B', and `B' imports `C', the immediate - sources of `A' may depend on the immediate sources of `C', even if `A' - does not import `C' explicitly. However, this is not recommended, - because if and when `B' ceases to import `C', some sources in `A' will - no longer compile. - - A side effect of this capability is that cyclic dependences are not - permitted: if `A' imports `B' (directly or indirectly) then `B' is not - allowed to import `A'. - -  - File: gnat_ug_wnt.info, Node: Project Extension, Next: External References in Project Files, Prev: Importing Projects, Up: GNAT Project Manager - - Project Extension - ================= - - During development of a large system, it is sometimes necessary to use - modified versions of some of the source files without changing the - original sources. This can be achieved through a facility known as - _project extension_. - - project Modified_Utilities extends "/baseline/utilities.gpr" is ... - - The project file for the project being extended (the _parent_) is - identified by the literal string that follows the reserved word - `extends', which itself follows the name of the extending project (the - _child_). - - By default, a child project inherits all the sources of its parent. - However, inherited sources can be overridden: a unit with the same name - as one in the parent will hide the original unit. Inherited sources - are considered to be sources (but not immediate sources) of the child - project; see *Note Project File Syntax::. - - An inherited source file retains any switches specified in the - parent project. - - For example if the project `Utilities' contains the specification - and the body of an Ada package `Util_IO', then the project - `Modified_Utilities' can contain a new body for package `Util_IO'. The - original body of `Util_IO' will not be considered in program builds. - However, the package specification will still be found in the project - `Utilities'. - - A child project can have only one parent but it may import any - number of other projects. - - A project is not allowed to import directly or indirectly at the - same time a child project and any of its ancestors. - -  - File: gnat_ug_wnt.info, Node: External References in Project Files, Next: Packages in Project Files, Prev: Project Extension, Up: GNAT Project Manager - - External References in Project Files - ==================================== - - A project file may contain references to external variables; such - references are called _external references_. - - An external variable is either defined as part of the environment (an - environment variable in Unix, for example) or else specified on the - command line via the `-X_vbl_=_value_' switch. If both, then the - command line value is used. - - An external reference is denoted by the built-in function - `external', which returns a string value. This function has two forms: - * `external (external_variable_name)' - - * `external (external_variable_name, default_value)' - - Each parameter must be a string literal. For example: - - external ("USER") - external ("OS", "Linux") - - In the form with one parameter, the function returns the value of the - external variable given as parameter. If this name is not present in the - environment, then the returned value is an empty string. - - In the form with two string parameters, the second parameter is the - value returned when the variable given as the first parameter is not - present in the environment. In the example above, if `"OS"' is not the - name of an environment variable and is not passed on the command line, - then the returned value will be `"Linux"'. - - An external reference may be part of a string expression or of a - string list expression, to define variables or attributes. - - type Mode_Type is ("Debug", "Release"); - Mode : Mode_Type := external ("MODE"); - case Mode is - when "Debug" => - ... - -  - File: gnat_ug_wnt.info, Node: Packages in Project Files, Next: Variables from Imported Projects, Prev: External References in Project Files, Up: GNAT Project Manager - - Packages in Project Files - ========================= - - The _package_ is the project file feature that defines the settings for - project-aware tools. For each such tool you can declare a - corresponding package; the names for these packages are preset (see - *Note Packages::) but are not case sensitive. A package may contain - variable declarations, attribute declarations, and case constructions. - - project Proj is - package Builder is -- used by gnatmake - for Default_Switches ("Ada") use ("-v", "-g"); - end Builder; - end Proj; - - A package declaration starts with the reserved word `package', followed - by the package name (case insensitive), followed by the reserved word - `is'. It ends with the reserved word `end', followed by the package - name, finally followed by a semi-colon. - - Most of the packages have an attribute `Default_Switches'. This - attribute is an associative array, and its value is a string list. The - index of the associative array is the name of a programming language - (case insensitive). This attribute indicates the switch or switches to - be used with the corresponding tool. - - Some packages also have another attribute, `Switches', an associative - array whose value is a string list. The index is the name of a source - file. This attribute indicates the switch or switches to be used by - the corresponding tool when dealing with this specific file. - - Further information on these switch-related attributes is found in - *Note Switches and Project Files::. - - A package may be declared as a _renaming_ of another package; e.g., - from the project file for an imported project. - - with "/global/apex.gpr"; - project Example is - package Naming renames Apex.Naming; - ... - end Example; - - Packages that are renamed in other project files often come from - project files that have no sources: they are just used as templates. - Any modification in the template will be reflected automatically in all - the project files that rename a package from the template. - - In addition to the tool-oriented packages, you can also declare a - package named `Naming' to establish specialized source file naming - conventions (see *Note Naming Schemes::). - -  - File: gnat_ug_wnt.info, Node: Variables from Imported Projects, Next: Naming Schemes, Prev: Packages in Project Files, Up: GNAT Project Manager - - Variables from Imported Projects - ================================ - - An attribute or variable defined in an imported or parent project can - be used in expressions in the importing / extending project. Such an - attribute or variable is prefixed with the name of the project and (if - relevant) the name of package where it is defined. - - with "imported"; - project Main extends "base" is - Var1 := Imported.Var; - Var2 := Base.Var & ".new"; - - package Builder is - for Default_Switches ("Ada") use Imported.Builder.Ada_Switches & - "-gnatg" & "-v"; - end Builder; - - package Compiler is - for Default_Switches ("Ada") use Base.Compiler.Ada_Switches; - end Compiler; - end Main; - - In this example: - - * `Var1' is a copy of the variable `Var' defined in the project file - `"imported.gpr"' - - * the value of `Var2' is a copy of the value of variable `Var' - defined in the project file `base.gpr', concatenated with `".new"' - - * attribute `Default_Switches ("Ada")' in package `Builder' is a - string list that includes in its value a copy of variable - `Ada_Switches' defined in the `Builder' package in project file - `imported.gpr' plus two new elements: `"-gnatg"' and `"-v"'; - - * attribute `Default_Switches ("Ada")' in package `Compiler' is a - copy of the variable `Ada_Switches' defined in the `Compiler' - package in project file `base.gpr', the project being extended. - -  - File: gnat_ug_wnt.info, Node: Naming Schemes, Next: Library Projects, Prev: Variables from Imported Projects, Up: GNAT Project Manager - - Naming Schemes - ============== - - Sometimes an Ada software system is ported from a foreign compilation - environment to GNAT, with file names that do not use the default GNAT - conventions. Instead of changing all the file names (which for a - variety of reasons might not be possible), you can define the relevant - file naming scheme in the `Naming' package in your project file. For - example, the following package models the Apex file naming rules: - - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "."; - for Specification_Suffix ("Ada") use ".1.ada"; - for Implementation_Suffix ("Ada") use ".2.ada"; - end Naming; - - You can define the following attributes in package `Naming': - - `CASING' - This must be a string with one of the three values `"lowercase"', - `"uppercase"' or `"mixedcase"'; these strings are case insensitive. - - If CASING is not specified, then the default is `"lowercase"'. - - `DOT_REPLACEMENT' - This must be a string whose value satisfies the following - conditions: - - * It must not be empty - - * It cannot start or end with an alphanumeric character - - * It cannot be a single underscore - - * It cannot start with an underscore followed by an alphanumeric - - * It cannot contain a dot `'.'' except if it the entire string - is `"."' - - If `Dot_Replacement' is not specified, then the default is `"-"'. - - `SPECIFICATION_SUFFIX' - This is an associative array (indexed by the programming language - name, case insensitive) whose value is a string that must satisfy - the following conditions: - - * It must not be empty - - * It cannot start with an alphanumeric character - - * It cannot start with an underscore followed by an - alphanumeric character - - If `Specification_Suffix ("Ada")' is not specified, then the - default is `".ads"'. - - `IMPLEMENTATION_SUFFIX' - This is an associative array (indexed by the programming language - name, case insensitive) whose value is a string that must satisfy - the following conditions: - - * It must not be empty - - * It cannot start with an alphanumeric character - - * It cannot start with an underscore followed by an - alphanumeric character - - * It cannot be a suffix of `Specification_Suffix' - - If `Implementation_Suffix ("Ada")' is not specified, then the - default is `".adb"'. - - `SEPARATE_SUFFIX' - This must be a string whose value satisfies the same conditions as - `Implementation_Suffix'. - - If `Separate_Suffix ("Ada")' is not specified, then it defaults to - same value as `Implementation_Suffix ("Ada")'. - - `SPECIFICATION' - You can use the `Specification' attribute, an associative array, - to define the source file name for an individual Ada compilation - unit's spec. The array index must be a string literal that - identifies the Ada unit (case insensitive). The value of this - attribute must be a string that identifies the file that contains - this unit's spec (case sensitive or insensitive depending on the - operating system). - - for Specification ("MyPack.MyChild") use "mypack.mychild.spec"; - - `IMPLEMENTATION' - You can use the `Implementation' attribute, an associative array, - to define the source file name for an individual Ada compilation - unit's body (possibly a subunit). The array index must be a - string literal that identifies the Ada unit (case insensitive). - The value of this attribute must be a string that identifies the - file that contains this unit's body or subunit (case sensitive or - insensitive depending on the operating system). - - for Implementation ("MyPack.MyChild") use "mypack.mychild.body"; - -  - File: gnat_ug_wnt.info, Node: Library Projects, Next: Switches Related to Project Files, Prev: Naming Schemes, Up: GNAT Project Manager - - Library Projects - ================ - - _Library projects_ are projects whose object code is placed in a - library. (Note that this facility is not yet supported on all - platforms) - - To create a library project, you need to define in its project file - two project-level attributes: `Library_Name' and `Library_Dir'. - Additionally, you may define the library-related attributes - `Library_Kind', `Library_Version' and `Library_Elaboration'. - - The `Library_Name' attribute has a string value that must start with - a letter and include only letters and digits. - - The `Library_Dir' attribute has a string value that designates the - path (absolute or relative) of the directory where the library will - reside. It must designate an existing directory, and this directory - needs to be different from the project's object directory. It also - needs to be writable. - - If both `Library_Name' and `Library_Dir' are specified and are - legal, then the project file defines a library project. The optional - library-related attributes are checked only for such project files. - - The `Library_Kind' attribute has a string value that must be one of - the following (case insensitive): `"static"', `"dynamic"' or - `"relocatable"'. If this attribute is not specified, the library is a - static library. Otherwise, the library may be dynamic or relocatable. - Depending on the operating system, there may or may not be a distinction - between dynamic and relocatable libraries. For example, on Unix there - is no such distinction. - - The `Library_Version' attribute has a string value whose - interpretation is platform dependent. On Unix, it is used only for - dynamic/relocatable libraries as the internal name of the library (the - `"soname"'). If the library file name (built from the `Library_Name') - is different from the `Library_Version', then the library file will be - a symbolic link to the actual file whose name will be `Library_Version'. - - Example (on Unix): - - project Plib is - - Version := "1"; - - for Library_Dir use "lib_dir"; - for Library_Name use "dummy"; - for Library_Kind use "relocatable"; - for Library_Version use "libdummy.so." & Version; - - end Plib; - - Directory `lib_dir' will contain the internal library file whose name - will be `libdummy.so.1', and `libdummy.so' will be a symbolic link to - `libdummy.so.1'. - - When `gnatmake' detects that a project file (not the main project - file) is a library project file, it will check all immediate sources of - the project and rebuild the library if any of the sources have been - recompiled. All `ALI' files will also be copied from the object - directory to the library directory. To build executables, `gnatmake' - will use the library rather than the individual object files. - -  - File: gnat_ug_wnt.info, Node: Switches Related to Project Files, Next: Tools Supporting Project Files, Prev: Library Projects, Up: GNAT Project Manager - - Switches Related to Project Files - ================================= - - The following switches are used by GNAT tools that support project - files: - - ``-PPROJECT'' - Indicates the name of a project file. This project file will be - parsed with the verbosity indicated by `-vP_x_', if any, and using - the external references indicated by `-X' switches, if any. - - There must be only one `-P' switch on the command line. - - Since the Project Manager parses the project file only after all - the switches on the command line are checked, the order of the - switches `-P', `-Vp_x_' or `-X' is not significant. - - ``-XNAME=VALUE'' - Indicates that external variable NAME has the value VALUE. The - Project Manager will use this value for occurrences of - `external(name)' when parsing the project file. - - If NAME or VALUE includes a space, then NAME=VALUE should be put - between quotes. - -XOS=NT - -X"user=John Doe" - - Several `-X' switches can be used simultaneously. If several `-X' - switches specify the same NAME, only the last one is used. - - An external variable specified with a `-X' switch takes precedence - over the value of the same name in the environment. - - ``-vP_x_'' - Indicates the verbosity of the parsing of GNAT project files. - `-vP0' means Default (no output for syntactically correct project - files); `-vP1' means Medium; `-vP2' means High. - - The default is Default. - - If several `-vP_x_' switches are present, only the last one is - used. - -  - File: gnat_ug_wnt.info, Node: Tools Supporting Project Files, Next: An Extended Example, Prev: Switches Related to Project Files, Up: GNAT Project Manager - - Tools Supporting Project Files - ============================== - - * Menu: - - * gnatmake and Project Files:: - * The GNAT Driver and Project Files:: - * Glide and Project Files:: - -  - File: gnat_ug_wnt.info, Node: gnatmake and Project Files, Next: The GNAT Driver and Project Files, Up: Tools Supporting Project Files - - gnatmake and Project Files - -------------------------- - - This section covers two topics related to `gnatmake' and project files: - defining switches for `gnatmake' and for the tools that it invokes; and - the use of the `Main' attribute. - - * Menu: - - * Switches and Project Files:: - * Project Files and Main Subprograms:: - -  - File: gnat_ug_wnt.info, Node: Switches and Project Files, Next: Project Files and Main Subprograms, Up: gnatmake and Project Files - - Switches and Project Files - .......................... - - For each of the packages `Builder', `Compiler', `Binder', and `Linker', - you can specify a `Default_Switches' attribute, a `Switches' attribute, - or both; as their names imply, these switch-related attributes affect - which switches are used for which files when `gnatmake' is invoked. As - will be explained below, these package-contributed switches precede the - switches passed on the `gnatmake' command line. - - The `Default_Switches' attribute is an associative array indexed by - language name (case insensitive) and returning a string list. For - example: - - package Compiler is - for Default_Switches ("Ada") use ("-gnaty", "-v"); - end Compiler; - - The `Switches' attribute is also an associative array, indexed by a file - name (which may or may not be case sensitive, depending on the operating - system) and returning a string list. For example: - - package Builder is - for Switches ("main1.adb") use ("-O2"); - for Switches ("main2.adb") use ("-g"); - end Builder; - - For the `Builder' package, the file names should designate source files - for main subprograms. For the `Binder' and `Linker' packages, the file - names should designate `ALI' or source files for main subprograms. In - each case just the file name (without explicit extension) is acceptable. - - For each tool used in a program build (`gnatmake', the compiler, the - binder, and the linker), its corresponding package "contributes" a set - of switches for each file on which the tool is invoked, based on the - switch-related attributes defined in the package. In particular, the - switches that each of these packages contributes for a given file F - comprise: - - * the value of attribute `Switches (F)', if it is specified in the - package for the given file, - - * otherwise, the value of `Default_Switches ("Ada")', if it is - specified in the package. - - If neither of these attributes is defined in the package, then the - package does not contribute any switches for the given file. - - When `gnatmake' is invoked on a file, the switches comprise two sets, - in the following order: those contributed for the file by the `Builder' - package; and the switches passed on the command line. - - When `gnatmake' invokes a tool (compiler, binder, linker) on a file, - the switches passed to the tool comprise three sets, in the following - order: - - 1. the applicable switches contributed for the file by the `Builder' - package in the project file supplied on the command line; - - 2. those contributed for the file by the package (in the relevant - project file - see below) corresponding to the tool; and - - 3. the applicable switches passed on the command line. - - The term _applicable switches_ reflects the fact that `gnatmake' - switches may or may not be passed to individual tools, depending on the - individual switch. - - `gnatmake' may invoke the compiler on source files from different - projects. The Project Manager will use the appropriate project file to - determine the `Compiler' package for each source file being compiled. - Likewise for the `Binder' and `Linker' packages. - - As an example, consider the following package in a project file: - - project Proj1 is - package Compiler is - for Default_Switches ("Ada") use ("-g"); - for Switches ("a.adb") use ("-O1"); - for Switches ("b.adb") use ("-O2", "-gnaty"); - end Compiler; - end Proj1; - - If `gnatmake' is invoked with this project file, and it needs to - compile, say, the files `a.adb', `b.adb', and `c.adb', then `a.adb' - will be compiled with the switch `-O1', `b.adb' with switches `-O2' and - `-gnaty', and `c.adb' with `-g'. - - Another example illustrates the ordering of the switches contributed - by different packages: - - project Proj2 is - package Builder is - for Switches ("main.adb") use ("-g", "-O1", "-f"); - end Builder; - - package Compiler is - for Switches ("main.adb") use ("-O2"); - end Compiler; - end Proj2; - - If you issue the command: - - gnatmake -PProj2 -O0 main - - then the compiler will be invoked on `main.adb' with the following - sequence of switches - - -g -O1 -O2 -O0 - - with the last `-O' switch having precedence over the earlier ones; - several other switches (such as `-c') are added implicitly. - - The switches `-g' and `-O1' are contributed by package `Builder', - `-O2' is contributed by the package `Compiler' and `-O0' comes from the - command line. - - The `-g' switch will also be passed in the invocation of `gnatlink.' - - A final example illustrates switch contributions from packages in - different project files: - - project Proj3 is - for Source_Files use ("pack.ads", "pack.adb"); - package Compiler is - for Default_Switches ("Ada") use ("-gnata"); - end Compiler; - end Proj3; - - with "Proj3"; - project Proj4 is - for Source_Files use ("foo_main.adb", "bar_main.adb"); - package Builder is - for Switches ("foo_main.adb") use ("-s", "-g"); - end Builder; - end Proj4; - - -- Ada source file: - with Pack; - procedure Foo_Main is - ... - end Foo_Main; - - If the command is - gnatmake -PProj4 foo_main.adb -cargs -gnato - - then the switches passed to the compiler for `foo_main.adb' are `-g' - (contributed by the package `Proj4.Builder') and `-gnato' (passed on - the command line). When the imported package `Pack' is compiled, the - switches used are `-g' from `Proj4.Builder', `-gnata' (contributed from - package `Proj3.Compiler', and `-gnato' from the command line. - -  - File: gnat_ug_wnt.info, Node: Project Files and Main Subprograms, Prev: Switches and Project Files, Up: gnatmake and Project Files - - Project Files and Main Subprograms - .................................. - - When using a project file, you can invoke `gnatmake' with several main - subprograms, by specifying their source files on the command line. - Each of these needs to be an immediate source file of the project. - - gnatmake -Pprj main1 main2 main3 - - When using a project file, you can also invoke `gnatmake' without - explicitly specifying any main, and the effect depends on whether you - have defined the `Main' attribute. This attribute has a string list - value, where each element in the list is the name of a source file (the - file extension is optional) containing a main subprogram. - - If the `Main' attribute is defined in a project file as a non-empty - string list and the switch `-u' is not used on the command line, then - invoking `gnatmake' with this project file but without any main on the - command line is equivalent to invoking `gnatmake' with all the file - names in the `Main' attribute on the command line. - - Example: - project Prj is - for Main use ("main1", "main2", "main3"); - end Prj; - - With this project file, `"gnatmake -Pprj"' is equivalent to `"gnatmake - -Pprj main1 main2 main3"'. - - When the project attribute `Main' is not specified, or is specified - as an empty string list, or when the switch `-u' is used on the command - line, then invoking `gnatmake' with no main on the command line will - result in all immediate sources of the project file being checked, and - potentially recompiled. Depending on the presence of the switch `-u', - sources from other project files on which the immediate sources of the - main project file depend are also checked and potentially recompiled. - In other words, the `-u' switch is applied to all of the immediate - sources of themain project file. - -  - File: gnat_ug_wnt.info, Node: The GNAT Driver and Project Files, Next: Glide and Project Files, Prev: gnatmake and Project Files, Up: Tools Supporting Project Files - - The GNAT Driver and Project Files - --------------------------------- - - A number of GNAT tools, other than `gnatmake' are project-aware: - `gnatbind', `gnatfind', `gnatlink', `gnatls' and `gnatxref'. However, - none of these tools can be invoked directly with a project file switch - (`-P'). They need to be invoke through the `gnat' driver. - - The `gnat' driver is a front-end that accepts a number of commands - and call the corresponding tool. It has been designed initially for VMS - to convert VMS style qualifiers to Unix style switches, but it is now - available to all the GNAT supported platforms. - - On non VMS platforms, the `gnat' driver accepts the following - commands (case insensitive): - - * BIND to invoke `gnatbind' - - * CHOP to invoke `gnatchop' - - * COMP or COMPILE to invoke the compiler - - * ELIM to invoke `gnatelim' - - * FIND to invoke `gnatfind' - - * KR or KRUNCH to invoke `gnatkr' - - * LINK to invoke `gnatlink' - - * LS or LIST to invoke `gnatls' - - * MAKE to invoke `gnatmake' - - * NAME to invoke `gnatname' - - * PREP or PREPROCESS to invoke `gnatprep' - - * PSTA or STANDARD to invoke `gnatpsta' - - * STUB to invoke `gnatstub' - - * XREF to invoke `gnatxref' - - Note that the compiler is invoked using the command `gnatmake -f -u'. - - Following the command, you may put switches and arguments for the - invoked tool. - - gnat bind -C main.ali - gnat ls -a main - gnat chop foo.txt - - In addition, for command BIND, FIND, LS or LIST, LINK and XREF, the - project file related switches (`-P', `-X' and `-vPx') may be used in - addition to the switches of the invoking tool. - - For each of these command, there is possibly a package in the main - project that corresponds to the invoked tool. - - * package `Binder' for command BIND (invoking `gnatbind') - - * package `Finder' for command FIND (invoking `gnatfind') - - * package `Gnatls' for command LS or LIST (invoking `gnatls') - - * package `Linker' for command LINK (invoking `gnatlink') - - * package `Cross_Reference' for command XREF (invoking `gnatlink') - - - Package `Gnatls' has a unique attribute `Switches', a simple variable - with a string list value. It contains switches for the invocation of - `gnatls'. - - project Proj1 is - package gnatls is - for Switches use ("-a", "-v"); - end gnatls; - end Proj1; - - All other packages contains a switch `Default_Switches', an associative - array, indexed by the programming language (case insensitive) and - having a string list value. `Default_Switches ("Ada")' contains the - switches for the invocation of the tool corresponding to the package. - - project Proj is - - for Source_Dirs use ("./**"); - - package gnatls is - for Switches use ("-a", "-v"); - end gnatls; - - package Binder is - for Default_Switches ("Ada") use ("-C", "-e"); - end Binder; - - package Linker is - for Default_Switches ("Ada") use ("-C"); - end Linker; - - package Finder is - for Default_Switches ("Ada") use ("-a", "-f"); - end Finder; - - package Cross_Reference is - for Default_Switches ("Ada") use ("-a", "-f", "-d", "-u"); - end Cross_Reference; - end Proj; - - With the above project file, commands such as - - gnat ls -Pproj main - gnat xref -Pproj main - gnat bind -Pproj main.ali - - will set up the environment properly and invoke the tool with the - switches found in the package corresponding to the tool. - -  - File: gnat_ug_wnt.info, Node: Glide and Project Files, Prev: The GNAT Driver and Project Files, Up: Tools Supporting Project Files - - Glide and Project Files - ----------------------- - - Glide will automatically recognize the `.gpr' extension for project - files, and will convert them to its own internal format automatically. - However, it doesn't provide a syntax-oriented editor for modifying these - files. The project file will be loaded as text when you select the - menu item `Ada' => `Project' => `Edit'. You can edit this text and - save the `gpr' file; when you next select this project file in Glide it - will be automatically reloaded. - -  - File: gnat_ug_wnt.info, Node: An Extended Example, Next: Project File Complete Syntax, Prev: Tools Supporting Project Files, Up: GNAT Project Manager - - An Extended Example - =================== - - Suppose that we have two programs, PROG1 and PROG2, with the sources in - the respective directories. We would like to build them with a single - `gnatmake' command, and we would like to place their object files into - `.build' subdirectories of the source directories. Furthermore, we would - like to have to have two separate subdirectories in `.build' - - `release' and `debug' - which will contain the object files compiled - with different set of compilation flags. - - In other words, we have the following structure: - - main - |- prog1 - | |- .build - | | debug - | | release - |- prog2 - |- .build - | debug - | release - - Here are the project files that we need to create in a directory `main' - to maintain this structure: - - 1. We create a `Common' project with a package `Compiler' that - specifies the compilation switches: - - File "common.gpr": - project Common is - - for Source_Dirs use (); -- No source files - - type Build_Type is ("release", "debug"); - Build : Build_Type := External ("BUILD", "debug"); - package Compiler is - case Build is - when "release" => - for Default_Switches ("Ada") use ("-O2"); - when "debug" => - for Default_Switches ("Ada") use ("-g"); - end case; - end Compiler; - - end Common; - - 2. We create separate projects for the two programs: - - File "prog1.gpr": - - with "common"; - project Prog1 is - - for Source_Dirs use ("prog1"); - for Object_Dir use "prog1/.build/" & Common.Build; - - package Compiler renames Common.Compiler; - - end Prog1; - - File "prog2.gpr": - - with "common"; - project Prog2 is - - for Source_Dirs use ("prog2"); - for Object_Dir use "prog2/.build/" & Common.Build; - - package Compiler renames Common.Compiler; - end Prog2; - - 3. We create a wrapping project MAIN: - - File "main.gpr": - - with "common"; - with "prog1"; - with "prog2"; - project Main is - - package Compiler renames Common.Compiler; - - end Main; - - 4. Finally we need to create a dummy procedure that `with's (either - explicitly or implicitly) all the sources of our two programs. - - - Now we can build the programs using the command - - gnatmake -Pmain dummy - - for the Debug mode, or - - gnatmake -Pmain -XBUILD=release - - for the Release mode. - -  - File: gnat_ug_wnt.info, Node: Project File Complete Syntax, Prev: An Extended Example, Up: GNAT Project Manager - - Project File Complete Syntax - ============================ - - project ::= - context_clause project_declaration - - context_clause ::= - {with_clause} - - with_clause ::= - with literal_string { , literal_string } ; - - project_declaration ::= - project simple_name [ extends literal_string ] is - {declarative_item} - end simple_name; - - declarative_item ::= - package_declaration | - typed_string_declaration | - other_declarative_item - - package_declaration ::= - package simple_name package_completion - - package_completion ::= - package_body | package_renaming - - package body ::= - is - {other_declarative_item} - end simple_name ; - - package_renaming ::== - renames simple_name.simple_name ; - - typed_string_declaration ::= - type _simple_name is - ( literal_string {, literal_string} ); - - other_declarative_item ::= - attribute_declaration | - typed_variable_declaration | - variable_declaration | - case_construction - - attribute_declaration ::= - for attribute use expression ; - - attribute ::= - simple_name | - simple_name ( literal_string ) - - typed_variable_declaration ::= - simple_name : name := string_expression ; - - variable_declaration ::= - simple_name := expression; - - expression ::= - term {& term} - - term ::= - literal_string | - string_list | - name | - external_value | - attribute_reference - - literal_string ::= - (same as Ada) - - string_list ::= - ( expression { , expression } ) - - external_value ::= - external ( literal_string [, literal_string] ) - - attribute_reference ::= - attribute_parent ' simple_name [ ( literal_string ) ] - - attribute_parent ::= - project | - simple_name | - simple_name . simple_name - - case_construction ::= - case name is - {case_item} - end case ; - - case_item ::= - when discrete_choice_list => {case_construction | attribute_declaration} - - discrete_choice_list ::= - literal_string {| literal_string} - - name ::= - simple_name {. simple_name} - - simple_name ::= - identifier (same as Ada) - -  - File: gnat_ug_wnt.info, Node: Elaboration Order Handling in GNAT, Next: The Cross-Referencing Tools gnatxref and gnatfind, Prev: GNAT Project Manager, Up: Top - - Elaboration Order Handling in GNAT - ********************************** - - * Menu: - - * Elaboration Code in Ada 95:: - * Checking the Elaboration Order in Ada 95:: - * Controlling the Elaboration Order in Ada 95:: - * Controlling Elaboration in GNAT - Internal Calls:: - * Controlling Elaboration in GNAT - External Calls:: - * Default Behavior in GNAT - Ensuring Safety:: - * Elaboration Issues for Library Tasks:: - * Mixing Elaboration Models:: - * What to Do If the Default Elaboration Behavior Fails:: - * Elaboration for Access-to-Subprogram Values:: - * Summary of Procedures for Elaboration Control:: - * Other Elaboration Order Considerations:: - - This chapter describes the handling of elaboration code in Ada 95 and - in GNAT, and discusses how the order of elaboration of program units can - be controlled in GNAT, either automatically or with explicit programming - features. - -  - File: gnat_ug_wnt.info, Node: Elaboration Code in Ada 95, Next: Checking the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Elaboration Code in Ada 95 - ========================== - - Ada 95 provides rather general mechanisms for executing code at - elaboration time, that is to say before the main program starts - executing. Such code arises in three contexts: - - Initializers for variables. - Variables declared at the library level, in package specs or - bodies, can require initialization that is performed at - elaboration time, as in: - Sqrt_Half : Float := Sqrt (0.5); - - Package initialization code - Code in a `BEGIN-END' section at the outer level of a package body - is executed as part of the package body elaboration code. - - Library level task allocators - Tasks that are declared using task allocators at the library level - start executing immediately and hence can execute at elaboration - time. - - Subprogram calls are possible in any of these contexts, which means that - any arbitrary part of the program may be executed as part of the - elaboration code. It is even possible to write a program which does all - its work at elaboration time, with a null main program, although - stylistically this would usually be considered an inappropriate way to - structure a program. - - An important concern arises in the context of elaboration code: we - have to be sure that it is executed in an appropriate order. What we - have is a series of elaboration code sections, potentially one section - for each unit in the program. It is important that these execute in the - correct order. Correctness here means that, taking the above example of - the declaration of `Sqrt_Half', if some other piece of elaboration code - references `Sqrt_Half', then it must run after the section of - elaboration code that contains the declaration of `Sqrt_Half'. - - There would never be any order of elaboration problem if we made a - rule that whenever you `with' a unit, you must elaborate both the spec - and body of that unit before elaborating the unit doing the `with''ing: - - with Unit_1; - package Unit_2 is ... - - would require that both the body and spec of `Unit_1' be elaborated - before the spec of `Unit_2'. However, a rule like that would be far too - restrictive. In particular, it would make it impossible to have routines - in separate packages that were mutually recursive. - - You might think that a clever enough compiler could look at the - actual elaboration code and determine an appropriate correct order of - elaboration, but in the general case, this is not possible. Consider - the following example. - - In the body of `Unit_1', we have a procedure `Func_1' that references - the variable `Sqrt_1', which is declared in the elaboration code of the - body of `Unit_1': - - Sqrt_1 : Float := Sqrt (0.1); - - The elaboration code of the body of `Unit_1' also contains: - - if expression_1 = 1 then - Q := Unit_2.Func_2; - end if; - - `Unit_2' is exactly parallel, it has a procedure `Func_2' that - references the variable `Sqrt_2', which is declared in the elaboration - code of the body `Unit_2': - - Sqrt_2 : Float := Sqrt (0.1); - - The elaboration code of the body of `Unit_2' also contains: - - if expression_2 = 2 then - Q := Unit_1.Func_1; - end if; - - Now the question is, which of the following orders of elaboration is - acceptable: - - Spec of Unit_1 - Spec of Unit_2 - Body of Unit_1 - Body of Unit_2 - - or - - Spec of Unit_2 - Spec of Unit_1 - Body of Unit_2 - Body of Unit_1 - - If you carefully analyze the flow here, you will see that you cannot - tell at compile time the answer to this question. If `expression_1' is - not equal to 1, and `expression_2' is not equal to 2, then either order - is acceptable, because neither of the function calls is executed. If - both tests evaluate to true, then neither order is acceptable and in - fact there is no correct order. - - If one of the two expressions is true, and the other is false, then - one of the above orders is correct, and the other is incorrect. For - example, if `expression_1' = 1 and `expression_2' /= 2, then the call - to `Func_2' will occur, but not the call to `Func_1.' This means that - it is essential to elaborate the body of `Unit_1' before the body of - `Unit_2', so the first order of elaboration is correct and the second - is wrong. - - By making `expression_1' and `expression_2' depend on input data, or - perhaps the time of day, we can make it impossible for the compiler or - binder to figure out which of these expressions will be true, and hence - it is impossible to guarantee a safe order of elaboration at run time. - -  - File: gnat_ug_wnt.info, Node: Checking the Elaboration Order in Ada 95, Next: Controlling the Elaboration Order in Ada 95, Prev: Elaboration Code in Ada 95, Up: Elaboration Order Handling in GNAT - - Checking the Elaboration Order in Ada 95 - ======================================== - - In some languages that involve the same kind of elaboration problems, - e.g. Java and C++, the programmer is expected to worry about these - ordering problems himself, and it is common to write a program in which - an incorrect elaboration order gives surprising results, because it - references variables before they are initialized. Ada 95 is designed - to be a safe language, and a programmer-beware approach is clearly not - sufficient. Consequently, the language provides three lines of defense: - - Standard rules - Some standard rules restrict the possible choice of elaboration - order. In particular, if you `with' a unit, then its spec is always - elaborated before the unit doing the `with'. Similarly, a parent - spec is always elaborated before the child spec, and finally a - spec is always elaborated before its corresponding body. - - Dynamic elaboration checks - Dynamic checks are made at run time, so that if some entity is - accessed before it is elaborated (typically by means of a - subprogram call) then the exception (`Program_Error') is raised. - - Elaboration control - Facilities are provided for the programmer to specify the desired - order of elaboration. - - Let's look at these facilities in more detail. First, the rules for - dynamic checking. One possible rule would be simply to say that the - exception is raised if you access a variable which has not yet been - elaborated. The trouble with this approach is that it could require - expensive checks on every variable reference. Instead Ada 95 has two - rules which are a little more restrictive, but easier to check, and - easier to state: - - Restrictions on calls - A subprogram can only be called at elaboration time if its body - has been elaborated. The rules for elaboration given above - guarantee that the spec of the subprogram has been elaborated - before the call, but not the body. If this rule is violated, then - the exception `Program_Error' is raised. - - Restrictions on instantiations - A generic unit can only be instantiated if the body of the generic - unit has been elaborated. Again, the rules for elaboration given - above guarantee that the spec of the generic unit has been - elaborated before the instantiation, but not the body. If this - rule is violated, then the exception `Program_Error' is raised. - - The idea is that if the body has been elaborated, then any variables it - references must have been elaborated; by checking for the body being - elaborated we guarantee that none of its references causes any trouble. - As we noted above, this is a little too restrictive, because a - subprogram that has no non-local references in its body may in fact be - safe to call. However, it really would be unsafe to rely on this, - because it would mean that the caller was aware of details of the - implementation in the body. This goes against the basic tenets of Ada. - - A plausible implementation can be described as follows. A Boolean - variable is associated with each subprogram and each generic unit. This - variable is initialized to False, and is set to True at the point body - is elaborated. Every call or instantiation checks the variable, and - raises `Program_Error' if the variable is False. - - Note that one might think that it would be good enough to have one - Boolean variable for each package, but that would not deal with cases - of trying to call a body in the same package as the call that has not - been elaborated yet. Of course a compiler may be able to do enough - analysis to optimize away some of the Boolean variables as unnecessary, - and `GNAT' indeed does such optimizations, but still the easiest - conceptual model is to think of there being one variable per subprogram. - -  - File: gnat_ug_wnt.info, Node: Controlling the Elaboration Order in Ada 95, Next: Controlling Elaboration in GNAT - Internal Calls, Prev: Checking the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Controlling the Elaboration Order in Ada 95 - =========================================== - - In the previous section we discussed the rules in Ada 95 which ensure - that `Program_Error' is raised if an incorrect elaboration order is - chosen. This prevents erroneous executions, but we need mechanisms to - specify a correct execution and avoid the exception altogether. To - achieve this, Ada 95 provides a number of features for controlling the - order of elaboration. We discuss these features in this section. - - First, there are several ways of indicating to the compiler that a - given unit has no elaboration problems: - - packages that do not require a body - In Ada 95, a library package that does not require a body does not - permit a body. This means that if we have a such a package, as in: - - package Definitions is - generic - type m is new integer; - package Subp is - type a is array (1 .. 10) of m; - type b is array (1 .. 20) of m; - end Subp; - end Definitions; - - A package that `with''s `Definitions' may safely instantiate - `Definitions.Subp' because the compiler can determine that there - definitely is no package body to worry about in this case - - pragma Pure - Places sufficient restrictions on a unit to guarantee that no call - to any subprogram in the unit can result in an elaboration - problem. This means that the compiler does not need to worry about - the point of elaboration of such units, and in particular, does - not need to check any calls to any subprograms in this unit. - - pragma Preelaborate - This pragma places slightly less stringent restrictions on a unit - than does pragma Pure, but these restrictions are still sufficient - to ensure that there are no elaboration problems with any calls to - the unit. - - pragma Elaborate_Body - This pragma requires that the body of a unit be elaborated - immediately after its spec. Suppose a unit `A' has such a pragma, - and unit `B' does a `with' of unit `A'. Recall that the standard - rules require the spec of unit `A' to be elaborated before the - `with''ing unit; given the pragma in `A', we also know that the - body of `A' will be elaborated before `B', so that calls to `A' - are safe and do not need a check. - - Note that, unlike pragma `Pure' and pragma `Preelaborate', the use of - `Elaborate_Body' does not guarantee that the program is free of - elaboration problems, because it may not be possible to satisfy the - requested elaboration order. Let's go back to the example with - `Unit_1' and `Unit_2'. If a programmer marks `Unit_1' as - `Elaborate_Body', and not `Unit_2,' then the order of elaboration will - be: - - Spec of Unit_2 - Spec of Unit_1 - Body of Unit_1 - Body of Unit_2 - - Now that means that the call to `Func_1' in `Unit_2' need not be - checked, it must be safe. But the call to `Func_2' in `Unit_1' may - still fail if `Expression_1' is equal to 1, and the programmer must - still take responsibility for this not being the case. - - If all units carry a pragma `Elaborate_Body', then all problems are - eliminated, except for calls entirely within a body, which are in any - case fully under programmer control. However, using the pragma - everywhere is not always possible. In particular, for our - `Unit_1'/`Unit_2' example, if we marked both of them as having pragma - `Elaborate_Body', then clearly there would be no possible elaboration - order. - - The above pragmas allow a server to guarantee safe use by clients, - and clearly this is the preferable approach. Consequently a good rule in - Ada 95 is to mark units as `Pure' or `Preelaborate' if possible, and if - this is not possible, mark them as `Elaborate_Body' if possible. As we - have seen, there are situations where neither of these three pragmas - can be used. So we also provide methods for clients to control the - order of elaboration of the servers on which they depend: - - pragma Elaborate (unit) - This pragma is placed in the context clause, after a `with' clause, - and it requires that the body of the named unit be elaborated - before the unit in which the pragma occurs. The idea is to use - this pragma if the current unit calls at elaboration time, - directly or indirectly, some subprogram in the named unit. - - pragma Elaborate_All (unit) - This is a stronger version of the Elaborate pragma. Consider the - following example: - - Unit A `with''s unit B and calls B.Func in elab code - Unit B `with''s unit C, and B.Func calls C.Func - - Now if we put a pragma `Elaborate (B)' in unit `A', this ensures - that the body of `B' is elaborated before the call, but not the - body of `C', so the call to `C.Func' could still cause - `Program_Error' to be raised. - - The effect of a pragma `Elaborate_All' is stronger, it requires - not only that the body of the named unit be elaborated before the - unit doing the `with', but also the bodies of all units that the - named unit uses, following `with' links transitively. For example, - if we put a pragma `Elaborate_All (B)' in unit `A', then it - requires not only that the body of `B' be elaborated before `A', - but also the body of `C', because `B' `with''s `C'. - - We are now in a position to give a usage rule in Ada 95 for avoiding - elaboration problems, at least if dynamic dispatching and access to - subprogram values are not used. We will handle these cases separately - later. - - The rule is simple. If a unit has elaboration code that can directly - or indirectly make a call to a subprogram in a `with''ed unit, or - instantiate a generic unit in a `with''ed unit, then if the `with''ed - unit does not have pragma `Pure' or `Preelaborate', then the client - should have a pragma `Elaborate_All' for the `with''ed unit. By - following this rule a client is assured that calls can be made without - risk of an exception. If this rule is not followed, then a program may - be in one of four states: - - No order exists - No order of elaboration exists which follows the rules, taking into - account any `Elaborate', `Elaborate_All', or `Elaborate_Body' - pragmas. In this case, an Ada 95 compiler must diagnose the - situation at bind time, and refuse to build an executable program. - - One or more orders exist, all incorrect - One or more acceptable elaboration orders exists, and all of them - generate an elaboration order problem. In this case, the binder - can build an executable program, but `Program_Error' will be raised - when the program is run. - - Several orders exist, some right, some incorrect - One or more acceptable elaboration orders exists, and some of them - work, and some do not. The programmer has not controlled the order - of elaboration, so the binder may or may not pick one of the - correct orders, and the program may or may not raise an exception - when it is run. This is the worst case, because it means that the - program may fail when moved to another compiler, or even another - version of the same compiler. - - One or more orders exists, all correct - One ore more acceptable elaboration orders exist, and all of them - work. In this case the program runs successfully. This state of - affairs can be guaranteed by following the rule we gave above, but - may be true even if the rule is not followed. - - Note that one additional advantage of following our Elaborate_All rule - is that the program continues to stay in the ideal (all orders OK) state - even if maintenance changes some bodies of some subprograms. - Conversely, if a program that does not follow this rule happens to be - safe at some point, this state of affairs may deteriorate silently as a - result of maintenance changes. - - You may have noticed that the above discussion did not mention the - use of `Elaborate_Body'. This was a deliberate omission. If you `with' - an `Elaborate_Body' unit, it still may be the case that code in the - body makes calls to some other unit, so it is still necessary to use - `Elaborate_All' on such units. - -  - File: gnat_ug_wnt.info, Node: Controlling Elaboration in GNAT - Internal Calls, Next: Controlling Elaboration in GNAT - External Calls, Prev: Controlling the Elaboration Order in Ada 95, Up: Elaboration Order Handling in GNAT - - Controlling Elaboration in GNAT - Internal Calls - ================================================ - - In the case of internal calls, i.e. calls within a single package, the - programmer has full control over the order of elaboration, and it is up - to the programmer to elaborate declarations in an appropriate order. For - example writing: - - function One return Float; - - Q : Float := One; - - function One return Float is - begin - return 1.0; - end One; - - will obviously raise `Program_Error' at run time, because function One - will be called before its body is elaborated. In this case GNAT will - generate a warning that the call will raise `Program_Error': - - 1. procedure y is - 2. function One return Float; - 3. - 4. Q : Float := One; - | - >>> warning: cannot call "One" before body is elaborated - >>> warning: Program_Error will be raised at run time - - 5. - 6. function One return Float is - 7. begin - 8. return 1.0; - 9. end One; - 10. - 11. begin - 12. null; - 13. end; - - Note that in this particular case, it is likely that the call is safe, - because the function `One' does not access any global variables. - Nevertheless in Ada 95, we do not want the validity of the check to - depend on the contents of the body (think about the separate - compilation case), so this is still wrong, as we discussed in the - previous sections. - - The error is easily corrected by rearranging the declarations so - that the body of One appears before the declaration containing the call - (note that in Ada 95, declarations can appear in any order, so there is - no restriction that would prevent this reordering, and if we write: - - function One return Float; - - function One return Float is - begin - return 1.0; - end One; - - Q : Float := One; - - then all is well, no warning is generated, and no `Program_Error' - exception will be raised. Things are more complicated when a chain of - subprograms is executed: - - function A return Integer; - function B return Integer; - function C return Integer; - - function B return Integer is begin return A; end; - function C return Integer is begin return B; end; - - X : Integer := C; - - function A return Integer is begin return 1; end; - - Now the call to `C' at elaboration time in the declaration of `X' is - correct, because the body of `C' is already elaborated, and the call to - `B' within the body of `C' is correct, but the call to `A' within the - body of `B' is incorrect, because the body of `A' has not been - elaborated, so `Program_Error' will be raised on the call to `A'. In - this case GNAT will generate a warning that `Program_Error' may be - raised at the point of the call. Let's look at the warning: - - 1. procedure x is - 2. function A return Integer; - 3. function B return Integer; - 4. function C return Integer; - 5. - 6. function B return Integer is begin return A; end; - | - >>> warning: call to "A" before body is elaborated may - raise Program_Error - >>> warning: "B" called at line 7 - >>> warning: "C" called at line 9 - - 7. function C return Integer is begin return B; end; - 8. - 9. X : Integer := C; - 10. - 11. function A return Integer is begin return 1; end; - 12. - 13. begin - 14. null; - 15. end; - - Note that the message here says "may raise", instead of the direct case, - where the message says "will be raised". That's because whether `A' is - actually called depends in general on run-time flow of control. For - example, if the body of `B' said - - function B return Integer is - begin - if some-condition-depending-on-input-data then - return A; - else - return 1; - end if; - end B; - - then we could not know until run time whether the incorrect call to A - would actually occur, so `Program_Error' might or might not be raised. - It is possible for a compiler to do a better job of analyzing bodies, to - determine whether or not `Program_Error' might be raised, but it - certainly couldn't do a perfect job (that would require solving the - halting problem and is provably impossible), and because this is a - warning anyway, it does not seem worth the effort to do the analysis. - Cases in which it would be relevant are rare. - - In practice, warnings of either of the forms given above will - usually correspond to real errors, and should be examined carefully and - eliminated. In the rare case where a warning is bogus, it can be - suppressed by any of the following methods: - - * Compile with the `-gnatws' switch set - - * Suppress `Elaboration_Checks' for the called subprogram - - * Use pragma `Warnings_Off' to turn warnings off for the call - - For the internal elaboration check case, GNAT by default generates the - necessary run-time checks to ensure that `Program_Error' is raised if - any call fails an elaboration check. Of course this can only happen if a - warning has been issued as described above. The use of pragma `Suppress - (Elaboration_Checks)' may (but is not guaranteed to) suppress some of - these checks, meaning that it may be possible (but is not guaranteed) - for a program to be able to call a subprogram whose body is not yet - elaborated, without raising a `Program_Error' exception. - -  - File: gnat_ug_wnt.info, Node: Controlling Elaboration in GNAT - External Calls, Next: Default Behavior in GNAT - Ensuring Safety, Prev: Controlling Elaboration in GNAT - Internal Calls, Up: Elaboration Order Handling in GNAT - - Controlling Elaboration in GNAT - External Calls - ================================================ - - The previous section discussed the case in which the execution of a - particular thread of elaboration code occurred entirely within a single - unit. This is the easy case to handle, because a programmer has direct - and total control over the order of elaboration, and furthermore, - checks need only be generated in cases which are rare and which the - compiler can easily detect. The situation is more complex when - separate compilation is taken into account. Consider the following: - - package Math is - function Sqrt (Arg : Float) return Float; - end Math; - - package body Math is - function Sqrt (Arg : Float) return Float is - begin - ... - end Sqrt; - end Math; - - with Math; - package Stuff is - X : Float := Math.Sqrt (0.5); - end Stuff; - - with Stuff; - procedure Main is - begin - ... - end Main; - - where `Main' is the main program. When this program is executed, the - elaboration code must first be executed, and one of the jobs of the - binder is to determine the order in which the units of a program are to - be elaborated. In this case we have four units: the spec and body of - `Math', the spec of `Stuff' and the body of `Main'). In what order - should the four separate sections of elaboration code be executed? - - There are some restrictions in the order of elaboration that the - binder can choose. In particular, if unit U has a `with' for a package - `X', then you are assured that the spec of `X' is elaborated before U , - but you are not assured that the body of `X' is elaborated before U. - This means that in the above case, the binder is allowed to choose the - order: - - spec of Math - spec of Stuff - body of Math - body of Main - - but that's not good, because now the call to `Math.Sqrt' that happens - during the elaboration of the `Stuff' spec happens before the body of - `Math.Sqrt' is elaborated, and hence causes `Program_Error' exception - to be raised. At first glance, one might say that the binder is - misbehaving, because obviously you want to elaborate the body of - something you `with' first, but that is not a general rule that can be - followed in all cases. Consider - - package X is ... - - package Y is ... - - with X; - package body Y is ... - - with Y; - package body X is ... - - This is a common arrangement, and, apart from the order of elaboration - problems that might arise in connection with elaboration code, this - works fine. A rule that says that you must first elaborate the body of - anything you `with' cannot work in this case: the body of `X' `with''s - `Y', which means you would have to elaborate the body of `Y' first, but - that `with''s `X', which means you have to elaborate the body of `X' - first, but ... and we have a loop that cannot be broken. - - It is true that the binder can in many cases guess an order of - elaboration that is unlikely to cause a `Program_Error' exception to be - raised, and it tries to do so (in the above example of - `Math/Stuff/Spec', the GNAT binder will by default elaborate the body - of `Math' right after its spec, so all will be well). - - However, a program that blindly relies on the binder to be helpful - can get into trouble, as we discussed in the previous sections, so GNAT - provides a number of facilities for assisting the programmer in - developing programs that are robust with respect to elaboration order. - -  - File: gnat_ug_wnt.info, Node: Default Behavior in GNAT - Ensuring Safety, Next: Elaboration Issues for Library Tasks, Prev: Controlling Elaboration in GNAT - External Calls, Up: Elaboration Order Handling in GNAT - - Default Behavior in GNAT - Ensuring Safety - ========================================== - - The default behavior in GNAT ensures elaboration safety. In its default - mode GNAT implements the rule we previously described as the right - approach. Let's restate it: - - * _If a unit has elaboration code that can directly or indirectly - make a call to a subprogram in a `with''ed unit, or instantiate a - generic unit in a `with''ed unit, then if the `with''ed unit does - not have pragma `Pure' or `Preelaborate', then the client should - have an `Elaborate_All' for the `with''ed unit._ - - By following this rule a client is assured that calls and - instantiations can be made without risk of an exception. - - In this mode GNAT traces all calls that are potentially made from - elaboration code, and puts in any missing implicit `Elaborate_All' - pragmas. The advantage of this approach is that no elaboration problems - are possible if the binder can find an elaboration order that is - consistent with these implicit `Elaborate_All' pragmas. The - disadvantage of this approach is that no such order may exist. - - If the binder does not generate any diagnostics, then it means that - it has found an elaboration order that is guaranteed to be safe. - However, the binder may still be relying on implicitly generated - `Elaborate_All' pragmas so portability to other compilers than GNAT is - not guaranteed. - - If it is important to guarantee portability, then the compilations - should use the `-gnatwl' (warn on elaboration problems) switch. This - will cause warning messages to be generated indicating the missing - `Elaborate_All' pragmas. Consider the following source program: - - with k; - package j is - m : integer := k.r; - end; - - where it is clear that there should be a pragma `Elaborate_All' for - unit `k'. An implicit pragma will be generated, and it is likely that - the binder will be able to honor it. However, it is safer to include - the pragma explicitly in the source. If this unit is compiled with the - `-gnatwl' switch, then the compiler outputs a warning: - - 1. with k; - 2. package j is - 3. m : integer := k.r; - | - >>> warning: call to "r" may raise Program_Error - >>> warning: missing pragma Elaborate_All for "k" - - 4. end; - - and these warnings can be used as a guide for supplying manually the - missing pragmas. - - This default mode is more restrictive than the Ada Reference Manual, - and it is possible to construct programs which will compile using the - dynamic model described there, but will run into a circularity using - the safer static model we have described. - - Of course any Ada compiler must be able to operate in a mode - consistent with the requirements of the Ada Reference Manual, and in - particular must have the capability of implementing the standard - dynamic model of elaboration with run-time checks. - - In GNAT, this standard mode can be achieved either by the use of the - `-gnatE' switch on the compiler (`gcc' or `gnatmake') command, or by - the use of the configuration pragma: - - pragma Elaboration_Checks (RM); - - Either approach will cause the unit affected to be compiled using the - standard dynamic run-time elaboration checks described in the Ada - Reference Manual. The static model is generally preferable, since it is - clearly safer to rely on compile and link time checks rather than - run-time checks. However, in the case of legacy code, it may be - difficult to meet the requirements of the static model. This issue is - further discussed in *Note What to Do If the Default Elaboration - Behavior Fails::. - - Note that the static model provides a strict subset of the allowed - behavior and programs of the Ada Reference Manual, so if you do adhere - to the static model and no circularities exist, then you are assured - that your program will work using the dynamic model. - -  - File: gnat_ug_wnt.info, Node: Elaboration Issues for Library Tasks, Next: Mixing Elaboration Models, Prev: Default Behavior in GNAT - Ensuring Safety, Up: Elaboration Order Handling in GNAT - - Elaboration Issues for Library Tasks - ==================================== - - In this section we examine special elaboration issues that arise for - programs that declare library level tasks. - - Generally the model of execution of an Ada program is that all units - are elaborated, and then execution of the program starts. However, the - declaration of library tasks definitely does not fit this model. The - reason for this is that library tasks start as soon as they are declared - (more precisely, as soon as the statement part of the enclosing package - body is reached), that is to say before elaboration of the program is - complete. This means that if such a task calls a subprogram, or an - entry in another task, the callee may or may not be elaborated yet, and - in the standard Reference Manual model of dynamic elaboration checks, - you can even get timing dependent Program_Error exceptions, since there - can be a race between the elaboration code and the task code. - - The static model of elaboration in GNAT seeks to avoid all such - dynamic behavior, by being conservative, and the conservative approach - in this particular case is to assume that all the code in a task body - is potentially executed at elaboration time if a task is declared at - the library level. - - This can definitely result in unexpected circularities. Consider the - following example - - package Decls is - task Lib_Task is - entry Start; - end Lib_Task; - - type My_Int is new Integer; - - function Ident (M : My_Int) return My_Int; - end Decls; - - with Utils; - package body Decls is - task body Lib_Task is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task; - - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls; - - with Decls; - package Utils is - procedure Put_Val (Arg : Decls.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls.My_Int) is - begin - Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls; - procedure Main is - begin - Decls.Lib_Task.Start; - end; - - If the above example is compiled in the default static elaboration - mode, then a circularity occurs. The circularity comes from the call - `Utils.Put_Val' in the task body of `Decls.Lib_Task'. Since this call - occurs in elaboration code, we need an implicit pragma `Elaborate_All' - for `Utils'. This means that not only must the spec and body of `Utils' - be elaborated before the body of `Decls', but also the spec and body of - any unit that is `with'ed' by the body of `Utils' must also be - elaborated before the body of `Decls'. This is the transitive - implication of pragma `Elaborate_All' and it makes sense, because in - general the body of `Put_Val' might have a call to something in a - `with'ed' unit. - - In this case, the body of Utils (actually its spec) `with's' - `Decls'. Unfortunately this means that the body of `Decls' must be - elaborated before itself, in case there is a call from the body of - `Utils'. - - Here is the exact chain of events we are worrying about: - - 1. In the body of `Decls' a call is made from within the body of a - library task to a subprogram in the package `Utils'. Since this - call may occur at elaboration time (given that the task is - activated at elaboration time), we have to assume the worst, i.e. - that the call does happen at elaboration time. - - 2. This means that the body and spec of `Util' must be elaborated - before the body of `Decls' so that this call does not cause an - access before elaboration. - - 3. Within the body of `Util', specifically within the body of - `Util.Put_Val' there may be calls to any unit `with''ed by this - package. - - 4. One such `with''ed package is package `Decls', so there might be a - call to a subprogram in `Decls' in `Put_Val'. In fact there is - such a call in this example, but we would have to assume that - there was such a call even if it were not there, since we are not - supposed to write the body of `Decls' knowing what is in the body - of `Utils'; certainly in the case of the static elaboration model, - the compiler does not know what is in other bodies and must assume - the worst. - - 5. This means that the spec and body of `Decls' must also be - elaborated before we elaborate the unit containing the call, but - that unit is `Decls'! This means that the body of `Decls' must be - elaborated before itself, and that's a circularity. - - Indeed, if you add an explicit pragma Elaborate_All for `Utils' in the - body of `Decls' you will get a true Ada Reference Manual circularity - that makes the program illegal. - - In practice, we have found that problems with the static model of - elaboration in existing code often arise from library tasks, so we must - address this particular situation. - - Note that if we compile and run the program above, using the dynamic - model of elaboration (that is to say use the `-gnatE' switch), then it - compiles, binds, links, and runs, printing the expected result of 2. - Therefore in some sense the circularity here is only apparent, and we - need to capture the properties of this program that distinguish it - from other library-level tasks that have real elaboration problems. - - We have four possible answers to this question: - - * Use the dynamic model of elaboration. - - If we use the `-gnatE' switch, then as noted above, the program - works. Why is this? If we examine the task body, it is apparent - that the task cannot proceed past the `accept' statement until - after elaboration has been completed, because the corresponding - entry call comes from the main program, not earlier. This is why - the dynamic model works here. But that's really giving up on a - precise analysis, and we prefer to take this approach only if we - cannot solve the problem in any other manner. So let us examine - two ways to reorganize the program to avoid the potential - elaboration problem. - - * Split library tasks into separate packages. - - Write separate packages, so that library tasks are isolated from - other declarations as much as possible. Let us look at a variation - on the above program. - - package Decls1 is - task Lib_Task is - entry Start; - end Lib_Task; - end Decls1; - - with Utils; - package body Decls1 is - task body Lib_Task is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task; - end Decls1; - - package Decls2 is - type My_Int is new Integer; - function Ident (M : My_Int) return My_Int; - end Decls2; - - with Utils; - package body Decls2 is - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls2; - - with Decls2; - package Utils is - procedure Put_Val (Arg : Decls2.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls2.My_Int) is - begin - Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls1; - procedure Main is - begin - Decls1.Lib_Task.Start; - end; - - All we have done is to split `Decls' into two packages, one - containing the library task, and one containing everything else. - Now there is no cycle, and the program compiles, binds, links and - executes using the default static model of elaboration. - - * Declare separate task types. - - A significant part of the problem arises because of the use of the - single task declaration form. This means that the elaboration of - the task type, and the elaboration of the task itself (i.e. the - creation of the task) happen at the same time. A good rule of - style in Ada 95 is to always create explicit task types. By - following the additional step of placing task objects in separate - packages from the task type declaration, many elaboration problems - are avoided. Here is another modified example of the example - program: - - package Decls is - task type Lib_Task_Type is - entry Start; - end Lib_Task_Type; - - type My_Int is new Integer; - - function Ident (M : My_Int) return My_Int; - end Decls; - - with Utils; - package body Decls is - task body Lib_Task_Type is - begin - accept Start; - Utils.Put_Val (2); - end Lib_Task_Type; - - function Ident (M : My_Int) return My_Int is - begin - return M; - end Ident; - end Decls; - - with Decls; - package Utils is - procedure Put_Val (Arg : Decls.My_Int); - end Utils; - - with Text_IO; - package body Utils is - procedure Put_Val (Arg : Decls.My_Int) is - begin - Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); - end Put_Val; - end Utils; - - with Decls; - package Declst is - Lib_Task : Decls.Lib_Task_Type; - end Declst; - - with Declst; - procedure Main is - begin - Declst.Lib_Task.Start; - end; - - What we have done here is to replace the `task' declaration in - package `Decls' with a `task type' declaration. Then we introduce - a separate package `Declst' to contain the actual task object. - This separates the elaboration issues for the `task type' - declaration, which causes no trouble, from the elaboration issues - of the task object, which is also unproblematic, since it is now - independent of the elaboration of `Utils'. This separation of - concerns also corresponds to a generally sound engineering - principle of separating declarations from instances. This version - of the program also compiles, binds, links, and executes, - generating the expected output. - - * Use No_Entry_Calls_In_Elaboration_Code restriction. - - The previous two approaches described how a program can be - restructured to avoid the special problems caused by library task - bodies. in practice, however, such restructuring may be difficult - to apply to existing legacy code, so we must consider solutions - that do not require massive rewriting. - - Let us consider more carefully why our original sample program - works under the dynamic model of elaboration. The reason is that - the code in the task body blocks immediately on the `accept' - statement. Now of course there is nothing to prohibit elaboration - code from making entry calls (for example from another library - level task), so we cannot tell in isolation that the task will not - execute the accept statement during elaboration. - - However, in practice it is very unusual to see elaboration code - make any entry calls, and the pattern of tasks starting at - elaboration time and then immediately blocking on `accept' or - `select' statements is very common. What this means is that the - compiler is being too pessimistic when it analyzes the whole - package body as though it might be executed at elaboration time. - - If we know that the elaboration code contains no entry calls, (a - very safe assumption most of the time, that could almost be made - the default behavior), then we can compile all units of the - program under control of the following configuration pragma: - - pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); - - This pragma can be placed in the `gnat.adc' file in the usual - manner. If we take our original unmodified program and compile it - in the presence of a `gnat.adc' containing the above pragma, then - once again, we can compile, bind, link, and execute, obtaining the - expected result. In the presence of this pragma, the compiler does - not trace calls in a task body, that appear after the first - `accept' or `select' statement, and therefore does not report a - potential circularity in the original program. - - The compiler will check to the extent it can that the above - restriction is not violated, but it is not always possible to do a - complete check at compile time, so it is important to use this - pragma only if the stated restriction is in fact met, that is to - say no task receives an entry call before elaboration of all units - is completed. - - -  - File: gnat_ug_wnt.info, Node: Mixing Elaboration Models, Next: What to Do If the Default Elaboration Behavior Fails, Prev: Elaboration Issues for Library Tasks, Up: Elaboration Order Handling in GNAT - - Mixing Elaboration Models - ========================= - - So far, we have assumed that the entire program is either compiled - using the dynamic model or static model, ensuring consistency. It is - possible to mix the two models, but rules have to be followed if this - mixing is done to ensure that elaboration checks are not omitted. - - The basic rule is that _a unit compiled with the static model cannot - be `with'ed' by a unit compiled with the dynamic model_. The reason for - this is that in the static model, a unit assumes that its clients - guarantee to use (the equivalent of) pragma `Elaborate_All' so that no - elaboration checks are required in inner subprograms, and this - assumption is violated if the client is compiled with dynamic checks. - - The precise rule is as follows. A unit that is compiled with dynamic - checks can only `with' a unit that meets at least one of the following - criteria: - - * The `with'ed' unit is itself compiled with dynamic elaboration - checks (that is with the `-gnatE' switch. - - * The `with'ed' unit is an internal GNAT implementation unit from - the System, Interfaces, Ada, or GNAT hierarchies. - - * The `with'ed' unit has pragma Preelaborate or pragma Pure. - - * The `with'ing' unit (that is the client) has an explicit pragma - `Elaborate_All' for the `with'ed' unit. - - - If this rule is violated, that is if a unit with dynamic elaboration - checks `with's' a unit that does not meet one of the above four - criteria, then the binder (`gnatbind') will issue a warning similar to - that in the following example: - - warning: "x.ads" has dynamic elaboration checks and with's - warning: "y.ads" which has static elaboration checks - - These warnings indicate that the rule has been violated, and that as a - result elaboration checks may be missed in the resulting executable - file. This warning may be suppressed using the `-ws' binder switch in - the usual manner. - - One useful application of this mixing rule is in the case of a - subsystem which does not itself `with' units from the remainder of the - application. In this case, the entire subsystem can be compiled with - dynamic checks to resolve a circularity in the subsystem, while - allowing the main application that uses this subsystem to be compiled - using the more reliable default static model. - -  - File: gnat_ug_wnt.info, Node: What to Do If the Default Elaboration Behavior Fails, Next: Elaboration for Access-to-Subprogram Values, Prev: Mixing Elaboration Models, Up: Elaboration Order Handling in GNAT - - What to Do If the Default Elaboration Behavior Fails - ==================================================== - - If the binder cannot find an acceptable order, it outputs detailed - diagnostics. For example: - error: elaboration circularity detected - info: "proc (body)" must be elaborated before "pack (body)" - info: reason: Elaborate_All probably needed in unit "pack (body)" - info: recompile "pack (body)" with -gnatwl - info: for full details - info: "proc (body)" - info: is needed by its spec: - info: "proc (spec)" - info: which is withed by: - info: "pack (body)" - info: "pack (body)" must be elaborated before "proc (body)" - info: reason: pragma Elaborate in unit "proc (body)" - - - In this case we have a cycle that the binder cannot break. On the one - hand, there is an explicit pragma Elaborate in `proc' for `pack'. This - means that the body of `pack' must be elaborated before the body of - `proc'. On the other hand, there is elaboration code in `pack' that - calls a subprogram in `proc'. This means that for maximum safety, there - should really be a pragma Elaborate_All in `pack' for `proc' which - would require that the body of `proc' be elaborated before the body of - `pack'. Clearly both requirements cannot be satisfied. Faced with a - circularity of this kind, you have three different options. - - Fix the program - The most desirable option from the point of view of long-term - maintenance is to rearrange the program so that the elaboration - problems are avoided. One useful technique is to place the - elaboration code into separate child packages. Another is to move - some of the initialization code to explicitly called subprograms, - where the program controls the order of initialization explicitly. - Although this is the most desirable option, it may be impractical - and involve too much modification, especially in the case of - complex legacy code. - - Perform dynamic checks - If the compilations are done using the `-gnatE' (dynamic - elaboration check) switch, then GNAT behaves in a quite different - manner. Dynamic checks are generated for all calls that could - possibly result in raising an exception. With this switch, the - compiler does not generate implicit `Elaborate_All' pragmas. The - behavior then is exactly as specified in the Ada 95 Reference - Manual. The binder will generate an executable program that may - or may not raise `Program_Error', and then it is the programmer's - job to ensure that it does not raise an exception. Note that it is - important to compile all units with the switch, it cannot be used - selectively. - - Suppress checks - The drawback of dynamic checks is that they generate a significant - overhead at run time, both in space and time. If you are - absolutely sure that your program cannot raise any elaboration - exceptions, and you still want to use the dynamic elaboration - model, then you can use the configuration pragma `Suppress - (Elaboration_Checks)' to suppress all such checks. For example - this pragma could be placed in the `gnat.adc' file. - - Suppress checks selectively - When you know that certain calls in elaboration code cannot - possibly lead to an elaboration error, and the binder nevertheless - generates warnings on those calls and inserts Elaborate_All - pragmas that lead to elaboration circularities, it is possible to - remove those warnings locally and obtain a program that will bind. - Clearly this can be unsafe, and it is the responsibility of the - programmer to make sure that the resulting program has no - elaboration anomalies. The pragma `Suppress (Elaboration_Check)' - can be used with different granularity to suppress warnings and - break elaboration circularities: - - * Place the pragma that names the called subprogram in the - declarative part that contains the call. - - * Place the pragma in the declarative part, without naming an - entity. This disables warnings on all calls in the - corresponding declarative region. - - * Place the pragma in the package spec that declares the called - subprogram, and name the subprogram. This disables warnings - on all elaboration calls to that subprogram. - - * Place the pragma in the package spec that declares the called - subprogram, without naming any entity. This disables warnings - on all elaboration calls to all subprograms declared in this - spec. - - These four cases are listed in order of decreasing safety, and - therefore require increasing programmer care in their application. - Consider the following program: - - package Pack1 is - function F1 return Integer; - X1 : Integer; - end Pack1; - - package Pack2 is - function F2 return Integer; - function Pure (x : integer) return integer; - -- pragma Suppress (Elaboration_Check, On => Pure); -- (3) - -- pragma Suppress (Elaboration_Check); -- (4) - end Pack2; - - with Pack2; - package body Pack1 is - function F1 return Integer is - begin - return 100; - end F1; - Val : integer := Pack2.Pure (11); -- Elab. call (1) - begin - declare - -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1) - -- pragma Suppress(Elaboration_Check); -- (2) - begin - X1 := Pack2.F2 + 1; -- Elab. call (2) - end; - end Pack1; - - with Pack1; - package body Pack2 is - function F2 return Integer is - begin - return Pack1.F1; - end F2; - function Pure (x : integer) return integer is - begin - return x ** 3 - 3 * x; - end; - end Pack2; - - with Pack1, Ada.Text_IO; - procedure Proc3 is - begin - Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 - end Proc3; - In the absence of any pragmas, an attempt to bind this program - produces the following diagnostics: - error: elaboration circularity detected - info: "pack1 (body)" must be elaborated before "pack1 (body)" - info: reason: Elaborate_All probably needed in unit "pack1 (body)" - info: recompile "pack1 (body)" with -gnatwl for full details - info: "pack1 (body)" - info: must be elaborated along with its spec: - info: "pack1 (spec)" - info: which is withed by: - info: "pack2 (body)" - info: which must be elaborated along with its spec: - info: "pack2 (spec)" - info: which is withed by: - info: "pack1 (body)" - The sources of the circularity are the two calls to - `Pack2.Pure' and `Pack2.F2' in the body of `Pack1'. We can see - that the call to F2 is safe, even though F2 calls F1, because the - call appears after the elaboration of the body of F1. Therefore - the pragma (1) is safe, and will remove the warning on the call. - It is also possible to use pragma (2) because there are no other - potentially unsafe calls in the block. - - The call to `Pure' is safe because this function does not depend - on the state of `Pack2'. Therefore any call to this function is - safe, and it is correct to place pragma (3) in the corresponding - package spec. - - Finally, we could place pragma (4) in the spec of `Pack2' to - disable warnings on all calls to functions declared therein. Note - that this is not necessarily safe, and requires more detailed - examination of the subprogram bodies involved. In particular, a - call to `F2' requires that `F1' be already elaborated. - - It is hard to generalize on which of these four approaches should be - taken. Obviously if it is possible to fix the program so that the - default treatment works, this is preferable, but this may not always be - practical. It is certainly simple enough to use `-gnatE' but the - danger in this case is that, even if the GNAT binder finds a correct - elaboration order, it may not always do so, and certainly a binder from - another Ada compiler might not. A combination of testing and analysis - (for which the warnings generated with the `-gnatwl' switch can be - useful) must be used to ensure that the program is free of errors. One - switch that is useful in this testing is the `-p (pessimistic - elaboration order)' switch for `gnatbind'. Normally the binder tries - to find an order that has the best chance of of avoiding elaboration - problems. With this switch, the binder plays a devil's advocate role, - and tries to choose the order that has the best chance of failing. If - your program works even with this switch, then it has a better chance - of being error free, but this is still not a guarantee. - - For an example of this approach in action, consider the C-tests - (executable tests) from the ACVC suite. If these are compiled and run - with the default treatment, then all but one of them succeed without - generating any error diagnostics from the binder. However, there is one - test that fails, and this is not surprising, because the whole point of - this test is to ensure that the compiler can handle cases where it is - impossible to determine a correct order statically, and it checks that - an exception is indeed raised at run time. - - This one test must be compiled and run using the `-gnatE' switch, - and then it passes. Alternatively, the entire suite can be run using - this switch. It is never wrong to run with the dynamic elaboration - switch if your code is correct, and we assume that the C-tests are - indeed correct (it is less efficient, but efficiency is not a factor in - running the ACVC tests.) - -  - File: gnat_ug_wnt.info, Node: Elaboration for Access-to-Subprogram Values, Next: Summary of Procedures for Elaboration Control, Prev: What to Do If the Default Elaboration Behavior Fails, Up: Elaboration Order Handling in GNAT - - Elaboration for Access-to-Subprogram Values - =========================================== - - The introduction of access-to-subprogram types in Ada 95 complicates - the handling of elaboration. The trouble is that it becomes impossible - to tell at compile time which procedure is being called. This means - that it is not possible for the binder to analyze the elaboration - requirements in this case. - - If at the point at which the access value is created (i.e., the - evaluation of `P'Access' for a subprogram `P'), the body of the - subprogram is known to have been elaborated, then the access value is - safe, and its use does not require a check. This may be achieved by - appropriate arrangement of the order of declarations if the subprogram - is in the current unit, or, if the subprogram is in another unit, by - using pragma `Pure', `Preelaborate', or `Elaborate_Body' on the - referenced unit. - - If the referenced body is not known to have been elaborated at the - point the access value is created, then any use of the access value - must do a dynamic check, and this dynamic check will fail and raise a - `Program_Error' exception if the body has not been elaborated yet. - GNAT will generate the necessary checks, and in addition, if the - `-gnatwl' switch is set, will generate warnings that such checks are - required. - - The use of dynamic dispatching for tagged types similarly generates - a requirement for dynamic checks, and premature calls to any primitive - operation of a tagged type before the body of the operation has been - elaborated, will result in the raising of `Program_Error'. - -  - File: gnat_ug_wnt.info, Node: Summary of Procedures for Elaboration Control, Next: Other Elaboration Order Considerations, Prev: Elaboration for Access-to-Subprogram Values, Up: Elaboration Order Handling in GNAT - - Summary of Procedures for Elaboration Control - ============================================= - - First, compile your program with the default options, using none of the - special elaboration control switches. If the binder successfully binds - your program, then you can be confident that, apart from issues raised - by the use of access-to-subprogram types and dynamic dispatching, the - program is free of elaboration errors. If it is important that the - program be portable, then use the `-gnatwl' switch to generate warnings - about missing `Elaborate_All' pragmas, and supply the missing pragmas. - - If the program fails to bind using the default static elaboration - handling, then you can fix the program to eliminate the binder message, - or recompile the entire program with the `-gnatE' switch to generate - dynamic elaboration checks, and, if you are sure there really are no - elaboration problems, use a global pragma `Suppress - (Elaboration_Checks)'. - -  - File: gnat_ug_wnt.info, Node: Other Elaboration Order Considerations, Prev: Summary of Procedures for Elaboration Control, Up: Elaboration Order Handling in GNAT - - Other Elaboration Order Considerations - ====================================== - - This section has been entirely concerned with the issue of finding a - valid elaboration order, as defined by the Ada Reference Manual. In a - case where several elaboration orders are valid, the task is to find one - of the possible valid elaboration orders (and the static model in GNAT - will ensure that this is achieved). - - The purpose of the elaboration rules in the Ada Reference Manual is - to make sure that no entity is accessed before it has been elaborated. - For a subprogram, this means that the spec and body must have been - elaborated before the subprogram is called. For an object, this means - that the object must have been elaborated before its value is read or - written. A violation of either of these two requirements is an access - before elaboration order, and this section has been all about avoiding - such errors. - - In the case where more than one order of elaboration is possible, in - the sense that access before elaboration errors are avoided, then any - one of the orders is "correct" in the sense that it meets the - requirements of the Ada Reference Manual, and no such error occurs. - - However, it may be the case for a given program, that there are - constraints on the order of elaboration that come not from consideration - of avoiding elaboration errors, but rather from extra-lingual logic - requirements. Consider this example: - - with Init_Constants; - package Constants is - X : Integer := 0; - Y : Integer := 0; - end Constants; - - package Init_Constants is - procedure Calc; - end Init_Constants; - - with Constants; - package body Init_Constants is - procedure Calc is begin null; end; - begin - Constants.X := 3; - Constants.Y := 4; - end Init_Constants; - - with Constants; - package Calc is - Z : Integer := Constants.X + Constants.Y; - end Calc; - - with Calc; - with Text_IO; use Text_IO; - procedure Main is - begin - Put_Line (Calc.Z'Img); - end Main; - - In this example, there is more than one valid order of elaboration. For - example both the following are correct orders: - - Init_Constants spec - Constants spec - Calc spec - Main body - Init_Constants body - - and - - Init_Constants spec - Init_Constants body - Constants spec - Calc spec - Main body - - There is no language rule to prefer one or the other, both are correct - from an order of elaboration point of view. But the programmatic effects - of the two orders are very different. In the first, the elaboration - routine of `Calc' initializes `Z' to zero, and then the main program - runs with this value of zero. But in the second order, the elaboration - routine of `Calc' runs after the body of Init_Constants has set `X' and - `Y' and thus `Z' is set to 7 before `Main' runs. - - One could perhaps by applying pretty clever non-artificial - intelligence to the situation guess that it is more likely that the - second order of elaboration is the one desired, but there is no formal - linguistic reason to prefer one over the other. In fact in this - particular case, GNAT will prefer the second order, because of the rule - that bodies are elaborated as soon as possible, but it's just luck that - this is what was wanted (if indeed the second order was preferred). - - If the program cares about the order of elaboration routines in a - case like this, it is important to specify the order required. In this - particular case, that could have been achieved by adding to the spec of - Calc: - - pragma Elaborate_All (Constants); - - which requires that the body (if any) and spec of `Constants', as well - as the body and spec of any unit `with''ed by `Constants' be elaborated - before `Calc' is elaborated. - - Clearly no automatic method can always guess which alternative you - require, and if you are working with legacy code that had constraints - of this kind which were not properly specified by adding `Elaborate' or - `Elaborate_All' pragmas, then indeed it is possible that two different - compilers can choose different orders. - - The `gnatbind' `-p' switch may be useful in smoking out problems. - This switch causes bodies to be elaborated as late as possible instead - of as early as possible. In the example above, it would have forced the - choice of the first elaboration order. If you get different results - when using this switch, and particularly if one set of results is right, - and one is wrong as far as you are concerned, it shows that you have - some missing `Elaborate' pragmas. For the example above, we have the - following output: - - gnatmake -f -q main - main - 7 - gnatmake -f -q main -bargs -p - main - 0 - - It is of course quite unlikely that both these results are correct, so - it is up to you in a case like this to investigate the source of the - difference, by looking at the two elaboration orders that are chosen, - and figuring out which is correct, and then adding the necessary - `Elaborate_All' pragmas to ensure the desired order. - -  - File: gnat_ug_wnt.info, Node: The Cross-Referencing Tools gnatxref and gnatfind, Next: File Name Krunching Using gnatkr, Prev: Elaboration Order Handling in GNAT, Up: Top - - The Cross-Referencing Tools `gnatxref' and `gnatfind' - ***************************************************** - - The compiler generates cross-referencing information (unless you set - the `-gnatx' switch), which are saved in the `.ali' files. This - information indicates where in the source each entity is declared and - referenced. Note that entities in package Standard are not included, but - entities in all other predefined units are included in the output. - - Before using any of these two tools, you need to compile - successfully your application, so that GNAT gets a chance to generate - the cross-referencing information. - - The two tools `gnatxref' and `gnatfind' take advantage of this - information to provide the user with the capability to easily locate the - declaration and references to an entity. These tools are quite similar, - the difference being that `gnatfind' is intended for locating - definitions and/or references to a specified entity or entities, whereas - `gnatxref' is oriented to generating a full report of all - cross-references. - - To use these tools, you must not compile your application using the - `-gnatx' switch on the `gnatmake' command line (*note (gnat_ug)The GNAT - Make Program gnatmake::). Otherwise, cross-referencing information will - not be generated. - - * Menu: - - * gnatxref Switches:: - * gnatfind Switches:: - * Project Files for gnatxref and gnatfind:: - * Regular Expressions in gnatfind and gnatxref:: - * Examples of gnatxref Usage:: - * Examples of gnatfind Usage:: - -  - File: gnat_ug_wnt.info, Node: gnatxref Switches, Next: gnatfind Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - `gnatxref' Switches - =================== - - The command lines for `gnatxref' is: - $ gnatxref [switches] sourcefile1 [sourcefile2 ...] - - where - - `sourcefile1, sourcefile2' - identifies the source files for which a report is to be generated. - The 'with'ed units will be processed too. You must provide at - least one file. - - These file names are considered to be regular expressions, so for - instance specifying 'source*.adb' is the same as giving every file - in the current directory whose name starts with 'source' and whose - extension is 'adb'. - - The switches can be : - `-a' - If this switch is present, `gnatfind' and `gnatxref' will parse - the read-only files found in the library search path. Otherwise, - these files will be ignored. This option can be used to protect - Gnat sources or your own libraries from being parsed, thus making - `gnatfind' and `gnatxref' much faster, and their output much - smaller. - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source file search is undertaken is the same as for - `gnatmake'. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is the same as - for `gnatmake'. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-d' - If this switch is set `gnatxref' will output the parent type - reference for each matching derived types. - - `-f' - If this switch is set, the output file names will be preceded by - their directory (if the file was found in the search path). If - this switch is not set, the directory will not be printed. - - `-g' - If this switch is set, information is output only for library-level - entities, ignoring local entities. The use of this switch may - accelerate `gnatfind' and `gnatxref'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-pFILE' - Specify a project file to use *Note Project Files::. By default, - `gnatxref' and `gnatfind' will try to locate a project file in the - current directory. - - If a project file is either specified or found by the tools, then - the content of the source directory and object directory lines are - added as if they had been specified respectively by `-aI' and - `-aO'. - - `-u' - Output only unused symbols. This may be really useful if you give - your main compilation unit on the command line, as `gnatxref' will - then display every unused entity and 'with'ed package. - - `-v' - Instead of producing the default output, `gnatxref' will generate a - `tags' file that can be used by vi. For examples how to use this - feature, see *Note Examples of gnatxref Usage::. The tags file is - output to the standard output, thus you will have to redirect it - to a file. - - All these switches may be in any order on the command line, and may - even appear after the file names. They need not be separated by spaces, - thus you can say `gnatxref -ag' instead of `gnatxref -a -g'. - -  - File: gnat_ug_wnt.info, Node: gnatfind Switches, Next: Project Files for gnatxref and gnatfind, Prev: gnatxref Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - `gnatfind' Switches - =================== - - The command line for `gnatfind' is: - - $ gnatfind [switches] pattern[:sourcefile[:line[:column]]] - [file1 file2 ...] - - where - - `pattern' - An entity will be output only if it matches the regular expression - found in `pattern', see *Note Regular Expressions in gnatfind and - gnatxref::. - - Omitting the pattern is equivalent to specifying `*', which will - match any entity. Note that if you do not provide a pattern, you - have to provide both a sourcefile and a line. - - Entity names are given in Latin-1, with uppercase/lowercase - equivalence for matching purposes. At the current time there is no - support for 8-bit codes other than Latin-1, or for wide characters - in identifiers. - - `sourcefile' - `gnatfind' will look for references, bodies or declarations of - symbols referenced in `sourcefile', at line `line' and column - `column'. See *note Examples of gnatfind Usage:: for syntax - examples. - - `line' - is a decimal integer identifying the line number containing the - reference to the entity (or entities) to be located. - - `column' - is a decimal integer identifying the exact location on the line of - the first character of the identifier for the entity reference. - Columns are numbered from 1. - - `file1 file2 ...' - The search will be restricted to these files. If none are given, - then the search will be done for every library file in the search - path. These file must appear only after the pattern or sourcefile. - - These file names are considered to be regular expressions, so for - instance specifying 'source*.adb' is the same as giving every file - in the current directory whose name starts with 'source' and whose - extension is 'adb'. - - Not that if you specify at least one file in this part, `gnatfind' - may sometimes not be able to find the body of the subprograms... - - At least one of 'sourcefile' or 'pattern' has to be present on the - command line. - - The following switches are available: - `-a' - If this switch is present, `gnatfind' and `gnatxref' will parse - the read-only files found in the library search path. Otherwise, - these files will be ignored. This option can be used to protect - Gnat sources or your own libraries from being parsed, thus making - `gnatfind' and `gnatxref' much faster, and their output much - smaller. - - `-aIDIR' - When looking for source files also look in directory DIR. The - order in which source file search is undertaken is the same as for - `gnatmake'. - - `-aODIR' - When searching for library and object files, look in directory - DIR. The order in which library files are searched is the same as - for `gnatmake'. - - `-nostdinc' - Do not look for sources in the system default directory. - - `-nostdlib' - Do not look for library files in the system default directory. - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-d' - If this switch is set, then `gnatfind' will output the parent type - reference for each matching derived types. - - `-e' - By default, `gnatfind' accept the simple regular expression set for - `pattern'. If this switch is set, then the pattern will be - considered as full Unix-style regular expression. - - `-f' - If this switch is set, the output file names will be preceded by - their directory (if the file was found in the search path). If - this switch is not set, the directory will not be printed. - - `-g' - If this switch is set, information is output only for library-level - entities, ignoring local entities. The use of this switch may - accelerate `gnatfind' and `gnatxref'. - - `-IDIR' - Equivalent to `-aODIR -aIDIR'. - - `-pFILE' - Specify a project file (*note Project Files::) to use. By - default, `gnatxref' and `gnatfind' will try to locate a project - file in the current directory. - - If a project file is either specified or found by the tools, then - the content of the source directory and object directory lines are - added as if they had been specified respectively by `-aI' and - `-aO'. - - `-r' - By default, `gnatfind' will output only the information about the - declaration, body or type completion of the entities. If this - switch is set, the `gnatfind' will locate every reference to the - entities in the files specified on the command line (or in every - file in the search path if no file is given on the command line). - - `-s' - If this switch is set, then `gnatfind' will output the content of - the Ada source file lines were the entity was found. - - `-t' - If this switch is set, then `gnatfind' will output the type - hierarchy for the specified type. It act like -d option but - recursively from parent type to parent type. When this switch is - set it is not possible to specify more than one file. - - All these switches may be in any order on the command line, and may - even appear after the file names. They need not be separated by spaces, - thus you can say `gnatxref -ag' instead of `gnatxref -a -g'. - - As stated previously, gnatfind will search in every directory in the - search path. You can force it to look only in the current directory if - you specify `*' at the end of the command line. - -  - File: gnat_ug_wnt.info, Node: Project Files for gnatxref and gnatfind, Next: Regular Expressions in gnatfind and gnatxref, Prev: gnatfind Switches, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Project Files for `gnatxref' and `gnatfind' - =========================================== - - Project files allow a programmer to specify how to compile its - application, where to find sources,... These files are used primarily by - the Glide Ada mode, but they can also be used by the two tools - `gnatxref' and `gnatfind'. - - A project file name must end with `.adp'. If a single one is present - in the current directory, then `gnatxref' and `gnatfind' will extract - the information from it. If multiple project files are found, none of - them is read, and you have to use the `-p' switch to specify the one - you want to use. - - The following lines can be included, even though most of them have - default values which can be used in most cases. The lines can be - entered in any order in the file. Except for `src_dir' and `obj_dir', - you can only have one instance of each line. If you have multiple - instances, only the last one is taken into account. - - `src_dir=DIR [default: "./"]' - specifies a directory where to look for source files. Multiple - src_dir lines can be specified and they will be searched in the - order they are specified. - - `obj_dir=DIR [default: "./"]' - specifies a directory where to look for object and library files. - Multiple obj_dir lines can be specified and they will be searched - in the order they are specified - - `comp_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${comp_opt}' notation. This is intended to store the default - switches given to `gnatmake' and `gcc'. - - `bind_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${bind_opt}' notation. This is intended to store the default - switches given to `gnatbind'. - - `link_opt=SWITCHES [default: ""]' - creates a variable which can be referred to subsequently by using - the `${link_opt}' notation. This is intended to store the default - switches given to `gnatlink'. - - `main=EXECUTABLE [default: ""]' - specifies the name of the executable for the application. This - variable can be referred to in the following lines by using the - `${main}' notation. - - `comp_cmd=COMMAND [default: "gcc -c -I${src_dir} -g -gnatq"]' - specifies the command used to compile a single file in the - application. - - `make_cmd=COMMAND [default: "gnatmake ${main} -aI${src_dir} -aO${obj_dir} -g -gnatq -cargs ${comp_opt} -bargs ${bind_opt} -largs ${link_opt}"]' - specifies the command used to recompile the whole application. - - `run_cmd=COMMAND [default: "${main}"]' - specifies the command used to run the application. - - `debug_cmd=COMMAND [default: "gdb ${main}"]' - specifies the command used to debug the application - - `gnatxref' and `gnatfind' only take into account the `src_dir' and - `obj_dir' lines, and ignore the others. - -  - File: gnat_ug_wnt.info, Node: Regular Expressions in gnatfind and gnatxref, Next: Examples of gnatxref Usage, Prev: Project Files for gnatxref and gnatfind, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Regular Expressions in `gnatfind' and `gnatxref' - ================================================ - - As specified in the section about `gnatfind', the pattern can be a - regular expression. Actually, there are to set of regular expressions - which are recognized by the program : - - `globbing patterns' - These are the most usual regular expression. They are the same - that you generally used in a Unix shell command line, or in a DOS - session. - - Here is a more formal grammar : - regexp ::= term - term ::= elmt -- matches elmt - term ::= elmt elmt -- concatenation (elmt then elmt) - term ::= * -- any string of 0 or more characters - term ::= ? -- matches any character - term ::= [char {char}] -- matches any character listed - term ::= [char - char] -- matches any character in range - - `full regular expression' - The second set of regular expressions is much more powerful. This - is the type of regular expressions recognized by utilities such a - `grep'. - - The following is the form of a regular expression, expressed in Ada - reference manual style BNF is as follows - - regexp ::= term {| term} -- alternation (term or term ...) - - term ::= item {item} -- concatenation (item then item) - - item ::= elmt -- match elmt - item ::= elmt * -- zero or more elmt's - item ::= elmt + -- one or more elmt's - item ::= elmt ? -- matches elmt or nothing - elmt ::= nschar -- matches given character - elmt ::= [nschar {nschar}] -- matches any character listed - elmt ::= [^ nschar {nschar}] -- matches any character not listed - elmt ::= [char - char] -- matches chars in given range - elmt ::= \ char -- matches given character - elmt ::= . -- matches any single character - elmt ::= ( regexp ) -- parens used for grouping - - char ::= any character, including special characters - nschar ::= any character except ()[].*+?^ - - Following are a few examples : - - `abcde|fghi' - will match any of the two strings 'abcde' and 'fghi'. - - `abc*d' - will match any string like 'abd', 'abcd', 'abccd', 'abcccd', - and so on - - `[a-z]+' - will match any string which has only lowercase characters in - it (and at least one character - -  - File: gnat_ug_wnt.info, Node: Examples of gnatxref Usage, Next: Examples of gnatfind Usage, Prev: Regular Expressions in gnatfind and gnatxref, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Examples of `gnatxref' Usage - ============================ - - General Usage - ------------- - - For the following examples, we will consider the following units : - - main.ads: - 1: with Bar; - 2: package Main is - 3: procedure Foo (B : in Integer); - 4: C : Integer; - 5: private - 6: D : Integer; - 7: end Main; - - main.adb: - 1: package body Main is - 2: procedure Foo (B : in Integer) is - 3: begin - 4: C := B; - 5: D := B; - 6: Bar.Print (B); - 7: Bar.Print (C); - 8: end Foo; - 9: end Main; - - bar.ads: - 1: package Bar is - 2: procedure Print (B : Integer); - 3: end bar; - - The first thing to do is to recompile your application (for - instance, in that case just by doing a `gnatmake main', so that - GNAT generates the cross-referencing information. You can then - issue any of the following commands: - - `gnatxref main.adb' - `gnatxref' generates cross-reference information for main.adb and - every unit 'with'ed by main.adb. - - The output would be: - B Type: Integer - Decl: bar.ads 2:22 - B Type: Integer - Decl: main.ads 3:20 - Body: main.adb 2:20 - Ref: main.adb 4:13 5:13 6:19 - Bar Type: Unit - Decl: bar.ads 1:9 - Ref: main.adb 6:8 7:8 - main.ads 1:6 - C Type: Integer - Decl: main.ads 4:5 - Modi: main.adb 4:8 - Ref: main.adb 7:19 - D Type: Integer - Decl: main.ads 6:5 - Modi: main.adb 5:8 - Foo Type: Unit - Decl: main.ads 3:15 - Body: main.adb 2:15 - Main Type: Unit - Decl: main.ads 2:9 - Body: main.adb 1:14 - Print Type: Unit - Decl: bar.ads 2:15 - Ref: main.adb 6:12 7:12 - - that is the entity `Main' is declared in main.ads, line 2, column - 9, its body is in main.adb, line 1, column 14 and is not - referenced any where. - - The entity `Print' is declared in bar.ads, line 2, column 15 and it - it referenced in main.adb, line 6 column 12 and line 7 column 12. - - `gnatxref package1.adb package2.ads' - `gnatxref' will generates cross-reference information for - package1.adb, package2.ads and any other package 'with'ed by any - of these. - - Using gnatxref with vi - ---------------------- - - `gnatxref' can generate a tags file output, which can be used - directly from `vi'. Note that the standard version of `vi' will not - work properly with overloaded symbols. Consider using another free - implementation of `vi', such as `vim'. - - $ gnatxref -v gnatfind.adb > tags - - will generate the tags file for `gnatfind' itself (if the sources are - in the search path!). - - From `vi', you can then use the command `:tag entity' (replacing - entity by whatever you are looking for), and vi will display a new file - with the corresponding declaration of entity. - -  - File: gnat_ug_wnt.info, Node: Examples of gnatfind Usage, Prev: Examples of gnatxref Usage, Up: The Cross-Referencing Tools gnatxref and gnatfind - - Examples of `gnatfind' Usage - ============================ - - `gnatfind -f xyz:main.adb' - Find declarations for all entities xyz referenced at least once in - main.adb. The references are search in every library file in the - search path. - - The directories will be printed as well (as the `-f' switch is set) - - The output will look like: - directory/main.ads:106:14: xyz <= declaration - directory/main.adb:24:10: xyz <= body - directory/foo.ads:45:23: xyz <= declaration - - that is to say, one of the entities xyz found in main.adb is - declared at line 12 of main.ads (and its body is in main.adb), and - another one is declared at line 45 of foo.ads - - `gnatfind -fs xyz:main.adb' - This is the same command as the previous one, instead `gnatfind' - will display the content of the Ada source file lines. - - The output will look like: - - directory/main.ads:106:14: xyz <= declaration - procedure xyz; - directory/main.adb:24:10: xyz <= body - procedure xyz is - directory/foo.ads:45:23: xyz <= declaration - xyz : Integer; - - This can make it easier to find exactly the location your are - looking for. - - `gnatfind -r "*x*":main.ads:123 foo.adb' - Find references to all entities containing an x that are - referenced on line 123 of main.ads. The references will be - searched only in main.adb and foo.adb. - - `gnatfind main.ads:123' - Find declarations and bodies for all entities that are referenced - on line 123 of main.ads. - - This is the same as `gnatfind "*":main.adb:123'. - - `gnatfind mydir/main.adb:123:45' - Find the declaration for the entity referenced at column 45 in - line 123 of file main.adb in directory mydir. Note that it is - usual to omit the identifier name when the column is given, since - the column position identifies a unique reference. - - The column has to be the beginning of the identifier, and should - not point to any character in the middle of the identifier. - -  - File: gnat_ug_wnt.info, Node: File Name Krunching Using gnatkr, Next: Preprocessing Using gnatprep, Prev: The Cross-Referencing Tools gnatxref and gnatfind, Up: Top - - File Name Krunching Using `gnatkr' - ********************************** - - This chapter discusses the method used by the compiler to shorten the - default file names chosen for Ada units so that they do not exceed the - maximum length permitted. It also describes the `gnatkr' utility that - can be used to determine the result of applying this shortening. - - * Menu: - - * About gnatkr:: - * Using gnatkr:: - * Krunching Method:: - * Examples of gnatkr Usage:: - -  - File: gnat_ug_wnt.info, Node: About gnatkr, Next: Using gnatkr, Up: File Name Krunching Using gnatkr - - About `gnatkr' - ============== - - The default file naming rule in GNAT is that the file name must be - derived from the unit name. The exact default rule is as follows: - * Take the unit name and replace all dots by hyphens. - - * If such a replacement occurs in the second character position of a - name, and the first character is a, g, s, or i then replace the - dot by the character ~ (tilde) instead of a minus. - The reason for this exception is to avoid clashes with the standard - names for children of System, Ada, Interfaces, and GNAT, which use the - prefixes s- a- i- and g- respectively. - - The `-gnatkNN' switch of the compiler activates a "krunching" - circuit that limits file names to nn characters (where nn is a decimal - integer). For example, using OpenVMS, where the maximum file name - length is 39, the value of nn is usually set to 39, but if you want to - generate a set of files that would be usable if ported to a system with - some different maximum file length, then a different value can be - specified. The default value of 39 for OpenVMS need not be specified. - - The `gnatkr' utility can be used to determine the krunched name for - a given file, when krunched to a specified maximum length. - -  - File: gnat_ug_wnt.info, Node: Using gnatkr, Next: Krunching Method, Prev: About gnatkr, Up: File Name Krunching Using gnatkr - - Using `gnatkr' - ============== - - The `gnatkr' command has the form - - $ gnatkr NAME [LENGTH] - - NAME can be an Ada name with dots or the GNAT name of the unit, where - the dots representing child units or subunit are replaced by hyphens. - The only confusion arises if a name ends in `.ads' or `.adb'. `gnatkr' - takes this to be an extension if there are no other dots in the name - and the whole name is in lowercase. - - LENGTH represents the length of the krunched name. The default when - no argument is given is 8 characters. A length of zero stands for - unlimited, in other words do not chop except for system files which are - always 8. - - The output is the krunched name. The output has an extension only if the - original argument was a file name with an extension. - -  - File: gnat_ug_wnt.info, Node: Krunching Method, Next: Examples of gnatkr Usage, Prev: Using gnatkr, Up: File Name Krunching Using gnatkr - - Krunching Method - ================ - - The initial file name is determined by the name of the unit that the - file contains. The name is formed by taking the full expanded name of - the unit and replacing the separating dots with hyphens and using - lowercase for all letters, except that a hyphen in the second character - position is replaced by a tilde if the first character is a, i, g, or s. - The extension is `.ads' for a specification and `.adb' for a body. - Krunching does not affect the extension, but the file name is shortened - to the specified length by following these rules: - - * The name is divided into segments separated by hyphens, tildes or - underscores and all hyphens, tildes, and underscores are - eliminated. If this leaves the name short enough, we are done. - - * If the name is too long, the longest segment is located (left-most - if there are two of equal length), and shortened by dropping its - last character. This is repeated until the name is short enough. - - As an example, consider the krunching of - `our-strings-wide_fixed.adb' to fit the name into 8 characters as - required by some operating systems. - - our-strings-wide_fixed 22 - our strings wide fixed 19 - our string wide fixed 18 - our strin wide fixed 17 - our stri wide fixed 16 - our stri wide fixe 15 - our str wide fixe 14 - our str wid fixe 13 - our str wid fix 12 - ou str wid fix 11 - ou st wid fix 10 - ou st wi fix 9 - ou st wi fi 8 - Final file name: oustwifi.adb - - * The file names for all predefined units are always krunched to - eight characters. The krunching of these predefined units uses the - following special prefix replacements: - - `ada-' - replaced by `a-' - - `gnat-' - replaced by `g-' - - `interfaces-' - replaced by `i-' - - `system-' - replaced by `s-' - - These system files have a hyphen in the second character position. - That is why normal user files replace such a character with a - tilde, to avoid confusion with system file names. - - As an example of this special rule, consider - `ada-strings-wide_fixed.adb', which gets krunched as follows: - - ada-strings-wide_fixed 22 - a- strings wide fixed 18 - a- string wide fixed 17 - a- strin wide fixed 16 - a- stri wide fixed 15 - a- stri wide fixe 14 - a- str wide fixe 13 - a- str wid fixe 12 - a- str wid fix 11 - a- st wid fix 10 - a- st wi fix 9 - a- st wi fi 8 - Final file name: a-stwifi.adb - - Of course no file shortening algorithm can guarantee uniqueness over - all possible unit names, and if file name krunching is used then it is - your responsibility to ensure that no name clashes occur. The utility - program `gnatkr' is supplied for conveniently determining the krunched - name of a file. - -  - File: gnat_ug_wnt.info, Node: Examples of gnatkr Usage, Prev: Krunching Method, Up: File Name Krunching Using gnatkr - - Examples of `gnatkr' Usage - ========================== - - $ gnatkr very_long_unit_name.ads --> velounna.ads - $ gnatkr grandparent-parent-child.ads --> grparchi.ads - $ gnatkr Grandparent.Parent.Child --> grparchi - $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads - $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads - -  - File: gnat_ug_wnt.info, Node: Preprocessing Using gnatprep, Next: The GNAT Library Browser gnatls, Prev: File Name Krunching Using gnatkr, Up: Top - - Preprocessing Using `gnatprep' - ****************************** - - The `gnatprep' utility provides a simple preprocessing capability for - Ada programs. It is designed for use with GNAT, but is not dependent - on any special features of GNAT. - - * Menu: - - * Using gnatprep:: - * Switches for gnatprep:: - * Form of Definitions File:: - * Form of Input Text for gnatprep:: - -  - File: gnat_ug_wnt.info, Node: Using gnatprep, Next: Switches for gnatprep, Up: Preprocessing Using gnatprep - - Using `gnatprep' - ================ - - To call `gnatprep' use - - $ gnatprep [-bcrsu] [-Dsymbol=value] infile outfile [deffile] - - where - `infile' - is the full name of the input file, which is an Ada source file - containing preprocessor directives. - - `outfile' - is the full name of the output file, which is an Ada source in - standard Ada form. When used with GNAT, this file name will - normally have an ads or adb suffix. - - `deffile' - is the full name of a text file containing definitions of symbols - to be referenced by the preprocessor. This argument is optional, - and can be replaced by the use of the `-D' switch. - - `switches' - is an optional sequence of switches as described in the next - section. - -  - File: gnat_ug_wnt.info, Node: Switches for gnatprep, Next: Form of Definitions File, Prev: Using gnatprep, Up: Preprocessing Using gnatprep - - Switches for `gnatprep' - ======================= - - `-b' - Causes both preprocessor lines and the lines deleted by - preprocessing to be replaced by blank lines in the output source - file, preserving line numbers in the output file. - - `-c' - Causes both preprocessor lines and the lines deleted by - preprocessing to be retained in the output source as comments - marked with the special string "-! ". This option will result in - line numbers being preserved in the output file. - - `-Dsymbol=value' - Defines a new symbol, associated with value. If no value is given - on the command line, then symbol is considered to be `True'. This - switch can be used in place of a definition file. - - `-r' - Causes a `Source_Reference' pragma to be generated that references - the original input file, so that error messages will use the file - name of this original file. The use of this switch implies that - preprocessor lines are not to be removed from the file, so its use - will force `-b' mode if `-c' has not been specified explicitly. - - Note that if the file to be preprocessed contains multiple units, - then it will be necessary to `gnatchop' the output file from - `gnatprep'. If a `Source_Reference' pragma is present in the - preprocessed file, it will be respected by `gnatchop -r' so that - the final chopped files will correctly refer to the original input - source file for `gnatprep'. - - `-s' - Causes a sorted list of symbol names and values to be listed on - the standard output file. - - `-u' - Causes undefined symbols to be treated as having the value FALSE - in the context of a preprocessor test. In the absence of this - option, an undefined symbol in a `#if' or `#elsif' test will be - treated as an error. - - Note: if neither `-b' nor `-c' is present, then preprocessor lines and - deleted lines are completely removed from the output, unless -r is - specified, in which case -b is assumed. - -  - File: gnat_ug_wnt.info, Node: Form of Definitions File, Next: Form of Input Text for gnatprep, Prev: Switches for gnatprep, Up: Preprocessing Using gnatprep - - Form of Definitions File - ======================== - - The definitions file contains lines of the form - - symbol := value - - where symbol is an identifier, following normal Ada (case-insensitive) - rules for its syntax, and value is one of the following: - - * Empty, corresponding to a null substitution - - * A string literal using normal Ada syntax - - * Any sequence of characters from the set (letters, digits, period, - underline). - - Comment lines may also appear in the definitions file, starting with - the usual `--', and comments may be added to the definitions lines. - -  - File: gnat_ug_wnt.info, Node: Form of Input Text for gnatprep, Prev: Form of Definitions File, Up: Preprocessing Using gnatprep - - Form of Input Text for `gnatprep' - ================================= - - The input text may contain preprocessor conditional inclusion lines, as - well as general symbol substitution sequences. - - The preprocessor conditional inclusion commands have the form - - #if expression [then] - lines - #elsif expression [then] - lines - #elsif expression [then] - lines - ... - #else - lines - #end if; - - In this example, expression is defined by the following grammar: - expression ::= - expression ::= = "" - expression ::= = - expression ::= 'Defined - expression ::= not expression - expression ::= expression and expression - expression ::= expression or expression - expression ::= expression and then expression - expression ::= expression or else expression - expression ::= ( expression ) - - For the first test (expression ::= ) the symbol must have - either the value true or false, that is to say the right-hand of the - symbol definition must be one of the (case-insensitive) literals `True' - or `False'. If the value is true, then the corresponding lines are - included, and if the value is false, they are excluded. - - The test (expression ::= `'Defined') is true only if the - symbol has been defined in the definition file or by a `-D' switch on - the command line. Otherwise, the test is false. - - The equality tests are case insensitive, as are all the preprocessor - lines. - - If the symbol referenced is not defined in the symbol definitions - file, then the effect depends on whether or not switch `-u' is - specified. If so, then the symbol is treated as if it had the value - false and the test fails. If this switch is not specified, then it is - an error to reference an undefined symbol. It is also an error to - reference a symbol that is defined with a value other than `True' or - `False'. - - The use of the `not' operator inverts the sense of this logical - test, so that the lines are included only if the symbol is not defined. - The `then' keyword is optional as shown - - The `#' must be the first non-blank character on a line, but - otherwise the format is free form. Spaces or tabs may appear between - the `#' and the keyword. The keywords and the symbols are case - insensitive as in normal Ada code. Comments may be used on a - preprocessor line, but other than that, no other tokens may appear on a - preprocessor line. Any number of `elsif' clauses can be present, - including none at all. The `else' is optional, as in Ada. - - The `#' marking the start of a preprocessor line must be the first - non-blank character on the line, i.e. it must be preceded only by - spaces or horizontal tabs. - - Symbol substitution outside of preprocessor lines is obtained by - using the sequence - - $symbol - - anywhere within a source line, except in a comment or within a string - literal. The identifier following the `$' must match one of the symbols - defined in the symbol definition file, and the result is to substitute - the value of the symbol in place of `$symbol' in the output file. - - Note that although the substitution of strings within a string - literal is not possible, it is possible to have a symbol whose defined - value is a string literal. So instead of setting XYZ to `hello' and - writing: - - Header : String := "$XYZ"; - - you should set XYZ to `"hello"' and write: - - Header : String := $XYZ; - - and then the substitution will occur as desired. - -  - File: gnat_ug_wnt.info, Node: The GNAT Library Browser gnatls, Next: GNAT and Libraries, Prev: Preprocessing Using gnatprep, Up: Top - - The GNAT Library Browser `gnatls' - ********************************* - - `gnatls' is a tool that outputs information about compiled units. It - gives the relationship between objects, unit names and source files. It - can also be used to check the source dependencies of a unit as well as - various characteristics. - - * Menu: - - * Running gnatls:: - * Switches for gnatls:: - * Examples of gnatls Usage:: - -  - File: gnat_ug_wnt.info, Node: Running gnatls, Next: Switches for gnatls, Up: The GNAT Library Browser gnatls - - Running `gnatls' - ================ - - The `gnatls' command has the form - - $ gnatls switches OBJECT_OR_ALI_FILE - - The main argument is the list of object or `ali' files (*note The Ada - Library Information Files::) for which information is requested. - - In normal mode, without additional option, `gnatls' produces a - four-column listing. Each line represents information for a specific - object. The first column gives the full path of the object, the second - column gives the name of the principal unit in this object, the third - column gives the status of the source and the fourth column gives the - full path of the source representing this unit. Here is a simple - example of use: - - $ gnatls *.o - ./demo1.o demo1 DIF demo1.adb - ./demo2.o demo2 OK demo2.adb - ./hello.o h1 OK hello.adb - ./instr-child.o instr.child MOK instr-child.adb - ./instr.o instr OK instr.adb - ./tef.o tef DIF tef.adb - ./text_io_example.o text_io_example OK text_io_example.adb - ./tgef.o tgef DIF tgef.adb - - The first line can be interpreted as follows: the main unit which is - contained in object file `demo1.o' is demo1, whose main source is in - `demo1.adb'. Furthermore, the version of the source used for the - compilation of demo1 has been modified (DIF). Each source file has a - status qualifier which can be: - - `OK (unchanged)' - The version of the source file used for the compilation of the - specified unit corresponds exactly to the actual source file. - - `MOK (slightly modified)' - The version of the source file used for the compilation of the - specified unit differs from the actual source file but not enough - to require recompilation. If you use gnatmake with the qualifier - `-m (minimal recompilation)', a file marked MOK will not be - recompiled. - - `DIF (modified)' - No version of the source found on the path corresponds to the - source used to build this object. - - `??? (file not found)' - No source file was found for this unit. - - `HID (hidden, unchanged version not first on PATH)' - The version of the source that corresponds exactly to the source - used for compilation has been found on the path but it is hidden - by another version of the same source that has been modified. - -  - File: gnat_ug_wnt.info, Node: Switches for gnatls, Next: Examples of gnatls Usage, Prev: Running gnatls, Up: The GNAT Library Browser gnatls - - Switches for `gnatls' - ===================== - - `gnatls' recognizes the following switches: - - `-a' - Consider all units, including those of the predefined Ada library. - Especially useful with `-d'. - - `-d' - List sources from which specified units depend on. - - `-h' - Output the list of options. - - `-o' - Only output information about object files. - - `-s' - Only output information about source files. - - `-u' - Only output information about compilation units. - - `-aODIR' - `-aIDIR' - `-IDIR' - `-I-' - `-nostdinc' - Source path manipulation. Same meaning as the equivalent - `gnatmake' flags (see *Note Switches for gnatmake::). - - `--RTS=RTS-PATH' - Specifies the default location of the runtime library. Same - meaning as the equivalent `gnatmake' flag (see *Note Switches for - gnatmake::). - - `-v' - Verbose mode. Output the complete source and object paths. Do not - use the default column layout but instead use long format giving - as much as information possible on each requested units, including - special characteristics such as: - - `Preelaborable' - The unit is preelaborable in the Ada 95 sense. - - `No_Elab_Code' - No elaboration code has been produced by the compiler for - this unit. - - `Pure' - The unit is pure in the Ada 95 sense. - - `Elaborate_Body' - The unit contains a pragma Elaborate_Body. - - `Remote_Types' - The unit contains a pragma Remote_Types. - - `Shared_Passive' - The unit contains a pragma Shared_Passive. - - `Predefined' - This unit is part of the predefined environment and cannot be - modified by the user. - - `Remote_Call_Interface' - The unit contains a pragma Remote_Call_Interface. - -  - File: gnat_ug_wnt.info, Node: Examples of gnatls Usage, Prev: Switches for gnatls, Up: The GNAT Library Browser gnatls - - Example of `gnatls' Usage - ========================= - - Example of using the verbose switch. Note how the source and object - paths are affected by the -I switch. - - $ gnatls -v -I.. demo1.o - - GNATLS 3.10w (970212) Copyright 1999 Free Software Foundation, Inc. - - Source Search Path: - - ../ - /home/comar/local/adainclude/ - - Object Search Path: - - ../ - /home/comar/local/lib/gcc-lib/mips-sni-sysv4/2.7.2/adalib/ - - ./demo1.o - Unit => - Name => demo1 - Kind => subprogram body - Flags => No_Elab_Code - Source => demo1.adb modified - - The following is an example of use of the dependency list. Note the - use of the -s switch which gives a straight list of source files. This - can be useful for building specialized scripts. - - $ gnatls -d demo2.o - ./demo2.o demo2 OK demo2.adb - OK gen_list.ads - OK gen_list.adb - OK instr.ads - OK instr-child.ads - - $ gnatls -d -s -a demo1.o - demo1.adb - /home/comar/local/adainclude/ada.ads - /home/comar/local/adainclude/a-finali.ads - /home/comar/local/adainclude/a-filico.ads - /home/comar/local/adainclude/a-stream.ads - /home/comar/local/adainclude/a-tags.ads - gen_list.ads - gen_list.adb - /home/comar/local/adainclude/gnat.ads - /home/comar/local/adainclude/g-io.ads - instr.ads - /home/comar/local/adainclude/system.ads - /home/comar/local/adainclude/s-exctab.ads - /home/comar/local/adainclude/s-finimp.ads - /home/comar/local/adainclude/s-finroo.ads - /home/comar/local/adainclude/s-secsta.ads - /home/comar/local/adainclude/s-stalib.ads - /home/comar/local/adainclude/s-stoele.ads - /home/comar/local/adainclude/s-stratt.ads - /home/comar/local/adainclude/s-tasoli.ads - /home/comar/local/adainclude/s-unstyp.ads - /home/comar/local/adainclude/unchconv.ads - -  - File: gnat_ug_wnt.info, Node: GNAT and Libraries, Next: Using the GNU make Utility, Prev: The GNAT Library Browser gnatls, Up: Top - - GNAT and Libraries - ****************** - - This chapter addresses some of the issues related to building and using - a library with GNAT. It also shows how the GNAT run-time library can be - recompiled. - - * Menu: - - * Creating an Ada Library:: - * Installing an Ada Library:: - * Using an Ada Library:: - * Creating an Ada Library to be Used in a Non-Ada Context:: - * Rebuilding the GNAT Run-Time Library:: - -  - File: gnat_ug_wnt.info, Node: Creating an Ada Library, Next: Installing an Ada Library, Up: GNAT and Libraries - - Creating an Ada Library - ======================= - - In the GNAT environment, a library has two components: - * Source files. - - * Compiled code and Ali files. See *Note The Ada Library Information - Files::. - - In order to use other packages *Note The GNAT Compilation Model:: - requires a certain number of sources to be available to the compiler. - The minimal set of sources required includes the specs of all the - packages that make up the visible part of the library as well as all - the sources upon which they depend. The bodies of all visible generic - units must also be provided. - - Although it is not strictly mandatory, it is recommended that all - sources needed to recompile the library be provided, so that the user - can make full use of inter-unit inlining and source-level debugging. - This can also make the situation easier for users that need to upgrade - their compilation toolchain and thus need to recompile the library from - sources. - - The compiled code can be provided in different ways. The simplest way is - to provide directly the set of objects produced by the compiler during - the compilation of the library. It is also possible to group the objects - into an archive using whatever commands are provided by the operating - system. Finally, it is also possible to create a shared library (see - option -shared in the GCC manual). - - There are various possibilities for compiling the units that make up the - library: for example with a Makefile *Note Using the GNU make Utility::, - or with a conventional script. For simple libraries, it is also - possible to create a dummy main program which depends upon all the - packages that comprise the interface of the library. This dummy main - program can then be given to gnatmake, in order to build all the - necessary objects. Here is an example of such a dummy program and the - generic commands used to build an archive or a shared library. - - with My_Lib.Service1; - with My_Lib.Service2; - with My_Lib.Service3; - procedure My_Lib_Dummy is - begin - null; - end; - - # compiling the library - $ gnatmake -c my_lib_dummy.adb - - # we don't need the dummy object itself - $ rm my_lib_dummy.o my_lib_dummy.ali - - # create an archive with the remaining objects - $ ar rc libmy_lib.a *.o - # some systems may require "ranlib" to be run as well - - # or create a shared library - $ gcc -shared -o libmy_lib.so *.o - # some systems may require the code to have been compiled with -fPIC - - When the objects are grouped in an archive or a shared library, the user - needs to specify the desired library at link time, unless a pragma - linker_options has been used in one of the sources: - pragma Linker_Options ("-lmy_lib"); - -  - File: gnat_ug_wnt.info, Node: Installing an Ada Library, Next: Using an Ada Library, Prev: Creating an Ada Library, Up: GNAT and Libraries - - Installing an Ada Library - ========================= - - In the GNAT model, installing a library consists in copying into a - specific location the files that make up this library. It is possible - to install the sources in a different directory from the other files - (ALI, objects, archives) since the source path and the object path can - easily be specified separately. - - For general purpose libraries, it is possible for the system - administrator to put those libraries in the default compiler paths. To - achieve this, he must specify their location in the configuration files - "ada_source_path" and "ada_object_path" that must be located in the GNAT - installation tree at the same place as the gcc spec file. The location - of the gcc spec file can be determined as follows: - $ gcc -v - - The configuration files mentioned above have simple format: each line - in them must contain one unique directory name. Those names are added - to the corresponding path in their order of appearance in the file. The - names can be either absolute or relative, in the latter case, they are - relative to where theses files are located. - - "ada_source_path" and "ada_object_path" might actually not be present - in a GNAT installation, in which case, GNAT will look for its run-time - library in the directories "adainclude" for the sources and "adalib" - for the objects and ALI files. When the files exist, the compiler does - not look in "adainclude" and "adalib" at all, and thus the - "ada_source_path" file must contain the location for the GNAT run-time - sources (which can simply be "adainclude"). In the same way, the - "ada_object_path" file must contain the location for the GNAT run-time - objects (which can simply be "adalib"). - - You can also specify a new default path to the runtime library at - compilation time with the switch "-RTS=RTS-PATH". You can easily choose - and change the runtime you want your program to be compiled with. This - switch is recognized by gcc, gnatmake, gnatbind, gnatls, gnatfind and - gnatxref. - - It is possible to install a library before or after the standard GNAT - library, by reordering the lines in the configuration files. In - general, a library must be installed before the GNAT library if it - redefines any part of it. - -  - File: gnat_ug_wnt.info, Node: Using an Ada Library, Next: Creating an Ada Library to be Used in a Non-Ada Context, Prev: Installing an Ada Library, Up: GNAT and Libraries - - Using an Ada Library - ==================== - - In order to use a Ada library, you need to make sure that this library - is on both your source and object path *Note Search Paths and the - Run-Time Library (RTL):: and *Note Search Paths for gnatbind::. For - instance, you can use the library "mylib" installed in "/dir/my_lib_src" - and "/dir/my_lib_obj" with the following commands: - - $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \ - -largs -lmy_lib - - This can be simplified down to the following: - $ gnatmake my_appl - when the following conditions are met: - * "/dir/my_lib_src" has been added by the user to the environment - variable "ADA_INCLUDE_PATH", or by the administrator to the file - "ada_source_path" - - * "/dir/my_lib_obj" has been added by the user to the environment - variable "ADA_OBJECTS_PATH", or by the administrator to the file - "ada_object_path" - - * a pragma linker_options, as mentioned in *Note Creating an Ada - Library:: as been added to the sources. - -  - File: gnat_ug_wnt.info, Node: Creating an Ada Library to be Used in a Non-Ada Context, Next: Rebuilding the GNAT Run-Time Library, Prev: Using an Ada Library, Up: GNAT and Libraries - - Creating an Ada Library to be Used in a Non-Ada Context - ======================================================= - - The previous sections detailed how to create and install a library that - was usable from an Ada main program. Using this library in a non-Ada - context is not possible, because the elaboration of the library is - automatically done as part of the main program elaboration. - - GNAT also provides the ability to build libraries that can be used - both in an Ada and non-Ada context. This section describes how to - build such a library, and then how to use it from a C program. The - method for interfacing with the library from other languages such as - Fortran for instance remains the same. - - Creating the Library - -------------------- - - * Identify the units representing the interface of the library. - - Here is an example of simple library interface: - - package Interface is - - procedure Do_Something; - - procedure Do_Something_Else; - - end Interface; - - * Use `pragma Export' or `pragma Convention' for the exported - entities. - - Our package `Interface' is then updated as follow: - package Interface is - - procedure Do_Something; - pragma Export (C, Do_Something, "do_something"); - - procedure Do_Something_Else; - pragma Export (C, Do_Something_Else, "do_something_else"); - - end Interface; - - * Compile all the units composing the library. - - * Bind the library objects. - - This step is performed by invoking gnatbind with the `-L' - switch. `gnatbind' will then generate the library elaboration - procedure (named `init') and the run-time finalization - procedure (named `final'). - - # generate the binder file in Ada - $ gnatbind -Lmylib interface - - # generate the binder file in C - $ gnatbind -C -Lmylib interface - - * Compile the files generated by the binder - - $ gcc -c b~interface.adb - - * Create the library; - - The procedure is identical to the procedure explained in *Note - Creating an Ada Library::, except that `b~interface.o' needs to be - added to the list of objects. - - # create an archive file - $ ar cr libmylib.a b~interface.o - - # create a shared library - $ gcc -shared -o libmylib.so b~interface.o - - * Provide a "foreign" view of the library interface; - - The example below shows the content of `mylib_interface.h' (note - that there is no rule for the naming of this file, any name can be - used) - /* the library elaboration procedure */ - extern void mylibinit (void); - - /* the library finalization procedure */ - extern void mylibfinal (void); - - /* the interface exported by the library */ - extern void do_something (void); - extern void do_something_else (void); - - Using the Library - ----------------- - - Libraries built as explained above can be used from any program, - provided that the elaboration procedures (named `mylibinit' in the - previous example) are called before the library services are used. Any - number of libraries can be used simultaneously, as long as the - elaboration procedure of each library is called. - - Below is an example of C program that uses our `mylib' library. - - #include "mylib_interface.h" - - int - main (void) - { - /* First, elaborate the library before using it */ - mylibinit (); - - /* Main program, using the library exported entities */ - do_something (); - do_something_else (); - - /* Library finalization at the end of the program */ - mylibfinal (); - return 0; - } - - Note that this same library can be used from an equivalent Ada main - program. In addition, if the libraries are installed as detailed in - *Note Installing an Ada Library::, it is not necessary to invoke the - library elaboration and finalization routines. The binder will ensure - that this is done as part of the main program elaboration and - finalization phases. - - The Finalization Phase - ---------------------- - - Invoking any library finalization procedure generated by `gnatbind' - shuts down the Ada run time permanently. Consequently, the finalization - of all Ada libraries must be performed at the end of the program. No - call to these libraries nor the Ada run time should be made past the - finalization phase. - - Restrictions in Libraries - ------------------------- - - The pragmas listed below should be used with caution inside libraries, - as they can create incompatibilities with other Ada libraries: - * pragma `Locking_Policy' - - * pragma `Queuing_Policy' - - * pragma `Task_Dispatching_Policy' - - * pragma `Unreserve_All_Interrupts' - When using a library that contains such pragmas, the user must make - sure that all libraries use the same pragmas with the same values. - Otherwise, a `Program_Error' will be raised during the elaboration of - the conflicting libraries. The usage of these pragmas and its - consequences for the user should therefore be well documented. - - Similarly, the traceback in exception occurrences mechanism should be - enabled or disabled in a consistent manner across all libraries. - Otherwise, a Program_Error will be raised during the elaboration of the - conflicting libraries. - - If the `'Version' and `'Body_Version' attributes are used inside a - library, then it is necessary to perform a `gnatbind' step that - mentions all ali files in all libraries, so that version identifiers - can be properly computed. In practice these attributes are rarely - used, so this is unlikely to be a consideration. - -  - File: gnat_ug_wnt.info, Node: Rebuilding the GNAT Run-Time Library, Prev: Creating an Ada Library to be Used in a Non-Ada Context, Up: GNAT and Libraries - - Rebuilding the GNAT Run-Time Library - ==================================== - - It may be useful to recompile the GNAT library in various contexts, the - most important one being the use of partition-wide configuration pragmas - such as Normalize_Scalar. A special Makefile called `Makefile.adalib' - is provided to that effect and can be found in the directory containing - the GNAT library. The location of this directory depends on the way the - GNAT environment has been installed and can be determined by means of - the command: - - $ gnatls -v - - The last entry in the object search path usually contains the gnat - library. This Makefile contains its own documentation and in particular - the set of instructions needed to rebuild a new library and to use it. - -  - File: gnat_ug_wnt.info, Node: Using the GNU make Utility, Next: Finding Memory Problems with gnatmem, Prev: GNAT and Libraries, Up: Top - - Using the GNU `make' Utility - **************************** - - This chapter offers some examples of makefiles that solve specific - problems. It does not explain how to write a makefile (see the GNU make - documentation), nor does it try to replace the `gnatmake' utility - (*note The GNAT Make Program gnatmake::). - - All the examples in this section are specific to the GNU version of - make. Although `make' is a standard utility, and the basic language is - the same, these examples use some advanced features found only in `GNU - make'. - - * Menu: - - * Using gnatmake in a Makefile:: - * Automatically Creating a List of Directories:: - * Generating the Command Line Switches:: - * Overcoming Command Line Length Limits:: - -  - File: gnat_ug_wnt.info, Node: Using gnatmake in a Makefile, Next: Automatically Creating a List of Directories, Up: Using the GNU make Utility - - Using gnatmake in a Makefile - ============================ - - Complex project organizations can be handled in a very powerful way by - using GNU make combined with gnatmake. For instance, here is a Makefile - which allows you to build each subsystem of a big project into a - separate shared library. Such a makefile allows you to significantly - reduce the link time of very big applications while maintaining full - coherence at each step of the build process. - - The list of dependencies are handled automatically by `gnatmake'. - The Makefile is simply used to call gnatmake in each of the appropriate - directories. - - Note that you should also read the example on how to automatically - create the list of directories (*note Automatically Creating a List of - Directories::) which might help you in case your project has a lot of - subdirectories. - - ## This Makefile is intended to be used with the following directory - ## configuration: - ## - The sources are split into a series of csc (computer software components) - ## Each of these csc is put in its own directory. - ## Their name are referenced by the directory names. - ## They will be compiled into shared library (although this would also work - ## with static libraries - ## - The main program (and possibly other packages that do not belong to any - ## csc is put in the top level directory (where the Makefile is). - ## toplevel_dir __ first_csc (sources) __ lib (will contain the library) - ## \_ second_csc (sources) __ lib (will contain the library) - ## \_ ... - ## Although this Makefile is build for shared library, it is easy to modify - ## to build partial link objects instead (modify the lines with -shared and - ## gnatlink below) - ## - ## With this makefile, you can change any file in the system or add any new - ## file, and everything will be recompiled correctly (only the relevant shared - ## objects will be recompiled, and the main program will be re-linked). - - # The list of computer software component for your project. This might be - # generated automatically. - CSC_LIST=aa bb cc - - # Name of the main program (no extension) - MAIN=main - - # If we need to build objects with -fPIC, uncomment the following line - #NEED_FPIC=-fPIC - - # The following variable should give the directory containing libgnat.so - # You can get this directory through 'gnatls -v'. This is usually the last - # directory in the Object_Path. - GLIB=... - - # The directories for the libraries - # (This macro expands the list of CSC to the list of shared libraries, you - # could simply use the expanded form : - # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so - LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so} - - ${MAIN}: objects ${LIB_DIR} - gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared - gnatlink ${MAIN} ${CSC_LIST:%=-l%} - - objects:: - # recompile the sources - gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%} - - # Note: In a future version of GNAT, the following commands will be simplified - # by a new tool, gnatmlib - ${LIB_DIR}: - mkdir -p ${dir $@ } - cd ${dir $@ }; gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat - cd ${dir $@ }; cp -f ../*.ali . - - # The dependencies for the modules - # Note that we have to force the expansion of *.o, since in some cases make won't - # be able to do it itself. - aa/lib/libaa.so: ${wildcard aa/*.o} - bb/lib/libbb.so: ${wildcard bb/*.o} - cc/lib/libcc.so: ${wildcard cc/*.o} - - # Make sure all of the shared libraries are in the path before starting the - # program - run:: - LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN} - - clean:: - ${RM} -rf ${CSC_LIST:%=%/lib} - ${RM} ${CSC_LIST:%=%/*.ali} - ${RM} ${CSC_LIST:%=%/*.o} - ${RM} *.o *.ali ${MAIN} - -  - File: gnat_ug_wnt.info, Node: Automatically Creating a List of Directories, Next: Generating the Command Line Switches, Prev: Using gnatmake in a Makefile, Up: Using the GNU make Utility - - Automatically Creating a List of Directories - ============================================ - - In most makefiles, you will have to specify a list of directories, and - store it in a variable. For small projects, it is often easier to - specify each of them by hand, since you then have full control over what - is the proper order for these directories, which ones should be - included... - - However, in larger projects, which might involve hundreds of - subdirectories, it might be more convenient to generate this list - automatically. - - The example below presents two methods. The first one, although less - general, gives you more control over the list. It involves wildcard - characters, that are automatically expanded by `make'. Its shortcoming - is that you need to explicitly specify some of the organization of your - project, such as for instance the directory tree depth, whether some - directories are found in a separate tree,... - - The second method is the most general one. It requires an external - program, called `find', which is standard on all Unix systems. All the - directories found under a given root directory will be added to the - list. - - # The examples below are based on the following directory hierarchy: - # All the directories can contain any number of files - # ROOT_DIRECTORY -> a -> aa -> aaa - # -> ab - # -> ac - # -> b -> ba -> baa - # -> bb - # -> bc - # This Makefile creates a variable called DIRS, that can be reused any time - # you need this list (see the other examples in this section) - - # The root of your project's directory hierarchy - ROOT_DIRECTORY=. - - #### - # First method: specify explicitly the list of directories - # This allows you to specify any subset of all the directories you need. - #### - - DIRS := a/aa/ a/ab/ b/ba/ - - #### - # Second method: use wildcards - # Note that the argument(s) to wildcard below should end with a '/'. - # Since wildcards also return file names, we have to filter them out - # to avoid duplicate directory names. - # We thus use make's `dir' and `sort' functions. - # It sets DIRs to the following value (note that the directories aaa and baa - # are not given, unless you change the arguments to wildcard). - # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ - #### - - DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/ ${ROOT_DIRECTORY}/*/*/}}} - - #### - # Third method: use an external program - # This command is much faster if run on local disks, avoiding NFS slowdowns. - # This is the most complete command: it sets DIRs to the following value: - # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc - #### - - DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print} - -  - File: gnat_ug_wnt.info, Node: Generating the Command Line Switches, Next: Overcoming Command Line Length Limits, Prev: Automatically Creating a List of Directories, Up: Using the GNU make Utility - - Generating the Command Line Switches - ==================================== - - Once you have created the list of directories as explained in the - previous section (*note Automatically Creating a List of Directories::), - you can easily generate the command line arguments to pass to gnatmake. - - For the sake of completeness, this example assumes that the source - path is not the same as the object path, and that you have two separate - lists of directories. - - # see "Automatically creating a list of directories" to create - # these variables - SOURCE_DIRS= - OBJECT_DIRS= - - GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}} - GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}} - - all: - gnatmake ${GNATMAKE_SWITCHES} main_unit - -  - File: gnat_ug_wnt.info, Node: Overcoming Command Line Length Limits, Prev: Generating the Command Line Switches, Up: Using the GNU make Utility - - Overcoming Command Line Length Limits - ===================================== - - One problem that might be encountered on big projects is that many - operating systems limit the length of the command line. It is thus hard - to give gnatmake the list of source and object directories. - - This example shows how you can set up environment variables, which - will make `gnatmake' behave exactly as if the directories had been - specified on the command line, but have a much higher length limit (or - even none on most systems). - - It assumes that you have created a list of directories in your - Makefile, using one of the methods presented in *Note Automatically - Creating a List of Directories::. For the sake of completeness, we - assume that the object path (where the ALI files are found) is - different from the sources patch. - - Note a small trick in the Makefile below: for efficiency reasons, we - create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are - expanded immediately by `make'. This way we overcome the standard make - behavior which is to expand the variables only when they are actually - used. - - # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH. - # This is the same thing as putting the -I arguments on the command line. - # (the equivalent of using -aI on the command line would be to define - # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECT_PATH). - # You can of course have different values for these variables. - # - # Note also that we need to keep the previous values of these variables, since - # they might have been set before running 'make' to specify where the GNAT - # library is installed. - - # see "Automatically creating a list of directories" to create these - # variables - SOURCE_DIRS= - OBJECT_DIRS= - - empty:= - space:=${empty} ${empty} - SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}} - OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}} - ADA_INCLUDE_PATH += ${SOURCE_LIST} - ADA_OBJECT_PATH += ${OBJECT_LIST} - export ADA_INCLUDE_PATH - export ADA_OBJECT_PATH - - all: - gnatmake main_unit - -  - File: gnat_ug_wnt.info, Node: Finding Memory Problems with gnatmem, Next: Finding Memory Problems with GNAT Debug Pool, Prev: Using the GNU make Utility, Up: Top - - Finding Memory Problems with `gnatmem' - ************************************** - - `gnatmem', is a tool that monitors dynamic allocation and deallocation - activity in a program, and displays information about incorrect - deallocations and possible sources of memory leaks. Gnatmem provides - three type of information: - * General information concerning memory management, such as the total - number of allocations and deallocations, the amount of allocated - memory and the high water mark, i.e. the largest amount of - allocated memory in the course of program execution. - - * Backtraces for all incorrect deallocations, that is to say - deallocations which do not correspond to a valid allocation. - - * Information on each allocation that is potentially the origin of a - memory leak. - - The `gnatmem' command has two modes. It can be used with `gdb' or - with instrumented allocation and deallocation routines. The later mode - is called the `GMEM' mode. Both modes produce the very same output. - - * Menu: - - * Running gnatmem (GDB Mode):: - * Running gnatmem (GMEM Mode):: - * Switches for gnatmem:: - * Examples of gnatmem Usage:: - * GDB and GMEM Modes:: - * Implementation Note:: - -  - File: gnat_ug_wnt.info, Node: Running gnatmem (GDB Mode), Next: Running gnatmem (GMEM Mode), Up: Finding Memory Problems with gnatmem - - Running `gnatmem' (GDB Mode) - ============================ - - The `gnatmem' command has the form - - $ gnatmem [-q] [n] [-o file] user_program [program_arg]* - or - $ gnatmem [-q] [n] -i file - - Gnatmem must be supplied with the executable to examine, followed by its - run-time inputs. For example, if a program is executed with the command: - $ my_program arg1 arg2 - then it can be run under `gnatmem' control using the command: - $ gnatmem my_program arg1 arg2 - - The program is transparently executed under the control of the - debugger *Note The GNAT Debugger GDB::. This does not affect the - behavior of the program, except for sensitive real-time programs. When - the program has completed execution, `gnatmem' outputs a report - containing general allocation/deallocation information and potential - memory leak. For better results, the user program should be compiled - with debugging options *Note Switches for gcc::. - - Here is a simple example of use: - - *************** debut cc - $ gnatmem test_gm - - Global information - ------------------ - Total number of allocations : 45 - Total number of deallocations : 6 - Final Water Mark (non freed mem) : 11.29 Kilobytes - High Water Mark : 11.40 Kilobytes - - . - . - . - Allocation Root # 2 - ------------------- - Number of non freed allocations : 11 - Final Water Mark (non freed mem) : 1.16 Kilobytes - High Water Mark : 1.27 Kilobytes - Backtrace : - test_gm.adb:23 test_gm.alloc - . - . - . - - The first block of output give general information. In this case, the - Ada construct "new" was executed 45 times, and only 6 calls to an - unchecked deallocation routine occurred. - - Subsequent paragraphs display information on all allocation roots. - An allocation root is a specific point in the execution of the program - that generates some dynamic allocation, such as a "new" construct. This - root is represented by an execution backtrace (or subprogram call - stack). By default the backtrace depth for allocations roots is 1, so - that a root corresponds exactly to a source location. The backtrace can - be made deeper, to make the root more specific. - -  - File: gnat_ug_wnt.info, Node: Running gnatmem (GMEM Mode), Next: Switches for gnatmem, Prev: Running gnatmem (GDB Mode), Up: Finding Memory Problems with gnatmem - - Running `gnatmem' (GMEM Mode) - ============================= - - The `gnatmem' command has the form - - $ gnatmem [-q] [n] -i gmem.out user_program [program_arg]* - - The program must have been linked with the instrumented version of - the allocation and deallocation routines. This is done with linking - with the `libgmem.a' library. For better results, the user program - should be compiled with debugging options *Note Switches for gcc::. For - example to build `my_program': - - $ gnatmake -g my_program -largs -lgmem - - When running `my_program' the file `gmem.out' is produced. This file - contains information about all allocations and deallocations done by the - program. It is produced by the instrumented allocations and - deallocations routines and will be used by `gnatmem'. - - Gnatmem must be supplied with the `gmem.out' file and the executable to - examine followed by its run-time inputs. For example, if a program is - executed with the command: - $ my_program arg1 arg2 - then `gmem.out' can be analysed by `gnatmem' using the command: - $ gnatmem -i gmem.out my_program arg1 arg2 - -  - File: gnat_ug_wnt.info, Node: Switches for gnatmem, Next: Examples of gnatmem Usage, Prev: Running gnatmem (GMEM Mode), Up: Finding Memory Problems with gnatmem - - Switches for `gnatmem' - ====================== - - `gnatmem' recognizes the following switches: - - ``-q'' - Quiet. Gives the minimum output needed to identify the origin of - the memory leaks. Omit statistical information. - - ``n'' - N is an integer literal (usually between 1 and 10) which controls - the depth of the backtraces defining allocation root. The default - value for N is 1. The deeper the backtrace, the more precise the - localization of the root. Note that the total number of roots can - depend on this parameter. - - ``-o file'' - Direct the gdb output to the specified file. The `gdb' script used - to generate this output is also saved in the file `gnatmem.tmp'. - - ``-i file'' - Do the `gnatmem' processing starting from `file' which has been - generated by a previous call to `gnatmem' with the -o switch or - `gmem.out' produced by `GMEM' mode. This is useful for post mortem - processing. - -  - File: gnat_ug_wnt.info, Node: Examples of gnatmem Usage, Next: GDB and GMEM Modes, Prev: Switches for gnatmem, Up: Finding Memory Problems with gnatmem - - Example of `gnatmem' Usage - ========================== - - This section is based on the `GDB' mode of `gnatmem'. The same results - can be achieved using `GMEM' mode. See section *Note Running gnatmem - (GMEM Mode)::. - - The first example shows the use of `gnatmem' on a simple leaking - program. Suppose that we have the following Ada program: - - with Unchecked_Deallocation; - procedure Test_Gm is - - type T is array (1..1000) of Integer; - type Ptr is access T; - procedure Free is new Unchecked_Deallocation (T, Ptr); - A : Ptr; - - procedure My_Alloc is - begin - A := new T; - end My_Alloc; - - procedure My_DeAlloc is - B : Ptr := A; - begin - Free (B); - end My_DeAlloc; - - begin - My_Alloc; - for I in 1 .. 5 loop - for J in I .. 5 loop - My_Alloc; - end loop; - My_Dealloc; - end loop; - end; - - The program needs to be compiled with debugging option: - - $ gnatmake -g test_gm - - `gnatmem' is invoked simply with - $ gnatmem test_gm - - which produces the following output: - - Global information - ------------------ - Total number of allocations : 18 - Total number of deallocations : 5 - Final Water Mark (non freed mem) : 53.00 Kilobytes - High Water Mark : 56.90 Kilobytes - - Allocation Root # 1 - ------------------- - Number of non freed allocations : 11 - Final Water Mark (non freed mem) : 42.97 Kilobytes - High Water Mark : 46.88 Kilobytes - Backtrace : - test_gm.adb:11 test_gm.my_alloc - - Allocation Root # 2 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 10.02 Kilobytes - High Water Mark : 10.02 Kilobytes - Backtrace : - s-secsta.adb:81 system.secondary_stack.ss_init - - Allocation Root # 3 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 12 Bytes - High Water Mark : 12 Bytes - Backtrace : - s-secsta.adb:181 system.secondary_stack.ss_init - - Note that the GNAT run time contains itself a certain number of - allocations that have no corresponding deallocation, as shown here for - root #2 and root #1. This is a normal behavior when the number of non - freed allocations is one, it locates dynamic data structures that the - run time needs for the complete lifetime of the program. Note also that - there is only one allocation root in the user program with a single - line back trace: test_gm.adb:11 test_gm.my_alloc, whereas a careful - analysis of the program shows that 'My_Alloc' is called at 2 different - points in the source (line 21 and line 24). If those two allocation - roots need to be distinguished, the backtrace depth parameter can be - used: - - $ gnatmem 3 test_gm - - which will give the following output: - - Global information - ------------------ - Total number of allocations : 18 - Total number of deallocations : 5 - Final Water Mark (non freed mem) : 53.00 Kilobytes - High Water Mark : 56.90 Kilobytes - - Allocation Root # 1 - ------------------- - Number of non freed allocations : 10 - Final Water Mark (non freed mem) : 39.06 Kilobytes - High Water Mark : 42.97 Kilobytes - Backtrace : - test_gm.adb:11 test_gm.my_alloc - test_gm.adb:24 test_gm - b_test_gm.c:52 main - - Allocation Root # 2 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 10.02 Kilobytes - High Water Mark : 10.02 Kilobytes - Backtrace : - s-secsta.adb:81 system.secondary_stack.ss_init - s-secsta.adb:283 - b_test_gm.c:33 adainit - - Allocation Root # 3 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 3.91 Kilobytes - High Water Mark : 3.91 Kilobytes - Backtrace : - test_gm.adb:11 test_gm.my_alloc - test_gm.adb:21 test_gm - b_test_gm.c:52 main - - Allocation Root # 4 - ------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 12 Bytes - High Water Mark : 12 Bytes - Backtrace : - s-secsta.adb:181 system.secondary_stack.ss_init - s-secsta.adb:283 - b_test_gm.c:33 adainit - - The allocation root #1 of the first example has been split in 2 roots #1 - and #3 thanks to the more precise associated backtrace. - -  - File: gnat_ug_wnt.info, Node: GDB and GMEM Modes, Next: Implementation Note, Prev: Examples of gnatmem Usage, Up: Finding Memory Problems with gnatmem - - GDB and GMEM Modes - ================== - - The main advantage of the `GMEM' mode is that it is a lot faster than - the `GDB' mode where the application must be monitored by a `GDB' - script. But the `GMEM' mode is available only for DEC Unix, Linux x86, - Solaris (sparc and x86) and Windows 95/98/NT/2000 (x86). - - The main advantage of the `GDB' mode is that it is available on all - supported platforms. But it can be very slow if the application does a - lot of allocations and deallocations. - -  - File: gnat_ug_wnt.info, Node: Implementation Note, Prev: GDB and GMEM Modes, Up: Finding Memory Problems with gnatmem - - Implementation Note - =================== - - * Menu: - - * gnatmem Using GDB Mode:: - * gnatmem Using GMEM Mode:: - -  - File: gnat_ug_wnt.info, Node: gnatmem Using GDB Mode, Next: gnatmem Using GMEM Mode, Up: Implementation Note - - `gnatmem' Using `GDB' Mode - -------------------------- - - `gnatmem' executes the user program under the control of `GDB' using a - script that sets breakpoints and gathers information on each dynamic - allocation and deallocation. The output of the script is then analyzed - by `gnatmem' in order to locate memory leaks and their origin in the - program. Gnatmem works by recording each address returned by the - allocation procedure (`__gnat_malloc') along with the backtrace at the - allocation point. On each deallocation, the deallocated address is - matched with the corresponding allocation. At the end of the processing, - the unmatched allocations are considered potential leaks. All the - allocations associated with the same backtrace are grouped together and - form an allocation root. The allocation roots are then sorted so that - those with the biggest number of unmatched allocation are printed - first. A delicate aspect of this technique is to distinguish between the - data produced by the user program and the data produced by the gdb - script. Currently, on systems that allow probing the terminal, the gdb - command "tty" is used to force the program output to be redirected to - the current terminal while the `gdb' output is directed to a file or to - a pipe in order to be processed subsequently by `gnatmem'. - -  - File: gnat_ug_wnt.info, Node: gnatmem Using GMEM Mode, Prev: gnatmem Using GDB Mode, Up: Implementation Note - - `gnatmem' Using `GMEM' Mode - --------------------------- - - This mode use the same algorithm to detect memory leak as the `GDB' - mode of `gnatmem', the only difference is in the way data are gathered. - In `GMEM' mode the program is linked with instrumented version of - `__gnat_malloc' and `__gnat_free' routines. Information needed to find - memory leak are recorded by these routines in file `gmem.out'. This - mode also require that the stack traceback be available, this is only - implemented on some platforms *Note GDB and GMEM Modes::. - -  - File: gnat_ug_wnt.info, Node: Finding Memory Problems with GNAT Debug Pool, Next: Creating Sample Bodies Using gnatstub, Prev: Finding Memory Problems with gnatmem, Up: Top - - Finding Memory Problems with GNAT Debug Pool - ******************************************** - - The use of unchecked deallocation and unchecked conversion can easily - lead to incorrect memory references. The problems generated by such - references are usually difficult to tackle because the symptoms can be - very remote from the origin of the problem. In such cases, it is very - helpful to detect the problem as early as possible. This is the purpose - of the Storage Pool provided by `GNAT.Debug_Pools'. - - In order to use the GNAT specific debugging pool, the user must - associate a debug pool object with each of the access types that may be - related to suspected memory problems. See Ada Reference Manual 13.11. - type Ptr is access Some_Type; - Pool : GNAT.Debug_Pools.Debug_Pool; - for Ptr'Storage_Pool use Pool; - - `GNAT.Debug_Pools' is derived from of a GNAT-specific kind of pool: - the Checked_Pool. Such pools, like standard Ada storage pools, allow - the user to redefine allocation and deallocation strategies. They also - provide a checkpoint for each dereference, through the use of the - primitive operation `Dereference' which is implicitly called at each - dereference of an access value. - - Once an access type has been associated with a debug pool, - operations on values of the type may raise four distinct exceptions, - which correspond to four potential kinds of memory corruption: - * `GNAT.Debug_Pools.Accessing_Not_Allocated_Storage' - - * `GNAT.Debug_Pools.Accessing_Deallocated_Storage' - - * `GNAT.Debug_Pools.Freeing_Not_Allocated_Storage' - - * `GNAT.Debug_Pools.Freeing_Deallocated_Storage ' - - For types associated with a Debug_Pool, dynamic allocation is performed - using the standard GNAT allocation routine. References to all allocated - chunks of memory are kept in an internal dictionary. The deallocation - strategy consists in not releasing the memory to the underlying system - but rather to fill it with a memory pattern easily recognizable during - debugging sessions: The memory pattern is the old IBM hexadecimal - convention: 16#DEADBEEF#. Upon each dereference, a check is made that - the access value denotes a properly allocated memory location. Here is - a complete example of use of `Debug_Pools', that includes typical - instances of memory corruption: - with Gnat.Io; use Gnat.Io; - with Unchecked_Deallocation; - with Unchecked_Conversion; - with GNAT.Debug_Pools; - with System.Storage_Elements; - with Ada.Exceptions; use Ada.Exceptions; - procedure Debug_Pool_Test is - - type T is access Integer; - type U is access all T; - - P : GNAT.Debug_Pools.Debug_Pool; - for T'Storage_Pool use P; - - procedure Free is new Unchecked_Deallocation (Integer, T); - function UC is new Unchecked_Conversion (U, T); - A, B : aliased T; - - procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); - - begin - Info (P); - A := new Integer; - B := new Integer; - B := A; - Info (P); - Free (A); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - B := UC(A'Access); - begin - Put_Line (Integer'Image(B.all)); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - begin - Free (B); - exception - when E : others => Put_Line ("raised: " & Exception_Name (E)); - end; - Info (P); - end Debug_Pool_Test; - - The debug pool mechanism provides the following precise diagnostics on - the execution of this erroneous program: - Debug Pool info: - Total allocated bytes : 0 - Total deallocated bytes : 0 - Current Water Mark: 0 - High Water Mark: 0 - - Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 0 - Current Water Mark: 8 - High Water Mark: 8 - - raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE - raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE - Debug Pool info: - Total allocated bytes : 8 - Total deallocated bytes : 4 - Current Water Mark: 4 - High Water Mark: 8 - -  - File: gnat_ug_wnt.info, Node: Creating Sample Bodies Using gnatstub, Next: Reducing the Size of Ada Executables with gnatelim, Prev: Finding Memory Problems with GNAT Debug Pool, Up: Top - - Creating Sample Bodies Using `gnatstub' - *************************************** - - `gnatstub' creates body stubs, that is, empty but compilable bodies for - library unit declarations. - - To create a body stub, `gnatstub' has to compile the library unit - declaration. Therefore, bodies can be created only for legal library - units. Moreover, if a library unit depends semantically upon units - located outside the current directory, you have to provide the source - search path when calling `gnatstub', see the description of `gnatstub' - switches below. - - * Menu: - - * Running gnatstub:: - * Switches for gnatstub:: - -  - File: gnat_ug_wnt.info, Node: Running gnatstub, Next: Switches for gnatstub, Up: Creating Sample Bodies Using gnatstub - - Running `gnatstub' - ================== - - `gnatstub' has the command-line interface of the form - - $ gnatstub [switches] filename [directory] - - where - `filename' - is the name of the source file that contains a library unit - declaration for which a body must be created. This name should - follow the GNAT file name conventions. No crunching is allowed for - this file name. The file name may contain the path information. - - `directory' - indicates the directory to place a body stub (default is the - current directory) - - `switches' - is an optional sequence of switches as described in the next - section - -  - File: gnat_ug_wnt.info, Node: Switches for gnatstub, Prev: Running gnatstub, Up: Creating Sample Bodies Using gnatstub - - Switches for `gnatstub' - ======================= - - `-f' - If the destination directory already contains a file with a name - of the body file for the argument spec file, replace it with the - generated body stub. - - `-hs' - Put the comment header (i.e. all the comments preceding the - compilation unit) from the source of the library unit declaration - into the body stub. - - `-hg' - Put a sample comment header into the body stub. - - `-IDIR' - `-I-' - These switches have the same meaning as in calls to gcc. They - define the source search path in the call to gcc issued by - `gnatstub' to compile an argument source file. - - `-iN' - (N is a decimal natural number). Set the indentation level in the - generated body sample to n, '-i0' means "no indentation", the - default indentation is 3. - - `-k' - Do not remove the tree file (i.e. the snapshot of the compiler - internal structures used by `gnatstub') after creating the body - stub. - - `-lN' - (N is a decimal positive number) Set the maximum line length in the - body stub to n, the default is 78. - - `-q' - Quiet mode: do not generate a confirmation when a body is - successfully created or a message when a body is not required for - an argument unit. - - `-r' - Reuse the tree file (if it exists) instead of creating it: instead - of creating the tree file for the library unit declaration, - gnatstub tries to find it in the current directory and use it for - creating a body. If the tree file is not found, no body is - created. `-r' also implies `-k', whether or not `-k' is set - explicitly. - - `-t' - Overwrite the existing tree file: if the current directory already - contains the file which, according to the GNAT file name rules - should be considered as a tree file for the argument source file, - gnatstub will refuse to create the tree file needed to create a - body sampler, unless `-t' option is set - - `-v' - Verbose mode: generate version information. - -  - File: gnat_ug_wnt.info, Node: Reducing the Size of Ada Executables with gnatelim, Next: Other Utility Programs, Prev: Creating Sample Bodies Using gnatstub, Up: Top - - Reducing the Size of Ada Executables with `gnatelim' - **************************************************** - - * Menu: - - * About gnatelim:: - * Eliminate Pragma:: - * Tree Files:: - * Preparing Tree and Bind Files for gnatelim:: - * Running gnatelim:: - * Correcting the List of Eliminate Pragmas:: - * Making Your Executables Smaller:: - * Summary of the gnatelim Usage Cycle:: - -  - File: gnat_ug_wnt.info, Node: About gnatelim, Next: Eliminate Pragma, Up: Reducing the Size of Ada Executables with gnatelim - - About `gnatelim' - ================ - - When a program shares a set of Ada packages with other programs, it may - happen that this program uses only a fraction of the subprograms - defined in these packages. The code created for these unused - subprograms increases the size of the executable. - - `gnatelim' tracks unused subprograms in an Ada program and outputs a - list of GNAT-specific `Eliminate' pragmas (see next section) marking - all the subprograms that are declared but never called. By placing the - list of `Eliminate' pragmas in the GNAT configuration file `gnat.adc' - and recompiling your program, you may decrease the size of its - executable, because the compiler will not generate the code for - 'eliminated' subprograms. - - `gnatelim' needs as its input data a set of tree files (see *Note - Tree Files::) representing all the components of a program to process - and a bind file for a main subprogram (see *Note Preparing Tree and - Bind Files for gnatelim::). - -  - File: gnat_ug_wnt.info, Node: Eliminate Pragma, Next: Tree Files, Prev: About gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - `Eliminate' Pragma - ================== - - The simplified syntax of the Eliminate pragma used by `gnatelim' is: - - pragma Eliminate (Library_Unit_Name, Subprogram_Name); - - where - `Library_Unit_Name' - full expanded Ada name of a library unit - - `Subprogram_Name' - a simple or expanded name of a subprogram declared within this - compilation unit - - The effect of an `Eliminate' pragma placed in the GNAT configuration - file `gnat.adc' is: - - * If the subprogram `Subprogram_Name' is declared within the library - unit `Library_Unit_Name', the compiler will not generate code for - this subprogram. This applies to all overloaded subprograms denoted - by `Subprogram_Name'. - - * If a subprogram marked by the pragma `Eliminate' is used (called) - in a program, the compiler will produce an error message in the - place where it is called. - -  - File: gnat_ug_wnt.info, Node: Tree Files, Next: Preparing Tree and Bind Files for gnatelim, Prev: Eliminate Pragma, Up: Reducing the Size of Ada Executables with gnatelim - - Tree Files - ========== - - A tree file stores a snapshot of the compiler internal data structures - at the very end of a successful compilation. It contains all the - syntactic and semantic information for the compiled unit and all the - units upon which it depends semantically. To use tools that make use - of tree files, you need to first produce the right set of tree files. - - GNAT produces correct tree files when -gnatt -gnatc options are set - in a gcc call. The tree files have an .adt extension. Therefore, to - produce a tree file for the compilation unit contained in a file named - `foo.adb', you must use the command - - $ gcc -c -gnatc -gnatt foo.adb - - and you will get the tree file `foo.adt'. compilation. - -  - File: gnat_ug_wnt.info, Node: Preparing Tree and Bind Files for gnatelim, Next: Running gnatelim, Prev: Tree Files, Up: Reducing the Size of Ada Executables with gnatelim - - Preparing Tree and Bind Files for `gnatelim' - ============================================ - - A set of tree files covering the program to be analyzed with `gnatelim' - and the bind file for the main subprogram does not have to be in the - current directory. '-T' gnatelim option may be used to provide the - search path for tree files, and '-b' option may be used to point to the - bind file to process (see *Note Running gnatelim::) - - If you do not have the appropriate set of tree files and the right - bind file, you may create them in the current directory using the - following procedure. - - Let `Main_Prog' be the name of a main subprogram, and suppose this - subprogram is in a file named `main_prog.adb'. - - To create a bind file for `gnatelim', run `gnatbind' for the main - subprogram. `gnatelim' can work with both Ada and C bind files; when - both are present, it uses the Ada bind file. The following commands - will build the program and create the bind file: - - $ gnatmake -c Main_Prog - $ gnatbind main_prog - - To create a minimal set of tree files covering the whole program, call - `gnatmake' for this program as follows: - - $ gnatmake -f -c -gnatc -gnatt Main_Prog - - The `-c' gnatmake option turns off the bind and link steps, that are - useless anyway because the sources are compiled with `-gnatc' option - which turns off code generation. - - The `-f' gnatmake option forces recompilation of all the needed - sources. - - This sequence of actions will create all the data needed by - `gnatelim' from scratch and therefore guarantee its consistency. If you - would like to use some existing set of files as `gnatelim' output, you - must make sure that the set of files is complete and consistent. You - can use the `-m' switch to check if there are missed tree files - - Note, that `gnatelim' needs neither object nor ALI files. - -  - File: gnat_ug_wnt.info, Node: Running gnatelim, Next: Correcting the List of Eliminate Pragmas, Prev: Preparing Tree and Bind Files for gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - Running `gnatelim' - ================== - - `gnatelim' has the following command-line interface: - - $ gnatelim [options] name - - `name' should be a full expanded Ada name of a main subprogram of a - program (partition). - - `gnatelim' options: - - `-q' - Quiet mode: by default `gnatelim' generates to the standard error - stream a trace of the source file names of the compilation units - being processed. This option turns this trace off. - - `-v' - Verbose mode: `gnatelim' version information is printed as Ada - comments to the standard output stream. - - `-a' - Also look for subprograms from the GNAT run time that can be - eliminated. - - `-m' - Check if any tree files are missing for an accurate result. - - `-TDIR' - When looking for tree files also look in directory DIR - - `-bBIND_FILE' - Specifies BIND_FILE as the bind file to process. If not set, the - name of the bind file is computed from the full expanded Ada name - of a main subprogram. - - `-dX' - Activate internal debugging switches. X is a letter or digit, or - string of letters or digits, which specifies the type of debugging - mode desired. Normally these are used only for internal - development or system debugging purposes. You can find full - documentation for these switches in the body of the - `Gnatelim.Options' unit in the compiler source file - `gnatelim-options.adb'. - - `gnatelim' sends its output to the standard output stream, and all the - tracing and debug information is sent to the standard error stream. In - order to produce a proper GNAT configuration file `gnat.adc', - redirection must be used: - - $ gnatelim Main_Prog > gnat.adc - - or - - $ gnatelim Main_Prog >> gnat.adc - - In order to append the `gnatelim' output to the existing contents of - `gnat.adc'. - -  - File: gnat_ug_wnt.info, Node: Correcting the List of Eliminate Pragmas, Next: Making Your Executables Smaller, Prev: Running gnatelim, Up: Reducing the Size of Ada Executables with gnatelim - - Correcting the List of Eliminate Pragmas - ======================================== - - In some rare cases it may happen that `gnatelim' will try to eliminate - subprograms which are actually called in the program. In this case, the - compiler will generate an error message of the form: - - file.adb:106:07: cannot call eliminated subprogram "My_Prog" - - You will need to manually remove the wrong `Eliminate' pragmas from the - `gnat.adc' file. It is advised that you recompile your program from - scratch after that because you need a consistent `gnat.adc' file during - the entire compilation. - -  - File: gnat_ug_wnt.info, Node: Making Your Executables Smaller, Next: Summary of the gnatelim Usage Cycle, Prev: Correcting the List of Eliminate Pragmas, Up: Reducing the Size of Ada Executables with gnatelim - - Making Your Executables Smaller - =============================== - - In order to get a smaller executable for your program you now have to - recompile the program completely with the new `gnat.adc' file created - by `gnatelim' in your current directory: - - $ gnatmake -f Main_Prog - - (you will need `-f' option for gnatmake to recompile everything with - the set of pragmas `Eliminate' you have obtained with `gnatelim'). - - Be aware that the set of `Eliminate' pragmas is specific to each - program. It is not recommended to merge sets of `Eliminate' pragmas - created for different programs in one `gnat.adc' file. - -  - File: gnat_ug_wnt.info, Node: Summary of the gnatelim Usage Cycle, Prev: Making Your Executables Smaller, Up: Reducing the Size of Ada Executables with gnatelim - - Summary of the gnatelim Usage Cycle - =================================== - - Here is a quick summary of the steps to be taken in order to reduce the - size of your executables with `gnatelim'. You may use other GNAT - options to control the optimization level, to produce the debugging - information, to set search path, etc. - - 1. Produce a bind file and a set of tree files - - $ gnatmake -c Main_Prog - $ gnatbind main_prog - $ gnatmake -f -c -gnatc -gnatt Main_Prog - - 2. Generate a list of `Eliminate' pragmas - $ gnatelim Main_Prog >[>] gnat.adc - - 3. Recompile the application - - $ gnatmake -f Main_Prog - - -  - File: gnat_ug_wnt.info, Node: Other Utility Programs, Next: Running and Debugging Ada Programs, Prev: Reducing the Size of Ada Executables with gnatelim, Up: Top - - Other Utility Programs - ********************** - - This chapter discusses some other utility programs available in the Ada - environment. - - * Menu: - - * Using Other Utility Programs with GNAT:: - * The gnatpsta Utility Program:: - * The External Symbol Naming Scheme of GNAT:: - * Ada Mode for Glide:: - * Converting Ada Files to html with gnathtml:: - * Installing gnathtml:: - -  - File: gnat_ug_wnt.info, Node: Using Other Utility Programs with GNAT, Next: The gnatpsta Utility Program, Up: Other Utility Programs - - Using Other Utility Programs with GNAT - ====================================== - - The object files generated by GNAT are in standard system format and in - particular the debugging information uses this format. This means - programs generated by GNAT can be used with existing utilities that - depend on these formats. - - In general, any utility program that works with C will also often - work with Ada programs generated by GNAT. This includes software - utilities such as gprof (a profiling program), `gdb' (the FSF - debugger), and utilities such as Purify. - -  - File: gnat_ug_wnt.info, Node: The gnatpsta Utility Program, Next: The External Symbol Naming Scheme of GNAT, Prev: Using Other Utility Programs with GNAT, Up: Other Utility Programs - - The `gnatpsta' Utility Program - ============================== - - Many of the definitions in package Standard are - implementation-dependent. However, the source of this package does not - exist as an Ada source file, so these values cannot be determined by - inspecting the source. They can be determined by examining in detail - the coding of `cstand.adb' which creates the image of Standard in the - compiler, but this is awkward and requires a great deal of internal - knowledge about the system. - - The `gnatpsta' utility is designed to deal with this situation. It - is an Ada program that dynamically determines the values of all the - relevant parameters in Standard, and prints them out in the form of an - Ada source listing for Standard, displaying all the values of interest. - This output is generated to `stdout'. - - To determine the value of any parameter in package Standard, simply - run `gnatpsta' with no qualifiers or arguments, and examine the output. - This is preferable to consulting documentation, because you know that - the values you are getting are the actual ones provided by the - executing system. - -  - File: gnat_ug_wnt.info, Node: The External Symbol Naming Scheme of GNAT, Next: Ada Mode for Glide, Prev: The gnatpsta Utility Program, Up: Other Utility Programs - - The External Symbol Naming Scheme of GNAT - ========================================= - - In order to interpret the output from GNAT, when using tools that are - originally intended for use with other languages, it is useful to - understand the conventions used to generate link names from the Ada - entity names. - - All link names are in all lowercase letters. With the exception of - library procedure names, the mechanism used is simply to use the full - expanded Ada name with dots replaced by double underscores. For - example, suppose we have the following package spec: - - package QRS is - MN : Integer; - end QRS; - - The variable `MN' has a full expanded Ada name of `QRS.MN', so the - corresponding link name is `qrs__mn'. Of course if a `pragma Export' - is used this may be overridden: - - package Exports is - Var1 : Integer; - pragma Export (Var1, C, External_Name => "var1_name"); - Var2 : Integer; - pragma Export (Var2, C, Link_Name => "var2_link_name"); - end Exports; - - In this case, the link name for VAR1 is whatever link name the C - compiler would assign for the C function VAR1_NAME. This typically - would be either VAR1_NAME or _VAR1_NAME, depending on operating system - conventions, but other possibilities exist. The link name for VAR2 is - VAR2_LINK_NAME, and this is not operating system dependent. - - One exception occurs for library level procedures. A potential - ambiguity arises between the required name `_main' for the C main - program, and the name we would otherwise assign to an Ada library level - procedure called `Main' (which might well not be the main program). - - To avoid this ambiguity, we attach the prefix `_ada_' to such names. - So if we have a library level procedure such as - - procedure Hello (S : String); - - the external name of this procedure will be _ADA_HELLO. - -  - File: gnat_ug_wnt.info, Node: Ada Mode for Glide, Next: Converting Ada Files to html with gnathtml, Prev: The External Symbol Naming Scheme of GNAT, Up: Other Utility Programs - - Ada Mode for `Glide' - ==================== - - The Glide mode for programming in Ada (both, Ada83 and Ada95) helps the - user in understanding existing code and facilitates writing new code. It - furthermore provides some utility functions for easier integration of - standard Emacs features when programming in Ada. - - General Features: - ----------------- - - * Full Integrated Development Environment : - - * support of 'project files' for the configuration (directories, - compilation options,...) - - * compiling and stepping through error messages. - - * running and debugging your applications within Glide. - - * easy to use for beginners by pull-down menus, - - * user configurable by many user-option variables. - - Ada Mode Features That Help Understanding Code: - ----------------------------------------------- - - * functions for easy and quick stepping through Ada code, - - * getting cross reference information for identifiers (e.g. find the - defining place by a keystroke), - - * displaying an index menu of types and subprograms and move point to - the chosen one, - - * automatic color highlighting of the various entities in Ada code. - - Glide Support for Writing Ada Code: - ----------------------------------- - - * switching between spec and body files with possible autogeneration - of body files, - - * automatic formating of subprograms parameter lists. - - * automatic smart indentation according to Ada syntax, - - * automatic completion of identifiers, - - * automatic casing of identifiers, keywords, and attributes, - - * insertion of statement templates, - - * filling comment paragraphs like filling normal text, - - For more information, please refer to the online Glide documentation - available in the Glide -> Help Menu. - -  - File: gnat_ug_wnt.info, Node: Converting Ada Files to html with gnathtml, Next: Installing gnathtml, Prev: Ada Mode for Glide, Up: Other Utility Programs - - Converting Ada Files to html with `gnathtml' - ============================================ - - This `Perl' script allows Ada source files to be browsed using standard - Web browsers. For installation procedure, see the section *Note - Installing gnathtml::. - - Ada reserved keywords are highlighted in a bold font and Ada - comments in a blue font. Unless your program was compiled with the gcc - `-gnatx' switch to suppress the generation of cross-referencing - information, user defined variables and types will appear in a - different color; you will be able to click on any identifier and go to - its declaration. - - The command line is as follow: - $ perl gnathtml.pl [switches] ada-files - - You can pass it as many Ada files as you want. `gnathtml' will - generate an html file for every ada file, and a global file called - `index.htm'. This file is an index of every identifier defined in the - files. - - The available switches are the following ones : - - `-83' - Only the subset on the Ada 83 keywords will be highlighted, not - the full Ada 95 keywords set. - - `-cc COLOR' - This option allows you to change the color used for comments. The - default value is green. The color argument can be any name - accepted by html. - - `-d' - If the ada files depend on some other files (using for instance the - `with' command, the latter will also be converted to html. Only - the files in the user project will be converted to html, not the - files in the run-time library itself. - - `-D' - This command is the same as -d above, but `gnathtml' will also look - for files in the run-time library, and generate html files for - them. - - `-f' - By default, gnathtml will generate html links only for global - entities ('with'ed units, global variables and types,...). If you - specify the `-f' on the command line, then links will be generated - for local entities too. - - `-l NUMBER' - If this switch is provided and NUMBER is not 0, then `gnathtml' - will number the html files every NUMBER line. - - `-I DIR' - Specify a directory to search for library files (`.ali' files) and - source files. You can provide several -I switches on the command - line, and the directories will be parsed in the order of the - command line. - - `-o DIR' - Specify the output directory for html files. By default, gnathtml - will saved the generated html files in a subdirectory named - `html/'. - - `-p FILE' - If you are using Emacs and the most recent Emacs Ada mode, which - provides a full Integrated Development Environment for compiling, - checking, running and debugging applications, you may be using - `.adp' files to give the directories where Emacs can find sources - and object files. - - Using this switch, you can tell gnathtml to use these files. This - allows you to get an html version of your application, even if it - is spread over multiple directories. - - `-sc COLOR' - This option allows you to change the color used for symbol - definitions. The default value is red. The color argument can be - any name accepted by html. - - `-t FILE' - This switch provides the name of a file. This file contains a list - of file names to be converted, and the effect is exactly as though - they had appeared explicitly on the command line. This is the - recommended way to work around the command line length limit on - some systems. - -  - File: gnat_ug_wnt.info, Node: Installing gnathtml, Prev: Converting Ada Files to html with gnathtml, Up: Other Utility Programs - - Installing `gnathtml' - ===================== - - `Perl' needs to be installed on your machine to run this script. - `Perl' is freely available for almost every architecture and Operating - System via the Internet. - - On Unix systems, you may want to modify the first line of the - script `gnathtml', to explicitly tell the Operating system where - Perl is. The syntax of this line is : - #!full_path_name_to_perl - - Alternatively, you may run the script using the following command line: - - $ perl gnathtml.pl [switches] files - -  - File: gnat_ug_wnt.info, Node: Running and Debugging Ada Programs, Next: Inline Assembler, Prev: Other Utility Programs, Up: Top - - Running and Debugging Ada Programs - ********************************** - - This chapter discusses how to debug Ada programs. An incorrect Ada - program may be handled in three ways by the GNAT compiler: - - 1. The illegality may be a violation of the static semantics of Ada. - In that case GNAT diagnoses the constructs in the program that are - illegal. It is then a straightforward matter for the user to - modify those parts of the program. - - 2. The illegality may be a violation of the dynamic semantics of Ada. - In that case the program compiles and executes, but may generate - incorrect results, or may terminate abnormally with some exception. - - 3. When presented with a program that contains convoluted errors, GNAT - itself may terminate abnormally without providing full diagnostics - on the incorrect user program. - - * Menu: - - * The GNAT Debugger GDB:: - * Running GDB:: - * Introduction to GDB Commands:: - * Using Ada Expressions:: - * Calling User-Defined Subprograms:: - * Using the Next Command in a Function:: - * Ada Exceptions:: - * Ada Tasks:: - * Debugging Generic Units:: - * GNAT Abnormal Termination or Failure to Terminate:: - * Naming Conventions for GNAT Source Files:: - * Getting Internal Debugging Information:: - * Stack Traceback:: - -  - File: gnat_ug_wnt.info, Node: The GNAT Debugger GDB, Next: Running GDB, Up: Running and Debugging Ada Programs - - The GNAT Debugger GDB - ===================== - - `GDB' is a general purpose, platform-independent debugger that can be - used to debug mixed-language programs compiled with `GCC', and in - particular is capable of debugging Ada programs compiled with GNAT. The - latest versions of `GDB' are Ada-aware and can handle complex Ada data - structures. - - The manual `Debugging with GDB' contains full details on the usage - of `GDB', including a section on its usage on programs. This manual - should be consulted for full details. The section that follows is a - brief introduction to the philosophy and use of `GDB'. - - When GNAT programs are compiled, the compiler optionally writes - debugging information into the generated object file, including - information on line numbers, and on declared types and variables. This - information is separate from the generated code. It makes the object - files considerably larger, but it does not add to the size of the - actual executable that will be loaded into memory, and has no impact on - run-time performance. The generation of debug information is triggered - by the use of the -g switch in the gcc or gnatmake command used to - carry out the compilations. It is important to emphasize that the use - of these options does not change the generated code. - - The debugging information is written in standard system formats that - are used by many tools, including debuggers and profilers. The format - of the information is typically designed to describe C types and - semantics, but GNAT implements a translation scheme which allows full - details about Ada types and variables to be encoded into these standard - C formats. Details of this encoding scheme may be found in the file - exp_dbug.ads in the GNAT source distribution. However, the details of - this encoding are, in general, of no interest to a user, since `GDB' - automatically performs the necessary decoding. - - When a program is bound and linked, the debugging information is - collected from the object files, and stored in the executable image of - the program. Again, this process significantly increases the size of - the generated executable file, but it does not increase the size of the - executable program itself. Furthermore, if this program is run in the - normal manner, it runs exactly as if the debug information were not - present, and takes no more actual memory. - - However, if the program is run under control of `GDB', the debugger - is activated. The image of the program is loaded, at which point it is - ready to run. If a run command is given, then the program will run - exactly as it would have if `GDB' were not present. This is a crucial - part of the `GDB' design philosophy. `GDB' is entirely non-intrusive - until a breakpoint is encountered. If no breakpoint is ever hit, the - program will run exactly as it would if no debugger were present. When - a breakpoint is hit, `GDB' accesses the debugging information and can - respond to user commands to inspect variables, and more generally to - report on the state of execution. - -  - File: gnat_ug_wnt.info, Node: Running GDB, Next: Introduction to GDB Commands, Prev: The GNAT Debugger GDB, Up: Running and Debugging Ada Programs - - Running GDB - =========== - - The debugger can be launched directly and simply from `glide' or - through its graphical interface: `gvd'. It can also be used directly in - text mode. Here is described the basic use of `GDB' in text mode. All - the commands described below can be used in the `gvd' console window - eventhough there is usually other more graphical ways to achieve the - same goals. - - The command to run de graphical interface of the debugger is - $ gvd program - - The command to run `GDB' in text mode is - - $ gdb program - - where `program' is the name of the executable file. This activates the - debugger and results in a prompt for debugger commands. The simplest - command is simply `run', which causes the program to run exactly as if - the debugger were not present. The following section describes some of - the additional commands that can be given to `GDB'. - -  - File: gnat_ug_wnt.info, Node: Introduction to GDB Commands, Next: Using Ada Expressions, Prev: Running GDB, Up: Running and Debugging Ada Programs - - Introduction to GDB Commands - ============================ - - `GDB' contains a large repertoire of commands. The manual `Debugging - with GDB' includes extensive documentation on the use of these - commands, together with examples of their use. Furthermore, the command - HELP invoked from within `GDB' activates a simple help facility which - summarizes the available commands and their options. In this section - we summarize a few of the most commonly used commands to give an idea - of what `GDB' is about. You should create a simple program with - debugging information and experiment with the use of these `GDB' - commands on the program as you read through the following section. - - `set args ARGUMENTS' - The ARGUMENTS list above is a list of arguments to be passed to - the program on a subsequent run command, just as though the - arguments had been entered on a normal invocation of the program. - The `set args' command is not needed if the program does not - require arguments. - - `run' - The `run' command causes execution of the program to start from - the beginning. If the program is already running, that is to say if - you are currently positioned at a breakpoint, then a prompt will - ask for confirmation that you want to abandon the current - execution and restart. - - `breakpoint LOCATION' - The breakpoint command sets a breakpoint, that is to say a point - at which execution will halt and `GDB' will await further - commands. LOCATION is either a line number within a file, given in - the format `file:linenumber', or it is the name of a subprogram. - If you request that a breakpoint be set on a subprogram that is - overloaded, a prompt will ask you to specify on which of those - subprograms you want to breakpoint. You can also specify that all - of them should be breakpointed. If the program is run and - execution encounters the breakpoint, then the program stops and - `GDB' signals that the breakpoint was encountered by printing the - line of code before which the program is halted. - - `breakpoint exception NAME' - A special form of the breakpoint command which breakpoints whenever - exception NAME is raised. If NAME is omitted, then a breakpoint - will occur when any exception is raised. - - `print EXPRESSION' - This will print the value of the given expression. Most simple Ada - expression formats are properly handled by `GDB', so the expression - can contain function calls, variables, operators, and attribute - references. - - `continue' - Continues execution following a breakpoint, until the next - breakpoint or the termination of the program. - - `step' - Executes a single line after a breakpoint. If the next statement - is a subprogram call, execution continues into (the first - statement of) the called subprogram. - - `next' - Executes a single line. If this line is a subprogram call, - executes and returns from the call. - - `list' - Lists a few lines around the current source location. In practice, - it is usually more convenient to have a separate edit window open - with the relevant source file displayed. Successive applications - of this command print subsequent lines. The command can be given - an argument which is a line number, in which case it displays a - few lines around the specified one. - - `backtrace' - Displays a backtrace of the call chain. This command is typically - used after a breakpoint has occurred, to examine the sequence of - calls that leads to the current breakpoint. The display includes - one line for each activation record (frame) corresponding to an - active subprogram. - - `up' - At a breakpoint, `GDB' can display the values of variables local - to the current frame. The command `up' can be used to examine the - contents of other active frames, by moving the focus up the stack, - that is to say from callee to caller, one frame at a time. - - `down' - Moves the focus of `GDB' down from the frame currently being - examined to the frame of its callee (the reverse of the previous - command), - - `frame N' - Inspect the frame with the given number. The value 0 denotes the - frame of the current breakpoint, that is to say the top of the - call stack. - - The above list is a very short introduction to the commands that - `GDB' provides. Important additional capabilities, including conditional - breakpoints, the ability to execute command sequences on a breakpoint, - the ability to debug at the machine instruction level and many other - features are described in detail in `Debugging with GDB'. Note that - most commands can be abbreviated (for example, c for continue, bt for - backtrace). - -  - File: gnat_ug_wnt.info, Node: Using Ada Expressions, Next: Calling User-Defined Subprograms, Prev: Introduction to GDB Commands, Up: Running and Debugging Ada Programs - - Using Ada Expressions - ===================== - - `GDB' supports a fairly large subset of Ada expression syntax, with some - extensions. The philosophy behind the design of this subset is - - * That `GDB' should provide basic literals and access to operations - for arithmetic, dereferencing, field selection, indexing, and - subprogram calls, leaving more sophisticated computations to - subprograms written into the program (which therefore may be - called from `GDB'). - - * That type safety and strict adherence to Ada language restrictions - are not particularly important to the `GDB' user. - - * That brevity is important to the `GDB' user. - - Thus, for brevity, the debugger acts as if there were implicit - `with' and `use' clauses in effect for all user-written packages, thus - making it unnecessary to fully qualify most names with their packages, - regardless of context. Where this causes ambiguity, `GDB' asks the - user's intent. - - For details on the supported Ada syntax, see `Debugging with GDB'. - -  - File: gnat_ug_wnt.info, Node: Calling User-Defined Subprograms, Next: Using the Next Command in a Function, Prev: Using Ada Expressions, Up: Running and Debugging Ada Programs - - Calling User-Defined Subprograms - ================================ - - An important capability of `GDB' is the ability to call user-defined - subprograms while debugging. This is achieved simply by entering a - subprogram call statement in the form: - - call subprogram-name (parameters) - - The keyword `call' can be omitted in the normal case where the - `subprogram-name' does not coincide with any of the predefined `GDB' - commands. - - The effect is to invoke the given subprogram, passing it the list of - parameters that is supplied. The parameters can be expressions and can - include variables from the program being debugged. The subprogram must - be defined at the library level within your program, and `GDB' will - call the subprogram within the environment of your program execution - (which means that the subprogram is free to access or even modify - variables within your program). - - The most important use of this facility is in allowing the inclusion - of debugging routines that are tailored to particular data structures - in your program. Such debugging routines can be written to provide a - suitably high-level description of an abstract type, rather than a - low-level dump of its physical layout. After all, the standard `GDB - print' command only knows the physical layout of your types, not their - abstract meaning. Debugging routines can provide information at the - desired semantic level and are thus enormously useful. - - For example, when debugging GNAT itself, it is crucial to have - access to the contents of the tree nodes used to represent the program - internally. But tree nodes are represented simply by an integer value - (which in turn is an index into a table of nodes). Using the `print' - command on a tree node would simply print this integer value, which is - not very useful. But the PN routine (defined in file treepr.adb in the - GNAT sources) takes a tree node as input, and displays a useful high - level representation of the tree node, which includes the syntactic - category of the node, its position in the source, the integers that - denote descendant nodes and parent node, as well as varied semantic - information. To study this example in more detail, you might want to - look at the body of the PN procedure in the stated file. - -  - File: gnat_ug_wnt.info, Node: Using the Next Command in a Function, Next: Ada Exceptions, Prev: Calling User-Defined Subprograms, Up: Running and Debugging Ada Programs - - Using the Next Command in a Function - ==================================== - - When you use the `next' command in a function, the current source - location will advance to the next statement as usual. A special case - arises in the case of a `return' statement. - - Part of the code for a return statement is the "epilog" of the - function. This is the code that returns to the caller. There is only - one copy of this epilog code, and it is typically associated with the - last return statement in the function if there is more than one return. - In some implementations, this epilog is associated with the first - statement of the function. - - The result is that if you use the `next' command from a return - statement that is not the last return statement of the function you may - see a strange apparent jump to the last return statement or to the - start of the function. You should simply ignore this odd jump. The - value returned is always that from the first return statement that was - stepped through. - -  - File: gnat_ug_wnt.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Using the Next Command in a Function, Up: Running and Debugging Ada Programs - - Breaking on Ada Exceptions - ========================== - - You can set breakpoints that trip when your program raises selected - exceptions. - - `break exception' - Set a breakpoint that trips whenever (any task in the) program - raises any exception. - - `break exception NAME' - Set a breakpoint that trips whenever (any task in the) program - raises the exception NAME. - - `break exception unhandled' - Set a breakpoint that trips whenever (any task in the) program - raises an exception for which there is no handler. - - `info exceptions' - `info exceptions REGEXP' - The `info exceptions' command permits the user to examine all - defined exceptions within Ada programs. With a regular expression, - REGEXP, as argument, prints out only those exceptions whose name - matches REGEXP. - -  - File: gnat_ug_wnt.info, Node: Ada Tasks, Next: Debugging Generic Units, Prev: Ada Exceptions, Up: Running and Debugging Ada Programs - - Ada Tasks - ========= - - `GDB' allows the following task-related commands: - - `info tasks' - This command shows a list of current Ada tasks, as in the - following example: - - (gdb) info tasks - ID TID P-ID Thread Pri State Name - 1 8088000 0 807e000 15 Child Activation Wait main_task - 2 80a4000 1 80ae000 15 Accept/Select Wait b - 3 809a800 1 80a4800 15 Child Activation Wait a - * 4 80ae800 3 80b8000 15 Running c - - In this listing, the asterisk before the first task indicates it - to be the currently running task. The first column lists the task - ID that is used to refer to tasks in the following commands. - - `break LINESPEC task TASKID' - `break LINESPEC task TASKID if ...' - These commands are like the `break ... thread ...'. LINESPEC - specifies source lines. - - Use the qualifier `task TASKID' with a breakpoint command to - specify that you only want `GDB' to stop the program when a - particular Ada task reaches this breakpoint. TASKID is one of the - numeric task identifiers assigned by `GDB', shown in the first - column of the `info tasks' display. - - If you do not specify `task TASKID' when you set a breakpoint, the - breakpoint applies to _all_ tasks of your program. - - You can use the `task' qualifier on conditional breakpoints as - well; in this case, place `task TASKID' before the breakpoint - condition (before the `if'). - - `task TASKNO' - This command allows to switch to the task referred by TASKNO. In - particular, This allows to browse the backtrace of the specified - task. It is advised to switch back to the original task before - continuing execution otherwise the scheduling of the program may be - perturbated. - - For more detailed information on the tasking support, see `Debugging - with GDB'. - -  - File: gnat_ug_wnt.info, Node: Debugging Generic Units, Next: GNAT Abnormal Termination or Failure to Terminate, Prev: Ada Tasks, Up: Running and Debugging Ada Programs - - Debugging Generic Units - ======================= - - GNAT always uses code expansion for generic instantiation. This means - that each time an instantiation occurs, a complete copy of the original - code is made, with appropriate substitutions of formals by actuals. - - It is not possible to refer to the original generic entities in - `GDB', but it is always possible to debug a particular instance of a - generic, by using the appropriate expanded names. For example, if we - have - - procedure g is - - generic package k is - procedure kp (v1 : in out integer); - end k; - - package body k is - procedure kp (v1 : in out integer) is - begin - v1 := v1 + 1; - end kp; - end k; - - package k1 is new k; - package k2 is new k; - - var : integer := 1; - - begin - k1.kp (var); - k2.kp (var); - k1.kp (var); - k2.kp (var); - end; - - Then to break on a call to procedure kp in the k2 instance, simply use - the command: - - (gdb) break g.k2.kp - - When the breakpoint occurs, you can step through the code of the - instance in the normal manner and examine the values of local - variables, as for other units. - -  - File: gnat_ug_wnt.info, Node: GNAT Abnormal Termination or Failure to Terminate, Next: Naming Conventions for GNAT Source Files, Prev: Debugging Generic Units, Up: Running and Debugging Ada Programs - - GNAT Abnormal Termination or Failure to Terminate - ================================================= - - When presented with programs that contain serious errors in syntax or - semantics, GNAT may on rare occasions experience problems in - operation, such as aborting with a segmentation fault or illegal memory - access, raising an internal exception, terminating abnormally, or - failing to terminate at all. In such cases, you can activate various - features of GNAT that can help you pinpoint the construct in your - program that is the likely source of the problem. - - The following strategies are presented in increasing order of - difficulty, corresponding to your experience in using GNAT and your - familiarity with compiler internals. - - 1. Run `gcc' with the `-gnatf'. This first switch causes all errors - on a given line to be reported. In its absence, only the first - error on a line is displayed. - - The `-gnatdO' switch causes errors to be displayed as soon as they - are encountered, rather than after compilation is terminated. If - GNAT terminates prematurely or goes into an infinite loop, the - last error message displayed may help to pinpoint the culprit. - - 2. Run `gcc' with the `-v (verbose)' switch. In this mode, `gcc' - produces ongoing information about the progress of the compilation - and provides the name of each procedure as code is generated. This - switch allows you to find which Ada procedure was being compiled - when it encountered a code generation problem. - - 3. Run `gcc' with the `-gnatdc' switch. This is a GNAT specific - switch that does for the front-end what `-v' does for the back end. - The system prints the name of each unit, either a compilation unit - or nested unit, as it is being analyzed. - - 4. Finally, you can start `gdb' directly on the `gnat1' executable. - `gnat1' is the front-end of GNAT, and can be run independently - (normally it is just called from `gcc'). You can use `gdb' on - `gnat1' as you would on a C program (but *note The GNAT Debugger - GDB:: for caveats). The `where' command is the first line of - attack; the variable `lineno' (seen by `print lineno'), used by - the second phase of `gnat1' and by the `gcc' backend, indicates - the source line at which the execution stopped, and `input_file - name' indicates the name of the source file. - -  - File: gnat_ug_wnt.info, Node: Naming Conventions for GNAT Source Files, Next: Getting Internal Debugging Information, Prev: GNAT Abnormal Termination or Failure to Terminate, Up: Running and Debugging Ada Programs - - Naming Conventions for GNAT Source Files - ======================================== - - In order to examine the workings of the GNAT system, the following - brief description of its organization may be helpful: - - * Files with prefix `sc' contain the lexical scanner. - - * All files prefixed with `par' are components of the parser. The - numbers correspond to chapters of the Ada 95 Reference Manual. For - example, parsing of select statements can be found in - `par-ch9.adb'. - - * All files prefixed with `sem' perform semantic analysis. The - numbers correspond to chapters of the Ada standard. For example, - all issues involving context clauses can be found in - `sem_ch10.adb'. In addition, some features of the language require - sufficient special processing to justify their own semantic files: - sem_aggr for aggregates, sem_disp for dynamic dispatching, etc. - - * All files prefixed with `exp' perform normalization and expansion - of the intermediate representation (abstract syntax tree, or AST). - these files use the same numbering scheme as the parser and - semantics files. For example, the construction of record - initialization procedures is done in `exp_ch3.adb'. - - * The files prefixed with `bind' implement the binder, which - verifies the consistency of the compilation, determines an order of - elaboration, and generates the bind file. - - * The files `atree.ads' and `atree.adb' detail the low-level data - structures used by the front-end. - - * The files `sinfo.ads' and `sinfo.adb' detail the structure of the - abstract syntax tree as produced by the parser. - - * The files `einfo.ads' and `einfo.adb' detail the attributes of all - entities, computed during semantic analysis. - - * Library management issues are dealt with in files with prefix - `lib'. - - * Ada files with the prefix `a-' are children of `Ada', as defined - in Annex A. - - * Files with prefix `i-' are children of `Interfaces', as defined in - Annex B. - - * Files with prefix `s-' are children of `System'. This includes - both language-defined children and GNAT run-time routines. - - * Files with prefix `g-' are children of `GNAT'. These are useful - general-purpose packages, fully documented in their - specifications. All the other `.c' files are modifications of - common `gcc' files. - -  - File: gnat_ug_wnt.info, Node: Getting Internal Debugging Information, Next: Stack Traceback, Prev: Naming Conventions for GNAT Source Files, Up: Running and Debugging Ada Programs - - Getting Internal Debugging Information - ====================================== - - Most compilers have internal debugging switches and modes. GNAT does - also, except GNAT internal debugging switches and modes are not secret. - A summary and full description of all the compiler and binder debug - flags are in the file `debug.adb'. You must obtain the sources of the - compiler to see the full detailed effects of these flags. - - The switches that print the source of the program (reconstructed from - the internal tree) are of general interest for user programs, as are the - options to print the full internal tree, and the entity table (the - symbol table information). The reconstructed source provides a readable - version of the program after the front-end has completed analysis and - expansion, and is useful when studying the performance of specific - constructs. For example, constraint checks are indicated, complex - aggregates are replaced with loops and assignments, and tasking - primitives are replaced with run-time calls. - -  - File: gnat_ug_wnt.info, Node: Stack Traceback, Prev: Getting Internal Debugging Information, Up: Running and Debugging Ada Programs - - Stack Traceback - =============== - - Traceback is a mechanism to display the sequence of subprogram calls - that leads to a specified execution point in a program. Often (but not - always) the execution point is an instruction at which an exception has - been raised. This mechanism is also known as stack unwinding because - it obtains its information by scanning the run-time stack and - recovering the activation records of all active subprograms. Stack - unwinding is one of the most important tools for program debugging. - - The first entry stored in traceback corresponds to the deepest calling - level, that is to say the subprogram currently executing the instruction - from which we want to obtain the traceback. - - Note that there is no runtime performance penalty when stack traceback - is enabled and no exception are raised during program execution. - - * Menu: - - * Non-Symbolic Traceback:: - * Symbolic Traceback:: - -  - File: gnat_ug_wnt.info, Node: Non-Symbolic Traceback, Next: Symbolic Traceback, Up: Stack Traceback - - Non-Symbolic Traceback - ---------------------- - - Note: this feature is not supported on all platforms. See - `GNAT.Traceback spec in g-traceb.ads' for a complete list of supported - platforms. - - * Menu: - - * Tracebacks From an Unhandled Exception:: - * Tracebacks From Exception Occurrences (non-symbolic):: - * Tracebacks From Anywhere in a Program (non-symbolic):: - -  - File: gnat_ug_wnt.info, Node: Tracebacks From an Unhandled Exception, Next: Tracebacks From Exception Occurrences (non-symbolic), Up: Non-Symbolic Traceback - - Tracebacks From an Unhandled Exception - ...................................... - - A runtime non-symbolic traceback is a list of addresses of call - instructions. To enable this feature you must use the `-E' - `gnatbind''s option. With this option a stack traceback is stored as - part of exception information. It is possible to retrieve this - information using the standard `Ada.Exception.Exception_Information' - routine. - - Let's have a look at a simple example: - - procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - $ gnatmake stb -bargs -E - $ stb - - Execution terminated by unhandled exception - Exception name: CONSTRAINT_ERROR - Message: stb.adb:5 - Call stack traceback locations: - 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - - As we see the traceback lists a sequence of addresses for the unhandled - exception `CONSTAINT_ERROR' raised in procedure P1. It is easy to guess - that this exception come from procedure P1. To translate these - addresses into the source lines where the calls appear, the `addr2line' - tool, described below, is invaluable. The use of this tool requires the - program to be compiled with debug information. - - $ gnatmake -g stb -bargs -E - $ stb - - Execution terminated by unhandled exception - Exception name: CONSTRAINT_ERROR - Message: stb.adb:5 - Call stack traceback locations: - 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 - - $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 - 0x4011f1 0x77e892a4 - - 00401373 at d:/stb/stb.adb:5 - 0040138B at d:/stb/stb.adb:10 - 0040139C at d:/stb/stb.adb:14 - 00401335 at d:/stb/b~stb.adb:104 - 004011C4 at /build/.../crt1.c:200 - 004011F1 at /build/.../crt1.c:222 - 77E892A4 in ?? at ??:0 - - `addr2line' has a number of other useful options: - - `--functions' - to get the function name corresponding to any location - - `--demangle=gnat' - to use the gnat decoding mode for the function names. Note that - for binutils version 2.9.x the option is simply `--demangle'. - - $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b - 0x40139c 0x401335 0x4011c4 0x4011f1 - - 00401373 in stb.p1 at d:/stb/stb.adb:5 - 0040138B in stb.p2 at d:/stb/stb.adb:10 - 0040139C in stb at d:/stb/stb.adb:14 - 00401335 in main at d:/stb/b~stb.adb:104 - 004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200 - 004011F1 in at /build/.../crt1.c:222 - - From this traceback we can see that the exception was raised in - `stb.adb' at line 5, which was reached from a procedure call in - `stb.adb' at line 10, and so on. The `b~std.adb' is the binder file, - which contains the call to the main program. *note Running gnatbind::. - The remaining entries are assorted runtime routines, and the output - will vary from platform to platform. - - It is also possible to use `GDB' with these traceback addresses to debug - the program. For example, we can break at a given code location, as - reported in the stack traceback: - - $ gdb -nw stb - - Furthermore, this feature is not implemented inside Windows DLL. Only - the non-symbolic traceback is reported in this case. - - (gdb) break *0x401373 - Breakpoint 1 at 0x401373: file stb.adb, line 5. - - It is important to note that the stack traceback addresses do not - change when debug information is included. This is particularly useful - because it makes it possible to release software without debug - information (to minimize object size), get a field report that includes - a stack traceback whenever an internal bug occurs, and then be able to - retrieve the sequence of calls with the same program compiled with - debug information. - -  - File: gnat_ug_wnt.info, Node: Tracebacks From Exception Occurrences (non-symbolic), Next: Tracebacks From Anywhere in a Program (non-symbolic), Prev: Tracebacks From an Unhandled Exception, Up: Non-Symbolic Traceback - - Tracebacks From Exception Occurrences - ..................................... - - Non-symbolic tracebacks are obtained by using the `-E' binder argument. - The stack traceback is attached to the exception information string, - and can be retrieved in an exception handler within the Ada program, by - means of the Ada95 facilities defined in `Ada.Exceptions'. Here is a - simple example: - - with Ada.Text_IO; - with Ada.Exceptions; - - procedure STB is - - use Ada; - use Ada.Exceptions; - - procedure P1 is - K : Positive := 1; - begin - K := K - 1; - exception - when E : others => - Text_IO.Put_Line (Exception_Information (E)); - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - This program will output: - - $ stb - - Exception name: CONSTRAINT_ERROR - Message: stb.adb:12 - Call stack traceback locations: - 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 - -  - File: gnat_ug_wnt.info, Node: Tracebacks From Anywhere in a Program (non-symbolic), Prev: Tracebacks From Exception Occurrences (non-symbolic), Up: Non-Symbolic Traceback - - Tracebacks From Anywhere in a Program - ..................................... - - It is also possible to retrieve a stack traceback from anywhere in a - program. For this you need to use the `GNAT.Traceback' API. This - package includes a procedure called `Call_Chain' that computes a - complete stack traceback, as well as useful display procedures - described below. It is not necessary to use the `-E gnatbind' option in - this case, because the stack traceback mechanism is invoked explicitly. - - In the following example we compute a traceback at a specific location - in the program, and we display it using `GNAT.Debug_Utilities.Image' to - convert addresses to strings: - - with Ada.Text_IO; - with GNAT.Traceback; - with GNAT.Debug_Utilities; - - procedure STB is - - use Ada; - use GNAT; - use GNAT.Traceback; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - - Text_IO.Put ("In STB.P1 : "); - - for K in 1 .. Len loop - Text_IO.Put (Debug_Utilities.Image (TB (K))); - Text_IO.Put (' '); - end loop; - - Text_IO.New_Line; - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - - $ gnatmake stb - $ stb - - In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# - 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# - -  - File: gnat_ug_wnt.info, Node: Symbolic Traceback, Prev: Non-Symbolic Traceback, Up: Stack Traceback - - Symbolic Traceback - ------------------ - - A symbolic traceback is a stack traceback in which procedure names are - associated with each code location. - - Note that this feature is not supported on all platforms. See - `GNAT.Traceback.Symbolic spec in g-trasym.ads' for a complete list of - currently supported platforms. - - Note that the symbolic traceback requires that the program be compiled - with debug information. If it is not compiled with debug information - only the non-symbolic information will be valid. - - * Menu: - - * Tracebacks From Exception Occurrences (symbolic):: - * Tracebacks From Anywhere in a Program (symbolic):: - -  - File: gnat_ug_wnt.info, Node: Tracebacks From Exception Occurrences (symbolic), Next: Tracebacks From Anywhere in a Program (symbolic), Up: Symbolic Traceback - - Tracebacks From Exception Occurrences - ..................................... - - with Ada.Text_IO; - with GNAT.Traceback.Symbolic; - - procedure STB is - - procedure P1 is - begin - raise Constraint_Error; - end P1; - - procedure P2 is - begin - P1; - end P2; - - procedure P3 is - begin - P2; - end P3; - - begin - P3; - exception - when E : others => - Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); - end STB; - - $ gnatmake -g stb -bargs -E -largs -lgnat -laddr2line -lintl - $ stb - - 0040149F in stb.p1 at stb.adb:8 - 004014B7 in stb.p2 at stb.adb:13 - 004014CF in stb.p3 at stb.adb:18 - 004015DD in ada.stb at stb.adb:22 - 00401461 in main at b~stb.adb:168 - 004011C4 in __mingw_CRTStartup at crt1.c:200 - 004011F1 in mainCRTStartup at crt1.c:222 - 77E892A4 in ?? at ??:0 - - The exact sequence of linker options may vary from platform to platform. - The above `-largs' section is for Windows platforms. By contrast, under - Unix there is no need for the `-largs' section. Differences across - platforms are due to details of linker implementation. - -  - File: gnat_ug_wnt.info, Node: Tracebacks From Anywhere in a Program (symbolic), Prev: Tracebacks From Exception Occurrences (symbolic), Up: Symbolic Traceback - - Tracebacks From Anywhere in a Program - ..................................... - - It is possible to get a symbolic stack traceback from anywhere in a - program, just as for non-symbolic tracebacks. The first step is to - obtain a non-symbolic traceback, and then call `Symbolic_Traceback' to - compute the symbolic information. Here is an example: - - with Ada.Text_IO; - with GNAT.Traceback; - with GNAT.Traceback.Symbolic; - - procedure STB is - - use Ada; - use GNAT.Traceback; - use GNAT.Traceback.Symbolic; - - procedure P1 is - TB : Tracebacks_Array (1 .. 10); - -- We are asking for a maximum of 10 stack frames. - Len : Natural; - -- Len will receive the actual number of stack frames returned. - begin - Call_Chain (TB, Len); - Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); - end P1; - - procedure P2 is - begin - P1; - end P2; - - begin - P2; - end STB; - -  - File: gnat_ug_wnt.info, Node: Inline Assembler, Next: Microsoft Windows Topics, Prev: Running and Debugging Ada Programs, Up: Top - - Inline Assembler - **************** - - If you need to write low-level software that interacts directly with - the hardware, Ada provides two ways to incorporate assembly language - code into your program. First, you can import and invoke external - routines written in assembly language, an Ada feature fully supported - by GNAT. However, for small sections of code it may be simpler or more - efficient to include assembly language statements directly in your Ada - source program, using the facilities of the implementation-defined - package `System.Machine_Code', which incorporates the gcc Inline - Assembler. The Inline Assembler approach offers a number of - advantages, including the following: - - * No need to use non-Ada tools - - * Consistent interface over different targets - - * Automatic usage of the proper calling conventions - - * Access to Ada constants and variables - - * Definition of intrinsic routines - - * Possibility of inlining a subprogram comprising assembler code - - * Code optimizer can take Inline Assembler code into account - - This chapter presents a series of examples to show you how to use - the Inline Assembler. Although it focuses on the Intel x86, the - general approach applies also to other processors. It is assumed that - you are familiar with Ada and with assembly language programming. - - * Menu: - - * Basic Assembler Syntax:: - * A Simple Example of Inline Assembler:: - * Output Variables in Inline Assembler:: - * Input Variables in Inline Assembler:: - * Inlining Inline Assembler Code:: - * Other Asm Functionality:: - * A Complete Example:: - -  - File: gnat_ug_wnt.info, Node: Basic Assembler Syntax, Next: A Simple Example of Inline Assembler, Up: Inline Assembler - - Basic Assembler Syntax - ====================== - - The assembler used by GNAT and gcc is based not on the Intel assembly - language, but rather on a language that descends from the AT&T Unix - assembler _as_ (and which is often referred to as "AT&T syntax"). The - following table summarizes the main features of _as_ syntax and points - out the differences from the Intel conventions. See the gcc _as_ and - _gas_ (an _as_ macro pre-processor) documentation for further - information. - - Register names - gcc / _as_: Prefix with "%"; for example `%eax' - Intel: No extra punctuation; for example `eax' - - Immediate operand - gcc / _as_: Prefix with "$"; for example `$4' - Intel: No extra punctuation; for example `4' - - Address - gcc / _as_: Prefix with "$"; for example `$loc' - Intel: No extra punctuation; for example `loc' - - Memory contents - gcc / _as_: No extra punctuation; for example `loc' - Intel: Square brackets; for example `[loc]' - - Register contents - gcc / _as_: Parentheses; for example `(%eax)' - Intel: Square brackets; for example `[eax]' - - Hexadecimal numbers - gcc / _as_: Leading "0x" (C language syntax); for example `0xA0' - Intel: Trailing "h"; for example `A0h' - - Operand size - gcc / _as_: Explicit in op code; for example `movw' to move a - 16-bit word - Intel: Implicit, deduced by assembler; for example `mov' - - Instruction repetition - gcc / _as_: Split into two lines; for example - `rep' - `stosl' - Intel: Keep on one line; for example `rep stosl' - - Order of operands - gcc / _as_: Source first; for example `movw $4, %eax' - Intel: Destination first; for example `mov eax, 4' - -  - File: gnat_ug_wnt.info, Node: A Simple Example of Inline Assembler, Next: Output Variables in Inline Assembler, Prev: Basic Assembler Syntax, Up: Inline Assembler - - A Simple Example of Inline Assembler - ==================================== - - The following example will generate a single assembly language - statement, `nop', which does nothing. Despite its lack of run-time - effect, the example will be useful in illustrating the basics of the - Inline Assembler facility. - - with System.Machine_Code; use System.Machine_Code; - procedure Nothing is - begin - Asm ("nop"); - end Nothing; - - `Asm' is a procedure declared in package `System.Machine_Code'; here - it takes one parameter, a _template string_ that must be a static - expression and that will form the generated instruction. `Asm' may be - regarded as a compile-time procedure that parses the template string - and additional parameters (none here), from which it generates a - sequence of assembly language instructions. - - The examples in this chapter will illustrate several of the forms - for invoking `Asm'; a complete specification of the syntax is found in - the `GNAT Reference Manual'. - - Under the standard GNAT conventions, the `Nothing' procedure should - be in a file named `nothing.adb'. You can build the executable in the - usual way: - gnatmake nothing - However, the interesting aspect of this example is not its run-time - behavior but rather the generated assembly code. To see this output, - invoke the compiler as follows: - gcc -c -S -fomit-frame-pointer -gnatp `nothing.adb' - where the options are: - - `-c' - compile only (no bind or link) - - `-S' - generate assembler listing - - `-fomit-frame-pointer' - do not set up separate stack frames - - `-gnatp' - do not add runtime checks - - This gives a human-readable assembler version of the code. The - resulting file will have the same name as the Ada source file, but with - a `.s' extension. In our example, the file `nothing.s' has the - following contents: - - .file "nothing.adb" - gcc2_compiled.: - ___gnu_compiled_ada: - .text - .align 4 - .globl __ada_nothing - __ada_nothing: - #APP - nop - #NO_APP - jmp L1 - .align 2,0x90 - L1: - ret - - The assembly code you included is clearly indicated by the compiler, - between the `#APP' and `#NO_APP' delimiters. The character before the - 'APP' and 'NOAPP' can differ on different targets. For example, Linux - uses '#APP' while on NT you will see '/APP'. - - If you make a mistake in your assembler code (such as using the - wrong size modifier, or using a wrong operand for the instruction) GNAT - will report this error in a temporary file, which will be deleted when - the compilation is finished. Generating an assembler file will help in - such cases, since you can assemble this file separately using the _as_ - assembler that comes with gcc. - - Assembling the file using the command - - as `nothing.s' - - will give you error messages whose lines correspond to the assembler - input file, so you can easily find and correct any mistakes you made. - If there are no errors, _as_ will generate an object file `nothing.out'. - -  - File: gnat_ug_wnt.info, Node: Output Variables in Inline Assembler, Next: Input Variables in Inline Assembler, Prev: A Simple Example of Inline Assembler, Up: Inline Assembler - - Output Variables in Inline Assembler - ==================================== - - The examples in this section, showing how to access the processor - flags, illustrate how to specify the destination operands for assembly - language statements. - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags; - - In order to have a nicely aligned assembly listing, we have separated - multiple assembler statements in the Asm template string with linefeed - (ASCII.LF) and horizontal tab (ASCII.HT) characters. The resulting - section of the assembly output file is: - - #APP - pushfl - popl %eax - movl %eax, -40(%ebp) - #NO_APP - - It would have been legal to write the Asm invocation as: - - Asm ("pushfl popl %%eax movl %%eax, %0") - - but in the generated assembler file, this would come out as: - - #APP - pushfl popl %eax movl %eax, -40(%ebp) - #NO_APP - - which is not so convenient for the human reader. - - We use Ada comments at the end of each line to explain what the - assembler instructions actually do. This is a useful convention. - - When writing Inline Assembler instructions, you need to precede each - register and variable name with a percent sign. Since the assembler - already requires a percent sign at the beginning of a register name, - you need two consecutive percent signs for such names in the Asm - template string, thus `%%eax'. In the generated assembly code, one of - the percent signs will be stripped off. - - Names such as `%0', `%1', `%2', etc., denote input or output - variables: operands you later define using `Input' or `Output' - parameters to `Asm'. An output variable is illustrated in the third - statement in the Asm template string: - movl %%eax, %0 - The intent is to store the contents of the eax register in a - variable that can be accessed in Ada. Simply writing `movl %%eax, - Flags' would not necessarily work, since the compiler might optimize by - using a register to hold Flags, and the expansion of the `movl' - instruction would not be aware of this optimization. The solution is - not to store the result directly but rather to advise the compiler to - choose the correct operand form; that is the purpose of the `%0' output - variable. - - Information about the output variable is supplied in the `Outputs' - parameter to `Asm': - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - - The output is defined by the `Asm_Output' attribute of the target - type; the general format is - Type'Asm_Output (constraint_string, variable_name) - - The constraint string directs the compiler how to store/access the - associated variable. In the example - Unsigned_32'Asm_Output ("=m", Flags); - the `"m"' (memory) constraint tells the compiler that the variable - `Flags' should be stored in a memory variable, thus preventing the - optimizer from keeping it in a register. In contrast, - Unsigned_32'Asm_Output ("=r", Flags); - uses the `"r"' (register) constraint, telling the compiler to store - the variable in a register. - - If the constraint is preceded by the equal character (*=*), it tells - the compiler that the variable will be used to store data into it. - - In the `Get_Flags' example, we used the "g" (global) constraint, - allowing the optimizer to choose whatever it deems best. - - There are a fairly large number of constraints, but the ones that - are most useful (for the Intel x86 processor) are the following: - - `=' - output constraint - - `g' - global (i.e. can be stored anywhere) - - `m' - in memory - - `I' - a constant - - `a' - use eax - - `b' - use ebx - - `c' - use ecx - - `d' - use edx - - `S' - use esi - - `D' - use edi - - `r' - use one of eax, ebx, ecx or edx - - `q' - use one of eax, ebx, ecx, edx, esi or edi - - The full set of constraints is described in the gcc and _as_ - documentation; note that it is possible to combine certain constraints - in one constraint string. - - You specify the association of an output variable with an assembler - operand through the `%'_n_ notation, where _n_ is a non-negative - integer. Thus in - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax" & LF & HT & -- load eax with flags - "movl %%eax, %0", -- store flags in variable - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - - `%0' will be replaced in the expanded code by the appropriate operand, - whatever the compiler decided for the `Flags' variable. - - In general, you may have any number of output variables: - * Count the operands starting at 0; thus `%0', `%1', etc. - - * Specify the `Outputs' parameter as a parenthesized comma-separated - list of `Asm_Output' attributes - - For example: - Asm ("movl %%eax, %0" & LF & HT & - "movl %%ebx, %1" & LF & HT & - "movl %%ecx, %2", - Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A - Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B - Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C - - where `Var_A', `Var_B', and `Var_C' are variables in the Ada program. - - As a variation on the `Get_Flags' example, we can use the - constraints string to direct the compiler to store the eax register - into the `Flags' variable, instead of including the store instruction - explicitly in the `Asm' template string: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags_2 is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "popl %%eax", -- save flags in eax - Outputs => Unsigned_32'Asm_Output ("=a", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags_2; - - The `"a"' constraint tells the compiler that the `Flags' variable will - come from the eax register. Here is the resulting code: - - #APP - pushfl - popl %eax - #NO_APP - movl %eax,-40(%ebp) - - The compiler generated the store of eax into Flags after expanding the - assembler code. - - Actually, there was no need to pop the flags into the eax register; - more simply, we could just pop the flags directly into the program - variable: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Get_Flags_3 is - Flags : Unsigned_32; - use ASCII; - begin - Asm ("pushfl" & LF & HT & -- push flags on stack - "pop %0", -- save flags in Flags - Outputs => Unsigned_32'Asm_Output ("=g", Flags)); - Put_Line ("Flags register:" & Flags'Img); - end Get_Flags_3; - -  - File: gnat_ug_wnt.info, Node: Input Variables in Inline Assembler, Next: Inlining Inline Assembler Code, Prev: Output Variables in Inline Assembler, Up: Inline Assembler - - Input Variables in Inline Assembler - =================================== - - The example in this section illustrates how to specify the source - operands for assembly language statements. The program simply - increments its input value by 1: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Increment is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Inputs => Unsigned_32'Asm_Input ("a", Value), - Outputs => Unsigned_32'Asm_Output ("=a", Result)); - return Result; - end Incr; - - Value : Unsigned_32; - - begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Incr (Value); - Put_Line ("Value after is" & Value'Img); - end Increment; - - The `Outputs' parameter to `Asm' specifies that the result will be - in the eax register and that it is to be stored in the `Result' - variable. - - The `Inputs' parameter looks much like the `Outputs' parameter, but - with an `Asm_Input' attribute. The `"="' constraint, indicating an - output value, is not present. - - You can have multiple input variables, in the same way that you can - have more than one output variable. - - The parameter count (%0, %1) etc, now starts at the first input - statement, and continues with the output statements. When both - parameters use the same variable, the compiler will treat them as the - same %n operand, which is the case here. - - Just as the `Outputs' parameter causes the register to be stored - into the target variable after execution of the assembler statements, - so does the `Inputs' parameter cause its variable to be loaded into the - register before execution of the assembler statements. - - Thus the effect of the `Asm' invocation is: - 1. load the 32-bit value of `Value' into eax - - 2. execute the `incl %eax' instruction - - 3. store the contents of eax into the `Result' variable - - The resulting assembler file (with `-O2' optimization) contains: - _increment__incr.1: - subl $4,%esp - movl 8(%esp),%eax - #APP - incl %eax - #NO_APP - movl %eax,%edx - movl %ecx,(%esp) - addl $4,%esp - ret - -  - File: gnat_ug_wnt.info, Node: Inlining Inline Assembler Code, Next: Other Asm Functionality, Prev: Input Variables in Inline Assembler, Up: Inline Assembler - - Inlining Inline Assembler Code - ============================== - - For a short subprogram such as the `Incr' function in the previous - section, the overhead of the call and return (creating / deleting the - stack frame) can be significant, compared to the amount of code in the - subprogram body. A solution is to apply Ada's `Inline' pragma to the - subprogram, which directs the compiler to expand invocations of the - subprogram at the point(s) of call, instead of setting up a stack frame - for out-of-line calls. Here is the resulting program: - - with Interfaces; use Interfaces; - with Ada.Text_IO; use Ada.Text_IO; - with System.Machine_Code; use System.Machine_Code; - procedure Increment_2 is - - function Incr (Value : Unsigned_32) return Unsigned_32 is - Result : Unsigned_32; - begin - Asm ("incl %0", - Inputs => Unsigned_32'Asm_Input ("a", Value), - Outputs => Unsigned_32'Asm_Output ("=a", Result)); - return Result; - end Incr; - pragma Inline (Increment); - - Value : Unsigned_32; - - begin - Value := 5; - Put_Line ("Value before is" & Value'Img); - Value := Increment (Value); - Put_Line ("Value after is" & Value'Img); - end Increment_2; - - Compile the program with both optimization (`-O2') and inlining - enabled (`-gnatpn' instead of `-gnatp'). - - The `Incr' function is still compiled as usual, but at the point in - `Increment' where our function used to be called: - - pushl %edi - call _increment__incr.1 - - the code for the function body directly appears: - - movl %esi,%eax - #APP - incl %eax - #NO_APP - movl %eax,%edx - - thus saving the overhead of stack frame setup and an out-of-line call. - -  - File: gnat_ug_wnt.info, Node: Other Asm Functionality, Next: A Complete Example, Prev: Inlining Inline Assembler Code, Up: Inline Assembler - - Other `Asm' Functionality - ========================= - - This section describes two important parameters to the `Asm' procedure: - `Clobber', which identifies register usage; and `Volatile', which - inhibits unwanted optimizations. - - * Menu: - - * The Clobber Parameter:: - * The Volatile Parameter:: - -  - File: gnat_ug_wnt.info, Node: The Clobber Parameter, Next: The Volatile Parameter, Up: Other Asm Functionality - - The `Clobber' Parameter - ----------------------- - - One of the dangers of intermixing assembly language and a compiled - language such as Ada is that the compiler needs to be aware of which - registers are being used by the assembly code. In some cases, such as - the earlier examples, the constraint string is sufficient to indicate - register usage (e.g. "a" for the eax register). But more generally, the - compiler needs an explicit identification of the registers that are - used by the Inline Assembly statements. - - Using a register that the compiler doesn't know about could be a - side effect of an instruction (like `mull' storing its result in both - eax and edx). It can also arise from explicit register usage in your - assembly code; for example: - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out)); - - where the compiler (since it does not analyze the `Asm' template string) - does not know you are using the ebx register. - - In such cases you need to supply the `Clobber' parameter to `Asm', - to identify the registers that will be used by your assembly code: - - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Clobber => "ebx"); - - The Clobber parameter is a static string expression specifying the - register(s) you are using. Note that register names are _not_ prefixed - by a percent sign. Also, if more than one register is used then their - names are separated by commas; e.g., `"eax, ebx"' - - The `Clobber' parameter has several additional uses: - 1. Use the "register" name `cc' to indicate that flags might have - changed - - 2. Use the "register" name `memory' if you changed a memory location - -  - File: gnat_ug_wnt.info, Node: The Volatile Parameter, Prev: The Clobber Parameter, Up: Other Asm Functionality - - The `Volatile' Parameter - ------------------------ - - Compiler optimizations in the presence of Inline Assembler may - sometimes have unwanted effects. For example, when an `Asm' invocation - with an input variable is inside a loop, the compiler might move the - loading of the input variable outside the loop, regarding it as a - one-time initialization. - - If this effect is not desired, you can disable such optimizations by - setting the `Volatile' parameter to `True'; for example: - - Asm ("movl %0, %%ebx" & LF & HT & - "movl %%ebx, %1", - Inputs => Unsigned_32'Asm_Input ("g", Var_In), - Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), - Clobber => "ebx", - Volatile => True); - - By default, `Volatile' is set to `False' unless there is no `Outputs' - parameter. - - Although setting `Volatile' to `True' prevents unwanted - optimizations, it will also disable other optimizations that might be - important for efficiency. In general, you should set `Volatile' to - `True' only if the compiler's optimizations have created problems. - -  - File: gnat_ug_wnt.info, Node: A Complete Example, Prev: Other Asm Functionality, Up: Inline Assembler - - A Complete Example - ================== - - This section contains a complete program illustrating a realistic usage - of GNAT's Inline Assembler capabilities. It comprises a main procedure - `Check_CPU' and a package `Intel_CPU'. The package declares a - collection of functions that detect the properties of the 32-bit x86 - processor that is running the program. The main procedure invokes - these functions and displays the information. - - The Intel_CPU package could be enhanced by adding functions to - detect the type of x386 co-processor, the processor caching options and - special operations such as the SIMD extensions. - - Although the Intel_CPU package has been written for 32-bit Intel - compatible CPUs, it is OS neutral. It has been tested on DOS, - Windows/NT and Linux. - - * Menu: - - * Check_CPU Procedure:: - * Intel_CPU Package Specification:: - * Intel_CPU Package Body:: - -  - File: gnat_ug_wnt.info, Node: Check_CPU Procedure, Next: Intel_CPU Package Specification, Up: A Complete Example - - `Check_CPU' Procedure - --------------------- - - --------------------------------------------------------------------- - -- -- - -- Uses the Intel_CPU package to identify the CPU the program is -- - -- running on, and some of the features it supports. -- - -- -- - --------------------------------------------------------------------- - - with Intel_CPU; -- Intel CPU detection functions - with Ada.Text_IO; -- Standard text I/O - with Ada.Command_Line; -- To set the exit status - - procedure Check_CPU is - - Type_Found : Boolean := False; - -- Flag to indicate that processor was identified - - Features : Intel_CPU.Processor_Features; - -- The processor features - - Signature : Intel_CPU.Processor_Signature; - -- The processor type signature - - begin - - ----------------------------------- - -- Display the program banner. -- - ----------------------------------- - - Ada.Text_IO.Put_Line (Ada.Command_Line.Command_Name & - ": check Intel CPU version and features, v1.0"); - Ada.Text_IO.Put_Line ("distribute freely, but no warranty whatsoever"); - Ada.Text_IO.New_Line; - - ----------------------------------------------------------------------- - -- We can safely start with the assumption that we are on at least -- - -- a x386 processor. If the CPUID instruction is present, then we -- - -- have a later processor type. -- - ----------------------------------------------------------------------- - - if Intel_CPU.Has_CPUID = False then - - -- No CPUID instruction, so we assume this is indeed a x386 - -- processor. We can still check if it has a FP co-processor. - if Intel_CPU.Has_FPU then - Ada.Text_IO.Put_Line - ("x386-type processor with a FP co-processor"); - else - Ada.Text_IO.Put_Line - ("x386-type processor without a FP co-processor"); - end if; -- check for FPU - - -- Program done - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - return; - - end if; -- check for CPUID - - ----------------------------------------------------------------------- - -- If CPUID is supported, check if this is a true Intel processor, -- - -- if it is not, display a warning. -- - ----------------------------------------------------------------------- - - if Intel_CPU.Vendor_ID /= Intel_CPU.Intel_Processor then - Ada.Text_IO.Put_Line ("*** This is a Intel compatible processor"); - Ada.Text_IO.Put_Line ("*** Some information may be incorrect"); - end if; -- check if Intel - - ---------------------------------------------------------------------- - -- With the CPUID instruction present, we can assume at least a -- - -- x486 processor. If the CPUID support level is < 1 then we have -- - -- to leave it at that. -- - ---------------------------------------------------------------------- - - if Intel_CPU.CPUID_Level < 1 then - - -- Ok, this is a x486 processor. we still can get the Vendor ID - Ada.Text_IO.Put_Line ("x486-type processor"); - Ada.Text_IO.Put_Line ("Vendor ID is " & Intel_CPU.Vendor_ID); - - -- We can also check if there is a FPU present - if Intel_CPU.Has_FPU then - Ada.Text_IO.Put_Line ("Floating-Point support"); - else - Ada.Text_IO.Put_Line ("No Floating-Point support"); - end if; -- check for FPU - - -- Program done - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - return; - - end if; -- check CPUID level - - --------------------------------------------------------------------- - -- With a CPUID level of 1 we can use the processor signature to -- - -- determine it's exact type. -- - --------------------------------------------------------------------- - - Signature := Intel_CPU.Signature; - - ---------------------------------------------------------------------- - -- Ok, now we go into a lot of messy comparisons to get the -- - -- processor type. For clarity, no attememt to try to optimize the -- - -- comparisons has been made. Note that since Intel_CPU does not -- - -- support getting cache info, we cannot distinguish between P5 -- - -- and Celeron types yet. -- - ---------------------------------------------------------------------- - - -- x486SL - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486SL processor"); - end if; - - -- x486DX2 Write-Back - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#0111# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Write-Back Enhanced x486DX2 processor"); - end if; - - -- x486DX4 - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0100# and - Signature.Model = 2#1000# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486DX4 processor"); - end if; - - -- x486DX4 Overdrive - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0100# and - Signature.Model = 2#1000# then - Type_Found := True; - Ada.Text_IO.Put_Line ("x486DX4 OverDrive processor"); - end if; - - -- Pentium (60, 66) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium processor (60, 66)"); - end if; - - -- Pentium (75, 90, 100, 120, 133, 150, 166, 200) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0010# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium processor (75, 90, 100, 120, 133, 150, 166, 200)"); - end if; - - -- Pentium OverDrive (60, 66) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium OverDrive processor (60, 66)"); - end if; - - -- Pentium OverDrive (75, 90, 100, 120, 133, 150, 166, 200) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0010# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive cpu (75, 90, 100, 120, 133, 150, 166, 200)"); - end if; - - -- Pentium OverDrive processor for x486 processor-based systems - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive processor for x486 processor-based systems"); - end if; - - -- Pentium processor with MMX technology (166, 200) - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0101# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium processor with MMX technology (166, 200)"); - end if; - - -- Pentium OverDrive with MMX for Pentium (75, 90, 100, 120, 133) - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0101# and - Signature.Model = 2#0100# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium OverDrive processor with MMX " & - "technology for Pentium processor (75, 90, 100, 120, 133)"); - end if; - - -- Pentium Pro processor - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0001# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium Pro processor"); - end if; - - -- Pentium II processor, model 3 - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium II processor, model 3"); - end if; - - -- Pentium II processor, model 5 or Celeron processor - if Signature.Processor_Type = 2#00# and - Signature.Family = 2#0110# and - Signature.Model = 2#0101# then - Type_Found := True; - Ada.Text_IO.Put_Line - ("Pentium II processor, model 5 or Celeron processor"); - end if; - - -- Pentium Pro OverDrive processor - if Signature.Processor_Type = 2#01# and - Signature.Family = 2#0110# and - Signature.Model = 2#0011# then - Type_Found := True; - Ada.Text_IO.Put_Line ("Pentium Pro OverDrive processor"); - end if; - - -- If no type recognized, we have an unknown. Display what - -- we _do_ know - if Type_Found = False then - Ada.Text_IO.Put_Line ("Unknown processor"); - end if; - - ----------------------------------------- - -- Display processor stepping level. -- - ----------------------------------------- - - Ada.Text_IO.Put_Line ("Stepping level:" & Signature.Stepping'Img); - - --------------------------------- - -- Display vendor ID string. -- - --------------------------------- - - Ada.Text_IO.Put_Line ("Vendor ID: " & Intel_CPU.Vendor_ID); - - ------------------------------------ - -- Get the processors features. -- - ------------------------------------ - - Features := Intel_CPU.Features; - - ----------------------------- - -- Check for a FPU unit. -- - ----------------------------- - - if Features.FPU = True then - Ada.Text_IO.Put_Line ("Floating-Point unit available"); - else - Ada.Text_IO.Put_Line ("no Floating-Point unit"); - end if; -- check for FPU - - -------------------------------- - -- List processor features. -- - -------------------------------- - - Ada.Text_IO.Put_Line ("Supported features: "); - - -- Virtual Mode Extension - if Features.VME = True then - Ada.Text_IO.Put_Line (" VME - Virtual Mode Extension"); - end if; - - -- Debugging Extension - if Features.DE = True then - Ada.Text_IO.Put_Line (" DE - Debugging Extension"); - end if; - - -- Page Size Extension - if Features.PSE = True then - Ada.Text_IO.Put_Line (" PSE - Page Size Extension"); - end if; - - -- Time Stamp Counter - if Features.TSC = True then - Ada.Text_IO.Put_Line (" TSC - Time Stamp Counter"); - end if; - - -- Model Specific Registers - if Features.MSR = True then - Ada.Text_IO.Put_Line (" MSR - Model Specific Registers"); - end if; - - -- Physical Address Extension - if Features.PAE = True then - Ada.Text_IO.Put_Line (" PAE - Physical Address Extension"); - end if; - - -- Machine Check Extension - if Features.MCE = True then - Ada.Text_IO.Put_Line (" MCE - Machine Check Extension"); - end if; - - -- CMPXCHG8 instruction supported - if Features.CX8 = True then - Ada.Text_IO.Put_Line (" CX8 - CMPXCHG8 instruction"); - end if; - - -- on-chip APIC hardware support - if Features.APIC = True then - Ada.Text_IO.Put_Line (" APIC - on-chip APIC hardware support"); - end if; - - -- Fast System Call - if Features.SEP = True then - Ada.Text_IO.Put_Line (" SEP - Fast System Call"); - end if; - - -- Memory Type Range Registers - if Features.MTRR = True then - Ada.Text_IO.Put_Line (" MTTR - Memory Type Range Registers"); - end if; - - -- Page Global Enable - if Features.PGE = True then - Ada.Text_IO.Put_Line (" PGE - Page Global Enable"); - end if; - - -- Machine Check Architecture - if Features.MCA = True then - Ada.Text_IO.Put_Line (" MCA - Machine Check Architecture"); - end if; - - -- Conditional Move Instruction Supported - if Features.CMOV = True then - Ada.Text_IO.Put_Line - (" CMOV - Conditional Move Instruction Supported"); - end if; - - -- Page Attribute Table - if Features.PAT = True then - Ada.Text_IO.Put_Line (" PAT - Page Attribute Table"); - end if; - - -- 36-bit Page Size Extension - if Features.PSE_36 = True then - Ada.Text_IO.Put_Line (" PSE_36 - 36-bit Page Size Extension"); - end if; - - -- MMX technology supported - if Features.MMX = True then - Ada.Text_IO.Put_Line (" MMX - MMX technology supported"); - end if; - - -- Fast FP Save and Restore - if Features.FXSR = True then - Ada.Text_IO.Put_Line (" FXSR - Fast FP Save and Restore"); - end if; - - --------------------- - -- Program done. -- - --------------------- - - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); - - exception - - when others => - Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Failure); - raise; - - end Check_CPU; - -  - File: gnat_ug_wnt.info, Node: Intel_CPU Package Specification, Next: Intel_CPU Package Body, Prev: Check_CPU Procedure, Up: A Complete Example - - `Intel_CPU' Package Specification - --------------------------------- - - ------------------------------------------------------------------------- - -- -- - -- file: intel_cpu.ads -- - -- -- - -- ********************************************* -- - -- * WARNING: for 32-bit Intel processors only * -- - -- ********************************************* -- - -- -- - -- This package contains a number of subprograms that are useful in -- - -- determining the Intel x86 CPU (and the features it supports) on -- - -- which the program is running. -- - -- -- - -- The package is based upon the information given in the Intel -- - -- Application Note AP-485: "Intel Processor Identification and the -- - -- CPUID Instruction" as of April 1998. This application note can be -- - -- found on www.intel.com. -- - -- -- - -- It currently deals with 32-bit processors only, will not detect -- - -- features added after april 1998, and does not guarantee proper -- - -- results on Intel-compatible processors. -- - -- -- - -- Cache info and x386 fpu type detection are not supported. -- - -- -- - -- This package does not use any privileged instructions, so should -- - -- work on any OS running on a 32-bit Intel processor. -- - -- -- - ------------------------------------------------------------------------- - - with Interfaces; use Interfaces; - -- for using unsigned types - - with System.Machine_Code; use System.Machine_Code; - -- for using inline assembler code - - with Ada.Characters.Latin_1; use Ada.Characters.Latin_1; - -- for inserting control characters - - package Intel_CPU is - - ---------------------- - -- Processor bits -- - ---------------------- - - subtype Num_Bits is Natural range 0 .. 31; - -- the number of processor bits (32) - - -------------------------- - -- Processor register -- - -------------------------- - - -- define a processor register type for easy access to - -- the individual bits - - type Processor_Register is array (Num_Bits) of Boolean; - pragma Pack (Processor_Register); - for Processor_Register'Size use 32; - - ------------------------- - -- Unsigned register -- - ------------------------- - - -- define a processor register type for easy access to - -- the individual bytes - - type Unsigned_Register is - record - L1 : Unsigned_8; - H1 : Unsigned_8; - L2 : Unsigned_8; - H2 : Unsigned_8; - end record; - - for Unsigned_Register use - record - L1 at 0 range 0 .. 7; - H1 at 0 range 8 .. 15; - L2 at 0 range 16 .. 23; - H2 at 0 range 24 .. 31; - end record; - - for Unsigned_Register'Size use 32; - - --------------------------------- - -- Intel processor vendor ID -- - --------------------------------- - - Intel_Processor : constant String (1 .. 12) := "GenuineIntel"; - -- indicates an Intel manufactured processor - - ------------------------------------ - -- Processor signature register -- - ------------------------------------ - - -- a register type to hold the processor signature - - type Processor_Signature is - record - Stepping : Natural range 0 .. 15; - Model : Natural range 0 .. 15; - Family : Natural range 0 .. 15; - Processor_Type : Natural range 0 .. 3; - Reserved : Natural range 0 .. 262143; - end record; - - for Processor_Signature use - record - Stepping at 0 range 0 .. 3; - Model at 0 range 4 .. 7; - Family at 0 range 8 .. 11; - Processor_Type at 0 range 12 .. 13; - Reserved at 0 range 14 .. 31; - end record; - - for Processor_Signature'Size use 32; - - ----------------------------------- - -- Processor features register -- - ----------------------------------- - - -- a processor register to hold the processor feature flags - - type Processor_Features is - record - FPU : Boolean; -- floating point unit on chip - VME : Boolean; -- virtual mode extension - DE : Boolean; -- debugging extension - PSE : Boolean; -- page size extension - TSC : Boolean; -- time stamp counter - MSR : Boolean; -- model specific registers - PAE : Boolean; -- physical address extension - MCE : Boolean; -- machine check extension - CX8 : Boolean; -- cmpxchg8 instruction - APIC : Boolean; -- on-chip apic hardware - Res_1 : Boolean; -- reserved for extensions - SEP : Boolean; -- fast system call - MTRR : Boolean; -- memory type range registers - PGE : Boolean; -- page global enable - MCA : Boolean; -- machine check architecture - CMOV : Boolean; -- conditional move supported - PAT : Boolean; -- page attribute table - PSE_36 : Boolean; -- 36-bit page size extension - Res_2 : Natural range 0 .. 31; -- reserved for extensions - MMX : Boolean; -- MMX technology supported - FXSR : Boolean; -- fast FP save and restore - Res_3 : Natural range 0 .. 127; -- reserved for extensions - end record; - - for Processor_Features use - record - FPU at 0 range 0 .. 0; - VME at 0 range 1 .. 1; - DE at 0 range 2 .. 2; - PSE at 0 range 3 .. 3; - TSC at 0 range 4 .. 4; - MSR at 0 range 5 .. 5; - PAE at 0 range 6 .. 6; - MCE at 0 range 7 .. 7; - CX8 at 0 range 8 .. 8; - APIC at 0 range 9 .. 9; - Res_1 at 0 range 10 .. 10; - SEP at 0 range 11 .. 11; - MTRR at 0 range 12 .. 12; - PGE at 0 range 13 .. 13; - MCA at 0 range 14 .. 14; - CMOV at 0 range 15 .. 15; - PAT at 0 range 16 .. 16; - PSE_36 at 0 range 17 .. 17; - Res_2 at 0 range 18 .. 22; - MMX at 0 range 23 .. 23; - FXSR at 0 range 24 .. 24; - Res_3 at 0 range 25 .. 31; - end record; - - for Processor_Features'Size use 32; - - ------------------- - -- Subprograms -- - ------------------- - - function Has_FPU return Boolean; - -- return True if a FPU is found - -- use only if CPUID is not supported - - function Has_CPUID return Boolean; - -- return True if the processor supports the CPUID instruction - - function CPUID_Level return Natural; - -- return the CPUID support level (0, 1 or 2) - -- can only be called if the CPUID instruction is supported - - function Vendor_ID return String; - -- return the processor vendor identification string - -- can only be called if the CPUID instruction is supported - - function Signature return Processor_Signature; - -- return the processor signature - -- can only be called if the CPUID instruction is supported - - function Features return Processor_Features; - -- return the processors features - -- can only be called if the CPUID instruction is supported - - private - - ------------------------ - -- EFLAGS bit names -- - ------------------------ - - ID_Flag : constant Num_Bits := 21; - -- ID flag bit - - end Intel_CPU; - -  - File: gnat_ug_wnt.info, Node: Intel_CPU Package Body, Prev: Intel_CPU Package Specification, Up: A Complete Example - - `Intel_CPU' Package Body - ------------------------ - - package body Intel_CPU is - - --------------------------- - -- Detect FPU presence -- - --------------------------- - - -- There is a FPU present if we can set values to the FPU Status - -- and Control Words. - - function Has_FPU return Boolean is - - Register : Unsigned_16; - -- processor register to store a word - - begin - - -- check if we can change the status word - Asm ( - - -- the assembler code - "finit" & LF & HT & -- reset status word - "movw $0x5A5A, %%ax" & LF & HT & -- set value status word - "fnstsw %0" & LF & HT & -- save status word - "movw %%ax, %0", -- store status word - - -- output stored in Register - -- register must be a memory location - Outputs => Unsigned_16'Asm_output ("=m", Register), - - -- tell compiler that we used eax - Clobber => "eax"); - - -- if the status word is zero, there is no FPU - if Register = 0 then - return False; -- no status word - end if; -- check status word value - - -- check if we can get the control word - Asm ( - - -- the assembler code - "fnstcw %0", -- save the control word - - -- output into Register - -- register must be a memory location - Outputs => Unsigned_16'Asm_output ("=m", Register)); - - -- check the relevant bits - if (Register and 16#103F#) /= 16#003F# then - return False; -- no control word - end if; -- check control word value - - -- FPU found - return True; - - end Has_FPU; - - -------------------------------- - -- Detect CPUID instruction -- - -------------------------------- - - -- The processor supports the CPUID instruction if it is possible - -- to change the value of ID flag bit in the EFLAGS register. - - function Has_CPUID return Boolean is - - Original_Flags, Modified_Flags : Processor_Register; - -- EFLAG contents before and after changing the ID flag - - begin - - -- try flipping the ID flag in the EFLAGS register - Asm ( - - -- the assembler code - "pushfl" & LF & HT & -- push EFLAGS on stack - "pop %%eax" & LF & HT & -- pop EFLAGS into eax - "movl %%eax, %0" & LF & HT & -- save EFLAGS content - "xor $0x200000, %%eax" & LF & HT & -- flip ID flag - "push %%eax" & LF & HT & -- push EFLAGS on stack - "popfl" & LF & HT & -- load EFLAGS register - "pushfl" & LF & HT & -- push EFLAGS on stack - "pop %1", -- save EFLAGS content - - -- output values, may be anything - -- Original_Flags is %0 - -- Modified_Flags is %1 - Outputs => - (Processor_Register'Asm_output ("=g", Original_Flags), - Processor_Register'Asm_output ("=g", Modified_Flags)), - - -- tell compiler eax is destroyed - Clobber => "eax"); - - -- check if CPUID is supported - if Original_Flags(ID_Flag) /= Modified_Flags(ID_Flag) then - return True; -- ID flag was modified - else - return False; -- ID flag unchanged - end if; -- check for CPUID - - end Has_CPUID; - - ------------------------------- - -- Get CPUID support level -- - ------------------------------- - - function CPUID_Level return Natural is - - Level : Unsigned_32; - -- returned support level - - begin - - -- execute CPUID, storing the results in the Level register - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- zero is stored in eax - -- returning the support level in eax - Inputs => Unsigned_32'Asm_input ("a", 0), - - -- eax is stored in Level - Outputs => Unsigned_32'Asm_output ("=a", Level), - - -- tell compiler ebx, ecx and edx registers are destroyed - Clobber => "ebx, ecx, edx"); - - -- return the support level - return Natural (Level); - - end CPUID_Level; - - -------------------------------- - -- Get CPU Vendor ID String -- - -------------------------------- - - -- The vendor ID string is returned in the ebx, ecx and edx register - -- after executing the CPUID instruction with eax set to zero. - -- In case of a true Intel processor the string returned is - -- "GenuineIntel" - - function Vendor_ID return String is - - Ebx, Ecx, Edx : Unsigned_Register; - -- registers containing the vendor ID string - - Vendor_ID : String (1 .. 12); - -- the vendor ID string - - begin - - -- execute CPUID, storing the results in the processor registers - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- zero stored in eax - -- vendor ID string returned in ebx, ecx and edx - Inputs => Unsigned_32'Asm_input ("a", 0), - - -- ebx is stored in Ebx - -- ecx is stored in Ecx - -- edx is stored in Edx - Outputs => (Unsigned_Register'Asm_output ("=b", Ebx), - Unsigned_Register'Asm_output ("=c", Ecx), - Unsigned_Register'Asm_output ("=d", Edx))); - - -- now build the vendor ID string - Vendor_ID( 1) := Character'Val (Ebx.L1); - Vendor_ID( 2) := Character'Val (Ebx.H1); - Vendor_ID( 3) := Character'Val (Ebx.L2); - Vendor_ID( 4) := Character'Val (Ebx.H2); - Vendor_ID( 5) := Character'Val (Edx.L1); - Vendor_ID( 6) := Character'Val (Edx.H1); - Vendor_ID( 7) := Character'Val (Edx.L2); - Vendor_ID( 8) := Character'Val (Edx.H2); - Vendor_ID( 9) := Character'Val (Ecx.L1); - Vendor_ID(10) := Character'Val (Ecx.H1); - Vendor_ID(11) := Character'Val (Ecx.L2); - Vendor_ID(12) := Character'Val (Ecx.H2); - - -- return string - return Vendor_ID; - - end Vendor_ID; - - ------------------------------- - -- Get processor signature -- - ------------------------------- - - function Signature return Processor_Signature is - - Result : Processor_Signature; - -- processor signature returned - - begin - - -- execute CPUID, storing the results in the Result variable - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- one is stored in eax - -- processor signature returned in eax - Inputs => Unsigned_32'Asm_input ("a", 1), - - -- eax is stored in Result - Outputs => Processor_Signature'Asm_output ("=a", Result), - - -- tell compiler that ebx, ecx and edx are also destroyed - Clobber => "ebx, ecx, edx"); - - -- return processor signature - return Result; - - end Signature; - - ------------------------------ - -- Get processor features -- - ------------------------------ - - function Features return Processor_Features is - - Result : Processor_Features; - -- processor features returned - - begin - - -- execute CPUID, storing the results in the Result variable - Asm ( - - -- the assembler code - "cpuid", -- execute CPUID - - -- one stored in eax - -- processor features returned in edx - Inputs => Unsigned_32'Asm_input ("a", 1), - - -- edx is stored in Result - Outputs => Processor_Features'Asm_output ("=d", Result), - - -- tell compiler that ebx and ecx are also destroyed - Clobber => "ebx, ecx"); - - -- return processor signature - return Result; - - end Features; - - end Intel_CPU; - -  - File: gnat_ug_wnt.info, Node: Microsoft Windows Topics, Next: Performance Considerations, Prev: Inline Assembler, Up: Top - - Microsoft Windows Topics - ************************ - - This chapter describes topics that are specific to the Microsoft Windows - platforms (NT, 95 and 98). - - * Menu: - - * Using GNAT on Windows:: - * GNAT Setup Tool:: - * CONSOLE and WINDOWS subsystems:: - * Temporary Files:: - * Mixed-Language Programming on Windows:: - * Windows Calling Conventions:: - * Introduction to Dynamic Link Libraries (DLLs):: - * Using DLLs with GNAT:: - * Building DLLs with GNAT:: - * GNAT and Windows Resources:: - * Debugging a DLL:: - * GNAT and COM/DCOM Objects:: - -  - File: gnat_ug_wnt.info, Node: Using GNAT on Windows, Next: GNAT Setup Tool, Up: Microsoft Windows Topics - - Using GNAT on Windows - ===================== - - One of the strengths of the GNAT technology is that its tool set - (`gcc', `gnatbind', `gnatlink', `gnatmake', the `gdb' debugger, etc.) - is used in the same way regardless of the platform. - - On Windows this tool set is complemented by a number of - Microsoft-specific tools that have been provided to facilitate - interoperability with Windows when this is required. With these tools: - - * You can build applications using the `CONSOLE' or `WINDOWS' - subsystems. - - * You can use any Dynamically Linked Library (DLL) in your Ada code - (both relocatable and non-relocatable DLLs are supported). - - * You can build Ada DLLs for use in other applications. These - applications can be written in a language other than Ada (e.g., C, - C++, etc). Again both relocatable and non-relocatable Ada DLLs are - supported. - - * You can include Windows resources in your Ada application. - - * You can use or create COM/DCOM objects. - - Immediately below are listed all known general GNAT-for-Windows - restrictions. Other restrictions about specific features like Windows - Resources and DLLs are listed in separate sections below. - - * It is not possible to use `GetLastError' and `SetLastError' when - tasking, protected records, or exceptions are used. In these - cases, in order to implement Ada semantics, the GNAT run-time - system calls certain Win32 routines that set the last error - variable to 0 upon success. It should be possible to use - `GetLastError' and `SetLastError' when tasking, protected record, - and exception features are not used, but it is not guaranteed to - work. - -  - File: gnat_ug_wnt.info, Node: GNAT Setup Tool, Next: CONSOLE and WINDOWS subsystems, Prev: Using GNAT on Windows, Up: Microsoft Windows Topics - - GNAT Setup Tool - =============== - - * Menu: - - * Command-line arguments:: - * Creating a network installation of GNAT:: - * Registering and unregistering additional libraries:: - - GNAT installation on Windows is using the Windows registry in order to - locate proper executables and standard libraries. GNAT setup tool, - called `gnatreg.exe', is provided in order to display and modify - GNAT-specific registry entries, allowing to create network GNAT - installations, modify the locations of GNAT components, as well as - register and unregister additional libraries for use with GNAT. - -  - File: gnat_ug_wnt.info, Node: Command-line arguments, Next: Creating a network installation of GNAT, Up: GNAT Setup Tool - - Command-line arguments - ---------------------- - - `gnatreg [switches] [parameter]' - - Specifying no arguments causes gnatreg to display current configuration. - - The switches understood by gnatreg are: - -h - print the help message - - -a - add a standard library - - -r - remove a standard library - - -f - force creation of keys if they don't exist - - -q - be quiet/terse - -  - File: gnat_ug_wnt.info, Node: Creating a network installation of GNAT, Next: Registering and unregistering additional libraries, Prev: Command-line arguments, Up: GNAT Setup Tool - - Creating a network installation of GNAT - --------------------------------------- - - Make sure the system on which GNAT is installed is accessible from the - current machine. - - Use the command - - ` gnatreg -f \\server\sharename\path' - - in order to setup the registry entries on a current machine. - - For example, if GNAT is installed in `\GNAT' directory of a share - location called `c-drive' on a machine `LOKI', the command that can be - used on other machines to allow the remote use of GNAT is, - - ` gnatreg -f \\loki\c-drive\gnat' - - Remember to also add `\\loki\c-drive\gnat\bin' in front of your PATH - variable. - - Be aware that every compilation using the network installation - results in the transfer of large amounts of data across the network and - may cause serious performance penalty. - -  - File: gnat_ug_wnt.info, Node: Registering and unregistering additional libraries, Prev: Creating a network installation of GNAT, Up: GNAT Setup Tool - - Registering and unregistering additional libraries - -------------------------------------------------- - - To register a standard library use a command: - - ` gnatreg -a =' - - For example: - - ` gnatreg -a WIN32ADA=c:\Win32Ada' - - The libraries registered in this manner will be treated like - standard libraries by the compiler (i.e. they don't have to be - specified in -I and -l switches to various GNAT tools). - - To unregister a library, enter ` gnatreg -r ' - - e.g., ` gnatreg -r WIN32ADA' - -  - File: gnat_ug_wnt.info, Node: CONSOLE and WINDOWS subsystems, Next: Temporary Files, Prev: GNAT Setup Tool, Up: Microsoft Windows Topics - - CONSOLE and WINDOWS subsystems - ============================== - - Under Windows there is two main subsystems. The `CONSOLE' subsystem - (which is the default subsystem) will always create a console when - launching the application. This is not something desirable when the - application has a Windows GUI. To get rid of this console the - application must be using the `WINDOWS' subsystem. To do so the - `-mwindows' linker option must be specified. - - $ gnatmake winprog -largs -mwindows - -  - File: gnat_ug_wnt.info, Node: Temporary Files, Next: Mixed-Language Programming on Windows, Prev: CONSOLE and WINDOWS subsystems, Up: Microsoft Windows Topics - - Temporary Files - =============== - - It is possible to control where temporary files gets created by setting - the TMP environment variable. The file will be created: - - * Under the directory pointed to by the TMP environment variable if - this directory exists. - - * Under c:\temp, if the TMP environment variable is not set (or not - pointing to a directory) and if this directory exists. - - * Under the current working directory otherwise. - - This allows you to determine exactly where the temporary file will be - created. This is particularly useful in networked environments where - you may not have write access to some directories. - -  - File: gnat_ug_wnt.info, Node: Mixed-Language Programming on Windows, Next: Windows Calling Conventions, Prev: Temporary Files, Up: Microsoft Windows Topics - - Mixed-Language Programming on Windows - ===================================== - - Developing pure Ada applications on Windows is no different than on - other GNAT-supported platforms. However, when developing or porting an - application that contains a mix of Ada and C/C++, the choice of your - Windows C/C++ development environment conditions your overall - interoperability strategy. - - If you use `gcc' to compile the non-Ada part of your application, - there are no Windows-specific restrictions that affect the overall - interoperability with your Ada code. If you plan to use Microsoft tools - (e.g. Microsoft Visual C/C++), you should be aware of the following - limitations: - - * You cannot link your Ada code with an object or library generated - with Microsoft tools if these use the `.tls' section (Thread Local - Storage section) since the GNAT linker does not yet support this - section. - - * You cannot link your Ada code with an object or library generated - with Microsoft tools if these use I/O routines other than those - provided in the Microsoft DLL: `msvcrt.dll'. This is because the - GNAT run time uses the services of `msvcrt.dll' for its I/Os. Use - of other I/O libraries can cause a conflict with `msvcrt.dll' - services. For instance Visual C++ I/O stream routines conflict - with those in `msvcrt.dll'. - - If you do want to use the Microsoft tools for your non-Ada code and hit - one of the above limitations, you have two choices: - - 1. Encapsulate your non Ada code in a DLL to be linked with your Ada - application. In this case, use the Microsoft or whatever - environment to build the DLL and use GNAT to build your executable - (*note Using DLLs with GNAT::). - - 2. Or you can encapsulate your Ada code in a DLL to be linked with the - other part of your application. In this case, use GNAT to build - the DLL (*note Building DLLs with GNAT::) and use the Microsoft or - whatever environment to build your executable. - -  - File: gnat_ug_wnt.info, Node: Windows Calling Conventions, Next: Introduction to Dynamic Link Libraries (DLLs), Prev: Mixed-Language Programming on Windows, Up: Microsoft Windows Topics - - Windows Calling Conventions - =========================== - - * Menu: - - * C Calling Convention:: - * Stdcall Calling Convention:: - * DLL Calling Convention:: - - When a subprogram `F' (caller) calls a subprogram `G' (callee), there - are several ways to push `G''s parameters on the stack and there are - several possible scenarios to clean up the stack upon `G''s return. A - calling convention is an agreed upon software protocol whereby the - responsibilities between the caller (`F') and the callee (`G') are - clearly defined. Several calling conventions are available for Windows: - - * `C' (Microsoft defined) - - * `Stdcall' (Microsoft defined) - - * `DLL' (GNAT specific) - -  - File: gnat_ug_wnt.info, Node: C Calling Convention, Next: Stdcall Calling Convention, Up: Windows Calling Conventions - - `C' Calling Convention - ---------------------- - - This is the default calling convention used when interfacing to C/C++ - routines compiled with either `gcc' or Microsoft Visual C++. - - In the `C' calling convention subprogram parameters are pushed on the - stack by the caller from right to left. The caller itself is in charge - of cleaning up the stack after the call. In addition, the name of a - routine with `C' calling convention is mangled by adding a leading - underscore. - - The name to use on the Ada side when importing (or exporting) a - routine with `C' calling convention is the name of the routine. For - instance the C function: - - int get_val (long); - - should be imported from Ada as follows: - - function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; - pragma Import (C, Get_Val, External_Name => "get_val"); - - Note that in this particular case the `External_Name' parameter could - have been omitted since, when missing, this parameter is taken to be the - name of the Ada entity in lower case. When the `Link_Name' parameter is - missing, as in the above example, this parameter is set to be the - `External_Name' with a leading underscore. - - When importing a variable defined in C, you should always use the `C' - calling convention unless the object containing the variable is part of - a DLL (in which case you should use the `DLL' calling convention, *note - DLL Calling Convention::). - -  - File: gnat_ug_wnt.info, Node: Stdcall Calling Convention, Next: DLL Calling Convention, Prev: C Calling Convention, Up: Windows Calling Conventions - - `Stdcall' Calling Convention - ---------------------------- - - This convention, which was the calling convention used for Pascal - programs, is used by Microsoft for all the routines in the Win32 API for - efficiency reasons. It must be used to import any routine for which this - convention was specified. - - In the `Stdcall' calling convention subprogram parameters are pushed - on the stack by the caller from right to left. The callee (and not the - caller) is in charge of cleaning the stack on routine exit. In addition, - the name of a routine with `Stdcall' calling convention is mangled by - adding a leading underscore (as for the `C' calling convention) and a - trailing `@'`nn', where nn is the overall size (in bytes) of the - parameters passed to the routine. - - The name to use on the Ada side when importing a C routine with a - `Stdcall' calling convention is the name of the C routine. The leading - underscore and trailing `@'`nn' are added automatically by the - compiler. For instance the Win32 function: - - APIENTRY int get_val (long); - - should be imported from Ada as follows: - - function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; - pragma Import (Stdcall, Get_Val); - -- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@4" - - As for the `C' calling convention, when the `External_Name' parameter - is missing, it is taken to be the name of the Ada entity in lower case. - If instead of writing the above import pragma you write: - - function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; - pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val"); - - then the imported routine is `_retrieve_val@4'. However, if instead of - specifying the `External_Name' parameter you specify the `Link_Name' as - in the following example: - - function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; - pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val"); - - then the imported routine is `retrieve_val@4', that is, there is no - trailing underscore but the appropriate `@'`nn' is always added at the - end of the `Link_Name' by the compiler. - - Note, that in some special cases a DLL's entry point name lacks a - trailing `@'`nn' while the exported name generated for a call has it. - The `gnatdll' tool, which creates the import library for the DLL, is - able to handle those cases (see the description of the switches in - *note Using gnatdll:: section). - -  - File: gnat_ug_wnt.info, Node: DLL Calling Convention, Prev: Stdcall Calling Convention, Up: Windows Calling Conventions - - `DLL' Calling Convention - ------------------------ - - This convention, which is GNAT-specific, must be used when you want to - import in Ada a variables defined in a DLL. For functions and procedures - this convention is equivalent to the `Stdcall' convention. As an - example, if a DLL contains a variable defined as: - - int my_var; - - then, to access this variable from Ada you should write: - - My_Var : Interfaces.C.int; - pragma Import (DLL, My_Var); - - The remarks concerning the `External_Name' and `Link_Name' - parameters given in the previous sections equally apply to the `DLL' - calling convention. - -  - File: gnat_ug_wnt.info, Node: Introduction to Dynamic Link Libraries (DLLs), Next: Using DLLs with GNAT, Prev: Windows Calling Conventions, Up: Microsoft Windows Topics - - Introduction to Dynamic Link Libraries (DLLs) - ============================================= - - A Dynamically Linked Library (DLL) is a library that can be shared by - several applications running under Windows. A DLL can contain any - number of routines and variables. - - One advantage of DLLs is that you can change and enhance them without - forcing all the applications that depend on them to be relinked or - recompiled. However, you should be aware than all calls to DLL routines - are slower since, as you will understand below, such calls are indirect. - - To illustrate the remainder of this section, suppose that an - application wants to use the services of a DLL `API.dll'. To use the - services provided by `API.dll' you must statically link against an - import library which contains a jump table with an entry for each - routine and variable exported by the DLL. In the Microsoft world this - import library is called `API.lib'. When using GNAT this import library - is called either `libAPI.a' or `libapi.a' (names are case insensitive). - - After you have statically linked your application with the import - library and you run your application, here is what happens: - - 1. Your application is loaded into memory. - - 2. The DLL `API.dll' is mapped into the address space of your - application. This means that: - - * The DLL will use the stack of the calling thread. - - * The DLL will use the virtual address space of the calling - process. - - * The DLL will allocate memory from the virtual address space - of the calling process. - - * Handles (pointers) can be safely exchanged between routines - in the DLL routines and routines in the application using the - DLL. - - 3. The entries in the `libAPI.a' or `API.lib' jump table which is - part of your application are initialized with the addresses of the - routines and variables in `API.dll'. - - 4. If present in `API.dll', routines `DllMain' or `DllMainCRTStartup' - are invoked. These routines typically contain the initialization - code needed for the well-being of the routines and variables - exported by the DLL. - - There is an additional point which is worth mentioning. In the Windows - world there are two kind of DLLs: relocatable and non-relocatable DLLs. - Non-relocatable DLLs can only be loaded at a very specific address in - the target application address space. If the addresses of two - non-relocatable DLLs overlap and these happen to be used by the same - application, a conflict will occur and the application will run - incorrectly. Hence, when possible, it is always preferable to use and - build relocatable DLLs. Both relocatable and non-relocatable DLLs are - supported by GNAT. - - As a side note, an interesting difference between Microsoft DLLs and - Unix shared libraries, is the fact that on most Unix systems all public - routines are exported by default in a Unix shared library, while under - Windows the exported routines must be listed explicitly in a definition - file (*note The Definition File::). - -  - File: gnat_ug_wnt.info, Node: Using DLLs with GNAT, Next: Building DLLs with GNAT, Prev: Introduction to Dynamic Link Libraries (DLLs), Up: Microsoft Windows Topics - - Using DLLs with GNAT - ==================== - - * Menu: - - * Creating an Ada Spec for the DLL Services:: - * Creating an Import Library:: - - To use the services of a DLL, say `API.dll', in your Ada application - you must have: - - 1. The Ada spec for the routines and/or variables you want to access - in `API.dll'. If not available this Ada spec must be built from - the C/C++ header files provided with the DLL. - - 2. The import library (`libAPI.a' or `API.lib'). As previously - mentioned an import library is a statically linked library - containing the import table which will be filled at load time to - point to the actual `API.dll' routines. Sometimes you don't have - an import library for the DLL you want to use. The following - sections will explain how to build one. - - 3. The actual DLL, `API.dll'. - - Once you have all the above, to compile an Ada application that uses the - services of `API.dll' and whose main subprogram is `My_Ada_App', you - simply issue the command - - $ gnatmake my_ada_app -largs -lAPI - - The argument `-largs -lAPI' at the end of the `gnatmake' command tells - the GNAT linker to look first for a library named `API.lib' - (Microsoft-style name) and if not found for a library named `libAPI.a' - (GNAT-style name). Note that if the Ada package spec for `API.dll' - contains the following pragma - - pragma Linker_Options ("-lAPI"); - - you do not have to add `-largs -lAPI' at the end of the `gnatmake' - command. - - If any one of the items above is missing you will have to create it - yourself. The following sections explain how to do so using as an - example a fictitious DLL called `API.dll'. - -  - File: gnat_ug_wnt.info, Node: Creating an Ada Spec for the DLL Services, Next: Creating an Import Library, Up: Using DLLs with GNAT - - Creating an Ada Spec for the DLL Services - ----------------------------------------- - - A DLL typically comes with a C/C++ header file which provides the - definitions of the routines and variables exported by the DLL. The Ada - equivalent of this header file is a package spec that contains - definitions for the imported entities. If the DLL you intend to use - does not come with an Ada spec you have to generate one such spec - yourself. For example if the header file of `API.dll' is a file `api.h' - containing the following two definitions: - - int some_var; - int get (char *); - - then the equivalent Ada spec could be: - - with Interfaces.C.Strings; - package API is - use Interfaces; - - Some_Var : C.int; - function Get (Str : C.Strings.Chars_Ptr) return C.int; - - private - pragma Import (C, Get); - pragma Import (DLL, Some_Var); - end API; - - Note that a variable is *always imported with a DLL convention*. A - function can have `C', `Stdcall' or `DLL' convention. For subprograms, - the `DLL' convention is a synonym of `Stdcall' (*note Windows Calling - Conventions::). - -  - File: gnat_ug_wnt.info, Node: Creating an Import Library, Prev: Creating an Ada Spec for the DLL Services, Up: Using DLLs with GNAT - - Creating an Import Library - -------------------------- - - * Menu: - - * The Definition File:: - * GNAT-Style Import Library:: - * Microsoft-Style Import Library:: - - If a Microsoft-style import library `API.lib' or a GNAT-style import - library `libAPI.a' is available with `API.dll' you can skip this - section. Otherwise read on. - -  - File: gnat_ug_wnt.info, Node: The Definition File, Next: GNAT-Style Import Library, Up: Creating an Import Library - - The Definition File - ................... - - As previously mentioned, and unlike Unix systems, the list of symbols - that are exported from a DLL must be provided explicitly in Windows. - The main goal of a definition file is precisely that: list the symbols - exported by a DLL. A definition file (usually a file with a `.def' - suffix) has the following structure: - - [LIBRARY name] - [DESCRIPTION string] - EXPORTS - symbol1 - symbol2 - ... - - `LIBRARY name' - This section, which is optional, gives the name of the DLL. - - `DESCRIPTION string' - This section, which is optional, gives a description string that - will be embedded in the import library. - - `EXPORTS' - This section gives the list of exported symbols (procedures, - functions or variables). For instance in the case of `API.dll' the - `EXPORTS' section of `API.def' looks like: - - EXPORTS - some_var - get - - Note that you must specify the correct suffix (`@'`nn') (*note Windows - Calling Conventions::) for a Stdcall calling convention function in the - exported symbols list. - - There can actually be other sections in a definition file, but these - sections are not relevant to the discussion at hand. - -  - File: gnat_ug_wnt.info, Node: GNAT-Style Import Library, Next: Microsoft-Style Import Library, Prev: The Definition File, Up: Creating an Import Library - - GNAT-Style Import Library - ......................... - - To create a static import library from `API.dll' with the GNAT tools - you should proceed as follows: - - 1. Create the definition file `API.def' (*note The Definition File::). - For that use the `dll2def' tool as follows: - - $ dll2def API.dll > API.def - - `dll2def' is a very simple tool: it takes as input a DLL and prints - to standard output the list of entry points in the DLL. Note that - if some routines in the DLL have the `Stdcall' convention (*note - Windows Calling Conventions::) with stripped `@'nn suffix then - you'll have to edit `api.def' to add it. - - Here are some hints to find the right `@'nn suffix. - - 1. If you have the Microsoft import library (.lib), it is - possible to get the right symbols by using Microsoft - `dumpbin' tool (see the corresponding Microsoft documentation - for further details). - - $ dumpbin /exports api.lib - - 2. If you have a message about a missing symbol at link time the - compiler tells you what symbol is expected. You just have to - go back to the definition file and add the right suffix. - - 2. Build the import library `libAPI.a', using `gnatdll' (*note Using - gnatdll::) as follows: - - $ gnatdll -e API.def -d API.dll - - `gnatdll' takes as input a definition file `API.def' and the name - of the DLL containing the services listed in the definition file - `API.dll'. The name of the static import library generated is - computed from the name of the definition file as follows: if the - definition file name is xyz`.def', the import library name will be - `lib'xyz`.a'. Note that in the previous example option `-e' could - have been removed because the name of the definition file (before - the "`.def'" suffix) is the same as the name of the DLL (*note - Using gnatdll:: for more information about `gnatdll'). - -  - File: gnat_ug_wnt.info, Node: Microsoft-Style Import Library, Prev: GNAT-Style Import Library, Up: Creating an Import Library - - Microsoft-Style Import Library - .............................. - - With GNAT you can either use a GNAT-style or Microsoft-style import - library. A Microsoft import library is needed only if you plan to make - an Ada DLL available to applications developed with Microsoft tools - (*note Mixed-Language Programming on Windows::). - - To create a Microsoft-style import library for `API.dll' you should - proceed as follows: - - 1. Create the definition file `API.def' from the DLL. For this use - either the `dll2def' tool as described above or the Microsoft - `dumpbin' tool (see the corresponding Microsoft documentation for - further details). - - 2. Build the actual import library using Microsoft's `lib' utility: - - $ lib -machine:IX86 -def:API.def -out:API.lib - - If you use the above command the definition file `API.def' must - contain a line giving the name of the DLL: - - LIBRARY "API" - - See the Microsoft documentation for further details about the - usage of `lib'. - -  - File: gnat_ug_wnt.info, Node: Building DLLs with GNAT, Next: GNAT and Windows Resources, Prev: Using DLLs with GNAT, Up: Microsoft Windows Topics - - Building DLLs with GNAT - ======================= - - * Menu: - - * Limitations When Using Ada DLLs from Ada:: - * Exporting Ada Entities:: - * Ada DLLs and Elaboration:: - * Ada DLLs and Finalization:: - * Creating a Spec for Ada DLLs:: - * Creating the Definition File:: - * Using gnatdll:: - - This section explains how to build DLLs containing Ada code. These DLLs - will be referred to as Ada DLLs in the remainder of this section. - - The steps required to build an Ada DLL that is to be used by Ada as - well as non-Ada applications are as follows: - - 1. You need to mark each Ada entity exported by the DLL with a `C' or - `Stdcall' calling convention to avoid any Ada name mangling for the - entities exported by the DLL (*note Exporting Ada Entities::). You - can skip this step if you plan to use the Ada DLL only from Ada - applications. - - 2. Your Ada code must export an initialization routine which calls - the routine `adainit' generated by `gnatbind' to perform the - elaboration of the Ada code in the DLL (*note Ada DLLs and - Elaboration::). The initialization routine exported by the Ada DLL - must be invoked by the clients of the DLL to initialize the DLL. - - 3. When useful, the DLL should also export a finalization routine - which calls routine `adafinal' generated by `gnatbind' to perform - the finalization of the Ada code in the DLL (*note Ada DLLs and - Finalization::). The finalization routine exported by the Ada DLL - must be invoked by the clients of the DLL when the DLL services - are no further needed. - - 4. You must provide a spec for the services exported by the Ada DLL - in each of the programming languages to which you plan to make the - DLL available. - - 5. You must provide a definition file listing the exported entities - (*note The Definition File::). - - 6. Finally you must use `gnatdll' to produce the DLL and the import - library (*note Using gnatdll::). - -  - File: gnat_ug_wnt.info, Node: Limitations When Using Ada DLLs from Ada, Next: Exporting Ada Entities, Up: Building DLLs with GNAT - - Limitations When Using Ada DLLs from Ada - ---------------------------------------- - - When using Ada DLLs from Ada applications there is a limitation users - should be aware of. Because on Windows the GNAT run time is not in a - DLL of its own, each Ada DLL includes a part of the GNAT run time. - Specifically, each Ada DLL includes the services of the GNAT run time - that are necessary to the Ada code inside the DLL. As a result, when an - Ada program uses an Ada DLL there are two independent GNAT run times: - one in the Ada DLL and one in the main program. - - It is therefore not possible to exchange GNAT run-time objects - between the Ada DLL and the main Ada program. Example of GNAT run-time - objects are file handles (e.g. `Text_IO.File_Type'), tasks types, - protected objects types, etc. - - It is completely safe to exchange plain elementary, array or record - types, Windows object handles, etc. - -  - File: gnat_ug_wnt.info, Node: Exporting Ada Entities, Next: Ada DLLs and Elaboration, Prev: Limitations When Using Ada DLLs from Ada, Up: Building DLLs with GNAT - - Exporting Ada Entities - ---------------------- - - Building a DLL is a way to encapsulate a set of services usable from any - application. As a result, the Ada entities exported by a DLL should be - exported with the `C' or `Stdcall' calling conventions to avoid any Ada - name mangling. Please note that the `Stdcall' convention should only be - used for subprograms, not for variables. As an example here is an Ada - package `API', spec and body, exporting two procedures, a function, and - a variable: - - with Interfaces.C; use Interfaces; - package API is - Count : C.int := 0; - function Factorial (Val : C.int) return C.int; - - procedure Initialize_API; - procedure Finalize_API; - -- Initialization & Finalization routines. More in the next section. - private - pragma Export (C, Initialize_API); - pragma Export (C, Finalize_API); - pragma Export (C, Count); - pragma Export (C, Factorial); - end API; - - package body API is - function Factorial (Val : C.int) return C.int is - Fact : C.int := 1; - begin - Count := Count + 1; - for K in 1 .. Val loop - Fact := Fact * K; - end loop; - return Fact; - end Factorial; - - procedure Initialize_API is - procedure Adainit; - pragma Import (C, Adainit); - begin - Adainit; - end Initialize_API; - - procedure Finalize_API is - procedure Adafinal; - pragma Import (C, Adafinal); - begin - Adafinal; - end Finalize_API; - end API; - - If the Ada DLL you are building will only be used by Ada applications - you do not have to export Ada entities with a `C' or `Stdcall' - convention. As an example, the previous package could be written as - follows: - - package API is - Count : Integer := 0; - function Factorial (Val : Integer) return Integer; - - procedure Initialize_API; - procedure Finalize_API; - -- Initialization and Finalization routines. - end API; - - package body API is - function Factorial (Val : Integer) return Integer is - Fact : Integer := 1; - begin - Count := Count + 1; - for K in 1 .. Val loop - Fact := Fact * K; - end loop; - return Fact; - end Factorial; - - ... - -- The remainder of this package body is unchanged. - end API; - - Note that if you do not export the Ada entities with a `C' or `Stdcall' - convention you will have to provide the mangled Ada names in the - definition file of the Ada DLL (*note Creating the Definition File::). - -  - File: gnat_ug_wnt.info, Node: Ada DLLs and Elaboration, Next: Ada DLLs and Finalization, Prev: Exporting Ada Entities, Up: Building DLLs with GNAT - - Ada DLLs and Elaboration - ------------------------ - - The DLL that you are building contains your Ada code as well as all the - routines in the Ada library that are needed by it. The first thing a - user of your DLL must do is elaborate the Ada code (*note Elaboration - Order Handling in GNAT::). - - To achieve this you must export an initialization routine - (`Initialize_API' in the previous example), which must be invoked - before using any of the DLL services. This elaboration routine must call - the Ada elaboration routine `adainit' generated by the GNAT binder - (*note Binding with Non-Ada Main Programs::). See the body of - `Initialize_Api' for an example. Note that the GNAT binder is - automatically invoked during the DLL build process by the `gnatdll' - tool (*note Using gnatdll::). - - When a DLL is loaded, Windows systematically invokes a routine called - `DllMain'. It would therefore be possible to call `adainit' directly - from `DllMain' without having to provide an explicit initialization - routine. Unfortunately, it is not possible to call `adainit' from the - `DllMain' if your program has library level tasks because access to the - `DllMain' entry point is serialized by the system (that is, only a - single thread can execute "through" it at a time), which means that the - GNAT run time will deadlock waiting for the newly created task to - complete its initialization. - -  - File: gnat_ug_wnt.info, Node: Ada DLLs and Finalization, Next: Creating a Spec for Ada DLLs, Prev: Ada DLLs and Elaboration, Up: Building DLLs with GNAT - - Ada DLLs and Finalization - ------------------------- - - When the services of an Ada DLL are no longer needed, the client code - should invoke the DLL finalization routine, if available. The DLL - finalization routine is in charge of releasing all resources acquired - by the DLL. In the case of the Ada code contained in the DLL, this is - achieved by calling routine `adafinal' generated by the GNAT binder - (*note Binding with Non-Ada Main Programs::). See the body of - `Finalize_Api' for an example. As already pointed out the GNAT binder - is automatically invoked during the DLL build process by the `gnatdll' - tool (*note Using gnatdll::). - - `-g' - Generate debugging information. This information is stored in the object - file and copied from there to the final DLL file by the linker, where - it can be read by the debugger. You must use the `-g' switch if you - plan on using the debugger or the symbolic stack traceback. - -  - File: gnat_ug_wnt.info, Node: Creating a Spec for Ada DLLs, Next: Creating the Definition File, Prev: Ada DLLs and Finalization, Up: Building DLLs with GNAT - - Creating a Spec for Ada DLLs - ---------------------------- - - To use the services exported by the Ada DLL from another programming - language (e.g. C), you have to translate the specs of the exported Ada - entities in that language. For instance in the case of `API.dll', the - corresponding C header file could look like: - - extern int *__imp__count; - #define count (*__imp__count) - int factorial (int); - - It is important to understand that when building an Ada DLL to be used - by other Ada applications, you need two different specs for the packages - contained in the DLL: one for building the DLL and the other for using - the DLL. This is because the `DLL' calling convention is needed to use - a variable defined in a DLL, but when building the DLL, the variable - must have either the `Ada' or `C' calling convention. As an example - consider a DLL comprising the following package `API': - - package API is - Count : Integer := 0; - ... - -- Remainder of the package omitted. - end API; - - After producing a DLL containing package `API', the spec that must be - used to import `API.Count' from Ada code outside of the DLL is: - - package API is - Count : Integer; - pragma Import (DLL, Count); - end API; - -  - File: gnat_ug_wnt.info, Node: Creating the Definition File, Next: Using gnatdll, Prev: Creating a Spec for Ada DLLs, Up: Building DLLs with GNAT - - Creating the Definition File - ---------------------------- - - The definition file is the last file needed to build the DLL. It lists - the exported symbols. As an example, the definition file for a DLL - containing only package `API' (where all the entities are exported with - a `C' calling convention) is: - - EXPORTS - count - factorial - finalize_api - initialize_api - - If the `C' calling convention is missing from package `API', then the - definition file contains the mangled Ada names of the above entities, - which in this case are: - - EXPORTS - api__count - api__factorial - api__finalize_api - api__initialize_api - -  - File: gnat_ug_wnt.info, Node: Using gnatdll, Prev: Creating the Definition File, Up: Building DLLs with GNAT - - Using `gnatdll' - --------------- - - * Menu: - - * gnatdll Example:: - * gnatdll behind the Scenes:: - * Using dlltool:: - - `gnatdll' is a tool to automate the DLL build process once all the Ada - and non-Ada sources that make up your DLL have been compiled. - `gnatdll' is actually in charge of two distinct tasks: build the static - import library for the DLL and the actual DLL. The form of the - `gnatdll' command is - - $ gnatdll [SWITCHES] LIST-OF-FILES [-largs OPTS] - - where list-of-files is a list of ALI and object files. The object file - list must be the exact list of objects corresponding to the non-Ada - sources whose services are to be included in the DLL. The ALI file list - must be the exact list of ALI files for the corresponding Ada sources - whose services are to be included in the DLL. If list-of-files is - missing, only the static import library is generated. - - You may specify any of the following switches to `gnatdll': - - `-a[ADDRESS]' - Build a non-relocatable DLL at ADDRESS. If ADDRESS is not - specified the default address 0X11000000 will be used. By default, - when this switch is missing, `gnatdll' builds relocatable DLL. We - advise the reader to build relocatable DLL. - - `-b ADDRESS' - Set the relocatable DLL base address. By default the address is - 0X11000000. - - `-d DLLFILE' - DLLFILE is the name of the DLL. This switch must be present for - `gnatdll' to do anything. The name of the generated import library - is obtained algorithmically from DLLFILE as shown in the following - example: if DLLFILE is `xyz.dll', the import library name is - `libxyz.a'. The name of the definition file to use (if not - specified by option `-e') is obtained algorithmically from DLLFILE - as shown in the following example: if DLLFILE is `xyz.dll', the - definition file used is `xyz.def'. - - `-e DEFFILE' - DEFFILE is the name of the definition file. - - `-h' - Help mode. Displays `gnatdll' switch usage information. - - `-Idir' - Direct `gnatdll' to search the DIR directory for source and object - files needed to build the DLL. (*note Search Paths and the - Run-Time Library (RTL)::). - - `-k' - Removes the `@'nn suffix from the import library's exported names. - You must specified this option if you want to use a `Stdcall' - function in a DLL for which the `@'nn suffix has been removed. - This is the case for most of the Windows NT DLL for example. This - option has no effect when `-n' option is specified. - - `-l FILE' - The list of ALI and object files used to build the DLL are listed - in FILE, instead of being given in the command line. Each line in - FILE contains the name of an ALI or object file. - - `-n' - No Import. Do not create the import library. - - `-q' - Quiet mode. Do not display unnecessary messages. - - `-v' - Verbose mode. Display extra information. - - `-largs OPTS' - Linker options. Pass OPTS to the linker. - -  - File: gnat_ug_wnt.info, Node: gnatdll Example, Next: gnatdll behind the Scenes, Up: Using gnatdll - - `gnatdll' Example - ................. - - As an example the command to build a relocatable DLL from `api.adb' - once `api.adb' has been compiled and `api.def' created is - - $ gnatdll -d api.dll api.ali - - The above command creates two files: `libapi.a' (the import library) - and `api.dll' (the actual DLL). If you want to create only the DLL, - just type: - - $ gnatdll -d api.dll -n api.ali - - Alternatively if you want to create just the import library, type: - - $ gnatdll -d api.dll - -  - File: gnat_ug_wnt.info, Node: gnatdll behind the Scenes, Next: Using dlltool, Prev: gnatdll Example, Up: Using gnatdll - - `gnatdll' behind the Scenes - ........................... - - This section details the steps involved in creating a DLL. `gnatdll' - does these steps for you. Unless you are interested in understanding - what goes on behind the scenes, you should skip this section. - - We use the previous example of a DLL containing the Ada package - `API', to illustrate the steps necessary to build a DLL. The starting - point is a set of objects that will make up the DLL and the - corresponding ALI files. In the case of this example this means that - `api.o' and `api.ali' are available. To build a relocatable DLL, - `gnatdll' does the following: - - 1. `gnatdll' builds the base file (`api.base'). A base file gives the - information necessary to generate relocation information for the - DLL. - - $ gnatbind -n api - $ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base - - In addition to the base file, the `gnatlink' command generates an - output file `api.jnk' which can be discarded. The `-mdll' switch - asks `gnatlink' to generate the routines `DllMain' and - `DllMainCRTStartup' that are called by the Windows loader when the - DLL is loaded into memory. - - 2. `gnatdll' uses `dlltool' (*note Using dlltool::) to build the - export table (`api.exp'). The export table contains the relocation - information in a form which can be used during the final link to - ensure that the Windows loader is able to place the DLL anywhere - in memory. - - $ dlltool --dllname api.dll --def api.def --base-file api.base \ - --output-exp api.exp - - 3. `gnatdll' builds the base file using the new export table. Note - that `gnatbind' must be called once again since the binder - generated file has been deleted during the previous call to - `gnatlink'. - - $ gnatbind -n api - $ gnatlink api -o api.jnk api.exp -mdll - -Wl,--base-file,api.base - - 4. `gnatdll' builds the new export table using the new base file and - generates the DLL import library `libAPI.a'. - - $ dlltool --dllname api.dll --def api.def --base-file api.base \ - --output-exp api.exp --output-lib libAPI.a - - 5. Finally `gnatdll' builds the relocatable DLL using the final export - table. - - $ gnatbind -n api - $ gnatlink api api.exp -o api.dll -mdll - -  - File: gnat_ug_wnt.info, Node: Using dlltool, Prev: gnatdll behind the Scenes, Up: Using gnatdll - - Using `dlltool' - ............... - - `dlltool' is the low-level tool used by `gnatdll' to build DLLs and - static import libraries. This section summarizes the most common - `dlltool' switches. The form of the `dlltool' command is - - $ dlltool [SWITCHES] - - `dlltool' switches include: - - `--base-file BASEFILE' - Read the base file BASEFILE generated by the linker. This switch - is used to create a relocatable DLL. - - `--def DEFFILE' - Read the definition file. - - `--dllname NAME' - Gives the name of the DLL. This switch is used to embed the name - of the DLL in the static import library generated by `dlltool' - with switch `--output-lib'. - - `-k' - Kill `@'nn from exported names (*note Windows Calling Conventions:: - for a discussion about `Stdcall'-style symbols. - - `--help' - Prints the `dlltool' switches with a concise description. - - `--output-exp EXPORTFILE' - Generate an export file EXPORTFILE. The export file contains the - export table (list of symbols in the DLL) and is used to create - the DLL. - - `--output-lib libfile' - Generate a static import library LIBFILE. - - `-v' - Verbose mode. - - `--as assembler-name' - Use assembler-name as the assembler. The default is `as'. - -  - File: gnat_ug_wnt.info, Node: GNAT and Windows Resources, Next: Debugging a DLL, Prev: Building DLLs with GNAT, Up: Microsoft Windows Topics - - GNAT and Windows Resources - ========================== - - * Menu: - - * Building Resources:: - * Compiling Resources:: - * Using Resources:: - * Limitations:: - - Resources are an easy way to add Windows specific objects to your - application. The objects that can be added as resources include: - - * menus - - * accelerators - - * dialog boxes - - * string tables - - * bitmaps - - * cursors - - * icons - - * fonts - - This section explains how to build, compile and use resources. - -  - File: gnat_ug_wnt.info, Node: Building Resources, Next: Compiling Resources, Up: GNAT and Windows Resources - - Building Resources - ------------------ - - A resource file is an ASCII file. By convention resource files have an - `.rc' extension. The easiest way to build a resource file is to use - Microsoft tools such as `imagedit.exe' to build bitmaps, icons and - cursors and `dlgedit.exe' to build dialogs. It is always possible to - build an `.rc' file yourself by writing a resource script. - - It is not our objective to explain how to write a resource file. A - complete description of the resource script language can be found in the - Microsoft documentation. - -  - File: gnat_ug_wnt.info, Node: Compiling Resources, Next: Using Resources, Prev: Building Resources, Up: GNAT and Windows Resources - - Compiling Resources - ------------------- - - This section describes how to build a GNAT-compatible (COFF) object file - containing the resources. This is done using the Resource Compiler - `rcl' as follows: - - $ rcl -i myres.rc -o myres.o - - By default `rcl' will run `gcc' to preprocess the `.rc' file. You can - specify an alternate preprocessor (usually named `cpp.exe') using the - `rcl' `-cpp' parameter. A list of all possible options may be obtained - by entering the command `rcl' with no parameters. - - It is also possible to use the Microsoft resource compiler `rc.exe' - to produce a `.res' file (binary resource file). See the corresponding - Microsoft documentation for further details. In this case you need to - use `res2coff' to translate the `.res' file to a GNAT-compatible object - file as follows: - - $ res2coff -i myres.res -o myres.o - -  - File: gnat_ug_wnt.info, Node: Using Resources, Next: Limitations, Prev: Compiling Resources, Up: GNAT and Windows Resources - - Using Resources - --------------- - - To include the resource file in your program just add the - GNAT-compatible object file for the resource(s) to the linker - arguments. With `gnatmake' this is done by using the `-largs' option: - - $ gnatmake myprog -largs myres.o - -  - File: gnat_ug_wnt.info, Node: Limitations, Prev: Using Resources, Up: GNAT and Windows Resources - - Limitations - ----------- - - In this section we describe the current limitations together with - suggestions for workarounds. - - * `rcl' does not handle the `RCINCLUDE' directive. - Workaround: replace `RCINCLUDE' by an `#include' directive. - - * `rcl' does not handle the brackets as block delimiters. - Workaround: replace character '{' by `BEGIN' and '}' by `END'. - Note that Microsoft's `rc' handles both forms of block delimiters. - - * `rcl' does not handle `TypeLib' resources. This type of resource - is used to build COM, DCOM or ActiveX objects. - Workaround: use `rc', the Microsoft resource compiler. - - * It is not possible to use `strip' to remove the debugging symbols - from a program with resources. - Workaround: use linker option `-s' to strip debugging symbols from - the final executable. - -  - File: gnat_ug_wnt.info, Node: Debugging a DLL, Next: GNAT and COM/DCOM Objects, Prev: GNAT and Windows Resources, Up: Microsoft Windows Topics - - Debugging a DLL - =============== - - * Menu: - - * The Program and the DLL Are Built with GCC/GNAT:: - * The Program Is Built with Some Foreign Tools and the DLL Is Built with GCC/GNAT:: - - Debugging a DLL is similar to debugging a standard program. But we have - to deal with two different executable parts: the DLL and the program - that uses it. We have the following four possibilities: - - 1. The program and the DLL are built with `GCC/GNAT'. - - 2. The program is built with foreign tools and the DLL is built with - `GCC/GNAT'. - - 3. The program is built with `GCC/GNAT' and the DLL is built with - foreign tools. - - 4. - In this section we address only cases one and two above. There is no - point in trying to debug a DLL with `GNU/GDB', if there is no - GDB-compatible debugging information in it. To do so you must use a - debugger compatible with the tools suite used to build the DLL. - -  - File: gnat_ug_wnt.info, Node: The Program and the DLL Are Built with GCC/GNAT, Next: The Program Is Built with Some Foreign Tools and the DLL Is Built with GCC/GNAT, Up: Debugging a DLL - - The Program and the DLL Are Built with GCC/GNAT - ----------------------------------------------- - - This is the simplest case. Both the DLL and the program have `GDB' - compatible debugging information. It is then possible to break anywhere - in the process. Let's suppose here that the main procedure is named - `ada_main' and that in the DLL there is an entry point named `ada_dll'. - - The DLL (*note Introduction to Dynamic Link Libraries (DLLs)::) and - program must have been built with the debugging information (see GNAT -g - switch). Here are the step-by-step instructions for debugging it: - - 1. Launch `GDB' on the main program. - - $ gdb -nw ada_main - - 2. Break on the main procedure and run the program. - - (gdb) break ada_main - (gdb) run - - This step is required to be able to set a breakpoint inside the - DLL. As long as the program is not run, the DLL is not loaded. - This has the consequence that the DLL debugging information is - also not loaded, so it is not possible to set a breakpoint in the - DLL. - - 3. Set a breakpoint inside the DLL - - (gdb) break ada_dll - (gdb) run - - - At this stage a breakpoint is set inside the DLL. From there on you can - use the standard approach to debug the whole program (*note Running and - Debugging Ada Programs::). - -  - File: gnat_ug_wnt.info, Node: The Program Is Built with Some Foreign Tools and the DLL Is Built with GCC/GNAT, Prev: The Program and the DLL Are Built with GCC/GNAT, Up: Debugging a DLL - - The Program Is Built with Some Foreign Tools and the DLL Is Built with GCC/GNAT - ------------------------------------------------------------------------------- - - * Menu: - - * Debugging the DLL Directly:: - * Attaching to a Running Process:: - - In this case things are slightly more complex because it is not - possible to start the main program and then break at the beginning to - load the DLL and the associated DLL debugging information. It is not - possible to break at the beginning of the program because there is no - `GDB' debugging information, and therefore there is no direct way of - getting initial control. This section addresses this issue by - describing some methods that can be used to break somewhere in the DLL - to debug it. - - First suppose that the main procedure is named `main' (this is for - example some C code built with Microsoft Visual C) and that there is a - DLL named `test.dll' containing an Ada entry point named `ada_dll'. - - The DLL (*note Introduction to Dynamic Link Libraries (DLLs)::) must - have been built with debugging information (see GNAT -g option). - -  - File: gnat_ug_wnt.info, Node: Debugging the DLL Directly, Next: Attaching to a Running Process, Up: The Program Is Built with Some Foreign Tools and the DLL Is Built with GCC/GNAT - - Debugging the DLL Directly - .......................... - - 1. Launch the debugger on the DLL. - - $ gdb -nw test.dll - - 2. Set a breakpoint on a DLL subroutine. - - (gdb) break ada_dll - - 3. Specify the executable file to `GDB'. - - (gdb) exec-file main.exe - - 4. Run the program. - - (gdb) run - - This will run the program until it reaches the breakpoint that has - been set. From that point you can use the standard way to debug a - program as described in (*note Running and Debugging Ada - Programs::). - - - It is also possible to debug the DLL by attaching to a running process. - -  - File: gnat_ug_wnt.info, Node: Attaching to a Running Process, Prev: Debugging the DLL Directly, Up: The Program Is Built with Some Foreign Tools and the DLL Is Built with GCC/GNAT - - Attaching to a Running Process - .............................. - - With `GDB' it is always possible to debug a running process by - attaching to it. It is possible to debug a DLL this way. The limitation - of this approach is that the DLL must run long enough to perform the - attach operation. It may be useful for instance to insert a time wasting - loop in the code of the DLL to meet this criterion. - - 1. Launch the main program `main.exe'. - - $ main - - 2. Use the Windows Task Manager to find the process ID. Let's say - that the process PID for `main.exe' is 208. - - 3. Launch gdb. - - $ gdb -nw - - 4. Attach to the running process to be debugged. - - (gdb) attach 208 - - 5. Load the process debugging information. - - (gdb) symbol-file main.exe - - 6. Break somewhere in the DLL. - - (gdb) break ada_dll - - 7. Continue process execution. - - (gdb) continue - - - This last step will resume the process execution, and stop at the - breakpoint we have set. From there you can use the standard approach to - debug a program as described in (*note Running and Debugging Ada - Programs::). - -  - File: gnat_ug_wnt.info, Node: GNAT and COM/DCOM Objects, Prev: Debugging a DLL, Up: Microsoft Windows Topics - - GNAT and COM/DCOM Objects - ========================= - - This section is temporarily left blank. - -  - File: gnat_ug_wnt.info, Node: Performance Considerations, Next: GNU Free Documentation License, Prev: Microsoft Windows Topics, Up: Top - - Performance Considerations - ************************** - - The GNAT system provides a number of options that allow a trade-off - between - - * performance of the generated code - - * speed of compilation - - * minimization of dependences and recompilation - - * the degree of run-time checking. - - The defaults (if no options are selected) aim at improving the speed of - compilation and minimizing dependences, at the expense of performance - of the generated code: - - * no optimization - - * no inlining of subprogram calls - - * all run-time checks enabled except overflow and elaboration checks - - These options are suitable for most program development purposes. This - chapter describes how you can modify these choices, and also provides - some guidelines on debugging optimized code. - - * Menu: - - * Controlling Run-Time Checks:: - * Optimization Levels:: - * Debugging Optimized Code:: - * Inlining of Subprograms:: - -  - File: gnat_ug_wnt.info, Node: Controlling Run-Time Checks, Next: Optimization Levels, Up: Performance Considerations - - Controlling Run-Time Checks - =========================== - - By default, GNAT generates all run-time checks, except arithmetic - overflow checking for integer operations and checks for access before - elaboration on subprogram calls. The latter are not required in default - mode, because all necessary checking is done at compile time. Two gnat - switches, `-gnatp' and `-gnato' allow this default to be modified. - *Note Run-Time Checks::. - - Our experience is that the default is suitable for most development - purposes. - - We treat integer overflow specially because these are quite - expensive and in our experience are not as important as other run-time - checks in the development process. Note that division by zero is not - considered an overflow check, and divide by zero checks are generated - where required by default. - - Elaboration checks are off by default, and also not needed by - default, since GNAT uses a static elaboration analysis approach that - avoids the need for run-time checking. This manual contains a full - chapter discussing the issue of elaboration checks, and if the default - is not satisfactory for your use, you should read this chapter. - - For validity checks, the minimal checks required by the Ada Reference - Manual (for case statements and assignments to array elements) are on - by default. These can be suppressed by use of the `-gnatVn' switch. - Note that in Ada 83, there were no validity checks, so if the Ada 83 - mode is acceptable (or when comparing GNAT performance with an Ada 83 - compiler), it may be reasonable to routinely use `-gnatVn'. Validity - checks are also suppressed entirely if `-gnatp' is used. - - Note that the setting of the switches controls the default setting of - the checks. They may be modified using either `pragma Suppress' (to - remove checks) or `pragma Unsuppress' (to add back suppressed checks) - in the program source. - -  - File: gnat_ug_wnt.info, Node: Optimization Levels, Next: Debugging Optimized Code, Prev: Controlling Run-Time Checks, Up: Performance Considerations - - Optimization Levels - =================== - - The default is optimization off. This results in the fastest compile - times, but GNAT makes absolutely no attempt to optimize, and the - generated programs are considerably larger and slower than when - optimization is enabled. You can use the `-ON' switch, where N is an - integer from 0 to 3, on the `gcc' command line to control the - optimization level: - - `-O0' - no optimization (the default) - - `-O1' - medium level optimization - - `-O2' - full optimization - - `-O3' - full optimization, and also attempt automatic inlining of small - subprograms within a unit (*note Inlining of Subprograms::). - - Higher optimization levels perform more global transformations on the - program and apply more expensive analysis algorithms in order to - generate faster and more compact code. The price in compilation time, - and the resulting improvement in execution time, both depend on the - particular application and the hardware environment. You should - experiment to find the best level for your application. - - Note: Unlike some other compilation systems, `gcc' has been tested - extensively at all optimization levels. There are some bugs which - appear only with optimization turned on, but there have also been bugs - which show up only in _unoptimized_ code. Selecting a lower level of - optimization does not improve the reliability of the code generator, - which in practice is highly reliable at all optimization levels. - - Note regarding the use of `-O3': The use of this optimization level - is generally discouraged with GNAT, since it often results in larger - executables which run more slowly. See further discussion of this point - in *note Inlining of Subprograms::. - -  - File: gnat_ug_wnt.info, Node: Debugging Optimized Code, Next: Inlining of Subprograms, Prev: Optimization Levels, Up: Performance Considerations - - Debugging Optimized Code - ======================== - - Since the compiler generates debugging tables for a compilation unit - before it performs optimizations, the optimizing transformations may - invalidate some of the debugging data. You therefore need to - anticipate certain anomalous situations that may arise while debugging - optimized code. This section describes the most common cases. - - 1. The "hopping Program Counter": Repeated 'step' or 'next' commands - show the PC bouncing back and forth in the code. This may result - from any of the following optimizations: - - * Common subexpression elimination: using a single instance of - code for a quantity that the source computes several times. - As a result you may not be able to stop on what looks like a - statement. - - * Invariant code motion: moving an expression that does not - change within a loop, to the beginning of the loop. - - * Instruction scheduling: moving instructions so as to overlap - loads and stores (typically) with other code, or in general - to move computations of values closer to their uses. Often - this causes you to pass an assignment statement without the - assignment happening and then later bounce back to the - statement when the value is actually needed. Placing a - breakpoint on a line of code and then stepping over it may, - therefore, not always cause all the expected side-effects. - - 2. The "big leap": More commonly known as cross-jumping, in which two - identical pieces of code are merged and the program counter - suddenly jumps to a statement that is not supposed to be executed, - simply because it (and the code following) translates to the same - thing as the code that _was_ supposed to be executed. This effect - is typically seen in sequences that end in a jump, such as a - `goto', a `return', or a `break' in a C `switch' statement. - - 3. The "roving variable": The symptom is an unexpected value in a - variable. There are various reasons for this effect: - - * In a subprogram prologue, a parameter may not yet have been - moved to its "home". - - * A variable may be dead, and its register re-used. This is - probably the most common cause. - - * As mentioned above, the assignment of a value to a variable - may have been moved. - - * A variable may be eliminated entirely by value propagation or - other means. In this case, GCC may incorrectly generate - debugging information for the variable - - In general, when an unexpected value appears for a local variable - or parameter you should first ascertain if that value was actually - computed by your program, as opposed to being incorrectly reported - by the debugger. Record fields or array elements in an object - designated by an access value are generally less of a problem, - once you have ascertained that the access value is sensible. - Typically, this means checking variables in the preceding code and - in the calling subprogram to verify that the value observed is - explainable from other values (one must apply the procedure - recursively to those other values); or re-running the code and - stopping a little earlier (perhaps before the call) and stepping - to better see how the variable obtained the value in question; or - continuing to step _from_ the point of the strange value to see if - code motion had simply moved the variable's assignments later. - -  - File: gnat_ug_wnt.info, Node: Inlining of Subprograms, Prev: Debugging Optimized Code, Up: Performance Considerations - - Inlining of Subprograms - ======================= - - A call to a subprogram in the current unit is inlined if all the - following conditions are met: - - * The optimization level is at least `-O1'. - - * The called subprogram is suitable for inlining: It must be small - enough and not contain nested subprograms or anything else that - `gcc' cannot support in inlined subprograms. - - * The call occurs after the definition of the body of the subprogram. - - * Either `pragma Inline' applies to the subprogram or it is small - and automatic inlining (optimization level `-O3') is specified. - - Calls to subprograms in `with''ed units are normally not inlined. To - achieve this level of inlining, the following conditions must all be - true: - - * The optimization level is at least `-O1'. - - * The called subprogram is suitable for inlining: It must be small - enough and not contain nested subprograms or anything else `gcc' - cannot support in inlined subprograms. - - * The call appears in a body (not in a package spec). - - * There is a `pragma Inline' for the subprogram. - - * The `-gnatn' switch is used in the `gcc' command line - - Note that specifying the `-gnatn' switch causes additional - compilation dependencies. Consider the following: - - package R is - procedure Q; - pragma Inline (Q); - end R; - package body R is - ... - end R; - - with R; - procedure Main is - begin - ... - R.Q; - end Main; - - With the default behavior (no `-gnatn' switch specified), the - compilation of the `Main' procedure depends only on its own source, - `main.adb', and the spec of the package in file `r.ads'. This means - that editing the body of `R' does not require recompiling `Main'. - - On the other hand, the call `R.Q' is not inlined under these - circumstances. If the `-gnatn' switch is present when `Main' is - compiled, the call will be inlined if the body of `Q' is small enough, - but now `Main' depends on the body of `R' in `r.adb' as well as on the - spec. This means that if this body is edited, the main program must be - recompiled. Note that this extra dependency occurs whether or not the - call is in fact inlined by `gcc'. - - The use of front end inlining with `-gnatN' generates similar - additional dependencies. - - Note: The `-fno-inline' switch can be used to prevent all inlining. - This switch overrides all other conditions and ensures that no inlining - occurs. The extra dependences resulting from `-gnatn' will still be - active, even if this switch is used to suppress the resulting inlining - actions. - - Note regarding the use of `-O3': There is no difference in inlining - behavior between `-O2' and `-O3' for subprograms with an explicit - pragma `Inline' assuming the use of `-gnatn' or `-gnatN' (the switches - that activate inlining). If you have used pragma `Inline' in - appropriate cases, then it is usually much better to use `-O2' and - `-gnatn' and avoid the use of `-O3' which in this case only has the - effect of inlining subprograms you did not think should be inlined. We - often find that the use of `-O3' slows down code by performing - excessive inlining, leading to increased instruction cache pressure - from the increased code size. So the bottom line here is that you - should not automatically assume that `-O3' is better than `-O2', and - indeed you should use `-O3' only if tests show that it actually - improves performance. - -  - File: gnat_ug_wnt.info, Node: GNU Free Documentation License, Next: Index, Prev: Performance Considerations, Up: Top - - GNU Free Documentation License - ****************************** - - Version 1.2, November 2002 - Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - functional and useful document "free" in the sense of freedom: to - assure everyone the effective freedom to copy and redistribute it, - with or without modifying it, either commercially or - noncommercially. Secondarily, this License preserves for the - author and publisher a way to get credit for their work, while not - being considered responsible for modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - We have designed this License in order to use it for manuals for - free software, because free software needs free documentation: a - free program should come with manuals providing the same freedoms - that the software does. But this License is not limited to - software manuals; it can be used for any textual work, regardless - of subject matter or whether it is published as a printed book. - We recommend this License principally for works whose purpose is - instruction or reference. - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work, in any medium, - that contains a notice placed by the copyright holder saying it - can be distributed under the terms of this License. Such a notice - grants a world-wide, royalty-free license, unlimited in duration, - to use that work under the conditions stated herein. The - "Document", below, refers to any such manual or work. Any member - of the public is a licensee, and is addressed as "you". You - accept the license if you copy, modify or distribute the work in a - way requiring permission under copyright law. - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (Thus, if the Document - is in part a textbook of mathematics, a Secondary Section may not - explain any mathematics.) The relationship could be a matter of - historical connection with the subject or with related matters, or - of legal, commercial, philosophical, ethical or political position - regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in - the notice that says that the Document is released under this - License. If a section does not fit the above definition of - Secondary then it is not allowed to be designated as Invariant. - The Document may contain zero Invariant Sections. If the Document - does not identify any Invariant Sections then there are none. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. A - Front-Cover Text may be at most 5 words, and a Back-Cover Text may - be at most 25 words. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, that is suitable for revising the document - straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup, or absence of - markup, has been arranged to thwart or discourage subsequent - modification by readers is not Transparent. An image format is - not Transparent if used for any substantial amount of text. A - copy that is not "Transparent" is called "Opaque". - - Examples of suitable formats for Transparent copies include plain - ASCII without markup, Texinfo input format, LaTeX input format, - SGML or XML using a publicly available DTD, and - standard-conforming simple HTML, PostScript or PDF designed for - human modification. Examples of transparent image formats include - PNG, XCF and JPG. Opaque formats include proprietary formats that - can be read and edited only by proprietary word processors, SGML or - XML for which the DTD and/or processing tools are not generally - available, and the machine-generated HTML, PostScript or PDF - produced by some word processors for output purposes only. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - A section "Entitled XYZ" means a named subunit of the Document - whose title either is precisely XYZ or contains XYZ in parentheses - following text that translates XYZ in another language. (Here XYZ - stands for a specific section name mentioned below, such as - "Acknowledgements", "Dedications", "Endorsements", or "History".) - To "Preserve the Title" of such a section when you modify the - Document means that it remains a section "Entitled XYZ" according - to this definition. - - The Document may include Warranty Disclaimers next to the notice - which states that this License applies to the Document. These - Warranty Disclaimers are considered to be included by reference in - this License, but only as regards disclaiming warranties: any other - implication that these Warranty Disclaimers may have is void and - has no effect on the meaning of this License. - - 2. VERBATIM COPYING - - You may copy and distribute the Document in any medium, either - commercially or noncommercially, provided that this License, the - copyright notices, and the license notice saying this License - applies to the Document are reproduced in all copies, and that you - add no other conditions whatsoever to those of this License. You - may not use technical measures to obstruct or control the reading - or further copying of the copies you make or distribute. However, - you may accept compensation in exchange for copies. If you - distribute a large enough number of copies you must also follow - the conditions in section 3. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - If you publish printed copies (or copies in media that commonly - have printed covers) of the Document, numbering more than 100, and - the Document's license notice requires Cover Texts, you must - enclose the copies in covers that carry, clearly and legibly, all - these Cover Texts: Front-Cover Texts on the front cover, and - Back-Cover Texts on the back cover. Both covers must also clearly - and legibly identify you as the publisher of these copies. The - front cover must present the full title with all words of the - title equally prominent and visible. You may add other material - on the covers in addition. Copying with changes limited to the - covers, as long as they preserve the title of the Document and - satisfy these conditions, can be treated as verbatim copying in - other respects. - - If the required texts for either cover are too voluminous to fit - legibly, you should put the first ones listed (as many as fit - reasonably) on the actual cover, and continue the rest onto - adjacent pages. - - If you publish or distribute Opaque copies of the Document - numbering more than 100, you must either include a - machine-readable Transparent copy along with each Opaque copy, or - state in or with each Opaque copy a computer-network location from - which the general network-using public has access to download - using public-standard network protocols a complete Transparent - copy of the Document, free of added material. If you use the - latter option, you must take reasonably prudent steps, when you - begin distribution of Opaque copies in quantity, to ensure that - this Transparent copy will remain thus accessible at the stated - location until at least one year after the last time you - distribute an Opaque copy (directly or through your agents or - retailers) of that edition to the public. - - It is requested, but not required, that you contact the authors of - the Document well before redistributing any large number of - copies, to give them a chance to provide you with an updated - version of the Document. - - 4. MODIFICATIONS - - You may copy and distribute a Modified Version of the Document - under the conditions of sections 2 and 3 above, provided that you - release the Modified Version under precisely this License, with - the Modified Version filling the role of the Document, thus - licensing distribution and modification of the Modified Version to - whoever possesses a copy of it. In addition, you must do these - things in the Modified Version: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of - previous versions (which should, if there were any, be listed - in the History section of the Document). You may use the - same title as a previous version if the original publisher of - that version gives permission. - - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in - the Modified Version, together with at least five of the - principal authors of the Document (all of its principal - authors, if it has fewer than five), unless they release you - from this requirement. - - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - - D. Preserve all the copyright notices of the Document. - - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified - Version under the terms of this License, in the form shown in - the Addendum below. - - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's - license notice. - - H. Include an unaltered copy of this License. - - I. Preserve the section Entitled "History", Preserve its Title, - and add to it an item stating at least the title, year, new - authors, and publisher of the Modified Version as given on - the Title Page. If there is no section Entitled "History" in - the Document, create one stating the title, year, authors, - and publisher of the Document as given on its Title Page, - then add an item describing the Modified Version as stated in - the previous sentence. - - J. Preserve the network location, if any, given in the Document - for public access to a Transparent copy of the Document, and - likewise the network locations given in the Document for - previous versions it was based on. These may be placed in - the "History" section. You may omit a network location for a - work that was published at least four years before the - Document itself, or if the original publisher of the version - it refers to gives permission. - - K. For any section Entitled "Acknowledgements" or "Dedications", - Preserve the Title of the section, and preserve in the - section all the substance and tone of each of the contributor - acknowledgements and/or dedications given therein. - - L. Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section - titles. - - M. Delete any section Entitled "Endorsements". Such a section - may not be included in the Modified Version. - - N. Do not retitle any existing section to be Entitled - "Endorsements" or to conflict in title with any Invariant - Section. - - O. Preserve any Warranty Disclaimers. - - If the Modified Version includes new front-matter sections or - appendices that qualify as Secondary Sections and contain no - material copied from the Document, you may at your option - designate some or all of these sections as invariant. To do this, - add their titles to the list of Invariant Sections in the Modified - Version's license notice. These titles must be distinct from any - other section titles. - - You may add a section Entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties--for example, statements of peer review or that the text - has been approved by an organization as the authoritative - definition of a standard. - - You may add a passage of up to five words as a Front-Cover Text, - and a passage of up to 25 words as a Back-Cover Text, to the end - of the list of Cover Texts in the Modified Version. Only one - passage of Front-Cover Text and one of Back-Cover Text may be - added by (or through arrangements made by) any one entity. If the - Document already includes a cover text for the same cover, - previously added by you or by arrangement made by the same entity - you are acting on behalf of, you may not add another; but you may - replace the old one, on explicit permission from the previous - publisher that added the old one. - - The author(s) and publisher(s) of the Document do not by this - License give permission to use their names for publicity for or to - assert or imply endorsement of any Modified Version. - - 5. COMBINING DOCUMENTS - - You may combine the Document with other documents released under - this License, under the terms defined in section 4 above for - modified versions, provided that you include in the combination - all of the Invariant Sections of all of the original documents, - unmodified, and list them all as Invariant Sections of your - combined work in its license notice, and that you preserve all - their Warranty Disclaimers. - - The combined work need only contain one copy of this License, and - multiple identical Invariant Sections may be replaced with a single - copy. If there are multiple Invariant Sections with the same name - but different contents, make the title of each such section unique - by adding at the end of it, in parentheses, the name of the - original author or publisher of that section if known, or else a - unique number. Make the same adjustment to the section titles in - the list of Invariant Sections in the license notice of the - combined work. - - In the combination, you must combine any sections Entitled - "History" in the various original documents, forming one section - Entitled "History"; likewise combine any sections Entitled - "Acknowledgements", and any sections Entitled "Dedications". You - must delete all sections Entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - You may make a collection consisting of the Document and other - documents released under this License, and replace the individual - copies of this License in the various documents with a single copy - that is included in the collection, provided that you follow the - rules of this License for verbatim copying of each of the - documents in all other respects. - - You may extract a single document from such a collection, and - distribute it individually under this License, provided you insert - a copy of this License into the extracted document, and follow - this License in all other respects regarding verbatim copying of - that document. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of - a storage or distribution medium, is called an "aggregate" if the - copyright resulting from the compilation is not used to limit the - legal rights of the compilation's users beyond what the individual - works permit. When the Document is included an aggregate, this - License does not apply to the other works in the aggregate which - are not themselves derivative works of the Document. - - If the Cover Text requirement of section 3 is applicable to these - copies of the Document, then if the Document is less than one half - of the entire aggregate, the Document's Cover Texts may be placed - on covers that bracket the Document within the aggregate, or the - electronic equivalent of covers if the Document is in electronic - form. Otherwise they must appear on printed covers that bracket - the whole aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License, and all the license notices in the - Document, and any Warrany Disclaimers, provided that you also - include the original English version of this License and the - original versions of those notices and disclaimers. In case of a - disagreement between the translation and the original version of - this License or a notice or disclaimer, the original version will - prevail. - - If a section in the Document is Entitled "Acknowledgements", - "Dedications", or "History", the requirement (section 4) to - Preserve its Title (section 1) will typically require changing the - actual title. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - `http://www.gnu.org/copyleft/'. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - - ADDENDUM: How to use this License for your documents - ==================================================== - - To use this License in a document you have written, include a copy of - the License in the document and put the following copyright and license - notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.2 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - - If you have Invariant Sections, Front-Cover Texts and Back-Cover - Texts, replace the "with...Texts." line with this: - - with the Invariant Sections being LIST THEIR TITLES, with - the Front-Cover Texts being LIST, and with the Back-Cover Texts - being LIST. - - If you have Invariant Sections without Cover Texts, or some other - combination of the three, merge those two alternatives to suit the - situation. - - If your document contains nontrivial examples of program code, we - recommend releasing these examples in parallel under your choice of - free software license, such as the GNU General Public License, to - permit their use in free software. - -  - File: gnat_ug_wnt.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - - Index - ***** - - * Menu: - - * --GCC= (gnatchop): Switches for gnatchop. - * --GCC=compiler_name (gnatlink): Switches for gnatlink. - * --GCC=compiler_name (gnatmake): Switches for gnatmake. - * --GNATBIND=binder_name (gnatmake): Switches for gnatmake. - * --GNATLINK=linker_name (gnatmake): Switches for gnatmake. - * --LINK= (gnatlink): Switches for gnatlink. - * --RTS (gcc): Switches for gcc. - * --RTS (gnatbind): Summary of Binder Switches. - * --RTS (gnatfind): gnatfind Switches. - * --RTS (gnatls): Switches for gnatls. - * --RTS (gnatmake): Switches for gnatmake. - * --RTS (gnatxref): gnatxref Switches. - * -83 (gnathtml): Converting Ada Files to html with gnathtml. - * -A (gnatbind): Output Control. - * -a (gnatdll): Using gnatdll. - * -A (gnatlink): Switches for gnatlink. - * -a (gnatls): Switches for gnatls. - * -A (gnatmake): Switches for gnatmake. - * -a (gnatmake): Switches for gnatmake. - * -aI (gnatmake): Switches for gnatmake. - * -aL (gnatmake): Switches for gnatmake. - * -aO (gnatmake): Switches for gnatmake. - * -B (gcc): Switches for gcc. - * -b (gcc): Switches for gcc. - * -b (gnatbind): Binder Error Message Control. - * -b (gnatdll): Using gnatdll. - * -B (gnatlink): Switches for gnatlink. - * -b (gnatlink): Switches for gnatlink. - * -b (gnatmake): Switches for gnatmake. - * -bargs (gnatmake): Mode Switches for gnatmake. - * -c (gcc): Switches for gcc. - * -C (gnatbind): Output Control. - * -c (gnatbind): Output Control. - * -c (gnatchop): Switches for gnatchop. - * -C (gnatlink): Switches for gnatlink. - * -C (gnatmake): Switches for gnatmake. - * -c (gnatmake): Switches for gnatmake. - * -c (gnatname): Switches for gnatname. - * -cargs (gnatmake): Mode Switches for gnatmake. - * -d (gnatdll): Using gnatdll. - * -d (gnathtml): Converting Ada Files to html with gnathtml. - * -d (gnatls): Switches for gnatls. - * -D (gnatname): Switches for gnatname. - * -d (gnatname): Switches for gnatname. - * -e (gnatbind): Output Control. - * -e (gnatdll): Using gnatdll. - * -f (gnathtml): Converting Ada Files to html with gnathtml. - * -f (gnatlink): Switches for gnatlink. - * -f (gnatmake): Switches for gnatmake. - * -fno-inline (gcc): Inlining of Subprograms. - * -fstack-check: Stack Overflow Checking. - * -g (gcc): Switches for gcc. - * -g (gnatdll): Ada DLLs and Finalization. - * -g (gnatlink): Switches for gnatlink. - * -gnat83 (gcc): Compiling Ada 83 Programs. - * -gnata (gcc): Debugging and Assertion Control. - * -gnatb (gcc): Output and Error Message Control. - * -gnatc (gcc): Using gcc for Semantic Checking. - * -gnatD (gcc): Debugging Control. - * -gnatdc switch: GNAT Abnormal Termination or Failure to Terminate. - * -gnatE (gcc) <1>: Debugging Control. - * -gnatE (gcc): Run-Time Checks. - * -gnatem (gcc): Units to Sources Mapping Files. - * -gnatf (gcc): Output and Error Message Control. - * -gnatG (gcc): Debugging Control. - * -gnati (gcc): Character Set Control. - * -gnatk (gcc): File Naming Control. - * -gnatl (gcc): Output and Error Message Control. - * -gnatm (gcc): Output and Error Message Control. - * -gnatn (gcc): Inlining of Subprograms. - * -gnatN (gcc): Subprogram Inlining Control. - * -gnatn (gcc): Subprogram Inlining Control. - * -gnatN switch: Source Dependencies. - * -gnatn switch: Source Dependencies. - * -gnato (gcc) <1>: Controlling Run-Time Checks. - * -gnato (gcc): Run-Time Checks. - * -gnatp (gcc) <1>: Controlling Run-Time Checks. - * -gnatp (gcc): Run-Time Checks. - * -gnatq (gcc): Output and Error Message Control. - * -gnatR (gcc): Debugging Control. - * -gnats (gcc): Using gcc for Syntax Checking. - * -gnatt (gcc): Auxiliary Output Control. - * -gnatT (gcc): Run-Time Control. - * -gnatu (gcc): Auxiliary Output Control. - * -gnatU (gcc): Output and Error Message Control. - * -gnatv (gcc): Output and Error Message Control. - * -gnatW (gcc): Character Set Control. - * -gnatwA (gcc): Output and Error Message Control. - * -gnatwa (gcc): Output and Error Message Control. - * -gnatwB (gcc): Output and Error Message Control. - * -gnatwb (gcc): Output and Error Message Control. - * -gnatwC (gcc): Output and Error Message Control. - * -gnatwc (gcc): Output and Error Message Control. - * -gnatwD (gcc): Output and Error Message Control. - * -gnatwd (gcc): Output and Error Message Control. - * -gnatwe (gcc): Output and Error Message Control. - * -gnatwF (gcc): Output and Error Message Control. - * -gnatwf (gcc): Output and Error Message Control. - * -gnatwH (gcc): Output and Error Message Control. - * -gnatwh (gcc): Output and Error Message Control. - * -gnatwI (gcc): Output and Error Message Control. - * -gnatwi (gcc): Output and Error Message Control. - * -gnatwL (gcc): Output and Error Message Control. - * -gnatwl (gcc): Output and Error Message Control. - * -gnatwO (gcc): Output and Error Message Control. - * -gnatwo (gcc): Output and Error Message Control. - * -gnatwP (gcc): Output and Error Message Control. - * -gnatwp (gcc): Output and Error Message Control. - * -gnatwR (gcc): Output and Error Message Control. - * -gnatwr (gcc): Output and Error Message Control. - * -gnatws (gcc): Output and Error Message Control. - * -gnatwU (gcc): Output and Error Message Control. - * -gnatwu (gcc): Output and Error Message Control. - * -gnatx (gcc): Debugging Control. - * -h (gnatbind) <1>: Output Control. - * -h (gnatbind): Elaboration Control. - * -h (gnatdll): Using gnatdll. - * -h (gnatls): Switches for gnatls. - * -h (gnatname): Switches for gnatname. - * -I (gcc): Switches for gcc. - * -I (gnathtml): Converting Ada Files to html with gnathtml. - * -I (gnatmake): Switches for gnatmake. - * -i (gnatmake): Switches for gnatmake. - * -i (gnatmem): Switches for gnatmem. - * -I- (gcc): Switches for gcc. - * -I- (gnatmake): Switches for gnatmake. - * -j (gnatmake): Switches for gnatmake. - * -K (gnatbind): Output Control. - * -k (gnatchop): Switches for gnatchop. - * -k (gnatmake): Switches for gnatmake. - * -l (gnatbind): Output Control. - * -l (gnatdll): Using gnatdll. - * -l (gnathtml): Converting Ada Files to html with gnathtml. - * -L (gnatmake): Switches for gnatmake. - * -l (gnatmake): Switches for gnatmake. - * -largs (gnatdll): Using gnatdll. - * -largs (gnatmake): Mode Switches for gnatmake. - * -M (gnatbind): Binder Error Message Control. - * -m (gnatbind): Binder Error Message Control. - * -M (gnatmake): Switches for gnatmake. - * -m (gnatmake): Switches for gnatmake. - * -mwindows: CONSOLE and WINDOWS subsystems. - * -n (gnatbind): Binding with Non-Ada Main Programs. - * -n (gnatdll): Using gnatdll. - * -n (gnatlink): Switches for gnatlink. - * -n (gnatmake): Switches for gnatmake. - * -nostdinc (gnatmake): Switches for gnatmake. - * -nostdlib (gnatmake): Switches for gnatmake. - * -O (gcc) <1>: Optimization Levels. - * -O (gcc): Switches for gcc. - * -o (gcc): Switches for gcc. - * -o (gnatbind): Output Control. - * -O (gnatbind): Output Control. - * -o (gnathtml): Converting Ada Files to html with gnathtml. - * -o (gnatlink): Switches for gnatlink. - * -o (gnatls): Switches for gnatls. - * -o (gnatmake): Switches for gnatmake. - * -o (gnatmem): Switches for gnatmem. - * -p (gnatchop): Switches for gnatchop. - * -p (gnathtml): Converting Ada Files to html with gnathtml. - * -P (gnatname): Switches for gnatname. - * -pass-exit-codes (gcc): Auxiliary Output Control. - * -q (gnatchop): Switches for gnatchop. - * -q (gnatdll): Using gnatdll. - * -q (gnatmake): Switches for gnatmake. - * -q (gnatmem): Switches for gnatmem. - * -r (gnatbind): Output Control. - * -r (gnatchop): Switches for gnatchop. - * -S (gcc): Switches for gcc. - * -s (gnatbind): Consistency-Checking Modes. - * -s (gnatls): Switches for gnatls. - * -s (gnatmake): Switches for gnatmake. - * -sc (gnathtml): Converting Ada Files to html with gnathtml. - * -t (gnatbind): Binder Error Message Control. - * -t (gnathtml): Converting Ada Files to html with gnathtml. - * -u (gnatls): Switches for gnatls. - * -u (gnatmake): Switches for gnatmake. - * -V (gcc): Switches for gcc. - * -v (gcc): Switches for gcc. - * -v (gnatbind): Binder Error Message Control. - * -v (gnatchop): Switches for gnatchop. - * -v (gnatdll): Using gnatdll. - * -v (gnatlink): Switches for gnatlink. - * -v (gnatmake): Switches for gnatmake. - * -v (gnatname): Switches for gnatname. - * -v -v (gnatlink): Switches for gnatlink. - * -w: Output and Error Message Control. - * -w (gnatchop): Switches for gnatchop. - * -we (gnatbind): Binder Error Message Control. - * -ws (gnatbind): Binder Error Message Control. - * -x (gnatbind): Consistency-Checking Modes. - * -z (gnatbind): Binding Programs with No Main Subprogram. - * -z (gnatmake): Switches for gnatmake. - * .def: The Definition File. - * __gnat_finalize: Running gnatbind. - * __gnat_initialize: Running gnatbind. - * __gnat_set_globals: Running gnatbind. - * _main: The External Symbol Naming Scheme of GNAT. - * Access before elaboration: Run-Time Checks. - * Access-to-subprogram: Elaboration for Access-to-Subprogram Values. - * ACVC, Ada 83 tests: Compiling Ada 83 Programs. - * Ada <1>: Naming Conventions for GNAT Source Files. - * Ada: Search Paths for gnatbind. - * Ada 83 compatibility: Compiling Ada 83 Programs. - * Ada 95 Language Reference Manual: What You Should Know before Reading This Guide. - * Ada expressions: Using Ada Expressions. - * Ada Library Information files: The Ada Library Information Files. - * Ada.Characters.Latin_1: Latin-1. - * ADA_INCLUDE_PATH: Search Paths and the Run-Time Library (RTL). - * ADA_OBJECTS_PATH: Search Paths for gnatbind. - * adafinal <1>: Binding with Non-Ada Main Programs. - * adafinal: Running gnatbind. - * adainit <1>: Binding with Non-Ada Main Programs. - * adainit: Running gnatbind. - * Address Clauses, warnings: Output and Error Message Control. - * ali files: The Ada Library Information Files. - * Annex A: Naming Conventions for GNAT Source Files. - * Annex B: Naming Conventions for GNAT Source Files. - * APIENTRY: Windows Calling Conventions. - * Arbitrary File Naming Conventions: Handling Arbitrary File Naming Conventions Using gnatname. - * Asm: Calling Conventions. - * Assert: Debugging and Assertion Control. - * Assertions: Debugging and Assertion Control. - * Biased rounding: Output and Error Message Control. - * Binder consistency checks: Binder Error Message Control. - * Binder output file: Interfacing to C. - * Binder, multiple input files: Binding with Non-Ada Main Programs. - * Breakpoints and tasks: Ada Tasks. - * C: Calling Conventions. - * C++: Calling Conventions. - * Calling Conventions: Calling Conventions. - * Check, elaboration: Run-Time Checks. - * Check, overflow: Run-Time Checks. - * Check_CPU procedure: Check_CPU Procedure. - * Checks, access before elaboration: Run-Time Checks. - * Checks, division by zero: Run-Time Checks. - * Checks, elaboration: Checking the Elaboration Order in Ada 95. - * Checks, overflow: Controlling Run-Time Checks. - * Checks, suppressing: Run-Time Checks. - * COBOL: Calling Conventions. - * code page 437: Other 8-Bit Codes. - * code page 850: Other 8-Bit Codes. - * COM: GNAT and COM/DCOM Objects. - * Combining GNAT switches: Switches for gcc. - * Command line length: Switches for gnatlink. - * Compilation model: The GNAT Compilation Model. - * Conditionals, constant: Output and Error Message Control. - * Configuration pragmas: Configuration Pragmas. - * Consistency checks, in binder: Binder Error Message Control. - * CONSOLE Subsystem: CONSOLE and WINDOWS subsystems. - * Convention Ada: Calling Conventions. - * Convention Asm: Calling Conventions. - * Convention Assembler: Calling Conventions. - * Convention C: Calling Conventions. - * Convention C++: Calling Conventions. - * Convention COBOL: Calling Conventions. - * Convention Default: Calling Conventions. - * Convention DLL: Calling Conventions. - * Convention External: Calling Conventions. - * Convention Fortran: Calling Conventions. - * Convention Stdcall: Calling Conventions. - * Convention Stubbed: Calling Conventions. - * Convention Win32: Calling Conventions. - * Conventions: Conventions. - * CR: Source Representation. - * Cyrillic: Other 8-Bit Codes. - * DCOM: GNAT and COM/DCOM Objects. - * Debug: Debugging and Assertion Control. - * Debug Pool: Finding Memory Problems with GNAT Debug Pool. - * Debugger: Running and Debugging Ada Programs. - * Debugging: Running and Debugging Ada Programs. - * Debugging Generic Units: Debugging Generic Units. - * Debugging information, including: Switches for gnatlink. - * Debugging options: Debugging Control. - * Default: Calling Conventions. - * Definition file: The Definition File. - * Dependencies, producing list: Switches for gnatmake. - * Dependency rules: The GNAT Make Program gnatmake. - * Dereferencing, implicit: Output and Error Message Control. - * Division by zero: Run-Time Checks. - * DLL <1>: Introduction to Dynamic Link Libraries (DLLs). - * DLL: Calling Conventions. - * DLL debugging: Debugging a DLL. - * DLL debugging, attach to process: Attaching to a Running Process. - * DLLs and elaboration: Ada DLLs and Elaboration. - * DLLs and finalization: Ada DLLs and Finalization. - * DLLs, building: Building DLLs with GNAT. - * Elaborate: Controlling the Elaboration Order in Ada 95. - * Elaborate_All: Controlling the Elaboration Order in Ada 95. - * Elaborate_Body: Controlling the Elaboration Order in Ada 95. - * Elaboration checks <1>: Checking the Elaboration Order in Ada 95. - * Elaboration checks: Run-Time Checks. - * Elaboration control <1>: Summary of Procedures for Elaboration Control. - * Elaboration control: Elaboration Order Handling in GNAT. - * Elaboration of library tasks: Elaboration Issues for Library Tasks. - * Elaboration order control: Comparison between GNAT and C/C++ Compilation Models. - * Elaboration, warnings: Output and Error Message Control. - * Eliminate: Eliminate Pragma. - * End of source file: Source Representation. - * Error messages, suppressing: Output and Error Message Control. - * EUC Coding: Wide Character Encodings. - * Exceptions: Ada Exceptions. - * Export: The External Symbol Naming Scheme of GNAT. - * Export table: Exporting Ada Entities. - * External: Calling Conventions. - * FDL, GNU Free Documentation License: GNU Free Documentation License. - * FF: Source Representation. - * File names <1>: Alternative File Naming Schemes. - * File names: Using Other File Names. - * File naming schemes, alternative: Alternative File Naming Schemes. - * Foreign Languages: Calling Conventions. - * Formals, unreferenced: Output and Error Message Control. - * Fortran: Calling Conventions. - * gdb: Running and Debugging Ada Programs. - * Generic formal parameters: Compiling Ada 83 Programs. - * Generics <1>: Debugging Generic Units. - * Generics: Generating Object Files. - * Glide: Introduction to Glide and GVD. - * GMEM (gnatmem): Running gnatmem (GMEM Mode). - * GNAT <1>: Naming Conventions for GNAT Source Files. - * GNAT: Search Paths for gnatbind. - * GNAT Abnormal Termination or Failure to Terminate: GNAT Abnormal Termination or Failure to Terminate. - * GNAT compilation model: The GNAT Compilation Model. - * GNAT library: Comparison between GNAT and Conventional Ada Library Models. - * GNAT Setup Tool: GNAT Setup Tool. - * gnat.adc <1>: The Configuration Pragmas Files. - * gnat.adc: Using Other File Names. - * gnat1: Compiling Programs. - * gnat_argc: Command-Line Access. - * gnat_argv: Command-Line Access. - * GNAT_STACK_LIMIT: Stack Overflow Checking. - * gnatbind: Binding Using gnatbind. - * gnatchop: Renaming Files Using gnatchop. - * gnatdll: Using gnatdll. - * gnatelim: Reducing the Size of Ada Executables with gnatelim. - * gnatfind: The Cross-Referencing Tools gnatxref and gnatfind. - * gnatkr: File Name Krunching Using gnatkr. - * gnatlink: Linking Using gnatlink. - * gnatls: The GNAT Library Browser gnatls. - * gnatmake: The GNAT Make Program gnatmake. - * gnatmem: Finding Memory Problems with gnatmem. - * gnatprep: Preprocessing Using gnatprep. - * gnatreg: GNAT Setup Tool. - * gnatstub: Creating Sample Bodies Using gnatstub. - * gnatxref: The Cross-Referencing Tools gnatxref and gnatfind. - * GNU make: Using gnatmake in a Makefile. - * GVD: Introduction to Glide and GVD. - * Hiding of Declarations: Output and Error Message Control. - * HT: Source Representation. - * Implicit dereferencing: Output and Error Message Control. - * Import library: Creating an Import Library. - * Inline <1>: Inlining of Subprograms. - * Inline: Source Dependencies. - * Inlining: Comparison between GNAT and Conventional Ada Library Models. - * Inlining, warnings: Output and Error Message Control. - * Intel_CPU package body: Intel_CPU Package Body. - * Intel_CPU package specification: Intel_CPU Package Specification. - * Interfaces <1>: Naming Conventions for GNAT Source Files. - * Interfaces: Search Paths for gnatbind. - * Interfacing to Ada: Calling Conventions. - * Interfacing to Assembly: Calling Conventions. - * Interfacing to C: Calling Conventions. - * Interfacing to C++: Calling Conventions. - * Interfacing to COBOL: Calling Conventions. - * Interfacing to Fortran: Calling Conventions. - * Internal trees, writing to file: Auxiliary Output Control. - * Latin-1 <1>: Latin-1. - * Latin-1: Source Representation. - * Latin-2: Other 8-Bit Codes. - * Latin-3: Other 8-Bit Codes. - * Latin-4: Other 8-Bit Codes. - * Latin-5: Other 8-Bit Codes. - * LF: Source Representation. - * Library browser: The GNAT Library Browser gnatls. - * Library tasks, elaboration issues: Elaboration Issues for Library Tasks. - * Library, building, installing: GNAT and Libraries. - * Linker libraries: Switches for gnatmake. - * Machine_Overflows: Run-Time Checks. - * Main Program: Running gnatbind. - * make: Using the GNU make Utility. - * makefile: Using gnatmake in a Makefile. - * Mixed Language Programming: Mixed Language Programming. - * Multiple units, syntax checking: Using gcc for Syntax Checking. - * n (gnatmem): Switches for gnatmem. - * No code generated: Compiling Programs. - * No_Entry_Calls_In_Elaboration_Code: Elaboration Issues for Library Tasks. - * Object file list: Running gnatbind. - * Order of elaboration: Elaboration Order Handling in GNAT. - * Other Ada compilers: Calling Conventions. - * Overflow checks <1>: Controlling Run-Time Checks. - * Overflow checks: Run-Time Checks. - * Parallel make: Switches for gnatmake. - * Performance: Performance Considerations. - * pragma Elaborate: Controlling the Elaboration Order in Ada 95. - * pragma Elaborate_All: Controlling the Elaboration Order in Ada 95. - * pragma Elaborate_Body: Controlling the Elaboration Order in Ada 95. - * pragma Inline: Inlining of Subprograms. - * pragma Preelaborate: Controlling the Elaboration Order in Ada 95. - * pragma Pure: Controlling the Elaboration Order in Ada 95. - * pragma Suppress: Controlling Run-Time Checks. - * pragma Unsuppress: Controlling Run-Time Checks. - * Pragmas, configuration: Configuration Pragmas. - * Preelaborate: Controlling the Elaboration Order in Ada 95. - * Pure: Controlling the Elaboration Order in Ada 95. - * rc: Compiling Resources. - * rcl: Compiling Resources. - * Recompilation, by gnatmake: Notes on the Command Line. - * res2coff: Compiling Resources. - * Resources, building: Building Resources. - * Resources, compiling: Compiling Resources. - * Resources, limitations: Limitations. - * Resources, using: Using Resources. - * Resources, windows: GNAT and Windows Resources. - * Rounding, biased: Output and Error Message Control. - * RTL: Switches for gcc. - * SDP_Table_Build: Running gnatbind. - * Search paths, for gnatmake: Switches for gnatmake. - * Setup Tool: GNAT Setup Tool. - * Shift JIS Coding: Wide Character Encodings. - * Source file, end: Source Representation. - * Source files, suppressing search: Switches for gnatmake. - * Source files, use by binder: Running gnatbind. - * Source_File_Name pragma <1>: Alternative File Naming Schemes. - * Source_File_Name pragma: Using Other File Names. - * Source_Reference: Switches for gnatchop. - * Stack Overflow Checking: Stack Overflow Checking. - * stack traceback: Stack Traceback. - * stack unwinding: Stack Traceback. - * Stdcall <1>: Windows Calling Conventions. - * Stdcall: Calling Conventions. - * stderr: Output and Error Message Control. - * stdout: Output and Error Message Control. - * storage, pool, memory corruption: Finding Memory Problems with GNAT Debug Pool. - * Stubbed: Calling Conventions. - * Style checking: Style Checking. - * SUB: Source Representation. - * Subunits: Generating Object Files. - * Suppress <1>: Controlling Run-Time Checks. - * Suppress: Run-Time Checks. - * Suppressing checks: Run-Time Checks. - * System <1>: Naming Conventions for GNAT Source Files. - * System: Search Paths for gnatbind. - * System.IO: Search Paths and the Run-Time Library (RTL). - * Task switching: Ada Tasks. - * Tasks: Ada Tasks. - * Temporary files: Temporary Files. - * Time Slicing: Run-Time Control. - * Time stamp checks, in binder: Binder Error Message Control. - * traceback: Stack Traceback. - * traceback, non-symbolic: Non-Symbolic Traceback. - * traceback, symbolic: Symbolic Traceback. - * Tree file: Tree Files. - * Typographical conventions: Conventions. - * Unsuppress <1>: Controlling Run-Time Checks. - * Unsuppress: Run-Time Checks. - * Upper-Half Coding: Wide Character Encodings. - * Validity Checking: Validity Checking. - * Version skew (avoided by gnatmake): Running a Simple Ada Program. - * Volatile parameter: The Volatile Parameter. - * VT: Source Representation. - * Warning messages: Output and Error Message Control. - * Warnings: Binder Error Message Control. - * Warnings, treat as error: Output and Error Message Control. - * Win32: Calling Conventions. - * Windows 95: Microsoft Windows Topics. - * Windows 98: Microsoft Windows Topics. - * Windows NT: Microsoft Windows Topics. - * WINDOWS Subsystem: CONSOLE and WINDOWS subsystems. - * Writing internal trees: Auxiliary Output Control. - * Zero Cost Exceptions: Running gnatbind. - - -  - Tag Table: - Node: Top91 - Node: About This Guide9257 - Node: What This Guide Contains9766 - Node: What You Should Know before Reading This Guide14111 - Node: Related Information14519 - Node: Conventions15242 - Node: Getting Started with GNAT16136 - Node: Running GNAT16577 - Node: Running a Simple Ada Program17179 - Node: Running a Program with Multiple Units20533 - Node: Using the gnatmake Utility22764 - Node: Introduction to Glide and GVD25164 - Node: Building a New Program with Glide25906 - Node: Simple Debugging with GVD31244 - Node: Other Glide Features34281 - Node: The GNAT Compilation Model36164 - Node: Source Representation37494 - Node: Foreign Language Representation39280 - Node: Latin-139766 - Node: Other 8-Bit Codes40632 - Node: Wide Character Encodings42725 - Node: File Naming Rules46531 - Node: Using Other File Names48820 - Node: Alternative File Naming Schemes51173 - Node: Generating Object Files56405 - Node: Source Dependencies59119 - Node: The Ada Library Information Files62642 - Node: Binding an Ada Program64775 - Node: Mixed Language Programming66623 - Node: Interfacing to C66900 - Node: Calling Conventions69406 - Node: Building Mixed Ada & C++ Programs75330 - Node: Interfacing to C++76411 - Node: Linking a Mixed C++ & Ada Program77451 - Node: A Simple Example80485 - Node: Adapting the Run Time to a New C++ Compiler83397 - Node: Comparison between GNAT and C/C++ Compilation Models84413 - Node: Comparison between GNAT and Conventional Ada Library Models86142 - Node: Compiling Using gcc88793 - Node: Compiling Programs89288 - Node: Switches for gcc92238 - Node: Output and Error Message Control101422 - Node: Debugging and Assertion Control119508 - Node: Validity Checking120838 - Node: Style Checking126985 - Node: Run-Time Checks138458 - Node: Stack Overflow Checking142442 - Node: Run-Time Control144529 - Node: Using gcc for Syntax Checking145423 - Node: Using gcc for Semantic Checking146922 - Node: Compiling Ada 83 Programs148400 - Node: Character Set Control149821 - Node: File Naming Control152748 - Node: Subprogram Inlining Control153256 - Node: Auxiliary Output Control154597 - Node: Debugging Control156028 - Node: Units to Sources Mapping Files163468 - Node: Search Paths and the Run-Time Library (RTL)164858 - Node: Order of Compilation Issues168029 - Node: Examples169730 - Node: Binding Using gnatbind170298 - Node: Running gnatbind172160 - Node: Generating the Binder Program in C202921 - Node: Consistency-Checking Modes220366 - Node: Binder Error Message Control221861 - Node: Elaboration Control224127 - Node: Output Control225352 - Node: Binding with Non-Ada Main Programs227793 - Node: Binding Programs with No Main Subprogram230933 - Node: Summary of Binder Switches231756 - Node: Command-Line Access235205 - Node: Search Paths for gnatbind236210 - Node: Examples of gnatbind Usage238776 - Node: Linking Using gnatlink240547 - Node: Running gnatlink241286 - Node: Switches for gnatlink243271 - Node: Setting Stack Size from gnatlink247544 - Node: Setting Heap Size from gnatlink248398 - Node: The GNAT Make Program gnatmake249213 - Node: Running gnatmake250664 - Node: Switches for gnatmake252323 - Node: Mode Switches for gnatmake265413 - Node: Notes on the Command Line266571 - Node: How gnatmake Works269467 - Node: Examples of gnatmake Usage271637 - Node: Renaming Files Using gnatchop272764 - Node: Handling Files with Multiple Units273353 - Node: Operating gnatchop in Compilation Mode274674 - Node: Command Line for gnatchop277997 - Node: Switches for gnatchop279462 - Node: Examples of gnatchop Usage283243 - Node: Configuration Pragmas284602 - Node: Handling of Configuration Pragmas286154 - Node: The Configuration Pragmas Files287013 - Node: Handling Arbitrary File Naming Conventions Using gnatname288376 - Node: Arbitrary File Naming Conventions288784 - Node: Running gnatname290045 - Node: Switches for gnatname291504 - Node: Examples of gnatname Usage294638 - Node: GNAT Project Manager295439 - Node: Introduction296101 - Node: Project Files297197 - Node: Examples of Project Files300400 - Node: Common Sources with Different Switches and Different Output Directories300874 - Node: Source Files303905 - Node: Specifying the Object Directory304381 - Node: Specifying the Exec Directory305313 - Node: Project File Packages306081 - Node: Specifying Switch Settings307090 - Node: Main Subprograms309058 - Node: Source File Naming Conventions309722 - Node: Source Language(s)310222 - Node: Using External Variables310663 - Node: Importing Other Projects313504 - Node: Extending a Project316612 - Node: Project File Syntax319083 - Node: Basic Syntax320445 - Node: Packages321453 - Node: Expressions322607 - Node: String Types324505 - Node: Variables325808 - Node: Attributes328836 - Node: Associative Array Attributes334269 - Node: case Constructions335114 - Node: Objects and Sources in Project Files336911 - Node: Object Directory337491 - Node: Exec Directory338482 - Node: Source Directories339311 - Node: Source File Names340678 - Node: Importing Projects343015 - Node: Project Extension345794 - Node: External References in Project Files347473 - Node: Packages in Project Files349216 - Node: Variables from Imported Projects351612 - Node: Naming Schemes353284 - Node: Library Projects357257 - Node: Switches Related to Project Files360151 - Node: Tools Supporting Project Files361855 - Node: gnatmake and Project Files362187 - Node: Switches and Project Files362640 - Node: Project Files and Main Subprograms368384 - Node: The GNAT Driver and Project Files370309 - Node: Glide and Project Files373977 - Node: An Extended Example374616 - Node: Project File Complete Syntax377611 - Node: Elaboration Order Handling in GNAT380403 - Node: Elaboration Code in Ada 95381423 - Node: Checking the Elaboration Order in Ada 95386069 - Node: Controlling the Elaboration Order in Ada 95390070 - Node: Controlling Elaboration in GNAT - Internal Calls398387 - Node: Controlling Elaboration in GNAT - External Calls404094 - Node: Default Behavior in GNAT - Ensuring Safety407828 - Node: Elaboration Issues for Library Tasks411911 - Node: Mixing Elaboration Models425116 - Node: What to Do If the Default Elaboration Behavior Fails427617 - Node: Elaboration for Access-to-Subprogram Values437932 - Node: Summary of Procedures for Elaboration Control439739 - Node: Other Elaboration Order Considerations440902 - Node: The Cross-Referencing Tools gnatxref and gnatfind446131 - Node: gnatxref Switches447795 - Node: gnatfind Switches451234 - Node: Project Files for gnatxref and gnatfind456830 - Node: Regular Expressions in gnatfind and gnatxref459936 - Node: Examples of gnatxref Usage462715 - Node: Examples of gnatfind Usage466514 - Node: File Name Krunching Using gnatkr468717 - Node: About gnatkr469331 - Node: Using gnatkr470653 - Node: Krunching Method471544 - Node: Examples of gnatkr Usage474781 - Node: Preprocessing Using gnatprep475271 - Node: Using gnatprep475782 - Node: Switches for gnatprep476634 - Node: Form of Definitions File478756 - Node: Form of Input Text for gnatprep479495 - Node: The GNAT Library Browser gnatls483114 - Node: Running gnatls483643 - Node: Switches for gnatls486153 - Node: Examples of gnatls Usage488048 - Node: GNAT and Libraries490237 - Node: Creating an Ada Library490765 - Node: Installing an Ada Library493605 - Node: Using an Ada Library495962 - Node: Creating an Ada Library to be Used in a Non-Ada Context497153 - Node: Rebuilding the GNAT Run-Time Library503121 - Node: Using the GNU make Utility504028 - Node: Using gnatmake in a Makefile504874 - Node: Automatically Creating a List of Directories509082 - Node: Generating the Command Line Switches512220 - Node: Overcoming Command Line Length Limits513198 - Node: Finding Memory Problems with gnatmem515503 - Node: Running gnatmem (GDB Mode)516854 - Node: Running gnatmem (GMEM Mode)519291 - Node: Switches for gnatmem520549 - Node: Examples of gnatmem Usage521657 - Node: GDB and GMEM Modes526881 - Node: Implementation Note527522 - Node: gnatmem Using GDB Mode527752 - Node: gnatmem Using GMEM Mode529165 - Node: Finding Memory Problems with GNAT Debug Pool529811 - Node: Creating Sample Bodies Using gnatstub534515 - Node: Running gnatstub535310 - Node: Switches for gnatstub536064 - Node: Reducing the Size of Ada Executables with gnatelim538196 - Node: About gnatelim538729 - Node: Eliminate Pragma539817 - Node: Tree Files540825 - Node: Preparing Tree and Bind Files for gnatelim541714 - Node: Running gnatelim543716 - Node: Correcting the List of Eliminate Pragmas545711 - Node: Making Your Executables Smaller546492 - Node: Summary of the gnatelim Usage Cycle547314 - Node: Other Utility Programs548123 - Node: Using Other Utility Programs with GNAT548651 - Node: The gnatpsta Utility Program549339 - Node: The External Symbol Naming Scheme of GNAT550633 - Node: Ada Mode for Glide552630 - Node: Converting Ada Files to html with gnathtml554581 - Node: Installing gnathtml558154 - Node: Running and Debugging Ada Programs558818 - Node: The GNAT Debugger GDB560212 - Node: Running GDB563330 - Node: Introduction to GDB Commands564346 - Node: Using Ada Expressions569211 - Node: Calling User-Defined Subprograms570405 - Node: Using the Next Command in a Function572825 - Node: Ada Exceptions573990 - Node: Ada Tasks574944 - Node: Debugging Generic Units577007 - Node: GNAT Abnormal Termination or Failure to Terminate578410 - Node: Naming Conventions for GNAT Source Files580989 - Node: Getting Internal Debugging Information583580 - Node: Stack Traceback584782 - Node: Non-Symbolic Traceback585819 - Node: Tracebacks From an Unhandled Exception586280 - Node: Tracebacks From Exception Occurrences (non-symbolic)590356 - Node: Tracebacks From Anywhere in a Program (non-symbolic)591639 - Node: Symbolic Traceback593482 - Node: Tracebacks From Exception Occurrences (symbolic)594205 - Node: Tracebacks From Anywhere in a Program (symbolic)595614 - Node: Inline Assembler596806 - Node: Basic Assembler Syntax598502 - Node: A Simple Example of Inline Assembler600279 - Node: Output Variables in Inline Assembler603446 - Node: Input Variables in Inline Assembler610826 - Node: Inlining Inline Assembler Code613334 - Node: Other Asm Functionality615268 - Node: The Clobber Parameter615703 - Node: The Volatile Parameter617702 - Node: A Complete Example618894 - Node: Check_CPU Procedure619868 - Node: Intel_CPU Package Specification634915 - Node: Intel_CPU Package Body644343 - Node: Microsoft Windows Topics653501 - Node: Using GNAT on Windows654151 - Node: GNAT Setup Tool655922 - Node: Command-line arguments656640 - Node: Creating a network installation of GNAT657137 - Node: Registering and unregistering additional libraries658123 - Node: CONSOLE and WINDOWS subsystems658813 - Node: Temporary Files659437 - Node: Mixed-Language Programming on Windows660241 - Node: Windows Calling Conventions662382 - Node: C Calling Convention663235 - Node: Stdcall Calling Convention664761 - Node: DLL Calling Convention667315 - Node: Introduction to Dynamic Link Libraries (DLLs)668047 - Node: Using DLLs with GNAT671252 - Node: Creating an Ada Spec for the DLL Services673051 - Node: Creating an Import Library674307 - Node: The Definition File674762 - Node: GNAT-Style Import Library676106 - Node: Microsoft-Style Import Library678220 - Node: Building DLLs with GNAT679360 - Node: Limitations When Using Ada DLLs from Ada681448 - Node: Exporting Ada Entities682476 - Node: Ada DLLs and Elaboration685327 - Node: Ada DLLs and Finalization686848 - Node: Creating a Spec for Ada DLLs687920 - Node: Creating the Definition File689325 - Node: Using gnatdll690150 - Node: gnatdll Example693177 - Node: gnatdll behind the Scenes693762 - Node: Using dlltool696238 - Node: GNAT and Windows Resources697560 - Node: Building Resources698174 - Node: Compiling Resources698833 - Node: Using Resources699811 - Node: Limitations700205 - Node: Debugging a DLL701141 - Node: The Program and the DLL Are Built with GCC/GNAT702173 - Node: The Program Is Built with Some Foreign Tools and the DLL Is Built with GCC/GNAT703676 - Node: Debugging the DLL Directly704936 - Node: Attaching to a Running Process705742 - Node: GNAT and COM/DCOM Objects707045 - Node: Performance Considerations707254 - Node: Controlling Run-Time Checks708296 - Node: Optimization Levels710281 - Node: Debugging Optimized Code712138 - Node: Inlining of Subprograms715871 - Node: GNU Free Documentation License719395 - Node: Index741824 -  - End Tag Table --- 0 ----