| \input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename gnat_ugn.info |
| @documentencoding UTF-8 |
| @ifinfo |
| @*Generated by Sphinx 1.3b2.@* |
| @end ifinfo |
| @settitle GNAT User's Guide for Native Platforms |
| @defindex ge |
| @paragraphindent 0 |
| @exampleindent 4 |
| @finalout |
| @dircategory GNU Ada Tools |
| @direntry |
| * gnat_ugn: (gnat_ugn.info). gnat_ugn |
| @end direntry |
| |
| @definfoenclose strong,`,' |
| @definfoenclose emph,`,' |
| @c %**end of header |
| |
| @copying |
| @quotation |
| GNAT User's Guide for Native Platforms , November 18, 2015 |
| |
| AdaCore |
| |
| Copyright @copyright{} 2008-2016, Free Software Foundation |
| @end quotation |
| |
| @end copying |
| |
| @titlepage |
| @title GNAT User's Guide for Native Platforms |
| @insertcopying |
| @end titlepage |
| @contents |
| |
| @c %** start of user preamble |
| |
| @c %** end of user preamble |
| |
| @ifnottex |
| @node Top |
| @top GNAT User's Guide for Native Platforms |
| @insertcopying |
| @end ifnottex |
| |
| @c %**start of body |
| @anchor{gnat_ugn doc}@anchor{0} |
| @emph{GNAT, The GNU Ada Development Environment} |
| |
| |
| @include gcc-common.texi |
| GCC version @value{version-GCC}@* |
| AdaCore |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with no |
| Invariant Sections, with the Front-Cover Texts being |
| "GNAT User's Guide for Native Platforms", |
| and with no Back-Cover Texts. A copy of the license is |
| included in the section entitled @ref{1,,GNU Free Documentation License}. |
| |
| @menu |
| * About This Guide:: |
| * Getting Started with GNAT:: |
| * The GNAT Compilation Model:: |
| * Building Executable Programs with GNAT:: |
| * GNAT Project Manager:: |
| * Tools Supporting Project Files:: |
| * GNAT Utility Programs:: |
| * GNAT and Program Execution:: |
| * Platform-Specific Information:: |
| * Example of Binder Output File:: |
| * Elaboration Order Handling in GNAT:: |
| * Inline Assembler:: |
| * GNU Free Documentation License:: |
| * Index:: |
| |
| @detailmenu |
| --- The Detailed Node Listing --- |
| |
| About This Guide |
| |
| * What This Guide Contains:: |
| * What You Should Know before Reading This Guide:: |
| * Related Information:: |
| * A Note to Readers of Previous Versions of the Manual:: |
| * 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 Topics and Utilities:: |
| * Configuration Pragmas:: |
| * Generating Object Files:: |
| * Source Dependencies:: |
| * The Ada Library Information Files:: |
| * Binding an Ada Program:: |
| * GNAT and Libraries:: |
| * Conditional Compilation:: |
| * Mixed Language Programming:: |
| * GNAT and Other Compilation Models:: |
| * Using GNAT Files with External Tools:: |
| |
| Foreign Language Representation |
| |
| * Latin-1:: |
| * Other 8-Bit Codes:: |
| * Wide_Character Encodings:: |
| * Wide_Wide_Character Encodings:: |
| |
| File Naming Topics and Utilities |
| |
| * File Naming Rules:: |
| * Using Other File Names:: |
| * Alternative File Naming Schemes:: |
| * Handling Arbitrary File Naming Conventions with gnatname:: |
| * File Name Krunching with gnatkr:: |
| * Renaming Files with gnatchop:: |
| |
| Handling Arbitrary File Naming Conventions with gnatname |
| |
| * Arbitrary File Naming Conventions:: |
| * Running gnatname:: |
| * Switches for gnatname:: |
| * Examples of gnatname Usage:: |
| |
| File Name Krunching with gnatkr |
| |
| * About gnatkr:: |
| * Using gnatkr:: |
| * Krunching Method:: |
| * Examples of gnatkr Usage:: |
| |
| Renaming Files with 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:: |
| |
| GNAT and Libraries |
| |
| * Introduction to Libraries in GNAT:: |
| * General Ada Libraries:: |
| * Stand-alone Ada Libraries:: |
| * Rebuilding the GNAT Run-Time Library:: |
| |
| General Ada Libraries |
| |
| * Building a library:: |
| * Installing a library:: |
| * Using a library:: |
| |
| Stand-alone Ada Libraries |
| |
| * Introduction to Stand-alone Libraries:: |
| * Building a Stand-alone Library:: |
| * Creating a Stand-alone Library to be used in a non-Ada context:: |
| * Restrictions in Stand-alone Libraries:: |
| |
| Conditional Compilation |
| |
| * Modeling Conditional Compilation in Ada:: |
| * Preprocessing with gnatprep:: |
| * Integrated Preprocessing:: |
| |
| Modeling Conditional Compilation in Ada |
| |
| * Use of Boolean Constants:: |
| * Debugging - A Special Case:: |
| * Conditionalizing Declarations:: |
| * Use of Alternative Implementations:: |
| * Preprocessing:: |
| |
| Preprocessing with gnatprep |
| |
| * Preprocessing Symbols:: |
| * Using gnatprep:: |
| * Switches for gnatprep:: |
| * Form of Definitions File:: |
| * Form of Input Text for gnatprep:: |
| |
| Mixed Language Programming |
| |
| * Interfacing to C:: |
| * Calling Conventions:: |
| * Building Mixed Ada and C++ Programs:: |
| * Generating Ada Bindings for C and C++ headers:: |
| * Generating C Headers for Ada Specifications:: |
| |
| Building Mixed Ada and C++ Programs |
| |
| * Interfacing to C++:: |
| * Linking a Mixed C++ & Ada Program:: |
| * A Simple Example:: |
| * Interfacing with C++ constructors:: |
| * Interfacing with C++ at the Class Level:: |
| |
| Generating Ada Bindings for C and C++ headers |
| |
| * Running the Binding Generator:: |
| * Generating Bindings for C++ Headers:: |
| * Switches:: |
| |
| Generating C Headers for Ada Specifications |
| |
| * Running the C Header Generator:: |
| |
| GNAT and Other Compilation Models |
| |
| * Comparison between GNAT and C/C++ Compilation Models:: |
| * Comparison between GNAT and Conventional Ada Library Models:: |
| |
| Using GNAT Files with External Tools |
| |
| * Using Other Utility Programs with GNAT:: |
| * The External Symbol Naming Scheme of GNAT:: |
| |
| Building Executable Programs with GNAT |
| |
| * Building with gnatmake:: |
| * Compiling with gcc:: |
| * Compiler Switches:: |
| * Binding with gnatbind:: |
| * Linking with gnatlink:: |
| * Using the GNU make Utility:: |
| |
| Building with gnatmake |
| |
| * Running gnatmake:: |
| * Switches for gnatmake:: |
| * Mode Switches for gnatmake:: |
| * Notes on the Command Line:: |
| * How gnatmake Works:: |
| * Examples of gnatmake Usage:: |
| |
| Compiling with gcc |
| |
| * Compiling Programs:: |
| * Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL. |
| * Order of Compilation Issues:: |
| * Examples:: |
| |
| Compiler Switches |
| |
| * Alphabetical List of All Switches:: |
| * Output and Error Message Control:: |
| * Warning Message Control:: |
| * Debugging and Assertion Control:: |
| * Validity Checking:: |
| * Style Checking:: |
| * Run-Time Checks:: |
| * Using gcc for Syntax Checking:: |
| * Using gcc for Semantic Checking:: |
| * Compiling Different Versions of Ada:: |
| * Character Set Control:: |
| * File Naming Control:: |
| * Subprogram Inlining Control:: |
| * Auxiliary Output Control:: |
| * Debugging Control:: |
| * Exception Handling Control:: |
| * Units to Sources Mapping Files:: |
| * Code Generation Control:: |
| |
| Binding with gnatbind |
| |
| * Running gnatbind:: |
| * Switches for gnatbind:: |
| * Command-Line Access:: |
| * Search Paths for gnatbind:: |
| * Examples of gnatbind Usage:: |
| |
| Switches for gnatbind |
| |
| * Consistency-Checking Modes:: |
| * Binder Error Message Control:: |
| * Elaboration Control:: |
| * Output Control:: |
| * Dynamic Allocation Control:: |
| * Binding with Non-Ada Main Programs:: |
| * Binding Programs with No Main Subprogram:: |
| |
| Linking with gnatlink |
| |
| * Running gnatlink:: |
| * Switches for gnatlink:: |
| |
| 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:: |
| |
| GNAT Project Manager |
| |
| * Introduction:: |
| * Building With Projects:: |
| * Organizing Projects into Subsystems:: |
| * Scenarios in Projects:: |
| * Library Projects:: |
| * Project Extension:: |
| * Aggregate Projects:: |
| * Aggregate Library Projects:: |
| * Project File Reference:: |
| |
| Building With Projects |
| |
| * Source Files and Directories:: |
| * Duplicate Sources in Projects:: |
| * Object and Exec Directory:: |
| * Main Subprograms:: |
| * Tools Options in Project Files:: |
| * Compiling with Project Files:: |
| * Executable File Names:: |
| * Avoid Duplication With Variables:: |
| * Naming Schemes:: |
| * Installation:: |
| * Distributed support:: |
| |
| Organizing Projects into Subsystems |
| |
| * Project Dependencies:: |
| * Cyclic Project Dependencies:: |
| * Sharing Between Projects:: |
| * Global Attributes:: |
| |
| Library Projects |
| |
| * Building Libraries:: |
| * Using Library Projects:: |
| * Stand-alone Library Projects:: |
| * Installing a library with project files:: |
| |
| Project Extension |
| |
| * Project Hierarchy Extension:: |
| |
| Aggregate Projects |
| |
| * Building all main programs from a single project tree:: |
| * Building a set of projects with a single command:: |
| * Define a build environment:: |
| * Performance improvements in builder:: |
| * Syntax of aggregate projects:: |
| * package Builder in aggregate projects:: |
| |
| Aggregate Library Projects |
| |
| * Building aggregate library projects:: |
| * Syntax of aggregate library projects:: |
| |
| Project File Reference |
| |
| * Project Declaration:: |
| * Qualified Projects:: |
| * Declarations:: |
| * Packages:: |
| * Expressions:: |
| * External Values:: |
| * Typed String Declaration:: |
| * Variables:: |
| * Case Constructions:: |
| * Attributes:: |
| |
| Attributes |
| |
| * Project Level Attributes:: |
| * Package Binder Attributes:: |
| * Package Builder Attributes:: |
| * Package Clean Attributes:: |
| * Package Compiler Attributes:: |
| * Package Cross_Reference Attributes:: |
| * Package Finder Attributes:: |
| * Package gnatls Attributes:: |
| * Package IDE Attributes:: |
| * Package Install Attributes:: |
| * Package Linker Attributes:: |
| * Package Naming Attributes:: |
| * Package Remote Attributes:: |
| * Package Stack Attributes:: |
| * Package Synchronize Attributes:: |
| |
| Tools Supporting Project Files |
| |
| * gnatmake and Project Files:: |
| * The GNAT Driver and Project Files:: |
| |
| gnatmake and Project Files |
| |
| * Switches Related to Project Files:: |
| * Switches and Project Files:: |
| * Specifying Configuration Pragmas:: |
| * Project Files and Main Subprograms:: |
| * Library Project Files:: |
| |
| GNAT Utility Programs |
| |
| * The File Cleanup Utility gnatclean:: |
| * The GNAT Library Browser gnatls:: |
| * The Cross-Referencing Tools gnatxref and gnatfind:: |
| * The Ada to HTML Converter gnathtml:: |
| |
| The File Cleanup Utility gnatclean |
| |
| * Running gnatclean:: |
| * Switches for gnatclean:: |
| |
| The GNAT Library Browser gnatls |
| |
| * Running gnatls:: |
| * Switches for gnatls:: |
| * Example of gnatls Usage:: |
| |
| 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:: |
| |
| Examples of gnatxref Usage |
| |
| * General Usage:: |
| * Using gnatxref with vi:: |
| |
| The Ada to HTML Converter gnathtml |
| |
| * Invoking gnathtml:: |
| * Installing gnathtml:: |
| |
| GNAT and Program Execution |
| |
| * Running and Debugging Ada Programs:: |
| * Code Coverage and Profiling:: |
| * Improving Performance:: |
| * Overflow Check Handling in GNAT:: |
| * Performing Dimensionality Analysis in GNAT:: |
| * Stack Related Facilities:: |
| * Memory Management Issues:: |
| |
| 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:: |
| * Stopping When Ada Exceptions Are Raised:: |
| * Ada Tasks:: |
| * Debugging Generic Units:: |
| * Remote Debugging with gdbserver:: |
| * GNAT Abnormal Termination or Failure to Terminate:: |
| * Naming Conventions for GNAT Source Files:: |
| * Getting Internal Debugging Information:: |
| * Stack Traceback:: |
| |
| Stack Traceback |
| |
| * Non-Symbolic Traceback:: |
| * Symbolic Traceback:: |
| |
| Code Coverage and Profiling |
| |
| * Code Coverage of Ada Programs with gcov:: |
| * Profiling an Ada Program with gprof:: |
| |
| Code Coverage of Ada Programs with gcov |
| |
| * Quick startup guide:: |
| * GNAT specifics:: |
| |
| Profiling an Ada Program with gprof |
| |
| * Compilation for profiling:: |
| * Program execution:: |
| * Running gprof:: |
| * Interpretation of profiling results:: |
| |
| Improving Performance |
| |
| * Performance Considerations:: |
| * Text_IO Suggestions:: |
| * Reducing Size of Executables with Unused Subprogram/Data Elimination:: |
| |
| Performance Considerations |
| |
| * Controlling Run-Time Checks:: |
| * Use of Restrictions:: |
| * Optimization Levels:: |
| * Debugging Optimized Code:: |
| * Inlining of Subprograms:: |
| * Floating_Point_Operations:: |
| * Vectorization of loops:: |
| * Other Optimization Switches:: |
| * Optimization and Strict Aliasing:: |
| * Aliased Variables and Optimization:: |
| * Atomic Variables and Optimization:: |
| * Passive Task Optimization:: |
| |
| Reducing Size of Executables with Unused Subprogram/Data Elimination |
| |
| * About unused subprogram/data elimination:: |
| * Compilation options:: |
| * Example of unused subprogram/data elimination:: |
| |
| Overflow Check Handling in GNAT |
| |
| * Background:: |
| * Management of Overflows in GNAT:: |
| * Specifying the Desired Mode:: |
| * Default Settings:: |
| * Implementation Notes:: |
| |
| Stack Related Facilities |
| |
| * Stack Overflow Checking:: |
| * Static Stack Usage Analysis:: |
| * Dynamic Stack Usage Analysis:: |
| |
| Memory Management Issues |
| |
| * Some Useful Memory Pools:: |
| * The GNAT Debug Pool Facility:: |
| |
| Platform-Specific Information |
| |
| * Run-Time Libraries:: |
| * Specifying a Run-Time Library:: |
| * Microsoft Windows Topics:: |
| * Mac OS Topics:: |
| |
| Run-Time Libraries |
| |
| * Summary of Run-Time Configurations:: |
| |
| Specifying a Run-Time Library |
| |
| * Choosing the Scheduling Policy:: |
| * Solaris-Specific Considerations:: |
| * Solaris Threads Issues:: |
| * AIX-Specific Considerations:: |
| |
| Microsoft Windows Topics |
| |
| * Using GNAT on Windows:: |
| * Using a network installation of GNAT:: |
| * CONSOLE and WINDOWS subsystems:: |
| * Temporary Files:: |
| * Mixed-Language Programming on Windows:: |
| * Windows Specific Add-Ons:: |
| |
| Mixed-Language Programming on Windows |
| |
| * Windows Calling Conventions:: |
| * Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs. |
| * Using DLLs with GNAT:: |
| * Building DLLs with GNAT Project files:: |
| * Building DLLs with GNAT:: |
| * Building DLLs with gnatdll:: |
| * Ada DLLs and Finalization:: |
| * Creating a Spec for Ada DLLs:: |
| * GNAT and Windows Resources:: |
| * Using GNAT DLLs from Microsoft Visual Studio Applications:: |
| * Debugging a DLL:: |
| * Setting Stack Size from gnatlink:: |
| * Setting Heap Size from gnatlink:: |
| |
| Windows Calling Conventions |
| |
| * C Calling Convention:: |
| * Stdcall Calling Convention:: |
| * Win32 Calling Convention:: |
| * DLL Calling Convention:: |
| |
| Using DLLs with GNAT |
| |
| * Creating an Ada Spec for the DLL Services:: |
| * Creating an Import Library:: |
| |
| Building DLLs with gnatdll |
| |
| * Limitations When Using Ada DLLs from Ada:: |
| * Exporting Ada Entities:: |
| * Ada DLLs and Elaboration:: |
| |
| Creating a Spec for Ada DLLs |
| |
| * Creating the Definition File:: |
| * Using gnatdll:: |
| |
| GNAT and Windows Resources |
| |
| * Building Resources:: |
| * Compiling Resources:: |
| * Using Resources:: |
| |
| Debugging a DLL |
| |
| * Program and DLL Both Built with GCC/GNAT:: |
| * Program Built with Foreign Tools and DLL Built with GCC/GNAT:: |
| |
| Windows Specific Add-Ons |
| |
| * Win32Ada:: |
| * wPOSIX:: |
| |
| Mac OS Topics |
| |
| * Codesigning the Debugger:: |
| |
| Elaboration Order Handling in GNAT |
| |
| * Elaboration Code:: |
| * Checking the Elaboration Order:: |
| * Controlling the Elaboration Order:: |
| * Controlling Elaboration in GNAT - Internal Calls:: |
| * Controlling Elaboration in GNAT - External Calls:: |
| * Default Behavior in GNAT - Ensuring Safety:: |
| * Treatment of Pragma Elaborate:: |
| * Elaboration Issues for Library Tasks:: |
| * Mixing Elaboration Models:: |
| * What to Do If the Default Elaboration Behavior Fails:: |
| * Elaboration for Indirect Calls:: |
| * Summary of Procedures for Elaboration Control:: |
| * Other Elaboration Order Considerations:: |
| * Determining the Chosen Elaboration Order:: |
| |
| 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:: |
| |
| Other Asm Functionality |
| |
| * The Clobber Parameter:: |
| * The Volatile Parameter:: |
| |
| @end detailmenu |
| @end menu |
| |
| @node About This Guide,Getting Started with GNAT,Top,Top |
| @anchor{gnat_ugn/about_this_guide about-this-guide}@anchor{2}@anchor{gnat_ugn/about_this_guide doc}@anchor{3}@anchor{gnat_ugn/about_this_guide gnat-user-s-guide-for-native-platforms}@anchor{4}@anchor{gnat_ugn/about_this_guide id1}@anchor{5} |
| @chapter About This Guide |
| |
| |
| |
| This guide describes the use of GNAT, |
| a compiler and software development |
| toolset for the full Ada programming language. |
| It documents the features of the compiler and tools, and explains |
| how to use them to build Ada applications. |
| |
| GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be |
| invoked in Ada 83 compatibility mode. |
| By default, GNAT assumes Ada 2012, but you can override with a |
| compiler switch (@ref{6,,Compiling Different Versions of Ada}) |
| to explicitly specify the language version. |
| Throughout this manual, references to 'Ada' without a year suffix |
| apply to all Ada 95/2005/2012 versions of the language. |
| |
| @menu |
| * What This Guide Contains:: |
| * What You Should Know before Reading This Guide:: |
| * Related Information:: |
| * A Note to Readers of Previous Versions of the Manual:: |
| * Conventions:: |
| |
| @end menu |
| |
| @node What This Guide Contains,What You Should Know before Reading This Guide,,About This Guide |
| @anchor{gnat_ugn/about_this_guide what-this-guide-contains}@anchor{7} |
| @section What This Guide Contains |
| |
| |
| This guide contains the following chapters: |
| |
| |
| @itemize * |
| |
| @item |
| @ref{8,,Getting Started with GNAT} describes how to get started compiling |
| and running Ada programs with the GNAT Ada programming environment. |
| |
| @item |
| @ref{9,,The GNAT Compilation Model} describes the compilation model used |
| by GNAT. |
| |
| @item |
| @ref{a,,Building Executable Programs with GNAT} describes how to use the |
| main GNAT tools to build executable programs, and it also gives examples of |
| using the GNU make utility with GNAT. |
| |
| @item |
| @ref{b,,GNAT Project Manager} describes how to use project files |
| to organize large projects. |
| |
| @item |
| @ref{c,,Tools Supporting Project Files} described how to use the project |
| facility in conjunction with various GNAT tools. |
| |
| @item |
| @ref{d,,GNAT Utility Programs} explains the various utility programs that |
| are included in the GNAT environment |
| |
| @item |
| @ref{e,,GNAT and Program Execution} covers a number of topics related to |
| running, debugging, and tuning the performace of programs developed |
| with GNAT |
| @end itemize |
| |
| Appendices cover several additional topics: |
| |
| |
| @itemize * |
| |
| @item |
| @ref{f,,Platform-Specific Information} describes the different run-time |
| library implementations and also presents information on how to use |
| GNAT on several specific platforms |
| |
| @item |
| @ref{10,,Example of Binder Output File} shows the source code for the binder |
| output file for a sample program. |
| |
| @item |
| @ref{11,,Elaboration Order Handling in GNAT} describes how GNAT helps |
| you deal with elaboration order issues. |
| |
| @item |
| @ref{12,,Inline Assembler} shows how to use the inline assembly facility |
| in an Ada program. |
| @end itemize |
| |
| @node What You Should Know before Reading This Guide,Related Information,What This Guide Contains,About This Guide |
| @anchor{gnat_ugn/about_this_guide what-you-should-know-before-reading-this-guide}@anchor{13} |
| @section What You Should Know before Reading This Guide |
| |
| |
| @geindex Ada 95 Language Reference Manual |
| |
| @geindex Ada 2005 Language Reference Manual |
| |
| This guide assumes a basic familiarity with the Ada 95 language, as |
| described in the International Standard ANSI/ISO/IEC-8652:1995, January |
| 1995. |
| It does not require knowledge of the features introduced by Ada 2005 |
| or Ada 2012. |
| Reference manuals for Ada 95, Ada 2005, and Ada 2012 are included in |
| the GNAT documentation package. |
| |
| @node Related Information,A Note to Readers of Previous Versions of the Manual,What You Should Know before Reading This Guide,About This Guide |
| @anchor{gnat_ugn/about_this_guide related-information}@anchor{14} |
| @section Related Information |
| |
| |
| For further information about Ada and related tools, please refer to the |
| following documents: |
| |
| |
| @itemize * |
| |
| @item |
| @cite{Ada 95 Reference Manual}, @cite{Ada 2005 Reference Manual}, and |
| @cite{Ada 2012 Reference Manual}, which contain reference |
| material for the several revisions of the Ada language standard. |
| |
| @item |
| @cite{GNAT Reference_Manual}, which contains all reference material for the GNAT |
| implementation of Ada. |
| |
| @item |
| @cite{Using the GNAT Programming Studio}, which describes the GPS |
| Integrated Development Environment. |
| |
| @item |
| @cite{GNAT Programming Studio Tutorial}, which introduces the |
| main GPS features through examples. |
| |
| @item |
| @cite{Debugging with GDB}, |
| for all details on the use of the GNU source-level debugger. |
| |
| @item |
| @cite{GNU Emacs Manual}, |
| for full information on the extensible editor and programming |
| environment Emacs. |
| @end itemize |
| |
| @node A Note to Readers of Previous Versions of the Manual,Conventions,Related Information,About This Guide |
| @anchor{gnat_ugn/about_this_guide a-note-to-readers-of-previous-versions-of-the-manual}@anchor{15} |
| @section A Note to Readers of Previous Versions of the Manual |
| |
| |
| In early 2015 the GNAT manuals were transitioned to the |
| reStructuredText (rst) / Sphinx documentation generator technology. |
| During that process the @cite{GNAT User's Guide} was reorganized |
| so that related topics would be described together in the same chapter |
| or appendix. Here's a summary of the major changes realized in |
| the new document structure. |
| |
| |
| @itemize * |
| |
| @item |
| @ref{9,,The GNAT Compilation Model} has been extended so that it now covers |
| the following material: |
| |
| |
| @itemize - |
| |
| @item |
| The @cite{gnatname}, @cite{gnatkr}, and @cite{gnatchop} tools |
| |
| @item |
| @ref{16,,Configuration Pragmas} |
| |
| @item |
| @ref{17,,GNAT and Libraries} |
| |
| @item |
| @ref{18,,Conditional Compilation} including @ref{19,,Preprocessing with gnatprep} |
| and @ref{1a,,Integrated Preprocessing} |
| |
| @item |
| @ref{1b,,Generating Ada Bindings for C and C++ headers} |
| |
| @item |
| @ref{1c,,Using GNAT Files with External Tools} |
| @end itemize |
| |
| @item |
| @ref{a,,Building Executable Programs with GNAT} is a new chapter consolidating |
| the following content: |
| |
| |
| @itemize - |
| |
| @item |
| @ref{1d,,Building with gnatmake} |
| |
| @item |
| @ref{1e,,Compiling with gcc} |
| |
| @item |
| @ref{1f,,Binding with gnatbind} |
| |
| @item |
| @ref{20,,Linking with gnatlink} |
| |
| @item |
| @ref{21,,Using the GNU make Utility} |
| @end itemize |
| |
| @item |
| @ref{d,,GNAT Utility Programs} is a new chapter consolidating the information about several |
| GNAT tools: |
| |
| |
| |
| @itemize - |
| |
| @item |
| @ref{22,,The File Cleanup Utility gnatclean} |
| |
| @item |
| @ref{23,,The GNAT Library Browser gnatls} |
| |
| @item |
| @ref{24,,The Cross-Referencing Tools gnatxref and gnatfind} |
| |
| @item |
| @ref{25,,The Ada to HTML Converter gnathtml} |
| @end itemize |
| |
| @item |
| @ref{e,,GNAT and Program Execution} is a new chapter consolidating the following: |
| |
| |
| @itemize - |
| |
| @item |
| @ref{26,,Running and Debugging Ada Programs} |
| |
| @item |
| @ref{27,,Code Coverage and Profiling} |
| |
| @item |
| @ref{28,,Improving Performance} |
| |
| @item |
| @ref{29,,Overflow Check Handling in GNAT} |
| |
| @item |
| @ref{2a,,Performing Dimensionality Analysis in GNAT} |
| |
| @item |
| @ref{2b,,Stack Related Facilities} |
| |
| @item |
| @ref{2c,,Memory Management Issues} |
| @end itemize |
| |
| @item |
| @ref{f,,Platform-Specific Information} is a new appendix consolidating the following: |
| |
| |
| @itemize - |
| |
| @item |
| @ref{2d,,Run-Time Libraries} |
| |
| @item |
| @ref{2e,,Microsoft Windows Topics} |
| |
| @item |
| @ref{2f,,Mac OS Topics} |
| @end itemize |
| |
| @item |
| The @cite{Compatibility and Porting Guide} appendix has been moved to the |
| @cite{GNAT Reference Manual}. It now includes a section |
| @cite{Writing Portable Fixed-Point Declarations} which was previously |
| a separate chapter in the @cite{GNAT User's Guide}. |
| @end itemize |
| |
| @node Conventions,,A Note to Readers of Previous Versions of the Manual,About This Guide |
| @anchor{gnat_ugn/about_this_guide conventions}@anchor{30} |
| @section Conventions |
| |
| |
| @geindex Conventions |
| @geindex typographical |
| |
| @geindex Typographical conventions |
| |
| Following are examples of the typographical and graphic conventions used |
| in this guide: |
| |
| |
| @itemize * |
| |
| @item |
| @cite{Functions}, @cite{utility program names}, @cite{standard names}, |
| and @cite{classes}. |
| |
| @item |
| @cite{Option flags} |
| |
| @item |
| @code{File names} |
| |
| @item |
| @cite{Variables} |
| |
| @item |
| @emph{Emphasis} |
| |
| @item |
| [optional information or parameters] |
| |
| @item |
| Examples are described by text |
| |
| @example |
| and then shown this way. |
| @end example |
| |
| @item |
| Commands that are entered by the user are shown as preceded by a prompt string |
| comprising the @code{$} character followed by a space. |
| |
| @item |
| Full file names are shown with the '/' character |
| as the directory separator; e.g., @code{parent-dir/subdir/myfile.adb}. |
| If you are using GNAT on a Windows platform, please note that |
| the '\' character should be used instead. |
| @end itemize |
| |
| @node Getting Started with GNAT,The GNAT Compilation Model,About This Guide,Top |
| @anchor{gnat_ugn/getting_started_with_gnat getting-started-with-gnat}@anchor{8}@anchor{gnat_ugn/getting_started_with_gnat doc}@anchor{31}@anchor{gnat_ugn/getting_started_with_gnat id1}@anchor{32} |
| @chapter Getting Started with GNAT |
| |
| |
| This chapter describes how to use GNAT's command line interface to build |
| executable Ada programs. |
| On most platforms a visually oriented Integrated Development Environment |
| is also available, the GNAT Programming Studio (GPS). |
| GPS offers a graphical "look and feel", support for development in |
| other programming languages, comprehensive browsing features, and |
| many other capabilities. |
| For information on GPS please refer to |
| @cite{Using the GNAT Programming Studio}. |
| |
| @menu |
| * Running GNAT:: |
| * Running a Simple Ada Program:: |
| * Running a Program with Multiple Units:: |
| * Using the gnatmake Utility:: |
| |
| @end menu |
| |
| @node Running GNAT,Running a Simple Ada Program,,Getting Started with GNAT |
| @anchor{gnat_ugn/getting_started_with_gnat running-gnat}@anchor{33}@anchor{gnat_ugn/getting_started_with_gnat id2}@anchor{34} |
| @section Running GNAT |
| |
| |
| Three steps are needed to create an executable file from an Ada source |
| file: |
| |
| |
| @itemize * |
| |
| @item |
| The source file(s) must be compiled. |
| |
| @item |
| The file(s) must be bound using the GNAT binder. |
| |
| @item |
| All appropriate object files must be linked to produce an executable. |
| @end itemize |
| |
| All three steps are most commonly handled by using the @emph{gnatmake} |
| utility program that, given the name of the main program, automatically |
| performs the necessary compilation, binding and linking steps. |
| |
| @node Running a Simple Ada Program,Running a Program with Multiple Units,Running GNAT,Getting Started with GNAT |
| @anchor{gnat_ugn/getting_started_with_gnat running-a-simple-ada-program}@anchor{35}@anchor{gnat_ugn/getting_started_with_gnat id3}@anchor{36} |
| @section Running a Simple Ada Program |
| |
| |
| Any text editor may be used to prepare an Ada program. |
| (If Emacs is used, the optional Ada mode may be helpful in laying out the |
| program.) |
| The program text is a normal text file. We will assume in our initial |
| example that you have used your editor to prepare the following |
| standard format text file: |
| |
| @example |
| with Ada.Text_IO; use Ada.Text_IO; |
| procedure Hello is |
| begin |
| Put_Line ("Hello WORLD!"); |
| end Hello; |
| @end example |
| |
| This file should be named @code{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 @code{ads} for a |
| spec and @code{adb} for a body. |
| You can override this default file naming convention by use of the |
| special pragma @cite{Source_File_Name} (for further information please |
| see @ref{37,,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 @cite{gnatchop} utility |
| can be used to generate correctly-named source files |
| (see @ref{38,,Renaming Files with gnatchop}). |
| |
| You can compile the program using the following command (@cite{$} is used |
| as the command prompt in the examples in this document): |
| |
| @example |
| $ gcc -c hello.adb |
| @end example |
| |
| @emph{gcc} is the command used to run the compiler. This compiler is |
| capable of compiling programs in several languages, including Ada and |
| C. It assumes that you have given it an Ada program if the file extension is |
| either @code{.ads} or @code{.adb}, and it will then call |
| the GNAT compiler to compile the specified file. |
| |
| The @code{-c} switch is required. It tells @emph{gcc} to only do a |
| compilation. (For C programs, @emph{gcc} can also do linking, but this |
| capability is not used directly for Ada programs, so the @code{-c} |
| switch must always be present.) |
| |
| This compile command generates a file |
| @code{hello.o}, which is the object |
| file corresponding to your Ada program. It also generates |
| an 'Ada Library Information' file @code{hello.ali}, |
| which contains additional information used to check |
| that an Ada program is consistent. |
| To build an executable file, |
| use @cite{gnatbind} to bind the program |
| and @emph{gnatlink} to link it. The |
| argument to both @cite{gnatbind} and @emph{gnatlink} is the name of the |
| @code{ALI} file, but the default extension of @code{.ali} can |
| be omitted. This means that in the most common case, the argument |
| is simply the name of the main program: |
| |
| @example |
| $ gnatbind hello |
| $ gnatlink hello |
| @end example |
| |
| A simpler method of carrying out these steps is to use @emph{gnatmake}, |
| a master program that invokes all the required |
| compilation, binding and linking tools in the correct order. In particular, |
| @emph{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. |
| |
| @geindex Version skew (avoided by *gnatmake*) |
| |
| @example |
| $ gnatmake hello.adb |
| @end example |
| |
| The result is an executable program called @code{hello}, which can be |
| run by entering: |
| |
| @example |
| $ hello |
| @end example |
| |
| assuming that the current directory is on the search path |
| for executable programs. |
| |
| and, if all has gone well, you will see: |
| |
| @example |
| Hello WORLD! |
| @end example |
| |
| appear in response to this command. |
| |
| @node Running a Program with Multiple Units,Using the gnatmake Utility,Running a Simple Ada Program,Getting Started with GNAT |
| @anchor{gnat_ugn/getting_started_with_gnat id4}@anchor{39}@anchor{gnat_ugn/getting_started_with_gnat running-a-program-with-multiple-units}@anchor{3a} |
| @section 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: |
| |
| @example |
| 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; |
| @end example |
| |
| Following the one-unit-per-file rule, place this program in the |
| following three separate files: |
| |
| |
| @table @asis |
| |
| @item @emph{greetings.ads} |
| |
| spec of package @cite{Greetings} |
| |
| @item @emph{greetings.adb} |
| |
| body of package @cite{Greetings} |
| |
| @item @emph{gmain.adb} |
| |
| body of main program |
| @end table |
| |
| To build an executable version of |
| this program, we could use four separate steps to compile, bind, and link |
| the program, as follows: |
| |
| @example |
| $ gcc -c gmain.adb |
| $ gcc -c greetings.adb |
| $ gnatbind gmain |
| $ gnatlink gmain |
| @end example |
| |
| 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 @code{-gnatc} switch: |
| |
| @example |
| $ gcc -c greetings.ads -gnatc |
| @end example |
| |
| 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 @emph{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: |
| |
| @example |
| $ gnatmake gmain.adb |
| @end example |
| |
| In the next section we discuss the advantages of using @emph{gnatmake} in |
| more detail. |
| |
| @node Using the gnatmake Utility,,Running a Program with Multiple Units,Getting Started with GNAT |
| @anchor{gnat_ugn/getting_started_with_gnat using-the-gnatmake-utility}@anchor{3b}@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{3c} |
| @section Using the @emph{gnatmake} Utility |
| |
| |
| If you work on a program by compiling single components at a time using |
| @emph{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 @code{gmain.adb}, you only need to recompile that file. But if |
| you edit @code{greetings.ads}, you must recompile both |
| @code{greetings.adb} and @code{gmain.adb}, because both files contain |
| units that depend on @code{greetings.ads}. |
| |
| @emph{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 @emph{gnatmake} utility takes care of these details automatically. |
| Invoke it using either one of the following forms: |
| |
| @example |
| $ gnatmake gmain.adb |
| $ gnatmake gmain |
| @end example |
| |
| The argument is the name of the file containing the main program; |
| you may omit the extension. @emph{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, @code{gmain}. |
| In a large program, it |
| can be extremely helpful to use @emph{gnatmake}, because working out by hand |
| what needs to be recompiled can be difficult. |
| |
| Note that @emph{gnatmake} takes into account all the Ada 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, @emph{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. @emph{gnatmake} determines the exact set of |
| dependencies from scratch each time it is run. |
| |
| @c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit |
| |
| @node The GNAT Compilation Model,Building Executable Programs with GNAT,Getting Started with GNAT,Top |
| @anchor{gnat_ugn/the_gnat_compilation_model doc}@anchor{3d}@anchor{gnat_ugn/the_gnat_compilation_model the-gnat-compilation-model}@anchor{9}@anchor{gnat_ugn/the_gnat_compilation_model id1}@anchor{3e} |
| @chapter The GNAT Compilation Model |
| |
| |
| @geindex GNAT compilation model |
| |
| @geindex Compilation model |
| |
| 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 centralized program library. The chapter covers |
| the following material: |
| |
| |
| @itemize * |
| |
| @item |
| Topics related to source file makeup and naming |
| |
| |
| @itemize * |
| |
| @item |
| @ref{3f,,Source Representation} |
| |
| @item |
| @ref{40,,Foreign Language Representation} |
| |
| @item |
| @ref{41,,File Naming Topics and Utilities} |
| @end itemize |
| |
| @item |
| @ref{16,,Configuration Pragmas} |
| |
| @item |
| @ref{42,,Generating Object Files} |
| |
| @item |
| @ref{43,,Source Dependencies} |
| |
| @item |
| @ref{44,,The Ada Library Information Files} |
| |
| @item |
| @ref{45,,Binding an Ada Program} |
| |
| @item |
| @ref{17,,GNAT and Libraries} |
| |
| @item |
| @ref{18,,Conditional Compilation} |
| |
| @item |
| @ref{46,,Mixed Language Programming} |
| |
| @item |
| @ref{47,,GNAT and Other Compilation Models} |
| |
| @item |
| @ref{1c,,Using GNAT Files with External Tools} |
| @end itemize |
| |
| @menu |
| * Source Representation:: |
| * Foreign Language Representation:: |
| * File Naming Topics and Utilities:: |
| * Configuration Pragmas:: |
| * Generating Object Files:: |
| * Source Dependencies:: |
| * The Ada Library Information Files:: |
| * Binding an Ada Program:: |
| * GNAT and Libraries:: |
| * Conditional Compilation:: |
| * Mixed Language Programming:: |
| * GNAT and Other Compilation Models:: |
| * Using GNAT Files with External Tools:: |
| |
| @end menu |
| |
| @node Source Representation,Foreign Language Representation,,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model source-representation}@anchor{3f}@anchor{gnat_ugn/the_gnat_compilation_model id2}@anchor{48} |
| @section Source Representation |
| |
| |
| @geindex Latin-1 |
| |
| @geindex VT |
| @geindex HT |
| @geindex CR |
| @geindex LF |
| @geindex FF |
| |
| 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 (see @ref{40,,Foreign Language Representation} |
| for support of non-USA character sets). The format effector characters |
| are represented using their standard ASCII encodings, as follows: |
| |
| @quotation |
| |
| |
| @multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx} |
| @item |
| |
| Character |
| |
| @tab |
| |
| Effect |
| |
| @tab |
| |
| Code |
| |
| @item |
| |
| @code{VT} |
| |
| @tab |
| |
| Vertical tab |
| |
| @tab |
| |
| @cite{16#0B#} |
| |
| @item |
| |
| @code{HT} |
| |
| @tab |
| |
| Horizontal tab |
| |
| @tab |
| |
| @cite{16#09#} |
| |
| @item |
| |
| @code{CR} |
| |
| @tab |
| |
| Carriage return |
| |
| @tab |
| |
| @cite{16#0D#} |
| |
| @item |
| |
| @code{LF} |
| |
| @tab |
| |
| Line feed |
| |
| @tab |
| |
| @cite{16#0A#} |
| |
| @item |
| |
| @code{FF} |
| |
| @tab |
| |
| Form feed |
| |
| @tab |
| |
| @cite{16#0C#} |
| |
| @end multitable |
| |
| @end quotation |
| |
| 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 lines is marked by any of the following sequences: |
| @cite{LF}, @cite{CR}, @cite{CR-LF}, or @cite{LF-CR}. This is useful |
| in accommodating files that are imported from other operating systems. |
| |
| @geindex End of source file; Source file@comma{} end |
| |
| @geindex SUB (control character) |
| |
| The end of a source file is normally represented by the physical end of |
| file. However, the control character @cite{16#1A#} (@code{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. |
| |
| @geindex spec (definition) |
| @geindex compilation (definition) |
| |
| 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 @cite{spec}) and the corresponding body in |
| separate files. An Ada @cite{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. |
| |
| @node Foreign Language Representation,File Naming Topics and Utilities,Source Representation,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model foreign-language-representation}@anchor{40}@anchor{gnat_ugn/the_gnat_compilation_model id3}@anchor{49} |
| @section Foreign Language Representation |
| |
| |
| GNAT supports the standard character sets defined in Ada as well as |
| several other non-standard character sets for use in localized versions |
| of the compiler (@ref{4a,,Character Set Control}). |
| |
| @menu |
| * Latin-1:: |
| * Other 8-Bit Codes:: |
| * Wide_Character Encodings:: |
| * Wide_Wide_Character Encodings:: |
| |
| @end menu |
| |
| @node Latin-1,Other 8-Bit Codes,,Foreign Language Representation |
| @anchor{gnat_ugn/the_gnat_compilation_model id4}@anchor{4b}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{4c} |
| @subsection Latin-1 |
| |
| |
| @geindex 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 @cite{16#00#} |
| ... @cite{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. |
| |
| @geindex Ada.Characters.Latin_1 |
| |
| For a complete list of Latin-1 codes and their encodings, see the source |
| file of library unit @cite{Ada.Characters.Latin_1} in file |
| @code{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. |
| |
| @node Other 8-Bit Codes,Wide_Character Encodings,Latin-1,Foreign Language Representation |
| @anchor{gnat_ugn/the_gnat_compilation_model other-8-bit-codes}@anchor{4d}@anchor{gnat_ugn/the_gnat_compilation_model id5}@anchor{4e} |
| @subsection Other 8-Bit Codes |
| |
| |
| GNAT also supports several other 8-bit coding schemes: |
| |
| @geindex Latin-2 |
| |
| @geindex ISO 8859-2 |
| |
| |
| @table @asis |
| |
| @item @emph{ISO 8859-2 (Latin-2)} |
| |
| Latin-2 letters allowed in identifiers, with uppercase and lowercase |
| equivalence. |
| @end table |
| |
| @geindex Latin-3 |
| |
| @geindex ISO 8859-3 |
| |
| |
| @table @asis |
| |
| @item @emph{ISO 8859-3 (Latin-3)} |
| |
| Latin-3 letters allowed in identifiers, with uppercase and lowercase |
| equivalence. |
| @end table |
| |
| @geindex Latin-4 |
| |
| @geindex ISO 8859-4 |
| |
| |
| @table @asis |
| |
| @item @emph{ISO 8859-4 (Latin-4)} |
| |
| Latin-4 letters allowed in identifiers, with uppercase and lowercase |
| equivalence. |
| @end table |
| |
| @geindex ISO 8859-5 |
| |
| @geindex Cyrillic |
| |
| |
| @table @asis |
| |
| @item @emph{ISO 8859-5 (Cyrillic)} |
| |
| ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and |
| lowercase equivalence. |
| @end table |
| |
| @geindex ISO 8859-15 |
| |
| @geindex Latin-9 |
| |
| |
| @table @asis |
| |
| @item @emph{ISO 8859-15 (Latin-9)} |
| |
| ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and |
| lowercase equivalence |
| @end table |
| |
| @geindex code page 437 (IBM PC) |
| |
| |
| @table @asis |
| |
| @item @emph{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. |
| @end table |
| |
| @geindex code page 850 (IBM PC) |
| |
| |
| @table @asis |
| |
| @item @emph{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. |
| |
| @item @emph{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). |
| |
| @item @emph{No Upper-Half} |
| |
| No upper-half characters in the range 80-FF are allowed in identifiers. |
| This gives Ada 83 compatibility for identifier names. |
| @end table |
| |
| For precise data on the encodings permitted, and the uppercase and lowercase |
| equivalences that are recognized, see the file @code{csets.adb} in |
| the GNAT compiler sources. You will need to obtain a full source release |
| of GNAT to obtain this file. |
| |
| @node Wide_Character Encodings,Wide_Wide_Character Encodings,Other 8-Bit Codes,Foreign Language Representation |
| @anchor{gnat_ugn/the_gnat_compilation_model id6}@anchor{4f}@anchor{gnat_ugn/the_gnat_compilation_model wide-character-encodings}@anchor{50} |
| @subsection 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: |
| |
| |
| @table @asis |
| |
| @item @emph{Hex Coding} |
| |
| In this encoding, a wide character is represented by the following five |
| character sequence: |
| |
| @example |
| ESC a b c d |
| @end example |
| |
| where @cite{a}, @cite{b}, @cite{c}, @cite{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 |
| @cite{16#A345#}. |
| This scheme is compatible with use of the full Wide_Character set. |
| |
| @item @emph{Upper-Half Coding} |
| |
| @geindex Upper-Half Coding |
| |
| The wide character with encoding @cite{16#abcd#} where the upper bit is on |
| (in other words, 'a' is in the range 8-F) is represented as two bytes, |
| @cite{16#ab#} and @cite{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. |
| |
| @item @emph{Shift JIS Coding} |
| |
| @geindex Shift JIS Coding |
| |
| A wide character is represented by a two-character sequence, |
| @cite{16#ab#} and |
| @cite{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. |
| |
| @item @emph{EUC Coding} |
| |
| @geindex EUC Coding |
| |
| A wide character is represented by a two-character sequence |
| @cite{16#ab#} and |
| @cite{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. |
| |
| @item @emph{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: |
| |
| @example |
| 16#0000#-16#007f#: 2#0`xxxxxxx`# |
| 16#0080#-16#07ff#: 2#110`xxxxx`# 2#10`xxxxxx`# |
| 16#0800#-16#ffff#: 2#1110`xxxx`# 2#10`xxxxxx`# 2#10`xxxxxx`# |
| @end example |
| |
| where the @cite{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, and in the following section on wide wide |
| characters, the use of these sequences is documented). |
| |
| @item @emph{Brackets Coding} |
| |
| In this encoding, a wide character is represented by the following eight |
| character sequence: |
| |
| @example |
| [ " a b c d " ] |
| @end example |
| |
| where @cite{a}, @cite{b}, @cite{c}, @cite{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 |
| @cite{16#A345#}. It is also possible (though not required) to use the |
| Brackets coding for upper half characters. For example, the code |
| @cite{16#A3#} can be represented as @cite{['A3']}. |
| |
| This scheme is compatible with use of the full Wide_Character set, |
| and is also the method used for wide character encoding in some standard |
| ACATS (Ada Conformity Assessment Test Suite) test suite distributions. |
| @end table |
| |
| @cartouche |
| @quotation Note |
| Some of these coding schemes do not permit the full use of the |
| Ada character set. For example, neither Shift JIS nor EUC allow the |
| use of the upper half of the Latin-1 set. |
| @end quotation |
| @end cartouche |
| |
| @node Wide_Wide_Character Encodings,,Wide_Character Encodings,Foreign Language Representation |
| @anchor{gnat_ugn/the_gnat_compilation_model id7}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model wide-wide-character-encodings}@anchor{52} |
| @subsection Wide_Wide_Character Encodings |
| |
| |
| GNAT allows wide wide character codes to appear in character and string |
| literals, and also optionally in identifiers, by means of the following |
| possible encoding schemes: |
| |
| |
| @table @asis |
| |
| @item @emph{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 |
| of character codes with values greater than 16#FFFF# is a |
| is a four, five, or six byte sequence: |
| |
| @example |
| 16#01_0000#-16#10_FFFF#: 11110xxx 10xxxxxx 10xxxxxx |
| 10xxxxxx |
| 16#0020_0000#-16#03FF_FFFF#: 111110xx 10xxxxxx 10xxxxxx |
| 10xxxxxx 10xxxxxx |
| 16#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx |
| 10xxxxxx 10xxxxxx 10xxxxxx |
| @end example |
| |
| where the @cite{xxx} bits correspond to the left-padded bits of the |
| 32-bit character value. |
| |
| @item @emph{Brackets Coding} |
| |
| In this encoding, a wide wide character is represented by the following ten or |
| twelve byte character sequence: |
| |
| @example |
| [ " a b c d e f " ] |
| [ " a b c d e f g h " ] |
| @end example |
| |
| where @cite{a-h} are the six or eight hexadecimal |
| characters (using uppercase letters) of the wide wide character code. For |
| example, ["1F4567"] is used to represent the wide wide character with code |
| @cite{16#001F_4567#}. |
| |
| This scheme is compatible with use of the full Wide_Wide_Character set, |
| and is also the method used for wide wide character encoding in some standard |
| ACATS (Ada Conformity Assessment Test Suite) test suite distributions. |
| @end table |
| |
| @node File Naming Topics and Utilities,Configuration Pragmas,Foreign Language Representation,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model id8}@anchor{53}@anchor{gnat_ugn/the_gnat_compilation_model file-naming-topics-and-utilities}@anchor{41} |
| @section File Naming Topics and Utilities |
| |
| |
| GNAT has a default file naming scheme and also provides the user with |
| a high degree of control over how the names and extensions of the |
| source files correspond to the Ada compilation units that they contain. |
| |
| @menu |
| * File Naming Rules:: |
| * Using Other File Names:: |
| * Alternative File Naming Schemes:: |
| * Handling Arbitrary File Naming Conventions with gnatname:: |
| * File Name Krunching with gnatkr:: |
| * Renaming Files with gnatchop:: |
| |
| @end menu |
| |
| @node File Naming Rules,Using Other File Names,,File Naming Topics and Utilities |
| @anchor{gnat_ugn/the_gnat_compilation_model file-naming-rules}@anchor{54}@anchor{gnat_ugn/the_gnat_compilation_model id9}@anchor{55} |
| @subsection 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 |
| @cite{a}, @cite{g}, @cite{i}, or @cite{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 |
| @cite{s-}, @cite{a-}, @cite{i-}, and @cite{g-}, |
| respectively. |
| |
| The file extension is @code{.ads} for a spec and |
| @code{.adb} for a body. The following table shows some |
| examples of these rules. |
| |
| @quotation |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| Source File |
| |
| @tab |
| |
| Ada Compilation Unit |
| |
| @item |
| |
| @code{main.ads} |
| |
| @tab |
| |
| Main (spec) |
| |
| @item |
| |
| @code{main.adb} |
| |
| @tab |
| |
| Main (body) |
| |
| @item |
| |
| @code{arith_functions.ads} |
| |
| @tab |
| |
| Arith_Functions (package spec) |
| |
| @item |
| |
| @code{arith_functions.adb} |
| |
| @tab |
| |
| Arith_Functions (package body) |
| |
| @item |
| |
| @code{func-spec.ads} |
| |
| @tab |
| |
| Func.Spec (child package spec) |
| |
| @item |
| |
| @code{func-spec.adb} |
| |
| @tab |
| |
| Func.Spec (child package body) |
| |
| @item |
| |
| @code{main-sub.adb} |
| |
| @tab |
| |
| Sub (subunit of Main) |
| |
| @item |
| |
| @code{a~bad.adb} |
| |
| @tab |
| |
| A.Bad (child package body) |
| |
| @end multitable |
| |
| @end quotation |
| |
| 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. @ref{56,,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 see @ref{38,,Renaming Files with gnatchop}.) |
| |
| Note: in the case of Windows or Mac OS operating systems, case is not |
| significant. So for example on @cite{Windows} if the canonical name is |
| @cite{main-sub.adb}, you can use the file name @code{Main-Sub.adb} instead. |
| However, case is significant for other operating systems, so for example, |
| if you want to use other than canonically cased file names on a Unix system, |
| you need to follow the procedures described in the next section. |
| |
| @node Using Other File Names,Alternative File Naming Schemes,File Naming Rules,File Naming Topics and Utilities |
| @anchor{gnat_ugn/the_gnat_compilation_model id10}@anchor{57}@anchor{gnat_ugn/the_gnat_compilation_model using-other-file-names}@anchor{37} |
| @subsection Using Other File Names |
| |
| |
| @geindex 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. |
| |
| @geindex Source_File_Name pragma |
| |
| 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: |
| |
| @example |
| 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"); |
| @end example |
| |
| 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 @code{gnat.adc} |
| file used to hold configuration |
| pragmas that apply to a complete compilation environment. |
| For more details on how the @code{gnat.adc} file is created and used |
| see @ref{58,,Handling of Configuration Pragmas}. |
| |
| @geindex gnat.adc |
| |
| 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 @code{.ads} or @code{.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 @emph{-x} followed by a space and the name |
| of the language, here @cite{ada}, as in: |
| |
| @example |
| $ gcc -c -x ada peculiar_file_name.sim |
| @end example |
| |
| @cite{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 @cite{gnatmake} command, it may not |
| be omitted. |
| |
| @node Alternative File Naming Schemes,Handling Arbitrary File Naming Conventions with gnatname,Using Other File Names,File Naming Topics and Utilities |
| @anchor{gnat_ugn/the_gnat_compilation_model id11}@anchor{59}@anchor{gnat_ugn/the_gnat_compilation_model alternative-file-naming-schemes}@anchor{5a} |
| @subsection Alternative File Naming Schemes |
| |
| |
| @geindex File naming schemes |
| @geindex alternative |
| |
| @geindex File names |
| |
| The previous section described the use of the @cite{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 @code{gnat.adc} files, and also create |
| a maintenance problem. |
| |
| @geindex Source_File_Name pragma |
| |
| 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 |
| @cite{Source_File_Name} pragmas having the following format: |
| |
| @example |
| 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 |
| @end example |
| |
| The @cite{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 |
| @cite{Casing} indicates |
| whether the unit name is to be all upper-case letters, all lower-case letters, |
| or mixed-case. If no |
| @cite{Casing} parameter is used, then the default is all |
| lower-case. |
| |
| The optional @cite{Dot_Replacement} string is used to replace any periods |
| that occur in subunit or child unit names. If no @cite{Dot_Replacement} |
| argument is used then separating dots appear unchanged in the resulting |
| file name. |
| Although the above syntax indicates that the |
| @cite{Casing} argument must appear |
| before the @cite{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 @cite{Subunit_File_Name} rule, and in this case the |
| @cite{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: |
| |
| |
| @itemize * |
| |
| @item |
| If there is a specific @cite{Source_File_Name} pragma for the given unit, |
| then this is always used, and any general pattern rules are ignored. |
| |
| @item |
| If there is a pattern type @cite{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. |
| |
| @item |
| If no pattern type @cite{Source_File_Name} pragma that applies to the unit |
| for which the corresponding file exists, then the standard GNAT default |
| naming rules are used. |
| @end itemize |
| |
| 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 @code{.1.ada}, and |
| bodies end with @code{.2.ada}. GNAT will follow this scheme if the following |
| two pragmas appear: |
| |
| @example |
| pragma Source_File_Name |
| (Spec_File_Name => ".1.ada"); |
| pragma Source_File_Name |
| (Body_File_Name => ".2.ada"); |
| @end example |
| |
| The default GNAT scheme is actually implemented by providing the following |
| default pragmas internally: |
| |
| @example |
| pragma Source_File_Name |
| (Spec_File_Name => ".ads", Dot_Replacement => "-"); |
| pragma Source_File_Name |
| (Body_File_Name => ".adb", Dot_Replacement => "-"); |
| @end example |
| |
| 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 @code{_.ADA}, bodies |
| by adding @code{.ADA}, and subunits by |
| adding @code{.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. |
| |
| @example |
| 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); |
| @end example |
| |
| @geindex gnatname |
| |
| @node Handling Arbitrary File Naming Conventions with gnatname,File Name Krunching with gnatkr,Alternative File Naming Schemes,File Naming Topics and Utilities |
| @anchor{gnat_ugn/the_gnat_compilation_model handling-arbitrary-file-naming-conventions-with-gnatname}@anchor{5b}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{5c} |
| @subsection Handling Arbitrary File Naming Conventions with @cite{gnatname} |
| |
| |
| @geindex File Naming Conventions |
| |
| @menu |
| * Arbitrary File Naming Conventions:: |
| * Running gnatname:: |
| * Switches for gnatname:: |
| * Examples of gnatname Usage:: |
| |
| @end menu |
| |
| @node Arbitrary File Naming Conventions,Running gnatname,,Handling Arbitrary File Naming Conventions with gnatname |
| @anchor{gnat_ugn/the_gnat_compilation_model arbitrary-file-naming-conventions}@anchor{5d}@anchor{gnat_ugn/the_gnat_compilation_model id13}@anchor{5e} |
| @subsubsection 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 |
| (@cite{.ads} for specs, @cite{.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 (@ref{16,,Configuration Pragmas}) |
| or a project file. |
| When the non-standard file naming conventions are well-defined, |
| a small number of pragmas @cite{Source_File_Name} specifying a naming pattern |
| (@ref{5a,,Alternative File Naming Schemes}) may be sufficient. However, |
| if the file naming conventions are irregular or arbitrary, a number |
| of pragma @cite{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 @cite{gnatname} to generate the required pragmas for a |
| set of files. |
| |
| @node Running gnatname,Switches for gnatname,Arbitrary File Naming Conventions,Handling Arbitrary File Naming Conventions with gnatname |
| @anchor{gnat_ugn/the_gnat_compilation_model running-gnatname}@anchor{5f}@anchor{gnat_ugn/the_gnat_compilation_model id14}@anchor{60} |
| @subsubsection Running @cite{gnatname} |
| |
| |
| The usual form of the @cite{gnatname} command is: |
| |
| @example |
| $ gnatname [`switches`] `naming_pattern` [`naming_patterns`] |
| [--and [`switches`] `naming_pattern` [`naming_patterns`]] |
| @end example |
| |
| All of the arguments are optional. If invoked without any argument, |
| @cite{gnatname} will display its usage. |
| |
| When used with at least one naming pattern, @cite{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, |
| @cite{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 @cite{gnatname}. |
| Each Naming Pattern is enclosed between double quotes (or single |
| quotes on Windows). |
| A Naming Pattern is a regular expression similar to the wildcard patterns |
| used in file names by the Unix shells or the DOS prompt. |
| |
| @cite{gnatname} may be called with several sections of directories/patterns. |
| Sections are separated by switch @cite{--and}. In each section, there must be |
| at least one pattern. If no directory is specified in a section, the current |
| directory (or the project directory is @cite{-P} is used) is implied. |
| The options other that the directory switches and the patterns apply globally |
| even if they are in different sections. |
| |
| Examples of Naming Patterns are: |
| |
| @example |
| "*.[12].ada" |
| "*.ad[sb]*" |
| "body_*" "spec_*" |
| @end example |
| |
| For a more complete description of the syntax of Naming Patterns, |
| see the second kind of regular expressions described in @code{g-regexp.ads} |
| (the 'Glob' regular expressions). |
| |
| When invoked with no switch @cite{-P}, @cite{gnatname} will create a |
| configuration pragmas file @code{gnat.adc} in the current working directory, |
| with pragmas @cite{Source_File_Name} for each file that contains a valid Ada |
| unit. |
| |
| @node Switches for gnatname,Examples of gnatname Usage,Running gnatname,Handling Arbitrary File Naming Conventions with gnatname |
| @anchor{gnat_ugn/the_gnat_compilation_model id15}@anchor{61}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{62} |
| @subsubsection Switches for @cite{gnatname} |
| |
| |
| Switches for @cite{gnatname} must precede any specified Naming Pattern. |
| |
| You may specify any of the following switches to @cite{gnatname}: |
| |
| @geindex --version (gnatname) |
| |
| |
| @table @asis |
| |
| @item @code{--version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatname) |
| |
| |
| @table @asis |
| |
| @item @code{--help} |
| |
| If @emph{--version} was not used, display usage, then exit disregarding |
| all other options. |
| |
| @item @code{--subdirs=@emph{dir}} |
| |
| Real object, library or exec directories are subdirectories <dir> of the |
| specified ones. |
| |
| @item @code{--no-backup} |
| |
| Do not create a backup copy of an existing project file. |
| |
| @item @code{--and} |
| |
| Start another section of directories/patterns. |
| @end table |
| |
| @geindex -c (gnatname) |
| |
| |
| @table @asis |
| |
| @item @code{-c@emph{filename}} |
| |
| Create a configuration pragmas file @code{filename} (instead of the default |
| @code{gnat.adc}). |
| There may be zero, one or more space between @emph{-c} and |
| @code{filename}. |
| @code{filename} may include directory information. @code{filename} must be |
| writable. There may be only one switch @emph{-c}. |
| When a switch @emph{-c} is |
| specified, no switch @emph{-P} may be specified (see below). |
| @end table |
| |
| @geindex -d (gnatname) |
| |
| |
| @table @asis |
| |
| @item @code{-d@emph{dir}} |
| |
| Look for source files in directory @code{dir}. There may be zero, one or more |
| spaces between @emph{-d} and @code{dir}. |
| @code{dir} may end with @cite{/**}, that is it may be of the form |
| @cite{root_dir/**}. In this case, the directory @cite{root_dir} and all of its |
| subdirectories, recursively, have to be searched for sources. |
| When a switch @emph{-d} |
| is specified, the current working directory will not be searched for source |
| files, unless it is explicitly specified with a @emph{-d} |
| or @emph{-D} switch. |
| Several switches @emph{-d} may be specified. |
| If @code{dir} is a relative path, it is relative to the directory of |
| the configuration pragmas file specified with switch |
| @emph{-c}, |
| or to the directory of the project file specified with switch |
| @emph{-P} or, |
| if neither switch @emph{-c} |
| nor switch @emph{-P} are specified, it is relative to the |
| current working directory. The directory |
| specified with switch @emph{-d} must exist and be readable. |
| @end table |
| |
| @geindex -D (gnatname) |
| |
| |
| @table @asis |
| |
| @item @code{-D@emph{filename}} |
| |
| Look for source files in all directories listed in text file @code{filename}. |
| There may be zero, one or more spaces between @emph{-D} |
| and @code{filename}. |
| @code{filename} must be an existing, readable text file. |
| Each nonempty line in @code{filename} must be a directory. |
| Specifying switch @emph{-D} is equivalent to specifying as many |
| switches @emph{-d} as there are nonempty lines in |
| @code{file}. |
| |
| @item @code{-eL} |
| |
| Follow symbolic links when processing project files. |
| |
| @geindex -f (gnatname) |
| |
| @item @code{-f@emph{pattern}} |
| |
| Foreign patterns. Using this switch, it is possible to add sources of languages |
| other than Ada to the list of sources of a project file. |
| It is only useful if a -P switch is used. |
| For example, |
| |
| @example |
| gnatname -Pprj -f"*.c" "*.ada" |
| @end example |
| |
| will look for Ada units in all files with the @code{.ada} extension, |
| and will add to the list of file for project @code{prj.gpr} the C files |
| with extension @code{.c}. |
| |
| @geindex -h (gnatname) |
| |
| @item @code{-h} |
| |
| Output usage (help) information. The output is written to @code{stdout}. |
| |
| @geindex -P (gnatname) |
| |
| @item @code{-P@emph{proj}} |
| |
| Create or update project file @code{proj}. There may be zero, one or more space |
| between @emph{-P} and @code{proj}. @code{proj} may include directory |
| information. @code{proj} must be writable. |
| There may be only one switch @emph{-P}. |
| When a switch @emph{-P} is specified, |
| no switch @emph{-c} may be specified. |
| On all platforms, except on VMS, when @cite{gnatname} is invoked for an |
| existing project file <proj>.gpr, a backup copy of the project file is created |
| in the project directory with file name <proj>.gpr.saved_x. 'x' is the first |
| non negative number that makes this backup copy a new file. |
| |
| @geindex -v (gnatname) |
| |
| @item @code{-v} |
| |
| Verbose mode. Output detailed explanation of behavior to @code{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. |
| @end table |
| |
| @geindex -v -v (gnatname) |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| |
| @geindex -x (gnatname) |
| |
| @item @code{-x@emph{pattern}} |
| |
| Excluded patterns. Using this switch, it is possible to exclude some files |
| that would match the name patterns. For example, |
| |
| @example |
| gnatname -x "*_nt.ada" "*.ada" |
| @end example |
| |
| will look for Ada units in all files with the @code{.ada} extension, |
| except those whose names end with @code{_nt.ada}. |
| @end table |
| |
| @node Examples of gnatname Usage,,Switches for gnatname,Handling Arbitrary File Naming Conventions with gnatname |
| @anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatname-usage}@anchor{63}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{64} |
| @subsubsection Examples of @cite{gnatname} Usage |
| |
| |
| @example |
| $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" |
| @end example |
| |
| In this example, the directory @code{/home/me} must already exist |
| and be writable. In addition, the directory |
| @code{/home/me/sources} (specified by |
| @emph{-d sources}) must exist and be readable. |
| |
| Note the optional spaces after @emph{-c} and @emph{-d}. |
| |
| @example |
| $ gnatname -P/home/me/proj -x "*_nt_body.ada" |
| -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" |
| @end example |
| |
| Note that several switches @emph{-d} may be used, |
| even in conjunction with one or several switches |
| @emph{-D}. Several Naming Patterns and one excluded pattern |
| are used in this example. |
| |
| @node File Name Krunching with gnatkr,Renaming Files with gnatchop,Handling Arbitrary File Naming Conventions with gnatname,File Naming Topics and Utilities |
| @anchor{gnat_ugn/the_gnat_compilation_model file-name-krunching-with-gnatkr}@anchor{65}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{66} |
| @subsection File Name Krunching with @cite{gnatkr} |
| |
| |
| @geindex 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 |
| @cite{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:: |
| |
| @end menu |
| |
| @node About gnatkr,Using gnatkr,,File Name Krunching with gnatkr |
| @anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{67}@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{68} |
| @subsubsection About @cite{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: |
| |
| |
| @itemize * |
| |
| @item |
| Take the unit name and replace all dots by hyphens. |
| |
| @item |
| If such a replacement occurs in the |
| second character position of a name, and the first character is |
| @code{a}, @code{g}, @code{s}, or @code{i}, |
| then replace the dot by the character |
| @code{~} (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 |
| @code{s-}, @code{a-}, @code{i-}, and @code{g-}, |
| respectively. |
| @end itemize |
| |
| The @code{-gnatk@emph{nn}} |
| switch of the compiler activates a 'krunching' |
| circuit that limits file names to nn characters (where nn is a decimal |
| integer). |
| |
| The @cite{gnatkr} utility can be used to determine the krunched name for |
| a given file, when krunched to a specified maximum length. |
| |
| @node Using gnatkr,Krunching Method,About gnatkr,File Name Krunching with gnatkr |
| @anchor{gnat_ugn/the_gnat_compilation_model id19}@anchor{69}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{56} |
| @subsubsection Using @cite{gnatkr} |
| |
| |
| The @cite{gnatkr} command has the form: |
| |
| @example |
| $ gnatkr `name` [`length`] |
| @end example |
| |
| @cite{name} is the uncrunched file name, derived from the name of the unit |
| in the standard manner described in the previous section (i.e., in particular |
| all dots are replaced by hyphens). The file name may or may not have an |
| extension (defined as a suffix of the form period followed by arbitrary |
| characters other than period). If an extension is present then it will |
| be preserved in the output. For example, when krunching @code{hellofile.ads} |
| to eight characters, the result will be hellofil.ads. |
| |
| Note: for compatibility with previous versions of @cite{gnatkr} dots may |
| appear in the name instead of hyphens, but the last dot will always be |
| taken as the start of an extension. So if @cite{gnatkr} is given an argument |
| such as @code{Hello.World.adb} it will be treated exactly as if the first |
| period had been a hyphen, and for example krunching to eight characters |
| gives the result @code{hellworl.adb}. |
| |
| Note that the result is always all lower case. |
| Characters of the other case are folded as required. |
| |
| @cite{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 where the |
| implied crunching length is always eight characters. |
| |
| The output is the krunched name. The output has an extension only if the |
| original argument was a file name with an extension. |
| |
| @node Krunching Method,Examples of gnatkr Usage,Using gnatkr,File Name Krunching with gnatkr |
| @anchor{gnat_ugn/the_gnat_compilation_model id20}@anchor{6a}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{6b} |
| @subsubsection 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 |
| @code{a}, @code{i}, @code{g}, or @code{s}. |
| The extension is @cite{.ads} for a |
| spec and @cite{.adb} for a body. |
| Krunching does not affect the extension, but the file name is shortened to |
| the specified length by following these rules: |
| |
| |
| @itemize * |
| |
| @item |
| 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. |
| |
| @item |
| 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 @code{our-strings-wide_fixed.adb} |
| to fit the name into 8 characters as required by some operating systems: |
| |
| @example |
| 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 |
| @end example |
| |
| @item |
| 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: |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} |
| @item |
| |
| Prefix |
| |
| @tab |
| |
| Replacement |
| |
| @item |
| |
| @code{ada-} |
| |
| @tab |
| |
| @code{a-} |
| |
| @item |
| |
| @code{gnat-} |
| |
| @tab |
| |
| @code{g-} |
| |
| @item |
| |
| @code{interfac es-} |
| |
| @tab |
| |
| @code{i-} |
| |
| @item |
| |
| @code{system-} |
| |
| @tab |
| |
| @code{s-} |
| |
| @end multitable |
| |
| |
| 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 |
| @code{ada-strings-wide_fixed.adb}, which gets krunched as follows: |
| |
| @example |
| 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 |
| @end example |
| @end itemize |
| |
| 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 @cite{gnatkr} is supplied for conveniently determining the |
| krunched name of a file. |
| |
| @node Examples of gnatkr Usage,,Krunching Method,File Name Krunching with gnatkr |
| @anchor{gnat_ugn/the_gnat_compilation_model id21}@anchor{6c}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatkr-usage}@anchor{6d} |
| @subsubsection Examples of @cite{gnatkr} Usage |
| |
| |
| @example |
| $ gnatkr very_long_unit_name.ads --> velounna.ads |
| $ gnatkr grandparent-parent-child.ads --> grparchi.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 |
| @end example |
| |
| @node Renaming Files with gnatchop,,File Name Krunching with gnatkr,File Naming Topics and Utilities |
| @anchor{gnat_ugn/the_gnat_compilation_model id22}@anchor{6e}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{38} |
| @subsection Renaming Files with @cite{gnatchop} |
| |
| |
| @geindex gnatchop |
| |
| This chapter discusses how to handle files with multiple units by using |
| the @cite{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:: |
| |
| @end menu |
| |
| @node Handling Files with Multiple Units,Operating gnatchop in Compilation Mode,,Renaming Files with gnatchop |
| @anchor{gnat_ugn/the_gnat_compilation_model id23}@anchor{6f}@anchor{gnat_ugn/the_gnat_compilation_model handling-files-with-multiple-units}@anchor{70} |
| @subsubsection 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 @cite{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. @cite{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 @emph{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 @emph{gnatchop} each |
| time you compile, regarding the source files that it writes as temporary |
| files that you throw away. |
| |
| Note that if your file containing multiple units starts with a byte order |
| mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop |
| will each start with a copy of this BOM, meaning that they can be compiled |
| automatically in UTF-8 mode without needing to specify an explicit encoding. |
| |
| @node Operating gnatchop in Compilation Mode,Command Line for gnatchop,Handling Files with Multiple Units,Renaming Files with gnatchop |
| @anchor{gnat_ugn/the_gnat_compilation_model operating-gnatchop-in-compilation-mode}@anchor{71}@anchor{gnat_ugn/the_gnat_compilation_model id24}@anchor{72} |
| @subsubsection Operating gnatchop in Compilation Mode |
| |
| |
| The basic function of @cite{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 @cite{gnatchop}. |
| |
| However, using a special option to activate 'compilation mode', |
| @cite{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 @cite{gnatchop} is given a file that consists of |
| only configuration pragmas, then this file is appended to the |
| @code{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 |
| @code{gnat.adc} file is the representation |
| of a compilation environment. For more information on the |
| @code{gnat.adc} file, see @ref{58,,Handling of Configuration Pragmas}. |
| |
| Second, in compilation mode, if @cite{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, @cite{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 @cite{gnatchop} with the compilation mode |
| switch provides the required behavior, and is for example the mode |
| in which GNAT processes the ACVC tests. |
| |
| @node Command Line for gnatchop,Switches for gnatchop,Operating gnatchop in Compilation Mode,Renaming Files with gnatchop |
| @anchor{gnat_ugn/the_gnat_compilation_model id25}@anchor{73}@anchor{gnat_ugn/the_gnat_compilation_model command-line-for-gnatchop}@anchor{74} |
| @subsubsection Command Line for @cite{gnatchop} |
| |
| |
| The @cite{gnatchop} command has the form: |
| |
| @example |
| $ gnatchop switches file_name [file_name ...] |
| [directory] |
| @end example |
| |
| 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, @cite{gnatchop} generates one output file in |
| the current directory for each unit in each of the files. |
| |
| @cite{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 @code{hellofiles} containing |
| |
| @example |
| procedure Hello; |
| |
| with Ada.Text_IO; use Ada.Text_IO; |
| procedure Hello is |
| begin |
| Put_Line ("Hello"); |
| end Hello; |
| @end example |
| |
| the command |
| |
| @example |
| $ gnatchop hellofiles |
| @end example |
| |
| generates two files in the current directory, one called |
| @code{hello.ads} containing the single line that is the procedure spec, |
| and the other called @code{hello.adb} containing the remaining text. The |
| original file is not affected. The generated files can be compiled in |
| the normal manner. |
| |
| When gnatchop is invoked on a file that is empty or that contains only empty |
| lines and/or comments, gnatchop will not fail, but will not produce any |
| new sources. |
| |
| For example, given a |
| file called @code{toto.txt} containing |
| |
| @example |
| -- Just a comment |
| @end example |
| |
| the command |
| |
| @example |
| $ gnatchop toto.txt |
| @end example |
| |
| will not produce any new file and will result in the following warnings: |
| |
| @example |
| toto.txt:1:01: warning: empty file, contains no compilation units |
| no compilation units found |
| no source files written |
| @end example |
| |
| @node Switches for gnatchop,Examples of gnatchop Usage,Command Line for gnatchop,Renaming Files with gnatchop |
| @anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatchop}@anchor{75}@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{76} |
| @subsubsection Switches for @cite{gnatchop} |
| |
| |
| @emph{gnatchop} recognizes the following switches: |
| |
| @geindex --version (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{--version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{--help} |
| |
| If @emph{--version} was not used, display usage, then exit disregarding |
| all other options. |
| @end table |
| |
| @geindex -c (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{-c} |
| |
| Causes @cite{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. |
| |
| @item @code{-gnat@emph{xxx}} |
| |
| This passes the given @emph{-gnat`xxx*` 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 @cite{gnatchop} to |
| process a source file that uses Latin-2 coding for identifiers. |
| |
| @item @code{-h} |
| |
| Causes @cite{gnatchop} to generate a brief help summary to the standard |
| output file showing usage information. |
| @end table |
| |
| @geindex -k (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{-k@emph{mm}} |
| |
| Limit generated file names to the specified number @cite{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 @emph{-k} and the numeric value. The numeric |
| value may be omitted in which case a default of @emph{-k8}, |
| suitable for use |
| with DOS-like file systems, is used. If no @emph{-k} switch |
| is present then |
| there is no limit on the length of file names. |
| @end table |
| |
| @geindex -p (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{-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 environment where |
| @cite{gnatchop} is used as part of a standard build process. |
| @end table |
| |
| @geindex -q (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{-q} |
| |
| Causes output of informational messages indicating the set of generated |
| files to be suppressed. Warnings and error messages are unaffected. |
| @end table |
| |
| @geindex -r (gnatchop) |
| |
| @geindex Source_Reference pragmas |
| |
| |
| @table @asis |
| |
| @item @code{-r} |
| |
| Generate @cite{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 |
| @cite{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 @emph{-g} switch of @emph{gcc} or @emph{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 @cite{Source_Reference} |
| pragma referencing a third file, then gnatchop respects |
| this pragma, and the generated @cite{Source_Reference} pragmas |
| in the chopped file refer to the original file, with appropriate |
| line numbers. This is particularly useful when @cite{gnatchop} |
| is used in conjunction with @cite{gnatprep} to compile files that |
| contain preprocessing statements and multiple units. |
| @end table |
| |
| @geindex -v (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{-v} |
| |
| Causes @cite{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. |
| @end table |
| |
| @geindex -w (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{-w} |
| |
| Overwrite existing file names. Normally @cite{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. |
| @end table |
| |
| @geindex --GCC= (gnatchop) |
| |
| |
| @table @asis |
| |
| @item @code{--GCC=@emph{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. |
| @end table |
| |
| @node Examples of gnatchop Usage,,Switches for gnatchop,Renaming Files with gnatchop |
| @anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{77}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{78} |
| @subsubsection Examples of @cite{gnatchop} Usage |
| |
| |
| @example |
| $ gnatchop -w hello_s.ada prerelease/files |
| @end example |
| |
| Chops the source file @code{hello_s.ada}. The output files will be |
| placed in the directory @code{prerelease/files}, |
| overwriting any |
| files with matching names in that directory (no files in the current |
| directory are modified). |
| |
| @example |
| $ gnatchop archive |
| @end example |
| |
| Chops the source file @code{archive} |
| into the current directory. One |
| useful application of @cite{gnatchop} is in sending sets of sources |
| around, for example in email messages. The required sources are simply |
| concatenated (for example, using a Unix @cite{cat} |
| command), and then |
| @emph{gnatchop} is used at the other end to reconstitute the original |
| file names. |
| |
| @example |
| $ gnatchop file1 file2 file3 direc |
| @end example |
| |
| Chops all units in files @code{file1}, @code{file2}, @code{file3}, placing |
| the resulting files in the directory @code{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 |
| @emph{-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. |
| |
| @node Configuration Pragmas,Generating Object Files,File Naming Topics and Utilities,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{79}@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{16} |
| @section Configuration Pragmas |
| |
| |
| @geindex Configuration pragmas |
| |
| @geindex Pragmas |
| @geindex configuration |
| |
| Configuration pragmas include those pragmas described as |
| such in the Ada Reference Manual, as well as |
| implementation-dependent pragmas that are configuration pragmas. |
| See the @cite{Implementation_Defined_Pragmas} chapter in the |
| @cite{GNAT_Reference_Manual} for details on these |
| additional GNAT-specific configuration pragmas. |
| Most notably, the pragma @cite{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: |
| |
| @example |
| Ada_83 |
| Ada_95 |
| Ada_05 |
| Ada_2005 |
| Ada_12 |
| Ada_2012 |
| Allow_Integer_Address |
| Annotate |
| Assertion_Policy |
| Assume_No_Invalid_Values |
| C_Pass_By_Copy |
| Check_Name |
| Check_Policy |
| Compile_Time_Error |
| Compile_Time_Warning |
| Compiler_Unit |
| Component_Alignment |
| Convention_Identifier |
| Debug_Policy |
| Detect_Blocking |
| Default_Storage_Pool |
| Discard_Names |
| Elaboration_Checks |
| Eliminate |
| Extend_System |
| Extensions_Allowed |
| External_Name_Casing |
| Fast_Math |
| Favor_Top_Level |
| Float_Representation |
| Implicit_Packing |
| Initialize_Scalars |
| Interrupt_State |
| License |
| Locking_Policy |
| Long_Float |
| No_Run_Time |
| No_Strict_Aliasing |
| Normalize_Scalars |
| Optimize_Alignment |
| Persistent_BSS |
| Polling |
| Priority_Specific_Dispatching |
| Profile |
| Profile_Warnings |
| Propagate_Exceptions |
| Queuing_Policy |
| Ravenscar |
| Restricted_Run_Time |
| Restrictions |
| Restrictions_Warnings |
| Reviewable |
| Short_Circuit_And_Or |
| Source_File_Name |
| Source_File_Name_Project |
| SPARK_Mode |
| Style_Checks |
| Suppress |
| Suppress_Exception_Locations |
| Task_Dispatching_Policy |
| Universal_Data |
| Unsuppress |
| Use_VADS_Size |
| Validity_Checks |
| Warnings |
| Wide_Character_Encoding |
| @end example |
| |
| @menu |
| * Handling of Configuration Pragmas:: |
| * The Configuration Pragmas Files:: |
| |
| @end menu |
| |
| @node Handling of Configuration Pragmas,The Configuration Pragmas Files,,Configuration Pragmas |
| @anchor{gnat_ugn/the_gnat_compilation_model id29}@anchor{7a}@anchor{gnat_ugn/the_gnat_compilation_model handling-of-configuration-pragmas}@anchor{58} |
| @subsection Handling of Configuration Pragmas |
| |
| |
| Configuration pragmas may either appear at the start of a compilation |
| unit, or they can appear in a configuration pragma file to apply to |
| all compilations performed in a given compilation environment. |
| |
| GNAT also provides the @cite{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 @ref{71,,Operating gnatchop in Compilation Mode} for details. |
| However, for most purposes, it will be more convenient to edit the |
| @code{gnat.adc} file that contains configuration pragmas directly, |
| as described in the following section. |
| |
| In the case of @cite{Restrictions} pragmas appearing as configuration |
| pragmas in individual compilation units, the exact handling depends on |
| the type of restriction. |
| |
| Restrictions that require partition-wide consistency (like |
| @cite{No_Tasking}) are |
| recognized wherever they appear |
| and can be freely inherited, e.g. from a @emph{with}ed unit to the @emph{with}ing |
| unit. This makes sense since the binder will in any case insist on seeing |
| consistent use, so any unit not conforming to any restrictions that are |
| anywhere in the partition will be rejected, and you might as well find |
| that out at compile time rather than at bind time. |
| |
| For restrictions that do not require partition-wide consistency, e.g. |
| SPARK or No_Implementation_Attributes, in general the restriction applies |
| only to the unit in which the pragma appears, and not to any other units. |
| |
| The exception is No_Elaboration_Code which always applies to the entire |
| object file from a compilation, i.e. to the body, spec, and all subunits. |
| This restriction can be specified in a configuration pragma file, or it |
| can be on the body and/or the spec (in eithe case it applies to all the |
| relevant units). It can appear on a subunit only if it has previously |
| appeared in the body of spec. |
| |
| @node The Configuration Pragmas Files,,Handling of Configuration Pragmas,Configuration Pragmas |
| @anchor{gnat_ugn/the_gnat_compilation_model the-configuration-pragmas-files}@anchor{7b}@anchor{gnat_ugn/the_gnat_compilation_model id30}@anchor{7c} |
| @subsection The Configuration Pragmas Files |
| |
| |
| @geindex gnat.adc |
| |
| 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 @code{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 @emph{-gnatA} is used, @code{gnat.adc} is not |
| considered. When taken into account, @code{gnat.adc} is added to the |
| dependencies, so that if @code{gnat.adc} is modified later, an invocation of |
| @emph{gnatmake} will recompile the source. |
| |
| Configuration pragmas may be entered into the @code{gnat.adc} file |
| either by running @cite{gnatchop} on a source file that consists only of |
| configuration pragmas, or more conveniently by direct editing of the |
| @code{gnat.adc} file, which is a standard format source file. |
| |
| Besides @code{gnat.adc}, additional files containing configuration |
| pragmas may be applied to the current compilation using the switch |
| @code{-gnatec=@emph{path}} where @cite{path} must designate an existing file that |
| contains only configuration pragmas. These configuration pragmas are |
| in addition to those found in @code{gnat.adc} (provided @code{gnat.adc} |
| is present and switch @emph{-gnatA} is not used). |
| |
| It is allowable to specify several switches @emph{-gnatec=}, all of which |
| will be taken into account. |
| |
| Files containing configuration pragmas specified with switches |
| @emph{-gnatec=} are added to the dependencies, unless they are |
| temporary files. A file is considered temporary if its name ends in |
| @code{.tmp} or @code{.TMP}. Certain tools follow this naming |
| convention because they pass information to @emph{gcc} via |
| temporary files that are immediately deleted; it doesn't make sense to |
| depend on a file that no longer exists. Such tools include |
| @emph{gprbuild}, @emph{gnatmake}, and @emph{gnatcheck}. |
| |
| If you are using project file, a separate mechanism is provided using |
| project attributes, see @ref{7d,,Specifying Configuration Pragmas} for more |
| details. |
| |
| @node Generating Object Files,Source Dependencies,Configuration Pragmas,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model generating-object-files}@anchor{42}@anchor{gnat_ugn/the_gnat_compilation_model id31}@anchor{7e} |
| @section 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: |
| |
| |
| @itemize * |
| |
| @item |
| If a package spec has no body, compile the package spec to produce the |
| object file for the package. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| @end itemize |
| |
| @geindex Subunits |
| |
| |
| @itemize * |
| |
| @item |
| 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. |
| |
| @item |
| 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). |
| |
| @geindex Generics |
| |
| @item |
| 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. |
| @end itemize |
| |
| 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 |
| @code{.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 @emph{-gnatc} switch. |
| |
| @node Source Dependencies,The Ada Library Information Files,Generating Object Files,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model id32}@anchor{7f}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{43} |
| @section 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 |
| @cite{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: |
| |
| |
| @itemize * |
| |
| @item |
| If a file being compiled @emph{with}s a unit @cite{X}, the object file |
| depends on the file containing the spec of unit @cite{X}. This includes |
| files that are @emph{with}ed implicitly either because they are parents |
| of @emph{with}ed child units or they are run-time units required by the |
| language constructs used in a particular unit. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| @end itemize |
| |
| @geindex Inline |
| |
| @geindex -gnatn switch |
| |
| |
| @itemize * |
| |
| @item |
| If a file being compiled contains a call to a subprogram for which |
| pragma @cite{Inline} applies and inlining is activated with the |
| @emph{-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. |
| |
| @geindex -gnatN switch |
| |
| The use of @emph{-gnatN} activates inlining optimization |
| that is performed by the front end of the compiler. This inlining does |
| not require that the code generation be optimized. Like @emph{-gnatn}, |
| the use of this switch generates additional dependencies. |
| |
| When using a gcc-based back end (in practice this means using any version |
| of GNAT other than for the JVM, .NET or GNAAMP platforms), then the use of |
| @emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred. |
| Historically front end inlining was more extensive than the gcc back end |
| inlining, but that is no longer the case. |
| |
| @item |
| If an object file @code{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 @code{O}. |
| |
| @item |
| The object file for a parent unit depends on all its subunit body files. |
| |
| @item |
| 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 @cite{A} @emph{with}s |
| unit @cite{B}, whose elaboration calls an inlined procedure in package |
| @cite{C}, the object file for unit @cite{A} will depend on the body of |
| @cite{C}, in file @code{c.adb}. |
| |
| The set of dependent files described by these rules includes all the |
| files on which the unit is semantically dependent, as dictated by the |
| Ada language standard. However, it is a superset of what the |
| standard 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 @cite{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 @emph{gnatmake}. |
| @end itemize |
| |
| @node The Ada Library Information Files,Binding an Ada Program,Source Dependencies,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model id33}@anchor{80}@anchor{gnat_ugn/the_gnat_compilation_model the-ada-library-information-files}@anchor{44} |
| @section The Ada Library Information Files |
| |
| |
| @geindex Ada Library Information files |
| |
| @geindex ALI files |
| |
| Each compilation actually generates two output files. The first of these |
| is the normal object file that has a @code{.o} extension. The second is a |
| text file containing full dependency information. It has the same |
| name as the source file, but an @code{.ali} extension. |
| This file is known as the Ada Library Information (@code{ALI}) file. |
| The following information is contained in the @code{ALI} file. |
| |
| |
| @itemize * |
| |
| @item |
| Version information (indicates which version of GNAT was used to compile |
| the unit(s) in question) |
| |
| @item |
| Main program information (including priority and time slice settings, |
| as well as the wide character encoding used during compilation). |
| |
| @item |
| List of arguments used in the @emph{gcc} command for the compilation |
| |
| @item |
| Attributes of the unit, including configuration pragmas used, an indication |
| of whether the compilation was successful, exception model used etc. |
| |
| @item |
| A list of relevant restrictions applying to the unit (used for consistency) |
| checking. |
| |
| @item |
| Categorization information (e.g., use of pragma @cite{Pure}). |
| |
| @item |
| Information on all @emph{with}ed units, including presence of |
| Elaborate` or @cite{Elaborate_All} pragmas. |
| |
| @item |
| Information from any @cite{Linker_Options} pragmas used in the unit |
| |
| @item |
| Information on the use of @cite{Body_Version} or @cite{Version} |
| attributes in the unit. |
| |
| @item |
| 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. |
| |
| @item |
| Cross-reference data. Contains information on all entities referenced |
| in the unit. Used by tools like @cite{gnatxref} and @cite{gnatfind} to |
| provide cross-reference information. |
| @end itemize |
| |
| For a full detailed description of the format of the @code{ALI} file, |
| see the source of the body of unit @cite{Lib.Writ}, contained in file |
| @code{lib-writ.adb} in the GNAT compiler sources. |
| |
| @node Binding an Ada Program,GNAT and Libraries,The Ada Library Information Files,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model id34}@anchor{81}@anchor{gnat_ugn/the_gnat_compilation_model binding-an-ada-program}@anchor{45} |
| @section 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 @code{b~xxx}.adb` (with the corresponding spec |
| @code{b~xxx}.ads`) where @cite{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. |
| |
| @node GNAT and Libraries,Conditional Compilation,Binding an Ada Program,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model gnat-and-libraries}@anchor{17}@anchor{gnat_ugn/the_gnat_compilation_model id35}@anchor{82} |
| @section GNAT and Libraries |
| |
| |
| @geindex Library building and using |
| |
| This chapter describes how to build and use libraries with GNAT, and also shows |
| how to recompile the GNAT run-time library. You should be familiar with the |
| Project Manager facility (@ref{b,,GNAT Project Manager}) before reading this |
| chapter. |
| |
| @menu |
| * Introduction to Libraries in GNAT:: |
| * General Ada Libraries:: |
| * Stand-alone Ada Libraries:: |
| * Rebuilding the GNAT Run-Time Library:: |
| |
| @end menu |
| |
| @node Introduction to Libraries in GNAT,General Ada Libraries,,GNAT and Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model introduction-to-libraries-in-gnat}@anchor{83}@anchor{gnat_ugn/the_gnat_compilation_model id36}@anchor{84} |
| @subsection Introduction to Libraries in GNAT |
| |
| |
| A library is, conceptually, a collection of objects which does not have its |
| own main thread of execution, but rather provides certain services to the |
| applications that use it. A library can be either statically linked with the |
| application, in which case its code is directly included in the application, |
| or, on platforms that support it, be dynamically linked, in which case |
| its code is shared by all applications making use of this library. |
| |
| GNAT supports both types of libraries. |
| In the static case, the compiled code can be provided in different ways. The |
| simplest approach is to provide directly the set of objects resulting from |
| compilation of the library source files. Alternatively, you can group the |
| objects into an archive using whatever commands are provided by the operating |
| system. For the latter case, the objects are grouped into a shared library. |
| |
| In the GNAT environment, a library has three types of components: |
| |
| |
| @itemize * |
| |
| @item |
| Source files, |
| |
| @item |
| @code{ALI} files (see @ref{44,,The Ada Library Information Files}), and |
| |
| @item |
| Object files, an archive or a shared library. |
| @end itemize |
| |
| A GNAT library may expose all its source files, which is useful for |
| documentation purposes. Alternatively, it may expose only the units needed by |
| an external user to make use of the library. That is to say, the specs |
| reflecting the library services along with all the units needed to compile |
| those specs, which can include generic bodies or any body implementing an |
| inlined routine. In the case of @emph{stand-alone libraries} those exposed |
| units are called @emph{interface units} (@ref{85,,Stand-alone Ada Libraries}). |
| |
| All compilation units comprising an application, including those in a library, |
| need to be elaborated in an order partially defined by Ada's semantics. GNAT |
| computes the elaboration order from the @code{ALI} files and this is why they |
| constitute a mandatory part of GNAT libraries. |
| @emph{Stand-alone libraries} are the exception to this rule because a specific |
| library elaboration routine is produced independently of the application(s) |
| using the library. |
| |
| @node General Ada Libraries,Stand-alone Ada Libraries,Introduction to Libraries in GNAT,GNAT and Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model general-ada-libraries}@anchor{86}@anchor{gnat_ugn/the_gnat_compilation_model id37}@anchor{87} |
| @subsection General Ada Libraries |
| |
| |
| @menu |
| * Building a library:: |
| * Installing a library:: |
| * Using a library:: |
| |
| @end menu |
| |
| @node Building a library,Installing a library,,General Ada Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model building-a-library}@anchor{88}@anchor{gnat_ugn/the_gnat_compilation_model id38}@anchor{89} |
| @subsubsection Building a library |
| |
| |
| The easiest way to build a library is to use the Project Manager, |
| which supports a special type of project called a @emph{Library Project} |
| (see @ref{8a,,Library Projects}). |
| |
| A project is considered a library project, when two project-level attributes |
| are defined in it: @cite{Library_Name} and @cite{Library_Dir}. In order to |
| control different aspects of library configuration, additional optional |
| project-level attributes can be specified: |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{Library_Kind} |
| |
| This attribute controls whether the library is to be static or dynamic |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{Library_Version} |
| |
| This attribute specifies the library version; this value is used |
| during dynamic linking of shared libraries to determine if the currently |
| installed versions of the binaries are compatible. |
| @end table |
| |
| @item |
| @emph{Library_Options} |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{Library_GCC} |
| |
| These attributes specify additional low-level options to be used during |
| library generation, and redefine the actual application used to generate |
| library. |
| @end table |
| @end itemize |
| |
| The GNAT Project Manager takes full care of the library maintenance task, |
| including recompilation of the source files for which objects do not exist |
| or are not up to date, assembly of the library archive, and installation of |
| the library (i.e., copying associated source, object and @code{ALI} files |
| to the specified location). |
| |
| Here is a simple library project file: |
| |
| @example |
| project My_Lib is |
| for Source_Dirs use ("src1", "src2"); |
| for Object_Dir use "obj"; |
| for Library_Name use "mylib"; |
| for Library_Dir use "lib"; |
| for Library_Kind use "dynamic"; |
| end My_lib; |
| @end example |
| |
| and the compilation command to build and install the library: |
| |
| @example |
| $ gnatmake -Pmy_lib |
| @end example |
| |
| It is not entirely trivial to perform manually all the steps required to |
| produce a library. We recommend that you use the GNAT Project Manager |
| for this task. In special cases where this is not desired, the necessary |
| steps are discussed below. |
| |
| There are various possibilities for compiling the units that make up the |
| library: for example with a Makefile (@ref{21,,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 |
| @emph{gnatmake}, which will ensure that all necessary objects are built. |
| |
| After this task is accomplished, you should follow the standard procedure |
| of the underlying operating system to produce the static or shared library. |
| |
| Here is an example of such a dummy program: |
| |
| @example |
| with My_Lib.Service1; |
| with My_Lib.Service2; |
| with My_Lib.Service3; |
| procedure My_Lib_Dummy is |
| begin |
| null; |
| end; |
| @end example |
| |
| Here are the generic commands that will build an archive or a shared library. |
| |
| @example |
| # 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 |
| |
| # remove the object files that are now in the library |
| $ rm *.o |
| |
| # Make the ALI files read-only so that gnatmake will not try to |
| # regenerate the objects that are in the library |
| $ chmod -w *.ali |
| @end example |
| |
| Please note that the library must have a name of the form @code{lib@emph{xxx}.a} |
| or @code{lib@emph{xxx}.so} (or @code{lib@emph{xxx}.dll} on Windows) in order to |
| be accessed by the directive @code{-l@emph{xxx}} at link time. |
| |
| @node Installing a library,Using a library,Building a library,General Ada Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model installing-a-library}@anchor{8b}@anchor{gnat_ugn/the_gnat_compilation_model id39}@anchor{8c} |
| @subsubsection Installing a library |
| |
| |
| @geindex ADA_PROJECT_PATH |
| |
| @geindex GPR_PROJECT_PATH |
| |
| If you use project files, library installation is part of the library build |
| process (@ref{8d,,Installing a library with project files}). |
| |
| When project files are not an option, it is also possible, but not recommended, |
| to install the library so that the sources needed to use the library are on the |
| Ada source path and the ALI files & libraries be on the Ada Object path (see |
| @ref{8e,,Search Paths and the Run-Time Library (RTL)}. Alternatively, the system |
| administrator can place general-purpose libraries in the default compiler |
| paths, by specifying the libraries' location in the configuration files |
| @code{ada_source_path} and @code{ada_object_path}. These configuration files |
| 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: |
| |
| @example |
| $ gcc -v |
| @end example |
| |
| The configuration files mentioned above have a simple format: each line |
| 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. |
| |
| The files @code{ada_source_path} and @code{ada_object_path} might not be |
| present in a |
| GNAT installation, in which case, GNAT will look for its run-time library in |
| the directories @code{adainclude} (for the sources) and @code{adalib} (for the |
| objects and @code{ALI} files). When the files exist, the compiler does not |
| look in @code{adainclude} and @code{adalib}, and thus the |
| @code{ada_source_path} file |
| must contain the location for the GNAT run-time sources (which can simply |
| be @code{adainclude}). In the same way, the @code{ada_object_path} file must |
| contain the location for the GNAT run-time objects (which can simply |
| be @code{adalib}). |
| |
| You can also specify a new default path to the run-time library at compilation |
| time with the switch @emph{--RTS=rts-path}. You can thus choose / change |
| the run-time library you want your program to be compiled with. This switch is |
| recognized by @emph{gcc}, @emph{gnatmake}, @emph{gnatbind}, |
| @emph{gnatls}, @emph{gnatfind} and @emph{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. |
| |
| @node Using a library,,Installing a library,General Ada Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model using-a-library}@anchor{8f}@anchor{gnat_ugn/the_gnat_compilation_model id40}@anchor{90} |
| @subsubsection Using a library |
| |
| |
| Once again, the project facility greatly simplifies the use of |
| libraries. In this context, using a library is just a matter of adding a |
| @emph{with} clause in the user project. For instance, to make use of the |
| library @cite{My_Lib} shown in examples in earlier sections, you can |
| write: |
| |
| @example |
| with "my_lib"; |
| project My_Proj is |
| ... |
| end My_Proj; |
| @end example |
| |
| Even if you have a third-party, non-Ada library, you can still use GNAT's |
| Project Manager facility to provide a wrapper for it. For example, the |
| following project, when @emph{with}ed by your main project, will link with the |
| third-party library @code{liba.a}: |
| |
| @example |
| project Liba is |
| for Externally_Built use "true"; |
| for Source_Files use (); |
| for Library_Dir use "lib"; |
| for Library_Name use "a"; |
| for Library_Kind use "static"; |
| end Liba; |
| @end example |
| |
| This is an alternative to the use of @cite{pragma Linker_Options}. It is |
| especially interesting in the context of systems with several interdependent |
| static libraries where finding a proper linker order is not easy and best be |
| left to the tools having visibility over project dependence information. |
| |
| In order to use an Ada library manually, you need to make sure that this |
| library is on both your source and object path |
| (see @ref{8e,,Search Paths and the Run-Time Library (RTL)} |
| and @ref{91,,Search Paths for gnatbind}). Furthermore, when the objects are grouped |
| in an archive or a shared library, you need to specify the desired |
| library at link time. |
| |
| For example, you can use the library @code{mylib} installed in |
| @code{/dir/my_lib_src} and @code{/dir/my_lib_obj} with the following commands: |
| |
| @example |
| $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\ |
| -largs -lmy_lib |
| @end example |
| |
| This can be expressed more simply: |
| |
| @example |
| $ gnatmake my_appl |
| @end example |
| |
| when the following conditions are met: |
| |
| |
| @itemize * |
| |
| @item |
| @code{/dir/my_lib_src} has been added by the user to the environment |
| variable |
| @geindex ADA_INCLUDE_PATH |
| @geindex environment variable; ADA_INCLUDE_PATH |
| @code{ADA_INCLUDE_PATH}, or by the administrator to the file |
| @code{ada_source_path} |
| |
| @item |
| @code{/dir/my_lib_obj} has been added by the user to the environment |
| variable |
| @geindex ADA_OBJECTS_PATH |
| @geindex environment variable; ADA_OBJECTS_PATH |
| @code{ADA_OBJECTS_PATH}, or by the administrator to the file |
| @code{ada_object_path} |
| |
| @item |
| a pragma @cite{Linker_Options} has been added to one of the sources. |
| For example: |
| |
| @example |
| pragma Linker_Options ("-lmy_lib"); |
| @end example |
| @end itemize |
| |
| Note that you may also load a library dynamically at |
| run time given its filename, as illustrated in the GNAT @code{plugins} example |
| in the directory @code{share/examples/gnat/plugins} within the GNAT |
| install area. |
| |
| @node Stand-alone Ada Libraries,Rebuilding the GNAT Run-Time Library,General Ada Libraries,GNAT and Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model stand-alone-ada-libraries}@anchor{85}@anchor{gnat_ugn/the_gnat_compilation_model id41}@anchor{92} |
| @subsection Stand-alone Ada Libraries |
| |
| |
| @geindex Stand-alone libraries |
| |
| @menu |
| * Introduction to Stand-alone Libraries:: |
| * Building a Stand-alone Library:: |
| * Creating a Stand-alone Library to be used in a non-Ada context:: |
| * Restrictions in Stand-alone Libraries:: |
| |
| @end menu |
| |
| @node Introduction to Stand-alone Libraries,Building a Stand-alone Library,,Stand-alone Ada Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model introduction-to-stand-alone-libraries}@anchor{93}@anchor{gnat_ugn/the_gnat_compilation_model id42}@anchor{94} |
| @subsubsection Introduction to Stand-alone Libraries |
| |
| |
| A Stand-alone Library (abbreviated 'SAL') is a library that contains the |
| necessary code to |
| elaborate the Ada units that are included in the library. In contrast with |
| an ordinary library, which consists of all sources, objects and @code{ALI} |
| files of the |
| library, a SAL may specify a restricted subset of compilation units |
| to serve as a library interface. In this case, the fully |
| self-sufficient set of files will normally consist of an objects |
| archive, the sources of interface units' specs, and the @code{ALI} |
| files of interface units. |
| If an interface spec contains a generic unit or an inlined subprogram, |
| the body's |
| source must also be provided; if the units that must be provided in the source |
| form depend on other units, the source and @code{ALI} files of those must |
| also be provided. |
| |
| The main purpose of a SAL is to minimize the recompilation overhead of client |
| applications when a new version of the library is installed. Specifically, |
| if the interface sources have not changed, client applications do not need to |
| be recompiled. If, furthermore, a SAL is provided in the shared form and its |
| version, controlled by @cite{Library_Version} attribute, is not changed, |
| then the clients do not need to be relinked. |
| |
| SALs also allow the library providers to minimize the amount of library source |
| text exposed to the clients. Such 'information hiding' might be useful or |
| necessary for various reasons. |
| |
| Stand-alone libraries are also well suited to be used in an executable whose |
| main routine is not written in Ada. |
| |
| @node Building a Stand-alone Library,Creating a Stand-alone Library to be used in a non-Ada context,Introduction to Stand-alone Libraries,Stand-alone Ada Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model id43}@anchor{95}@anchor{gnat_ugn/the_gnat_compilation_model building-a-stand-alone-library}@anchor{96} |
| @subsubsection Building a Stand-alone Library |
| |
| |
| GNAT's Project facility provides a simple way of building and installing |
| stand-alone libraries; see @ref{97,,Stand-alone Library Projects}. |
| To be a Stand-alone Library Project, in addition to the two attributes |
| that make a project a Library Project (@cite{Library_Name} and |
| @cite{Library_Dir}; see @ref{8a,,Library Projects}), the attribute |
| @cite{Library_Interface} must be defined. For example: |
| |
| @example |
| for Library_Dir use "lib_dir"; |
| for Library_Name use "dummy"; |
| for Library_Interface use ("int1", "int1.child"); |
| @end example |
| |
| Attribute @cite{Library_Interface} has a non-empty string list value, |
| each string in the list designating a unit contained in an immediate source |
| of the project file. |
| |
| When a Stand-alone Library is built, first the binder is invoked to build |
| a package whose name depends on the library name |
| (@code{b~dummy.ads/b} in the example above). |
| This binder-generated package includes initialization and |
| finalization procedures whose |
| names depend on the library name (@cite{dummyinit} and @cite{dummyfinal} |
| in the example |
| above). The object corresponding to this package is included in the library. |
| |
| You must ensure timely (e.g., prior to any use of interfaces in the SAL) |
| calling of these procedures if a static SAL is built, or if a shared SAL |
| is built |
| with the project-level attribute @cite{Library_Auto_Init} set to |
| @cite{"false"}. |
| |
| For a Stand-Alone Library, only the @code{ALI} files of the Interface Units |
| (those that are listed in attribute @cite{Library_Interface}) are copied to |
| the Library Directory. As a consequence, only the Interface Units may be |
| imported from Ada units outside of the library. If other units are imported, |
| the binding phase will fail. |
| |
| It is also possible to build an encapsulated library where not only |
| the code to elaborate and finalize the library is embedded but also |
| ensuring that the library is linked only against static |
| libraries. So an encapsulated library only depends on system |
| libraries, all other code, including the GNAT runtime, is embedded. To |
| build an encapsulated library the attribute |
| @cite{Library_Standalone} must be set to @cite{encapsulated}: |
| |
| @example |
| for Library_Dir use "lib_dir"; |
| for Library_Name use "dummy"; |
| for Library_Kind use "dynamic"; |
| for Library_Interface use ("int1", "int1.child"); |
| for Library_Standalone use "encapsulated"; |
| @end example |
| |
| The default value for this attribute is @cite{standard} in which case |
| a stand-alone library is built. |
| |
| The attribute @cite{Library_Src_Dir} may be specified for a |
| Stand-Alone Library. @cite{Library_Src_Dir} is a simple attribute that has a |
| single string value. Its value must be the path (absolute or relative to the |
| project directory) of an existing directory. This directory cannot be the |
| object directory or one of the source directories, but it can be the same as |
| the library directory. The sources of the Interface |
| Units of the library that are needed by an Ada client of the library will be |
| copied to the designated directory, called the Interface Copy directory. |
| These sources include the specs of the Interface Units, but they may also |
| include bodies and subunits, when pragmas @cite{Inline} or @cite{Inline_Always} |
| are used, or when there is a generic unit in the spec. Before the sources |
| are copied to the Interface Copy directory, an attempt is made to delete all |
| files in the Interface Copy directory. |
| |
| Building stand-alone libraries by hand is somewhat tedious, but for those |
| occasions when it is necessary here are the steps that you need to perform: |
| |
| |
| @itemize * |
| |
| @item |
| Compile all library sources. |
| |
| @item |
| Invoke the binder with the switch @emph{-n} (No Ada main program), |
| with all the @code{ALI} files of the interfaces, and |
| with the switch @emph{-L} to give specific names to the @cite{init} |
| and @cite{final} procedures. For example: |
| |
| @example |
| $ gnatbind -n int1.ali int2.ali -Lsal1 |
| @end example |
| |
| @item |
| Compile the binder generated file: |
| |
| @example |
| $ gcc -c b~int2.adb |
| @end example |
| |
| @item |
| Link the dynamic library with all the necessary object files, |
| indicating to the linker the names of the @cite{init} (and possibly |
| @cite{final}) procedures for automatic initialization (and finalization). |
| The built library should be placed in a directory different from |
| the object directory. |
| |
| @item |
| Copy the @cite{ALI} files of the interface to the library directory, |
| add in this copy an indication that it is an interface to a SAL |
| (i.e., add a word @emph{SL} on the line in the @code{ALI} file that starts |
| with letter 'P') and make the modified copy of the @code{ALI} file |
| read-only. |
| @end itemize |
| |
| Using SALs is not different from using other libraries |
| (see @ref{8f,,Using a library}). |
| |
| @node Creating a Stand-alone Library to be used in a non-Ada context,Restrictions in Stand-alone Libraries,Building a Stand-alone Library,Stand-alone Ada Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model creating-a-stand-alone-library-to-be-used-in-a-non-ada-context}@anchor{98}@anchor{gnat_ugn/the_gnat_compilation_model id44}@anchor{99} |
| @subsubsection Creating a Stand-alone Library to be used in a non-Ada context |
| |
| |
| It is easy to adapt the SAL build procedure discussed above for use of a SAL in |
| a non-Ada context. |
| |
| The only extra step required is to ensure that library interface subprograms |
| are compatible with the main program, by means of @cite{pragma Export} |
| or @cite{pragma Convention}. |
| |
| Here is an example of simple library interface for use with C main program: |
| |
| @example |
| package My_Package 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 My_Package; |
| @end example |
| |
| On the foreign language side, you must provide a 'foreign' view of the |
| library interface; remember that it should contain elaboration routines in |
| addition to interface subprograms. |
| |
| The example below shows the content of @cite{mylib_interface.h} (note |
| that there is no rule for the naming of this file, any name can be used) |
| |
| @example |
| /* 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); |
| @end example |
| |
| Libraries built as explained above can be used from any program, provided |
| that the elaboration procedures (named @cite{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 a C program that uses the @cite{mylib} library. |
| |
| @example |
| #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; |
| @} |
| @end example |
| |
| Note that invoking any library finalization procedure generated by |
| @cite{gnatbind} shuts down the Ada run-time environment. |
| Consequently, the |
| finalization of all Ada libraries must be performed at the end of the program. |
| No call to these libraries or to the Ada run-time library should be made |
| after the finalization phase. |
| |
| Note also that special care must be taken with multi-tasks |
| applications. The initialization and finalization routines are not |
| protected against concurrent access. If such requirement is needed it |
| must be ensured at the application level using a specific operating |
| system services like a mutex or a critical-section. |
| |
| @node Restrictions in Stand-alone Libraries,,Creating a Stand-alone Library to be used in a non-Ada context,Stand-alone Ada Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model id45}@anchor{9a}@anchor{gnat_ugn/the_gnat_compilation_model restrictions-in-stand-alone-libraries}@anchor{9b} |
| @subsubsection Restrictions in Stand-alone Libraries |
| |
| |
| The pragmas listed below should be used with caution inside libraries, |
| as they can create incompatibilities with other Ada libraries: |
| |
| |
| @itemize * |
| |
| @item |
| pragma @cite{Locking_Policy} |
| |
| @item |
| pragma @cite{Partition_Elaboration_Policy} |
| |
| @item |
| pragma @cite{Queuing_Policy} |
| |
| @item |
| pragma @cite{Task_Dispatching_Policy} |
| |
| @item |
| pragma @cite{Unreserve_All_Interrupts} |
| @end itemize |
| |
| 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, |
| @cite{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 the exception occurrence mechanism should be |
| enabled or disabled in a consistent manner across all libraries. |
| Otherwise, Program_Error will be raised during the elaboration of the |
| conflicting libraries. |
| |
| If the @cite{Version} or @cite{Body_Version} |
| attributes are used inside a library, then you need to |
| perform a @cite{gnatbind} step that specifies all @code{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. |
| |
| @node Rebuilding the GNAT Run-Time Library,,Stand-alone Ada Libraries,GNAT and Libraries |
| @anchor{gnat_ugn/the_gnat_compilation_model id46}@anchor{9c}@anchor{gnat_ugn/the_gnat_compilation_model rebuilding-the-gnat-run-time-library}@anchor{9d} |
| @subsection Rebuilding the GNAT Run-Time Library |
| |
| |
| @geindex GNAT Run-Time Library |
| @geindex rebuilding |
| |
| @geindex Building the GNAT Run-Time Library |
| |
| @geindex Rebuilding the GNAT Run-Time Library |
| |
| @geindex Run-Time Library |
| @geindex rebuilding |
| |
| 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 @cite{Normalize_Scalars}. A special Makefile called |
| @cite{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: |
| |
| @example |
| $ gnatls -v |
| @end example |
| |
| 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. |
| |
| @geindex Conditional compilation |
| |
| @node Conditional Compilation,Mixed Language Programming,GNAT and Libraries,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model id47}@anchor{9e}@anchor{gnat_ugn/the_gnat_compilation_model conditional-compilation}@anchor{18} |
| @section Conditional Compilation |
| |
| |
| This section presents some guidelines for modeling conditional compilation in Ada and describes the |
| gnatprep preprocessor utility. |
| |
| @geindex Conditional compilation |
| |
| @menu |
| * Modeling Conditional Compilation in Ada:: |
| * Preprocessing with gnatprep:: |
| * Integrated Preprocessing:: |
| |
| @end menu |
| |
| @node Modeling Conditional Compilation in Ada,Preprocessing with gnatprep,,Conditional Compilation |
| @anchor{gnat_ugn/the_gnat_compilation_model modeling-conditional-compilation-in-ada}@anchor{9f}@anchor{gnat_ugn/the_gnat_compilation_model id48}@anchor{a0} |
| @subsection Modeling Conditional Compilation in Ada |
| |
| |
| It is often necessary to arrange for a single source program |
| to serve multiple purposes, where it is compiled in different |
| ways to achieve these different goals. Some examples of the |
| need for this feature are |
| |
| |
| @itemize * |
| |
| @item |
| Adapting a program to a different hardware environment |
| |
| @item |
| Adapting a program to a different target architecture |
| |
| @item |
| Turning debugging features on and off |
| |
| @item |
| Arranging for a program to compile with different compilers |
| @end itemize |
| |
| In C, or C++, the typical approach would be to use the preprocessor |
| that is defined as part of the language. The Ada language does not |
| contain such a feature. This is not an oversight, but rather a very |
| deliberate design decision, based on the experience that overuse of |
| the preprocessing features in C and C++ can result in programs that |
| are extremely difficult to maintain. For example, if we have ten |
| switches that can be on or off, this means that there are a thousand |
| separate programs, any one of which might not even be syntactically |
| correct, and even if syntactically correct, the resulting program |
| might not work correctly. Testing all combinations can quickly become |
| impossible. |
| |
| Nevertheless, the need to tailor programs certainly exists, and in |
| this section we will discuss how this can |
| be achieved using Ada in general, and GNAT in particular. |
| |
| @menu |
| * Use of Boolean Constants:: |
| * Debugging - A Special Case:: |
| * Conditionalizing Declarations:: |
| * Use of Alternative Implementations:: |
| * Preprocessing:: |
| |
| @end menu |
| |
| @node Use of Boolean Constants,Debugging - A Special Case,,Modeling Conditional Compilation in Ada |
| @anchor{gnat_ugn/the_gnat_compilation_model id49}@anchor{a1}@anchor{gnat_ugn/the_gnat_compilation_model use-of-boolean-constants}@anchor{a2} |
| @subsubsection Use of Boolean Constants |
| |
| |
| In the case where the difference is simply which code |
| sequence is executed, the cleanest solution is to use Boolean |
| constants to control which code is executed. |
| |
| @example |
| FP_Initialize_Required : constant Boolean := True; |
| ... |
| if FP_Initialize_Required then |
| ... |
| end if; |
| @end example |
| |
| Not only will the code inside the @cite{if} statement not be executed if |
| the constant Boolean is @cite{False}, but it will also be completely |
| deleted from the program. |
| However, the code is only deleted after the @cite{if} statement |
| has been checked for syntactic and semantic correctness. |
| (In contrast, with preprocessors the code is deleted before the |
| compiler ever gets to see it, so it is not checked until the switch |
| is turned on.) |
| |
| @geindex Preprocessors (contrasted with conditional compilation) |
| |
| Typically the Boolean constants will be in a separate package, |
| something like: |
| |
| @example |
| package Config is |
| FP_Initialize_Required : constant Boolean := True; |
| Reset_Available : constant Boolean := False; |
| ... |
| end Config; |
| @end example |
| |
| The @cite{Config} package exists in multiple forms for the various targets, |
| with an appropriate script selecting the version of @cite{Config} needed. |
| Then any other unit requiring conditional compilation can do a @emph{with} |
| of @cite{Config} to make the constants visible. |
| |
| @node Debugging - A Special Case,Conditionalizing Declarations,Use of Boolean Constants,Modeling Conditional Compilation in Ada |
| @anchor{gnat_ugn/the_gnat_compilation_model debugging-a-special-case}@anchor{a3}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{a4} |
| @subsubsection Debugging - A Special Case |
| |
| |
| A common use of conditional code is to execute statements (for example |
| dynamic checks, or output of intermediate results) under control of a |
| debug switch, so that the debugging behavior can be turned on and off. |
| This can be done using a Boolean constant to control whether the code |
| is active: |
| |
| @example |
| if Debugging then |
| Put_Line ("got to the first stage!"); |
| end if; |
| @end example |
| |
| or |
| |
| @example |
| if Debugging and then Temperature > 999.0 then |
| raise Temperature_Crazy; |
| end if; |
| @end example |
| |
| @geindex pragma Assert |
| |
| Since this is a common case, there are special features to deal with |
| this in a convenient manner. For the case of tests, Ada 2005 has added |
| a pragma @cite{Assert} that can be used for such tests. This pragma is modeled |
| on the @cite{Assert} pragma that has always been available in GNAT, so this |
| feature may be used with GNAT even if you are not using Ada 2005 features. |
| The use of pragma @cite{Assert} is described in the |
| @cite{GNAT_Reference_Manual}, but as an |
| example, the last test could be written: |
| |
| @example |
| pragma Assert (Temperature <= 999.0, "Temperature Crazy"); |
| @end example |
| |
| or simply |
| |
| @example |
| pragma Assert (Temperature <= 999.0); |
| @end example |
| |
| In both cases, if assertions are active and the temperature is excessive, |
| the exception @cite{Assert_Failure} will be raised, with the given string in |
| the first case or a string indicating the location of the pragma in the second |
| case used as the exception message. |
| |
| @geindex pragma Assertion_Policy |
| |
| You can turn assertions on and off by using the @cite{Assertion_Policy} |
| pragma. |
| |
| @geindex -gnata switch |
| |
| This is an Ada 2005 pragma which is implemented in all modes by |
| GNAT. Alternatively, you can use the @emph{-gnata} switch |
| to enable assertions from the command line, which applies to |
| all versions of Ada. |
| |
| @geindex pragma Debug |
| |
| For the example above with the @cite{Put_Line}, the GNAT-specific pragma |
| @cite{Debug} can be used: |
| |
| @example |
| pragma Debug (Put_Line ("got to the first stage!")); |
| @end example |
| |
| If debug pragmas are enabled, the argument, which must be of the form of |
| a procedure call, is executed (in this case, @cite{Put_Line} will be called). |
| Only one call can be present, but of course a special debugging procedure |
| containing any code you like can be included in the program and then |
| called in a pragma @cite{Debug} argument as needed. |
| |
| One advantage of pragma @cite{Debug} over the @cite{if Debugging then} |
| construct is that pragma @cite{Debug} can appear in declarative contexts, |
| such as at the very beginning of a procedure, before local declarations have |
| been elaborated. |
| |
| @geindex pragma Debug_Policy |
| |
| Debug pragmas are enabled using either the @emph{-gnata} switch that also |
| controls assertions, or with a separate Debug_Policy pragma. |
| |
| The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used |
| in Ada 95 and Ada 83 programs as well), and is analogous to |
| pragma @cite{Assertion_Policy} to control assertions. |
| |
| @cite{Assertion_Policy} and @cite{Debug_Policy} are configuration pragmas, |
| and thus they can appear in @code{gnat.adc} if you are not using a |
| project file, or in the file designated to contain configuration pragmas |
| in a project file. |
| They then apply to all subsequent compilations. In practice the use of |
| the @emph{-gnata} switch is often the most convenient method of controlling |
| the status of these pragmas. |
| |
| Note that a pragma is not a statement, so in contexts where a statement |
| sequence is required, you can't just write a pragma on its own. You have |
| to add a @cite{null} statement. |
| |
| @example |
| if ... then |
| ... -- some statements |
| else |
| pragma Assert (Num_Cases < 10); |
| null; |
| end if; |
| @end example |
| |
| @node Conditionalizing Declarations,Use of Alternative Implementations,Debugging - A Special Case,Modeling Conditional Compilation in Ada |
| @anchor{gnat_ugn/the_gnat_compilation_model conditionalizing-declarations}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{a6} |
| @subsubsection Conditionalizing Declarations |
| |
| |
| In some cases it may be necessary to conditionalize declarations to meet |
| different requirements. For example we might want a bit string whose length |
| is set to meet some hardware message requirement. |
| |
| This may be possible using declare blocks controlled |
| by conditional constants: |
| |
| @example |
| if Small_Machine then |
| declare |
| X : Bit_String (1 .. 10); |
| begin |
| ... |
| end; |
| else |
| declare |
| X : Large_Bit_String (1 .. 1000); |
| begin |
| ... |
| end; |
| end if; |
| @end example |
| |
| Note that in this approach, both declarations are analyzed by the |
| compiler so this can only be used where both declarations are legal, |
| even though one of them will not be used. |
| |
| Another approach is to define integer constants, e.g., @cite{Bits_Per_Word}, |
| or Boolean constants, e.g., @cite{Little_Endian}, and then write declarations |
| that are parameterized by these constants. For example |
| |
| @example |
| for Rec use |
| Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word; |
| end record; |
| @end example |
| |
| If @cite{Bits_Per_Word} is set to 32, this generates either |
| |
| @example |
| for Rec use |
| Field1 at 0 range 0 .. 32; |
| end record; |
| @end example |
| |
| for the big endian case, or |
| |
| @example |
| for Rec use record |
| Field1 at 0 range 10 .. 32; |
| end record; |
| @end example |
| |
| for the little endian case. Since a powerful subset of Ada expression |
| notation is usable for creating static constants, clever use of this |
| feature can often solve quite difficult problems in conditionalizing |
| compilation (note incidentally that in Ada 95, the little endian |
| constant was introduced as @cite{System.Default_Bit_Order}, so you do not |
| need to define this one yourself). |
| |
| @node Use of Alternative Implementations,Preprocessing,Conditionalizing Declarations,Modeling Conditional Compilation in Ada |
| @anchor{gnat_ugn/the_gnat_compilation_model use-of-alternative-implementations}@anchor{a7}@anchor{gnat_ugn/the_gnat_compilation_model id52}@anchor{a8} |
| @subsubsection Use of Alternative Implementations |
| |
| |
| In some cases, none of the approaches described above are adequate. This |
| can occur for example if the set of declarations required is radically |
| different for two different configurations. |
| |
| In this situation, the official Ada way of dealing with conditionalizing |
| such code is to write separate units for the different cases. As long as |
| this does not result in excessive duplication of code, this can be done |
| without creating maintenance problems. The approach is to share common |
| code as far as possible, and then isolate the code and declarations |
| that are different. Subunits are often a convenient method for breaking |
| out a piece of a unit that is to be conditionalized, with separate files |
| for different versions of the subunit for different targets, where the |
| build script selects the right one to give to the compiler. |
| |
| @geindex Subunits (and conditional compilation) |
| |
| As an example, consider a situation where a new feature in Ada 2005 |
| allows something to be done in a really nice way. But your code must be able |
| to compile with an Ada 95 compiler. Conceptually you want to say: |
| |
| @example |
| if Ada_2005 then |
| ... neat Ada 2005 code |
| else |
| ... not quite as neat Ada 95 code |
| end if; |
| @end example |
| |
| where @cite{Ada_2005} is a Boolean constant. |
| |
| But this won't work when @cite{Ada_2005} is set to @cite{False}, |
| since the @cite{then} clause will be illegal for an Ada 95 compiler. |
| (Recall that although such unreachable code would eventually be deleted |
| by the compiler, it still needs to be legal. If it uses features |
| introduced in Ada 2005, it will be illegal in Ada 95.) |
| |
| So instead we write |
| |
| @example |
| procedure Insert is separate; |
| @end example |
| |
| Then we have two files for the subunit @cite{Insert}, with the two sets of |
| code. |
| If the package containing this is called @cite{File_Queries}, then we might |
| have two files |
| |
| |
| @itemize * |
| |
| @item |
| @code{file_queries-insert-2005.adb} |
| |
| @item |
| @code{file_queries-insert-95.adb} |
| @end itemize |
| |
| and the build script renames the appropriate file to @code{file_queries-insert.adb} and then carries out the compilation. |
| |
| This can also be done with project files' naming schemes. For example: |
| |
| @example |
| for body ("File_Queries.Insert") use "file_queries-insert-2005.ada"; |
| @end example |
| |
| Note also that with project files it is desirable to use a different extension |
| than @code{ads} / @code{adb} for alternative versions. Otherwise a naming |
| conflict may arise through another commonly used feature: to declare as part |
| of the project a set of directories containing all the sources obeying the |
| default naming scheme. |
| |
| The use of alternative units is certainly feasible in all situations, |
| and for example the Ada part of the GNAT run-time is conditionalized |
| based on the target architecture using this approach. As a specific example, |
| consider the implementation of the AST feature in VMS. There is one |
| spec: @code{s-asthan.ads} which is the same for all architectures, and three |
| bodies: |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @code{s-asthan.adb} |
| |
| used for all non-VMS operating systems |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @code{s-asthan-vms-alpha.adb} |
| |
| used for VMS on the Alpha |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @code{s-asthan-vms-ia64.adb} |
| |
| used for VMS on the ia64 |
| @end table |
| @end itemize |
| |
| The dummy version @code{s-asthan.adb} simply raises exceptions noting that |
| this operating system feature is not available, and the two remaining |
| versions interface with the corresponding versions of VMS to provide |
| VMS-compatible AST handling. The GNAT build script knows the architecture |
| and operating system, and automatically selects the right version, |
| renaming it if necessary to @code{s-asthan.adb} before the run-time build. |
| |
| Another style for arranging alternative implementations is through Ada's |
| access-to-subprogram facility. |
| In case some functionality is to be conditionally included, |
| you can declare an access-to-procedure variable @cite{Ref} that is initialized |
| to designate a 'do nothing' procedure, and then invoke @cite{Ref.all} |
| when appropriate. |
| In some library package, set @cite{Ref} to @cite{Proc'Access} for some |
| procedure @cite{Proc} that performs the relevant processing. |
| The initialization only occurs if the library package is included in the |
| program. |
| The same idea can also be implemented using tagged types and dispatching |
| calls. |
| |
| @node Preprocessing,,Use of Alternative Implementations,Modeling Conditional Compilation in Ada |
| @anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{a9}@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{aa} |
| @subsubsection Preprocessing |
| |
| |
| @geindex Preprocessing |
| |
| Although it is quite possible to conditionalize code without the use of |
| C-style preprocessing, as described earlier in this section, it is |
| nevertheless convenient in some cases to use the C approach. Moreover, |
| older Ada compilers have often provided some preprocessing capability, |
| so legacy code may depend on this approach, even though it is not |
| standard. |
| |
| To accommodate such use, GNAT provides a preprocessor (modeled to a large |
| extent on the various preprocessors that have been used |
| with legacy code on other compilers, to enable easier transition). |
| |
| @geindex gnatprep |
| |
| The preprocessor may be used in two separate modes. It can be used quite |
| separately from the compiler, to generate a separate output source file |
| that is then fed to the compiler as a separate step. This is the |
| @cite{gnatprep} utility, whose use is fully described in |
| @ref{19,,Preprocessing with gnatprep}. |
| |
| The preprocessing language allows such constructs as |
| |
| @example |
| #if DEBUG or else (PRIORITY > 4) then |
| bunch of declarations |
| #else |
| completely different bunch of declarations |
| #end if; |
| @end example |
| |
| The values of the symbols @cite{DEBUG} and @cite{PRIORITY} can be |
| defined either on the command line or in a separate file. |
| |
| The other way of running the preprocessor is even closer to the C style and |
| often more convenient. In this approach the preprocessing is integrated into |
| the compilation process. The compiler is fed the preprocessor input which |
| includes @cite{#if} lines etc, and then the compiler carries out the |
| preprocessing internally and processes the resulting output. |
| For more details on this approach, see @ref{1a,,Integrated Preprocessing}. |
| |
| @node Preprocessing with gnatprep,Integrated Preprocessing,Modeling Conditional Compilation in Ada,Conditional Compilation |
| @anchor{gnat_ugn/the_gnat_compilation_model id54}@anchor{ab}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{19} |
| @subsection Preprocessing with @cite{gnatprep} |
| |
| |
| @geindex gnatprep |
| |
| @geindex Preprocessing (gnatprep) |
| |
| This section discusses how to use GNAT's @cite{gnatprep} utility for simple |
| preprocessing. |
| Although designed for use with GNAT, @cite{gnatprep} does not depend on any |
| special GNAT features. |
| For further discussion of conditional compilation in general, see |
| @ref{18,,Conditional Compilation}. |
| |
| @menu |
| * Preprocessing Symbols:: |
| * Using gnatprep:: |
| * Switches for gnatprep:: |
| * Form of Definitions File:: |
| * Form of Input Text for gnatprep:: |
| |
| @end menu |
| |
| @node Preprocessing Symbols,Using gnatprep,,Preprocessing with gnatprep |
| @anchor{gnat_ugn/the_gnat_compilation_model id55}@anchor{ac}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{ad} |
| @subsubsection Preprocessing Symbols |
| |
| |
| Preprocessing symbols are defined in definition files and referred to in |
| sources to be preprocessed. A Preprocessing symbol is an identifier, following |
| normal Ada (case-insensitive) rules for its syntax, with the restriction that |
| all characters need to be in the ASCII set (no accented letters). |
| |
| @node Using gnatprep,Switches for gnatprep,Preprocessing Symbols,Preprocessing with gnatprep |
| @anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{ae}@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{af} |
| @subsubsection Using @cite{gnatprep} |
| |
| |
| To call @cite{gnatprep} use: |
| |
| @example |
| $ gnatprep [`switches`] `infile` `outfile` [`deffile`] |
| @end example |
| |
| where |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{switches} |
| |
| is an optional sequence of switches as described in the next section. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{infile} |
| |
| is the full name of the input file, which is an Ada source |
| file containing preprocessor directives. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{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. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{deffile} |
| |
| is the full name of a text file containing definitions of |
| preprocessing symbols to be referenced by the preprocessor. This argument is |
| optional, and can be replaced by the use of the @emph{-D} switch. |
| @end table |
| @end itemize |
| |
| @node Switches for gnatprep,Form of Definitions File,Using gnatprep,Preprocessing with gnatprep |
| @anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatprep}@anchor{b0}@anchor{gnat_ugn/the_gnat_compilation_model id57}@anchor{b1} |
| @subsubsection Switches for @cite{gnatprep} |
| |
| |
| @geindex -b (gnatprep) |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| @end table |
| |
| @geindex -c (gnatprep) |
| |
| |
| @table @asis |
| |
| @item @code{-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 @cite{"--! "}. This option will result in line numbers |
| being preserved in the output file. |
| @end table |
| |
| @geindex -C (gnatprep) |
| |
| |
| @table @asis |
| |
| @item @code{-C} |
| |
| Causes comments to be scanned. Normally comments are ignored by gnatprep. |
| If this option is specified, then comments are scanned and any $symbol |
| substitutions performed as in program text. This is particularly useful |
| when structured comments are used (e.g., when writing programs in the |
| SPARK dialect of Ada). Note that this switch is not available when |
| doing integrated preprocessing (it would be useless in this context |
| since comments are ignored by the compiler in any case). |
| @end table |
| |
| @geindex -D (gnatprep) |
| |
| |
| @table @asis |
| |
| @item @code{-D@emph{symbol}=@emph{value}} |
| |
| Defines a new preprocessing symbol, associated with value. If no value is given |
| on the command line, then symbol is considered to be @cite{True}. This switch |
| can be used in place of a definition file. |
| @end table |
| |
| @geindex -r (gnatprep) |
| |
| |
| @table @asis |
| |
| @item @code{-r} |
| |
| Causes a @cite{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 @emph{-b} mode if @emph{-c} |
| has not been specified explicitly. |
| |
| Note that if the file to be preprocessed contains multiple units, then |
| it will be necessary to @cite{gnatchop} the output file from |
| @cite{gnatprep}. If a @cite{Source_Reference} pragma is present |
| in the preprocessed file, it will be respected by |
| @cite{gnatchop -r} |
| so that the final chopped files will correctly refer to the original |
| input source file for @cite{gnatprep}. |
| @end table |
| |
| @geindex -s (gnatprep) |
| |
| |
| @table @asis |
| |
| @item @code{-s} |
| |
| Causes a sorted list of symbol names and values to be |
| listed on the standard output file. |
| @end table |
| |
| @geindex -u (gnatprep) |
| |
| |
| @table @asis |
| |
| @item @code{-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 @cite{#if} or @cite{#elsif} test will be treated as an error. |
| @end table |
| |
| Note: if neither @emph{-b} nor @emph{-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. |
| |
| @node Form of Definitions File,Form of Input Text for gnatprep,Switches for gnatprep,Preprocessing with gnatprep |
| @anchor{gnat_ugn/the_gnat_compilation_model form-of-definitions-file}@anchor{b2}@anchor{gnat_ugn/the_gnat_compilation_model id58}@anchor{b3} |
| @subsubsection Form of Definitions File |
| |
| |
| The definitions file contains lines of the form: |
| |
| @example |
| symbol := value |
| @end example |
| |
| where @cite{symbol} is a preprocessing symbol, and @cite{value} is one of the following: |
| |
| |
| @itemize * |
| |
| @item |
| Empty, corresponding to a null substitution, |
| |
| @item |
| A string literal using normal Ada syntax, or |
| |
| @item |
| Any sequence of characters from the set @{letters, digits, period, underline@}. |
| @end itemize |
| |
| Comment lines may also appear in the definitions file, starting with |
| the usual @code{--}, |
| and comments may be added to the definitions lines. |
| |
| @node Form of Input Text for gnatprep,,Form of Definitions File,Preprocessing with gnatprep |
| @anchor{gnat_ugn/the_gnat_compilation_model id59}@anchor{b4}@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{b5} |
| @subsubsection Form of Input Text for @cite{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: |
| |
| @example |
| #if <expression> [then] |
| lines |
| #elsif <expression> [then] |
| lines |
| #elsif <expression> [then] |
| lines |
| ... |
| #else |
| lines |
| #end if; |
| @end example |
| |
| In this example, <expression> is defined by the following grammar: |
| |
| @example |
| <expression> ::= <symbol> |
| <expression> ::= <symbol> = "<value>" |
| <expression> ::= <symbol> = <symbol> |
| <expression> ::= <symbol> = <integer> |
| <expression> ::= <symbol> > <integer> |
| <expression> ::= <symbol> >= <integer> |
| <expression> ::= <symbol> < <integer> |
| <expression> ::= <symbol> <= <integer> |
| <expression> ::= <symbol> 'Defined |
| <expression> ::= not <expression> |
| <expression> ::= <expression> and <expression> |
| <expression> ::= <expression> or <expression> |
| <expression> ::= <expression> and then <expression> |
| <expression> ::= <expression> or else <expression> |
| <expression> ::= ( <expression> ) |
| @end example |
| |
| Note the following restriction: it is not allowed to have "and" or "or" |
| following "not" in the same expression without parentheses. For example, this |
| is not allowed: |
| |
| @example |
| not X or Y |
| @end example |
| |
| This can be expressed instead as one of the following forms: |
| |
| @example |
| (not X) or Y |
| not (X or Y) |
| @end example |
| |
| For the first test (<expression> ::= <symbol>) 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 |
| @cite{True} or @cite{False}. If the value is true, then the |
| corresponding lines are included, and if the value is false, they are |
| excluded. |
| |
| When comparing a symbol to an integer, the integer is any non negative |
| literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or |
| 2#11#. The symbol value must also be a non negative integer. Integer values |
| in the range 0 .. 2**31-1 are supported. |
| |
| The test (<expression> ::= <symbol>'Defined) is true only if |
| the symbol has been defined in the definition file or by a @emph{-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 @emph{-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 @cite{True} |
| or @cite{False}. |
| |
| The use of the @cite{not} operator inverts the sense of this logical test. |
| The @cite{not} operator cannot be combined with the @cite{or} or @cite{and} |
| operators, without parentheses. For example, "if not X or Y then" is not |
| allowed, but "if (not X) or Y then" and "if not (X or Y) then" are. |
| |
| The @cite{then} keyword is optional as shown |
| |
| The @cite{#} must be the first non-blank character on a line, but |
| otherwise the format is free form. Spaces or tabs may appear between |
| the @cite{#} 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 @cite{elsif} clauses can be present, |
| including none at all. The @cite{else} is optional, as in Ada. |
| |
| The @cite{#} 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: |
| |
| @example |
| $symbol |
| @end example |
| |
| anywhere within a source line, except in a comment or within a |
| string literal. The identifier |
| following the @cite{$} 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 @cite{$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 @cite{hello} and writing: |
| |
| @example |
| Header : String := "$XYZ"; |
| @end example |
| |
| you should set XYZ to @cite{"hello"} and write: |
| |
| @example |
| Header : String := $XYZ; |
| @end example |
| |
| and then the substitution will occur as desired. |
| |
| @node Integrated Preprocessing,,Preprocessing with gnatprep,Conditional Compilation |
| @anchor{gnat_ugn/the_gnat_compilation_model id60}@anchor{b6}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{1a} |
| @subsection Integrated Preprocessing |
| |
| |
| GNAT sources may be preprocessed immediately before compilation. |
| In this case, the actual |
| text of the source is not the text of the source file, but is derived from it |
| through a process called preprocessing. Integrated preprocessing is specified |
| through switches @emph{-gnatep} and/or @emph{-gnateD}. @emph{-gnatep} |
| indicates, through a text file, the preprocessing data to be used. |
| @code{-gnateD} specifies or modifies the values of preprocessing symbol. |
| Note that integrated preprocessing applies only to Ada source files, it is |
| not available for configuration pragma files. |
| |
| Note that when integrated preprocessing is used, the output from the |
| preprocessor is not written to any external file. Instead it is passed |
| internally to the compiler. If you need to preserve the result of |
| preprocessing in a file, then you should use @emph{gnatprep} |
| to perform the desired preprocessing in stand-alone mode. |
| |
| It is recommended that @emph{gnatmake} switch -s should be |
| used when Integrated Preprocessing is used. The reason is that preprocessing |
| with another Preprocessing Data file without changing the sources will |
| not trigger recompilation without this switch. |
| |
| Note that @emph{gnatmake} switch -m will almost |
| always trigger recompilation for sources that are preprocessed, |
| because @emph{gnatmake} cannot compute the checksum of the source after |
| preprocessing. |
| |
| The actual preprocessing function is described in detail in section |
| @ref{19,,Preprocessing with gnatprep}. This section only describes how integrated |
| preprocessing is triggered and parameterized. |
| |
| @geindex -gnatep (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatep=@emph{file}} |
| |
| This switch indicates to the compiler the file name (without directory |
| information) of the preprocessor data file to use. The preprocessor data file |
| should be found in the source directories. Note that when the compiler is |
| called by a builder such as (@emph{gnatmake} with a project |
| file, if the object directory is not also a source directory, the builder needs |
| to be called with @emph{-x}. |
| |
| A preprocessing data file is a text file with significant lines indicating |
| how should be preprocessed either a specific source or all sources not |
| mentioned in other lines. A significant line is a nonempty, non-comment line. |
| Comments are similar to Ada comments. |
| |
| Each significant line starts with either a literal string or the character '*'. |
| A literal string is the file name (without directory information) of the source |
| to preprocess. A character '*' indicates the preprocessing for all the sources |
| that are not specified explicitly on other lines (order of the lines is not |
| significant). It is an error to have two lines with the same file name or two |
| lines starting with the character '*'. |
| |
| After the file name or the character '*', another optional literal string |
| indicating the file name of the definition file to be used for preprocessing |
| (@ref{b2,,Form of Definitions File}). The definition files are found by the |
| compiler in one of the source directories. In some cases, when compiling |
| a source in a directory other than the current directory, if the definition |
| file is in the current directory, it may be necessary to add the current |
| directory as a source directory through switch -I., otherwise |
| the compiler would not find the definition file. |
| |
| Then, optionally, switches similar to those of @cite{gnatprep} may |
| be found. Those switches are: |
| |
| |
| @table @asis |
| |
| @item @code{-b} |
| |
| Causes both preprocessor lines and the lines deleted by |
| preprocessing to be replaced by blank lines, preserving the line number. |
| This switch is always implied; however, if specified after @emph{-c} |
| it cancels the effect of @emph{-c}. |
| |
| @item @code{-c} |
| |
| Causes both preprocessor lines and the lines deleted |
| by preprocessing to be retained as comments marked |
| with the special string '@cite{--!}'. |
| |
| @item @code{-Dsymbol=@emph{value}} |
| |
| Define or redefine a symbol, associated with value. A symbol is an Ada |
| identifier, or an Ada reserved word, with the exception of @cite{if}, |
| @cite{else}, @cite{elsif}, @cite{end}, @cite{and}, @cite{or} and @cite{then}. |
| @cite{value} is either a literal string, an Ada identifier or any Ada reserved |
| word. A symbol declared with this switch replaces a symbol with the |
| same name defined in a definition file. |
| |
| @item @code{-s} |
| |
| Causes a sorted list of symbol names and values to be |
| listed on the standard output file. |
| |
| @item @code{-u} |
| |
| Causes undefined symbols to be treated as having the value @cite{FALSE} |
| in the context |
| of a preprocessor test. In the absence of this option, an undefined symbol in |
| a @cite{#if} or @cite{#elsif} test will be treated as an error. |
| @end table |
| |
| Examples of valid lines in a preprocessor data file: |
| |
| @example |
| "toto.adb" "prep.def" -u |
| -- preprocess "toto.adb", using definition file "prep.def", |
| -- undefined symbol are False. |
| |
| * -c -DVERSION=V101 |
| -- preprocess all other sources without a definition file; |
| -- suppressed lined are commented; symbol VERSION has the value V101. |
| |
| "titi.adb" "prep2.def" -s |
| -- preprocess "titi.adb", using definition file "prep2.def"; |
| -- list all symbols with their values. |
| @end example |
| @end table |
| |
| @geindex -gnateD (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateDsymbol[=value]} |
| |
| Define or redefine a preprocessing symbol, associated with value. If no value |
| is given on the command line, then the value of the symbol is @cite{True}. |
| A symbol is an identifier, following normal Ada (case-insensitive) |
| rules for its syntax, and value is either an arbitrary string between double |
| quotes or any sequence (including an empty sequence) of characters from the |
| set (letters, digits, period, underline). |
| Ada reserved words may be used as symbols, with the exceptions of @cite{if}, |
| @cite{else}, @cite{elsif}, @cite{end}, @cite{and}, @cite{or} and @cite{then}. |
| |
| Examples: |
| |
| @example |
| -gnateDToto=Titi |
| -gnateDFoo |
| -gnateDFoo=\"Foo-Bar\" |
| @end example |
| |
| A symbol declared with this switch on the command line replaces a |
| symbol with the same name either in a definition file or specified with a |
| switch -D in the preprocessor data file. |
| |
| This switch is similar to switch @emph{-D} of @cite{gnatprep}. |
| |
| @item @code{-gnateG} |
| |
| When integrated preprocessing is performed and the preprocessor modifies |
| the source text, write the result of this preprocessing into a file |
| <source>.prep. |
| @end table |
| |
| @node Mixed Language Programming,GNAT and Other Compilation Models,Conditional Compilation,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model mixed-language-programming}@anchor{46}@anchor{gnat_ugn/the_gnat_compilation_model id61}@anchor{b7} |
| @section Mixed Language Programming |
| |
| |
| @geindex Mixed Language Programming |
| |
| This section describes how to develop a mixed-language program, |
| with a focus on combining Ada with C or C++. |
| |
| @menu |
| * Interfacing to C:: |
| * Calling Conventions:: |
| * Building Mixed Ada and C++ Programs:: |
| * Generating Ada Bindings for C and C++ headers:: |
| * Generating C Headers for Ada Specifications:: |
| |
| @end menu |
| |
| @node Interfacing to C,Calling Conventions,,Mixed Language Programming |
| @anchor{gnat_ugn/the_gnat_compilation_model interfacing-to-c}@anchor{b8}@anchor{gnat_ugn/the_gnat_compilation_model id62}@anchor{b9} |
| @subsection Interfacing to C |
| |
| |
| Interfacing Ada with a foreign language such as C involves using |
| compiler directives to import and/or export entity definitions in each |
| language -- using @cite{extern} statements in C, for instance, and the |
| @cite{Import}, @cite{Export}, and @cite{Convention} pragmas in Ada. |
| A full treatment of these topics is provided in Appendix B, section 1 |
| of the Ada Reference Manual. |
| |
| There are two ways to build a program using GNAT that contains some Ada |
| sources and some foreign language sources, depending on whether or not |
| the main subprogram is written in Ada. Here is a source example with |
| the main subprogram in Ada: |
| |
| @example |
| /* file1.c */ |
| #include <stdio.h> |
| |
| void print_num (int num) |
| @{ |
| printf ("num is %d.\\n", num); |
| return; |
| @} |
| @end example |
| |
| @example |
| /* file2.c */ |
| |
| /* num_from_Ada is declared in my_main.adb */ |
| extern int num_from_Ada; |
| |
| int get_num (void) |
| @{ |
| return num_from_Ada; |
| @} |
| @end example |
| |
| @example |
| -- my_main.adb |
| procedure My_Main is |
| |
| -- Declare then export an Integer entity called num_from_Ada |
| My_Num : Integer := 10; |
| pragma Export (C, My_Num, "num_from_Ada"); |
| |
| -- Declare an Ada function spec for Get_Num, then use |
| -- C function get_num for the implementation. |
| function Get_Num return Integer; |
| pragma Import (C, Get_Num, "get_num"); |
| |
| -- Declare an Ada procedure spec for Print_Num, then use |
| -- C function print_num for the implementation. |
| procedure Print_Num (Num : Integer); |
| pragma Import (C, Print_Num, "print_num"; |
| |
| begin |
| Print_Num (Get_Num); |
| end My_Main; |
| @end example |
| |
| To build this example: |
| |
| |
| @itemize * |
| |
| @item |
| First compile the foreign language files to |
| generate object files: |
| |
| @example |
| $ gcc -c file1.c |
| $ gcc -c file2.c |
| @end example |
| |
| @item |
| Then, compile the Ada units to produce a set of object files and ALI |
| files: |
| |
| @example |
| $ gnatmake -c my_main.adb |
| @end example |
| |
| @item |
| Run the Ada binder on the Ada main program: |
| |
| @example |
| $ gnatbind my_main.ali |
| @end example |
| |
| @item |
| Link the Ada main program, the Ada objects and the other language |
| objects: |
| |
| @example |
| $ gnatlink my_main.ali file1.o file2.o |
| @end example |
| @end itemize |
| |
| The last three steps can be grouped in a single command: |
| |
| @example |
| $ gnatmake my_main.adb -largs file1.o file2.o |
| @end example |
| |
| @geindex Binder output file |
| |
| If the main program is in a language other than Ada, then you may have |
| more than one entry point into the Ada subsystem. You must use a special |
| binder option to generate callable routines that initialize and |
| finalize the Ada units (@ref{ba,,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. The binder will place the |
| initialization and finalization subprograms into the |
| @code{b~xxx.adb} file where they can be accessed by your C |
| sources. To illustrate, we have the following example: |
| |
| @example |
| /* main.c */ |
| extern void adainit (void); |
| extern void adafinal (void); |
| extern int add (int, int); |
| extern int sub (int, int); |
| |
| int main (int argc, char *argv[]) |
| @{ |
| int a = 21, b = 7; |
| |
| adainit(); |
| |
| /* Should print "21 + 7 = 28" */ |
| printf ("%d + %d = %d\\n", a, b, add (a, b)); |
| |
| /* Should print "21 - 7 = 14" */ |
| printf ("%d - %d = %d\\n", a, b, sub (a, b)); |
| |
| adafinal(); |
| @} |
| @end example |
| |
| @example |
| -- unit1.ads |
| package Unit1 is |
| function Add (A, B : Integer) return Integer; |
| pragma Export (C, Add, "add"); |
| end Unit1; |
| @end example |
| |
| @example |
| -- unit1.adb |
| package body Unit1 is |
| function Add (A, B : Integer) return Integer is |
| begin |
| return A + B; |
| end Add; |
| end Unit1; |
| @end example |
| |
| @example |
| -- unit2.ads |
| package Unit2 is |
| function Sub (A, B : Integer) return Integer; |
| pragma Export (C, Sub, "sub"); |
| end Unit2; |
| @end example |
| |
| @example |
| -- unit2.adb |
| package body Unit2 is |
| function Sub (A, B : Integer) return Integer is |
| begin |
| return A - B; |
| end Sub; |
| end Unit2; |
| @end example |
| |
| The build procedure for this application is similar to the last |
| example's: |
| |
| |
| @itemize * |
| |
| @item |
| First, compile the foreign language files to generate object files: |
| |
| @example |
| $ gcc -c main.c |
| @end example |
| |
| @item |
| Next, compile the Ada units to produce a set of object files and ALI |
| files: |
| |
| @example |
| $ gnatmake -c unit1.adb |
| $ gnatmake -c unit2.adb |
| @end example |
| |
| @item |
| Run the Ada binder on every generated ALI file. Make sure to use the |
| @code{-n} option to specify a foreign main program: |
| |
| @example |
| $ gnatbind -n unit1.ali unit2.ali |
| @end example |
| |
| @item |
| Link the Ada main program, the Ada objects and the foreign language |
| objects. You need only list the last ALI file here: |
| |
| @example |
| $ gnatlink unit2.ali main.o -o exec_file |
| @end example |
| |
| This procedure yields a binary executable called @code{exec_file}. |
| @end itemize |
| |
| Depending on the circumstances (for example when your non-Ada main object |
| does not provide symbol @cite{main}), you may also need to instruct the |
| GNAT linker not to include the standard startup objects by passing the |
| @code{-nostartfiles} switch to @cite{gnatlink}. |
| |
| @node Calling Conventions,Building Mixed Ada and C++ Programs,Interfacing to C,Mixed Language Programming |
| @anchor{gnat_ugn/the_gnat_compilation_model calling-conventions}@anchor{bb}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{bc} |
| @subsection Calling Conventions |
| |
| |
| @geindex Foreign Languages |
| |
| @geindex 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: |
| |
| @geindex Interfacing to Ada |
| |
| @geindex Other Ada compilers |
| |
| @geindex Convention Ada |
| |
| |
| @table @asis |
| |
| @item @emph{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 HP Ada 83, a higher degree of compatibility |
| can be guaranteed, and in particular records are laid 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 |
| HP Ada 83, All the tasking operations must either be entirely within |
| GNAT compiled sections of the program, or entirely within HP Ada 83 |
| compiled sections of the program. |
| @end table |
| |
| @geindex Interfacing to Assembly |
| |
| @geindex Convention Assembler |
| |
| |
| @table @asis |
| |
| @item @emph{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). |
| @end table |
| |
| @geindex Convention Asm |
| |
| @geindex Asm |
| |
| |
| @table @asis |
| |
| @item @emph{Asm} |
| |
| Equivalent to Assembler. |
| |
| @geindex Interfacing to COBOL |
| |
| @geindex Convention COBOL |
| @end table |
| |
| @geindex COBOL |
| |
| |
| @table @asis |
| |
| @item @emph{COBOL} |
| |
| Data will be passed according to the conventions described |
| in section B.4 of the Ada Reference Manual. |
| @end table |
| |
| @geindex C |
| |
| @geindex Interfacing to C |
| |
| @geindex Convention C |
| |
| |
| @table @asis |
| |
| @item @emph{C} |
| |
| Data will be passed according to the conventions described |
| in section B.3 of the Ada Reference Manual. |
| |
| A note on interfacing to a C 'varargs' function: |
| |
| @quotation |
| |
| @geindex C varargs function |
| |
| @geindex Interfacing to C varargs function |
| |
| @geindex varargs function interfaces |
| |
| In C, @cite{varargs} allows a function to take a variable number of |
| arguments. There is no direct equivalent in this to Ada. One |
| approach that can be used is to create a C wrapper for each |
| different profile and then interface to this C wrapper. For |
| example, to print an @cite{int} value using @cite{printf}, |
| create a C function @cite{printfi} that takes two arguments, a |
| pointer to a string and an int, and calls @cite{printf}. |
| Then in the Ada program, use pragma @cite{Import} to |
| interface to @cite{printfi}. |
| |
| It may work on some platforms to directly interface to |
| a @cite{varargs} function by providing a specific Ada profile |
| for a particular call. However, this does not work on |
| all platforms, since there is no guarantee that the |
| calling sequence for a two argument normal C function |
| is the same as for calling a @cite{varargs} C function with |
| the same two arguments. |
| @end quotation |
| @end table |
| |
| @geindex Convention Default |
| |
| @geindex Default |
| |
| |
| @table @asis |
| |
| @item @emph{Default} |
| |
| Equivalent to C. |
| @end table |
| |
| @geindex Convention External |
| |
| @geindex External |
| |
| |
| @table @asis |
| |
| @item @emph{External} |
| |
| Equivalent to C. |
| @end table |
| |
| @geindex C++ |
| |
| @geindex Interfacing to C++ |
| |
| @geindex Convention C++ |
| |
| |
| @table @asis |
| |
| @item @emph{C_Plus_Plus (or 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. |
| @end table |
| |
| @geindex Fortran |
| |
| @geindex Interfacing to Fortran |
| |
| @geindex Convention Fortran |
| |
| |
| @table @asis |
| |
| @item @emph{Fortran} |
| |
| Data will be passed according to the conventions described |
| in section B.5 of the Ada Reference Manual. |
| |
| @item @emph{Intrinsic} |
| |
| This applies to an intrinsic operation, as defined in the Ada |
| Reference Manual. If 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 may |
| be applied to the following sets of names: |
| |
| |
| @itemize * |
| |
| @item |
| 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. |
| |
| @item |
| 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: |
| @end itemize |
| |
| @example |
| 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. |
| @end example |
| |
| |
| @itemize * |
| |
| @item |
| General subprogram entities. This is used to bind an Ada subprogram |
| declaration to |
| a compiler builtin by name with back-ends where such interfaces are |
| available. A typical example is the set of @cite{__builtin} functions |
| exposed by the GCC back-end, as in the following example: |
| |
| @example |
| function builtin_sqrt (F : Float) return Float; |
| pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf"); |
| @end example |
| |
| Most of the GCC builtins are accessible this way, and as for other |
| import conventions (e.g. C), it is the user's responsibility to ensure |
| that the Ada subprogram profile matches the underlying builtin |
| expectations. |
| @end itemize |
| @end table |
| |
| @geindex Stdcall |
| |
| @geindex Convention Stdcall |
| |
| |
| @table @asis |
| |
| @item @emph{Stdcall} |
| |
| This is relevant only to Windows implementations of GNAT, |
| and specifies that the @cite{Stdcall} calling sequence will be used, |
| as defined by the NT API. Nevertheless, to ease building |
| cross-platform bindings this convention will be handled as a @cite{C} calling |
| convention on non-Windows platforms. |
| @end table |
| |
| @geindex DLL |
| |
| @geindex Convention DLL |
| |
| |
| @table @asis |
| |
| @item @emph{DLL} |
| |
| This is equivalent to @cite{Stdcall}. |
| @end table |
| |
| @geindex Win32 |
| |
| @geindex Convention Win32 |
| |
| |
| @table @asis |
| |
| @item @emph{Win32} |
| |
| This is equivalent to @cite{Stdcall}. |
| @end table |
| |
| @geindex Stubbed |
| |
| @geindex Convention Stubbed |
| |
| |
| @table @asis |
| |
| @item @emph{Stubbed} |
| |
| This is a special convention that indicates that the compiler |
| should provide a stub body that raises @cite{Program_Error}. |
| @end table |
| |
| GNAT additionally provides a useful pragma @cite{Convention_Identifier} |
| that can be used to parameterize 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: |
| |
| @example |
| pragma Convention_Identifier (Fortran77, Fortran); |
| @end example |
| |
| And from now on the identifier Fortran77 may be used as a convention |
| identifier (for example in an @cite{Import} pragma) with the same |
| meaning as Fortran. |
| |
| @node Building Mixed Ada and C++ Programs,Generating Ada Bindings for C and C++ headers,Calling Conventions,Mixed Language Programming |
| @anchor{gnat_ugn/the_gnat_compilation_model id64}@anchor{bd}@anchor{gnat_ugn/the_gnat_compilation_model building-mixed-ada-and-c-programs}@anchor{be} |
| @subsection Building Mixed Ada and C++ Programs |
| |
| |
| A programmer inexperienced with mixed-language development may find that |
| building an application containing both Ada and C++ code can be a |
| challenge. This section gives a few hints that should make this task easier. |
| |
| @menu |
| * Interfacing to C++:: |
| * Linking a Mixed C++ & Ada Program:: |
| * A Simple Example:: |
| * Interfacing with C++ constructors:: |
| * Interfacing with C++ at the Class Level:: |
| |
| @end menu |
| |
| @node Interfacing to C++,Linking a Mixed C++ & Ada Program,,Building Mixed Ada and C++ Programs |
| @anchor{gnat_ugn/the_gnat_compilation_model id65}@anchor{bf}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{c0} |
| @subsubsection Interfacing to C++ |
| |
| |
| GNAT supports interfacing with the G++ compiler (or any C++ compiler |
| generating code that is compatible with the G++ Application Binary |
| Interface ---see @indicateurl{http://www.codesourcery.com/archives/cxx-abi}). |
| |
| Interfacing can be done at 3 levels: simple data, subprograms, and |
| classes. In the first two cases, GNAT offers a specific @cite{Convention C_Plus_Plus} |
| (or @cite{CPP}) that behaves exactly like @cite{Convention C}. |
| Usually, C++ mangles the names of subprograms. To generate proper mangled |
| names automatically, see @ref{1b,,Generating Ada Bindings for C and C++ headers}). |
| This problem can also be addressed manually in two ways: |
| |
| |
| @itemize * |
| |
| @item |
| by modifying the C++ code in order to force a C convention using |
| the @cite{extern "C"} syntax. |
| |
| @item |
| by figuring out the mangled name (using e.g. @emph{nm}) and using it as the |
| Link_Name argument of the pragma import. |
| @end itemize |
| |
| Interfacing at the class level can be achieved by using the GNAT specific |
| pragmas such as @cite{CPP_Constructor}. See the @cite{GNAT_Reference_Manual} for additional information. |
| |
| @node Linking a Mixed C++ & Ada Program,A Simple Example,Interfacing to C++,Building Mixed Ada and C++ Programs |
| @anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-ada-program}@anchor{c1}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{c2} |
| @subsubsection 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: |
| |
| |
| @itemize * |
| |
| @item |
| 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 @cite{g++}. |
| |
| Note that if the C++ code uses inline functions, you will need to |
| compile your C++ code with the @cite{-fkeep-inline-functions} switch in |
| order to provide an existing function implementation that the Ada code can |
| link with. |
| |
| @example |
| $ g++ -c -fkeep-inline-functions file1.C |
| $ g++ -c -fkeep-inline-functions file2.C |
| $ gnatmake ada_unit -largs file1.o file2.o --LINK=g++ |
| @end example |
| |
| @item |
| Using GNAT and G++ from two different GCC installations: If both |
| compilers are on the :envvar`PATH`, the previous method may be used. It is |
| important to note that environment variables such as |
| @geindex C_INCLUDE_PATH |
| @geindex environment variable; C_INCLUDE_PATH |
| @code{C_INCLUDE_PATH}, |
| @geindex GCC_EXEC_PREFIX |
| @geindex environment variable; GCC_EXEC_PREFIX |
| @code{GCC_EXEC_PREFIX}, |
| @geindex BINUTILS_ROOT |
| @geindex environment variable; BINUTILS_ROOT |
| @code{BINUTILS_ROOT}, and |
| @geindex GCC_ROOT |
| @geindex environment variable; GCC_ROOT |
| @code{GCC_ROOT} will affect both compilers |
| at the same time and may make one of the two compilers operate |
| improperly if set during invocation of the wrong compiler. It is also |
| very important that the linker uses the proper @code{libgcc.a} GCC |
| library -- that is, the one from the C++ compiler installation. The |
| implicit link command as suggested in the @cite{gnatmake} command |
| from the former example can be replaced by an explicit link command with |
| the full-verbosity option in order to verify which library is used: |
| |
| @example |
| $ gnatbind ada_unit |
| $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ |
| @end example |
| |
| If there is a problem due to interfering environment variables, it can |
| be worked around 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: |
| |
| @example |
| $ cat ./my_script |
| #!/bin/sh |
| unset BINUTILS_ROOT |
| unset GCC_ROOT |
| c++ $* |
| $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script |
| @end example |
| |
| @item |
| Using a non-GNU C++ compiler: The commands previously described can be |
| used to insure that the C++ linker is used. Nonetheless, you need to add |
| a few more parameters to the link command line, depending on the exception |
| mechanism used. |
| |
| If the @cite{setjmp/longjmp} exception mechanism is used, only the paths |
| to the libgcc libraries are required: |
| |
| @example |
| $ cat ./my_script |
| #!/bin/sh |
| CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` |
| $ gnatlink ada_unit file1.o file2.o --LINK=./my_script |
| @end example |
| |
| where CC is the name of the non-GNU C++ compiler. |
| |
| If the @cite{zero cost} exception mechanism is used, and the platform |
| supports automatic registration of exception tables (e.g., Solaris), |
| paths to more objects are required: |
| |
| @example |
| $ cat ./my_script |
| #!/bin/sh |
| CC `gcc -print-file-name=crtbegin.o` $* \\ |
| `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \\ |
| `gcc -print-file-name=crtend.o` |
| $ gnatlink ada_unit file1.o file2.o --LINK=./my_script |
| @end example |
| |
| If the "zero cost exception" mechanism is used, and the platform |
| doesn't support automatic registration of exception tables (e.g., HP-UX |
| or AIX), the simple approach described above will not work and |
| a pre-linking phase using GNAT will be necessary. |
| @end itemize |
| |
| Another alternative is to use the @code{gprbuild} multi-language builder |
| which has a large knowledge base and knows how to link Ada and C++ code |
| together automatically in most cases. |
| |
| @node A Simple Example,Interfacing with C++ constructors,Linking a Mixed C++ & Ada Program,Building Mixed Ada and C++ Programs |
| @anchor{gnat_ugn/the_gnat_compilation_model id67}@anchor{c3}@anchor{gnat_ugn/the_gnat_compilation_model a-simple-example}@anchor{c4} |
| @subsubsection A Simple Example |
| |
| |
| The following example, provided as part of the GNAT examples, shows how |
| to achieve procedural interfacing between Ada and C++ in both |
| directions. The C++ class A has two 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 are modelled by |
| a limited record with a layout comparable to the C++ class. The Ada |
| subprogram, in turn, calls the C++ method. So, starting from the C++ |
| main program, the process passes back and forth between the two |
| languages. |
| |
| Here are the compilation commands: |
| |
| @example |
| $ gnatmake -c simple_cpp_interface |
| $ g++ -c cpp_main.C |
| $ g++ -c ex7.C |
| $ gnatbind -n simple_cpp_interface |
| $ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ -lstdc++ ex7.o cpp_main.o |
| @end example |
| |
| Here are the corresponding sources: |
| |
| @example |
| //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 (); |
| @} |
| @end example |
| |
| @example |
| //ex7.h |
| |
| class Origin @{ |
| public: |
| int o_value; |
| @}; |
| class A : public Origin @{ |
| public: |
| void method1 (void); |
| void method2 (int v); |
| A(); |
| int a_value; |
| @}; |
| @end example |
| |
| @example |
| //ex7.C |
| |
| #include "ex7.h" |
| #include <stdio.h> |
| |
| 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); |
| @} |
| @end example |
| |
| @example |
| -- simple_cpp_interface.ads |
| with System; |
| package Simple_Cpp_Interface is |
| type A is limited |
| record |
| Vptr : System.Address; |
| 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; |
| @end example |
| |
| @example |
| -- simple_cpp_interface.adb |
| 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; |
| @end example |
| |
| @node Interfacing with C++ constructors,Interfacing with C++ at the Class Level,A Simple Example,Building Mixed Ada and C++ Programs |
| @anchor{gnat_ugn/the_gnat_compilation_model id68}@anchor{c5}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-constructors}@anchor{c6} |
| @subsubsection Interfacing with C++ constructors |
| |
| |
| In order to interface with C++ constructors GNAT provides the |
| @cite{pragma CPP_Constructor} (see the @cite{GNAT_Reference_Manual} |
| for additional information). |
| In this section we present some common uses of C++ constructors |
| in mixed-languages programs in GNAT. |
| |
| Let us assume that we need to interface with the following |
| C++ class: |
| |
| @example |
| class Root @{ |
| public: |
| int a_value; |
| int b_value; |
| virtual int Get_Value (); |
| Root(); // Default constructor |
| Root(int v); // 1st non-default constructor |
| Root(int v, int w); // 2nd non-default constructor |
| @}; |
| @end example |
| |
| For this purpose we can write the following package spec (further |
| information on how to build this spec is available in |
| @ref{c7,,Interfacing with C++ at the Class Level} and |
| @ref{1b,,Generating Ada Bindings for C and C++ headers}). |
| |
| @example |
| with Interfaces.C; use Interfaces.C; |
| package Pkg_Root is |
| type Root is tagged limited record |
| A_Value : int; |
| B_Value : int; |
| end record; |
| pragma Import (CPP, Root); |
| |
| function Get_Value (Obj : Root) return int; |
| pragma Import (CPP, Get_Value); |
| |
| function Constructor return Root; |
| pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev"); |
| |
| function Constructor (v : Integer) return Root; |
| pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei"); |
| |
| function Constructor (v, w : Integer) return Root; |
| pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii"); |
| end Pkg_Root; |
| @end example |
| |
| On the Ada side the constructor is represented by a function (whose |
| name is arbitrary) that returns the classwide type corresponding to |
| the imported C++ class. Although the constructor is described as a |
| function, 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. |
| |
| Constructors can only appear in the following contexts: |
| |
| |
| @itemize * |
| |
| @item |
| On the right side of an initialization of an object of type @cite{T}. |
| |
| @item |
| On the right side of an initialization of a record component of type @cite{T}. |
| |
| @item |
| In an Ada 2005 limited aggregate. |
| |
| @item |
| In an Ada 2005 nested limited aggregate. |
| |
| @item |
| In an Ada 2005 limited aggregate that initializes an object built in |
| place by an extended return statement. |
| @end itemize |
| |
| In a declaration of an object whose type is a class imported from C++, |
| either the default C++ constructor is implicitly called by GNAT, or |
| else the required C++ constructor must be explicitly called in the |
| expression that initializes the object. For example: |
| |
| @example |
| Obj1 : Root; |
| Obj2 : Root := Constructor; |
| Obj3 : Root := Constructor (v => 10); |
| Obj4 : Root := Constructor (30, 40); |
| @end example |
| |
| The first two declarations are equivalent: in both cases the default C++ |
| constructor is invoked (in the former case the call to the constructor is |
| implicit, and in the latter case the call is explicit in the object |
| declaration). @cite{Obj3} is initialized by the C++ non-default constructor |
| that takes an integer argument, and @cite{Obj4} is initialized by the |
| non-default C++ constructor that takes two integers. |
| |
| Let us derive the imported C++ class in the Ada side. For example: |
| |
| @example |
| type DT is new Root with record |
| C_Value : Natural := 2009; |
| end record; |
| @end example |
| |
| In this case the components DT inherited from the C++ side must be |
| initialized by a C++ constructor, and the additional Ada components |
| of type DT are initialized by GNAT. The initialization of such an |
| object is done either by default, or by means of a function returning |
| an aggregate of type DT, or by means of an extension aggregate. |
| |
| @example |
| Obj5 : DT; |
| Obj6 : DT := Function_Returning_DT (50); |
| Obj7 : DT := (Constructor (30,40) with C_Value => 50); |
| @end example |
| |
| The declaration of @cite{Obj5} invokes the default constructors: the |
| C++ default constructor of the parent type takes care of the initialization |
| of the components inherited from Root, and GNAT takes care of the default |
| initialization of the additional Ada components of type DT (that is, |
| @cite{C_Value} is initialized to value 2009). The order of invocation of |
| the constructors is consistent with the order of elaboration required by |
| Ada and C++. That is, the constructor of the parent type is always called |
| before the constructor of the derived type. |
| |
| Let us now consider a record that has components whose type is imported |
| from C++. For example: |
| |
| @example |
| type Rec1 is limited record |
| Data1 : Root := Constructor (10); |
| Value : Natural := 1000; |
| end record; |
| |
| type Rec2 (D : Integer := 20) is limited record |
| Rec : Rec1; |
| Data2 : Root := Constructor (D, 30); |
| end record; |
| @end example |
| |
| The initialization of an object of type @cite{Rec2} will call the |
| non-default C++ constructors specified for the imported components. |
| For example: |
| |
| @example |
| Obj8 : Rec2 (40); |
| @end example |
| |
| Using Ada 2005 we can use limited aggregates to initialize an object |
| invoking C++ constructors that differ from those specified in the type |
| declarations. For example: |
| |
| @example |
| Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16), |
| others => <>), |
| others => <>); |
| @end example |
| |
| The above declaration uses an Ada 2005 limited aggregate to |
| initialize @cite{Obj9}, and the C++ constructor that has two integer |
| arguments is invoked to initialize the @cite{Data1} component instead |
| of the constructor specified in the declaration of type @cite{Rec1}. In |
| Ada 2005 the box in the aggregate indicates that unspecified components |
| are initialized using the expression (if any) available in the component |
| declaration. That is, in this case discriminant @cite{D} is initialized |
| to value @cite{20}, @cite{Value} is initialized to value 1000, and the |
| non-default C++ constructor that handles two integers takes care of |
| initializing component @cite{Data2} with values @cite{20@comma{}30}. |
| |
| In Ada 2005 we can use the extended return statement to build the Ada |
| equivalent to C++ non-default constructors. For example: |
| |
| @example |
| function Constructor (V : Integer) return Rec2 is |
| begin |
| return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20), |
| others => <>), |
| others => <>) do |
| -- Further actions required for construction of |
| -- objects of type Rec2 |
| ... |
| end record; |
| end Constructor; |
| @end example |
| |
| In this example the extended return statement construct is used to |
| build in place the returned object whose components are initialized |
| by means of a limited aggregate. Any further action associated with |
| the constructor can be placed inside the construct. |
| |
| @node Interfacing with C++ at the Class Level,,Interfacing with C++ constructors,Building Mixed Ada and C++ Programs |
| @anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-at-the-class-level}@anchor{c7}@anchor{gnat_ugn/the_gnat_compilation_model id69}@anchor{c8} |
| @subsubsection Interfacing with C++ at the Class Level |
| |
| |
| In this section we demonstrate the GNAT features for interfacing with |
| C++ by means of an example making use of Ada 2005 abstract interface |
| types. This example consists of a classification of animals; classes |
| have been used to model our main classification of animals, and |
| interfaces provide support for the management of secondary |
| classifications. We first demonstrate a case in which the types and |
| constructors are defined on the C++ side and imported from the Ada |
| side, and latter the reverse case. |
| |
| The root of our derivation will be the @cite{Animal} class, with a |
| single private attribute (the @cite{Age} of the animal), a constructor, |
| and two public primitives to set and get the value of this attribute. |
| |
| @example |
| class Animal @{ |
| public: |
| virtual void Set_Age (int New_Age); |
| virtual int Age (); |
| Animal() @{Age_Count = 0;@}; |
| private: |
| int Age_Count; |
| @}; |
| @end example |
| |
| Abstract interface types are defined in C++ by means of classes with pure |
| virtual functions and no data members. In our example we will use two |
| interfaces that provide support for the common management of @cite{Carnivore} |
| and @cite{Domestic} animals: |
| |
| @example |
| class Carnivore @{ |
| public: |
| virtual int Number_Of_Teeth () = 0; |
| @}; |
| |
| class Domestic @{ |
| public: |
| virtual void Set_Owner (char* Name) = 0; |
| @}; |
| @end example |
| |
| Using these declarations, we can now say that a @cite{Dog} is an animal that is |
| both Carnivore and Domestic, that is: |
| |
| @example |
| class Dog : Animal, Carnivore, Domestic @{ |
| public: |
| virtual int Number_Of_Teeth (); |
| virtual void Set_Owner (char* Name); |
| |
| Dog(); // Constructor |
| private: |
| int Tooth_Count; |
| char *Owner; |
| @}; |
| @end example |
| |
| In the following examples we will assume that the previous declarations are |
| located in a file named @cite{animals.h}. The following package demonstrates |
| how to import these C++ declarations from the Ada side: |
| |
| @example |
| with Interfaces.C.Strings; use Interfaces.C.Strings; |
| package Animals is |
| type Carnivore is limited interface; |
| pragma Convention (C_Plus_Plus, Carnivore); |
| function Number_Of_Teeth (X : Carnivore) |
| return Natural is abstract; |
| |
| type Domestic is limited interface; |
| pragma Convention (C_Plus_Plus, Domestic); |
| procedure Set_Owner |
| (X : in out Domestic; |
| Name : Chars_Ptr) is abstract; |
| |
| type Animal is tagged limited record |
| Age : Natural; |
| end record; |
| pragma Import (C_Plus_Plus, Animal); |
| |
| procedure Set_Age (X : in out Animal; Age : Integer); |
| pragma Import (C_Plus_Plus, Set_Age); |
| |
| function Age (X : Animal) return Integer; |
| pragma Import (C_Plus_Plus, Age); |
| |
| function New_Animal return Animal; |
| pragma CPP_Constructor (New_Animal); |
| pragma Import (CPP, New_Animal, "_ZN6AnimalC1Ev"); |
| |
| type Dog is new Animal and Carnivore and Domestic with record |
| Tooth_Count : Natural; |
| Owner : String (1 .. 30); |
| end record; |
| pragma Import (C_Plus_Plus, Dog); |
| |
| function Number_Of_Teeth (A : Dog) return Natural; |
| pragma Import (C_Plus_Plus, Number_Of_Teeth); |
| |
| procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); |
| pragma Import (C_Plus_Plus, Set_Owner); |
| |
| function New_Dog return Dog; |
| pragma CPP_Constructor (New_Dog); |
| pragma Import (CPP, New_Dog, "_ZN3DogC2Ev"); |
| end Animals; |
| @end example |
| |
| Thanks to the compatibility between GNAT run-time structures and the C++ ABI, |
| interfacing with these C++ classes is easy. The only requirement is that all |
| the primitives and components must be declared exactly in the same order in |
| the two languages. |
| |
| Regarding the abstract interfaces, we must indicate to the GNAT compiler by |
| means of a @cite{pragma Convention (C_Plus_Plus)}, the convention used to pass |
| the arguments to the called primitives will be the same as for C++. For the |
| imported classes we use @cite{pragma Import} with convention @cite{C_Plus_Plus} |
| to indicate that they have been defined on the C++ side; this is required |
| because the dispatch table associated with these tagged types will be built |
| in the C++ side and therefore will not contain the predefined Ada primitives |
| which Ada would otherwise expect. |
| |
| As the reader can see there is no need to indicate the C++ mangled names |
| associated with each subprogram because it is assumed that all the calls to |
| these primitives will be dispatching calls. The only exception is the |
| constructor, which must be registered with the compiler by means of |
| @cite{pragma CPP_Constructor} and needs to provide its associated C++ |
| mangled name because the Ada compiler generates direct calls to it. |
| |
| With the above packages we can now declare objects of type Dog on the Ada side |
| and dispatch calls to the corresponding subprograms on the C++ side. We can |
| also extend the tagged type Dog with further fields and primitives, and |
| override some of its C++ primitives on the Ada side. For example, here we have |
| a type derivation defined on the Ada side that inherits all the dispatching |
| primitives of the ancestor from the C++ side. |
| |
| @example |
| with Animals; use Animals; |
| package Vaccinated_Animals is |
| type Vaccinated_Dog is new Dog with null record; |
| function Vaccination_Expired (A : Vaccinated_Dog) return Boolean; |
| end Vaccinated_Animals; |
| @end example |
| |
| It is important to note that, because of the ABI compatibility, the programmer |
| does not need to add any further information to indicate either the object |
| layout or the dispatch table entry associated with each dispatching operation. |
| |
| Now let us define all the types and constructors on the Ada side and export |
| them to C++, using the same hierarchy of our previous example: |
| |
| @example |
| with Interfaces.C.Strings; |
| use Interfaces.C.Strings; |
| package Animals is |
| type Carnivore is limited interface; |
| pragma Convention (C_Plus_Plus, Carnivore); |
| function Number_Of_Teeth (X : Carnivore) |
| return Natural is abstract; |
| |
| type Domestic is limited interface; |
| pragma Convention (C_Plus_Plus, Domestic); |
| procedure Set_Owner |
| (X : in out Domestic; |
| Name : Chars_Ptr) is abstract; |
| |
| type Animal is tagged record |
| Age : Natural; |
| end record; |
| pragma Convention (C_Plus_Plus, Animal); |
| |
| procedure Set_Age (X : in out Animal; Age : Integer); |
| pragma Export (C_Plus_Plus, Set_Age); |
| |
| function Age (X : Animal) return Integer; |
| pragma Export (C_Plus_Plus, Age); |
| |
| function New_Animal return Animal'Class; |
| pragma Export (C_Plus_Plus, New_Animal); |
| |
| type Dog is new Animal and Carnivore and Domestic with record |
| Tooth_Count : Natural; |
| Owner : String (1 .. 30); |
| end record; |
| pragma Convention (C_Plus_Plus, Dog); |
| |
| function Number_Of_Teeth (A : Dog) return Natural; |
| pragma Export (C_Plus_Plus, Number_Of_Teeth); |
| |
| procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); |
| pragma Export (C_Plus_Plus, Set_Owner); |
| |
| function New_Dog return Dog'Class; |
| pragma Export (C_Plus_Plus, New_Dog); |
| end Animals; |
| @end example |
| |
| Compared with our previous example the only differences are the use of |
| @cite{pragma Convention} (instead of @cite{pragma Import}), and the use of |
| @cite{pragma Export} to indicate to the GNAT compiler that the primitives will |
| be available to C++. Thanks to the ABI compatibility, on the C++ side there is |
| nothing else to be done; as explained above, the only requirement is that all |
| the primitives and components are declared in exactly the same order. |
| |
| For completeness, let us see a brief C++ main program that uses the |
| declarations available in @cite{animals.h} (presented in our first example) to |
| import and use the declarations from the Ada side, properly initializing and |
| finalizing the Ada run-time system along the way: |
| |
| @example |
| #include "animals.h" |
| #include <iostream> |
| using namespace std; |
| |
| void Check_Carnivore (Carnivore *obj) @{...@} |
| void Check_Domestic (Domestic *obj) @{...@} |
| void Check_Animal (Animal *obj) @{...@} |
| void Check_Dog (Dog *obj) @{...@} |
| |
| extern "C" @{ |
| void adainit (void); |
| void adafinal (void); |
| Dog* new_dog (); |
| @} |
| |
| void test () |
| @{ |
| Dog *obj = new_dog(); // Ada constructor |
| Check_Carnivore (obj); // Check secondary DT |
| Check_Domestic (obj); // Check secondary DT |
| Check_Animal (obj); // Check primary DT |
| Check_Dog (obj); // Check primary DT |
| @} |
| |
| int main () |
| @{ |
| adainit (); test(); adafinal (); |
| return 0; |
| @} |
| @end example |
| |
| @node Generating Ada Bindings for C and C++ headers,Generating C Headers for Ada Specifications,Building Mixed Ada and C++ Programs,Mixed Language Programming |
| @anchor{gnat_ugn/the_gnat_compilation_model id70}@anchor{c9}@anchor{gnat_ugn/the_gnat_compilation_model generating-ada-bindings-for-c-and-c-headers}@anchor{1b} |
| @subsection Generating Ada Bindings for C and C++ headers |
| |
| |
| @geindex Binding generation (for C and C++ headers) |
| |
| @geindex C headers (binding generation) |
| |
| @geindex C++ headers (binding generation) |
| |
| GNAT includes a binding generator for C and C++ headers which is |
| intended to do 95% of the tedious work of generating Ada specs from C |
| or C++ header files. |
| |
| Note that this capability is not intended to generate 100% correct Ada specs, |
| and will is some cases require manual adjustments, although it can often |
| be used out of the box in practice. |
| |
| Some of the known limitations include: |
| |
| |
| @itemize * |
| |
| @item |
| only very simple character constant macros are translated into Ada |
| constants. Function macros (macros with arguments) are partially translated |
| as comments, to be completed manually if needed. |
| |
| @item |
| some extensions (e.g. vector types) are not supported |
| |
| @item |
| pointers to pointers or complex structures are mapped to System.Address |
| |
| @item |
| identifiers with identical name (except casing) will generate compilation |
| errors (e.g. @cite{shm_get} vs @cite{SHM_GET}). |
| @end itemize |
| |
| The code generated is using the Ada 2005 syntax, which makes it |
| easier to interface with other languages than previous versions of Ada. |
| |
| @menu |
| * Running the Binding Generator:: |
| * Generating Bindings for C++ Headers:: |
| * Switches:: |
| |
| @end menu |
| |
| @node Running the Binding Generator,Generating Bindings for C++ Headers,,Generating Ada Bindings for C and C++ headers |
| @anchor{gnat_ugn/the_gnat_compilation_model id71}@anchor{ca}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{cb} |
| @subsubsection Running the Binding Generator |
| |
| |
| The binding generator is part of the @emph{gcc} compiler and can be |
| invoked via the @emph{-fdump-ada-spec} switch, which will generate Ada |
| spec files for the header files specified on the command line, and all |
| header files needed by these files transitively. For example: |
| |
| @example |
| $ g++ -c -fdump-ada-spec -C /usr/include/time.h |
| $ gcc -c -gnat05 *.ads |
| @end example |
| |
| will generate, under GNU/Linux, the following files: @code{time_h.ads}, |
| @code{bits_time_h.ads}, @code{stddef_h.ads}, @code{bits_types_h.ads} which |
| correspond to the files @code{/usr/include/time.h}, |
| @code{/usr/include/bits/time.h}, etc..., and will then compile in Ada 2005 |
| mode these Ada specs. |
| |
| The @cite{-C} switch tells @emph{gcc} to extract comments from headers, |
| and will attempt to generate corresponding Ada comments. |
| |
| If you want to generate a single Ada file and not the transitive closure, you |
| can use instead the @emph{-fdump-ada-spec-slim} switch. |
| |
| You can optionally specify a parent unit, of which all generated units will |
| be children, using @cite{-fada-spec-parent=<unit>}. |
| |
| Note that we recommend when possible to use the @emph{g++} driver to |
| generate bindings, even for most C headers, since this will in general |
| generate better Ada specs. For generating bindings for C++ headers, it is |
| mandatory to use the @emph{g++} command, or @emph{gcc -x c++} which |
| is equivalent in this case. If @emph{g++} cannot work on your C headers |
| because of incompatibilities between C and C++, then you can fallback to |
| @emph{gcc} instead. |
| |
| For an example of better bindings generated from the C++ front-end, |
| the name of the parameters (when available) are actually ignored by the C |
| front-end. Consider the following C header: |
| |
| @example |
| extern void foo (int variable); |
| @end example |
| |
| with the C front-end, @cite{variable} is ignored, and the above is handled as: |
| |
| @example |
| extern void foo (int); |
| @end example |
| |
| generating a generic: |
| |
| @example |
| procedure foo (param1 : int); |
| @end example |
| |
| with the C++ front-end, the name is available, and we generate: |
| |
| @example |
| procedure foo (variable : int); |
| @end example |
| |
| In some cases, the generated bindings will be more complete or more meaningful |
| when defining some macros, which you can do via the @emph{-D} switch. This |
| is for example the case with @code{Xlib.h} under GNU/Linux: |
| |
| @example |
| $ g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h |
| @end example |
| |
| The above will generate more complete bindings than a straight call without |
| the @emph{-DXLIB_ILLEGAL_ACCESS} switch. |
| |
| In other cases, it is not possible to parse a header file in a stand-alone |
| manner, because other include files need to be included first. In this |
| case, the solution is to create a small header file including the needed |
| @cite{#include} and possible @cite{#define} directives. For example, to |
| generate Ada bindings for @code{readline/readline.h}, you need to first |
| include @code{stdio.h}, so you can create a file with the following two |
| lines in e.g. @code{readline1.h}: |
| |
| @example |
| #include <stdio.h> |
| #include <readline/readline.h> |
| @end example |
| |
| and then generate Ada bindings from this file: |
| |
| @example |
| $ g++ -c -fdump-ada-spec readline1.h |
| @end example |
| |
| @node Generating Bindings for C++ Headers,Switches,Running the Binding Generator,Generating Ada Bindings for C and C++ headers |
| @anchor{gnat_ugn/the_gnat_compilation_model id72}@anchor{cc}@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{cd} |
| @subsubsection Generating Bindings for C++ Headers |
| |
| |
| Generating bindings for C++ headers is done using the same options, always |
| with the @emph{g++} compiler. Note that generating Ada spec from C++ headers is a |
| much more complex job and support for C++ headers is much more limited that |
| support for C headers. As a result, you will need to modify the resulting |
| bindings by hand more extensively when using C++ headers. |
| |
| In this mode, C++ classes will be mapped to Ada tagged types, constructors |
| will be mapped using the @cite{CPP_Constructor} pragma, and when possible, |
| multiple inheritance of abstract classes will be mapped to Ada interfaces |
| (see the @emph{Interfacing to C++} section in the @cite{GNAT Reference Manual} |
| for additional information on interfacing to C++). |
| |
| For example, given the following C++ header file: |
| |
| @example |
| class Carnivore @{ |
| public: |
| virtual int Number_Of_Teeth () = 0; |
| @}; |
| |
| class Domestic @{ |
| public: |
| virtual void Set_Owner (char* Name) = 0; |
| @}; |
| |
| class Animal @{ |
| public: |
| int Age_Count; |
| virtual void Set_Age (int New_Age); |
| @}; |
| |
| class Dog : Animal, Carnivore, Domestic @{ |
| public: |
| int Tooth_Count; |
| char *Owner; |
| |
| virtual int Number_Of_Teeth (); |
| virtual void Set_Owner (char* Name); |
| |
| Dog(); |
| @}; |
| @end example |
| |
| The corresponding Ada code is generated: |
| |
| @example |
| package Class_Carnivore is |
| type Carnivore is limited interface; |
| pragma Import (CPP, Carnivore); |
| |
| function Number_Of_Teeth (this : access Carnivore) return int is abstract; |
| end; |
| use Class_Carnivore; |
| |
| package Class_Domestic is |
| type Domestic is limited interface; |
| pragma Import (CPP, Domestic); |
| |
| procedure Set_Owner |
| (this : access Domestic; |
| Name : Interfaces.C.Strings.chars_ptr) is abstract; |
| end; |
| use Class_Domestic; |
| |
| package Class_Animal is |
| type Animal is tagged limited record |
| Age_Count : aliased int; |
| end record; |
| pragma Import (CPP, Animal); |
| |
| procedure Set_Age (this : access Animal; New_Age : int); |
| pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi"); |
| end; |
| use Class_Animal; |
| |
| package Class_Dog is |
| type Dog is new Animal and Carnivore and Domestic with record |
| Tooth_Count : aliased int; |
| Owner : Interfaces.C.Strings.chars_ptr; |
| end record; |
| pragma Import (CPP, Dog); |
| |
| function Number_Of_Teeth (this : access Dog) return int; |
| pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv"); |
| |
| procedure Set_Owner |
| (this : access Dog; Name : Interfaces.C.Strings.chars_ptr); |
| pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc"); |
| |
| function New_Dog return Dog; |
| pragma CPP_Constructor (New_Dog); |
| pragma Import (CPP, New_Dog, "_ZN3DogC1Ev"); |
| end; |
| use Class_Dog; |
| @end example |
| |
| @node Switches,,Generating Bindings for C++ Headers,Generating Ada Bindings for C and C++ headers |
| @anchor{gnat_ugn/the_gnat_compilation_model switches}@anchor{ce}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-ada-binding-generation}@anchor{cf} |
| @subsubsection Switches |
| |
| |
| @geindex -fdump-ada-spec (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fdump-ada-spec} |
| |
| Generate Ada spec files for the given header files transitively (including |
| all header files that these headers depend upon). |
| @end table |
| |
| @geindex -fdump-ada-spec-slim (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fdump-ada-spec-slim} |
| |
| Generate Ada spec files for the header files specified on the command line |
| only. |
| @end table |
| |
| @geindex -fada-spec-parent (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fada-spec-parent=@emph{unit}} |
| |
| Specifies that all files generated by @emph{-fdump-ada-spec*} are |
| to be child units of the specified parent unit. |
| @end table |
| |
| @geindex -C (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-C} |
| |
| Extract comments from headers and generate Ada comments in the Ada spec files. |
| @end table |
| |
| @node Generating C Headers for Ada Specifications,,Generating Ada Bindings for C and C++ headers,Mixed Language Programming |
| @anchor{gnat_ugn/the_gnat_compilation_model generating-c-headers-for-ada-specifications}@anchor{d0}@anchor{gnat_ugn/the_gnat_compilation_model id73}@anchor{d1} |
| @subsection Generating C Headers for Ada Specifications |
| |
| |
| @geindex Binding generation (for Ada specs) |
| |
| @geindex C headers (binding generation) |
| |
| GNAT includes a C header generator for Ada specifications which supports |
| Ada types that have a direct mapping to C types. This includes in particular |
| support for: |
| |
| |
| @itemize * |
| |
| @item |
| Scalar types |
| |
| @item |
| Constrained arrays |
| |
| @item |
| Records (untagged) |
| |
| @item |
| Composition of the above types |
| |
| @item |
| Constant declarations |
| |
| @item |
| Object declarations |
| |
| @item |
| Subprogram declarations |
| @end itemize |
| |
| @menu |
| * Running the C Header Generator:: |
| |
| @end menu |
| |
| @node Running the C Header Generator,,,Generating C Headers for Ada Specifications |
| @anchor{gnat_ugn/the_gnat_compilation_model running-the-c-header-generator}@anchor{d2} |
| @subsubsection Running the C Header Generator |
| |
| |
| The C header generator is part of the GNAT compiler and can be invoked via |
| the @emph{-gnatceg} combination of switches, which will generate a @code{.h} |
| file corresponding to the given input file (Ada spec or body). Note that |
| only spec files are processed in any case, so giving a spec or a body file |
| as input is equivalent. For example: |
| |
| @example |
| $ gcc -c -gnatceg pack1.ads |
| @end example |
| |
| will generate a self-contained file called @code{pack1.h} including |
| common definitions from the Ada Standard package, followed by the |
| definitions included in @code{pack1.ads}, as well as all the other units |
| withed by this file. |
| |
| For instance, given the following Ada files: |
| |
| @example |
| package Pack2 is |
| type Int is range 1 .. 10; |
| end Pack2; |
| @end example |
| |
| @example |
| with Pack2; |
| |
| package Pack1 is |
| type Rec is record |
| Field1, Field2 : Pack2.Int; |
| end record; |
| |
| Global : Rec := (1, 2); |
| |
| procedure Proc1 (R : Rec); |
| procedure Proc2 (R : in out Rec); |
| end Pack1; |
| @end example |
| |
| The above @cite{gcc} command will generate the following @code{pack1.h} file: |
| |
| @example |
| /* Standard definitions skipped */ |
| #ifndef PACK2_ADS |
| #define PACK2_ADS |
| typedef short_short_integer pack2__TintB; |
| typedef pack2__TintB pack2__int; |
| #endif /* PACK2_ADS */ |
| |
| #ifndef PACK1_ADS |
| #define PACK1_ADS |
| typedef struct _pack1__rec @{ |
| pack2__int field1; |
| pack2__int field2; |
| @} pack1__rec; |
| extern pack1__rec pack1__global; |
| extern void pack1__proc1(const pack1__rec r); |
| extern void pack1__proc2(pack1__rec *r); |
| #endif /* PACK1_ADS */ |
| @end example |
| |
| You can then @cite{include} @code{pack1.h} from a C source file and use the types, |
| call subprograms, reference objects, and constants. |
| |
| @node GNAT and Other Compilation Models,Using GNAT Files with External Tools,Mixed Language Programming,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model id74}@anchor{d3}@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{47} |
| @section GNAT and Other Compilation Models |
| |
| |
| This section compares the GNAT model with the approaches taken in |
| other environents, first the C/C++ model and then the mechanism that |
| has been used in other Ada systems, in particular those traditionally |
| used for Ada 83. |
| |
| @menu |
| * Comparison between GNAT and C/C++ Compilation Models:: |
| * Comparison between GNAT and Conventional Ada Library Models:: |
| |
| @end menu |
| |
| @node Comparison between GNAT and C/C++ Compilation Models,Comparison between GNAT and Conventional Ada Library Models,,GNAT and Other Compilation Models |
| @anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-c-c-compilation-models}@anchor{d4}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{d5} |
| @subsection 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 @emph{with} is similar in effect to the @cite{#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. |
| |
| @geindex Elaboration order control |
| |
| 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 @cite{gnatbind} might complain there was no valid order of |
| elaboration, a C++ compiler would simply construct a program that |
| malfunctioned at run time. |
| |
| @node Comparison between GNAT and Conventional Ada Library Models,,Comparison between GNAT and C/C++ Compilation Models,GNAT and Other Compilation Models |
| @anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-conventional-ada-library-models}@anchor{d6}@anchor{gnat_ugn/the_gnat_compilation_model id76}@anchor{d7} |
| @subsection Comparison between GNAT and Conventional Ada Library Models |
| |
| |
| This section is intended for Ada programmers who have |
| used an Ada compiler implementing the traditional Ada library |
| model, as described in the Ada Reference Manual. |
| |
| @geindex GNAT library |
| |
| 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: |
| |
| |
| @itemize * |
| |
| @item |
| When a unit is @emph{with}ed, the unit seen by the compiler corresponds |
| to the version of the unit most recently compiled into the library. |
| |
| @item |
| Inlining is effective only if the necessary body has already been |
| compiled into the library. |
| |
| @item |
| Compiling a unit may obsolete other units in the library. |
| @end itemize |
| |
| 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: |
| |
| |
| @itemize * |
| |
| @item |
| When a unit is @emph{with}ed, the unit seen by the compiler corresponds |
| to the source version of the unit that is currently accessible to the |
| compiler. |
| |
| @geindex Inlining |
| |
| @item |
| 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 compiled. |
| |
| @item |
| 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. |
| @end itemize |
| |
| 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. |
| |
| @node Using GNAT Files with External Tools,,GNAT and Other Compilation Models,The GNAT Compilation Model |
| @anchor{gnat_ugn/the_gnat_compilation_model using-gnat-files-with-external-tools}@anchor{1c}@anchor{gnat_ugn/the_gnat_compilation_model id77}@anchor{d8} |
| @section Using GNAT Files with External Tools |
| |
| |
| This section explains how files that are produced by GNAT may be |
| used with tools designed for other languages. |
| |
| @menu |
| * Using Other Utility Programs with GNAT:: |
| * The External Symbol Naming Scheme of GNAT:: |
| |
| @end menu |
| |
| @node Using Other Utility Programs with GNAT,The External Symbol Naming Scheme of GNAT,,Using GNAT Files with External Tools |
| @anchor{gnat_ugn/the_gnat_compilation_model using-other-utility-programs-with-gnat}@anchor{d9}@anchor{gnat_ugn/the_gnat_compilation_model id78}@anchor{da} |
| @subsection 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. |
| |
| @node The External Symbol Naming Scheme of GNAT,,Using Other Utility Programs with GNAT,Using GNAT Files with External Tools |
| @anchor{gnat_ugn/the_gnat_compilation_model the-external-symbol-naming-scheme-of-gnat}@anchor{db}@anchor{gnat_ugn/the_gnat_compilation_model id79}@anchor{dc} |
| @subsection 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: |
| |
| @example |
| package QRS is |
| MN : Integer; |
| end QRS; |
| @end example |
| |
| @geindex pragma Export |
| |
| The variable @cite{MN} has a full expanded Ada name of @cite{QRS.MN}, so |
| the corresponding link name is @cite{qrs__mn}. |
| Of course if a @cite{pragma Export} is used this may be overridden: |
| |
| @example |
| 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; |
| @end example |
| |
| In this case, the link name for @cite{Var1} is whatever link name the |
| C compiler would assign for the C function @cite{var1_name}. This typically |
| would be either @cite{var1_name} or @cite{_var1_name}, depending on operating |
| system conventions, but other possibilities exist. The link name for |
| @cite{Var2} is @cite{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 @cite{_main} for the C main program, |
| and the name we would otherwise assign to an Ada library level procedure |
| called @cite{Main} (which might well not be the main program). |
| |
| To avoid this ambiguity, we attach the prefix @cite{_ada_} to such |
| names. So if we have a library level procedure such as: |
| |
| @example |
| procedure Hello (S : String); |
| @end example |
| |
| the external name of this procedure will be @cite{_ada_hello}. |
| |
| @c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit |
| |
| @node Building Executable Programs with GNAT,GNAT Project Manager,The GNAT Compilation Model,Top |
| @anchor{gnat_ugn/building_executable_programs_with_gnat building-executable-programs-with-gnat}@anchor{a}@anchor{gnat_ugn/building_executable_programs_with_gnat doc}@anchor{dd}@anchor{gnat_ugn/building_executable_programs_with_gnat id1}@anchor{de} |
| @chapter Building Executable Programs with GNAT |
| |
| |
| This chapter describes first the gnatmake tool |
| (@ref{1d,,Building with gnatmake}), |
| which automatically determines the set of sources |
| needed by an Ada compilation unit and executes the necessary |
| (re)compilations, binding and linking. |
| It also explains how to use each tool individually: the |
| compiler (gcc, see @ref{1e,,Compiling with gcc}), |
| binder (gnatbind, see @ref{1f,,Binding with gnatbind}), |
| and linker (gnatlink, see @ref{20,,Linking with gnatlink}) |
| to build executable programs. |
| Finally, this chapter provides examples of |
| how to make use of the general GNU make mechanism |
| in a GNAT context (see @ref{21,,Using the GNU make Utility}). |
| |
| @menu |
| * Building with gnatmake:: |
| * Compiling with gcc:: |
| * Compiler Switches:: |
| * Binding with gnatbind:: |
| * Linking with gnatlink:: |
| * Using the GNU make Utility:: |
| |
| @end menu |
| |
| @node Building with gnatmake,Compiling with gcc,,Building Executable Programs with GNAT |
| @anchor{gnat_ugn/building_executable_programs_with_gnat the-gnat-make-program-gnatmake}@anchor{1d}@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{df} |
| @section Building with @emph{gnatmake} |
| |
| |
| @geindex gnatmake |
| |
| A typical development cycle when working on an Ada program consists of |
| the following steps: |
| |
| |
| @enumerate |
| |
| @item |
| Edit some sources to fix bugs; |
| |
| @item |
| Add enhancements; |
| |
| @item |
| Compile all sources affected; |
| |
| @item |
| Rebind and relink; and |
| |
| @item |
| Test. |
| @end enumerate |
| |
| @geindex Dependency rules (compilation) |
| |
| The third step in particular 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, @cite{use} clauses, generics and inlined |
| subprograms. |
| |
| @emph{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 |
| @emph{gnatmake}. |
| |
| Note that for advanced description of project structure, we recommend creating |
| a project file as explained in @ref{b,,GNAT Project Manager} and use the |
| @emph{gprbuild} tool which supports building with project files and works similarly |
| to @emph{gnatmake}. |
| |
| @menu |
| * Running gnatmake:: |
| * Switches for gnatmake:: |
| * Mode Switches for gnatmake:: |
| * Notes on the Command Line:: |
| * How gnatmake Works:: |
| * Examples of gnatmake Usage:: |
| |
| @end menu |
| |
| @node Running gnatmake,Switches for gnatmake,,Building with gnatmake |
| @anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{e0}@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{e1} |
| @subsection Running @emph{gnatmake} |
| |
| |
| The usual form of the @emph{gnatmake} command is |
| |
| @example |
| $ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>] |
| @end example |
| |
| The only required argument is one @cite{file_name}, which specifies |
| a compilation unit that is a main program. Several @cite{file_names} can be |
| specified: this will result in several executables being built. |
| If @cite{switches} are present, they can be placed before the first |
| @cite{file_name}, between @cite{file_names} or after the last @cite{file_name}. |
| If @cite{mode_switches} are present, they must always be placed after |
| the last @cite{file_name} and all @cite{switches}. |
| |
| If you are using standard file extensions (@code{.adb} and |
| @code{.ads}), then the |
| extension may be omitted from the @cite{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 @cite{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 |
| @emph{gnatmake} was invoked and if it is not found, it will be search on |
| the source path of the compiler as described in |
| @ref{8e,,Search Paths and the Run-Time Library (RTL)}. |
| |
| All @emph{gnatmake} output (except when you specify @emph{-M}) is sent to |
| @code{stderr}. The output produced by the |
| @emph{-M} switch is sent to @code{stdout}. |
| |
| @node Switches for gnatmake,Mode Switches for gnatmake,Running gnatmake,Building with gnatmake |
| @anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatmake}@anchor{e2}@anchor{gnat_ugn/building_executable_programs_with_gnat id3}@anchor{e3} |
| @subsection Switches for @emph{gnatmake} |
| |
| |
| You may specify any of the following switches to @emph{gnatmake}: |
| |
| @geindex --version (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{--version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{--help} |
| |
| If @code{--version} was not used, display usage, then exit disregarding |
| all other options. |
| @end table |
| |
| @geindex --GCC=compiler_name (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{--GCC=@emph{compiler_name}} |
| |
| Program used for compiling. The default is @code{gcc}. You need to use |
| quotes around @cite{compiler_name} if @cite{compiler_name} contains |
| spaces or other separator characters. |
| As an example @code{--GCC="foo -x -y"} |
| will instruct @emph{gnatmake} to use @code{foo -x -y} as your |
| compiler. A limitation of this syntax is that the name and path name of |
| the executable itself must not include any embedded spaces. Note that |
| switch @code{-c} is always inserted after your command name. Thus in the |
| above example the compiler command that will be used by @emph{gnatmake} |
| will be @code{foo -c -x -y}. If several @code{--GCC=compiler_name} are |
| used, only the last @cite{compiler_name} is taken into account. However, |
| all the additional switches are also taken into account. Thus, |
| @code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to |
| @code{--GCC="bar -x -y -z -t"}. |
| @end table |
| |
| @geindex --GNATBIND=binder_name (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{--GNATBIND=@emph{binder_name}} |
| |
| Program used for binding. The default is @code{gnatbind}. You need to |
| use quotes around @cite{binder_name} if @cite{binder_name} contains spaces |
| or other separator characters. |
| As an example @code{--GNATBIND="bar -x -y"} |
| will instruct @emph{gnatmake} to use @cite{bar -x -y} as your |
| binder. Binder switches that are normally appended by @emph{gnatmake} |
| to @code{gnatbind} are now appended to the end of @cite{bar -x -y}. |
| A limitation of this syntax is that the name and path name of the executable |
| itself must not include any embedded spaces. |
| @end table |
| |
| @geindex --GNATLINK=linker_name (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{--GNATLINK=@emph{linker_name}} |
| |
| Program used for linking. The default is @code{gnatlink}. You need to |
| use quotes around @cite{linker_name} if @cite{linker_name} contains spaces |
| or other separator characters. |
| As an example @code{--GNATLINK="lan -x -y"} |
| will instruct @emph{gnatmake} to use @code{lan -x -y} as your |
| linker. Linker switches that are normally appended by @code{gnatmake} to |
| @code{gnatlink} are now appended to the end of @code{lan -x -y}. |
| A limitation of this syntax is that the name and path name of the executable |
| itself must not include any embedded spaces. |
| |
| @item @code{--create-map-file} |
| |
| When linking an executable, create a map file. The name of the map file |
| has the same name as the executable with extension ".map". |
| |
| @item @code{--create-map-file=@emph{mapfile}} |
| |
| When linking an executable, create a map file with the specified name. |
| @end table |
| |
| @geindex --create-missing-dirs (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{--create-missing-dirs} |
| |
| When using project files (@code{-P@emph{project}}), automatically create |
| missing object directories, library directories and exec |
| directories. |
| |
| @item @code{--single-compile-per-obj-dir} |
| |
| Disallow simultaneous compilations in the same object directory when |
| project files are used. |
| |
| @item @code{--subdirs=@emph{subdir}} |
| |
| Actual object directory of each project file is the subdirectory subdir of the |
| object directory specified or defaulted in the project file. |
| |
| @item @code{--unchecked-shared-lib-imports} |
| |
| By default, shared library projects are not allowed to import static library |
| projects. When this switch is used on the command line, this restriction is |
| relaxed. |
| |
| @item @code{--source-info=@emph{source info file}} |
| |
| Specify a source info file. This switch is active only when project files |
| are used. If the source info file is specified as a relative path, then it is |
| relative to the object directory of the main project. If the source info file |
| does not exist, then after the Project Manager has successfully parsed and |
| processed the project files and found the sources, it creates the source info |
| file. If the source info file already exists and can be read successfully, |
| then the Project Manager will get all the needed information about the sources |
| from the source info file and will not look for them. This reduces the time |
| to process the project files, especially when looking for sources that take a |
| long time. If the source info file exists but cannot be parsed successfully, |
| the Project Manager will attempt to recreate it. If the Project Manager fails |
| to create the source info file, a message is issued, but gnatmake does not |
| fail. @emph{gnatmake} "trusts" the source info file. This means that |
| if the source files have changed (addition, deletion, moving to a different |
| source directory), then the source info file need to be deleted and recreated. |
| @end table |
| |
| @geindex -a (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-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, |
| @emph{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. The switch @code{-a} is also useful |
| in conjunction with @code{-f} |
| if you need to recompile an entire application, |
| including run-time files, using special configuration pragmas, |
| such as a @cite{Normalize_Scalars} pragma. |
| |
| By default |
| @code{gnatmake -a} compiles all GNAT |
| internal files with |
| @code{gcc -c -gnatpg} rather than @code{gcc -c}. |
| @end table |
| |
| @geindex -b (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-b} |
| |
| Bind only. Can be combined with @emph{-c} to do |
| compilation and binding, but no link. |
| Can be combined with @emph{-l} |
| to do binding and linking. When not combined with |
| @emph{-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 @cite{file_name} |
| may be given without extension, with the source extension or, if no GNAT |
| Project File is specified, with the ALI file extension. |
| @end table |
| |
| @geindex -c (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-c} |
| |
| Compile only. Do not perform binding, except when @emph{-b} |
| is also specified. Do not perform linking, except if both |
| @emph{-b} and |
| @emph{-l} are also specified. |
| If the root unit specified by @cite{file_name} is not a main unit, this is the |
| default. Otherwise @emph{gnatmake} will attempt binding and linking |
| unless all objects are up to date and the executable is more recent than |
| the objects. |
| @end table |
| |
| @geindex -C (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-C} |
| |
| Use a temporary 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). A mapping file can make the compiler's |
| file searches faster, especially if there are many source directories, |
| or the sources are read over a slow network connection. If |
| @emph{-P} is used, a mapping file is always used, so |
| @emph{-C} is unnecessary; in this case the mapping file |
| is initially populated based on the project file. If |
| @emph{-C} is used without |
| @emph{-P}, |
| the mapping file is initially empty. Each invocation of the compiler |
| will add any newly accessed sources to the mapping file. |
| @end table |
| |
| @geindex -C= (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-C=@emph{file}} |
| |
| Use a specific mapping file. The file, specified as a path name (absolute or |
| relative) by this switch, should already exist, otherwise the switch is |
| ineffective. The specified mapping file will be communicated to the compiler. |
| This switch is not compatible with a project file |
| (-P`file`) or with multiple compiling processes |
| (-jnnn, when nnn is greater than 1). |
| @end table |
| |
| @geindex -d (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-d} |
| |
| Display progress for each source, up to date or not, as a single line: |
| |
| @example |
| completed x out of y (zz%) |
| @end example |
| |
| If the file needs to be compiled this is displayed after the invocation of |
| the compiler. These lines are displayed even in quiet output mode. |
| @end table |
| |
| @geindex -D (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-D @emph{dir}} |
| |
| Put all object files and ALI file in directory @cite{dir}. |
| If the @emph{-D} switch is not used, all object files |
| and ALI files go in the current working directory. |
| |
| This switch cannot be used when using a project file. |
| @end table |
| |
| @geindex -eI (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-eI@emph{nnn}} |
| |
| Indicates that the main source is a multi-unit source and the rank of the unit |
| in the source file is nnn. nnn needs to be a positive number and a valid |
| index in the source. This switch cannot be used when @emph{gnatmake} is |
| invoked for several mains. |
| @end table |
| |
| @geindex -eL (gnatmake) |
| |
| @geindex symbolic links |
| |
| |
| @table @asis |
| |
| @item @code{-eL} |
| |
| Follow all symbolic links when processing project files. |
| This should be used if your project uses symbolic links for files or |
| directories, but is not needed in other cases. |
| |
| @geindex naming scheme |
| |
| This also assumes that no directory matches the naming scheme for files (for |
| instance that you do not have a directory called "sources.ads" when using the |
| default GNAT naming scheme). |
| |
| When you do not have to use this switch (i.e., by default), gnatmake is able to |
| save a lot of system calls (several per source file and object file), which |
| can result in a significant speed up to load and manipulate a project file, |
| especially when using source files from a remote system. |
| @end table |
| |
| @geindex -eS (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-eS} |
| |
| Output the commands for the compiler, the binder and the linker |
| on standard output, |
| instead of standard error. |
| @end table |
| |
| @geindex -f (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-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 @emph{-a} switch is also specified. |
| @end table |
| |
| @geindex -F (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-F} |
| |
| When using project files, if some errors or warnings are detected during |
| parsing and verbose mode is not in effect (no use of switch |
| -v), then error lines start with the full path name of the project |
| file, rather than its simple file name. |
| @end table |
| |
| @geindex -g (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-g} |
| |
| Enable debugging. This switch is simply passed to the compiler and to the |
| linker. |
| @end table |
| |
| @geindex -i (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-i} |
| |
| In normal mode, @emph{gnatmake} compiles all object files and ALI files |
| into the current directory. If the @emph{-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 @emph{gnatmake} will automatically |
| maintain and update this organization. If no ALI files are found on the |
| Ada object path (see @ref{8e,,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, @emph{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. |
| @end table |
| |
| @geindex -j (gnatmake) |
| |
| @geindex Parallel make |
| |
| |
| @table @asis |
| |
| @item @code{-j@emph{n}} |
| |
| Use @cite{n} processes to carry out the (re)compilations. On a multiprocessor |
| machine compilations will occur in parallel. If @cite{n} is 0, then the |
| maximum number of parallel compilations is the number of core processors |
| on the platform. In the event of compilation errors, messages from various |
| compilations might get interspersed (but @emph{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. |
| @end table |
| |
| @geindex -k (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-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 @emph{gnatmake} |
| terminates. |
| |
| If @emph{gnatmake} is invoked with several @code{file_names} and with this |
| switch, if there are compilation errors when building an executable, |
| @emph{gnatmake} will not attempt to build the following executables. |
| @end table |
| |
| @geindex -l (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-l} |
| |
| Link only. Can be combined with @emph{-b} to binding |
| and linking. Linking will not be performed if combined with |
| @emph{-c} |
| but not with @emph{-b}. |
| When not combined with @emph{-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 needs to have been bound. |
| The root unit specified by @cite{file_name} |
| may be given without extension, with the source extension or, if no GNAT |
| Project File is specified, with the ALI file extension. |
| @end table |
| |
| @geindex -m (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-m} |
| |
| Specify that the minimum necessary amount of recompilations |
| be performed. In this mode @emph{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 @emph{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 @emph{-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. |
| @end table |
| |
| @geindex Dependencies |
| @geindex producing list |
| |
| @geindex -M (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-M} |
| |
| Check if all objects are up to date. If they are, output the object |
| dependences to @code{stdout} in a form that can be directly exploited in |
| a @code{Makefile}. By default, each source file is prefixed with its |
| (relative or absolute) directory name. This name is whatever you |
| specified in the various @emph{-aI} |
| and @emph{-I} switches. If you use |
| @cite{gnatmake -M} @emph{-q} |
| (see below), only the source file names, |
| without relative paths, are output. If you just specify the @emph{-M} |
| switch, dependencies of the GNAT internal system files are omitted. This |
| is typically what you want. If you also specify |
| the @emph{-a} switch, |
| dependencies of the GNAT internal files are also listed. Note that |
| dependencies of the objects in external Ada libraries (see |
| switch @code{-aL@emph{dir}} in the following list) |
| are never reported. |
| @end table |
| |
| @geindex -n (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| @end table |
| |
| @geindex -o (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-o @emph{exec_name}} |
| |
| Output executable name. The name of the final executable program will be |
| @cite{exec_name}. If the @emph{-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 @emph{gnatmake} with several |
| @code{file_names}. |
| @end table |
| |
| @geindex -p (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-p} |
| |
| Same as @code{--create-missing-dirs} |
| @end table |
| |
| @geindex -P (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-P@emph{project}} |
| |
| Use project file @cite{project}. Only one such switch can be used. |
| @ref{e4,,gnatmake and Project Files}. |
| @end table |
| |
| @geindex -q (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-q} |
| |
| Quiet. When this flag is not set, the commands carried out by |
| @emph{gnatmake} are displayed. |
| @end table |
| |
| @geindex -s (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-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, |
| @emph{-O -O2} is different than @emph{-O2 -O}, but @emph{-g -O} |
| is equivalent to @emph{-O -g}. |
| |
| This switch is recommended when Integrated Preprocessing is used. |
| @end table |
| |
| @geindex -u (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-u} |
| |
| Unique. Recompile at most the main files. It implies -c. Combined with |
| -f, it is equivalent to calling the compiler directly. Note that using |
| -u with a project file and no main has a special meaning |
| (@ref{e5,,Project Files and Main Subprograms}). |
| @end table |
| |
| @geindex -U (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-U} |
| |
| When used without a project file or with one or several mains on the command |
| line, is equivalent to -u. When used with a project file and no main |
| on the command line, all sources of all project files are checked and compiled |
| if not up to date, and libraries are rebuilt, if necessary. |
| @end table |
| |
| @geindex -v (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-v} |
| |
| Verbose. Display the reason for all recompilations @emph{gnatmake} |
| decides are necessary, with the highest verbosity level. |
| @end table |
| |
| @geindex -vl (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-vl} |
| |
| Verbosity level Low. Display fewer lines than in verbosity Medium. |
| @end table |
| |
| @geindex -vm (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-vm} |
| |
| Verbosity level Medium. Potentially display fewer lines than in verbosity High. |
| @end table |
| |
| @geindex -vm (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-vh} |
| |
| Verbosity level High. Equivalent to -v. |
| |
| @item @code{-vP@emph{x}} |
| |
| Indicate the verbosity of the parsing of GNAT project files. |
| See @ref{e6,,Switches Related to Project Files}. |
| @end table |
| |
| @geindex -x (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-x} |
| |
| Indicate that sources that are not part of any Project File may be compiled. |
| Normally, when using Project Files, only sources that are part of a Project |
| File may be compile. When this switch is used, a source outside of all Project |
| Files may be compiled. The ALI file and the object file will be put in the |
| object directory of the main Project. The compilation switches used will only |
| be those specified on the command line. Even when |
| @emph{-x} is used, mains specified on the |
| command line need to be sources of a project file. |
| |
| @item @code{-X@emph{name}=@emph{value}} |
| |
| Indicate that external variable @cite{name} has the value @cite{value}. |
| The Project Manager will use this value for occurrences of |
| @cite{external(name)} when parsing the project file. |
| @ref{e6,,Switches Related to Project Files}. |
| @end table |
| |
| @geindex -z (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| @end table |
| |
| @subsubheading GCC switches |
| |
| |
| Any uppercase or multi-character switch that is not a @emph{gnatmake} switch |
| is passed to @emph{gcc} (e.g., @emph{-O}, @emph{-gnato,} etc.) |
| |
| @subsubheading Source and library search path switches |
| |
| |
| @geindex -aI (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-aI@emph{dir}} |
| |
| When looking for source files also look in directory @cite{dir}. |
| The order in which source files search is undertaken is |
| described in @ref{8e,,Search Paths and the Run-Time Library (RTL)}. |
| @end table |
| |
| @geindex -aL (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-aL@emph{dir}} |
| |
| Consider @cite{dir} as being an externally provided Ada library. |
| Instructs @emph{gnatmake} to skip compilation units whose @code{.ALI} |
| files have been located in directory @cite{dir}. This allows you to have |
| missing bodies for the units in @cite{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 |
| @code{-aI@emph{dir}} or @code{-I@emph{dir}}. |
| Note: this switch is provided for compatibility with previous versions |
| of @emph{gnatmake}. The easier method of causing standard libraries |
| to be excluded from consideration is to write-protect the corresponding |
| ALI files. |
| @end table |
| |
| @geindex -aO (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-aO@emph{dir}} |
| |
| When searching for library and object files, look in directory |
| @cite{dir}. The order in which library files are searched is described in |
| @ref{91,,Search Paths for gnatbind}. |
| @end table |
| |
| @geindex Search paths |
| @geindex for gnatmake |
| |
| @geindex -A (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-A@emph{dir}} |
| |
| Equivalent to @code{-aL@emph{dir}} @code{-aI@emph{dir}}. |
| |
| @geindex -I (gnatmake) |
| |
| @item @code{-I@emph{dir}} |
| |
| Equivalent to @code{-aO@emph{dir} -aI@emph{dir}}. |
| @end table |
| |
| @geindex -I- (gnatmake) |
| |
| @geindex Source files |
| @geindex suppressing search |
| |
| |
| @table @asis |
| |
| @item @code{-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 @emph{gnatmake} was invoked. |
| @end table |
| |
| @geindex -L (gnatmake) |
| |
| @geindex Linker libraries |
| |
| |
| @table @asis |
| |
| @item @code{-L@emph{dir}} |
| |
| Add directory @cite{dir} to the list of directories in which the linker |
| will search for libraries. This is equivalent to |
| @code{-largs} @code{-L@emph{dir}}. |
| Furthermore, under Windows, the sources pointed to by the libraries path |
| set in the registry are not searched for. |
| @end table |
| |
| @geindex -nostdinc (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-nostdinc} |
| |
| Do not look for source files in the system default directory. |
| @end table |
| |
| @geindex -nostdlib (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-nostdlib} |
| |
| Do not look for library files in the system default directory. |
| @end table |
| |
| @geindex --RTS (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{--RTS=@emph{rts-path}} |
| |
| Specifies the default location of the runtime library. GNAT looks for the |
| runtime |
| in the following directories, and stops as soon as a valid runtime is found |
| (@code{adainclude} or @code{ada_source_path}, and @code{adalib} or |
| @code{ada_object_path} present): |
| |
| |
| @itemize * |
| |
| @item |
| @emph{<current directory>/$rts_path} |
| |
| @item |
| @emph{<default-search-dir>/$rts_path} |
| |
| @item |
| @emph{<default-search-dir>/rts-$rts_path} |
| |
| @item |
| The selected path is handled like a normal RTS path. |
| @end itemize |
| @end table |
| |
| @node Mode Switches for gnatmake,Notes on the Command Line,Switches for gnatmake,Building with gnatmake |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id4}@anchor{e7}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{e8} |
| @subsection Mode Switches for @emph{gnatmake} |
| |
| |
| The mode switches (referred to as @cite{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. |
| |
| @geindex -cargs (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-cargs @emph{switches}} |
| |
| Compiler switches. Here @cite{switches} is a list of switches |
| that are valid switches for @emph{gcc}. They will be passed on to |
| all compile steps performed by @emph{gnatmake}. |
| @end table |
| |
| @geindex -bargs (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-bargs @emph{switches}} |
| |
| Binder switches. Here @cite{switches} is a list of switches |
| that are valid switches for @cite{gnatbind}. They will be passed on to |
| all bind steps performed by @emph{gnatmake}. |
| @end table |
| |
| @geindex -largs (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-largs @emph{switches}} |
| |
| Linker switches. Here @cite{switches} is a list of switches |
| that are valid switches for @emph{gnatlink}. They will be passed on to |
| all link steps performed by @emph{gnatmake}. |
| @end table |
| |
| @geindex -margs (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{-margs @emph{switches}} |
| |
| Make switches. The switches are directly interpreted by @emph{gnatmake}, |
| regardless of any previous occurrence of @emph{-cargs}, @emph{-bargs} |
| or @emph{-largs}. |
| @end table |
| |
| @node Notes on the Command Line,How gnatmake Works,Mode Switches for gnatmake,Building with gnatmake |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id5}@anchor{e9}@anchor{gnat_ugn/building_executable_programs_with_gnat notes-on-the-command-line}@anchor{ea} |
| @subsection Notes on the Command Line |
| |
| |
| This section contains some additional useful notes on the operation |
| of the @emph{gnatmake} command. |
| |
| @geindex Recompilation (by gnatmake) |
| |
| |
| @itemize * |
| |
| @item |
| If @emph{gnatmake} finds no ALI files, it recompiles the main program |
| and all other units required by the main program. |
| This means that @emph{gnatmake} |
| can be used for the initial compile, as well as during subsequent steps of |
| the development cycle. |
| |
| @item |
| If you enter @code{gnatmake foo.adb}, where @code{foo} |
| is a subunit or body of a generic unit, @emph{gnatmake} recompiles |
| @code{foo.adb} (because it finds no ALI) and stops, issuing a |
| warning. |
| |
| @item |
| In @emph{gnatmake} the switch @emph{-I} |
| is used to specify both source and |
| library file paths. Use @emph{-aI} |
| instead if you just want to specify |
| source paths only and @emph{-aO} |
| if you want to specify library paths |
| only. |
| |
| @item |
| @emph{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 |
| @emph{-f} switch will not recompile these files |
| unless @emph{-a} is also specified. |
| |
| @item |
| @emph{gnatmake} has been designed to make the use of Ada libraries |
| particularly convenient. Assume you have an Ada library organized |
| as follows: @emph{obj-dir} contains the objects and ALI files for |
| of your Ada compilation units, |
| whereas @emph{include-dir} contains the |
| specs of these units, but no bodies. Then to compile a unit |
| stored in @cite{main.adb}, which uses this Ada library you would just type: |
| |
| @example |
| $ gnatmake -aI`include-dir` -aL`obj-dir` main |
| @end example |
| |
| @item |
| Using @emph{gnatmake} along with the @emph{-m (minimal recompilation)} |
| switch provides a mechanism for avoiding unnecessary recompilations. 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. |
| @end itemize |
| |
| @node How gnatmake Works,Examples of gnatmake Usage,Notes on the Command Line,Building with gnatmake |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id6}@anchor{eb}@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{ec} |
| @subsection How @emph{gnatmake} Works |
| |
| |
| Generally @emph{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 @emph{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 @emph{up to date} if the |
| corresponding ALI file exists 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. |
| |
| @emph{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, |
| @emph{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 @emph{gnatmake} recursively applies the above procedure on all these |
| files. |
| |
| This process ensures that @emph{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 |
| @emph{gnatmake} will recompute a correct set of new dependencies if |
| necessary. |
| |
| When invoking @emph{gnatmake} with several @cite{file_names}, if a unit is |
| imported by several of the executables, it will be recompiled at most once. |
| |
| Note: when using non-standard naming conventions |
| (@ref{37,,Using Other File Names}), changing through a configuration pragmas |
| file the version of a source and invoking @emph{gnatmake} to recompile may |
| have no effect, if the previous version of the source is still accessible |
| by @emph{gnatmake}. It may be necessary to use the switch |
| -f. |
| |
| @node Examples of gnatmake Usage,,How gnatmake Works,Building with gnatmake |
| @anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatmake-usage}@anchor{ed}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{ee} |
| @subsection Examples of @emph{gnatmake} Usage |
| |
| |
| |
| @table @asis |
| |
| @item @emph{gnatmake hello.adb} |
| |
| Compile all files necessary to bind and link the main program |
| @code{hello.adb} (containing unit @cite{Hello}) and bind and link the |
| resulting object files to generate an executable file @code{hello}. |
| |
| @item @emph{gnatmake main1 main2 main3} |
| |
| Compile all files necessary to bind and link the main programs |
| @code{main1.adb} (containing unit @cite{Main1}), @code{main2.adb} |
| (containing unit @cite{Main2}) and @code{main3.adb} |
| (containing unit @cite{Main3}) and bind and link the resulting object files |
| to generate three executable files @code{main1}, |
| @code{main2} and @code{main3}. |
| |
| @item @emph{gnatmake -q Main_Unit -cargs -O2 -bargs -l} |
| |
| Compile all files necessary to bind and link the main program unit |
| @cite{Main_Unit} (from file @code{main_unit.adb}). All compilations will |
| be done with optimization level 2 and the order of elaboration will be |
| listed by the binder. @emph{gnatmake} will operate in quiet mode, not |
| displaying commands it is executing. |
| @end table |
| |
| @node Compiling with gcc,Compiler Switches,Building with gnatmake,Building Executable Programs with GNAT |
| @anchor{gnat_ugn/building_executable_programs_with_gnat compiling-with-gcc}@anchor{1e}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{ef} |
| @section Compiling with @emph{gcc} |
| |
| |
| This section discusses how to compile Ada programs using the @emph{gcc} |
| command. It also describes the set of switches |
| that can be used to control the behavior of the compiler. |
| |
| @menu |
| * Compiling Programs:: |
| * Search Paths and the Run-Time Library (RTL): Search Paths and the Run-Time Library RTL. |
| * Order of Compilation Issues:: |
| * Examples:: |
| |
| @end menu |
| |
| @node Compiling Programs,Search Paths and the Run-Time Library RTL,,Compiling with gcc |
| @anchor{gnat_ugn/building_executable_programs_with_gnat compiling-programs}@anchor{f0}@anchor{gnat_ugn/building_executable_programs_with_gnat id9}@anchor{f1} |
| @subsection Compiling Programs |
| |
| |
| The first step in creating an executable program is to compile the units |
| of the program using the @emph{gcc} command. You must compile the |
| following files: |
| |
| |
| @itemize * |
| |
| @item |
| the body file (@code{.adb}) for a library level subprogram or generic |
| subprogram |
| |
| @item |
| the spec file (@code{.ads}) for a library level package or generic |
| package that has no body |
| |
| @item |
| the body file (@code{.adb}) for a library level package |
| or generic package that has a body |
| @end itemize |
| |
| You need @emph{not} compile the following files |
| |
| |
| @itemize * |
| |
| @item |
| the spec of a library unit which has a body |
| |
| @item |
| subunits |
| @end itemize |
| |
| 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. |
| |
| @geindex cannot generate code |
| |
| If you attempt to compile any of these files, you will get one of the |
| following error messages (where @cite{fff} is the name of the file you |
| compiled): |
| |
| @quotation |
| |
| @example |
| cannot generate code for file `fff` (package spec) |
| to check package spec, use -gnatc |
| |
| cannot generate code for file `fff` (missing subunits) |
| to check parent unit, use -gnatc |
| |
| cannot generate code for file `fff` (subprogram spec) |
| to check subprogram spec, use -gnatc |
| |
| cannot generate code for file `fff` (subunit) |
| to check subunit, use -gnatc |
| @end example |
| @end quotation |
| |
| As indicated by the above error messages, if you want to submit |
| one of these files to the compiler to check for correct semantics |
| without generating code, then use the @emph{-gnatc} switch. |
| |
| The basic command for compiling a file containing an Ada unit is: |
| |
| @example |
| $ gcc -c [switches] <file name> |
| @end example |
| |
| where @cite{file name} is the name of the Ada file (usually |
| having an extension @code{.ads} for a spec or @code{.adb} for a body). |
| You specify the |
| @code{-c} switch to tell @emph{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 @code{.o} and an Ada |
| Library Information (ALI) file, which also has the same name as the |
| source file, but with @code{.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. |
| |
| @geindex gnat1 |
| |
| @emph{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 @code{cc1}, and the Ada compiler is @code{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 @emph{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 @emph{gcc} |
| command. This causes @emph{gcc} to call the appropriate compiler for |
| each file. For example, the following command lists two separate |
| files to be compiled: |
| |
| @example |
| $ gcc -c x.adb y.adb |
| @end example |
| |
| calls @cite{gnat1} (the Ada compiler) twice to compile @code{x.adb} and |
| @code{y.adb}. |
| The compiler generates two object files @code{x.o} and @code{y.o} |
| and the two ALI files @code{x.ali} and @code{y.ali}. |
| |
| Any switches apply to all the files listed, see @ref{f2,,Compiler Switches} for a |
| list of available @emph{gcc} switches. |
| |
| @node Search Paths and the Run-Time Library RTL,Order of Compilation Issues,Compiling Programs,Compiling with gcc |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id10}@anchor{f3}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{8e} |
| @subsection 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: |
| |
| |
| @itemize * |
| |
| @item |
| The directory containing the source file of the main unit being compiled |
| (the file name on the command line). |
| |
| @item |
| Each directory named by an @emph{-I} switch given on the @emph{gcc} |
| command line, in the order given. |
| |
| @geindex ADA_PRJ_INCLUDE_FILE |
| |
| @item |
| Each of the directories listed in the text file whose name is given |
| by the |
| @geindex ADA_PRJ_INCLUDE_FILE |
| @geindex environment variable; ADA_PRJ_INCLUDE_FILE |
| @code{ADA_PRJ_INCLUDE_FILE} environment variable. |
| @geindex ADA_PRJ_INCLUDE_FILE |
| @geindex environment variable; ADA_PRJ_INCLUDE_FILE |
| @code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the gnat |
| driver when project files are used. It should not normally be set |
| by other means. |
| |
| @geindex ADA_INCLUDE_PATH |
| |
| @item |
| Each of the directories listed in the value of the |
| @geindex ADA_INCLUDE_PATH |
| @geindex environment variable; ADA_INCLUDE_PATH |
| @code{ADA_INCLUDE_PATH} environment variable. |
| Construct this value |
| exactly as the |
| @geindex PATH |
| @geindex environment variable; PATH |
| @code{PATH} environment variable: a list of directory |
| names separated by colons (semicolons when working with the NT version). |
| |
| @item |
| The content of the @code{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. |
| @ref{8b,,Installing a library} |
| @end itemize |
| |
| Specifying the switch @emph{-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 @emph{-I} switch. |
| |
| Specifying the switch @emph{-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 @emph{-o} switch; |
| however, @emph{gcc} and @cite{gnat1} have not been coordinated on this |
| so the @code{ALI} file will not go to the right place. Therefore, you should |
| avoid using the @emph{-o} switch. |
| |
| @geindex System.IO |
| |
| The packages @cite{Ada}, @cite{System}, and @cite{Interfaces} and their |
| children make up the GNAT RTL, together with the simple @cite{System.IO} |
| package used in the @cite{"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 (@cite{System}, @cite{Ada} and |
| @cite{Interfaces}), the GNAT distribution provides a fourth hierarchy, |
| consisting of child units of @cite{GNAT}. This is a collection of generally |
| useful types, subprograms, etc. See the @cite{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. |
| |
| @node Order of Compilation Issues,Examples,Search Paths and the Run-Time Library RTL,Compiling with gcc |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id11}@anchor{f4}@anchor{gnat_ugn/building_executable_programs_with_gnat order-of-compilation-issues}@anchor{f5} |
| @subsection Order of Compilation Issues |
| |
| |
| If, in our earlier example, there was a spec for the @cite{hello} |
| procedure, it would be contained in the file @code{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: |
| |
| |
| @itemize * |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| There is no library as such, apart from the ALI files |
| (@ref{44,,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. |
| |
| @item |
| When you compile a unit, the source files for the specs of all units |
| that it @emph{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. |
| @end itemize |
| |
| @node Examples,,Order of Compilation Issues,Compiling with gcc |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id12}@anchor{f6}@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{f7} |
| @subsection Examples |
| |
| |
| The following are some typical Ada compilation command line examples: |
| |
| @example |
| $ gcc -c xyz.adb |
| @end example |
| |
| Compile body in file @code{xyz.adb} with all default options. |
| |
| @example |
| $ gcc -c -O2 -gnata xyz-def.adb |
| @end example |
| |
| Compile the child unit package in file @code{xyz-def.adb} with extensive |
| optimizations, and pragma @cite{Assert}/@cite{Debug} statements |
| enabled. |
| |
| @example |
| $ gcc -c -gnatc abc-def.adb |
| @end example |
| |
| Compile the subunit in file @code{abc-def.adb} in semantic-checking-only |
| mode. |
| |
| @node Compiler Switches,Binding with gnatbind,Compiling with gcc,Building Executable Programs with GNAT |
| @anchor{gnat_ugn/building_executable_programs_with_gnat compiler-switches}@anchor{f8}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gcc}@anchor{f2} |
| @section Compiler Switches |
| |
| |
| The @emph{gcc} command accepts switches that control the |
| compilation process. These switches are fully described in this section: |
| first an alphabetical listing of all switches with a brief description, |
| and then functionally grouped sets of switches with more detailed |
| information. |
| |
| More switches exist for GCC than those documented here, especially |
| for specific targets. However, their use is not recommended as |
| they may change code generation in ways that are incompatible with |
| the Ada run-time library, or can cause inconsistencies between |
| compilation units. |
| |
| @menu |
| * Alphabetical List of All Switches:: |
| * Output and Error Message Control:: |
| * Warning Message Control:: |
| * Debugging and Assertion Control:: |
| * Validity Checking:: |
| * Style Checking:: |
| * Run-Time Checks:: |
| * Using gcc for Syntax Checking:: |
| * Using gcc for Semantic Checking:: |
| * Compiling Different Versions of Ada:: |
| * Character Set Control:: |
| * File Naming Control:: |
| * Subprogram Inlining Control:: |
| * Auxiliary Output Control:: |
| * Debugging Control:: |
| * Exception Handling Control:: |
| * Units to Sources Mapping Files:: |
| * Code Generation Control:: |
| |
| @end menu |
| |
| @node Alphabetical List of All Switches,Output and Error Message Control,,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id13}@anchor{f9}@anchor{gnat_ugn/building_executable_programs_with_gnat alphabetical-list-of-all-switches}@anchor{fa} |
| @subsection Alphabetical List of All Switches |
| |
| |
| @geindex -b (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-b @emph{target}} |
| |
| Compile your program to run on @cite{target}, which is the name of a |
| system configuration. You must have a GNAT cross-compiler built if |
| @cite{target} is not the same as your host system. |
| @end table |
| |
| @geindex -B (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-B@emph{dir}} |
| |
| Load compiler executables (for example, @cite{gnat1}, the Ada compiler) |
| from @cite{dir} instead of the default location. Only use this switch |
| when multiple versions of the GNAT compiler are available. |
| See the "Options for Directory Search" section in the |
| @cite{Using the GNU Compiler Collection (GCC)} manual for further details. |
| You would normally use the @emph{-b} or @emph{-V} switch instead. |
| @end table |
| |
| @geindex -c (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-c} |
| |
| Compile. Always use this switch when compiling Ada programs. |
| |
| Note: for some other languages when using @emph{gcc}, notably in |
| the case of C and C++, it is possible to use |
| use @emph{gcc} without a @emph{-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 @emph{gcc} cannot be used to run the GNAT binder. |
| @end table |
| |
| @geindex -fcallgraph-info (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fcallgraph-info[=su,da]} |
| |
| Makes the compiler output callgraph information for the program, on a |
| per-file basis. The information is generated in the VCG format. It can |
| be decorated with additional, per-node and/or per-edge information, if a |
| list of comma-separated markers is additionally specified. When the |
| @cite{su} marker is specified, the callgraph is decorated with stack usage |
| information; it is equivalent to @emph{-fstack-usage}. When the @cite{da} |
| marker is specified, the callgraph is decorated with information about |
| dynamically allocated objects. |
| @end table |
| |
| @geindex -fdump-scos (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fdump-scos} |
| |
| Generates SCO (Source Coverage Obligation) information in the ALI file. |
| This information is used by advanced coverage tools. See unit @code{SCOs} |
| in the compiler sources for details in files @code{scos.ads} and |
| @code{scos.adb}. |
| @end table |
| |
| @geindex -fdump-xref (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fdump-xref} |
| |
| Generates cross reference information in GLI files for C and C++ sources. |
| The GLI files have the same syntax as the ALI files for Ada, and can be used |
| for source navigation in IDEs and on the command line using e.g. gnatxref |
| and the @emph{--ext=gli} switch. |
| @end table |
| |
| @geindex -flto (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-flto[=@emph{n}]} |
| |
| Enables Link Time Optimization. This switch must be used in conjunction |
| with the traditional @emph{-Ox} switches and instructs the compiler to |
| defer most optimizations until the link stage. The advantage of this |
| approach is that the compiler can do a whole-program analysis and choose |
| the best interprocedural optimization strategy based on a complete view |
| of the program, instead of a fragmentary view with the usual approach. |
| This can also speed up the compilation of big programs and reduce the |
| size of the executable, compared with a traditional per-unit compilation |
| with inlining across modules enabled by the @emph{-gnatn} switch. |
| The drawback of this approach is that it may require more memory and that |
| the debugging information generated by -g with it might be hardly usable. |
| The switch, as well as the accompanying @emph{-Ox} switches, must be |
| specified both for the compilation and the link phases. |
| If the @cite{n} parameter is specified, the optimization and final code |
| generation at link time are executed using @cite{n} parallel jobs by |
| means of an installed @emph{make} program. |
| @end table |
| |
| @geindex -fno-inline (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fno-inline} |
| |
| Suppresses all inlining, unless requested with pragma @cite{Inline_Always}. The |
| effect is enforced regardless of other optimization or inlining switches. |
| Note that inlining can also be suppressed on a finer-grained basis with |
| pragma @cite{No_Inline}. |
| @end table |
| |
| @geindex -fno-inline-functions (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fno-inline-functions} |
| |
| Suppresses automatic inlining of subprograms, which is enabled |
| if @emph{-O3} is used. |
| @end table |
| |
| @geindex -fno-inline-small-functions (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fno-inline-small-functions} |
| |
| Suppresses automatic inlining of small subprograms, which is enabled |
| if @emph{-O2} is used. |
| @end table |
| |
| @geindex -fno-inline-functions-called-once (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fno-inline-functions-called-once} |
| |
| Suppresses inlining of subprograms local to the unit and called once |
| from within it, which is enabled if @emph{-O1} is used. |
| @end table |
| |
| @geindex -fno-ivopts (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fno-ivopts} |
| |
| Suppresses high-level loop induction variable optimizations, which are |
| enabled if @emph{-O1} is used. These optimizations are generally |
| profitable but, for some specific cases of loops with numerous uses |
| of the iteration variable that follow a common pattern, they may end |
| up destroying the regularity that could be exploited at a lower level |
| and thus producing inferior code. |
| @end table |
| |
| @geindex -fno-strict-aliasing (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fno-strict-aliasing} |
| |
| Causes the compiler to avoid assumptions regarding non-aliasing |
| of objects of different types. See |
| @ref{fb,,Optimization and Strict Aliasing} for details. |
| @end table |
| |
| @geindex -fno-strict-overflow (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fno-strict-overflow} |
| |
| Causes the compiler to avoid assumptions regarding the rules of signed |
| integer overflow. These rules specify that signed integer overflow will |
| result in a Constraint_Error exception at run time and are enforced in |
| default mode by the compiler, so this switch should not be necessary in |
| normal operating mode. It might be useful in conjunction with @emph{-gnato0} |
| for very peculiar cases of low-level programming. |
| @end table |
| |
| @geindex -fstack-check (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fstack-check} |
| |
| Activates stack checking. |
| See @ref{fc,,Stack Overflow Checking} for details. |
| @end table |
| |
| @geindex -fstack-usage (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fstack-usage} |
| |
| Makes the compiler output stack usage information for the program, on a |
| per-subprogram basis. See @ref{fd,,Static Stack Usage Analysis} for details. |
| @end table |
| |
| @geindex -g (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-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 |
| @emph{-g} switch if you plan on using the debugger. |
| @end table |
| |
| @geindex -gnat05 (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnat05} |
| |
| Allow full Ada 2005 features. |
| @end table |
| |
| @geindex -gnat12 (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnat12} |
| |
| Allow full Ada 2012 features. |
| @end table |
| |
| @geindex -gnat83 (gcc) |
| |
| @geindex -gnat2005 (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnat2005} |
| |
| Allow full Ada 2005 features (same as @emph{-gnat05}) |
| @end table |
| |
| @geindex -gnat2012 (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnat2012} |
| |
| Allow full Ada 2012 features (same as @emph{-gnat12}) |
| |
| @item @code{-gnat83} |
| |
| Enforce Ada 83 restrictions. |
| @end table |
| |
| @geindex -gnat95 (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnat95} |
| |
| Enforce Ada 95 restrictions. |
| |
| Note: for compatibility with some Ada 95 compilers which support only |
| the @cite{overriding} keyword of Ada 2005, the @emph{-gnatd.D} switch can |
| be used along with @emph{-gnat95} to achieve a similar effect with GNAT. |
| |
| @emph{-gnatd.D} instructs GNAT to consider @cite{overriding} as a keyword |
| and handle its associated semantic checks, even in Ada 95 mode. |
| @end table |
| |
| @geindex -gnata (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnata} |
| |
| Assertions enabled. @cite{Pragma Assert} and @cite{pragma Debug} to be |
| activated. Note that these pragmas can also be controlled using the |
| configuration pragmas @cite{Assertion_Policy} and @cite{Debug_Policy}. |
| It also activates pragmas @cite{Check}, @cite{Precondition}, and |
| @cite{Postcondition}. Note that these pragmas can also be controlled |
| using the configuration pragma @cite{Check_Policy}. In Ada 2012, it |
| also activates all assertions defined in the RM as aspects: preconditions, |
| postconditions, type invariants and (sub)type predicates. In all Ada modes, |
| corresponding pragmas for type invariants and (sub)type predicates are |
| also activated. The default is that all these assertions are disabled, |
| and have no effect, other than being checked for syntactic validity, and |
| in the case of subtype predicates, constructions such as membership tests |
| still test predicates even if assertions are turned off. |
| @end table |
| |
| @geindex -gnatA (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatA} |
| |
| Avoid processing @code{gnat.adc}. If a @code{gnat.adc} file is present, |
| it will be ignored. |
| @end table |
| |
| @geindex -gnatb (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatb} |
| |
| Generate brief messages to @code{stderr} even if verbose mode set. |
| @end table |
| |
| @geindex -gnatB (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatB} |
| |
| Assume no invalid (bad) values except for 'Valid attribute use |
| (@ref{fe,,Validity Checking}). |
| @end table |
| |
| @geindex -gnatc (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatc} |
| |
| Check syntax and semantics only (no code generation attempted). When the |
| compiler is invoked by @emph{gnatmake}, if the switch @emph{-gnatc} is |
| only given to the compiler (after @emph{-cargs} or in package Compiler of |
| the project file, @emph{gnatmake} will fail because it will not find the |
| object file after compilation. If @emph{gnatmake} is called with |
| @emph{-gnatc} as a builder switch (before @emph{-cargs} or in package |
| Builder of the project file) then @emph{gnatmake} will not fail because |
| it will not look for the object files after compilation, and it will not try |
| to build and link. This switch may not be given if a previous @cite{-gnatR} |
| switch has been given, since @cite{-gnatR} requires that the code generator |
| be called to complete determination of representation information. |
| @end table |
| |
| @geindex -gnatC (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatC} |
| |
| Generate CodePeer intermediate format (no code generation attempted). |
| This switch will generate an intermediate representation suitable for |
| use by CodePeer (@code{.scil} files). This switch is not compatible with |
| code generation (it will, among other things, disable some switches such |
| as -gnatn, and enable others such as -gnata). |
| @end table |
| |
| @geindex -gnatd (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatd} |
| |
| Specify debug options for the compiler. The string of characters after |
| the @emph{-gnatd} specify the specific debug options. The possible |
| characters are 0-9, a-z, A-Z, optionally preceded by a dot. See |
| compiler source file @code{debug.adb} for details of the implemented |
| debug options. Certain debug options are relevant to applications |
| programmers, and these are documented at appropriate points in this |
| users guide. |
| @end table |
| |
| @geindex -gnatD[nn] (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatD} |
| |
| Create expanded source files for source level debugging. This switch |
| also suppress generation of cross-reference information |
| (see @emph{-gnatx}). Note that this switch is not allowed if a previous |
| -gnatR switch has been given, since these two switches are not compatible. |
| @end table |
| |
| @geindex -gnateA (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateA} |
| |
| Check that the actual parameters of a subprogram call are not aliases of one |
| another. To qualify as aliasing, the actuals must denote objects of a composite |
| type, their memory locations must be identical or overlapping, and at least one |
| of the corresponding formal parameters must be of mode OUT or IN OUT. |
| |
| @example |
| type Rec_Typ is record |
| Data : Integer := 0; |
| end record; |
| |
| function Self (Val : Rec_Typ) return Rec_Typ is |
| begin |
| return Val; |
| end Self; |
| |
| procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is |
| begin |
| null; |
| end Detect_Aliasing; |
| |
| Obj : Rec_Typ; |
| |
| Detect_Aliasing (Obj, Obj); |
| Detect_Aliasing (Obj, Self (Obj)); |
| @end example |
| |
| In the example above, the first call to @cite{Detect_Aliasing} fails with a |
| @cite{Program_Error} at runtime because the actuals for @cite{Val_1} and |
| @cite{Val_2} denote the same object. The second call executes without raising |
| an exception because @cite{Self(Obj)} produces an anonymous object which does |
| not share the memory location of @cite{Obj}. |
| @end table |
| |
| @geindex -gnatec (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatec=@emph{path}} |
| |
| Specify a configuration pragma file |
| (the equal sign is optional) |
| (@ref{7b,,The Configuration Pragmas Files}). |
| @end table |
| |
| @geindex -gnateC (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateC} |
| |
| Generate CodePeer messages in a compiler-like format. This switch is only |
| effective if @emph{-gnatcC} is also specified and requires an installation |
| of CodePeer. |
| @end table |
| |
| @geindex -gnated (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnated} |
| |
| Disable atomic synchronization |
| @end table |
| |
| @geindex -gnateD (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateDsymbol[=@emph{value}]} |
| |
| Defines a symbol, associated with @cite{value}, for preprocessing. |
| (@ref{1a,,Integrated Preprocessing}). |
| @end table |
| |
| @geindex -gnateE (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateE} |
| |
| Generate extra information in exception messages. In particular, display |
| extra column information and the value and range associated with index and |
| range check failures, and extra column information for access checks. |
| In cases where the compiler is able to determine at compile time that |
| a check will fail, it gives a warning, and the extra information is not |
| produced at run time. |
| @end table |
| |
| @geindex -gnatef (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatef} |
| |
| Display full source path name in brief error messages. |
| @end table |
| |
| @geindex -gnateF (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateF} |
| |
| Check for overflow on all floating-point operations, including those |
| for unconstrained predefined types. See description of pragma |
| @cite{Check_Float_Overflow} in GNAT RM. |
| @end table |
| |
| @geindex -gnateg (gcc) |
| |
| @code{-gnateg} |
| @code{-gnatceg} |
| |
| @quotation |
| |
| The @cite{-gnatc} switch must always be specified before this switch, e.g. |
| @cite{-gnatceg}. Generate a C header from the Ada input file. See |
| @ref{d0,,Generating C Headers for Ada Specifications} for more |
| information. |
| @end quotation |
| |
| @geindex -gnateG (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateG} |
| |
| Save result of preprocessing in a text file. |
| @end table |
| |
| @geindex -gnatei (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatei@emph{nnn}} |
| |
| Set maximum number of instantiations during compilation of a single unit to |
| @cite{nnn}. This may be useful in increasing the default maximum of 8000 for |
| the rare case when a single unit legitimately exceeds this limit. |
| @end table |
| |
| @geindex -gnateI (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateI@emph{nnn}} |
| |
| Indicates that the source is a multi-unit source and that the index of the |
| unit to compile is @cite{nnn}. @cite{nnn} needs to be a positive number and need |
| to be a valid index in the multi-unit source. |
| @end table |
| |
| @geindex -gnatel (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatel} |
| |
| This switch can be used with the static elaboration model to issue info |
| messages showing |
| where implicit @cite{pragma Elaborate} and @cite{pragma Elaborate_All} |
| are generated. This is useful in diagnosing elaboration circularities |
| caused by these implicit pragmas when using the static elaboration |
| model. See See the section in this guide on elaboration checking for |
| further details. These messages are not generated by default, and are |
| intended only for temporary use when debugging circularity problems. |
| @end table |
| |
| @geindex -gnatel (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateL} |
| |
| This switch turns off the info messages about implicit elaboration pragmas. |
| @end table |
| |
| @geindex -gnatem (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatem=@emph{path}} |
| |
| Specify a mapping file |
| (the equal sign is optional) |
| (@ref{ff,,Units to Sources Mapping Files}). |
| @end table |
| |
| @geindex -gnatep (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatep=@emph{file}} |
| |
| Specify a preprocessing data file |
| (the equal sign is optional) |
| (@ref{1a,,Integrated Preprocessing}). |
| @end table |
| |
| @geindex -gnateP (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateP} |
| |
| Turn categorization dependency errors into warnings. |
| Ada requires that units that WITH one another have compatible categories, for |
| example a Pure unit cannot WITH a Preelaborate unit. If this switch is used, |
| these errors become warnings (which can be ignored, or suppressed in the usual |
| manner). This can be useful in some specialized circumstances such as the |
| temporary use of special test software. |
| @end table |
| |
| @geindex -gnateS (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateS} |
| |
| Synonym of @emph{-fdump-scos}, kept for backwards compatibility. |
| @end table |
| |
| @geindex -gnatet=file (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatet=@emph{path}} |
| |
| Generate target dependent information. The format of the output file is |
| described in the section about switch @emph{-gnateT}. |
| @end table |
| |
| @geindex -gnateT (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateT=@emph{path}} |
| |
| Read target dependent information, such as endianness or sizes and alignments |
| of base type. If this switch is passed, the default target dependent |
| information of the compiler is replaced by the one read from the input file. |
| This is used by tools other than the compiler, e.g. to do |
| semantic analysis of programs that will run on some other target than |
| the machine on which the tool is run. |
| |
| The following target dependent values should be defined, |
| where @cite{Nat} denotes a natural integer value, @cite{Pos} denotes a |
| positive integer value, and fields marked with a question mark are |
| boolean fields, where a value of 0 is False, and a value of 1 is True: |
| |
| @example |
| Bits_BE : Nat; -- Bits stored big-endian? |
| Bits_Per_Unit : Pos; -- Bits in a storage unit |
| Bits_Per_Word : Pos; -- Bits in a word |
| Bytes_BE : Nat; -- Bytes stored big-endian? |
| Char_Size : Pos; -- Standard.Character'Size |
| Double_Float_Alignment : Nat; -- Alignment of double float |
| Double_Scalar_Alignment : Nat; -- Alignment of double length scalar |
| Double_Size : Pos; -- Standard.Long_Float'Size |
| Float_Size : Pos; -- Standard.Float'Size |
| Float_Words_BE : Nat; -- Float words stored big-endian? |
| Int_Size : Pos; -- Standard.Integer'Size |
| Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size |
| Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size |
| Long_Size : Pos; -- Standard.Long_Integer'Size |
| Maximum_Alignment : Pos; -- Maximum permitted alignment |
| Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field |
| Pointer_Size : Pos; -- System.Address'Size |
| Short_Enums : Nat; -- Short foreign convention enums? |
| Short_Size : Pos; -- Standard.Short_Integer'Size |
| Strict_Alignment : Nat; -- Strict alignment? |
| System_Allocator_Alignment : Nat; -- Alignment for malloc calls |
| Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size |
| Words_BE : Nat; -- Words stored big-endian? |
| @end example |
| |
| The format of the input file is as follows. First come the values of |
| the variables defined above, with one line per value: |
| |
| @example |
| name value |
| @end example |
| |
| where @cite{name} is the name of the parameter, spelled out in full, |
| and cased as in the above list, and @cite{value} is an unsigned decimal |
| integer. Two or more blanks separates the name from the value. |
| |
| All the variables must be present, in alphabetical order (i.e. the |
| same order as the list above). |
| |
| Then there is a blank line to separate the two parts of the file. Then |
| come the lines showing the floating-point types to be registered, with |
| one line per registered mode: |
| |
| @example |
| name digs float_rep size alignment |
| @end example |
| |
| where @cite{name} is the string name of the type (which can have |
| single spaces embedded in the name (e.g. long double), @cite{digs} is |
| the number of digits for the floating-point type, @cite{float_rep} is |
| the float representation (I/V/A for IEEE-754-Binary, Vax_Native, |
| AAMP), @cite{size} is the size in bits, @cite{alignment} is the |
| alignment in bits. The name is followed by at least two blanks, fields |
| are separated by at least one blank, and a LF character immediately |
| follows the alignment field. |
| |
| Here is an example of a target parameterization file: |
| |
| @example |
| Bits_BE 0 |
| Bits_Per_Unit 8 |
| Bits_Per_Word 64 |
| Bytes_BE 0 |
| Char_Size 8 |
| Double_Float_Alignment 0 |
| Double_Scalar_Alignment 0 |
| Double_Size 64 |
| Float_Size 32 |
| Float_Words_BE 0 |
| Int_Size 64 |
| Long_Double_Size 128 |
| Long_Long_Size 64 |
| Long_Size 64 |
| Maximum_Alignment 16 |
| Max_Unaligned_Field 64 |
| Pointer_Size 64 |
| Short_Size 16 |
| Strict_Alignment 0 |
| System_Allocator_Alignment 16 |
| Wchar_T_Size 32 |
| Words_BE 0 |
| |
| float 15 I 64 64 |
| double 15 I 64 64 |
| long double 18 I 80 128 |
| TF 33 I 128 128 |
| @end example |
| @end table |
| |
| @geindex -gnateu (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateu} |
| |
| Ignore unrecognized validity, warning, and style switches that |
| appear after this switch is given. This may be useful when |
| compiling sources developed on a later version of the compiler |
| with an earlier version. Of course the earlier version must |
| support this switch. |
| @end table |
| |
| @geindex -gnateV (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateV} |
| |
| Check that all actual parameters of a subprogram call are valid according to |
| the rules of validity checking (@ref{fe,,Validity Checking}). |
| @end table |
| |
| @geindex -gnateY (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnateY} |
| |
| Ignore all STYLE_CHECKS pragmas. Full legality checks |
| are still carried out, but the pragmas have no effect |
| on what style checks are active. This allows all style |
| checking options to be controlled from the command line. |
| @end table |
| |
| @geindex -gnatE (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatE} |
| |
| Full dynamic elaboration checks. |
| @end table |
| |
| @geindex -gnatf (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatf} |
| |
| Full errors. Multiple errors per line, all undefined references, do not |
| attempt to suppress cascaded errors. |
| @end table |
| |
| @geindex -gnatF (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatF} |
| |
| Externals names are folded to all uppercase. |
| @end table |
| |
| @geindex -gnatg (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| Note that @emph{-gnatg} implies |
| @emph{-gnatw.ge} and |
| @emph{-gnatyg} |
| so that all standard warnings and all standard style options are turned on. |
| All warnings and style messages are treated as errors. |
| @end table |
| |
| @geindex -gnatG[nn] (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatG=nn} |
| |
| List generated expanded code in source form. |
| @end table |
| |
| @geindex -gnath (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnath} |
| |
| Output usage information. The output is written to @code{stdout}. |
| @end table |
| |
| @geindex -gnati (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnati@emph{c}} |
| |
| Identifier character set (@cite{c} = 1/2/3/4/8/9/p/f/n/w). |
| For details of the possible selections for @cite{c}, |
| see @ref{4a,,Character Set Control}. |
| @end table |
| |
| @geindex -gnatI (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatI} |
| |
| Ignore representation clauses. When this switch is used, |
| representation clauses are treated as comments. This is useful |
| when initially porting code where you want to ignore rep clause |
| problems, and also for compiling foreign code (particularly |
| for use with ASIS). The representation clauses that are ignored |
| are: enumeration_representation_clause, record_representation_clause, |
| and attribute_definition_clause for the following attributes: |
| Address, Alignment, Bit_Order, Component_Size, Machine_Radix, |
| Object_Size, Size, Small, Stream_Size, and Value_Size. |
| Note that this option should be used only for compiling -- the |
| code is likely to malfunction at run time. |
| |
| Note that when @cite{-gnatct} is used to generate trees for input |
| into @cite{ASIS} tools, these representation clauses are removed |
| from the tree and ignored. This means that the tool will not see them. |
| @end table |
| |
| @geindex -gnatjnn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatj@emph{nn}} |
| |
| Reformat error messages to fit on @cite{nn} character lines |
| @end table |
| |
| @geindex -gnatk (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatk=@emph{n}} |
| |
| Limit file names to @cite{n} (1-999) characters (@cite{k} = krunch). |
| @end table |
| |
| @geindex -gnatl (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatl} |
| |
| Output full source listing with embedded error messages. |
| @end table |
| |
| @geindex -gnatL (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatL} |
| |
| Used in conjunction with -gnatG or -gnatD to intersperse original |
| source lines (as comment lines with line numbers) in the expanded |
| source output. |
| @end table |
| |
| @geindex -gnatm (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatm=@emph{n}} |
| |
| Limit number of detected error or warning messages to @cite{n} |
| where @cite{n} is in the range 1..999999. The default setting if |
| no switch is given is 9999. If the number of warnings reaches this |
| limit, then a message is output and further warnings are suppressed, |
| but the compilation is continued. If the number of error messages |
| reaches this limit, then a message is output and the compilation |
| is abandoned. The equal sign here is optional. A value of zero |
| means that no limit applies. |
| @end table |
| |
| @geindex -gnatn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatn[12]} |
| |
| Activate inlining for subprograms for which pragma @cite{Inline} is |
| specified. This inlining is performed by the GCC back-end. An optional |
| digit sets the inlining level: 1 for moderate inlining across modules |
| or 2 for full inlining across modules. If no inlining level is specified, |
| the compiler will pick it based on the optimization level. |
| @end table |
| |
| @geindex -gnatN (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatN} |
| |
| Activate front end inlining for subprograms for which |
| pragma @cite{Inline} is specified. This inlining is performed |
| by the front end and will be visible in the |
| @emph{-gnatG} output. |
| |
| When using a gcc-based back end (in practice this means using any version |
| of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of |
| @emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred. |
| Historically front end inlining was more extensive than the gcc back end |
| inlining, but that is no longer the case. |
| @end table |
| |
| @geindex -gnato0 (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnato0} |
| |
| Suppresses overflow checking. This causes the behavior of the compiler to |
| match the default for older versions where overflow checking was suppressed |
| by default. This is equivalent to having |
| @cite{pragma Suppress (Overflow_Mode)} in a configuration pragma file. |
| @end table |
| |
| @geindex -gnato?? (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnato??} |
| |
| Set default mode for handling generation of code to avoid intermediate |
| arithmetic overflow. Here @cite{??} is two digits, a |
| single digit, or nothing. Each digit is one of the digits @cite{1} |
| through @cite{3}: |
| |
| |
| @multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| Digit |
| |
| @tab |
| |
| Interpretation |
| |
| @item |
| |
| @emph{1} |
| |
| @tab |
| |
| All intermediate overflows checked against base type (@cite{STRICT}) |
| |
| @item |
| |
| @emph{2} |
| |
| @tab |
| |
| Minimize intermediate overflows (@cite{MINIMIZED}) |
| |
| @item |
| |
| @emph{3} |
| |
| @tab |
| |
| Eliminate intermediate overflows (@cite{ELIMINATED}) |
| |
| @end multitable |
| |
| |
| If only one digit appears, then it applies to all |
| cases; if two digits are given, then the first applies outside |
| assertions, pre/postconditions, and type invariants, and the second |
| applies within assertions, pre/postconditions, and type invariants. |
| |
| If no digits follow the @emph{-gnato}, then it is equivalent to |
| @emph{-gnato11}, |
| causing all intermediate overflows to be handled in strict |
| mode. |
| |
| This switch also causes arithmetic overflow checking to be performed |
| (as though @cite{pragma Unsuppress (Overflow_Mode)} had been specified). |
| |
| The default if no option @emph{-gnato} is given is that overflow handling |
| is in @cite{STRICT} mode (computations done using the base type), and that |
| overflow checking is enabled. |
| |
| Note that division by zero is a separate check that is not |
| controlled by this switch (divide-by-zero checking is on by default). |
| |
| See also @ref{100,,Specifying the Desired Mode}. |
| @end table |
| |
| @geindex -gnatp (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatp} |
| |
| Suppress all checks. See @ref{101,,Run-Time Checks} for details. This switch |
| has no effect if cancelled by a subsequent @emph{-gnat-p} switch. |
| @end table |
| |
| @geindex -gnat-p (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnat-p} |
| |
| Cancel effect of previous @emph{-gnatp} switch. |
| @end table |
| |
| @geindex -gnatP (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatP} |
| |
| Enable polling. This is required on some systems (notably Windows NT) to |
| obtain asynchronous abort and asynchronous transfer of control capability. |
| See @cite{Pragma_Polling} in the @cite{GNAT_Reference_Manual} for full |
| details. |
| @end table |
| |
| @geindex -gnatq (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatq} |
| |
| Don't quit. Try semantics, even if parse errors. |
| @end table |
| |
| @geindex -gnatQ (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatQ} |
| |
| Don't quit. Generate @code{ALI} and tree files even if illegalities. |
| Note that code generation is still suppressed in the presence of any |
| errors, so even with @emph{-gnatQ} no object file is generated. |
| @end table |
| |
| @geindex -gnatr (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatr} |
| |
| Treat pragma Restrictions as Restriction_Warnings. |
| @end table |
| |
| @geindex -gnatR (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatR[0/1/2/3[s]]} |
| |
| Output representation information for declared types and objects. |
| Note that this switch is not allowed if a previous @cite{-gnatD} switch has |
| been given, since these two switches are not compatible. |
| |
| @item @code{-gnatRm[s]} |
| |
| Output convention and parameter passing mechanisms for all subprograms. |
| @end table |
| |
| @geindex -gnats (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnats} |
| |
| Syntax check only. |
| @end table |
| |
| @geindex -gnatS (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatS} |
| |
| Print package Standard. |
| @end table |
| |
| @geindex -gnatt (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatt} |
| |
| Generate tree output file. |
| @end table |
| |
| @geindex -gnatT (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatT@emph{nnn}} |
| |
| All compiler tables start at @cite{nnn} times usual starting size. |
| @end table |
| |
| @geindex -gnatu (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatu} |
| |
| List units for this compilation. |
| @end table |
| |
| @geindex -gnatU (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatU} |
| |
| Tag all error messages with the unique string 'error:' |
| @end table |
| |
| @geindex -gnatv (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatv} |
| |
| Verbose mode. Full error output with source lines to @code{stdout}. |
| @end table |
| |
| @geindex -gnatV (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatV} |
| |
| Control level of validity checking (@ref{fe,,Validity Checking}). |
| @end table |
| |
| @geindex -gnatw (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw@emph{xxx}} |
| |
| Warning mode where |
| @cite{xxx} is a string of option letters that denotes |
| the exact warnings that |
| are enabled or disabled (@ref{102,,Warning Message Control}). |
| @end table |
| |
| @geindex -gnatW (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatW@emph{e}} |
| |
| Wide character encoding method |
| (@cite{e}=n/h/u/s/e/8). |
| @end table |
| |
| @geindex -gnatx (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatx} |
| |
| Suppress generation of cross-reference information. |
| @end table |
| |
| @geindex -gnatX (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatX} |
| |
| Enable GNAT implementation extensions and latest Ada version. |
| @end table |
| |
| @geindex -gnaty (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnaty} |
| |
| Enable built-in style checks (@ref{103,,Style Checking}). |
| @end table |
| |
| @geindex -gnatz (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatz@emph{m}} |
| |
| Distribution stub generation and compilation |
| (@cite{m}=r/c for receiver/caller stubs). |
| @end table |
| |
| @geindex -I (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-I@emph{dir}} |
| |
| @geindex RTL |
| |
| Direct GNAT to search the @cite{dir} directory for source files needed by |
| the current compilation |
| (see @ref{8e,,Search Paths and the Run-Time Library (RTL)}). |
| @end table |
| |
| @geindex -I- (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-I-} |
| |
| @geindex RTL |
| |
| 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 |
| (see @ref{8e,,Search Paths and the Run-Time Library (RTL)}). |
| @end table |
| |
| @geindex -o (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-o @emph{file}} |
| |
| This switch is used in @emph{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. |
| @end table |
| |
| @geindex -nostdinc (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-nostdinc} |
| |
| Inhibit the search of the default location for the GNAT Run Time |
| Library (RTL) source files. |
| @end table |
| |
| @geindex -nostdlib (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-nostdlib} |
| |
| Inhibit the search of the default location for the GNAT Run Time |
| Library (RTL) ALI files. |
| @end table |
| |
| @geindex -O (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-O[@emph{n}]} |
| |
| @cite{n} controls the optimization level: |
| |
| |
| @multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| @emph{n} |
| |
| @tab |
| |
| Effect |
| |
| @item |
| |
| @emph{0} |
| |
| @tab |
| |
| No optimization, the default setting if no @emph{-O} appears |
| |
| @item |
| |
| @emph{1} |
| |
| @tab |
| |
| Normal optimization, the default if you specify @emph{-O} without an |
| operand. A good compromise between code quality and compilation |
| time. |
| |
| @item |
| |
| @emph{2} |
| |
| @tab |
| |
| Extensive optimization, may improve execution time, possibly at |
| the cost of substantially increased compilation time. |
| |
| @item |
| |
| @emph{3} |
| |
| @tab |
| |
| Same as @emph{-O2}, and also includes inline expansion for small |
| subprograms in the same unit. |
| |
| @item |
| |
| @emph{s} |
| |
| @tab |
| |
| Optimize space usage |
| |
| @end multitable |
| |
| |
| See also @ref{104,,Optimization Levels}. |
| @end table |
| |
| @geindex -pass-exit-codes (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-pass-exit-codes} |
| |
| Catch exit codes from the compiler and use the most meaningful as |
| exit status. |
| @end table |
| |
| @geindex --RTS (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{--RTS=@emph{rts-path}} |
| |
| Specifies the default location of the runtime library. Same meaning as the |
| equivalent @emph{gnatmake} flag (@ref{e2,,Switches for gnatmake}). |
| @end table |
| |
| @geindex -S (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-S} |
| |
| Used in place of @emph{-c} to |
| cause the assembler source file to be |
| generated, using @code{.s} as the extension, |
| instead of the object file. |
| This may be useful if you need to examine the generated assembly code. |
| @end table |
| |
| @geindex -fverbose-asm (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-fverbose-asm} |
| |
| Used in conjunction with @emph{-S} |
| to cause the generated assembly code file to be annotated with variable |
| names, making it significantly easier to follow. |
| @end table |
| |
| @geindex -v (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-v} |
| |
| Show commands generated by the @emph{gcc} driver. Normally used only for |
| debugging purposes or if you need to be sure what version of the |
| compiler you are executing. |
| @end table |
| |
| @geindex -V (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-V @emph{ver}} |
| |
| Execute @cite{ver} version of the compiler. This is the @emph{gcc} |
| version, not the GNAT version. |
| @end table |
| |
| @geindex -w (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-w} |
| |
| Turn off warnings generated by the back end of the compiler. Use of |
| this switch also causes the default for front end warnings to be set |
| to suppress (as though @emph{-gnatws} had appeared at the start of |
| the options). |
| @end table |
| |
| @geindex Combining GNAT switches |
| |
| You may combine a sequence of GNAT switches into a single switch. For |
| example, the combined switch |
| |
| @quotation |
| |
| @example |
| -gnatofi3 |
| @end example |
| @end quotation |
| |
| is equivalent to specifying the following sequence of switches: |
| |
| @quotation |
| |
| @example |
| -gnato -gnatf -gnati3 |
| @end example |
| @end quotation |
| |
| The following restrictions apply to the combination of switches |
| in this manner: |
| |
| |
| @itemize * |
| |
| @item |
| The switch @emph{-gnatc} if combined with other switches must come |
| first in the string. |
| |
| @item |
| The switch @emph{-gnats} if combined with other switches must come |
| first in the string. |
| |
| @item |
| The switches |
| @emph{-gnatzc} and @emph{-gnatzr} may not be combined with any other |
| switches, and only one of them may appear in the command line. |
| |
| @item |
| The switch @emph{-gnat-p} may not be combined with any other switch. |
| |
| @item |
| Once a 'y' appears in the string (that is a use of the @emph{-gnaty} |
| switch), then all further characters in the switch are interpreted |
| as style modifiers (see description of @emph{-gnaty}). |
| |
| @item |
| Once a 'd' appears in the string (that is a use of the @emph{-gnatd} |
| switch), then all further characters in the switch are interpreted |
| as debug flags (see description of @emph{-gnatd}). |
| |
| @item |
| Once a 'w' appears in the string (that is a use of the @emph{-gnatw} |
| switch), then all further characters in the switch are interpreted |
| as warning mode modifiers (see description of @emph{-gnatw}). |
| |
| @item |
| Once a 'V' appears in the string (that is a use of the @emph{-gnatV} |
| switch), then all further characters in the switch are interpreted |
| as validity checking options (@ref{fe,,Validity Checking}). |
| |
| @item |
| Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in |
| a combined list of options. |
| @end itemize |
| |
| @node Output and Error Message Control,Warning Message Control,Alphabetical List of All Switches,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id14}@anchor{105}@anchor{gnat_ugn/building_executable_programs_with_gnat output-and-error-message-control}@anchor{106} |
| @subsection Output and Error Message Control |
| |
| |
| @geindex stderr |
| |
| The standard default format for error messages is called 'brief format'. |
| Brief format messages are written to @code{stderr} (the standard error |
| file) and have the following form: |
| |
| @example |
| e.adb:3:04: Incorrect spelling of keyword "function" |
| e.adb:4:20: ";" should be "is" |
| @end example |
| |
| 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. |
| @cite{GPS} can parse the error messages |
| and point to the referenced character. |
| The following switches provide control over the error message |
| format: |
| |
| @geindex -gnatv (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatv} |
| |
| The @cite{v} stands for verbose. |
| The effect of this setting is to write long-format error |
| messages to @code{stdout} (the standard output file. |
| The same program compiled with the |
| @emph{-gnatv} switch would generate: |
| |
| @example |
| 3. funcion X (Q : Integer) |
| | |
| >>> Incorrect spelling of keyword "function" |
| 4. return Integer; |
| | |
| >>> ";" should be "is" |
| @end example |
| |
| The vertical bar indicates the location of the error, and the @code{>>>} |
| prefix can be used to search for error messages. When this switch is |
| used the only source lines output are those with errors. |
| @end table |
| |
| @geindex -gnatl (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatl} |
| |
| The @cite{l} stands for list. |
| This switch causes a full listing of |
| the file to be generated. In the case where a body is |
| compiled, the corresponding spec is also listed, along |
| with any subunits. Typical output from compiling a package |
| body @code{p.adb} might look like: |
| |
| @example |
| Compiling: p.adb |
| |
| 1. package body p is |
| 2. procedure a; |
| 3. procedure a is separate; |
| 4. begin |
| 5. null |
| | |
| >>> missing ";" |
| |
| 6. end; |
| |
| Compiling: p.ads |
| |
| 1. package p is |
| 2. pragma Elaborate_Body |
| | |
| >>> missing ";" |
| |
| 3. end p; |
| |
| Compiling: p-a.adb |
| |
| 1. separate p |
| | |
| >>> missing "(" |
| |
| 2. procedure a is |
| 3. begin |
| 4. null |
| | |
| >>> missing ";" |
| |
| 5. end; |
| @end example |
| |
| When you specify the @emph{-gnatv} or @emph{-gnatl} switches and |
| standard output is redirected, a brief summary is written to |
| @code{stderr} (standard error) giving the number of error messages and |
| warning messages generated. |
| @end table |
| |
| @geindex -gnatl=fname (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatl=@emph{fname}} |
| |
| This has the same effect as @emph{-gnatl} except that the output is |
| written to a file instead of to standard output. If the given name |
| @code{fname} does not start with a period, then it is the full name |
| of the file to be written. If @code{fname} is an extension, it is |
| appended to the name of the file being compiled. For example, if |
| file @code{xyz.adb} is compiled with @emph{-gnatl=.lst}, |
| then the output is written to file xyz.adb.lst. |
| @end table |
| |
| @geindex -gnatU (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| @end table |
| |
| @geindex -gnatb (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatb} |
| |
| The @cite{b} stands for brief. |
| This switch causes GNAT to generate the |
| brief format error messages to @code{stderr} (the standard error |
| file) as well as the verbose |
| format message or full listing (which as usual is written to |
| @code{stdout} (the standard output file). |
| @end table |
| |
| @geindex -gnatm (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatm=@emph{n}} |
| |
| The @cite{m} stands for maximum. |
| @cite{n} is a decimal integer in the |
| range of 1 to 999999 and limits the number of error or warning |
| messages to be generated. For example, using |
| @emph{-gnatm2} might yield |
| |
| @example |
| e.adb:3:04: Incorrect spelling of keyword "function" |
| e.adb:5:35: missing ".." |
| fatal error: maximum number of errors detected |
| compilation abandoned |
| @end example |
| |
| The default setting if |
| no switch is given is 9999. If the number of warnings reaches this |
| limit, then a message is output and further warnings are suppressed, |
| but the compilation is continued. If the number of error messages |
| reaches this limit, then a message is output and the compilation |
| is abandoned. A value of zero means that no limit applies. |
| |
| Note that the equal sign is optional, so the switches |
| @emph{-gnatm2} and @emph{-gnatm=2} are equivalent. |
| @end table |
| |
| @geindex -gnatf (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatf} |
| |
| @geindex Error messages |
| @geindex suppressing |
| |
| The @cite{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 |
| |
| @example |
| e.adb:7:07: "V" is undefined (more references follow) |
| @end example |
| |
| where the parenthetical comment warns that there are additional |
| references to the variable @cite{V}. Compiling the same program with the |
| @emph{-gnatf} switch yields |
| |
| @example |
| 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 |
| @end example |
| |
| The @emph{-gnatf} switch also generates additional information for |
| some error messages. Some examples are: |
| |
| |
| @itemize * |
| |
| @item |
| Details on possibly non-portable unchecked conversion |
| |
| @item |
| List possible interpretations for ambiguous calls |
| |
| @item |
| Additional details on incorrect parameters |
| @end itemize |
| @end table |
| |
| @geindex -gnatjnn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatjnn} |
| |
| In normal operation mode (or if @emph{-gnatj0} is used), then error messages |
| with continuation lines are treated as though the continuation lines were |
| separate messages (and so a warning with two continuation lines counts as |
| three warnings, and is listed as three separate messages). |
| |
| If the @emph{-gnatjnn} switch is used with a positive value for nn, then |
| messages are output in a different manner. A message and all its continuation |
| lines are treated as a unit, and count as only one warning or message in the |
| statistics totals. Furthermore, the message is reformatted so that no line |
| is longer than nn characters. |
| @end table |
| |
| @geindex -gnatq (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatq} |
| |
| The @cite{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. |
| @end table |
| |
| @geindex -gnatQ (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatQ} |
| |
| In normal operation mode, the @code{ALI} file is not generated if any |
| illegalities are detected in the program. The use of @emph{-gnatQ} forces |
| generation of the @code{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 @code{ALI} file. This switch |
| implies @emph{-gnatq}, since the semantic phase must be run to get a |
| meaningful ALI file. |
| |
| In addition, if @emph{-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 @emph{-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. |
| |
| When @emph{-gnatQ} is used and the generated @code{ALI} file is marked as |
| being in error, @emph{gnatmake} will attempt to recompile the source when it |
| finds such an @code{ALI} file, including with switch @emph{-gnatc}. |
| |
| Note that @emph{-gnatQ} has no effect if @emph{-gnats} is specified, |
| since ALI files are never generated if @emph{-gnats} is set. |
| @end table |
| |
| @node Warning Message Control,Debugging and Assertion Control,Output and Error Message Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat warning-message-control}@anchor{102}@anchor{gnat_ugn/building_executable_programs_with_gnat id15}@anchor{107} |
| @subsection Warning Message Control |
| |
| |
| @geindex Warning messages |
| |
| In addition to error messages, which correspond to illegalities as defined |
| in the Ada 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: |
| |
| @example |
| 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 |
| @end example |
| |
| 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 |
| @cite{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. This list is not complete, and new warnings are often added to |
| subsequent versions of GNAT. The list is intended to give a general idea |
| of the kinds of warnings that are generated. |
| |
| |
| @itemize * |
| |
| @item |
| Possible infinitely recursive calls |
| |
| @item |
| Out-of-range values being assigned |
| |
| @item |
| Possible order of elaboration problems |
| |
| @item |
| Size not a multiple of alignment for a record type |
| |
| @item |
| Assertions (pragma Assert) that are sure to fail |
| |
| @item |
| Unreachable code |
| |
| @item |
| Address clauses with possibly unaligned values, or where an attempt is |
| made to overlay a smaller variable with a larger one. |
| |
| @item |
| Fixed-point type declarations with a null range |
| |
| @item |
| Direct_IO or Sequential_IO instantiated with a type that has access values |
| |
| @item |
| Variables that are never assigned a value |
| |
| @item |
| Variables that are referenced before being initialized |
| |
| @item |
| Task entries with no corresponding @cite{accept} statement |
| |
| @item |
| Duplicate accepts for the same task entry in a @cite{select} |
| |
| @item |
| Objects that take too much storage |
| |
| @item |
| Unchecked conversion between types of differing sizes |
| |
| @item |
| Missing @cite{return} statement along some execution path in a function |
| |
| @item |
| Incorrect (unrecognized) pragmas |
| |
| @item |
| Incorrect external names |
| |
| @item |
| Allocation from empty storage pool |
| |
| @item |
| Potentially blocking operation in protected type |
| |
| @item |
| Suspicious parenthesization of expressions |
| |
| @item |
| Mismatching bounds in an aggregate |
| |
| @item |
| Attempt to return local value by reference |
| |
| @item |
| Premature instantiation of a generic body |
| |
| @item |
| Attempt to pack aliased components |
| |
| @item |
| Out of bounds array subscripts |
| |
| @item |
| Wrong length on string assignment |
| |
| @item |
| Violations of style rules if style checking is enabled |
| |
| @item |
| Unused @emph{with} clauses |
| |
| @item |
| @cite{Bit_Order} usage that does not have any effect |
| |
| @item |
| @cite{Standard.Duration} used to resolve universal fixed expression |
| |
| @item |
| Dereference of possibly null value |
| |
| @item |
| Declaration that is likely to cause storage error |
| |
| @item |
| Internal GNAT unit @emph{with}ed by application unit |
| |
| @item |
| Values known to be out of range at compile time |
| |
| @item |
| Unreferenced or unmodified variables. Note that a special |
| exemption applies to variables which contain any of the substrings |
| @cite{DISCARD@comma{} DUMMY@comma{} IGNORE@comma{} JUNK@comma{} UNUSED}, in any casing. Such variables |
| are considered likely to be intentionally used in a situation where |
| otherwise a warning would be given, so warnings of this kind are |
| always suppressed for such variables. |
| |
| @item |
| Address overlays that could clobber memory |
| |
| @item |
| Unexpected initialization when address clause present |
| |
| @item |
| Bad alignment for address clause |
| |
| @item |
| Useless type conversions |
| |
| @item |
| Redundant assignment statements and other redundant constructs |
| |
| @item |
| Useless exception handlers |
| |
| @item |
| Accidental hiding of name by child unit |
| |
| @item |
| Access before elaboration detected at compile time |
| |
| @item |
| A range in a @cite{for} loop that is known to be null or might be null |
| @end itemize |
| |
| The following section lists compiler switches that are available |
| to control the handling of warning messages. It is also possible |
| to exercise much finer control over what warnings are issued and |
| suppressed using the GNAT pragma Warnings (see the description |
| of the pragma in the @cite{GNAT_Reference_manual}). |
| |
| @geindex -gnatwa (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwa} |
| |
| @emph{Activate most optional warnings.} |
| |
| This switch activates most optional warning messages. See the 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: |
| |
| |
| @itemize * |
| |
| @item |
| @code{-gnatwd} (implicit dereferencing) |
| |
| @item |
| @code{-gnatw.d} (tag warnings with -gnatw switch) |
| |
| @item |
| @code{-gnatwh} (hiding) |
| |
| @item |
| @code{-gnatw.h} (holes in record layouts) |
| |
| @item |
| @code{-gnatw.k} (redefinition of names in standard) |
| |
| @item |
| @code{-gnatwl} (elaboration warnings) |
| |
| @item |
| @code{-gnatw.l} (inherited aspects) |
| |
| @item |
| @code{-gnatw.n} (atomic synchronization) |
| |
| @item |
| @code{-gnatwo} (address clause overlay) |
| |
| @item |
| @code{-gnatw.o} (values set by out parameters ignored) |
| |
| @item |
| @code{-gnatw.s} (overridden size clause) |
| |
| @item |
| @code{-gnatwt} (tracking of deleted conditional code) |
| |
| @item |
| @code{-gnatw.u} (unordered enumeration) |
| |
| @item |
| @code{-gnatw.w} (use of Warnings Off) |
| |
| @item |
| @code{-gnatw.y} (reasons for package needing body) |
| @end itemize |
| |
| All other optional warnings are turned on. |
| @end table |
| |
| @geindex -gnatwA (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwA} |
| |
| @emph{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. Note that unlike switch @emph{-gnatws}, the |
| use of switch @emph{-gnatwA} does not suppress warnings that are |
| normally given unconditionally and cannot be individually controlled |
| (for example, the warning about a missing exit path in a function). |
| Also, again unlike switch @emph{-gnatws}, warnings suppressed by |
| the use of switch @emph{-gnatwA} can be individually turned back |
| on. For example the use of switch @emph{-gnatwA} followed by |
| switch @emph{-gnatwd} will suppress all optional warnings except |
| the warnings for implicit dereferencing. |
| @end table |
| |
| @geindex -gnatw.a (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.a} |
| |
| @emph{Activate warnings on failing assertions.} |
| |
| @geindex Assert failures |
| |
| This switch activates warnings for assertions where the compiler can tell at |
| compile time that the assertion will fail. Note that this warning is given |
| even if assertions are disabled. The default is that such warnings are |
| generated. |
| @end table |
| |
| @geindex -gnatw.A (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.A} |
| |
| @emph{Suppress warnings on failing assertions.} |
| |
| @geindex Assert failures |
| |
| This switch suppresses warnings for assertions where the compiler can tell at |
| compile time that the assertion will fail. |
| @end table |
| |
| @geindex -gnatwb (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwb} |
| |
| @emph{Activate warnings on bad fixed values.} |
| |
| @geindex Bad fixed values |
| |
| @geindex Fixed-point Small value |
| |
| @geindex Small value |
| |
| This switch activates warnings for static fixed-point expressions whose |
| value is not an exact multiple of Small. Such values are implementation |
| dependent, since an implementation is free to choose either of the multiples |
| that surround the value. GNAT always chooses the closer one, but this is not |
| required behavior, and it is better to specify a value that is an exact |
| multiple, ensuring predictable execution. The default is that such warnings |
| are not generated. |
| @end table |
| |
| @geindex -gnatwB (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwB} |
| |
| @emph{Suppress warnings on bad fixed values.} |
| |
| This switch suppresses warnings for static fixed-point expressions whose |
| value is not an exact multiple of Small. |
| @end table |
| |
| @geindex -gnatw.b (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.b} |
| |
| @emph{Activate warnings on biased representation.} |
| |
| @geindex Biased representation |
| |
| This switch activates warnings when a size clause, value size clause, component |
| clause, or component size clause forces the use of biased representation for an |
| integer type (e.g. representing a range of 10..11 in a single bit by using 0/1 |
| to represent 10/11). The default is that such warnings are generated. |
| @end table |
| |
| @geindex -gnatwB (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.B} |
| |
| @emph{Suppress warnings on biased representation.} |
| |
| This switch suppresses warnings for representation clauses that force the use |
| of biased representation. |
| @end table |
| |
| @geindex -gnatwc (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwc} |
| |
| @emph{Activate warnings on conditionals.} |
| |
| @geindex Conditionals |
| @geindex constant |
| |
| 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. |
| Note that this warning does |
| not get issued for the use of boolean variables or constants whose |
| values are known at compile time, since this is a standard technique |
| for conditional compilation in Ada, and this would generate too many |
| false positive warnings. |
| |
| This warning option also activates a special test for comparisons using |
| the operators '>=' and' <='. |
| If the compiler can tell that only the equality condition is possible, |
| then it will warn that the '>' or '<' part of the test |
| is useless and that the operator could be replaced by '='. |
| An example would be comparing a @cite{Natural} variable <= 0. |
| |
| This warning option also generates warnings if |
| one or both tests is optimized away in a membership test for integer |
| values if the result can be determined at compile time. Range tests on |
| enumeration types are not included, since it is common for such tests |
| to include an end point. |
| |
| This warning can also be turned on using @emph{-gnatwa}. |
| @end table |
| |
| @geindex -gnatwC (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwC} |
| |
| @emph{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. |
| @end table |
| |
| @geindex -gnatw.c (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.c} |
| |
| @emph{Activate warnings on missing component clauses.} |
| |
| @geindex Component clause |
| @geindex missing |
| |
| This switch activates warnings for record components where a record |
| representation clause is present and has component clauses for the |
| majority, but not all, of the components. A warning is given for each |
| component for which no component clause is present. |
| @end table |
| |
| @geindex -gnatwC (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.C} |
| |
| @emph{Suppress warnings on missing component clauses.} |
| |
| This switch suppresses warnings for record components that are |
| missing a component clause in the situation described above. |
| @end table |
| |
| @geindex -gnatwd (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwd} |
| |
| @emph{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 @cite{.all} will generate a warning. With this warning |
| enabled, access checks occur only at points where an explicit |
| @cite{.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. |
| @end table |
| |
| @geindex -gnatwD (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwD} |
| |
| @emph{Suppress warnings on implicit dereferencing.} |
| |
| @geindex Implicit dereferencing |
| |
| @geindex Dereferencing |
| @geindex implicit |
| |
| This switch suppresses warnings for implicit dereferences in |
| indexed components, slices, and selected components. |
| @end table |
| |
| @geindex -gnatw.d (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.d} |
| |
| @emph{Activate tagging of warning and info messages.} |
| |
| If this switch is set, then warning messages are tagged, with one of the |
| following strings: |
| |
| @quotation |
| |
| |
| @itemize - |
| |
| @item |
| @emph{[-gnatw?]} |
| Used to tag warnings controlled by the switch @emph{-gnatwx} where x |
| is a letter a-z. |
| |
| @item |
| @emph{[-gnatw.?]} |
| Used to tag warnings controlled by the switch @emph{-gnatw.x} where x |
| is a letter a-z. |
| |
| @item |
| @emph{[-gnatel]} |
| Used to tag elaboration information (info) messages generated when the |
| static model of elaboration is used and the @emph{-gnatel} switch is set. |
| |
| @item |
| @emph{[restriction warning]} |
| Used to tag warning messages for restriction violations, activated by use |
| of the pragma @emph{Restriction_Warnings}. |
| |
| @item |
| @emph{[warning-as-error]} |
| Used to tag warning messages that have been converted to error messages by |
| use of the pragma Warning_As_Error. Note that such warnings are prefixed by |
| the string "error: " rather than "warning: ". |
| |
| @item |
| @emph{[enabled by default]} |
| Used to tag all other warnings that are always given by default, unless |
| warnings are completely suppressed using pragma @emph{Warnings(Off)} or |
| the switch @emph{-gnatws}. |
| @end itemize |
| @end quotation |
| @end table |
| |
| @geindex -gnatw.d (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.D} |
| |
| @emph{Deactivate tagging of warning and info messages messages.} |
| |
| If this switch is set, then warning messages return to the default |
| mode in which warnings and info messages are not tagged as described above for |
| @cite{-gnatw.d}. |
| @end table |
| |
| @geindex -gnatwe (gcc) |
| |
| @geindex Warnings |
| @geindex treat as error |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwe} |
| |
| @emph{Treat warnings and style checks as errors.} |
| |
| This switch causes warning messages and style check 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. Note that this |
| is the only -gnatw switch that affects the handling of style check messages. |
| Note also that this switch has no effect on info (information) messages, which |
| are not treated as errors if this switch is present. |
| @end table |
| |
| @geindex -gnatw.e (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.e} |
| |
| @emph{Activate every optional warning.} |
| |
| @geindex Warnings |
| @geindex activate every optional warning |
| |
| This switch activates all optional warnings, including those which |
| are not activated by @cite{-gnatwa}. The use of this switch is not |
| recommended for normal use. If you turn this switch on, it is almost |
| certain that you will get large numbers of useless warnings. The |
| warnings that are excluded from @cite{-gnatwa} are typically highly |
| specialized warnings that are suitable for use only in code that has |
| been specifically designed according to specialized coding rules. |
| @end table |
| |
| @geindex -gnatwf (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwf} |
| |
| @emph{Activate warnings on unreferenced formals.} |
| |
| @geindex Formals |
| @geindex unreferenced |
| |
| 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 @emph{-gnatwu}. The |
| default is that these warnings are not generated. |
| @end table |
| |
| @geindex -gnatwF (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwF} |
| |
| @emph{Suppress warnings on unreferenced formals.} |
| |
| This switch suppresses warnings for unreferenced formal |
| parameters. Note that the |
| combination @emph{-gnatwu} followed by @emph{-gnatwF} has the |
| effect of warning on unreferenced entities other than subprogram |
| formals. |
| @end table |
| |
| @geindex -gnatwg (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwg} |
| |
| @emph{Activate warnings on unrecognized pragmas.} |
| |
| @geindex Pragmas |
| @geindex unrecognized |
| |
| This switch causes a warning to be generated if an unrecognized |
| pragma is encountered. Apart from issuing this warning, the |
| pragma is ignored and has no effect. The default |
| is that such warnings are issued (satisfying the Ada Reference |
| Manual requirement that such warnings appear). |
| @end table |
| |
| @geindex -gnatwG (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwG} |
| |
| @emph{Suppress warnings on unrecognized pragmas.} |
| |
| This switch suppresses warnings for unrecognized pragmas. |
| @end table |
| |
| @geindex -gnatw.g (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.g} |
| |
| @emph{Warnings used for GNAT sources.} |
| |
| This switch sets the warning categories that are used by the standard |
| GNAT style. Currently this is equivalent to |
| @emph{-gnatwAao.sI.C.V.X} |
| but more warnings may be added in the future without advanced notice. |
| @end table |
| |
| @geindex -gnatwh (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwh} |
| |
| @emph{Activate warnings on hiding.} |
| |
| @geindex Hiding of Declarations |
| |
| 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. |
| @end table |
| |
| @geindex -gnatwH (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwH} |
| |
| @emph{Suppress warnings on hiding.} |
| |
| This switch suppresses warnings on hiding declarations. |
| @end table |
| |
| @geindex -gnatw.h (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.h} |
| |
| @emph{Activate warnings on holes/gaps in records.} |
| |
| @geindex Record Representation (gaps) |
| |
| This switch activates warnings on component clauses in record |
| representation clauses that leave holes (gaps) in the record layout. |
| If this warning option is active, then record representation clauses |
| should specify a contiguous layout, adding unused fill fields if needed. |
| @end table |
| |
| @geindex -gnatw.H (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.H} |
| |
| @emph{Suppress warnings on holes/gaps in records.} |
| |
| This switch suppresses warnings on component clauses in record |
| representation clauses that leave holes (haps) in the record layout. |
| @end table |
| |
| @geindex -gnatwi (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwi} |
| |
| @emph{Activate warnings on implementation units.} |
| |
| This switch activates warnings for a @emph{with} of an internal GNAT |
| implementation unit, defined as any unit from the @cite{Ada}, |
| @cite{Interfaces}, @cite{GNAT}, |
| or @cite{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 @emph{with}ed |
| by user programs. The default is that such warnings are generated |
| @end table |
| |
| @geindex -gnatwI (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwI} |
| |
| @emph{Disable warnings on implementation units.} |
| |
| This switch disables warnings for a @emph{with} of an internal GNAT |
| implementation unit. |
| @end table |
| |
| @geindex -gnatw.i (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.i} |
| |
| @emph{Activate warnings on overlapping actuals.} |
| |
| This switch enables a warning on statically detectable overlapping actuals in |
| a subprogram call, when one of the actuals is an in-out parameter, and the |
| types of the actuals are not by-copy types. This warning is off by default. |
| @end table |
| |
| @geindex -gnatw.I (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.I} |
| |
| @emph{Disable warnings on overlapping actuals.} |
| |
| This switch disables warnings on overlapping actuals in a call.. |
| @end table |
| |
| @geindex -gnatwj (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwj} |
| |
| @emph{Activate warnings on obsolescent features (Annex J).} |
| |
| @geindex Features |
| @geindex obsolescent |
| |
| @geindex Obsolescent features |
| |
| If this warning option is activated, then warnings are generated for |
| calls to subprograms marked with @cite{pragma Obsolescent} and |
| for use of features in Annex J of the Ada Reference Manual. In the |
| case of Annex J, not all features are flagged. In particular use |
| of the renamed packages (like @cite{Text_IO}) and use of package |
| @cite{ASCII} are not flagged, since these are very common and |
| would generate many annoying positive warnings. The default is that |
| such warnings are not generated. |
| |
| In addition to the above cases, warnings are also generated for |
| GNAT features that have been provided in past versions but which |
| have been superseded (typically by features in the new Ada standard). |
| For example, @cite{pragma Ravenscar} will be flagged since its |
| function is replaced by @cite{pragma Profile(Ravenscar)}, and |
| @cite{pragma Interface_Name} will be flagged since its function |
| is replaced by @cite{pragma Import}. |
| |
| Note that this warning option functions differently from the |
| restriction @cite{No_Obsolescent_Features} in two respects. |
| First, the restriction applies only to annex J features. |
| Second, the restriction does flag uses of package @cite{ASCII}. |
| @end table |
| |
| @geindex -gnatwJ (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwJ} |
| |
| @emph{Suppress warnings on obsolescent features (Annex J).} |
| |
| This switch disables warnings on use of obsolescent features. |
| @end table |
| |
| @geindex -gnatwk (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwk} |
| |
| @emph{Activate warnings on variables that could be constants.} |
| |
| This switch activates warnings for variables that are initialized but |
| never modified, and then could be declared constants. The default is that |
| such warnings are not given. |
| @end table |
| |
| @geindex -gnatwK (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwK} |
| |
| @emph{Suppress warnings on variables that could be constants.} |
| |
| This switch disables warnings on variables that could be declared constants. |
| @end table |
| |
| @geindex -gnatw.k (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.k} |
| |
| @emph{Activate warnings on redefinition of names in standard.} |
| |
| This switch activates warnings for declarations that declare a name that |
| is defined in package Standard. Such declarations can be confusing, |
| especially since the names in package Standard continue to be directly |
| visible, meaning that use visibiliy on such redeclared names does not |
| work as expected. Names of discriminants and components in records are |
| not included in this check. |
| @end table |
| |
| @geindex -gnatwK (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.K} |
| |
| @emph{Suppress warnings on redefinition of names in standard.} |
| |
| This switch activates warnings for declarations that declare a name that |
| is defined in package Standard. |
| @end table |
| |
| @geindex -gnatwl (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwl} |
| |
| @emph{Activate warnings for elaboration pragmas.} |
| |
| @geindex Elaboration |
| @geindex warnings |
| |
| This switch activates warnings for possible elaboration problems, |
| including suspicious use |
| of @cite{Elaborate} pragmas, when using the static elaboration model, and |
| possible situations that may raise @cite{Program_Error} when using the |
| dynamic elaboration model. |
| See the section in this guide on elaboration checking for further details. |
| The default is that such warnings |
| are not generated. |
| @end table |
| |
| @geindex -gnatwL (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwL} |
| |
| @emph{Suppress warnings for elaboration pragmas.} |
| |
| This switch suppresses warnings for possible elaboration problems. |
| @end table |
| |
| @geindex -gnatw.l (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.l} |
| |
| @emph{List inherited aspects.} |
| |
| This switch causes the compiler to list inherited invariants, |
| preconditions, and postconditions from Type_Invariant'Class, Invariant'Class, |
| Pre'Class, and Post'Class aspects. Also list inherited subtype predicates. |
| @end table |
| |
| @geindex -gnatw.L (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.L} |
| |
| @emph{Suppress listing of inherited aspects.} |
| |
| This switch suppresses listing of inherited aspects. |
| @end table |
| |
| @geindex -gnatwm (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwm} |
| |
| @emph{Activate warnings on modified but unreferenced variables.} |
| |
| This switch activates warnings for variables that are assigned (using |
| an initialization value or with one or more assignment statements) but |
| whose value is never read. The warning is suppressed for volatile |
| variables and also for variables that are renamings of other variables |
| or for which an address clause is given. |
| The default is that these warnings are not given. |
| @end table |
| |
| @geindex -gnatwM (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwM} |
| |
| @emph{Disable warnings on modified but unreferenced variables.} |
| |
| This switch disables warnings for variables that are assigned or |
| initialized, but never read. |
| @end table |
| |
| @geindex -gnatw.m (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.m} |
| |
| @emph{Activate warnings on suspicious modulus values.} |
| |
| This switch activates warnings for modulus values that seem suspicious. |
| The cases caught are where the size is the same as the modulus (e.g. |
| a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64 |
| with no size clause. The guess in both cases is that 2**x was intended |
| rather than x. In addition expressions of the form 2*x for small x |
| generate a warning (the almost certainly accurate guess being that |
| 2**x was intended). The default is that these warnings are given. |
| @end table |
| |
| @geindex -gnatw.M (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.M} |
| |
| @emph{Disable warnings on suspicious modulus values.} |
| |
| This switch disables warnings for suspicious modulus values. |
| @end table |
| |
| @geindex -gnatwn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwn} |
| |
| @emph{Set normal warnings mode.} |
| |
| This switch sets normal warning mode, in which enabled warnings are |
| issued and treated as warnings rather than errors. This is the default |
| mode. the switch @emph{-gnatwn} can be used to cancel the effect of |
| an explicit @emph{-gnatws} or |
| @emph{-gnatwe}. It also cancels the effect of the |
| implicit @emph{-gnatwe} that is activated by the |
| use of @emph{-gnatg}. |
| @end table |
| |
| @geindex -gnatw.n (gcc) |
| |
| @geindex Atomic Synchronization |
| @geindex warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.n} |
| |
| @emph{Activate warnings on atomic synchronization.} |
| |
| This switch actives warnings when an access to an atomic variable |
| requires the generation of atomic synchronization code. These |
| warnings are off by default. |
| @end table |
| |
| @geindex -gnatw.N (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.N} |
| |
| @emph{Suppress warnings on atomic synchronization.} |
| |
| @geindex Atomic Synchronization |
| @geindex warnings |
| |
| This switch suppresses warnings when an access to an atomic variable |
| requires the generation of atomic synchronization code. |
| @end table |
| |
| @geindex -gnatwo (gcc) |
| |
| @geindex Address Clauses |
| @geindex warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwo} |
| |
| @emph{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. |
| @end table |
| |
| @geindex -gnatwO (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwO} |
| |
| @emph{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. |
| @end table |
| |
| @geindex -gnatw.o (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.o} |
| |
| @emph{Activate warnings on modified but unreferenced out parameters.} |
| |
| This switch activates warnings for variables that are modified by using |
| them as actuals for a call to a procedure with an out mode formal, where |
| the resulting assigned value is never read. It is applicable in the case |
| where there is more than one out mode formal. If there is only one out |
| mode formal, the warning is issued by default (controlled by -gnatwu). |
| The warning is suppressed for volatile |
| variables and also for variables that are renamings of other variables |
| or for which an address clause is given. |
| The default is that these warnings are not given. |
| @end table |
| |
| @geindex -gnatw.O (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.O} |
| |
| @emph{Disable warnings on modified but unreferenced out parameters.} |
| |
| This switch suppresses warnings for variables that are modified by using |
| them as actuals for a call to a procedure with an out mode formal, where |
| the resulting assigned value is never read. |
| @end table |
| |
| @geindex -gnatwp (gcc) |
| |
| @geindex Inlining |
| @geindex warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwp} |
| |
| @emph{Activate warnings on ineffective pragma Inlines.} |
| |
| This switch activates warnings for failure of front end inlining |
| (activated by @emph{-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. The default is |
| that such warnings are not given. |
| Warnings on ineffective inlining by the gcc back-end can be activated |
| separately, using the gcc switch -Winline. |
| @end table |
| |
| @geindex -gnatwP (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwP} |
| |
| @emph{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. |
| @end table |
| |
| @geindex -gnatw.p (gcc) |
| |
| @geindex Parameter order |
| @geindex warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.p} |
| |
| @emph{Activate warnings on parameter ordering.} |
| |
| This switch activates warnings for cases of suspicious parameter |
| ordering when the list of arguments are all simple identifiers that |
| match the names of the formals, but are in a different order. The |
| warning is suppressed if any use of named parameter notation is used, |
| so this is the appropriate way to suppress a false positive (and |
| serves to emphasize that the "misordering" is deliberate). The |
| default is that such warnings are not given. |
| @end table |
| |
| @geindex -gnatw.P (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.P} |
| |
| @emph{Suppress warnings on parameter ordering.} |
| |
| This switch suppresses warnings on cases of suspicious parameter |
| ordering. |
| @end table |
| |
| @geindex -gnatwq (gcc) |
| |
| @geindex Parentheses |
| @geindex warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwq} |
| |
| @emph{Activate warnings on questionable missing parentheses.} |
| |
| This switch activates warnings for cases where parentheses are not used and |
| the result is potential ambiguity from a readers point of view. For example |
| (not a > b) when a and b are modular means ((not a) > b) and very likely the |
| programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and |
| quite likely ((-x) mod 5) was intended. In such situations it seems best to |
| follow the rule of always parenthesizing to make the association clear, and |
| this warning switch warns if such parentheses are not present. The default |
| is that these warnings are given. |
| @end table |
| |
| @geindex -gnatwQ (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwQ} |
| |
| @emph{Suppress warnings on questionable missing parentheses.} |
| |
| This switch suppresses warnings for cases where the association is not |
| clear and the use of parentheses is preferred. |
| @end table |
| |
| @geindex -gnatwr (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwr} |
| |
| @emph{Activate warnings on redundant constructs.} |
| |
| This switch activates warnings for redundant constructs. The following |
| is the current list of constructs regarded as redundant: |
| |
| |
| @itemize * |
| |
| @item |
| Assignment of an item to itself. |
| |
| @item |
| Type conversion that converts an expression to its own type. |
| |
| @item |
| Use of the attribute @cite{Base} where @cite{typ'Base} is the same |
| as @cite{typ}. |
| |
| @item |
| Use of pragma @cite{Pack} when all components are placed by a record |
| representation clause. |
| |
| @item |
| Exception handler containing only a reraise statement (raise with no |
| operand) which has no effect. |
| |
| @item |
| Use of the operator abs on an operand that is known at compile time |
| to be non-negative |
| |
| @item |
| Comparison of boolean expressions to an explicit True value. |
| @end itemize |
| |
| The default is that warnings for redundant constructs are not given. |
| @end table |
| |
| @geindex -gnatwR (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwR} |
| |
| @emph{Suppress warnings on redundant constructs.} |
| |
| This switch suppresses warnings for redundant constructs. |
| @end table |
| |
| @geindex -gnatw.r (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.r} |
| |
| @emph{Activate warnings for object renaming function.} |
| |
| This switch activates warnings for an object renaming that renames a |
| function call, which is equivalent to a constant declaration (as |
| opposed to renaming the function itself). The default is that these |
| warnings are given. |
| @end table |
| |
| @geindex -gnatwT (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.R} |
| |
| @emph{Suppress warnings for object renaming function.} |
| |
| This switch suppresses warnings for object renaming function. |
| @end table |
| |
| @geindex -gnatws (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatws} |
| |
| @emph{Suppress all warnings.} |
| |
| This switch completely suppresses the |
| output of all warning messages from the GNAT front end, including |
| both warnings that can be controlled by switches described in this |
| section, and those that are normally given unconditionally. The |
| effect of this suppress action can only be cancelled by a subsequent |
| use of the switch @emph{-gnatwn}. |
| |
| Note that switch @emph{-gnatws} does not suppress |
| warnings from the @emph{gcc} back end. |
| To suppress these back end warnings as well, use the switch @emph{-w} |
| in addition to @emph{-gnatws}. Also this switch has no effect on the |
| handling of style check messages. |
| @end table |
| |
| @geindex -gnatw.s (gcc) |
| |
| @geindex Record Representation (component sizes) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.s} |
| |
| @emph{Activate warnings on overridden size clauses.} |
| |
| This switch activates warnings on component clauses in record |
| representation clauses where the length given overrides that |
| specified by an explicit size clause for the component type. A |
| warning is similarly given in the array case if a specified |
| component size overrides an explicit size clause for the array |
| component type. |
| @end table |
| |
| @geindex -gnatw.S (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.S} |
| |
| @emph{Suppress warnings on overridden size clauses.} |
| |
| This switch suppresses warnings on component clauses in record |
| representation clauses that override size clauses, and similar |
| warnings when an array component size overrides a size clause. |
| @end table |
| |
| @geindex -gnatwt (gcc) |
| |
| @geindex Deactivated code |
| @geindex warnings |
| |
| @geindex Deleted code |
| @geindex warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwt} |
| |
| @emph{Activate warnings for tracking of deleted conditional code.} |
| |
| This switch activates warnings for tracking of code in conditionals (IF and |
| CASE statements) that is detected to be dead code which cannot be executed, and |
| which is removed by the front end. This warning is off by default. This may be |
| useful for detecting deactivated code in certified applications. |
| @end table |
| |
| @geindex -gnatwT (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwT} |
| |
| @emph{Suppress warnings for tracking of deleted conditional code.} |
| |
| This switch suppresses warnings for tracking of deleted conditional code. |
| @end table |
| |
| @geindex -gnatw.t (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.t} |
| |
| @emph{Activate warnings on suspicious contracts.} |
| |
| This switch activates warnings on suspicious contracts. This includes |
| warnings on suspicious postconditions (whether a pragma @cite{Postcondition} or a |
| @cite{Post} aspect in Ada 2012) and suspicious contract cases (pragma or aspect |
| @cite{Contract_Cases}). A function postcondition or contract case is suspicious |
| when no postcondition or contract case for this function mentions the result |
| of the function. A procedure postcondition or contract case is suspicious |
| when it only refers to the pre-state of the procedure, because in that case |
| it should rather be expressed as a precondition. This switch also controls |
| warnings on suspicious cases of expressions typically found in contracts like |
| quantified expressions and uses of Update attribute. The default is that such |
| warnings are generated. |
| @end table |
| |
| @geindex -gnatw.T (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.T} |
| |
| @emph{Suppress warnings on suspicious contracts.} |
| |
| This switch suppresses warnings on suspicious contracts. |
| @end table |
| |
| @geindex -gnatwu (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwu} |
| |
| @emph{Activate warnings on unused entities.} |
| |
| This switch activates warnings to be generated for entities that |
| are declared but not referenced, and for units that are @emph{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 a with'ed |
| package is referenced but the only references are in @cite{use} |
| clauses or @cite{renames} |
| declarations, a warning is still generated. A warning is also generated |
| for a generic package that is @emph{with}ed but never instantiated. |
| In the case where a package or subprogram body is compiled, and there |
| is a @emph{with} on the corresponding spec |
| that is only referenced in the body, |
| a warning is also generated, noting that the |
| @emph{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 includes the effect of @emph{-gnatwf}). |
| @end table |
| |
| @geindex -gnatwU (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwU} |
| |
| @emph{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 @emph{-gnatwF}). |
| @end table |
| |
| @geindex -gnatw.u (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.u} |
| |
| @emph{Activate warnings on unordered enumeration types.} |
| |
| This switch causes enumeration types to be considered as conceptually |
| unordered, unless an explicit pragma @cite{Ordered} is given for the type. |
| The effect is to generate warnings in clients that use explicit comparisons |
| or subranges, since these constructs both treat objects of the type as |
| ordered. (A @emph{client} is defined as a unit that is other than the unit in |
| which the type is declared, or its body or subunits.) Please refer to |
| the description of pragma @cite{Ordered} in the |
| @cite{GNAT Reference Manual} for further details. |
| The default is that such warnings are not generated. |
| @end table |
| |
| @geindex -gnatw.U (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.U} |
| |
| @emph{Deactivate warnings on unordered enumeration types.} |
| |
| This switch causes all enumeration types to be considered as ordered, so |
| that no warnings are given for comparisons or subranges for any type. |
| @end table |
| |
| @geindex -gnatwv (gcc) |
| |
| @geindex Unassigned variable warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwv} |
| |
| @emph{Activate warnings on unassigned variables.} |
| |
| This switch activates warnings for access to variables which |
| may not be properly initialized. The default is that |
| such warnings are generated. |
| @end table |
| |
| @geindex -gnatwV (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwV} |
| |
| @emph{Suppress warnings on unassigned variables.} |
| |
| This switch suppresses warnings for access to variables which |
| may not be properly initialized. |
| For variables of a composite type, the warning can also be suppressed in |
| Ada 2005 by using a default initialization with a box. For example, if |
| Table is an array of records whose components are only partially uninitialized, |
| then the following code: |
| |
| @example |
| Tab : Table := (others => <>); |
| @end example |
| |
| will suppress warnings on subsequent statements that access components |
| of variable Tab. |
| @end table |
| |
| @geindex -gnatw.v (gcc) |
| |
| @geindex bit order warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.v} |
| |
| @emph{Activate info messages for non-default bit order.} |
| |
| This switch activates messages (labeled "info", they are not warnings, |
| just informational messages) about the effects of non-default bit-order |
| on records to which a component clause is applied. The effect of specifying |
| non-default bit ordering is a bit subtle (and changed with Ada 2005), so |
| these messages, which are given by default, are useful in understanding the |
| exact consequences of using this feature. |
| @end table |
| |
| @geindex -gnatw.V (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.V} |
| |
| @emph{Suppress info messages for non-default bit order.} |
| |
| This switch suppresses information messages for the effects of specifying |
| non-default bit order on record components with component clauses. |
| @end table |
| |
| @geindex -gnatww (gcc) |
| |
| @geindex String indexing warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatww} |
| |
| @emph{Activate warnings on wrong low bound assumption.} |
| |
| This switch activates warnings for indexing an unconstrained string parameter |
| with a literal or S'Length. This is a case where the code is assuming that the |
| low bound is one, which is in general not true (for example when a slice is |
| passed). The default is that such warnings are generated. |
| @end table |
| |
| @geindex -gnatwW (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwW} |
| |
| @emph{Suppress warnings on wrong low bound assumption.} |
| |
| This switch suppresses warnings for indexing an unconstrained string parameter |
| with a literal or S'Length. Note that this warning can also be suppressed |
| in a particular case by adding an assertion that the lower bound is 1, |
| as shown in the following example: |
| |
| @example |
| procedure K (S : String) is |
| pragma Assert (S'First = 1); |
| ... |
| @end example |
| @end table |
| |
| @geindex -gnatw.w (gcc) |
| |
| @geindex Warnings Off control |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.w} |
| |
| @emph{Activate warnings on Warnings Off pragmas.} |
| |
| This switch activates warnings for use of @cite{pragma Warnings (Off@comma{} entity)} |
| where either the pragma is entirely useless (because it suppresses no |
| warnings), or it could be replaced by @cite{pragma Unreferenced} or |
| @cite{pragma Unmodified}. |
| Also activates warnings for the case of |
| Warnings (Off, String), where either there is no matching |
| Warnings (On, String), or the Warnings (Off) did not suppress any warning. |
| The default is that these warnings are not given. |
| @end table |
| |
| @geindex -gnatw.W (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.W} |
| |
| @emph{Suppress warnings on unnecessary Warnings Off pragmas.} |
| |
| This switch suppresses warnings for use of @cite{pragma Warnings (Off@comma{} ...)}. |
| @end table |
| |
| @geindex -gnatwx (gcc) |
| |
| @geindex Export/Import pragma warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwx} |
| |
| @emph{Activate warnings on Export/Import pragmas.} |
| |
| This switch activates warnings on Export/Import pragmas when |
| the compiler detects a possible conflict between the Ada and |
| foreign language calling sequences. For example, the use of |
| default parameters in a convention C procedure is dubious |
| because the C compiler cannot supply the proper default, so |
| a warning is issued. The default is that such warnings are |
| generated. |
| @end table |
| |
| @geindex -gnatwX (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwX} |
| |
| @emph{Suppress warnings on Export/Import pragmas.} |
| |
| This switch suppresses warnings on Export/Import pragmas. |
| The sense of this is that you are telling the compiler that |
| you know what you are doing in writing the pragma, and it |
| should not complain at you. |
| @end table |
| |
| @geindex -gnatwm (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.x} |
| |
| @emph{Activate warnings for No_Exception_Propagation mode.} |
| |
| This switch activates warnings for exception usage when pragma Restrictions |
| (No_Exception_Propagation) is in effect. Warnings are given for implicit or |
| explicit exception raises which are not covered by a local handler, and for |
| exception handlers which do not cover a local raise. The default is that these |
| warnings are not given. |
| |
| @item @code{-gnatw.X} |
| |
| @emph{Disable warnings for No_Exception_Propagation mode.} |
| |
| This switch disables warnings for exception usage when pragma Restrictions |
| (No_Exception_Propagation) is in effect. |
| @end table |
| |
| @geindex -gnatwy (gcc) |
| |
| @geindex Ada compatibility issues warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwy} |
| |
| @emph{Activate warnings for Ada compatibility issues.} |
| |
| For the most part, newer versions of Ada are upwards compatible |
| with older versions. For example, Ada 2005 programs will almost |
| always work when compiled as Ada 2012. |
| However there are some exceptions (for example the fact that |
| @cite{some} is now a reserved word in Ada 2012). This |
| switch activates several warnings to help in identifying |
| and correcting such incompatibilities. The default is that |
| these warnings are generated. Note that at one point Ada 2005 |
| was called Ada 0Y, hence the choice of character. |
| @end table |
| |
| @geindex -gnatwY (gcc) |
| |
| @geindex Ada compatibility issues warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwY} |
| |
| @emph{Disable warnings for Ada compatibility issues.} |
| |
| This switch suppresses the warnings intended to help in identifying |
| incompatibilities between Ada language versions. |
| @end table |
| |
| @geindex -gnatw.y (gcc) |
| |
| @geindex Package spec needing body |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.y} |
| |
| @emph{Activate information messages for why package spec needs body.} |
| |
| There are a number of cases in which a package spec needs a body. |
| For example, the use of pragma Elaborate_Body, or the declaration |
| of a procedure specification requiring a completion. This switch |
| causes information messages to be output showing why a package |
| specification requires a body. This can be useful in the case of |
| a large package specification which is unexpectedly requiring a |
| body. The default is that such information messages are not output. |
| @end table |
| |
| @geindex -gnatw.Y (gcc) |
| |
| @geindex No information messages for why package spec needs body |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.Y} |
| |
| @emph{Disable information messages for why package spec needs body.} |
| |
| This switch suppresses the output of information messages showing why |
| a package specification needs a body. |
| @end table |
| |
| @geindex -gnatwz (gcc) |
| |
| @geindex Unchecked_Conversion warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwz} |
| |
| @emph{Activate warnings on unchecked conversions.} |
| |
| This switch activates warnings for unchecked conversions |
| where the types are known at compile time to have different |
| sizes. The default is that such warnings are generated. Warnings are also |
| generated for subprogram pointers with different conventions. |
| @end table |
| |
| @geindex -gnatwZ (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatwZ} |
| |
| @emph{Suppress warnings on unchecked conversions.} |
| |
| This switch suppresses warnings for unchecked conversions |
| where the types are known at compile time to have different |
| sizes or conventions. |
| @end table |
| |
| @geindex -gnatw.z (gcc) |
| |
| @geindex Size/Alignment warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.z} |
| |
| @emph{Activate warnings for size not a multiple of alignment.} |
| |
| This switch activates warnings for cases of record types with |
| specified @cite{Size} and @cite{Alignment} attributes where the |
| size is not a multiple of the alignment, resulting in an object |
| size that is greater than the specified size. The default |
| is that such warnings are generated. |
| @end table |
| |
| @geindex -gnatw.Z (gcc) |
| |
| @geindex Size/Alignment warnings |
| |
| |
| @table @asis |
| |
| @item @code{-gnatw.Z} |
| |
| @emph{Suppress warnings for size not a multiple of alignment.} |
| |
| This switch suppresses warnings for cases of record types with |
| specified @cite{Size} and @cite{Alignment} attributes where the |
| size is not a multiple of the alignment, resulting in an object |
| size that is greater than the specified size. |
| The warning can also be |
| suppressed by giving an explicit @cite{Object_Size} value. |
| @end table |
| |
| @geindex -Wunused (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-Wunused} |
| |
| The warnings controlled by the @emph{-gnatw} switch are generated by |
| the front end of the compiler. The @emph{GCC} back end can provide |
| additional warnings and they are controlled by the @emph{-W} switch. |
| For example, @emph{-Wunused} activates back end |
| warnings for entities that are declared but not referenced. |
| @end table |
| |
| @geindex -Wuninitialized (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-Wuninitialized} |
| |
| Similarly, @emph{-Wuninitialized} activates |
| the back end warning for uninitialized variables. This switch must be |
| used in conjunction with an optimization level greater than zero. |
| @end table |
| |
| @geindex -Wstack-usage (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-Wstack-usage=@emph{len}} |
| |
| Warn if the stack usage of a subprogram might be larger than @cite{len} bytes. |
| See @ref{fd,,Static Stack Usage Analysis} for details. |
| @end table |
| |
| @geindex -Wall (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-Wall} |
| |
| This switch enables most warnings from the @emph{GCC} back end. |
| The code generator detects a number of warning situations that are missed |
| by the @emph{GNAT} front end, and this switch can be used to activate them. |
| The use of this switch also sets the default front end warning mode to |
| @emph{-gnatwa}, that is, most front end warnings activated as well. |
| @end table |
| |
| @geindex -w (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-w} |
| |
| Conversely, this switch suppresses warnings from the @emph{GCC} back end. |
| The use of this switch also sets the default front end warning mode to |
| @emph{-gnatws}, that is, front end warnings suppressed as well. |
| @end table |
| |
| @geindex -Werror (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-Werror} |
| |
| This switch causes warnings from the @emph{GCC} back end 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. |
| @end table |
| |
| A string of warning parameters can be used in the same parameter. For example: |
| |
| @example |
| -gnatwaGe |
| @end example |
| |
| will turn on all optional warnings except for unrecognized pragma warnings, |
| and also specify that warnings should be treated as errors. |
| |
| When no switch @emph{-gnatw} is used, this is equivalent to: |
| |
| @quotation |
| |
| |
| @itemize * |
| |
| @item |
| @code{-gnatw.a} |
| |
| @item |
| @code{-gnatwB} |
| |
| @item |
| @code{-gnatw.b} |
| |
| @item |
| @code{-gnatwC} |
| |
| @item |
| @code{-gnatw.C} |
| |
| @item |
| @code{-gnatwD} |
| |
| @item |
| @code{-gnatwF} |
| |
| @item |
| @code{-gnatwg} |
| |
| @item |
| @code{-gnatwH} |
| |
| @item |
| @code{-gnatwi} |
| |
| @item |
| @code{-gnatw.I} |
| |
| @item |
| @code{-gnatwJ} |
| |
| @item |
| @code{-gnatwK} |
| |
| @item |
| @code{-gnatwL} |
| |
| @item |
| @code{-gnatw.L} |
| |
| @item |
| @code{-gnatwM} |
| |
| @item |
| @code{-gnatw.m} |
| |
| @item |
| @code{-gnatwn} |
| |
| @item |
| @code{-gnatwo} |
| |
| @item |
| @code{-gnatw.O} |
| |
| @item |
| @code{-gnatwP} |
| |
| @item |
| @code{-gnatw.P} |
| |
| @item |
| @code{-gnatwq} |
| |
| @item |
| @code{-gnatwR} |
| |
| @item |
| @code{-gnatw.R} |
| |
| @item |
| @code{-gnatw.S} |
| |
| @item |
| @code{-gnatwT} |
| |
| @item |
| @code{-gnatw.T} |
| |
| @item |
| @code{-gnatwU} |
| |
| @item |
| @code{-gnatwv} |
| |
| @item |
| @code{-gnatww} |
| |
| @item |
| @code{-gnatw.W} |
| |
| @item |
| @code{-gnatwx} |
| |
| @item |
| @code{-gnatw.X} |
| |
| @item |
| @code{-gnatwy} |
| |
| @item |
| @code{-gnatwz} |
| @end itemize |
| @end quotation |
| |
| @node Debugging and Assertion Control,Validity Checking,Warning Message Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat debugging-and-assertion-control}@anchor{108}@anchor{gnat_ugn/building_executable_programs_with_gnat id16}@anchor{109} |
| @subsection Debugging and Assertion Control |
| |
| |
| @geindex -gnata (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnata} |
| |
| @geindex Assert |
| |
| @geindex Debug |
| |
| @geindex Assertions |
| |
| @geindex Precondition |
| |
| @geindex Postcondition |
| |
| @geindex Type invariants |
| |
| @geindex Subtype predicates |
| |
| The @cite{-gnata} option is equivalent to the following Assertion_Policy pragma: |
| |
| @example |
| pragma Assertion_Policy (Check); |
| @end example |
| |
| Which is a shorthand for: |
| |
| @example |
| pragma Assertion_Policy |
| (Assert => Check, |
| Static_Predicate => Check, |
| Dynamic_Predicate => Check, |
| Pre => Check, |
| Pre'Class => Check, |
| Post => Check, |
| Post'Class => Check, |
| Type_Invariant => Check, |
| Type_Invariant'Class => Check); |
| @end example |
| |
| The pragmas @cite{Assert} and @cite{Debug} normally have no effect and |
| are ignored. This switch, where @code{a} stands for assert, causes |
| pragmas @cite{Assert} and @cite{Debug} to be activated. This switch also |
| causes preconditions, postconditions, subtype predicates, and |
| type invariants to be activated. |
| |
| The pragmas have the form: |
| |
| @example |
| pragma Assert (<Boolean-expression> [, <static-string-expression>]) |
| pragma Debug (<procedure call>) |
| pragma Type_Invariant (<type-local-name>, <Boolean-expression>) |
| pragma Predicate (<type-local-name>, <Boolean-expression>) |
| pragma Precondition (<Boolean-expression>, <string-expression>) |
| pragma Postcondition (<Boolean-expression>, <string-expression>) |
| @end example |
| |
| The aspects have the form: |
| |
| @example |
| with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate] |
| => <Boolean-expression>; |
| @end example |
| |
| The @cite{Assert} pragma causes @cite{Boolean-expression} to be tested. |
| If the result is @cite{True}, the pragma has no effect (other than |
| possible side effects from evaluating the expression). If the result is |
| @cite{False}, the exception @cite{Assert_Failure} declared in the package |
| @cite{System.Assertions} is raised (passing @cite{static-string-expression}, if |
| present, as the message associated with the exception). If no string |
| expression is given, the default is a string containing the file name and |
| line number of the pragma. |
| |
| The @cite{Debug} pragma causes @cite{procedure} to be called. Note that |
| @cite{pragma Debug} may appear within a declaration sequence, allowing |
| debugging procedures to be called between declarations. |
| |
| For the aspect specification, the @cite{<Boolean-expression>} is evaluated. |
| If the result is @cite{True}, the aspect has no effect. If the result |
| is @cite{False}, the exception @cite{Assert_Failure} is raised. |
| @end table |
| |
| @node Validity Checking,Style Checking,Debugging and Assertion Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat validity-checking}@anchor{fe}@anchor{gnat_ugn/building_executable_programs_with_gnat id17}@anchor{10a} |
| @subsection Validity Checking |
| |
| |
| @geindex Validity Checking |
| |
| The Ada Reference Manual defines the concept of invalid values (see |
| RM 13.9.1). The primary source of invalid values is uninitialized |
| variables. A scalar variable that is left uninitialized may contain |
| an invalid value; the concept of invalid does not apply to access or |
| composite types. |
| |
| It is an error to read an invalid value, but the RM does not require |
| run-time checks to detect such errors, except for some minimal |
| checking to prevent erroneous execution (i.e. unpredictable |
| behavior). This corresponds to the @emph{-gnatVd} switch below, |
| which is the default. For example, by default, if the expression of a |
| case statement is invalid, it will raise Constraint_Error rather than |
| causing a wild jump, and if an array index on the left-hand side of an |
| assignment is invalid, it will raise Constraint_Error rather than |
| overwriting an arbitrary memory location. |
| |
| The @emph{-gnatVa} may be used to enable additional validity checks, |
| which are not required by the RM. These checks are often very |
| expensive (which is why the RM does not require them). These checks |
| are useful in tracking down uninitialized variables, but they are |
| not usually recommended for production builds, and in particular |
| we do not recommend using these extra validity checking options in |
| combination with optimization, since this can confuse the optimizer. |
| If performance is a consideration, leading to the need to optimize, |
| then the validity checking options should not be used. |
| |
| The other @emph{-gnatV}@code{x} switches below allow finer-grained |
| control; you can enable whichever validity checks you desire. However, |
| for most debugging purposes, @emph{-gnatVa} is sufficient, and the |
| default @emph{-gnatVd} (i.e. standard Ada behavior) is usually |
| sufficient for non-debugging use. |
| |
| The @emph{-gnatB} switch tells the compiler to assume that all |
| values are valid (that is, within their declared subtype range) |
| except in the context of a use of the Valid attribute. This means |
| the compiler can generate more efficient code, since the range |
| of values is better known at compile time. However, an uninitialized |
| variable can cause wild jumps and memory corruption in this mode. |
| |
| The @emph{-gnatV}@code{x} switch allows control over the validity |
| checking mode as described below. |
| The @code{x} argument is a string of letters that |
| indicate validity checks that are performed or not performed in addition |
| to the default checks required by Ada as described above. |
| |
| @geindex -gnatVa (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVa} |
| |
| @emph{All validity checks.} |
| |
| All validity checks are turned on. |
| That is, @emph{-gnatVa} is |
| equivalent to @emph{gnatVcdfimorst}. |
| @end table |
| |
| @geindex -gnatVc (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVc} |
| |
| @emph{Validity checks for copies.} |
| |
| The right hand side of assignments, and the initializing values of |
| object declarations are validity checked. |
| @end table |
| |
| @geindex -gnatVd (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVd} |
| |
| @emph{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 @emph{-gnatVD}. |
| They are turned on by default. If @emph{-gnatVD} is specified, a subsequent |
| switch @emph{-gnatVd} will leave the checks turned on. |
| Switch @emph{-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. |
| @end table |
| |
| @geindex -gnatVe (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVe} |
| |
| @emph{Validity checks for elementary components.} |
| |
| In the absence of this switch, assignments to record or array components are |
| not validity checked, even if validity checks for assignments generally |
| (@emph{-gnatVc}) are turned on. In Ada, assignment of composite values do not |
| require valid data, but assignment of individual components does. So for |
| example, there is a difference between copying the elements of an array with a |
| slice assignment, compared to assigning element by element in a loop. This |
| switch allows you to turn off validity checking for components, even when they |
| are assigned component by component. |
| @end table |
| |
| @geindex -gnatVf (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVf} |
| |
| @emph{Validity checks for floating-point values.} |
| |
| In the absence of this switch, validity checking occurs only for discrete |
| values. If @emph{-gnatVf} is specified, then validity checking also applies |
| for floating-point values, and NaNs 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, @emph{-gnatVif} or @emph{-gnatVfi} |
| (the order does not matter) specifies that floating-point parameters of mode |
| @cite{in} should be validity checked. |
| @end table |
| |
| @geindex -gnatVi (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVi} |
| |
| @emph{Validity checks for `in` mode parameters.} |
| |
| Arguments for parameters of mode @cite{in} are validity checked in function |
| and procedure calls at the point of call. |
| @end table |
| |
| @geindex -gnatVm (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVm} |
| |
| @emph{Validity checks for `in out` mode parameters.} |
| |
| Arguments for parameters of mode @cite{in out} are validity checked in |
| procedure calls at the point of call. The @cite{'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 @cite{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. |
| @end table |
| |
| @geindex -gnatVn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVn} |
| |
| @emph{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 @emph{-gnatp} suppresses all run-time checks, including |
| validity checks, and thus implies @emph{-gnatVn}. When this switch |
| is used, it cancels any other @emph{-gnatV} previously issued. |
| @end table |
| |
| @geindex -gnatVo (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVo} |
| |
| @emph{Validity checks for operator and attribute operands.} |
| |
| Arguments for predefined operators and attributes are validity checked. |
| This includes all operators in package @cite{Standard}, |
| the shift operators defined as intrinsic in package @cite{Interfaces} |
| and operands for attributes such as @cite{Pos}. Checks are also made |
| on individual component values for composite comparisons, and on the |
| expressions in type conversions and qualified expressions. Checks are |
| also made on explicit ranges using @code{..} (e.g., slices, loops etc). |
| @end table |
| |
| @geindex -gnatVp (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVp} |
| |
| @emph{Validity checks for parameters.} |
| |
| This controls the treatment of parameters within a subprogram (as opposed |
| to @emph{-gnatVi} and @emph{-gnatVm} which control validity testing |
| of parameters on a call. If either of these call options is used, then |
| normally an assumption is made within a subprogram that the input arguments |
| have been validity checking at the point of call, and do not need checking |
| again within a subprogram). If @emph{-gnatVp} is set, then this assumption |
| is not made, and parameters are not assumed to be valid, so their validity |
| will be checked (or rechecked) within the subprogram. |
| @end table |
| |
| @geindex -gnatVr (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVr} |
| |
| @emph{Validity checks for function returns.} |
| |
| The expression in @cite{return} statements in functions is validity |
| checked. |
| @end table |
| |
| @geindex -gnatVs (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVs} |
| |
| @emph{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). |
| @end table |
| |
| @geindex -gnatVt (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatVt} |
| |
| @emph{Validity checks for tests.} |
| |
| Expressions used as conditions in @cite{if}, @cite{while} or @cite{exit} |
| statements are checked, as well as guard expressions in entry calls. |
| @end table |
| |
| The @emph{-gnatV} switch may be followed by a string of letters |
| to turn on a series of validity checking options. |
| For example, @code{-gnatVcr} |
| specifies that in addition to the default validity checking, copies and |
| function return expressions are to be validity checked. |
| In order to make it easier to specify the desired combination of effects, |
| the upper case letters @cite{CDFIMORST} may |
| be used to turn off the corresponding lower case option. |
| Thus @code{-gnatVaM} turns on all validity checking options except for |
| checking of @cite{**in out**} procedure arguments. |
| |
| The specification of additional validity checking generates extra code (and |
| in the case of @emph{-gnatVa} the code expansion can be substantial). |
| However, these additional checks can be very useful in detecting |
| uninitialized variables, incorrect use of unchecked conversion, and other |
| errors leading to invalid values. The use of pragma @cite{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 @cite{Validity_Checks} which allows modification of |
| the validity checking mode at the program source level, and also allows for |
| temporary disabling of validity checks. |
| |
| @node Style Checking,Run-Time Checks,Validity Checking,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id18}@anchor{10b}@anchor{gnat_ugn/building_executable_programs_with_gnat style-checking}@anchor{103} |
| @subsection Style Checking |
| |
| |
| @geindex Style checking |
| |
| @geindex -gnaty (gcc) |
| |
| The @emph{-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 message is given, preceded by |
| the character sequence '(style)'. This message does not prevent |
| successful compilation (unless the @emph{-gnatwe} switch is used). |
| |
| Note that this is by no means intended to be a general facility for |
| checking arbitrary coding standards. It is simply an embedding of the |
| style rules we have chosen for the GNAT sources. If you are starting |
| a project which does not have established style standards, you may |
| find it useful to adopt the entire set of GNAT coding standards, or |
| some subset of them. |
| |
| |
| The string @cite{x} is a sequence of letters or digits |
| indicating the particular style |
| checks to be performed. The following checks are defined: |
| |
| @geindex -gnaty[0-9] (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnaty0} |
| |
| @emph{Specify indentation level.} |
| |
| If a digit from 1-9 appears |
| in the string after @emph{-gnaty} |
| then proper indentation is checked, with the digit indicating the |
| indentation level required. A value of zero turns off this style check. |
| 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 @cite{--} starting on a column that is a multiple of |
| the alignment level, or they may be aligned the same way as the following |
| non-blank line (this is useful when full line comments appear in the middle |
| of a statement, or they may be aligned with the source line on the previous |
| non-blank line. |
| @end table |
| |
| @geindex -gnatya (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatya} |
| |
| @emph{Check attribute casing.} |
| |
| Attribute names, including the case of keywords such as @cite{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. |
| @end table |
| |
| @geindex -gnatyA (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyA} |
| |
| @emph{Use of array index numbers in array attributes.} |
| |
| When using the array attributes First, Last, Range, |
| or Length, the index number must be omitted for one-dimensional arrays |
| and is required for multi-dimensional arrays. |
| @end table |
| |
| @geindex -gnatyb (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyb} |
| |
| @emph{Blanks not allowed at statement end.} |
| |
| 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. |
| @end table |
| |
| @geindex -gnatyB (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyB} |
| |
| @emph{Check Boolean operators.} |
| |
| The use of AND/OR operators is not permitted except in the cases of modular |
| operands, array operands, and simple stand-alone boolean variables or |
| boolean constants. In all other cases @cite{and then}/@cite{or else} are |
| required. |
| @end table |
| |
| @geindex -gnatyc (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyc} |
| |
| @emph{Check comments, double space.} |
| |
| Comments must meet the following set of rules: |
| |
| |
| @itemize * |
| |
| @item |
| The '@cite{--}' that starts the column must either start in column one, |
| or else at least one blank must precede this sequence. |
| |
| @item |
| Comments that follow other tokens on a line must have at least one blank |
| following the '@cite{--}' at the start of the comment. |
| |
| @item |
| Full line comments must have at least two blanks following the |
| '@cite{--}' that starts the comment, with the following exceptions. |
| |
| @item |
| A line consisting only of the '@cite{--}' characters, possibly preceded |
| by blanks is permitted. |
| |
| @item |
| A comment starting with '@cite{--x}' where @cite{x} is a special character |
| is permitted. |
| This allows proper processing of the output generated by specialized tools |
| including @emph{gnatprep} (where '@cite{--!}' is used) and the SPARK |
| annotation |
| language (where '@cite{--#}' is used). For the purposes of this rule, a |
| special character is defined as being in one of the ASCII ranges |
| @cite{16#21#...16#2F#} or @cite{16#3A#...16#3F#}. |
| Note that this usage is not permitted |
| in GNAT implementation units (i.e., when @emph{-gnatg} is used). |
| |
| @item |
| 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. |
| |
| @item |
| A comment that starts and ends with '@cite{--}' is permitted as long as at |
| least one blank follows the initial '@cite{--}'. Together with the preceding |
| rule, this allows the construction of box comments, as shown in the following |
| example: |
| |
| @example |
| --------------------------- |
| -- This is a box comment -- |
| -- with two text lines. -- |
| --------------------------- |
| @end example |
| @end itemize |
| @end table |
| |
| @geindex -gnatyC (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyC} |
| |
| @emph{Check comments, single space.} |
| |
| This is identical to @cite{c} except that only one space |
| is required following the @cite{--} of a comment instead of two. |
| @end table |
| |
| @geindex -gnatyd (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyd} |
| |
| @emph{Check no DOS line terminators present.} |
| |
| All lines must be terminated by a single ASCII.LF |
| character (in particular the DOS line terminator sequence CR/LF is not |
| allowed). |
| @end table |
| |
| @geindex -gnatye (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatye} |
| |
| @emph{Check end/exit labels.} |
| |
| Optional labels on @cite{end} statements ending subprograms and on |
| @cite{exit} statements exiting named loops, are required to be present. |
| @end table |
| |
| @geindex -gnatyf (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyf} |
| |
| @emph{No form feeds or vertical tabs.} |
| |
| Neither form feeds nor vertical tab characters are permitted |
| in the source text. |
| @end table |
| |
| @geindex -gnatyg (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyg} |
| |
| @emph{GNAT style mode.} |
| |
| The set of style check switches is set to match that used by the GNAT sources. |
| This may be useful when developing code that is eventually intended to be |
| incorporated into GNAT. Currently this is equivalent to @emph{-gnatwydISux}) |
| but additional style switches may be added to this set in the future without |
| advance notice. |
| @end table |
| |
| @geindex -gnatyh (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyh} |
| |
| @emph{No horizontal tabs.} |
| |
| 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. |
| @end table |
| |
| @geindex -gnatyi (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyi} |
| |
| @emph{Check if-then layout.} |
| |
| The keyword @cite{then} must appear either on the same |
| line as corresponding @cite{if}, or on a line on its own, lined |
| up under the @cite{if}. |
| @end table |
| |
| @geindex -gnatyI (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyI} |
| |
| @emph{check mode IN keywords.} |
| |
| Mode @cite{in} (the default mode) is not |
| allowed to be given explicitly. @cite{in out} is fine, |
| but not @cite{in} on its own. |
| @end table |
| |
| @geindex -gnatyk (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyk} |
| |
| @emph{Check keyword casing.} |
| |
| All keywords must be in lower case (with the exception of keywords |
| such as @cite{digits} used as attribute names to which this check |
| does not apply). |
| @end table |
| |
| @geindex -gnatyl (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyl} |
| |
| @emph{Check layout.} |
| |
| 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 @cite{else} keyword must |
| be lined up with the corresponding @cite{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 |
| @cite{record} keyword on the same line as the @cite{type} keyword, and |
| then the @cite{end} in @cite{end record} must line up under @cite{type}. |
| This is also permitted when the type declaration is split on two lines. |
| For example, any of the following three layouts is acceptable: |
| |
| @example |
| type q is record |
| a : integer; |
| b : integer; |
| end record; |
| |
| type q is |
| record |
| a : integer; |
| b : integer; |
| end record; |
| |
| type q is |
| record |
| a : integer; |
| b : integer; |
| end record; |
| @end example |
| |
| Second, in the case of a block statement, a permitted alternative |
| is to put the block label on the same line as the @cite{declare} or |
| @cite{begin} keyword, and then line the @cite{end} keyword up under |
| the block label. For example both the following are permitted: |
| |
| @example |
| Block : declare |
| A : Integer := 3; |
| begin |
| Proc (A, A); |
| end Block; |
| |
| Block : |
| declare |
| A : Integer := 3; |
| begin |
| Proc (A, A); |
| end Block; |
| @end example |
| |
| The same alternative format is allowed for loops. For example, both of |
| the following are permitted: |
| |
| @example |
| Clear : while J < 10 loop |
| A (J) := 0; |
| end loop Clear; |
| |
| Clear : |
| while J < 10 loop |
| A (J) := 0; |
| end loop Clear; |
| @end example |
| @end table |
| |
| @geindex -gnatyLnnn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyL} |
| |
| @emph{Set maximum nesting level.} |
| |
| The maximum level of nesting of constructs (including subprograms, loops, |
| blocks, packages, and conditionals) may not exceed the given value |
| @emph{nnn}. A value of zero disconnects this style check. |
| @end table |
| |
| @geindex -gnatym (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatym} |
| |
| @emph{Check maximum line length.} |
| |
| 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. Note that this count is of |
| characters in the source text. This means that a tab character counts |
| as one character in this count and a wide character sequence counts as |
| a single character (however many bytes are needed in the encoding). |
| @end table |
| |
| @geindex -gnatyMnnn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyM} |
| |
| @emph{Set maximum line length.} |
| |
| The length of lines must not exceed the |
| given value @emph{nnn}. The maximum value that can be specified is 32767. |
| If neither style option for setting the line length is used, then the |
| default is 255. This also controls the maximum length of lexical elements, |
| where the only restriction is that they must fit on a single line. |
| @end table |
| |
| @geindex -gnatyn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyn} |
| |
| @emph{Check casing of entities in Standard.} |
| |
| Any identifier from Standard must be cased |
| to match the presentation in the Ada Reference Manual (for example, |
| @cite{Integer} and @cite{ASCII.NUL}). |
| @end table |
| |
| @geindex -gnatyN (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyN} |
| |
| @emph{Turn off all style checks.} |
| |
| All style check options are turned off. |
| @end table |
| |
| @geindex -gnatyo (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyo} |
| |
| @emph{Check order of subprogram bodies.} |
| |
| 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). |
| @end table |
| |
| @geindex -gnatyO (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyO} |
| |
| @emph{Check that overriding subprograms are explicitly marked as such.} |
| |
| This applies to all subprograms of a derived type that override a primitive |
| operation of the type, for both tagged and untagged types. In particular, |
| the declaration of a primitive operation of a type extension that overrides |
| an inherited operation must carry an overriding indicator. Another case is |
| the declaration of a function that overrides a predefined operator (such |
| as an equality operator). |
| @end table |
| |
| @geindex -gnatyp (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyp} |
| |
| @emph{Check pragma casing.} |
| |
| 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. An exception is that SPARK_Mode is |
| allowed as an alternative for Spark_Mode. |
| @end table |
| |
| @geindex -gnatyr (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyr} |
| |
| @emph{Check references.} |
| |
| 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. |
| @end table |
| |
| @geindex -gnatys (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatys} |
| |
| @emph{Check separate specs.} |
| |
| 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. |
| @end table |
| |
| @geindex -gnatyS (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyS} |
| |
| @emph{Check no statements after then/else.} |
| |
| No statements are allowed |
| on the same line as a @cite{then} or @cite{else} keyword following the |
| keyword in an @cite{if} statement. @cite{or else} and @cite{and then} are not |
| affected, and a special exception allows a pragma to appear after @cite{else}. |
| @end table |
| |
| @geindex -gnatyt (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyt} |
| |
| @emph{Check token spacing.} |
| |
| The following token spacing rules are enforced: |
| |
| |
| @itemize * |
| |
| @item |
| The keywords @cite{abs} and @cite{not} must be followed by a space. |
| |
| @item |
| The token @cite{=>} must be surrounded by spaces. |
| |
| @item |
| The token @cite{<>} must be preceded by a space or a left parenthesis. |
| |
| @item |
| Binary operators other than @cite{**} must be surrounded by spaces. |
| There is no restriction on the layout of the @cite{**} binary operator. |
| |
| @item |
| Colon must be surrounded by spaces. |
| |
| @item |
| Colon-equal (assignment, initialization) must be surrounded by spaces. |
| |
| @item |
| 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. |
| |
| @item |
| If the token preceding a left parenthesis ends with a letter or digit, then |
| a space must separate the two tokens. |
| |
| @item |
| If the token following a right parenthesis starts with a letter or digit, then |
| a space must separate the two tokens. |
| |
| @item |
| A right parenthesis must either be the first non-blank character on |
| a line, or it must be preceded by a non-blank character. |
| |
| @item |
| A semicolon must not be preceded by a space, and must not be followed by |
| a non-blank character. |
| |
| @item |
| A unary plus or minus may not be followed by a space. |
| |
| @item |
| A vertical bar must be surrounded by spaces. |
| @end itemize |
| |
| Exactly one blank (and no other white space) must appear between |
| a @cite{not} token and a following @cite{in} token. |
| @end table |
| |
| @geindex -gnatyu (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyu} |
| |
| @emph{Check unnecessary blank lines.} |
| |
| Unnecessary blank lines are not allowed. A blank line is considered |
| unnecessary if it appears at the end of the file, or if more than |
| one blank line occurs in sequence. |
| @end table |
| |
| @geindex -gnatyx (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyx} |
| |
| @emph{Check extra parentheses.} |
| |
| Unnecessary extra level of parentheses (C-style) are not allowed |
| around conditions in @cite{if} statements, @cite{while} statements and |
| @cite{exit} statements. |
| @end table |
| |
| @geindex -gnatyy (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatyy} |
| |
| @emph{Set all standard style check options.} |
| |
| This is equivalent to @cite{gnaty3aAbcefhiklmnprst}, that is all checking |
| options enabled with the exception of @emph{-gnatyB}, @emph{-gnatyd}, |
| @emph{-gnatyI}, @emph{-gnatyLnnn}, @emph{-gnatyo}, @emph{-gnatyO}, |
| @emph{-gnatyS}, @emph{-gnatyu}, and @emph{-gnatyx}. |
| @end table |
| |
| @geindex -gnaty- (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnaty-} |
| |
| @emph{Remove style check options.} |
| |
| This causes any subsequent options in the string to act as canceling the |
| corresponding style check option. To cancel maximum nesting level control, |
| use @emph{L} parameter witout any integer value after that, because any |
| digit following @emph{-} in the parameter string of the @emph{-gnaty} |
| option will be threated as canceling indentation check. The same is true |
| for @emph{M} parameter. @emph{y} and @emph{N} parameters are not |
| allowed after @emph{-}. |
| @end table |
| |
| @geindex -gnaty+ (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnaty+} |
| |
| @emph{Enable style check options.} |
| |
| This causes any subsequent options in the string to enable the corresponding |
| style check option. That is, it cancels the effect of a previous -, |
| if any. |
| @end table |
| |
| @c end of switch description (leave this comment to ease automatic parsing for |
| |
| @c GPS |
| |
| 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 '@cite{(style)}'. Note that these messages are treated as warning |
| messages, so they normally do not prevent the generation of an object |
| file. The @emph{-gnatwe} switch can be used to treat warning messages, |
| including style messages, as fatal errors. |
| |
| The switch @code{-gnaty} on its own (that is not |
| followed by any letters or digits) is equivalent |
| to the use of @emph{-gnatyy} as described above, that is all |
| built-in standard style check options are enabled. |
| |
| The switch @code{-gnatyN} clears any previously set style checks. |
| |
| @node Run-Time Checks,Using gcc for Syntax Checking,Style Checking,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat run-time-checks}@anchor{101}@anchor{gnat_ugn/building_executable_programs_with_gnat id19}@anchor{10c} |
| @subsection Run-Time Checks |
| |
| |
| @geindex Division by zero |
| |
| @geindex Access before elaboration |
| |
| @geindex Checks |
| @geindex division by zero |
| |
| @geindex Checks |
| @geindex access before elaboration |
| |
| @geindex Checks |
| @geindex stack overflow checking |
| |
| By default, the following checks are suppressed: stack overflow |
| checks, and checks for access before elaboration on subprogram |
| calls. All other checks, including overflow checks, range checks and |
| array bounds checks, are turned on by default. The following @emph{gcc} |
| switches refine this default behavior. |
| |
| @geindex -gnatp (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatp} |
| |
| @geindex Suppressing checks |
| |
| @geindex Checks |
| @geindex suppressing |
| |
| This switch causes the unit to be compiled |
| as though @cite{pragma Suppress (All_checks)} |
| had been present in the source. Validity checks are also eliminated (in |
| other words @emph{-gnatp} also implies @emph{-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. |
| |
| Note that when checks are suppressed, the compiler is allowed, but not |
| required, to omit the checking code. If the run-time cost of the |
| checking code is zero or near-zero, the compiler will generate it even |
| if checks are suppressed. In particular, if the compiler can prove |
| that a certain check will necessarily fail, it will generate code to |
| do an unconditional 'raise', even if checks are suppressed. The |
| compiler warns in this case. Another case in which checks may not be |
| eliminated is when they are embedded in certain run time routines such |
| as math library routines. |
| |
| Of course, run-time checks are omitted whenever the compiler can prove |
| that they will not fail, whether or not checks are suppressed. |
| |
| Note that if you suppress a check that would have failed, program |
| execution is erroneous, which means the behavior is totally |
| unpredictable. The program might crash, or print wrong answers, or |
| do anything else. It might even do exactly what you wanted it to do |
| (and then it might start failing mysteriously next week or next |
| year). The compiler will generate code based on the assumption that |
| the condition being checked is true, which can result in erroneous |
| execution if that assumption is wrong. |
| |
| The checks subject to suppression include all the checks defined by the Ada |
| standard, the additional implementation defined checks @cite{Alignment_Check}, |
| @cite{Duplicated_Tag_Check}, @cite{Predicate_Check}, Container_Checks, Tampering_Check, |
| and @cite{Validity_Check}, as well as any checks introduced using @cite{pragma Check_Name}. Note that @cite{Atomic_Synchronization} is not automatically |
| suppressed by use of this option. |
| |
| If the code depends on certain checks being active, you can use |
| pragma @cite{Unsuppress} either as a configuration pragma or as |
| a local pragma to make sure that a specified check is performed |
| even if @emph{gnatp} is specified. |
| |
| The @emph{-gnatp} switch has no effect if a subsequent |
| @emph{-gnat-p} switch appears. |
| @end table |
| |
| @geindex -gnat-p (gcc) |
| |
| @geindex Suppressing checks |
| |
| @geindex Checks |
| @geindex suppressing |
| |
| @geindex Suppress |
| |
| |
| @table @asis |
| |
| @item @code{-gnat-p} |
| |
| This switch cancels the effect of a previous @emph{gnatp} switch. |
| @end table |
| |
| @geindex -gnato?? (gcc) |
| |
| @geindex Overflow checks |
| |
| @geindex Overflow mode |
| |
| @geindex Check |
| @geindex overflow |
| |
| |
| @table @asis |
| |
| @item @code{-gnato??} |
| |
| This switch controls the mode used for computing intermediate |
| arithmetic integer operations, and also enables overflow checking. |
| For a full description of overflow mode and checking control, see |
| the 'Overflow Check Handling in GNAT' appendix in this |
| User's Guide. |
| |
| Overflow checks are always enabled by this switch. The argument |
| controls the mode, using the codes |
| |
| |
| @table @asis |
| |
| @item @emph{1 = STRICT} |
| |
| In STRICT mode, intermediate operations are always done using the |
| base type, and overflow checking ensures that the result is within |
| the base type range. |
| |
| @item @emph{2 = MINIMIZED} |
| |
| In MINIMIZED mode, overflows in intermediate operations are avoided |
| where possible by using a larger integer type for the computation |
| (typically @cite{Long_Long_Integer}). Overflow checking ensures that |
| the result fits in this larger integer type. |
| |
| @item @emph{3 = ELIMINATED} |
| |
| In ELIMINATED mode, overflows in intermediate operations are avoided |
| by using multi-precision arithmetic. In this case, overflow checking |
| has no effect on intermediate operations (since overflow is impossible). |
| @end table |
| |
| If two digits are present after @emph{-gnato} then the first digit |
| sets the mode for expressions outside assertions, and the second digit |
| sets the mode for expressions within assertions. Here assertions is used |
| in the technical sense (which includes for example precondition and |
| postcondition expressions). |
| |
| If one digit is present, the corresponding mode is applicable to both |
| expressions within and outside assertion expressions. |
| |
| If no digits are present, the default is to enable overflow checks |
| and set STRICT mode for both kinds of expressions. This is compatible |
| with the use of @emph{-gnato} in previous versions of GNAT. |
| |
| @geindex Machine_Overflows |
| |
| Note that the @emph{-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 @cite{Machine_Overflows} |
| attribute set to @cite{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, unlike |
| for example the failure of a range check, can result in an incorrect |
| value, but cannot cause random memory destruction (like an out of range |
| subscript), or a wild jump (from an out of range case value). Overflow |
| checking is also quite expensive in time and space, since in general it |
| requires the use of double length arithmetic. |
| |
| Note again that the default is @emph{-gnato11} (equivalent to @emph{-gnato1}), |
| so overflow checking is performed in STRICT mode by default. |
| @end table |
| |
| @geindex -gnatE (gcc) |
| |
| @geindex Elaboration checks |
| |
| @geindex Check |
| @geindex elaboration |
| |
| |
| @table @asis |
| |
| @item @code{-gnatE} |
| |
| Enables dynamic checks for access-before-elaboration |
| on subprogram calls and generic instantiations. |
| Note that @emph{-gnatE} is not necessary for safety, because in the |
| default mode, GNAT ensures statically that the checks would not fail. |
| For full details of the effect and use of this switch, |
| @ref{1e,,Compiling with gcc}. |
| @end table |
| |
| @geindex -fstack-check (gcc) |
| |
| @geindex Stack Overflow Checking |
| |
| @geindex Checks |
| @geindex stack overflow checking |
| |
| |
| @table @asis |
| |
| @item @code{-fstack-check} |
| |
| Activates stack overflow checking. For full details of the effect and use of |
| this switch see @ref{fc,,Stack Overflow Checking}. |
| @end table |
| |
| @geindex Unsuppress |
| |
| The setting of these switches only controls the default setting of the |
| checks. You may modify them using either @cite{Suppress} (to remove |
| checks) or @cite{Unsuppress} (to add back suppressed checks) pragmas in |
| the program source. |
| |
| @node Using gcc for Syntax Checking,Using gcc for Semantic Checking,Run-Time Checks,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id20}@anchor{10d}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{10e} |
| @subsection Using @emph{gcc} for Syntax Checking |
| |
| |
| @geindex -gnats (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnats} |
| |
| The @cite{s} stands for 'syntax'. |
| |
| Run GNAT in syntax checking only mode. For |
| example, the command |
| |
| @example |
| $ gcc -c -gnats x.adb |
| @end example |
| |
| compiles file @code{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 @emph{-c} (compile |
| only) flag in addition to the @emph{-gnats} flag. |
| |
| You may use other switches in conjunction with @emph{-gnats}. In |
| particular, @emph{-gnatl} and @emph{-gnatv} are useful to control the |
| format of any generated error messages. |
| |
| When the source file is empty or contains only empty lines and/or comments, |
| the output is a warning: |
| |
| @example |
| $ gcc -c -gnats -x ada toto.txt |
| toto.txt:1:01: warning: empty file, contains no compilation units |
| $ |
| @end example |
| |
| Otherwise, 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 @cite{X} |
| @emph{with}s a unit @cite{Y}, compiling unit @cite{X} in syntax |
| check only mode does not access the source file containing unit |
| @cite{Y}. |
| |
| @geindex Multiple units |
| @geindex syntax checking |
| |
| 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 @cite{gnatchop} utility |
| (@ref{38,,Renaming Files with gnatchop}). |
| @end table |
| |
| @node Using gcc for Semantic Checking,Compiling Different Versions of Ada,Using gcc for Syntax Checking,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id21}@anchor{10f}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{110} |
| @subsection Using @emph{gcc} for Semantic Checking |
| |
| |
| @geindex -gnatc (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatc} |
| |
| The @cite{c} stands for 'check'. |
| Causes the compiler to operate in semantic check mode, |
| with full checking for all illegalities specified in the |
| Ada 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: |
| |
| |
| @itemize * |
| |
| @item |
| The needed source files must be accessible |
| (see @ref{8e,,Search Paths and the Run-Time Library (RTL)}). |
| |
| @item |
| Each file must contain only one compilation unit. |
| |
| @item |
| The file name and unit name must match (@ref{54,,File Naming Rules}). |
| @end itemize |
| |
| The output consists of error messages as appropriate. No object file is |
| generated. An @code{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 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). |
| @end table |
| |
| @node Compiling Different Versions of Ada,Character Set Control,Using gcc for Semantic Checking,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat compiling-different-versions-of-ada}@anchor{6}@anchor{gnat_ugn/building_executable_programs_with_gnat id22}@anchor{111} |
| @subsection Compiling Different Versions of Ada |
| |
| |
| The switches described in this section allow you to explicitly specify |
| the version of the Ada language that your programs are written in. |
| The default mode is Ada 2012, |
| but you can also specify Ada 95, Ada 2005 mode, or |
| indicate Ada 83 compatibility mode. |
| |
| @geindex Compatibility with Ada 83 |
| |
| @geindex -gnat83 (gcc) |
| |
| @geindex ACVC |
| @geindex Ada 83 tests |
| |
| @geindex Ada 83 mode |
| |
| |
| @table @asis |
| |
| @item @code{-gnat83} (Ada 83 Compatibility Mode) |
| |
| Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch |
| specifies that the program is to be compiled in Ada 83 mode. With |
| @emph{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83 |
| semantics where this can be done easily. |
| It is not possible to guarantee this switch does a perfect |
| job; some subtle tests, such as are |
| found in earlier ACVC tests (and that have been removed from the ACATS suite |
| for Ada 95), might not compile correctly. |
| Nevertheless, this switch may be useful in some circumstances, for example |
| where, due to contractual reasons, existing code needs to be maintained |
| using only Ada 83 features. |
| |
| With few exceptions (most notably the need to use @cite{<>} on |
| unconstrained |
| @geindex Generic formal parameters |
| generic formal parameters, |
| the use of the new Ada 95 / Ada 2005 |
| reserved words, and the use of packages |
| with optional bodies), it is not necessary to specify the |
| @emph{-gnat83} switch when compiling Ada 83 programs, because, with rare |
| exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus |
| a correct Ada 83 program is usually also a correct program |
| in these later versions of the language standard. For further information |
| please refer to the @cite{Compatibility_and_Porting_Guide} chapter in the |
| @cite{GNAT Reference Manual}. |
| @end table |
| |
| @geindex -gnat95 (gcc) |
| |
| @geindex Ada 95 mode |
| |
| |
| @table @asis |
| |
| @item @code{-gnat95} (Ada 95 mode) |
| |
| This switch directs the compiler to implement the Ada 95 version of the |
| language. |
| Since Ada 95 is almost completely upwards |
| compatible with Ada 83, Ada 83 programs may generally be compiled using |
| this switch (see the description of the @emph{-gnat83} switch for further |
| information about Ada 83 mode). |
| If an Ada 2005 program is compiled in Ada 95 mode, |
| uses of the new Ada 2005 features will cause error |
| messages or warnings. |
| |
| This switch also can be used to cancel the effect of a previous |
| @emph{-gnat83}, @emph{-gnat05/2005}, or @emph{-gnat12/2012} |
| switch earlier in the command line. |
| @end table |
| |
| @geindex -gnat05 (gcc) |
| |
| @geindex -gnat2005 (gcc) |
| |
| @geindex Ada 2005 mode |
| |
| |
| @table @asis |
| |
| @item @code{-gnat05} or @code{-gnat2005} (Ada 2005 mode) |
| |
| This switch directs the compiler to implement the Ada 2005 version of the |
| language, as documented in the official Ada standards document. |
| Since Ada 2005 is almost completely upwards |
| compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs |
| may generally be compiled using this switch (see the description of the |
| @emph{-gnat83} and @emph{-gnat95} switches for further |
| information). |
| @end table |
| |
| @geindex -gnat12 (gcc) |
| |
| @geindex -gnat2012 (gcc) |
| |
| @geindex Ada 2012 mode |
| |
| |
| @table @asis |
| |
| @item @code{-gnat12} or @code{-gnat2012} (Ada 2012 mode) |
| |
| This switch directs the compiler to implement the Ada 2012 version of the |
| language (also the default). |
| Since Ada 2012 is almost completely upwards |
| compatible with Ada 2005 (and thus also with Ada 83, and Ada 95), |
| Ada 83 and Ada 95 programs |
| may generally be compiled using this switch (see the description of the |
| @emph{-gnat83}, @emph{-gnat95}, and @emph{-gnat05/2005} switches |
| for further information). |
| @end table |
| |
| @geindex -gnatX (gcc) |
| |
| @geindex Ada language extensions |
| |
| @geindex GNAT extensions |
| |
| |
| @table @asis |
| |
| @item @code{-gnatX} (Enable GNAT Extensions) |
| |
| This switch directs the compiler to implement the latest version of the |
| language (currently Ada 2012) and also to enable certain GNAT implementation |
| extensions that are not part of any Ada standard. For a full list of these |
| extensions, see the GNAT reference manual. |
| @end table |
| |
| @node Character Set Control,File Naming Control,Compiling Different Versions of Ada,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id23}@anchor{112}@anchor{gnat_ugn/building_executable_programs_with_gnat character-set-control}@anchor{4a} |
| @subsection Character Set Control |
| |
| |
| @geindex -gnati (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnati@emph{c}} |
| |
| Normally GNAT recognizes the Latin-1 character set in source program |
| identifiers, as described in the Ada Reference Manual. |
| This switch causes |
| GNAT to recognize alternate character sets in identifiers. @cite{c} is a |
| single character indicating the character set, as follows: |
| |
| |
| @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| @emph{1} |
| |
| @tab |
| |
| ISO 8859-1 (Latin-1) identifiers |
| |
| @item |
| |
| @emph{2} |
| |
| @tab |
| |
| ISO 8859-2 (Latin-2) letters allowed in identifiers |
| |
| @item |
| |
| @emph{3} |
| |
| @tab |
| |
| ISO 8859-3 (Latin-3) letters allowed in identifiers |
| |
| @item |
| |
| @emph{4} |
| |
| @tab |
| |
| ISO 8859-4 (Latin-4) letters allowed in identifiers |
| |
| @item |
| |
| @emph{5} |
| |
| @tab |
| |
| ISO 8859-5 (Cyrillic) letters allowed in identifiers |
| |
| @item |
| |
| @emph{9} |
| |
| @tab |
| |
| ISO 8859-15 (Latin-9) letters allowed in identifiers |
| |
| @item |
| |
| @emph{p} |
| |
| @tab |
| |
| IBM PC letters (code page 437) allowed in identifiers |
| |
| @item |
| |
| @emph{8} |
| |
| @tab |
| |
| IBM PC letters (code page 850) allowed in identifiers |
| |
| @item |
| |
| @emph{f} |
| |
| @tab |
| |
| Full upper-half codes allowed in identifiers |
| |
| @item |
| |
| @emph{n} |
| |
| @tab |
| |
| No upper-half codes allowed in identifiers |
| |
| @item |
| |
| @emph{w} |
| |
| @tab |
| |
| Wide-character codes (that is, codes greater than 255) |
| allowed in identifiers |
| |
| @end multitable |
| |
| |
| See @ref{40,,Foreign Language Representation} for full details on the |
| implementation of these character sets. |
| @end table |
| |
| @geindex -gnatW (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatW@emph{e}} |
| |
| Specify the method of encoding for wide characters. |
| @cite{e} is one of the following: |
| |
| |
| @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| @emph{h} |
| |
| @tab |
| |
| Hex encoding (brackets coding also recognized) |
| |
| @item |
| |
| @emph{u} |
| |
| @tab |
| |
| Upper half encoding (brackets encoding also recognized) |
| |
| @item |
| |
| @emph{s} |
| |
| @tab |
| |
| Shift/JIS encoding (brackets encoding also recognized) |
| |
| @item |
| |
| @emph{e} |
| |
| @tab |
| |
| EUC encoding (brackets encoding also recognized) |
| |
| @item |
| |
| @emph{8} |
| |
| @tab |
| |
| UTF-8 encoding (brackets encoding also recognized) |
| |
| @item |
| |
| @emph{b} |
| |
| @tab |
| |
| Brackets encoding only (default value) |
| |
| @end multitable |
| |
| |
| For full details on these encoding |
| methods see @ref{50,,Wide_Character Encodings}. |
| Note that brackets coding is always accepted, even if one of the other |
| options is specified, so for example @emph{-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. |
| |
| Note that brackets encoding only applies to program text. Within comments, |
| brackets are considered to be normal graphic characters, and bracket sequences |
| are never recognized as wide characters. |
| |
| If no @emph{-gnatW?} parameter is present, then the default |
| representation is normally Brackets encoding only. However, if the |
| first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard |
| byte order mark or BOM for UTF-8), then these three characters are |
| skipped and the default representation for the file is set to UTF-8. |
| |
| 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. |
| @end table |
| |
| When no @emph{-gnatW?} is specified, then characters (other than wide |
| characters represented using brackets notation) are treated as 8-bit |
| Latin-1 codes. The codes recognized are the Latin-1 graphic characters, |
| and ASCII format effectors (CR, LF, HT, VT). Other lower half control |
| characters in the range 16#00#..16#1F# are not accepted in program text |
| or in comments. Upper half control characters (16#80#..16#9F#) are rejected |
| in program text, but allowed and ignored in comments. Note in particular |
| that the Next Line (NEL) character whose encoding is 16#85# is not recognized |
| as an end of line in this default mode. If your source program contains |
| instances of the NEL character used as a line terminator, |
| you must use UTF-8 encoding for the whole |
| source program. In default mode, all lines must be ended by a standard |
| end of line sequence (CR, CR/LF, or LF). |
| |
| Note that the convention of simply accepting all upper half characters in |
| comments means that programs that use standard ASCII for program text, but |
| UTF-8 encoding for comments are accepted in default mode, providing that the |
| comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator. |
| This is a common mode for many programs with foreign language comments. |
| |
| @node File Naming Control,Subprogram Inlining Control,Character Set Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat file-naming-control}@anchor{113}@anchor{gnat_ugn/building_executable_programs_with_gnat id24}@anchor{114} |
| @subsection File Naming Control |
| |
| |
| @geindex -gnatk (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatk@emph{n}} |
| |
| Activates file name 'krunching'. @cite{n}, a decimal integer in the range |
| 1-999, indicates the maximum allowable length of a file name (not |
| including the @code{.ads} or @code{.adb} extension). The default is not |
| to enable file name krunching. |
| |
| For the source file naming rules, @ref{54,,File Naming Rules}. |
| @end table |
| |
| @node Subprogram Inlining Control,Auxiliary Output Control,File Naming Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat subprogram-inlining-control}@anchor{115}@anchor{gnat_ugn/building_executable_programs_with_gnat id25}@anchor{116} |
| @subsection Subprogram Inlining Control |
| |
| |
| @geindex -gnatn (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatn[12]} |
| |
| The @cite{n} here is intended to suggest the first syllable of the |
| word 'inline'. |
| GNAT recognizes and processes @cite{Inline} pragmas. However, for the |
| inlining to actually occur, optimization must be enabled and, in order |
| to enable inlining of subprograms specified by pragma @cite{Inline}, |
| you must also specify this switch. |
| In the absence of this switch, GNAT does not attempt |
| inlining and does not need to access the bodies of |
| subprograms for which @cite{pragma Inline} is specified if they are not |
| in the current unit. |
| |
| You can optionally specify the inlining level: 1 for moderate inlining across |
| modules, which is a good compromise between compilation times and performances |
| at run time, or 2 for full inlining across modules, which may bring about |
| longer compilation times. If no inlining level is specified, the compiler will |
| pick it based on the optimization level: 1 for @emph{-O1}, @emph{-O2} or |
| @emph{-Os} and 2 for @emph{-O3}. |
| |
| 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 @ref{117,,Inlining of Subprograms}. |
| @end table |
| |
| @geindex -gnatN (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatN} |
| |
| This switch activates front-end inlining which also |
| generates additional dependencies. |
| |
| When using a gcc-based back end (in practice this means using any version |
| of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of |
| @emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred. |
| Historically front end inlining was more extensive than the gcc back end |
| inlining, but that is no longer the case. |
| @end table |
| |
| @node Auxiliary Output Control,Debugging Control,Subprogram Inlining Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat auxiliary-output-control}@anchor{118}@anchor{gnat_ugn/building_executable_programs_with_gnat id26}@anchor{119} |
| @subsection Auxiliary Output Control |
| |
| |
| @geindex -gnatt (gcc) |
| |
| @geindex Writing internal trees |
| |
| @geindex Internal trees |
| @geindex writing to file |
| |
| |
| @table @asis |
| |
| @item @code{-gnatt} |
| |
| Causes GNAT to write the internal tree for a unit to a file (with the |
| extension @code{.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. |
| Note that the combination of switches @emph{-gnatct} |
| generates a tree in the form required by ASIS applications. |
| @end table |
| |
| @geindex -gnatu (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatu} |
| |
| Print a list of units required by this compilation on @code{stdout}. |
| The listing includes all units on which the unit being compiled depends |
| either directly or indirectly. |
| @end table |
| |
| @geindex -pass-exit-codes (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-pass-exit-codes} |
| |
| If this switch is not used, the exit code returned by @emph{gcc} when |
| compiling multiple files indicates whether all source files have |
| been successfully used to generate object files or not. |
| |
| When @emph{-pass-exit-codes} is used, @emph{gcc} exits with an extended |
| exit status and allows an integrated development environment to better |
| react to a compilation failure. Those exit status are: |
| |
| |
| @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| @emph{5} |
| |
| @tab |
| |
| There was an error in at least one source file. |
| |
| @item |
| |
| @emph{3} |
| |
| @tab |
| |
| At least one source file did not generate an object file. |
| |
| @item |
| |
| @emph{2} |
| |
| @tab |
| |
| The compiler died unexpectedly (internal error for example). |
| |
| @item |
| |
| @emph{0} |
| |
| @tab |
| |
| An object file has been generated for every source file. |
| |
| @end multitable |
| |
| @end table |
| |
| @node Debugging Control,Exception Handling Control,Auxiliary Output Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat debugging-control}@anchor{11a}@anchor{gnat_ugn/building_executable_programs_with_gnat id27}@anchor{11b} |
| @subsection Debugging Control |
| |
| |
| @quotation |
| |
| @geindex Debugging options |
| @end quotation |
| |
| @geindex -gnatd (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatd@emph{x}} |
| |
| Activate internal debugging switches. @cite{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 @cite{Debug} unit in the compiler source |
| file @code{debug.adb}. |
| @end table |
| |
| @geindex -gnatG (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatG[=@emph{nn}]} |
| |
| 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 @emph{-gnatG} you can identify |
| these cases, and consider whether it may be desirable to modify the coding |
| approach to improve efficiency. |
| |
| The optional parameter @cite{nn} if present after -gnatG specifies an |
| alternative maximum line length that overrides the normal default of 72. |
| This value is in the range 40-999999, values less than 40 being silently |
| reset to 40. The equal sign is optional. |
| |
| 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 spec |
| of package @cite{Sprint} in file @code{sprint.ads} for a full list. |
| |
| @geindex -gnatL (gcc) |
| |
| If the switch @emph{-gnatL} is used in conjunction with |
| @emph{-gnatG}, then the original source lines are interspersed |
| in the expanded source (as comment lines with the original line number). |
| |
| |
| @table @asis |
| |
| @item @code{new @emph{xxx} [storage_pool = @emph{yyy}]} |
| |
| Shows the storage pool being used for an allocator. |
| |
| @item @code{at end @emph{procedure-name};} |
| |
| Shows the finalization (cleanup) procedure for a scope. |
| |
| @item @code{(if @emph{expr} then @emph{expr} else @emph{expr})} |
| |
| Conditional expression equivalent to the @cite{x?y:z} construction in C. |
| |
| @item @code{@emph{target}^(@emph{source})} |
| |
| A conversion with floating-point truncation instead of rounding. |
| |
| @item @code{@emph{target}?(@emph{source})} |
| |
| A conversion that bypasses normal Ada semantic checking. In particular |
| enumeration types and fixed-point types are treated simply as integers. |
| |
| @item @code{@emph{target}?^(@emph{source})} |
| |
| Combines the above two cases. |
| @end table |
| |
| @code{@emph{x} #/ @emph{y}} |
| |
| @code{@emph{x} #mod @emph{y}} |
| |
| @code{@emph{x} # @emph{y}} |
| |
| |
| @table @asis |
| |
| @item @code{@emph{x} #rem @emph{y}} |
| |
| A division or multiplication of fixed-point values which are treated as |
| integers without any kind of scaling. |
| |
| @item @code{free @emph{expr} [storage_pool = @emph{xxx}]} |
| |
| Shows the storage pool associated with a @cite{free} statement. |
| |
| @item @code{[subtype or type declaration]} |
| |
| Used to list an equivalent declaration for an internally generated |
| type that is referenced elsewhere in the listing. |
| |
| @item @code{freeze @emph{type-name} [@emph{actions}]} |
| |
| Shows the point at which @cite{type-name} is frozen, with possible |
| associated actions to be performed at the freeze point. |
| |
| @item @code{reference @emph{itype}} |
| |
| Reference (and hence definition) to internal type @cite{itype}. |
| |
| @item @code{@emph{function-name}! (@emph{arg}, @emph{arg}, @emph{arg})} |
| |
| Intrinsic function call. |
| |
| @item @code{@emph{label-name} : label} |
| |
| Declaration of label @cite{labelname}. |
| |
| @item @code{#$ @emph{subprogram-name}} |
| |
| An implicit call to a run-time support routine |
| (to meet the requirement of H.3.1(9) in a |
| convenient manner). |
| |
| @item @code{@emph{expr} && @emph{expr} && @emph{expr} ... && @emph{expr}} |
| |
| A multiple concatenation (same effect as @cite{expr} & @cite{expr} & |
| @cite{expr}, but handled more efficiently). |
| |
| @item @code{[constraint_error]} |
| |
| Raise the @cite{Constraint_Error} exception. |
| |
| @item @code{@emph{expression}'reference} |
| |
| A pointer to the result of evaluating @{expression@}. |
| |
| @item @code{@emph{target-type}!(@emph{source-expression})} |
| |
| An unchecked conversion of @cite{source-expression} to @cite{target-type}. |
| |
| @item @code{[@emph{numerator}/@emph{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). |
| @end table |
| @end table |
| |
| @geindex -gnatD (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatD[=nn]} |
| |
| When used in conjunction with @emph{-gnatG}, this switch causes |
| the expanded source, as described above for |
| @emph{-gnatG} to be written to files with names |
| @code{xxx.dg}, where @code{xxx} is the normal file name, |
| instead of to the standard output file. For |
| example, if the source file name is @code{hello.adb}, then a file |
| @code{hello.adb.dg} will be written. The debugging |
| information generated by the @emph{gcc} @emph{-g} switch |
| will refer to the generated @code{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 |
| @emph{-gnatx}) since otherwise the cross-reference information |
| would refer to the @code{.dg} file, which would cause |
| confusion since this is not the original source file. |
| |
| Note that @emph{-gnatD} actually implies @emph{-gnatG} |
| automatically, so it is not necessary to give both options. |
| In other words @emph{-gnatD} is equivalent to @emph{-gnatDG}). |
| |
| @geindex -gnatL (gcc) |
| |
| If the switch @emph{-gnatL} is used in conjunction with |
| @emph{-gnatDG}, then the original source lines are interspersed |
| in the expanded source (as comment lines with the original line number). |
| |
| The optional parameter @cite{nn} if present after -gnatD specifies an |
| alternative maximum line length that overrides the normal default of 72. |
| This value is in the range 40-999999, values less than 40 being silently |
| reset to 40. The equal sign is optional. |
| @end table |
| |
| @geindex -gnatr (gcc) |
| |
| @geindex pragma Restrictions |
| |
| |
| @table @asis |
| |
| @item @code{-gnatr} |
| |
| This switch causes pragma Restrictions to be treated as Restriction_Warnings |
| so that violation of restrictions causes warnings rather than illegalities. |
| This is useful during the development process when new restrictions are added |
| or investigated. The switch also causes pragma Profile to be treated as |
| Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set |
| restriction warnings rather than restrictions. |
| @end table |
| |
| @geindex -gnatR (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-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 |
| @emph{-gnatR0}, no information is output (equivalent to omitting |
| the @emph{-gnatR} switch). For @emph{-gnatR1} (which is the default, |
| so @emph{-gnatR} with no parameter has the same effect), size and alignment |
| information is listed for declared array and record types. For |
| @emph{-gnatR2}, size and alignment information is listed for all |
| declared types and objects. The @cite{Linker_Section} is also listed for any |
| entity for which the @cite{Linker_Section} is set explicitly or implicitly (the |
| latter case occurs for objects of a type for which a @cite{Linker_Section} |
| is set). |
| |
| Finally @emph{-gnatR3} includes symbolic |
| expressions 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 @code{repinfo.ads/adb} in the |
| @cite{GNAT} sources for full details on the format of @emph{-gnatR3} |
| output. If the switch is followed by an s (e.g., @emph{-gnatR2s}), then |
| the output is to a file with the name @code{file.rep} where |
| file is the name of the corresponding source file. |
| |
| @item @code{-gnatRm[s]} |
| |
| This form of the switch controls output of subprogram conventions |
| and parameter passing mechanisms for all subprograms. A following |
| @cite{s} means output to a file as described above. |
| |
| Note that it is possible for record components to have zero size. In |
| this case, the component clause uses an obvious extension of permitted |
| Ada syntax, for example @cite{at 0 range 0 .. -1}. |
| |
| Representation information requires that code be generated (since it is the |
| code generator that lays out complex data structures). If an attempt is made |
| to output representation information when no code is generated, for example |
| when a subunit is compiled on its own, then no information can be generated |
| and the compiler outputs a message to this effect. |
| @end table |
| |
| @geindex -gnatS (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatS} |
| |
| The use of the switch @emph{-gnatS} for an |
| Ada compilation will cause the compiler to output a |
| representation of package Standard in a form very |
| close to standard Ada. It is not quite possible to |
| do this entirely in standard Ada (since new |
| numeric base types cannot be created in standard |
| Ada), but the output is easily |
| readable to any Ada programmer, and is useful to |
| determine the characteristics of target dependent |
| types in package Standard. |
| @end table |
| |
| @geindex -gnatx (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatx} |
| |
| Normally the compiler generates full cross-referencing information in |
| the @code{ALI} file. This information is used by a number of tools, |
| including @cite{gnatfind} and @cite{gnatxref}. The @emph{-gnatx} switch |
| suppresses this information. This saves some space and may slightly |
| speed up compilation, but means that these tools cannot be used. |
| @end table |
| |
| @node Exception Handling Control,Units to Sources Mapping Files,Debugging Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id28}@anchor{11c}@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{11d} |
| @subsection Exception Handling Control |
| |
| |
| GNAT uses two methods for handling exceptions at run-time. The |
| @cite{setjmp/longjmp} method saves the context when entering |
| a frame with an exception handler. Then when an exception is |
| raised, the context can be restored immediately, without the |
| need for tracing stack frames. This method provides very fast |
| exception propagation, but introduces significant overhead for |
| the use of exception handlers, even if no exception is raised. |
| |
| The other approach is called 'zero cost' exception handling. |
| With this method, the compiler builds static tables to describe |
| the exception ranges. No dynamic code is required when entering |
| a frame containing an exception handler. When an exception is |
| raised, the tables are used to control a back trace of the |
| subprogram invocation stack to locate the required exception |
| handler. This method has considerably poorer performance for |
| the propagation of exceptions, but there is no overhead for |
| exception handlers if no exception is raised. Note that in this |
| mode and in the context of mixed Ada and C/C++ programming, |
| to propagate an exception through a C/C++ code, the C/C++ code |
| must be compiled with the @emph{-funwind-tables} GCC's |
| option. |
| |
| The following switches may be used to control which of the |
| two exception handling methods is used. |
| |
| @geindex --RTS=sjlj (gnatmake) |
| |
| |
| @table @asis |
| |
| @item @code{--RTS=sjlj} |
| |
| This switch causes the setjmp/longjmp run-time (when available) to be used |
| for exception handling. If the default |
| mechanism for the target is zero cost exceptions, then |
| this switch can be used to modify this default, and must be |
| used for all units in the partition. |
| This option is rarely used. One case in which it may be |
| advantageous is if you have an application where exception |
| raising is common and the overall performance of the |
| application is improved by favoring exception propagation. |
| @end table |
| |
| @geindex --RTS=zcx (gnatmake) |
| |
| @geindex Zero Cost Exceptions |
| |
| |
| @table @asis |
| |
| @item @code{--RTS=zcx} |
| |
| This switch causes the zero cost approach to be used |
| for exception handling. If this is the default mechanism for the |
| target (see below), then this switch is unneeded. If the default |
| mechanism for the target is setjmp/longjmp exceptions, then |
| this switch can be used to modify this default, and must be |
| used for all units in the partition. |
| This option can only be used if the zero cost approach |
| is available for the target in use, otherwise it will generate an error. |
| @end table |
| |
| The same option @emph{--RTS} must be used both for @emph{gcc} |
| and @emph{gnatbind}. Passing this option to @emph{gnatmake} |
| (@ref{e2,,Switches for gnatmake}) will ensure the required consistency |
| through the compilation and binding steps. |
| |
| @node Units to Sources Mapping Files,Code Generation Control,Exception Handling Control,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id29}@anchor{11e}@anchor{gnat_ugn/building_executable_programs_with_gnat units-to-sources-mapping-files}@anchor{ff} |
| @subsection Units to Sources Mapping Files |
| |
| |
| @geindex -gnatem (gcc) |
| |
| |
| @table @asis |
| |
| @item @code{-gnatem=@emph{path}} |
| |
| 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. |
| |
| The use of mapping files is not required for correct operation of the |
| compiler, but mapping files can improve efficiency, particularly when |
| sources are read over a slow network connection. In normal operation, |
| you need not be concerned with the format or use of mapping files, |
| and the @emph{-gnatem} switch is not a switch that you would use |
| explicitly. It is intended primarily for use by automatic tools such as |
| @emph{gnatmake} running under the project file facility. The |
| description here of the format of mapping files is provided |
| for completeness and for possible use by other tools. |
| |
| 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 @cite{%s} appended |
| for specs and @cite{%b} appended for bodies; the second line is the |
| file name; and the third line is the path name. |
| |
| Example: |
| |
| @example |
| main%b |
| main.2.ada |
| /gnat/project1/sources/main.2.ada |
| @end example |
| |
| When the switch @emph{-gnatem} is specified, the compiler will |
| create in memory the two mappings from the specified file. If there is |
| any problem (nonexistent file, truncated file or duplicate entries), |
| no mapping will be created. |
| |
| Several @emph{-gnatem} switches may be specified; however, only the |
| last one on the command line will be taken into account. |
| |
| When using a project file, @emph{gnatmake} creates a temporary |
| mapping file and communicates it to the compiler using this switch. |
| @end table |
| |
| @node Code Generation Control,,Units to Sources Mapping Files,Compiler Switches |
| @anchor{gnat_ugn/building_executable_programs_with_gnat code-generation-control}@anchor{11f}@anchor{gnat_ugn/building_executable_programs_with_gnat id30}@anchor{120} |
| @subsection Code Generation Control |
| |
| |
| The GCC technology provides a wide range of target dependent |
| @code{-m} switches for controlling |
| details of code generation with respect to different versions of |
| architectures. This includes variations in instruction sets (e.g., |
| different members of the power pc family), and different requirements |
| for optimal arrangement of instructions (e.g., different members of |
| the x86 family). The list of available @emph{-m} switches may be |
| found in the GCC documentation. |
| |
| Use of these @emph{-m} switches may in some cases result in improved |
| code performance. |
| |
| The GNAT technology is tested and qualified without any |
| @code{-m} switches, |
| so generally the most reliable approach is to avoid the use of these |
| switches. However, we generally expect most of these switches to work |
| successfully with GNAT, and many customers have reported successful |
| use of these options. |
| |
| Our general advice is to avoid the use of @emph{-m} switches unless |
| special needs lead to requirements in this area. In particular, |
| there is no point in using @emph{-m} switches to improve performance |
| unless you actually see a performance improvement. |
| |
| @node Binding with gnatbind,Linking with gnatlink,Compiler Switches,Building Executable Programs with GNAT |
| @anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-gnatbind}@anchor{1f}@anchor{gnat_ugn/building_executable_programs_with_gnat id31}@anchor{121} |
| @section Binding with @cite{gnatbind} |
| |
| |
| @geindex gnatbind |
| |
| This chapter describes the GNAT binder, @cite{gnatbind}, which is used |
| to bind compiled GNAT objects. |
| |
| Note: to invoke @cite{gnatbind} with a project file, use the @cite{gnat} |
| driver (see @ref{122,,The GNAT Driver and Project Files}). |
| |
| The @cite{gnatbind} program performs four separate functions: |
| |
| |
| @itemize * |
| |
| @item |
| Checks that a program is consistent, in accordance with the rules in |
| Chapter 10 of the Ada Reference Manual. In particular, error |
| messages are generated if a program uses inconsistent versions of a |
| given unit. |
| |
| @item |
| 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 Language Manual. |
| |
| @item |
| 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 @emph{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. |
| |
| @item |
| 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 @emph{gnatlink} utility used to link the Ada application. |
| @end itemize |
| |
| @menu |
| * Running gnatbind:: |
| * Switches for gnatbind:: |
| * Command-Line Access:: |
| * Search Paths for gnatbind:: |
| * Examples of gnatbind Usage:: |
| |
| @end menu |
| |
| @node Running gnatbind,Switches for gnatbind,,Binding with gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{123}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{124} |
| @subsection Running @cite{gnatbind} |
| |
| |
| The form of the @cite{gnatbind} command is |
| |
| @example |
| $ gnatbind [`switches`] `mainprog`[.ali] [`switches`] |
| @end example |
| |
| where @code{mainprog.adb} is the Ada file containing the main program |
| unit body. @cite{gnatbind} constructs an Ada |
| package in two files whose names are |
| @code{b~mainprog.ads}, and @code{b~mainprog.adb}. |
| For example, if given the |
| parameter @code{hello.ali}, for a main program contained in file |
| @code{hello.adb}, the binder output files would be @code{b~hello.ads} |
| and @code{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 @cite{Pack}, whose |
| @code{.ALI} |
| file is @code{pack.ali} and whose corresponding source spec file is |
| @code{pack.ads}, it attempts to locate the source file @code{pack.ads} |
| (using the same search path conventions as previously described for the |
| @emph{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 @code{ALI} files |
| match. In other words, any @code{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). |
| |
| @geindex Source files |
| @geindex use by binder |
| |
| 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 @code{hello.adb} and a |
| package @cite{P}, from file @code{p.ads} and you perform the following |
| steps: |
| |
| |
| @itemize * |
| |
| @item |
| Enter @cite{gcc -c hello.adb} to compile the main program. |
| |
| @item |
| Enter @cite{gcc -c p.ads} to compile package @cite{P}. |
| |
| @item |
| Edit file @code{p.ads}. |
| |
| @item |
| Enter @cite{gnatbind hello}. |
| @end itemize |
| |
| At this point, the file @code{p.ali} contains an out-of-date time stamp |
| because the file @code{p.ads} has been edited. The attempt at binding |
| fails, and the binder generates the following error messages: |
| |
| @example |
| error: "hello.adb" must be recompiled ("p.ads" has been modified) |
| error: "p.ads" has been modified and must be recompiled |
| @end example |
| |
| 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 for reference purposes a sample |
| binder output file is given in @ref{10,,Example of Binder Output File}. |
| |
| In most normal usage, the default mode of @emph{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 @emph{-g} switch is used for |
| @emph{gnatbind} and @emph{gnatlink}. |
| |
| @node Switches for gnatbind,Command-Line Access,Running gnatbind,Binding with gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id33}@anchor{125}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{126} |
| @subsection Switches for @emph{gnatbind} |
| |
| |
| The following switches are available with @cite{gnatbind}; details will |
| be presented in subsequent sections. |
| |
| @geindex --version (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{--version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{--help} |
| |
| If @emph{--version} was not used, display usage, then exit disregarding |
| all other options. |
| @end table |
| |
| @geindex -a (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-a} |
| |
| Indicates that, if supported by the platform, the adainit procedure should |
| be treated as an initialisation routine by the linker (a constructor). This |
| is intended to be used by the Project Manager to automatically initialize |
| shared Stand-Alone Libraries. |
| @end table |
| |
| @geindex -aO (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-aO} |
| |
| Specify directory to be searched for ALI files. |
| @end table |
| |
| @geindex -aI (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-aI} |
| |
| Specify directory to be searched for source file. |
| @end table |
| |
| @geindex -A (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-A[=@emph{filename}]} |
| |
| Output ALI list (to standard output or to the named file). |
| @end table |
| |
| @geindex -b (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-b} |
| |
| Generate brief messages to @code{stderr} even if verbose mode set. |
| @end table |
| |
| @geindex -c (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-c} |
| |
| Check only, no generation of binder output file. |
| @end table |
| |
| @geindex -dnn[k|m] (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-d@emph{nn}[k|m]} |
| |
| This switch can be used to change the default task stack size value |
| to a specified size @cite{nn}, which is expressed in bytes by default, or |
| in kilobytes when suffixed with @cite{k} or in megabytes when suffixed |
| with @cite{m}. |
| In the absence of a @code{[k|m]} suffix, this switch is equivalent, |
| in effect, to completing all task specs with |
| |
| @example |
| pragma Storage_Size (nn); |
| @end example |
| |
| When they do not already have such a pragma. |
| @end table |
| |
| @geindex -D (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-D@emph{nn}[k|m]} |
| |
| This switch can be used to change the default secondary stack size value |
| to a specified size @cite{nn}, which is expressed in bytes by default, or |
| in kilobytes when suffixed with @cite{k} or in megabytes when suffixed |
| with @cite{m}. |
| |
| The secondary stack is used to deal with functions that return a variable |
| sized result, for example a function returning an unconstrained |
| String. There are two ways in which this secondary stack is allocated. |
| |
| For most targets, the secondary stack is growing on demand and is allocated |
| as a chain of blocks in the heap. The -D option is not very |
| relevant. It only give some control over the size of the allocated |
| blocks (whose size is the minimum of the default secondary stack size value, |
| and the actual size needed for the current allocation request). |
| |
| For certain targets, notably VxWorks 653, |
| the secondary stack is allocated by carving off a fixed ratio chunk of the |
| primary task stack. The -D option is used to define the |
| size of the environment task's secondary stack. |
| @end table |
| |
| @geindex -e (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-e} |
| |
| Output complete list of elaboration-order dependencies. |
| @end table |
| |
| @geindex -Ea (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-Ea} |
| |
| Store tracebacks in exception occurrences when the target supports it. |
| The "a" is for "address"; tracebacks will contain hexadecimal addresses, |
| unless symbolic tracebacks are enabled. |
| |
| See also the packages @cite{GNAT.Traceback} and |
| @cite{GNAT.Traceback.Symbolic} for more information. |
| Note that on x86 ports, you must not use @emph{-fomit-frame-pointer} |
| @emph{gcc} option. |
| @end table |
| |
| @geindex -Es (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-Es} |
| |
| Store tracebacks in exception occurrences when the target supports it. |
| The "s" is for "symbolic"; symbolic tracebacks are enabled. |
| @end table |
| |
| @geindex -E (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-E} |
| |
| Currently the same as @cite{-Ea}. |
| @end table |
| |
| @geindex -F (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-F} |
| |
| Force the checks of elaboration flags. @emph{gnatbind} does not normally |
| generate checks of elaboration flags for the main executable, except when |
| a Stand-Alone Library is used. However, there are cases when this cannot be |
| detected by gnatbind. An example is importing an interface of a Stand-Alone |
| Library through a pragma Import and only specifying through a linker switch |
| this Stand-Alone Library. This switch is used to guarantee that elaboration |
| flag checks are generated. |
| @end table |
| |
| @geindex -h (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-h} |
| |
| Output usage (help) information. |
| |
| @geindex -H32 (gnatbind) |
| |
| @item @code{-H32} |
| |
| Use 32-bit allocations for @cite{__gnat_malloc} (and thus for access types). |
| For further details see @ref{127,,Dynamic Allocation Control}. |
| |
| @geindex -H64 (gnatbind) |
| |
| @geindex __gnat_malloc |
| |
| @item @code{-H64} |
| |
| Use 64-bit allocations for @cite{__gnat_malloc} (and thus for access types). |
| For further details see @ref{127,,Dynamic Allocation Control}. |
| |
| @geindex -I (gnatbind) |
| |
| @item @code{-I} |
| |
| Specify directory to be searched for source and ALI files. |
| |
| @geindex -I- (gnatbind) |
| |
| @item @code{-I-} |
| |
| Do not look for sources in the current directory where @cite{gnatbind} was |
| invoked, and do not look for ALI files in the directory containing the |
| ALI file named in the @cite{gnatbind} command line. |
| |
| @geindex -l (gnatbind) |
| |
| @item @code{-l} |
| |
| Output chosen elaboration order. |
| |
| @geindex -L (gnatbind) |
| |
| @item @code{-L@emph{xxx}} |
| |
| Bind the units for library building. In this case the adainit and |
| adafinal procedures (@ref{ba,,Binding with Non-Ada Main Programs}) |
| are renamed to @cite{xxx`init and `xxx`final. Implies -n. (:ref:`GNAT_and_Libraries}, for more details.) |
| |
| @geindex -M (gnatbind) |
| |
| @item @code{-M@emph{xyz}} |
| |
| Rename generated main program from main to xyz. This option is |
| supported on cross environments only. |
| |
| @geindex -m (gnatbind) |
| |
| @item @code{-m@emph{n}} |
| |
| Limit number of detected errors or warnings to @cite{n}, where @cite{n} is |
| in the range 1..999999. The default value if no switch is |
| given is 9999. If the number of warnings reaches this limit, then a |
| message is output and further warnings are suppressed, the bind |
| continues in this case. If the number of errors reaches this |
| limit, then a message is output and the bind is abandoned. |
| A value of zero means that no limit is enforced. The equal |
| sign is optional. |
| |
| @geindex -n (gnatbind) |
| |
| @item @code{-n} |
| |
| No main program. |
| |
| @geindex -nostdinc (gnatbind) |
| |
| @item @code{-nostdinc} |
| |
| Do not look for sources in the system default directory. |
| |
| @geindex -nostdlib (gnatbind) |
| |
| @item @code{-nostdlib} |
| |
| Do not look for library files in the system default directory. |
| |
| @geindex --RTS (gnatbind) |
| |
| @item @code{--RTS=@emph{rts-path}} |
| |
| Specifies the default location of the runtime library. Same meaning as the |
| equivalent @emph{gnatmake} flag (@ref{e2,,Switches for gnatmake}). |
| |
| @geindex -o (gnatbind) |
| |
| @item @code{-o @emph{file}} |
| |
| Name the output file @cite{file} (default is @code{b~`xxx}.adb`). |
| Note that if this option is used, then linking must be done manually, |
| gnatlink cannot be used. |
| |
| @geindex -O (gnatbind) |
| |
| @item @code{-O[=@emph{filename}]} |
| |
| Output object list (to standard output or to the named file). |
| |
| @geindex -p (gnatbind) |
| |
| @item @code{-p} |
| |
| Pessimistic (worst-case) elaboration order. |
| |
| @geindex -P (gnatbind) |
| |
| @item @code{-P} |
| |
| Generate binder file suitable for CodePeer. |
| |
| @geindex -R (gnatbind) |
| |
| @item @code{-R} |
| |
| Output closure source list, which includes all non-run-time units that are |
| included in the bind. |
| |
| @geindex -Ra (gnatbind) |
| |
| @item @code{-Ra} |
| |
| Like @emph{-R} but the list includes run-time units. |
| |
| @geindex -s (gnatbind) |
| |
| @item @code{-s} |
| |
| Require all source files to be present. |
| |
| @geindex -S (gnatbind) |
| |
| @item @code{-S@emph{xxx}} |
| |
| Specifies the value to be used when detecting uninitialized scalar |
| objects with pragma Initialize_Scalars. |
| The @cite{xxx} string specified with the switch is one of: |
| |
| |
| @itemize * |
| |
| @item |
| @code{in} for an invalid value. |
| |
| If zero is invalid for the discrete type in question, |
| then the scalar value is set to all zero bits. |
| For signed discrete types, the largest possible negative value of |
| the underlying scalar is set (i.e. a one bit followed by all zero bits). |
| For unsigned discrete types, the underlying scalar value is set to all |
| one bits. For floating-point types, a NaN value is set |
| (see body of package System.Scalar_Values for exact values). |
| |
| @item |
| @code{lo} for low value. |
| |
| If zero is invalid for the discrete type in question, |
| then the scalar value is set to all zero bits. |
| For signed discrete types, the largest possible negative value of |
| the underlying scalar is set (i.e. a one bit followed by all zero bits). |
| For unsigned discrete types, the underlying scalar value is set to all |
| zero bits. For floating-point, a small value is set |
| (see body of package System.Scalar_Values for exact values). |
| |
| @item |
| @code{hi} for high value. |
| |
| If zero is invalid for the discrete type in question, |
| then the scalar value is set to all one bits. |
| For signed discrete types, the largest possible positive value of |
| the underlying scalar is set (i.e. a zero bit followed by all one bits). |
| For unsigned discrete types, the underlying scalar value is set to all |
| one bits. For floating-point, a large value is set |
| (see body of package System.Scalar_Values for exact values). |
| |
| @item |
| @cite{xx} for hex value (two hex digits). |
| |
| The underlying scalar is set to a value consisting of repeated bytes, whose |
| value corresponds to the given value. For example if @code{BF} is given, |
| then a 32-bit scalar value will be set to the bit patterm @code{16#BFBFBFBF#}. |
| @end itemize |
| |
| @geindex GNAT_INIT_SCALARS |
| |
| In addition, you can specify @emph{-Sev} to indicate that the value is |
| to be set at run time. In this case, the program will look for an environment |
| variable of the form @code{GNAT_INIT_SCALARS=@emph{yy}}, where @cite{yy} is one |
| of @emph{in/lo/hi/`xx*` with the same meanings as above. |
| If no environment variable is found, or if it does not have a valid value, |
| then the default is *in} (invalid values). |
| @end table |
| |
| @geindex -static (gnatbind) |
| |
| |
| @table @asis |
| |
| @item @code{-static} |
| |
| Link against a static GNAT run time. |
| |
| @geindex -shared (gnatbind) |
| |
| @item @code{-shared} |
| |
| Link against a shared GNAT run time when available. |
| |
| @geindex -t (gnatbind) |
| |
| @item @code{-t} |
| |
| Tolerate time stamp and other consistency errors. |
| |
| @geindex -T (gnatbind) |
| |
| @item @code{-T@emph{n}} |
| |
| Set the time slice value to @cite{n} milliseconds. If the system supports |
| the specification of a specific time slice value, then the indicated value |
| is used. If the system does not support specific time slice values, but |
| does support some general notion of round-robin scheduling, then any |
| nonzero value will activate round-robin scheduling. |
| |
| A value of zero is treated specially. It turns off time |
| slicing, and in addition, indicates to the tasking run time that the |
| semantics should match as closely as possible the Annex D |
| requirements of the Ada RM, and in particular sets the default |
| scheduling policy to @cite{FIFO_Within_Priorities}. |
| |
| @geindex -u (gnatbind) |
| |
| @item @code{-u@emph{n}} |
| |
| Enable dynamic stack usage, with @cite{n} results stored and displayed |
| at program termination. A result is generated when a task |
| terminates. Results that can't be stored are displayed on the fly, at |
| task termination. This option is currently not supported on Itanium |
| platforms. (See @ref{128,,Dynamic Stack Usage Analysis} for details.) |
| |
| @geindex -v (gnatbind) |
| |
| @item @code{-v} |
| |
| Verbose mode. Write error messages, header, summary output to |
| @code{stdout}. |
| |
| @geindex -V (gnatbind) |
| |
| @item @code{-V@emph{key}=@emph{value}} |
| |
| Store the given association of @cite{key} to @cite{value} in the bind environment. |
| Values stored this way can be retrieved at run time using |
| @cite{GNAT.Bind_Environment}. |
| |
| @geindex -w (gnatbind) |
| |
| @item @code{-w@emph{x}} |
| |
| Warning mode; @cite{x} = s/e for suppress/treat as error. |
| |
| @geindex -Wx (gnatbind) |
| |
| @item @code{-Wx@emph{e}} |
| |
| Override default wide character encoding for standard Text_IO files. |
| |
| @geindex -x (gnatbind) |
| |
| @item @code{-x} |
| |
| Exclude source files (check object consistency only). |
| |
| @geindex -Xnnn (gnatbind) |
| |
| @item @code{-X@emph{nnn}} |
| |
| Set default exit status value, normally 0 for POSIX compliance. |
| |
| @geindex -y (gnatbind) |
| |
| @item @code{-y} |
| |
| Enable leap seconds support in @cite{Ada.Calendar} and its children. |
| |
| @geindex -z (gnatbind) |
| |
| @item @code{-z} |
| |
| No main subprogram. |
| @end table |
| |
| You may obtain this listing of switches by running @cite{gnatbind} with |
| no arguments. |
| |
| @menu |
| * Consistency-Checking Modes:: |
| * Binder Error Message Control:: |
| * Elaboration Control:: |
| * Output Control:: |
| * Dynamic Allocation Control:: |
| * Binding with Non-Ada Main Programs:: |
| * Binding Programs with No Main Subprogram:: |
| |
| @end menu |
| |
| @node Consistency-Checking Modes,Binder Error Message Control,,Switches for gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat consistency-checking-modes}@anchor{129}@anchor{gnat_ugn/building_executable_programs_with_gnat id34}@anchor{12a} |
| @subsubsection Consistency-Checking Modes |
| |
| |
| As described earlier, by default @cite{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. |
| |
| @quotation |
| |
| @geindex -s (gnatbind) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| |
| @geindex -Wx (gnatbind) |
| |
| @item @code{-Wx@emph{e}} |
| |
| Override default wide character encoding for standard Text_IO files. |
| Normally the default wide character encoding method used for standard |
| [Wide_[Wide_]]Text_IO files is taken from the encoding specified for |
| the main source input (see description of switch |
| @emph{-gnatWx} for the compiler). The |
| use of this switch for the binder (which has the same set of |
| possible arguments) overrides this default as specified. |
| |
| @geindex -x (gnatbind) |
| |
| @item @code{-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 @emph{gnatmake} because in this |
| case the checking against sources has already been performed by |
| @emph{gnatmake} in the course of compilation (i.e., before binding). |
| @end table |
| |
| @node Binder Error Message Control,Elaboration Control,Consistency-Checking Modes,Switches for gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id35}@anchor{12b}@anchor{gnat_ugn/building_executable_programs_with_gnat binder-error-message-control}@anchor{12c} |
| @subsubsection Binder Error Message Control |
| |
| |
| The following switches provide control over the generation of error |
| messages from the binder: |
| |
| @quotation |
| |
| @geindex -v (gnatbind) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @code{-v} |
| |
| Verbose mode. In the normal mode, brief error messages are generated to |
| @code{stderr}. If this switch is present, a header is written |
| to @code{stdout} and any error messages are directed to @code{stdout}. |
| All that is written to @code{stderr} is a brief summary message. |
| |
| @geindex -b (gnatbind) |
| |
| @item @code{-b} |
| |
| Generate brief error messages to @code{stderr} even if verbose mode is |
| specified. This is relevant only when used with the |
| @emph{-v} switch. |
| |
| @geindex -m (gnatbind) |
| |
| @item @code{-m@emph{n}} |
| |
| Limits the number of error messages to @cite{n}, a decimal integer in the |
| range 1-999. The binder terminates immediately if this limit is reached. |
| |
| @geindex -M (gnatbind) |
| |
| @item @code{-M@emph{xxx}} |
| |
| Renames the generated main program from @cite{main} to @cite{xxx}. |
| This is useful in the case of some cross-building environments, where |
| the actual main program is separate from the one generated |
| by @cite{gnatbind}. |
| |
| @geindex -ws (gnatbind) |
| |
| @geindex Warnings |
| |
| @item @code{-ws} |
| |
| Suppress all warning messages. |
| |
| @geindex -we (gnatbind) |
| |
| @item @code{-we} |
| |
| Treat any warning messages as fatal errors. |
| |
| @geindex -t (gnatbind) |
| |
| @geindex Time stamp checks |
| @geindex in binder |
| |
| @geindex Binder consistency checks |
| |
| @geindex Consistency checks |
| @geindex in binder |
| |
| @item @code{-t} |
| |
| The binder performs a number of consistency checks including: |
| |
| |
| @itemize * |
| |
| @item |
| Check that time stamps of a given source unit are consistent |
| |
| @item |
| Check that checksums of a given source unit are consistent |
| |
| @item |
| Check that consistent versions of @cite{GNAT} were used for compilation |
| |
| @item |
| Check consistency of configuration pragmas as required |
| @end itemize |
| |
| 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 @emph{-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. |
| |
| @cartouche |
| @quotation Note |
| This means that @emph{-t} should be used only in unusual situations, |
| with extreme care. |
| @end quotation |
| @end cartouche |
| @end table |
| |
| @node Elaboration Control,Output Control,Binder Error Message Control,Switches for gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id36}@anchor{12d}@anchor{gnat_ugn/building_executable_programs_with_gnat elaboration-control}@anchor{12e} |
| @subsubsection Elaboration Control |
| |
| |
| The following switches provide additional control over the elaboration |
| order. For full details see @ref{11,,Elaboration Order Handling in GNAT}. |
| |
| @quotation |
| |
| @geindex -p (gnatbind) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @code{-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 @cite{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 @emph{-p} |
| switch if dynamic |
| elaboration checking is used (@emph{-gnatE} switch used for compilation). |
| This is because in the default static elaboration mode, all necessary |
| @cite{Elaborate} and @cite{Elaborate_All} pragmas are implicitly inserted. |
| These implicit pragmas are still respected by the binder in |
| @emph{-p} mode, so a |
| safe elaboration order is assured. |
| |
| Note that @emph{-p} is not intended for |
| production use; it is more for debugging/experimental use. |
| @end table |
| |
| @node Output Control,Dynamic Allocation Control,Elaboration Control,Switches for gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat output-control}@anchor{12f}@anchor{gnat_ugn/building_executable_programs_with_gnat id37}@anchor{130} |
| @subsubsection Output Control |
| |
| |
| The following switches allow additional control over the output |
| generated by the binder. |
| |
| @quotation |
| |
| @geindex -c (gnatbind) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| |
| @geindex -e (gnatbind) |
| |
| @item @code{-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 @code{stdout}. |
| |
| @geindex -h (gnatbind) |
| |
| @item @code{-h} |
| |
| Output usage information. The output is written to @code{stdout}. |
| |
| @geindex -K (gnatbind) |
| |
| @item @code{-K} |
| |
| Output linker options to @code{stdout}. Includes library search paths, |
| contents of pragmas Ident and Linker_Options, and libraries added |
| by @cite{gnatbind}. |
| |
| @geindex -l (gnatbind) |
| |
| @item @code{-l} |
| |
| Output chosen elaboration order. The output is written to @code{stdout}. |
| |
| @geindex -O (gnatbind) |
| |
| @item @code{-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 @code{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. |
| |
| @geindex -o (gnatbind) |
| |
| @item @code{-o @emph{file}} |
| |
| Set name of output file to @cite{file} instead of the normal |
| @code{b~`mainprog}.adb` default. Note that @cite{file} denote the Ada |
| binder generated body filename. |
| 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. |
| |
| @geindex -r (gnatbind) |
| |
| @item @code{-r} |
| |
| Generate list of @cite{pragma Restrictions} 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. |
| @end table |
| |
| @node Dynamic Allocation Control,Binding with Non-Ada Main Programs,Output Control,Switches for gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat dynamic-allocation-control}@anchor{127}@anchor{gnat_ugn/building_executable_programs_with_gnat id38}@anchor{131} |
| @subsubsection Dynamic Allocation Control |
| |
| |
| The heap control switches -- @emph{-H32} and @emph{-H64} -- |
| determine whether dynamic allocation uses 32-bit or 64-bit memory. |
| They only affect compiler-generated allocations via @cite{__gnat_malloc}; |
| explicit calls to @cite{malloc} and related functions from the C |
| run-time library are unaffected. |
| |
| |
| @table @asis |
| |
| @item @code{-H32} |
| |
| Allocate memory on 32-bit heap |
| |
| @item @code{-H64} |
| |
| Allocate memory on 64-bit heap. This is the default |
| unless explicitly overridden by a @cite{'Size} clause on the access type. |
| @end table |
| |
| These switches are only effective on VMS platforms. |
| |
| @node Binding with Non-Ada Main Programs,Binding Programs with No Main Subprogram,Dynamic Allocation Control,Switches for gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-non-ada-main-programs}@anchor{ba}@anchor{gnat_ugn/building_executable_programs_with_gnat id39}@anchor{132} |
| @subsubsection Binding with Non-Ada Main Programs |
| |
| |
| The description so far has assumed that the main |
| program is in Ada, and that the task of the binder is to generate a |
| corresponding function @cite{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 (@ref{46,,Mixed Language Programming}). |
| The following switch is used in this situation: |
| |
| @quotation |
| |
| @geindex -n (gnatbind) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @code{-n} |
| |
| No main program. The main program is not in Ada. |
| @end table |
| |
| 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: |
| |
| @quotation |
| |
| @geindex adainit |
| |
| |
| @table @asis |
| |
| @item @emph{adainit} |
| |
| You must call this routine to initialize the Ada part of the program by |
| calling the necessary elaboration routines. A call to @cite{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. |
| @end table |
| |
| @geindex adafinal |
| |
| |
| @table @asis |
| |
| @item @emph{adafinal} |
| |
| You must call this routine to perform any library-level finalization |
| required by the Ada subprograms. A call to @cite{adafinal} is required |
| after the last call to an Ada subprogram, and before the program |
| terminates. |
| @end table |
| @end quotation |
| |
| @geindex -n (gnatbind) |
| |
| @geindex Binder |
| @geindex multiple input files |
| |
| If the @emph{-n} switch |
| is given, more than one ALI file may appear on |
| the command line for @cite{gnatbind}. The normal @emph{closure} |
| calculation is performed for each of the specified units. Calculating |
| the closure means finding out the set of units involved by tracing |
| @emph{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 @emph{-o file}. |
| |
| @geindex -o (gnatbind) |
| |
| The output is an Ada unit in source form that can be compiled with GNAT. |
| This compilation occurs automatically as part of the @emph{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. |
| |
| @node Binding Programs with No Main Subprogram,,Binding with Non-Ada Main Programs,Switches for gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat binding-programs-with-no-main-subprogram}@anchor{133}@anchor{gnat_ugn/building_executable_programs_with_gnat id40}@anchor{134} |
| @subsubsection 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: |
| |
| @quotation |
| |
| @geindex -z (gnatbind) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @code{-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. Note |
| that the default wide character encoding method for standard Text_IO |
| files is always set to Brackets if this switch is set (you can use |
| the binder switch |
| @emph{-Wx} to override this default). |
| @end table |
| |
| @node Command-Line Access,Search Paths for gnatbind,Switches for gnatbind,Binding with gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id41}@anchor{135}@anchor{gnat_ugn/building_executable_programs_with_gnat command-line-access}@anchor{136} |
| @subsection Command-Line Access |
| |
| |
| The package @cite{Ada.Command_Line} provides access to the command-line |
| arguments and program name. In order for this interface to operate |
| correctly, the two variables |
| |
| @example |
| int gnat_argc; |
| char **gnat_argv; |
| @end example |
| |
| @geindex gnat_argv |
| |
| @geindex gnat_argc |
| |
| are declared in one of the GNAT library routines. These variables must |
| be set from the actual @cite{argc} and @cite{argv} values passed to the |
| main program. With no @emph{n} present, @cite{gnatbind} |
| generates the C main program to automatically set these variables. |
| If the @emph{n} switch is used, there is no automatic way to |
| set these variables. If they are not set, the procedures in |
| @cite{Ada.Command_Line} will not be available, and any attempt to use |
| them will raise @cite{Constraint_Error}. If command line access is |
| required, your main program must set @cite{gnat_argc} and |
| @cite{gnat_argv} from the @cite{argc} and @cite{argv} values passed to |
| it. |
| |
| @node Search Paths for gnatbind,Examples of gnatbind Usage,Command-Line Access,Binding with gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-for-gnatbind}@anchor{91}@anchor{gnat_ugn/building_executable_programs_with_gnat id42}@anchor{137} |
| @subsection Search Paths for @cite{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 @emph{gcc} |
| (see @ref{8e,,Search Paths and the Run-Time Library (RTL)}). For ALI files the |
| directories searched are: |
| |
| |
| @itemize * |
| |
| @item |
| The directory containing the ALI file named in the command line, unless |
| the switch @emph{-I-} is specified. |
| |
| @item |
| All directories specified by @emph{-I} |
| switches on the @cite{gnatbind} |
| command line, in the order given. |
| |
| @geindex ADA_PRJ_OBJECTS_FILE |
| |
| @item |
| Each of the directories listed in the text file whose name is given |
| by the |
| @geindex ADA_PRJ_OBJECTS_FILE |
| @geindex environment variable; ADA_PRJ_OBJECTS_FILE |
| @code{ADA_PRJ_OBJECTS_FILE} environment variable. |
| |
| @geindex ADA_PRJ_OBJECTS_FILE |
| @geindex environment variable; ADA_PRJ_OBJECTS_FILE |
| @code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the gnat |
| driver when project files are used. It should not normally be set |
| by other means. |
| |
| @geindex ADA_OBJECTS_PATH |
| |
| @item |
| Each of the directories listed in the value of the |
| @geindex ADA_OBJECTS_PATH |
| @geindex environment variable; ADA_OBJECTS_PATH |
| @code{ADA_OBJECTS_PATH} environment variable. |
| Construct this value |
| exactly as the |
| @geindex PATH |
| @geindex environment variable; PATH |
| @code{PATH} environment variable: a list of directory |
| names separated by colons (semicolons when working with the NT version |
| of GNAT). |
| |
| @item |
| The content of the @code{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 @emph{-nostdlib} is |
| specified. See @ref{8b,,Installing a library} |
| @end itemize |
| |
| @geindex -I (gnatbind) |
| |
| @geindex -aI (gnatbind) |
| |
| @geindex -aO (gnatbind) |
| |
| In the binder the switch @emph{-I} |
| is used to specify both source and |
| library file paths. Use @emph{-aI} |
| instead if you want to specify |
| source paths only, and @emph{-aO} |
| if you want to specify library paths |
| only. This means that for the binder |
| @code{-I@emph{dir}} is equivalent to |
| @code{-aI@emph{dir}} |
| @code{-aO`@emph{dir}}. |
| The binder generates the bind file (a C language source file) in the |
| current working directory. |
| |
| @geindex Ada |
| |
| @geindex System |
| |
| @geindex Interfaces |
| |
| @geindex GNAT |
| |
| The packages @cite{Ada}, @cite{System}, and @cite{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. |
| |
| @node Examples of gnatbind Usage,,Search Paths for gnatbind,Binding with gnatbind |
| @anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatbind-usage}@anchor{138}@anchor{gnat_ugn/building_executable_programs_with_gnat id43}@anchor{139} |
| @subsection Examples of @cite{gnatbind} Usage |
| |
| |
| Here are some examples of @cite{gnatbind} invovations: |
| |
| @quotation |
| |
| @example |
| gnatbind hello |
| @end example |
| |
| The main program @cite{Hello} (source program in @code{hello.adb}) is |
| bound using the standard switch settings. The generated main program is |
| @code{b~hello.adb}. This is the normal, default use of the binder. |
| |
| @example |
| gnatbind hello -o mainprog.adb |
| @end example |
| |
| The main program @cite{Hello} (source program in @code{hello.adb}) is |
| bound using the standard switch settings. The generated main program is |
| @code{mainprog.adb} with the associated spec in |
| @code{mainprog.ads}. Note that you must specify the body here not the |
| spec. Note that if this option is used, then linking must be done manually, |
| since gnatlink will not be able to find the generated file. |
| @end quotation |
| |
| @node Linking with gnatlink,Using the GNU make Utility,Binding with gnatbind,Building Executable Programs with GNAT |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id44}@anchor{13a}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{20} |
| @section Linking with @emph{gnatlink} |
| |
| |
| @geindex gnatlink |
| |
| This chapter discusses @emph{gnatlink}, a tool that links |
| an Ada program and builds an executable file. This utility |
| invokes the system linker (via the @emph{gcc} command) |
| with a correct list of object files and library references. |
| @emph{gnatlink} automatically determines the list of files and |
| references for the Ada part of a program. It uses the binder file |
| generated by the @emph{gnatbind} to determine this list. |
| |
| Note: to invoke @cite{gnatlink} with a project file, use the @cite{gnat} |
| driver (see @ref{122,,The GNAT Driver and Project Files}). |
| |
| @menu |
| * Running gnatlink:: |
| * Switches for gnatlink:: |
| |
| @end menu |
| |
| @node Running gnatlink,Switches for gnatlink,,Linking with gnatlink |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id45}@anchor{13b}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{13c} |
| @subsection Running @emph{gnatlink} |
| |
| |
| The form of the @emph{gnatlink} command is |
| |
| @example |
| $ gnatlink [`switches`] `mainprog`[.ali] |
| [`non-Ada objects`] [`linker options`] |
| @end example |
| |
| The arguments of @emph{gnatlink} (switches, main @code{ALI} file, |
| non-Ada objects |
| or linker options) may be in any order, provided that no non-Ada object may |
| be mistaken for a main @code{ALI} file. |
| Any file name @code{F} without the @code{.ali} |
| extension will be taken as the main @code{ALI} file if a file exists |
| whose name is the concatenation of @code{F} and @code{.ali}. |
| |
| @code{mainprog.ali} references the ALI file of the main program. |
| The @code{.ali} extension of this file can be omitted. From this |
| reference, @emph{gnatlink} locates the corresponding binder file |
| @code{b~mainprog.adb} and, using the information in this file along |
| with the list of non-Ada objects and linker options, constructs a |
| linker command file to create the executable. |
| |
| The arguments other than the @emph{gnatlink} switches and the main |
| @code{ALI} file 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 @cite{Import} pragmas in any Ada units. |
| |
| @cite{linker options} is an optional list of linker specific |
| switches. |
| The default linker called by gnatlink is @emph{gcc} which in |
| turn calls the appropriate system linker. |
| |
| One useful option for the linker is @emph{-s}: it reduces the size of the |
| executable by removing all symbol table and relocation information from the |
| executable. |
| |
| Standard options for the linker such as @emph{-lmy_lib} or |
| @emph{-Ldir} can be added as is. |
| For options that are not recognized by |
| @emph{gcc} as linker options, use the @emph{gcc} switches |
| @emph{-Xlinker} or @emph{-Wl,}. |
| |
| Refer to the GCC documentation for |
| details. |
| |
| Here is an example showing how to generate a linker map: |
| |
| @example |
| $ gnatlink my_prog -Wl,-Map,MAPFILE |
| @end example |
| |
| Using @cite{linker options} it is possible to set the program stack and |
| heap size. |
| See @ref{13d,,Setting Stack Size from gnatlink} and |
| @ref{13e,,Setting Heap Size from gnatlink}. |
| |
| @emph{gnatlink} determines the list of objects required by the Ada |
| program and prepends them to the list of objects passed to the linker. |
| @emph{gnatlink} also gathers any arguments set by the use of |
| @cite{pragma Linker_Options} and adds them to the list of arguments |
| presented to the linker. |
| |
| @node Switches for gnatlink,,Running gnatlink,Linking with gnatlink |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{13f}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{140} |
| @subsection Switches for @emph{gnatlink} |
| |
| |
| The following switches are available with the @emph{gnatlink} utility: |
| |
| @geindex --version (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{--version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{--help} |
| |
| If @emph{--version} was not used, display usage, then exit disregarding |
| all other options. |
| @end table |
| |
| @geindex Command line length |
| |
| @geindex -f (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-f} |
| |
| On some targets, the command line length is limited, and @emph{gnatlink} |
| will generate a separate file for the linker if the list of object files |
| is too long. |
| The @emph{-f} switch 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. |
| @end table |
| |
| @geindex Debugging information |
| @geindex including |
| |
| @geindex -g (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-g} |
| |
| The option to include debugging information causes the Ada bind file (in |
| other words, @code{b~mainprog.adb}) to be compiled with @emph{-g}. |
| In addition, the binder does not delete the @code{b~mainprog.adb}, |
| @code{b~mainprog.o} and @code{b~mainprog.ali} files. |
| Without @emph{-g}, the binder removes these files by default. |
| @end table |
| |
| @geindex -n (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| @end table |
| |
| @geindex -v (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-v} |
| |
| Verbose mode. 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. |
| @end table |
| |
| @geindex -v -v (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-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. |
| @end table |
| |
| @geindex -o (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-o @emph{exec-name}} |
| |
| @cite{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, @cite{gnatlink try.ali} creates |
| an executable called @code{try}. |
| @end table |
| |
| @geindex -b (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-b @emph{target}} |
| |
| Compile your program to run on @cite{target}, which is the name of a |
| system configuration. You must have a GNAT cross-compiler built if |
| @cite{target} is not the same as your host system. |
| @end table |
| |
| @geindex -B (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-B@emph{dir}} |
| |
| Load compiler executables (for example, @cite{gnat1}, the Ada compiler) |
| from @cite{dir} instead of the default location. Only use this switch |
| when multiple versions of the GNAT compiler are available. |
| See the @cite{Directory Options} section in @cite{The_GNU_Compiler_Collection} |
| for further details. You would normally use the @emph{-b} or |
| @emph{-V} switch instead. |
| @end table |
| |
| @geindex -M (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-M} |
| |
| When linking an executable, create a map file. The name of the map file |
| has the same name as the executable with extension ".map". |
| @end table |
| |
| @geindex -M= (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{-M=@emph{mapfile}} |
| |
| When linking an executable, create a map file. The name of the map file is |
| @cite{mapfile}. |
| @end table |
| |
| @geindex --GCC=compiler_name (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{--GCC=@emph{compiler_name}} |
| |
| Program used for compiling the binder file. The default is |
| @code{gcc}. You need to use quotes around @cite{compiler_name} if |
| @cite{compiler_name} contains spaces or other separator characters. |
| As an example @code{--GCC="foo -x -y"} will instruct @emph{gnatlink} to |
| use @code{foo -x -y} as your compiler. Note that switch @code{-c} is always |
| inserted after your command name. Thus in the above example the compiler |
| command that will be used by @emph{gnatlink} will be @code{foo -c -x -y}. |
| A limitation of this syntax is that the name and path name of the executable |
| itself must not include any embedded spaces. If the compiler executable is |
| different from the default one (gcc or <prefix>-gcc), then the back-end |
| switches in the ALI file are not used to compile the binder generated source. |
| For example, this is the case with @code{--GCC="foo -x -y"}. But the back end |
| switches will be used for @code{--GCC="gcc -gnatv"}. If several |
| @code{--GCC=compiler_name} are used, only the last @cite{compiler_name} |
| is taken into account. However, all the additional switches are also taken |
| into account. Thus, |
| @code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to |
| @code{--GCC="bar -x -y -z -t"}. |
| @end table |
| |
| @geindex --LINK= (gnatlink) |
| |
| |
| @table @asis |
| |
| @item @code{--LINK=@emph{name}} |
| |
| @cite{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 @emph{gcc}. When this switch is used, the |
| specified linker is called instead of @emph{gcc} with exactly the same |
| parameters that would have been passed to @emph{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. |
| @end table |
| |
| @node Using the GNU make Utility,,Linking with gnatlink,Building Executable Programs with GNAT |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id47}@anchor{141}@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{21} |
| @section Using the GNU @cite{make} Utility |
| |
| |
| @geindex make (GNU) |
| @geindex GNU make |
| |
| This chapter offers some examples of makefiles that solve specific |
| problems. It does not explain how to write a makefile, nor does it try to replace the |
| @emph{gnatmake} utility (@ref{1d,,Building with gnatmake}). |
| |
| All the examples in this section are specific to the GNU version of |
| make. Although @emph{make} is a standard utility, and the basic language |
| is the same, these examples use some advanced features found only in |
| @cite{GNU make}. |
| |
| @menu |
| * Using gnatmake in a Makefile:: |
| * Automatically Creating a List of Directories:: |
| * Generating the Command Line Switches:: |
| * Overcoming Command Line Length Limits:: |
| |
| @end menu |
| |
| @node Using gnatmake in a Makefile,Automatically Creating a List of Directories,,Using the GNU make Utility |
| @anchor{gnat_ugn/building_executable_programs_with_gnat using-gnatmake-in-a-makefile}@anchor{142}@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{143} |
| @subsection Using gnatmake in a Makefile |
| |
| |
| @c index makefile (GNU make) |
| |
| 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 |
| @emph{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 |
| (@ref{144,,Automatically Creating a List of Directories}) |
| which might help you in case your project has a lot of subdirectories. |
| |
| @example |
| ## 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@} |
| @end example |
| |
| @node Automatically Creating a List of Directories,Generating the Command Line Switches,Using gnatmake in a Makefile,Using the GNU make Utility |
| @anchor{gnat_ugn/building_executable_programs_with_gnat automatically-creating-a-list-of-directories}@anchor{144}@anchor{gnat_ugn/building_executable_programs_with_gnat id49}@anchor{145} |
| @subsection 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 @emph{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, etc. |
| |
| The second method is the most general one. It requires an external |
| program, called @emph{find}, which is standard on all Unix systems. All |
| the directories found under a given root directory will be added to the |
| list. |
| |
| @example |
| # 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@} |
| @end example |
| |
| @node Generating the Command Line Switches,Overcoming Command Line Length Limits,Automatically Creating a List of Directories,Using the GNU make Utility |
| @anchor{gnat_ugn/building_executable_programs_with_gnat id50}@anchor{146}@anchor{gnat_ugn/building_executable_programs_with_gnat generating-the-command-line-switches}@anchor{147} |
| @subsection Generating the Command Line Switches |
| |
| |
| Once you have created the list of directories as explained in the |
| previous section (@ref{144,,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. |
| |
| @example |
| # 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 |
| @end example |
| |
| @node Overcoming Command Line Length Limits,,Generating the Command Line Switches,Using the GNU make Utility |
| @anchor{gnat_ugn/building_executable_programs_with_gnat overcoming-command-line-length-limits}@anchor{148}@anchor{gnat_ugn/building_executable_programs_with_gnat id51}@anchor{149} |
| @subsection 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 @emph{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 |
| @ref{144,,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 @cite{make}. This way we overcome the standard |
| make behavior which is to expand the variables only when they are |
| actually used. |
| |
| On Windows, if you are using the standard Windows command shell, you must |
| replace colons with semicolons in the assignments to these variables. |
| |
| @example |
| # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_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_OBJECTS_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_OBJECTS_PATH += $@{OBJECT_LIST@} |
| export ADA_INCLUDE_PATH |
| export ADA_OBJECTS_PATH |
| |
| all: |
| gnatmake main_unit |
| @end example |
| |
| @c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit |
| |
| @node GNAT Project Manager,Tools Supporting Project Files,Building Executable Programs with GNAT,Top |
| @anchor{gnat_ugn/gnat_project_manager doc}@anchor{14a}@anchor{gnat_ugn/gnat_project_manager gnat-project-manager}@anchor{b}@anchor{gnat_ugn/gnat_project_manager id1}@anchor{14b} |
| @chapter GNAT Project Manager |
| |
| |
| @menu |
| * Introduction:: |
| * Building With Projects:: |
| * Organizing Projects into Subsystems:: |
| * Scenarios in Projects:: |
| * Library Projects:: |
| * Project Extension:: |
| * Aggregate Projects:: |
| * Aggregate Library Projects:: |
| * Project File Reference:: |
| |
| @end menu |
| |
| @node Introduction,Building With Projects,,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager introduction}@anchor{14c}@anchor{gnat_ugn/gnat_project_manager gnat-project-manager-introduction}@anchor{14d} |
| @section Introduction |
| |
| |
| This chapter describes GNAT's @emph{Project Manager}, a facility that allows |
| you to manage complex builds involving a number of source files, directories, |
| and options for different system configurations. In particular, |
| project files allow you to specify: |
| |
| |
| @itemize * |
| |
| @item |
| The directory or set of directories containing the source files, and/or the |
| names of the specific source files themselves |
| |
| @item |
| The directory in which the compiler's output |
| (@code{ALI} files, object files, tree files, etc.) is to be placed |
| |
| @item |
| The directory in which the executable programs are to be placed |
| |
| @item |
| Switch settings for any of the project-enabled tools; |
| you can apply these settings either globally or to individual compilation units. |
| |
| @item |
| The source files containing the main subprogram(s) to be built |
| |
| @item |
| The source programming language(s) |
| |
| @item |
| Source file naming conventions; you can specify these either globally or for |
| individual compilation units (see @ref{14e,,Naming Schemes}). |
| |
| @item |
| Change any of the above settings depending on external values, thus enabling |
| the reuse of the projects in various @strong{scenarios} (see @ref{14f,,Scenarios in Projects}). |
| |
| @item |
| Automatically build libraries as part of the build process |
| (see @ref{8a,,Library Projects}). |
| @end itemize |
| |
| Project files are written in a syntax close to that of Ada, using familiar |
| notions such as packages, context clauses, declarations, default values, |
| assignments, and inheritance (see @ref{150,,Project File Reference}). |
| |
| Project files can be built hierarchically from other project files, simplifying |
| complex system integration and project reuse (see @ref{151,,Organizing Projects into Subsystems}). |
| |
| |
| @itemize * |
| |
| @item |
| One project can import other projects containing needed source files. |
| More generally, the Project Manager lets you structure large development |
| efforts into hierarchical subsystems, where build decisions are delegated |
| to the subsystem level, and thus different compilation environments |
| (switch settings) used for different subsystems. |
| |
| @item |
| 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 |
| (see @ref{152,,Project Extension}). |
| @end itemize |
| |
| Several tools support project files, generally in addition to specifying |
| the information on the command line itself). They share common switches |
| to control the loading of the project (in particular |
| @code{-P@emph{projectfile}} and |
| @code{-X@emph{vbl}=@emph{value}}). |
| |
| The Project Manager supports a wide range of development strategies, |
| for systems of all sizes. Here are some typical practices that are |
| easily handled: |
| |
| |
| @itemize * |
| |
| @item |
| Using a common set of source files and generating object files in different |
| directories via different switch settings. It can be used for instance, for |
| generating separate sets of object files for debugging and for production. |
| |
| @item |
| Using a mostly-shared set of source files with different versions of |
| some units or subunits. It can be used for instance, for grouping and hiding |
| all OS dependencies in a small number of implementation units. |
| @end itemize |
| |
| Project files can be used 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 tool |
| that might be used by the developers. |
| |
| The various sections below introduce the different concepts related to |
| projects. Each section starts with examples and use cases, and then goes into |
| the details of related project file capabilities. |
| |
| @node Building With Projects,Organizing Projects into Subsystems,Introduction,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager building-with-projects}@anchor{153}@anchor{gnat_ugn/gnat_project_manager id2}@anchor{154} |
| @section Building With Projects |
| |
| |
| In its simplest form, a unique project is used to build a single executable. |
| This section concentrates on such a simple setup. Later sections will extend |
| this basic model to more complex setups. |
| |
| The following concepts are the foundation of project files, and will be further |
| detailed later in this documentation. They are summarized here as a reference. |
| |
| |
| @table @asis |
| |
| @item @strong{Project file}: |
| |
| A text file using an Ada-like syntax, generally using the @code{.gpr} |
| extension. It defines build-related characteristics of an application. |
| The characteristics include the list of sources, the location of those |
| sources, the location for the generated object files, the name of |
| the main program, and the options for the various tools involved in the |
| build process. |
| |
| @item @strong{Project attribute}: |
| |
| A specific project characteristic is defined by an attribute clause. Its |
| value is a string or a sequence of strings. All settings in a project |
| are defined through a list of predefined attributes with precise |
| semantics. See @ref{155,,Attributes}. |
| |
| @item @strong{Package in a project}: |
| |
| Global attributes are defined at the top level of a project. |
| Attributes affecting specific tools are grouped in a |
| package whose name is related to tool's function. The most common |
| packages are @cite{Builder}, @cite{Compiler}, @cite{Binder}, |
| and @cite{Linker}. See @ref{156,,Packages}. |
| |
| @item @strong{Project variables}: |
| |
| In addition to attributes, a project can use variables to store intermediate |
| values and avoid duplication in complex expressions. It can be initialized |
| with a value coming from the environment. |
| A frequent use of variables is to define scenarios. |
| See @ref{157,,External Values}, @ref{14f,,Scenarios in Projects}, and @ref{158,,Variables}. |
| |
| @item @strong{Source files} and @strong{source directories}: |
| |
| A source file is associated with a language through a naming convention. For |
| instance, @cite{foo.c} is typically the name of a C source file; |
| @cite{bar.ads} or @cite{bar.1.ada} are two common naming conventions for a |
| file containing an Ada spec. A compilation unit is often composed of a main |
| source file and potentially several auxiliary ones, such as header files in C. |
| The naming conventions can be user defined @ref{14e,,Naming Schemes}, and will |
| drive the builder to call the appropriate compiler for the given source file. |
| Source files are searched for in the source directories associated with the |
| project through the @strong{Source_Dirs} attribute. By default, all the files (in |
| these source directories) following the naming conventions associated with the |
| declared languages are considered to be part of the project. It is also |
| possible to limit the list of source files using the @strong{Source_Files} or |
| @strong{Source_List_File} attributes. Note that those last two attributes only |
| accept basenames with no directory information. |
| |
| @item @strong{Object files} and @strong{object directory}: |
| |
| An object file is an intermediate file produced by the compiler from a |
| compilation unit. It is used by post-compilation tools to produce |
| final executables or libraries. Object files produced in the context of |
| a given project are stored in a single directory that can be specified by the |
| @strong{Object_Dir} attribute. In order to store objects in |
| two or more object directories, the system must be split into |
| distinct subsystems with their own project file. |
| @end table |
| |
| The following subsections introduce gradually all the attributes of interest |
| for simple build needs. Here is the simple setup that will be used in the |
| following examples. |
| |
| The Ada source files @code{pack.ads}, @code{pack.adb}, and @code{proc.adb} are in |
| the @code{common/} directory. The file @code{proc.adb} contains an Ada main |
| subprogram @cite{Proc} that @emph{with}s package @cite{Pack}. We want to compile |
| these source files with the switch |
| @emph{-O2}, and put the resulting files in |
| the directory @code{obj/}. |
| |
| @example |
| common/ |
| pack.ads |
| pack.adb |
| proc.adb |
| common/obj/ |
| proc.ali, proc.o pack.ali, pack.o |
| @end example |
| |
| Our project is to be called @emph{Build}. The name of the |
| file is the name of the project (case-insensitive) with the |
| @code{.gpr} extension, therefore the project file name is @code{build.gpr}. This |
| is not mandatory, but a warning is issued when this convention is not followed. |
| |
| This is a very simple example, and as stated above, a single project |
| file is enough for it. We will thus create a new file, that for now |
| should contain the following code: |
| |
| @example |
| project Build is |
| end Build; |
| @end example |
| |
| @menu |
| * Source Files and Directories:: |
| * Duplicate Sources in Projects:: |
| * Object and Exec Directory:: |
| * Main Subprograms:: |
| * Tools Options in Project Files:: |
| * Compiling with Project Files:: |
| * Executable File Names:: |
| * Avoid Duplication With Variables:: |
| * Naming Schemes:: |
| * Installation:: |
| * Distributed support:: |
| |
| @end menu |
| |
| @node Source Files and Directories,Duplicate Sources in Projects,,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager id3}@anchor{159}@anchor{gnat_ugn/gnat_project_manager source-files-and-directories}@anchor{15a} |
| @subsection Source Files and Directories |
| |
| |
| When you create a new project, the first thing to describe is how to find the |
| corresponding source files. These are the only settings that are needed by all |
| the tools that will use this project (builder, compiler, binder and linker for |
| the compilation, IDEs to edit the source files,...). |
| |
| @geindex Source directories (GNAT Project Manager) |
| |
| The first step is to declare the source directories, which are the directories |
| to be searched to find source files. In the case of the example, |
| the @code{common} directory is the only source directory. |
| |
| @geindex Source_Dirs (GNAT Project Manager) |
| |
| There are several ways of defining source directories: |
| |
| |
| @itemize * |
| |
| @item |
| When the attribute @strong{Source_Dirs} is not used, a project contains a |
| single source directory which is the one where the project file itself |
| resides. In our example, if @code{build.gpr} is placed in the @code{common} |
| directory, the project has the needed implicit source directory. |
| |
| @item |
| The attribute @strong{Source_Dirs} can be set to a list of path names, one |
| for each of the source directories. Such paths can either be absolute |
| names (for instance @code{"/usr/local/common/"} on UNIX), or relative to the |
| directory in which the project file resides (for instance "." if |
| @code{build.gpr} is inside @code{common/}, or "common" if it is one level up). |
| Each of the source directories must exist and be readable. |
| |
| @geindex portability of path names (GNAT Project Manager) |
| |
| The syntax for directories is platform specific. For portability, however, |
| the project manager will always properly translate UNIX-like path names to |
| the native format of the specific platform. For instance, when the same |
| project file is to be used both on Unix and Windows, "/" should be used as |
| the directory separator rather than "\". |
| |
| @item |
| The attribute @strong{Source_Dirs} can automatically include subdirectories |
| using a special syntax inspired by some UNIX shells. If any of the paths in |
| the list ends with "@code{**}", then that path and all its subdirectories |
| (recursively) are included in the list of source directories. For instance, |
| @code{**} and @code{./**} represent the complete directory tree rooted at |
| the directory in which the project file resides. |
| |
| @geindex Source directories (GNAT Project Manager) |
| |
| @geindex Excluded_Source_Dirs (GNAT Project Manager) |
| |
| When using that construct, it can sometimes be convenient to also use the |
| attribute @strong{Excluded_Source_Dirs}, which is also a list of paths. Each entry |
| specifies a directory whose immediate content, not including subdirs, is to |
| be excluded. It is also possible to exclude a complete directory subtree |
| using the "**" notation. |
| |
| @geindex Ignore_Source_Sub_Dirs (GNAT Project Manager) |
| |
| It is often desirable to remove, from the source directories, directory |
| subtrees rooted at some subdirectories. An example is the subdirectories |
| created by a Version Control System such as Subversion that creates directory |
| subtrees rooted at subdirectories ".svn". To do that, attribute |
| @strong{Ignore_Source_Sub_Dirs} can be used. It specifies the list of simple |
| file names for the roots of these undesirable directory subtrees. |
| |
| @example |
| for Source_Dirs use ("./**"); |
| for Ignore_Source_Sub_Dirs use (".svn"); |
| @end example |
| @end itemize |
| |
| When applied to the simple example, and because we generally prefer to have |
| the project file at the toplevel directory rather than mixed with the sources, |
| we will create the following file |
| |
| @example |
| build.gpr |
| project Build is |
| for Source_Dirs use ("common"); -- <<<< |
| end Build; |
| @end example |
| |
| Once source directories have been specified, one may need to indicate |
| source files of interest. By default, all source files present in the source |
| directories are considered by the project manager. When this is not desired, |
| it is possible to specify the list of sources to consider explicitly. |
| In such a case, only source file base names are indicated and not |
| their absolute or relative path names. The project manager is in charge of |
| locating the specified source files in the specified source directories. |
| |
| |
| @itemize * |
| |
| @item |
| By default, the project manager searches for all source files of all |
| specified languages in all the source directories. |
| |
| Since the project manager was initially developed for Ada environments, the |
| default language is usually Ada and the above project file is complete: it |
| defines without ambiguity the sources composing the project: that is to say, |
| all the sources in subdirectory "common" for the default language (Ada) using |
| the default naming convention. |
| |
| @geindex Languages (GNAT Project Manager) |
| |
| However, when compiling a multi-language application, or a pure C |
| application, the project manager must be told which languages are of |
| interest, which is done by setting the @strong{Languages} attribute to a list of |
| strings, each of which is the name of a language. |
| |
| @geindex Naming scheme (GNAT Project Manager) |
| |
| Even when using only Ada, the default naming might not be suitable. Indeed, |
| how does the project manager recognizes an "Ada file" from any other |
| file? Project files can describe the naming scheme used for source files, |
| and override the default (see @ref{14e,,Naming Schemes}). The default is the |
| standard GNAT extension (@code{.adb} for bodies and @code{.ads} for |
| specs), which is what is used in our example, explaining why no naming scheme |
| is explicitly specified. |
| See @ref{14e,,Naming Schemes}. |
| |
| @geindex Source_Files (GNAT Project Manager) |
| |
| @item |
| @cite{Source_Files}. |
| In some cases, source directories might contain files that should not be |
| included in a project. One can specify the explicit list of file names to |
| be considered through the @strong{Source_Files} attribute. |
| When this attribute is defined, instead of looking at every file in the |
| source directories, the project manager takes only those names into |
| consideration reports errors if they cannot be found in the source |
| directories or does not correspond to the naming scheme. |
| |
| @item |
| For various reasons, it is sometimes useful to have a project with no |
| sources (most of the time because the attributes defined in the project |
| file will be reused in other projects, as explained in |
| @ref{151,,Organizing Projects into Subsystems}. To do this, the attribute |
| @emph{Source_Files} is set to the empty list, i.e. @cite{()}. Alternatively, |
| @emph{Source_Dirs} can be set to the empty list, with the same |
| result. |
| |
| @geindex Source_List_File (GNAT Project Manager) |
| |
| @item |
| @cite{Source_List_File}. |
| If there is a great number of files, it might be more convenient to use |
| the attribute @strong{Source_List_File}, which specifies the full path of a file. |
| This file must contain a list of source file names (one per line, no |
| directory information) that are searched as if they had been defined |
| through @emph{Source_Files}. Such a file can easily be created through |
| external tools. |
| |
| A warning is issued if both attributes @cite{Source_Files} and |
| @cite{Source_List_File} are given explicit values. In this case, the |
| attribute @cite{Source_Files} prevails. |
| |
| @geindex Excluded_Source_Files (GNAT Project Manager) |
| |
| @geindex Locally_Removed_Files (GNAT Project Manager) |
| |
| @geindex Excluded_Source_List_File (GNAT Project Manager) |
| |
| @item |
| @cite{Excluded_Source_Files}. |
| Specifying an explicit list of files is not always convenient.It might be |
| more convenient to use the default search rules with specific exceptions. |
| This can be done thanks to the attribute @strong{Excluded_Source_Files} |
| (or its synonym @strong{Locally_Removed_Files}). |
| Its value is the list of file names that should not be taken into account. |
| This attribute is often used when extending a project, |
| see @ref{152,,Project Extension}. A similar attribute |
| @strong{Excluded_Source_List_File} plays the same |
| role but takes the name of file containing file names similarly to |
| @cite{Source_List_File}. |
| @end itemize |
| |
| In most simple cases, such as the above example, the default source file search |
| behavior provides the expected result, and we do not need to add anything after |
| setting @cite{Source_Dirs}. The project manager automatically finds |
| @code{pack.ads}, @code{pack.adb}, and @code{proc.adb} as source files of the |
| project. |
| |
| Note that by default a warning is issued when a project has no sources attached |
| to it and this is not explicitly indicated in the project file. |
| |
| @node Duplicate Sources in Projects,Object and Exec Directory,Source Files and Directories,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager duplicate-sources-in-projects}@anchor{15b}@anchor{gnat_ugn/gnat_project_manager id4}@anchor{15c} |
| @subsection Duplicate Sources in Projects |
| |
| |
| If the order of the source directories is known statically, that is if |
| @cite{"/**"} is not used in the string list @cite{Source_Dirs}, then there may |
| be several files with the same name sitting in different directories of the |
| project. In this case, only the file in the first directory is considered as a |
| source of the project and the others are hidden. If @cite{"/**"} is used in the |
| string list @cite{Source_Dirs}, it is an error to have several files with the |
| same name in the same directory @cite{"/**"} subtree, since there would be an |
| ambiguity as to which one should be used. However, two files with the same name |
| may exist in two single directories or directory subtrees. In this case, the |
| one in the first directory or directory subtree is a source of the project. |
| |
| If there are two sources in different directories of the same @cite{"/**"} |
| subtree, one way to resolve the problem is to exclude the directory of the |
| file that should not be used as a source of the project. |
| |
| @node Object and Exec Directory,Main Subprograms,Duplicate Sources in Projects,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager object-and-exec-directory}@anchor{15d}@anchor{gnat_ugn/gnat_project_manager id5}@anchor{15e} |
| @subsection Object and Exec Directory |
| |
| |
| The next step when writing a project is to indicate where the compiler should |
| put the object files. In fact, the compiler and other tools might create |
| several different kind of files (for GNAT, there is the object file and the ALI |
| file for instance). One of the important concepts in projects is that most |
| tools may consider source directories as read-only and do not attempt to create |
| new or temporary files there. Instead, all files are created in the object |
| directory. It is of course not true for project-aware IDEs, whose purpose it is |
| to create the source files. |
| |
| @geindex Object_Dir (GNAT Project Manager) |
| |
| The object directory is specified through the @strong{Object_Dir} attribute. |
| Its value is the path to the object directory, either absolute or |
| relative to the directory containing the project file. This |
| directory must already exist and be readable and writable, although |
| some tools have a switch to create the directory if needed (See |
| the switch @cite{-p} for @emph{gprbuild}). |
| |
| If the attribute @cite{Object_Dir} is not specified, it defaults to |
| the project directory, that is the directory containing the project file. |
| |
| For our example, we can specify the object dir in this way: |
| |
| @example |
| project Build is |
| for Source_Dirs use ("common"); |
| for Object_Dir use "obj"; -- <<<< |
| end Build; |
| @end example |
| |
| As mentioned earlier, there is a single object directory per project. As a |
| result, if you have an existing system where the object files are spread across |
| several directories, you can either move all of them into the same directory if |
| you want to build it with a single project file, or study the section on |
| subsystems (see @ref{151,,Organizing Projects into Subsystems}) to see how each |
| separate object directory can be associated with one of the subsystems |
| constituting the application. |
| |
| When the @emph{linker} is called, it usually creates an executable. By |
| default, this executable is placed in the object directory of the project. It |
| might be convenient to store it in its own directory. |
| |
| @geindex Exec_Dir (GNAT Project Manager) |
| |
| This can be done through the @cite{Exec_Dir} attribute, which, like |
| @emph{Object_Dir} contains a single absolute or relative path and must point to |
| an existing and writable directory, unless you ask the tool to create it on |
| your behalf. When not specified, It defaults to the object directory and |
| therefore to the project file's directory if neither @emph{Object_Dir} nor |
| @emph{Exec_Dir} was specified. |
| |
| In the case of the example, let's place the executable in the root |
| of the hierarchy, ie the same directory as @code{build.gpr}. Hence |
| the project file is now |
| |
| @example |
| project Build is |
| for Source_Dirs use ("common"); |
| for Object_Dir use "obj"; |
| for Exec_Dir use "."; -- <<<< |
| end Build; |
| @end example |
| |
| @node Main Subprograms,Tools Options in Project Files,Object and Exec Directory,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager id6}@anchor{15f}@anchor{gnat_ugn/gnat_project_manager main-subprograms}@anchor{160} |
| @subsection Main Subprograms |
| |
| |
| In the previous section, executables were mentioned. The project manager needs |
| to be taught what they are. In a project file, an executable is indicated by |
| pointing to the source file of a main subprogram. In C this is the file that |
| contains the @cite{main} function, and in Ada the file that contains the main |
| unit. |
| |
| There can be any number of such main files within a given project, and thus |
| several executables can be built in the context of a single project file. Of |
| course, one given executable might not (and in fact will not) need all the |
| source files referenced by the project. As opposed to other build environments |
| such as @emph{makefile}, one does not need to specify the list of |
| dependencies of each executable, the project-aware builder knows enough of the |
| semantics of the languages to build and link only the necessary elements. |
| |
| @geindex Main (GNAT Project Manager) |
| |
| The list of main files is specified via the @strong{Main} attribute. It contains |
| a list of file names (no directories). If a project defines this |
| attribute, it is not necessary to identify main files on the |
| command line when invoking a builder, and editors like |
| @emph{GPS} will be able to create extra menus to spawn or debug the |
| corresponding executables. |
| |
| @example |
| project Build is |
| for Source_Dirs use ("common"); |
| for Object_Dir use "obj"; |
| for Exec_Dir use "."; |
| for Main use ("proc.adb"); -- <<<< |
| end Build; |
| @end example |
| |
| If this attribute is defined in the project, then spawning the builder |
| with a command such as |
| |
| @example |
| gprbuild -Pbuild |
| @end example |
| |
| automatically builds all the executables corresponding to the files |
| listed in the @emph{Main} attribute. It is possible to specify one |
| or more executables on the command line to build a subset of them. |
| |
| @node Tools Options in Project Files,Compiling with Project Files,Main Subprograms,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager tools-options-in-project-files}@anchor{161}@anchor{gnat_ugn/gnat_project_manager id7}@anchor{162} |
| @subsection Tools Options in Project Files |
| |
| |
| We now have a project file that fully describes our environment, and can be |
| used to build the application with a simple @emph{gprbuild} command as seen |
| in the previous section. In fact, the empty project we showed immediately at |
| the beginning (with no attribute at all) could already fulfill that need if it |
| was put in the @code{common} directory. |
| |
| Of course, we might want more control. This section shows you how to specify |
| the compilation switches that the various tools involved in the building of the |
| executable should use. |
| |
| @geindex command line length (GNAT Project Manager) |
| |
| Since source names and locations are described in the project file, it is not |
| necessary to use switches on the command line for this purpose (switches such |
| as -I for gcc). This removes a major source of command line length overflow. |
| Clearly, the builders will have to communicate this information one way or |
| another to the underlying compilers and tools they call but they usually use |
| response files for this and thus are not subject to command line overflows. |
| |
| Several tools participate to the creation of an executable: the compiler |
| produces object files from the source files; the binder (in the Ada case) |
| creates a "source" file that takes care, among other things, of elaboration |
| issues and global variable initialization; and the linker gathers everything |
| into a single executable that users can execute. All these tools are known to |
| the project manager and will be called with user defined switches from the |
| project files. However, we need to introduce a new project file concept to |
| express the switches to be used for any of the tools involved in the build. |
| |
| @geindex project file packages (GNAT Project Manager) |
| |
| A project file is subdivided into zero or more @strong{packages}, each of which |
| contains the attributes specific to one tool (or one set of tools). Project |
| files use an Ada-like syntax for packages. Package names permitted in project |
| files are restricted to a predefined set (see @ref{156,,Packages}), and the contents |
| of packages are limited to a small set of constructs and attributes |
| (see @ref{155,,Attributes}). |
| |
| Our example project file can be extended with the following empty packages. At |
| this stage, they could all be omitted since they are empty, but they show which |
| packages would be involved in the build process. |
| |
| @example |
| project Build is |
| for Source_Dirs use ("common"); |
| for Object_Dir use "obj"; |
| for Exec_Dir use "."; |
| for Main use ("proc.adb"); |
| |
| package Builder is --<<< for gprbuild |
| end Builder; |
| |
| package Compiler is --<<< for the compiler |
| end Compiler; |
| |
| package Binder is --<<< for the binder |
| end Binder; |
| |
| package Linker is --<<< for the linker |
| end Linker; |
| end Build; |
| @end example |
| |
| Let's first examine the compiler switches. As stated in the initial description |
| of the example, we want to compile all files with @emph{-O2}. This is a |
| compiler switch, although it is usual, on the command line, to pass it to the |
| builder which then passes it to the compiler. It is recommended to use directly |
| the right package, which will make the setup easier to understand for other |
| people. |
| |
| Several attributes can be used to specify the switches: |
| |
| @geindex Default_Switches (GNAT Project Manager) |
| |
| @strong{Default_Switches}: |
| |
| @quotation |
| |
| This is the first mention in this manual of an @strong{indexed attribute}. When |
| this attribute is defined, one must supply an @emph{index} in the form of a |
| literal string. |
| In the case of @emph{Default_Switches}, the index is the name of the |
| language to which the switches apply (since a different compiler will |
| likely be used for each language, and each compiler has its own set of |
| switches). The value of the attribute is a list of switches. |
| |
| In this example, we want to compile all Ada source files with the switch |
| @emph{-O2}, and the resulting project file is as follows |
| (only the @cite{Compiler} package is shown): |
| |
| @example |
| package Compiler is |
| for Default_Switches ("Ada") use ("-O2"); |
| end Compiler; |
| @end example |
| @end quotation |
| |
| @geindex Switches (GNAT Project Manager) |
| |
| @strong{Switches}: |
| |
| @quotation |
| |
| In some cases, we might want to use specific switches |
| for one or more files. For instance, compiling @code{proc.adb} might not be |
| possible at high level of optimization because of a compiler issue. |
| In such a case, the @emph{Switches} |
| attribute (indexed on the file name) can be used and will override the |
| switches defined by @emph{Default_Switches}. Our project file would |
| become: |
| |
| @example |
| package Compiler is |
| for Default_Switches ("Ada") |
| use ("-O2"); |
| for Switches ("proc.adb") |
| use ("-O0"); |
| end Compiler; |
| @end example |
| |
| @cite{Switches} may take a pattern as an index, such as in: |
| |
| @example |
| package Compiler is |
| for Default_Switches ("Ada") |
| use ("-O2"); |
| for Switches ("pkg*") |
| use ("-O0"); |
| end Compiler; |
| @end example |
| |
| Sources @code{pkg.adb} and @code{pkg-child.adb} would be compiled with -O0, |
| not -O2. |
| |
| @cite{Switches} can also be given a language name as index instead of a file |
| name in which case it has the same semantics as @emph{Default_Switches}. |
| However, indexes with wild cards are never valid for language name. |
| @end quotation |
| |
| @geindex Local_Configuration_Pragmas (GNAT Project Manager) |
| |
| @strong{Local_Configuration_Pragmas}: |
| |
| @quotation |
| |
| This attribute may specify the path |
| of a file containing configuration pragmas for use by the Ada compiler, |
| such as @cite{pragma Restrictions (No_Tasking)}. These pragmas will be |
| used for all the sources of the project. |
| @end quotation |
| |
| The switches for the other tools are defined in a similar manner through the |
| @strong{Default_Switches} and @strong{Switches} attributes, respectively in the |
| @emph{Builder} package (for @emph{gprbuild}), |
| the @emph{Binder} package (binding Ada executables) and the @emph{Linker} |
| package (for linking executables). |
| |
| @node Compiling with Project Files,Executable File Names,Tools Options in Project Files,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager compiling-with-project-files}@anchor{163}@anchor{gnat_ugn/gnat_project_manager id8}@anchor{164} |
| @subsection Compiling with Project Files |
| |
| |
| Now that our project files are written, let's build our executable. |
| Here is the command we would use from the command line: |
| |
| @example |
| gprbuild -Pbuild |
| @end example |
| |
| This will automatically build the executables specified through the |
| @emph{Main} attribute: for each, it will compile or recompile the |
| sources for which the object file does not exist or is not up-to-date; it |
| will then run the binder; and finally run the linker to create the |
| executable itself. |
| |
| The @emph{gprbuild} builder, can automatically manage C files the |
| same way: create the file @code{utils.c} in the @code{common} directory, |
| set the attribute @emph{Languages} to @cite{"(Ada@comma{} C)"}, and re-run |
| |
| @example |
| gprbuild -Pbuild |
| @end example |
| |
| Gprbuild knows how to recompile the C files and will |
| recompile them only if one of their dependencies has changed. No direct |
| indication on how to build the various elements is given in the |
| project file, which describes the project properties rather than a |
| set of actions to be executed. Here is the invocation of |
| @emph{gprbuild} when building a multi-language program: |
| |
| @example |
| $ gprbuild -Pbuild |
| gcc -c proc.adb |
| gcc -c pack.adb |
| gcc -c utils.c |
| gprbind proc |
| ... |
| gcc proc.o -o proc |
| @end example |
| |
| Notice the three steps described earlier: |
| |
| |
| @itemize * |
| |
| @item |
| The first three gcc commands correspond to the compilation phase. |
| |
| @item |
| The gprbind command corresponds to the post-compilation phase. |
| |
| @item |
| The last gcc command corresponds to the final link. |
| @end itemize |
| |
| @geindex -v option (for GPRbuild) |
| |
| The default output of GPRbuild's execution is kept reasonably simple and easy |
| to understand. In particular, some of the less frequently used commands are not |
| shown, and some parameters are abbreviated. So it is not possible to rerun the |
| effect of the @emph{gprbuild} command by cut-and-pasting its output. |
| GPRbuild's option @cite{-v} provides a much more verbose output which includes, |
| among other information, more complete compilation, post-compilation and link |
| commands. |
| |
| @node Executable File Names,Avoid Duplication With Variables,Compiling with Project Files,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager executable-file-names}@anchor{165}@anchor{gnat_ugn/gnat_project_manager id9}@anchor{166} |
| @subsection Executable File Names |
| |
| |
| @geindex Executable (GNAT Project Manager) |
| |
| By default, the executable name corresponding to a main file is |
| computed from the main source file name. Through the attribute |
| @strong{Builder.Executable}, it is possible to change this default. |
| |
| For instance, instead of building @emph{proc} (or @emph{proc.exe} |
| on Windows), we could configure our project file to build "proc1" |
| (resp proc1.exe) with the following addition: |
| |
| @example |
| project Build is |
| ... -- same as before |
| package Builder is |
| for Executable ("proc.adb") use "proc1"; |
| end Builder |
| end Build; |
| @end example |
| |
| @geindex Executable_Suffix (GNAT Project Manager) |
| |
| Attribute @strong{Executable_Suffix}, when specified, may change the suffix |
| of the executable files, when no attribute @cite{Executable} applies: |
| its value replaces the platform-specific executable suffix. |
| The default executable suffix is empty on UNIX and ".exe" on Windows. |
| |
| It is also possible to change the name of the produced executable by using the |
| command line switch @emph{-o}. When several mains are defined in the project, |
| it is not possible to use the @emph{-o} switch and the only way to change the |
| names of the executable is provided by Attributes @cite{Executable} and |
| @cite{Executable_Suffix}. |
| |
| @node Avoid Duplication With Variables,Naming Schemes,Executable File Names,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager id10}@anchor{167}@anchor{gnat_ugn/gnat_project_manager avoid-duplication-with-variables}@anchor{168} |
| @subsection Avoid Duplication With Variables |
| |
| |
| To illustrate some other project capabilities, here is a slightly more complex |
| project using similar sources and a main program in C: |
| |
| @example |
| project C_Main is |
| for Languages use ("Ada", "C"); |
| for Source_Dirs use ("common"); |
| for Object_Dir use "obj"; |
| for Main use ("main.c"); |
| package Compiler is |
| C_Switches := ("-pedantic"); |
| for Default_Switches ("C") use C_Switches; |
| for Default_Switches ("Ada") use ("-gnaty"); |
| for Switches ("main.c") use C_Switches & ("-g"); |
| end Compiler; |
| end C_Main; |
| @end example |
| |
| This project has many similarities with the previous one. |
| As expected, its @cite{Main} attribute now refers to a C source. |
| The attribute @emph{Exec_Dir} is now omitted, thus the resulting |
| executable will be put in the directory @code{obj}. |
| |
| The most noticeable difference is the use of a variable in the |
| @emph{Compiler} package to store settings used in several attributes. |
| This avoids text duplication, and eases maintenance (a single place to |
| modify if we want to add new switches for C files). We will revisit |
| the use of variables in the context of scenarios (see @ref{14f,,Scenarios in Projects}). |
| |
| In this example, we see how the file @code{main.c} can be compiled with |
| the switches used for all the other C files, plus @emph{-g}. |
| In this specific situation the use of a variable could have been |
| replaced by a reference to the @cite{Default_Switches} attribute: |
| |
| @example |
| for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g"); |
| @end example |
| |
| Note the tick (@emph{'}) used to refer to attributes defined in a package. |
| |
| Here is the output of the GPRbuild command using this project: |
| |
| @example |
| $ gprbuild -Pc_main |
| gcc -c -pedantic -g main.c |
| gcc -c -gnaty proc.adb |
| gcc -c -gnaty pack.adb |
| gcc -c -pedantic utils.c |
| gprbind main.bexch |
| ... |
| gcc main.o -o main |
| @end example |
| |
| The default switches for Ada sources, |
| the default switches for C sources (in the compilation of @code{lib.c}), |
| and the specific switches for @code{main.c} have all been taken into |
| account. |
| |
| @node Naming Schemes,Installation,Avoid Duplication With Variables,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager id11}@anchor{169}@anchor{gnat_ugn/gnat_project_manager naming-schemes}@anchor{14e} |
| @subsection Naming Schemes |
| |
| |
| Sometimes an Ada software system is ported from one compilation environment to |
| another (say GNAT), and the file are not named using 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 @strong{Naming} package of your project file. |
| |
| The naming scheme has two distinct goals for the project manager: it |
| allows finding of source files when searching in the source |
| directories, and given a source file name it makes it possible to guess |
| the associated language, and thus the compiler to use. |
| |
| Note that the use by the Ada compiler of pragmas Source_File_Name is not |
| supported when using project files. You must use the features described in this |
| paragraph. You can however specify other configuration pragmas. |
| |
| The following attributes can be defined in package @cite{Naming}: |
| |
| @geindex Casing (GNAT Project Manager) |
| |
| @strong{Casing}: |
| |
| @quotation |
| |
| Its value must be one of @cite{"lowercase"} (the default if |
| unspecified), @cite{"uppercase"} or @cite{"mixedcase"}. It describes the |
| casing of file names with regards to the Ada unit name. Given an Ada unit |
| My_Unit, the file name will respectively be @code{my_unit.adb} (lowercase), |
| @code{MY_UNIT.ADB} (uppercase) or @code{My_Unit.adb} (mixedcase). |
| On Windows, file names are case insensitive, so this attribute is |
| irrelevant. |
| @end quotation |
| |
| @geindex Dot_Replacement (GNAT Project Manager) |
| |
| @strong{Dot_Replacement}: |
| |
| @quotation |
| |
| This attribute specifies the string that should replace the "." in unit |
| names. Its default value is @cite{"-"} so that a unit |
| @cite{Parent.Child} is expected to be found in the file |
| @code{parent-child.adb}. The replacement string must satisfy the following |
| requirements to avoid ambiguities in the naming scheme: |
| |
| |
| @itemize * |
| |
| @item |
| It must not be empty |
| |
| @item |
| It cannot start or end with an alphanumeric character |
| |
| @item |
| It cannot be a single underscore |
| |
| @item |
| It cannot start with an underscore followed by an alphanumeric |
| |
| @item |
| It cannot contain a dot @cite{'.'} except if the entire string is @cite{"."} |
| @end itemize |
| @end quotation |
| |
| @geindex Spec_Suffix (GNAT Project Manager) |
| |
| @geindex Specification_Suffix (GNAT Project Manager) |
| |
| @strong{Spec_Suffix} and @strong{Specification_Suffix}: |
| |
| @quotation |
| |
| For Ada, these attributes give the suffix used in file names that contain |
| specifications. For other languages, they give the extension for files |
| that contain declaration (header files in C for instance). The attribute |
| is indexed on the language. |
| The two attributes are equivalent, but the latter is obsolescent. |
| |
| If the value of the attribute is the empty string, it indicates to the |
| Project Manager that the only specifications/header files for the language |
| are those specified with attributes @cite{Spec} or |
| @cite{Specification_Exceptions}. |
| |
| If @cite{Spec_Suffix ("Ada")} is not specified, then the default is |
| @cite{".ads"}. |
| |
| A non empty value must satisfy the following requirements: |
| |
| |
| @itemize * |
| |
| @item |
| It must include at least one dot |
| |
| @item |
| If @cite{Dot_Replacement} is a single dot, then it cannot include |
| more than one dot. |
| @end itemize |
| @end quotation |
| |
| @geindex Body_Suffix (GNAT Project Manager) |
| |
| @geindex Implementation_Suffix (GNAT Project Manager) |
| |
| @strong{Body_Suffix} and @strong{Implementation_Suffix}: |
| |
| @quotation |
| |
| These attributes give the extension used for file names that contain |
| code (bodies in Ada). They are indexed on the language. The second |
| version is obsolescent and fully replaced by the first attribute. |
| |
| For each language of a project, one of these two attributes need to be |
| specified, either in the project itself or in the configuration project file. |
| |
| If the value of the attribute is the empty string, it indicates to the |
| Project Manager that the only source files for the language |
| are those specified with attributes @cite{Body} or |
| @cite{Implementation_Exceptions}. |
| |
| These attributes must satisfy the same requirements as @cite{Spec_Suffix}. |
| In addition, they must be different from any of the values in |
| @cite{Spec_Suffix}. |
| If @cite{Body_Suffix ("Ada")} is not specified, then the default is |
| @cite{".adb"}. |
| |
| If @cite{Body_Suffix ("Ada")} and @cite{Spec_Suffix ("Ada")} end with the |
| same string, then a file name that ends with the longest of these two |
| suffixes will be a body if the longest suffix is @cite{Body_Suffix ("Ada")} |
| or a spec if the longest suffix is @cite{Spec_Suffix ("Ada")}. |
| |
| If the suffix does not start with a '.', a file with a name exactly equal to |
| the suffix will also be part of the project (for instance if you define the |
| suffix as @cite{Makefile.in}, a file called @code{Makefile.in} will be part |
| of the project. This capability is usually not interesting when building. |
| However, it might become useful when a project is also used to |
| find the list of source files in an editor, like the GNAT Programming System |
| (GPS). |
| @end quotation |
| |
| @geindex Separate_Suffix (GNAT Project Manager) |
| |
| @strong{Separate_Suffix}: |
| |
| @quotation |
| |
| This attribute is specific to Ada. It denotes the suffix used in file names |
| that contain separate bodies. If it is not specified, then it defaults to |
| same value as @cite{Body_Suffix ("Ada")}. |
| |
| The value of this attribute cannot be the empty string. |
| |
| Otherwise, the same rules apply as for the |
| @cite{Body_Suffix} attribute. The only accepted index is "Ada". |
| @end quotation |
| |
| @strong{Spec} or @strong{Specification}: |
| |
| @quotation |
| |
| @geindex Spec (GNAT Project Manager) |
| |
| @geindex Specification (GNAT Project Manager) |
| |
| This attribute @cite{Spec} can be used to define the source file name for a |
| given Ada compilation unit's spec. The index is the literal name of the Ada |
| unit (case insensitive). The value is the literal base name of the file that |
| contains this unit's spec (case sensitive or insensitive depending on the |
| operating system). This attribute allows the definition of exceptions to the |
| general naming scheme, in case some files do not follow the usual |
| convention. |
| |
| When a source file contains several units, the relative position of the unit |
| can be indicated. The first unit in the file is at position 1 |
| |
| @example |
| for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; |
| for Spec ("top") use "foo.a" at 1; |
| for Spec ("foo") use "foo.a" at 2; |
| @end example |
| @end quotation |
| |
| @geindex Body (GNAT Project Manager) |
| |
| @geindex Implementation (GNAT Project Manager) |
| |
| @strong{Body} or @strong{Implementation}: |
| |
| @quotation |
| |
| These attribute play the same role as @emph{Spec} for Ada bodies. |
| @end quotation |
| |
| @geindex Specification_Exceptions (GNAT Project Manager) |
| |
| @geindex Implementation_Exceptions (GNAT Project Manager) |
| |
| @strong{Specification_Exceptions} and @strong{Implementation_Exceptions}: |
| |
| @quotation |
| |
| These attributes define exceptions to the naming scheme for languages |
| other than Ada. They are indexed on the language name, and contain |
| a list of file names respectively for headers and source code. |
| @end quotation |
| |
| For example, the following package models the Apex file naming rules: |
| |
| @example |
| package Naming is |
| for Casing use "lowercase"; |
| for Dot_Replacement use "."; |
| for Spec_Suffix ("Ada") use ".1.ada"; |
| for Body_Suffix ("Ada") use ".2.ada"; |
| end Naming; |
| @end example |
| |
| @node Installation,Distributed support,Naming Schemes,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager id12}@anchor{16a}@anchor{gnat_ugn/gnat_project_manager installation}@anchor{16b} |
| @subsection Installation |
| |
| |
| After building an application or a library it is often required to |
| install it into the development environment. For instance this step is |
| required if the library is to be used by another application. |
| The @emph{gprinstall} tool provides an easy way to install |
| libraries, executable or object code generated during the build. The |
| @strong{Install} package can be used to change the default locations. |
| |
| The following attributes can be defined in package @cite{Install}: |
| |
| @geindex Active (GNAT Project Manager) |
| |
| |
| @table @asis |
| |
| @item @strong{Active} |
| |
| Whether the project is to be installed, values are @cite{true} |
| (default) or @cite{false}. |
| @end table |
| |
| @geindex Artifacts (GNAT Project Manager) |
| |
| @strong{Artifacts} |
| |
| @quotation |
| |
| An array attribute to declare a set of files not part of the sources |
| to be installed. The array discriminant is the directory where the |
| file is to be installed. If a relative directory then Prefix (see |
| below) is prepended. Note also that if the same file name occurs |
| multiple time in the attribute list, the last one will be the one |
| installed. |
| @end quotation |
| |
| @geindex Prefix (GNAT Project Manager) |
| |
| @strong{Prefix}: |
| |
| @quotation |
| |
| Root directory for the installation. |
| @end quotation |
| |
| @strong{Exec_Subdir} |
| |
| @quotation |
| |
| Subdirectory of @strong{Prefix} where executables are to be |
| installed. Default is @strong{bin}. |
| @end quotation |
| |
| @strong{Lib_Subdir} |
| |
| @quotation |
| |
| Subdirectory of @strong{Prefix} where directory with the library or object |
| files is to be installed. Default is @strong{lib}. |
| @end quotation |
| |
| @strong{Sources_Subdir} |
| |
| @quotation |
| |
| Subdirectory of @strong{Prefix} where directory with sources is to be |
| installed. Default is @strong{include}. |
| @end quotation |
| |
| @strong{Project_Subdir} |
| |
| @quotation |
| |
| Subdirectory of @strong{Prefix} where the generated project file is to be |
| installed. Default is @strong{share/gpr}. |
| @end quotation |
| |
| @strong{Mode} |
| |
| @quotation |
| |
| The installation mode, it is either @strong{dev} (default) or @strong{usage}. |
| See @strong{gprbuild} user's guide for details. |
| @end quotation |
| |
| @strong{Install_Name} |
| |
| @quotation |
| |
| Specify the name to use for recording the installation. The default is |
| the project name without the extension. |
| @end quotation |
| |
| @node Distributed support,,Installation,Building With Projects |
| @anchor{gnat_ugn/gnat_project_manager id13}@anchor{16c}@anchor{gnat_ugn/gnat_project_manager distributed-support}@anchor{16d} |
| @subsection Distributed support |
| |
| |
| For large projects the compilation time can become a limitation in |
| the development cycle. To cope with that, GPRbuild supports |
| distributed compilation. |
| |
| The following attributes can be defined in package @cite{Remote}: |
| |
| @geindex Root_Dir (GNAT Project Manager) |
| |
| @strong{Root_Dir}: |
| |
| @quotation |
| |
| Root directory of the project's sources. The default value is the |
| project's directory. |
| @end quotation |
| |
| @node Organizing Projects into Subsystems,Scenarios in Projects,Building With Projects,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager organizing-projects-into-subsystems}@anchor{151}@anchor{gnat_ugn/gnat_project_manager id14}@anchor{16e} |
| @section Organizing Projects into Subsystems |
| |
| |
| A @strong{subsystem} is a coherent part of the complete system to be built. It is |
| represented by a set of sources and one single object directory. A system can |
| be composed of a single subsystem when it is simple as we have seen in the |
| first section. Complex systems are usually composed of several interdependent |
| subsystems. A subsystem is dependent on another subsystem if knowledge of the |
| other one is required to build it, and in particular if visibility on some of |
| the sources of this other subsystem is required. Each subsystem is usually |
| represented by its own project file. |
| |
| In this section, the previous example is being extended. Let's assume some |
| sources of our @cite{Build} project depend on other sources. |
| For instance, when building a graphical interface, it is usual to depend upon |
| a graphical library toolkit such as GtkAda. Furthermore, we also need |
| sources from a logging module we had previously written. |
| |
| @menu |
| * Project Dependencies:: |
| * Cyclic Project Dependencies:: |
| * Sharing Between Projects:: |
| * Global Attributes:: |
| |
| @end menu |
| |
| @node Project Dependencies,Cyclic Project Dependencies,,Organizing Projects into Subsystems |
| @anchor{gnat_ugn/gnat_project_manager project-dependencies}@anchor{16f}@anchor{gnat_ugn/gnat_project_manager id15}@anchor{170} |
| @subsection Project Dependencies |
| |
| |
| GtkAda comes with its own project file (appropriately called |
| @code{gtkada.gpr}), and we will assume we have already built a project |
| called @code{logging.gpr} for the logging module. With the information provided |
| so far in @code{build.gpr}, building the application would fail with an error |
| indicating that the gtkada and logging units that are relied upon by the sources |
| of this project cannot be found. |
| |
| This is solved by adding the following @strong{with} clauses at the beginning of our |
| project: |
| |
| @example |
| with "gtkada.gpr"; |
| with "a/b/logging.gpr"; |
| project Build is |
| ... -- as before |
| end Build; |
| @end example |
| |
| @geindex Externally_Built (GNAT Project Manager) |
| |
| When such a project is compiled, @emph{gprbuild} will automatically check |
| the other projects and recompile their sources when needed. It will also |
| recompile the sources from @cite{Build} when needed, and finally create the |
| executable. In some cases, the implementation units needed to recompile a |
| project are not available, or come from some third party and you do not want to |
| recompile it yourself. In this case, set the attribute @strong{Externally_Built} to |
| "true", indicating to the builder that this project can be assumed to be |
| up-to-date, and should not be considered for recompilation. In Ada, if the |
| sources of this externally built project were compiled with another version of |
| the compiler or with incompatible options, the binder will issue an error. |
| |
| The project's @emph{with} clause has several effects. It provides source |
| visibility between projects during the compilation process. It also guarantees |
| that the necessary object files from @cite{Logging} and @cite{GtkAda} are |
| available when linking @cite{Build}. |
| |
| 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 @emph{with} clause identifies |
| project files rather than packages. |
| |
| Each literal string after @emph{with} is the path |
| (absolute or relative) to a project file. The @cite{.gpr} extension is |
| optional, although we recommend adding it. If no extension is specified, |
| and no project file with the @code{.gpr} extension is found, then |
| the file is searched for exactly as written in the @emph{with} clause, |
| that is with no extension. |
| |
| As mentioned above, the path after a @emph{with} has to be a literal |
| string, and you cannot use concatenation, or lookup the value of external |
| variables to change the directories from which a project is loaded. |
| A solution if you need something like this is to use aggregate projects |
| (see @ref{171,,Aggregate Projects}). |
| |
| @geindex project path (GNAT Project Manager) |
| |
| When a relative path or a base name is used, the |
| project files are searched relative to each of the directories in the |
| @strong{project path}. This path includes all the directories found with the |
| following algorithm, in this order; the first matching file is used: |
| |
| |
| @itemize * |
| |
| @item |
| First, the file is searched relative to the directory that contains the |
| current project file. |
| |
| @geindex GPR_PROJECT_PATH_FILE (GNAT Project Manager) |
| |
| @geindex GPR_PROJECT_PATH (GNAT Project Manager) |
| |
| @geindex ADA_PROJECT_PATH (GNAT Project Manager) |
| |
| @item |
| Then it is searched relative to all the directories specified in the |
| environment variables @strong{GPR_PROJECT_PATH_FILE}, |
| @strong{GPR_PROJECT_PATH} and @strong{ADA_PROJECT_PATH} (in that order) if they exist. |
| The value of @strong{GPR_PROJECT_PATH_FILE}, when defined, is the path name of |
| a text file that contains project directory path names, one per line. |
| @strong{GPR_PROJECT_PATH} and @strong{ADA_PROJECT_PATH}, when defined, contain |
| project directory path names separated by directory separators. |
| @strong{ADA_PROJECT_PATH} is used for compatibility, it is recommended to |
| use @strong{GPR_PROJECT_PATH_FILE} or @strong{GPR_PROJECT_PATH}. |
| |
| @item |
| Finally, it is searched relative to the default project directories. |
| Such directories depend on the tool used. The locations searched in the |
| specified order are: |
| |
| |
| @itemize * |
| |
| @item |
| @code{<prefix>/<target>/lib/gnat} if option @emph{--target} is specified |
| |
| @item |
| @code{<prefix>/<target>/share/gpr} if option @emph{--target} is specified |
| |
| @item |
| @code{<prefix>/share/gpr/} |
| |
| @item |
| @code{<prefix>/lib/gnat/} |
| @end itemize |
| |
| In our example, @code{gtkada.gpr} is found in the predefined directory if |
| it was installed at the same root as GNAT. |
| @end itemize |
| |
| Some tools also support extending the project path from the command line, |
| generally through the @emph{-aP}. You can see the value of the project |
| path by using the @emph{gnatls -v} command. |
| |
| Any symbolic link will be fully resolved in the directory of the |
| importing project file before the imported project file is examined. |
| |
| Any source file in the imported project can be used by the sources of the |
| importing project, transitively. |
| Thus if @cite{A} imports @cite{B}, which imports @cite{C}, the sources of |
| @cite{A} may depend on the sources of @cite{C}, even if @cite{A} does not |
| import @cite{C} explicitly. However, this is not recommended, because if |
| and when @cite{B} ceases to import @cite{C}, some sources in @cite{A} will |
| no longer compile. @emph{gprbuild} has a switch @emph{--no-indirect-imports} |
| that will report such indirect dependencies. |
| |
| @cartouche |
| @quotation Note |
| One very important aspect of a project hierarchy is that |
| @strong{a given source can only belong to one project} (otherwise the project manager |
| would not know which settings apply to it and when to recompile it). It means |
| that different project files do not usually share source directories or |
| when they do, they need to specify precisely which project owns which sources |
| using attribute @cite{Source_Files} or equivalent. By contrast, 2 projects |
| can each own a source with the same base file name as long as they live in |
| different directories. The latter is not true for Ada Sources because of the |
| correlation between source files and Ada units. |
| @end quotation |
| @end cartouche |
| |
| @node Cyclic Project Dependencies,Sharing Between Projects,Project Dependencies,Organizing Projects into Subsystems |
| @anchor{gnat_ugn/gnat_project_manager id16}@anchor{172}@anchor{gnat_ugn/gnat_project_manager cyclic-project-dependencies}@anchor{173} |
| @subsection Cyclic Project Dependencies |
| |
| |
| Cyclic dependencies are mostly forbidden: |
| if @cite{A} imports @cite{B} (directly or indirectly) then @cite{B} |
| is not allowed to import @cite{A}. However, there are cases when cyclic |
| dependencies would be beneficial. For these cases, another form of import |
| between projects exists: the @strong{limited with}. A project @cite{A} that |
| imports a project @cite{B} with a straight @emph{with} may also be imported, |
| directly or indirectly, by @cite{B} through a @cite{limited with}. |
| |
| The difference between straight @emph{with} and @cite{limited with} is that |
| the name of a project imported with a @cite{limited with} cannot be used in the |
| project importing it. In particular, its packages cannot be renamed and |
| its variables cannot be referred to. |
| |
| @example |
| with "b.gpr"; |
| with "c.gpr"; |
| project A is |
| for Exec_Dir use B'Exec_Dir; -- ok |
| end A; |
| |
| limited with "a.gpr"; -- Cyclic dependency: A -> B -> A |
| project B is |
| for Exec_Dir use A'Exec_Dir; -- not ok |
| end B; |
| |
| with "d.gpr"; |
| project C is |
| end C; |
| |
| limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A |
| project D is |
| for Exec_Dir use A'Exec_Dir; -- not ok |
| end D; |
| @end example |
| |
| @node Sharing Between Projects,Global Attributes,Cyclic Project Dependencies,Organizing Projects into Subsystems |
| @anchor{gnat_ugn/gnat_project_manager sharing-between-projects}@anchor{174}@anchor{gnat_ugn/gnat_project_manager id17}@anchor{175} |
| @subsection Sharing Between Projects |
| |
| |
| When building an application, it is common to have similar needs in several of |
| the projects corresponding to the subsystems under construction. For instance, |
| they will all have the same compilation switches. |
| |
| As seen before (see @ref{161,,Tools Options in Project Files}), setting compilation |
| switches for all sources of a subsystem is simple: it is just a matter of |
| adding a @cite{Compiler.Default_Switches} attribute to each project files with |
| the same value. Of course, that means duplication of data, and both places need |
| to be changed in order to recompile the whole application with different |
| switches. It can become a real problem if there are many subsystems and thus |
| many project files to edit. |
| |
| There are two main approaches to avoiding this duplication: |
| |
| |
| @itemize * |
| |
| @item |
| Since @code{build.gpr} imports @code{logging.gpr}, we could change it |
| to reference the attribute in Logging, either through a package renaming, |
| or by referencing the attribute. The following example shows both cases: |
| |
| @example |
| project Logging is |
| package Compiler is |
| for Switches ("Ada") |
| use ("-O2"); |
| end Compiler; |
| package Binder is |
| for Switches ("Ada") |
| use ("-E"); |
| end Binder; |
| end Logging; |
| |
| with "logging.gpr"; |
| project Build is |
| package Compiler renames Logging.Compiler; |
| package Binder is |
| for Switches ("Ada") use Logging.Binder'Switches ("Ada"); |
| end Binder; |
| end Build; |
| @end example |
| |
| The solution used for @cite{Compiler} gets the same value for all |
| attributes of the package, but you cannot modify anything from the |
| package (adding extra switches or some exceptions). The second |
| version is more flexible, but more verbose. |
| |
| If you need to refer to the value of a variable in an imported |
| project, rather than an attribute, the syntax is similar but uses |
| a "." rather than an apostrophe. For instance: |
| |
| @example |
| with "imported"; |
| project Main is |
| Var1 := Imported.Var; |
| end Main; |
| @end example |
| |
| @item |
| The second approach is to define the switches in a third project. |
| That project is set up without any sources (so that, as opposed to |
| the first example, none of the project plays a special role), and |
| will only be used to define the attributes. Such a project is |
| typically called @code{shared.gpr}. |
| |
| @example |
| abstract project Shared is |
| for Source_Files use (); -- no sources |
| package Compiler is |
| for Switches ("Ada") |
| use ("-O2"); |
| end Compiler; |
| end Shared; |
| |
| with "shared.gpr"; |
| project Logging is |
| package Compiler renames Shared.Compiler; |
| end Logging; |
| |
| with "shared.gpr"; |
| project Build is |
| package Compiler renames Shared.Compiler; |
| end Build; |
| @end example |
| |
| As for the first example, we could have chosen to set the attributes |
| one by one rather than to rename a package. The reason we explicitly |
| indicate that @cite{Shared} has no sources is so that it can be created |
| in any directory and we are sure it shares no sources with @cite{Build} |
| or @cite{Logging}, which of course would be invalid. |
| |
| @geindex project qualifier (GNAT Project Manager) |
| |
| Note the additional use of the @strong{abstract} qualifier in @code{shared.gpr}. |
| This qualifier is optional, but helps convey the message that we do not |
| intend this project to have sources (see @ref{176,,Qualified Projects} for |
| more qualifiers). |
| @end itemize |
| |
| @node Global Attributes,,Sharing Between Projects,Organizing Projects into Subsystems |
| @anchor{gnat_ugn/gnat_project_manager global-attributes}@anchor{177}@anchor{gnat_ugn/gnat_project_manager id18}@anchor{178} |
| @subsection Global Attributes |
| |
| |
| We have already seen many examples of attributes used to specify a special |
| option of one of the tools involved in the build process. Most of those |
| attributes are project specific. That it to say, they only affect the invocation |
| of tools on the sources of the project where they are defined. |
| |
| There are a few additional attributes that apply to all projects in a |
| hierarchy as long as they are defined on the "main" project. |
| The main project is the project explicitly mentioned on the command-line. |
| The project hierarchy is the "with"-closure of the main project. |
| |
| Here is a list of commonly used global attributes: |
| |
| @geindex Global_Configuration_Pragmas (GNAT Project Manager) |
| |
| @strong{Builder.Global_Configuration_Pragmas}: |
| |
| @quotation |
| |
| This attribute points to a file that contains configuration pragmas |
| to use when building executables. These pragmas apply for all |
| executables built from this project hierarchy. As we have seen before, |
| additional pragmas can be specified on a per-project basis by setting the |
| @cite{Compiler.Local_Configuration_Pragmas} attribute. |
| @end quotation |
| |
| @geindex Global_Compilation_Switches (GNAT Project Manager) |
| |
| @strong{Builder.Global_Compilation_Switches}: |
| |
| @quotation |
| |
| This attribute is a list of compiler switches to use when compiling any |
| source file in the project hierarchy. These switches are used in addition |
| to the ones defined in the @cite{Compiler} package, which only apply to |
| the sources of the corresponding project. This attribute is indexed on |
| the name of the language. |
| @end quotation |
| |
| Using such global capabilities is convenient. It can also lead to unexpected |
| behavior. Especially when several subsystems are shared among different main |
| projects and the different global attributes are not |
| compatible. Note that using aggregate projects can be a safer and more powerful |
| replacement to global attributes. |
| |
| @node Scenarios in Projects,Library Projects,Organizing Projects into Subsystems,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager id19}@anchor{179}@anchor{gnat_ugn/gnat_project_manager scenarios-in-projects}@anchor{14f} |
| @section Scenarios in Projects |
| |
| |
| Various aspects of the projects can be modified based on @strong{scenarios}. These |
| are user-defined modes that change the behavior of a project. Typical |
| examples are the setup of platform-specific compiler options, or the use of |
| a debug and a release mode (the former would activate the generation of debug |
| information, while the second will focus on improving code optimization). |
| |
| Let's enhance our example to support debug and release modes. The issue is to |
| let the user choose what kind of system he is building: use @emph{-g} as |
| compiler switches in debug mode and @emph{-O2} in release mode. We will also |
| set up the projects so that we do not share the same object directory in both |
| modes; otherwise switching from one to the other might trigger more |
| recompilations than needed or mix objects from the two modes. |
| |
| One naive approach is to create two different project files, say |
| @code{build_debug.gpr} and @code{build_release.gpr}, that set the appropriate |
| attributes as explained in previous sections. This solution does not scale |
| well, because in the presence of multiple projects depending on each other, you |
| will also have to duplicate the complete hierarchy and adapt the project files |
| to point to the right copies. |
| |
| @geindex scenarios (GNAT Project Manager) |
| |
| Instead, project files support the notion of scenarios controlled |
| by external values. Such values can come from several sources (in decreasing |
| order of priority): |
| |
| @geindex -X (usage with GNAT Project Manager) |
| |
| |
| @table @asis |
| |
| @item @strong{Command line}: |
| |
| When launching @emph{gprbuild}, the user can pass |
| extra @emph{-X} switches to define the external value. In |
| our case, the command line might look like |
| |
| @example |
| gprbuild -Pbuild.gpr -Xmode=release |
| @end example |
| |
| @item @strong{Environment variables}: |
| |
| When the external value does not come from the command line, it can come from |
| the value of environment variables of the appropriate name. |
| In our case, if an environment variable called "mode" |
| exists, its value will be taken into account. |
| @end table |
| |
| @geindex external (GNAT Project Manager) |
| |
| @strong{External function second parameter}. |
| |
| We now need to get that value in the project. The general form is to use |
| the predefined function @strong{external} which returns the current value of |
| the external. For instance, we could set up the object directory to point to |
| either @code{obj/debug} or @code{obj/release} by changing our project to |
| |
| @example |
| project Build is |
| for Object_Dir use "obj/" & external ("mode", "debug"); |
| ... -- as before |
| end Build; |
| @end example |
| |
| The second parameter to @cite{external} is optional, and is the default |
| value to use if "mode" is not set from the command line or the environment. |
| |
| In order to set the switches according to the different scenarios, other |
| constructs have to be introduced such as typed variables and case constructions. |
| |
| @geindex typed variable (GNAT Project Manager) |
| |
| @geindex case construction (GNAT Project Manager) |
| |
| A @strong{typed variable} is a variable that |
| can take only a limited number of values, similar to an enumeration in Ada. |
| Such a variable can then be used in a @strong{case construction} and create conditional |
| sections in the project. The following example shows how this can be done: |
| |
| @example |
| project Build is |
| type Mode_Type is ("debug", "release"); -- all possible values |
| Mode : Mode_Type := external ("mode", "debug"); -- a typed variable |
| |
| package Compiler is |
| case Mode is |
| when "debug" => |
| for Switches ("Ada") |
| use ("-g"); |
| when "release" => |
| for Switches ("Ada") |
| use ("-O2"); |
| end case; |
| end Compiler; |
| end Build; |
| @end example |
| |
| The project has suddenly grown in size, but has become much more flexible. |
| @cite{Mode_Type} defines the only valid values for the @cite{mode} variable. If |
| any other value is read from the environment, an error is reported and the |
| project is considered as invalid. |
| |
| The @cite{Mode} variable is initialized with an external value |
| defaulting to @cite{"debug"}. This default could be omitted and that would |
| force the user to define the value. Finally, we can use a case construction to set the |
| switches depending on the scenario the user has chosen. |
| |
| Most aspects of the projects can depend on scenarios. The notable exception |
| are project dependencies (@emph{with} clauses), which cannot depend on a scenario. |
| |
| Scenarios work the same way with @strong{project hierarchies}: you can either |
| duplicate a variable similar to @cite{Mode} in each of the project (as long |
| as the first argument to @cite{external} is always the same and the type is |
| the same), or simply set the variable in the @code{shared.gpr} project |
| (see @ref{174,,Sharing Between Projects}). |
| |
| @node Library Projects,Project Extension,Scenarios in Projects,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager library-projects}@anchor{8a}@anchor{gnat_ugn/gnat_project_manager id20}@anchor{17a} |
| @section Library Projects |
| |
| |
| So far, we have seen examples of projects that create executables. However, |
| it is also possible to create libraries instead. A @strong{library} is a specific |
| type of subsystem where, for convenience, objects are grouped together |
| using system-specific means such as archives or windows DLLs. |
| |
| Library projects provide a system- and language-independent way of building |
| both @strong{static} and @strong{dynamic} libraries. They also support the concept of |
| @strong{standalone libraries} (SAL) which offer two significant properties: the |
| elaboration (e.g. initialization) of the library is either automatic or |
| very simple; a change in the |
| implementation part of the library implies minimal post-compilation actions on |
| the complete system and potentially no action at all for the rest of the |
| system in the case of dynamic SALs. |
| |
| There is a restriction on shared library projects: by default, they are only |
| allowed to import other shared library projects. They are not allowed to |
| import non library projects or static library projects. |
| |
| The GNAT Project Manager takes complete care of the library build, rebuild and |
| installation tasks, including recompilation of the source files for which |
| objects do not exist or are not up to date, assembly of the library archive, and |
| installation of the library (i.e., copying associated source, object and |
| @code{ALI} files to the specified location). |
| |
| @menu |
| * Building Libraries:: |
| * Using Library Projects:: |
| * Stand-alone Library Projects:: |
| * Installing a library with project files:: |
| |
| @end menu |
| |
| @node Building Libraries,Using Library Projects,,Library Projects |
| @anchor{gnat_ugn/gnat_project_manager id21}@anchor{17b}@anchor{gnat_ugn/gnat_project_manager building-libraries}@anchor{17c} |
| @subsection Building Libraries |
| |
| |
| Let's enhance our example and transform the @cite{logging} subsystem into a |
| library. In order to do so, a few changes need to be made to |
| @code{logging.gpr}. Some attributes need to be defined: at least |
| @cite{Library_Name} and @cite{Library_Dir}; in addition, some other attributes |
| can be used to specify specific aspects of the library. For readability, it is |
| also recommended (although not mandatory), to use the qualifier @cite{library} |
| in front of the @cite{project} keyword. |
| |
| @geindex Library_Name (GNAT Project Manager) |
| |
| @strong{Library_Name}: |
| |
| @quotation |
| |
| This attribute is the name of the library to be built. There is no |
| restriction on the name of a library imposed by the project manager, except |
| for stand-alone libraries whose names must follow the syntax of Ada |
| identifiers; however, there may be system-specific restrictions on the name. |
| In general, it is recommended to stick to alphanumeric characters (and |
| possibly single underscores) to help portability. |
| @end quotation |
| |
| @geindex Library_Dir (GNAT Project Manager) |
| |
| @strong{Library_Dir}: |
| |
| @quotation |
| |
| This attribute is the path (absolute or relative) of the directory where |
| the library is to be installed. In the process of building a library, |
| the sources are compiled, the object files end up in the explicit or |
| implicit @cite{Object_Dir} directory. When all sources of a library |
| are compiled, some of the compilation artifacts, including the library itself, |
| are copied to the library_dir directory. This directory must exist and be |
| writable. It must also be different from the object directory so that cleanup |
| activities in the Library_Dir do not affect recompilation needs. |
| @end quotation |
| |
| Here is the new version of @code{logging.gpr} that makes it a library: |
| |
| @example |
| library project Logging is -- "library" is optional |
| for Library_Name use "logging"; -- will create "liblogging.a" on Unix |
| for Object_Dir use "obj"; |
| for Library_Dir use "lib"; -- different from object_dir |
| end Logging; |
| @end example |
| |
| Once the above two attributes are defined, the library project is valid and |
| is enough for building a library with default characteristics. |
| Other library-related attributes can be used to change the defaults: |
| |
| @geindex Library_Kind (GNAT Project Manager) |
| |
| @strong{Library_Kind}: |
| |
| @quotation |
| |
| The value of this attribute must be either @cite{"static"}, @cite{"dynamic"} or |
| @cite{"relocatable"} (the latter is a synonym for dynamic). It indicates |
| which kind of library should be built (the default is to build a |
| static library, that is an archive of object files that can potentially |
| be linked into a static executable). When the library is set to be dynamic, |
| a separate image is created that will be loaded independently, usually |
| at the start of the main program execution. Support for dynamic libraries is |
| very platform specific, for instance on Windows it takes the form of a DLL |
| while on GNU/Linux, it is a dynamic elf image whose suffix is usually |
| @code{.so}. Library project files, on the other hand, can be written in |
| a platform independent way so that the same project file can be used to build |
| a library on different operating systems. |
| |
| If you need to build both a static and a dynamic library, it is recommended |
| to use two different object directories, since in some cases some extra code |
| needs to be generated for the latter. For such cases, one can either define |
| two different project files, or a single one that uses scenarios to indicate |
| the various kinds of library to be built and their corresponding object_dir. |
| @end quotation |
| |
| @geindex Library_ALI_Dir (GNAT Project Manager) |
| |
| @strong{Library_ALI_Dir}: |
| |
| @quotation |
| |
| This attribute may be specified to indicate the directory where the ALI |
| files of the library are installed. By default, they are copied into the |
| @cite{Library_Dir} directory, but as for the executables where we have a |
| separate @cite{Exec_Dir} attribute, you might want to put them in a separate |
| directory since there can be hundreds of them. The same restrictions as for |
| the @cite{Library_Dir} attribute apply. |
| @end quotation |
| |
| @geindex Library_Version (GNAT Project Manager) |
| |
| @strong{Library_Version}: |
| |
| @quotation |
| |
| This attribute is platform dependent, and has no effect on Windows. |
| On Unix, it is used only for dynamic libraries as the internal |
| name of the library (the @cite{"soname"}). If the library file name (built |
| from the @cite{Library_Name}) is different from the @cite{Library_Version}, |
| then the library file will be a symbolic link to the actual file whose name |
| will be @cite{Library_Version}. This follows the usual installation schemes |
| for dynamic libraries on many Unix systems. |
| |
| @example |
| project Logging is |
| Version := "1"; |
| for Library_Dir use "lib"; |
| for Library_Name use "logging"; |
| for Library_Kind use "dynamic"; |
| for Library_Version use "liblogging.so." & Version; |
| end Logging; |
| @end example |
| |
| After the compilation, the directory @code{lib} will contain both a |
| @code{libdummy.so.1} library and a symbolic link to it called |
| @code{libdummy.so}. |
| @end quotation |
| |
| @geindex Library_GCC (GNAT Project Manager) |
| |
| @strong{Library_GCC}: |
| |
| @quotation |
| |
| This attribute is the name of the tool to use instead of "gcc" to link shared |
| libraries. A common use of this attribute is to define a wrapper script that |
| accomplishes specific actions before calling gcc (which itself calls the |
| linker to build the library image). |
| @end quotation |
| |
| @geindex Library_Options (GNAT Project Manager) |
| |
| @strong{Library_Options}: |
| |
| @quotation |
| |
| This attribute may be used to specify additional switches (last switches) |
| when linking a shared library. |
| |
| It may also be used to add foreign object files to a static library. |
| Each string in Library_Options is an absolute or relative path of an object |
| file. When a relative path, it is relative to the object directory. |
| @end quotation |
| |
| @geindex Leading_Library_Options (GNAT Project Manager) |
| |
| @strong{Leading_Library_Options}: |
| |
| @quotation |
| |
| This attribute, that is taken into account only by @emph{gprbuild}, may be |
| used to specified leading options (first switches) when linking a shared |
| library. |
| @end quotation |
| |
| @geindex Linker_Options (GNAT Project Manager) |
| |
| @strong{Linker.Linker_Options}: |
| |
| @quotation |
| |
| This attribute specifies additional switches to be given to the linker when |
| linking an executable. It is ignored when defined in the main project and |
| taken into account in all other projects that are imported directly or |
| indirectly. These switches complement the @cite{Linker.Switches} |
| defined in the main project. This is useful when a particular subsystem |
| depends on an external library: adding this dependency as a |
| @cite{Linker_Options} in the project of the subsystem is more convenient than |
| adding it to all the @cite{Linker.Switches} of the main projects that depend |
| upon this subsystem. |
| @end quotation |
| |
| @node Using Library Projects,Stand-alone Library Projects,Building Libraries,Library Projects |
| @anchor{gnat_ugn/gnat_project_manager id22}@anchor{17d}@anchor{gnat_ugn/gnat_project_manager using-library-projects}@anchor{17e} |
| @subsection Using Library Projects |
| |
| |
| When the builder detects that a project file is a library project file, it |
| recompiles all sources of the project that need recompilation and rebuild the |
| library if any of the sources have been recompiled. It then groups all object |
| files into a single file, which is a shared or a static library. This library |
| can later on be linked with multiple executables. Note that the use |
| of shard libraries reduces the size of the final executable and can also reduce |
| the memory footprint at execution time when the library is shared among several |
| executables. |
| |
| @emph{gprbuild also allows to build **multi-language libraries*} when specifying |
| sources from multiple languages. |
| |
| A non-library project can import a library project. When the builder is invoked |
| on the former, the library of the latter is only rebuilt when absolutely |
| necessary. For instance, if a unit of the library is not up-to-date but none of |
| the executables need this unit, then the unit is not recompiled and the library |
| is not reassembled. For instance, let's assume in our example that logging has |
| the following sources: @code{log1.ads}, @code{log1.adb}, @code{log2.ads} and |
| @code{log2.adb}. If @code{log1.adb} has been modified, then the library |
| @code{liblogging} will be rebuilt when compiling all the sources of |
| @cite{Build} only if @code{proc.ads}, @code{pack.ads} or @code{pack.adb} |
| include a @cite{"with Log1"}. |
| |
| To ensure that all the sources in the @cite{Logging} library are |
| up to date, and that all the sources of @cite{Build} are also up to date, |
| the following two commands need to be used: |
| |
| @example |
| gprbuild -Plogging.gpr |
| gprbuild -Pbuild.gpr |
| @end example |
| |
| All @code{ALI} files will also be copied from the object directory to the |
| library directory. To build executables, @emph{gprbuild} will use the |
| library rather than the individual object files. |
| |
| Library projects can also be useful to describe a library that needs to be used |
| but, for some reason, cannot be rebuilt. For instance, it is the case when some |
| of the library sources are not available. Such library projects need to use the |
| @cite{Externally_Built} attribute as in the example below: |
| |
| @example |
| library project Extern_Lib is |
| for Languages use ("Ada", "C"); |
| for Source_Dirs use ("lib_src"); |
| for Library_Dir use "lib2"; |
| for Library_Kind use "dynamic"; |
| for Library_Name use "l2"; |
| for Externally_Built use "true"; -- <<<< |
| end Extern_Lib; |
| @end example |
| |
| In the case of externally built libraries, the @cite{Object_Dir} |
| attribute does not need to be specified because it will never be |
| used. |
| |
| The main effect of using such an externally built library project is mostly to |
| affect the linker command in order to reference the desired library. It can |
| also be achieved by using @cite{Linker.Linker_Options} or @cite{Linker.Switches} |
| in the project corresponding to the subsystem needing this external library. |
| This latter method is more straightforward in simple cases but when several |
| subsystems depend upon the same external library, finding the proper place |
| for the @cite{Linker.Linker_Options} might not be easy and if it is |
| not placed properly, the final link command is likely to present ordering issues. |
| In such a situation, it is better to use the externally built library project |
| so that all other subsystems depending on it can declare this dependency thanks |
| to a project @emph{with} clause, which in turn will trigger the builder to find |
| the proper order of libraries in the final link command. |
| |
| @node Stand-alone Library Projects,Installing a library with project files,Using Library Projects,Library Projects |
| @anchor{gnat_ugn/gnat_project_manager id23}@anchor{17f}@anchor{gnat_ugn/gnat_project_manager stand-alone-library-projects}@anchor{97} |
| @subsection Stand-alone Library Projects |
| |
| |
| @geindex standalone libraries (usage with GNAT Project Manager) |
| |
| A @strong{stand-alone library} is a library that contains the necessary code to |
| elaborate the Ada units that are included in the library. A stand-alone |
| library is a convenient way to add an Ada subsystem to a more global system |
| whose main is not in Ada since it makes the elaboration of the Ada part mostly |
| transparent. However, stand-alone libraries are also useful when the main is in |
| Ada: they provide a means for minimizing relinking & redeployment of complex |
| systems when localized changes are made. |
| |
| The name of a stand-alone library, specified with attribute |
| @cite{Library_Name}, must have the syntax of an Ada identifier. |
| |
| The most prominent characteristic of a stand-alone library is that it offers a |
| distinction between interface units and implementation units. Only the former |
| are visible to units outside the library. A stand-alone library project is thus |
| characterised by a third attribute, usually @strong{Library_Interface}, in addition |
| to the two attributes that make a project a Library Project |
| (@cite{Library_Name} and @cite{Library_Dir}). This third attribute may also be |
| @strong{Interfaces}. @strong{Library_Interface} only works when the interface is in Ada |
| and takes a list of units as parameter. @strong{Interfaces} works for any supported |
| language and takes a list of sources as parameter. |
| |
| @geindex Library_Interface (GNAT Project Manager) |
| |
| @strong{Library_Interface}: |
| |
| @quotation |
| |
| This attribute defines an explicit subset of the units of the project. Units |
| from projects importing this library project may only "with" units whose |
| sources are listed in the @cite{Library_Interface}. Other sources are |
| considered implementation units. |
| |
| @example |
| for Library_Dir use "lib"; |
| for Library_Name use "logging"; |
| for Library_Interface use ("lib1", "lib2"); -- unit names |
| @end example |
| @end quotation |
| |
| @strong{Interfaces} |
| |
| @quotation |
| |
| This attribute defines an explicit subset of the source files of a project. |
| Sources from projects importing this project, can only depend on sources from |
| this subset. This attribute can be used on non library projects. It can also |
| be used as a replacement for attribute @cite{Library_Interface}, in which |
| case, units have to be replaced by source files. For multi-language library |
| projects, it is the only way to make the project a Stand-Alone Library project |
| whose interface is not purely Ada. |
| @end quotation |
| |
| @geindex Library_Standalone (GNAT Project Manager) |
| |
| @strong{Library_Standalone}: |
| |
| @quotation |
| |
| This attribute defines the kind of standalone library to |
| build. Values are either @cite{standard} (the default), @cite{no} or |
| @cite{encapsulated}. When @cite{standard} is used the code to elaborate and |
| finalize the library is embedded, when @cite{encapsulated} is used the |
| library can furthermore depend only on static libraries (including |
| the GNAT runtime). This attribute can be set to @cite{no} to make it clear |
| that the library should not be standalone in which case the |
| @cite{Library_Interface} should not defined. Note that this attribute |
| only applies to shared libraries, so @cite{Library_Kind} must be set |
| to @cite{dynamic}. |
| |
| @example |
| for Library_Dir use "lib"; |
| for Library_Name use "logging"; |
| for Library_Kind use "dynamic"; |
| for Library_Interface use ("lib1", "lib2"); -- unit names |
| for Library_Standalone use "encapsulated"; |
| @end example |
| @end quotation |
| |
| In order to include the elaboration code in the stand-alone library, the binder |
| is invoked on the closure of the library units creating a package whose name |
| depends on the library name (b~logging.ads/b in the example). |
| This binder-generated package includes @strong{initialization} and @strong{finalization} |
| procedures whose names depend on the library name (@cite{logginginit} and |
| @cite{loggingfinal} in the example). The object corresponding to this package is |
| included in the library. |
| |
| @geindex Library_Auto_Init (GNAT Project Manager) |
| |
| @strong{Library_Auto_Init}: |
| |
| @quotation |
| |
| A dynamic stand-alone Library is automatically initialized |
| if automatic initialization of Stand-alone Libraries is supported on the |
| platform and if attribute @strong{Library_Auto_Init} is not specified or |
| is specified with the value "true". A static Stand-alone Library is never |
| automatically initialized. Specifying "false" for this attribute |
| prevents automatic initialization. |
| |
| When a non-automatically initialized stand-alone library is used in an |
| executable, its initialization procedure must be called before any service of |
| the library is used. When the main subprogram is in Ada, it may mean that the |
| initialization procedure has to be called during elaboration of another |
| package. |
| @end quotation |
| |
| @geindex Library_Dir (GNAT Project Manager) |
| |
| @strong{Library_Dir}: |
| |
| @quotation |
| |
| For a stand-alone library, only the @code{ALI} files of the interface units |
| (those that are listed in attribute @cite{Library_Interface}) are copied to |
| the library directory. As a consequence, only the interface units may be |
| imported from Ada units outside of the library. If other units are imported, |
| the binding phase will fail. |
| @end quotation |
| |
| @strong{Binder.Default_Switches}: |
| |
| @quotation |
| |
| When a stand-alone library is bound, the switches that are specified in |
| the attribute @strong{Binder.Default_Switches ("Ada")} are |
| used in the call to @emph{gnatbind}. |
| @end quotation |
| |
| @geindex Library_Src_Dir (GNAT Project Manager) |
| |
| @strong{Library_Src_Dir}: |
| |
| @quotation |
| |
| This attribute defines the location (absolute or relative to the project |
| directory) where the sources of the interface units are copied at |
| installation time. |
| These sources includes the specs of the interface units along with the |
| closure of sources necessary to compile them successfully. That may include |
| bodies and subunits, when pragmas @cite{Inline} are used, or when there are |
| generic units in specs. This directory cannot point to the object directory |
| or one of the source directories, but it can point to the library directory, |
| which is the default value for this attribute. |
| @end quotation |
| |
| @geindex Library_Symbol_Policy (GNAT Project Manager) |
| |
| @strong{Library_Symbol_Policy}: |
| |
| @quotation |
| |
| This attribute controls the export of symbols and, on some platforms (like |
| VMS) that have the notions of major and minor IDs built in the library |
| files, it controls the setting of these IDs. It is not supported on all |
| platforms (where it will just have no effect). It may have one of the |
| following values: |
| |
| |
| @itemize * |
| |
| @item |
| @cite{"autonomous"} or @cite{"default"}: exported symbols are not controlled |
| |
| @item |
| @cite{"compliant"}: if attribute @strong{Library_Reference_Symbol_File} |
| is not defined, then it is equivalent to policy "autonomous". If there |
| are exported symbols in the reference symbol file that are not in the |
| object files of the interfaces, the major ID of the library is increased. |
| If there are symbols in the object files of the interfaces that are not |
| in the reference symbol file, these symbols are put at the end of the list |
| in the newly created symbol file and the minor ID is increased. |
| |
| @item |
| @cite{"controlled"}: the attribute @strong{Library_Reference_Symbol_File} must be |
| defined. The library will fail to build if the exported symbols in the |
| object files of the interfaces do not match exactly the symbol in the |
| symbol file. |
| |
| @item |
| @cite{"restricted"}: The attribute @strong{Library_Symbol_File} must be defined. |
| The library will fail to build if there are symbols in the symbol file that |
| are not in the exported symbols of the object files of the interfaces. |
| Additional symbols in the object files are not added to the symbol file. |
| |
| @item |
| @cite{"direct"}: The attribute @strong{Library_Symbol_File} must be defined and |
| must designate an existing file in the object directory. This symbol file |
| is passed directly to the underlying linker without any symbol processing. |
| @end itemize |
| @end quotation |
| |
| @geindex Library_Reference_Symbol_File (GNAT Project Manager) |
| |
| @strong{Library_Reference_Symbol_File} |
| |
| @quotation |
| |
| This attribute may define the path name of a reference symbol file that is |
| read when the symbol policy is either "compliant" or "controlled", on |
| platforms that support symbol control, such as VMS, when building a |
| stand-alone library. The path may be an absolute path or a path relative |
| to the project directory. |
| @end quotation |
| |
| @geindex Library_Symbol_File (GNAT Project Manager) |
| |
| @strong{Library_Symbol_File} |
| |
| @quotation |
| |
| This attribute may define the name of the symbol file to be created when |
| building a stand-alone library when the symbol policy is either "compliant", |
| "controlled" or "restricted", on platforms that support symbol control, |
| such as VMS. When symbol policy is "direct", then a file with this name |
| must exist in the object directory. |
| @end quotation |
| |
| @node Installing a library with project files,,Stand-alone Library Projects,Library Projects |
| @anchor{gnat_ugn/gnat_project_manager installing-a-library-with-project-files}@anchor{8d}@anchor{gnat_ugn/gnat_project_manager id24}@anchor{180} |
| @subsection Installing a library with project files |
| |
| |
| When using project files, a usable version of the library is created in the |
| directory specified by the @cite{Library_Dir} attribute of the library |
| project file. Thus no further action is needed in order to make use of |
| the libraries that are built as part of the general application build. |
| |
| You may want to install a library in a context different from where the library |
| is built. This situation arises with third party suppliers, who may want |
| to distribute a library in binary form where the user is not expected to be |
| able to recompile the library. The simplest option in this case is to provide |
| a project file slightly different from the one used to build the library, by |
| using the @cite{externally_built} attribute. See @ref{17e,,Using Library Projects} |
| |
| Another option is to use @emph{gprinstall} to install the library in a |
| different context than the build location. @emph{gprinstall} automatically |
| generates a project to use this library, and also copies the minimum set of |
| sources needed to use the library to the install location. |
| @ref{16b,,Installation} |
| |
| @node Project Extension,Aggregate Projects,Library Projects,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager id25}@anchor{181}@anchor{gnat_ugn/gnat_project_manager project-extension}@anchor{152} |
| @section 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 the @strong{project extension} facility. |
| |
| Suppose for instance that our example @cite{Build} project is built every night |
| for the whole team, in some shared directory. A developer usually needs to work |
| on a small part of the system, and might not want to have a copy of all the |
| sources and all the object files (mostly because that would require too much |
| disk space, time to recompile everything). He prefers to be able to override |
| some of the source files in his directory, while taking advantage of all the |
| object files generated at night. |
| |
| Another example can be taken from large software systems, where it is common to have |
| multiple implementations of a common interface; in Ada terms, multiple |
| versions of a package body for the same spec. For example, one implementation |
| might be safe for use in tasking programs, while another might be used only |
| in sequential applications. This can be modeled in GNAT using the concept |
| of @emph{project extension}. If one project (the 'child') @emph{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 or remove unnecessary ones. |
| This facility is the project analog of a type extension in |
| object-oriented programming. Project hierarchies are permitted (an extending |
| project may itself be extended), and a project that |
| extends a project can also import other projects. |
| |
| A third example is that of using project extensions to provide different |
| versions of the same system. For instance, assume that a @cite{Common} |
| project is used by two development branches. One of the branches has now |
| been frozen, and no further change can be done to it or to @cite{Common}. |
| However, the other development branch still needs evolution of @cite{Common}. |
| Project extensions provide a flexible solution to create a new version |
| of a subsystem while sharing and reusing as much as possible from the original |
| one. |
| |
| A project extension implicitly inherits all the sources and objects from the |
| project it extends. It is possible to create a new version of some of the |
| sources in one of the additional source directories of the extending |
| project. Those new versions hide the original versions. Adding new sources or |
| removing existing ones is also possible. Here is an example on how to extend |
| the project @cite{Build} from previous examples: |
| |
| @example |
| project Work extends "../bld/build.gpr" is |
| end Work; |
| @end example |
| |
| The project after @strong{extends} is the one being extended. As usual, it can be |
| specified using an absolute path, or a path relative to any of the directories |
| in the project path (see @ref{16f,,Project Dependencies}). This project does not |
| specify source or object directories, so the default values for these |
| attributes will be used that is to say the current directory (where project |
| @cite{Work} is placed). We can compile that project with |
| |
| @example |
| gprbuild -Pwork |
| @end example |
| |
| If no sources have been placed in the current directory, this command |
| won't do anything, since this project does not change the |
| sources it inherited from @cite{Build}, therefore all the object files |
| in @cite{Build} and its dependencies are still valid and are reused |
| automatically. |
| |
| Suppose we now want to supply an alternate version of @code{pack.adb} but use |
| the existing versions of @code{pack.ads} and @code{proc.adb}. We can create |
| the new file in Work's current directory (likely by copying the one from the |
| @cite{Build} project and making changes to it. If new packages are needed at |
| the same time, we simply create new files in the source directory of the |
| extending project. |
| |
| When we recompile, @emph{gprbuild} will now automatically recompile |
| this file (thus creating @code{pack.o} in the current directory) and |
| any file that depends on it (thus creating @code{proc.o}). Finally, the |
| executable is also linked locally. |
| |
| Note that we could have obtained the desired behavior using project import |
| rather than project inheritance. A @cite{base} project would contain the |
| sources for @code{pack.ads} and @code{proc.adb}, and @cite{Work} would |
| import @cite{base} and add @code{pack.adb}. In this scenario, @cite{base} |
| cannot contain the original version of @code{pack.adb} otherwise there would be |
| 2 versions of the same unit in the closure of the project and this is not |
| allowed. Generally speaking, it is not recommended to put the spec and the |
| body of a unit in different projects since this affects their autonomy and |
| reusability. |
| |
| In a project file that extends another project, it is possible to |
| indicate that an inherited source is @strong{not part} of the sources of the |
| extending project. This is necessary sometimes when a package spec has |
| been overridden and no longer requires a body: in this case, it is |
| necessary to indicate that the inherited body is not part of the sources |
| of the project, otherwise there will be a compilation error |
| when compiling the spec. |
| |
| @geindex Excluded_Source_Files (GNAT Project Manager) |
| |
| @geindex Excluded_Source_List_File (GNAT Project Manager) |
| |
| For that purpose, the attribute @strong{Excluded_Source_Files} is used. |
| Its value is a list of file names. |
| It is also possible to use attribute @cite{Excluded_Source_List_File}. |
| Its value is the path of a text file containing one file name per |
| line. |
| |
| @example |
| project Work extends "../bld/build.gpr" is |
| for Source_Files use ("pack.ads"); |
| -- New spec of Pkg does not need a completion |
| for Excluded_Source_Files use ("pack.adb"); |
| end Work; |
| @end example |
| |
| All packages that are not declared in the extending project are inherited from |
| the project being extended, with their attributes, with the exception of |
| @cite{Linker'Linker_Options} which is never inherited. In particular, an |
| extending project retains all the switches specified in the project being |
| extended. |
| |
| At the project level, if they are not declared in the extending project, some |
| attributes are inherited from the project being extended. They are: |
| @cite{Languages}, @cite{Main} (for a root non library project) and |
| @cite{Library_Name} (for a project extending a library project). |
| |
| @menu |
| * Project Hierarchy Extension:: |
| |
| @end menu |
| |
| @node Project Hierarchy Extension,,,Project Extension |
| @anchor{gnat_ugn/gnat_project_manager project-hierarchy-extension}@anchor{182}@anchor{gnat_ugn/gnat_project_manager id26}@anchor{183} |
| @subsection Project Hierarchy Extension |
| |
| |
| One of the fundamental restrictions in project extension is the following: |
| @strong{A project is not allowed to import directly or indirectly at the same time an extending project and one of its ancestors}. |
| |
| For example, consider the following hierarchy of projects. |
| |
| @example |
| a.gpr contains package A1 |
| b.gpr, imports a.gpr and contains B1, which depends on A1 |
| c.gpr, imports b.gpr and contains C1, which depends on B1 |
| @end example |
| |
| If we want to locally extend the packages @cite{A1} and @cite{C1}, we need to |
| create several extending projects: |
| |
| @example |
| a_ext.gpr which extends a.gpr, and overrides A1 |
| b_ext.gpr which extends b.gpr and imports a_ext.gpr |
| c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1 |
| @end example |
| |
| @example |
| project A_Ext extends "a.gpr" is |
| for Source_Files use ("a1.adb", "a1.ads"); |
| end A_Ext; |
| |
| with "a_ext.gpr"; |
| project B_Ext extends "b.gpr" is |
| end B_Ext; |
| |
| with "b_ext.gpr"; |
| project C_Ext extends "c.gpr" is |
| for Source_Files use ("c1.adb"); |
| end C_Ext; |
| @end example |
| |
| The extension @code{b_ext.gpr} is required, even though we are not overriding |
| any of the sources of @code{b.gpr} because otherwise @code{c_expr.gpr} would |
| import @code{b.gpr} which itself knows nothing about @code{a_ext.gpr}. |
| |
| @geindex extends all (GNAT Project Manager) |
| |
| When extending a large system spanning multiple projects, it is often |
| inconvenient to extend every project in the hierarchy that is impacted by a |
| small change introduced in a low layer. In such cases, it is possible to create |
| an @strong{implicit extension} of an entire hierarchy using @strong{extends all} |
| relationship. |
| |
| When the project is extended using @cite{extends all} inheritance, all projects |
| that are imported by it, both directly and indirectly, are considered virtually |
| extended. That is, the project manager creates implicit projects |
| that extend every project in the hierarchy; all these implicit projects do not |
| control sources on their own and use the object directory of |
| the "extending all" project. |
| |
| It is possible to explicitly extend one or more projects in the hierarchy |
| in order to modify the sources. These extending projects must be imported by |
| the "extending all" project, which will replace the corresponding virtual |
| projects with the explicit ones. |
| |
| When building such a project hierarchy extension, the project manager will |
| ensure that both modified sources and sources in implicit extending projects |
| that depend on them are recompiled. |
| |
| Thus, in our example we could create the following projects instead: |
| |
| @example |
| a_ext.gpr, extends a.gpr and overrides A1 |
| c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1 |
| @end example |
| |
| @example |
| project A_Ext extends "a.gpr" is |
| for Source_Files use ("a1.adb", "a1.ads"); |
| end A_Ext; |
| |
| with "a_ext.gpr"; |
| project C_Ext extends all "c.gpr" is |
| for Source_Files use ("c1.adb"); |
| end C_Ext; |
| @end example |
| |
| When building project @code{c_ext.gpr}, the entire modified project space is |
| considered for recompilation, including the sources of @code{b.gpr} that are |
| impacted by the changes in @cite{A1} and @cite{C1}. |
| |
| @node Aggregate Projects,Aggregate Library Projects,Project Extension,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager aggregate-projects}@anchor{171}@anchor{gnat_ugn/gnat_project_manager id27}@anchor{184} |
| @section Aggregate Projects |
| |
| |
| Aggregate projects are an extension of the project paradigm, and are |
| meant to solve a few specific use cases that cannot be solved directly |
| using standard projects. This section will go over a few of these use |
| cases to try to explain what you can use aggregate projects for. |
| |
| @menu |
| * Building all main programs from a single project tree:: |
| * Building a set of projects with a single command:: |
| * Define a build environment:: |
| * Performance improvements in builder:: |
| * Syntax of aggregate projects:: |
| * package Builder in aggregate projects:: |
| |
| @end menu |
| |
| @node Building all main programs from a single project tree,Building a set of projects with a single command,,Aggregate Projects |
| @anchor{gnat_ugn/gnat_project_manager id28}@anchor{185}@anchor{gnat_ugn/gnat_project_manager building-all-main-programs-from-a-single-project-tree}@anchor{186} |
| @subsection Building all main programs from a single project tree |
| |
| |
| Most often, an application is organized into modules and submodules, |
| which are very conveniently represented as a project tree or graph |
| (the root project A @emph{with}s the projects for each modules (say B and C), |
| which in turn @emph{with} projects for submodules. |
| |
| Very often, modules will build their own executables (for testing |
| purposes for instance), or libraries (for easier reuse in various |
| contexts). |
| |
| However, if you build your project through @emph{gprbuild}, using a syntax similar to |
| |
| @example |
| gprbuild -PA.gpr |
| @end example |
| |
| this will only rebuild the main programs of project A, not those of the |
| imported projects B and C. Therefore you have to spawn several |
| @emph{gprbuild} commands, one per project, to build all executables. |
| This is a little inconvenient, but more importantly is inefficient |
| because @emph{gprbuild} needs to do duplicate work to ensure that sources are |
| up-to-date, and cannot easily compile things in parallel when using |
| the -j switch. |
| |
| Also libraries are always rebuilt when building a project. |
| |
| You could therefore define an aggregate project Agg that groups A, B |
| and C. Then, when you build with |
| |
| @example |
| gprbuild -PAgg.gpr |
| @end example |
| |
| this will build all mains from A, B and C. |
| |
| @example |
| aggregate project Agg is |
| for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); |
| end Agg; |
| @end example |
| |
| If B or C do not define any main program (through their Main |
| attribute), all their sources are built. When you do not group them |
| in the aggregate project, only those sources that are needed by A |
| will be built. |
| |
| If you add a main to a project P not already explicitly referenced in the |
| aggregate project, you will need to add "p.gpr" in the list of project |
| files for the aggregate project, or the main will not be built when |
| building the aggregate project. |
| |
| @node Building a set of projects with a single command,Define a build environment,Building all main programs from a single project tree,Aggregate Projects |
| @anchor{gnat_ugn/gnat_project_manager building-a-set-of-projects-with-a-single-command}@anchor{187}@anchor{gnat_ugn/gnat_project_manager id29}@anchor{188} |
| @subsection Building a set of projects with a single command |
| |
| |
| One other case is when you have multiple applications and libraries |
| that are built independently from each other (but can be built in |
| parallel). For instance, you have a project tree rooted at A, and |
| another one (which might share some subprojects) rooted at B. |
| |
| Using only @emph{gprbuild}, you could do |
| |
| @example |
| gprbuild -PA.gpr |
| gprbuild -PB.gpr |
| @end example |
| |
| to build both. But again, @emph{gprbuild} has to do some duplicate work for |
| those files that are shared between the two, and cannot truly build |
| things in parallel efficiently. |
| |
| If the two projects are really independent, share no sources other |
| than through a common subproject, and have no source files with a |
| common basename, you could create a project C that imports A and |
| B. But these restrictions are often too strong, and one has to build |
| them independently. An aggregate project does not have these |
| limitations and can aggregate two project trees that have common |
| sources. |
| |
| This scenario is particularly useful in environments like VxWorks 653 |
| where the applications running in the multiple partitions can be built |
| in parallel through a single @emph{gprbuild} command. This also works nicely |
| with Annex E. |
| |
| @node Define a build environment,Performance improvements in builder,Building a set of projects with a single command,Aggregate Projects |
| @anchor{gnat_ugn/gnat_project_manager id30}@anchor{189}@anchor{gnat_ugn/gnat_project_manager define-a-build-environment}@anchor{18a} |
| @subsection Define a build environment |
| |
| |
| The environment variables at the time you launch @emph{gprbuild} |
| will influence the view these tools have of the project |
| (PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the |
| projects, environment variables that are referenced in project files |
| through the "external" built-in function, ...). Several command line switches |
| can be used to override those (-X or -aP), but on some systems and |
| with some projects, this might make the command line too long, and on |
| all systems often make it hard to read. |
| |
| An aggregate project can be used to set the environment for all |
| projects built through that aggregate. One of the nice aspects is that |
| you can put the aggregate project under configuration management, and |
| make sure all your user have a consistent environment when |
| building. The syntax looks like |
| |
| @example |
| aggregate project Agg is |
| for Project_Files use ("A.gpr", "B.gpr"); |
| for Project_Path use ("../dir1", "../dir1/dir2"); |
| for External ("BUILD") use "PRODUCTION"; |
| |
| package Builder is |
| for Global_Compilation_Switches ("Ada") use ("-g"); |
| end Builder; |
| end Agg; |
| @end example |
| |
| One of the often requested features in projects is to be able to |
| reference external variables in @emph{with} declarations, as in |
| |
| @example |
| with external("SETUP") & "path/prj.gpr"; -- ILLEGAL |
| project MyProject is |
| ... |
| end MyProject; |
| @end example |
| |
| For various reasons, this is not allowed. But using aggregate projects provide |
| an elegant solution. For instance, you could use a project file like: |
| |
| @example |
| aggregate project Agg is |
| for Project_Path use (external("SETUP") & "path"); |
| for Project_Files use ("myproject.gpr"); |
| end Agg; |
| |
| with "prj.gpr"; -- searched on Agg'Project_Path |
| project MyProject is |
| ... |
| end MyProject; |
| @end example |
| |
| @node Performance improvements in builder,Syntax of aggregate projects,Define a build environment,Aggregate Projects |
| @anchor{gnat_ugn/gnat_project_manager performance-improvements-in-builder}@anchor{18b}@anchor{gnat_ugn/gnat_project_manager id31}@anchor{18c} |
| @subsection Performance improvements in builder |
| |
| |
| The loading of aggregate projects is optimized in @emph{gprbuild}, |
| so that all files are searched for only once on the disk |
| (thus reducing the number of system calls and contributing to faster |
| compilation times, especially on systems with sources on remote |
| servers). As part of the loading, @emph{gprbuild} |
| computes how and where a source file should be compiled, and even if it is |
| found several times in the aggregated projects it will be compiled only |
| once. |
| |
| Since there is no ambiguity as to which switches should be used, files |
| can be compiled in parallel (through the usual -j switch) and this can |
| be done while maximizing the use of CPUs (compared to launching |
| multiple @emph{gprbuild} commands in parallel). |
| |
| @node Syntax of aggregate projects,package Builder in aggregate projects,Performance improvements in builder,Aggregate Projects |
| @anchor{gnat_ugn/gnat_project_manager id32}@anchor{18d}@anchor{gnat_ugn/gnat_project_manager syntax-of-aggregate-projects}@anchor{18e} |
| @subsection Syntax of aggregate projects |
| |
| |
| An aggregate project follows the general syntax of project files. The |
| recommended extension is still @code{.gpr}. However, a special |
| @cite{aggregate} qualifier must be put before the keyword |
| @cite{project}. |
| |
| An aggregate project cannot @emph{with} any other project (standard or |
| aggregate), except an abstract project which can be used to share attribute |
| values. Also, aggregate projects cannot be extended or imported though a |
| @emph{with} clause by any other project. Building other aggregate projects from |
| an aggregate project is done through the Project_Files attribute (see below). |
| |
| An aggregate project does not have any source files directly (only |
| through other standard projects). Therefore a number of the standard |
| attributes and packages are forbidden in an aggregate project. Here is the |
| (non exhaustive) list: |
| |
| |
| @itemize * |
| |
| @item |
| Languages |
| |
| @item |
| Source_Files, Source_List_File and other attributes dealing with |
| list of sources. |
| |
| @item |
| Source_Dirs, Exec_Dir and Object_Dir |
| |
| @item |
| Library_Dir, Library_Name and other library-related attributes |
| |
| @item |
| Main |
| |
| @item |
| Roots |
| |
| @item |
| Externally_Built |
| |
| @item |
| Inherit_Source_Path |
| |
| @item |
| Excluded_Source_Dirs |
| |
| @item |
| Locally_Removed_Files |
| |
| @item |
| Excluded_Source_Files |
| |
| @item |
| Excluded_Source_List_File |
| |
| @item |
| Interfaces |
| @end itemize |
| |
| The only package that is authorized (albeit optional) is |
| Builder. Other packages (in particular Compiler, Binder and Linker) |
| are forbidden. |
| |
| The following three attributes can be used only in an aggregate project: |
| |
| @geindex Project_Files (GNAT Project Manager) |
| |
| @strong{Project_Files}: |
| |
| @quotation |
| |
| This attribute is compulsory (or else we are not aggregating any project, |
| and thus not doing anything). It specifies a list of @code{.gpr} files |
| that are grouped in the aggregate. The list may be empty. The project |
| files can be either other aggregate projects, or standard projects. When |
| grouping standard projects, you can have both the root of a project tree |
| (and you do not need to specify all its imported projects), and any project |
| within the tree. |
| |
| Basically, the idea is to specify all those projects that have |
| main programs you want to build and link, or libraries you want to |
| build. You can even specify projects that do not use the Main |
| attribute nor the @cite{Library_*} attributes, and the result will be to |
| build all their source files (not just the ones needed by other |
| projects). |
| |
| The file can include paths (absolute or relative). Paths are relative to |
| the location of the aggregate project file itself (if you use a base name, |
| we expect to find the .gpr file in the same directory as the aggregate |
| project file). The environment variables @cite{ADA_PROJECT_PATH}, |
| @cite{GPR_PROJECT_PATH} and @cite{GPR_PROJECT_PATH_FILE} are not used to find |
| the project files. The extension @code{.gpr} is mandatory, since this attribute |
| contains file names, not project names. |
| |
| Paths can also include the @cite{"*"} and @cite{"**"} globbing patterns. The |
| latter indicates that any subdirectory (recursively) will be |
| searched for matching files. The latter (@cite{"**"}) can only occur at the |
| last position in the directory part (ie @cite{"a/**/*.gpr"} is supported, but |
| not @cite{"**/a/*.gpr"}). Starting the pattern with @cite{"**"} is equivalent |
| to starting with @cite{"./**"}. |
| |
| For now, the pattern @cite{"*"} is only allowed in the filename part, not |
| in the directory part. This is mostly for efficiency reasons to limit the |
| number of system calls that are needed. |
| |
| Here are a few valid examples: |
| |
| @example |
| for Project_Files use ("a.gpr", "subdir/b.gpr"); |
| -- two specific projects relative to the directory of agg.gpr |
| |
| for Project_Files use ("/.gpr"); |
| -- all projects recursively |
| @end example |
| @end quotation |
| |
| @geindex Project_Path (GNAT Project Manager) |
| |
| @strong{Project_Path}: |
| |
| @quotation |
| |
| This attribute can be used to specify a list of directories in |
| which to look for project files in @emph{with} declarations. |
| |
| When you specify a project in Project_Files (say @cite{x/y/a.gpr}), and |
| @cite{a.gpr} imports a project @cite{b.gpr}, only @cite{b.gpr} is searched in |
| the project path. @cite{a.gpr} must be exactly at |
| @cite{<dir of the aggregate>/x/y/a.gpr}. |
| |
| This attribute, however, does not affect the search for the aggregated |
| project files specified with @cite{Project_Files}. |
| |
| Each aggregate project has its own @cite{Project_Path} (that is if |
| @cite{agg1.gpr} includes @cite{agg2.gpr}, they can potentially both have a |
| different @cite{Project_Path}). |
| |
| This project path is defined as the concatenation, in that order, of: |
| |
| |
| @itemize * |
| |
| @item |
| the current directory; |
| |
| @item |
| followed by the command line -aP switches; |
| |
| @item |
| then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment |
| variables; |
| |
| @item |
| then the directories from the Project_Path attribute; |
| |
| @item |
| and finally the predefined directories. |
| @end itemize |
| |
| In the example above, agg2.gpr's project path is not influenced by |
| the attribute agg1'Project_Path, nor is agg1 influenced by |
| agg2'Project_Path. |
| |
| This can potentially lead to errors. Consider the following example: |
| |
| @example |
| -- |
| -- +---------------+ +----------------+ |
| -- | Agg1.gpr |-=--includes--=-->| Agg2.gpr | |
| -- | 'project_path| | 'project_path | |
| -- | | | | |
| -- +---------------+ +----------------+ |
| -- : : |
| -- includes includes |
| -- : : |
| -- v v |
| -- +-------+ +---------+ |
| -- | P.gpr |<---------- withs --------| Q.gpr | |
| -- +-------+---------\ +---------+ |
| -- | | |
| -- withs | |
| -- | | |
| -- v v |
| -- +-------+ +---------+ |
| -- | R.gpr | | R'.gpr | |
| -- +-------+ +---------+ |
| @end example |
| |
| When looking for p.gpr, both aggregates find the same physical file on |
| the disk. However, it might happen that with their different project |
| paths, both aggregate projects would in fact find a different r.gpr. |
| Since we have a common project (p.gpr) "with"ing two different r.gpr, |
| this will be reported as an error by the builder. |
| |
| Directories are relative to the location of the aggregate project file. |
| |
| Example: |
| |
| @example |
| for Project_Path use ("/usr/local/gpr", "gpr/"); |
| @end example |
| @end quotation |
| |
| @geindex External (GNAT Project Manager) |
| |
| @strong{External}: |
| |
| @quotation |
| |
| This attribute can be used to set the value of environment |
| variables as retrieved through the @cite{external} function |
| in projects. It does not affect the environment variables |
| themselves (so for instance you cannot use it to change the value |
| of your PATH as seen from the spawned compiler). |
| |
| This attribute affects the external values as seen in the rest of |
| the aggregate project, and in the aggregated projects. |
| |
| The exact value of external a variable comes from one of three |
| sources (each level overrides the previous levels): |
| |
| |
| @itemize * |
| |
| @item |
| An External attribute in aggregate project, for instance |
| @cite{for External ("BUILD_MODE") use "DEBUG"}; |
| |
| @item |
| Environment variables. |
| These override the value given by the attribute, so that |
| users can override the value set in the (presumably shared |
| with others team members) aggregate project. |
| |
| @item |
| The -X command line switch to @emph{gprbuild}. |
| This always takes precedence. |
| @end itemize |
| |
| This attribute is only taken into account in the main aggregate |
| project (i.e. the one specified on the command line to @emph{gprbuild}), |
| and ignored in other aggregate projects. It is invalid |
| in standard projects. |
| The goal is to have a consistent value in all |
| projects that are built through the aggregate, which would not |
| be the case in the diamond case: A groups the aggregate |
| projects B and C, which both (either directly or indirectly) |
| build the project P. If B and C could set different values for |
| the environment variables, we would have two different views of |
| P, which in particular might impact the list of source files in P. |
| @end quotation |
| |
| @node package Builder in aggregate projects,,Syntax of aggregate projects,Aggregate Projects |
| @anchor{gnat_ugn/gnat_project_manager package-builder-in-aggregate-projects}@anchor{18f}@anchor{gnat_ugn/gnat_project_manager id33}@anchor{190} |
| @subsection package Builder in aggregate projects |
| |
| |
| As mentioned above, only the package Builder can be specified in |
| an aggregate project. In this package, only the following attributes |
| are valid: |
| |
| @geindex Switches (GNAT Project Manager) |
| |
| @strong{Switches}: |
| |
| @quotation |
| |
| This attribute gives the list of switches to use for @emph{gprbuild}. |
| Because no mains can be specified for aggregate projects, the only possible |
| index for attribute @cite{Switches} is @cite{others}. All other indexes will |
| be ignored. |
| |
| Example: |
| |
| @example |
| for Switches (others) use ("-v", "-k", "-j8"); |
| @end example |
| |
| These switches are only read from the main aggregate project (the |
| one passed on the command line), and ignored in all other aggregate |
| projects or projects. |
| |
| It can only contain builder switches, not compiler switches. |
| @end quotation |
| |
| @geindex Global_Compilation_Switches (GNAT Project Manager) |
| |
| @strong{Global_Compilation_Switches} |
| |
| @quotation |
| |
| This attribute gives the list of compiler switches for the various |
| languages. For instance, |
| |
| @example |
| for Global_Compilation_Switches ("Ada") use ("O1", "-g"); |
| for Global_Compilation_Switches ("C") use ("-O2"); |
| @end example |
| |
| This attribute is only taken into account in the aggregate project |
| specified on the command line, not in other aggregate projects. |
| |
| In the projects grouped by that aggregate, the attribute |
| Builder.Global_Compilation_Switches is also ignored. However, the |
| attribute Compiler.Default_Switches will be taken into account (but |
| that of the aggregate have higher priority). The attribute |
| Compiler.Switches is also taken into account and can be used to |
| override the switches for a specific file. As a result, it always |
| has priority. |
| |
| The rules are meant to avoid ambiguities when compiling. For |
| instance, aggregate project Agg groups the projects A and B, that |
| both depend on C. Here is an extra for all of these projects: |
| |
| @example |
| aggregate project Agg is |
| for Project_Files use ("a.gpr", "b.gpr"); |
| package Builder is |
| for Global_Compilation_Switches ("Ada") use ("-O2"); |
| end Builder; |
| end Agg; |
| |
| with "c.gpr"; |
| project A is |
| package Builder is |
| for Global_Compilation_Switches ("Ada") use ("-O1"); |
| -- ignored |
| end Builder; |
| |
| package Compiler is |
| for Default_Switches ("Ada") |
| use ("-O1", "-g"); |
| for Switches ("a_file1.adb") |
| use ("-O0"); |
| end Compiler; |
| end A; |
| |
| with "c.gpr"; |
| project B is |
| package Compiler is |
| for Default_Switches ("Ada") use ("-O0"); |
| end Compiler; |
| end B; |
| |
| project C is |
| package Compiler is |
| for Default_Switches ("Ada") |
| use ("-O3", |
| "-gnatn"); |
| for Switches ("c_file1.adb") |
| use ("-O0", "-g"); |
| end Compiler; |
| end C; |
| @end example |
| |
| then the following switches are used: |
| |
| |
| @itemize * |
| |
| @item |
| all files from project A except a_file1.adb are compiled |
| with "-O2 -g", since the aggregate project has priority. |
| |
| @item |
| the file a_file1.adb is compiled with |
| "-O0", since the Compiler.Switches has priority |
| |
| @item |
| all files from project B are compiled with |
| "-O2", since the aggregate project has priority |
| |
| @item |
| all files from C are compiled with "-O2 -gnatn", except for |
| c_file1.adb which is compiled with "-O0 -g" |
| @end itemize |
| |
| Even though C is seen through two paths (through A and through |
| B), the switches used by the compiler are unambiguous. |
| @end quotation |
| |
| @geindex Global_Configuration_Pragmas (GNAT Project Manager) |
| |
| @strong{Global_Configuration_Pragmas} |
| |
| @quotation |
| |
| This attribute can be used to specify a file containing |
| configuration pragmas, to be passed to the Ada compiler. Since we |
| ignore the package Builder in other aggregate projects and projects, |
| only those pragmas defined in the main aggregate project will be |
| taken into account. |
| |
| Projects can locally add to those by using the |
| @cite{Compiler.Local_Configuration_Pragmas} attribute if they need. |
| @end quotation |
| |
| @geindex Global_Config_File (GNAT Project Manager) |
| |
| @strong{Global_Config_File} |
| |
| @quotation |
| |
| This attribute, indexed with a language name, can be used to specify a config |
| when compiling sources of the language. For Ada, these files are configuration |
| pragmas files. |
| @end quotation |
| |
| For projects that are built through the aggregate, the package Builder |
| is ignored, except for the Executable attribute which specifies the |
| name of the executables resulting from the link of the main programs, and |
| for the Executable_Suffix. |
| |
| @node Aggregate Library Projects,Project File Reference,Aggregate Projects,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager id34}@anchor{191}@anchor{gnat_ugn/gnat_project_manager aggregate-library-projects}@anchor{192} |
| @section Aggregate Library Projects |
| |
| |
| Aggregate library projects make it possible to build a single library |
| using object files built using other standard or library |
| projects. This gives the flexibility to describe an application as |
| having multiple modules (a GUI, database access, ...) using different |
| project files (so possibly built with different compiler options) and |
| yet create a single library (static or relocatable) out of the |
| corresponding object files. |
| |
| @menu |
| * Building aggregate library projects:: |
| * Syntax of aggregate library projects:: |
| |
| @end menu |
| |
| @node Building aggregate library projects,Syntax of aggregate library projects,,Aggregate Library Projects |
| @anchor{gnat_ugn/gnat_project_manager building-aggregate-library-projects}@anchor{193}@anchor{gnat_ugn/gnat_project_manager id35}@anchor{194} |
| @subsection Building aggregate library projects |
| |
| |
| For example, we can define an aggregate project Agg that groups A, B |
| and C: |
| |
| @example |
| aggregate library project Agg is |
| for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); |
| for Library_Name use ("agg"); |
| for Library_Dir use ("lagg"); |
| end Agg; |
| @end example |
| |
| Then, when you build with: |
| |
| @example |
| gprbuild agg.gpr |
| @end example |
| |
| This will build all units from projects A, B and C and will create a |
| static library named @code{libagg.a} in the @code{lagg} |
| directory. An aggregate library project has the same set of |
| restriction as a standard library project. |
| |
| Note that a shared aggregate library project cannot aggregate a |
| static library project. In platforms where a compiler option is |
| required to create relocatable object files, a Builder package in the |
| aggregate library project may be used: |
| |
| @example |
| aggregate library project Agg is |
| for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); |
| for Library_Name use ("agg"); |
| for Library_Dir use ("lagg"); |
| for Library_Kind use "relocatable"; |
| |
| package Builder is |
| for Global_Compilation_Switches ("Ada") use ("-fPIC"); |
| end Builder; |
| end Agg; |
| @end example |
| |
| With the above aggregate library Builder package, the @cite{-fPIC} |
| option will be passed to the compiler when building any source code |
| from projects @code{a.gpr}, @code{b.gpr} and @code{c.gpr}. |
| |
| @node Syntax of aggregate library projects,,Building aggregate library projects,Aggregate Library Projects |
| @anchor{gnat_ugn/gnat_project_manager syntax-of-aggregate-library-projects}@anchor{195}@anchor{gnat_ugn/gnat_project_manager id36}@anchor{196} |
| @subsection Syntax of aggregate library projects |
| |
| |
| An aggregate library project follows the general syntax of project |
| files. The recommended extension is still @code{.gpr}. However, a special |
| @cite{aggregate library} qualifier must be put before the keyword |
| @cite{project}. |
| |
| An aggregate library project cannot @emph{with} any other project |
| (standard or aggregate), except an abstract project which can be used |
| to share attribute values. |
| |
| An aggregate library project does not have any source files directly (only |
| through other standard projects). Therefore a number of the standard |
| attributes and packages are forbidden in an aggregate library |
| project. Here is the (non exhaustive) list: |
| |
| |
| @itemize * |
| |
| @item |
| Languages |
| |
| @item |
| Source_Files, Source_List_File and other attributes dealing with |
| list of sources. |
| |
| @item |
| Source_Dirs, Exec_Dir and Object_Dir |
| |
| @item |
| Main |
| |
| @item |
| Roots |
| |
| @item |
| Externally_Built |
| |
| @item |
| Inherit_Source_Path |
| |
| @item |
| Excluded_Source_Dirs |
| |
| @item |
| Locally_Removed_Files |
| |
| @item |
| Excluded_Source_Files |
| |
| @item |
| Excluded_Source_List_File |
| |
| @item |
| Interfaces |
| @end itemize |
| |
| The only package that is authorized (albeit optional) is Builder. |
| |
| The Project_Files attribute (See @ref{171,,Aggregate Projects}) is used to |
| described the aggregated projects whose object files have to be |
| included into the aggregate library. The environment variables |
| @cite{ADA_PROJECT_PATH}, @cite{GPR_PROJECT_PATH} and |
| @cite{GPR_PROJECT_PATH_FILE} are not used to find the project files. |
| |
| @node Project File Reference,,Aggregate Library Projects,GNAT Project Manager |
| @anchor{gnat_ugn/gnat_project_manager id37}@anchor{197}@anchor{gnat_ugn/gnat_project_manager project-file-reference}@anchor{150} |
| @section Project File Reference |
| |
| |
| This section describes the syntactic structure of project files, the various |
| constructs that can be used. Finally, it ends with a summary of all available |
| attributes. |
| |
| @menu |
| * Project Declaration:: |
| * Qualified Projects:: |
| * Declarations:: |
| * Packages:: |
| * Expressions:: |
| * External Values:: |
| * Typed String Declaration:: |
| * Variables:: |
| * Case Constructions:: |
| * Attributes:: |
| |
| @end menu |
| |
| @node Project Declaration,Qualified Projects,,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager id38}@anchor{198}@anchor{gnat_ugn/gnat_project_manager project-declaration}@anchor{199} |
| @subsection Project Declaration |
| |
| |
| Project files have an Ada-like syntax. The minimal project file is: |
| |
| @example |
| project Empty is |
| end Empty; |
| @end example |
| |
| The identifier @cite{Empty} is the name of the project. |
| This project name must be present after the reserved |
| word @cite{end} at the end of the project file, followed by a semi-colon. |
| |
| @strong{Identifiers} (i.e., the user-defined names such as project or variable names) |
| have the same syntax as Ada identifiers: they must start with a letter, |
| and be followed by zero or more letters, digits or underscore characters; |
| it is also illegal to have two underscores next to each other. Identifiers |
| are always case-insensitive ("Name" is the same as "name"). |
| |
| @example |
| simple_name ::= identifier |
| name ::= simple_name @{ . simple_name @} |
| @end example |
| |
| @strong{Strings} are used for values of attributes or as indexes for these |
| attributes. They are in general case sensitive, except when noted |
| otherwise (in particular, strings representing file names will be case |
| insensitive on some systems, so that "file.adb" and "File.adb" both |
| represent the same file). |
| |
| @strong{Reserved words} are the same as for standard Ada 95, and cannot |
| be used for identifiers. In particular, the following words are currently |
| used in project files, but others could be added later on. In bold are the |
| extra reserved words in project files: |
| @code{all}, @code{at}, @code{case}, @code{end}, @code{for}, @code{is}, @code{limited}, |
| @code{null}, @code{others}, @code{package}, @code{renames}, @code{type}, @code{use}, @code{when}, |
| @code{with}, @strong{extends}, @strong{external}, @strong{project}. |
| |
| @strong{Comments} in project files have the same syntax as in Ada, two consecutive |
| hyphens through the end of the line. |
| |
| A project may be an @strong{independent project}, entirely defined by a single |
| project file. Any source file in an independent project depends only |
| on the predefined library and other source files in the same project. |
| But a project may also depend on other projects, either by importing them |
| through @strong{with clauses}, or by @strong{extending} at most one other project. Both |
| types of dependency can be used in the same project. |
| |
| A path name denotes a project file. It can be absolute or relative. |
| An absolute path name includes a sequence of directories, in the syntax of |
| the host operating system, that identifies uniquely the project file in the |
| file system. A relative path name identifies the project file, relative |
| to the directory that contains the current project, or relative to a |
| directory listed in the environment variables ADA_PROJECT_PATH and |
| GPR_PROJECT_PATH. Path names are case sensitive if file names in the host |
| operating system are case sensitive. As a special case, the directory |
| separator can always be "/" even on Windows systems, so that project files |
| can be made portable across architectures. |
| The syntax of the environment variables ADA_PROJECT_PATH and |
| GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and |
| semicolons on Windows. |
| |
| A given project name can appear only once in a context clause. |
| |
| It is illegal for a project imported by a context clause to refer, directly |
| or indirectly, to the project in which this context clause appears (the |
| dependency graph cannot contain cycles), except when one of the with clauses |
| in the cycle is a @strong{limited with}. |
| |
| @example |
| with "other_project.gpr"; |
| project My_Project extends "extended.gpr" is |
| end My_Project; |
| @end example |
| |
| These dependencies form a @strong{directed graph}, potentially cyclic when using |
| @strong{limited with}. The subgraph reflecting the @strong{extends} relations is a tree. |
| |
| A project's @strong{immediate sources} are the source files directly defined by |
| that project, either implicitly by residing in the project source directories, |
| or explicitly through any of the source-related attributes. |
| More generally, a project's @strong{sources} are the immediate sources of the |
| project together with the immediate sources (unless overridden) of any project |
| on which it depends directly or indirectly. |
| |
| A @strong{project hierarchy} can be created, where projects are children of |
| other projects. The name of such a child project must be @cite{Parent.Child}, |
| where @cite{Parent} is the name of the parent project. In particular, this |
| makes all @emph{with} clauses of the parent project automatically visible |
| in the child project. |
| |
| @example |
| project ::= context_clause project_declaration |
| |
| context_clause ::= @{with_clause@} |
| with_clause ::= *with* path_name @{ , path_name @} ; |
| path_name ::= string_literal |
| |
| project_declaration ::= simple_project_declaration | project_extension |
| simple_project_declaration ::= |
| project <project_>name is |
| @{declarative_item@} |
| end <project_>simple_name; |
| @end example |
| |
| @node Qualified Projects,Declarations,Project Declaration,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager qualified-projects}@anchor{176}@anchor{gnat_ugn/gnat_project_manager id39}@anchor{19a} |
| @subsection Qualified Projects |
| |
| |
| Before the reserved @cite{project}, there may be one or two @strong{qualifiers}, that |
| is identifiers or reserved words, to qualify the project. |
| The current list of qualifiers is: |
| |
| |
| @table @asis |
| |
| @item @strong{abstract}: |
| |
| Qualifies a project with no sources. |
| Such a project must either have no declaration of attributes @cite{Source_Dirs}, |
| @cite{Source_Files}, @cite{Languages} or @cite{Source_List_File}, or one of |
| @cite{Source_Dirs}, @cite{Source_Files}, or @cite{Languages} must be declared |
| as empty. If it extends another project, the project it extends must also be a |
| qualified abstract project. |
| |
| @item @strong{standard}: |
| |
| A standard project is a non library project with sources. |
| This is the default (implicit) qualifier. |
| |
| @item @strong{aggregate}: |
| |
| A project whose sources are aggregated from other project files. |
| |
| @item @strong{aggregate library}: |
| |
| A library whose sources are aggregated from other project |
| or library project files. |
| |
| @item @strong{library}: |
| |
| A library project must declare both attributes |
| Library_Name` and @cite{Library_Dir}. |
| |
| @item @strong{configuration}: |
| |
| A configuration project cannot be in a project tree. |
| It describes compilers and other tools to @emph{gprbuild}. |
| @end table |
| |
| @node Declarations,Packages,Qualified Projects,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager declarations}@anchor{19b}@anchor{gnat_ugn/gnat_project_manager id40}@anchor{19c} |
| @subsection Declarations |
| |
| |
| Declarations introduce new entities that denote types, variables, attributes, |
| and packages. Some declarations can only appear immediately within a project |
| declaration. Others can appear within a project or within a package. |
| |
| @example |
| declarative_item ::= simple_declarative_item |
| | typed_string_declaration |
| | package_declaration |
| |
| simple_declarative_item ::= variable_declaration |
| | typed_variable_declaration |
| | attribute_declaration |
| | case_construction |
| | empty_declaration |
| |
| empty_declaration ::= *null* ; |
| @end example |
| |
| An empty declaration is allowed anywhere a declaration is allowed. It has |
| no effect. |
| |
| @node Packages,Expressions,Declarations,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager packages}@anchor{156}@anchor{gnat_ugn/gnat_project_manager id41}@anchor{19d} |
| @subsection Packages |
| |
| |
| A project file may contain @strong{packages}, that group attributes (typically |
| all the attributes that are used by one of the GNAT tools). |
| |
| A package with a given name may only appear once in a project file. |
| The following packages are currently supported in project files |
| (See @ref{155,,Attributes} for the list of attributes that each can contain). |
| |
| |
| @table @asis |
| |
| @item @emph{Binder} |
| |
| This package specifies characteristics useful when invoking the binder either |
| directly via the @emph{gnat} driver or when using @emph{gprbuild}. |
| See @ref{160,,Main Subprograms}. |
| |
| @item @emph{Builder} |
| |
| This package specifies the compilation options used when building an |
| executable or a library for a project. Most of the options should be |
| set in one of @cite{Compiler}, @cite{Binder} or @cite{Linker} packages, |
| but there are some general options that should be defined in this |
| package. See @ref{160,,Main Subprograms}, and @ref{165,,Executable File Names} in |
| particular. |
| @end table |
| |
| |
| |
| @table @asis |
| |
| @item @emph{Clean} |
| |
| This package specifies the options used when cleaning a project or a project |
| tree using the tools @emph{gnatclean} or @emph{gprclean}. |
| |
| @item @emph{Compiler} |
| |
| This package specifies the compilation options used by the compiler for |
| each languages. See @ref{161,,Tools Options in Project Files}. |
| |
| @item @emph{Cross_Reference} |
| |
| This package specifies the options used when calling the library tool |
| @emph{gnatxref} via the @emph{gnat} driver. Its attributes |
| @strong{Default_Switches} and @strong{Switches} have the same semantics as for the |
| package @cite{Builder}. |
| @end table |
| |
| |
| |
| @table @asis |
| |
| @item @emph{Finder} |
| |
| This package specifies the options used when calling the search tool |
| @emph{gnatfind} via the @emph{gnat} driver. Its attributes |
| @strong{Default_Switches} and @strong{Switches} have the same semantics as for the |
| package @cite{Builder}. |
| |
| @item @emph{Gnatls} |
| |
| This package specifies the options to use when invoking @emph{gnatls} |
| via the @emph{gnat} driver. |
| @end table |
| |
| |
| |
| @table @asis |
| |
| @item @emph{IDE} |
| |
| This package specifies the options used when starting an integrated |
| development environment, for instance @emph{GPS} or @emph{Gnatbench}. |
| |
| @item @emph{Install} |
| |
| This package specifies the options used when installing a project |
| with @emph{gprinstall}. See @ref{16b,,Installation}. |
| |
| @item @emph{Linker} |
| |
| This package specifies the options used by the linker. |
| See @ref{160,,Main Subprograms}. |
| @end table |
| |
| |
| |
| @table @asis |
| |
| @item @emph{Naming} |
| |
| @quotation |
| |
| This package specifies the naming conventions that apply |
| to the source files in a project. In particular, these conventions are |
| used to automatically find all source files in the source directories, |
| or given a file name to find out its language for proper processing. |
| See @ref{14e,,Naming Schemes}. |
| @end quotation |
| |
| |
| @item @emph{Remote} |
| |
| This package is used by @emph{gprbuild} to describe how distributed |
| compilation should be done. |
| |
| @item @emph{Stack} |
| |
| This package specifies the options used when calling the tool |
| @emph{gnatstack} via the @emph{gnat} driver. Its attributes |
| @strong{Default_Switches} and @strong{Switches} have the same semantics as for the |
| package @cite{Builder}. |
| |
| @item @emph{Synchronize} |
| |
| This package specifies the options used when calling the tool |
| @emph{gnatsync} via the @emph{gnat} driver. |
| @end table |
| |
| In its simplest form, a package may be empty: |
| |
| @example |
| project Simple is |
| package Builder is |
| end Builder; |
| end Simple; |
| @end example |
| |
| A package may contain @strong{attribute declarations}, |
| @strong{variable declarations} and @strong{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 @cite{gnat}. |
| |
| A package can also be defined by a @strong{renaming declaration}. The new package |
| renames a package declared in a different project file, and has the same |
| attributes as the package it renames. The name of the renamed package |
| must be the same as the name of the renaming package. The project must |
| contain a package declaration with this name, and the project |
| must appear in the context clause of the current project, or be its parent |
| project. It is not possible to add or override attributes to the renaming |
| project. If you need to do so, you should use an @strong{extending declaration} |
| (see below). |
| |
| 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. This is a very common way to share settings |
| between projects. |
| |
| Finally, a package can also be defined by an @strong{extending declaration}. This is |
| similar to a @strong{renaming declaration}, except that it is possible to add or |
| override attributes. |
| |
| @example |
| package_declaration ::= package_spec | package_renaming | package_extension |
| package_spec ::= |
| package <package_>simple_name is |
| @{simple_declarative_item@} |
| end package_identifier ; |
| package_renaming ::== |
| package <package_>simple_name renames <project_>simple_name.package_identifier ; |
| package_extension ::== |
| package <package_>simple_name extends <project_>simple_name.package_identifier is |
| @{simple_declarative_item@} |
| end package_identifier ; |
| @end example |
| |
| @node Expressions,External Values,Packages,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager expressions}@anchor{19e}@anchor{gnat_ugn/gnat_project_manager id42}@anchor{19f} |
| @subsection Expressions |
| |
| |
| An expression is any value that can be assigned to an attribute or a |
| variable. It is either a literal value, or a construct requiring runtime |
| computation by the project manager. In a project file, the computed value of |
| an expression is either a string or a list of strings. |
| |
| A string value is one of: |
| |
| |
| @itemize * |
| |
| @item |
| A literal string, for instance @cite{"comm/my_proj.gpr"} |
| |
| @item |
| The name of a variable that evaluates to a string (see @ref{158,,Variables}) |
| |
| @item |
| The name of an attribute that evaluates to a string (see @ref{155,,Attributes}) |
| |
| @item |
| An external reference (see @ref{157,,External Values}) |
| |
| @item |
| A concatenation of the above, as in @cite{"prefix_" & Var}. |
| @end itemize |
| |
| A list of strings is one of the following: |
| |
| |
| @itemize * |
| |
| @item |
| A parenthesized comma-separated list of zero or more string expressions, for |
| instance @cite{(File_Name@comma{} "gnat.adc"@comma{} File_Name & ".orig")} or @cite{()}. |
| |
| @item |
| The name of a variable that evaluates to a list of strings |
| |
| @item |
| The name of an attribute that evaluates to a list of strings |
| |
| @item |
| A concatenation of a list of strings and a string (as defined above), for |
| instance @cite{("A"@comma{} "B") & "C"} |
| |
| @item |
| A concatenation of two lists of strings |
| @end itemize |
| |
| The following is the grammar for expressions |
| |
| @example |
| string_literal ::= "@{string_element@}" -- Same as Ada |
| string_expression ::= string_literal |
| | *variable_*name |
| | external_value |
| | attribute_reference |
| | ( string_expression @{ & string_expression @} ) |
| string_list ::= ( string_expression @{ , string_expression @} ) |
| | *string_variable*_name |
| | *string_*attribute_reference |
| term ::= string_expression | string_list |
| expression ::= term @{ & term @} -- Concatenation |
| @end example |
| |
| Concatenation involves strings and list of strings. As soon as a list of |
| strings is involved, the result of the concatenation is a list of strings. The |
| following Ada declarations show the existing operators: |
| |
| @example |
| function "&" (X : String; Y : String) return String; |
| function "&" (X : String_List; Y : String) return String_List; |
| function "&" (X : String_List; Y : String_List) return String_List; |
| @end example |
| |
| Here are some specific examples: |
| |
| @example |
| List := () & File_Name; -- One string in this list |
| List2 := List & (File_Name & ".orig"); -- Two strings |
| Big_List := List & Lists2; -- Three strings |
| Illegal := "gnat.adc" & List2; -- Illegal, must start with list |
| @end example |
| |
| @node External Values,Typed String Declaration,Expressions,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager external-values}@anchor{157}@anchor{gnat_ugn/gnat_project_manager id43}@anchor{1a0} |
| @subsection External Values |
| |
| |
| An external value is an expression whose value is obtained from the command |
| that invoked the processing of the current project file (typically a |
| @emph{gprbuild} command). |
| |
| There are two kinds of external values, one that returns a single string, and |
| one that returns a string list. |
| |
| The syntax of a single string external value is: |
| |
| @example |
| external_value ::= *external* ( string_literal [, string_literal] ) |
| @end example |
| |
| The first string_literal is the string to be used on the command line or |
| in the environment to specify the external value. The second string_literal, |
| if present, is the default to use if there is no specification for this |
| external value either on the command line or in the environment. |
| |
| Typically, the external value will either exist in the |
| environment variables |
| or be specified on the command line through the |
| @code{-X@emph{vbl}=@emph{value}} switch. If both |
| are specified, then the command line value is used, so that a user can more |
| easily override the value. |
| |
| The function @cite{external} always returns a string. It is an error if the |
| value was not found in the environment and no default was specified in the |
| call to @cite{external}. |
| |
| An external reference may be part of a string expression or of a string |
| list expression, and can therefore appear in a variable declaration or |
| an attribute declaration. |
| |
| Most of the time, this construct is used to initialize typed variables, which |
| are then used in @strong{case} constructions to control the value assigned to |
| attributes in various scenarios. Thus such variables are often called |
| @strong{scenario variables}. |
| |
| The syntax for a string list external value is: |
| |
| @example |
| external_value ::= *external_as_list* ( string_literal , string_literal ) |
| @end example |
| |
| The first string_literal is the string to be used on the command line or |
| in the environment to specify the external value. The second string_literal is |
| the separator between each component of the string list. |
| |
| If the external value does not exist in the environment or on the command line, |
| the result is an empty list. This is also the case, if the separator is an |
| empty string or if the external value is only one separator. |
| |
| Any separator at the beginning or at the end of the external value is |
| discarded. Then, if there is no separator in the external value, the result is |
| a string list with only one string. Otherwise, any string between the beginning |
| and the first separator, between two consecutive separators and between the |
| last separator and the end are components of the string list. |
| |
| @example |
| *external_as_list* ("SWITCHES", ",") |
| @end example |
| |
| If the external value is "-O2,-g", |
| the result is ("-O2", "-g"). |
| |
| If the external value is ",-O2,-g,", |
| the result is also ("-O2", "-g"). |
| |
| if the external value is "-gnatv", |
| the result is ("-gnatv"). |
| |
| If the external value is ",,", the result is (""). |
| |
| If the external value is ",", the result is (), the empty string list. |
| |
| @node Typed String Declaration,Variables,External Values,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager id44}@anchor{1a1}@anchor{gnat_ugn/gnat_project_manager typed-string-declaration}@anchor{1a2} |
| @subsection Typed String Declaration |
| |
| |
| A @strong{type declaration} introduces a discrete set of string literals. |
| If a string variable is declared to have this type, its value |
| is restricted to the given set of literals. These are the only named |
| types in project files. A string type may only be declared at the project |
| level, not inside a package. |
| |
| @example |
| typed_string_declaration ::= |
| *type* *<typed_string_>*_simple_name *is* ( string_literal @{, string_literal@} ); |
| @end example |
| |
| 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. |
| Here is an example of a string type declaration: |
| |
| @example |
| type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS"); |
| @end example |
| |
| Variables of a string type are called @strong{typed variables}; all other |
| variables are called @strong{untyped variables}. Typed variables are |
| particularly useful in @cite{case} constructions, to support conditional |
| attribute declarations. (See @ref{1a3,,Case Constructions}). |
| |
| A string type may be referenced by its name if it has been declared in the same |
| project file, or by an expanded name whose prefix is the name of the project |
| in which it is declared. |
| |
| @node Variables,Case Constructions,Typed String Declaration,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager variables}@anchor{158}@anchor{gnat_ugn/gnat_project_manager id45}@anchor{1a4} |
| @subsection Variables |
| |
| |
| @strong{Variables} store values (strings or list of strings) and can appear |
| as part of an expression. The declaration of a variable creates the |
| variable and assigns the value of the expression to it. The name of the |
| variable is available immediately after the assignment symbol, if you |
| need to reuse its old value to compute the new value. Before the completion |
| of its first declaration, the value of a variable defaults to the empty |
| string (""). |
| |
| A @strong{typed} variable can be used as part of a @strong{case} expression to |
| compute the value, but it can only be declared once in the project file, |
| so that all case constructions see the same value for the variable. This |
| provides more consistency and makes the project easier to understand. |
| The syntax for its declaration is identical to the Ada syntax for an |
| object declaration. In effect, a typed variable acts as a constant. |
| |
| An @strong{untyped} variable can be declared and overridden multiple times |
| within the same project. It is declared implicitly through an Ada |
| assignment. The first declaration establishes the kind of the variable |
| (string or list of strings) and successive declarations must respect |
| the initial kind. Assignments are executed in the order in which they |
| appear, so the new value replaces the old one and any subsequent reference |
| to the variable uses the new value. |
| |
| A variable may be declared at the project file level, or within a package. |
| |
| @example |
| typed_variable_declaration ::= |
| *<typed_variable_>*simple_name : *<typed_string_>*name := string_expression; |
| |
| variable_declaration ::= *<variable_>*simple_name := expression; |
| @end example |
| |
| Here are some examples of variable declarations: |
| |
| @example |
| This_OS : OS := external ("OS"); -- a typed variable declaration |
| That_OS := "GNU/Linux"; -- an untyped variable declaration |
| |
| Name := "readme.txt"; |
| Save_Name := Name & ".saved"; |
| |
| 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"); |
| @end example |
| |
| A @strong{variable reference} may take several forms: |
| |
| |
| @itemize * |
| |
| @item |
| The simple variable name, for a variable in the current package (if any) |
| or in the current project |
| |
| @item |
| An expanded name, whose prefix is a context name. |
| @end itemize |
| |
| A @strong{context} may be one of the following: |
| |
| |
| @itemize * |
| |
| @item |
| The name of an existing package in the current project |
| |
| @item |
| The name of an imported project of the current project |
| |
| @item |
| The name of an ancestor project (i.e., a project extended by the current |
| project, either directly or indirectly) |
| |
| @item |
| An expanded name whose prefix is an imported/parent project name, and |
| whose selector is a package name in that project. |
| @end itemize |
| |
| @node Case Constructions,Attributes,Variables,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager id46}@anchor{1a5}@anchor{gnat_ugn/gnat_project_manager case-constructions}@anchor{1a3} |
| @subsection Case Constructions |
| |
| |
| A @strong{case} construction is used in a project file to effect conditional |
| behavior. Through this construction, you can set the value of attributes |
| and variables depending on the value previously assigned to a typed |
| variable. |
| |
| All choices in a choice list must be distinct. Unlike Ada, the choice |
| lists of all alternatives do not need to include all values of the type. |
| An @cite{others} choice must appear last in the list of alternatives. |
| |
| The syntax of a @cite{case} construction is based on the Ada case construction |
| (although the @cite{null} declaration for empty alternatives is optional). |
| |
| The case expression must be a string variable, either typed or not, whose value |
| is often given by an external reference (see @ref{157,,External Values}). |
| |
| Each alternative starts with the reserved word @cite{when}, either a list of |
| literal strings separated by the @cite{"|"} character or the reserved word |
| @cite{others}, and the @cite{"=>"} token. |
| When the case expression is a typed string variable, each literal string must |
| belong to the string type that is the type of the case variable. |
| After each @cite{=>}, there are zero or more declarations. The only |
| declarations allowed in a case construction are other case constructions, |
| attribute declarations and variable declarations. String type declarations and |
| package declarations are not allowed. Variable declarations are restricted to |
| variables that have already been declared before the case construction. |
| |
| @example |
| case_construction ::= |
| *case* *<variable_>*name *is* @{case_item@} *end case* ; |
| |
| case_item ::= |
| *when* discrete_choice_list => |
| @{case_declaration |
| | attribute_declaration |
| | variable_declaration |
| | empty_declaration@} |
| |
| discrete_choice_list ::= string_literal @{| string_literal@} | *others* |
| @end example |
| |
| Here is a typical example, with a typed string variable: |
| |
| @example |
| project MyProj is |
| type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS"); |
| OS : OS_Type := external ("OS", "GNU/Linux"); |
| |
| package Compiler is |
| case OS is |
| when "GNU/Linux" | "Unix" => |
| for Switches ("Ada") |
| use ("-gnath"); |
| when "NT" => |
| for Switches ("Ada") |
| use ("-gnatP"); |
| when others => |
| null; |
| end case; |
| end Compiler; |
| end MyProj; |
| @end example |
| |
| @node Attributes,,Case Constructions,Project File Reference |
| @anchor{gnat_ugn/gnat_project_manager id47}@anchor{1a6}@anchor{gnat_ugn/gnat_project_manager attributes}@anchor{155} |
| @subsection Attributes |
| |
| |
| A project (and its packages) may have @strong{attributes} that define |
| the project's properties. Some attributes have values that are strings; |
| others have values that are string lists. |
| |
| @example |
| attribute_declaration ::= |
| simple_attribute_declaration | indexed_attribute_declaration |
| |
| simple_attribute_declaration ::= *for* attribute_designator *use* expression ; |
| |
| indexed_attribute_declaration ::= |
| *for* *<indexed_attribute_>*simple_name ( string_literal) *use* expression ; |
| |
| attribute_designator ::= |
| *<simple_attribute_>*simple_name |
| | *<indexed_attribute_>*simple_name ( string_literal ) |
| @end example |
| |
| There are two categories of attributes: @strong{simple attributes} |
| and @strong{indexed attributes}. |
| Each simple attribute has a default value: the empty string (for string |
| attributes) and the empty list (for string list attributes). |
| An attribute declaration defines a new value for an attribute, and overrides |
| the previous value. The syntax of a simple attribute declaration is similar to |
| that of an attribute definition clause in Ada. |
| |
| Some attributes are indexed. These attributes are mappings whose |
| domain is a set of strings. They are declared one association |
| at a time, by specifying a point in the domain and the corresponding image |
| of the attribute. |
| Like untyped variables and simple attributes, indexed attributes |
| may be declared several times. Each declaration supplies a new value for the |
| attribute, and replaces the previous setting. |
| |
| Here are some examples of attribute declarations: |
| |
| @example |
| -- simple attributes |
| for Object_Dir use "objects"; |
| for Source_Dirs use ("units", "test/drivers"); |
| |
| -- indexed attributes |
| for Body ("main") use "Main.ada"; |
| for Switches ("main.ada") |
| use ("-v", "-gnatv"); |
| for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g"; |
| |
| -- indexed attributes copy (from package Builder in project Default) |
| -- The package name must always be specified, even if it is the current |
| -- package. |
| for Default_Switches use Default.Builder'Default_Switches; |
| @end example |
| |
| Attributes references may appear anywhere in expressions, and are used |
| to retrieve the value previously assigned to the attribute. If an attribute |
| has not been set in a given package or project, its value defaults to the |
| empty string or the empty list, with some exceptions. |
| |
| @example |
| attribute_reference ::= |
| attribute_prefix ' *<simple_attribute>_*simple_name [ (string_literal) ] |
| attribute_prefix ::= *project* |
| | *<project_>*simple_name |
| | package_identifier |
| | *<project_>*simple_name . package_identifier |
| @end example |
| |
| Examples are: |
| |
| @example |
| <project>'Object_Dir |
| Naming'Dot_Replacement |
| Imported_Project'Source_Dirs |
| Imported_Project.Naming'Casing |
| Builder'Default_Switches ("Ada") |
| @end example |
| |
| The exceptions to the empty defaults are: |
| |
| |
| @itemize * |
| |
| @item |
| Object_Dir: default is "." |
| |
| @item |
| Exec_Dir: default is 'Object_Dir, that is the value of attribute |
| Object_Dir in the same project, declared or defaulted. |
| |
| @item |
| Source_Dirs: default is (".") |
| @end itemize |
| |
| The prefix of an attribute may be: |
| |
| |
| @itemize * |
| |
| @item |
| @cite{project} for an attribute of the current project |
| |
| @item |
| The name of an existing package of the current project |
| |
| @item |
| The name of an imported project |
| |
| @item |
| The name of a parent project that is extended by the current project |
| |
| @item |
| An expanded name whose prefix is imported/parent project name, |
| and whose selector is a package name |
| @end itemize |
| |
| In the following sections, all predefined attributes are succinctly described, |
| first the project level attributes, that is those attributes that are not in a |
| package, then the attributes in the different packages. |
| |
| It is possible for different tools to dynamically create new packages with |
| attributes, or new attributes in predefined packages. These attributes are |
| not documented here. |
| |
| The attributes under Configuration headings are usually found only in |
| configuration project files. |
| |
| The characteristics of each attribute are indicated as follows: |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Type of value} |
| |
| The value of an attribute may be a single string, indicated by the word |
| "single", or a string list, indicated by the word "list". |
| |
| @item |
| @strong{Read-only} |
| |
| When the attribute is read-only, that is when it is not allowed to declare |
| the attribute, this is indicated by the words "read-only". |
| |
| @item |
| @strong{Optional index} |
| |
| If it is allowed in the value of the attribute (both single and list) to have |
| an optional index, this is indicated by the words "optional index". |
| |
| @item |
| @strong{Indexed attribute} |
| |
| When it is an indexed attribute, this is indicated by the word "indexed". |
| |
| @item |
| @strong{Case-sensitivity of the index} |
| |
| For an indexed attribute, if the index is case-insensitive, this is indicated |
| by the words "case-insensitive index". |
| |
| @item |
| @strong{File name index} |
| |
| For an indexed attribute, when the index is a file name, this is indicated by |
| the words "file name index". The index may or may not be case-sensitive, |
| depending on the platform. |
| |
| @item |
| @strong{others allowed in index} |
| |
| For an indexed attribute, if it is allowed to use @strong{others} as the index, |
| this is indicated by the words "others allowed". |
| |
| When @strong{others} is used as the index of an indexed attribute, the value of |
| the attribute indexed by @strong{others} is used when no other index would apply. |
| @end itemize |
| |
| @menu |
| * Project Level Attributes:: |
| * Package Binder Attributes:: |
| * Package Builder Attributes:: |
| * Package Clean Attributes:: |
| * Package Compiler Attributes:: |
| * Package Cross_Reference Attributes:: |
| * Package Finder Attributes:: |
| * Package gnatls Attributes:: |
| * Package IDE Attributes:: |
| * Package Install Attributes:: |
| * Package Linker Attributes:: |
| * Package Naming Attributes:: |
| * Package Remote Attributes:: |
| * Package Stack Attributes:: |
| * Package Synchronize Attributes:: |
| |
| @end menu |
| |
| @node Project Level Attributes,Package Binder Attributes,,Attributes |
| @anchor{gnat_ugn/gnat_project_manager project-level-attributes}@anchor{1a7}@anchor{gnat_ugn/gnat_project_manager id48}@anchor{1a8} |
| @subsubsection Project Level Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{General} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Name}: single, read-only |
| |
| The name of the project. |
| |
| @item |
| @strong{Project_Dir}: single, read-only |
| |
| The path name of the project directory. |
| |
| @item |
| @strong{Main}: list, optional index |
| |
| The list of main sources for the executables. |
| |
| @item |
| @strong{Languages}: list |
| |
| The list of languages of the sources of the project. |
| |
| @item |
| @strong{Roots}: list, indexed, file name index |
| |
| The index is the file name of an executable source. Indicates the list of units |
| from the main project that need to be bound and linked with their closures |
| with the executable. The index is either a file name, a language name or "*". |
| The roots for an executable source are those in @strong{Roots} with an index that |
| is the executable source file name, if declared. Otherwise, they are those in |
| @strong{Roots} with an index that is the language name of the executable source, |
| if present. Otherwise, they are those in @strong{Roots ("*")}, if declared. If none |
| of these three possibilities are declared, then there are no roots for the |
| executable source. |
| |
| @item |
| @strong{Externally_Built}: single |
| |
| Indicates if the project is externally built. |
| Only case-insensitive values allowed are "true" and "false", the default. |
| @end itemize |
| |
| @item |
| @strong{Directories} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Object_Dir}: single |
| |
| Indicates the object directory for the project. |
| |
| @item |
| @strong{Exec_Dir}: single |
| |
| Indicates the exec directory for the project, that is the directory where the |
| executables are. |
| |
| @item |
| @strong{Source_Dirs}: list |
| |
| The list of source directories of the project. |
| |
| @item |
| @strong{Inherit_Source_Path}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of language names. Indicates that |
| in the source search path of the index language the source directories of |
| the languages in the list should be included. |
| |
| Example: |
| |
| @example |
| for Inherit_Source_Path ("C++") use ("C"); |
| @end example |
| |
| @item |
| @strong{Exclude_Source_Dirs}: list |
| |
| The list of directories that are included in Source_Dirs but are not source |
| directories of the project. |
| |
| @item |
| @strong{Ignore_Source_Sub_Dirs}: list |
| |
| Value is a list of simple names for subdirectories that are removed from the |
| list of source directories, including theur subdirectories. |
| @end itemize |
| |
| @item |
| @strong{Source Files} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Source_Files}: list |
| |
| Value is a list of source file simple names. |
| |
| @item |
| @strong{Locally_Removed_Files}: list |
| |
| Obsolescent. Equivalent to Excluded_Source_Files. |
| |
| @item |
| @strong{Excluded_Source_Files}: list |
| |
| Value is a list of simple file names that are not sources of the project. |
| Allows to remove sources that are inherited or found in the source directories |
| and that match the naming scheme. |
| |
| @item |
| @strong{Source_List_File}: single |
| |
| Value is a text file name that contains a list of source file simple names, |
| one on each line. |
| |
| @item |
| @strong{Excluded_Source_List_File}: single |
| |
| Value is a text file name that contains a list of file simple names that |
| are not sources of the project. |
| |
| @item |
| @strong{Interfaces}: list |
| |
| Value is a list of file names that constitutes the interfaces of the project. |
| @end itemize |
| |
| @item |
| @strong{Aggregate Projects} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Project_Files}: list |
| |
| Value is the list of aggregated projects. |
| |
| @item |
| @strong{Project_Path}: list |
| |
| Value is a list of directories that are added to the project search path when |
| looking for the aggregated projects. |
| |
| @item |
| @strong{External}: single, indexed |
| |
| Index is the name of an external reference. Value is the value of the |
| external reference to be used when parsing the aggregated projects. |
| @end itemize |
| |
| @item |
| @strong{Libraries} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Library_Dir}: single |
| |
| Value is the name of the library directory. This attribute needs to be |
| declared for each library project. |
| |
| @item |
| @strong{Library_Name}: single |
| |
| Value is the name of the library. This attribute needs to be declared or |
| inherited for each library project. |
| |
| @item |
| @strong{Library_Kind}: single |
| |
| Specifies the kind of library: static library (archive) or shared library. |
| Case-insensitive values must be one of "static" for archives (the default) or |
| "dynamic" or "relocatable" for shared libraries. |
| |
| @item |
| @strong{Library_Version}: single |
| |
| Value is the name of the library file. |
| |
| @item |
| @strong{Library_Interface}: list |
| |
| Value is the list of unit names that constitutes the interfaces |
| of a Stand-Alone Library project. |
| |
| @item |
| @strong{Library_Standalone}: single |
| |
| Specifies if a Stand-Alone Library (SAL) is encapsulated or not. |
| Only authorized case-insensitive values are "standard" for non encapsulated |
| SALs, "encapsulated" for encapsulated SALs or "no" for non SAL library project. |
| |
| @item |
| @strong{Library_Encapsulated_Options}: list |
| |
| Value is a list of options that need to be used when linking an encapsulated |
| Stand-Alone Library. |
| |
| @item |
| @strong{Library_Encapsulated_Supported}: single |
| |
| Indicates if encapsulated Stand-Alone Libraries are supported. Only |
| authorized case-insensitive values are "true" and "false" (the default). |
| |
| @item |
| @strong{Library_Auto_Init}: single |
| |
| Indicates if a Stand-Alone Library is auto-initialized. Only authorized |
| case-insentive values are "true" and "false". |
| |
| @item |
| @strong{Leading_Library_Options}: list |
| |
| Value is a list of options that are to be used at the beginning of |
| the command line when linking a shared library. |
| |
| @item |
| @strong{Library_Options}: list |
| |
| Value is a list of options that are to be used when linking a shared library. |
| |
| @item |
| @strong{Library_Rpath_Options}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of options for an invocation of the |
| compiler of the language. This invocation is done for a shared library project |
| with sources of the language. The output of the invocation is the path name |
| of a shared library file. The directory name is to be put in the run path |
| option switch when linking the shared library for the project. |
| |
| @item |
| @strong{Library_Src_Dir}: single |
| |
| Value is the name of the directory where copies of the sources of the |
| interfaces of a Stand-Alone Library are to be copied. |
| |
| @item |
| @strong{Library_ALI_Dir}: single |
| |
| Value is the name of the directory where the ALI files of the interfaces |
| of a Stand-Alone Library are to be copied. When this attribute is not declared, |
| the directory is the library directory. |
| |
| @item |
| @strong{Library_gcc}: single |
| |
| Obsolescent attribute. Specify the linker driver used to link a shared library. |
| Use instead attribute Linker'Driver. |
| |
| @item |
| @strong{Library_Symbol_File}: single |
| |
| Value is the name of the library symbol file. |
| |
| @item |
| @strong{Library_Symbol_Policy}: single |
| |
| Indicates the symbol policy kind. Only authorized case-insensitive values are |
| "autonomous", "default", "compliant", "controlled" or "direct". |
| |
| @item |
| @strong{Library_Reference_Symbol_File}: single |
| |
| Value is the name of the reference symbol file. |
| @end itemize |
| |
| @item |
| @strong{Configuration - General} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Default_Language}: single |
| |
| Value is the case-insensitive name of the language of a project when attribute |
| Languages is not specified. |
| |
| @item |
| @strong{Run_Path_Option}: list |
| |
| Value is the list of switches to be used when specifying the run path option |
| in an executable. |
| |
| @item |
| @strong{Run_Path_Origin}: single |
| |
| Value is the the string that may replace the path name of the executable |
| directory in the run path options. |
| |
| @item |
| @strong{Separate_Run_Path_Options}: single |
| |
| Indicates if there may be several run path options specified when linking an |
| executable. Only authorized case-insensitive values are "true" or "false" (the |
| default). |
| |
| @item |
| @strong{Toolchain_Version}: single, indexed, case-insensitive index |
| |
| Index is a language name. Specify the version of a toolchain for a language. |
| |
| @item |
| @strong{Toolchain_Description}: single, indexed, case-insensitive index |
| |
| Obsolescent. No longer used. |
| |
| @item |
| @strong{Object_Generated}: single, indexed, case-insensitive index |
| |
| Index is a language name. Indicates if invoking the compiler for a language |
| produces an object file. Only authorized case-insensitive values are "false" |
| and "true" (the default). |
| |
| @item |
| @strong{Objects_Linked}: single, indexed, case-insensitive index |
| |
| Index is a language name. Indicates if the object files created by the compiler |
| for a language need to be linked in the executable. Only authorized |
| case-insensitive values are "false" and "true" (the default). |
| |
| @item |
| @strong{Target}: single |
| |
| Value is the name of the target platform. Taken into account only in the main |
| project. |
| |
| Note that when the target is specified on the command line (usually with |
| a switch --target=), the value of attribute reference 'Target is the one |
| specified on the command line. |
| |
| @item |
| @strong{Runtime}: single, indexed, case-insensitive index |
| |
| Index is a language name. Indicates the runtime directory that is to be used |
| when using the compiler of the language. Taken into account only in the main |
| project. |
| |
| Note that when the runtime is specified for a language on the command line |
| (usually with a switch --RTS), the value of attribute reference 'Runtime |
| for this language is the one specified on the command line. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Libraries} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Library_Builder}: single |
| |
| Value is the path name of the application that is to be used to build |
| libraries. Usually the path name of "gprlib". |
| |
| @item |
| @strong{Library_Support}: single |
| |
| Indicates the level of support of libraries. Only authorized case-insensitive |
| values are "static_only", "full" or "none" (the default). |
| @end itemize |
| |
| @item |
| @strong{Configuration - Archives} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Archive_Builder}: list |
| |
| Value is the name of the application to be used to create a static library |
| (archive), followed by the options to be used. |
| |
| @item |
| @strong{Archive_Builder_Append_Option}: list |
| |
| Value is the list of options to be used when invoking the archive builder |
| to add project files into an archive. |
| |
| @item |
| @strong{Archive_Indexer}: list |
| |
| Value is the name of the archive indexer, followed by the required options. |
| |
| @item |
| @strong{Archive_Suffix}: single |
| |
| Value is the extension of archives. When not declared, the extension is ".a". |
| |
| @item |
| @strong{Library_Partial_Linker}: list |
| |
| Value is the name of the partial linker executable, followed by the required |
| options. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Shared Libraries} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Shared_Library_Prefix}: single |
| |
| Value is the prefix in the name of shared library files. When not declared, |
| the prefix is "lib". |
| |
| @item |
| @strong{Shared_Library_Suffix}: single |
| |
| Value is the the extension of the name of shared library files. When not |
| declared, the extension is ".so". |
| |
| @item |
| @strong{Symbolic_Link_Supported}: single |
| |
| Indicates if symbolic links are supported on the platform. Only authorized |
| case-insensitive values are "true" and "false" (the default). |
| |
| @item |
| @strong{Library_Major_Minor_Id_Supported}: single |
| |
| Indicates if major and minor ids for shared library names are supported on |
| the platform. Only authorized case-insensitive values are "true" and "false" |
| (the default). |
| |
| @item |
| @strong{Library_Auto_Init_Supported}: single |
| |
| Indicates if auto-initialization of Stand-Alone Libraries is supported. Only |
| authorized case-insensitive values are "true" and "false" (the default). |
| |
| @item |
| @strong{Shared_Library_Minimum_Switches}: list |
| |
| Value is the list of required switches when linking a shared library. |
| |
| @item |
| @strong{Library_Version_Switches}: list |
| |
| Value is the list of switches to specify a internal name for a shared library. |
| |
| @item |
| @strong{Library_Install_Name_Option}: single |
| |
| Value is the name of the option that needs to be used, concatenated with the |
| path name of the library file, when linking a shared library. |
| |
| @item |
| @strong{Runtime_Library_Dir}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the path name of the directory where the |
| runtime libraries are located. |
| |
| @item |
| @strong{Runtime_Source_Dir}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the path name of the directory where the |
| sources of runtime libraries are located. |
| @end itemize |
| @end itemize |
| |
| @node Package Binder Attributes,Package Builder Attributes,Project Level Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager package-binder-attributes}@anchor{1a9}@anchor{gnat_ugn/gnat_project_manager id49}@anchor{1aa} |
| @subsubsection Package Binder Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{General} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Default_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to be used when binding |
| code of the language, if there is no applicable attribute Switches. |
| |
| @item |
| @strong{Switches}: list, optional index, indexed, |
| case-insensitive index, others allowed |
| |
| Index is either a language name or a source file name. Value is the list of |
| switches to be used when binding code. Index is either the source file name |
| of the executable to be bound or the language name of the code to be bound. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Binding} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Driver}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the name of the application to be used when |
| binding code of the language. |
| |
| @item |
| @strong{Required_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of the required switches to be |
| used when binding code of the language. |
| |
| @item |
| @strong{Prefix}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is a prefix to be used for the binder exchange |
| file name for the language. Used to have different binder exchange file names |
| when binding different languages. |
| |
| @item |
| @strong{Objects_Path}: single,indexed, case-insensitive index |
| |
| Index is a language name. Value is the name of the environment variable that |
| contains the path for the object directories. |
| |
| @item |
| @strong{Object_Path_File}: single,indexed, case-insensitive index |
| |
| Index is a language name. Value is the name of the environment variable. The |
| value of the environment variable is the path name of a text file that |
| contains the list of object directories. |
| @end itemize |
| @end itemize |
| |
| @node Package Builder Attributes,Package Clean Attributes,Package Binder Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager package-builder-attributes}@anchor{1ab}@anchor{gnat_ugn/gnat_project_manager id50}@anchor{1ac} |
| @subsubsection Package Builder Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Default_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of builder switches to be used when |
| building an executable of the language, if there is no applicable attribute |
| Switches. |
| |
| @item |
| @strong{Switches}: list, optional index, indexed, case-insensitive index, |
| others allowed |
| |
| Index is either a language name or a source file name. Value is the list of |
| builder switches to be used when building an executable. Index is either the |
| source file name of the executable to be built or its language name. |
| |
| @item |
| @strong{Global_Compilation_Switches}: list, optional index, indexed, |
| case-insensitive index |
| |
| Index is either a language name or a source file name. Value is the list of |
| compilation switches to be used when building an executable. Index is either |
| the source file name of the executable to be built or its language name. |
| |
| @item |
| @strong{Executable}: single, indexed, case-insensitive index |
| |
| Index is an executable source file name. Value is the simple file name of the |
| executable to be built. |
| |
| @item |
| @strong{Executable_Suffix}: single |
| |
| Value is the extension of the file names of executable. When not specified, |
| the extension is the default extension of executables on the platform. |
| |
| @item |
| @strong{Global_Configuration_Pragmas}: single |
| |
| Value is the file name of a configuration pragmas file that is specified to |
| the Ada compiler when compiling any Ada source in the project tree. |
| |
| @item |
| @strong{Global_Config_File}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the file name of a configuration file that |
| is specified to the compiler when compiling any source of the language in the |
| project tree. |
| @end itemize |
| |
| |
| @node Package Clean Attributes,Package Compiler Attributes,Package Builder Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager package-clean-attributes}@anchor{1ad}@anchor{gnat_ugn/gnat_project_manager id52}@anchor{1ae} |
| @subsubsection Package Clean Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Switches}: list |
| |
| Value is a list of switches to be used by the cleaning application. |
| |
| @item |
| @strong{Source_Artifact_Extensions}: list, indexed, case-insensitive index |
| |
| Index is a language names. Value is the list of extensions for file names |
| derived from object file names that need to be cleaned in the object |
| directory of the project. |
| |
| @item |
| @strong{Object_Artifact_Extensions}: list, indexed, case-insensitive index |
| |
| Index is a language names. Value is the list of extensions for file names |
| derived from source file names that need to be cleaned in the object |
| directory of the project. |
| |
| @item |
| @strong{Artifacts_In_Object_Dir}: single |
| |
| Value is a list of file names expressed as regular expressions that are to be |
| deleted by gprclean in the object directory of the project. |
| |
| @item |
| @strong{Artifacts_In_Exec_Dir}: single |
| |
| Value is list of file names expressed as regular expressions that are to be |
| deleted by gprclean in the exec directory of the main project. |
| @end itemize |
| |
| @node Package Compiler Attributes,Package Cross_Reference Attributes,Package Clean Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager id53}@anchor{1af}@anchor{gnat_ugn/gnat_project_manager package-compiler-attributes}@anchor{1b0} |
| @subsubsection Package Compiler Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{General} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Default_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of switches to be used when invoking |
| the compiler for the language for a source of the project, if there is no |
| applicable attribute Switches. |
| |
| @item |
| @strong{Switches}: list, optional index, indexed, case-insensitive index, |
| others allowed |
| |
| Index is a source file name or a language name. Value is the list of switches |
| to be used when invoking the compiler for the source or for its language. |
| |
| @item |
| @strong{Local_Configuration_Pragmas}: single |
| |
| Value is the file name of a configuration pragmas file that is specified to |
| the Ada compiler when compiling any Ada source in the project. |
| |
| @item |
| @strong{Local_Config_File}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the file name of a configuration file that |
| is specified to the compiler when compiling any source of the language in the |
| project. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Compiling} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Driver}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the name of the executable for the compiler |
| of the language. |
| |
| @item |
| @strong{Language_Kind}: single, indexed, case-insensitive index |
| |
| Index is a language name. Indicates the kind of the language, either file based |
| or unit based. Only authorized case-insensitive values are "unit_based" and |
| "file_based" (the default). |
| |
| @item |
| @strong{Dependency_Kind}: single, indexed, case-insensitive index |
| |
| Index is a language name. Indicates how the dependencies are handled for the |
| language. Only authorized case-insensitive values are "makefile", "ali_file", |
| "ali_closure" or "none" (the default). |
| |
| @item |
| @strong{Required_Switches}: list, indexed, case-insensitive index |
| |
| Equivalent to attribute Leading_Required_Switches. |
| |
| @item |
| @strong{Leading_Required_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of the minimum switches to be used |
| at the beginning of the command line when invoking the compiler for the |
| language. |
| |
| @item |
| @strong{Trailing_Required_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of the minimum switches to be used |
| at the end of the command line when invoking the compiler for the language. |
| |
| @item |
| @strong{PIC_Option}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to be used when |
| compiling a source of the language when the project is a shared library |
| project. |
| |
| @item |
| @strong{Path_Syntax}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the kind of path syntax to be used when |
| invoking the compiler for the language. Only authorized case-insensitive |
| values are "canonical" and "host" (the default). |
| |
| @item |
| @strong{Source_File_Switches}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of switches to be used just before |
| the path name of the source to compile when invoking the compiler for a source |
| of the language. |
| |
| @item |
| @strong{Object_File_Suffix}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the extension of the object files created |
| by the compiler of the language. When not specified, the extension is the |
| default one for the platform. |
| |
| @item |
| @strong{Object_File_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to be used by the |
| compiler of the language to specify the path name of the object file. When not |
| specified, the switch used is "-o". |
| |
| @item |
| @strong{Multi_Unit_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to be used to compile |
| a unit in a multi unit source of the language. The index of the unit in the |
| source is concatenated with the last switches in the list. |
| |
| @item |
| @strong{Multi_Unit_Object_Separator}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the string to be used in the object file |
| name before the index of the unit, when compiling a unit in a multi unit source |
| of the language. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Mapping Files} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Mapping_File_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to be used to specify |
| a mapping file when invoking the compiler for a source of the language. |
| |
| @item |
| @strong{Mapping_Spec_Suffix}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the suffix to be used in a mapping file |
| to indicate that the source is a spec. |
| |
| @item |
| @strong{Mapping_Body_Suffix}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the suffix to be used in a mapping file |
| to indicate that the source is a body. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Config Files} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Config_File_Switches}: list: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to specify to the |
| compiler of the language a configuration file. |
| |
| @item |
| @strong{Config_Body_File_Name}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the template to be used to indicate a |
| configuration specific to a body of the language in a configuration |
| file. |
| |
| @item |
| @strong{Config_Body_File_Name_Index}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the template to be used to indicate a |
| configuration specific to the body a unit in a multi unit source of the |
| language in a configuration file. |
| |
| @item |
| @strong{Config_Body_File_Name_Pattern}: single, indexed, |
| case-insensitive index |
| |
| Index is a language name. Value is the template to be used to indicate a |
| configuration for all bodies of the languages in a configuration file. |
| |
| @item |
| @strong{Config_Spec_File_Name}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the template to be used to indicate a |
| configuration specific to a spec of the language in a configuration |
| file. |
| |
| @item |
| @strong{Config_Spec_File_Name_Index}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the template to be used to indicate a |
| configuration specific to the spec a unit in a multi unit source of the |
| language in a configuration file. |
| |
| @item |
| @strong{Config_Spec_File_Name_Pattern}: single, indexed, |
| case-insensitive index |
| |
| Index is a language name. Value is the template to be used to indicate a |
| configuration for all specs of the languages in a configuration file. |
| |
| @item |
| @strong{Config_File_Unique}: single, indexed, case-insensitive index |
| |
| Index is a language name. Indicates if there should be only one configuration |
| file specified to the compiler of the language. Only authorized |
| case-insensitive values are "true" and "false" (the default). |
| @end itemize |
| |
| @item |
| @strong{Configuration - Dependencies} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Dependency_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to be used to specify |
| to the compiler the dependency file when the dependency kind of the language is |
| file based, and when Dependency_Driver is not specified for the language. |
| |
| @item |
| @strong{Dependency_Driver}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the name of the executable to be used to |
| create the dependency file for a source of the language, followed by the |
| required switches. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Search Paths} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Include_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to specify to the |
| compiler of the language to indicate a directory to look for sources. |
| |
| @item |
| @strong{Include_Path}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the name of an environment variable that |
| contains the path of all the directories that the compiler of the language |
| may search for sources. |
| |
| @item |
| @strong{Include_Path_File}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the name of an environment variable the |
| value of which is the path name of a text file that contains the directories |
| that the compiler of the language may search for sources. |
| |
| @item |
| @strong{Object_Path_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is the list of switches to specify to the |
| compiler of the language the name of a text file that contains the list of |
| object directories. When this attribute is not declared, the text file is |
| not created. |
| @end itemize |
| @end itemize |
| |
| @node Package Cross_Reference Attributes,Package Finder Attributes,Package Compiler Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager id54}@anchor{1b1}@anchor{gnat_ugn/gnat_project_manager package-cross-reference-attributes}@anchor{1b2} |
| @subsubsection Package Cross_Reference Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Default_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of switches to be used when invoking |
| @cite{gnatxref} for a source of the language, if there is no applicable |
| attribute Switches. |
| |
| @item |
| @strong{Switches}: list, optional index, indexed, case-insensitive index, |
| others allowed |
| |
| Index is a source file name. Value is the list of switches to be used when |
| invoking @cite{gnatxref} for the source. |
| @end itemize |
| |
| |
| @node Package Finder Attributes,Package gnatls Attributes,Package Cross_Reference Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager id56}@anchor{1b3}@anchor{gnat_ugn/gnat_project_manager package-finder-attributes}@anchor{1b4} |
| @subsubsection Package Finder Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Default_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of switches to be used when invoking |
| @cite{gnatfind} for a source of the language, if there is no applicable |
| attribute Switches. |
| |
| @item |
| @strong{Switches}: list, optional index, indexed, case-insensitive index, |
| others allowed |
| |
| Index is a source file name. Value is the list of switches to be used when |
| invoking @cite{gnatfind} for the source. |
| @end itemize |
| |
| @node Package gnatls Attributes,Package IDE Attributes,Package Finder Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager package-gnatls-attributes}@anchor{1b5}@anchor{gnat_ugn/gnat_project_manager id57}@anchor{1b6} |
| @subsubsection Package gnatls Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Switches}: list |
| |
| Value is a list of switches to be used when invoking @cite{gnatls}. |
| @end itemize |
| |
| |
| @node Package IDE Attributes,Package Install Attributes,Package gnatls Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager id58}@anchor{1b7}@anchor{gnat_ugn/gnat_project_manager package-ide-attributes}@anchor{1b8} |
| @subsubsection Package IDE Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Default_Switches}: list, indexed |
| |
| Index is the name of an external tool that the GNAT Programming System (GPS) |
| is supporting. Value is a list of switches to use when invoking that tool. |
| |
| @item |
| @strong{Remote_Host}: single |
| |
| Value is a string that designates the remote host in a cross-compilation |
| environment, to be used for remote compilation and debugging. This attribute |
| should not be specified when running on the local machine. |
| |
| @item |
| @strong{Program_Host}: single |
| |
| Value is a string that specifies the name of IP address of the embedded target |
| in a cross-compilation environment, on which the program should execute. |
| |
| @item |
| @strong{Communication_Protocol}: single |
| |
| Value is the name of the protocol to use to communicate with the target |
| in a cross-compilation environment, for example @cite{"wtx"} or |
| @cite{"vxworks"}. |
| |
| @item |
| @strong{Compiler_Command}: single, indexed, case-insensitive index |
| |
| Index is a language Name. Value is a string that denotes the command to be |
| used to invoke the compiler. For historical reasons, the value of |
| @cite{Compiler_Command ("Ada")} is expected to be a reference to @emph{gnatmake} or |
| @emph{cross-gnatmake}. |
| |
| @item |
| @strong{Debugger_Command}: single |
| |
| Value is a string that specifies the name of the debugger to be used, such as |
| gdb, powerpc-wrs-vxworks-gdb or gdb-4. |
| |
| @item |
| @strong{gnatlist}: single |
| |
| Value is a string that specifies the name of the @emph{gnatls} utility |
| to be used to retrieve information about the predefined path; for example, |
| @cite{"gnatls"}, @cite{"powerpc-wrs-vxworks-gnatls"}. |
| |
| @item |
| @strong{VCS_Kind}: single |
| |
| Value is a string used to specify the Version Control System (VCS) to be used |
| for this project, for example "Subversion", "ClearCase". If the |
| value is set to "Auto", the IDE will try to detect the actual VCS used |
| on the list of supported ones. |
| |
| @item |
| @strong{VCS_File_Check}: single |
| |
| Value is a string that specifies the command used by the VCS to check |
| the validity of a file, either when the user explicitly asks for a check, |
| or as a sanity check before doing the check-in. |
| |
| @item |
| @strong{VCS_Log_Check}: single |
| |
| Value is a string that specifies the command used by the VCS to check |
| the validity of a log file. |
| |
| @item |
| @strong{Documentation_Dir}: single |
| |
| Value is the directory used to generate the documentation of source code. |
| @end itemize |
| |
| @node Package Install Attributes,Package Linker Attributes,Package IDE Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager package-install-attributes}@anchor{1b9}@anchor{gnat_ugn/gnat_project_manager id59}@anchor{1ba} |
| @subsubsection Package Install Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Artifacts}: list, indexed |
| |
| An array attribute to declare a set of files not part of the sources |
| to be installed. The array discriminant is the directory where the |
| file is to be installed. If a relative directory then Prefix (see |
| below) is prepended. Note also that if the same file name occurs |
| multiple time in the attribute list, the last one will be the one |
| installed. |
| |
| @item |
| @strong{Prefix}: single |
| |
| Value is the install destination directory. |
| |
| @item |
| @strong{Sources_Subdir}: single |
| |
| Value is the sources directory or subdirectory of Prefix. |
| |
| @item |
| @strong{Exec_Subdir}: single |
| |
| Value is the executables directory or subdirectory of Prefix. |
| |
| @item |
| @strong{Lib_Subdir}: single |
| |
| Value is library directory or subdirectory of Prefix. |
| |
| @item |
| @strong{Project_Subdir}: single |
| |
| Value is the project directory or subdirectory of Prefix. |
| |
| @item |
| @strong{Active}: single |
| |
| Indicates that the project is to be installed or not. Case-insensitive value |
| "false" means that the project is not to be installed, all other values mean |
| that the project is to be installed. |
| |
| @item |
| @strong{Mode}: single |
| |
| Value is the installation mode, it is either @strong{dev} (default) or @strong{usage}. |
| |
| @item |
| @strong{Install_Name}: single |
| |
| Specify the name to use for recording the installation. The default is |
| the project name without the extension. |
| @end itemize |
| |
| @node Package Linker Attributes,Package Naming Attributes,Package Install Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager id60}@anchor{1bb}@anchor{gnat_ugn/gnat_project_manager package-linker-attributes}@anchor{1bc} |
| @subsubsection Package Linker Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{General} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Required_Switches}: list |
| |
| Value is a list of switches that are required when invoking the linker to link |
| an executable. |
| |
| @item |
| @strong{Default_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of switches for the linker when |
| linking an executable for a main source of the language, when there is no |
| applicable Switches. |
| |
| @item |
| @strong{Leading_Switches}: list, optional index, indexed, |
| case-insensitive index, others allowed |
| |
| Index is a source file name or a language name. Value is the list of switches |
| to be used at the beginning of the command line when invoking the linker to |
| build an executable for the source or for its language. |
| |
| @item |
| @strong{Switches}: list, optional index, indexed, case-insensitive index, |
| others allowed |
| |
| Index is a source file name or a language name. Value is the list of switches |
| to be used when invoking the linker to build an executable for the source or |
| for its language. |
| |
| @item |
| @strong{Trailing_Switches}: list, optional index, indexed, |
| case-insensitive index, others allowed |
| |
| Index is a source file name or a language name. Value is the list of switches |
| to be used at the end of the command line when invoking the linker to |
| build an executable for the source or for its language. These switches may |
| override the Required_Switches. |
| |
| @item |
| @strong{Linker_Options}: list |
| |
| Value is a list of switches/options that are to be added when linking an |
| executable from a project importing the current project directly or indirectly. |
| Linker_Options are not used when linking an executable from the current |
| project. |
| |
| @item |
| @strong{Map_File_Option}: single |
| |
| Value is the switch to specify the map file name that the linker needs to |
| create. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Linking} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Driver}: single |
| |
| Value is the name of the linker executable. |
| @end itemize |
| |
| @item |
| @strong{Configuration - Response Files} |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Max_Command_Line_Length}: single |
| |
| Value is the maximum number of character in the command line when invoking |
| the linker to link an executable. |
| |
| @item |
| @strong{Response_File_Format}: single |
| |
| Indicates the kind of response file to create when the length of the linking |
| command line is too large. Only authorized case-insensitive values are "none", |
| "gnu", "object_list", "gcc_gnu", "gcc_option_list" and "gcc_object_list". |
| |
| @item |
| @strong{Response_File_Switches}: list |
| |
| Value is the list of switches to specify a response file to the linker. |
| @end itemize |
| @end itemize |
| |
| @c only PRO or GPL |
| @c |
| @c .. _Package_Metrics_Attribute: |
| @c |
| @c Package Metrics Attribute |
| @c ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| @c |
| @c * **Default_Switches**: list, indexed, case-insensitive index |
| @c |
| @c Index is a language name. Value is a list of switches to be used when invoking |
| @c `gnatmetric` for a source of the language, if there is no applicable |
| @c attribute Switches. |
| @c |
| @c * **Switches**: list, optional index, indexed, case-insensitive index, |
| @c others allowed |
| @c |
| @c Index is a source file name. Value is the list of switches to be used when |
| @c invoking `gnatmetric` for the source. |
| |
| @node Package Naming Attributes,Package Remote Attributes,Package Linker Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager package-naming-attributes}@anchor{1bd}@anchor{gnat_ugn/gnat_project_manager id61}@anchor{1be} |
| @subsubsection Package Naming Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Specification_Suffix}: single, indexed, case-insensitive index |
| |
| Equivalent to attribute Spec_Suffix. |
| |
| @item |
| @strong{Spec_Suffix}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the extension of file names for specs of |
| the language. |
| |
| @item |
| @strong{Implementation_Suffix}: single, indexed, case-insensitive index |
| |
| Equivalent to attribute Body_Suffix. |
| |
| @item |
| @strong{Body_Suffix}: single, indexed, case-insensitive index |
| |
| Index is a language name. Value is the extension of file names for bodies of |
| the language. |
| |
| @item |
| @strong{Separate_Suffix}: single |
| |
| Value is the extension of file names for subunits of Ada. |
| |
| @item |
| @strong{Casing}: single |
| |
| Indicates the casing of sources of the Ada language. Only authorized |
| case-insensitive values are "lowercase", "uppercase" and "mixedcase". |
| |
| @item |
| @strong{Dot_Replacement}: single |
| |
| Value is the string that replace the dot of unit names in the source file names |
| of the Ada language. |
| |
| @item |
| @strong{Specification}: single, optional index, indexed, |
| case-insensitive index |
| |
| Equivalent to attribute Spec. |
| |
| @item |
| @strong{Spec}: single, optional index, indexed, case-insensitive index |
| |
| Index is a unit name. Value is the file name of the spec of the unit. |
| |
| @item |
| @strong{Implementation}: single, optional index, indexed, |
| case-insensitive index |
| |
| Equivalent to attribute Body. |
| |
| @item |
| @strong{Body}: single, optional index, indexed, case-insensitive index |
| |
| Index is a unit name. Value is the file name of the body of the unit. |
| |
| @item |
| @strong{Specification_Exceptions}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of specs for the language that do not |
| necessarily follow the naming scheme for the language and that may or may not |
| be found in the source directories of the project. |
| |
| @item |
| @strong{Implementation_Exceptions}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of bodies for the language that do not |
| necessarily follow the naming scheme for the language and that may or may not |
| be found in the source directories of the project. |
| @end itemize |
| |
| |
| @node Package Remote Attributes,Package Stack Attributes,Package Naming Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager package-remote-attributes}@anchor{1bf}@anchor{gnat_ugn/gnat_project_manager id63}@anchor{1c0} |
| @subsubsection Package Remote Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Included_Patterns}: list |
| |
| If this attribute is defined it sets the patterns to |
| synchronized from the master to the slaves. It is exclusive |
| with Excluded_Patterns, that is it is an error to define |
| both. |
| |
| @item |
| @strong{Included_Artifact_Patterns}: list |
| |
| If this attribute is defined it sets the patterns of compilation |
| artifacts to synchronized from the slaves to the build master. |
| This attribute replace the default hard-coded patterns. |
| |
| @item |
| @strong{Excluded_Patterns}: list |
| |
| Set of patterns to ignore when synchronizing sources from the build |
| master to the slaves. A set of predefined patterns are supported |
| (e.g. *.o, *.ali, *.exe, etc.), this attributes make it possible to |
| add some more patterns. |
| |
| @item |
| @strong{Root_Dir}: single |
| |
| Value is the root directory used by the slave machines. |
| @end itemize |
| |
| @node Package Stack Attributes,Package Synchronize Attributes,Package Remote Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager id64}@anchor{1c1}@anchor{gnat_ugn/gnat_project_manager package-stack-attributes}@anchor{1c2} |
| @subsubsection Package Stack Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Switches}: list |
| |
| Value is the list of switches to be used when invoking @cite{gnatstack}. |
| @end itemize |
| |
| @node Package Synchronize Attributes,,Package Stack Attributes,Attributes |
| @anchor{gnat_ugn/gnat_project_manager package-synchronize-attributes}@anchor{1c3} |
| @subsubsection Package Synchronize Attributes |
| |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Default_Switches}: list, indexed, case-insensitive index |
| |
| Index is a language name. Value is a list of switches to be used when invoking |
| @cite{gnatsync} for a source of the language, if there is no applicable |
| attribute Switches. |
| |
| @item |
| @strong{Switches}: list, optional index, indexed, case-insensitive index, |
| others allowed |
| |
| Index is a source file name. Value is the list of switches to be used when |
| invoking @cite{gnatsync} for the source. |
| @end itemize |
| |
| @node Tools Supporting Project Files,GNAT Utility Programs,GNAT Project Manager,Top |
| @anchor{gnat_ugn/tools_supporting_project_files doc}@anchor{1c4}@anchor{gnat_ugn/tools_supporting_project_files tools-supporting-project-files}@anchor{c}@anchor{gnat_ugn/tools_supporting_project_files id1}@anchor{1c5} |
| @chapter Tools Supporting Project Files |
| |
| |
| This section describes how project files can be used in conjunction with a number of |
| GNAT tools. |
| |
| @menu |
| * gnatmake and Project Files:: |
| * The GNAT Driver and Project Files:: |
| |
| @end menu |
| |
| @node gnatmake and Project Files,The GNAT Driver and Project Files,,Tools Supporting Project Files |
| @anchor{gnat_ugn/tools_supporting_project_files id2}@anchor{1c6}@anchor{gnat_ugn/tools_supporting_project_files gnatmake-and-project-files}@anchor{e4} |
| @section gnatmake and Project Files |
| |
| |
| This section covers several topics related to @emph{gnatmake} and |
| project files: defining switches for @emph{gnatmake} |
| and for the tools that it invokes; specifying configuration pragmas; |
| the use of the @cite{Main} attribute; building and rebuilding library project |
| files. |
| |
| @menu |
| * Switches Related to Project Files:: |
| * Switches and Project Files:: |
| * Specifying Configuration Pragmas:: |
| * Project Files and Main Subprograms:: |
| * Library Project Files:: |
| |
| @end menu |
| |
| @node Switches Related to Project Files,Switches and Project Files,,gnatmake and Project Files |
| @anchor{gnat_ugn/tools_supporting_project_files switches-related-to-project-files}@anchor{e6}@anchor{gnat_ugn/tools_supporting_project_files id3}@anchor{1c7} |
| @subsection Switches Related to Project Files |
| |
| |
| The following switches are used by GNAT tools that support project files: |
| |
| @quotation |
| |
| @geindex -P (any project-aware tool) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @code{-P@emph{project}} |
| |
| Indicates the name of a project file. This project file will be parsed with |
| the verbosity indicated by @emph{-vP*x*}, |
| if any, and using the external references indicated |
| by @emph{-X} switches, if any. |
| There may zero, one or more spaces between @emph{-P} and @cite{project}. |
| |
| There must be only one @emph{-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 |
| @emph{-P}, |
| @emph{-vP*x*} |
| or @emph{-X} is not significant. |
| |
| @geindex -X (any project-aware tool) |
| |
| @item @code{-X@emph{name}=@emph{value}} |
| |
| Indicates that external variable @cite{name} has the value @cite{value}. |
| The Project Manager will use this value for occurrences of |
| @cite{external(name)} when parsing the project file. |
| |
| If @cite{name} or @cite{value} includes a space, then @cite{name=value} should be |
| put between quotes. |
| |
| @example |
| -XOS=NT |
| -X"user=John Doe" |
| @end example |
| |
| Several @emph{-X} switches can be used simultaneously. |
| If several @emph{-X} switches specify the same |
| @cite{name}, only the last one is used. |
| |
| An external variable specified with a @emph{-X} switch |
| takes precedence over the value of the same name in the environment. |
| |
| @geindex -vP (any project-aware tool) |
| |
| @item @code{-vP@emph{x}} |
| |
| Indicates the verbosity of the parsing of GNAT project files. |
| |
| @emph{-vP0} means Default; |
| @emph{-vP1} means Medium; |
| @emph{-vP2} means High. |
| |
| The default is Default: no output for syntactically correct |
| project files. |
| If several @emph{-vP*x*} switches are present, |
| only the last one is used. |
| |
| @geindex -aP (any project-aware tool) |
| |
| @item @code{-aP@emph{dir}} |
| |
| Add directory @cite{dir} at the beginning of the project search path, in order, |
| after the current working directory. |
| |
| @geindex -eL (any project-aware tool) |
| |
| @item @code{-eL} |
| |
| Follow all symbolic links when processing project files. |
| |
| @geindex --subdirs= (gnatmake and gnatclean) |
| |
| @item @code{--subdirs=@emph{subdir}} |
| |
| This switch is recognized by @emph{gnatmake} and @emph{gnatclean}. It |
| indicate that the real directories (except the source directories) are the |
| subdirectories @cite{subdir} of the directories specified in the project files. |
| This applies in particular to object directories, library directories and |
| exec directories. If the subdirectories do not exist, they are created |
| automatically. |
| @end table |
| |
| @node Switches and Project Files,Specifying Configuration Pragmas,Switches Related to Project Files,gnatmake and Project Files |
| @anchor{gnat_ugn/tools_supporting_project_files id4}@anchor{1c8}@anchor{gnat_ugn/tools_supporting_project_files switches-and-project-files}@anchor{1c9} |
| @subsection Switches and Project Files |
| |
| |
| For each of the packages @cite{Builder}, @cite{Compiler}, @cite{Binder}, and |
| @cite{Linker}, you can specify a @cite{Default_Switches} |
| attribute, a @cite{Switches} attribute, or both; |
| as their names imply, these switch-related |
| attributes affect the switches that are used for each of these GNAT |
| components when |
| @emph{gnatmake} is invoked. As will be explained below, these |
| component-specific switches precede |
| the switches provided on the @emph{gnatmake} command line. |
| |
| The @cite{Default_Switches} attribute is an attribute |
| indexed by language name (case insensitive) whose value is a string list. |
| For example: |
| |
| @quotation |
| |
| @example |
| package Compiler is |
| for Default_Switches ("Ada") |
| use ("-gnaty", |
| "-v"); |
| end Compiler; |
| @end example |
| @end quotation |
| |
| The @cite{Switches} attribute is indexed on a file name (which may or may |
| not be case sensitive, depending |
| on the operating system) whose value is a string list. For example: |
| |
| @quotation |
| |
| @example |
| package Builder is |
| for Switches ("main1.adb") |
| use ("-O2"); |
| for Switches ("main2.adb") |
| use ("-g"); |
| end Builder; |
| @end example |
| @end quotation |
| |
| For the @cite{Builder} package, the file names must designate source files |
| for main subprograms. For the @cite{Binder} and @cite{Linker} packages, the |
| file names must designate @code{ALI} or source files for main subprograms. |
| In each case just the file name without an explicit extension is acceptable. |
| |
| For each tool used in a program build (@emph{gnatmake}, the compiler, the |
| binder, and the linker), the corresponding package @@dfn@{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 @cite{f} comprise: |
| |
| |
| @itemize * |
| |
| @item |
| the value of attribute @cite{Switches (`f})`, |
| if it is specified in the package for the given file, |
| |
| @item |
| otherwise, the value of @cite{Default_Switches ("Ada")}, |
| if it is specified in the package. |
| @end itemize |
| |
| If neither of these attributes is defined in the package, then the package does |
| not contribute any switches for the given file. |
| |
| When @emph{gnatmake} is invoked on a file, the switches comprise |
| two sets, in the following order: those contributed for the file |
| by the @cite{Builder} package; |
| and the switches passed on the command line. |
| |
| When @emph{gnatmake} invokes a tool (compiler, binder, linker) on a file, |
| the switches passed to the tool comprise three sets, |
| in the following order: |
| |
| |
| @itemize * |
| |
| @item |
| the applicable switches contributed for the file |
| by the @cite{Builder} package in the project file supplied on the command line; |
| |
| @item |
| those contributed for the file by the package (in the relevant project file -- |
| see below) corresponding to the tool; and |
| |
| @item |
| the applicable switches passed on the command line. |
| @end itemize |
| |
| The term @emph{applicable switches} reflects the fact that |
| @emph{gnatmake} switches may or may not be passed to individual |
| tools, depending on the individual switch. |
| |
| @emph{gnatmake} may invoke the compiler on source files from different |
| projects. The Project Manager will use the appropriate project file to |
| determine the @cite{Compiler} package for each source file being compiled. |
| Likewise for the @cite{Binder} and @cite{Linker} packages. |
| |
| As an example, consider the following package in a project file: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| If @emph{gnatmake} is invoked with this project file, and it needs to |
| compile, say, the files @code{a.adb}, @code{b.adb}, and @code{c.adb}, then |
| @code{a.adb} will be compiled with the switch @emph{-O1}, |
| @code{b.adb} with switches @emph{-O2} and @emph{-gnaty}, |
| and @code{c.adb} with @emph{-g}. |
| |
| The following example illustrates the ordering of the switches |
| contributed by different packages: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| If you issue the command: |
| |
| @quotation |
| |
| @example |
| $ gnatmake -Pproj2 -O0 main |
| @end example |
| @end quotation |
| |
| then the compiler will be invoked on @code{main.adb} with the following |
| sequence of switches |
| |
| @quotation |
| |
| @example |
| -g -O1 -O2 -O0 |
| @end example |
| @end quotation |
| |
| with the last @emph{-O} |
| switch having precedence over the earlier ones; |
| several other switches |
| (such as @emph{-c}) are added implicitly. |
| |
| The switches @emph{-g} |
| and @emph{-O1} are contributed by package |
| @cite{Builder}, @emph{-O2} is contributed |
| by the package @cite{Compiler} |
| and @emph{-O0} comes from the command line. |
| |
| The @emph{-g} switch will also be passed in the invocation of |
| @emph{Gnatlink.} |
| |
| A final example illustrates switch contributions from packages in different |
| project files: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| |
| @example |
| -- Ada source file: |
| with Pack; |
| procedure Foo_Main is |
| ... |
| end Foo_Main; |
| @end example |
| @end quotation |
| |
| If the command is |
| |
| @quotation |
| |
| @example |
| $ gnatmake -PProj4 foo_main.adb -cargs -gnato |
| @end example |
| @end quotation |
| |
| then the switches passed to the compiler for @code{foo_main.adb} are |
| @emph{-g} (contributed by the package @cite{Proj4.Builder}) and |
| @emph{-gnato} (passed on the command line). |
| When the imported package @cite{Pack} is compiled, the switches used |
| are @emph{-g} from @cite{Proj4.Builder}, |
| @emph{-gnata} (contributed from package @cite{Proj3.Compiler}, |
| and @emph{-gnato} from the command line. |
| |
| When using @emph{gnatmake} with project files, some switches or |
| arguments may be expressed as relative paths. As the working directory where |
| compilation occurs may change, these relative paths are converted to absolute |
| paths. For the switches found in a project file, the relative paths |
| are relative to the project file directory, for the switches on the command |
| line, they are relative to the directory where @emph{gnatmake} is invoked. |
| The switches for which this occurs are: |
| -I, |
| -A, |
| -L, |
| -aO, |
| -aL, |
| -aI, as well as all arguments that are not switches (arguments to |
| switch |
| -o, object files specified in package @cite{Linker} or after |
| -largs on the command line). The exception to this rule is the switch |
| --RTS= for which a relative path argument is never converted. |
| |
| @node Specifying Configuration Pragmas,Project Files and Main Subprograms,Switches and Project Files,gnatmake and Project Files |
| @anchor{gnat_ugn/tools_supporting_project_files id5}@anchor{1ca}@anchor{gnat_ugn/tools_supporting_project_files specifying-configuration-pragmas}@anchor{7d} |
| @subsection Specifying Configuration Pragmas |
| |
| |
| When using @emph{gnatmake} with project files, if there exists a file |
| @code{gnat.adc} that contains configuration pragmas, this file will be |
| ignored. |
| |
| Configuration pragmas can be defined by means of the following attributes in |
| project files: @cite{Global_Configuration_Pragmas} in package @cite{Builder} |
| and @cite{Local_Configuration_Pragmas} in package @cite{Compiler}. |
| |
| Both these attributes are single string attributes. Their values is the path |
| name of a file containing configuration pragmas. If a path name is relative, |
| then it is relative to the project directory of the project file where the |
| attribute is defined. |
| |
| When compiling a source, the configuration pragmas used are, in order, |
| those listed in the file designated by attribute |
| @cite{Global_Configuration_Pragmas} in package @cite{Builder} of the main |
| project file, if it is specified, and those listed in the file designated by |
| attribute @cite{Local_Configuration_Pragmas} in package @cite{Compiler} of |
| the project file of the source, if it exists. |
| |
| @node Project Files and Main Subprograms,Library Project Files,Specifying Configuration Pragmas,gnatmake and Project Files |
| @anchor{gnat_ugn/tools_supporting_project_files id6}@anchor{1cb}@anchor{gnat_ugn/tools_supporting_project_files project-files-and-main-subprograms}@anchor{e5} |
| @subsection Project Files and Main Subprograms |
| |
| |
| When using a project file, you can invoke @emph{gnatmake} |
| with one or several main subprograms, by specifying their source files on the |
| command line. |
| |
| @quotation |
| |
| @example |
| $ gnatmake -Pprj main1.adb main2.adb main3.adb |
| @end example |
| @end quotation |
| |
| Each of these needs to be a source file of the same project, except |
| when the switch @cite{-u} is used. |
| |
| When @cite{-u} is not used, all the mains need to be sources of the |
| same project, one of the project in the tree rooted at the project specified |
| on the command line. The package @cite{Builder} of this common project, the |
| "main project" is the one that is considered by @emph{gnatmake}. |
| |
| When @cite{-u} is used, the specified source files may be in projects |
| imported directly or indirectly by the project specified on the command line. |
| Note that if such a source file is not part of the project specified on the |
| command line, the switches found in package @cite{Builder} of the |
| project specified on the command line, if any, that are transmitted |
| to the compiler will still be used, not those found in the project file of |
| the source file. |
| |
| When using a project file, you can also invoke @emph{gnatmake} without |
| explicitly specifying any main, and the effect depends on whether you have |
| defined the @cite{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) that contains a unit that can be a main subprogram. |
| |
| If the @cite{Main} attribute is defined in a project file as a non-empty |
| string list and the switch @emph{-u} is not used on the command |
| line, then invoking @emph{gnatmake} with this project file but without any |
| main on the command line is equivalent to invoking @emph{gnatmake} with all |
| the file names in the @cite{Main} attribute on the command line. |
| |
| Example: |
| |
| @quotation |
| |
| @example |
| project Prj is |
| for Main use ("main1.adb", "main2.adb", "main3.adb"); |
| end Prj; |
| @end example |
| @end quotation |
| |
| With this project file, @cite{"gnatmake -Pprj"} |
| is equivalent to |
| @cite{"gnatmake -Pprj main1.adb main2.adb main3.adb"}. |
| |
| When the project attribute @cite{Main} is not specified, or is specified |
| as an empty string list, or when the switch @emph{-u} is used on the command |
| line, then invoking @emph{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 @emph{-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 @emph{-u} switch is applied to all of the immediate sources of the |
| main project file. |
| |
| When no main is specified on the command line and attribute @cite{Main} exists |
| and includes several mains, or when several mains are specified on the |
| command line, the default switches in package @cite{Builder} will |
| be used for all mains, even if there are specific switches |
| specified for one or several mains. |
| |
| But the switches from package @cite{Binder} or @cite{Linker} will be |
| the specific switches for each main, if they are specified. |
| |
| @node Library Project Files,,Project Files and Main Subprograms,gnatmake and Project Files |
| @anchor{gnat_ugn/tools_supporting_project_files id7}@anchor{1cc}@anchor{gnat_ugn/tools_supporting_project_files library-project-files}@anchor{1cd} |
| @subsection Library Project Files |
| |
| |
| When @emph{gnatmake} is invoked with a main project file that is a library |
| project file, it is not allowed to specify one or more mains on the command |
| line. |
| |
| When a library project file is specified, switches @cite{-b} and |
| @cite{-l} have special meanings. |
| |
| |
| @itemize * |
| |
| @item |
| @cite{-b} is only allowed for stand-alone libraries. It indicates |
| to @emph{gnatmake} that @emph{gnatbind} should be invoked for the |
| library. |
| |
| @item |
| @cite{-l} may be used for all library projects. It indicates |
| to @emph{gnatmake} that the binder generated file should be compiled |
| (in the case of a stand-alone library) and that the library should be built. |
| @end itemize |
| |
| @node The GNAT Driver and Project Files,,gnatmake and Project Files,Tools Supporting Project Files |
| @anchor{gnat_ugn/tools_supporting_project_files id8}@anchor{1ce}@anchor{gnat_ugn/tools_supporting_project_files the-gnat-driver-and-project-files}@anchor{122} |
| @section The GNAT Driver and Project Files |
| |
| |
| A number of GNAT tools beyond @emph{gnatmake} |
| can benefit from project files: |
| |
| |
| |
| @itemize * |
| |
| @item |
| @emph{gnatbind} |
| |
| @item |
| @emph{gnatclean} |
| |
| @item |
| @emph{gnatfind} |
| |
| @item |
| @emph{gnatlink} |
| |
| @item |
| @emph{gnatls} |
| |
| @item |
| @emph{gnatxref} |
| @end itemize |
| |
| However, none of these tools can be invoked |
| directly with a project file switch (@emph{-P}). |
| They must be invoked through the @emph{gnat} driver. |
| |
| The @emph{gnat} driver is a wrapper that accepts a number of commands and |
| calls the corresponding tool. It was designed initially for VMS platforms (to |
| convert VMS qualifiers to Unix-style switches), but it is now available on all |
| GNAT platforms. |
| |
| On non-VMS platforms, the @emph{gnat} driver accepts the following commands |
| (case insensitive): |
| |
| |
| |
| @itemize * |
| |
| @item |
| BIND to invoke @emph{gnatbind} |
| |
| @item |
| CHOP to invoke @emph{gnatchop} |
| |
| @item |
| CLEAN to invoke @emph{gnatclean} |
| |
| @item |
| COMP or COMPILE to invoke the compiler |
| |
| @item |
| FIND to invoke @emph{gnatfind} |
| |
| @item |
| KR or KRUNCH to invoke @emph{gnatkr} |
| |
| @item |
| LINK to invoke @emph{gnatlink} |
| |
| @item |
| LS or LIST to invoke @emph{gnatls} |
| |
| @item |
| MAKE to invoke @emph{gnatmake} |
| |
| @item |
| NAME to invoke @emph{gnatname} |
| |
| @item |
| PREP or PREPROCESS to invoke @emph{gnatprep} |
| |
| @item |
| XREF to invoke @emph{gnatxref} |
| @end itemize |
| |
| Note that the command |
| @emph{gnatmake -c -f -u} is used to invoke the compiler. |
| |
| On non-VMS platforms, between @emph{gnat} and the command, two |
| special switches may be used: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{-v} to display the invocation of the tool. |
| |
| @item |
| @emph{-dn} to prevent the @emph{gnat} driver from removing |
| the temporary files it has created. These temporary files are |
| configuration files and temporary file list files. |
| @end itemize |
| |
| The command may be followed by switches and arguments for the invoked |
| tool. |
| |
| @quotation |
| |
| @example |
| $ gnat bind -C main.ali |
| $ gnat ls -a main |
| $ gnat chop foo.txt |
| @end example |
| @end quotation |
| |
| Switches may also be put in text files, one switch per line, and the text |
| files may be specified with their path name preceded by '@@'. |
| |
| @quotation |
| |
| @example |
| $ gnat bind @@args.txt main.ali |
| @end example |
| @end quotation |
| |
| In addition, for the following commands the project file related switches |
| (@emph{-P}, @emph{-X} and @emph{-vPx}) may be used in addition to |
| the switches of the invoking tool: |
| |
| |
| |
| @itemize * |
| |
| @item |
| BIND |
| |
| @item |
| COMP or COMPILE |
| |
| @item |
| FIND |
| |
| @item |
| LS or LIST |
| |
| @item |
| LINK |
| |
| @item |
| XREF |
| @end itemize |
| |
| |
| For each of the following commands, there is optionally a corresponding |
| package in the main project. |
| |
| |
| |
| @itemize * |
| |
| @item |
| package @cite{Binder} for command BIND (invoking @cite{gnatbind}) |
| |
| @item |
| package @cite{Compiler} for command COMP or COMPILE (invoking the compiler) |
| |
| @item |
| package @cite{Cross_Reference} for command XREF (invoking @cite{gnatxref}) |
| |
| @item |
| package @cite{Finder} for command FIND (invoking @cite{gnatfind}) |
| |
| @item |
| package @cite{Gnatls} for command LS or LIST (invoking @cite{gnatls}) |
| |
| @item |
| package @cite{Linker} for command LINK (invoking @cite{gnatlink}) |
| @end itemize |
| |
| Package @cite{Gnatls} has a unique attribute @cite{Switches}, |
| a simple variable with a string list value. It contains switches |
| for the invocation of @cite{gnatls}. |
| |
| @quotation |
| |
| @example |
| project Proj1 is |
| package gnatls is |
| for Switches |
| use ("-a", |
| "-v"); |
| end gnatls; |
| end Proj1; |
| @end example |
| @end quotation |
| |
| All other packages have two attribute @cite{Switches} and |
| @cite{Default_Switches}. |
| |
| @cite{Switches} is an indexed attribute, indexed by the |
| source file name, that has a string list value: the switches to be |
| used when the tool corresponding to the package is invoked for the specific |
| source file. |
| |
| @cite{Default_Switches} is an attribute, |
| indexed by the programming language that has a string list value. |
| @cite{Default_Switches ("Ada")} contains the |
| switches for the invocation of the tool corresponding |
| to the package, except if a specific @cite{Switches} attribute |
| is specified for the source file. |
| |
| @quotation |
| |
| @example |
| project Proj is |
| |
| for Source_Dirs use (""); |
| |
| package gnatls is |
| for Switches use |
| ("-a", |
| "-v"); |
| end gnatls; |
| |
| package Compiler is |
| for Default_Switches ("Ada") |
| use ("-gnatv", |
| "-gnatwa"); |
| end Binder; |
| |
| package Binder is |
| for Default_Switches ("Ada") |
| use ("-C", |
| "-e"); |
| end Binder; |
| |
| package Linker is |
| for Default_Switches ("Ada") |
| use ("-C"); |
| for Switches ("main.adb") |
| use ("-C", |
| "-v", |
| "-v"); |
| 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; |
| @end example |
| @end quotation |
| |
| With the above project file, commands such as |
| |
| @quotation |
| |
| @example |
| $ gnat comp -Pproj main |
| $ gnat ls -Pproj main |
| $ gnat xref -Pproj main |
| $ gnat bind -Pproj main.ali |
| $ gnat link -Pproj main.ali |
| @end example |
| @end quotation |
| |
| will set up the environment properly and invoke the tool with the switches |
| found in the package corresponding to the tool: |
| @cite{Default_Switches ("Ada")} for all tools, |
| except @cite{Switches ("main.adb")} |
| for @cite{gnatlink}. |
| |
| |
| @node GNAT Utility Programs,GNAT and Program Execution,Tools Supporting Project Files,Top |
| @anchor{gnat_ugn/gnat_utility_programs doc}@anchor{1cf}@anchor{gnat_ugn/gnat_utility_programs gnat-utility-programs}@anchor{d}@anchor{gnat_ugn/gnat_utility_programs id1}@anchor{1d0} |
| @chapter GNAT Utility Programs |
| |
| |
| This chapter describes a number of utility programs: |
| |
| |
| |
| @itemize * |
| |
| @item |
| @ref{22,,The File Cleanup Utility gnatclean} |
| |
| @item |
| @ref{23,,The GNAT Library Browser gnatls} |
| |
| @item |
| @ref{24,,The Cross-Referencing Tools gnatxref and gnatfind} |
| |
| @item |
| @ref{25,,The Ada to HTML Converter gnathtml} |
| @end itemize |
| |
| Other GNAT utilities are described elsewhere in this manual: |
| |
| |
| @itemize * |
| |
| @item |
| @ref{5b,,Handling Arbitrary File Naming Conventions with gnatname} |
| |
| @item |
| @ref{65,,File Name Krunching with gnatkr} |
| |
| @item |
| @ref{38,,Renaming Files with gnatchop} |
| |
| @item |
| @ref{19,,Preprocessing with gnatprep} |
| @end itemize |
| |
| @menu |
| * The File Cleanup Utility gnatclean:: |
| * The GNAT Library Browser gnatls:: |
| * The Cross-Referencing Tools gnatxref and gnatfind:: |
| * The Ada to HTML Converter gnathtml:: |
| |
| @end menu |
| |
| @node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs |
| @anchor{gnat_ugn/gnat_utility_programs id2}@anchor{1d1}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{22} |
| @section The File Cleanup Utility @emph{gnatclean} |
| |
| |
| @geindex File cleanup tool |
| |
| @geindex gnatclean |
| |
| @cite{gnatclean} is a tool that allows the deletion of files produced by the |
| compiler, binder and linker, including ALI files, object files, tree files, |
| expanded source files, library files, interface copy source files, binder |
| generated files and executable files. |
| |
| @menu |
| * Running gnatclean:: |
| * Switches for gnatclean:: |
| |
| @end menu |
| |
| @node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean |
| @anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{1d2}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{1d3} |
| @subsection Running @cite{gnatclean} |
| |
| |
| The @cite{gnatclean} command has the form: |
| |
| @quotation |
| |
| @example |
| $ gnatclean switches `names` |
| @end example |
| @end quotation |
| |
| where @cite{names} is a list of source file names. Suffixes @code{.ads} and |
| @code{adb} may be omitted. If a project file is specified using switch |
| @code{-P}, then @cite{names} may be completely omitted. |
| |
| In normal mode, @cite{gnatclean} delete the files produced by the compiler and, |
| if switch @cite{-c} is not specified, by the binder and |
| the linker. In informative-only mode, specified by switch |
| @cite{-n}, the list of files that would have been deleted in |
| normal mode is listed, but no file is actually deleted. |
| |
| @node Switches for gnatclean,,Running gnatclean,The File Cleanup Utility gnatclean |
| @anchor{gnat_ugn/gnat_utility_programs id4}@anchor{1d4}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{1d5} |
| @subsection Switches for @cite{gnatclean} |
| |
| |
| @cite{gnatclean} recognizes the following switches: |
| |
| @geindex --version (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{--version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{--help} |
| |
| If @emph{--version} was not used, display usage, then exit disregarding |
| all other options. |
| |
| @item @code{--subdirs=@emph{subdir}} |
| |
| Actual object directory of each project file is the subdirectory subdir of the |
| object directory specified or defaulted in the project file. |
| |
| @item @code{--unchecked-shared-lib-imports} |
| |
| By default, shared library projects are not allowed to import static library |
| projects. When this switch is used on the command line, this restriction is |
| relaxed. |
| @end table |
| |
| @geindex -c (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-c} |
| |
| Only attempt to delete the files produced by the compiler, not those produced |
| by the binder or the linker. The files that are not to be deleted are library |
| files, interface copy files, binder generated files and executable files. |
| @end table |
| |
| @geindex -D (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-D @emph{dir}} |
| |
| Indicate that ALI and object files should normally be found in directory @cite{dir}. |
| @end table |
| |
| @geindex -F (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-F} |
| |
| When using project files, if some errors or warnings are detected during |
| parsing and verbose mode is not in effect (no use of switch |
| -v), then error lines start with the full path name of the project |
| file, rather than its simple file name. |
| @end table |
| |
| @geindex -h (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-h} |
| |
| Output a message explaining the usage of @cite{gnatclean}. |
| @end table |
| |
| @geindex -n (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-n} |
| |
| Informative-only mode. Do not delete any files. Output the list of the files |
| that would have been deleted if this switch was not specified. |
| @end table |
| |
| @geindex -P (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-P@emph{project}} |
| |
| Use project file @cite{project}. Only one such switch can be used. |
| When cleaning a project file, the files produced by the compilation of the |
| immediate sources or inherited sources of the project files are to be |
| deleted. This is not depending on the presence or not of executable names |
| on the command line. |
| @end table |
| |
| @geindex -q (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-q} |
| |
| Quiet output. If there are no errors, do not output anything, except in |
| verbose mode (switch -v) or in informative-only mode |
| (switch -n). |
| @end table |
| |
| @geindex -r (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-r} |
| |
| When a project file is specified (using switch -P), |
| clean all imported and extended project files, recursively. If this switch |
| is not specified, only the files related to the main project file are to be |
| deleted. This switch has no effect if no project file is specified. |
| @end table |
| |
| @geindex -v (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-v} |
| |
| Verbose mode. |
| @end table |
| |
| @geindex -vP (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-vP@emph{x}} |
| |
| Indicates the verbosity of the parsing of GNAT project files. |
| @ref{e6,,Switches Related to Project Files}. |
| @end table |
| |
| @geindex -X (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-X@emph{name}=@emph{value}} |
| |
| Indicates that external variable @cite{name} has the value @cite{value}. |
| The Project Manager will use this value for occurrences of |
| @cite{external(name)} when parsing the project file. |
| @ref{e6,,Switches Related to Project Files}. |
| @end table |
| |
| @geindex -aO (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-aO@emph{dir}} |
| |
| When searching for ALI and object files, look in directory @cite{dir}. |
| @end table |
| |
| @geindex -I (gnatclean) |
| |
| |
| @table @asis |
| |
| @item @code{-I@emph{dir}} |
| |
| Equivalent to @code{-aO@emph{dir}}. |
| @end table |
| |
| @geindex -I- (gnatclean) |
| |
| @geindex Source files |
| @geindex suppressing search |
| |
| |
| @table @asis |
| |
| @item @code{-I-} |
| |
| Do not look for ALI or object files in the directory |
| where @cite{gnatclean} was invoked. |
| @end table |
| |
| @node The GNAT Library Browser gnatls,The Cross-Referencing Tools gnatxref and gnatfind,The File Cleanup Utility gnatclean,GNAT Utility Programs |
| @anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{23}@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{1d6} |
| @section The GNAT Library Browser @cite{gnatls} |
| |
| |
| @geindex Library browser |
| |
| @geindex gnatls |
| |
| @cite{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. |
| |
| Note: to invoke @cite{gnatls} with a project file, use the @cite{gnat} |
| driver (see @ref{122,,The GNAT Driver and Project Files}). |
| |
| @menu |
| * Running gnatls:: |
| * Switches for gnatls:: |
| * Example of gnatls Usage:: |
| |
| @end menu |
| |
| @node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls |
| @anchor{gnat_ugn/gnat_utility_programs id6}@anchor{1d7}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{1d8} |
| @subsection Running @cite{gnatls} |
| |
| |
| The @cite{gnatls} command has the form |
| |
| @quotation |
| |
| @example |
| $ gnatls switches `object_or_ali_file` |
| @end example |
| @end quotation |
| |
| The main argument is the list of object or @code{ali} files |
| (see @ref{44,,The Ada Library Information Files}) |
| for which information is requested. |
| |
| In normal mode, without additional option, @cite{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: |
| |
| @quotation |
| |
| @example |
| $ 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 |
| @end example |
| @end quotation |
| |
| The first line can be interpreted as follows: the main unit which is |
| contained in |
| object file @code{demo1.o} is demo1, whose main source is in |
| @code{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: |
| |
| |
| @table @asis |
| |
| @item @emph{OK (unchanged)} |
| |
| The version of the source file used for the compilation of the |
| specified unit corresponds exactly to the actual source file. |
| |
| @item @emph{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 |
| @emph{-m (minimal recompilation)}, a file marked |
| MOK will not be recompiled. |
| |
| @item @emph{DIF (modified)} |
| |
| No version of the source found on the path corresponds to the source |
| used to build this object. |
| |
| @item @emph{??? (file not found)} |
| |
| No source file was found for this unit. |
| |
| @item @emph{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. |
| @end table |
| |
| @node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls |
| @anchor{gnat_ugn/gnat_utility_programs id7}@anchor{1d9}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{1da} |
| @subsection Switches for @cite{gnatls} |
| |
| |
| @cite{gnatls} recognizes the following switches: |
| |
| @geindex --version (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{--version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{*--help} |
| |
| If @emph{--version} was not used, display usage, then exit disregarding |
| all other options. |
| @end table |
| |
| @geindex -a (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-a} |
| |
| Consider all units, including those of the predefined Ada library. |
| Especially useful with @emph{-d}. |
| @end table |
| |
| @geindex -d (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-d} |
| |
| List sources from which specified units depend on. |
| @end table |
| |
| @geindex -h (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-h} |
| |
| Output the list of options. |
| @end table |
| |
| @geindex -o (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-o} |
| |
| Only output information about object files. |
| @end table |
| |
| @geindex -s (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-s} |
| |
| Only output information about source files. |
| @end table |
| |
| @geindex -u (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-u} |
| |
| Only output information about compilation units. |
| @end table |
| |
| @geindex -files (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-files=@emph{file}} |
| |
| Take as arguments the files listed in text file @cite{file}. |
| Text file @cite{file} may contain empty lines that are ignored. |
| Each nonempty line should contain the name of an existing file. |
| Several such switches may be specified simultaneously. |
| @end table |
| |
| @geindex -aO (gnatls) |
| |
| @geindex -aI (gnatls) |
| |
| @geindex -I (gnatls) |
| |
| @geindex -I- (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-aO@emph{dir}}, @code{-aI@emph{dir}}, @code{-I@emph{dir}}, @code{-I-}, @code{-nostdinc} |
| |
| Source path manipulation. Same meaning as the equivalent @emph{gnatmake} |
| flags (@ref{e2,,Switches for gnatmake}). |
| @end table |
| |
| @geindex -aP (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-aP@emph{dir}} |
| |
| Add @cite{dir} at the beginning of the project search dir. |
| @end table |
| |
| @geindex --RTS (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{--RTS=@emph{rts-path}`} |
| |
| Specifies the default location of the runtime library. Same meaning as the |
| equivalent @emph{gnatmake} flag (@ref{e2,,Switches for gnatmake}). |
| @end table |
| |
| @geindex -v (gnatls) |
| |
| |
| @table @asis |
| |
| @item @code{-v} |
| |
| Verbose mode. Output the complete source, object and project 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: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Preelaborable}: The unit is preelaborable in the Ada sense. |
| |
| @item |
| @emph{No_Elab_Code}: No elaboration code has been produced by the compiler for this unit. |
| |
| @item |
| @emph{Pure}: The unit is pure in the Ada sense. |
| |
| @item |
| @emph{Elaborate_Body}: The unit contains a pragma Elaborate_Body. |
| |
| @item |
| @emph{Remote_Types}: The unit contains a pragma Remote_Types. |
| |
| @item |
| @emph{Shared_Passive}: The unit contains a pragma Shared_Passive. |
| |
| @item |
| @emph{Predefined}: This unit is part of the predefined environment and cannot be modified |
| by the user. |
| |
| @item |
| @emph{Remote_Call_Interface}: The unit contains a pragma Remote_Call_Interface. |
| @end itemize |
| @end table |
| |
| @node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls |
| @anchor{gnat_ugn/gnat_utility_programs id8}@anchor{1db}@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{1dc} |
| @subsection Example of @cite{gnatls} Usage |
| |
| |
| Example of using the verbose switch. Note how the source and |
| object paths are affected by the -I switch. |
| |
| @quotation |
| |
| @example |
| $ gnatls -v -I.. demo1.o |
| |
| GNATLS 5.03w (20041123-34) |
| Copyright 1997-2004 Free Software Foundation, Inc. |
| |
| Source Search Path: |
| <Current_Directory> |
| ../ |
| /home/comar/local/adainclude/ |
| |
| Object Search Path: |
| <Current_Directory> |
| ../ |
| /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ |
| |
| Project Search Path: |
| <Current_Directory> |
| /home/comar/local/lib/gnat/ |
| |
| ./demo1.o |
| Unit => |
| Name => demo1 |
| Kind => subprogram body |
| Flags => No_Elab_Code |
| Source => demo1.adb modified |
| @end example |
| @end quotation |
| |
| 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. |
| |
| @quotation |
| |
| @example |
| $ 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 |
| @end example |
| @end quotation |
| |
| @node The Cross-Referencing Tools gnatxref and gnatfind,The Ada to HTML Converter gnathtml,The GNAT Library Browser gnatls,GNAT Utility Programs |
| @anchor{gnat_ugn/gnat_utility_programs the-cross-referencing-tools-gnatxref-and-gnatfind}@anchor{24}@anchor{gnat_ugn/gnat_utility_programs id9}@anchor{1dd} |
| @section The Cross-Referencing Tools @cite{gnatxref} and @cite{gnatfind} |
| |
| |
| @geindex gnatxref |
| |
| @geindex gnatfind |
| |
| The compiler generates cross-referencing information (unless |
| you set the @code{-gnatx} switch), which are saved in the @code{.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 @cite{gnatxref} and @cite{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 @cite{gnatfind} is intended for locating |
| definitions and/or references to a specified entity or entities, whereas |
| @cite{gnatxref} is oriented to generating a full report of all |
| cross-references. |
| |
| To use these tools, you must not compile your application using the |
| @emph{-gnatx} switch on the @emph{gnatmake} command line |
| (see @ref{1d,,Building with gnatmake}). Otherwise, cross-referencing |
| information will not be generated. |
| |
| Note: to invoke @cite{gnatxref} or @cite{gnatfind} with a project file, |
| use the @cite{gnat} driver (see @ref{122,,The GNAT Driver and Project Files}). |
| |
| @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:: |
| |
| @end menu |
| |
| @node gnatxref Switches,gnatfind Switches,,The Cross-Referencing Tools gnatxref and gnatfind |
| @anchor{gnat_ugn/gnat_utility_programs id10}@anchor{1de}@anchor{gnat_ugn/gnat_utility_programs gnatxref-switches}@anchor{1df} |
| @subsection @cite{gnatxref} Switches |
| |
| |
| The command invocation for @cite{gnatxref} is: |
| |
| @quotation |
| |
| @example |
| $ gnatxref [`switches`] `sourcefile1` [`sourcefile2` ...] |
| @end example |
| @end quotation |
| |
| where |
| |
| |
| @table @asis |
| |
| @item @emph{sourcefile1} [, @emph{sourcefile2} ...] |
| |
| identify 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 @code{source*.adb} is the same as giving every file in the current |
| directory whose name starts with @code{source} and whose extension is |
| @code{adb}. |
| |
| You shouldn't specify any directory name, just base names. @emph{gnatxref} |
| and @emph{gnatfind} will be able to locate these files by themselves using |
| the source path. If you specify directories, no result is produced. |
| @end table |
| |
| The following switches are available for @emph{gnatxref}: |
| |
| @geindex --version (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{-version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{-help} |
| |
| If @emph{--version} was not used, display usage, then exit disregarding |
| all other options. |
| @end table |
| |
| @geindex -a (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{a} |
| |
| If this switch is present, @cite{gnatfind} and @cite{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 @cite{gnatfind} and @cite{gnatxref} |
| much faster, and their output much smaller. Read-only here refers to access |
| or permissions status in the file system for the current user. |
| @end table |
| |
| @geindex -aIDIR (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{aI@emph{DIR}} |
| |
| When looking for source files also look in directory DIR. The order in which |
| source file search is undertaken is the same as for @emph{gnatmake}. |
| @end table |
| |
| @geindex -aODIR (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{aO@emph{DIR}} |
| |
| When searching for library and object files, look in directory |
| DIR. The order in which library files are searched is the same as for |
| @emph{gnatmake}. |
| @end table |
| |
| @geindex -nostdinc (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{nostdinc} |
| |
| Do not look for sources in the system default directory. |
| @end table |
| |
| @geindex -nostdlib (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{nostdlib} |
| |
| Do not look for library files in the system default directory. |
| @end table |
| |
| @geindex --ext (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{-ext=@emph{extension}} |
| |
| Specify an alternate ali file extension. The default is @cite{ali} and other |
| extensions (e.g. @cite{gli} for C/C++ sources when using @emph{-fdump-xref}) |
| may be specified via this switch. Note that if this switch overrides the |
| default, which means that only the new extension will be considered. |
| @end table |
| |
| @geindex --RTS (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{-RTS=@emph{rts-path}} |
| |
| Specifies the default location of the runtime library. Same meaning as the |
| equivalent @emph{gnatmake} flag (@ref{e2,,Switches for gnatmake}). |
| @end table |
| |
| @geindex -d (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{d} |
| |
| If this switch is set @cite{gnatxref} will output the parent type |
| reference for each matching derived types. |
| @end table |
| |
| @geindex -f (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{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. |
| @end table |
| |
| @geindex -g (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{g} |
| |
| If this switch is set, information is output only for library-level |
| entities, ignoring local entities. The use of this switch may accelerate |
| @cite{gnatfind} and @cite{gnatxref}. |
| @end table |
| |
| @geindex -IDIR (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{I@emph{DIR}} |
| |
| Equivalent to @code{-aODIR -aIDIR}. |
| @end table |
| |
| @geindex -pFILE (gnatxref) |
| |
| |
| @table @asis |
| |
| @item @code{p@emph{FILE}} |
| |
| Specify a project file to use @ref{b,,GNAT Project Manager}. |
| If you need to use the @code{.gpr} |
| project files, you should use gnatxref through the GNAT driver |
| (@emph{gnat xref -Pproject}). |
| |
| By default, @cite{gnatxref} and @cite{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 @code{-aI} |
| and @code{-aO}. |
| |
| @item @code{u} |
| |
| Output only unused symbols. This may be really useful if you give your |
| main compilation unit on the command line, as @cite{gnatxref} will then |
| display every unused entity and 'with'ed package. |
| |
| @item @code{v} |
| |
| Instead of producing the default output, @cite{gnatxref} will generate a |
| @code{tags} file that can be used by vi. For examples how to use this |
| feature, see @ref{1e0,,Examples of gnatxref Usage}. The tags file is output |
| to the standard output, thus you will have to redirect it to a file. |
| @end table |
| |
| 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 @code{gnatxref -ag} instead of @code{gnatxref -a -g}. |
| |
| @node gnatfind Switches,Project Files for gnatxref and gnatfind,gnatxref Switches,The Cross-Referencing Tools gnatxref and gnatfind |
| @anchor{gnat_ugn/gnat_utility_programs id11}@anchor{1e1}@anchor{gnat_ugn/gnat_utility_programs gnatfind-switches}@anchor{1e2} |
| @subsection @cite{gnatfind} Switches |
| |
| |
| The command invocation for @cite{gnatfind} is: |
| |
| @quotation |
| |
| @example |
| $ gnatfind [`switches`] `pattern`[:`sourcefile`[:`line`[:`column`]]] |
| [`file1` `file2` ...] |
| @end example |
| @end quotation |
| |
| with the following iterpretation of the command arguments: |
| |
| |
| @table @asis |
| |
| @item @emph{pattern} |
| |
| An entity will be output only if it matches the regular expression found |
| in @cite{pattern}, see @ref{1e3,,Regular Expressions in gnatfind and gnatxref}. |
| |
| Omitting the pattern is equivalent to specifying @code{*}, 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. |
| |
| @item @emph{sourcefile} |
| |
| @cite{gnatfind} will look for references, bodies or declarations |
| of symbols referenced in @code{sourcefile}, at line @cite{line} |
| and column @cite{column}. See @ref{1e4,,Examples of gnatfind Usage} |
| for syntax examples. |
| |
| @item @emph{line} |
| |
| A decimal integer identifying the line number containing |
| the reference to the entity (or entities) to be located. |
| |
| @item @emph{column} |
| |
| 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. |
| |
| @item @emph{file1 file2 ...} |
| |
| The search will be restricted to these source files. If none are given, then |
| the search will be conducted for every library file in the search path. |
| These files must appear only after the pattern or sourcefile. |
| |
| These file names are considered to be regular expressions, so for instance |
| specifying @code{source*.adb} is the same as giving every file in the current |
| directory whose name starts with @code{source} and whose extension is |
| @code{adb}. |
| |
| The location of the spec of the entity will always be displayed, even if it |
| isn't in one of @code{file1}, @code{file2}, ... The |
| occurrences of the entity in the separate units of the ones given on the |
| command line will also be displayed. |
| |
| Note that if you specify at least one file in this part, @cite{gnatfind} may |
| sometimes not be able to find the body of the subprograms. |
| @end table |
| |
| At least one of 'sourcefile' or 'pattern' has to be present on |
| the command line. |
| |
| The following switches are available: |
| |
| @geindex --version (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{--version} |
| |
| Display Copyright and version, then exit disregarding all other options. |
| @end table |
| |
| @geindex --help (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{-help} |
| |
| If @emph{--version} was not used, display usage, then exit disregarding |
| all other options. |
| @end table |
| |
| @geindex -a (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{a} |
| |
| If this switch is present, @cite{gnatfind} and @cite{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 @cite{gnatfind} and @cite{gnatxref} |
| much faster, and their output much smaller. Read-only here refers to access |
| or permission status in the file system for the current user. |
| @end table |
| |
| @geindex -aIDIR (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{aI@emph{DIR}} |
| |
| When looking for source files also look in directory DIR. The order in which |
| source file search is undertaken is the same as for @emph{gnatmake}. |
| @end table |
| |
| @geindex -aODIR (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{aO@emph{DIR}} |
| |
| When searching for library and object files, look in directory |
| DIR. The order in which library files are searched is the same as for |
| @emph{gnatmake}. |
| @end table |
| |
| @geindex -nostdinc (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{nostdinc} |
| |
| Do not look for sources in the system default directory. |
| @end table |
| |
| @geindex -nostdlib (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{nostdlib} |
| |
| Do not look for library files in the system default directory. |
| @end table |
| |
| @geindex --ext (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{-ext=@emph{extension}} |
| |
| Specify an alternate ali file extension. The default is @cite{ali} and other |
| extensions (e.g. @cite{gli} for C/C++ sources when using @emph{-fdump-xref}) |
| may be specified via this switch. Note that if this switch overrides the |
| default, which means that only the new extension will be considered. |
| @end table |
| |
| @geindex --RTS (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{-RTS=@emph{rts-path}} |
| |
| Specifies the default location of the runtime library. Same meaning as the |
| equivalent @emph{gnatmake} flag (@ref{e2,,Switches for gnatmake}). |
| @end table |
| |
| @geindex -d (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{d} |
| |
| If this switch is set, then @cite{gnatfind} will output the parent type |
| reference for each matching derived types. |
| @end table |
| |
| @geindex -e (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{e} |
| |
| By default, @cite{gnatfind} accept the simple regular expression set for |
| @cite{pattern}. If this switch is set, then the pattern will be |
| considered as full Unix-style regular expression. |
| @end table |
| |
| @geindex -f (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{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. |
| @end table |
| |
| @geindex -g (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{g} |
| |
| If this switch is set, information is output only for library-level |
| entities, ignoring local entities. The use of this switch may accelerate |
| @cite{gnatfind} and @cite{gnatxref}. |
| @end table |
| |
| @geindex -IDIR (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{I@emph{DIR}} |
| |
| Equivalent to @code{-aODIR -aIDIR}. |
| @end table |
| |
| @geindex -pFILE (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{p@emph{FILE}} |
| |
| Specify a project file (@ref{b,,GNAT Project Manager}) to use. |
| By default, @cite{gnatxref} and @cite{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 @code{-aI} and |
| @code{-aO}. |
| @end table |
| |
| @geindex -r (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{r} |
| |
| By default, @cite{gnatfind} will output only the information about the |
| declaration, body or type completion of the entities. If this switch is |
| set, the @cite{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). |
| @end table |
| |
| @geindex -s (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{s} |
| |
| If this switch is set, then @cite{gnatfind} will output the content |
| of the Ada source file lines were the entity was found. |
| @end table |
| |
| @geindex -t (gnatfind) |
| |
| |
| @table @asis |
| |
| @item @code{t} |
| |
| If this switch is set, then @cite{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. |
| @end table |
| |
| 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 @code{gnatxref -ag} instead of |
| @code{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 @cite{*} at the end of the command line. |
| |
| @node Project Files for gnatxref and gnatfind,Regular Expressions in gnatfind and gnatxref,gnatfind Switches,The Cross-Referencing Tools gnatxref and gnatfind |
| @anchor{gnat_ugn/gnat_utility_programs project-files-for-gnatxref-and-gnatfind}@anchor{1e5}@anchor{gnat_ugn/gnat_utility_programs id12}@anchor{1e6} |
| @subsection Project Files for @emph{gnatxref} and @emph{gnatfind} |
| |
| |
| Project files allow a programmer to specify how to compile its |
| application, where to find sources, etc. These files are used |
| primarily by GPS, but they can also be used |
| by the two tools @cite{gnatxref} and @cite{gnatfind}. |
| |
| A project file name must end with @code{.gpr}. If a single one is |
| present in the current directory, then @cite{gnatxref} and @cite{gnatfind} will |
| extract the information from it. If multiple project files are found, none of |
| them is read, and you have to use the @code{-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 @code{src_dir} and @code{obj_dir}, you can only have one instance of |
| each line. If you have multiple instances, only the last one is taken into |
| account. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{src_dir=DIR} |
| |
| [default: @cite{"./"}]. |
| Specifies a directory where to look for source files. Multiple @cite{src_dir} |
| lines can be specified and they will be searched in the order they |
| are specified. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{obj_dir=DIR} |
| |
| [default: @cite{"./"}]. |
| Specifies a directory where to look for object and library files. Multiple |
| @cite{obj_dir} lines can be specified, and they will be searched in the order |
| they are specified |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{comp_opt=SWITCHES} |
| |
| [default: @cite{""}]. |
| Creates a variable which can be referred to subsequently by using |
| the @cite{$@{comp_opt@}} notation. This is intended to store the default |
| switches given to @emph{gnatmake} and @emph{gcc}. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{bind_opt=SWITCHES} |
| |
| [default: @cite{""}]. |
| Creates a variable which can be referred to subsequently by using |
| the @code{$@emph{bind_opt}} notation. This is intended to store the default |
| switches given to @emph{gnatbind}. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{link_opt=SWITCHES} |
| |
| [default: @cite{""}]. |
| Creates a variable which can be referred to subsequently by using |
| the @code{$@emph{link_opt}} notation. This is intended to store the default |
| switches given to @emph{gnatlink}. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{main=EXECUTABLE} |
| |
| [default: @cite{""}]. |
| Specifies the name of the executable for the application. This variable can |
| be referred to in the following lines by using the @code{@emph{$@{main}} notation. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{comp_cmd=COMMAND} |
| |
| [default: @cite{"gcc -c -I$@{src_dir@} -g -gnatq"}]. |
| Specifies the command used to compile a single file in the application. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{make_cmd=COMMAND} |
| |
| [default: @cite{"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. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{run_cmd=COMMAND} |
| |
| [default: @cite{"$@{main@}"}]. |
| Specifies the command used to run the application. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{debug_cmd=COMMAND} |
| |
| [default: @cite{"gdb $@{main@}"}]. |
| Specifies the command used to debug the application |
| @end table |
| @end itemize |
| |
| @emph{gnatxref} and @emph{gnatfind} only take into account the |
| @cite{src_dir} and @cite{obj_dir} lines, and ignore the others. |
| |
| @node Regular Expressions in gnatfind and gnatxref,Examples of gnatxref Usage,Project Files for gnatxref and gnatfind,The Cross-Referencing Tools gnatxref and gnatfind |
| @anchor{gnat_ugn/gnat_utility_programs id13}@anchor{1e7}@anchor{gnat_ugn/gnat_utility_programs regular-expressions-in-gnatfind-and-gnatxref}@anchor{1e3} |
| @subsection Regular Expressions in @cite{gnatfind} and @cite{gnatxref} |
| |
| |
| As specified in the section about @emph{gnatfind}, the pattern can be a |
| regular expression. Two kinds of regular expressions |
| are recognized: |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{Globbing pattern} |
| |
| These are the most common regular expression. They are the same as are |
| generally used in a Unix shell command line, or in a DOS session. |
| |
| Here is a more formal grammar: |
| |
| @example |
| 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 |
| @end example |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{Full regular expression} |
| |
| The second set of regular expressions is much more powerful. This is the |
| type of regular expressions recognized by utilities such as @code{grep}. |
| |
| The following is the form of a regular expression, expressed in same BNF |
| style as is found in the Ada Reference Manual: |
| |
| @example |
| 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 ()[].*+?^ |
| @end example |
| |
| Here are a few examples: |
| |
| @quotation |
| |
| |
| @table @asis |
| |
| @item @code{abcde|fghi} |
| |
| will match any of the two strings @code{abcde} and @code{fghi}, |
| |
| @item @code{abc*d} |
| |
| will match any string like @code{abd}, @code{abcd}, @code{abccd}, |
| @code{abcccd}, and so on, |
| |
| @item @code{[a-z]+} |
| |
| will match any string which has only lowercase characters in it (and at |
| least one character. |
| @end table |
| @end quotation |
| @end table |
| @end itemize |
| |
| @node Examples of gnatxref Usage,Examples of gnatfind Usage,Regular Expressions in gnatfind and gnatxref,The Cross-Referencing Tools gnatxref and gnatfind |
| @anchor{gnat_ugn/gnat_utility_programs examples-of-gnatxref-usage}@anchor{1e0}@anchor{gnat_ugn/gnat_utility_programs id14}@anchor{1e8} |
| @subsection Examples of @cite{gnatxref} Usage |
| |
| |
| @menu |
| * General Usage:: |
| * Using gnatxref with vi:: |
| |
| @end menu |
| |
| @node General Usage,Using gnatxref with vi,,Examples of gnatxref Usage |
| @anchor{gnat_ugn/gnat_utility_programs general-usage}@anchor{1e9} |
| @subsubsection General Usage |
| |
| |
| For the following examples, we will consider the following units: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| The first thing to do is to recompile your application (for instance, in |
| that case just by doing a @code{gnatmake main}, so that GNAT generates |
| the cross-referencing information. |
| You can then issue any of the following commands: |
| |
| @quotation |
| |
| |
| @itemize * |
| |
| @item |
| @code{gnatxref main.adb} |
| @cite{gnatxref} generates cross-reference information for main.adb |
| and every unit 'with'ed by main.adb. |
| |
| The output would be: |
| |
| @quotation |
| |
| @example |
| 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 |
| @end example |
| @end quotation |
| |
| This shows that the entity @cite{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 @cite{Print} is declared in bar.ads, line 2, column 15 and it |
| is referenced in main.adb, line 6 column 12 and line 7 column 12. |
| |
| @item |
| @code{gnatxref package1.adb package2.ads} |
| @cite{gnatxref} will generates cross-reference information for |
| package1.adb, package2.ads and any other package 'with'ed by any |
| of these. |
| @end itemize |
| @end quotation |
| |
| @node Using gnatxref with vi,,General Usage,Examples of gnatxref Usage |
| @anchor{gnat_ugn/gnat_utility_programs using-gnatxref-with-vi}@anchor{1ea} |
| @subsubsection Using gnatxref with vi |
| |
| |
| @cite{gnatxref} can generate a tags file output, which can be used |
| directly from @emph{vi}. Note that the standard version of @emph{vi} |
| will not work properly with overloaded symbols. Consider using another |
| free implementation of @emph{vi}, such as @emph{vim}. |
| |
| @quotation |
| |
| @example |
| $ gnatxref -v gnatfind.adb > tags |
| @end example |
| @end quotation |
| |
| The following command will generate the tags file for @cite{gnatfind} itself |
| (if the sources are in the search path!): |
| |
| @quotation |
| |
| @example |
| $ gnatxref -v gnatfind.adb > tags |
| @end example |
| @end quotation |
| |
| From @emph{vi}, you can then use the command @code{:tag @emph{entity}} |
| (replacing @cite{entity} by whatever you are looking for), and vi will |
| display a new file with the corresponding declaration of entity. |
| |
| @node Examples of gnatfind Usage,,Examples of gnatxref Usage,The Cross-Referencing Tools gnatxref and gnatfind |
| @anchor{gnat_ugn/gnat_utility_programs id15}@anchor{1eb}@anchor{gnat_ugn/gnat_utility_programs examples-of-gnatfind-usage}@anchor{1e4} |
| @subsection Examples of @cite{gnatfind} Usage |
| |
| |
| |
| @itemize * |
| |
| @item |
| @code{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 @code{-f} |
| switch is set) |
| |
| The output will look like: |
| |
| @quotation |
| |
| @example |
| directory/main.ads:106:14: xyz <= declaration |
| directory/main.adb:24:10: xyz <= body |
| directory/foo.ads:45:23: xyz <= declaration |
| @end example |
| @end quotation |
| |
| I.e., 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 |
| |
| @item |
| @code{gnatfind -fs xyz:main.adb} |
| This is the same command as the previous one, but @cite{gnatfind} will |
| display the content of the Ada source file lines. |
| |
| The output will look like: |
| |
| @example |
| 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; |
| @end example |
| |
| This can make it easier to find exactly the location your are looking |
| for. |
| |
| @item |
| @code{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.ads and foo.adb. |
| |
| @item |
| @code{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 @code{gnatfind "*":main.adb:123`} |
| |
| @item |
| @code{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. |
| @end itemize |
| |
| @node The Ada to HTML Converter gnathtml,,The Cross-Referencing Tools gnatxref and gnatfind,GNAT Utility Programs |
| @anchor{gnat_ugn/gnat_utility_programs the-ada-to-html-converter-gnathtml}@anchor{25}@anchor{gnat_ugn/gnat_utility_programs id16}@anchor{1ec} |
| @section The Ada to HTML Converter @cite{gnathtml} |
| |
| |
| @geindex gnathtml |
| |
| @emph{gnathtml} is a Perl script that allows Ada source files to be browsed using |
| standard Web browsers. For installation information, see @ref{1ed,,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 @emph{-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. |
| |
| @menu |
| * Invoking gnathtml:: |
| * Installing gnathtml:: |
| |
| @end menu |
| |
| @node Invoking gnathtml,Installing gnathtml,,The Ada to HTML Converter gnathtml |
| @anchor{gnat_ugn/gnat_utility_programs invoking-gnathtml}@anchor{1ee}@anchor{gnat_ugn/gnat_utility_programs id17}@anchor{1ef} |
| @subsection Invoking @emph{gnathtml} |
| |
| |
| The command line is as follows: |
| |
| @quotation |
| |
| @example |
| $ perl gnathtml.pl [`switches`] `ada-files` |
| @end example |
| @end quotation |
| |
| You can specify as many Ada files as you want. @cite{gnathtml} will generate |
| an html file for every ada file, and a global file called @code{index.htm}. |
| This file is an index of every identifier defined in the files. |
| |
| The following switches are available: |
| |
| @geindex -83 (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{83} |
| |
| Only the Ada 83 subset of keywords will be highlighted. |
| @end table |
| |
| @geindex -cc (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{cc @emph{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. |
| @end table |
| |
| @geindex -d (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{d} |
| |
| If the Ada files depend on some other files (for instance through |
| @cite{with} clauses, the latter files 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. |
| @end table |
| |
| @geindex -D (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{D} |
| |
| This command is the same as @emph{-d} above, but @emph{gnathtml} will |
| also look for files in the run-time library, and generate html files for them. |
| @end table |
| |
| @geindex -ext (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{ext @emph{extension}} |
| |
| This option allows you to change the extension of the generated HTML files. |
| If you do not specify an extension, it will default to @code{htm}. |
| @end table |
| |
| @geindex -f (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{f} |
| |
| By default, gnathtml will generate html links only for global entities |
| ('with'ed units, global variables and types,...). If you specify |
| @emph{-f} on the command line, then links will be generated for local |
| entities too. |
| @end table |
| |
| @geindex -l (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{l @emph{number}} |
| |
| If this switch is provided and @cite{number} is not 0, then |
| @cite{gnathtml} will number the html files every @cite{number} line. |
| @end table |
| |
| @geindex -I (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{I @emph{dir}} |
| |
| Specify a directory to search for library files (@code{.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. |
| @end table |
| |
| @geindex -o (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{o @emph{dir}} |
| |
| Specify the output directory for html files. By default, gnathtml will |
| saved the generated html files in a subdirectory named @code{html/}. |
| @end table |
| |
| @geindex -p (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{p @emph{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 use @code{.gpr} 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. |
| @end table |
| |
| @geindex -sc (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{sc @emph{color}} |
| |
| This switch 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. |
| @end table |
| |
| @geindex -t (gnathtml) |
| |
| |
| @table @asis |
| |
| @item @code{t @emph{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. |
| @end table |
| |
| @node Installing gnathtml,,Invoking gnathtml,The Ada to HTML Converter gnathtml |
| @anchor{gnat_ugn/gnat_utility_programs installing-gnathtml}@anchor{1ed}@anchor{gnat_ugn/gnat_utility_programs id18}@anchor{1f0} |
| @subsection Installing @cite{gnathtml} |
| |
| |
| @cite{Perl} needs to be installed on your machine to run this script. |
| @cite{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 |
| @cite{gnathtml}, to explicitly specify where Perl |
| is located. The syntax of this line is: |
| |
| @quotation |
| |
| @example |
| #!full_path_name_to_perl |
| @end example |
| @end quotation |
| |
| Alternatively, you may run the script using the following command line: |
| |
| @quotation |
| |
| @example |
| $ perl gnathtml.pl [`switches`] `files` |
| @end example |
| @end quotation |
| |
| @c -- +---------------------------------------------------------------------+ |
| |
| @c -- | The following sections are present only in the PRO and GPL editions | |
| |
| @c -- +---------------------------------------------------------------------+ |
| |
| |
| |
| |
| |
| |
| |
| @c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit |
| |
| @node GNAT and Program Execution,Platform-Specific Information,GNAT Utility Programs,Top |
| @anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{e}@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{1f1}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{1f2} |
| @chapter GNAT and Program Execution |
| |
| |
| This chapter covers several topics: |
| |
| |
| @itemize * |
| |
| @item |
| @ref{1f3,,Running and Debugging Ada Programs} |
| |
| @item |
| @ref{1f4,,Code Coverage and Profiling} |
| |
| @item |
| @ref{1f5,,Improving Performance} |
| |
| @item |
| @ref{1f6,,Overflow Check Handling in GNAT} |
| |
| @item |
| @ref{1f7,,Performing Dimensionality Analysis in GNAT} |
| |
| @item |
| @ref{1f8,,Stack Related Facilities} |
| |
| @item |
| @ref{1f9,,Memory Management Issues} |
| @end itemize |
| |
| @menu |
| * Running and Debugging Ada Programs:: |
| * Code Coverage and Profiling:: |
| * Improving Performance:: |
| * Overflow Check Handling in GNAT:: |
| * Performing Dimensionality Analysis in GNAT:: |
| * Stack Related Facilities:: |
| * Memory Management Issues:: |
| |
| @end menu |
| |
| @node Running and Debugging Ada Programs,Code Coverage and Profiling,,GNAT and Program Execution |
| @anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{1f3}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{26} |
| @section Running and Debugging Ada Programs |
| |
| |
| @geindex Debugging |
| |
| This section discusses how to debug Ada programs. |
| |
| An incorrect Ada program may be handled in three ways by the GNAT compiler: |
| |
| |
| @itemize * |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| When presented with a program that contains convoluted errors, GNAT |
| itself may terminate abnormally without providing full diagnostics on |
| the incorrect user program. |
| @end itemize |
| |
| @geindex Debugger |
| |
| @geindex gdb |
| |
| @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:: |
| * Stopping When Ada Exceptions Are Raised:: |
| * Ada Tasks:: |
| * Debugging Generic Units:: |
| * Remote Debugging with gdbserver:: |
| * GNAT Abnormal Termination or Failure to Terminate:: |
| * Naming Conventions for GNAT Source Files:: |
| * Getting Internal Debugging Information:: |
| * Stack Traceback:: |
| |
| @end menu |
| |
| @node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{1fa}@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{1fb} |
| @subsection The GNAT Debugger GDB |
| |
| |
| @cite{GDB} is a general purpose, platform-independent debugger that |
| can be used to debug mixed-language programs compiled with @emph{gcc}, |
| and in particular is capable of debugging Ada programs compiled with |
| GNAT. The latest versions of @cite{GDB} are Ada-aware and can handle |
| complex Ada data structures. |
| |
| See @cite{Debugging with GDB}, |
| for full details on the usage of @cite{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 @cite{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 @emph{gcc} or @emph{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 @cite{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 @cite{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 @cite{GDB} were not present. This |
| is a crucial part of the @cite{GDB} design philosophy. @cite{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, @cite{GDB} accesses |
| the debugging information and can respond to user commands to inspect |
| variables, and more generally to report on the state of execution. |
| |
| @node Running GDB,Introduction to GDB Commands,The GNAT Debugger GDB,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution id4}@anchor{1fc}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{1fd} |
| @subsection Running GDB |
| |
| |
| This section describes how to initiate the debugger. |
| |
| The debugger can be launched from a @cite{GPS} menu or |
| directly from the command line. The description below covers the latter use. |
| All the commands shown can be used in the @cite{GPS} debug console window, |
| but there are usually more GUI-based ways to achieve the same effect. |
| |
| The command to run @cite{GDB} is |
| |
| @quotation |
| |
| @example |
| $ gdb program |
| @end example |
| @end quotation |
| |
| where @cite{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 @cite{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 @cite{GDB}. |
| |
| @node Introduction to GDB Commands,Using Ada Expressions,Running GDB,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{1fe}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{1ff} |
| @subsection Introduction to GDB Commands |
| |
| |
| @cite{GDB} contains a large repertoire of commands. |
| See @cite{Debugging with GDB} for extensive documentation on the use |
| of these commands, together with examples of their use. Furthermore, |
| the command @emph{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 @cite{GDB} is about. You should create |
| a simple program with debugging information and experiment with the use of |
| these @cite{GDB} commands on the program as you read through the |
| following section. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{set args `arguments`} |
| |
| The @cite{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 @cite{set args} |
| command is not needed if the program does not require arguments. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{run} |
| |
| The @cite{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. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{breakpoint `location`} |
| |
| The breakpoint command sets a breakpoint, that is to say a point at which |
| execution will halt and @cite{GDB} will await further |
| commands. @cite{location} is |
| either a line number within a file, given in the format @cite{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 @cite{GDB} signals that the breakpoint was encountered by |
| printing the line of code before which the program is halted. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{catch exception `name`} |
| |
| This command causes the program execution to stop whenever exception |
| @cite{name} is raised. If @cite{name} is omitted, then the execution is |
| suspended when any exception is raised. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{print `expression`} |
| |
| This will print the value of the given expression. Most simple |
| Ada expression formats are properly handled by @cite{GDB}, so the expression |
| can contain function calls, variables, operators, and attribute references. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{continue} |
| |
| Continues execution following a breakpoint, until the next breakpoint or the |
| termination of the program. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{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. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{next} |
| |
| Executes a single line. If this line is a subprogram call, executes and |
| returns from the call. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{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. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{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. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{up} |
| |
| At a breakpoint, @cite{GDB} can display the values of variables local |
| to the current frame. The command @cite{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. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{down} |
| |
| Moves the focus of @cite{GDB} down from the frame currently being |
| examined to the frame of its callee (the reverse of the previous command), |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{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. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{kill} |
| |
| Kills the child process in which the program is running under GDB. |
| This may be useful for several purposes: |
| |
| |
| @itemize * |
| |
| @item |
| It allows you to recompile and relink your program, since on many systems |
| you cannot regenerate an executable file while it is running in a process. |
| |
| @item |
| You can run your program outside the debugger, on systems that do not |
| permit executing a program outside GDB while breakpoints are set |
| within GDB. |
| |
| @item |
| It allows you to debug a core dump rather than a running process. |
| @end itemize |
| @end table |
| @end itemize |
| |
| The above list is a very short introduction to the commands that |
| @cite{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 @cite{Debugging with GDB}. |
| Note that most commands can be abbreviated |
| (for example, c for continue, bt for backtrace). |
| |
| @node Using Ada Expressions,Calling User-Defined Subprograms,Introduction to GDB Commands,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution id6}@anchor{200}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{201} |
| @subsection Using Ada Expressions |
| |
| |
| @geindex Ada expressions (in gdb) |
| |
| @cite{GDB} supports a fairly large subset of Ada expression syntax, with some |
| extensions. The philosophy behind the design of this subset is |
| |
| @quotation |
| |
| |
| @itemize * |
| |
| @item |
| That @cite{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 @cite{GDB}). |
| |
| @item |
| That type safety and strict adherence to Ada language restrictions |
| are not particularly relevant in a debugging context. |
| |
| @item |
| That brevity is important to the @cite{GDB} user. |
| @end itemize |
| @end quotation |
| |
| Thus, for brevity, the debugger acts as if there were |
| implicit @cite{with} and @cite{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, |
| @cite{GDB} asks the user's intent. |
| |
| For details on the supported Ada syntax, see @cite{Debugging with GDB}. |
| |
| @node Calling User-Defined Subprograms,Using the next Command in a Function,Using Ada Expressions,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{202}@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{203} |
| @subsection Calling User-Defined Subprograms |
| |
| |
| An important capability of @cite{GDB} is the ability to call user-defined |
| subprograms while debugging. This is achieved simply by entering |
| a subprogram call statement in the form: |
| |
| @quotation |
| |
| @example |
| call subprogram-name (parameters) |
| @end example |
| @end quotation |
| |
| The keyword @cite{call} can be omitted in the normal case where the |
| @cite{subprogram-name} does not coincide with any of the predefined |
| @cite{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 @cite{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 |
| @cite{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 @cite{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. |
| |
| Another useful application of this capability is to deal with situations of |
| complex data which are not handled suitably by GDB. For example, if you specify |
| Convention Fortran for a multi-dimensional array, GDB does not know that |
| the ordering of array elements has been switched and will not properly |
| address the array elements. In such a case, instead of trying to print the |
| elements directly from GDB, you can write a callable procedure that prints |
| the elements in the desired format. |
| |
| @node Using the next Command in a Function,Stopping When Ada Exceptions Are Raised,Calling User-Defined Subprograms,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{204}@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{205} |
| @subsection Using the @emph{next} Command in a Function |
| |
| |
| When you use the @cite{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 @cite{return} statement. |
| |
| Part of the code for a return statement is the 'epilogue' of the function. |
| This is the code that returns to the caller. There is only one copy of |
| this epilogue 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 epilogue is associated with the first statement |
| of the function. |
| |
| The result is that if you use the @cite{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. |
| |
| @node Stopping When Ada Exceptions Are Raised,Ada Tasks,Using the next Command in a Function,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{206}@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{207} |
| @subsection Stopping When Ada Exceptions Are Raised |
| |
| |
| @geindex Exceptions (in gdb) |
| |
| You can set catchpoints that stop the program execution when your program |
| raises selected exceptions. |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{catch exception} |
| |
| Set a catchpoint that stops execution whenever (any task in the) program |
| raises any exception. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{catch exception `name`} |
| |
| Set a catchpoint that stops execution whenever (any task in the) program |
| raises the exception @cite{name}. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{catch exception unhandled} |
| |
| Set a catchpoint that stops executing whenever (any task in the) program |
| raises an exception for which there is no handler. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{info exceptions}, @emph{info exceptions `regexp`} |
| |
| The @cite{info exceptions} command permits the user to examine all defined |
| exceptions within Ada programs. With a regular expression, @cite{regexp}, as |
| argument, prints out only those exceptions whose name matches @cite{regexp}. |
| @end table |
| @end itemize |
| |
| @geindex Tasks (in gdb) |
| |
| @node Ada Tasks,Debugging Generic Units,Stopping When Ada Exceptions Are Raised,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution ada-tasks}@anchor{208}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{209} |
| @subsection Ada Tasks |
| |
| |
| @cite{GDB} allows the following task-related commands: |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{info tasks} |
| |
| This command shows a list of current Ada tasks, as in the following example: |
| |
| @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 |
| @end example |
| |
| 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. |
| @end table |
| @end itemize |
| |
| @geindex Breakpoints and tasks |
| |
| |
| @itemize * |
| |
| @item |
| @emph{break `linespec` task `taskid`}, @emph{break `linespec` task `taskid` if ...} |
| |
| @quotation |
| |
| These commands are like the @cite{break ... thread ...}. |
| @cite{linespec} specifies source lines. |
| |
| Use the qualifier @code{task @emph{taskid}} with a breakpoint command |
| to specify that you only want @cite{GDB} to stop the program when a |
| particular Ada task reaches this breakpoint. @cite{taskid} is one of the |
| numeric task identifiers assigned by @cite{GDB}, shown in the first |
| column of the @code{info tasks} display. |
| |
| If you do not specify @code{task @emph{taskid}} when you set a |
| breakpoint, the breakpoint applies to @emph{all} tasks of your |
| program. |
| |
| You can use the @cite{task} qualifier on conditional breakpoints as |
| well; in this case, place @code{task @emph{taskid}} before the |
| breakpoint condition (before the @cite{if}). |
| @end quotation |
| @end itemize |
| |
| @geindex Task switching (in gdb) |
| |
| |
| @itemize * |
| |
| @item |
| @emph{task `taskno`} |
| |
| @quotation |
| |
| This command allows switching to the task referred by @cite{taskno}. In |
| particular, this allows browsing of the backtrace of the specified |
| task. It is advisable to switch back to the original task before |
| continuing execution otherwise the scheduling of the program may be |
| perturbed. |
| @end quotation |
| @end itemize |
| |
| For more detailed information on the tasking support, |
| see @cite{Debugging with GDB}. |
| |
| @geindex Debugging Generic Units |
| |
| @geindex Generics |
| |
| @node Debugging Generic Units,Remote Debugging with gdbserver,Ada Tasks,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution debugging-generic-units}@anchor{20a}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{20b} |
| @subsection 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 |
| @cite{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 |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| Then to break on a call to procedure kp in the k2 instance, simply |
| use the command: |
| |
| @quotation |
| |
| @example |
| (gdb) break g.k2.kp |
| @end example |
| @end quotation |
| |
| 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. |
| |
| @geindex Remote Debugging with gdbserver |
| |
| @node Remote Debugging with gdbserver,GNAT Abnormal Termination or Failure to Terminate,Debugging Generic Units,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{20c}@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{20d} |
| @subsection Remote Debugging with gdbserver |
| |
| |
| On platforms where gdbserver is supported, it is possible to use this tool |
| to debug your application remotely. This can be useful in situations |
| where the program needs to be run on a target host that is different |
| from the host used for development, particularly when the target has |
| a limited amount of resources (either CPU and/or memory). |
| |
| To do so, start your program using gdbserver on the target machine. |
| gdbserver then automatically suspends the execution of your program |
| at its entry point, waiting for a debugger to connect to it. The |
| following commands starts an application and tells gdbserver to |
| wait for a connection with the debugger on localhost port 4444. |
| |
| @quotation |
| |
| @example |
| $ gdbserver localhost:4444 program |
| Process program created; pid = 5685 |
| Listening on port 4444 |
| @end example |
| @end quotation |
| |
| Once gdbserver has started listening, we can tell the debugger to establish |
| a connection with this gdbserver, and then start the same debugging session |
| as if the program was being debugged on the same host, directly under |
| the control of GDB. |
| |
| @quotation |
| |
| @example |
| $ gdb program |
| (gdb) target remote targethost:4444 |
| Remote debugging using targethost:4444 |
| 0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so. |
| (gdb) b foo.adb:3 |
| Breakpoint 1 at 0x401f0c: file foo.adb, line 3. |
| (gdb) continue |
| Continuing. |
| |
| Breakpoint 1, foo () at foo.adb:4 |
| 4 end foo; |
| @end example |
| @end quotation |
| |
| It is also possible to use gdbserver to attach to an already running |
| program, in which case the execution of that program is simply suspended |
| until the connection between the debugger and gdbserver is established. |
| |
| For more information on how to use gdbserver, see the @emph{Using the gdbserver Program} |
| section in @cite{Debugging with GDB}. |
| GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux. |
| |
| @geindex Abnormal Termination or Failure to Terminate |
| |
| @node GNAT Abnormal Termination or Failure to Terminate,Naming Conventions for GNAT Source Files,Remote Debugging with gdbserver,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution gnat-abnormal-termination-or-failure-to-terminate}@anchor{20e}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{20f} |
| @subsection 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. |
| |
| |
| @itemize * |
| |
| @item |
| Run @emph{gcc} with the @emph{-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 @emph{-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. |
| |
| @item |
| Run @emph{gcc} with the @emph{-v (verbose)} switch. In this |
| mode, @emph{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. |
| @end itemize |
| |
| @geindex -gnatdc switch |
| |
| |
| @itemize * |
| |
| @item |
| Run @emph{gcc} with the @emph{-gnatdc} switch. This is a GNAT specific |
| switch that does for the front-end what @emph{-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. |
| |
| @item |
| Finally, you can start |
| @cite{gdb} directly on the @cite{gnat1} executable. @cite{gnat1} is the |
| front-end of GNAT, and can be run independently (normally it is just |
| called from @emph{gcc}). You can use @cite{gdb} on @cite{gnat1} as you |
| would on a C program (but @ref{1fa,,The GNAT Debugger GDB} for caveats). The |
| @cite{where} command is the first line of attack; the variable |
| @cite{lineno} (seen by @cite{print lineno}), used by the second phase of |
| @cite{gnat1} and by the @emph{gcc} backend, indicates the source line at |
| which the execution stopped, and @cite{input_file name} indicates the name of |
| the source file. |
| @end itemize |
| |
| @node Naming Conventions for GNAT Source Files,Getting Internal Debugging Information,GNAT Abnormal Termination or Failure to Terminate,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{210}@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{211} |
| @subsection 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: |
| |
| |
| @itemize * |
| |
| @item |
| Files with prefix @code{sc} contain the lexical scanner. |
| |
| @item |
| All files prefixed with @code{par} are components of the parser. The |
| numbers correspond to chapters of the Ada Reference Manual. For example, |
| parsing of select statements can be found in @code{par-ch9.adb}. |
| |
| @item |
| All files prefixed with @code{sem} perform semantic analysis. The |
| numbers correspond to chapters of the Ada standard. For example, all |
| issues involving context clauses can be found in @code{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. |
| |
| @item |
| All files prefixed with @code{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 |
| @code{exp_ch3.adb}. |
| |
| @item |
| The files prefixed with @code{bind} implement the binder, which |
| verifies the consistency of the compilation, determines an order of |
| elaboration, and generates the bind file. |
| |
| @item |
| The files @code{atree.ads} and @code{atree.adb} detail the low-level |
| data structures used by the front-end. |
| |
| @item |
| The files @code{sinfo.ads} and @code{sinfo.adb} detail the structure of |
| the abstract syntax tree as produced by the parser. |
| |
| @item |
| The files @code{einfo.ads} and @code{einfo.adb} detail the attributes of |
| all entities, computed during semantic analysis. |
| |
| @item |
| Library management issues are dealt with in files with prefix |
| @code{lib}. |
| |
| @geindex Annex A (in Ada Reference Manual) |
| |
| @item |
| Ada files with the prefix @code{a-} are children of @cite{Ada}, as |
| defined in Annex A. |
| |
| @geindex Annex B (in Ada reference Manual) |
| |
| @item |
| Files with prefix @code{i-} are children of @cite{Interfaces}, as |
| defined in Annex B. |
| |
| @geindex System (package in Ada Reference Manual) |
| |
| @item |
| Files with prefix @code{s-} are children of @cite{System}. This includes |
| both language-defined children and GNAT run-time routines. |
| |
| @geindex GNAT (package) |
| |
| @item |
| Files with prefix @code{g-} are children of @cite{GNAT}. These are useful |
| general-purpose packages, fully documented in their specs. All |
| the other @code{.c} files are modifications of common @emph{gcc} files. |
| @end itemize |
| |
| @node Getting Internal Debugging Information,Stack Traceback,Naming Conventions for GNAT Source Files,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{212}@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{213} |
| @subsection 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 @code{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. |
| |
| @geindex traceback |
| |
| @geindex stack traceback |
| |
| @geindex stack unwinding |
| |
| @node Stack Traceback,,Getting Internal Debugging Information,Running and Debugging Ada Programs |
| @anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{214}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{215} |
| @subsection 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 @emph{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 is raised during program execution. |
| |
| @geindex traceback |
| @geindex non-symbolic |
| |
| @menu |
| * Non-Symbolic Traceback:: |
| * Symbolic Traceback:: |
| |
| @end menu |
| |
| @node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback |
| @anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{216}@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{217} |
| @subsubsection Non-Symbolic Traceback |
| |
| |
| Note: this feature is not supported on all platforms. See |
| @code{GNAT.Traceback} spec in @code{g-traceb.ads} |
| for a complete list of supported platforms. |
| |
| @subsubheading 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 @emph{-E} |
| @cite{gnatbind}'s option. With this option a stack traceback is stored as part |
| of exception information. You can retrieve this information using the |
| @cite{addr2line} tool. |
| |
| Here is a simple example: |
| |
| @quotation |
| |
| @example |
| procedure STB is |
| |
| procedure P1 is |
| begin |
| raise Constraint_Error; |
| end P1; |
| |
| procedure P2 is |
| begin |
| P1; |
| end P2; |
| |
| begin |
| P2; |
| end STB; |
| @end example |
| |
| @example |
| $ 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 |
| @end example |
| @end quotation |
| |
| As we see the traceback lists a sequence of addresses for the unhandled |
| exception @cite{CONSTRAINT_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 |
| @cite{addr2line} tool, described below, is invaluable. The use of this tool |
| requires the program to be compiled with debug information. |
| |
| @quotation |
| |
| @example |
| $ 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 |
| @end example |
| @end quotation |
| |
| The @cite{addr2line} tool has several other useful options: |
| |
| @quotation |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| @code{--functions} |
| |
| @tab |
| |
| to get the function name corresponding to any location |
| |
| @item |
| |
| @code{--demangle=gnat} |
| |
| @tab |
| |
| to use the gnat decoding mode for the function names. |
| Note that for binutils version 2.9.x the option is |
| simply @code{--demangle}. |
| |
| @end multitable |
| |
| |
| @example |
| $ 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 <mainCRTStartup> at /build/.../crt1.c:222 |
| @end example |
| @end quotation |
| |
| From this traceback we can see that the exception was raised in |
| @code{stb.adb} at line 5, which was reached from a procedure call in |
| @code{stb.adb} at line 10, and so on. The @code{b~std.adb} is the binder file, |
| which contains the call to the main program. |
| @ref{123,,Running gnatbind}. The remaining entries are assorted runtime routines, |
| and the output will vary from platform to platform. |
| |
| It is also possible to use @cite{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: |
| |
| @quotation |
| |
| @example |
| $ gdb -nw stb |
| @end example |
| @end quotation |
| |
| Furthermore, this feature is not implemented inside Windows DLL. Only |
| the non-symbolic traceback is reported in this case. |
| |
| @quotation |
| |
| @example |
| (gdb) break *0x401373 |
| Breakpoint 1 at 0x401373: file stb.adb, line 5. |
| @end example |
| @end quotation |
| |
| 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. |
| |
| @subsubheading Tracebacks From Exception Occurrences |
| |
| |
| Non-symbolic tracebacks are obtained by using the @emph{-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 |
| Ada facilities defined in @cite{Ada.Exceptions}. Here is a simple example: |
| |
| @quotation |
| |
| @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; |
| @end example |
| @end quotation |
| |
| This program will output: |
| |
| @quotation |
| |
| @example |
| $ stb |
| |
| Exception name: CONSTRAINT_ERROR |
| Message: stb.adb:12 |
| Call stack traceback locations: |
| 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 |
| @end example |
| @end quotation |
| |
| @subsubheading 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 @cite{GNAT.Traceback} API. This package includes a procedure called |
| @cite{Call_Chain} that computes a complete stack traceback, as well as useful |
| display procedures described below. It is not necessary to use the |
| @emph{-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 @cite{GNAT.Debug_Utilities.Image} to |
| convert addresses to strings: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| |
| @example |
| $ gnatmake -g 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# |
| @end example |
| @end quotation |
| |
| You can then get further information by invoking the @cite{addr2line} |
| tool as described earlier (note that the hexadecimal addresses |
| need to be specified in C format, with a leading '0x'). |
| |
| @geindex traceback |
| @geindex symbolic |
| |
| @node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback |
| @anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{218}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{219} |
| @subsubsection 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 |
| @code{GNAT.Traceback.Symbolic} spec in @code{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. |
| |
| @subsubheading Tracebacks From Exception Occurrences |
| |
| |
| Here is an example: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| |
| @example |
| $ gnatmake -g .\stb -bargs -E |
| $ 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 |
| @end example |
| @end quotation |
| |
| In the above example the @code{.\} syntax in the @emph{gnatmake} command |
| is currently required by @emph{addr2line} for files that are in |
| the current working directory. |
| Moreover, the exact sequence of linker options may vary from platform |
| to platform. |
| The above @emph{-largs} section is for Windows platforms. By contrast, |
| under Unix there is no need for the @emph{-largs} section. |
| Differences across platforms are due to details of linker implementation. |
| |
| @subsubheading 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 @cite{Symbolic_Traceback} to compute the symbolic |
| information. Here is an example: |
| |
| @quotation |
| |
| @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; |
| @end example |
| @end quotation |
| |
| @subsubheading Automatic Symbolic Tracebacks |
| |
| |
| Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as |
| in @cite{gprbuild -g ... -bargs -Es}). |
| This will cause the Exception_Information to contain a symbolic traceback, |
| which will also be printed if an unhandled exception terminates the |
| program. |
| |
| @geindex Code Coverage |
| |
| @geindex Profiling |
| |
| @node Code Coverage and Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution |
| @anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{1f4}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-and-profiling}@anchor{27} |
| @section Code Coverage and Profiling |
| |
| |
| This section describes how to use the @cite{gcov} coverage testing tool and |
| the @cite{gprof} profiler tool on Ada programs. |
| |
| @geindex gcov |
| |
| @menu |
| * Code Coverage of Ada Programs with gcov:: |
| * Profiling an Ada Program with gprof:: |
| |
| @end menu |
| |
| @node Code Coverage of Ada Programs with gcov,Profiling an Ada Program with gprof,,Code Coverage and Profiling |
| @anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{21a}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-of-ada-programs-with-gcov}@anchor{21b} |
| @subsection Code Coverage of Ada Programs with gcov |
| |
| |
| @cite{gcov} is a test coverage program: it analyzes the execution of a given |
| program on selected tests, to help you determine the portions of the program |
| that are still untested. |
| |
| @cite{gcov} is part of the GCC suite, and is described in detail in the GCC |
| User's Guide. You can refer to this documentation for a more complete |
| description. |
| |
| This chapter provides a quick startup guide, and |
| details some GNAT-specific features. |
| |
| @menu |
| * Quick startup guide:: |
| * GNAT specifics:: |
| |
| @end menu |
| |
| @node Quick startup guide,GNAT specifics,,Code Coverage of Ada Programs with gcov |
| @anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{21c}@anchor{gnat_ugn/gnat_and_program_execution quick-startup-guide}@anchor{21d} |
| @subsubsection Quick startup guide |
| |
| |
| In order to perform coverage analysis of a program using @cite{gcov}, several |
| steps are needed: |
| |
| |
| @enumerate |
| |
| @item |
| Instrument the code during the compilation process, |
| |
| @item |
| Execute the instrumented program, and |
| |
| @item |
| Invoke the @cite{gcov} tool to generate the coverage results. |
| @end enumerate |
| |
| @geindex -fprofile-arcs (gcc) |
| |
| @geindex -ftest-coverage (gcc |
| |
| @geindex -fprofile-arcs (gnatbind) |
| |
| The code instrumentation needed by gcov is created at the object level. |
| The source code is not modified in any way, because the instrumentation code is |
| inserted by gcc during the compilation process. To compile your code with code |
| coverage activated, you need to recompile your whole project using the |
| switches |
| @cite{-fprofile-arcs} and @cite{-ftest-coverage}, and link it using |
| @cite{-fprofile-arcs}. |
| |
| @quotation |
| |
| @example |
| $ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \\ |
| -largs -fprofile-arcs |
| @end example |
| @end quotation |
| |
| This compilation process will create @code{.gcno} files together with |
| the usual object files. |
| |
| Once the program is compiled with coverage instrumentation, you can |
| run it as many times as needed -- on portions of a test suite for |
| example. The first execution will produce @code{.gcda} files at the |
| same location as the @code{.gcno} files. Subsequent executions |
| will update those files, so that a cumulative result of the covered |
| portions of the program is generated. |
| |
| Finally, you need to call the @cite{gcov} tool. The different options of |
| @cite{gcov} are described in the GCC User's Guide, section 'Invoking gcov'. |
| |
| This will create annotated source files with a @code{.gcov} extension: |
| @code{my_main.adb} file will be analyzed in @code{my_main.adb.gcov}. |
| |
| @node GNAT specifics,,Quick startup guide,Code Coverage of Ada Programs with gcov |
| @anchor{gnat_ugn/gnat_and_program_execution gnat-specifics}@anchor{21e}@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{21f} |
| @subsubsection GNAT specifics |
| |
| |
| Because of Ada semantics, portions of the source code may be shared among |
| several object files. This is the case for example when generics are |
| involved, when inlining is active or when declarations generate initialisation |
| calls. In order to take |
| into account this shared code, you need to call @cite{gcov} on all |
| source files of the tested program at once. |
| |
| The list of source files might exceed the system's maximum command line |
| length. In order to bypass this limitation, a new mechanism has been |
| implemented in @cite{gcov}: you can now list all your project's files into a |
| text file, and provide this file to gcov as a parameter, preceded by a @code{@@} |
| (e.g. @code{gcov @@mysrclist.txt}). |
| |
| Note that on AIX compiling a static library with @cite{-fprofile-arcs} is |
| not supported as there can be unresolved symbols during the final link. |
| |
| @geindex gprof |
| |
| @geindex Profiling |
| |
| @node Profiling an Ada Program with gprof,,Code Coverage of Ada Programs with gcov,Code Coverage and Profiling |
| @anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{220}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{221} |
| @subsection Profiling an Ada Program with gprof |
| |
| |
| This section is not meant to be an exhaustive documentation of @cite{gprof}. |
| Full documentation for it can be found in the @cite{GNU Profiler User's Guide} |
| documentation that is part of this GNAT distribution. |
| |
| Profiling a program helps determine the parts of a program that are executed |
| most often, and are therefore the most time-consuming. |
| |
| @cite{gprof} is the standard GNU profiling tool; it has been enhanced to |
| better handle Ada programs and multitasking. |
| It is currently supported on the following platforms |
| |
| |
| @itemize * |
| |
| @item |
| linux x86/x86_64 |
| |
| @item |
| solaris sparc/sparc64/x86 |
| |
| @item |
| windows x86 |
| @end itemize |
| |
| In order to profile a program using @cite{gprof}, several steps are needed: |
| |
| |
| @enumerate |
| |
| @item |
| Instrument the code, which requires a full recompilation of the project with the |
| proper switches. |
| |
| @item |
| Execute the program under the analysis conditions, i.e. with the desired |
| input. |
| |
| @item |
| Analyze the results using the @cite{gprof} tool. |
| @end enumerate |
| |
| The following sections detail the different steps, and indicate how |
| to interpret the results. |
| |
| @menu |
| * Compilation for profiling:: |
| * Program execution:: |
| * Running gprof:: |
| * Interpretation of profiling results:: |
| |
| @end menu |
| |
| @node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof |
| @anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{222}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{223} |
| @subsubsection Compilation for profiling |
| |
| |
| @geindex -pg (gcc) |
| @geindex for profiling |
| |
| @geindex -pg (gnatlink) |
| @geindex for profiling |
| |
| In order to profile a program the first step is to tell the compiler |
| to generate the necessary profiling information. The compiler switch to be used |
| is @code{-pg}, which must be added to other compilation switches. This |
| switch needs to be specified both during compilation and link stages, and can |
| be specified once when using gnatmake: |
| |
| @quotation |
| |
| @example |
| $ gnatmake -f -pg -P my_project |
| @end example |
| @end quotation |
| |
| Note that only the objects that were compiled with the @code{-pg} switch will |
| be profiled; if you need to profile your whole project, use the @code{-f} |
| gnatmake switch to force full recompilation. |
| |
| @node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof |
| @anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{224}@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{225} |
| @subsubsection Program execution |
| |
| |
| Once the program has been compiled for profiling, you can run it as usual. |
| |
| The only constraint imposed by profiling is that the program must terminate |
| normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be |
| properly analyzed. |
| |
| Once the program completes execution, a data file called @code{gmon.out} is |
| generated in the directory where the program was launched from. If this file |
| already exists, it will be overwritten. |
| |
| @node Running gprof,Interpretation of profiling results,Program execution,Profiling an Ada Program with gprof |
| @anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{226}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{227} |
| @subsubsection Running gprof |
| |
| |
| The @cite{gprof} tool is called as follow: |
| |
| @quotation |
| |
| @example |
| $ gprof my_prog gmon.out |
| @end example |
| @end quotation |
| |
| or simply: |
| |
| @quotation |
| |
| @example |
| $ gprof my_prog |
| @end example |
| @end quotation |
| |
| The complete form of the gprof command line is the following: |
| |
| @quotation |
| |
| @example |
| $ gprof [switches] [executable [data-file]] |
| @end example |
| @end quotation |
| |
| @cite{gprof} supports numerous switches. The order of these |
| switch does not matter. The full list of options can be found in |
| the GNU Profiler User's Guide documentation that comes with this documentation. |
| |
| The following is the subset of those switches that is most relevant: |
| |
| @geindex --demangle (gprof) |
| |
| |
| @table @asis |
| |
| @item @code{--demangle[=@emph{style}]}, @code{--no-demangle} |
| |
| These options control whether symbol names should be demangled when |
| printing output. The default is to demangle C++ symbols. The |
| @code{--no-demangle} option may be used to turn off demangling. Different |
| compilers have different mangling styles. The optional demangling style |
| argument can be used to choose an appropriate demangling style for your |
| compiler, in particular Ada symbols generated by GNAT can be demangled using |
| @code{--demangle=gnat}. |
| @end table |
| |
| @geindex -e (gprof) |
| |
| |
| @table @asis |
| |
| @item @code{-e @emph{function_name}} |
| |
| The @code{-e @emph{function}} option tells @cite{gprof} not to print |
| information about the function @cite{function_name} (and its |
| children...) in the call graph. The function will still be listed |
| as a child of any functions that call it, but its index number will be |
| shown as @code{[not printed]}. More than one @code{-e} option may be |
| given; only one @cite{function_name} may be indicated with each @code{-e} |
| option. |
| @end table |
| |
| @geindex -E (gprof) |
| |
| |
| @table @asis |
| |
| @item @code{-E @emph{function_name}} |
| |
| The @code{-E @emph{function}} option works like the @code{-e} option, but |
| execution time spent in the function (and children who were not called from |
| anywhere else), will not be used to compute the percentages-of-time for |
| the call graph. More than one @code{-E} option may be given; only one |
| @cite{function_name} may be indicated with each @code{-E} option. |
| @end table |
| |
| @geindex -f (gprof) |
| |
| |
| @table @asis |
| |
| @item @code{-f @emph{function_name}} |
| |
| The @code{-f @emph{function}} option causes @cite{gprof} to limit the |
| call graph to the function @cite{function_name} and its children (and |
| their children...). More than one @code{-f} option may be given; |
| only one @cite{function_name} may be indicated with each @code{-f} |
| option. |
| @end table |
| |
| @geindex -F (gprof) |
| |
| |
| @table @asis |
| |
| @item @code{-F @emph{function_name}} |
| |
| The @code{-F @emph{function}} option works like the @code{-f} option, but |
| only time spent in the function and its children (and their |
| children...) will be used to determine total-time and |
| percentages-of-time for the call graph. More than one @code{-F} option |
| may be given; only one @cite{function_name} may be indicated with each |
| @code{-F} option. The @code{-F} option overrides the @code{-E} option. |
| @end table |
| |
| @node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof |
| @anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{228}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{229} |
| @subsubsection Interpretation of profiling results |
| |
| |
| The results of the profiling analysis are represented by two arrays: the |
| 'flat profile' and the 'call graph'. Full documentation of those outputs |
| can be found in the GNU Profiler User's Guide. |
| |
| The flat profile shows the time spent in each function of the program, and how |
| many time it has been called. This allows you to locate easily the most |
| time-consuming functions. |
| |
| The call graph shows, for each subprogram, the subprograms that call it, |
| and the subprograms that it calls. It also provides an estimate of the time |
| spent in each of those callers/called subprograms. |
| |
| @node Improving Performance,Overflow Check Handling in GNAT,Code Coverage and Profiling,GNAT and Program Execution |
| @anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{28}@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{1f5} |
| @section Improving Performance |
| |
| |
| @geindex Improving performance |
| |
| This section presents several topics related to program performance. |
| It first describes some of the tradeoffs that need to be considered |
| and some of the techniques for making your program run faster. |
| |
| |
| It then documents the unused subprogram/data elimination feature, |
| which can reduce the size of program executables. |
| |
| @menu |
| * Performance Considerations:: |
| * Text_IO Suggestions:: |
| * Reducing Size of Executables with Unused Subprogram/Data Elimination:: |
| |
| @end menu |
| |
| @node Performance Considerations,Text_IO Suggestions,,Improving Performance |
| @anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{22a}@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{22b} |
| @subsection Performance Considerations |
| |
| |
| The GNAT system provides a number of options that allow a trade-off |
| between |
| |
| |
| @itemize * |
| |
| @item |
| performance of the generated code |
| |
| @item |
| speed of compilation |
| |
| @item |
| minimization of dependences and recompilation |
| |
| @item |
| the degree of run-time checking. |
| @end itemize |
| |
| 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: |
| |
| |
| @itemize * |
| |
| @item |
| no optimization |
| |
| @item |
| no inlining of subprogram calls |
| |
| @item |
| all run-time checks enabled except overflow and elaboration checks |
| @end itemize |
| |
| These options are suitable for most program development purposes. This |
| section describes how you can modify these choices, and also provides |
| some guidelines on debugging optimized code. |
| |
| @menu |
| * Controlling Run-Time Checks:: |
| * Use of Restrictions:: |
| * Optimization Levels:: |
| * Debugging Optimized Code:: |
| * Inlining of Subprograms:: |
| * Floating_Point_Operations:: |
| * Vectorization of loops:: |
| * Other Optimization Switches:: |
| * Optimization and Strict Aliasing:: |
| * Aliased Variables and Optimization:: |
| * Atomic Variables and Optimization:: |
| * Passive Task Optimization:: |
| |
| @end menu |
| |
| @node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{22c}@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{22d} |
| @subsubsection Controlling Run-Time Checks |
| |
| |
| By default, GNAT generates all run-time checks, except stack overflow |
| checks, 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. |
| |
| @geindex -gnatp (gcc) |
| |
| @geindex -gnato (gcc) |
| |
| The gnat switch, @emph{-gnatp} allows this default to be modified. See |
| @ref{101,,Run-Time Checks}. |
| |
| Our experience is that the default is suitable for most development |
| purposes. |
| |
| 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 @emph{-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 @emph{-gnatVn}. Validity checks |
| are also suppressed entirely if @emph{-gnatp} is used. |
| |
| @geindex Overflow checks |
| |
| @geindex Checks |
| @geindex overflow |
| |
| @geindex Suppress |
| |
| @geindex Unsuppress |
| |
| @geindex pragma Suppress |
| |
| @geindex pragma Unsuppress |
| |
| Note that the setting of the switches controls the default setting of |
| the checks. They may be modified using either @cite{pragma Suppress} (to |
| remove checks) or @cite{pragma Unsuppress} (to add back suppressed |
| checks) in the program source. |
| |
| @node Use of Restrictions,Optimization Levels,Controlling Run-Time Checks,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{22e}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{22f} |
| @subsubsection Use of Restrictions |
| |
| |
| The use of pragma Restrictions allows you to control which features are |
| permitted in your program. Apart from the obvious point that if you avoid |
| relatively expensive features like finalization (enforceable by the use |
| of pragma Restrictions (No_Finalization), the use of this pragma does not |
| affect the generated code in most cases. |
| |
| One notable exception to this rule is that the possibility of task abort |
| results in some distributed overhead, particularly if finalization or |
| exception handlers are used. The reason is that certain sections of code |
| have to be marked as non-abortable. |
| |
| If you use neither the @cite{abort} statement, nor asynchronous transfer |
| of control (@cite{select ... then abort}), then this distributed overhead |
| is removed, which may have a general positive effect in improving |
| overall performance. Especially code involving frequent use of tasking |
| constructs and controlled types will show much improved performance. |
| The relevant restrictions pragmas are |
| |
| @quotation |
| |
| @example |
| pragma Restrictions (No_Abort_Statements); |
| pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); |
| @end example |
| @end quotation |
| |
| It is recommended that these restriction pragmas be used if possible. Note |
| that this also means that you can write code without worrying about the |
| possibility of an immediate abort at any point. |
| |
| @node Optimization Levels,Debugging Optimized Code,Use of Restrictions,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{230}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{104} |
| @subsubsection Optimization Levels |
| |
| |
| @geindex -O (gcc) |
| |
| Without any optimization option, |
| the compiler's goal is to reduce the cost of |
| compilation and to make debugging produce the expected results. |
| Statements are independent: if you stop the program with a breakpoint between |
| statements, you can then assign a new value to any variable or change |
| the program counter to any other statement in the subprogram and get exactly |
| the results you would expect from the source code. |
| |
| Turning on optimization makes the compiler attempt to improve the |
| performance and/or code size at the expense of compilation time and |
| possibly the ability to debug the program. |
| |
| If you use multiple |
| -O options, with or without level numbers, |
| the last such option is the one that is effective. |
| |
| 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 |
| @emph{-O} switch (the permitted forms are @emph{-O0}, @emph{-O1} |
| @emph{-O2}, @emph{-O3}, and @emph{-Os}) |
| to @emph{gcc} to control the optimization level: |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{-O0} |
| |
| No optimization (the default); |
| generates unoptimized code but has |
| the fastest compilation time. |
| |
| Note that many other compilers do fairly extensive optimization |
| even if 'no optimization' is specified. With gcc, it is |
| very unusual to use -O0 for production if |
| execution time is of any concern, since -O0 |
| really does mean no optimization at all. This difference between |
| gcc and other compilers should be kept in mind when doing |
| performance comparisons. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{-O1} |
| |
| Moderate optimization; |
| optimizes reasonably well but does not |
| degrade compilation time significantly. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{-O2} |
| |
| Full optimization; |
| generates highly optimized code and has |
| the slowest compilation time. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{-O3} |
| |
| Full optimization as in @emph{-O2}; |
| also uses more aggressive automatic inlining of subprograms within a unit |
| (@ref{117,,Inlining of Subprograms}) and attempts to vectorize loops. |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @emph{-Os} |
| |
| Optimize space usage (code and data) of resulting program. |
| @end table |
| @end itemize |
| |
| 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. |
| |
| Since the precise set of optimizations done at each level will vary from |
| release to release (and sometime from target to target), it is best to think |
| of the optimization settings in general terms. |
| See the @emph{Options That Control Optimization} section in |
| @cite{Using the GNU Compiler Collection (GCC)} |
| for details about |
| the @emph{-O} settings and a number of @emph{-f} options that |
| individually enable or disable specific optimizations. |
| |
| Unlike some other compilation systems, @emph{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 @emph{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 @emph{-O3}: The use of this optimization level |
| is generally discouraged with GNAT, since it often results in larger |
| executables which may run more slowly. See further discussion of this point |
| in @ref{117,,Inlining of Subprograms}. |
| |
| @node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{231}@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{232} |
| @subsubsection Debugging Optimized Code |
| |
| |
| @geindex Debugging optimized code |
| |
| @geindex Optimization and debugging |
| |
| Although it is possible to do a reasonable amount of debugging at |
| nonzero optimization levels, |
| the higher the level the more likely that |
| source-level constructs will have been eliminated by optimization. |
| For example, if a loop is strength-reduced, the loop |
| control variable may be completely eliminated and thus cannot be |
| displayed in the debugger. |
| This can only happen at @emph{-O2} or @emph{-O3}. |
| Explicit temporary variables that you code might be eliminated at |
| level @emph{-O1} or higher. |
| |
| @geindex -g (gcc) |
| |
| The use of the @emph{-g} switch, |
| which is needed for source-level debugging, |
| affects the size of the program executable on disk, |
| and indeed the debugging information can be quite large. |
| However, it has no effect on the generated code (and thus does not |
| degrade performance) |
| |
| 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. |
| These are the most common cases: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{The 'hopping Program Counter':} Repeated @cite{step} or @cite{next} |
| commands show |
| the PC bouncing back and forth in the code. This may result from any of |
| the following optimizations: |
| |
| |
| @itemize - |
| |
| @item |
| @emph{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. |
| |
| @item |
| @emph{Invariant code motion:} moving an expression that does not change within a |
| loop, to the beginning of the loop. |
| |
| @item |
| @emph{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. |
| @end itemize |
| |
| @item |
| @emph{The 'big leap':} More commonly known as @emph{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 @emph{was} supposed to be executed. This effect is typically seen in |
| sequences that end in a jump, such as a @cite{goto}, a @cite{return}, or |
| a @cite{break} in a C @cite{switch} statement. |
| |
| @item |
| @emph{The 'roving variable':} The symptom is an unexpected value in a variable. |
| There are various reasons for this effect: |
| |
| |
| @itemize - |
| |
| @item |
| In a subprogram prologue, a parameter may not yet have been moved to its |
| 'home'. |
| |
| @item |
| A variable may be dead, and its register re-used. This is |
| probably the most common cause. |
| |
| @item |
| As mentioned above, the assignment of a value to a variable may |
| have been moved. |
| |
| @item |
| A variable may be eliminated entirely by value propagation or |
| other means. In this case, GCC may incorrectly generate debugging |
| information for the variable |
| @end itemize |
| |
| 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 @emph{from} the point of the |
| strange value to see if code motion had simply moved the variable's |
| assignments later. |
| @end itemize |
| |
| In light of such anomalies, a recommended technique is to use @emph{-O0} |
| early in the software development cycle, when extensive debugging capabilities |
| are most needed, and then move to @emph{-O1} and later @emph{-O2} as |
| the debugger becomes less critical. |
| Whether to use the @emph{-g} switch in the release version is |
| a release management issue. |
| Note that if you use @emph{-g} you can then use the @emph{strip} program |
| on the resulting executable, |
| which removes both debugging information and global symbols. |
| |
| @node Inlining of Subprograms,Floating_Point_Operations,Debugging Optimized Code,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{233}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{117} |
| @subsubsection Inlining of Subprograms |
| |
| |
| A call to a subprogram in the current unit is inlined if all the |
| following conditions are met: |
| |
| |
| @itemize * |
| |
| @item |
| The optimization level is at least @emph{-O1}. |
| |
| @item |
| The called subprogram is suitable for inlining: It must be small enough |
| and not contain something that @emph{gcc} cannot support in inlined |
| subprograms. |
| |
| @geindex pragma Inline |
| |
| @geindex Inline |
| |
| @item |
| Any one of the following applies: @cite{pragma Inline} is applied to the |
| subprogram and the @emph{-gnatn} switch is specified; the |
| subprogram is local to the unit and called once from within it; the |
| subprogram is small and optimization level @emph{-O2} is specified; |
| optimization level @emph{-O3} is specified. |
| @end itemize |
| |
| Calls to subprograms in @emph{with}ed units are normally not inlined. |
| To achieve actual inlining (that is, replacement of the call by the code |
| in the body of the subprogram), the following conditions must all be true: |
| |
| |
| @itemize * |
| |
| @item |
| The optimization level is at least @emph{-O1}. |
| |
| @item |
| The called subprogram is suitable for inlining: It must be small enough |
| and not contain something that @emph{gcc} cannot support in inlined |
| subprograms. |
| |
| @item |
| The call appears in a body (not in a package spec). |
| |
| @item |
| There is a @cite{pragma Inline} for the subprogram. |
| |
| @item |
| The @emph{-gnatn} switch is used on the command line. |
| @end itemize |
| |
| Even if all these conditions are met, it may not be possible for |
| the compiler to inline the call, due to the length of the body, |
| or features in the body that make it impossible for the compiler |
| to do the inlining. |
| |
| Note that specifying the @emph{-gnatn} switch causes additional |
| compilation dependencies. Consider the following: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| With the default behavior (no @emph{-gnatn} switch specified), the |
| compilation of the @cite{Main} procedure depends only on its own source, |
| @code{main.adb}, and the spec of the package in file @code{r.ads}. This |
| means that editing the body of @cite{R} does not require recompiling |
| @cite{Main}. |
| |
| On the other hand, the call @cite{R.Q} is not inlined under these |
| circumstances. If the @emph{-gnatn} switch is present when @cite{Main} |
| is compiled, the call will be inlined if the body of @cite{Q} is small |
| enough, but now @cite{Main} depends on the body of @cite{R} in |
| @code{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 @emph{gcc}. |
| |
| The use of front end inlining with @emph{-gnatN} generates similar |
| additional dependencies. |
| |
| @geindex -fno-inline (gcc) |
| |
| Note: The @emph{-fno-inline} switch overrides all other conditions and ensures that |
| no inlining occurs, unless requested with pragma Inline_Always for gcc |
| back-ends. The extra dependences resulting from @emph{-gnatn} will still be active, |
| even if this switch is used to suppress the resulting inlining actions. |
| |
| @geindex -fno-inline-functions (gcc) |
| |
| Note: The @emph{-fno-inline-functions} switch can be used to prevent |
| automatic inlining of subprograms if @emph{-O3} is used. |
| |
| @geindex -fno-inline-small-functions (gcc) |
| |
| Note: The @emph{-fno-inline-small-functions} switch can be used to prevent |
| automatic inlining of small subprograms if @emph{-O2} is used. |
| |
| @geindex -fno-inline-functions-called-once (gcc) |
| |
| Note: The @emph{-fno-inline-functions-called-once} switch |
| can be used to prevent inlining of subprograms local to the unit |
| and called once from within it if @emph{-O1} is used. |
| |
| Note regarding the use of @emph{-O3}: @emph{-gnatn} is made up of two |
| sub-switches @emph{-gnatn1} and @emph{-gnatn2} that can be directly |
| specified in lieu of it, @emph{-gnatn} being translated into one of them |
| based on the optimization level. With @emph{-O2} or below, @emph{-gnatn} |
| is equivalent to @emph{-gnatn1} which activates pragma @cite{Inline} with |
| moderate inlining across modules. With @emph{-O3}, @emph{-gnatn} is |
| equivalent to @emph{-gnatn2} which activates pragma @cite{Inline} with |
| full inlining across modules. If you have used pragma @cite{Inline} in |
| appropriate cases, then it is usually much better to use @emph{-O2} |
| and @emph{-gnatn} and avoid the use of @emph{-O3} which has the additional |
| effect of inlining subprograms you did not think should be inlined. We have |
| found that the use of @emph{-O3} may slow down the compilation and increase |
| the code size by performing excessive inlining, leading to increased |
| instruction cache pressure from the increased code size and thus minor |
| performance improvements. So the bottom line here is that you should not |
| automatically assume that @emph{-O3} is better than @emph{-O2}, and |
| indeed you should use @emph{-O3} only if tests show that it actually |
| improves performance for your program. |
| |
| @node Floating_Point_Operations,Vectorization of loops,Inlining of Subprograms,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{234}@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{235} |
| @subsubsection Floating_Point_Operations |
| |
| |
| @geindex Floating-Point Operations |
| |
| On almost all targets, GNAT maps Float and Long_Float to the 32-bit and |
| 64-bit standard IEEE floating-point representations, and operations will |
| use standard IEEE arithmetic as provided by the processor. On most, but |
| not all, architectures, the attribute Machine_Overflows is False for these |
| types, meaning that the semantics of overflow is implementation-defined. |
| In the case of GNAT, these semantics correspond to the normal IEEE |
| treatment of infinities and NaN (not a number) values. For example, |
| 1.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By |
| avoiding explicit overflow checks, the performance is greatly improved |
| on many targets. However, if required, floating-point overflow can be |
| enabled by the use of the pragma Check_Float_Overflow. |
| |
| Another consideration that applies specifically to x86 32-bit |
| architectures is which form of floating-point arithmetic is used. |
| By default the operations use the old style x86 floating-point, |
| which implements an 80-bit extended precision form (on these |
| architectures the type Long_Long_Float corresponds to that form). |
| In addition, generation of efficient code in this mode means that |
| the extended precision form will be used for intermediate results. |
| This may be helpful in improving the final precision of a complex |
| expression. However it means that the results obtained on the x86 |
| will be different from those on other architectures, and for some |
| algorithms, the extra intermediate precision can be detrimental. |
| |
| In addition to this old-style floating-point, all modern x86 chips |
| implement an alternative floating-point operation model referred |
| to as SSE2. In this model there is no extended form, and furthermore |
| execution performance is significantly enhanced. To force GNAT to use |
| this more modern form, use both of the switches: |
| |
| @quotation |
| |
| -msse2 -mfpmath=sse |
| @end quotation |
| |
| A unit compiled with these switches will automatically use the more |
| efficient SSE2 instruction set for Float and Long_Float operations. |
| Note that the ABI has the same form for both floating-point models, |
| so it is permissible to mix units compiled with and without these |
| switches. |
| |
| @node Vectorization of loops,Other Optimization Switches,Floating_Point_Operations,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{236}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{237} |
| @subsubsection Vectorization of loops |
| |
| |
| @geindex Optimization Switches |
| |
| You can take advantage of the auto-vectorizer present in the @emph{gcc} |
| back end to vectorize loops with GNAT. The corresponding command line switch |
| is @emph{-ftree-vectorize} but, as it is enabled by default at @emph{-O3} |
| and other aggressive optimizations helpful for vectorization also are enabled |
| by default at this level, using @emph{-O3} directly is recommended. |
| |
| You also need to make sure that the target architecture features a supported |
| SIMD instruction set. For example, for the x86 architecture, you should at |
| least specify @emph{-msse2} to get significant vectorization (but you don't |
| need to specify it for x86-64 as it is part of the base 64-bit architecture). |
| Similarly, for the PowerPC architecture, you should specify @emph{-maltivec}. |
| |
| The preferred loop form for vectorization is the @cite{for} iteration scheme. |
| Loops with a @cite{while} iteration scheme can also be vectorized if they are |
| very simple, but the vectorizer will quickly give up otherwise. With either |
| iteration scheme, the flow of control must be straight, in particular no |
| @cite{exit} statement may appear in the loop body. The loop may however |
| contain a single nested loop, if it can be vectorized when considered alone: |
| |
| @quotation |
| |
| @example |
| A : array (1..4, 1..4) of Long_Float; |
| S : array (1..4) of Long_Float; |
| |
| procedure Sum is |
| begin |
| for I in A'Range(1) loop |
| for J in A'Range(2) loop |
| S (I) := S (I) + A (I, J); |
| end loop; |
| end loop; |
| end Sum; |
| @end example |
| @end quotation |
| |
| The vectorizable operations depend on the targeted SIMD instruction set, but |
| the adding and some of the multiplying operators are generally supported, as |
| well as the logical operators for modular types. Note that compiling |
| with @emph{-gnatp} might well reveal cases where some checks do thwart |
| vectorization. |
| |
| Type conversions may also prevent vectorization if they involve semantics that |
| are not directly supported by the code generator or the SIMD instruction set. |
| A typical example is direct conversion from floating-point to integer types. |
| The solution in this case is to use the following idiom: |
| |
| @quotation |
| |
| @example |
| Integer (S'Truncation (F)) |
| @end example |
| @end quotation |
| |
| if @cite{S} is the subtype of floating-point object @cite{F}. |
| |
| In most cases, the vectorizable loops are loops that iterate over arrays. |
| All kinds of array types are supported, i.e. constrained array types with |
| static bounds: |
| |
| @quotation |
| |
| @example |
| type Array_Type is array (1 .. 4) of Long_Float; |
| @end example |
| @end quotation |
| |
| constrained array types with dynamic bounds: |
| |
| @quotation |
| |
| @example |
| type Array_Type is array (1 .. Q.N) of Long_Float; |
| |
| type Array_Type is array (Q.K .. 4) of Long_Float; |
| |
| type Array_Type is array (Q.K .. Q.N) of Long_Float; |
| @end example |
| @end quotation |
| |
| or unconstrained array types: |
| |
| @quotation |
| |
| @example |
| type Array_Type is array (Positive range <>) of Long_Float; |
| @end example |
| @end quotation |
| |
| The quality of the generated code decreases when the dynamic aspect of the |
| array type increases, the worst code being generated for unconstrained array |
| types. This is so because, the less information the compiler has about the |
| bounds of the array, the more fallback code it needs to generate in order to |
| fix things up at run time. |
| |
| It is possible to specify that a given loop should be subject to vectorization |
| preferably to other optimizations by means of pragma @cite{Loop_Optimize}: |
| |
| @quotation |
| |
| @example |
| pragma Loop_Optimize (Vector); |
| @end example |
| @end quotation |
| |
| placed immediately within the loop will convey the appropriate hint to the |
| compiler for this loop. |
| |
| It is also possible to help the compiler generate better vectorized code |
| for a given loop by asserting that there are no loop-carried dependencies |
| in the loop. Consider for example the procedure: |
| |
| @quotation |
| |
| @example |
| type Arr is array (1 .. 4) of Long_Float; |
| |
| procedure Add (X, Y : not null access Arr; R : not null access Arr) is |
| begin |
| for I in Arr'Range loop |
| R(I) := X(I) + Y(I); |
| end loop; |
| end; |
| @end example |
| @end quotation |
| |
| By default, the compiler cannot unconditionally vectorize the loop because |
| assigning to a component of the array designated by R in one iteration could |
| change the value read from the components of the array designated by X or Y |
| in a later iteration. As a result, the compiler will generate two versions |
| of the loop in the object code, one vectorized and the other not vectorized, |
| as well as a test to select the appropriate version at run time. This can |
| be overcome by another hint: |
| |
| @quotation |
| |
| @example |
| pragma Loop_Optimize (Ivdep); |
| @end example |
| @end quotation |
| |
| placed immediately within the loop will tell the compiler that it can safely |
| omit the non-vectorized version of the loop as well as the run-time test. |
| |
| @node Other Optimization Switches,Optimization and Strict Aliasing,Vectorization of loops,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{238}@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{239} |
| @subsubsection Other Optimization Switches |
| |
| |
| @geindex Optimization Switches |
| |
| Since @cite{GNAT} uses the @emph{gcc} back end, all the specialized |
| @emph{gcc} optimization switches are potentially usable. These switches |
| have not been extensively tested with GNAT but can generally be expected |
| to work. Examples of switches in this category are @emph{-funroll-loops} |
| and the various target-specific @emph{-m} options (in particular, it has |
| been observed that @emph{-march=xxx} can significantly improve performance |
| on appropriate machines). For full details of these switches, see |
| the @cite{Submodel Options} section in the @cite{Hardware Models and Configurations} |
| chapter of @cite{Using the GNU Compiler Collection (GCC)}. |
| |
| @node Optimization and Strict Aliasing,Aliased Variables and Optimization,Other Optimization Switches,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{fb}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{23a} |
| @subsubsection Optimization and Strict Aliasing |
| |
| |
| @geindex Aliasing |
| |
| @geindex Strict Aliasing |
| |
| @geindex No_Strict_Aliasing |
| |
| The strong typing capabilities of Ada allow an optimizer to generate |
| efficient code in situations where other languages would be forced to |
| make worst case assumptions preventing such optimizations. Consider |
| the following example: |
| |
| @quotation |
| |
| @example |
| procedure R is |
| type Int1 is new Integer; |
| type Int2 is new Integer; |
| type Int1A is access Int1; |
| type Int2A is access Int2; |
| Int1V : Int1A; |
| Int2V : Int2A; |
| ... |
| |
| begin |
| ... |
| for J in Data'Range loop |
| if Data (J) = Int1V.all then |
| Int2V.all := Int2V.all + 1; |
| end if; |
| end loop; |
| ... |
| end R; |
| @end example |
| @end quotation |
| |
| In this example, since the variable @cite{Int1V} can only access objects |
| of type @cite{Int1}, and @cite{Int2V} can only access objects of type |
| @cite{Int2}, there is no possibility that the assignment to |
| @cite{Int2V.all} affects the value of @cite{Int1V.all}. This means that |
| the compiler optimizer can "know" that the value @cite{Int1V.all} is constant |
| for all iterations of the loop and avoid the extra memory reference |
| required to dereference it each time through the loop. |
| |
| This kind of optimization, called strict aliasing analysis, is |
| triggered by specifying an optimization level of @emph{-O2} or |
| higher or @emph{-Os} and allows @cite{GNAT} to generate more efficient code |
| when access values are involved. |
| |
| However, although this optimization is always correct in terms of |
| the formal semantics of the Ada Reference Manual, difficulties can |
| arise if features like @cite{Unchecked_Conversion} are used to break |
| the typing system. Consider the following complete program example: |
| |
| @quotation |
| |
| @example |
| package p1 is |
| type int1 is new integer; |
| type int2 is new integer; |
| type a1 is access int1; |
| type a2 is access int2; |
| end p1; |
| |
| with p1; use p1; |
| package p2 is |
| function to_a2 (Input : a1) return a2; |
| end p2; |
| |
| with Unchecked_Conversion; |
| package body p2 is |
| function to_a2 (Input : a1) return a2 is |
| function to_a2u is |
| new Unchecked_Conversion (a1, a2); |
| begin |
| return to_a2u (Input); |
| end to_a2; |
| end p2; |
| |
| with p2; use p2; |
| with p1; use p1; |
| with Text_IO; use Text_IO; |
| procedure m is |
| v1 : a1 := new int1; |
| v2 : a2 := to_a2 (v1); |
| begin |
| v1.all := 1; |
| v2.all := 0; |
| put_line (int1'image (v1.all)); |
| end; |
| @end example |
| @end quotation |
| |
| This program prints out 0 in @emph{-O0} or @emph{-O1} |
| mode, but it prints out 1 in @emph{-O2} mode. That's |
| because in strict aliasing mode, the compiler can and |
| does assume that the assignment to @cite{v2.all} could not |
| affect the value of @cite{v1.all}, since different types |
| are involved. |
| |
| This behavior is not a case of non-conformance with the standard, since |
| the Ada RM specifies that an unchecked conversion where the resulting |
| bit pattern is not a correct value of the target type can result in an |
| abnormal value and attempting to reference an abnormal value makes the |
| execution of a program erroneous. That's the case here since the result |
| does not point to an object of type @cite{int2}. This means that the |
| effect is entirely unpredictable. |
| |
| However, although that explanation may satisfy a language |
| lawyer, in practice an applications programmer expects an |
| unchecked conversion involving pointers to create true |
| aliases and the behavior of printing 1 seems plain wrong. |
| In this case, the strict aliasing optimization is unwelcome. |
| |
| Indeed the compiler recognizes this possibility, and the |
| unchecked conversion generates a warning: |
| |
| @quotation |
| |
| @example |
| p2.adb:5:07: warning: possible aliasing problem with type "a2" |
| p2.adb:5:07: warning: use -fno-strict-aliasing switch for references |
| p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);" |
| @end example |
| @end quotation |
| |
| Unfortunately the problem is recognized when compiling the body of |
| package @cite{p2}, but the actual "bad" code is generated while |
| compiling the body of @cite{m} and this latter compilation does not see |
| the suspicious @cite{Unchecked_Conversion}. |
| |
| As implied by the warning message, there are approaches you can use to |
| avoid the unwanted strict aliasing optimization in a case like this. |
| |
| One possibility is to simply avoid the use of @emph{-O2}, but |
| that is a bit drastic, since it throws away a number of useful |
| optimizations that do not involve strict aliasing assumptions. |
| |
| A less drastic approach is to compile the program using the |
| option @emph{-fno-strict-aliasing}. Actually it is only the |
| unit containing the dereferencing of the suspicious pointer |
| that needs to be compiled. So in this case, if we compile |
| unit @cite{m} with this switch, then we get the expected |
| value of zero printed. Analyzing which units might need |
| the switch can be painful, so a more reasonable approach |
| is to compile the entire program with options @emph{-O2} |
| and @emph{-fno-strict-aliasing}. If the performance is |
| satisfactory with this combination of options, then the |
| advantage is that the entire issue of possible "wrong" |
| optimization due to strict aliasing is avoided. |
| |
| To avoid the use of compiler switches, the configuration |
| pragma @cite{No_Strict_Aliasing} with no parameters may be |
| used to specify that for all access types, the strict |
| aliasing optimization should be suppressed. |
| |
| However, these approaches are still overkill, in that they causes |
| all manipulations of all access values to be deoptimized. A more |
| refined approach is to concentrate attention on the specific |
| access type identified as problematic. |
| |
| First, if a careful analysis of uses of the pointer shows |
| that there are no possible problematic references, then |
| the warning can be suppressed by bracketing the |
| instantiation of @cite{Unchecked_Conversion} to turn |
| the warning off: |
| |
| @quotation |
| |
| @example |
| pragma Warnings (Off); |
| function to_a2u is |
| new Unchecked_Conversion (a1, a2); |
| pragma Warnings (On); |
| @end example |
| @end quotation |
| |
| Of course that approach is not appropriate for this particular |
| example, since indeed there is a problematic reference. In this |
| case we can take one of two other approaches. |
| |
| The first possibility is to move the instantiation of unchecked |
| conversion to the unit in which the type is declared. In |
| this example, we would move the instantiation of |
| @cite{Unchecked_Conversion} from the body of package |
| @cite{p2} to the spec of package @cite{p1}. Now the |
| warning disappears. That's because any use of the |
| access type knows there is a suspicious unchecked |
| conversion, and the strict aliasing optimization |
| is automatically suppressed for the type. |
| |
| If it is not practical to move the unchecked conversion to the same unit |
| in which the destination access type is declared (perhaps because the |
| source type is not visible in that unit), you may use pragma |
| @cite{No_Strict_Aliasing} for the type. This pragma must occur in the |
| same declarative sequence as the declaration of the access type: |
| |
| @quotation |
| |
| @example |
| type a2 is access int2; |
| pragma No_Strict_Aliasing (a2); |
| @end example |
| @end quotation |
| |
| Here again, the compiler now knows that the strict aliasing optimization |
| should be suppressed for any reference to type @cite{a2} and the |
| expected behavior is obtained. |
| |
| Finally, note that although the compiler can generate warnings for |
| simple cases of unchecked conversions, there are tricker and more |
| indirect ways of creating type incorrect aliases which the compiler |
| cannot detect. Examples are the use of address overlays and unchecked |
| conversions involving composite types containing access types as |
| components. In such cases, no warnings are generated, but there can |
| still be aliasing problems. One safe coding practice is to forbid the |
| use of address clauses for type overlaying, and to allow unchecked |
| conversion only for primitive types. This is not really a significant |
| restriction since any possible desired effect can be achieved by |
| unchecked conversion of access values. |
| |
| The aliasing analysis done in strict aliasing mode can certainly |
| have significant benefits. We have seen cases of large scale |
| application code where the time is increased by up to 5% by turning |
| this optimization off. If you have code that includes significant |
| usage of unchecked conversion, you might want to just stick with |
| @emph{-O1} and avoid the entire issue. If you get adequate |
| performance at this level of optimization level, that's probably |
| the safest approach. If tests show that you really need higher |
| levels of optimization, then you can experiment with @emph{-O2} |
| and @emph{-O2 -fno-strict-aliasing} to see how much effect this |
| has on size and speed of the code. If you really need to use |
| @emph{-O2} with strict aliasing in effect, then you should |
| review any uses of unchecked conversion of access types, |
| particularly if you are getting the warnings described above. |
| |
| @node Aliased Variables and Optimization,Atomic Variables and Optimization,Optimization and Strict Aliasing,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{23b}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{23c} |
| @subsubsection Aliased Variables and Optimization |
| |
| |
| @geindex Aliasing |
| |
| There are scenarios in which programs may |
| use low level techniques to modify variables |
| that otherwise might be considered to be unassigned. For example, |
| a variable can be passed to a procedure by reference, which takes |
| the address of the parameter and uses the address to modify the |
| variable's value, even though it is passed as an IN parameter. |
| Consider the following example: |
| |
| @quotation |
| |
| @example |
| procedure P is |
| Max_Length : constant Natural := 16; |
| type Char_Ptr is access all Character; |
| |
| procedure Get_String(Buffer: Char_Ptr; Size : Integer); |
| pragma Import (C, Get_String, "get_string"); |
| |
| Name : aliased String (1 .. Max_Length) := (others => ' '); |
| Temp : Char_Ptr; |
| |
| function Addr (S : String) return Char_Ptr is |
| function To_Char_Ptr is |
| new Ada.Unchecked_Conversion (System.Address, Char_Ptr); |
| begin |
| return To_Char_Ptr (S (S'First)'Address); |
| end; |
| |
| begin |
| Temp := Addr (Name); |
| Get_String (Temp, Max_Length); |
| end; |
| @end example |
| @end quotation |
| |
| where Get_String is a C function that uses the address in Temp to |
| modify the variable @cite{Name}. This code is dubious, and arguably |
| erroneous, and the compiler would be entitled to assume that |
| @cite{Name} is never modified, and generate code accordingly. |
| |
| However, in practice, this would cause some existing code that |
| seems to work with no optimization to start failing at high |
| levels of optimzization. |
| |
| What the compiler does for such cases is to assume that marking |
| a variable as aliased indicates that some "funny business" may |
| be going on. The optimizer recognizes the aliased keyword and |
| inhibits optimizations that assume the value cannot be assigned. |
| This means that the above example will in fact "work" reliably, |
| that is, it will produce the expected results. |
| |
| @node Atomic Variables and Optimization,Passive Task Optimization,Aliased Variables and Optimization,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{23d}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{23e} |
| @subsubsection Atomic Variables and Optimization |
| |
| |
| @geindex Atomic |
| |
| There are two considerations with regard to performance when |
| atomic variables are used. |
| |
| First, the RM only guarantees that access to atomic variables |
| be atomic, it has nothing to say about how this is achieved, |
| though there is a strong implication that this should not be |
| achieved by explicit locking code. Indeed GNAT will never |
| generate any locking code for atomic variable access (it will |
| simply reject any attempt to make a variable or type atomic |
| if the atomic access cannot be achieved without such locking code). |
| |
| That being said, it is important to understand that you cannot |
| assume that the entire variable will always be accessed. Consider |
| this example: |
| |
| @quotation |
| |
| @example |
| type R is record |
| A,B,C,D : Character; |
| end record; |
| for R'Size use 32; |
| for R'Alignment use 4; |
| |
| RV : R; |
| pragma Atomic (RV); |
| X : Character; |
| ... |
| X := RV.B; |
| @end example |
| @end quotation |
| |
| You cannot assume that the reference to @cite{RV.B} |
| will read the entire 32-bit |
| variable with a single load instruction. It is perfectly legitimate if |
| the hardware allows it to do a byte read of just the B field. This read |
| is still atomic, which is all the RM requires. GNAT can and does take |
| advantage of this, depending on the architecture and optimization level. |
| Any assumption to the contrary is non-portable and risky. Even if you |
| examine the assembly language and see a full 32-bit load, this might |
| change in a future version of the compiler. |
| |
| If your application requires that all accesses to @cite{RV} in this |
| example be full 32-bit loads, you need to make a copy for the access |
| as in: |
| |
| @quotation |
| |
| @example |
| declare |
| RV_Copy : constant R := RV; |
| begin |
| X := RV_Copy.B; |
| end; |
| @end example |
| @end quotation |
| |
| Now the reference to RV must read the whole variable. |
| Actually one can imagine some compiler which figures |
| out that the whole copy is not required (because only |
| the B field is actually accessed), but GNAT |
| certainly won't do that, and we don't know of any |
| compiler that would not handle this right, and the |
| above code will in practice work portably across |
| all architectures (that permit the Atomic declaration). |
| |
| The second issue with atomic variables has to do with |
| the possible requirement of generating synchronization |
| code. For more details on this, consult the sections on |
| the pragmas Enable/Disable_Atomic_Synchronization in the |
| GNAT Reference Manual. If performance is critical, and |
| such synchronization code is not required, it may be |
| useful to disable it. |
| |
| @node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations |
| @anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{23f}@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{240} |
| @subsubsection Passive Task Optimization |
| |
| |
| @geindex Passive Task |
| |
| A passive task is one which is sufficiently simple that |
| in theory a compiler could recognize it an implement it |
| efficiently without creating a new thread. The original design |
| of Ada 83 had in mind this kind of passive task optimization, but |
| only a few Ada 83 compilers attempted it. The problem was that |
| it was difficult to determine the exact conditions under which |
| the optimization was possible. The result is a very fragile |
| optimization where a very minor change in the program can |
| suddenly silently make a task non-optimizable. |
| |
| With the revisiting of this issue in Ada 95, there was general |
| agreement that this approach was fundamentally flawed, and the |
| notion of protected types was introduced. When using protected |
| types, the restrictions are well defined, and you KNOW that the |
| operations will be optimized, and furthermore this optimized |
| performance is fully portable. |
| |
| Although it would theoretically be possible for GNAT to attempt to |
| do this optimization, but it really doesn't make sense in the |
| context of Ada 95, and none of the Ada 95 compilers implement |
| this optimization as far as we know. In particular GNAT never |
| attempts to perform this optimization. |
| |
| In any new Ada 95 code that is written, you should always |
| use protected types in place of tasks that might be able to |
| be optimized in this manner. |
| Of course this does not help if you have legacy Ada 83 code |
| that depends on this optimization, but it is unusual to encounter |
| a case where the performance gains from this optimization |
| are significant. |
| |
| Your program should work correctly without this optimization. If |
| you have performance problems, then the most practical |
| approach is to figure out exactly where these performance problems |
| arise, and update those particular tasks to be protected types. Note |
| that typically clients of the tasks who call entries, will not have |
| to be modified, only the task definition itself. |
| |
| @node Text_IO Suggestions,Reducing Size of Executables with Unused Subprogram/Data Elimination,Performance Considerations,Improving Performance |
| @anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{241}@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{242} |
| @subsection @cite{Text_IO} Suggestions |
| |
| |
| @geindex Text_IO and performance |
| |
| The @cite{Ada.Text_IO} package has fairly high overheads due in part to |
| the requirement of maintaining page and line counts. If performance |
| is critical, a recommendation is to use @cite{Stream_IO} instead of |
| @cite{Text_IO} for volume output, since this package has less overhead. |
| |
| If @cite{Text_IO} must be used, note that by default output to the standard |
| output and standard error files is unbuffered (this provides better |
| behavior when output statements are used for debugging, or if the |
| progress of a program is observed by tracking the output, e.g. by |
| using the Unix @emph{tail -f} command to watch redirected output. |
| |
| If you are generating large volumes of output with @cite{Text_IO} and |
| performance is an important factor, use a designated file instead |
| of the standard output file, or change the standard output file to |
| be buffered using @cite{Interfaces.C_Streams.setvbuf}. |
| |
| @node Reducing Size of Executables with Unused Subprogram/Data Elimination,,Text_IO Suggestions,Improving Performance |
| @anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{243}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{244} |
| @subsection Reducing Size of Executables with Unused Subprogram/Data Elimination |
| |
| |
| @geindex Uunused subprogram/data elimination |
| |
| This section describes how you can eliminate unused subprograms and data from |
| your executable just by setting options at compilation time. |
| |
| @menu |
| * About unused subprogram/data elimination:: |
| * Compilation options:: |
| * Example of unused subprogram/data elimination:: |
| |
| @end menu |
| |
| @node About unused subprogram/data elimination,Compilation options,,Reducing Size of Executables with Unused Subprogram/Data Elimination |
| @anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{245}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{246} |
| @subsubsection About unused subprogram/data elimination |
| |
| |
| By default, an executable contains all code and data of its composing objects |
| (directly linked or coming from statically linked libraries), even data or code |
| never used by this executable. |
| |
| This feature will allow you to eliminate such unused code from your |
| executable, making it smaller (in disk and in memory). |
| |
| This functionality is available on all Linux platforms except for the IA-64 |
| architecture and on all cross platforms using the ELF binary file format. |
| In both cases GNU binutils version 2.16 or later are required to enable it. |
| |
| @node Compilation options,Example of unused subprogram/data elimination,About unused subprogram/data elimination,Reducing Size of Executables with Unused Subprogram/Data Elimination |
| @anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{247}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{248} |
| @subsubsection Compilation options |
| |
| |
| The operation of eliminating the unused code and data from the final executable |
| is directly performed by the linker. |
| |
| @geindex -ffunction-sections (gcc) |
| |
| @geindex -fdata-sections (gcc) |
| |
| In order to do this, it has to work with objects compiled with the |
| following options: |
| @emph{-ffunction-sections} @emph{-fdata-sections}. |
| |
| These options are usable with C and Ada files. |
| They will place respectively each |
| function or data in a separate section in the resulting object file. |
| |
| Once the objects and static libraries are created with these options, the |
| linker can perform the dead code elimination. You can do this by setting |
| the @emph{-Wl,--gc-sections} option to gcc command or in the |
| @emph{-largs} section of @emph{gnatmake}. This will perform a |
| garbage collection of code and data never referenced. |
| |
| If the linker performs a partial link (@emph{-r} linker option), then you |
| will need to provide the entry point using the @emph{-e} / @emph{--entry} |
| linker option. |
| |
| Note that objects compiled without the @emph{-ffunction-sections} and |
| @emph{-fdata-sections} options can still be linked with the executable. |
| However, no dead code elimination will be performed on those objects (they will |
| be linked as is). |
| |
| The GNAT static library is now compiled with -ffunction-sections and |
| -fdata-sections on some platforms. This allows you to eliminate the unused code |
| and data of the GNAT library from your executable. |
| |
| @node Example of unused subprogram/data elimination,,Compilation options,Reducing Size of Executables with Unused Subprogram/Data Elimination |
| @anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{249}@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{24a} |
| @subsubsection Example of unused subprogram/data elimination |
| |
| |
| Here is a simple example: |
| |
| @quotation |
| |
| @example |
| with Aux; |
| |
| procedure Test is |
| begin |
| Aux.Used (10); |
| end Test; |
| |
| package Aux is |
| Used_Data : Integer; |
| Unused_Data : Integer; |
| |
| procedure Used (Data : Integer); |
| procedure Unused (Data : Integer); |
| end Aux; |
| |
| package body Aux is |
| procedure Used (Data : Integer) is |
| begin |
| Used_Data := Data; |
| end Used; |
| |
| procedure Unused (Data : Integer) is |
| begin |
| Unused_Data := Data; |
| end Unused; |
| end Aux; |
| @end example |
| @end quotation |
| |
| @cite{Unused} and @cite{Unused_Data} are never referenced in this code |
| excerpt, and hence they may be safely removed from the final executable. |
| |
| @quotation |
| |
| @example |
| $ gnatmake test |
| |
| $ nm test | grep used |
| 020015f0 T aux__unused |
| 02005d88 B aux__unused_data |
| 020015cc T aux__used |
| 02005d84 B aux__used_data |
| |
| $ gnatmake test -cargs -fdata-sections -ffunction-sections \\ |
| -largs -Wl,--gc-sections |
| |
| $ nm test | grep used |
| 02005350 T aux__used |
| 0201ffe0 B aux__used_data |
| @end example |
| @end quotation |
| |
| It can be observed that the procedure @cite{Unused} and the object |
| @cite{Unused_Data} are removed by the linker when using the |
| appropriate options. |
| |
| @geindex Overflow checks |
| |
| @geindex Checks (overflow) |
| |
| |
| @node Overflow Check Handling in GNAT,Performing Dimensionality Analysis in GNAT,Improving Performance,GNAT and Program Execution |
| @anchor{gnat_ugn/gnat_and_program_execution id54}@anchor{1f6}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{29} |
| @section Overflow Check Handling in GNAT |
| |
| |
| This section explains how to control the handling of overflow checks. |
| |
| @menu |
| * Background:: |
| * Management of Overflows in GNAT:: |
| * Specifying the Desired Mode:: |
| * Default Settings:: |
| * Implementation Notes:: |
| |
| @end menu |
| |
| @node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT |
| @anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{24b}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{24c} |
| @subsection Background |
| |
| |
| Overflow checks are checks that the compiler may make to ensure |
| that intermediate results are not out of range. For example: |
| |
| @quotation |
| |
| @example |
| A : Integer; |
| ... |
| A := A + 1; |
| @end example |
| @end quotation |
| |
| If @cite{A} has the value @cite{Integer'Last}, then the addition may cause |
| overflow since the result is out of range of the type @cite{Integer}. |
| In this case @cite{Constraint_Error} will be raised if checks are |
| enabled. |
| |
| A trickier situation arises in examples like the following: |
| |
| @quotation |
| |
| @example |
| A, C : Integer; |
| ... |
| A := (A + 1) + C; |
| @end example |
| @end quotation |
| |
| where @cite{A} is @cite{Integer'Last} and @cite{C} is @cite{-1}. |
| Now the final result of the expression on the right hand side is |
| @cite{Integer'Last} which is in range, but the question arises whether the |
| intermediate addition of @cite{(A + 1)} raises an overflow error. |
| |
| The (perhaps surprising) answer is that the Ada language |
| definition does not answer this question. Instead it leaves |
| it up to the implementation to do one of two things if overflow |
| checks are enabled. |
| |
| |
| @itemize * |
| |
| @item |
| raise an exception (@cite{Constraint_Error}), or |
| |
| @item |
| yield the correct mathematical result which is then used in |
| subsequent operations. |
| @end itemize |
| |
| If the compiler chooses the first approach, then the assignment of this |
| example will indeed raise @cite{Constraint_Error} if overflow checking is |
| enabled, or result in erroneous execution if overflow checks are suppressed. |
| |
| But if the compiler |
| chooses the second approach, then it can perform both additions yielding |
| the correct mathematical result, which is in range, so no exception |
| will be raised, and the right result is obtained, regardless of whether |
| overflow checks are suppressed. |
| |
| Note that in the first example an |
| exception will be raised in either case, since if the compiler |
| gives the correct mathematical result for the addition, it will |
| be out of range of the target type of the assignment, and thus |
| fails the range check. |
| |
| This lack of specified behavior in the handling of overflow for |
| intermediate results is a source of non-portability, and can thus |
| be problematic when programs are ported. Most typically this arises |
| in a situation where the original compiler did not raise an exception, |
| and then the application is moved to a compiler where the check is |
| performed on the intermediate result and an unexpected exception is |
| raised. |
| |
| Furthermore, when using Ada 2012's preconditions and other |
| assertion forms, another issue arises. Consider: |
| |
| @quotation |
| |
| @example |
| procedure P (A, B : Integer) with |
| Pre => A + B <= Integer'Last; |
| @end example |
| @end quotation |
| |
| One often wants to regard arithmetic in a context like this from |
| a mathematical point of view. So for example, if the two actual parameters |
| for a call to @cite{P} are both @cite{Integer'Last}, then |
| the precondition should be regarded as False. If we are executing |
| in a mode with run-time checks enabled for preconditions, then we would |
| like this precondition to fail, rather than raising an exception |
| because of the intermediate overflow. |
| |
| However, the language definition leaves the specification of |
| whether the above condition fails (raising @cite{Assert_Error}) or |
| causes an intermediate overflow (raising @cite{Constraint_Error}) |
| up to the implementation. |
| |
| The situation is worse in a case such as the following: |
| |
| @quotation |
| |
| @example |
| procedure Q (A, B, C : Integer) with |
| Pre => A + B + C <= Integer'Last; |
| @end example |
| @end quotation |
| |
| Consider the call |
| |
| @quotation |
| |
| @example |
| Q (A => Integer'Last, B => 1, C => -1); |
| @end example |
| @end quotation |
| |
| From a mathematical point of view the precondition |
| is True, but at run time we may (but are not guaranteed to) get an |
| exception raised because of the intermediate overflow (and we really |
| would prefer this precondition to be considered True at run time). |
| |
| @node Management of Overflows in GNAT,Specifying the Desired Mode,Background,Overflow Check Handling in GNAT |
| @anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{24d}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{24e} |
| @subsection Management of Overflows in GNAT |
| |
| |
| To deal with the portability issue, and with the problem of |
| mathematical versus run-time interpretation of the expressions in |
| assertions, GNAT provides comprehensive control over the handling |
| of intermediate overflow. GNAT can operate in three modes, and |
| furthemore, permits separate selection of operating modes for |
| the expressions within assertions (here the term 'assertions' |
| is used in the technical sense, which includes preconditions and so forth) |
| and for expressions appearing outside assertions. |
| |
| The three modes are: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Use base type for intermediate operations} (@cite{STRICT}) |
| |
| In this mode, all intermediate results for predefined arithmetic |
| operators are computed using the base type, and the result must |
| be in range of the base type. If this is not the |
| case then either an exception is raised (if overflow checks are |
| enabled) or the execution is erroneous (if overflow checks are suppressed). |
| This is the normal default mode. |
| |
| @item |
| @emph{Most intermediate overflows avoided} (@cite{MINIMIZED}) |
| |
| In this mode, the compiler attempts to avoid intermediate overflows by |
| using a larger integer type, typically @cite{Long_Long_Integer}, |
| as the type in which arithmetic is |
| performed for predefined arithmetic operators. This may be slightly more |
| expensive at |
| run time (compared to suppressing intermediate overflow checks), though |
| the cost is negligible on modern 64-bit machines. For the examples given |
| earlier, no intermediate overflows would have resulted in exceptions, |
| since the intermediate results are all in the range of |
| @cite{Long_Long_Integer} (typically 64-bits on nearly all implementations |
| of GNAT). In addition, if checks are enabled, this reduces the number of |
| checks that must be made, so this choice may actually result in an |
| improvement in space and time behavior. |
| |
| However, there are cases where @cite{Long_Long_Integer} is not large |
| enough, consider the following example: |
| |
| @quotation |
| |
| @example |
| procedure R (A, B, C, D : Integer) with |
| Pre => (A**2 * B**2) / (C**2 * D**2) <= 10; |
| @end example |
| @end quotation |
| |
| where @cite{A} = @cite{B} = @cite{C} = @cite{D} = @cite{Integer'Last}. |
| Now the intermediate results are |
| out of the range of @cite{Long_Long_Integer} even though the final result |
| is in range and the precondition is True (from a mathematical point |
| of view). In such a case, operating in this mode, an overflow occurs |
| for the intermediate computation (which is why this mode |
| says @emph{most} intermediate overflows are avoided). In this case, |
| an exception is raised if overflow checks are enabled, and the |
| execution is erroneous if overflow checks are suppressed. |
| |
| @item |
| @emph{All intermediate overflows avoided} (@cite{ELIMINATED}) |
| |
| In this mode, the compiler avoids all intermediate overflows |
| by using arbitrary precision arithmetic as required. In this |
| mode, the above example with @cite{A**2 * B**2} would |
| not cause intermediate overflow, because the intermediate result |
| would be evaluated using sufficient precision, and the result |
| of evaluating the precondition would be True. |
| |
| This mode has the advantage of avoiding any intermediate |
| overflows, but at the expense of significant run-time overhead, |
| including the use of a library (included automatically in this |
| mode) for multiple-precision arithmetic. |
| |
| This mode provides cleaner semantics for assertions, since now |
| the run-time behavior emulates true arithmetic behavior for the |
| predefined arithmetic operators, meaning that there is never a |
| conflict between the mathematical view of the assertion, and its |
| run-time behavior. |
| |
| Note that in this mode, the behavior is unaffected by whether or |
| not overflow checks are suppressed, since overflow does not occur. |
| It is possible for gigantic intermediate expressions to raise |
| @cite{Storage_Error} as a result of attempting to compute the |
| results of such expressions (e.g. @cite{Integer'Last ** Integer'Last}) |
| but overflow is impossible. |
| @end itemize |
| |
| Note that these modes apply only to the evaluation of predefined |
| arithmetic, membership, and comparison operators for signed integer |
| aritmetic. |
| |
| For fixed-point arithmetic, checks can be suppressed. But if checks |
| are enabled |
| then fixed-point values are always checked for overflow against the |
| base type for intermediate expressions (that is such checks always |
| operate in the equivalent of @cite{STRICT} mode). |
| |
| For floating-point, on nearly all architectures, @cite{Machine_Overflows} |
| is False, and IEEE infinities are generated, so overflow exceptions |
| are never raised. If you want to avoid infinities, and check that |
| final results of expressions are in range, then you can declare a |
| constrained floating-point type, and range checks will be carried |
| out in the normal manner (with infinite values always failing all |
| range checks). |
| |
| @node Specifying the Desired Mode,Default Settings,Management of Overflows in GNAT,Overflow Check Handling in GNAT |
| @anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{100}@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{24f} |
| @subsection Specifying the Desired Mode |
| |
| |
| @geindex pragma Overflow_Mode |
| |
| The desired mode of for handling intermediate overflow can be specified using |
| either the @cite{Overflow_Mode} pragma or an equivalent compiler switch. |
| The pragma has the form |
| |
| @quotation |
| |
| @example |
| pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]); |
| @end example |
| @end quotation |
| |
| where @cite{MODE} is one of |
| |
| |
| @itemize * |
| |
| @item |
| @cite{STRICT}: intermediate overflows checked (using base type) |
| |
| @item |
| @cite{MINIMIZED}: minimize intermediate overflows |
| |
| @item |
| @cite{ELIMINATED}: eliminate intermediate overflows |
| @end itemize |
| |
| The case is ignored, so @cite{MINIMIZED}, @cite{Minimized} and |
| @cite{minimized} all have the same effect. |
| |
| If only the @cite{General} parameter is present, then the given @cite{MODE} |
| applies |
| to expressions both within and outside assertions. If both arguments |
| are present, then @cite{General} applies to expressions outside assertions, |
| and @cite{Assertions} applies to expressions within assertions. For example: |
| |
| @quotation |
| |
| @example |
| pragma Overflow_Mode |
| (General => Minimized, Assertions => Eliminated); |
| @end example |
| @end quotation |
| |
| specifies that general expressions outside assertions be evaluated |
| in 'minimize intermediate overflows' mode, and expressions within |
| assertions be evaluated in 'eliminate intermediate overflows' mode. |
| This is often a reasonable choice, avoiding excessive overhead |
| outside assertions, but assuring a high degree of portability |
| when importing code from another compiler, while incurring |
| the extra overhead for assertion expressions to ensure that |
| the behavior at run time matches the expected mathematical |
| behavior. |
| |
| The @cite{Overflow_Mode} pragma has the same scoping and placement |
| rules as pragma @cite{Suppress}, so it can occur either as a |
| configuration pragma, specifying a default for the whole |
| program, or in a declarative scope, where it applies to the |
| remaining declarations and statements in that scope. |
| |
| Note that pragma @cite{Overflow_Mode} does not affect whether |
| overflow checks are enabled or suppressed. It only controls the |
| method used to compute intermediate values. To control whether |
| overflow checking is enabled or suppressed, use pragma @cite{Suppress} |
| or @cite{Unsuppress} in the usual manner |
| |
| @geindex -gnato? (gcc) |
| |
| @geindex -gnato?? (gcc) |
| |
| Additionally, a compiler switch @emph{-gnato?} or @emph{-gnato??} |
| can be used to control the checking mode default (which can be subsequently |
| overridden using pragmas). |
| |
| Here @code{?} is one of the digits @code{1} through @code{3}: |
| |
| @quotation |
| |
| |
| @multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| @code{1} |
| |
| @tab |
| |
| use base type for intermediate operations (@cite{STRICT}) |
| |
| @item |
| |
| @code{2} |
| |
| @tab |
| |
| minimize intermediate overflows (@cite{MINIMIZED}) |
| |
| @item |
| |
| @code{3} |
| |
| @tab |
| |
| eliminate intermediate overflows (@cite{ELIMINATED}) |
| |
| @end multitable |
| |
| @end quotation |
| |
| As with the pragma, if only one digit appears then it applies to all |
| cases; if two digits are given, then the first applies outside |
| assertions, and the second within assertions. Thus the equivalent |
| of the example pragma above would be |
| @emph{-gnato23}. |
| |
| If no digits follow the @emph{-gnato}, then it is equivalent to |
| @emph{-gnato11}, |
| causing all intermediate operations to be computed using the base |
| type (@cite{STRICT} mode). |
| |
| @node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT |
| @anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{250}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{251} |
| @subsection Default Settings |
| |
| |
| The default mode for overflow checks is |
| |
| @quotation |
| |
| @example |
| General => Strict |
| @end example |
| @end quotation |
| |
| which causes all computations both inside and outside assertions to use |
| the base type. |
| |
| This retains compatibility with previous versions of |
| GNAT which suppressed overflow checks by default and always |
| used the base type for computation of intermediate results. |
| |
| @c Sphinx allows no emphasis within :index: role. As a workaround we |
| @c point the index to "switch" and use emphasis for "-gnato". |
| |
| The |
| @geindex -gnato (gcc) |
| switch @emph{-gnato} (with no digits following) |
| is equivalent to |
| |
| @quotation |
| |
| @example |
| General => Strict |
| @end example |
| @end quotation |
| |
| which causes overflow checking of all intermediate overflows |
| both inside and outside assertions against the base type. |
| |
| The pragma @cite{Suppress (Overflow_Check)} disables overflow |
| checking, but it has no effect on the method used for computing |
| intermediate results. |
| |
| The pragma @cite{Unsuppress (Overflow_Check)} enables overflow |
| checking, but it has no effect on the method used for computing |
| intermediate results. |
| |
| @node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT |
| @anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{252}@anchor{gnat_ugn/gnat_and_program_execution id59}@anchor{253} |
| @subsection Implementation Notes |
| |
| |
| In practice on typical 64-bit machines, the @cite{MINIMIZED} mode is |
| reasonably efficient, and can be generally used. It also helps |
| to ensure compatibility with code imported from some other |
| compiler to GNAT. |
| |
| Setting all intermediate overflows checking (@cite{CHECKED} mode) |
| makes sense if you want to |
| make sure that your code is compatible with any other possible |
| Ada implementation. This may be useful in ensuring portability |
| for code that is to be exported to some other compiler than GNAT. |
| |
| The Ada standard allows the reassociation of expressions at |
| the same precedence level if no parentheses are present. For |
| example, @cite{A+B+C} parses as though it were @cite{(A+B)+C}, but |
| the compiler can reintepret this as @cite{A+(B+C)}, possibly |
| introducing or eliminating an overflow exception. The GNAT |
| compiler never takes advantage of this freedom, and the |
| expression @cite{A+B+C} will be evaluated as @cite{(A+B)+C}. |
| If you need the other order, you can write the parentheses |
| explicitly @cite{A+(B+C)} and GNAT will respect this order. |
| |
| The use of @cite{ELIMINATED} mode will cause the compiler to |
| automatically include an appropriate arbitrary precision |
| integer arithmetic package. The compiler will make calls |
| to this package, though only in cases where it cannot be |
| sure that @cite{Long_Long_Integer} is sufficient to guard against |
| intermediate overflows. This package does not use dynamic |
| alllocation, but it does use the secondary stack, so an |
| appropriate secondary stack package must be present (this |
| is always true for standard full Ada, but may require |
| specific steps for restricted run times such as ZFP). |
| |
| Although @cite{ELIMINATED} mode causes expressions to use arbitrary |
| precision arithmetic, avoiding overflow, the final result |
| must be in an appropriate range. This is true even if the |
| final result is of type @cite{[Long_[Long_]]Integer'Base}, which |
| still has the same bounds as its associated constrained |
| type at run-time. |
| |
| Currently, the @cite{ELIMINATED} mode is only available on target |
| platforms for which @cite{Long_Long_Integer} is 64-bits (nearly all GNAT |
| platforms). |
| |
| @node Performing Dimensionality Analysis in GNAT,Stack Related Facilities,Overflow Check Handling in GNAT,GNAT and Program Execution |
| @anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{2a}@anchor{gnat_ugn/gnat_and_program_execution id60}@anchor{1f7} |
| @section Performing Dimensionality Analysis in GNAT |
| |
| |
| @geindex Dimensionality analysis |
| |
| The GNAT compiler supports dimensionality checking. The user can |
| specify physical units for objects, and the compiler will verify that uses |
| of these objects are compatible with their dimensions, in a fashion that is |
| familiar to engineering practice. The dimensions of algebraic expressions |
| (including powers with static exponents) are computed from their constituents. |
| |
| @geindex Dimension_System aspect |
| |
| @geindex Dimension aspect |
| |
| This feature depends on Ada 2012 aspect specifications, and is available from |
| version 7.0.1 of GNAT onwards. |
| The GNAT-specific aspect @cite{Dimension_System} |
| allows you to define a system of units; the aspect @cite{Dimension} |
| then allows the user to declare dimensioned quantities within a given system. |
| (These aspects are described in the @emph{Implementation Defined Aspects} |
| chapter of the @emph{GNAT Reference Manual}). |
| |
| The major advantage of this model is that it does not require the declaration of |
| multiple operators for all possible combinations of types: it is only necessary |
| to use the proper subtypes in object declarations. |
| |
| @geindex System.Dim.Mks package (GNAT library) |
| |
| @geindex MKS_Type type |
| |
| The simplest way to impose dimensionality checking on a computation is to make |
| use of the package @cite{System.Dim.Mks}, |
| which is part of the GNAT library. This |
| package defines a floating-point type @cite{MKS_Type}, |
| for which a sequence of |
| dimension names are specified, together with their conventional abbreviations. |
| The following should be read together with the full specification of the |
| package, in file @code{s-dimmks.ads}. |
| |
| @quotation |
| |
| @geindex s-dimmks.ads file |
| |
| @example |
| type Mks_Type is new Long_Long_Float |
| with |
| Dimension_System => ( |
| (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), |
| (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), |
| (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), |
| (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), |
| (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"), |
| (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), |
| (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); |
| @end example |
| @end quotation |
| |
| The package then defines a series of subtypes that correspond to these |
| conventional units. For example: |
| |
| @quotation |
| |
| @example |
| subtype Length is Mks_Type |
| with |
| Dimension => (Symbol => 'm', Meter => 1, others => 0); |
| @end example |
| @end quotation |
| |
| and similarly for @cite{Mass}, @cite{Time}, @cite{Electric_Current}, |
| @cite{Thermodynamic_Temperature}, @cite{Amount_Of_Substance}, and |
| @cite{Luminous_Intensity} (the standard set of units of the SI system). |
| |
| The package also defines conventional names for values of each unit, for |
| example: |
| |
| @quotation |
| |
| @c code-block":: ada |
| @c |
| @c m : constant Length := 1.0; |
| @c kg : constant Mass := 1.0; |
| @c s : constant Time := 1.0; |
| @c A : constant Electric_Current := 1.0; |
| @end quotation |
| |
| as well as useful multiples of these units: |
| |
| @quotation |
| |
| @example |
| cm : constant Length := 1.0E-02; |
| g : constant Mass := 1.0E-03; |
| min : constant Time := 60.0; |
| day : constant Time := 60.0 * 24.0 * min; |
| ... |
| @end example |
| @end quotation |
| |
| Using this package, you can then define a derived unit by |
| providing the aspect that |
| specifies its dimensions within the MKS system, as well as the string to |
| be used for output of a value of that unit: |
| |
| @quotation |
| |
| @example |
| subtype Acceleration is Mks_Type |
| with Dimension => ("m/sec^2", |
| Meter => 1, |
| Second => -2, |
| others => 0); |
| @end example |
| @end quotation |
| |
| Here is a complete example of use: |
| |
| @quotation |
| |
| @example |
| with System.Dim.MKS; use System.Dim.Mks; |
| with System.Dim.Mks_IO; use System.Dim.Mks_IO; |
| with Text_IO; use Text_IO; |
| procedure Free_Fall is |
| subtype Acceleration is Mks_Type |
| with Dimension => ("m/sec^2", 1, 0, -2, others => 0); |
| G : constant acceleration := 9.81 * m / (s ** 2); |
| T : Time := 10.0*s; |
| Distance : Length; |
| |
| begin |
| Put ("Gravitational constant: "); |
| Put (G, Aft => 2, Exp => 0); Put_Line (""); |
| Distance := 0.5 * G * T ** 2; |
| Put ("distance travelled in 10 seconds of free fall "); |
| Put (Distance, Aft => 2, Exp => 0); |
| Put_Line (""); |
| end Free_Fall; |
| @end example |
| @end quotation |
| |
| Execution of this program yields: |
| |
| @quotation |
| |
| @example |
| Gravitational constant: 9.81 m/sec^2 |
| distance travelled in 10 seconds of free fall 490.50 m |
| @end example |
| @end quotation |
| |
| However, incorrect assignments such as: |
| |
| @quotation |
| |
| @example |
| Distance := 5.0; |
| Distance := 5.0 * kg: |
| @end example |
| @end quotation |
| |
| are rejected with the following diagnoses: |
| |
| @quotation |
| |
| @example |
| Distance := 5.0; |
| >>> dimensions mismatch in assignment |
| >>> left-hand side has dimension [L] |
| >>> right-hand side is dimensionless |
| |
| Distance := 5.0 * kg: |
| >>> dimensions mismatch in assignment |
| >>> left-hand side has dimension [L] |
| >>> right-hand side has dimension [M] |
| @end example |
| @end quotation |
| |
| The dimensions of an expression are properly displayed, even if there is |
| no explicit subtype for it. If we add to the program: |
| |
| @quotation |
| |
| @example |
| Put ("Final velocity: "); |
| Put (G * T, Aft =>2, Exp =>0); |
| Put_Line (""); |
| @end example |
| @end quotation |
| |
| then the output includes: |
| |
| @quotation |
| |
| @example |
| Final velocity: 98.10 m.s**(-1) |
| @end example |
| @end quotation |
| |
| @node Stack Related Facilities,Memory Management Issues,Performing Dimensionality Analysis in GNAT,GNAT and Program Execution |
| @anchor{gnat_ugn/gnat_and_program_execution id61}@anchor{1f8}@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{2b} |
| @section Stack Related Facilities |
| |
| |
| This section describes some useful tools associated with stack |
| checking and analysis. In |
| particular, it deals with dynamic and static stack usage measurements. |
| |
| @menu |
| * Stack Overflow Checking:: |
| * Static Stack Usage Analysis:: |
| * Dynamic Stack Usage Analysis:: |
| |
| @end menu |
| |
| @node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities |
| @anchor{gnat_ugn/gnat_and_program_execution id62}@anchor{254}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{fc} |
| @subsection Stack Overflow Checking |
| |
| |
| @geindex Stack Overflow Checking |
| |
| @geindex -fstack-check (gcc) |
| |
| For most operating systems, @emph{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. Most native systems offer some level of protection by |
| adding a guard page at the end of each task stack. This mechanism is usually |
| not enough for dealing properly with stack overflow situations because |
| a large local variable could "jump" above the guard page. |
| Furthermore, when the |
| guard page is hit, there may not be any space left on the stack for executing |
| the exception propagation code. Enabling stack checking avoids |
| such situations. |
| |
| To activate stack checking, compile all units with the gcc option |
| @cite{-fstack-check}. For example: |
| |
| @quotation |
| |
| @example |
| $ gcc -c -fstack-check package1.adb |
| @end example |
| @end quotation |
| |
| 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) does not exceed the available stack space. |
| If the space is exceeded, then a @cite{Storage_Error} exception is raised. |
| |
| For declared tasks, the stack size is controlled by the size |
| given in an applicable @cite{Storage_Size} pragma or by the value specified |
| at bind time with @code{-d} (@ref{126,,Switches for gnatbind}) or is set to |
| the default size as defined in the GNAT runtime otherwise. |
| |
| @geindex GNAT_STACK_LIMIT |
| |
| For the environment task, the stack size depends on |
| system defaults and is unknown to the compiler. 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 |
| @geindex GNAT_STACK_LIMIT |
| @geindex environment variable; GNAT_STACK_LIMIT |
| @code{GNAT_STACK_LIMIT} to indicate the maximum |
| stack area that can be used, as in: |
| |
| @quotation |
| |
| @example |
| $ SET GNAT_STACK_LIMIT 1600 |
| @end example |
| @end quotation |
| |
| 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. |
| |
| @node Static Stack Usage Analysis,Dynamic Stack Usage Analysis,Stack Overflow Checking,Stack Related Facilities |
| @anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{fd}@anchor{gnat_ugn/gnat_and_program_execution id63}@anchor{255} |
| @subsection Static Stack Usage Analysis |
| |
| |
| @geindex Static Stack Usage Analysis |
| |
| @geindex -fstack-usage |
| |
| A unit compiled with @code{-fstack-usage} will generate an extra file |
| that specifies |
| the maximum amount of stack used, on a per-function basis. |
| The file has the same |
| basename as the target object file with a @code{.su} extension. |
| Each line of this file is made up of three fields: |
| |
| |
| @itemize * |
| |
| @item |
| The name of the function. |
| |
| @item |
| A number of bytes. |
| |
| @item |
| One or more qualifiers: @cite{static}, @cite{dynamic}, @cite{bounded}. |
| @end itemize |
| |
| The second field corresponds to the size of the known part of the function |
| frame. |
| |
| The qualifier @cite{static} means that the function frame size |
| is purely static. |
| It usually means that all local variables have a static size. |
| In this case, the second field is a reliable measure of the function stack |
| utilization. |
| |
| The qualifier @cite{dynamic} means that the function frame size is not static. |
| It happens mainly when some local variables have a dynamic size. When this |
| qualifier appears alone, the second field is not a reliable measure |
| of the function stack analysis. When it is qualified with @cite{bounded}, it |
| means that the second field is a reliable maximum of the function stack |
| utilization. |
| |
| A unit compiled with @code{-Wstack-usage} will issue a warning for each |
| subprogram whose stack usage might be larger than the specified amount of |
| bytes. The wording is in keeping with the qualifier documented above. |
| |
| @node Dynamic Stack Usage Analysis,,Static Stack Usage Analysis,Stack Related Facilities |
| @anchor{gnat_ugn/gnat_and_program_execution id64}@anchor{256}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{128} |
| @subsection Dynamic Stack Usage Analysis |
| |
| |
| It is possible to measure the maximum amount of stack used by a task, by |
| adding a switch to @emph{gnatbind}, as: |
| |
| @quotation |
| |
| @example |
| $ gnatbind -u0 file |
| @end example |
| @end quotation |
| |
| With this option, at each task termination, its stack usage is output on |
| @code{stderr}. |
| It is not always convenient to output the stack usage when the program |
| is still running. Hence, it is possible to delay this output until program |
| termination. for a given number of tasks specified as the argument of the |
| @code{-u} option. For instance: |
| |
| @quotation |
| |
| @example |
| $ gnatbind -u100 file |
| @end example |
| @end quotation |
| |
| will buffer the stack usage information of the first 100 tasks to terminate and |
| output this info at program termination. Results are displayed in four |
| columns: |
| |
| @quotation |
| |
| @example |
| Index | Task Name | Stack Size | Stack Usage |
| @end example |
| @end quotation |
| |
| where: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Index} is a number associated with each task. |
| |
| @item |
| @emph{Task Name} is the name of the task analyzed. |
| |
| @item |
| @emph{Stack Size} is the maximum size for the stack. |
| |
| @item |
| @emph{Stack Usage} is the measure done by the stack analyzer. |
| In order to prevent overflow, the stack |
| is not entirely analyzed, and it's not possible to know exactly how |
| much has actually been used. |
| @end itemize |
| |
| The environment task stack, e.g., the stack that contains the main unit, is |
| only processed when the environment variable GNAT_STACK_LIMIT is set. |
| |
| The package @cite{GNAT.Task_Stack_Usage} provides facilities to get |
| stack usage reports at run-time. See its body for the details. |
| |
| @node Memory Management Issues,,Stack Related Facilities,GNAT and Program Execution |
| @anchor{gnat_ugn/gnat_and_program_execution id65}@anchor{1f9}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{2c} |
| @section Memory Management Issues |
| |
| |
| This section describes some useful memory pools provided in the GNAT library |
| and in particular the GNAT Debug Pool facility, which can be used to detect |
| incorrect uses of access values (including 'dangling references'). |
| |
| |
| @menu |
| * Some Useful Memory Pools:: |
| * The GNAT Debug Pool Facility:: |
| |
| @end menu |
| |
| @node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues |
| @anchor{gnat_ugn/gnat_and_program_execution id66}@anchor{257}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{258} |
| @subsection Some Useful Memory Pools |
| |
| |
| @geindex Memory Pool |
| |
| @geindex storage |
| @geindex pool |
| |
| The @cite{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool |
| storage pool. Allocations use the standard system call @cite{malloc} while |
| deallocations use the standard system call @cite{free}. No reclamation is |
| performed when the pool goes out of scope. For performance reasons, the |
| standard default Ada allocators/deallocators do not use any explicit storage |
| pools but if they did, they could use this storage pool without any change in |
| behavior. That is why this storage pool is used when the user |
| manages to make the default implicit allocator explicit as in this example: |
| |
| @quotation |
| |
| @example |
| type T1 is access Something; |
| -- no Storage pool is defined for T2 |
| |
| type T2 is access Something_Else; |
| for T2'Storage_Pool use T1'Storage_Pool; |
| -- the above is equivalent to |
| for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object; |
| @end example |
| @end quotation |
| |
| The @cite{System.Pool_Local} package offers the Unbounded_Reclaim_Pool storage |
| pool. The allocation strategy is similar to @cite{Pool_Local}'s |
| except that the all |
| storage allocated with this pool is reclaimed when the pool object goes out of |
| scope. This pool provides a explicit mechanism similar to the implicit one |
| provided by several Ada 83 compilers for allocations performed through a local |
| access type and whose purpose was to reclaim memory when exiting the |
| scope of a given local access. As an example, the following program does not |
| leak memory even though it does not perform explicit deallocation: |
| |
| @quotation |
| |
| @example |
| with System.Pool_Local; |
| procedure Pooloc1 is |
| procedure Internal is |
| type A is access Integer; |
| X : System.Pool_Local.Unbounded_Reclaim_Pool; |
| for A'Storage_Pool use X; |
| v : A; |
| begin |
| for I in 1 .. 50 loop |
| v := new Integer; |
| end loop; |
| end Internal; |
| begin |
| for I in 1 .. 100 loop |
| Internal; |
| end loop; |
| end Pooloc1; |
| @end example |
| @end quotation |
| |
| The @cite{System.Pool_Size} package implements the Stack_Bounded_Pool used when |
| @cite{Storage_Size} is specified for an access type. |
| The whole storage for the pool is |
| allocated at once, usually on the stack at the point where the access type is |
| elaborated. It is automatically reclaimed when exiting the scope where the |
| access type is defined. This package is not intended to be used directly by the |
| user and it is implicitly used for each such declaration: |
| |
| @quotation |
| |
| @example |
| type T1 is access Something; |
| for T1'Storage_Size use 10_000; |
| @end example |
| @end quotation |
| |
| @node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues |
| @anchor{gnat_ugn/gnat_and_program_execution id67}@anchor{259}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{25a} |
| @subsection The GNAT Debug Pool Facility |
| |
| |
| @geindex Debug Pool |
| |
| @geindex storage |
| @geindex pool |
| @geindex memory corruption |
| |
| 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 @cite{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. |
| |
| @quotation |
| |
| @example |
| type Ptr is access Some_Type; |
| Pool : GNAT.Debug_Pools.Debug_Pool; |
| for Ptr'Storage_Pool use Pool; |
| @end example |
| @end quotation |
| |
| @cite{GNAT.Debug_Pools} is derived from a GNAT-specific kind of |
| pool: the @cite{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 @cite{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: |
| |
| |
| @itemize * |
| |
| @item |
| @cite{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage} |
| |
| @item |
| @cite{GNAT.Debug_Pools.Accessing_Deallocated_Storage} |
| |
| @item |
| @cite{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage} |
| |
| @item |
| @cite{GNAT.Debug_Pools.Freeing_Deallocated_Storage} |
| @end itemize |
| |
| 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. Several deallocation strategies are |
| provided, whereupon the user can choose to release the memory to the system, |
| keep it allocated for further invalid access checks, or fill it with an easily |
| recognizable pattern for debug sessions. The memory pattern is the old IBM |
| hexadecimal convention: @cite{16#DEADBEEF#}. |
| |
| See the documentation in the file g-debpoo.ads for more information on the |
| various strategies. |
| |
| 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 |
| @cite{Debug_Pools}, that includes typical instances of memory corruption: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| The debug pool mechanism provides the following precise diagnostics on the |
| execution of this erroneous program: |
| |
| @quotation |
| |
| @example |
| 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 |
| @end example |
| @end quotation |
| |
| |
| @c -- Non-breaking space in running text |
| @c -- E.g. Ada |nbsp| 95 |
| |
| @node Platform-Specific Information,Example of Binder Output File,GNAT and Program Execution,Top |
| @anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{f}@anchor{gnat_ugn/platform_specific_information doc}@anchor{25b}@anchor{gnat_ugn/platform_specific_information id1}@anchor{25c} |
| @chapter Platform-Specific Information |
| |
| |
| This appendix contains information relating to the implementation |
| of run-time libraries on various platforms and also covers |
| topics related to the GNAT implementation on Windows and Mac OS. |
| |
| @menu |
| * Run-Time Libraries:: |
| * Specifying a Run-Time Library:: |
| * Microsoft Windows Topics:: |
| * Mac OS Topics:: |
| |
| @end menu |
| |
| @node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information |
| @anchor{gnat_ugn/platform_specific_information id2}@anchor{25d}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{2d} |
| @section Run-Time Libraries |
| |
| |
| @geindex Tasking and threads libraries |
| |
| @geindex Threads libraries and tasking |
| |
| @geindex Run-time libraries (platform-specific information) |
| |
| The GNAT run-time implementation may vary with respect to both the |
| underlying threads library and the exception handling scheme. |
| For threads support, one or more of the following are supplied: |
| |
| |
| @itemize * |
| |
| @item |
| @strong{native threads library}, a binding to the thread package from |
| the underlying operating system |
| |
| @item |
| @strong{pthreads library} (Sparc Solaris only), a binding to the Solaris |
| POSIX thread package |
| @end itemize |
| |
| For exception handling, either or both of two models are supplied: |
| |
| @quotation |
| |
| @geindex Zero-Cost Exceptions |
| |
| @geindex ZCX (Zero-Cost Exceptions) |
| @end quotation |
| |
| |
| @itemize * |
| |
| @item |
| @strong{Zero-Cost Exceptions} ("ZCX"), |
| which uses binder-generated tables that |
| are interrogated at run time to locate a handler. |
| |
| @geindex setjmp/longjmp Exception Model |
| |
| @geindex SJLJ (setjmp/longjmp Exception Model) |
| |
| @item |
| @strong{setjmp / longjmp} ('SJLJ'), |
| which uses dynamically-set data to establish |
| the set of handlers |
| @end itemize |
| |
| Most programs should experience a substantial speed improvement by |
| being compiled with a ZCX run-time. |
| This is especially true for |
| tasking applications or applications with many exception handlers.@} |
| |
| This section summarizes which combinations of threads and exception support |
| are supplied on various GNAT platforms. |
| It then shows how to select a particular library either |
| permanently or temporarily, |
| explains the properties of (and tradeoffs among) the various threads |
| libraries, and provides some additional |
| information about several specific platforms. |
| |
| @menu |
| * Summary of Run-Time Configurations:: |
| |
| @end menu |
| |
| @node Summary of Run-Time Configurations,,,Run-Time Libraries |
| @anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{25e}@anchor{gnat_ugn/platform_specific_information id3}@anchor{25f} |
| @subsection Summary of Run-Time Configurations |
| |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx} |
| @headitem |
| |
| Platform |
| |
| @tab |
| |
| Run-Time |
| |
| @tab |
| |
| Tasking |
| |
| @tab |
| |
| Exceptions |
| |
| @item |
| |
| ppc-aix |
| |
| @tab |
| |
| rts-native |
| (default) |
| |
| @tab |
| |
| native AIX threads |
| |
| @tab |
| |
| ZCX |
| |
| @item |
| |
| rts-sjlj |
| |
| @tab |
| |
| native AIX threads |
| |
| @tab |
| |
| SJLJ |
| |
| @item |
| |
| sparc-solaris |
| |
| @tab |
| |
| rts-native |
| (default) |
| |
| @tab |
| |
| native Solaris |
| threads library |
| |
| @tab |
| |
| ZCX |
| |
| @item |
| |
| rts-pthread |
| |
| @tab |
| |
| pthread library |
| |
| @tab |
| |
| ZCX |
| |
| @item |
| |
| rts-sjlj |
| |
| @tab |
| |
| native Solaris |
| threads library |
| |
| @tab |
| |
| SJLJ |
| |
| @item |
| |
| sparc64-solaris |
| |
| @tab |
| |
| rts-native |
| (default) |
| |
| @tab |
| |
| native Solaris |
| threads library |
| |
| @tab |
| |
| ZCX |
| |
| @item |
| |
| x86-linux |
| |
| @tab |
| |
| rts-native |
| (default) |
| |
| @tab |
| |
| pthread library |
| |
| @tab |
| |
| ZCX |
| |
| @item |
| |
| rts-sjlj |
| |
| @tab |
| |
| pthread library |
| |
| @tab |
| |
| SJLJ |
| |
| @item |
| |
| x86-lynx |
| |
| @tab |
| |
| rts-native |
| (default) |
| |
| @tab |
| |
| native LynxOS threads |
| |
| @tab |
| |
| SJLJ |
| |
| @item |
| |
| x86-solaris |
| |
| @tab |
| |
| rts-native |
| (default) |
| |
| @tab |
| |
| native Solaris |
| threads library |
| |
| @tab |
| |
| ZCX |
| |
| @item |
| |
| rts-sjlj |
| |
| @tab |
| |
| native Solaris |
| threads library |
| |
| @tab |
| |
| SJLJ |
| |
| @item |
| |
| x86-windows |
| |
| @tab |
| |
| rts-native |
| (default) |
| |
| @tab |
| |
| native Win32 threads |
| |
| @tab |
| |
| ZCX |
| |
| @item |
| |
| rts-sjlj |
| |
| @tab |
| |
| native Win32 threads |
| |
| @tab |
| |
| SJLJ |
| |
| @item |
| |
| x86_64-linux |
| |
| @tab |
| |
| rts-native |
| (default) |
| |
| @tab |
| |
| pthread library |
| |
| @tab |
| |
| ZCX |
| |
| @item |
| |
| rts-sjlj |
| |
| @tab |
| |
| pthread library |
| |
| @tab |
| |
| SJLJ |
| |
| @end multitable |
| |
| |
| @node Specifying a Run-Time Library,Microsoft Windows Topics,Run-Time Libraries,Platform-Specific Information |
| @anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{260}@anchor{gnat_ugn/platform_specific_information id4}@anchor{261} |
| @section Specifying a Run-Time Library |
| |
| |
| The @code{adainclude} subdirectory containing the sources of the GNAT |
| run-time library, and the @code{adalib} subdirectory containing the |
| @code{ALI} files and the static and/or shared GNAT library, are located |
| in the gcc target-dependent area: |
| |
| @quotation |
| |
| @example |
| target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/ |
| @end example |
| @end quotation |
| |
| As indicated above, on some platforms several run-time libraries are supplied. |
| These libraries are installed in the target dependent area and |
| contain a complete source and binary subdirectory. The detailed description |
| below explains the differences between the different libraries in terms of |
| their thread support. |
| |
| The default run-time library (when GNAT is installed) is @emph{rts-native}. |
| This default run time is selected by the means of soft links. |
| For example on x86-linux: |
| |
| @example |
| -- |
| -- $(target-dir) |
| -- | |
| -- +--- adainclude----------+ |
| -- | | |
| -- +--- adalib-----------+ | |
| -- | | | |
| -- +--- rts-native | | |
| -- | | | | |
| -- | +--- adainclude <---+ |
| -- | | | |
| -- | +--- adalib <----+ |
| -- | |
| -- +--- rts-sjlj |
| -- | |
| -- +--- adainclude |
| -- | |
| -- +--- adalib |
| @end example |
| |
| If the @emph{rts-sjlj} library is to be selected on a permanent basis, |
| these soft links can be modified with the following commands: |
| |
| @quotation |
| |
| @example |
| $ cd $target |
| $ rm -f adainclude adalib |
| $ ln -s rts-sjlj/adainclude adainclude |
| $ ln -s rts-sjlj/adalib adalib |
| @end example |
| @end quotation |
| |
| Alternatively, you can specify @code{rts-sjlj/adainclude} in the file |
| @code{$target/ada_source_path} and @code{rts-sjlj/adalib} in |
| @code{$target/ada_object_path}. |
| |
| @geindex --RTS option |
| |
| Selecting another run-time library temporarily can be |
| achieved by using the @emph{--RTS} switch, e.g., @emph{--RTS=sjlj} |
| @anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{262} |
| @geindex SCHED_FIFO scheduling policy |
| |
| @geindex SCHED_RR scheduling policy |
| |
| @geindex SCHED_OTHER scheduling policy |
| |
| @menu |
| * Choosing the Scheduling Policy:: |
| * Solaris-Specific Considerations:: |
| * Solaris Threads Issues:: |
| * AIX-Specific Considerations:: |
| |
| @end menu |
| |
| @node Choosing the Scheduling Policy,Solaris-Specific Considerations,,Specifying a Run-Time Library |
| @anchor{gnat_ugn/platform_specific_information id5}@anchor{263} |
| @subsection Choosing the Scheduling Policy |
| |
| |
| When using a POSIX threads implementation, you have a choice of several |
| scheduling policies: @cite{SCHED_FIFO}, @cite{SCHED_RR} and @cite{SCHED_OTHER}. |
| |
| Typically, the default is @cite{SCHED_OTHER}, while using @cite{SCHED_FIFO} |
| or @cite{SCHED_RR} requires special (e.g., root) privileges. |
| |
| @geindex pragma Time_Slice |
| |
| @geindex -T0 option |
| |
| @geindex pragma Task_Dispatching_Policy |
| |
| By default, GNAT uses the @cite{SCHED_OTHER} policy. To specify |
| @cite{SCHED_FIFO}, |
| you can use one of the following: |
| |
| |
| @itemize * |
| |
| @item |
| @cite{pragma Time_Slice (0.0)} |
| |
| @item |
| the corresponding binder option @emph{-T0} |
| |
| @item |
| @cite{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} |
| @end itemize |
| |
| To specify @cite{SCHED_RR}, |
| you should use @cite{pragma Time_Slice} with a |
| value greater than 0.0, or else use the corresponding @emph{-T} |
| binder option. |
| |
| @geindex Solaris Sparc threads libraries |
| |
| @node Solaris-Specific Considerations,Solaris Threads Issues,Choosing the Scheduling Policy,Specifying a Run-Time Library |
| @anchor{gnat_ugn/platform_specific_information id6}@anchor{264}@anchor{gnat_ugn/platform_specific_information solaris-specific-considerations}@anchor{265} |
| @subsection Solaris-Specific Considerations |
| |
| |
| This section addresses some topics related to the various threads libraries |
| on Sparc Solaris. |
| |
| @geindex rts-pthread threads library |
| |
| @node Solaris Threads Issues,AIX-Specific Considerations,Solaris-Specific Considerations,Specifying a Run-Time Library |
| @anchor{gnat_ugn/platform_specific_information id7}@anchor{266}@anchor{gnat_ugn/platform_specific_information solaris-threads-issues}@anchor{267} |
| @subsection Solaris Threads Issues |
| |
| |
| GNAT under Solaris/Sparc 32 bits comes with an alternate tasking run-time |
| library based on POSIX threads --- @emph{rts-pthread}. |
| |
| @geindex PTHREAD_PRIO_INHERIT policy (under rts-pthread) |
| |
| @geindex PTHREAD_PRIO_PROTECT policy (under rts-pthread) |
| |
| @geindex pragma Locking_Policy (under rts-pthread) |
| |
| @geindex Inheritance_Locking (under rts-pthread) |
| |
| @geindex Ceiling_Locking (under rts-pthread) |
| |
| This run-time library has the advantage of being mostly shared across all |
| POSIX-compliant thread implementations, and it also provides under |
| Solaris 8 the @cite{PTHREAD_PRIO_INHERIT} |
| and @cite{PTHREAD_PRIO_PROTECT} |
| semantics that can be selected using the predefined pragma |
| @cite{Locking_Policy} |
| with respectively |
| @cite{Inheritance_Locking} and @cite{Ceiling_Locking} as the policy. |
| |
| As explained above, the native run-time library is based on the Solaris thread |
| library (@cite{libthread}) and is the default library. |
| |
| @geindex GNAT_PROCESSOR environment variable (on Sparc Solaris) |
| |
| When the Solaris threads library is used (this is the default), programs |
| compiled with GNAT can automatically take advantage of |
| and can thus execute on multiple processors. |
| The user can alternatively specify a processor on which the program should run |
| to emulate a single-processor system. The multiprocessor / uniprocessor choice |
| is made by |
| setting the environment variable |
| @geindex GNAT_PROCESSOR |
| @geindex environment variable; GNAT_PROCESSOR |
| @code{GNAT_PROCESSOR} |
| to one of the following: |
| |
| @quotation |
| |
| |
| @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @headitem |
| |
| @code{GNAT_PROCESSOR} Value |
| |
| @tab |
| |
| Effect |
| |
| @item |
| |
| @emph{-2} |
| |
| @tab |
| |
| Use the default configuration (run the program on all |
| available processors) - this is the same as having @cite{GNAT_PROCESSOR} |
| unset |
| |
| @item |
| |
| @emph{-1} |
| |
| @tab |
| |
| Let the run-time implementation choose one processor and run the |
| program on that processor |
| |
| @item |
| |
| @emph{0 .. Last_Proc} |
| |
| @tab |
| |
| Run the program on the specified processor. |
| @cite{Last_Proc} is equal to @cite{_SC_NPROCESSORS_CONF - 1} |
| (where @cite{_SC_NPROCESSORS_CONF} is a system variable). |
| |
| @end multitable |
| |
| @end quotation |
| |
| @node AIX-Specific Considerations,,Solaris Threads Issues,Specifying a Run-Time Library |
| @anchor{gnat_ugn/platform_specific_information aix-specific-considerations}@anchor{268}@anchor{gnat_ugn/platform_specific_information id8}@anchor{269} |
| @subsection AIX-Specific Considerations |
| |
| |
| @geindex AIX resolver library |
| |
| On AIX, the resolver library initializes some internal structure on |
| the first call to @cite{get*by*} functions, which are used to implement |
| @cite{GNAT.Sockets.Get_Host_By_Name} and |
| @cite{GNAT.Sockets.Get_Host_By_Address}. |
| If such initialization occurs within an Ada task, and the stack size for |
| the task is the default size, a stack overflow may occur. |
| |
| To avoid this overflow, the user should either ensure that the first call |
| to @cite{GNAT.Sockets.Get_Host_By_Name} or |
| @cite{GNAT.Sockets.Get_Host_By_Addrss} |
| occurs in the environment task, or use @cite{pragma Storage_Size} to |
| specify a sufficiently large size for the stack of the task that contains |
| this call. |
| |
| @geindex Windows NT |
| |
| @geindex Windows 95 |
| |
| @geindex Windows 98 |
| |
| @node Microsoft Windows Topics,Mac OS Topics,Specifying a Run-Time Library,Platform-Specific Information |
| @anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{2e}@anchor{gnat_ugn/platform_specific_information id9}@anchor{26a} |
| @section Microsoft Windows Topics |
| |
| |
| This section describes topics that are specific to the Microsoft Windows |
| platforms. |
| |
| |
| |
| |
| |
| @menu |
| * Using GNAT on Windows:: |
| * Using a network installation of GNAT:: |
| * CONSOLE and WINDOWS subsystems:: |
| * Temporary Files:: |
| * Mixed-Language Programming on Windows:: |
| * Windows Specific Add-Ons:: |
| |
| @end menu |
| |
| @node Using GNAT on Windows,Using a network installation of GNAT,,Microsoft Windows Topics |
| @anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{26b}@anchor{gnat_ugn/platform_specific_information id10}@anchor{26c} |
| @subsection Using GNAT on Windows |
| |
| |
| One of the strengths of the GNAT technology is that its tool set |
| (@emph{gcc}, @emph{gnatbind}, @emph{gnatlink}, @emph{gnatmake}, the |
| @cite{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: |
| |
| |
| @itemize * |
| |
| @item |
| You can build applications using the @cite{CONSOLE} or @cite{WINDOWS} |
| subsystems. |
| |
| @item |
| You can use any Dynamically Linked Library (DLL) in your Ada code (both |
| relocatable and non-relocatable DLLs are supported). |
| |
| @item |
| 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. |
| |
| @item |
| You can include Windows resources in your Ada application. |
| |
| @item |
| You can use or create COM/DCOM objects. |
| @end itemize |
| |
| 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. |
| |
| |
| @itemize * |
| |
| @item |
| It is not possible to use @cite{GetLastError} and @cite{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 @cite{GetLastError} and |
| @cite{SetLastError} when tasking, protected record, and exception |
| features are not used, but it is not guaranteed to work. |
| |
| @item |
| It is not possible to link against Microsoft C++ libraries except for |
| import libraries. Interfacing must be done by the mean of DLLs. |
| |
| @item |
| It is possible to link against Microsoft C libraries. Yet the preferred |
| solution is to use C/C++ compiler that comes with GNAT, since it |
| doesn't require having two different development environments and makes the |
| inter-language debugging experience smoother. |
| |
| @item |
| When the compilation environment is located on FAT32 drives, users may |
| experience recompilations of the source files that have not changed if |
| Daylight Saving Time (DST) state has changed since the last time files |
| were compiled. NTFS drives do not have this problem. |
| |
| @item |
| No components of the GNAT toolset use any entries in the Windows |
| registry. The only entries that can be created are file associations and |
| PATH settings, provided the user has chosen to create them at installation |
| time, as well as some minimal book-keeping information needed to correctly |
| uninstall or integrate different GNAT products. |
| @end itemize |
| |
| @node Using a network installation of GNAT,CONSOLE and WINDOWS subsystems,Using GNAT on Windows,Microsoft Windows Topics |
| @anchor{gnat_ugn/platform_specific_information id11}@anchor{26d}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{26e} |
| @subsection Using a network installation of GNAT |
| |
| |
| Make sure the system on which GNAT is installed is accessible from the |
| current machine, i.e., the install location is shared over the network. |
| Shared resources are accessed on Windows by means of UNC paths, which |
| have the format @cite{\\server\sharename\path} |
| |
| In order to use such a network installation, simply add the UNC path of the |
| @code{bin} directory of your GNAT installation in front of your PATH. For |
| example, if GNAT is installed in @code{\GNAT} directory of a share location |
| called @code{c-drive} on a machine @code{LOKI}, the following command will |
| make it available: |
| |
| @quotation |
| |
| @example |
| $ path \\loki\c-drive\gnat\bin;%path%` |
| @end example |
| @end quotation |
| |
| Be aware that every compilation using the network installation results in the |
| transfer of large amounts of data across the network and will likely cause |
| serious performance penalty. |
| |
| @node CONSOLE and WINDOWS subsystems,Temporary Files,Using a network installation of GNAT,Microsoft Windows Topics |
| @anchor{gnat_ugn/platform_specific_information id12}@anchor{26f}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{270} |
| @subsection CONSOLE and WINDOWS subsystems |
| |
| |
| @geindex CONSOLE Subsystem |
| |
| @geindex WINDOWS Subsystem |
| |
| @geindex -mwindows |
| |
| There are two main subsystems under Windows. The @cite{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 @cite{WINDOWS} subsystem. To do so |
| the @emph{-mwindows} linker option must be specified. |
| |
| @quotation |
| |
| @example |
| $ gnatmake winprog -largs -mwindows |
| @end example |
| @end quotation |
| |
| @node Temporary Files,Mixed-Language Programming on Windows,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics |
| @anchor{gnat_ugn/platform_specific_information id13}@anchor{271}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{272} |
| @subsection Temporary Files |
| |
| |
| @geindex Temporary files |
| |
| It is possible to control where temporary files gets created by setting |
| the |
| @geindex TMP |
| @geindex environment variable; TMP |
| @code{TMP} environment variable. The file will be created: |
| |
| |
| @itemize * |
| |
| @item |
| Under the directory pointed to by the |
| @geindex TMP |
| @geindex environment variable; TMP |
| @code{TMP} environment variable if |
| this directory exists. |
| |
| @item |
| Under @code{c:\temp}, if the |
| @geindex TMP |
| @geindex environment variable; TMP |
| @code{TMP} environment variable is not |
| set (or not pointing to a directory) and if this directory exists. |
| |
| @item |
| Under the current working directory otherwise. |
| @end itemize |
| |
| 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. |
| |
| @node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Temporary Files,Microsoft Windows Topics |
| @anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{273}@anchor{gnat_ugn/platform_specific_information id14}@anchor{274} |
| @subsection 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 @emph{gcc} or Microsoft C 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 do want |
| to use the Microsoft tools for your C++ code, you have two choices: |
| |
| |
| @itemize * |
| |
| @item |
| Encapsulate your C++ 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 |
| (@ref{275,,Using DLLs with GNAT}). |
| |
| @item |
| 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 |
| (@ref{276,,Building DLLs with GNAT Project files}) and use the Microsoft |
| or whatever environment to build your executable. |
| @end itemize |
| |
| In addition to the description about C main in |
| @ref{46,,Mixed Language Programming} section, if the C main uses a |
| stand-alone library it is required on x86-windows to |
| setup the SEH context. For this the C main must looks like this: |
| |
| @quotation |
| |
| @example |
| /* main.c */ |
| extern void adainit (void); |
| extern void adafinal (void); |
| extern void __gnat_initialize(void*); |
| extern void call_to_ada (void); |
| |
| int main (int argc, char *argv[]) |
| @{ |
| int SEH [2]; |
| |
| /* Initialize the SEH context */ |
| __gnat_initialize (&SEH); |
| |
| adainit(); |
| |
| /* Then call Ada services in the stand-alone library */ |
| |
| call_to_ada(); |
| |
| adafinal(); |
| @} |
| @end example |
| @end quotation |
| |
| Note that this is not needed on x86_64-windows where the Windows |
| native SEH support is used. |
| |
| @menu |
| * Windows Calling Conventions:: |
| * Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs. |
| * Using DLLs with GNAT:: |
| * Building DLLs with GNAT Project files:: |
| * Building DLLs with GNAT:: |
| * Building DLLs with gnatdll:: |
| * Ada DLLs and Finalization:: |
| * Creating a Spec for Ada DLLs:: |
| * GNAT and Windows Resources:: |
| * Using GNAT DLLs from Microsoft Visual Studio Applications:: |
| * Debugging a DLL:: |
| * Setting Stack Size from gnatlink:: |
| * Setting Heap Size from gnatlink:: |
| |
| @end menu |
| |
| @node Windows Calling Conventions,Introduction to Dynamic Link Libraries DLLs,,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{277}@anchor{gnat_ugn/platform_specific_information id15}@anchor{278} |
| @subsubsection Windows Calling Conventions |
| |
| |
| @geindex Stdcall |
| |
| @geindex APIENTRY |
| |
| This section pertain only to Win32. On Win64 there is a single native |
| calling convention. All convention specifiers are ignored on this |
| platform. |
| |
| When a subprogram @cite{F} (caller) calls a subprogram @cite{G} |
| (callee), there are several ways to push @cite{G}'s parameters on the |
| stack and there are several possible scenarios to clean up the stack |
| upon @cite{G}'s return. A calling convention is an agreed upon software |
| protocol whereby the responsibilities between the caller (@cite{F}) and |
| the callee (@cite{G}) are clearly defined. Several calling conventions |
| are available for Windows: |
| |
| |
| @itemize * |
| |
| @item |
| @cite{C} (Microsoft defined) |
| |
| @item |
| @cite{Stdcall} (Microsoft defined) |
| |
| @item |
| @cite{Win32} (GNAT specific) |
| |
| @item |
| @cite{DLL} (GNAT specific) |
| @end itemize |
| |
| @menu |
| * C Calling Convention:: |
| * Stdcall Calling Convention:: |
| * Win32 Calling Convention:: |
| * DLL Calling Convention:: |
| |
| @end menu |
| |
| @node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions |
| @anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{279}@anchor{gnat_ugn/platform_specific_information id16}@anchor{27a} |
| @subsubsection @cite{C} Calling Convention |
| |
| |
| This is the default calling convention used when interfacing to C/C++ |
| routines compiled with either @emph{gcc} or Microsoft Visual C++. |
| |
| In the @cite{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 @cite{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 @cite{C} calling convention is the name of the routine. For |
| instance the C function: |
| |
| @quotation |
| |
| @example |
| int get_val (long); |
| @end example |
| @end quotation |
| |
| should be imported from Ada as follows: |
| |
| @quotation |
| |
| @example |
| function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; |
| pragma Import (C, Get_Val, External_Name => "get_val"); |
| @end example |
| @end quotation |
| |
| Note that in this particular case the @cite{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 @cite{Link_Name} parameter |
| is missing, as in the above example, this parameter is set to be the |
| @cite{External_Name} with a leading underscore. |
| |
| When importing a variable defined in C, you should always use the @cite{C} |
| calling convention unless the object containing the variable is part of a |
| DLL (in which case you should use the @cite{Stdcall} calling |
| convention, @ref{27b,,Stdcall Calling Convention}). |
| |
| @node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions |
| @anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{27b}@anchor{gnat_ugn/platform_specific_information id17}@anchor{27c} |
| @subsubsection @cite{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 @cite{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 @cite{Stdcall} calling convention is mangled by |
| adding a leading underscore (as for the @cite{C} calling convention) and a |
| trailing @code{@@@emph{nn}}, where @cite{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 |
| @cite{Stdcall} calling convention is the name of the C routine. The leading |
| underscore and trailing @code{@@@emph{nn}} are added automatically by |
| the compiler. For instance the Win32 function: |
| |
| @quotation |
| |
| @example |
| APIENTRY int get_val (long); |
| @end example |
| @end quotation |
| |
| should be imported from Ada as follows: |
| |
| @quotation |
| |
| @example |
| 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" |
| @end example |
| @end quotation |
| |
| As for the @cite{C} calling convention, when the @cite{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: |
| |
| @quotation |
| |
| @example |
| function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; |
| pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val"); |
| @end example |
| @end quotation |
| |
| then the imported routine is @cite{_retrieve_val@@4}. However, if instead |
| of specifying the @cite{External_Name} parameter you specify the |
| @cite{Link_Name} as in the following example: |
| |
| @quotation |
| |
| @example |
| function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; |
| pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val"); |
| @end example |
| @end quotation |
| |
| then the imported routine is @cite{retrieve_val}, that is, there is no |
| decoration at all. No leading underscore and no Stdcall suffix |
| @code{@@@emph{nn}}. |
| |
| This is especially important as in some special cases a DLL's entry |
| point name lacks a trailing @code{@@@emph{nn}} while the exported |
| name generated for a call has it. |
| |
| It is also possible to import variables defined in a DLL by using an |
| import pragma for a variable. As an example, if a DLL contains a |
| variable defined as: |
| |
| @quotation |
| |
| @example |
| int my_var; |
| @end example |
| @end quotation |
| |
| then, to access this variable from Ada you should write: |
| |
| @quotation |
| |
| @example |
| My_Var : Interfaces.C.int; |
| pragma Import (Stdcall, My_Var); |
| @end example |
| @end quotation |
| |
| Note that to ease building cross-platform bindings this convention |
| will be handled as a @cite{C} calling convention on non-Windows platforms. |
| |
| @node Win32 Calling Convention,DLL Calling Convention,Stdcall Calling Convention,Windows Calling Conventions |
| @anchor{gnat_ugn/platform_specific_information id18}@anchor{27d}@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{27e} |
| @subsubsection @cite{Win32} Calling Convention |
| |
| |
| This convention, which is GNAT-specific is fully equivalent to the |
| @cite{Stdcall} calling convention described above. |
| |
| @node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions |
| @anchor{gnat_ugn/platform_specific_information id19}@anchor{27f}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{280} |
| @subsubsection @cite{DLL} Calling Convention |
| |
| |
| This convention, which is GNAT-specific is fully equivalent to the |
| @cite{Stdcall} calling convention described above. |
| |
| @node Introduction to Dynamic Link Libraries DLLs,Using DLLs with GNAT,Windows Calling Conventions,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information id20}@anchor{281}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{282} |
| @subsubsection Introduction to Dynamic Link Libraries (DLLs) |
| |
| |
| @geindex DLL |
| |
| 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 @code{API.dll}. To use the services |
| provided by @code{API.dll} you must statically link against the DLL or |
| 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 @code{API.lib}. When using GNAT this import |
| library is called either @code{libAPI.dll.a}, @code{libapi.dll.a}, |
| @code{libAPI.a} or @code{libapi.a} (names are case insensitive). |
| |
| After you have linked your application with the DLL or the import library |
| and you run your application, here is what happens: |
| |
| |
| @itemize * |
| |
| @item |
| Your application is loaded into memory. |
| |
| @item |
| The DLL @code{API.dll} is mapped into the address space of your |
| application. This means that: |
| |
| |
| @itemize - |
| |
| @item |
| The DLL will use the stack of the calling thread. |
| |
| @item |
| The DLL will use the virtual address space of the calling process. |
| |
| @item |
| The DLL will allocate memory from the virtual address space of the calling |
| process. |
| |
| @item |
| Handles (pointers) can be safely exchanged between routines in the DLL |
| routines and routines in the application using the DLL. |
| @end itemize |
| |
| @item |
| The entries in the jump table (from the import library @code{libAPI.dll.a} |
| or @code{API.lib} or automatically created when linking against a DLL) |
| which is part of your application are initialized with the addresses |
| of the routines and variables in @code{API.dll}. |
| |
| @item |
| If present in @code{API.dll}, routines @cite{DllMain} or |
| @cite{DllMainCRTStartup} are invoked. These routines typically contain |
| the initialization code needed for the well-being of the routines and |
| variables exported by the DLL. |
| @end itemize |
| |
| 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. Note that the @emph{-s} linker option (see GNU Linker |
| User's Guide) removes the debugging symbols from the DLL but the DLL can |
| still be relocated. |
| |
| 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 it is possible (but not required) to list exported routines in |
| a definition file (see @ref{283,,The Definition File}). |
| |
| @node Using DLLs with GNAT,Building DLLs with GNAT Project files,Introduction to Dynamic Link Libraries DLLs,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information id21}@anchor{284}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{275} |
| @subsubsection Using DLLs with GNAT |
| |
| |
| To use the services of a DLL, say @code{API.dll}, in your Ada application |
| you must have: |
| |
| |
| @itemize * |
| |
| @item |
| The Ada spec for the routines and/or variables you want to access in |
| @code{API.dll}. If not available this Ada spec must be built from the C/C++ |
| header files provided with the DLL. |
| |
| @item |
| The import library (@code{libAPI.dll.a} or @code{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 |
| @code{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. Note that this is optional. |
| |
| @item |
| The actual DLL, @code{API.dll}. |
| @end itemize |
| |
| Once you have all the above, to compile an Ada application that uses the |
| services of @code{API.dll} and whose main subprogram is @cite{My_Ada_App}, |
| you simply issue the command |
| |
| @quotation |
| |
| @example |
| $ gnatmake my_ada_app -largs -lAPI |
| @end example |
| @end quotation |
| |
| The argument @emph{-largs -lAPI} at the end of the @emph{gnatmake} command |
| tells the GNAT linker to look for an import library. The linker will |
| look for a library name in this specific order: |
| |
| |
| @itemize * |
| |
| @item |
| @code{libAPI.dll.a} |
| |
| @item |
| @code{API.dll.a} |
| |
| @item |
| @code{libAPI.a} |
| |
| @item |
| @code{API.lib} |
| |
| @item |
| @code{libAPI.dll} |
| |
| @item |
| @code{API.dll} |
| @end itemize |
| |
| The first three are the GNU style import libraries. The third is the |
| Microsoft style import libraries. The last two are the actual DLL names. |
| |
| Note that if the Ada package spec for @code{API.dll} contains the |
| following pragma |
| |
| @quotation |
| |
| @example |
| pragma Linker_Options ("-lAPI"); |
| @end example |
| @end quotation |
| |
| you do not have to add @emph{-largs -lAPI} at the end of the |
| @emph{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 @code{API.dll}. |
| |
| @menu |
| * Creating an Ada Spec for the DLL Services:: |
| * Creating an Import Library:: |
| |
| @end menu |
| |
| @node Creating an Ada Spec for the DLL Services,Creating an Import Library,,Using DLLs with GNAT |
| @anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{285}@anchor{gnat_ugn/platform_specific_information id22}@anchor{286} |
| @subsubsection 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 @code{API.dll} is a file @code{api.h} containing the |
| following two definitions: |
| |
| @quotation |
| |
| @example |
| int some_var; |
| int get (char *); |
| @end example |
| @end quotation |
| |
| then the equivalent Ada spec could be: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| @node Creating an Import Library,,Creating an Ada Spec for the DLL Services,Using DLLs with GNAT |
| @anchor{gnat_ugn/platform_specific_information id23}@anchor{287}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{288} |
| @subsubsection Creating an Import Library |
| |
| |
| @geindex Import library |
| |
| If a Microsoft-style import library @code{API.lib} or a GNAT-style |
| import library @code{libAPI.dll.a} or @code{libAPI.a} is available |
| with @code{API.dll} you can skip this section. You can also skip this |
| section if @code{API.dll} or @code{libAPI.dll} is built with GNU tools |
| as in this case it is possible to link directly against the |
| DLL. Otherwise read on. |
| |
| @geindex Definition file |
| @anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{283} |
| @subsubheading 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 @cite{.def} |
| suffix) has the following structure: |
| |
| @quotation |
| |
| @example |
| [LIBRARY `name`] |
| [DESCRIPTION `string`] |
| EXPORTS |
| `symbol1` |
| `symbol2` |
| ... |
| @end example |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @emph{LIBRARY `name`} |
| |
| This section, which is optional, gives the name of the DLL. |
| |
| @item @emph{DESCRIPTION `string`} |
| |
| This section, which is optional, gives a description string that will be |
| embedded in the import library. |
| |
| @item @emph{EXPORTS} |
| |
| This section gives the list of exported symbols (procedures, functions or |
| variables). For instance in the case of @code{API.dll} the @cite{EXPORTS} |
| section of @code{API.def} looks like: |
| |
| @example |
| EXPORTS |
| some_var |
| get |
| @end example |
| @end table |
| |
| Note that you must specify the correct suffix (@code{@@@emph{nn}}) |
| (see @ref{277,,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. |
| @anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{289} |
| @subsubheading Creating a Definition File Automatically |
| |
| |
| You can automatically create the definition file @code{API.def} |
| (see @ref{283,,The Definition File}) from a DLL. |
| For that use the @cite{dlltool} program as follows: |
| |
| @quotation |
| |
| @example |
| $ dlltool API.dll -z API.def --export-all-symbols |
| @end example |
| |
| Note that if some routines in the DLL have the @cite{Stdcall} convention |
| (@ref{277,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}} |
| suffix then you'll have to edit @code{api.def} to add it, and specify |
| @emph{-k} to @emph{gnatdll} when creating the import library. |
| |
| Here are some hints to find the right @code{@@@emph{nn}} suffix. |
| |
| |
| @itemize - |
| |
| @item |
| If you have the Microsoft import library (.lib), it is possible to get |
| the right symbols by using Microsoft @cite{dumpbin} tool (see the |
| corresponding Microsoft documentation for further details). |
| |
| @example |
| $ dumpbin /exports api.lib |
| @end example |
| |
| @item |
| 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. |
| @end itemize |
| @end quotation |
| @anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{28a} |
| @subsubheading GNAT-Style Import Library |
| |
| |
| To create a static import library from @code{API.dll} with the GNAT tools |
| you should create the .def file, then use @cite{gnatdll} tool |
| (see @ref{28b,,Using gnatdll}) as follows: |
| |
| @quotation |
| |
| @example |
| $ gnatdll -e API.def -d API.dll |
| @end example |
| |
| @cite{gnatdll} takes as input a definition file @code{API.def} and the |
| name of the DLL containing the services listed in the definition file |
| @code{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 @cite{xyz`}.def`, the import library name will |
| be @cite{lib`@w{`}xyz`}.a`. Note that in the previous example option |
| @emph{-e} could have been removed because the name of the definition |
| file (before the '@cite{.def}' suffix) is the same as the name of the |
| DLL (@ref{28b,,Using gnatdll} for more information about @cite{gnatdll}). |
| @end quotation |
| @anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{28c} |
| @subsubheading 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 (@ref{273,,Mixed-Language Programming on Windows}). |
| |
| To create a Microsoft-style import library for @code{API.dll} you |
| should create the .def file, then build the actual import library using |
| Microsoft's @cite{lib} utility: |
| |
| @quotation |
| |
| @example |
| $ lib -machine:IX86 -def:API.def -out:API.lib |
| @end example |
| |
| If you use the above command the definition file @code{API.def} must |
| contain a line giving the name of the DLL: |
| |
| @example |
| LIBRARY "API" |
| @end example |
| |
| See the Microsoft documentation for further details about the usage of |
| @cite{lib}. |
| @end quotation |
| |
| @node Building DLLs with GNAT Project files,Building DLLs with GNAT,Using DLLs with GNAT,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information id24}@anchor{28d}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{276} |
| @subsubsection Building DLLs with GNAT Project files |
| |
| |
| @geindex DLLs |
| @geindex building |
| |
| There is nothing specific to Windows in the build process. |
| @ref{8a,,Library Projects}. |
| |
| Due to a system limitation, it is not possible under Windows to create threads |
| when inside the @cite{DllMain} routine which is used for auto-initialization |
| of shared libraries, so it is not possible to have library level tasks in SALs. |
| |
| @node Building DLLs with GNAT,Building DLLs with gnatdll,Building DLLs with GNAT Project files,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{28e}@anchor{gnat_ugn/platform_specific_information id25}@anchor{28f} |
| @subsubsection Building DLLs with GNAT |
| |
| |
| @geindex DLLs |
| @geindex building |
| |
| This section explain how to build DLLs using the GNAT built-in DLL |
| support. With the following procedure it is straight forward to build |
| and use DLLs with GNAT. |
| |
| |
| @itemize * |
| |
| @item |
| Building object files. |
| The first step is to build all objects files that are to be included |
| into the DLL. This is done by using the standard @emph{gnatmake} tool. |
| |
| @item |
| Building the DLL. |
| To build the DLL you must use @emph{gcc}'s @emph{-shared} and |
| @emph{-shared-libgcc} options. It is quite simple to use this method: |
| |
| @example |
| $ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ... |
| @end example |
| |
| It is important to note that in this case all symbols found in the |
| object files are automatically exported. It is possible to restrict |
| the set of symbols to export by passing to @emph{gcc} a definition |
| file (see @ref{283,,The Definition File}). |
| For example: |
| |
| @example |
| $ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ... |
| @end example |
| |
| If you use a definition file you must export the elaboration procedures |
| for every package that required one. Elaboration procedures are named |
| using the package name followed by "_E". |
| |
| @item |
| Preparing DLL to be used. |
| For the DLL to be used by client programs the bodies must be hidden |
| from it and the .ali set with read-only attribute. This is very important |
| otherwise GNAT will recompile all packages and will not actually use |
| the code in the DLL. For example: |
| |
| @example |
| $ mkdir apilib |
| $ copy *.ads *.ali api.dll apilib |
| $ attrib +R apilib\\*.ali |
| @end example |
| @end itemize |
| |
| At this point it is possible to use the DLL by directly linking |
| against it. Note that you must use the GNAT shared runtime when using |
| GNAT shared libraries. This is achieved by using @emph{-shared} binder's |
| option. |
| |
| @quotation |
| |
| @example |
| $ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI |
| @end example |
| @end quotation |
| |
| @node Building DLLs with gnatdll,Ada DLLs and Finalization,Building DLLs with GNAT,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{290}@anchor{gnat_ugn/platform_specific_information id26}@anchor{291} |
| @subsubsection Building DLLs with gnatdll |
| |
| |
| @geindex DLLs |
| @geindex building |
| |
| Note that it is preferred to use GNAT Project files |
| (@ref{276,,Building DLLs with GNAT Project files}) or the built-in GNAT |
| DLL support (@ref{28e,,Building DLLs with GNAT}) or to build DLLs. |
| |
| This section explains how to build DLLs containing Ada code using |
| @cite{gnatdll}. 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: |
| |
| |
| @itemize * |
| |
| @item |
| You need to mark each Ada @emph{entity} exported by the DLL with a @cite{C} or |
| @cite{Stdcall} calling convention to avoid any Ada name mangling for the |
| entities exported by the DLL |
| (see @ref{292,,Exporting Ada Entities}). You can |
| skip this step if you plan to use the Ada DLL only from Ada applications. |
| |
| @item |
| Your Ada code must export an initialization routine which calls the routine |
| @cite{adainit} generated by @emph{gnatbind} to perform the elaboration of |
| the Ada code in the DLL (@ref{293,,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. |
| |
| @item |
| When useful, the DLL should also export a finalization routine which calls |
| routine @cite{adafinal} generated by @emph{gnatbind} to perform the |
| finalization of the Ada code in the DLL (@ref{294,,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. |
| |
| @item |
| 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. |
| |
| @item |
| You must provide a definition file listing the exported entities |
| (@ref{283,,The Definition File}). |
| |
| @item |
| Finally you must use @cite{gnatdll} to produce the DLL and the import |
| library (@ref{28b,,Using gnatdll}). |
| @end itemize |
| |
| Note that a relocatable DLL stripped using the @cite{strip} |
| binutils tool will not be relocatable anymore. To build a DLL without |
| debug information pass @cite{-largs -s} to @cite{gnatdll}. This |
| restriction does not apply to a DLL built using a Library Project. |
| See @ref{8a,,Library Projects}. |
| |
| @c Limitations_When_Using_Ada_DLLs_from Ada: |
| |
| @menu |
| * Limitations When Using Ada DLLs from Ada:: |
| * Exporting Ada Entities:: |
| * Ada DLLs and Elaboration:: |
| |
| @end menu |
| |
| @node Limitations When Using Ada DLLs from Ada,Exporting Ada Entities,,Building DLLs with gnatdll |
| @anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{295} |
| @subsubsection 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., @cite{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. |
| |
| @node Exporting Ada Entities,Ada DLLs and Elaboration,Limitations When Using Ada DLLs from Ada,Building DLLs with gnatdll |
| @anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{292}@anchor{gnat_ugn/platform_specific_information id27}@anchor{296} |
| @subsubsection Exporting Ada Entities |
| |
| |
| @geindex Export table |
| |
| 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 @cite{C} or @cite{Stdcall} calling conventions to avoid |
| any Ada name mangling. As an example here is an Ada package |
| @cite{API}, spec and body, exporting two procedures, a function, and a |
| variable: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| If the Ada DLL you are building will only be used by Ada applications |
| you do not have to export Ada entities with a @cite{C} or @cite{Stdcall} |
| convention. As an example, the previous package could be written as |
| follows: |
| |
| @quotation |
| |
| @example |
| package API is |
| Count : Integer := 0; |
| function Factorial (Val : Integer) return Integer; |
| |
| procedure Initialize_API; |
| procedure Finalize_API; |
| -- Initialization and Finalization routines. |
| end API; |
| @end example |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| Note that if you do not export the Ada entities with a @cite{C} or |
| @cite{Stdcall} convention you will have to provide the mangled Ada names |
| in the definition file of the Ada DLL |
| (@ref{297,,Creating the Definition File}). |
| |
| @node Ada DLLs and Elaboration,,Exporting Ada Entities,Building DLLs with gnatdll |
| @anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{293}@anchor{gnat_ugn/platform_specific_information id28}@anchor{298} |
| @subsubsection Ada DLLs and Elaboration |
| |
| |
| @geindex 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 |
| (@ref{11,,Elaboration Order Handling in GNAT}). |
| |
| To achieve this you must export an initialization routine |
| (@cite{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 @cite{adainit} generated by the GNAT binder |
| (@ref{ba,,Binding with Non-Ada Main Programs}). See the body of |
| @cite{Initialize_Api} for an example. Note that the GNAT binder is |
| automatically invoked during the DLL build process by the @cite{gnatdll} |
| tool (@ref{28b,,Using gnatdll}). |
| |
| When a DLL is loaded, Windows systematically invokes a routine called |
| @cite{DllMain}. It would therefore be possible to call @cite{adainit} |
| directly from @cite{DllMain} without having to provide an explicit |
| initialization routine. Unfortunately, it is not possible to call |
| @cite{adainit} from the @cite{DllMain} if your program has library level |
| tasks because access to the @cite{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. |
| |
| @node Ada DLLs and Finalization,Creating a Spec for Ada DLLs,Building DLLs with gnatdll,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information id29}@anchor{299}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{294} |
| @subsubsection Ada DLLs and Finalization |
| |
| |
| @geindex 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 @cite{adafinal} generated by the GNAT binder |
| (@ref{ba,,Binding with Non-Ada Main Programs}). |
| See the body of @cite{Finalize_Api} for an |
| example. As already pointed out the GNAT binder is automatically invoked |
| during the DLL build process by the @cite{gnatdll} tool |
| (@ref{28b,,Using gnatdll}). |
| |
| @node Creating a Spec for Ada DLLs,GNAT and Windows Resources,Ada DLLs and Finalization,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information id30}@anchor{29a}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{29b} |
| @subsubsection 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 @cite{API.dll}, |
| the corresponding C header file could look like: |
| |
| @quotation |
| |
| @example |
| extern int *_imp__count; |
| #define count (*_imp__count) |
| int factorial (int); |
| @end example |
| @end quotation |
| |
| 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 @cite{DLL} calling convention is needed to |
| use a variable defined in a DLL, but when building the DLL, the variable |
| must have either the @cite{Ada} or @cite{C} calling convention. As an |
| example consider a DLL comprising the following package @cite{API}: |
| |
| @quotation |
| |
| @example |
| package API is |
| Count : Integer := 0; |
| ... |
| -- Remainder of the package omitted. |
| end API; |
| @end example |
| @end quotation |
| |
| After producing a DLL containing package @cite{API}, the spec that |
| must be used to import @cite{API.Count} from Ada code outside of the |
| DLL is: |
| |
| @quotation |
| |
| @example |
| package API is |
| Count : Integer; |
| pragma Import (DLL, Count); |
| end API; |
| @end example |
| @end quotation |
| |
| @menu |
| * Creating the Definition File:: |
| * Using gnatdll:: |
| |
| @end menu |
| |
| @node Creating the Definition File,Using gnatdll,,Creating a Spec for Ada DLLs |
| @anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{297}@anchor{gnat_ugn/platform_specific_information id31}@anchor{29c} |
| @subsubsection 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 @cite{API} (where all the entities are exported |
| with a @cite{C} calling convention) is: |
| |
| @quotation |
| |
| @example |
| EXPORTS |
| count |
| factorial |
| finalize_api |
| initialize_api |
| @end example |
| @end quotation |
| |
| If the @cite{C} calling convention is missing from package @cite{API}, |
| then the definition file contains the mangled Ada names of the above |
| entities, which in this case are: |
| |
| @quotation |
| |
| @example |
| EXPORTS |
| api__count |
| api__factorial |
| api__finalize_api |
| api__initialize_api |
| @end example |
| @end quotation |
| |
| @node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs |
| @anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{28b}@anchor{gnat_ugn/platform_specific_information id32}@anchor{29d} |
| @subsubsection Using @cite{gnatdll} |
| |
| |
| @geindex gnatdll |
| |
| @cite{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. |
| @cite{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 |
| @cite{gnatdll} command is |
| |
| @quotation |
| |
| @example |
| $ gnatdll [`switches`] `list-of-files` [-largs `opts`] |
| @end example |
| @end quotation |
| |
| where @cite{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 @cite{list-of-files} is |
| missing, only the static import library is generated. |
| |
| You may specify any of the following switches to @cite{gnatdll}: |
| |
| @quotation |
| |
| @geindex -a (gnatdll) |
| @end quotation |
| |
| |
| @table @asis |
| |
| @item @code{-a[@emph{address}]} |
| |
| Build a non-relocatable DLL at @cite{address}. If @cite{address} is not |
| specified the default address @cite{0x11000000} will be used. By default, |
| when this switch is missing, @cite{gnatdll} builds relocatable DLL. We |
| advise the reader to build relocatable DLL. |
| |
| @geindex -b (gnatdll) |
| |
| @item @code{-b @emph{address}} |
| |
| Set the relocatable DLL base address. By default the address is |
| @cite{0x11000000}. |
| |
| @geindex -bargs (gnatdll) |
| |
| @item @code{-bargs @emph{opts}} |
| |
| Binder options. Pass @cite{opts} to the binder. |
| |
| @geindex -d (gnatdll) |
| |
| @item @code{-d @emph{dllfile}} |
| |
| @cite{dllfile} is the name of the DLL. This switch must be present for |
| @cite{gnatdll} to do anything. The name of the generated import library is |
| obtained algorithmically from @cite{dllfile} as shown in the following |
| example: if @cite{dllfile} is @cite{xyz.dll}, the import library name is |
| @cite{libxyz.dll.a}. The name of the definition file to use (if not specified |
| by option @emph{-e}) is obtained algorithmically from @cite{dllfile} |
| as shown in the following example: |
| if @cite{dllfile} is @cite{xyz.dll}, the definition |
| file used is @cite{xyz.def}. |
| |
| @geindex -e (gnatdll) |
| |
| @item @code{-e @emph{deffile}} |
| |
| @cite{deffile} is the name of the definition file. |
| |
| @geindex -g (gnatdll) |
| |
| @item @code{-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 |
| @emph{-g} switch if you plan on using the debugger or the symbolic |
| stack traceback. |
| |
| @geindex -h (gnatdll) |
| |
| @item @code{-h} |
| |
| Help mode. Displays @cite{gnatdll} switch usage information. |
| |
| @geindex -I (gnatdll) |
| |
| @item @code{-I@emph{dir}} |
| |
| Direct @cite{gnatdll} to search the @cite{dir} directory for source and |
| object files needed to build the DLL. |
| (@ref{8e,,Search Paths and the Run-Time Library (RTL)}). |
| |
| @geindex -k (gnatdll) |
| |
| @item @code{-k} |
| |
| Removes the @code{@@@emph{nn}} suffix from the import library's exported |
| names, but keeps them for the link names. You must specify this |
| option if you want to use a @cite{Stdcall} function in a DLL for which |
| the @code{@@@emph{nn}} suffix has been removed. This is the case for most |
| of the Windows NT DLL for example. This option has no effect when |
| @emph{-n} option is specified. |
| |
| @geindex -l (gnatdll) |
| |
| @item @code{-l @emph{file}} |
| |
| The list of ALI and object files used to build the DLL are listed in |
| @cite{file}, instead of being given in the command line. Each line in |
| @cite{file} contains the name of an ALI or object file. |
| |
| @geindex -n (gnatdll) |
| |
| @item @code{-n} |
| |
| No Import. Do not create the import library. |
| |
| @geindex -q (gnatdll) |
| |
| @item @code{-q} |
| |
| Quiet mode. Do not display unnecessary messages. |
| |
| @geindex -v (gnatdll) |
| |
| @item @code{-v} |
| |
| Verbose mode. Display extra information. |
| |
| @geindex -largs (gnatdll) |
| |
| @item @code{-largs @emph{opts}} |
| |
| Linker options. Pass @cite{opts} to the linker. |
| @end table |
| |
| @subsubheading @cite{gnatdll} Example |
| |
| |
| As an example the command to build a relocatable DLL from @code{api.adb} |
| once @code{api.adb} has been compiled and @code{api.def} created is |
| |
| @quotation |
| |
| @example |
| $ gnatdll -d api.dll api.ali |
| @end example |
| @end quotation |
| |
| The above command creates two files: @code{libapi.dll.a} (the import |
| library) and @code{api.dll} (the actual DLL). If you want to create |
| only the DLL, just type: |
| |
| @quotation |
| |
| @example |
| $ gnatdll -d api.dll -n api.ali |
| @end example |
| @end quotation |
| |
| Alternatively if you want to create just the import library, type: |
| |
| @quotation |
| |
| @example |
| $ gnatdll -d api.dll |
| @end example |
| @end quotation |
| |
| @subsubheading @cite{gnatdll} behind the Scenes |
| |
| |
| This section details the steps involved in creating a DLL. @cite{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 @cite{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 @code{api.o} and |
| @code{api.ali} are available. To build a relocatable DLL, @cite{gnatdll} does |
| the following: |
| |
| |
| @itemize * |
| |
| @item |
| @cite{gnatdll} builds the base file (@code{api.base}). A base file gives |
| the information necessary to generate relocation information for the |
| DLL. |
| |
| @example |
| $ gnatbind -n api |
| $ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base |
| @end example |
| |
| In addition to the base file, the @emph{gnatlink} command generates an |
| output file @code{api.jnk} which can be discarded. The @emph{-mdll} switch |
| asks @emph{gnatlink} to generate the routines @cite{DllMain} and |
| @cite{DllMainCRTStartup} that are called by the Windows loader when the DLL |
| is loaded into memory. |
| |
| @item |
| @cite{gnatdll} uses @cite{dlltool} (see @ref{29e,,Using dlltool}) to build the |
| export table (@code{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. |
| |
| @example |
| $ dlltool --dllname api.dll --def api.def --base-file api.base \\ |
| --output-exp api.exp |
| @end example |
| |
| @item |
| @cite{gnatdll} builds the base file using the new export table. Note that |
| @emph{gnatbind} must be called once again since the binder generated file |
| has been deleted during the previous call to @emph{gnatlink}. |
| |
| @example |
| $ gnatbind -n api |
| $ gnatlink api -o api.jnk api.exp -mdll |
| -Wl,--base-file,api.base |
| @end example |
| |
| @item |
| @cite{gnatdll} builds the new export table using the new base file and |
| generates the DLL import library @code{libAPI.dll.a}. |
| |
| @example |
| $ dlltool --dllname api.dll --def api.def --base-file api.base \\ |
| --output-exp api.exp --output-lib libAPI.a |
| @end example |
| |
| @item |
| Finally @cite{gnatdll} builds the relocatable DLL using the final export |
| table. |
| |
| @example |
| $ gnatbind -n api |
| $ gnatlink api api.exp -o api.dll -mdll |
| @end example |
| @end itemize |
| @anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{29e} |
| @subsubheading Using @cite{dlltool} |
| |
| |
| @cite{dlltool} is the low-level tool used by @cite{gnatdll} to build |
| DLLs and static import libraries. This section summarizes the most |
| common @cite{dlltool} switches. The form of the @cite{dlltool} command |
| is |
| |
| @quotation |
| |
| @example |
| $ dlltool [`switches`] |
| @end example |
| @end quotation |
| |
| @cite{dlltool} switches include: |
| |
| @geindex --base-file (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{--base-file @emph{basefile}} |
| |
| Read the base file @cite{basefile} generated by the linker. This switch |
| is used to create a relocatable DLL. |
| @end table |
| |
| @geindex --def (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{--def @emph{deffile}} |
| |
| Read the definition file. |
| @end table |
| |
| @geindex --dllname (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{--dllname @emph{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 @cite{dlltool} with switch |
| @emph{--output-lib}. |
| @end table |
| |
| @geindex -k (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{-k} |
| |
| Kill @code{@@@emph{nn}} from exported names |
| (@ref{277,,Windows Calling Conventions} |
| for a discussion about @cite{Stdcall}-style symbols. |
| @end table |
| |
| @geindex --help (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{--help} |
| |
| Prints the @cite{dlltool} switches with a concise description. |
| @end table |
| |
| @geindex --output-exp (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{--output-exp @emph{exportfile}} |
| |
| Generate an export file @cite{exportfile}. The export file contains the |
| export table (list of symbols in the DLL) and is used to create the DLL. |
| @end table |
| |
| @geindex --output-lib (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{--output-lib @emph{libfile}} |
| |
| Generate a static import library @cite{libfile}. |
| @end table |
| |
| @geindex -v (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{-v} |
| |
| Verbose mode. |
| @end table |
| |
| @geindex --as (dlltool) |
| |
| |
| @table @asis |
| |
| @item @code{--as @emph{assembler-name}} |
| |
| Use @cite{assembler-name} as the assembler. The default is @cite{as}. |
| @end table |
| |
| @node GNAT and Windows Resources,Using GNAT DLLs from Microsoft Visual Studio Applications,Creating a Spec for Ada DLLs,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{29f}@anchor{gnat_ugn/platform_specific_information id33}@anchor{2a0} |
| @subsubsection GNAT and Windows Resources |
| |
| |
| @geindex Resources |
| @geindex windows |
| |
| Resources are an easy way to add Windows specific objects to your |
| application. The objects that can be added as resources include: |
| |
| |
| @itemize * |
| |
| @item |
| menus |
| |
| @item |
| accelerators |
| |
| @item |
| dialog boxes |
| |
| @item |
| string tables |
| |
| @item |
| bitmaps |
| |
| @item |
| cursors |
| |
| @item |
| icons |
| |
| @item |
| fonts |
| |
| @item |
| version information |
| @end itemize |
| |
| For example, a version information resource can be defined as follow and |
| embedded into an executable or DLL: |
| |
| A version information resource can be used to embed information into an |
| executable or a DLL. These information can be viewed using the file properties |
| from the Windows Explorer. Here is an example of a version information |
| resource: |
| |
| @quotation |
| |
| @example |
| 1 VERSIONINFO |
| FILEVERSION 1,0,0,0 |
| PRODUCTVERSION 1,0,0,0 |
| BEGIN |
| BLOCK "StringFileInfo" |
| BEGIN |
| BLOCK "080904E4" |
| BEGIN |
| VALUE "CompanyName", "My Company Name" |
| VALUE "FileDescription", "My application" |
| VALUE "FileVersion", "1.0" |
| VALUE "InternalName", "my_app" |
| VALUE "LegalCopyright", "My Name" |
| VALUE "OriginalFilename", "my_app.exe" |
| VALUE "ProductName", "My App" |
| VALUE "ProductVersion", "1.0" |
| END |
| END |
| |
| BLOCK "VarFileInfo" |
| BEGIN |
| VALUE "Translation", 0x809, 1252 |
| END |
| END |
| @end example |
| @end quotation |
| |
| The value @cite{0809} (langID) is for the U.K English language and |
| @cite{04E4} (charsetID), which is equal to @cite{1252} decimal, for |
| multilingual. |
| |
| This section explains how to build, compile and use resources. Note that this |
| section does not cover all resource objects, for a complete description see |
| the corresponding Microsoft documentation. |
| |
| @menu |
| * Building Resources:: |
| * Compiling Resources:: |
| * Using Resources:: |
| |
| @end menu |
| |
| @node Building Resources,Compiling Resources,,GNAT and Windows Resources |
| @anchor{gnat_ugn/platform_specific_information building-resources}@anchor{2a1}@anchor{gnat_ugn/platform_specific_information id34}@anchor{2a2} |
| @subsubsection Building Resources |
| |
| |
| @geindex Resources |
| @geindex building |
| |
| A resource file is an ASCII file. By convention resource files have an |
| @code{.rc} extension. |
| The easiest way to build a resource file is to use Microsoft tools |
| such as @cite{imagedit.exe} to build bitmaps, icons and cursors and |
| @cite{dlgedit.exe} to build dialogs. |
| It is always possible to build an @code{.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. |
| |
| @node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources |
| @anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{2a3}@anchor{gnat_ugn/platform_specific_information id35}@anchor{2a4} |
| @subsubsection Compiling Resources |
| |
| |
| @geindex rc |
| |
| @geindex windres |
| |
| @geindex Resources |
| @geindex compiling |
| |
| This section describes how to build a GNAT-compatible (COFF) object file |
| containing the resources. This is done using the Resource Compiler |
| @cite{windres} as follows: |
| |
| @quotation |
| |
| @example |
| $ windres -i myres.rc -o myres.o |
| @end example |
| @end quotation |
| |
| By default @cite{windres} will run @emph{gcc} to preprocess the @code{.rc} |
| file. You can specify an alternate preprocessor (usually named |
| @code{cpp.exe}) using the @cite{windres} @emph{--preprocessor} |
| parameter. A list of all possible options may be obtained by entering |
| the command @cite{windres} @emph{--help}. |
| |
| It is also possible to use the Microsoft resource compiler @cite{rc.exe} |
| to produce a @code{.res} file (binary resource file). See the |
| corresponding Microsoft documentation for further details. In this case |
| you need to use @cite{windres} to translate the @code{.res} file to a |
| GNAT-compatible object file as follows: |
| |
| @quotation |
| |
| @example |
| $ windres -i myres.res -o myres.o |
| @end example |
| @end quotation |
| |
| @node Using Resources,,Compiling Resources,GNAT and Windows Resources |
| @anchor{gnat_ugn/platform_specific_information id36}@anchor{2a5}@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{2a6} |
| @subsubsection Using Resources |
| |
| |
| @geindex Resources |
| @geindex using |
| |
| To include the resource file in your program just add the |
| GNAT-compatible object file for the resource(s) to the linker |
| arguments. With @emph{gnatmake} this is done by using the @emph{-largs} |
| option: |
| |
| @quotation |
| |
| @example |
| $ gnatmake myprog -largs myres.o |
| @end example |
| @end quotation |
| |
| @node Using GNAT DLLs from Microsoft Visual Studio Applications,Debugging a DLL,GNAT and Windows Resources,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{2a7}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{2a8} |
| @subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications |
| |
| |
| @geindex Microsoft Visual Studio |
| @geindex use with GNAT DLLs |
| |
| This section describes a common case of mixed GNAT/Microsoft Visual Studio |
| application development, where the main program is developed using MSVS, and |
| is linked with a DLL developed using GNAT. Such a mixed application should |
| be developed following the general guidelines outlined above; below is the |
| cookbook-style sequence of steps to follow: |
| |
| |
| @enumerate |
| |
| @item |
| First develop and build the GNAT shared library using a library project |
| (let's assume the project is @cite{mylib.gpr}, producing the library @cite{libmylib.dll}): |
| @end enumerate |
| |
| @quotation |
| |
| @example |
| $ gprbuild -p mylib.gpr |
| @end example |
| @end quotation |
| |
| |
| @enumerate 2 |
| |
| @item |
| Produce a .def file for the symbols you need to interface with, either by |
| hand or automatically with possibly some manual adjustments |
| (see @ref{289,,Creating Definition File Automatically}): |
| @end enumerate |
| |
| @quotation |
| |
| @example |
| $ dlltool libmylib.dll -z libmylib.def --export-all-symbols |
| @end example |
| @end quotation |
| |
| |
| @enumerate 3 |
| |
| @item |
| Make sure that MSVS command-line tools are accessible on the path. |
| |
| @item |
| Create the Microsoft-style import library (see @ref{28c,,MSVS-Style Import Library}): |
| @end enumerate |
| |
| @quotation |
| |
| @example |
| $ lib -machine:IX86 -def:libmylib.def -out:libmylib.lib |
| @end example |
| @end quotation |
| |
| If you are using a 64-bit toolchain, the above becomes... |
| |
| @quotation |
| |
| @example |
| $ lib -machine:X64 -def:libmylib.def -out:libmylib.lib |
| @end example |
| @end quotation |
| |
| |
| @enumerate 5 |
| |
| @item |
| Build the C main |
| @end enumerate |
| |
| @quotation |
| |
| @example |
| $ cl /O2 /MD main.c libmylib.lib |
| @end example |
| @end quotation |
| |
| |
| @enumerate 6 |
| |
| @item |
| Before running the executable, make sure you have set the PATH to the DLL, |
| or copy the DLL into into the directory containing the .exe. |
| @end enumerate |
| |
| @node Debugging a DLL,Setting Stack Size from gnatlink,Using GNAT DLLs from Microsoft Visual Studio Applications,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information id37}@anchor{2a9}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{2aa} |
| @subsubsection Debugging a DLL |
| |
| |
| @geindex DLL debugging |
| |
| 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: |
| |
| |
| @itemize * |
| |
| @item |
| The program and the DLL are built with @cite{GCC/GNAT}. |
| |
| @item |
| The program is built with foreign tools and the DLL is built with |
| @cite{GCC/GNAT}. |
| |
| @item |
| The program is built with @cite{GCC/GNAT} and the DLL is built with |
| foreign tools. |
| @end itemize |
| |
| In this section we address only cases one and two above. |
| There is no point in trying to debug |
| a DLL with @cite{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. |
| |
| @menu |
| * Program and DLL Both Built with GCC/GNAT:: |
| * Program Built with Foreign Tools and DLL Built with GCC/GNAT:: |
| |
| @end menu |
| |
| @node Program and DLL Both Built with GCC/GNAT,Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Debugging a DLL |
| @anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{2ab}@anchor{gnat_ugn/platform_specific_information id38}@anchor{2ac} |
| @subsubsection Program and DLL Both Built with GCC/GNAT |
| |
| |
| This is the simplest case. Both the DLL and the program have @cite{GDB} |
| compatible debugging information. It is then possible to break anywhere in |
| the process. Let's suppose here that the main procedure is named |
| @cite{ada_main} and that in the DLL there is an entry point named |
| @cite{ada_dll}. |
| |
| The DLL (@ref{282,,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: |
| |
| |
| @itemize * |
| |
| @item |
| Launch @cite{GDB} on the main program. |
| |
| @example |
| $ gdb -nw ada_main |
| @end example |
| |
| @item |
| Start the program and stop at the beginning of the main procedure |
| |
| @example |
| (gdb) start |
| @end example |
| |
| 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. |
| |
| @item |
| Set a breakpoint inside the DLL |
| |
| @example |
| (gdb) break ada_dll |
| (gdb) cont |
| @end example |
| @end itemize |
| |
| At this stage a breakpoint is set inside the DLL. From there on |
| you can use the standard approach to debug the whole program |
| (@ref{26,,Running and Debugging Ada Programs}). |
| |
| @node Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Program and DLL Both Built with GCC/GNAT,Debugging a DLL |
| @anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{2ad}@anchor{gnat_ugn/platform_specific_information id39}@anchor{2ae} |
| @subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT |
| |
| |
| 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 @cite{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 @cite{main} (this is for |
| example some C code built with Microsoft Visual C) and that there is a |
| DLL named @cite{test.dll} containing an Ada entry point named |
| @cite{ada_dll}. |
| |
| The DLL (see @ref{282,,Introduction to Dynamic Link Libraries (DLLs)}) must have |
| been built with debugging information (see GNAT @cite{-g} option). |
| |
| @subsubheading Debugging the DLL Directly |
| |
| |
| |
| @itemize * |
| |
| @item |
| Find out the executable starting address |
| |
| @example |
| $ objdump --file-header main.exe |
| @end example |
| |
| The starting address is reported on the last line. For example: |
| |
| @example |
| main.exe: file format pei-i386 |
| architecture: i386, flags 0x0000010a: |
| EXEC_P, HAS_DEBUG, D_PAGED |
| start address 0x00401010 |
| @end example |
| |
| @item |
| Launch the debugger on the executable. |
| |
| @example |
| $ gdb main.exe |
| @end example |
| |
| @item |
| Set a breakpoint at the starting address, and launch the program. |
| |
| @example |
| $ (gdb) break *0x00401010 |
| $ (gdb) run |
| @end example |
| |
| The program will stop at the given address. |
| |
| @item |
| Set a breakpoint on a DLL subroutine. |
| |
| @example |
| (gdb) break ada_dll.adb:45 |
| @end example |
| |
| Or if you want to break using a symbol on the DLL, you need first to |
| select the Ada language (language used by the DLL). |
| |
| @example |
| (gdb) set language ada |
| (gdb) break ada_dll |
| @end example |
| |
| @item |
| Continue the program. |
| |
| @example |
| (gdb) cont |
| @end example |
| |
| 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 (@ref{26,,Running and Debugging Ada Programs}). |
| @end itemize |
| |
| It is also possible to debug the DLL by attaching to a running process. |
| |
| @subsubheading Attaching to a Running Process |
| |
| |
| @geindex DLL debugging |
| @geindex attach to process |
| |
| With @cite{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. |
| |
| |
| @itemize * |
| |
| @item |
| Launch the main program @code{main.exe}. |
| |
| @example |
| $ main |
| @end example |
| |
| @item |
| Use the Windows @emph{Task Manager} to find the process ID. Let's say |
| that the process PID for @code{main.exe} is 208. |
| |
| @item |
| Launch gdb. |
| |
| @example |
| $ gdb |
| @end example |
| |
| @item |
| Attach to the running process to be debugged. |
| |
| @example |
| (gdb) attach 208 |
| @end example |
| |
| @item |
| Load the process debugging information. |
| |
| @example |
| (gdb) symbol-file main.exe |
| @end example |
| |
| @item |
| Break somewhere in the DLL. |
| |
| @example |
| (gdb) break ada_dll |
| @end example |
| |
| @item |
| Continue process execution. |
| |
| @example |
| (gdb) cont |
| @end example |
| @end itemize |
| |
| 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 |
| @ref{26,,Running and Debugging Ada Programs}. |
| |
| @node Setting Stack Size from gnatlink,Setting Heap Size from gnatlink,Debugging a DLL,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{13d}@anchor{gnat_ugn/platform_specific_information id40}@anchor{2af} |
| @subsubsection Setting Stack Size from @emph{gnatlink} |
| |
| |
| It is possible to specify the program stack size at link time. On modern |
| versions of Windows, starting with XP, this is mostly useful to set the size of |
| the main stack (environment task). The other task stacks are set with pragma |
| Storage_Size or with the @emph{gnatbind -d} command. |
| |
| Since older versions of Windows (2000, NT4, etc.) do not allow setting the |
| reserve size of individual tasks, the link-time stack size applies to all |
| tasks, and pragma Storage_Size has no effect. |
| In particular, Stack Overflow checks are made against this |
| link-time specified size. |
| |
| This setting can be done with @emph{gnatlink} using either of the following: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{-Xlinker} linker option |
| |
| @example |
| $ gnatlink hello -Xlinker --stack=0x10000,0x1000 |
| @end example |
| |
| This sets the stack reserve size to 0x10000 bytes and the stack commit |
| size to 0x1000 bytes. |
| |
| @item |
| @emph{-Wl} linker option |
| |
| @example |
| $ gnatlink hello -Wl,--stack=0x1000000 |
| @end example |
| |
| This sets the stack reserve size to 0x1000000 bytes. Note that with |
| @emph{-Wl} option it is not possible to set the stack commit size |
| because the coma is a separator for this option. |
| @end itemize |
| |
| @node Setting Heap Size from gnatlink,,Setting Stack Size from gnatlink,Mixed-Language Programming on Windows |
| @anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{13e}@anchor{gnat_ugn/platform_specific_information id41}@anchor{2b0} |
| @subsubsection Setting Heap Size from @emph{gnatlink} |
| |
| |
| Under Windows systems, it is possible to specify the program heap size from |
| @emph{gnatlink} using either of the following: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{-Xlinker} linker option |
| |
| @example |
| $ gnatlink hello -Xlinker --heap=0x10000,0x1000 |
| @end example |
| |
| This sets the heap reserve size to 0x10000 bytes and the heap commit |
| size to 0x1000 bytes. |
| |
| @item |
| @emph{-Wl} linker option |
| |
| @example |
| $ gnatlink hello -Wl,--heap=0x1000000 |
| @end example |
| |
| This sets the heap reserve size to 0x1000000 bytes. Note that with |
| @emph{-Wl} option it is not possible to set the heap commit size |
| because the coma is a separator for this option. |
| @end itemize |
| |
| @node Windows Specific Add-Ons,,Mixed-Language Programming on Windows,Microsoft Windows Topics |
| @anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{2b1}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{2b2} |
| @subsection Windows Specific Add-Ons |
| |
| |
| This section describes the Windows specific add-ons. |
| |
| @menu |
| * Win32Ada:: |
| * wPOSIX:: |
| |
| @end menu |
| |
| @node Win32Ada,wPOSIX,,Windows Specific Add-Ons |
| @anchor{gnat_ugn/platform_specific_information win32ada}@anchor{2b3}@anchor{gnat_ugn/platform_specific_information id42}@anchor{2b4} |
| @subsubsection Win32Ada |
| |
| |
| Win32Ada is a binding for the Microsoft Win32 API. This binding can be |
| easily installed from the provided installer. To use the Win32Ada |
| binding you need to use a project file, and adding a single with_clause |
| will give you full access to the Win32Ada binding sources and ensure |
| that the proper libraries are passed to the linker. |
| |
| @quotation |
| |
| @example |
| with "win32ada"; |
| project P is |
| for Sources use ...; |
| end P; |
| @end example |
| @end quotation |
| |
| To build the application you just need to call gprbuild for the |
| application's project, here p.gpr: |
| |
| @quotation |
| |
| @example |
| gprbuild p.gpr |
| @end example |
| @end quotation |
| |
| @node wPOSIX,,Win32Ada,Windows Specific Add-Ons |
| @anchor{gnat_ugn/platform_specific_information id43}@anchor{2b5}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{2b6} |
| @subsubsection wPOSIX |
| |
| |
| wPOSIX is a minimal POSIX binding whose goal is to help with building |
| cross-platforms applications. This binding is not complete though, as |
| the Win32 API does not provide the necessary support for all POSIX APIs. |
| |
| To use the wPOSIX binding you need to use a project file, and adding |
| a single with_clause will give you full access to the wPOSIX binding |
| sources and ensure that the proper libraries are passed to the linker. |
| |
| @quotation |
| |
| @example |
| with "wposix"; |
| project P is |
| for Sources use ...; |
| end P; |
| @end example |
| @end quotation |
| |
| To build the application you just need to call gprbuild for the |
| application's project, here p.gpr: |
| |
| @quotation |
| |
| @example |
| gprbuild p.gpr |
| @end example |
| @end quotation |
| |
| @node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information |
| @anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{2f}@anchor{gnat_ugn/platform_specific_information id44}@anchor{2b7} |
| @section Mac OS Topics |
| |
| |
| @geindex OS X |
| |
| This section describes topics that are specific to Apple's OS X |
| platform. |
| |
| @menu |
| * Codesigning the Debugger:: |
| |
| @end menu |
| |
| @node Codesigning the Debugger,,,Mac OS Topics |
| @anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{2b8} |
| @subsection Codesigning the Debugger |
| |
| |
| The Darwin Kernel requires the debugger to have special permissions |
| before it is allowed to control other processes. These permissions |
| are granted by codesigning the GDB executable. Without these |
| permissions, the debugger will report error messages such as: |
| |
| @example |
| Starting program: /x/y/foo |
| Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5). |
| (please check gdb is codesigned - see taskgated(8)) |
| @end example |
| |
| Codesigning requires a certificate. The following procedure explains |
| how to create one: |
| |
| |
| @itemize * |
| |
| @item |
| Start the Keychain Access application (in |
| /Applications/Utilities/Keychain Access.app) |
| |
| @item |
| Select the Keychain Access -> Certificate Assistant -> |
| Create a Certificate... menu |
| |
| @item |
| Then: |
| |
| |
| @itemize * |
| |
| @item |
| Choose a name for the new certificate (this procedure will use |
| "gdb-cert" as an example) |
| |
| @item |
| Set "Identity Type" to "Self Signed Root" |
| |
| @item |
| Set "Certificate Type" to "Code Signing" |
| |
| @item |
| Activate the "Let me override defaults" option |
| @end itemize |
| |
| @item |
| Click several times on "Continue" until the "Specify a Location |
| For The Certificate" screen appears, then set "Keychain" to "System" |
| |
| @item |
| Click on "Continue" until the certificate is created |
| |
| @item |
| Finally, in the view, double-click on the new certificate, |
| and set "When using this certificate" to "Always Trust" |
| |
| @item |
| Exit the Keychain Access application and restart the computer |
| (this is unfortunately required) |
| @end itemize |
| |
| Once a certificate has been created, the debugger can be codesigned |
| as follow. In a Terminal, run the following command: |
| |
| @quotation |
| |
| @example |
| $ codesign -f -s "gdb-cert" <gnat_install_prefix>/bin/gdb |
| @end example |
| @end quotation |
| |
| where "gdb-cert" should be replaced by the actual certificate |
| name chosen above, and <gnat_install_prefix> should be replaced by |
| the location where you installed GNAT. Also, be sure that users are |
| in the Unix group @code{_developer}. |
| |
| @node Example of Binder Output File,Elaboration Order Handling in GNAT,Platform-Specific Information,Top |
| @anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{10}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{2b9}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{2ba} |
| @chapter Example of Binder Output File |
| |
| |
| @geindex Binder output (example) |
| |
| This Appendix displays the source code for the output file |
| generated by @emph{gnatbind} for a simple 'Hello World' program. |
| Comments have been added for clarification purposes. |
| |
| @example |
| -- 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. |
| |
| pragma Ada_95; |
| with System; |
| package ada_main is |
| pragma Warnings (Off); |
| |
| -- 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: Pro 7.4.0w (20141119-49)" & ASCII.NUL; |
| pragma Export (C, GNAT_Version, "__gnat_version"); |
| |
| Ada_Main_Program_Name : constant String := "_ada_hello" & ASCII.NUL; |
| pragma Export (C, Ada_Main_Program_Name, "__gnat_ada_main_program_name"); |
| |
| -- 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 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 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. |
| |
| -- 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. |
| |
| -- 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. |
| |
| type Version_32 is mod 2 ** 32; |
| u00001 : constant Version_32 := 16#8ad6e54a#; |
| pragma Export (C, u00001, "helloB"); |
| u00002 : constant Version_32 := 16#fbff4c67#; |
| pragma Export (C, u00002, "system__standard_libraryB"); |
| u00003 : constant Version_32 := 16#1ec6fd90#; |
| pragma Export (C, u00003, "system__standard_libraryS"); |
| u00004 : constant Version_32 := 16#3ffc8e18#; |
| pragma Export (C, u00004, "adaS"); |
| u00005 : constant Version_32 := 16#28f088c2#; |
| pragma Export (C, u00005, "ada__text_ioB"); |
| u00006 : constant Version_32 := 16#f372c8ac#; |
| pragma Export (C, u00006, "ada__text_ioS"); |
| u00007 : constant Version_32 := 16#2c143749#; |
| pragma Export (C, u00007, "ada__exceptionsB"); |
| u00008 : constant Version_32 := 16#f4f0cce8#; |
| pragma Export (C, u00008, "ada__exceptionsS"); |
| u00009 : constant Version_32 := 16#a46739c0#; |
| pragma Export (C, u00009, "ada__exceptions__last_chance_handlerB"); |
| u00010 : constant Version_32 := 16#3aac8c92#; |
| pragma Export (C, u00010, "ada__exceptions__last_chance_handlerS"); |
| u00011 : constant Version_32 := 16#1d274481#; |
| pragma Export (C, u00011, "systemS"); |
| u00012 : constant Version_32 := 16#a207fefe#; |
| pragma Export (C, u00012, "system__soft_linksB"); |
| u00013 : constant Version_32 := 16#467d9556#; |
| pragma Export (C, u00013, "system__soft_linksS"); |
| u00014 : constant Version_32 := 16#b01dad17#; |
| pragma Export (C, u00014, "system__parametersB"); |
| u00015 : constant Version_32 := 16#630d49fe#; |
| pragma Export (C, u00015, "system__parametersS"); |
| u00016 : constant Version_32 := 16#b19b6653#; |
| pragma Export (C, u00016, "system__secondary_stackB"); |
| u00017 : constant Version_32 := 16#b6468be8#; |
| pragma Export (C, u00017, "system__secondary_stackS"); |
| u00018 : constant Version_32 := 16#39a03df9#; |
| pragma Export (C, u00018, "system__storage_elementsB"); |
| u00019 : constant Version_32 := 16#30e40e85#; |
| pragma Export (C, u00019, "system__storage_elementsS"); |
| u00020 : constant Version_32 := 16#41837d1e#; |
| pragma Export (C, u00020, "system__stack_checkingB"); |
| u00021 : constant Version_32 := 16#93982f69#; |
| pragma Export (C, u00021, "system__stack_checkingS"); |
| u00022 : constant Version_32 := 16#393398c1#; |
| pragma Export (C, u00022, "system__exception_tableB"); |
| u00023 : constant Version_32 := 16#b33e2294#; |
| pragma Export (C, u00023, "system__exception_tableS"); |
| u00024 : constant Version_32 := 16#ce4af020#; |
| pragma Export (C, u00024, "system__exceptionsB"); |
| u00025 : constant Version_32 := 16#75442977#; |
| pragma Export (C, u00025, "system__exceptionsS"); |
| u00026 : constant Version_32 := 16#37d758f1#; |
| pragma Export (C, u00026, "system__exceptions__machineS"); |
| u00027 : constant Version_32 := 16#b895431d#; |
| pragma Export (C, u00027, "system__exceptions_debugB"); |
| u00028 : constant Version_32 := 16#aec55d3f#; |
| pragma Export (C, u00028, "system__exceptions_debugS"); |
| u00029 : constant Version_32 := 16#570325c8#; |
| pragma Export (C, u00029, "system__img_intB"); |
| u00030 : constant Version_32 := 16#1ffca443#; |
| pragma Export (C, u00030, "system__img_intS"); |
| u00031 : constant Version_32 := 16#b98c3e16#; |
| pragma Export (C, u00031, "system__tracebackB"); |
| u00032 : constant Version_32 := 16#831a9d5a#; |
| pragma Export (C, u00032, "system__tracebackS"); |
| u00033 : constant Version_32 := 16#9ed49525#; |
| pragma Export (C, u00033, "system__traceback_entriesB"); |
| u00034 : constant Version_32 := 16#1d7cb2f1#; |
| pragma Export (C, u00034, "system__traceback_entriesS"); |
| u00035 : constant Version_32 := 16#8c33a517#; |
| pragma Export (C, u00035, "system__wch_conB"); |
| u00036 : constant Version_32 := 16#065a6653#; |
| pragma Export (C, u00036, "system__wch_conS"); |
| u00037 : constant Version_32 := 16#9721e840#; |
| pragma Export (C, u00037, "system__wch_stwB"); |
| u00038 : constant Version_32 := 16#2b4b4a52#; |
| pragma Export (C, u00038, "system__wch_stwS"); |
| u00039 : constant Version_32 := 16#92b797cb#; |
| pragma Export (C, u00039, "system__wch_cnvB"); |
| u00040 : constant Version_32 := 16#09eddca0#; |
| pragma Export (C, u00040, "system__wch_cnvS"); |
| u00041 : constant Version_32 := 16#6033a23f#; |
| pragma Export (C, u00041, "interfacesS"); |
| u00042 : constant Version_32 := 16#ece6fdb6#; |
| pragma Export (C, u00042, "system__wch_jisB"); |
| u00043 : constant Version_32 := 16#899dc581#; |
| pragma Export (C, u00043, "system__wch_jisS"); |
| u00044 : constant Version_32 := 16#10558b11#; |
| pragma Export (C, u00044, "ada__streamsB"); |
| u00045 : constant Version_32 := 16#2e6701ab#; |
| pragma Export (C, u00045, "ada__streamsS"); |
| u00046 : constant Version_32 := 16#db5c917c#; |
| pragma Export (C, u00046, "ada__io_exceptionsS"); |
| u00047 : constant Version_32 := 16#12c8cd7d#; |
| pragma Export (C, u00047, "ada__tagsB"); |
| u00048 : constant Version_32 := 16#ce72c228#; |
| pragma Export (C, u00048, "ada__tagsS"); |
| u00049 : constant Version_32 := 16#c3335bfd#; |
| pragma Export (C, u00049, "system__htableB"); |
| u00050 : constant Version_32 := 16#99e5f76b#; |
| pragma Export (C, u00050, "system__htableS"); |
| u00051 : constant Version_32 := 16#089f5cd0#; |
| pragma Export (C, u00051, "system__string_hashB"); |
| u00052 : constant Version_32 := 16#3bbb9c15#; |
| pragma Export (C, u00052, "system__string_hashS"); |
| u00053 : constant Version_32 := 16#807fe041#; |
| pragma Export (C, u00053, "system__unsigned_typesS"); |
| u00054 : constant Version_32 := 16#d27be59e#; |
| pragma Export (C, u00054, "system__val_lluB"); |
| u00055 : constant Version_32 := 16#fa8db733#; |
| pragma Export (C, u00055, "system__val_lluS"); |
| u00056 : constant Version_32 := 16#27b600b2#; |
| pragma Export (C, u00056, "system__val_utilB"); |
| u00057 : constant Version_32 := 16#b187f27f#; |
| pragma Export (C, u00057, "system__val_utilS"); |
| u00058 : constant Version_32 := 16#d1060688#; |
| pragma Export (C, u00058, "system__case_utilB"); |
| u00059 : constant Version_32 := 16#392e2d56#; |
| pragma Export (C, u00059, "system__case_utilS"); |
| u00060 : constant Version_32 := 16#84a27f0d#; |
| pragma Export (C, u00060, "interfaces__c_streamsB"); |
| u00061 : constant Version_32 := 16#8bb5f2c0#; |
| pragma Export (C, u00061, "interfaces__c_streamsS"); |
| u00062 : constant Version_32 := 16#6db6928f#; |
| pragma Export (C, u00062, "system__crtlS"); |
| u00063 : constant Version_32 := 16#4e6a342b#; |
| pragma Export (C, u00063, "system__file_ioB"); |
| u00064 : constant Version_32 := 16#ba56a5e4#; |
| pragma Export (C, u00064, "system__file_ioS"); |
| u00065 : constant Version_32 := 16#b7ab275c#; |
| pragma Export (C, u00065, "ada__finalizationB"); |
| u00066 : constant Version_32 := 16#19f764ca#; |
| pragma Export (C, u00066, "ada__finalizationS"); |
| u00067 : constant Version_32 := 16#95817ed8#; |
| pragma Export (C, u00067, "system__finalization_rootB"); |
| u00068 : constant Version_32 := 16#52d53711#; |
| pragma Export (C, u00068, "system__finalization_rootS"); |
| u00069 : constant Version_32 := 16#769e25e6#; |
| pragma Export (C, u00069, "interfaces__cB"); |
| u00070 : constant Version_32 := 16#4a38bedb#; |
| pragma Export (C, u00070, "interfaces__cS"); |
| u00071 : constant Version_32 := 16#07e6ee66#; |
| pragma Export (C, u00071, "system__os_libB"); |
| u00072 : constant Version_32 := 16#d7b69782#; |
| pragma Export (C, u00072, "system__os_libS"); |
| u00073 : constant Version_32 := 16#1a817b8e#; |
| pragma Export (C, u00073, "system__stringsB"); |
| u00074 : constant Version_32 := 16#639855e7#; |
| pragma Export (C, u00074, "system__stringsS"); |
| u00075 : constant Version_32 := 16#e0b8de29#; |
| pragma Export (C, u00075, "system__file_control_blockS"); |
| u00076 : constant Version_32 := 16#b5b2aca1#; |
| pragma Export (C, u00076, "system__finalization_mastersB"); |
| u00077 : constant Version_32 := 16#69316dc1#; |
| pragma Export (C, u00077, "system__finalization_mastersS"); |
| u00078 : constant Version_32 := 16#57a37a42#; |
| pragma Export (C, u00078, "system__address_imageB"); |
| u00079 : constant Version_32 := 16#bccbd9bb#; |
| pragma Export (C, u00079, "system__address_imageS"); |
| u00080 : constant Version_32 := 16#7268f812#; |
| pragma Export (C, u00080, "system__img_boolB"); |
| u00081 : constant Version_32 := 16#e8fe356a#; |
| pragma Export (C, u00081, "system__img_boolS"); |
| u00082 : constant Version_32 := 16#d7aac20c#; |
| pragma Export (C, u00082, "system__ioB"); |
| u00083 : constant Version_32 := 16#8365b3ce#; |
| pragma Export (C, u00083, "system__ioS"); |
| u00084 : constant Version_32 := 16#6d4d969a#; |
| pragma Export (C, u00084, "system__storage_poolsB"); |
| u00085 : constant Version_32 := 16#e87cc305#; |
| pragma Export (C, u00085, "system__storage_poolsS"); |
| u00086 : constant Version_32 := 16#e34550ca#; |
| pragma Export (C, u00086, "system__pool_globalB"); |
| u00087 : constant Version_32 := 16#c88d2d16#; |
| pragma Export (C, u00087, "system__pool_globalS"); |
| u00088 : constant Version_32 := 16#9d39c675#; |
| pragma Export (C, u00088, "system__memoryB"); |
| u00089 : constant Version_32 := 16#445a22b5#; |
| pragma Export (C, u00089, "system__memoryS"); |
| u00090 : constant Version_32 := 16#6a859064#; |
| pragma Export (C, u00090, "system__storage_pools__subpoolsB"); |
| u00091 : constant Version_32 := 16#e3b008dc#; |
| pragma Export (C, u00091, "system__storage_pools__subpoolsS"); |
| u00092 : constant Version_32 := 16#63f11652#; |
| pragma Export (C, u00092, "system__storage_pools__subpools__finalizationB"); |
| u00093 : constant Version_32 := 16#fe2f4b3a#; |
| pragma Export (C, u00093, "system__storage_pools__subpools__finalizationS"); |
| |
| -- BEGIN ELABORATION ORDER |
| -- ada%s |
| -- interfaces%s |
| -- system%s |
| -- system.case_util%s |
| -- system.case_util%b |
| -- system.htable%s |
| -- system.img_bool%s |
| -- system.img_bool%b |
| -- system.img_int%s |
| -- system.img_int%b |
| -- system.io%s |
| -- system.io%b |
| -- system.parameters%s |
| -- system.parameters%b |
| -- system.crtl%s |
| -- interfaces.c_streams%s |
| -- interfaces.c_streams%b |
| -- system.standard_library%s |
| -- system.exceptions_debug%s |
| -- system.exceptions_debug%b |
| -- system.storage_elements%s |
| -- system.storage_elements%b |
| -- system.stack_checking%s |
| -- system.stack_checking%b |
| -- system.string_hash%s |
| -- system.string_hash%b |
| -- system.htable%b |
| -- system.strings%s |
| -- system.strings%b |
| -- system.os_lib%s |
| -- system.traceback_entries%s |
| -- system.traceback_entries%b |
| -- ada.exceptions%s |
| -- system.soft_links%s |
| -- system.unsigned_types%s |
| -- system.val_llu%s |
| -- system.val_util%s |
| -- system.val_util%b |
| -- system.val_llu%b |
| -- system.wch_con%s |
| -- system.wch_con%b |
| -- system.wch_cnv%s |
| -- system.wch_jis%s |
| -- system.wch_jis%b |
| -- system.wch_cnv%b |
| -- system.wch_stw%s |
| -- system.wch_stw%b |
| -- ada.exceptions.last_chance_handler%s |
| -- ada.exceptions.last_chance_handler%b |
| -- system.address_image%s |
| -- system.exception_table%s |
| -- system.exception_table%b |
| -- ada.io_exceptions%s |
| -- ada.tags%s |
| -- ada.streams%s |
| -- ada.streams%b |
| -- interfaces.c%s |
| -- system.exceptions%s |
| -- system.exceptions%b |
| -- system.exceptions.machine%s |
| -- system.finalization_root%s |
| -- system.finalization_root%b |
| -- ada.finalization%s |
| -- ada.finalization%b |
| -- system.storage_pools%s |
| -- system.storage_pools%b |
| -- system.finalization_masters%s |
| -- system.storage_pools.subpools%s |
| -- system.storage_pools.subpools.finalization%s |
| -- system.storage_pools.subpools.finalization%b |
| -- system.memory%s |
| -- system.memory%b |
| -- system.standard_library%b |
| -- system.pool_global%s |
| -- system.pool_global%b |
| -- system.file_control_block%s |
| -- system.file_io%s |
| -- system.secondary_stack%s |
| -- system.file_io%b |
| -- system.storage_pools.subpools%b |
| -- system.finalization_masters%b |
| -- interfaces.c%b |
| -- ada.tags%b |
| -- system.soft_links%b |
| -- system.os_lib%b |
| -- system.secondary_stack%b |
| -- system.address_image%b |
| -- system.traceback%s |
| -- ada.exceptions%b |
| -- system.traceback%b |
| -- ada.text_io%s |
| -- ada.text_io%b |
| -- hello%b |
| -- END ELABORATION ORDER |
| |
| end ada_main; |
| @end example |
| |
| @example |
| pragma Ada_95; |
| -- 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"); |
| |
| pragma Suppress (Overflow_Check); |
| with Ada.Exceptions; |
| |
| -- Generated package body for Ada_Main starts here |
| |
| package body ada_main is |
| pragma Warnings (Off); |
| |
| -- These values are reference counter associated to units which have |
| -- been elaborated. It is also used to avoid elaborating the |
| -- same unit twice. |
| |
| E72 : Short_Integer; pragma Import (Ada, E72, "system__os_lib_E"); |
| E13 : Short_Integer; pragma Import (Ada, E13, "system__soft_links_E"); |
| E23 : Short_Integer; pragma Import (Ada, E23, "system__exception_table_E"); |
| E46 : Short_Integer; pragma Import (Ada, E46, "ada__io_exceptions_E"); |
| E48 : Short_Integer; pragma Import (Ada, E48, "ada__tags_E"); |
| E45 : Short_Integer; pragma Import (Ada, E45, "ada__streams_E"); |
| E70 : Short_Integer; pragma Import (Ada, E70, "interfaces__c_E"); |
| E25 : Short_Integer; pragma Import (Ada, E25, "system__exceptions_E"); |
| E68 : Short_Integer; pragma Import (Ada, E68, "system__finalization_root_E"); |
| E66 : Short_Integer; pragma Import (Ada, E66, "ada__finalization_E"); |
| E85 : Short_Integer; pragma Import (Ada, E85, "system__storage_pools_E"); |
| E77 : Short_Integer; pragma Import (Ada, E77, "system__finalization_masters_E"); |
| E91 : Short_Integer; pragma Import (Ada, E91, "system__storage_pools__subpools_E"); |
| E87 : Short_Integer; pragma Import (Ada, E87, "system__pool_global_E"); |
| E75 : Short_Integer; pragma Import (Ada, E75, "system__file_control_block_E"); |
| E64 : Short_Integer; pragma Import (Ada, E64, "system__file_io_E"); |
| E17 : Short_Integer; pragma Import (Ada, E17, "system__secondary_stack_E"); |
| E06 : Short_Integer; pragma Import (Ada, E06, "ada__text_io_E"); |
| |
| Local_Priority_Specific_Dispatching : constant String := ""; |
| Local_Interrupt_States : constant String := ""; |
| |
| Is_Elaborated : Boolean := False; |
| |
| procedure finalize_library is |
| begin |
| E06 := E06 - 1; |
| declare |
| procedure F1; |
| pragma Import (Ada, F1, "ada__text_io__finalize_spec"); |
| begin |
| F1; |
| end; |
| E77 := E77 - 1; |
| E91 := E91 - 1; |
| declare |
| procedure F2; |
| pragma Import (Ada, F2, "system__file_io__finalize_body"); |
| begin |
| E64 := E64 - 1; |
| F2; |
| end; |
| declare |
| procedure F3; |
| pragma Import (Ada, F3, "system__file_control_block__finalize_spec"); |
| begin |
| E75 := E75 - 1; |
| F3; |
| end; |
| E87 := E87 - 1; |
| declare |
| procedure F4; |
| pragma Import (Ada, F4, "system__pool_global__finalize_spec"); |
| begin |
| F4; |
| end; |
| declare |
| procedure F5; |
| pragma Import (Ada, F5, "system__storage_pools__subpools__finalize_spec"); |
| begin |
| F5; |
| end; |
| declare |
| procedure F6; |
| pragma Import (Ada, F6, "system__finalization_masters__finalize_spec"); |
| begin |
| F6; |
| end; |
| declare |
| procedure Reraise_Library_Exception_If_Any; |
| pragma Import (Ada, Reraise_Library_Exception_If_Any, "__gnat_reraise_library_exception_if_any"); |
| begin |
| Reraise_Library_Exception_If_Any; |
| end; |
| end finalize_library; |
| |
| ------------- |
| -- adainit -- |
| ------------- |
| |
| procedure adainit is |
| |
| Main_Priority : Integer; |
| pragma Import (C, Main_Priority, "__gl_main_priority"); |
| Time_Slice_Value : Integer; |
| pragma Import (C, Time_Slice_Value, "__gl_time_slice_val"); |
| WC_Encoding : Character; |
| pragma Import (C, WC_Encoding, "__gl_wc_encoding"); |
| Locking_Policy : Character; |
| pragma Import (C, Locking_Policy, "__gl_locking_policy"); |
| Queuing_Policy : Character; |
| pragma Import (C, Queuing_Policy, "__gl_queuing_policy"); |
| Task_Dispatching_Policy : Character; |
| pragma Import (C, Task_Dispatching_Policy, "__gl_task_dispatching_policy"); |
| Priority_Specific_Dispatching : System.Address; |
| pragma Import (C, Priority_Specific_Dispatching, "__gl_priority_specific_dispatching"); |
| Num_Specific_Dispatching : Integer; |
| pragma Import (C, Num_Specific_Dispatching, "__gl_num_specific_dispatching"); |
| Main_CPU : Integer; |
| pragma Import (C, Main_CPU, "__gl_main_cpu"); |
| Interrupt_States : System.Address; |
| pragma Import (C, Interrupt_States, "__gl_interrupt_states"); |
| Num_Interrupt_States : Integer; |
| pragma Import (C, Num_Interrupt_States, "__gl_num_interrupt_states"); |
| Unreserve_All_Interrupts : Integer; |
| pragma Import (C, Unreserve_All_Interrupts, "__gl_unreserve_all_interrupts"); |
| Detect_Blocking : Integer; |
| pragma Import (C, Detect_Blocking, "__gl_detect_blocking"); |
| Default_Stack_Size : Integer; |
| pragma Import (C, Default_Stack_Size, "__gl_default_stack_size"); |
| Leap_Seconds_Support : Integer; |
| pragma Import (C, Leap_Seconds_Support, "__gl_leap_seconds_support"); |
| |
| procedure Runtime_Initialize; |
| pragma Import (C, Runtime_Initialize, "__gnat_runtime_initialize"); |
| |
| Finalize_Library_Objects : No_Param_Proc; |
| pragma Import (C, Finalize_Library_Objects, "__gnat_finalize_library_objects"); |
| |
| -- Start of processing for adainit |
| |
| begin |
| |
| -- Record various information for this partition. The values |
| -- are derived by the binder from information stored in the ali |
| -- files by the compiler. |
| |
| if Is_Elaborated then |
| return; |
| end if; |
| Is_Elaborated := True; |
| Main_Priority := -1; |
| Time_Slice_Value := -1; |
| WC_Encoding := 'b'; |
| Locking_Policy := ' '; |
| Queuing_Policy := ' '; |
| Task_Dispatching_Policy := ' '; |
| Priority_Specific_Dispatching := |
| Local_Priority_Specific_Dispatching'Address; |
| Num_Specific_Dispatching := 0; |
| Main_CPU := -1; |
| Interrupt_States := Local_Interrupt_States'Address; |
| Num_Interrupt_States := 0; |
| Unreserve_All_Interrupts := 0; |
| Detect_Blocking := 0; |
| Default_Stack_Size := -1; |
| Leap_Seconds_Support := 0; |
| |
| Runtime_Initialize; |
| |
| Finalize_Library_Objects := finalize_library'access; |
| |
| -- 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. Increment a counter of |
| -- reference for each unit. |
| |
| System.Soft_Links'Elab_Spec; |
| System.Exception_Table'Elab_Body; |
| E23 := E23 + 1; |
| Ada.Io_Exceptions'Elab_Spec; |
| E46 := E46 + 1; |
| Ada.Tags'Elab_Spec; |
| Ada.Streams'Elab_Spec; |
| E45 := E45 + 1; |
| Interfaces.C'Elab_Spec; |
| System.Exceptions'Elab_Spec; |
| E25 := E25 + 1; |
| System.Finalization_Root'Elab_Spec; |
| E68 := E68 + 1; |
| Ada.Finalization'Elab_Spec; |
| E66 := E66 + 1; |
| System.Storage_Pools'Elab_Spec; |
| E85 := E85 + 1; |
| System.Finalization_Masters'Elab_Spec; |
| System.Storage_Pools.Subpools'Elab_Spec; |
| System.Pool_Global'Elab_Spec; |
| E87 := E87 + 1; |
| System.File_Control_Block'Elab_Spec; |
| E75 := E75 + 1; |
| System.File_Io'Elab_Body; |
| E64 := E64 + 1; |
| E91 := E91 + 1; |
| System.Finalization_Masters'Elab_Body; |
| E77 := E77 + 1; |
| E70 := E70 + 1; |
| Ada.Tags'Elab_Body; |
| E48 := E48 + 1; |
| System.Soft_Links'Elab_Body; |
| E13 := E13 + 1; |
| System.Os_Lib'Elab_Body; |
| E72 := E72 + 1; |
| System.Secondary_Stack'Elab_Body; |
| E17 := E17 + 1; |
| Ada.Text_Io'Elab_Spec; |
| Ada.Text_Io'Elab_Body; |
| E06 := E06 + 1; |
| end adainit; |
| |
| -------------- |
| -- adafinal -- |
| -------------- |
| |
| procedure adafinal is |
| procedure s_stalib_adafinal; |
| pragma Import (C, s_stalib_adafinal, "system__standard_library__adafinal"); |
| |
| procedure Runtime_Finalize; |
| pragma Import (C, Runtime_Finalize, "__gnat_runtime_finalize"); |
| |
| begin |
| if not Is_Elaborated then |
| return; |
| end if; |
| Is_Elaborated := False; |
| Runtime_Finalize; |
| s_stalib_adafinal; |
| end adafinal; |
| |
| -- 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"); |
| |
| ---------- |
| -- 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"); |
| |
| -- The following is to initialize the SEH exceptions |
| |
| SEH : aliased array (1 .. 2) of Integer; |
| |
| Ensure_Reference : aliased System.Address := Ada_Main_Program_Name'Address; |
| pragma Volatile (Ensure_Reference); |
| |
| -- Start of processing for main |
| |
| begin |
| -- Save global variables |
| |
| gnat_argc := argc; |
| gnat_argv := argv; |
| gnat_envp := envp; |
| |
| -- Call low level system initialization |
| |
| Initialize (SEH'Address); |
| |
| -- Call our generated Ada initialization routine |
| |
| adainit; |
| |
| -- 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; |
| @end example |
| |
| 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 @cite{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 @cite{Ada_Main} package. For example, |
| suppose that for reasons that you do not understand, your program is crashing |
| during elaboration of the body of @cite{Ada.Text_IO}. To locate this bug, |
| you can place a breakpoint on the call: |
| |
| @quotation |
| |
| @example |
| Ada.Text_Io'Elab_Body; |
| @end example |
| @end quotation |
| |
| 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). |
| |
| @c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit |
| |
| @node Elaboration Order Handling in GNAT,Inline Assembler,Example of Binder Output File,Top |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{11}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{2bb}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{2bc} |
| @chapter Elaboration Order Handling in GNAT |
| |
| |
| @geindex Order of elaboration |
| |
| @geindex Elaboration control |
| |
| This appendix describes the handling of elaboration code in Ada 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. |
| |
| @menu |
| * Elaboration Code:: |
| * Checking the Elaboration Order:: |
| * Controlling the Elaboration Order:: |
| * Controlling Elaboration in GNAT - Internal Calls:: |
| * Controlling Elaboration in GNAT - External Calls:: |
| * Default Behavior in GNAT - Ensuring Safety:: |
| * Treatment of Pragma Elaborate:: |
| * Elaboration Issues for Library Tasks:: |
| * Mixing Elaboration Models:: |
| * What to Do If the Default Elaboration Behavior Fails:: |
| * Elaboration for Indirect Calls:: |
| * Summary of Procedures for Elaboration Control:: |
| * Other Elaboration Order Considerations:: |
| * Determining the Chosen Elaboration Order:: |
| |
| @end menu |
| |
| @node Elaboration Code,Checking the Elaboration Order,,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{2bd}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{2be} |
| @section Elaboration Code |
| |
| |
| Ada 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: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{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: |
| |
| @example |
| Sqrt_Half : Float := Sqrt (0.5); |
| @end example |
| |
| @item |
| @emph{Package initialization code} |
| |
| Code in a @cite{BEGIN-END} section at the outer level of a package body is |
| executed as part of the package body elaboration code. |
| |
| @item |
| @emph{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. |
| @end itemize |
| |
| 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 @cite{Sqrt_Half}, |
| if some other piece of |
| elaboration code references @cite{Sqrt_Half}, |
| then it must run after the |
| section of elaboration code that contains the declaration of |
| @cite{Sqrt_Half}. |
| |
| There would never be any order of elaboration problem if we made a rule |
| that whenever you @emph{with} a unit, you must elaborate both the spec and body |
| of that unit before elaborating the unit doing the @emph{with}ing: |
| |
| @example |
| with Unit_1; |
| package Unit_2 is ... |
| @end example |
| |
| would require that both the body and spec of @cite{Unit_1} be elaborated |
| before the spec of @cite{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 @cite{Unit_1}, we have a procedure @cite{Func_1} |
| that references |
| the variable @cite{Sqrt_1}, which is declared in the elaboration code |
| of the body of @cite{Unit_1}: |
| |
| @example |
| Sqrt_1 : Float := Sqrt (0.1); |
| @end example |
| |
| The elaboration code of the body of @cite{Unit_1} also contains: |
| |
| @example |
| if expression_1 = 1 then |
| Q := Unit_2.Func_2; |
| end if; |
| @end example |
| |
| @cite{Unit_2} is exactly parallel, |
| it has a procedure @cite{Func_2} that references |
| the variable @cite{Sqrt_2}, which is declared in the elaboration code of |
| the body @cite{Unit_2}: |
| |
| @example |
| Sqrt_2 : Float := Sqrt (0.1); |
| @end example |
| |
| The elaboration code of the body of @cite{Unit_2} also contains: |
| |
| @example |
| if expression_2 = 2 then |
| Q := Unit_1.Func_1; |
| end if; |
| @end example |
| |
| Now the question is, which of the following orders of elaboration is |
| acceptable: |
| |
| @example |
| Spec of Unit_1 |
| Spec of Unit_2 |
| Body of Unit_1 |
| Body of Unit_2 |
| @end example |
| |
| or |
| |
| @example |
| Spec of Unit_2 |
| Spec of Unit_1 |
| Body of Unit_2 |
| Body of Unit_1 |
| @end example |
| |
| If you carefully analyze the flow here, you will see that you cannot tell |
| at compile time the answer to this question. |
| If @cite{expression_1} is not equal to 1, |
| and @cite{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 @cite{expression_1} /= 1 and @cite{expression_2} = 2, |
| then the call to @cite{Func_1} |
| will occur, but not the call to @cite{Func_2.} |
| This means that it is essential |
| to elaborate the body of @cite{Unit_1} before |
| the body of @cite{Unit_2}, so the first |
| order of elaboration is correct and the second is wrong. |
| |
| By making @cite{expression_1} and @cite{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. |
| |
| @node Checking the Elaboration Order,Controlling the Elaboration Order,Elaboration Code,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{2bf}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{2c0} |
| @section Checking the Elaboration Order |
| |
| |
| In some languages that involve the same kind of elaboration problems, |
| e.g., Java and C++, the programmer needs to take these |
| ordering problems into account, 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 is designed to be a safe language, and a programmer-beware approach is |
| clearly not sufficient. Consequently, the language provides three lines |
| of defense: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{Standard rules} |
| |
| Some standard rules restrict the possible choice of elaboration |
| order. In particular, if you @emph{with} a unit, then its spec is always |
| elaborated before the unit doing the @emph{with}. Similarly, a parent |
| spec is always elaborated before the child spec, and finally |
| a spec is always elaborated before its corresponding body. |
| @end itemize |
| |
| @geindex Elaboration checks |
| |
| @geindex Checks |
| @geindex elaboration |
| |
| |
| @itemize * |
| |
| @item |
| @emph{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 (@cite{Program_Error}) is raised. |
| |
| @item |
| @emph{Elaboration control} |
| |
| Facilities are provided for the programmer to specify the desired order |
| of elaboration. |
| @end itemize |
| |
| 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 has two |
| rules which are a little more restrictive, but easier to check, and |
| easier to state: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{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 @cite{Program_Error} is raised. |
| |
| @item |
| @emph{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 @cite{Program_Error} is raised. |
| @end itemize |
| |
| 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 @cite{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 @cite{GNAT} indeed |
| does such optimizations, but still the easiest conceptual model is to |
| think of there being one variable per subprogram. |
| |
| @node Controlling the Elaboration Order,Controlling Elaboration in GNAT - Internal Calls,Checking the Elaboration Order,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{2c1}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order}@anchor{2c2} |
| @section Controlling the Elaboration Order |
| |
| |
| In the previous section we discussed the rules in Ada which ensure |
| that @cite{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 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: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{packages that do not require a body} |
| |
| A library package that does not require a body does not permit |
| a body (this rule was introduced in Ada 95). |
| Thus if we have a such a package, as in: |
| |
| @example |
| 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; |
| @end example |
| |
| A package that @emph{with}s @cite{Definitions} may safely instantiate |
| @cite{Definitions.Subp} because the compiler can determine that there |
| definitely is no package body to worry about in this case |
| @end itemize |
| |
| @geindex pragma Pure |
| |
| |
| @itemize * |
| |
| @item |
| @emph{pragma Pure} |
| |
| This pragma 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. |
| @end itemize |
| |
| @geindex pragma Preelaborate |
| |
| |
| @itemize * |
| |
| @item |
| @emph{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. |
| @end itemize |
| |
| @geindex pragma Elaborate_Body |
| |
| |
| @itemize * |
| |
| @item |
| @emph{pragma Elaborate_Body} |
| |
| This pragma requires that the body of a unit be elaborated immediately |
| after its spec. Suppose a unit @cite{A} has such a pragma, |
| and unit @cite{B} does |
| a @emph{with} of unit @cite{A}. Recall that the standard rules require |
| the spec of unit @cite{A} |
| to be elaborated before the @emph{with}ing unit; given the pragma in |
| @cite{A}, we also know that the body of @cite{A} |
| will be elaborated before @cite{B}, so |
| that calls to @cite{A} are safe and do not need a check. |
| |
| Note that, unlike pragma @cite{Pure} and pragma @cite{Preelaborate}, |
| the use of @cite{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 @cite{Unit_1} and @cite{Unit_2}. |
| If a programmer marks @cite{Unit_1} as @cite{Elaborate_Body}, |
| and not @cite{Unit_2@comma{}} then the order of |
| elaboration will be: |
| |
| @example |
| Spec of Unit_2 |
| Spec of Unit_1 |
| Body of Unit_1 |
| Body of Unit_2 |
| @end example |
| |
| Now that means that the call to @cite{Func_1} in @cite{Unit_2} |
| need not be checked, |
| it must be safe. But the call to @cite{Func_2} in |
| @cite{Unit_1} may still fail if |
| @cite{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 @cite{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 @cite{Unit_1}/@cite{Unit_2} example, if |
| we marked both of them as having pragma @cite{Elaborate_Body}, then |
| clearly there would be no possible elaboration order. |
| @end itemize |
| |
| The above pragmas allow a server to guarantee safe use by clients, and |
| clearly this is the preferable approach. Consequently a good rule |
| is to mark units as @cite{Pure} or @cite{Preelaborate} if possible, |
| and if this is not possible, |
| mark them as @cite{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: |
| |
| @geindex pragma Elaborate |
| |
| |
| @itemize * |
| |
| @item |
| @emph{pragma Elaborate (unit)} |
| |
| This pragma is placed in the context clause, after a @emph{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. |
| @end itemize |
| |
| @geindex pragma Elaborate_All |
| |
| |
| @itemize * |
| |
| @item |
| @emph{pragma Elaborate_All (unit)} |
| |
| This is a stronger version of the Elaborate pragma. Consider the |
| following example: |
| |
| @example |
| Unit A |withs| unit B and calls B.Func in elab code |
| Unit B |withs| unit C, and B.Func calls C.Func |
| @end example |
| |
| Now if we put a pragma @cite{Elaborate (B)} |
| in unit @cite{A}, this ensures that the |
| body of @cite{B} is elaborated before the call, but not the |
| body of @cite{C}, so |
| the call to @cite{C.Func} could still cause @cite{Program_Error} to |
| be raised. |
| |
| The effect of a pragma @cite{Elaborate_All} is stronger, it requires |
| not only that the body of the named unit be elaborated before the |
| unit doing the @emph{with}, but also the bodies of all units that the |
| named unit uses, following @emph{with} links transitively. For example, |
| if we put a pragma @cite{Elaborate_All (B)} in unit @cite{A}, |
| then it requires not only that the body of @cite{B} be elaborated before @cite{A}, |
| but also the body of @cite{C}, because @cite{B} @emph{with}s @cite{C}. |
| @end itemize |
| |
| We are now in a position to give a usage rule in Ada 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: |
| |
| @emph{If a unit has elaboration code that can directly or |
| indirectly make a call to a subprogram in a |withed| unit, or instantiate |
| a generic package in a |withed| unit, |
| then if the |withed| unit does not have |
| pragma `Pure` or `Preelaborate`, then the client should have |
| a pragma `Elaborate_All`for the |withed| unit.*} |
| |
| By following this rule a client is |
| assured that calls can be made without risk of an exception. |
| |
| For generic subprogram instantiations, the rule can be relaxed to |
| require only a pragma @cite{Elaborate} since elaborating the body |
| of a subprogram cannot cause any transitive elaboration (we are |
| not calling the subprogram in this case, just elaborating its |
| declaration). |
| |
| If this rule is not followed, then a program may be in one of four |
| states: |
| |
| |
| @itemize * |
| |
| @item |
| @emph{No order exists} |
| |
| No order of elaboration exists which follows the rules, taking into |
| account any @cite{Elaborate}, @cite{Elaborate_All}, |
| or @cite{Elaborate_Body} pragmas. In |
| this case, an Ada compiler must diagnose the situation at bind |
| time, and refuse to build an executable program. |
| |
| @item |
| @emph{One or more orders exist, all incorrect} |
| |
| One or more acceptable elaboration orders exist, and all of them |
| generate an elaboration order problem. In this case, the binder |
| can build an executable program, but @cite{Program_Error} will be raised |
| when the program is run. |
| |
| @item |
| @emph{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. |
| |
| @item |
| @emph{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. |
| @end itemize |
| |
| Note that one additional advantage of following our rules on the use |
| of @cite{Elaborate} and @cite{Elaborate_All} |
| is that the program continues to stay in the ideal (all orders OK) state |
| even if maintenance |
| changes some bodies of some units. 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 @cite{Elaborate_Body}. This was a deliberate omission. If you |
| @emph{with} an @cite{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 @cite{Elaborate_All} on such units. |
| |
| @node Controlling Elaboration in GNAT - Internal Calls,Controlling Elaboration in GNAT - External Calls,Controlling the Elaboration Order,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{2c3}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-elaboration-in-gnat-internal-calls}@anchor{2c4} |
| @section 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: |
| |
| @example |
| function One return Float; |
| |
| Q : Float := One; |
| |
| function One return Float is |
| begin |
| return 1.0; |
| end One; |
| @end example |
| |
| will obviously raise @cite{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 @cite{Program_Error}: |
| |
| @example |
| 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; |
| @end example |
| |
| Note that in this particular case, it is likely that the call is safe, because |
| the function @cite{One} does not access any global variables. |
| Nevertheless in Ada, 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 @cite{One} appears before the declaration containing the call |
| (note that in Ada 95 as well as later versions of the Ada standard, |
| declarations can appear in any order, so there is no restriction that |
| would prevent this reordering, and if we write: |
| |
| @example |
| function One return Float; |
| |
| function One return Float is |
| begin |
| return 1.0; |
| end One; |
| |
| Q : Float := One; |
| @end example |
| |
| then all is well, no warning is generated, and no |
| @cite{Program_Error} exception |
| will be raised. |
| Things are more complicated when a chain of subprograms is executed: |
| |
| @example |
| 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; |
| @end example |
| |
| Now the call to @cite{C} |
| at elaboration time in the declaration of @cite{X} is correct, because |
| the body of @cite{C} is already elaborated, |
| and the call to @cite{B} within the body of |
| @cite{C} is correct, but the call |
| to @cite{A} within the body of @cite{B} is incorrect, because the body |
| of @cite{A} has not been elaborated, so @cite{Program_Error} |
| will be raised on the call to @cite{A}. |
| In this case GNAT will generate a |
| warning that @cite{Program_Error} may be |
| raised at the point of the call. Let's look at the warning: |
| |
| @example |
| 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; |
| @end example |
| |
| Note that the message here says 'may raise', instead of the direct case, |
| where the message says 'will be raised'. That's because whether |
| @cite{A} is |
| actually called depends in general on run-time flow of control. |
| For example, if the body of @cite{B} said |
| |
| @example |
| function B return Integer is |
| begin |
| if some-condition-depending-on-input-data then |
| return A; |
| else |
| return 1; |
| end if; |
| end B; |
| @end example |
| |
| then we could not know until run time whether the incorrect call to A would |
| actually occur, so @cite{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 @cite{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: |
| |
| |
| @itemize * |
| |
| @item |
| Compile with the @emph{-gnatws} switch set |
| |
| @item |
| Suppress @cite{Elaboration_Check} for the called subprogram |
| |
| @item |
| Use pragma @cite{Warnings_Off} to turn warnings off for the call |
| @end itemize |
| |
| For the internal elaboration check case, |
| GNAT by default generates the |
| necessary run-time checks to ensure |
| that @cite{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 |
| @cite{Suppress (Elaboration_Check)} 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 @cite{Program_Error} exception. |
| |
| @node Controlling Elaboration in GNAT - External Calls,Default Behavior in GNAT - Ensuring Safety,Controlling Elaboration in GNAT - Internal Calls,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{2c5}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-elaboration-in-gnat-external-calls}@anchor{2c6} |
| @section 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: |
| |
| @example |
| 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; |
| @end example |
| |
| where @cite{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 @cite{Math}, |
| the spec of @cite{Stuff} and the body of @cite{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 @emph{with} |
| for a package @cite{X}, then you |
| are assured that the spec of @cite{X} |
| is elaborated before U , but you are |
| not assured that the body of @cite{X} |
| is elaborated before U. |
| This means that in the above case, the binder is allowed to choose the |
| order: |
| |
| @example |
| spec of Math |
| spec of Stuff |
| body of Math |
| body of Main |
| @end example |
| |
| but that's not good, because now the call to @cite{Math.Sqrt} |
| that happens during |
| the elaboration of the @cite{Stuff} |
| spec happens before the body of @cite{Math.Sqrt} is |
| elaborated, and hence causes @cite{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 @emph{with} first, but |
| that is not a general rule that can be followed in all cases. Consider |
| |
| @example |
| package X is ... |
| |
| package Y is ... |
| |
| with X; |
| package body Y is ... |
| |
| with Y; |
| package body X is ... |
| @end example |
| |
| 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 |
| @emph{with} cannot work in this case: |
| the body of @cite{X} @emph{with}s @cite{Y}, |
| which means you would have to |
| elaborate the body of @cite{Y} first, but that @emph{with}s @cite{X}, |
| which means |
| you have to elaborate the body of @cite{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 @cite{Program_Error} |
| exception to be raised, and it tries to do so (in the |
| above example of @cite{Math/Stuff/Spec}, the GNAT binder will |
| by default |
| elaborate the body of @cite{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. |
| |
| @node Default Behavior in GNAT - Ensuring Safety,Treatment of Pragma Elaborate,Controlling Elaboration in GNAT - External Calls,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{2c7}@anchor{gnat_ugn/elaboration_order_handling_in_gnat default-behavior-in-gnat-ensuring-safety}@anchor{2c8} |
| @section 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: |
| |
| @emph{If a unit has elaboration code that can directly or indirectly make a |
| call to a subprogram in a |withed| unit, or instantiate a generic |
| package in a |withed| unit, then if the |withed| unit |
| does not have pragma `Pure` or `Preelaborate`, then the client should have an |
| `Elaborate_All` pragma for the |withed| unit.} |
| |
| @emph{In the case of instantiating a generic subprogram, it is always |
| sufficient to have only an `Elaborate` pragma for the |
| |withed| 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 @cite{Elaborate} |
| and @cite{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 @cite{Elaborate} and |
| @cite{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 @cite{Elaborate} and |
| @cite{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 @emph{-gnatel} |
| (info messages for elaboration pragmas) switch. This will cause info messages |
| to be generated indicating the missing @cite{Elaborate} and |
| @cite{Elaborate_All} pragmas. |
| Consider the following source program: |
| |
| @example |
| with k; |
| package j is |
| m : integer := k.r; |
| end; |
| @end example |
| |
| where it is clear that there |
| should be a pragma @cite{Elaborate_All} |
| for unit @cite{k}. An implicit pragma will be generated, and it is |
| likely that the binder will be able to honor it. However, if you want |
| to port this program to some other Ada compiler than GNAT. |
| it is safer to include the pragma explicitly in the source. If this |
| unit is compiled with the @emph{-gnatel} |
| switch, then the compiler outputs an information message: |
| |
| @example |
| 1. with k; |
| 2. package j is |
| 3. m : integer := k.r; |
| | |
| >>> info: call to "r" may raise Program_Error |
| >>> info: missing pragma Elaborate_All for "k" |
| |
| 4. end; |
| @end example |
| |
| and these messages can be used as a guide for supplying manually |
| the missing pragmas. It is usually a bad idea to use this |
| option during development. That's because it will tell you when |
| you need to put in a pragma, but cannot tell you when it is time |
| to take it out. So the use of pragma @cite{Elaborate_All} may lead to |
| unnecessary dependencies and even false circularities. |
| |
| 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 @emph{-gnatE} switch on the compiler (@emph{gcc} or |
| @emph{gnatmake}) command, or by the use of the configuration pragma: |
| |
| @example |
| pragma Elaboration_Checks (DYNAMIC); |
| @end example |
| |
| 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 |
| @ref{2c9,,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, providing that you remove any |
| pragma Elaborate statements from the source. |
| |
| @node Treatment of Pragma Elaborate,Elaboration Issues for Library Tasks,Default Behavior in GNAT - Ensuring Safety,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat treatment-of-pragma-elaborate}@anchor{2ca}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{2cb} |
| @section Treatment of Pragma Elaborate |
| |
| |
| @geindex Pragma Elaborate |
| |
| The use of @cite{pragma Elaborate} |
| should generally be avoided in Ada 95 and Ada 2005 programs, |
| since there is no guarantee that transitive calls |
| will be properly handled. Indeed at one point, this pragma was placed |
| in Annex J (Obsolescent Features), on the grounds that it is never useful. |
| |
| Now that's a bit restrictive. In practice, the case in which |
| @cite{pragma Elaborate} is useful is when the caller knows that there |
| are no transitive calls, or that the called unit contains all necessary |
| transitive @cite{pragma Elaborate} statements, and legacy code often |
| contains such uses. |
| |
| Strictly speaking the static mode in GNAT should ignore such pragmas, |
| since there is no assurance at compile time that the necessary safety |
| conditions are met. In practice, this would cause GNAT to be incompatible |
| with correctly written Ada 83 code that had all necessary |
| @cite{pragma Elaborate} statements in place. Consequently, we made the |
| decision that GNAT in its default mode will believe that if it encounters |
| a @cite{pragma Elaborate} then the programmer knows what they are doing, |
| and it will trust that no elaboration errors can occur. |
| |
| The result of this decision is two-fold. First to be safe using the |
| static mode, you should remove all @cite{pragma Elaborate} statements. |
| Second, when fixing circularities in existing code, you can selectively |
| use @cite{pragma Elaborate} statements to convince the static mode of |
| GNAT that it need not generate an implicit @cite{pragma Elaborate_All} |
| statement. |
| |
| When using the static mode with @emph{-gnatwl}, any use of |
| @cite{pragma Elaborate} will generate a warning about possible |
| problems. |
| |
| @node Elaboration Issues for Library Tasks,Mixing Elaboration Models,Treatment of Pragma Elaborate,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-issues-for-library-tasks}@anchor{2cc}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{2cd} |
| @section Elaboration Issues for Library Tasks |
| |
| |
| @geindex Library tasks |
| @geindex elaboration issues |
| |
| @geindex Elaboration of 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 |
| |
| @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; |
| @end example |
| |
| If the above example is compiled in the default static elaboration |
| mode, then a circularity occurs. The circularity comes from the call |
| @cite{Utils.Put_Val} in the task body of @cite{Decls.Lib_Task}. Since |
| this call occurs in elaboration code, we need an implicit pragma |
| @cite{Elaborate_All} for @cite{Utils}. This means that not only must |
| the spec and body of @cite{Utils} be elaborated before the body |
| of @cite{Decls}, but also the spec and body of any unit that is |
| @emph{with}ed by the body of @cite{Utils} must also be elaborated before |
| the body of @cite{Decls}. This is the transitive implication of |
| pragma @cite{Elaborate_All} and it makes sense, because in general |
| the body of @cite{Put_Val} might have a call to something in a |
| @emph{with}ed unit. |
| |
| In this case, the body of Utils (actually its spec) @emph{with}s |
| @cite{Decls}. Unfortunately this means that the body of @cite{Decls} |
| must be elaborated before itself, in case there is a call from the |
| body of @cite{Utils}. |
| |
| Here is the exact chain of events we are worrying about: |
| |
| |
| @itemize * |
| |
| @item |
| In the body of @cite{Decls} a call is made from within the body of a library |
| task to a subprogram in the package @cite{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. |
| |
| @item |
| This means that the body and spec of @cite{Util} must be elaborated before |
| the body of @cite{Decls} so that this call does not cause an access before |
| elaboration. |
| |
| @item |
| Within the body of @cite{Util}, specifically within the body of |
| @cite{Util.Put_Val} there may be calls to any unit @emph{with}ed |
| by this package. |
| |
| @item |
| One such @emph{with}ed package is package @cite{Decls}, so there |
| might be a call to a subprogram in @cite{Decls} in @cite{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 @cite{Decls} knowing what |
| is in the body of @cite{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. |
| |
| @item |
| This means that the spec and body of @cite{Decls} must also be |
| elaborated before we elaborate the unit containing the call, but |
| that unit is @cite{Decls}! This means that the body of @cite{Decls} |
| must be elaborated before itself, and that's a circularity. |
| @end itemize |
| |
| Indeed, if you add an explicit pragma @cite{Elaborate_All} for @cite{Utils} in |
| the body of @cite{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 @emph{-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: |
| |
| |
| @itemize * |
| |
| @item |
| Use the dynamic model of elaboration. |
| |
| If we use the @emph{-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 |
| @cite{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. |
| |
| @item |
| 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. |
| |
| @example |
| 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; |
| @end example |
| |
| All we have done is to split @cite{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. |
| |
| @item |
| 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 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: |
| |
| @example |
| 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; |
| @end example |
| |
| What we have done here is to replace the @cite{task} declaration in |
| package @cite{Decls} with a @cite{task type} declaration. Then we |
| introduce a separate package @cite{Declst} to contain the actual |
| task object. This separates the elaboration issues for |
| the @cite{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 @cite{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. |
| @end itemize |
| |
| @geindex No_Entry_Calls_In_Elaboration_Code restriction |
| |
| |
| @itemize * |
| |
| @item |
| 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 @cite{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 @cite{accept} or |
| @cite{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: |
| |
| @example |
| pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); |
| @end example |
| |
| This pragma can be placed in the @code{gnat.adc} file in the usual |
| manner. If we take our original unmodified program and compile it |
| in the presence of a @code{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 @cite{accept} |
| or @cite{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. |
| @end itemize |
| |
| @node Mixing Elaboration Models,What to Do If the Default Elaboration Behavior Fails,Elaboration Issues for Library Tasks,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{2ce}@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{2cf} |
| @section 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 |
| @strong{a unit compiled with the static model cannot |
| be |withed| 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 |
| @cite{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 @emph{with} a unit that meets at least one of the |
| following criteria: |
| |
| |
| @itemize * |
| |
| @item |
| The @emph{with}ed unit is itself compiled with dynamic elaboration |
| checks (that is with the @emph{-gnatE} switch. |
| |
| @item |
| The @emph{with}ed unit is an internal GNAT implementation unit from |
| the System, Interfaces, Ada, or GNAT hierarchies. |
| |
| @item |
| The @emph{with}ed unit has pragma Preelaborate or pragma Pure. |
| |
| @item |
| The @emph{with}ing unit (that is the client) has an explicit pragma |
| @cite{Elaborate_All} for the @emph{with}ed unit. |
| @end itemize |
| |
| If this rule is violated, that is if a unit with dynamic elaboration |
| checks @emph{with}s a unit that does not meet one of the above four |
| criteria, then the binder (@cite{gnatbind}) will issue a warning |
| similar to that in the following example: |
| |
| @example |
| warning: "x.ads" has dynamic elaboration checks and with's |
| warning: "y.ads" which has static elaboration checks |
| @end example |
| |
| 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 @emph{-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 @emph{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. |
| |
| @node What to Do If the Default Elaboration Behavior Fails,Elaboration for Indirect Calls,Mixing Elaboration Models,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{2d0}@anchor{gnat_ugn/elaboration_order_handling_in_gnat what-to-do-if-the-default-elaboration-behavior-fails}@anchor{2c9} |
| @section What to Do If the Default Elaboration Behavior Fails |
| |
| |
| If the binder cannot find an acceptable order, it outputs detailed |
| diagnostics. For example: |
| |
| @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 -gnatel |
| 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)" |
| @end example |
| |
| In this case we have a cycle that the binder cannot break. On the one |
| hand, there is an explicit pragma Elaborate in @cite{proc} for |
| @cite{pack}. This means that the body of @cite{pack} must be elaborated |
| before the body of @cite{proc}. On the other hand, there is elaboration |
| code in @cite{pack} that calls a subprogram in @cite{proc}. This means |
| that for maximum safety, there should really be a pragma |
| Elaborate_All in @cite{pack} for @cite{proc} which would require that |
| the body of @cite{proc} be elaborated before the body of |
| @cite{pack}. Clearly both requirements cannot be satisfied. |
| Faced with a circularity of this kind, you have three different options. |
| |
| |
| @itemize * |
| |
| @item |
| @emph{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. |
| |
| @item |
| @emph{Perform dynamic checks} |
| |
| If the compilations are done using the @emph{-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 @cite{Elaborate} or @cite{Elaborate_All} pragmas. The behavior then is |
| exactly as specified in the @cite{Ada Reference Manual}. |
| The binder will generate |
| an executable program that may or may not raise @cite{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. |
| |
| @item |
| @emph{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 |
| @cite{Suppress (Elaboration_Check)} to suppress all such checks. For |
| example this pragma could be placed in the @code{gnat.adc} file. |
| |
| @item |
| @emph{Suppress checks selectively} |
| |
| When you know that certain calls or instantiations in elaboration code cannot |
| possibly lead to an elaboration error, and the binder nevertheless complains |
| about implicit @cite{Elaborate} and @cite{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 @cite{Suppress (Elaboration_Check)} can be |
| used with different granularity to suppress warnings and break elaboration |
| circularities: |
| |
| |
| @itemize * |
| |
| @item |
| Place the pragma that names the called subprogram in the declarative part |
| that contains the call. |
| |
| @item |
| Place the pragma in the declarative part, without naming an entity. This |
| disables warnings on all calls in the corresponding declarative region. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| Use Pragma Elaborate. |
| |
| As previously described in section @ref{2ca,,Treatment of Pragma Elaborate}, |
| GNAT in static mode assumes that a @cite{pragma} Elaborate indicates correctly |
| that no elaboration checks are required on calls to the designated unit. |
| There may be cases in which the caller knows that no transitive calls |
| can occur, so that a @cite{pragma Elaborate} will be sufficient in a |
| case where @cite{pragma Elaborate_All} would cause a circularity. |
| @end itemize |
| |
| These five cases are listed in order of decreasing safety, and therefore |
| require increasing programmer care in their application. Consider the |
| following program: |
| |
| @example |
| 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; |
| @end example |
| |
| In the absence of any pragmas, an attempt to bind this program produces |
| the following diagnostics: |
| |
| @example |
| 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 -gnatel 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)" |
| @end example |
| |
| The sources of the circularity are the two calls to @cite{Pack2.Pure} and |
| @cite{Pack2.F2} in the body of @cite{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 @cite{Pure} is safe because this function does not depend on the |
| state of @cite{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 @cite{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 @cite{F2} requires that @cite{F1} |
| be already elaborated. |
| @end itemize |
| |
| 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 @emph{-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 |
| information messages generated with the @emph{-gnatel} |
| 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 |
| @emph{-p (pessimistic elaboration order)} switch for @cite{gnatbind}. |
| Normally the binder tries to find an order that has the best chance |
| of avoiding elaboration problems. However, if this switch is used, 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 ACATS 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 @emph{-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 ACATS tests.) |
| |
| @node Elaboration for Indirect Calls,Summary of Procedures for Elaboration Control,What to Do If the Default Elaboration Behavior Fails,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{2d1}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-for-indirect-calls}@anchor{2d2} |
| @section Elaboration for Indirect Calls |
| |
| |
| @geindex Dispatching calls |
| |
| @geindex Indirect calls |
| |
| In rare cases, the static elaboration model fails to prevent |
| dispatching calls to not-yet-elaborated subprograms. In such cases, we |
| fall back to run-time checks; premature calls to any primitive |
| operation of a tagged type before the body of the operation has been |
| elaborated will raise @cite{Program_Error}. |
| |
| Access-to-subprogram types, however, are handled conservatively, and |
| do not require run-time checks. This was not true in earlier versions |
| of the compiler; you can use the @emph{-gnatd.U} debug switch to |
| revert to the old behavior if the new conservative behavior causes |
| elaboration cycles. Here, 'conservative' means that if you do |
| @cite{P'Access} during elaboration, the compiler will assume that you |
| might call @cite{P} indirectly during elaboration, so it adds an |
| implicit @cite{pragma Elaborate_All} on the library unit containing |
| @cite{P}. The @emph{-gnatd.U} switch is safe if you know there are |
| no such calls. If the program worked before, it will continue to work |
| with @emph{-gnatd.U}. But beware that code modifications such as |
| adding an indirect call can cause erroneous behavior in the presence |
| of @emph{-gnatd.U}. |
| |
| @node Summary of Procedures for Elaboration Control,Other Elaboration Order Considerations,Elaboration for Indirect Calls,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{2d3}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{2d4} |
| @section Summary of Procedures for Elaboration Control |
| |
| |
| @geindex 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 to other compilers than GNAT, then use the |
| @emph{-gnatel} |
| switch to generate messages about missing @cite{Elaborate} or |
| @cite{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 |
| @emph{-gnatE} switch to generate dynamic elaboration checks, |
| and, if you are sure there really are no elaboration problems, |
| use a global pragma @cite{Suppress (Elaboration_Check)}. |
| |
| @node Other Elaboration Order Considerations,Determining the Chosen Elaboration Order,Summary of Procedures for Elaboration Control,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{2d5}@anchor{gnat_ugn/elaboration_order_handling_in_gnat other-elaboration-order-considerations}@anchor{2d6} |
| @section 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: |
| |
| @example |
| with Init_Constants; |
| package Constants is |
| X : Integer := 0; |
| Y : Integer := 0; |
| end Constants; |
| |
| package Init_Constants is |
| procedure P; --* require a body* |
| end Init_Constants; |
| |
| with Constants; |
| package body Init_Constants is |
| procedure P 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; |
| @end example |
| |
| In this example, there is more than one valid order of elaboration. For |
| example both the following are correct orders: |
| |
| @example |
| Init_Constants spec |
| Constants spec |
| Calc spec |
| Init_Constants body |
| Main body |
| @end example |
| |
| and |
| |
| @example |
| Init_Constants spec |
| Init_Constants body |
| Constants spec |
| Calc spec |
| Main body |
| @end example |
| |
| 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 @cite{Calc} initializes @cite{Z} to zero, and then the main program |
| runs with this value of zero. But in the second order, the elaboration |
| routine of @cite{Calc} runs after the body of Init_Constants has set |
| @cite{X} and @cite{Y} and thus @cite{Z} is set to 7 before @cite{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: |
| |
| @example |
| pragma Elaborate_All (Constants); |
| @end example |
| |
| which requires that the body (if any) and spec of @cite{Constants}, |
| as well as the body and spec of any unit @emph{with}ed by |
| @cite{Constants} be elaborated before @cite{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 @cite{Elaborate} or |
| @cite{Elaborate_All} pragmas, then indeed it is possible that two different |
| compilers can choose different orders. |
| |
| However, GNAT does attempt to diagnose the common situation where there |
| are uninitialized variables in the visible part of a package spec, and the |
| corresponding package body has an elaboration block that directly or |
| indirectly initialized one or more of these variables. This is the situation |
| in which a pragma Elaborate_Body is usually desirable, and GNAT will generate |
| a warning that suggests this addition if it detects this situation. |
| |
| The @cite{gnatbind} @emph{-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 @cite{Elaborate} pragmas. For the example above, we have the |
| following output: |
| |
| @example |
| $ gnatmake -f -q main |
| $ main |
| 7 |
| $ gnatmake -f -q main -bargs -p |
| $ main |
| 0 |
| @end example |
| |
| 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 |
| @cite{Elaborate} or @cite{Elaborate_All} pragmas to ensure the desired order. |
| |
| @node Determining the Chosen Elaboration Order,,Other Elaboration Order Considerations,Elaboration Order Handling in GNAT |
| @anchor{gnat_ugn/elaboration_order_handling_in_gnat determining-the-chosen-elaboration-order}@anchor{2d7}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id15}@anchor{2d8} |
| @section Determining the Chosen Elaboration Order |
| |
| |
| To see the elaboration order that the binder chooses, you can look at |
| the last part of the file:@cite{b~xxx.adb} binder output file. Here is an example: |
| |
| @example |
| System.Soft_Links'Elab_Body; |
| E14 := True; |
| System.Secondary_Stack'Elab_Body; |
| E18 := True; |
| System.Exception_Table'Elab_Body; |
| E24 := True; |
| Ada.Io_Exceptions'Elab_Spec; |
| E67 := True; |
| Ada.Tags'Elab_Spec; |
| Ada.Streams'Elab_Spec; |
| E43 := True; |
| Interfaces.C'Elab_Spec; |
| E69 := True; |
| System.Finalization_Root'Elab_Spec; |
| E60 := True; |
| System.Os_Lib'Elab_Body; |
| E71 := True; |
| System.Finalization_Implementation'Elab_Spec; |
| System.Finalization_Implementation'Elab_Body; |
| E62 := True; |
| Ada.Finalization'Elab_Spec; |
| E58 := True; |
| Ada.Finalization.List_Controller'Elab_Spec; |
| E76 := True; |
| System.File_Control_Block'Elab_Spec; |
| E74 := True; |
| System.File_Io'Elab_Body; |
| E56 := True; |
| Ada.Tags'Elab_Body; |
| E45 := True; |
| Ada.Text_Io'Elab_Spec; |
| Ada.Text_Io'Elab_Body; |
| E07 := True; |
| @end example |
| |
| Here Elab_Spec elaborates the spec |
| and Elab_Body elaborates the body. The assignments to the @code{E@emph{xx}} flags |
| flag that the corresponding body is now elaborated. |
| |
| You can also ask the binder to generate a more |
| readable list of the elaboration order using the |
| @cite{-l} switch when invoking the binder. Here is |
| an example of the output generated by this switch: |
| |
| @example |
| ada (spec) |
| interfaces (spec) |
| system (spec) |
| system.case_util (spec) |
| system.case_util (body) |
| system.concat_2 (spec) |
| system.concat_2 (body) |
| system.concat_3 (spec) |
| system.concat_3 (body) |
| system.htable (spec) |
| system.parameters (spec) |
| system.parameters (body) |
| system.crtl (spec) |
| interfaces.c_streams (spec) |
| interfaces.c_streams (body) |
| system.restrictions (spec) |
| system.restrictions (body) |
| system.standard_library (spec) |
| system.exceptions (spec) |
| system.exceptions (body) |
| system.storage_elements (spec) |
| system.storage_elements (body) |
| system.secondary_stack (spec) |
| system.stack_checking (spec) |
| system.stack_checking (body) |
| system.string_hash (spec) |
| system.string_hash (body) |
| system.htable (body) |
| system.strings (spec) |
| system.strings (body) |
| system.traceback (spec) |
| system.traceback (body) |
| system.traceback_entries (spec) |
| system.traceback_entries (body) |
| ada.exceptions (spec) |
| ada.exceptions.last_chance_handler (spec) |
| system.soft_links (spec) |
| system.soft_links (body) |
| ada.exceptions.last_chance_handler (body) |
| system.secondary_stack (body) |
| system.exception_table (spec) |
| system.exception_table (body) |
| ada.io_exceptions (spec) |
| ada.tags (spec) |
| ada.streams (spec) |
| interfaces.c (spec) |
| interfaces.c (body) |
| system.finalization_root (spec) |
| system.finalization_root (body) |
| system.memory (spec) |
| system.memory (body) |
| system.standard_library (body) |
| system.os_lib (spec) |
| system.os_lib (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) |
| system.val_uns (spec) |
| system.val_util (spec) |
| system.val_util (body) |
| system.val_uns (body) |
| system.wch_con (spec) |
| system.wch_con (body) |
| system.wch_cnv (spec) |
| system.wch_jis (spec) |
| system.wch_jis (body) |
| system.wch_cnv (body) |
| system.wch_stw (spec) |
| system.wch_stw (body) |
| ada.tags (body) |
| ada.exceptions (body) |
| ada.text_io (spec) |
| ada.text_io (body) |
| text_io (spec) |
| gdbstr (body) |
| @end example |
| |
| @node Inline Assembler,GNU Free Documentation License,Elaboration Order Handling in GNAT,Top |
| @anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{12}@anchor{gnat_ugn/inline_assembler doc}@anchor{2d9}@anchor{gnat_ugn/inline_assembler id1}@anchor{2da} |
| @chapter Inline Assembler |
| |
| |
| @geindex 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 @cite{System.Machine_Code}, which incorporates the gcc |
| Inline Assembler. The Inline Assembler approach offers a number of advantages, |
| including the following: |
| |
| |
| @itemize * |
| |
| @item |
| No need to use non-Ada tools |
| |
| @item |
| Consistent interface over different targets |
| |
| @item |
| Automatic usage of the proper calling conventions |
| |
| @item |
| Access to Ada constants and variables |
| |
| @item |
| Definition of intrinsic routines |
| |
| @item |
| Possibility of inlining a subprogram comprising assembler code |
| |
| @item |
| Code optimizer can take Inline Assembler code into account |
| @end itemize |
| |
| This appendix 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:: |
| |
| @end menu |
| |
| @node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler |
| @anchor{gnat_ugn/inline_assembler id2}@anchor{2db}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{2dc} |
| @section 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 @emph{as} (and which is often referred to as 'AT&T syntax'). |
| The following table summarizes the main features of @emph{as} syntax |
| and points out the differences from the Intel conventions. |
| See the gcc @emph{as} and @emph{gas} (an @emph{as} macro |
| pre-processor) documentation for further information. |
| |
| |
| @display |
| @emph{Register names}@w{ } |
| @display |
| gcc / @emph{as}: Prefix with '%'; for example @cite{%eax}@w{ } |
| Intel: No extra punctuation; for example @cite{eax}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| |
| @display |
| @emph{Immediate operand}@w{ } |
| @display |
| gcc / @emph{as}: Prefix with '$'; for example @cite{$4}@w{ } |
| Intel: No extra punctuation; for example @cite{4}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| |
| @display |
| @emph{Address}@w{ } |
| @display |
| gcc / @emph{as}: Prefix with '$'; for example @cite{$loc}@w{ } |
| Intel: No extra punctuation; for example @cite{loc}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| |
| @display |
| @emph{Memory contents}@w{ } |
| @display |
| gcc / @emph{as}: No extra punctuation; for example @cite{loc}@w{ } |
| Intel: Square brackets; for example @cite{[loc]}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| |
| @display |
| @emph{Register contents}@w{ } |
| @display |
| gcc / @emph{as}: Parentheses; for example @cite{(%eax)}@w{ } |
| Intel: Square brackets; for example @cite{[eax]}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| |
| @display |
| @emph{Hexadecimal numbers}@w{ } |
| @display |
| gcc / @emph{as}: Leading '0x' (C language syntax); for example @cite{0xA0}@w{ } |
| Intel: Trailing 'h'; for example @cite{A0h}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| |
| @display |
| @emph{Operand size}@w{ } |
| @display |
| gcc / @emph{as}: Explicit in op code; for example @cite{movw} to move a 16-bit word@w{ } |
| Intel: Implicit, deduced by assembler; for example @cite{mov}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| |
| @display |
| @emph{Instruction repetition}@w{ } |
| @display |
| gcc / @emph{as}: Split into two lines; for example@w{ } |
| @display |
| @cite{rep}@w{ } |
| @cite{stosl}@w{ } |
| @end display |
| Intel: Keep on one line; for example @cite{rep stosl}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| |
| @display |
| @emph{Order of operands}@w{ } |
| @display |
| gcc / @emph{as}: Source first; for example @cite{movw $4@comma{} %eax}@w{ } |
| Intel: Destination first; for example @cite{mov eax@comma{} 4}@w{ } |
| @end display |
| @end display |
| |
| |
| |
| @node A Simple Example of Inline Assembler,Output Variables in Inline Assembler,Basic Assembler Syntax,Inline Assembler |
| @anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{2dd}@anchor{gnat_ugn/inline_assembler id3}@anchor{2de} |
| @section A Simple Example of Inline Assembler |
| |
| |
| The following example will generate a single assembly language statement, |
| @cite{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. |
| |
| @quotation |
| |
| @example |
| with System.Machine_Code; use System.Machine_Code; |
| procedure Nothing is |
| begin |
| Asm ("nop"); |
| end Nothing; |
| @end example |
| @end quotation |
| |
| @cite{Asm} is a procedure declared in package @cite{System.Machine_Code}; |
| here it takes one parameter, a @emph{template string} that must be a static |
| expression and that will form the generated instruction. |
| @cite{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 @cite{Asm}; a complete specification of the syntax |
| is found in the @cite{Machine_Code_Insertions} section of the |
| @cite{GNAT Reference Manual}. |
| |
| Under the standard GNAT conventions, the @cite{Nothing} procedure |
| should be in a file named @code{nothing.adb}. |
| You can build the executable in the usual way: |
| |
| @quotation |
| |
| @example |
| $ gnatmake nothing |
| @end example |
| @end quotation |
| |
| 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: |
| |
| @quotation |
| |
| @example |
| $ gcc -c -S -fomit-frame-pointer -gnatp nothing.adb |
| @end example |
| @end quotation |
| |
| where the options are: |
| |
| |
| @itemize * |
| |
| @item |
| |
| @table @asis |
| |
| @item @code{-c} |
| |
| compile only (no bind or link) |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @code{-S} |
| |
| generate assembler listing |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @code{-fomit-frame-pointer} |
| |
| do not set up separate stack frames |
| @end table |
| |
| @item |
| |
| @table @asis |
| |
| @item @code{-gnatp} |
| |
| do not add runtime checks |
| @end table |
| @end itemize |
| |
| 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 @cite{.s} |
| extension. In our example, the file @code{nothing.s} has the following |
| contents: |
| |
| @quotation |
| |
| @example |
| .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 |
| @end example |
| @end quotation |
| |
| The assembly code you included is clearly indicated by |
| the compiler, between the @cite{#APP} and @cite{#NO_APP} |
| delimiters. The character before the 'APP' and 'NOAPP' |
| can differ on different targets. For example, GNU/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 |
| @emph{as} assembler that comes with gcc. |
| |
| Assembling the file using the command |
| |
| @quotation |
| |
| @example |
| $ as nothing.s |
| @end example |
| @end quotation |
| |
| 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, @emph{as} will generate an object file |
| @code{nothing.out}. |
| |
| @node Output Variables in Inline Assembler,Input Variables in Inline Assembler,A Simple Example of Inline Assembler,Inline Assembler |
| @anchor{gnat_ugn/inline_assembler id4}@anchor{2df}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{2e0} |
| @section 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. |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| 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: |
| |
| @quotation |
| |
| @example |
| #APP |
| pushfl |
| popl %eax |
| movl %eax, -40(%ebp) |
| #NO_APP |
| @end example |
| @end quotation |
| |
| It would have been legal to write the Asm invocation as: |
| |
| @quotation |
| |
| @example |
| Asm ("pushfl popl %%eax movl %%eax, %0") |
| @end example |
| @end quotation |
| |
| but in the generated assembler file, this would come out as: |
| |
| @quotation |
| |
| @example |
| #APP |
| pushfl popl %eax movl %eax, -40(%ebp) |
| #NO_APP |
| @end example |
| @end quotation |
| |
| 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 @cite{%%eax}. |
| In the generated assembly code, one of the percent signs will be stripped off. |
| |
| Names such as @cite{%0}, @cite{%1}, @cite{%2}, etc., denote input or output |
| variables: operands you later define using @cite{Input} or @cite{Output} |
| parameters to @cite{Asm}. |
| An output variable is illustrated in |
| the third statement in the Asm template string: |
| |
| @quotation |
| |
| @example |
| movl %%eax, %0 |
| @end example |
| @end quotation |
| |
| The intent is to store the contents of the eax register in a variable that can |
| be accessed in Ada. Simply writing @cite{movl %%eax@comma{} Flags} would not |
| necessarily work, since the compiler might optimize by using a register |
| to hold Flags, and the expansion of the @cite{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 @cite{%0} output variable. |
| |
| Information about the output variable is supplied in the @cite{Outputs} |
| parameter to @cite{Asm}: |
| |
| @quotation |
| |
| @example |
| Outputs => Unsigned_32'Asm_Output ("=g", Flags)); |
| @end example |
| @end quotation |
| |
| The output is defined by the @cite{Asm_Output} attribute of the target type; |
| the general format is |
| |
| @quotation |
| |
| @example |
| Type'Asm_Output (constraint_string, variable_name) |
| @end example |
| @end quotation |
| |
| The constraint string directs the compiler how |
| to store/access the associated variable. In the example |
| |
| @quotation |
| |
| @example |
| Unsigned_32'Asm_Output ("=m", Flags); |
| @end example |
| @end quotation |
| |
| the @cite{"m"} (memory) constraint tells the compiler that the variable |
| @cite{Flags} should be stored in a memory variable, thus preventing |
| the optimizer from keeping it in a register. In contrast, |
| |
| @quotation |
| |
| @example |
| Unsigned_32'Asm_Output ("=r", Flags); |
| @end example |
| @end quotation |
| |
| uses the @cite{"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 @cite{Get_Flags} example, we used the @cite{"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: |
| |
| @quotation |
| |
| |
| @multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
| @item |
| |
| @emph{=} |
| |
| @tab |
| |
| output constraint |
| |
| @item |
| |
| @emph{g} |
| |
| @tab |
| |
| global (i.e., can be stored anywhere) |
| |
| @item |
| |
| @emph{m} |
| |
| @tab |
| |
| in memory |
| |
| @item |
| |
| @emph{I} |
| |
| @tab |
| |
| a constant |
| |
| @item |
| |
| @emph{a} |
| |
| @tab |
| |
| use eax |
| |
| @item |
| |
| @emph{b} |
| |
| @tab |
| |
| use ebx |
| |
| @item |
| |
| @emph{c} |
| |
| @tab |
| |
| use ecx |
| |
| @item |
| |
| @emph{d} |
| |
| @tab |
| |
| use edx |
| |
| @item |
| |
| @emph{S} |
| |
| @tab |
| |
| use esi |
| |
| @item |
| |
| @emph{D} |
| |
| @tab |
| |
| use edi |
| |
| @item |
| |
| @emph{r} |
| |
| @tab |
| |
| use one of eax, ebx, ecx or edx |
| |
| @item |
| |
| @emph{q} |
| |
| @tab |
| |
| use one of eax, ebx, ecx, edx, esi or edi |
| |
| @end multitable |
| |
| @end quotation |
| |
| The full set of constraints is described in the gcc and @emph{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 @code{%@emph{n}} notation, where @emph{n} is a non-negative |
| integer. Thus in |
| |
| @quotation |
| |
| @example |
| 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)); |
| @end example |
| @end quotation |
| |
| @cite{%0} will be replaced in the expanded code by the appropriate operand, |
| whatever |
| the compiler decided for the @cite{Flags} variable. |
| |
| In general, you may have any number of output variables: |
| |
| |
| @itemize * |
| |
| @item |
| Count the operands starting at 0; thus @cite{%0}, @cite{%1}, etc. |
| |
| @item |
| Specify the @cite{Outputs} parameter as a parenthesized comma-separated list |
| of @cite{Asm_Output} attributes |
| @end itemize |
| |
| For example: |
| |
| @quotation |
| |
| @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 |
| @end example |
| @end quotation |
| |
| where @cite{Var_A}, @cite{Var_B}, and @cite{Var_C} are variables |
| in the Ada program. |
| |
| As a variation on the @cite{Get_Flags} example, we can use the constraints |
| string to direct the compiler to store the eax register into the @cite{Flags} |
| variable, instead of including the store instruction explicitly in the |
| @cite{Asm} template string: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| The @cite{"a"} constraint tells the compiler that the @cite{Flags} |
| variable will come from the eax register. Here is the resulting code: |
| |
| @quotation |
| |
| @example |
| #APP |
| pushfl |
| popl %eax |
| #NO_APP |
| movl %eax,-40(%ebp) |
| @end example |
| @end quotation |
| |
| 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: |
| |
| @quotation |
| |
| @example |
| 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; |
| @end example |
| @end quotation |
| |
| @node Input Variables in Inline Assembler,Inlining Inline Assembler Code,Output Variables in Inline Assembler,Inline Assembler |
| @anchor{gnat_ugn/inline_assembler id5}@anchor{2e1}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{2e2} |
| @section 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: |
| |
| @quotation |
| |
| @example |
| 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", |
| Outputs => Unsigned_32'Asm_Output ("=a", Result), |
| Inputs => Unsigned_32'Asm_Input ("a", Value)); |
| 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; |
| @end example |
| @end quotation |
| |
| The @cite{Outputs} parameter to @cite{Asm} specifies |
| that the result will be in the eax register and that it is to be stored |
| in the @cite{Result} variable. |
| |
| The @cite{Inputs} parameter looks much like the @cite{Outputs} parameter, |
| but with an @cite{Asm_Input} attribute. |
| The @cite{"="} 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, still starts at the first output statement, |
| and continues with the input statements. |
| |
| Just as the @cite{Outputs} parameter causes the register to be stored into the |
| target variable after execution of the assembler statements, so does the |
| @cite{Inputs} parameter cause its variable to be loaded into the register |
| before execution of the assembler statements. |
| |
| Thus the effect of the @cite{Asm} invocation is: |
| |
| |
| @itemize * |
| |
| @item |
| load the 32-bit value of @cite{Value} into eax |
| |
| @item |
| execute the @cite{incl %eax} instruction |
| |
| @item |
| store the contents of eax into the @cite{Result} variable |
| @end itemize |
| |
| The resulting assembler file (with @emph{-O2} optimization) contains: |
| |
| @quotation |
| |
| @example |
| _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 |
| @end example |
| @end quotation |
| |
| @node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler |
| @anchor{gnat_ugn/inline_assembler id6}@anchor{2e3}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{2e4} |
| @section Inlining Inline Assembler Code |
| |
| |
| For a short subprogram such as the @cite{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 @cite{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: |
| |
| @quotation |
| |
| @example |
| 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", |
| Outputs => Unsigned_32'Asm_Output ("=a", Result), |
| Inputs => Unsigned_32'Asm_Input ("a", Value)); |
| 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; |
| @end example |
| @end quotation |
| |
| Compile the program with both optimization (@emph{-O2}) and inlining |
| (@emph{-gnatn}) enabled. |
| |
| The @cite{Incr} function is still compiled as usual, but at the |
| point in @cite{Increment} where our function used to be called: |
| |
| @quotation |
| |
| @example |
| pushl %edi |
| call _increment__incr.1 |
| @end example |
| @end quotation |
| |
| the code for the function body directly appears: |
| |
| @quotation |
| |
| @example |
| movl %esi,%eax |
| #APP |
| incl %eax |
| #NO_APP |
| movl %eax,%edx |
| @end example |
| @end quotation |
| |
| thus saving the overhead of stack frame setup and an out-of-line call. |
| |
| @node Other Asm Functionality,,Inlining Inline Assembler Code,Inline Assembler |
| @anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{2e5}@anchor{gnat_ugn/inline_assembler id7}@anchor{2e6} |
| @section Other @cite{Asm} Functionality |
| |
| |
| This section describes two important parameters to the @cite{Asm} |
| procedure: @cite{Clobber}, which identifies register usage; |
| and @cite{Volatile}, which inhibits unwanted optimizations. |
| |
| @menu |
| * The Clobber Parameter:: |
| * The Volatile Parameter:: |
| |
| @end menu |
| |
| @node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality |
| @anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{2e7}@anchor{gnat_ugn/inline_assembler id8}@anchor{2e8} |
| @subsection The @cite{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., |
| @cite{"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 @cite{mull} |
| storing its result in both eax and edx). |
| It can also arise from explicit register usage in your |
| assembly code; for example: |
| |
| @quotation |
| |
| @example |
| Asm ("movl %0, %%ebx" & LF & HT & |
| "movl %%ebx, %1", |
| Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), |
| Inputs => Unsigned_32'Asm_Input ("g", Var_In)); |
| @end example |
| @end quotation |
| |
| where the compiler (since it does not analyze the @cite{Asm} template string) |
| does not know you are using the ebx register. |
| |
| In such cases you need to supply the @cite{Clobber} parameter to @cite{Asm}, |
| to identify the registers that will be used by your assembly code: |
| |
| @quotation |
| |
| @example |
| Asm ("movl %0, %%ebx" & LF & HT & |
| "movl %%ebx, %1", |
| Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), |
| Inputs => Unsigned_32'Asm_Input ("g", Var_In), |
| Clobber => "ebx"); |
| @end example |
| @end quotation |
| |
| The Clobber parameter is a static string expression specifying the |
| register(s) you are using. Note that register names are @emph{not} prefixed |
| by a percent sign. Also, if more than one register is used then their names |
| are separated by commas; e.g., @cite{"eax@comma{} ebx"} |
| |
| The @cite{Clobber} parameter has several additional uses: |
| |
| |
| @itemize * |
| |
| @item |
| Use 'register' name @cite{cc} to indicate that flags might have changed |
| |
| @item |
| Use 'register' name @cite{memory} if you changed a memory location |
| @end itemize |
| |
| @node The Volatile Parameter,,The Clobber Parameter,Other Asm Functionality |
| @anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{2e9}@anchor{gnat_ugn/inline_assembler id9}@anchor{2ea} |
| @subsection The @cite{Volatile} Parameter |
| |
| |
| @geindex Volatile parameter |
| |
| Compiler optimizations in the presence of Inline Assembler may sometimes have |
| unwanted effects. For example, when an @cite{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 @cite{Volatile} parameter to @cite{True}; for example: |
| |
| @quotation |
| |
| @example |
| Asm ("movl %0, %%ebx" & LF & HT & |
| "movl %%ebx, %1", |
| Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), |
| Inputs => Unsigned_32'Asm_Input ("g", Var_In), |
| Clobber => "ebx", |
| Volatile => True); |
| @end example |
| @end quotation |
| |
| By default, @cite{Volatile} is set to @cite{False} unless there is no |
| @cite{Outputs} parameter. |
| |
| Although setting @cite{Volatile} to @cite{True} prevents unwanted |
| optimizations, it will also disable other optimizations that might be |
| important for efficiency. In general, you should set @cite{Volatile} |
| to @cite{True} only if the compiler's optimizations have created |
| problems. |
| |
| @node GNU Free Documentation License,Index,Inline Assembler,Top |
| @anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{2eb}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{2ec} |
| @chapter GNU Free Documentation License |
| |
| |
| Version 1.3, 3 November 2008 |
| |
| Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc |
| @indicateurl{http://fsf.org/} |
| |
| Everyone is permitted to copy and distribute verbatim copies of this |
| license document, but changing it is not allowed. |
| |
| @strong{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. |
| |
| @strong{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 @strong{Document}, below, |
| refers to any such manual or work. Any member of the public is a |
| licensee, and is addressed as "@strong{you}". You accept the license if you |
| copy, modify or distribute the work in a way requiring permission |
| under copyright law. |
| |
| A "@strong{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 "@strong{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 "@strong{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 "@strong{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 "@strong{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 @strong{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 "@strong{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. |
| |
| The "@strong{publisher}" means any person or entity that distributes |
| copies of the Document to the public. |
| |
| A section "@strong{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 "@strong{Acknowledgements}", |
| "@strong{Dedications}", "@strong{Endorsements}", or "@strong{History}".) |
| To "@strong{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. |
| |
| @strong{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. |
| |
| @strong{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. |
| |
| @strong{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: |
| |
| |
| @enumerate A |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| State on the Title page the name of the publisher of the |
| Modified Version, as the publisher. |
| |
| @item |
| Preserve all the copyright notices of the Document. |
| |
| @item |
| Add an appropriate copyright notice for your modifications |
| adjacent to the other copyright notices. |
| |
| @item |
| 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. |
| |
| @item |
| Preserve in that license notice the full lists of Invariant Sections |
| and required Cover Texts given in the Document's license notice. |
| |
| @item |
| Include an unaltered copy of this License. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| 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. |
| |
| @item |
| Delete any section Entitled "Endorsements". Such a section |
| may not be included in the Modified Version. |
| |
| @item |
| Do not retitle any existing section to be Entitled "Endorsements" |
| or to conflict in title with any Invariant Section. |
| |
| @item |
| Preserve any Warranty Disclaimers. |
| @end enumerate |
| |
| 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. |
| |
| @strong{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". |
| |
| @strong{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. |
| |
| @strong{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 in 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. |
| |
| @strong{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 Warranty 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. |
| |
| @strong{9. TERMINATION} |
| |
| You may not copy, modify, sublicense, or distribute the Document |
| except as expressly provided under this License. Any attempt |
| otherwise to copy, modify, sublicense, or distribute it is void, and |
| will automatically terminate your rights under this License. |
| |
| However, if you cease all violation of this License, then your license |
| from a particular copyright holder is reinstated (a) provisionally, |
| unless and until the copyright holder explicitly and finally |
| terminates your license, and (b) permanently, if the copyright holder |
| fails to notify you of the violation by some reasonable means prior to |
| 60 days after the cessation. |
| |
| Moreover, your license from a particular copyright holder is |
| reinstated permanently if the copyright holder notifies you of the |
| violation by some reasonable means, this is the first time you have |
| received notice of violation of this License (for any work) from that |
| copyright holder, and you cure the violation prior to 30 days after |
| your receipt of the notice. |
| |
| Termination of your rights under this section does not terminate the |
| licenses of parties who have received copies or rights from you under |
| this License. If your rights have been terminated and not permanently |
| reinstated, receipt of a copy of some or all of the same material does |
| not give you any rights to use it. |
| |
| @strong{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 |
| @indicateurl{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. If the Document |
| specifies that a proxy can decide which future versions of this |
| License can be used, that proxy's public statement of acceptance of a |
| version permanently authorizes you to choose that version for the |
| Document. |
| |
| @strong{11. RELICENSING} |
| |
| "Massive Multiauthor Collaboration Site" (or "MMC Site") means any |
| World Wide Web server that publishes copyrightable works and also |
| provides prominent facilities for anybody to edit those works. A |
| public wiki that anybody can edit is an example of such a server. A |
| "Massive Multiauthor Collaboration" (or "MMC") contained in the |
| site means any set of copyrightable works thus published on the MMC |
| site. |
| |
| "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 |
| license published by Creative Commons Corporation, a not-for-profit |
| corporation with a principal place of business in San Francisco, |
| California, as well as future copyleft versions of that license |
| published by that same organization. |
| |
| "Incorporate" means to publish or republish a Document, in whole or |
| in part, as part of another Document. |
| |
| An MMC is "eligible for relicensing" if it is licensed under this |
| License, and if all works that were first published under this License |
| somewhere other than this MMC, and subsequently incorporated in whole |
| or in part into the MMC, (1) had no cover texts or invariant sections, |
| and (2) were thus incorporated prior to November 1, 2008. |
| |
| The operator of an MMC Site may republish an MMC contained in the site |
| under CC-BY-SA on the same site at any time before August 1, 2009, |
| provided the MMC is eligible for relicensing. |
| |
| @strong{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: |
| |
| @quotation |
| |
| Copyright © 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.3 |
| 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". |
| @end quotation |
| |
| If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, |
| replace the "with ... Texts." line with this: |
| |
| @quotation |
| |
| with the Invariant Sections being LIST THEIR TITLES, with the |
| Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. |
| @end quotation |
| |
| 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. |
| |
| @node Index,,GNU Free Documentation License,Top |
| @unnumbered Index |
| |
| |
| @printindex ge |
| |
| |
| @c %**end of body |
| @bye |
