1 \input texinfo @c -*-texinfo-*-
4 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
6 @c GNAT DOCUMENTATION o
10 @c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
12 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
14 @setfilename gnat_ugn.info
17 Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation,
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.2 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with no Front-Cover Texts and with no Back-Cover
24 Texts. A copy of the license is included in the section entitled
25 ``GNU Free Documentation License''.
28 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
30 @c GNAT_UGN Style Guide
32 @c 1. Always put a @noindent on the line before the first paragraph
33 @c after any of these commands:
45 @c 2. DO NOT use @example. Use @smallexample instead.
46 @c a) DO NOT use highlighting commands (@b{}, @i{}) inside an @smallexample
47 @c context. These can interfere with the readability of the texi
48 @c source file. Instead, use one of the following annotated
49 @c @smallexample commands, and preprocess the texi file with the
50 @c ada2texi tool (which generates appropriate highlighting):
51 @c @smallexample @c ada
52 @c @smallexample @c adanocomment
53 @c @smallexample @c projectfile
54 @c b) The "@c ada" markup will result in boldface for reserved words
55 @c and italics for comments
56 @c c) The "@c adanocomment" markup will result only in boldface for
57 @c reserved words (comments are left alone)
58 @c d) The "@c projectfile" markup is like "@c ada" except that the set
59 @c of reserved words include the new reserved words for project files
61 @c 3. Each @chapter, @section, @subsection, @subsubsection, etc.
62 @c command must be preceded by two empty lines
64 @c 4. The @item command should be on a line of its own if it is in an
65 @c @itemize or @enumerate command.
67 @c 5. When talking about ALI files use "ALI" (all uppercase), not "Ali"
70 @c 6. DO NOT put trailing spaces at the end of a line. Such spaces will
71 @c cause the document build to fail.
73 @c 7. DO NOT use @cartouche for examples that are longer than around 10 lines.
74 @c This command inhibits page breaks, so long examples in a @cartouche can
75 @c lead to large, ugly patches of empty space on a page.
77 @c NOTE: This file should be submitted to xgnatugn with either the vms flag
78 @c or the unw flag set. The unw flag covers topics for both Unix and
81 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
84 @c This flag is used where the text refers to conditions that exist when the
85 @c text was entered into the document but which may change over time.
86 @c Update the setting for the flag, and (if necessary) the text surrounding,
87 @c the references to the flag, on future doc revisions:
88 @c search for @value{NOW}.
92 @set DEFAULTLANGUAGEVERSION Ada 2005
93 @set NONDEFAULTLANGUAGEVERSION Ada 95
100 @set PLATFORM OpenVMS
105 @c The ARG is an optional argument. To be used for macro arguments in
106 @c their documentation (@defmac).
108 @r{[}@var{\varname\}@r{]}@c
111 @settitle @value{EDITION} User's Guide @value{PLATFORM}
112 @dircategory GNU Ada tools
114 * @value{EDITION} User's Guide: (gnat_ugn). @value{PLATFORM}
117 @include gcc-common.texi
119 @setchapternewpage odd
124 @title @value{EDITION} User's Guide
128 @titlefont{@i{@value{PLATFORM}}}
134 @subtitle GNAT, The GNU Ada Compiler
139 @vskip 0pt plus 1filll
146 @node Top, About This Guide, (dir), (dir)
147 @top @value{EDITION} User's Guide
150 @value{EDITION} User's Guide @value{PLATFORM}
153 GNAT, The GNU Ada Compiler@*
154 GCC version @value{version-GCC}@*
161 * Getting Started with GNAT::
162 * The GNAT Compilation Model::
163 * Compiling Using gcc::
164 * Binding Using gnatbind::
165 * Linking Using gnatlink::
166 * The GNAT Make Program gnatmake::
167 * Improving Performance::
168 * Renaming Files Using gnatchop::
169 * Configuration Pragmas::
170 * Handling Arbitrary File Naming Conventions Using gnatname::
171 * GNAT Project Manager::
172 * The Cross-Referencing Tools gnatxref and gnatfind::
173 * The GNAT Pretty-Printer gnatpp::
174 * The GNAT Metric Tool gnatmetric::
175 * File Name Krunching Using gnatkr::
176 * Preprocessing Using gnatprep::
178 * The GNAT Run-Time Library Builder gnatlbr::
180 * The GNAT Library Browser gnatls::
181 * Cleaning Up Using gnatclean::
183 * GNAT and Libraries::
184 * Using the GNU make Utility::
186 * Memory Management Issues::
187 * Stack Related Facilities::
188 * Verifying Properties Using gnatcheck::
189 * Creating Sample Bodies Using gnatstub::
190 * Generating Ada Bindings for C and C++ headers::
191 * Other Utility Programs::
192 * Running and Debugging Ada Programs::
194 * Code Coverage and Profiling::
197 * Compatibility with HP Ada::
199 * Platform-Specific Information for the Run-Time Libraries::
200 * Example of Binder Output File::
201 * Elaboration Order Handling in GNAT::
202 * Conditional Compilation::
204 * Compatibility and Porting Guide::
206 * Microsoft Windows Topics::
208 * GNU Free Documentation License::
211 --- The Detailed Node Listing ---
215 * What This Guide Contains::
216 * What You Should Know before Reading This Guide::
217 * Related Information::
220 Getting Started with GNAT
223 * Running a Simple Ada Program::
224 * Running a Program with Multiple Units::
225 * Using the gnatmake Utility::
227 * Editing with Emacs::
230 * Introduction to GPS::
233 The GNAT Compilation Model
235 * Source Representation::
236 * Foreign Language Representation::
237 * File Naming Rules::
238 * Using Other File Names::
239 * Alternative File Naming Schemes::
240 * Generating Object Files::
241 * Source Dependencies::
242 * The Ada Library Information Files::
243 * Binding an Ada Program::
244 * Mixed Language Programming::
246 * Building Mixed Ada & C++ Programs::
247 * Comparison between GNAT and C/C++ Compilation Models::
249 * Comparison between GNAT and Conventional Ada Library Models::
251 * Placement of temporary files::
254 Foreign Language Representation
257 * Other 8-Bit Codes::
258 * Wide Character Encodings::
260 Compiling Ada Programs With gcc
262 * Compiling Programs::
264 * Search Paths and the Run-Time Library (RTL)::
265 * Order of Compilation Issues::
270 * Output and Error Message Control::
271 * Warning Message Control::
272 * Debugging and Assertion Control::
273 * Validity Checking::
276 * Using gcc for Syntax Checking::
277 * Using gcc for Semantic Checking::
278 * Compiling Different Versions of Ada::
279 * Character Set Control::
280 * File Naming Control::
281 * Subprogram Inlining Control::
282 * Auxiliary Output Control::
283 * Debugging Control::
284 * Exception Handling Control::
285 * Units to Sources Mapping Files::
286 * Integrated Preprocessing::
291 Binding Ada Programs With gnatbind
294 * Switches for gnatbind::
295 * Command-Line Access::
296 * Search Paths for gnatbind::
297 * Examples of gnatbind Usage::
299 Switches for gnatbind
301 * Consistency-Checking Modes::
302 * Binder Error Message Control::
303 * Elaboration Control::
305 * Binding with Non-Ada Main Programs::
306 * Binding Programs with No Main Subprogram::
308 Linking Using gnatlink
311 * Switches for gnatlink::
313 The GNAT Make Program gnatmake
316 * Switches for gnatmake::
317 * Mode Switches for gnatmake::
318 * Notes on the Command Line::
319 * How gnatmake Works::
320 * Examples of gnatmake Usage::
322 Improving Performance
323 * Performance Considerations::
324 * Text_IO Suggestions::
325 * Reducing Size of Ada Executables with gnatelim::
326 * Reducing Size of Executables with unused subprogram/data elimination::
328 Performance Considerations
329 * Controlling Run-Time Checks::
330 * Use of Restrictions::
331 * Optimization Levels::
332 * Debugging Optimized Code::
333 * Inlining of Subprograms::
334 * Other Optimization Switches::
335 * Optimization and Strict Aliasing::
337 * Coverage Analysis::
340 Reducing Size of Ada Executables with gnatelim
343 * Correcting the List of Eliminate Pragmas::
344 * Making Your Executables Smaller::
345 * Summary of the gnatelim Usage Cycle::
347 Reducing Size of Executables with unused subprogram/data elimination
348 * About unused subprogram/data elimination::
349 * Compilation options::
351 Renaming Files Using gnatchop
353 * Handling Files with Multiple Units::
354 * Operating gnatchop in Compilation Mode::
355 * Command Line for gnatchop::
356 * Switches for gnatchop::
357 * Examples of gnatchop Usage::
359 Configuration Pragmas
361 * Handling of Configuration Pragmas::
362 * The Configuration Pragmas Files::
364 Handling Arbitrary File Naming Conventions Using gnatname
366 * Arbitrary File Naming Conventions::
368 * Switches for gnatname::
369 * Examples of gnatname Usage::
374 * Examples of Project Files::
375 * Project File Syntax::
376 * Objects and Sources in Project Files::
377 * Importing Projects::
378 * Project Extension::
379 * Project Hierarchy Extension::
380 * External References in Project Files::
381 * Packages in Project Files::
382 * Variables from Imported Projects::
385 * Stand-alone Library Projects::
386 * Switches Related to Project Files::
387 * Tools Supporting Project Files::
388 * An Extended Example::
389 * Project File Complete Syntax::
391 The Cross-Referencing Tools gnatxref and gnatfind
393 * gnatxref Switches::
394 * gnatfind Switches::
395 * Project Files for gnatxref and gnatfind::
396 * Regular Expressions in gnatfind and gnatxref::
397 * Examples of gnatxref Usage::
398 * Examples of gnatfind Usage::
400 The GNAT Pretty-Printer gnatpp
402 * Switches for gnatpp::
405 The GNAT Metrics Tool gnatmetric
407 * Switches for gnatmetric::
409 File Name Krunching Using gnatkr
414 * Examples of gnatkr Usage::
416 Preprocessing Using gnatprep
417 * Preprocessing Symbols::
419 * Switches for gnatprep::
420 * Form of Definitions File::
421 * Form of Input Text for gnatprep::
424 The GNAT Run-Time Library Builder gnatlbr
427 * Switches for gnatlbr::
428 * Examples of gnatlbr Usage::
431 The GNAT Library Browser gnatls
434 * Switches for gnatls::
435 * Examples of gnatls Usage::
437 Cleaning Up Using gnatclean
439 * Running gnatclean::
440 * Switches for gnatclean::
441 @c * Examples of gnatclean Usage::
447 * Introduction to Libraries in GNAT::
448 * General Ada Libraries::
449 * Stand-alone Ada Libraries::
450 * Rebuilding the GNAT Run-Time Library::
452 Using the GNU make Utility
454 * Using gnatmake in a Makefile::
455 * Automatically Creating a List of Directories::
456 * Generating the Command Line Switches::
457 * Overcoming Command Line Length Limits::
460 Memory Management Issues
462 * Some Useful Memory Pools::
463 * The GNAT Debug Pool Facility::
468 Stack Related Facilities
470 * Stack Overflow Checking::
471 * Static Stack Usage Analysis::
472 * Dynamic Stack Usage Analysis::
474 Some Useful Memory Pools
476 The GNAT Debug Pool Facility
482 * Switches for gnatmem::
483 * Example of gnatmem Usage::
486 Verifying Properties Using gnatcheck
488 * Format of the Report File::
489 * General gnatcheck Switches::
490 * gnatcheck Rule Options::
491 * Adding the Results of Compiler Checks to gnatcheck Output::
492 * Project-Wide Checks::
495 Sample Bodies Using gnatstub
498 * Switches for gnatstub::
500 Other Utility Programs
502 * Using Other Utility Programs with GNAT::
503 * The External Symbol Naming Scheme of GNAT::
504 * Converting Ada Files to html with gnathtml::
507 Code Coverage and Profiling
509 * Code Coverage of Ada Programs using gcov::
510 * Profiling an Ada Program using gprof::
513 Running and Debugging Ada Programs
515 * The GNAT Debugger GDB::
517 * Introduction to GDB Commands::
518 * Using Ada Expressions::
519 * Calling User-Defined Subprograms::
520 * Using the Next Command in a Function::
523 * Debugging Generic Units::
524 * GNAT Abnormal Termination or Failure to Terminate::
525 * Naming Conventions for GNAT Source Files::
526 * Getting Internal Debugging Information::
534 Compatibility with HP Ada
536 * Ada Language Compatibility::
537 * Differences in the Definition of Package System::
538 * Language-Related Features::
539 * The Package STANDARD::
540 * The Package SYSTEM::
541 * Tasking and Task-Related Features::
542 * Pragmas and Pragma-Related Features::
543 * Library of Predefined Units::
545 * Main Program Definition::
546 * Implementation-Defined Attributes::
547 * Compiler and Run-Time Interfacing::
548 * Program Compilation and Library Management::
550 * Implementation Limits::
551 * Tools and Utilities::
553 Language-Related Features
555 * Integer Types and Representations::
556 * Floating-Point Types and Representations::
557 * Pragmas Float_Representation and Long_Float::
558 * Fixed-Point Types and Representations::
559 * Record and Array Component Alignment::
561 * Other Representation Clauses::
563 Tasking and Task-Related Features
565 * Implementation of Tasks in HP Ada for OpenVMS Alpha Systems::
566 * Assigning Task IDs::
567 * Task IDs and Delays::
568 * Task-Related Pragmas::
569 * Scheduling and Task Priority::
571 * External Interrupts::
573 Pragmas and Pragma-Related Features
575 * Restrictions on the Pragma INLINE::
576 * Restrictions on the Pragma INTERFACE::
577 * Restrictions on the Pragma SYSTEM_NAME::
579 Library of Predefined Units
581 * Changes to DECLIB::
585 * Shared Libraries and Options Files::
589 Platform-Specific Information for the Run-Time Libraries
591 * Summary of Run-Time Configurations::
592 * Specifying a Run-Time Library::
593 * Choosing the Scheduling Policy::
594 * Solaris-Specific Considerations::
595 * Linux-Specific Considerations::
596 * AIX-Specific Considerations::
597 * Irix-Specific Considerations::
599 Example of Binder Output File
601 Elaboration Order Handling in GNAT
604 * Checking the Elaboration Order::
605 * Controlling the Elaboration Order::
606 * Controlling Elaboration in GNAT - Internal Calls::
607 * Controlling Elaboration in GNAT - External Calls::
608 * Default Behavior in GNAT - Ensuring Safety::
609 * Treatment of Pragma Elaborate::
610 * Elaboration Issues for Library Tasks::
611 * Mixing Elaboration Models::
612 * What to Do If the Default Elaboration Behavior Fails::
613 * Elaboration for Access-to-Subprogram Values::
614 * Summary of Procedures for Elaboration Control::
615 * Other Elaboration Order Considerations::
617 Conditional Compilation
618 * Use of Boolean Constants::
619 * Debugging - A Special Case::
620 * Conditionalizing Declarations::
621 * Use of Alternative Implementations::
626 * Basic Assembler Syntax::
627 * A Simple Example of Inline Assembler::
628 * Output Variables in Inline Assembler::
629 * Input Variables in Inline Assembler::
630 * Inlining Inline Assembler Code::
631 * Other Asm Functionality::
633 Compatibility and Porting Guide
635 * Compatibility with Ada 83::
636 * Compatibility between Ada 95 and Ada 2005::
637 * Implementation-dependent characteristics::
639 @c This brief section is only in the non-VMS version
640 @c The complete chapter on HP Ada issues is in the VMS version
641 * Compatibility with HP Ada 83::
643 * Compatibility with Other Ada Systems::
644 * Representation Clauses::
646 * Transitioning to 64-Bit GNAT for OpenVMS::
650 Microsoft Windows Topics
652 * Using GNAT on Windows::
653 * CONSOLE and WINDOWS subsystems::
655 * Mixed-Language Programming on Windows::
656 * Windows Calling Conventions::
657 * Introduction to Dynamic Link Libraries (DLLs)::
658 * Using DLLs with GNAT::
659 * Building DLLs with GNAT::
660 * GNAT and Windows Resources::
662 * Setting Stack Size from gnatlink::
663 * Setting Heap Size from gnatlink::
670 @node About This Guide
671 @unnumbered About This Guide
675 This guide describes the use of @value{EDITION},
676 a compiler and software development toolset for the full Ada
677 programming language, implemented on OpenVMS for HP's Alpha and
678 Integrity server (I64) platforms.
681 This guide describes the use of @value{EDITION},
682 a compiler and software development
683 toolset for the full Ada programming language.
685 It documents the features of the compiler and tools, and explains
686 how to use them to build Ada applications.
688 @value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in
689 Ada 83 compatibility mode.
690 By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
691 but you can override with a compiler switch
692 (@pxref{Compiling Different Versions of Ada})
693 to explicitly specify the language version.
694 Throughout this manual, references to ``Ada'' without a year suffix
695 apply to both the Ada 95 and Ada 2005 versions of the language.
699 For ease of exposition, ``@value{EDITION}'' will be referred to simply as
700 ``GNAT'' in the remainder of this document.
707 * What This Guide Contains::
708 * What You Should Know before Reading This Guide::
709 * Related Information::
713 @node What This Guide Contains
714 @unnumberedsec What This Guide Contains
717 This guide contains the following chapters:
721 @ref{Getting Started with GNAT}, describes how to get started compiling
722 and running Ada programs with the GNAT Ada programming environment.
724 @ref{The GNAT Compilation Model}, describes the compilation model used
728 @ref{Compiling Using gcc}, describes how to compile
729 Ada programs with @command{gcc}, the Ada compiler.
732 @ref{Binding Using gnatbind}, describes how to
733 perform binding of Ada programs with @code{gnatbind}, the GNAT binding
737 @ref{Linking Using gnatlink},
738 describes @command{gnatlink}, a
739 program that provides for linking using the GNAT run-time library to
740 construct a program. @command{gnatlink} can also incorporate foreign language
741 object units into the executable.
744 @ref{The GNAT Make Program gnatmake}, describes @command{gnatmake}, a
745 utility that automatically determines the set of sources
746 needed by an Ada compilation unit, and executes the necessary compilations
750 @ref{Improving Performance}, shows various techniques for making your
751 Ada program run faster or take less space.
752 It discusses the effect of the compiler's optimization switch and
753 also describes the @command{gnatelim} tool and unused subprogram/data
757 @ref{Renaming Files Using gnatchop}, describes
758 @code{gnatchop}, a utility that allows you to preprocess a file that
759 contains Ada source code, and split it into one or more new files, one
760 for each compilation unit.
763 @ref{Configuration Pragmas}, describes the configuration pragmas
767 @ref{Handling Arbitrary File Naming Conventions Using gnatname},
768 shows how to override the default GNAT file naming conventions,
769 either for an individual unit or globally.
772 @ref{GNAT Project Manager}, describes how to use project files
773 to organize large projects.
776 @ref{The Cross-Referencing Tools gnatxref and gnatfind}, discusses
777 @code{gnatxref} and @code{gnatfind}, two tools that provide an easy
778 way to navigate through sources.
781 @ref{The GNAT Pretty-Printer gnatpp}, shows how to produce a reformatted
782 version of an Ada source file with control over casing, indentation,
783 comment placement, and other elements of program presentation style.
786 @ref{The GNAT Metric Tool gnatmetric}, shows how to compute various
787 metrics for an Ada source file, such as the number of types and subprograms,
788 and assorted complexity measures.
791 @ref{File Name Krunching Using gnatkr}, describes the @code{gnatkr}
792 file name krunching utility, used to handle shortened
793 file names on operating systems with a limit on the length of names.
796 @ref{Preprocessing Using gnatprep}, describes @code{gnatprep}, a
797 preprocessor utility that allows a single source file to be used to
798 generate multiple or parameterized source files by means of macro
803 @ref{The GNAT Run-Time Library Builder gnatlbr}, describes @command{gnatlbr},
804 a tool for rebuilding the GNAT run time with user-supplied
805 configuration pragmas.
809 @ref{The GNAT Library Browser gnatls}, describes @code{gnatls}, a
810 utility that displays information about compiled units, including dependences
811 on the corresponding sources files, and consistency of compilations.
814 @ref{Cleaning Up Using gnatclean}, describes @code{gnatclean}, a utility
815 to delete files that are produced by the compiler, binder and linker.
819 @ref{GNAT and Libraries}, describes the process of creating and using
820 Libraries with GNAT. It also describes how to recompile the GNAT run-time
824 @ref{Using the GNU make Utility}, describes some techniques for using
825 the GNAT toolset in Makefiles.
829 @ref{Memory Management Issues}, describes some useful predefined storage pools
830 and in particular the GNAT Debug Pool facility, which helps detect incorrect
833 It also describes @command{gnatmem}, a utility that monitors dynamic
834 allocation and deallocation and helps detect ``memory leaks''.
838 @ref{Stack Related Facilities}, describes some useful tools associated with
839 stack checking and analysis.
842 @ref{Verifying Properties Using gnatcheck}, discusses @code{gnatcheck},
843 a utility that checks Ada code against a set of rules.
846 @ref{Creating Sample Bodies Using gnatstub}, discusses @code{gnatstub},
847 a utility that generates empty but compilable bodies for library units.
850 @ref{Generating Ada Bindings for C and C++ headers}, describes how to
851 generate automatically Ada bindings from C and C++ headers.
854 @ref{Other Utility Programs}, discusses several other GNAT utilities,
855 including @code{gnathtml}.
859 @ref{Code Coverage and Profiling}, describes how to perform a structural
860 coverage and profile the execution of Ada programs.
864 @ref{Running and Debugging Ada Programs}, describes how to run and debug
869 @ref{Compatibility with HP Ada}, details the compatibility of GNAT with
870 HP Ada 83 @footnote{``HP Ada'' refers to the legacy product originally
871 developed by Digital Equipment Corporation and currently supported by HP.}
872 for OpenVMS Alpha. This product was formerly known as DEC Ada,
875 historical compatibility reasons, the relevant libraries still use the
880 @ref{Platform-Specific Information for the Run-Time Libraries},
881 describes the various run-time
882 libraries supported by GNAT on various platforms and explains how to
883 choose a particular library.
886 @ref{Example of Binder Output File}, shows the source code for the binder
887 output file for a sample program.
890 @ref{Elaboration Order Handling in GNAT}, describes how GNAT helps
891 you deal with elaboration order issues.
894 @ref{Conditional Compilation}, describes how to model conditional compilation,
895 both with Ada in general and with GNAT facilities in particular.
898 @ref{Inline Assembler}, shows how to use the inline assembly facility
902 @ref{Compatibility and Porting Guide}, contains sections on compatibility
903 of GNAT with other Ada development environments (including Ada 83 systems),
904 to assist in porting code from those environments.
908 @ref{Microsoft Windows Topics}, presents information relevant to the
909 Microsoft Windows platform.
913 @c *************************************************
914 @node What You Should Know before Reading This Guide
915 @c *************************************************
916 @unnumberedsec What You Should Know before Reading This Guide
918 @cindex Ada 95 Language Reference Manual
919 @cindex Ada 2005 Language Reference Manual
921 This guide assumes a basic familiarity with the Ada 95 language, as
922 described in the International Standard ANSI/ISO/IEC-8652:1995, January
924 It does not require knowledge of the new features introduced by Ada 2005,
925 (officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1
927 Both reference manuals are included in the GNAT documentation
930 @node Related Information
931 @unnumberedsec Related Information
934 For further information about related tools, refer to the following
939 @xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT
940 Reference Manual}, which contains all reference material for the GNAT
941 implementation of Ada.
945 @cite{Using the GNAT Programming Studio}, which describes the GPS
946 Integrated Development Environment.
949 @cite{GNAT Programming Studio Tutorial}, which introduces the
950 main GPS features through examples.
954 @cite{Ada 95 Reference Manual}, which contains reference
955 material for the Ada 95 programming language.
958 @cite{Ada 2005 Reference Manual}, which contains reference
959 material for the Ada 2005 programming language.
962 @xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
964 in the GNU:[DOCS] directory,
966 for all details on the use of the GNU source-level debugger.
969 @xref{Top,, The extensible self-documenting text editor, emacs,
972 located in the GNU:[DOCS] directory if the EMACS kit is installed,
974 for full information on the extensible editor and programming
981 @unnumberedsec Conventions
983 @cindex Typographical conventions
986 Following are examples of the typographical and graphic conventions used
991 @code{Functions}, @command{utility program names}, @code{standard names},
995 @option{Option flags}
998 @file{File names}, @samp{button names}, and @samp{field names}.
1001 @code{Variables}, @env{environment variables}, and @var{metasyntactic
1008 @r{[}optional information or parameters@r{]}
1011 Examples are described by text
1013 and then shown this way.
1018 Commands that are entered by the user are preceded in this manual by the
1019 characters @w{``@code{$ }''} (dollar sign followed by space). If your system
1020 uses this sequence as a prompt, then the commands will appear exactly as
1021 you see them in the manual. If your system uses some other prompt, then
1022 the command will appear with the @code{$} replaced by whatever prompt
1023 character you are using.
1026 Full file names are shown with the ``@code{/}'' character
1027 as the directory separator; e.g., @file{parent-dir/subdir/myfile.adb}.
1028 If you are using GNAT on a Windows platform, please note that
1029 the ``@code{\}'' character should be used instead.
1032 @c ****************************
1033 @node Getting Started with GNAT
1034 @chapter Getting Started with GNAT
1037 This chapter describes some simple ways of using GNAT to build
1038 executable Ada programs.
1040 @ref{Running GNAT}, through @ref{Using the gnatmake Utility},
1041 show how to use the command line environment.
1042 @ref{Introduction to GPS}, provides a brief
1043 introduction to the GNAT Programming Studio, a visually-oriented
1044 Integrated Development Environment for GNAT.
1045 GPS offers a graphical ``look and feel'', support for development in
1046 other programming languages, comprehensive browsing features, and
1047 many other capabilities.
1048 For information on GPS please refer to
1049 @cite{Using the GNAT Programming Studio}.
1054 * Running a Simple Ada Program::
1055 * Running a Program with Multiple Units::
1056 * Using the gnatmake Utility::
1058 * Editing with Emacs::
1061 * Introduction to GPS::
1066 @section Running GNAT
1069 Three steps are needed to create an executable file from an Ada source
1074 The source file(s) must be compiled.
1076 The file(s) must be bound using the GNAT binder.
1078 All appropriate object files must be linked to produce an executable.
1082 All three steps are most commonly handled by using the @command{gnatmake}
1083 utility program that, given the name of the main program, automatically
1084 performs the necessary compilation, binding and linking steps.
1086 @node Running a Simple Ada Program
1087 @section Running a Simple Ada Program
1090 Any text editor may be used to prepare an Ada program.
1092 used, the optional Ada mode may be helpful in laying out the program.)
1094 program text is a normal text file. We will assume in our initial
1095 example that you have used your editor to prepare the following
1096 standard format text file:
1098 @smallexample @c ada
1100 with Ada.Text_IO; use Ada.Text_IO;
1103 Put_Line ("Hello WORLD!");
1109 This file should be named @file{hello.adb}.
1110 With the normal default file naming conventions, GNAT requires
1112 contain a single compilation unit whose file name is the
1114 with periods replaced by hyphens; the
1115 extension is @file{ads} for a
1116 spec and @file{adb} for a body.
1117 You can override this default file naming convention by use of the
1118 special pragma @code{Source_File_Name} (@pxref{Using Other File Names}).
1119 Alternatively, if you want to rename your files according to this default
1120 convention, which is probably more convenient if you will be using GNAT
1121 for all your compilations, then the @code{gnatchop} utility
1122 can be used to generate correctly-named source files
1123 (@pxref{Renaming Files Using gnatchop}).
1125 You can compile the program using the following command (@code{$} is used
1126 as the command prompt in the examples in this document):
1133 @command{gcc} is the command used to run the compiler. This compiler is
1134 capable of compiling programs in several languages, including Ada and
1135 C. It assumes that you have given it an Ada program if the file extension is
1136 either @file{.ads} or @file{.adb}, and it will then call
1137 the GNAT compiler to compile the specified file.
1140 The @option{-c} switch is required. It tells @command{gcc} to only do a
1141 compilation. (For C programs, @command{gcc} can also do linking, but this
1142 capability is not used directly for Ada programs, so the @option{-c}
1143 switch must always be present.)
1146 This compile command generates a file
1147 @file{hello.o}, which is the object
1148 file corresponding to your Ada program. It also generates
1149 an ``Ada Library Information'' file @file{hello.ali},
1150 which contains additional information used to check
1151 that an Ada program is consistent.
1152 To build an executable file,
1153 use @code{gnatbind} to bind the program
1154 and @command{gnatlink} to link it. The
1155 argument to both @code{gnatbind} and @command{gnatlink} is the name of the
1156 @file{ALI} file, but the default extension of @file{.ali} can
1157 be omitted. This means that in the most common case, the argument
1158 is simply the name of the main program:
1166 A simpler method of carrying out these steps is to use
1168 a master program that invokes all the required
1169 compilation, binding and linking tools in the correct order. In particular,
1170 @command{gnatmake} automatically recompiles any sources that have been
1171 modified since they were last compiled, or sources that depend
1172 on such modified sources, so that ``version skew'' is avoided.
1173 @cindex Version skew (avoided by @command{gnatmake})
1176 $ gnatmake hello.adb
1180 The result is an executable program called @file{hello}, which can be
1188 assuming that the current directory is on the search path
1189 for executable programs.
1192 and, if all has gone well, you will see
1199 appear in response to this command.
1201 @c ****************************************
1202 @node Running a Program with Multiple Units
1203 @section Running a Program with Multiple Units
1206 Consider a slightly more complicated example that has three files: a
1207 main program, and the spec and body of a package:
1209 @smallexample @c ada
1212 package Greetings is
1217 with Ada.Text_IO; use Ada.Text_IO;
1218 package body Greetings is
1221 Put_Line ("Hello WORLD!");
1224 procedure Goodbye is
1226 Put_Line ("Goodbye WORLD!");
1243 Following the one-unit-per-file rule, place this program in the
1244 following three separate files:
1248 spec of package @code{Greetings}
1251 body of package @code{Greetings}
1254 body of main program
1258 To build an executable version of
1259 this program, we could use four separate steps to compile, bind, and link
1260 the program, as follows:
1264 $ gcc -c greetings.adb
1270 Note that there is no required order of compilation when using GNAT.
1271 In particular it is perfectly fine to compile the main program first.
1272 Also, it is not necessary to compile package specs in the case where
1273 there is an accompanying body; you only need to compile the body. If you want
1274 to submit these files to the compiler for semantic checking and not code
1275 generation, then use the
1276 @option{-gnatc} switch:
1279 $ gcc -c greetings.ads -gnatc
1283 Although the compilation can be done in separate steps as in the
1284 above example, in practice it is almost always more convenient
1285 to use the @command{gnatmake} tool. All you need to know in this case
1286 is the name of the main program's source file. The effect of the above four
1287 commands can be achieved with a single one:
1290 $ gnatmake gmain.adb
1294 In the next section we discuss the advantages of using @command{gnatmake} in
1297 @c *****************************
1298 @node Using the gnatmake Utility
1299 @section Using the @command{gnatmake} Utility
1302 If you work on a program by compiling single components at a time using
1303 @command{gcc}, you typically keep track of the units you modify. In order to
1304 build a consistent system, you compile not only these units, but also any
1305 units that depend on the units you have modified.
1306 For example, in the preceding case,
1307 if you edit @file{gmain.adb}, you only need to recompile that file. But if
1308 you edit @file{greetings.ads}, you must recompile both
1309 @file{greetings.adb} and @file{gmain.adb}, because both files contain
1310 units that depend on @file{greetings.ads}.
1312 @code{gnatbind} will warn you if you forget one of these compilation
1313 steps, so that it is impossible to generate an inconsistent program as a
1314 result of forgetting to do a compilation. Nevertheless it is tedious and
1315 error-prone to keep track of dependencies among units.
1316 One approach to handle the dependency-bookkeeping is to use a
1317 makefile. However, makefiles present maintenance problems of their own:
1318 if the dependencies change as you change the program, you must make
1319 sure that the makefile is kept up-to-date manually, which is also an
1320 error-prone process.
1322 The @command{gnatmake} utility takes care of these details automatically.
1323 Invoke it using either one of the following forms:
1326 $ gnatmake gmain.adb
1327 $ gnatmake ^gmain^GMAIN^
1331 The argument is the name of the file containing the main program;
1332 you may omit the extension. @command{gnatmake}
1333 examines the environment, automatically recompiles any files that need
1334 recompiling, and binds and links the resulting set of object files,
1335 generating the executable file, @file{^gmain^GMAIN.EXE^}.
1336 In a large program, it
1337 can be extremely helpful to use @command{gnatmake}, because working out by hand
1338 what needs to be recompiled can be difficult.
1340 Note that @command{gnatmake}
1341 takes into account all the Ada rules that
1342 establish dependencies among units. These include dependencies that result
1343 from inlining subprogram bodies, and from
1344 generic instantiation. Unlike some other
1345 Ada make tools, @command{gnatmake} does not rely on the dependencies that were
1346 found by the compiler on a previous compilation, which may possibly
1347 be wrong when sources change. @command{gnatmake} determines the exact set of
1348 dependencies from scratch each time it is run.
1351 @node Editing with Emacs
1352 @section Editing with Emacs
1356 Emacs is an extensible self-documenting text editor that is available in a
1357 separate VMSINSTAL kit.
1359 Invoke Emacs by typing @kbd{Emacs} at the command prompt. To get started,
1360 click on the Emacs Help menu and run the Emacs Tutorial.
1361 In a character cell terminal, Emacs help is invoked with @kbd{Ctrl-h} (also
1362 written as @kbd{C-h}), and the tutorial by @kbd{C-h t}.
1364 Documentation on Emacs and other tools is available in Emacs under the
1365 pull-down menu button: @code{Help - Info}. After selecting @code{Info},
1366 use the middle mouse button to select a topic (e.g.@: Emacs).
1368 In a character cell terminal, do @kbd{C-h i} to invoke info, and then @kbd{m}
1369 (stands for menu) followed by the menu item desired, as in @kbd{m Emacs}, to
1370 get to the Emacs manual.
1371 Help on Emacs is also available by typing @kbd{HELP EMACS} at the DCL command
1374 The tutorial is highly recommended in order to learn the intricacies of Emacs,
1375 which is sufficiently extensible to provide for a complete programming
1376 environment and shell for the sophisticated user.
1380 @node Introduction to GPS
1381 @section Introduction to GPS
1382 @cindex GPS (GNAT Programming Studio)
1383 @cindex GNAT Programming Studio (GPS)
1385 Although the command line interface (@command{gnatmake}, etc.) alone
1386 is sufficient, a graphical Interactive Development
1387 Environment can make it easier for you to compose, navigate, and debug
1388 programs. This section describes the main features of GPS
1389 (``GNAT Programming Studio''), the GNAT graphical IDE.
1390 You will see how to use GPS to build and debug an executable, and
1391 you will also learn some of the basics of the GNAT ``project'' facility.
1393 GPS enables you to do much more than is presented here;
1394 e.g., you can produce a call graph, interface to a third-party
1395 Version Control System, and inspect the generated assembly language
1397 Indeed, GPS also supports languages other than Ada.
1398 Such additional information, and an explanation of all of the GPS menu
1399 items. may be found in the on-line help, which includes
1400 a user's guide and a tutorial (these are also accessible from the GNAT
1404 * Building a New Program with GPS::
1405 * Simple Debugging with GPS::
1408 @node Building a New Program with GPS
1409 @subsection Building a New Program with GPS
1411 GPS invokes the GNAT compilation tools using information
1412 contained in a @emph{project} (also known as a @emph{project file}):
1413 a collection of properties such
1414 as source directories, identities of main subprograms, tool switches, etc.,
1415 and their associated values.
1416 See @ref{GNAT Project Manager} for details.
1417 In order to run GPS, you will need to either create a new project
1418 or else open an existing one.
1420 This section will explain how you can use GPS to create a project,
1421 to associate Ada source files with a project, and to build and run
1425 @item @emph{Creating a project}
1427 Invoke GPS, either from the command line or the platform's IDE.
1428 After it starts, GPS will display a ``Welcome'' screen with three
1433 @code{Start with default project in directory}
1436 @code{Create new project with wizard}
1439 @code{Open existing project}
1443 Select @code{Create new project with wizard} and press @code{OK}.
1444 A new window will appear. In the text box labeled with
1445 @code{Enter the name of the project to create}, type @file{sample}
1446 as the project name.
1447 In the next box, browse to choose the directory in which you
1448 would like to create the project file.
1449 After selecting an appropriate directory, press @code{Forward}.
1451 A window will appear with the title
1452 @code{Version Control System Configuration}.
1453 Simply press @code{Forward}.
1455 A window will appear with the title
1456 @code{Please select the source directories for this project}.
1457 The directory that you specified for the project file will be selected
1458 by default as the one to use for sources; simply press @code{Forward}.
1460 A window will appear with the title
1461 @code{Please select the build directory for this project}.
1462 The directory that you specified for the project file will be selected
1463 by default for object files and executables;
1464 simply press @code{Forward}.
1466 A window will appear with the title
1467 @code{Please select the main units for this project}.
1468 You will supply this information later, after creating the source file.
1469 Simply press @code{Forward} for now.
1471 A window will appear with the title
1472 @code{Please select the switches to build the project}.
1473 Press @code{Apply}. This will create a project file named
1474 @file{sample.prj} in the directory that you had specified.
1476 @item @emph{Creating and saving the source file}
1478 After you create the new project, a GPS window will appear, which is
1479 partitioned into two main sections:
1483 A @emph{Workspace area}, initially greyed out, which you will use for
1484 creating and editing source files
1487 Directly below, a @emph{Messages area}, which initially displays a
1488 ``Welcome'' message.
1489 (If the Messages area is not visible, drag its border upward to expand it.)
1493 Select @code{File} on the menu bar, and then the @code{New} command.
1494 The Workspace area will become white, and you can now
1495 enter the source program explicitly.
1496 Type the following text
1498 @smallexample @c ada
1500 with Ada.Text_IO; use Ada.Text_IO;
1503 Put_Line("Hello from GPS!");
1509 Select @code{File}, then @code{Save As}, and enter the source file name
1511 The file will be saved in the same directory you specified as the
1512 location of the default project file.
1514 @item @emph{Updating the project file}
1516 You need to add the new source file to the project.
1518 the @code{Project} menu and then @code{Edit project properties}.
1519 Click the @code{Main files} tab on the left, and then the
1521 Choose @file{hello.adb} from the list, and press @code{Open}.
1522 The project settings window will reflect this action.
1525 @item @emph{Building and running the program}
1527 In the main GPS window, now choose the @code{Build} menu, then @code{Make},
1528 and select @file{hello.adb}.
1529 The Messages window will display the resulting invocations of @command{gcc},
1530 @command{gnatbind}, and @command{gnatlink}
1531 (reflecting the default switch settings from the
1532 project file that you created) and then a ``successful compilation/build''
1535 To run the program, choose the @code{Build} menu, then @code{Run}, and
1536 select @command{hello}.
1537 An @emph{Arguments Selection} window will appear.
1538 There are no command line arguments, so just click @code{OK}.
1540 The Messages window will now display the program's output (the string
1541 @code{Hello from GPS}), and at the bottom of the GPS window a status
1542 update is displayed (@code{Run: hello}).
1543 Close the GPS window (or select @code{File}, then @code{Exit}) to
1544 terminate this GPS session.
1547 @node Simple Debugging with GPS
1548 @subsection Simple Debugging with GPS
1550 This section illustrates basic debugging techniques (setting breakpoints,
1551 examining/modifying variables, single stepping).
1554 @item @emph{Opening a project}
1556 Start GPS and select @code{Open existing project}; browse to
1557 specify the project file @file{sample.prj} that you had created in the
1560 @item @emph{Creating a source file}
1562 Select @code{File}, then @code{New}, and type in the following program:
1564 @smallexample @c ada
1566 with Ada.Text_IO; use Ada.Text_IO;
1567 procedure Example is
1568 Line : String (1..80);
1571 Put_Line("Type a line of text at each prompt; an empty line to exit");
1575 Put_Line (Line (1..N) );
1583 Select @code{File}, then @code{Save as}, and enter the file name
1586 @item @emph{Updating the project file}
1588 Add @code{Example} as a new main unit for the project:
1591 Select @code{Project}, then @code{Edit Project Properties}.
1594 Select the @code{Main files} tab, click @code{Add}, then
1595 select the file @file{example.adb} from the list, and
1597 You will see the file name appear in the list of main units
1603 @item @emph{Building/running the executable}
1605 To build the executable
1606 select @code{Build}, then @code{Make}, and then choose @file{example.adb}.
1608 Run the program to see its effect (in the Messages area).
1609 Each line that you enter is displayed; an empty line will
1610 cause the loop to exit and the program to terminate.
1612 @item @emph{Debugging the program}
1614 Note that the @option{-g} switches to @command{gcc} and @command{gnatlink},
1615 which are required for debugging, are on by default when you create
1617 Thus unless you intentionally remove these settings, you will be able
1618 to debug any program that you develop using GPS.
1621 @item @emph{Initializing}
1623 Select @code{Debug}, then @code{Initialize}, then @file{example}
1625 @item @emph{Setting a breakpoint}
1627 After performing the initialization step, you will observe a small
1628 icon to the right of each line number.
1629 This serves as a toggle for breakpoints; clicking the icon will
1630 set a breakpoint at the corresponding line (the icon will change to
1631 a red circle with an ``x''), and clicking it again
1632 will remove the breakpoint / reset the icon.
1634 For purposes of this example, set a breakpoint at line 10 (the
1635 statement @code{Put_Line@ (Line@ (1..N));}
1637 @item @emph{Starting program execution}
1639 Select @code{Debug}, then @code{Run}. When the
1640 @code{Program Arguments} window appears, click @code{OK}.
1641 A console window will appear; enter some line of text,
1642 e.g.@: @code{abcde}, at the prompt.
1643 The program will pause execution when it gets to the
1644 breakpoint, and the corresponding line is highlighted.
1646 @item @emph{Examining a variable}
1648 Move the mouse over one of the occurrences of the variable @code{N}.
1649 You will see the value (5) displayed, in ``tool tip'' fashion.
1650 Right click on @code{N}, select @code{Debug}, then select @code{Display N}.
1651 You will see information about @code{N} appear in the @code{Debugger Data}
1652 pane, showing the value as 5.
1654 @item @emph{Assigning a new value to a variable}
1656 Right click on the @code{N} in the @code{Debugger Data} pane, and
1657 select @code{Set value of N}.
1658 When the input window appears, enter the value @code{4} and click
1660 This value does not automatically appear in the @code{Debugger Data}
1661 pane; to see it, right click again on the @code{N} in the
1662 @code{Debugger Data} pane and select @code{Update value}.
1663 The new value, 4, will appear in red.
1665 @item @emph{Single stepping}
1667 Select @code{Debug}, then @code{Next}.
1668 This will cause the next statement to be executed, in this case the
1669 call of @code{Put_Line} with the string slice.
1670 Notice in the console window that the displayed string is simply
1671 @code{abcd} and not @code{abcde} which you had entered.
1672 This is because the upper bound of the slice is now 4 rather than 5.
1674 @item @emph{Removing a breakpoint}
1676 Toggle the breakpoint icon at line 10.
1678 @item @emph{Resuming execution from a breakpoint}
1680 Select @code{Debug}, then @code{Continue}.
1681 The program will reach the next iteration of the loop, and
1682 wait for input after displaying the prompt.
1683 This time, just hit the @kbd{Enter} key.
1684 The value of @code{N} will be 0, and the program will terminate.
1685 The console window will disappear.
1690 @node The GNAT Compilation Model
1691 @chapter The GNAT Compilation Model
1692 @cindex GNAT compilation model
1693 @cindex Compilation model
1696 * Source Representation::
1697 * Foreign Language Representation::
1698 * File Naming Rules::
1699 * Using Other File Names::
1700 * Alternative File Naming Schemes::
1701 * Generating Object Files::
1702 * Source Dependencies::
1703 * The Ada Library Information Files::
1704 * Binding an Ada Program::
1705 * Mixed Language Programming::
1707 * Building Mixed Ada & C++ Programs::
1708 * Comparison between GNAT and C/C++ Compilation Models::
1710 * Comparison between GNAT and Conventional Ada Library Models::
1712 * Placement of temporary files::
1717 This chapter describes the compilation model used by GNAT. Although
1718 similar to that used by other languages, such as C and C++, this model
1719 is substantially different from the traditional Ada compilation models,
1720 which are based on a library. The model is initially described without
1721 reference to the library-based model. If you have not previously used an
1722 Ada compiler, you need only read the first part of this chapter. The
1723 last section describes and discusses the differences between the GNAT
1724 model and the traditional Ada compiler models. If you have used other
1725 Ada compilers, this section will help you to understand those
1726 differences, and the advantages of the GNAT model.
1728 @node Source Representation
1729 @section Source Representation
1733 Ada source programs are represented in standard text files, using
1734 Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar
1735 7-bit ASCII set, plus additional characters used for
1736 representing foreign languages (@pxref{Foreign Language Representation}
1737 for support of non-USA character sets). The format effector characters
1738 are represented using their standard ASCII encodings, as follows:
1743 Vertical tab, @code{16#0B#}
1747 Horizontal tab, @code{16#09#}
1751 Carriage return, @code{16#0D#}
1755 Line feed, @code{16#0A#}
1759 Form feed, @code{16#0C#}
1763 Source files are in standard text file format. In addition, GNAT will
1764 recognize a wide variety of stream formats, in which the end of
1765 physical lines is marked by any of the following sequences:
1766 @code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful
1767 in accommodating files that are imported from other operating systems.
1769 @cindex End of source file
1770 @cindex Source file, end
1772 The end of a source file is normally represented by the physical end of
1773 file. However, the control character @code{16#1A#} (@code{SUB}) is also
1774 recognized as signalling the end of the source file. Again, this is
1775 provided for compatibility with other operating systems where this
1776 code is used to represent the end of file.
1778 Each file contains a single Ada compilation unit, including any pragmas
1779 associated with the unit. For example, this means you must place a
1780 package declaration (a package @dfn{spec}) and the corresponding body in
1781 separate files. An Ada @dfn{compilation} (which is a sequence of
1782 compilation units) is represented using a sequence of files. Similarly,
1783 you will place each subunit or child unit in a separate file.
1785 @node Foreign Language Representation
1786 @section Foreign Language Representation
1789 GNAT supports the standard character sets defined in Ada as well as
1790 several other non-standard character sets for use in localized versions
1791 of the compiler (@pxref{Character Set Control}).
1794 * Other 8-Bit Codes::
1795 * Wide Character Encodings::
1803 The basic character set is Latin-1. This character set is defined by ISO
1804 standard 8859, part 1. The lower half (character codes @code{16#00#}
1805 @dots{} @code{16#7F#)} is identical to standard ASCII coding, but the upper half
1806 is used to represent additional characters. These include extended letters
1807 used by European languages, such as French accents, the vowels with umlauts
1808 used in German, and the extra letter A-ring used in Swedish.
1810 @findex Ada.Characters.Latin_1
1811 For a complete list of Latin-1 codes and their encodings, see the source
1812 file of library unit @code{Ada.Characters.Latin_1} in file
1813 @file{a-chlat1.ads}.
1814 You may use any of these extended characters freely in character or
1815 string literals. In addition, the extended characters that represent
1816 letters can be used in identifiers.
1818 @node Other 8-Bit Codes
1819 @subsection Other 8-Bit Codes
1822 GNAT also supports several other 8-bit coding schemes:
1825 @item ISO 8859-2 (Latin-2)
1828 Latin-2 letters allowed in identifiers, with uppercase and lowercase
1831 @item ISO 8859-3 (Latin-3)
1834 Latin-3 letters allowed in identifiers, with uppercase and lowercase
1837 @item ISO 8859-4 (Latin-4)
1840 Latin-4 letters allowed in identifiers, with uppercase and lowercase
1843 @item ISO 8859-5 (Cyrillic)
1846 ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and
1847 lowercase equivalence.
1849 @item ISO 8859-15 (Latin-9)
1852 ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and
1853 lowercase equivalence
1855 @item IBM PC (code page 437)
1856 @cindex code page 437
1857 This code page is the normal default for PCs in the U.S. It corresponds
1858 to the original IBM PC character set. This set has some, but not all, of
1859 the extended Latin-1 letters, but these letters do not have the same
1860 encoding as Latin-1. In this mode, these letters are allowed in
1861 identifiers with uppercase and lowercase equivalence.
1863 @item IBM PC (code page 850)
1864 @cindex code page 850
1865 This code page is a modification of 437 extended to include all the
1866 Latin-1 letters, but still not with the usual Latin-1 encoding. In this
1867 mode, all these letters are allowed in identifiers with uppercase and
1868 lowercase equivalence.
1870 @item Full Upper 8-bit
1871 Any character in the range 80-FF allowed in identifiers, and all are
1872 considered distinct. In other words, there are no uppercase and lowercase
1873 equivalences in this range. This is useful in conjunction with
1874 certain encoding schemes used for some foreign character sets (e.g.,
1875 the typical method of representing Chinese characters on the PC).
1878 No upper-half characters in the range 80-FF are allowed in identifiers.
1879 This gives Ada 83 compatibility for identifier names.
1883 For precise data on the encodings permitted, and the uppercase and lowercase
1884 equivalences that are recognized, see the file @file{csets.adb} in
1885 the GNAT compiler sources. You will need to obtain a full source release
1886 of GNAT to obtain this file.
1888 @node Wide Character Encodings
1889 @subsection Wide Character Encodings
1892 GNAT allows wide character codes to appear in character and string
1893 literals, and also optionally in identifiers, by means of the following
1894 possible encoding schemes:
1899 In this encoding, a wide character is represented by the following five
1907 Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
1908 characters (using uppercase letters) of the wide character code. For
1909 example, ESC A345 is used to represent the wide character with code
1911 This scheme is compatible with use of the full Wide_Character set.
1913 @item Upper-Half Coding
1914 @cindex Upper-Half Coding
1915 The wide character with encoding @code{16#abcd#} where the upper bit is on
1916 (in other words, ``a'' is in the range 8-F) is represented as two bytes,
1917 @code{16#ab#} and @code{16#cd#}. The second byte cannot be a format control
1918 character, but is not required to be in the upper half. This method can
1919 be also used for shift-JIS or EUC, where the internal coding matches the
1922 @item Shift JIS Coding
1923 @cindex Shift JIS Coding
1924 A wide character is represented by a two-character sequence,
1926 @code{16#cd#}, with the restrictions described for upper-half encoding as
1927 described above. The internal character code is the corresponding JIS
1928 character according to the standard algorithm for Shift-JIS
1929 conversion. Only characters defined in the JIS code set table can be
1930 used with this encoding method.
1934 A wide character is represented by a two-character sequence
1936 @code{16#cd#}, with both characters being in the upper half. The internal
1937 character code is the corresponding JIS character according to the EUC
1938 encoding algorithm. Only characters defined in the JIS code set table
1939 can be used with this encoding method.
1942 A wide character is represented using
1943 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
1944 10646-1/Am.2. Depending on the character value, the representation
1945 is a one, two, or three byte sequence:
1950 16#0000#-16#007f#: 2#0@var{xxxxxxx}#
1951 16#0080#-16#07ff#: 2#110@var{xxxxx}# 2#10@var{xxxxxx}#
1952 16#0800#-16#ffff#: 2#1110@var{xxxx}# 2#10@var{xxxxxx}# 2#10@var{xxxxxx}#
1957 where the @var{xxx} bits correspond to the left-padded bits of the
1958 16-bit character value. Note that all lower half ASCII characters
1959 are represented as ASCII bytes and all upper half characters and
1960 other wide characters are represented as sequences of upper-half
1961 (The full UTF-8 scheme allows for encoding 31-bit characters as
1962 6-byte sequences, but in this implementation, all UTF-8 sequences
1963 of four or more bytes length will be treated as illegal).
1964 @item Brackets Coding
1965 In this encoding, a wide character is represented by the following eight
1973 Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
1974 characters (using uppercase letters) of the wide character code. For
1975 example, [``A345''] is used to represent the wide character with code
1976 @code{16#A345#}. It is also possible (though not required) to use the
1977 Brackets coding for upper half characters. For example, the code
1978 @code{16#A3#} can be represented as @code{[``A3'']}.
1980 This scheme is compatible with use of the full Wide_Character set,
1981 and is also the method used for wide character encoding in the standard
1982 ACVC (Ada Compiler Validation Capability) test suite distributions.
1987 Note: Some of these coding schemes do not permit the full use of the
1988 Ada character set. For example, neither Shift JIS, nor EUC allow the
1989 use of the upper half of the Latin-1 set.
1991 @node File Naming Rules
1992 @section File Naming Rules
1995 The default file name is determined by the name of the unit that the
1996 file contains. The name is formed by taking the full expanded name of
1997 the unit and replacing the separating dots with hyphens and using
1998 ^lowercase^uppercase^ for all letters.
2000 An exception arises if the file name generated by the above rules starts
2001 with one of the characters
2003 @samp{A}, @samp{G}, @samp{I}, or @samp{S},
2006 @samp{a}, @samp{g}, @samp{i}, or @samp{s},
2008 and the second character is a
2009 minus. In this case, the character ^tilde^dollar sign^ is used in place
2010 of the minus. The reason for this special rule is to avoid clashes with
2011 the standard names for child units of the packages System, Ada,
2012 Interfaces, and GNAT, which use the prefixes
2014 @samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},
2017 @samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},
2021 The file extension is @file{.ads} for a spec and
2022 @file{.adb} for a body. The following list shows some
2023 examples of these rules.
2030 @item arith_functions.ads
2031 Arith_Functions (package spec)
2032 @item arith_functions.adb
2033 Arith_Functions (package body)
2035 Func.Spec (child package spec)
2037 Func.Spec (child package body)
2039 Sub (subunit of Main)
2040 @item ^a~bad.adb^A$BAD.ADB^
2041 A.Bad (child package body)
2045 Following these rules can result in excessively long
2046 file names if corresponding
2047 unit names are long (for example, if child units or subunits are
2048 heavily nested). An option is available to shorten such long file names
2049 (called file name ``krunching''). This may be particularly useful when
2050 programs being developed with GNAT are to be used on operating systems
2051 with limited file name lengths. @xref{Using gnatkr}.
2053 Of course, no file shortening algorithm can guarantee uniqueness over
2054 all possible unit names; if file name krunching is used, it is your
2055 responsibility to ensure no name clashes occur. Alternatively you
2056 can specify the exact file names that you want used, as described
2057 in the next section. Finally, if your Ada programs are migrating from a
2058 compiler with a different naming convention, you can use the gnatchop
2059 utility to produce source files that follow the GNAT naming conventions.
2060 (For details @pxref{Renaming Files Using gnatchop}.)
2062 Note: in the case of @code{Windows NT/XP} or @code{OpenVMS} operating
2063 systems, case is not significant. So for example on @code{Windows XP}
2064 if the canonical name is @code{main-sub.adb}, you can use the file name
2065 @code{Main-Sub.adb} instead. However, case is significant for other
2066 operating systems, so for example, if you want to use other than
2067 canonically cased file names on a Unix system, you need to follow
2068 the procedures described in the next section.
2070 @node Using Other File Names
2071 @section Using Other File Names
2075 In the previous section, we have described the default rules used by
2076 GNAT to determine the file name in which a given unit resides. It is
2077 often convenient to follow these default rules, and if you follow them,
2078 the compiler knows without being explicitly told where to find all
2081 However, in some cases, particularly when a program is imported from
2082 another Ada compiler environment, it may be more convenient for the
2083 programmer to specify which file names contain which units. GNAT allows
2084 arbitrary file names to be used by means of the Source_File_Name pragma.
2085 The form of this pragma is as shown in the following examples:
2086 @cindex Source_File_Name pragma
2088 @smallexample @c ada
2090 pragma Source_File_Name (My_Utilities.Stacks,
2091 Spec_File_Name => "myutilst_a.ada");
2092 pragma Source_File_name (My_Utilities.Stacks,
2093 Body_File_Name => "myutilst.ada");
2098 As shown in this example, the first argument for the pragma is the unit
2099 name (in this example a child unit). The second argument has the form
2100 of a named association. The identifier
2101 indicates whether the file name is for a spec or a body;
2102 the file name itself is given by a string literal.
2104 The source file name pragma is a configuration pragma, which means that
2105 normally it will be placed in the @file{gnat.adc}
2106 file used to hold configuration
2107 pragmas that apply to a complete compilation environment.
2108 For more details on how the @file{gnat.adc} file is created and used
2109 see @ref{Handling of Configuration Pragmas}.
2110 @cindex @file{gnat.adc}
2113 GNAT allows completely arbitrary file names to be specified using the
2114 source file name pragma. However, if the file name specified has an
2115 extension other than @file{.ads} or @file{.adb} it is necessary to use
2116 a special syntax when compiling the file. The name in this case must be
2117 preceded by the special sequence @option{-x} followed by a space and the name
2118 of the language, here @code{ada}, as in:
2121 $ gcc -c -x ada peculiar_file_name.sim
2126 @command{gnatmake} handles non-standard file names in the usual manner (the
2127 non-standard file name for the main program is simply used as the
2128 argument to gnatmake). Note that if the extension is also non-standard,
2129 then it must be included in the @command{gnatmake} command, it may not
2132 @node Alternative File Naming Schemes
2133 @section Alternative File Naming Schemes
2134 @cindex File naming schemes, alternative
2137 In the previous section, we described the use of the @code{Source_File_Name}
2138 pragma to allow arbitrary names to be assigned to individual source files.
2139 However, this approach requires one pragma for each file, and especially in
2140 large systems can result in very long @file{gnat.adc} files, and also create
2141 a maintenance problem.
2143 GNAT also provides a facility for specifying systematic file naming schemes
2144 other than the standard default naming scheme previously described. An
2145 alternative scheme for naming is specified by the use of
2146 @code{Source_File_Name} pragmas having the following format:
2147 @cindex Source_File_Name pragma
2149 @smallexample @c ada
2150 pragma Source_File_Name (
2151 Spec_File_Name => FILE_NAME_PATTERN
2152 @r{[},Casing => CASING_SPEC@r{]}
2153 @r{[},Dot_Replacement => STRING_LITERAL@r{]});
2155 pragma Source_File_Name (
2156 Body_File_Name => FILE_NAME_PATTERN
2157 @r{[},Casing => CASING_SPEC@r{]}
2158 @r{[},Dot_Replacement => STRING_LITERAL@r{]});
2160 pragma Source_File_Name (
2161 Subunit_File_Name => FILE_NAME_PATTERN
2162 @r{[},Casing => CASING_SPEC@r{]}
2163 @r{[},Dot_Replacement => STRING_LITERAL@r{]});
2165 FILE_NAME_PATTERN ::= STRING_LITERAL
2166 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
2170 The @code{FILE_NAME_PATTERN} string shows how the file name is constructed.
2171 It contains a single asterisk character, and the unit name is substituted
2172 systematically for this asterisk. The optional parameter
2173 @code{Casing} indicates
2174 whether the unit name is to be all upper-case letters, all lower-case letters,
2175 or mixed-case. If no
2176 @code{Casing} parameter is used, then the default is all
2177 ^lower-case^upper-case^.
2179 The optional @code{Dot_Replacement} string is used to replace any periods
2180 that occur in subunit or child unit names. If no @code{Dot_Replacement}
2181 argument is used then separating dots appear unchanged in the resulting
2183 Although the above syntax indicates that the
2184 @code{Casing} argument must appear
2185 before the @code{Dot_Replacement} argument, but it
2186 is also permissible to write these arguments in the opposite order.
2188 As indicated, it is possible to specify different naming schemes for
2189 bodies, specs, and subunits. Quite often the rule for subunits is the
2190 same as the rule for bodies, in which case, there is no need to give
2191 a separate @code{Subunit_File_Name} rule, and in this case the
2192 @code{Body_File_name} rule is used for subunits as well.
2194 The separate rule for subunits can also be used to implement the rather
2195 unusual case of a compilation environment (e.g.@: a single directory) which
2196 contains a subunit and a child unit with the same unit name. Although
2197 both units cannot appear in the same partition, the Ada Reference Manual
2198 allows (but does not require) the possibility of the two units coexisting
2199 in the same environment.
2201 The file name translation works in the following steps:
2206 If there is a specific @code{Source_File_Name} pragma for the given unit,
2207 then this is always used, and any general pattern rules are ignored.
2210 If there is a pattern type @code{Source_File_Name} pragma that applies to
2211 the unit, then the resulting file name will be used if the file exists. If
2212 more than one pattern matches, the latest one will be tried first, and the
2213 first attempt resulting in a reference to a file that exists will be used.
2216 If no pattern type @code{Source_File_Name} pragma that applies to the unit
2217 for which the corresponding file exists, then the standard GNAT default
2218 naming rules are used.
2223 As an example of the use of this mechanism, consider a commonly used scheme
2224 in which file names are all lower case, with separating periods copied
2225 unchanged to the resulting file name, and specs end with @file{.1.ada}, and
2226 bodies end with @file{.2.ada}. GNAT will follow this scheme if the following
2229 @smallexample @c ada
2230 pragma Source_File_Name
2231 (Spec_File_Name => "*.1.ada");
2232 pragma Source_File_Name
2233 (Body_File_Name => "*.2.ada");
2237 The default GNAT scheme is actually implemented by providing the following
2238 default pragmas internally:
2240 @smallexample @c ada
2241 pragma Source_File_Name
2242 (Spec_File_Name => "*.ads", Dot_Replacement => "-");
2243 pragma Source_File_Name
2244 (Body_File_Name => "*.adb", Dot_Replacement => "-");
2248 Our final example implements a scheme typically used with one of the
2249 Ada 83 compilers, where the separator character for subunits was ``__''
2250 (two underscores), specs were identified by adding @file{_.ADA}, bodies
2251 by adding @file{.ADA}, and subunits by
2252 adding @file{.SEP}. All file names were
2253 upper case. Child units were not present of course since this was an
2254 Ada 83 compiler, but it seems reasonable to extend this scheme to use
2255 the same double underscore separator for child units.
2257 @smallexample @c ada
2258 pragma Source_File_Name
2259 (Spec_File_Name => "*_.ADA",
2260 Dot_Replacement => "__",
2261 Casing = Uppercase);
2262 pragma Source_File_Name
2263 (Body_File_Name => "*.ADA",
2264 Dot_Replacement => "__",
2265 Casing = Uppercase);
2266 pragma Source_File_Name
2267 (Subunit_File_Name => "*.SEP",
2268 Dot_Replacement => "__",
2269 Casing = Uppercase);
2272 @node Generating Object Files
2273 @section Generating Object Files
2276 An Ada program consists of a set of source files, and the first step in
2277 compiling the program is to generate the corresponding object files.
2278 These are generated by compiling a subset of these source files.
2279 The files you need to compile are the following:
2283 If a package spec has no body, compile the package spec to produce the
2284 object file for the package.
2287 If a package has both a spec and a body, compile the body to produce the
2288 object file for the package. The source file for the package spec need
2289 not be compiled in this case because there is only one object file, which
2290 contains the code for both the spec and body of the package.
2293 For a subprogram, compile the subprogram body to produce the object file
2294 for the subprogram. The spec, if one is present, is as usual in a
2295 separate file, and need not be compiled.
2299 In the case of subunits, only compile the parent unit. A single object
2300 file is generated for the entire subunit tree, which includes all the
2304 Compile child units independently of their parent units
2305 (though, of course, the spec of all the ancestor unit must be present in order
2306 to compile a child unit).
2310 Compile generic units in the same manner as any other units. The object
2311 files in this case are small dummy files that contain at most the
2312 flag used for elaboration checking. This is because GNAT always handles generic
2313 instantiation by means of macro expansion. However, it is still necessary to
2314 compile generic units, for dependency checking and elaboration purposes.
2318 The preceding rules describe the set of files that must be compiled to
2319 generate the object files for a program. Each object file has the same
2320 name as the corresponding source file, except that the extension is
2323 You may wish to compile other files for the purpose of checking their
2324 syntactic and semantic correctness. For example, in the case where a
2325 package has a separate spec and body, you would not normally compile the
2326 spec. However, it is convenient in practice to compile the spec to make
2327 sure it is error-free before compiling clients of this spec, because such
2328 compilations will fail if there is an error in the spec.
2330 GNAT provides an option for compiling such files purely for the
2331 purposes of checking correctness; such compilations are not required as
2332 part of the process of building a program. To compile a file in this
2333 checking mode, use the @option{-gnatc} switch.
2335 @node Source Dependencies
2336 @section Source Dependencies
2339 A given object file clearly depends on the source file which is compiled
2340 to produce it. Here we are using @dfn{depends} in the sense of a typical
2341 @code{make} utility; in other words, an object file depends on a source
2342 file if changes to the source file require the object file to be
2344 In addition to this basic dependency, a given object may depend on
2345 additional source files as follows:
2349 If a file being compiled @code{with}'s a unit @var{X}, the object file
2350 depends on the file containing the spec of unit @var{X}. This includes
2351 files that are @code{with}'ed implicitly either because they are parents
2352 of @code{with}'ed child units or they are run-time units required by the
2353 language constructs used in a particular unit.
2356 If a file being compiled instantiates a library level generic unit, the
2357 object file depends on both the spec and body files for this generic
2361 If a file being compiled instantiates a generic unit defined within a
2362 package, the object file depends on the body file for the package as
2363 well as the spec file.
2367 @cindex @option{-gnatn} switch
2368 If a file being compiled contains a call to a subprogram for which
2369 pragma @code{Inline} applies and inlining is activated with the
2370 @option{-gnatn} switch, the object file depends on the file containing the
2371 body of this subprogram as well as on the file containing the spec. Note
2372 that for inlining to actually occur as a result of the use of this switch,
2373 it is necessary to compile in optimizing mode.
2375 @cindex @option{-gnatN} switch
2376 The use of @option{-gnatN} activates inlining optimization
2377 that is performed by the front end of the compiler. This inlining does
2378 not require that the code generation be optimized. Like @option{-gnatn},
2379 the use of this switch generates additional dependencies.
2381 When using a gcc-based back end (in practice this means using any version
2382 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
2383 @option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
2384 Historically front end inlining was more extensive than the gcc back end
2385 inlining, but that is no longer the case.
2388 If an object file @file{O} depends on the proper body of a subunit through
2389 inlining or instantiation, it depends on the parent unit of the subunit.
2390 This means that any modification of the parent unit or one of its subunits
2391 affects the compilation of @file{O}.
2394 The object file for a parent unit depends on all its subunit body files.
2397 The previous two rules meant that for purposes of computing dependencies and
2398 recompilation, a body and all its subunits are treated as an indivisible whole.
2401 These rules are applied transitively: if unit @code{A} @code{with}'s
2402 unit @code{B}, whose elaboration calls an inlined procedure in package
2403 @code{C}, the object file for unit @code{A} will depend on the body of
2404 @code{C}, in file @file{c.adb}.
2406 The set of dependent files described by these rules includes all the
2407 files on which the unit is semantically dependent, as dictated by the
2408 Ada language standard. However, it is a superset of what the
2409 standard describes, because it includes generic, inline, and subunit
2412 An object file must be recreated by recompiling the corresponding source
2413 file if any of the source files on which it depends are modified. For
2414 example, if the @code{make} utility is used to control compilation,
2415 the rule for an Ada object file must mention all the source files on
2416 which the object file depends, according to the above definition.
2417 The determination of the necessary
2418 recompilations is done automatically when one uses @command{gnatmake}.
2421 @node The Ada Library Information Files
2422 @section The Ada Library Information Files
2423 @cindex Ada Library Information files
2424 @cindex @file{ALI} files
2427 Each compilation actually generates two output files. The first of these
2428 is the normal object file that has a @file{.o} extension. The second is a
2429 text file containing full dependency information. It has the same
2430 name as the source file, but an @file{.ali} extension.
2431 This file is known as the Ada Library Information (@file{ALI}) file.
2432 The following information is contained in the @file{ALI} file.
2436 Version information (indicates which version of GNAT was used to compile
2437 the unit(s) in question)
2440 Main program information (including priority and time slice settings,
2441 as well as the wide character encoding used during compilation).
2444 List of arguments used in the @command{gcc} command for the compilation
2447 Attributes of the unit, including configuration pragmas used, an indication
2448 of whether the compilation was successful, exception model used etc.
2451 A list of relevant restrictions applying to the unit (used for consistency)
2455 Categorization information (e.g.@: use of pragma @code{Pure}).
2458 Information on all @code{with}'ed units, including presence of
2459 @code{Elaborate} or @code{Elaborate_All} pragmas.
2462 Information from any @code{Linker_Options} pragmas used in the unit
2465 Information on the use of @code{Body_Version} or @code{Version}
2466 attributes in the unit.
2469 Dependency information. This is a list of files, together with
2470 time stamp and checksum information. These are files on which
2471 the unit depends in the sense that recompilation is required
2472 if any of these units are modified.
2475 Cross-reference data. Contains information on all entities referenced
2476 in the unit. Used by tools like @code{gnatxref} and @code{gnatfind} to
2477 provide cross-reference information.
2482 For a full detailed description of the format of the @file{ALI} file,
2483 see the source of the body of unit @code{Lib.Writ}, contained in file
2484 @file{lib-writ.adb} in the GNAT compiler sources.
2486 @node Binding an Ada Program
2487 @section Binding an Ada Program
2490 When using languages such as C and C++, once the source files have been
2491 compiled the only remaining step in building an executable program
2492 is linking the object modules together. This means that it is possible to
2493 link an inconsistent version of a program, in which two units have
2494 included different versions of the same header.
2496 The rules of Ada do not permit such an inconsistent program to be built.
2497 For example, if two clients have different versions of the same package,
2498 it is illegal to build a program containing these two clients.
2499 These rules are enforced by the GNAT binder, which also determines an
2500 elaboration order consistent with the Ada rules.
2502 The GNAT binder is run after all the object files for a program have
2503 been created. It is given the name of the main program unit, and from
2504 this it determines the set of units required by the program, by reading the
2505 corresponding ALI files. It generates error messages if the program is
2506 inconsistent or if no valid order of elaboration exists.
2508 If no errors are detected, the binder produces a main program, in Ada by
2509 default, that contains calls to the elaboration procedures of those
2510 compilation unit that require them, followed by
2511 a call to the main program. This Ada program is compiled to generate the
2512 object file for the main program. The name of
2513 the Ada file is @file{b~@var{xxx}.adb} (with the corresponding spec
2514 @file{b~@var{xxx}.ads}) where @var{xxx} is the name of the
2517 Finally, the linker is used to build the resulting executable program,
2518 using the object from the main program from the bind step as well as the
2519 object files for the Ada units of the program.
2521 @node Mixed Language Programming
2522 @section Mixed Language Programming
2523 @cindex Mixed Language Programming
2526 This section describes how to develop a mixed-language program,
2527 specifically one that comprises units in both Ada and C.
2530 * Interfacing to C::
2531 * Calling Conventions::
2534 @node Interfacing to C
2535 @subsection Interfacing to C
2537 Interfacing Ada with a foreign language such as C involves using
2538 compiler directives to import and/or export entity definitions in each
2539 language---using @code{extern} statements in C, for instance, and the
2540 @code{Import}, @code{Export}, and @code{Convention} pragmas in Ada.
2541 A full treatment of these topics is provided in Appendix B, section 1
2542 of the Ada Reference Manual.
2544 There are two ways to build a program using GNAT that contains some Ada
2545 sources and some foreign language sources, depending on whether or not
2546 the main subprogram is written in Ada. Here is a source example with
2547 the main subprogram in Ada:
2553 void print_num (int num)
2555 printf ("num is %d.\n", num);
2561 /* num_from_Ada is declared in my_main.adb */
2562 extern int num_from_Ada;
2566 return num_from_Ada;
2570 @smallexample @c ada
2572 procedure My_Main is
2574 -- Declare then export an Integer entity called num_from_Ada
2575 My_Num : Integer := 10;
2576 pragma Export (C, My_Num, "num_from_Ada");
2578 -- Declare an Ada function spec for Get_Num, then use
2579 -- C function get_num for the implementation.
2580 function Get_Num return Integer;
2581 pragma Import (C, Get_Num, "get_num");
2583 -- Declare an Ada procedure spec for Print_Num, then use
2584 -- C function print_num for the implementation.
2585 procedure Print_Num (Num : Integer);
2586 pragma Import (C, Print_Num, "print_num");
2589 Print_Num (Get_Num);
2595 To build this example, first compile the foreign language files to
2596 generate object files:
2598 ^gcc -c file1.c^gcc -c FILE1.C^
2599 ^gcc -c file2.c^gcc -c FILE2.C^
2603 Then, compile the Ada units to produce a set of object files and ALI
2606 gnatmake ^-c^/ACTIONS=COMPILE^ my_main.adb
2610 Run the Ada binder on the Ada main program:
2612 gnatbind my_main.ali
2616 Link the Ada main program, the Ada objects and the other language
2619 gnatlink my_main.ali file1.o file2.o
2623 The last three steps can be grouped in a single command:
2625 gnatmake my_main.adb -largs file1.o file2.o
2628 @cindex Binder output file
2630 If the main program is in a language other than Ada, then you may have
2631 more than one entry point into the Ada subsystem. You must use a special
2632 binder option to generate callable routines that initialize and
2633 finalize the Ada units (@pxref{Binding with Non-Ada Main Programs}).
2634 Calls to the initialization and finalization routines must be inserted
2635 in the main program, or some other appropriate point in the code. The
2636 call to initialize the Ada units must occur before the first Ada
2637 subprogram is called, and the call to finalize the Ada units must occur
2638 after the last Ada subprogram returns. The binder will place the
2639 initialization and finalization subprograms into the
2640 @file{b~@var{xxx}.adb} file where they can be accessed by your C
2641 sources. To illustrate, we have the following example:
2645 extern void adainit (void);
2646 extern void adafinal (void);
2647 extern int add (int, int);
2648 extern int sub (int, int);
2650 int main (int argc, char *argv[])
2656 /* Should print "21 + 7 = 28" */
2657 printf ("%d + %d = %d\n", a, b, add (a, b));
2658 /* Should print "21 - 7 = 14" */
2659 printf ("%d - %d = %d\n", a, b, sub (a, b));
2665 @smallexample @c ada
2668 function Add (A, B : Integer) return Integer;
2669 pragma Export (C, Add, "add");
2673 package body Unit1 is
2674 function Add (A, B : Integer) return Integer is
2682 function Sub (A, B : Integer) return Integer;
2683 pragma Export (C, Sub, "sub");
2687 package body Unit2 is
2688 function Sub (A, B : Integer) return Integer is
2697 The build procedure for this application is similar to the last
2698 example's. First, compile the foreign language files to generate object
2701 ^gcc -c main.c^gcc -c main.c^
2705 Next, compile the Ada units to produce a set of object files and ALI
2708 gnatmake ^-c^/ACTIONS=COMPILE^ unit1.adb
2709 gnatmake ^-c^/ACTIONS=COMPILE^ unit2.adb
2713 Run the Ada binder on every generated ALI file. Make sure to use the
2714 @option{-n} option to specify a foreign main program:
2716 gnatbind ^-n^/NOMAIN^ unit1.ali unit2.ali
2720 Link the Ada main program, the Ada objects and the foreign language
2721 objects. You need only list the last ALI file here:
2723 gnatlink unit2.ali main.o -o exec_file
2726 This procedure yields a binary executable called @file{exec_file}.
2730 Depending on the circumstances (for example when your non-Ada main object
2731 does not provide symbol @code{main}), you may also need to instruct the
2732 GNAT linker not to include the standard startup objects by passing the
2733 @option{^-nostartfiles^/NOSTART_FILES^} switch to @command{gnatlink}.
2735 @node Calling Conventions
2736 @subsection Calling Conventions
2737 @cindex Foreign Languages
2738 @cindex Calling Conventions
2739 GNAT follows standard calling sequence conventions and will thus interface
2740 to any other language that also follows these conventions. The following
2741 Convention identifiers are recognized by GNAT:
2744 @cindex Interfacing to Ada
2745 @cindex Other Ada compilers
2746 @cindex Convention Ada
2748 This indicates that the standard Ada calling sequence will be
2749 used and all Ada data items may be passed without any limitations in the
2750 case where GNAT is used to generate both the caller and callee. It is also
2751 possible to mix GNAT generated code and code generated by another Ada
2752 compiler. In this case, the data types should be restricted to simple
2753 cases, including primitive types. Whether complex data types can be passed
2754 depends on the situation. Probably it is safe to pass simple arrays, such
2755 as arrays of integers or floats. Records may or may not work, depending
2756 on whether both compilers lay them out identically. Complex structures
2757 involving variant records, access parameters, tasks, or protected types,
2758 are unlikely to be able to be passed.
2760 Note that in the case of GNAT running
2761 on a platform that supports HP Ada 83, a higher degree of compatibility
2762 can be guaranteed, and in particular records are layed out in an identical
2763 manner in the two compilers. Note also that if output from two different
2764 compilers is mixed, the program is responsible for dealing with elaboration
2765 issues. Probably the safest approach is to write the main program in the
2766 version of Ada other than GNAT, so that it takes care of its own elaboration
2767 requirements, and then call the GNAT-generated adainit procedure to ensure
2768 elaboration of the GNAT components. Consult the documentation of the other
2769 Ada compiler for further details on elaboration.
2771 However, it is not possible to mix the tasking run time of GNAT and
2772 HP Ada 83, All the tasking operations must either be entirely within
2773 GNAT compiled sections of the program, or entirely within HP Ada 83
2774 compiled sections of the program.
2776 @cindex Interfacing to Assembly
2777 @cindex Convention Assembler
2779 Specifies assembler as the convention. In practice this has the
2780 same effect as convention Ada (but is not equivalent in the sense of being
2781 considered the same convention).
2783 @cindex Convention Asm
2786 Equivalent to Assembler.
2788 @cindex Interfacing to COBOL
2789 @cindex Convention COBOL
2792 Data will be passed according to the conventions described
2793 in section B.4 of the Ada Reference Manual.
2796 @cindex Interfacing to C
2797 @cindex Convention C
2799 Data will be passed according to the conventions described
2800 in section B.3 of the Ada Reference Manual.
2802 A note on interfacing to a C ``varargs'' function:
2803 @findex C varargs function
2804 @cindex Interfacing to C varargs function
2805 @cindex varargs function interfaces
2809 In C, @code{varargs} allows a function to take a variable number of
2810 arguments. There is no direct equivalent in this to Ada. One
2811 approach that can be used is to create a C wrapper for each
2812 different profile and then interface to this C wrapper. For
2813 example, to print an @code{int} value using @code{printf},
2814 create a C function @code{printfi} that takes two arguments, a
2815 pointer to a string and an int, and calls @code{printf}.
2816 Then in the Ada program, use pragma @code{Import} to
2817 interface to @code{printfi}.
2820 It may work on some platforms to directly interface to
2821 a @code{varargs} function by providing a specific Ada profile
2822 for a particular call. However, this does not work on
2823 all platforms, since there is no guarantee that the
2824 calling sequence for a two argument normal C function
2825 is the same as for calling a @code{varargs} C function with
2826 the same two arguments.
2829 @cindex Convention Default
2834 @cindex Convention External
2841 @cindex Interfacing to C++
2842 @cindex Convention C++
2843 @item C_Plus_Plus (or CPP)
2844 This stands for C++. For most purposes this is identical to C.
2845 See the separate description of the specialized GNAT pragmas relating to
2846 C++ interfacing for further details.
2850 @cindex Interfacing to Fortran
2851 @cindex Convention Fortran
2853 Data will be passed according to the conventions described
2854 in section B.5 of the Ada Reference Manual.
2857 This applies to an intrinsic operation, as defined in the Ada
2858 Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram,
2859 this means that the body of the subprogram is provided by the compiler itself,
2860 usually by means of an efficient code sequence, and that the user does not
2861 supply an explicit body for it. In an application program, the pragma may
2862 be applied to the following sets of names:
2866 Rotate_Left, Rotate_Right, Shift_Left, Shift_Right,
2867 Shift_Right_Arithmetic. The corresponding subprogram declaration must have
2868 two formal parameters. The
2869 first one must be a signed integer type or a modular type with a binary
2870 modulus, and the second parameter must be of type Natural.
2871 The return type must be the same as the type of the first argument. The size
2872 of this type can only be 8, 16, 32, or 64.
2875 Binary arithmetic operators: ``+'', ``-'', ``*'', ``/''
2876 The corresponding operator declaration must have parameters and result type
2877 that have the same root numeric type (for example, all three are long_float
2878 types). This simplifies the definition of operations that use type checking
2879 to perform dimensional checks:
2881 @smallexample @c ada
2882 type Distance is new Long_Float;
2883 type Time is new Long_Float;
2884 type Velocity is new Long_Float;
2885 function "/" (D : Distance; T : Time)
2887 pragma Import (Intrinsic, "/");
2891 This common idiom is often programmed with a generic definition and an
2892 explicit body. The pragma makes it simpler to introduce such declarations.
2893 It incurs no overhead in compilation time or code size, because it is
2894 implemented as a single machine instruction.
2897 General subprogram entities, to bind an Ada subprogram declaration to
2898 a compiler builtin by name with back-ends where such interfaces are
2899 available. A typical example is the set of ``__builtin'' functions
2900 exposed by the GCC back-end, as in the following example:
2902 @smallexample @c ada
2903 function builtin_sqrt (F : Float) return Float;
2904 pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf");
2907 Most of the GCC builtins are accessible this way, and as for other
2908 import conventions (e.g. C), it is the user's responsibility to ensure
2909 that the Ada subprogram profile matches the underlying builtin
2917 @cindex Convention Stdcall
2919 This is relevant only to Windows XP/2000/NT implementations of GNAT,
2920 and specifies that the @code{Stdcall} calling sequence will be used,
2921 as defined by the NT API. Nevertheless, to ease building
2922 cross-platform bindings this convention will be handled as a @code{C} calling
2923 convention on non-Windows platforms.
2926 @cindex Convention DLL
2928 This is equivalent to @code{Stdcall}.
2931 @cindex Convention Win32
2933 This is equivalent to @code{Stdcall}.
2937 @cindex Convention Stubbed
2939 This is a special convention that indicates that the compiler
2940 should provide a stub body that raises @code{Program_Error}.
2944 GNAT additionally provides a useful pragma @code{Convention_Identifier}
2945 that can be used to parametrize conventions and allow additional synonyms
2946 to be specified. For example if you have legacy code in which the convention
2947 identifier Fortran77 was used for Fortran, you can use the configuration
2950 @smallexample @c ada
2951 pragma Convention_Identifier (Fortran77, Fortran);
2955 And from now on the identifier Fortran77 may be used as a convention
2956 identifier (for example in an @code{Import} pragma) with the same
2960 @node Building Mixed Ada & C++ Programs
2961 @section Building Mixed Ada and C++ Programs
2964 A programmer inexperienced with mixed-language development may find that
2965 building an application containing both Ada and C++ code can be a
2966 challenge. This section gives a few
2967 hints that should make this task easier. The first section addresses
2968 the differences between interfacing with C and interfacing with C++.
2970 looks into the delicate problem of linking the complete application from
2971 its Ada and C++ parts. The last section gives some hints on how the GNAT
2972 run-time library can be adapted in order to allow inter-language dispatching
2973 with a new C++ compiler.
2976 * Interfacing to C++::
2977 * Linking a Mixed C++ & Ada Program::
2978 * A Simple Example::
2979 * Interfacing with C++ constructors::
2980 * Interfacing with C++ at the Class Level::
2983 @node Interfacing to C++
2984 @subsection Interfacing to C++
2987 GNAT supports interfacing with the G++ compiler (or any C++ compiler
2988 generating code that is compatible with the G++ Application Binary
2989 Interface ---see http://www.codesourcery.com/archives/cxx-abi).
2992 Interfacing can be done at 3 levels: simple data, subprograms, and
2993 classes. In the first two cases, GNAT offers a specific @code{Convention
2994 C_Plus_Plus} (or @code{CPP}) that behaves exactly like @code{Convention C}.
2995 Usually, C++ mangles the names of subprograms, and currently, GNAT does
2996 not provide any help to solve the demangling problem. This problem can be
2997 addressed in two ways:
3000 by modifying the C++ code in order to force a C convention using
3001 the @code{extern "C"} syntax.
3004 by figuring out the mangled name and use it as the Link_Name argument of
3009 Interfacing at the class level can be achieved by using the GNAT specific
3010 pragmas such as @code{CPP_Constructor}. @xref{Interfacing to C++,,,
3011 gnat_rm, GNAT Reference Manual}, for additional information.
3013 @node Linking a Mixed C++ & Ada Program
3014 @subsection Linking a Mixed C++ & Ada Program
3017 Usually the linker of the C++ development system must be used to link
3018 mixed applications because most C++ systems will resolve elaboration
3019 issues (such as calling constructors on global class instances)
3020 transparently during the link phase. GNAT has been adapted to ease the
3021 use of a foreign linker for the last phase. Three cases can be
3026 Using GNAT and G++ (GNU C++ compiler) from the same GCC installation:
3027 The C++ linker can simply be called by using the C++ specific driver
3028 called @code{c++}. Note that this setup is not very common because it
3029 may involve recompiling the whole GCC tree from sources, which makes it
3030 harder to upgrade the compilation system for one language without
3031 destabilizing the other.
3036 $ gnatmake ada_unit -largs file1.o file2.o --LINK=c++
3040 Using GNAT and G++ from two different GCC installations: If both
3041 compilers are on the @env{PATH}, the previous method may be used. It is
3042 important to note that environment variables such as
3043 @env{C_INCLUDE_PATH}, @env{GCC_EXEC_PREFIX}, @env{BINUTILS_ROOT}, and
3044 @env{GCC_ROOT} will affect both compilers
3045 at the same time and may make one of the two compilers operate
3046 improperly if set during invocation of the wrong compiler. It is also
3047 very important that the linker uses the proper @file{libgcc.a} GCC
3048 library -- that is, the one from the C++ compiler installation. The
3049 implicit link command as suggested in the @command{gnatmake} command
3050 from the former example can be replaced by an explicit link command with
3051 the full-verbosity option in order to verify which library is used:
3054 $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++
3056 If there is a problem due to interfering environment variables, it can
3057 be worked around by using an intermediate script. The following example
3058 shows the proper script to use when GNAT has not been installed at its
3059 default location and g++ has been installed at its default location:
3067 $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script
3071 Using a non-GNU C++ compiler: The commands previously described can be
3072 used to insure that the C++ linker is used. Nonetheless, you need to add
3073 a few more parameters to the link command line, depending on the exception
3076 If the @code{setjmp/longjmp} exception mechanism is used, only the paths
3077 to the libgcc libraries are required:
3082 CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a`
3083 $ gnatlink ada_unit file1.o file2.o --LINK=./my_script
3086 Where CC is the name of the non-GNU C++ compiler.
3088 If the @code{zero cost} exception mechanism is used, and the platform
3089 supports automatic registration of exception tables (e.g.@: Solaris or IRIX),
3090 paths to more objects are required:
3095 CC `gcc -print-file-name=crtbegin.o` $* \
3096 `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \
3097 `gcc -print-file-name=crtend.o`
3098 $ gnatlink ada_unit file1.o file2.o --LINK=./my_script
3101 If the @code{zero cost} exception mechanism is used, and the platform
3102 doesn't support automatic registration of exception tables (e.g.@: HP-UX,
3103 Tru64 or AIX), the simple approach described above will not work and
3104 a pre-linking phase using GNAT will be necessary.
3108 @node A Simple Example
3109 @subsection A Simple Example
3111 The following example, provided as part of the GNAT examples, shows how
3112 to achieve procedural interfacing between Ada and C++ in both
3113 directions. The C++ class A has two methods. The first method is exported
3114 to Ada by the means of an extern C wrapper function. The second method
3115 calls an Ada subprogram. On the Ada side, The C++ calls are modelled by
3116 a limited record with a layout comparable to the C++ class. The Ada
3117 subprogram, in turn, calls the C++ method. So, starting from the C++
3118 main program, the process passes back and forth between the two
3122 Here are the compilation commands:
3124 $ gnatmake -c simple_cpp_interface
3127 $ gnatbind -n simple_cpp_interface
3128 $ gnatlink simple_cpp_interface -o cpp_main --LINK=$(CPLUSPLUS)
3129 -lstdc++ ex7.o cpp_main.o
3133 Here are the corresponding sources:
3141 void adainit (void);
3142 void adafinal (void);
3143 void method1 (A *t);
3165 class A : public Origin @{
3167 void method1 (void);
3168 void method2 (int v);
3178 extern "C" @{ void ada_method2 (A *t, int v);@}
3180 void A::method1 (void)
3183 printf ("in A::method1, a_value = %d \n",a_value);
3187 void A::method2 (int v)
3189 ada_method2 (this, v);
3190 printf ("in A::method2, a_value = %d \n",a_value);
3197 printf ("in A::A, a_value = %d \n",a_value);
3201 @smallexample @c ada
3203 package body Simple_Cpp_Interface is
3205 procedure Ada_Method2 (This : in out A; V : Integer) is
3211 end Simple_Cpp_Interface;
3214 package Simple_Cpp_Interface is
3217 Vptr : System.Address;
3221 pragma Convention (C, A);
3223 procedure Method1 (This : in out A);
3224 pragma Import (C, Method1);
3226 procedure Ada_Method2 (This : in out A; V : Integer);
3227 pragma Export (C, Ada_Method2);
3229 end Simple_Cpp_Interface;
3232 @node Interfacing with C++ constructors
3233 @subsection Interfacing with C++ constructors
3236 In order to interface with C++ constructors GNAT provides the
3237 @code{pragma CPP_Constructor} (@xref{Interfacing to C++,,,
3238 gnat_rm, GNAT Reference Manual}, for additional information).
3239 In this section we present some common uses of C++ constructors
3240 in mixed-languages programs in GNAT.
3242 Let us assume that we need to interface with the following
3250 @b{virtual} int Get_Value ();
3251 Root(); // Default constructor
3252 Root(int v); // 1st non-default constructor
3253 Root(int v, int w); // 2nd non-default constructor
3257 For this purpose we can write the following package spec (further
3258 information on how to build this spec is available in
3259 @ref{Interfacing with C++ at the Class Level} and
3260 @ref{Generating Ada Bindings for C and C++ headers}).
3262 @smallexample @c ada
3263 with Interfaces.C; use Interfaces.C;
3265 type Root is tagged limited record
3269 pragma Import (CPP, Root);
3271 function Get_Value (Obj : Root) return int;
3272 pragma Import (CPP, Get_Value);
3274 function Constructor return Root'Class;
3275 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev");
3277 function Constructor (v : Integer) return Root'Class;
3278 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei");
3280 function Constructor (v, w : Integer) return Root'Class;
3281 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii");
3285 On the Ada side the constructor is represented by a function (whose
3286 name is arbitrary) that returns the classwide type corresponding to
3287 the imported C++ class.
3289 In a declaration of an object whose type is a class imported from C++,
3290 either the default C++ constructor is implicitly called by GNAT, or
3291 else the required C++ constructor must be explicitly called in the
3292 expression that initializes the object. For example:
3294 @smallexample @c ada
3296 Obj2 : Root := Constructor;
3297 Obj3 : Root := Constructor (v => 10);
3298 Obj4 : Root := Constructor (30, 40);
3301 The first two declarations are equivalent: in both cases the default C++
3302 constructor is invoked (in the former case the call to the constructor is
3303 implicit, and in the latter case the call is explicit in the object
3304 declaration). @code{Obj3} is initialized by the C++ non-default constructor
3305 that takes an integer argument, and @code{Obj4} is initialized by the
3306 non-default C++ constructor that takes two integers.
3308 Let us derive the imported C++ class in the Ada side. For example:
3310 @smallexample @c ada
3311 type DT is new Root with record
3312 C_Value : Natural := 2009;
3316 In this case the components DT inherited from the C++ side must be
3317 initialized by a C++ constructor, and the additional Ada components
3318 of type DT are initialized by GNAT. The initialization of such an
3319 object is done either by default, or by means of a function returning
3320 an aggregate of type DT, or by means of an extended aggregate.
3322 @smallexample @c ada
3324 Obj6 : DT := Function_Returning_DT (50);
3325 Obj7 : DT := (Constructor (30,40) with (C_Value => 50));
3328 The declaration of @code{Obj5} invokes the default constructors: the
3329 C++ default constructor of the parent type takes care of the initialization
3330 of the components inherited from Root, and GNAT takes care of the default
3331 initialization of the additional Ada components of type DT (that is,
3332 @code{C_Value} is initialized to value 2009). The order of invocation of
3333 the constructors is consistent with the order of elaboration required by
3334 Ada and C++. That is, the constructor of the parent type is always called
3335 before the constructor of the derived type.
3337 Let us now consider a record that has components whose type is imported
3338 from C++. For example:
3340 @smallexample @c ada
3341 type Rec1 is limited record
3342 Data1 : Root := Constructor (10);
3343 Value : Natural := 1000;
3346 type Rec2 (D : Integer := 20) is limited record
3348 Data2 : Root := Constructor (D, 30);
3352 The initialization of an object of type @code{Rec2} will call the
3353 non-default C++ constructors specified for the imported components.
3356 @smallexample @c ada
3360 Using Ada 2005 we can use limited aggregates to initialize an object
3361 invoking C++ constructors that differ from those specified in the type
3362 declarations. For example:
3364 @smallexample @c ada
3365 Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16),
3370 The above declaration uses an Ada 2005 limited aggregate to
3371 initialize @code{Obj9}, and the C++ constructor that has two integer
3372 arguments is invoked to initialize the @code{Data1} component instead
3373 of the constructor specified in the declaration of type @code{Rec1}. In
3374 Ada 2005 the box in the aggregate indicates that unspecified components
3375 are initialized using the expression (if any) available in the component
3376 declaration. That is, in this case discriminant @code{D} is initialized
3377 to value @code{20}, @code{Value} is initialized to value 1000, and the
3378 non-default C++ constructor that handles two integers takes care of
3379 initializing component @code{Data2} with values @code{20,30}.
3381 In Ada 2005 we can use the extended return statement to build the Ada
3382 equivalent to C++ non-default constructors. For example:
3384 @smallexample @c ada
3385 function Constructor (V : Integer) return Rec2 is
3387 return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20),
3390 -- Further actions required for construction of
3391 -- objects of type Rec2
3397 In this example the extended return statement construct is used to
3398 build in place the returned object whose components are initialized
3399 by means of a limited aggregate. Any further action associated with
3400 the constructor can be placed inside the construct.
3402 @node Interfacing with C++ at the Class Level
3403 @subsection Interfacing with C++ at the Class Level
3405 In this section we demonstrate the GNAT features for interfacing with
3406 C++ by means of an example making use of Ada 2005 abstract interface
3407 types. This example consists of a classification of animals; classes
3408 have been used to model our main classification of animals, and
3409 interfaces provide support for the management of secondary
3410 classifications. We first demonstrate a case in which the types and
3411 constructors are defined on the C++ side and imported from the Ada
3412 side, and latter the reverse case.
3414 The root of our derivation will be the @code{Animal} class, with a
3415 single private attribute (the @code{Age} of the animal) and two public
3416 primitives to set and get the value of this attribute.
3421 @b{virtual} void Set_Age (int New_Age);
3422 @b{virtual} int Age ();
3428 Abstract interface types are defined in C++ by means of classes with pure
3429 virtual functions and no data members. In our example we will use two
3430 interfaces that provide support for the common management of @code{Carnivore}
3431 and @code{Domestic} animals:
3434 @b{class} Carnivore @{
3436 @b{virtual} int Number_Of_Teeth () = 0;
3439 @b{class} Domestic @{
3441 @b{virtual void} Set_Owner (char* Name) = 0;
3445 Using these declarations, we can now say that a @code{Dog} is an animal that is
3446 both Carnivore and Domestic, that is:
3449 @b{class} Dog : Animal, Carnivore, Domestic @{
3451 @b{virtual} int Number_Of_Teeth ();
3452 @b{virtual} void Set_Owner (char* Name);
3454 Dog(); // Constructor
3461 In the following examples we will assume that the previous declarations are
3462 located in a file named @code{animals.h}. The following package demonstrates
3463 how to import these C++ declarations from the Ada side:
3465 @smallexample @c ada
3466 with Interfaces.C.Strings; use Interfaces.C.Strings;
3468 type Carnivore is interface;
3469 pragma Convention (C_Plus_Plus, Carnivore);
3470 function Number_Of_Teeth (X : Carnivore)
3471 return Natural is abstract;
3473 type Domestic is interface;
3474 pragma Convention (C_Plus_Plus, Set_Owner);
3476 (X : in out Domestic;
3477 Name : Chars_Ptr) is abstract;
3479 type Animal is tagged record
3482 pragma Import (C_Plus_Plus, Animal);
3484 procedure Set_Age (X : in out Animal; Age : Integer);
3485 pragma Import (C_Plus_Plus, Set_Age);
3487 function Age (X : Animal) return Integer;
3488 pragma Import (C_Plus_Plus, Age);
3490 type Dog is new Animal and Carnivore and Domestic with record
3491 Tooth_Count : Natural;
3492 Owner : String (1 .. 30);
3494 pragma Import (C_Plus_Plus, Dog);
3496 function Number_Of_Teeth (A : Dog) return Integer;
3497 pragma Import (C_Plus_Plus, Number_Of_Teeth);
3499 procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
3500 pragma Import (C_Plus_Plus, Set_Owner);
3502 function New_Dog return Dog'Class;
3503 pragma CPP_Constructor (New_Dog);
3504 pragma Import (CPP, New_Dog, "_ZN3DogC2Ev");
3508 Thanks to the compatibility between GNAT run-time structures and the C++ ABI,
3509 interfacing with these C++ classes is easy. The only requirement is that all
3510 the primitives and components must be declared exactly in the same order in
3513 Regarding the abstract interfaces, we must indicate to the GNAT compiler by
3514 means of a @code{pragma Convention (C_Plus_Plus)}, the convention used to pass
3515 the arguments to the called primitives will be the same as for C++. For the
3516 imported classes we use @code{pragma Import} with convention @code{C_Plus_Plus}
3517 to indicate that they have been defined on the C++ side; this is required
3518 because the dispatch table associated with these tagged types will be built
3519 in the C++ side and therefore will not contain the predefined Ada primitives
3520 which Ada would otherwise expect.
3522 As the reader can see there is no need to indicate the C++ mangled names
3523 associated with each subprogram because it is assumed that all the calls to
3524 these primitives will be dispatching calls. The only exception is the
3525 constructor, which must be registered with the compiler by means of
3526 @code{pragma CPP_Constructor} and needs to provide its associated C++
3527 mangled name because the Ada compiler generates direct calls to it.
3529 With the above packages we can now declare objects of type Dog on the Ada side
3530 and dispatch calls to the corresponding subprograms on the C++ side. We can
3531 also extend the tagged type Dog with further fields and primitives, and
3532 override some of its C++ primitives on the Ada side. For example, here we have
3533 a type derivation defined on the Ada side that inherits all the dispatching
3534 primitives of the ancestor from the C++ side.
3537 @b{with} Animals; @b{use} Animals;
3538 @b{package} Vaccinated_Animals @b{is}
3539 @b{type} Vaccinated_Dog @b{is new} Dog @b{with null record};
3540 @b{function} Vaccination_Expired (A : Vaccinated_Dog) @b{return} Boolean;
3541 @b{end} Vaccinated_Animals;
3544 It is important to note that, because of the ABI compatibility, the programmer
3545 does not need to add any further information to indicate either the object
3546 layout or the dispatch table entry associated with each dispatching operation.
3548 Now let us define all the types and constructors on the Ada side and export
3549 them to C++, using the same hierarchy of our previous example:
3551 @smallexample @c ada
3552 with Interfaces.C.Strings;
3553 use Interfaces.C.Strings;
3555 type Carnivore is interface;
3556 pragma Convention (C_Plus_Plus, Carnivore);
3557 function Number_Of_Teeth (X : Carnivore)
3558 return Natural is abstract;
3560 type Domestic is interface;
3561 pragma Convention (C_Plus_Plus, Set_Owner);
3563 (X : in out Domestic;
3564 Name : Chars_Ptr) is abstract;
3566 type Animal is tagged record
3569 pragma Convention (C_Plus_Plus, Animal);
3571 procedure Set_Age (X : in out Animal; Age : Integer);
3572 pragma Export (C_Plus_Plus, Set_Age);
3574 function Age (X : Animal) return Integer;
3575 pragma Export (C_Plus_Plus, Age);
3577 type Dog is new Animal and Carnivore and Domestic with record
3578 Tooth_Count : Natural;
3579 Owner : String (1 .. 30);
3581 pragma Convention (C_Plus_Plus, Dog);
3583 function Number_Of_Teeth (A : Dog) return Integer;
3584 pragma Export (C_Plus_Plus, Number_Of_Teeth);
3586 procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
3587 pragma Export (C_Plus_Plus, Set_Owner);
3589 function New_Dog return Dog'Class;
3590 pragma Export (C_Plus_Plus, New_Dog);
3594 Compared with our previous example the only difference is the use of
3595 @code{pragma Export} to indicate to the GNAT compiler that the primitives will
3596 be available to C++. Thanks to the ABI compatibility, on the C++ side there is
3597 nothing else to be done; as explained above, the only requirement is that all
3598 the primitives and components are declared in exactly the same order.
3600 For completeness, let us see a brief C++ main program that uses the
3601 declarations available in @code{animals.h} (presented in our first example) to
3602 import and use the declarations from the Ada side, properly initializing and
3603 finalizing the Ada run-time system along the way:
3606 @b{#include} "animals.h"
3607 @b{#include} <iostream>
3608 @b{using namespace} std;
3610 void Check_Carnivore (Carnivore *obj) @{@dots{}@}
3611 void Check_Domestic (Domestic *obj) @{@dots{}@}
3612 void Check_Animal (Animal *obj) @{@dots{}@}
3613 void Check_Dog (Dog *obj) @{@dots{}@}
3616 void adainit (void);
3617 void adafinal (void);
3623 Dog *obj = new_dog(); // Ada constructor
3624 Check_Carnivore (obj); // Check secondary DT
3625 Check_Domestic (obj); // Check secondary DT
3626 Check_Animal (obj); // Check primary DT
3627 Check_Dog (obj); // Check primary DT
3632 adainit (); test(); adafinal ();
3637 @node Comparison between GNAT and C/C++ Compilation Models
3638 @section Comparison between GNAT and C/C++ Compilation Models
3641 The GNAT model of compilation is close to the C and C++ models. You can
3642 think of Ada specs as corresponding to header files in C. As in C, you
3643 don't need to compile specs; they are compiled when they are used. The
3644 Ada @code{with} is similar in effect to the @code{#include} of a C
3647 One notable difference is that, in Ada, you may compile specs separately
3648 to check them for semantic and syntactic accuracy. This is not always
3649 possible with C headers because they are fragments of programs that have
3650 less specific syntactic or semantic rules.
3652 The other major difference is the requirement for running the binder,
3653 which performs two important functions. First, it checks for
3654 consistency. In C or C++, the only defense against assembling
3655 inconsistent programs lies outside the compiler, in a makefile, for
3656 example. The binder satisfies the Ada requirement that it be impossible
3657 to construct an inconsistent program when the compiler is used in normal
3660 @cindex Elaboration order control
3661 The other important function of the binder is to deal with elaboration
3662 issues. There are also elaboration issues in C++ that are handled
3663 automatically. This automatic handling has the advantage of being
3664 simpler to use, but the C++ programmer has no control over elaboration.
3665 Where @code{gnatbind} might complain there was no valid order of
3666 elaboration, a C++ compiler would simply construct a program that
3667 malfunctioned at run time.
3670 @node Comparison between GNAT and Conventional Ada Library Models
3671 @section Comparison between GNAT and Conventional Ada Library Models
3674 This section is intended for Ada programmers who have
3675 used an Ada compiler implementing the traditional Ada library
3676 model, as described in the Ada Reference Manual.
3678 @cindex GNAT library
3679 In GNAT, there is no ``library'' in the normal sense. Instead, the set of
3680 source files themselves acts as the library. Compiling Ada programs does
3681 not generate any centralized information, but rather an object file and
3682 a ALI file, which are of interest only to the binder and linker.
3683 In a traditional system, the compiler reads information not only from
3684 the source file being compiled, but also from the centralized library.
3685 This means that the effect of a compilation depends on what has been
3686 previously compiled. In particular:
3690 When a unit is @code{with}'ed, the unit seen by the compiler corresponds
3691 to the version of the unit most recently compiled into the library.
3694 Inlining is effective only if the necessary body has already been
3695 compiled into the library.
3698 Compiling a unit may obsolete other units in the library.
3702 In GNAT, compiling one unit never affects the compilation of any other
3703 units because the compiler reads only source files. Only changes to source
3704 files can affect the results of a compilation. In particular:
3708 When a unit is @code{with}'ed, the unit seen by the compiler corresponds
3709 to the source version of the unit that is currently accessible to the
3714 Inlining requires the appropriate source files for the package or
3715 subprogram bodies to be available to the compiler. Inlining is always
3716 effective, independent of the order in which units are complied.
3719 Compiling a unit never affects any other compilations. The editing of
3720 sources may cause previous compilations to be out of date if they
3721 depended on the source file being modified.
3725 The most important result of these differences is that order of compilation
3726 is never significant in GNAT. There is no situation in which one is
3727 required to do one compilation before another. What shows up as order of
3728 compilation requirements in the traditional Ada library becomes, in
3729 GNAT, simple source dependencies; in other words, there is only a set
3730 of rules saying what source files must be present when a file is
3734 @node Placement of temporary files
3735 @section Placement of temporary files
3736 @cindex Temporary files (user control over placement)
3739 GNAT creates temporary files in the directory designated by the environment
3740 variable @env{TMPDIR}.
3741 (See the HP @emph{C RTL Reference Manual} on the function @code{getenv()}
3742 for detailed information on how environment variables are resolved.
3743 For most users the easiest way to make use of this feature is to simply
3744 define @env{TMPDIR} as a job level logical name).
3745 For example, if you wish to use a Ramdisk (assuming DECRAM is installed)
3746 for compiler temporary files, then you can include something like the
3747 following command in your @file{LOGIN.COM} file:
3750 $ define/job TMPDIR "/disk$scratchram/000000/temp/"
3754 If @env{TMPDIR} is not defined, then GNAT uses the directory designated by
3755 @env{TMP}; if @env{TMP} is not defined, then GNAT uses the directory
3756 designated by @env{TEMP}.
3757 If none of these environment variables are defined then GNAT uses the
3758 directory designated by the logical name @code{SYS$SCRATCH:}
3759 (by default the user's home directory). If all else fails
3760 GNAT uses the current directory for temporary files.
3763 @c *************************
3764 @node Compiling Using gcc
3765 @chapter Compiling Using @command{gcc}
3768 This chapter discusses how to compile Ada programs using the @command{gcc}
3769 command. It also describes the set of switches
3770 that can be used to control the behavior of the compiler.
3772 * Compiling Programs::
3773 * Switches for gcc::
3774 * Search Paths and the Run-Time Library (RTL)::
3775 * Order of Compilation Issues::
3779 @node Compiling Programs
3780 @section Compiling Programs
3783 The first step in creating an executable program is to compile the units
3784 of the program using the @command{gcc} command. You must compile the
3789 the body file (@file{.adb}) for a library level subprogram or generic
3793 the spec file (@file{.ads}) for a library level package or generic
3794 package that has no body
3797 the body file (@file{.adb}) for a library level package
3798 or generic package that has a body
3803 You need @emph{not} compile the following files
3808 the spec of a library unit which has a body
3815 because they are compiled as part of compiling related units. GNAT
3817 when the corresponding body is compiled, and subunits when the parent is
3820 @cindex cannot generate code
3821 If you attempt to compile any of these files, you will get one of the
3822 following error messages (where @var{fff} is the name of the file you compiled):
3825 cannot generate code for file @var{fff} (package spec)
3826 to check package spec, use -gnatc
3828 cannot generate code for file @var{fff} (missing subunits)
3829 to check parent unit, use -gnatc
3831 cannot generate code for file @var{fff} (subprogram spec)
3832 to check subprogram spec, use -gnatc
3834 cannot generate code for file @var{fff} (subunit)
3835 to check subunit, use -gnatc
3839 As indicated by the above error messages, if you want to submit
3840 one of these files to the compiler to check for correct semantics
3841 without generating code, then use the @option{-gnatc} switch.
3843 The basic command for compiling a file containing an Ada unit is
3846 $ gcc -c @ovar{switches} @file{file name}
3850 where @var{file name} is the name of the Ada file (usually
3852 @file{.ads} for a spec or @file{.adb} for a body).
3855 @option{-c} switch to tell @command{gcc} to compile, but not link, the file.
3857 The result of a successful compilation is an object file, which has the
3858 same name as the source file but an extension of @file{.o} and an Ada
3859 Library Information (ALI) file, which also has the same name as the
3860 source file, but with @file{.ali} as the extension. GNAT creates these
3861 two output files in the current directory, but you may specify a source
3862 file in any directory using an absolute or relative path specification
3863 containing the directory information.
3866 @command{gcc} is actually a driver program that looks at the extensions of
3867 the file arguments and loads the appropriate compiler. For example, the
3868 GNU C compiler is @file{cc1}, and the Ada compiler is @file{gnat1}.
3869 These programs are in directories known to the driver program (in some
3870 configurations via environment variables you set), but need not be in
3871 your path. The @command{gcc} driver also calls the assembler and any other
3872 utilities needed to complete the generation of the required object
3875 It is possible to supply several file names on the same @command{gcc}
3876 command. This causes @command{gcc} to call the appropriate compiler for
3877 each file. For example, the following command lists three separate
3878 files to be compiled:
3881 $ gcc -c x.adb y.adb z.c
3885 calls @code{gnat1} (the Ada compiler) twice to compile @file{x.adb} and
3886 @file{y.adb}, and @code{cc1} (the C compiler) once to compile @file{z.c}.
3887 The compiler generates three object files @file{x.o}, @file{y.o} and
3888 @file{z.o} and the two ALI files @file{x.ali} and @file{y.ali} from the
3889 Ada compilations. Any switches apply to all the files ^listed,^listed.^
3892 @option{-gnat@var{x}} switches, which apply only to Ada compilations.
3895 @node Switches for gcc
3896 @section Switches for @command{gcc}
3899 The @command{gcc} command accepts switches that control the
3900 compilation process. These switches are fully described in this section.
3901 First we briefly list all the switches, in alphabetical order, then we
3902 describe the switches in more detail in functionally grouped sections.
3904 More switches exist for GCC than those documented here, especially
3905 for specific targets. However, their use is not recommended as
3906 they may change code generation in ways that are incompatible with
3907 the Ada run-time library, or can cause inconsistencies between
3911 * Output and Error Message Control::
3912 * Warning Message Control::
3913 * Debugging and Assertion Control::
3914 * Validity Checking::
3917 * Using gcc for Syntax Checking::
3918 * Using gcc for Semantic Checking::
3919 * Compiling Different Versions of Ada::
3920 * Character Set Control::
3921 * File Naming Control::
3922 * Subprogram Inlining Control::
3923 * Auxiliary Output Control::
3924 * Debugging Control::
3925 * Exception Handling Control::
3926 * Units to Sources Mapping Files::
3927 * Integrated Preprocessing::
3928 * Code Generation Control::
3937 @cindex @option{-b} (@command{gcc})
3938 @item -b @var{target}
3939 Compile your program to run on @var{target}, which is the name of a
3940 system configuration. You must have a GNAT cross-compiler built if
3941 @var{target} is not the same as your host system.
3944 @cindex @option{-B} (@command{gcc})
3945 Load compiler executables (for example, @code{gnat1}, the Ada compiler)
3946 from @var{dir} instead of the default location. Only use this switch
3947 when multiple versions of the GNAT compiler are available.
3948 @xref{Directory Options,, Options for Directory Search, gcc, Using the
3949 GNU Compiler Collection (GCC)}, for further details. You would normally
3950 use the @option{-b} or @option{-V} switch instead.
3953 @cindex @option{-c} (@command{gcc})
3954 Compile. Always use this switch when compiling Ada programs.
3956 Note: for some other languages when using @command{gcc}, notably in
3957 the case of C and C++, it is possible to use
3958 use @command{gcc} without a @option{-c} switch to
3959 compile and link in one step. In the case of GNAT, you
3960 cannot use this approach, because the binder must be run
3961 and @command{gcc} cannot be used to run the GNAT binder.
3965 @cindex @option{-fno-inline} (@command{gcc})
3966 Suppresses all back-end inlining, even if other optimization or inlining
3968 This includes suppression of inlining that results
3969 from the use of the pragma @code{Inline_Always}.
3970 Any occurrences of pragma @code{Inline} or @code{Inline_Always}
3971 are ignored, and @option{-gnatn} and @option{-gnatN} have no
3972 effect if this switch is present.
3974 @item -fno-inline-functions
3975 @cindex @option{-fno-inline-functions} (@command{gcc})
3976 Suppresses automatic inlining of simple subprograms, which is enabled
3977 if @option{-O3} is used.
3979 @item -fno-inline-small-functions
3980 @cindex @option{-fno-inline-small-functions} (@command{gcc})
3981 Suppresses automatic inlining of small subprograms, which is enabled
3982 if @option{-O2} is used.
3984 @item -fno-inline-functions-called-once
3985 @cindex @option{-fno-inline-functions-called-once} (@command{gcc})
3986 Suppresses inlining of subprograms local to the unit and called once
3987 from within it, which is enabled if @option{-O1} is used.
3990 @cindex @option{-fno-ivopts} (@command{gcc})
3991 Suppresses high-level loop induction variable optimizations, which are
3992 enabled if @option{-O1} is used. These optimizations are generally
3993 profitable but, for some specific cases of loops with numerous uses
3994 of the iteration variable that follow a common pattern, they may end
3995 up destroying the regularity that could be exploited at a lower level
3996 and thus producing inferior code.
3998 @item -fno-strict-aliasing
3999 @cindex @option{-fno-strict-aliasing} (@command{gcc})
4000 Causes the compiler to avoid assumptions regarding non-aliasing
4001 of objects of different types. See
4002 @ref{Optimization and Strict Aliasing} for details.
4005 @cindex @option{-fstack-check} (@command{gcc})
4006 Activates stack checking.
4007 See @ref{Stack Overflow Checking} for details.
4010 @cindex @option{-fstack-usage} (@command{gcc})
4011 Makes the compiler output stack usage information for the program, on a
4012 per-function basis. See @ref{Static Stack Usage Analysis} for details.
4014 @item -fcallgraph-info@r{[}=su@r{]}
4015 @cindex @option{-fcallgraph-info} (@command{gcc})
4016 Makes the compiler output callgraph information for the program, on a
4017 per-file basis. The information is generated in the VCG format. It can
4018 be decorated with stack-usage per-node information.
4021 @cindex @option{^-g^/DEBUG^} (@command{gcc})
4022 Generate debugging information. This information is stored in the object
4023 file and copied from there to the final executable file by the linker,
4024 where it can be read by the debugger. You must use the
4025 @option{^-g^/DEBUG^} switch if you plan on using the debugger.
4028 @cindex @option{-gnat83} (@command{gcc})
4029 Enforce Ada 83 restrictions.
4032 @cindex @option{-gnat95} (@command{gcc})
4033 Enforce Ada 95 restrictions.
4036 @cindex @option{-gnat05} (@command{gcc})
4037 Allow full Ada 2005 features.
4040 @cindex @option{-gnata} (@command{gcc})
4041 Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
4042 activated. Note that these pragmas can also be controlled using the
4043 configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}.
4044 It also activates pragmas @code{Check}, @code{Precondition}, and
4045 @code{Postcondition}. Note that these pragmas can also be controlled
4046 using the configuration pragma @code{Check_Policy}.
4049 @cindex @option{-gnatA} (@command{gcc})
4050 Avoid processing @file{gnat.adc}. If a @file{gnat.adc} file is present,
4054 @cindex @option{-gnatb} (@command{gcc})
4055 Generate brief messages to @file{stderr} even if verbose mode set.
4058 @cindex @option{-gnatB} (@command{gcc})
4059 Assume no invalid (bad) values except for 'Valid attribute use.
4062 @cindex @option{-gnatc} (@command{gcc})
4063 Check syntax and semantics only (no code generation attempted).
4066 @cindex @option{-gnatd} (@command{gcc})
4067 Specify debug options for the compiler. The string of characters after
4068 the @option{-gnatd} specify the specific debug options. The possible
4069 characters are 0-9, a-z, A-Z, optionally preceded by a dot. See
4070 compiler source file @file{debug.adb} for details of the implemented
4071 debug options. Certain debug options are relevant to applications
4072 programmers, and these are documented at appropriate points in this
4077 @cindex @option{-gnatD[nn]} (@command{gcc})
4080 @item /XDEBUG /LXDEBUG=nnn
4082 Create expanded source files for source level debugging. This switch
4083 also suppress generation of cross-reference information
4084 (see @option{-gnatx}).
4086 @item -gnatec=@var{path}
4087 @cindex @option{-gnatec} (@command{gcc})
4088 Specify a configuration pragma file
4090 (the equal sign is optional)
4092 (@pxref{The Configuration Pragmas Files}).
4094 @item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=@var{value}@r{]}
4095 @cindex @option{-gnateD} (@command{gcc})
4096 Defines a symbol, associated with @var{value}, for preprocessing.
4097 (@pxref{Integrated Preprocessing}).
4100 @cindex @option{-gnatef} (@command{gcc})
4101 Display full source path name in brief error messages.
4104 @cindex @option{-gnateG} (@command{gcc})
4105 Save result of preprocessing in a text file.
4107 @item -gnatem=@var{path}
4108 @cindex @option{-gnatem} (@command{gcc})
4109 Specify a mapping file
4111 (the equal sign is optional)
4113 (@pxref{Units to Sources Mapping Files}).
4115 @item -gnatep=@var{file}
4116 @cindex @option{-gnatep} (@command{gcc})
4117 Specify a preprocessing data file
4119 (the equal sign is optional)
4121 (@pxref{Integrated Preprocessing}).
4124 @cindex @option{-gnatE} (@command{gcc})
4125 Full dynamic elaboration checks.
4128 @cindex @option{-gnatf} (@command{gcc})
4129 Full errors. Multiple errors per line, all undefined references, do not
4130 attempt to suppress cascaded errors.
4133 @cindex @option{-gnatF} (@command{gcc})
4134 Externals names are folded to all uppercase.
4136 @item ^-gnatg^/GNAT_INTERNAL^
4137 @cindex @option{^-gnatg^/GNAT_INTERNAL^} (@command{gcc})
4138 Internal GNAT implementation mode. This should not be used for
4139 applications programs, it is intended only for use by the compiler
4140 and its run-time library. For documentation, see the GNAT sources.
4141 Note that @option{^-gnatg^/GNAT_INTERNAL^} implies
4142 @option{^-gnatwae^/WARNINGS=ALL,ERRORS^} and
4143 @option{^-gnatyg^/STYLE_CHECKS=GNAT^}
4144 so that all standard warnings and all standard style options are turned on.
4145 All warnings and style error messages are treated as errors.
4149 @cindex @option{-gnatG[nn]} (@command{gcc})
4152 @item /EXPAND_SOURCE, /LEXPAND_SOURCE=nnn
4154 List generated expanded code in source form.
4156 @item ^-gnath^/HELP^
4157 @cindex @option{^-gnath^/HELP^} (@command{gcc})
4158 Output usage information. The output is written to @file{stdout}.
4160 @item ^-gnati^/IDENTIFIER_CHARACTER_SET=^@var{c}
4161 @cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@command{gcc})
4162 Identifier character set
4164 (@var{c}=1/2/3/4/8/9/p/f/n/w).
4166 For details of the possible selections for @var{c},
4167 see @ref{Character Set Control}.
4169 @item ^-gnatI^/IGNORE_REP_CLAUSES^
4170 @cindex @option{^-gnatI^IGNORE_REP_CLAUSES^} (@command{gcc})
4171 Ignore representation clauses. When this switch is used, all
4172 representation clauses are treated as comments. This is useful
4173 when initially porting code where you want to ignore rep clause
4174 problems, and also for compiling foreign code (particularly
4178 @cindex @option{-gnatjnn} (@command{gcc})
4179 Reformat error messages to fit on nn character lines
4181 @item -gnatk=@var{n}
4182 @cindex @option{-gnatk} (@command{gcc})
4183 Limit file names to @var{n} (1-999) characters ^(@code{k} = krunch)^^.
4186 @cindex @option{-gnatl} (@command{gcc})
4187 Output full source listing with embedded error messages.
4190 @cindex @option{-gnatL} (@command{gcc})
4191 Used in conjunction with -gnatG or -gnatD to intersperse original
4192 source lines (as comment lines with line numbers) in the expanded
4195 @item -gnatm=@var{n}
4196 @cindex @option{-gnatm} (@command{gcc})
4197 Limit number of detected error or warning messages to @var{n}
4198 where @var{n} is in the range 1..999999. The default setting if
4199 no switch is given is 9999. If the number of warnings reaches this
4200 limit, then a message is output and further warnings are suppressed,
4201 but the compilation is continued. If the number of error messages
4202 reaches this limit, then a message is output and the compilation
4203 is abandoned. The equal sign here is optional. A value of zero
4204 means that no limit applies.
4207 @cindex @option{-gnatn} (@command{gcc})
4208 Activate inlining for subprograms for which
4209 pragma @code{inline} is specified. This inlining is performed
4210 by the GCC back-end.
4213 @cindex @option{-gnatN} (@command{gcc})
4214 Activate front end inlining for subprograms for which
4215 pragma @code{Inline} is specified. This inlining is performed
4216 by the front end and will be visible in the
4217 @option{-gnatG} output.
4219 When using a gcc-based back end (in practice this means using any version
4220 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
4221 @option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
4222 Historically front end inlining was more extensive than the gcc back end
4223 inlining, but that is no longer the case.
4226 @cindex @option{-gnato} (@command{gcc})
4227 Enable numeric overflow checking (which is not normally enabled by
4228 default). Note that division by zero is a separate check that is not
4229 controlled by this switch (division by zero checking is on by default).
4232 @cindex @option{-gnatp} (@command{gcc})
4233 Suppress all checks. See @ref{Run-Time Checks} for details.
4236 @cindex @option{-gnatP} (@command{gcc})
4237 Enable polling. This is required on some systems (notably Windows NT) to
4238 obtain asynchronous abort and asynchronous transfer of control capability.
4239 @xref{Pragma Polling,,, gnat_rm, GNAT Reference Manual}, for full
4243 @cindex @option{-gnatq} (@command{gcc})
4244 Don't quit. Try semantics, even if parse errors.
4247 @cindex @option{-gnatQ} (@command{gcc})
4248 Don't quit. Generate @file{ALI} and tree files even if illegalities.
4251 @cindex @option{-gnatr} (@command{gcc})
4252 Treat pragma Restrictions as Restriction_Warnings.
4254 @item ^-gnatR@r{[}0@r{/}1@r{/}2@r{/}3@r{[}s@r{]]}^/REPRESENTATION_INFO^
4255 @cindex @option{-gnatR} (@command{gcc})
4256 Output representation information for declared types and objects.
4259 @cindex @option{-gnats} (@command{gcc})
4263 @cindex @option{-gnatS} (@command{gcc})
4264 Print package Standard.
4267 @cindex @option{-gnatt} (@command{gcc})
4268 Generate tree output file.
4270 @item ^-gnatT^/TABLE_MULTIPLIER=^@var{nnn}
4271 @cindex @option{^-gnatT^/TABLE_MULTIPLIER^} (@command{gcc})
4272 All compiler tables start at @var{nnn} times usual starting size.
4275 @cindex @option{-gnatu} (@command{gcc})
4276 List units for this compilation.
4279 @cindex @option{-gnatU} (@command{gcc})
4280 Tag all error messages with the unique string ``error:''
4283 @cindex @option{-gnatv} (@command{gcc})
4284 Verbose mode. Full error output with source lines to @file{stdout}.
4287 @cindex @option{-gnatV} (@command{gcc})
4288 Control level of validity checking. See separate section describing
4291 @item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}@r{[},@dots{}@r{]})^
4292 @cindex @option{^-gnatw^/WARNINGS^} (@command{gcc})
4294 ^@var{xxx} is a string of option letters that^the list of options^ denotes
4295 the exact warnings that
4296 are enabled or disabled (@pxref{Warning Message Control}).
4298 @item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e}
4299 @cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@command{gcc})
4300 Wide character encoding method
4302 (@var{e}=n/h/u/s/e/8).
4305 (@var{e}=@code{BRACKETS, NONE, HEX, UPPER, SHIFT_JIS, EUC, UTF8})
4309 @cindex @option{-gnatx} (@command{gcc})
4310 Suppress generation of cross-reference information.
4312 @item ^-gnaty^/STYLE_CHECKS=(option,option@dots{})^
4313 @cindex @option{^-gnaty^/STYLE_CHECKS^} (@command{gcc})
4314 Enable built-in style checks (@pxref{Style Checking}).
4316 @item ^-gnatz^/DISTRIBUTION_STUBS=^@var{m}
4317 @cindex @option{^-gnatz^/DISTRIBUTION_STUBS^} (@command{gcc})
4318 Distribution stub generation and compilation
4320 (@var{m}=r/c for receiver/caller stubs).
4323 (@var{m}=@code{RECEIVER} or @code{CALLER} to specify the type of stubs
4324 to be generated and compiled).
4327 @item ^-I^/SEARCH=^@var{dir}
4328 @cindex @option{^-I^/SEARCH^} (@command{gcc})
4330 Direct GNAT to search the @var{dir} directory for source files needed by
4331 the current compilation
4332 (@pxref{Search Paths and the Run-Time Library (RTL)}).
4334 @item ^-I-^/NOCURRENT_DIRECTORY^
4335 @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gcc})
4337 Except for the source file named in the command line, do not look for source
4338 files in the directory containing the source file named in the command line
4339 (@pxref{Search Paths and the Run-Time Library (RTL)}).
4343 @cindex @option{-mbig-switch} (@command{gcc})
4344 @cindex @code{case} statement (effect of @option{-mbig-switch} option)
4345 This standard gcc switch causes the compiler to use larger offsets in its
4346 jump table representation for @code{case} statements.
4347 This may result in less efficient code, but is sometimes necessary
4348 (for example on HP-UX targets)
4349 @cindex HP-UX and @option{-mbig-switch} option
4350 in order to compile large and/or nested @code{case} statements.
4353 @cindex @option{-o} (@command{gcc})
4354 This switch is used in @command{gcc} to redirect the generated object file
4355 and its associated ALI file. Beware of this switch with GNAT, because it may
4356 cause the object file and ALI file to have different names which in turn
4357 may confuse the binder and the linker.
4361 @cindex @option{-nostdinc} (@command{gcc})
4362 Inhibit the search of the default location for the GNAT Run Time
4363 Library (RTL) source files.
4366 @cindex @option{-nostdlib} (@command{gcc})
4367 Inhibit the search of the default location for the GNAT Run Time
4368 Library (RTL) ALI files.
4372 @cindex @option{-O} (@command{gcc})
4373 @var{n} controls the optimization level.
4377 No optimization, the default setting if no @option{-O} appears
4380 Normal optimization, the default if you specify @option{-O} without
4381 an operand. A good compromise between code quality and compilation
4385 Extensive optimization, may improve execution time, possibly at the cost of
4386 substantially increased compilation time.
4389 Same as @option{-O2}, and also includes inline expansion for small subprograms
4393 Optimize space usage
4397 See also @ref{Optimization Levels}.
4402 @cindex @option{/NOOPTIMIZE} (@code{GNAT COMPILE})
4403 Equivalent to @option{/OPTIMIZE=NONE}.
4404 This is the default behavior in the absence of an @option{/OPTIMIZE}
4407 @item /OPTIMIZE@r{[}=(keyword@r{[},@dots{}@r{]})@r{]}
4408 @cindex @option{/OPTIMIZE} (@code{GNAT COMPILE})
4409 Selects the level of optimization for your program. The supported
4410 keywords are as follows:
4413 Perform most optimizations, including those that
4415 This is the default if the @option{/OPTIMIZE} qualifier is supplied
4416 without keyword options.
4419 Do not do any optimizations. Same as @code{/NOOPTIMIZE}.
4422 Perform some optimizations, but omit ones that are costly.
4425 Same as @code{SOME}.
4428 Full optimization as in @option{/OPTIMIZE=ALL}, and also attempts
4429 automatic inlining of small subprograms within a unit
4432 Try to unroll loops. This keyword may be specified together with
4433 any keyword above other than @code{NONE}. Loop unrolling
4434 usually, but not always, improves the performance of programs.
4437 Optimize space usage
4441 See also @ref{Optimization Levels}.
4445 @item -pass-exit-codes
4446 @cindex @option{-pass-exit-codes} (@command{gcc})
4447 Catch exit codes from the compiler and use the most meaningful as
4451 @item --RTS=@var{rts-path}
4452 @cindex @option{--RTS} (@command{gcc})
4453 Specifies the default location of the runtime library. Same meaning as the
4454 equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
4457 @cindex @option{^-S^/ASM^} (@command{gcc})
4458 ^Used in place of @option{-c} to^Used to^
4459 cause the assembler source file to be
4460 generated, using @file{^.s^.S^} as the extension,
4461 instead of the object file.
4462 This may be useful if you need to examine the generated assembly code.
4464 @item ^-fverbose-asm^/VERBOSE_ASM^
4465 @cindex @option{^-fverbose-asm^/VERBOSE_ASM^} (@command{gcc})
4466 ^Used in conjunction with @option{-S}^Used in place of @option{/ASM}^
4467 to cause the generated assembly code file to be annotated with variable
4468 names, making it significantly easier to follow.
4471 @cindex @option{^-v^/VERBOSE^} (@command{gcc})
4472 Show commands generated by the @command{gcc} driver. Normally used only for
4473 debugging purposes or if you need to be sure what version of the
4474 compiler you are executing.
4478 @cindex @option{-V} (@command{gcc})
4479 Execute @var{ver} version of the compiler. This is the @command{gcc}
4480 version, not the GNAT version.
4483 @item ^-w^/NO_BACK_END_WARNINGS^
4484 @cindex @option{-w} (@command{gcc})
4485 Turn off warnings generated by the back end of the compiler. Use of
4486 this switch also causes the default for front end warnings to be set
4487 to suppress (as though @option{-gnatws} had appeared at the start of
4493 @c Combining qualifiers does not work on VMS
4494 You may combine a sequence of GNAT switches into a single switch. For
4495 example, the combined switch
4497 @cindex Combining GNAT switches
4503 is equivalent to specifying the following sequence of switches:
4506 -gnato -gnatf -gnati3
4511 The following restrictions apply to the combination of switches
4516 The switch @option{-gnatc} if combined with other switches must come
4517 first in the string.
4520 The switch @option{-gnats} if combined with other switches must come
4521 first in the string.
4525 @option{^-gnatz^/DISTRIBUTION_STUBS^}, @option{-gnatzc}, and @option{-gnatzr}
4526 may not be combined with any other switches.
4530 Once a ``y'' appears in the string (that is a use of the @option{-gnaty}
4531 switch), then all further characters in the switch are interpreted
4532 as style modifiers (see description of @option{-gnaty}).
4535 Once a ``d'' appears in the string (that is a use of the @option{-gnatd}
4536 switch), then all further characters in the switch are interpreted
4537 as debug flags (see description of @option{-gnatd}).
4540 Once a ``w'' appears in the string (that is a use of the @option{-gnatw}
4541 switch), then all further characters in the switch are interpreted
4542 as warning mode modifiers (see description of @option{-gnatw}).
4545 Once a ``V'' appears in the string (that is a use of the @option{-gnatV}
4546 switch), then all further characters in the switch are interpreted
4547 as validity checking options (see description of @option{-gnatV}).
4551 @node Output and Error Message Control
4552 @subsection Output and Error Message Control
4556 The standard default format for error messages is called ``brief format''.
4557 Brief format messages are written to @file{stderr} (the standard error
4558 file) and have the following form:
4561 e.adb:3:04: Incorrect spelling of keyword "function"
4562 e.adb:4:20: ";" should be "is"
4566 The first integer after the file name is the line number in the file,
4567 and the second integer is the column number within the line.
4569 @code{GPS} can parse the error messages
4570 and point to the referenced character.
4572 The following switches provide control over the error message
4578 @cindex @option{-gnatv} (@command{gcc})
4581 The v stands for verbose.
4583 The effect of this setting is to write long-format error
4584 messages to @file{stdout} (the standard output file.
4585 The same program compiled with the
4586 @option{-gnatv} switch would generate:
4590 3. funcion X (Q : Integer)
4592 >>> Incorrect spelling of keyword "function"
4595 >>> ";" should be "is"
4600 The vertical bar indicates the location of the error, and the @samp{>>>}
4601 prefix can be used to search for error messages. When this switch is
4602 used the only source lines output are those with errors.
4605 @cindex @option{-gnatl} (@command{gcc})
4607 The @code{l} stands for list.
4609 This switch causes a full listing of
4610 the file to be generated. In the case where a body is
4611 compiled, the corresponding spec is also listed, along
4612 with any subunits. Typical output from compiling a package
4613 body @file{p.adb} might look like:
4615 @smallexample @c ada
4619 1. package body p is
4621 3. procedure a is separate;
4632 2. pragma Elaborate_Body
4656 When you specify the @option{-gnatv} or @option{-gnatl} switches and
4657 standard output is redirected, a brief summary is written to
4658 @file{stderr} (standard error) giving the number of error messages and
4659 warning messages generated.
4661 @item -^gnatl^OUTPUT_FILE^=file
4662 @cindex @option{^-gnatl^OUTPUT_FILE^=fname} (@command{gcc})
4663 This has the same effect as @option{-gnatl} except that the output is
4664 written to a file instead of to standard output. If the given name
4665 @file{fname} does not start with a period, then it is the full name
4666 of the file to be written. If @file{fname} is an extension, it is
4667 appended to the name of the file being compiled. For example, if
4668 file @file{xyz.adb} is compiled with @option{^-gnatl^OUTPUT_FILE^=.lst},
4669 then the output is written to file ^xyz.adb.lst^xyz.adb_lst^.
4672 @cindex @option{-gnatU} (@command{gcc})
4673 This switch forces all error messages to be preceded by the unique
4674 string ``error:''. This means that error messages take a few more
4675 characters in space, but allows easy searching for and identification
4679 @cindex @option{-gnatb} (@command{gcc})
4681 The @code{b} stands for brief.
4683 This switch causes GNAT to generate the
4684 brief format error messages to @file{stderr} (the standard error
4685 file) as well as the verbose
4686 format message or full listing (which as usual is written to
4687 @file{stdout} (the standard output file).
4689 @item -gnatm=@var{n}
4690 @cindex @option{-gnatm} (@command{gcc})
4692 The @code{m} stands for maximum.
4694 @var{n} is a decimal integer in the
4695 range of 1 to 999999 and limits the number of error or warning
4696 messages to be generated. For example, using
4697 @option{-gnatm2} might yield
4700 e.adb:3:04: Incorrect spelling of keyword "function"
4701 e.adb:5:35: missing ".."
4702 fatal error: maximum number of errors detected
4703 compilation abandoned
4707 The default setting if
4708 no switch is given is 9999. If the number of warnings reaches this
4709 limit, then a message is output and further warnings are suppressed,
4710 but the compilation is continued. If the number of error messages
4711 reaches this limit, then a message is output and the compilation
4712 is abandoned. A value of zero means that no limit applies.
4715 Note that the equal sign is optional, so the switches
4716 @option{-gnatm2} and @option{-gnatm=2} are equivalent.
4719 @cindex @option{-gnatf} (@command{gcc})
4720 @cindex Error messages, suppressing
4722 The @code{f} stands for full.
4724 Normally, the compiler suppresses error messages that are likely to be
4725 redundant. This switch causes all error
4726 messages to be generated. In particular, in the case of
4727 references to undefined variables. If a given variable is referenced
4728 several times, the normal format of messages is
4730 e.adb:7:07: "V" is undefined (more references follow)
4734 where the parenthetical comment warns that there are additional
4735 references to the variable @code{V}. Compiling the same program with the
4736 @option{-gnatf} switch yields
4739 e.adb:7:07: "V" is undefined
4740 e.adb:8:07: "V" is undefined
4741 e.adb:8:12: "V" is undefined
4742 e.adb:8:16: "V" is undefined
4743 e.adb:9:07: "V" is undefined
4744 e.adb:9:12: "V" is undefined
4748 The @option{-gnatf} switch also generates additional information for
4749 some error messages. Some examples are:
4753 Full details on entities not available in high integrity mode
4755 Details on possibly non-portable unchecked conversion
4757 List possible interpretations for ambiguous calls
4759 Additional details on incorrect parameters
4763 @cindex @option{-gnatjnn} (@command{gcc})
4764 In normal operation mode (or if @option{-gnatj0} is used, then error messages
4765 with continuation lines are treated as though the continuation lines were
4766 separate messages (and so a warning with two continuation lines counts as
4767 three warnings, and is listed as three separate messages).
4769 If the @option{-gnatjnn} switch is used with a positive value for nn, then
4770 messages are output in a different manner. A message and all its continuation
4771 lines are treated as a unit, and count as only one warning or message in the
4772 statistics totals. Furthermore, the message is reformatted so that no line
4773 is longer than nn characters.
4776 @cindex @option{-gnatq} (@command{gcc})
4778 The @code{q} stands for quit (really ``don't quit'').
4780 In normal operation mode, the compiler first parses the program and
4781 determines if there are any syntax errors. If there are, appropriate
4782 error messages are generated and compilation is immediately terminated.
4784 GNAT to continue with semantic analysis even if syntax errors have been
4785 found. This may enable the detection of more errors in a single run. On
4786 the other hand, the semantic analyzer is more likely to encounter some
4787 internal fatal error when given a syntactically invalid tree.
4790 @cindex @option{-gnatQ} (@command{gcc})
4791 In normal operation mode, the @file{ALI} file is not generated if any
4792 illegalities are detected in the program. The use of @option{-gnatQ} forces
4793 generation of the @file{ALI} file. This file is marked as being in
4794 error, so it cannot be used for binding purposes, but it does contain
4795 reasonably complete cross-reference information, and thus may be useful
4796 for use by tools (e.g., semantic browsing tools or integrated development
4797 environments) that are driven from the @file{ALI} file. This switch
4798 implies @option{-gnatq}, since the semantic phase must be run to get a
4799 meaningful ALI file.
4801 In addition, if @option{-gnatt} is also specified, then the tree file is
4802 generated even if there are illegalities. It may be useful in this case
4803 to also specify @option{-gnatq} to ensure that full semantic processing
4804 occurs. The resulting tree file can be processed by ASIS, for the purpose
4805 of providing partial information about illegal units, but if the error
4806 causes the tree to be badly malformed, then ASIS may crash during the
4809 When @option{-gnatQ} is used and the generated @file{ALI} file is marked as
4810 being in error, @command{gnatmake} will attempt to recompile the source when it
4811 finds such an @file{ALI} file, including with switch @option{-gnatc}.
4813 Note that @option{-gnatQ} has no effect if @option{-gnats} is specified,
4814 since ALI files are never generated if @option{-gnats} is set.
4818 @node Warning Message Control
4819 @subsection Warning Message Control
4820 @cindex Warning messages
4822 In addition to error messages, which correspond to illegalities as defined
4823 in the Ada Reference Manual, the compiler detects two kinds of warning
4826 First, the compiler considers some constructs suspicious and generates a
4827 warning message to alert you to a possible error. Second, if the
4828 compiler detects a situation that is sure to raise an exception at
4829 run time, it generates a warning message. The following shows an example
4830 of warning messages:
4832 e.adb:4:24: warning: creation of object may raise Storage_Error
4833 e.adb:10:17: warning: static value out of range
4834 e.adb:10:17: warning: "Constraint_Error" will be raised at run time
4838 GNAT considers a large number of situations as appropriate
4839 for the generation of warning messages. As always, warnings are not
4840 definite indications of errors. For example, if you do an out-of-range
4841 assignment with the deliberate intention of raising a
4842 @code{Constraint_Error} exception, then the warning that may be
4843 issued does not indicate an error. Some of the situations for which GNAT
4844 issues warnings (at least some of the time) are given in the following
4845 list. This list is not complete, and new warnings are often added to
4846 subsequent versions of GNAT. The list is intended to give a general idea
4847 of the kinds of warnings that are generated.
4851 Possible infinitely recursive calls
4854 Out-of-range values being assigned
4857 Possible order of elaboration problems
4860 Assertions (pragma Assert) that are sure to fail
4866 Address clauses with possibly unaligned values, or where an attempt is
4867 made to overlay a smaller variable with a larger one.
4870 Fixed-point type declarations with a null range
4873 Direct_IO or Sequential_IO instantiated with a type that has access values
4876 Variables that are never assigned a value
4879 Variables that are referenced before being initialized
4882 Task entries with no corresponding @code{accept} statement
4885 Duplicate accepts for the same task entry in a @code{select}
4888 Objects that take too much storage
4891 Unchecked conversion between types of differing sizes
4894 Missing @code{return} statement along some execution path in a function
4897 Incorrect (unrecognized) pragmas
4900 Incorrect external names
4903 Allocation from empty storage pool
4906 Potentially blocking operation in protected type
4909 Suspicious parenthesization of expressions
4912 Mismatching bounds in an aggregate
4915 Attempt to return local value by reference
4918 Premature instantiation of a generic body
4921 Attempt to pack aliased components
4924 Out of bounds array subscripts
4927 Wrong length on string assignment
4930 Violations of style rules if style checking is enabled
4933 Unused @code{with} clauses
4936 @code{Bit_Order} usage that does not have any effect
4939 @code{Standard.Duration} used to resolve universal fixed expression
4942 Dereference of possibly null value
4945 Declaration that is likely to cause storage error
4948 Internal GNAT unit @code{with}'ed by application unit
4951 Values known to be out of range at compile time
4954 Unreferenced labels and variables
4957 Address overlays that could clobber memory
4960 Unexpected initialization when address clause present
4963 Bad alignment for address clause
4966 Useless type conversions
4969 Redundant assignment statements and other redundant constructs
4972 Useless exception handlers
4975 Accidental hiding of name by child unit
4978 Access before elaboration detected at compile time
4981 A range in a @code{for} loop that is known to be null or might be null
4986 The following section lists compiler switches that are available
4987 to control the handling of warning messages. It is also possible
4988 to exercise much finer control over what warnings are issued and
4989 suppressed using the GNAT pragma Warnings, @xref{Pragma Warnings,,,
4990 gnat_rm, GNAT Reference manual}.
4995 @emph{Activate all optional errors.}
4996 @cindex @option{-gnatwa} (@command{gcc})
4997 This switch activates most optional warning messages, see remaining list
4998 in this section for details on optional warning messages that can be
4999 individually controlled. The warnings that are not turned on by this
5001 @option{-gnatwd} (implicit dereferencing),
5002 @option{-gnatwh} (hiding),
5003 @option{-gnatwl} (elaboration warnings),
5004 @option{-gnatw.o} (warn on values set by out parameters ignored)
5005 and @option{-gnatwt} (tracking of deleted conditional code).
5006 All other optional warnings are turned on.
5009 @emph{Suppress all optional errors.}
5010 @cindex @option{-gnatwA} (@command{gcc})
5011 This switch suppresses all optional warning messages, see remaining list
5012 in this section for details on optional warning messages that can be
5013 individually controlled.
5016 @emph{Activate warnings on failing assertions.}
5017 @cindex @option{-gnatw.a} (@command{gcc})
5018 @cindex Assert failures
5019 This switch activates warnings for assertions where the compiler can tell at
5020 compile time that the assertion will fail. Note that this warning is given
5021 even if assertions are disabled. The default is that such warnings are
5025 @emph{Suppress warnings on failing assertions.}
5026 @cindex @option{-gnatw.A} (@command{gcc})
5027 @cindex Assert failures
5028 This switch suppresses warnings for assertions where the compiler can tell at
5029 compile time that the assertion will fail.
5032 @emph{Activate warnings on bad fixed values.}
5033 @cindex @option{-gnatwb} (@command{gcc})
5034 @cindex Bad fixed values
5035 @cindex Fixed-point Small value
5037 This switch activates warnings for static fixed-point expressions whose
5038 value is not an exact multiple of Small. Such values are implementation
5039 dependent, since an implementation is free to choose either of the multiples
5040 that surround the value. GNAT always chooses the closer one, but this is not
5041 required behavior, and it is better to specify a value that is an exact
5042 multiple, ensuring predictable execution. The default is that such warnings
5046 @emph{Suppress warnings on bad fixed values.}
5047 @cindex @option{-gnatwB} (@command{gcc})
5048 This switch suppresses warnings for static fixed-point expressions whose
5049 value is not an exact multiple of Small.
5052 @emph{Activate warnings on biased representation.}
5053 @cindex @option{-gnatw.b} (@command{gcc})
5054 @cindex Biased representation
5055 This switch activates warnings when a size clause, value size clause, component
5056 clause, or component size clause forces the use of biased representation for an
5057 integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
5058 to represent 10/11). The default is that such warnings are generated.
5061 @emph{Suppress warnings on biased representation.}
5062 @cindex @option{-gnatwB} (@command{gcc})
5063 This switch suppresses warnings for representation clauses that force the use
5064 of biased representation.
5067 @emph{Activate warnings on conditionals.}
5068 @cindex @option{-gnatwc} (@command{gcc})
5069 @cindex Conditionals, constant
5070 This switch activates warnings for conditional expressions used in
5071 tests that are known to be True or False at compile time. The default
5072 is that such warnings are not generated.
5073 Note that this warning does
5074 not get issued for the use of boolean variables or constants whose
5075 values are known at compile time, since this is a standard technique
5076 for conditional compilation in Ada, and this would generate too many
5077 false positive warnings.
5079 This warning option also activates a special test for comparisons using
5080 the operators ``>='' and`` <=''.
5081 If the compiler can tell that only the equality condition is possible,
5082 then it will warn that the ``>'' or ``<'' part of the test
5083 is useless and that the operator could be replaced by ``=''.
5084 An example would be comparing a @code{Natural} variable <= 0.
5086 This warning option also generates warnings if
5087 one or both tests is optimized away in a membership test for integer
5088 values if the result can be determined at compile time. Range tests on
5089 enumeration types are not included, since it is common for such tests
5090 to include an end point.
5092 This warning can also be turned on using @option{-gnatwa}.
5095 @emph{Suppress warnings on conditionals.}
5096 @cindex @option{-gnatwC} (@command{gcc})
5097 This switch suppresses warnings for conditional expressions used in
5098 tests that are known to be True or False at compile time.
5101 @emph{Activate warnings on missing component clauses.}
5102 @cindex @option{-gnatw.c} (@command{gcc})
5103 @cindex Component clause, missing
5104 This switch activates warnings for record components where a record
5105 representation clause is present and has component clauses for the
5106 majority, but not all, of the components. A warning is given for each
5107 component for which no component clause is present.
5109 This warning can also be turned on using @option{-gnatwa}.
5112 @emph{Suppress warnings on missing component clauses.}
5113 @cindex @option{-gnatwC} (@command{gcc})
5114 This switch suppresses warnings for record components that are
5115 missing a component clause in the situation described above.
5118 @emph{Activate warnings on implicit dereferencing.}
5119 @cindex @option{-gnatwd} (@command{gcc})
5120 If this switch is set, then the use of a prefix of an access type
5121 in an indexed component, slice, or selected component without an
5122 explicit @code{.all} will generate a warning. With this warning
5123 enabled, access checks occur only at points where an explicit
5124 @code{.all} appears in the source code (assuming no warnings are
5125 generated as a result of this switch). The default is that such
5126 warnings are not generated.
5127 Note that @option{-gnatwa} does not affect the setting of
5128 this warning option.
5131 @emph{Suppress warnings on implicit dereferencing.}
5132 @cindex @option{-gnatwD} (@command{gcc})
5133 @cindex Implicit dereferencing
5134 @cindex Dereferencing, implicit
5135 This switch suppresses warnings for implicit dereferences in
5136 indexed components, slices, and selected components.
5139 @emph{Treat warnings as errors.}
5140 @cindex @option{-gnatwe} (@command{gcc})
5141 @cindex Warnings, treat as error
5142 This switch causes warning messages to be treated as errors.
5143 The warning string still appears, but the warning messages are counted
5144 as errors, and prevent the generation of an object file.
5147 @emph{Activate every optional warning}
5148 @cindex @option{-gnatw.e} (@command{gcc})
5149 @cindex Warnings, activate every optional warning
5150 This switch activates all optional warnings, including those which
5151 are not activated by @code{-gnatwa}.
5154 @emph{Activate warnings on unreferenced formals.}
5155 @cindex @option{-gnatwf} (@command{gcc})
5156 @cindex Formals, unreferenced
5157 This switch causes a warning to be generated if a formal parameter
5158 is not referenced in the body of the subprogram. This warning can
5159 also be turned on using @option{-gnatwa} or @option{-gnatwu}. The
5160 default is that these warnings are not generated.
5163 @emph{Suppress warnings on unreferenced formals.}
5164 @cindex @option{-gnatwF} (@command{gcc})
5165 This switch suppresses warnings for unreferenced formal
5166 parameters. Note that the
5167 combination @option{-gnatwu} followed by @option{-gnatwF} has the
5168 effect of warning on unreferenced entities other than subprogram
5172 @emph{Activate warnings on unrecognized pragmas.}
5173 @cindex @option{-gnatwg} (@command{gcc})
5174 @cindex Pragmas, unrecognized
5175 This switch causes a warning to be generated if an unrecognized
5176 pragma is encountered. Apart from issuing this warning, the
5177 pragma is ignored and has no effect. This warning can
5178 also be turned on using @option{-gnatwa}. The default
5179 is that such warnings are issued (satisfying the Ada Reference
5180 Manual requirement that such warnings appear).
5183 @emph{Suppress warnings on unrecognized pragmas.}
5184 @cindex @option{-gnatwG} (@command{gcc})
5185 This switch suppresses warnings for unrecognized pragmas.
5188 @emph{Activate warnings on hiding.}
5189 @cindex @option{-gnatwh} (@command{gcc})
5190 @cindex Hiding of Declarations
5191 This switch activates warnings on hiding declarations.
5192 A declaration is considered hiding
5193 if it is for a non-overloadable entity, and it declares an entity with the
5194 same name as some other entity that is directly or use-visible. The default
5195 is that such warnings are not generated.
5196 Note that @option{-gnatwa} does not affect the setting of this warning option.
5199 @emph{Suppress warnings on hiding.}
5200 @cindex @option{-gnatwH} (@command{gcc})
5201 This switch suppresses warnings on hiding declarations.
5204 @emph{Activate warnings on implementation units.}
5205 @cindex @option{-gnatwi} (@command{gcc})
5206 This switch activates warnings for a @code{with} of an internal GNAT
5207 implementation unit, defined as any unit from the @code{Ada},
5208 @code{Interfaces}, @code{GNAT},
5209 ^^@code{DEC},^ or @code{System}
5210 hierarchies that is not
5211 documented in either the Ada Reference Manual or the GNAT
5212 Programmer's Reference Manual. Such units are intended only
5213 for internal implementation purposes and should not be @code{with}'ed
5214 by user programs. The default is that such warnings are generated
5215 This warning can also be turned on using @option{-gnatwa}.
5218 @emph{Disable warnings on implementation units.}
5219 @cindex @option{-gnatwI} (@command{gcc})
5220 This switch disables warnings for a @code{with} of an internal GNAT
5221 implementation unit.
5224 @emph{Activate warnings on obsolescent features (Annex J).}
5225 @cindex @option{-gnatwj} (@command{gcc})
5226 @cindex Features, obsolescent
5227 @cindex Obsolescent features
5228 If this warning option is activated, then warnings are generated for
5229 calls to subprograms marked with @code{pragma Obsolescent} and
5230 for use of features in Annex J of the Ada Reference Manual. In the
5231 case of Annex J, not all features are flagged. In particular use
5232 of the renamed packages (like @code{Text_IO}) and use of package
5233 @code{ASCII} are not flagged, since these are very common and
5234 would generate many annoying positive warnings. The default is that
5235 such warnings are not generated. This warning is also turned on by
5236 the use of @option{-gnatwa}.
5238 In addition to the above cases, warnings are also generated for
5239 GNAT features that have been provided in past versions but which
5240 have been superseded (typically by features in the new Ada standard).
5241 For example, @code{pragma Ravenscar} will be flagged since its
5242 function is replaced by @code{pragma Profile(Ravenscar)}.
5244 Note that this warning option functions differently from the
5245 restriction @code{No_Obsolescent_Features} in two respects.
5246 First, the restriction applies only to annex J features.
5247 Second, the restriction does flag uses of package @code{ASCII}.
5250 @emph{Suppress warnings on obsolescent features (Annex J).}
5251 @cindex @option{-gnatwJ} (@command{gcc})
5252 This switch disables warnings on use of obsolescent features.
5255 @emph{Activate warnings on variables that could be constants.}
5256 @cindex @option{-gnatwk} (@command{gcc})
5257 This switch activates warnings for variables that are initialized but
5258 never modified, and then could be declared constants. The default is that
5259 such warnings are not given.
5260 This warning can also be turned on using @option{-gnatwa}.
5263 @emph{Suppress warnings on variables that could be constants.}
5264 @cindex @option{-gnatwK} (@command{gcc})
5265 This switch disables warnings on variables that could be declared constants.
5268 @emph{Activate warnings for elaboration pragmas.}
5269 @cindex @option{-gnatwl} (@command{gcc})
5270 @cindex Elaboration, warnings
5271 This switch activates warnings on missing
5272 @code{Elaborate_All} and @code{Elaborate} pragmas.
5273 See the section in this guide on elaboration checking for details on
5274 when such pragmas should be used. In dynamic elaboration mode, this switch
5275 generations warnings about the need to add elaboration pragmas. Note however,
5276 that if you blindly follow these warnings, and add @code{Elaborate_All}
5277 warnings wherever they are recommended, you basically end up with the
5278 equivalent of the static elaboration model, which may not be what you want for
5279 legacy code for which the static model does not work.
5281 For the static model, the messages generated are labeled "info:" (for
5282 information messages). They are not warnings to add elaboration pragmas,
5283 merely informational messages showing what implicit elaboration pragmas
5284 have been added, for use in analyzing elaboration circularity problems.
5286 Warnings are also generated if you
5287 are using the static mode of elaboration, and a @code{pragma Elaborate}
5288 is encountered. The default is that such warnings
5290 This warning is not automatically turned on by the use of @option{-gnatwa}.
5293 @emph{Suppress warnings for elaboration pragmas.}
5294 @cindex @option{-gnatwL} (@command{gcc})
5295 This switch suppresses warnings on missing Elaborate and Elaborate_All pragmas.
5296 See the section in this guide on elaboration checking for details on
5297 when such pragmas should be used.
5300 @emph{Activate warnings on modified but unreferenced variables.}
5301 @cindex @option{-gnatwm} (@command{gcc})
5302 This switch activates warnings for variables that are assigned (using
5303 an initialization value or with one or more assignment statements) but
5304 whose value is never read. The warning is suppressed for volatile
5305 variables and also for variables that are renamings of other variables
5306 or for which an address clause is given.
5307 This warning can also be turned on using @option{-gnatwa}.
5308 The default is that these warnings are not given.
5311 @emph{Disable warnings on modified but unreferenced variables.}
5312 @cindex @option{-gnatwM} (@command{gcc})
5313 This switch disables warnings for variables that are assigned or
5314 initialized, but never read.
5317 @emph{Set normal warnings mode.}
5318 @cindex @option{-gnatwn} (@command{gcc})
5319 This switch sets normal warning mode, in which enabled warnings are
5320 issued and treated as warnings rather than errors. This is the default
5321 mode. the switch @option{-gnatwn} can be used to cancel the effect of
5322 an explicit @option{-gnatws} or
5323 @option{-gnatwe}. It also cancels the effect of the
5324 implicit @option{-gnatwe} that is activated by the
5325 use of @option{-gnatg}.
5328 @emph{Activate warnings on address clause overlays.}
5329 @cindex @option{-gnatwo} (@command{gcc})
5330 @cindex Address Clauses, warnings
5331 This switch activates warnings for possibly unintended initialization
5332 effects of defining address clauses that cause one variable to overlap
5333 another. The default is that such warnings are generated.
5334 This warning can also be turned on using @option{-gnatwa}.
5337 @emph{Suppress warnings on address clause overlays.}
5338 @cindex @option{-gnatwO} (@command{gcc})
5339 This switch suppresses warnings on possibly unintended initialization
5340 effects of defining address clauses that cause one variable to overlap
5344 @emph{Activate warnings on modified but unreferenced out parameters.}
5345 @cindex @option{-gnatw.o} (@command{gcc})
5346 This switch activates warnings for variables that are modified by using
5347 them as actuals for a call to a procedure with an out mode formal, where
5348 the resulting assigned value is never read. It is applicable in the case
5349 where there is more than one out mode formal. If there is only one out
5350 mode formal, the warning is issued by default (controlled by -gnatwu).
5351 The warning is suppressed for volatile
5352 variables and also for variables that are renamings of other variables
5353 or for which an address clause is given.
5354 The default is that these warnings are not given. Note that this warning
5355 is not included in -gnatwa, it must be activated explicitly.
5358 @emph{Disable warnings on modified but unreferenced out parameters.}
5359 @cindex @option{-gnatw.O} (@command{gcc})
5360 This switch suppresses warnings for variables that are modified by using
5361 them as actuals for a call to a procedure with an out mode formal, where
5362 the resulting assigned value is never read.
5365 @emph{Activate warnings on ineffective pragma Inlines.}
5366 @cindex @option{-gnatwp} (@command{gcc})
5367 @cindex Inlining, warnings
5368 This switch activates warnings for failure of front end inlining
5369 (activated by @option{-gnatN}) to inline a particular call. There are
5370 many reasons for not being able to inline a call, including most
5371 commonly that the call is too complex to inline. The default is
5372 that such warnings are not given.
5373 This warning can also be turned on using @option{-gnatwa}.
5374 Warnings on ineffective inlining by the gcc back-end can be activated
5375 separately, using the gcc switch -Winline.
5378 @emph{Suppress warnings on ineffective pragma Inlines.}
5379 @cindex @option{-gnatwP} (@command{gcc})
5380 This switch suppresses warnings on ineffective pragma Inlines. If the
5381 inlining mechanism cannot inline a call, it will simply ignore the
5385 @emph{Activate warnings on parameter ordering.}
5386 @cindex @option{-gnatw.p} (@command{gcc})
5387 @cindex Parameter order, warnings
5388 This switch activates warnings for cases of suspicious parameter
5389 ordering when the list of arguments are all simple identifiers that
5390 match the names of the formals, but are in a different order. The
5391 warning is suppressed if any use of named parameter notation is used,
5392 so this is the appropriate way to suppress a false positive (and
5393 serves to emphasize that the "misordering" is deliberate). The
5395 that such warnings are not given.
5396 This warning can also be turned on using @option{-gnatwa}.
5399 @emph{Suppress warnings on parameter ordering.}
5400 @cindex @option{-gnatw.P} (@command{gcc})
5401 This switch suppresses warnings on cases of suspicious parameter
5405 @emph{Activate warnings on questionable missing parentheses.}
5406 @cindex @option{-gnatwq} (@command{gcc})
5407 @cindex Parentheses, warnings
5408 This switch activates warnings for cases where parentheses are not used and
5409 the result is potential ambiguity from a readers point of view. For example
5410 (not a > b) when a and b are modular means ((not a) > b) and very likely the
5411 programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
5412 quite likely ((-x) mod 5) was intended. In such situations it seems best to
5413 follow the rule of always parenthesizing to make the association clear, and
5414 this warning switch warns if such parentheses are not present. The default
5415 is that these warnings are given.
5416 This warning can also be turned on using @option{-gnatwa}.
5419 @emph{Suppress warnings on questionable missing parentheses.}
5420 @cindex @option{-gnatwQ} (@command{gcc})
5421 This switch suppresses warnings for cases where the association is not
5422 clear and the use of parentheses is preferred.
5425 @emph{Activate warnings on redundant constructs.}
5426 @cindex @option{-gnatwr} (@command{gcc})
5427 This switch activates warnings for redundant constructs. The following
5428 is the current list of constructs regarded as redundant:
5432 Assignment of an item to itself.
5434 Type conversion that converts an expression to its own type.
5436 Use of the attribute @code{Base} where @code{typ'Base} is the same
5439 Use of pragma @code{Pack} when all components are placed by a record
5440 representation clause.
5442 Exception handler containing only a reraise statement (raise with no
5443 operand) which has no effect.
5445 Use of the operator abs on an operand that is known at compile time
5448 Comparison of boolean expressions to an explicit True value.
5451 This warning can also be turned on using @option{-gnatwa}.
5452 The default is that warnings for redundant constructs are not given.
5455 @emph{Suppress warnings on redundant constructs.}
5456 @cindex @option{-gnatwR} (@command{gcc})
5457 This switch suppresses warnings for redundant constructs.
5460 @emph{Suppress all warnings.}
5461 @cindex @option{-gnatws} (@command{gcc})
5462 This switch completely suppresses the
5463 output of all warning messages from the GNAT front end.
5464 Note that it does not suppress warnings from the @command{gcc} back end.
5465 To suppress these back end warnings as well, use the switch @option{-w}
5466 in addition to @option{-gnatws}.
5469 @emph{Activate warnings for tracking of deleted conditional code.}
5470 @cindex @option{-gnatwt} (@command{gcc})
5471 @cindex Deactivated code, warnings
5472 @cindex Deleted code, warnings
5473 This switch activates warnings for tracking of code in conditionals (IF and
5474 CASE statements) that is detected to be dead code which cannot be executed, and
5475 which is removed by the front end. This warning is off by default, and is not
5476 turned on by @option{-gnatwa}, it has to be turned on explicitly. This may be
5477 useful for detecting deactivated code in certified applications.
5480 @emph{Suppress warnings for tracking of deleted conditional code.}
5481 @cindex @option{-gnatwT} (@command{gcc})
5482 This switch suppresses warnings for tracking of deleted conditional code.
5485 @emph{Activate warnings on unused entities.}
5486 @cindex @option{-gnatwu} (@command{gcc})
5487 This switch activates warnings to be generated for entities that
5488 are declared but not referenced, and for units that are @code{with}'ed
5490 referenced. In the case of packages, a warning is also generated if
5491 no entities in the package are referenced. This means that if the package
5492 is referenced but the only references are in @code{use}
5493 clauses or @code{renames}
5494 declarations, a warning is still generated. A warning is also generated
5495 for a generic package that is @code{with}'ed but never instantiated.
5496 In the case where a package or subprogram body is compiled, and there
5497 is a @code{with} on the corresponding spec
5498 that is only referenced in the body,
5499 a warning is also generated, noting that the
5500 @code{with} can be moved to the body. The default is that
5501 such warnings are not generated.
5502 This switch also activates warnings on unreferenced formals
5503 (it includes the effect of @option{-gnatwf}).
5504 This warning can also be turned on using @option{-gnatwa}.
5507 @emph{Suppress warnings on unused entities.}
5508 @cindex @option{-gnatwU} (@command{gcc})
5509 This switch suppresses warnings for unused entities and packages.
5510 It also turns off warnings on unreferenced formals (and thus includes
5511 the effect of @option{-gnatwF}).
5514 @emph{Activate warnings on unassigned variables.}
5515 @cindex @option{-gnatwv} (@command{gcc})
5516 @cindex Unassigned variable warnings
5517 This switch activates warnings for access to variables which
5518 may not be properly initialized. The default is that
5519 such warnings are generated.
5520 This warning can also be turned on using @option{-gnatwa}.
5523 @emph{Suppress warnings on unassigned variables.}
5524 @cindex @option{-gnatwV} (@command{gcc})
5525 This switch suppresses warnings for access to variables which
5526 may not be properly initialized.
5527 For variables of a composite type, the warning can also be suppressed in
5528 Ada 2005 by using a default initialization with a box. For example, if
5529 Table is an array of records whose components are only partially uninitialized,
5530 then the following code:
5532 @smallexample @c ada
5533 Tab : Table := (others => <>);
5536 will suppress warnings on subsequent statements that access components
5540 @emph{Activate warnings on wrong low bound assumption.}
5541 @cindex @option{-gnatww} (@command{gcc})
5542 @cindex String indexing warnings
5543 This switch activates warnings for indexing an unconstrained string parameter
5544 with a literal or S'Length. This is a case where the code is assuming that the
5545 low bound is one, which is in general not true (for example when a slice is
5546 passed). The default is that such warnings are generated.
5547 This warning can also be turned on using @option{-gnatwa}.
5550 @emph{Suppress warnings on wrong low bound assumption.}
5551 @cindex @option{-gnatwW} (@command{gcc})
5552 This switch suppresses warnings for indexing an unconstrained string parameter
5553 with a literal or S'Length. Note that this warning can also be suppressed
5554 in a particular case by adding an
5555 assertion that the lower bound is 1,
5556 as shown in the following example.
5558 @smallexample @c ada
5559 procedure K (S : String) is
5560 pragma Assert (S'First = 1);
5565 @emph{Activate warnings on unnecessary Warnings Off pragmas}
5566 @cindex @option{-gnatw.w} (@command{gcc})
5567 @cindex Warnings Off control
5568 This switch activates warnings for use of @code{pragma Warnings (Off, entity}
5569 where either the pragma is entirely useless (because it suppresses no
5570 warnings), or it could be replaced by @code{pragma Unreferenced} or
5571 @code{pragma Unmodified}.The default is that these warnings are not given.
5572 Note that this warning is not included in -gnatwa, it must be
5573 activated explicitly.
5576 @emph{Suppress warnings on unnecessary Warnings Off pragmas}
5577 @cindex @option{-gnatw.W} (@command{gcc})
5578 This switch suppresses warnings for use of @code{pragma Warnings (Off, entity}.
5581 @emph{Activate warnings on Export/Import pragmas.}
5582 @cindex @option{-gnatwx} (@command{gcc})
5583 @cindex Export/Import pragma warnings
5584 This switch activates warnings on Export/Import pragmas when
5585 the compiler detects a possible conflict between the Ada and
5586 foreign language calling sequences. For example, the use of
5587 default parameters in a convention C procedure is dubious
5588 because the C compiler cannot supply the proper default, so
5589 a warning is issued. The default is that such warnings are
5591 This warning can also be turned on using @option{-gnatwa}.
5594 @emph{Suppress warnings on Export/Import pragmas.}
5595 @cindex @option{-gnatwX} (@command{gcc})
5596 This switch suppresses warnings on Export/Import pragmas.
5597 The sense of this is that you are telling the compiler that
5598 you know what you are doing in writing the pragma, and it
5599 should not complain at you.
5602 @emph{Activate warnings for No_Exception_Propagation mode.}
5603 @cindex @option{-gnatwm} (@command{gcc})
5604 This switch activates warnings for exception usage when pragma Restrictions
5605 (No_Exception_Propagation) is in effect. Warnings are given for implicit or
5606 explicit exception raises which are not covered by a local handler, and for
5607 exception handlers which do not cover a local raise. The default is that these
5608 warnings are not given.
5611 @emph{Disable warnings for No_Exception_Propagation mode.}
5612 This switch disables warnings for exception usage when pragma Restrictions
5613 (No_Exception_Propagation) is in effect.
5616 @emph{Activate warnings for Ada 2005 compatibility issues.}
5617 @cindex @option{-gnatwy} (@command{gcc})
5618 @cindex Ada 2005 compatibility issues warnings
5619 For the most part Ada 2005 is upwards compatible with Ada 95,
5620 but there are some exceptions (for example the fact that
5621 @code{interface} is now a reserved word in Ada 2005). This
5622 switch activates several warnings to help in identifying
5623 and correcting such incompatibilities. The default is that
5624 these warnings are generated. Note that at one point Ada 2005
5625 was called Ada 0Y, hence the choice of character.
5626 This warning can also be turned on using @option{-gnatwa}.
5629 @emph{Disable warnings for Ada 2005 compatibility issues.}
5630 @cindex @option{-gnatwY} (@command{gcc})
5631 @cindex Ada 2005 compatibility issues warnings
5632 This switch suppresses several warnings intended to help in identifying
5633 incompatibilities between Ada 95 and Ada 2005.
5636 @emph{Activate warnings on unchecked conversions.}
5637 @cindex @option{-gnatwz} (@command{gcc})
5638 @cindex Unchecked_Conversion warnings
5639 This switch activates warnings for unchecked conversions
5640 where the types are known at compile time to have different
5642 is that such warnings are generated. Warnings are also
5643 generated for subprogram pointers with different conventions,
5644 and, on VMS only, for data pointers with different conventions.
5645 This warning can also be turned on using @option{-gnatwa}.
5648 @emph{Suppress warnings on unchecked conversions.}
5649 @cindex @option{-gnatwZ} (@command{gcc})
5650 This switch suppresses warnings for unchecked conversions
5651 where the types are known at compile time to have different
5652 sizes or conventions.
5654 @item ^-Wunused^WARNINGS=UNUSED^
5655 @cindex @option{-Wunused}
5656 The warnings controlled by the @option{-gnatw} switch are generated by
5657 the front end of the compiler. The @option{GCC} back end can provide
5658 additional warnings and they are controlled by the @option{-W} switch.
5659 For example, @option{^-Wunused^WARNINGS=UNUSED^} activates back end
5660 warnings for entities that are declared but not referenced.
5662 @item ^-Wuninitialized^WARNINGS=UNINITIALIZED^
5663 @cindex @option{-Wuninitialized}
5664 Similarly, @option{^-Wuninitialized^WARNINGS=UNINITIALIZED^} activates
5665 the back end warning for uninitialized variables. This switch must be
5666 used in conjunction with an optimization level greater than zero.
5668 @item ^-Wall^/ALL_BACK_END_WARNINGS^
5669 @cindex @option{-Wall}
5670 This switch enables all the above warnings from the @option{GCC} back end.
5671 The code generator detects a number of warning situations that are missed
5672 by the @option{GNAT} front end, and this switch can be used to activate them.
5673 The use of this switch also sets the default front end warning mode to
5674 @option{-gnatwa}, that is, most front end warnings activated as well.
5676 @item ^-w^/NO_BACK_END_WARNINGS^
5678 Conversely, this switch suppresses warnings from the @option{GCC} back end.
5679 The use of this switch also sets the default front end warning mode to
5680 @option{-gnatws}, that is, front end warnings suppressed as well.
5686 A string of warning parameters can be used in the same parameter. For example:
5693 will turn on all optional warnings except for elaboration pragma warnings,
5694 and also specify that warnings should be treated as errors.
5696 When no switch @option{^-gnatw^/WARNINGS^} is used, this is equivalent to:
5721 @node Debugging and Assertion Control
5722 @subsection Debugging and Assertion Control
5726 @cindex @option{-gnata} (@command{gcc})
5732 The pragmas @code{Assert} and @code{Debug} normally have no effect and
5733 are ignored. This switch, where @samp{a} stands for assert, causes
5734 @code{Assert} and @code{Debug} pragmas to be activated.
5736 The pragmas have the form:
5740 @b{pragma} Assert (@var{Boolean-expression} @r{[},
5741 @var{static-string-expression}@r{]})
5742 @b{pragma} Debug (@var{procedure call})
5747 The @code{Assert} pragma causes @var{Boolean-expression} to be tested.
5748 If the result is @code{True}, the pragma has no effect (other than
5749 possible side effects from evaluating the expression). If the result is
5750 @code{False}, the exception @code{Assert_Failure} declared in the package
5751 @code{System.Assertions} is
5752 raised (passing @var{static-string-expression}, if present, as the
5753 message associated with the exception). If no string expression is
5754 given the default is a string giving the file name and line number
5757 The @code{Debug} pragma causes @var{procedure} to be called. Note that
5758 @code{pragma Debug} may appear within a declaration sequence, allowing
5759 debugging procedures to be called between declarations.
5762 @item /DEBUG@r{[}=debug-level@r{]}
5764 Specifies how much debugging information is to be included in
5765 the resulting object file where 'debug-level' is one of the following:
5768 Include both debugger symbol records and traceback
5770 This is the default setting.
5772 Include both debugger symbol records and traceback in
5775 Excludes both debugger symbol records and traceback
5776 the object file. Same as /NODEBUG.
5778 Includes only debugger symbol records in the object
5779 file. Note that this doesn't include traceback information.
5784 @node Validity Checking
5785 @subsection Validity Checking
5786 @findex Validity Checking
5789 The Ada Reference Manual has specific requirements for checking
5790 for invalid values. In particular, RM 13.9.1 requires that the
5791 evaluation of invalid values (for example from unchecked conversions),
5792 not result in erroneous execution. In GNAT, the result of such an
5793 evaluation in normal default mode is to either use the value
5794 unmodified, or to raise Constraint_Error in those cases where use
5795 of the unmodified value would cause erroneous execution. The cases
5796 where unmodified values might lead to erroneous execution are case
5797 statements (where a wild jump might result from an invalid value),
5798 and subscripts on the left hand side (where memory corruption could
5799 occur as a result of an invalid value).
5801 The @option{-gnatB} switch tells the compiler to assume that all
5802 values are valid (that is, within their declared subtype range)
5803 except in the context of a use of the Valid attribute. This means
5804 the compiler can generate more efficient code, since the range
5805 of values is better known at compile time.
5807 The @option{-gnatV^@var{x}^^} switch allows more control over the validity
5810 The @code{x} argument is a string of letters that
5811 indicate validity checks that are performed or not performed in addition
5812 to the default checks described above.
5815 The options allowed for this qualifier
5816 indicate validity checks that are performed or not performed in addition
5817 to the default checks described above.
5823 @emph{All validity checks.}
5824 @cindex @option{-gnatVa} (@command{gcc})
5825 All validity checks are turned on.
5827 That is, @option{-gnatVa} is
5828 equivalent to @option{gnatVcdfimorst}.
5832 @emph{Validity checks for copies.}
5833 @cindex @option{-gnatVc} (@command{gcc})
5834 The right hand side of assignments, and the initializing values of
5835 object declarations are validity checked.
5838 @emph{Default (RM) validity checks.}
5839 @cindex @option{-gnatVd} (@command{gcc})
5840 Some validity checks are done by default following normal Ada semantics
5842 A check is done in case statements that the expression is within the range
5843 of the subtype. If it is not, Constraint_Error is raised.
5844 For assignments to array components, a check is done that the expression used
5845 as index is within the range. If it is not, Constraint_Error is raised.
5846 Both these validity checks may be turned off using switch @option{-gnatVD}.
5847 They are turned on by default. If @option{-gnatVD} is specified, a subsequent
5848 switch @option{-gnatVd} will leave the checks turned on.
5849 Switch @option{-gnatVD} should be used only if you are sure that all such
5850 expressions have valid values. If you use this switch and invalid values
5851 are present, then the program is erroneous, and wild jumps or memory
5852 overwriting may occur.
5855 @emph{Validity checks for elementary components.}
5856 @cindex @option{-gnatVe} (@command{gcc})
5857 In the absence of this switch, assignments to record or array components are
5858 not validity checked, even if validity checks for assignments generally
5859 (@option{-gnatVc}) are turned on. In Ada, assignment of composite values do not
5860 require valid data, but assignment of individual components does. So for
5861 example, there is a difference between copying the elements of an array with a
5862 slice assignment, compared to assigning element by element in a loop. This
5863 switch allows you to turn off validity checking for components, even when they
5864 are assigned component by component.
5867 @emph{Validity checks for floating-point values.}
5868 @cindex @option{-gnatVf} (@command{gcc})
5869 In the absence of this switch, validity checking occurs only for discrete
5870 values. If @option{-gnatVf} is specified, then validity checking also applies
5871 for floating-point values, and NaNs and infinities are considered invalid,
5872 as well as out of range values for constrained types. Note that this means
5873 that standard IEEE infinity mode is not allowed. The exact contexts
5874 in which floating-point values are checked depends on the setting of other
5875 options. For example,
5876 @option{^-gnatVif^VALIDITY_CHECKING=(IN_PARAMS,FLOATS)^} or
5877 @option{^-gnatVfi^VALIDITY_CHECKING=(FLOATS,IN_PARAMS)^}
5878 (the order does not matter) specifies that floating-point parameters of mode
5879 @code{in} should be validity checked.
5882 @emph{Validity checks for @code{in} mode parameters}
5883 @cindex @option{-gnatVi} (@command{gcc})
5884 Arguments for parameters of mode @code{in} are validity checked in function
5885 and procedure calls at the point of call.
5888 @emph{Validity checks for @code{in out} mode parameters.}
5889 @cindex @option{-gnatVm} (@command{gcc})
5890 Arguments for parameters of mode @code{in out} are validity checked in
5891 procedure calls at the point of call. The @code{'m'} here stands for
5892 modify, since this concerns parameters that can be modified by the call.
5893 Note that there is no specific option to test @code{out} parameters,
5894 but any reference within the subprogram will be tested in the usual
5895 manner, and if an invalid value is copied back, any reference to it
5896 will be subject to validity checking.
5899 @emph{No validity checks.}
5900 @cindex @option{-gnatVn} (@command{gcc})
5901 This switch turns off all validity checking, including the default checking
5902 for case statements and left hand side subscripts. Note that the use of
5903 the switch @option{-gnatp} suppresses all run-time checks, including
5904 validity checks, and thus implies @option{-gnatVn}. When this switch
5905 is used, it cancels any other @option{-gnatV} previously issued.
5908 @emph{Validity checks for operator and attribute operands.}
5909 @cindex @option{-gnatVo} (@command{gcc})
5910 Arguments for predefined operators and attributes are validity checked.
5911 This includes all operators in package @code{Standard},
5912 the shift operators defined as intrinsic in package @code{Interfaces}
5913 and operands for attributes such as @code{Pos}. Checks are also made
5914 on individual component values for composite comparisons, and on the
5915 expressions in type conversions and qualified expressions. Checks are
5916 also made on explicit ranges using @samp{..} (e.g.@: slices, loops etc).
5919 @emph{Validity checks for parameters.}
5920 @cindex @option{-gnatVp} (@command{gcc})
5921 This controls the treatment of parameters within a subprogram (as opposed
5922 to @option{-gnatVi} and @option{-gnatVm} which control validity testing
5923 of parameters on a call. If either of these call options is used, then
5924 normally an assumption is made within a subprogram that the input arguments
5925 have been validity checking at the point of call, and do not need checking
5926 again within a subprogram). If @option{-gnatVp} is set, then this assumption
5927 is not made, and parameters are not assumed to be valid, so their validity
5928 will be checked (or rechecked) within the subprogram.
5931 @emph{Validity checks for function returns.}
5932 @cindex @option{-gnatVr} (@command{gcc})
5933 The expression in @code{return} statements in functions is validity
5937 @emph{Validity checks for subscripts.}
5938 @cindex @option{-gnatVs} (@command{gcc})
5939 All subscripts expressions are checked for validity, whether they appear
5940 on the right side or left side (in default mode only left side subscripts
5941 are validity checked).
5944 @emph{Validity checks for tests.}
5945 @cindex @option{-gnatVt} (@command{gcc})
5946 Expressions used as conditions in @code{if}, @code{while} or @code{exit}
5947 statements are checked, as well as guard expressions in entry calls.
5952 The @option{-gnatV} switch may be followed by
5953 ^a string of letters^a list of options^
5954 to turn on a series of validity checking options.
5956 @option{^-gnatVcr^/VALIDITY_CHECKING=(COPIES, RETURNS)^}
5957 specifies that in addition to the default validity checking, copies and
5958 function return expressions are to be validity checked.
5959 In order to make it easier
5960 to specify the desired combination of effects,
5962 the upper case letters @code{CDFIMORST} may
5963 be used to turn off the corresponding lower case option.
5966 the prefix @code{NO} on an option turns off the corresponding validity
5969 @item @code{NOCOPIES}
5970 @item @code{NODEFAULT}
5971 @item @code{NOFLOATS}
5972 @item @code{NOIN_PARAMS}
5973 @item @code{NOMOD_PARAMS}
5974 @item @code{NOOPERANDS}
5975 @item @code{NORETURNS}
5976 @item @code{NOSUBSCRIPTS}
5977 @item @code{NOTESTS}
5981 @option{^-gnatVaM^/VALIDITY_CHECKING=(ALL, NOMOD_PARAMS)^}
5982 turns on all validity checking options except for
5983 checking of @code{@b{in out}} procedure arguments.
5985 The specification of additional validity checking generates extra code (and
5986 in the case of @option{-gnatVa} the code expansion can be substantial).
5987 However, these additional checks can be very useful in detecting
5988 uninitialized variables, incorrect use of unchecked conversion, and other
5989 errors leading to invalid values. The use of pragma @code{Initialize_Scalars}
5990 is useful in conjunction with the extra validity checking, since this
5991 ensures that wherever possible uninitialized variables have invalid values.
5993 See also the pragma @code{Validity_Checks} which allows modification of
5994 the validity checking mode at the program source level, and also allows for
5995 temporary disabling of validity checks.
5997 @node Style Checking
5998 @subsection Style Checking
5999 @findex Style checking
6002 The @option{-gnaty^x^(option,option,@dots{})^} switch
6003 @cindex @option{-gnaty} (@command{gcc})
6004 causes the compiler to
6005 enforce specified style rules. A limited set of style rules has been used
6006 in writing the GNAT sources themselves. This switch allows user programs
6007 to activate all or some of these checks. If the source program fails a
6008 specified style check, an appropriate warning message is given, preceded by
6009 the character sequence ``(style)''.
6011 @code{(option,option,@dots{})} is a sequence of keywords
6014 The string @var{x} is a sequence of letters or digits
6016 indicating the particular style
6017 checks to be performed. The following checks are defined:
6022 @emph{Specify indentation level.}
6023 If a digit from 1-9 appears
6024 ^in the string after @option{-gnaty}^as an option for /STYLE_CHECKS^
6025 then proper indentation is checked, with the digit indicating the
6026 indentation level required. A value of zero turns off this style check.
6027 The general style of required indentation is as specified by
6028 the examples in the Ada Reference Manual. Full line comments must be
6029 aligned with the @code{--} starting on a column that is a multiple of
6030 the alignment level, or they may be aligned the same way as the following
6031 non-blank line (this is useful when full line comments appear in the middle
6035 @emph{Check attribute casing.}
6036 Attribute names, including the case of keywords such as @code{digits}
6037 used as attributes names, must be written in mixed case, that is, the
6038 initial letter and any letter following an underscore must be uppercase.
6039 All other letters must be lowercase.
6041 @item ^A^ARRAY_INDEXES^
6042 @emph{Use of array index numbers in array attributes.}
6043 When using the array attributes First, Last, Range,
6044 or Length, the index number must be omitted for one-dimensional arrays
6045 and is required for multi-dimensional arrays.
6048 @emph{Blanks not allowed at statement end.}
6049 Trailing blanks are not allowed at the end of statements. The purpose of this
6050 rule, together with h (no horizontal tabs), is to enforce a canonical format
6051 for the use of blanks to separate source tokens.
6054 @emph{Check comments.}
6055 Comments must meet the following set of rules:
6060 The ``@code{--}'' that starts the column must either start in column one,
6061 or else at least one blank must precede this sequence.
6064 Comments that follow other tokens on a line must have at least one blank
6065 following the ``@code{--}'' at the start of the comment.
6068 Full line comments must have two blanks following the ``@code{--}'' that
6069 starts the comment, with the following exceptions.
6072 A line consisting only of the ``@code{--}'' characters, possibly preceded
6073 by blanks is permitted.
6076 A comment starting with ``@code{--x}'' where @code{x} is a special character
6078 This allows proper processing of the output generated by specialized tools
6079 including @command{gnatprep} (where ``@code{--!}'' is used) and the SPARK
6081 language (where ``@code{--#}'' is used). For the purposes of this rule, a
6082 special character is defined as being in one of the ASCII ranges
6083 @code{16#21#@dots{}16#2F#} or @code{16#3A#@dots{}16#3F#}.
6084 Note that this usage is not permitted
6085 in GNAT implementation units (i.e., when @option{-gnatg} is used).
6088 A line consisting entirely of minus signs, possibly preceded by blanks, is
6089 permitted. This allows the construction of box comments where lines of minus
6090 signs are used to form the top and bottom of the box.
6093 A comment that starts and ends with ``@code{--}'' is permitted as long as at
6094 least one blank follows the initial ``@code{--}''. Together with the preceding
6095 rule, this allows the construction of box comments, as shown in the following
6098 ---------------------------
6099 -- This is a box comment --
6100 -- with two text lines. --
6101 ---------------------------
6105 @item ^d^DOS_LINE_ENDINGS^
6106 @emph{Check no DOS line terminators present.}
6107 All lines must be terminated by a single ASCII.LF
6108 character (in particular the DOS line terminator sequence CR/LF is not
6112 @emph{Check end/exit labels.}
6113 Optional labels on @code{end} statements ending subprograms and on
6114 @code{exit} statements exiting named loops, are required to be present.
6117 @emph{No form feeds or vertical tabs.}
6118 Neither form feeds nor vertical tab characters are permitted
6122 @emph{GNAT style mode}
6123 The set of style check switches is set to match that used by the GNAT sources.
6124 This may be useful when developing code that is eventually intended to be
6125 incorporated into GNAT. For further details, see GNAT sources.
6128 @emph{No horizontal tabs.}
6129 Horizontal tab characters are not permitted in the source text.
6130 Together with the b (no blanks at end of line) check, this
6131 enforces a canonical form for the use of blanks to separate
6135 @emph{Check if-then layout.}
6136 The keyword @code{then} must appear either on the same
6137 line as corresponding @code{if}, or on a line on its own, lined
6138 up under the @code{if} with at least one non-blank line in between
6139 containing all or part of the condition to be tested.
6142 @emph{check mode IN keywords}
6143 Mode @code{in} (the default mode) is not
6144 allowed to be given explicitly. @code{in out} is fine,
6145 but not @code{in} on its own.
6148 @emph{Check keyword casing.}
6149 All keywords must be in lower case (with the exception of keywords
6150 such as @code{digits} used as attribute names to which this check
6154 @emph{Check layout.}
6155 Layout of statement and declaration constructs must follow the
6156 recommendations in the Ada Reference Manual, as indicated by the
6157 form of the syntax rules. For example an @code{else} keyword must
6158 be lined up with the corresponding @code{if} keyword.
6160 There are two respects in which the style rule enforced by this check
6161 option are more liberal than those in the Ada Reference Manual. First
6162 in the case of record declarations, it is permissible to put the
6163 @code{record} keyword on the same line as the @code{type} keyword, and
6164 then the @code{end} in @code{end record} must line up under @code{type}.
6165 This is also permitted when the type declaration is split on two lines.
6166 For example, any of the following three layouts is acceptable:
6168 @smallexample @c ada
6191 Second, in the case of a block statement, a permitted alternative
6192 is to put the block label on the same line as the @code{declare} or
6193 @code{begin} keyword, and then line the @code{end} keyword up under
6194 the block label. For example both the following are permitted:
6196 @smallexample @c ada
6214 The same alternative format is allowed for loops. For example, both of
6215 the following are permitted:
6217 @smallexample @c ada
6219 Clear : while J < 10 loop
6230 @item ^Lnnn^MAX_NESTING=nnn^
6231 @emph{Set maximum nesting level}
6232 The maximum level of nesting of constructs (including subprograms, loops,
6233 blocks, packages, and conditionals) may not exceed the given value
6234 @option{nnn}. A value of zero disconnects this style check.
6236 @item ^m^LINE_LENGTH^
6237 @emph{Check maximum line length.}
6238 The length of source lines must not exceed 79 characters, including
6239 any trailing blanks. The value of 79 allows convenient display on an
6240 80 character wide device or window, allowing for possible special
6241 treatment of 80 character lines. Note that this count is of
6242 characters in the source text. This means that a tab character counts
6243 as one character in this count but a wide character sequence counts as
6244 a single character (however many bytes are needed in the encoding).
6246 @item ^Mnnn^MAX_LENGTH=nnn^
6247 @emph{Set maximum line length.}
6248 The length of lines must not exceed the
6249 given value @option{nnn}. The maximum value that can be specified is 32767.
6251 @item ^n^STANDARD_CASING^
6252 @emph{Check casing of entities in Standard.}
6253 Any identifier from Standard must be cased
6254 to match the presentation in the Ada Reference Manual (for example,
6255 @code{Integer} and @code{ASCII.NUL}).
6258 @emph{Turn off all style checks}
6259 All style check options are turned off.
6261 @item ^o^ORDERED_SUBPROGRAMS^
6262 @emph{Check order of subprogram bodies.}
6263 All subprogram bodies in a given scope
6264 (e.g.@: a package body) must be in alphabetical order. The ordering
6265 rule uses normal Ada rules for comparing strings, ignoring casing
6266 of letters, except that if there is a trailing numeric suffix, then
6267 the value of this suffix is used in the ordering (e.g.@: Junk2 comes
6270 @item ^O^OVERRIDING_INDICATORS^
6271 @emph{Check that overriding subprograms are explicitly marked as such.}
6272 The declaration of a primitive operation of a type extension that overrides
6273 an inherited operation must carry an overriding indicator.
6276 @emph{Check pragma casing.}
6277 Pragma names must be written in mixed case, that is, the
6278 initial letter and any letter following an underscore must be uppercase.
6279 All other letters must be lowercase.
6281 @item ^r^REFERENCES^
6282 @emph{Check references.}
6283 All identifier references must be cased in the same way as the
6284 corresponding declaration. No specific casing style is imposed on
6285 identifiers. The only requirement is for consistency of references
6288 @item ^S^STATEMENTS_AFTER_THEN_ELSE^
6289 @emph{Check no statements after THEN/ELSE.}
6290 No statements are allowed
6291 on the same line as a THEN or ELSE keyword following the
6292 keyword in an IF statement. OR ELSE and AND THEN are not affected,
6293 and a special exception allows a pragma to appear after ELSE.
6296 @emph{Check separate specs.}
6297 Separate declarations (``specs'') are required for subprograms (a
6298 body is not allowed to serve as its own declaration). The only
6299 exception is that parameterless library level procedures are
6300 not required to have a separate declaration. This exception covers
6301 the most frequent form of main program procedures.
6304 @emph{Check token spacing.}
6305 The following token spacing rules are enforced:
6310 The keywords @code{@b{abs}} and @code{@b{not}} must be followed by a space.
6313 The token @code{=>} must be surrounded by spaces.
6316 The token @code{<>} must be preceded by a space or a left parenthesis.
6319 Binary operators other than @code{**} must be surrounded by spaces.
6320 There is no restriction on the layout of the @code{**} binary operator.
6323 Colon must be surrounded by spaces.
6326 Colon-equal (assignment, initialization) must be surrounded by spaces.
6329 Comma must be the first non-blank character on the line, or be
6330 immediately preceded by a non-blank character, and must be followed
6334 If the token preceding a left parenthesis ends with a letter or digit, then
6335 a space must separate the two tokens.
6338 A right parenthesis must either be the first non-blank character on
6339 a line, or it must be preceded by a non-blank character.
6342 A semicolon must not be preceded by a space, and must not be followed by
6343 a non-blank character.
6346 A unary plus or minus may not be followed by a space.
6349 A vertical bar must be surrounded by spaces.
6352 @item ^u^UNNECESSARY_BLANK_LINES^
6353 @emph{Check unnecessary blank lines.}
6354 Unnecessary blank lines are not allowed. A blank line is considered
6355 unnecessary if it appears at the end of the file, or if more than
6356 one blank line occurs in sequence.
6358 @item ^x^XTRA_PARENS^
6359 @emph{Check extra parentheses.}
6360 Unnecessary extra level of parentheses (C-style) are not allowed
6361 around conditions in @code{if} statements, @code{while} statements and
6362 @code{exit} statements.
6364 @item ^y^ALL_BUILTIN^
6365 @emph{Set all standard style check options}
6366 This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
6367 options enabled with the exception of @option{-gnatyo}, @option{-gnatyI},
6368 @option{-gnatyS}, @option{-gnatyLnnn},
6369 @option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
6373 @emph{Remove style check options}
6374 This causes any subsequent options in the string to act as canceling the
6375 corresponding style check option. To cancel maximum nesting level control,
6376 use @option{L} parameter witout any integer value after that, because any
6377 digit following @option{-} in the parameter string of the @option{-gnaty}
6378 option will be threated as canceling indentation check. The same is true
6379 for @option{M} parameter. @option{y} and @option{N} parameters are not
6380 allowed after @option{-}.
6383 This causes any subsequent options in the string to enable the corresponding
6384 style check option. That is, it cancels the effect of a previous ^-^REMOVE^,
6390 @emph{Removing style check options}
6391 If the name of a style check is preceded by @option{NO} then the corresponding
6392 style check is turned off. For example @option{NOCOMMENTS} turns off style
6393 checking for comments.
6398 In the above rules, appearing in column one is always permitted, that is,
6399 counts as meeting either a requirement for a required preceding space,
6400 or as meeting a requirement for no preceding space.
6402 Appearing at the end of a line is also always permitted, that is, counts
6403 as meeting either a requirement for a following space, or as meeting
6404 a requirement for no following space.
6407 If any of these style rules is violated, a message is generated giving
6408 details on the violation. The initial characters of such messages are
6409 always ``@code{(style)}''. Note that these messages are treated as warning
6410 messages, so they normally do not prevent the generation of an object
6411 file. The @option{-gnatwe} switch can be used to treat warning messages,
6412 including style messages, as fatal errors.
6416 @option{-gnaty} on its own (that is not
6417 followed by any letters or digits), then the effect is equivalent
6418 to the use of @option{-gnatyy}, as described above, that is all
6419 built-in standard style check options are enabled.
6423 /STYLE_CHECKS=ALL_BUILTIN enables all checking options with
6424 the exception of ORDERED_SUBPROGRAMS, UNNECESSARY_BLANK_LINES,
6425 XTRA_PARENS, and DOS_LINE_ENDINGS. In addition
6437 clears any previously set style checks.
6439 @node Run-Time Checks
6440 @subsection Run-Time Checks
6441 @cindex Division by zero
6442 @cindex Access before elaboration
6443 @cindex Checks, division by zero
6444 @cindex Checks, access before elaboration
6445 @cindex Checks, stack overflow checking
6448 By default, the following checks are suppressed: integer overflow
6449 checks, stack overflow checks, and checks for access before
6450 elaboration on subprogram calls. All other checks, including range
6451 checks and array bounds checks, are turned on by default. The
6452 following @command{gcc} switches refine this default behavior.
6457 @cindex @option{-gnatp} (@command{gcc})
6458 @cindex Suppressing checks
6459 @cindex Checks, suppressing
6461 Suppress all run-time checks as though @code{pragma Suppress (All_checks)}
6462 had been present in the source. Validity checks are also suppressed (in
6463 other words @option{-gnatp} also implies @option{-gnatVn}.
6464 Use this switch to improve the performance
6465 of the code at the expense of safety in the presence of invalid data or
6468 Note that when checks are suppressed, the compiler is allowed, but not
6469 required, to omit the checking code. If the run-time cost of the
6470 checking code is zero or near-zero, the compiler will generate it even
6471 if checks are suppressed. In particular, if the compiler can prove
6472 that a certain check will necessarily fail, it will generate code to
6473 do an unconditional ``raise'', even if checks are suppressed. The
6474 compiler warns in this case.
6476 Of course, run-time checks are omitted whenever the compiler can prove
6477 that they will not fail, whether or not checks are suppressed.
6479 Note that if you suppress a check that would have failed, program
6480 execution is erroneous, which means the behavior is totally
6481 unpredictable. The program might crash, or print wrong answers, or
6482 do anything else. It might even do exactly what you wanted it to do
6483 (and then it might start failing mysteriously next week or next
6484 year). The compiler will generate code based on the assumption that
6485 the condition being checked is true, which can result in disaster if
6486 that assumption is wrong.
6489 @cindex @option{-gnato} (@command{gcc})
6490 @cindex Overflow checks
6491 @cindex Check, overflow
6492 Enables overflow checking for integer operations.
6493 This causes GNAT to generate slower and larger executable
6494 programs by adding code to check for overflow (resulting in raising
6495 @code{Constraint_Error} as required by standard Ada
6496 semantics). These overflow checks correspond to situations in which
6497 the true value of the result of an operation may be outside the base
6498 range of the result type. The following example shows the distinction:
6500 @smallexample @c ada
6501 X1 : Integer := "Integer'Last";
6502 X2 : Integer range 1 .. 5 := "5";
6503 X3 : Integer := "Integer'Last";
6504 X4 : Integer range 1 .. 5 := "5";
6505 F : Float := "2.0E+20";
6514 Note that if explicit values are assigned at compile time, the
6515 compiler may be able to detect overflow at compile time, in which case
6516 no actual run-time checking code is required, and Constraint_Error
6517 will be raised unconditionally, with or without
6518 @option{-gnato}. That's why the assigned values in the above fragment
6519 are in quotes, the meaning is "assign a value not known to the
6520 compiler that happens to be equal to ...". The remaining discussion
6521 assumes that the compiler cannot detect the values at compile time.
6523 Here the first addition results in a value that is outside the base range
6524 of Integer, and hence requires an overflow check for detection of the
6525 constraint error. Thus the first assignment to @code{X1} raises a
6526 @code{Constraint_Error} exception only if @option{-gnato} is set.
6528 The second increment operation results in a violation of the explicit
6529 range constraint; such range checks are performed by default, and are
6530 unaffected by @option{-gnato}.
6532 The two conversions of @code{F} both result in values that are outside
6533 the base range of type @code{Integer} and thus will raise
6534 @code{Constraint_Error} exceptions only if @option{-gnato} is used.
6535 The fact that the result of the second conversion is assigned to
6536 variable @code{X4} with a restricted range is irrelevant, since the problem
6537 is in the conversion, not the assignment.
6539 Basically the rule is that in the default mode (@option{-gnato} not
6540 used), the generated code assures that all integer variables stay
6541 within their declared ranges, or within the base range if there is
6542 no declared range. This prevents any serious problems like indexes
6543 out of range for array operations.
6545 What is not checked in default mode is an overflow that results in
6546 an in-range, but incorrect value. In the above example, the assignments
6547 to @code{X1}, @code{X2}, @code{X3} all give results that are within the
6548 range of the target variable, but the result is wrong in the sense that
6549 it is too large to be represented correctly. Typically the assignment
6550 to @code{X1} will result in wrap around to the largest negative number.
6551 The conversions of @code{F} will result in some @code{Integer} value
6552 and if that integer value is out of the @code{X4} range then the
6553 subsequent assignment would generate an exception.
6555 @findex Machine_Overflows
6556 Note that the @option{-gnato} switch does not affect the code generated
6557 for any floating-point operations; it applies only to integer
6559 For floating-point, GNAT has the @code{Machine_Overflows}
6560 attribute set to @code{False} and the normal mode of operation is to
6561 generate IEEE NaN and infinite values on overflow or invalid operations
6562 (such as dividing 0.0 by 0.0).
6564 The reason that we distinguish overflow checking from other kinds of
6565 range constraint checking is that a failure of an overflow check, unlike
6566 for example the failure of a range check, can result in an incorrect
6567 value, but cannot cause random memory destruction (like an out of range
6568 subscript), or a wild jump (from an out of range case value). Overflow
6569 checking is also quite expensive in time and space, since in general it
6570 requires the use of double length arithmetic.
6572 Note again that @option{-gnato} is off by default, so overflow checking is
6573 not performed in default mode. This means that out of the box, with the
6574 default settings, GNAT does not do all the checks expected from the
6575 language description in the Ada Reference Manual. If you want all constraint
6576 checks to be performed, as described in this Manual, then you must
6577 explicitly use the -gnato switch either on the @command{gnatmake} or
6578 @command{gcc} command.
6581 @cindex @option{-gnatE} (@command{gcc})
6582 @cindex Elaboration checks
6583 @cindex Check, elaboration
6584 Enables dynamic checks for access-before-elaboration
6585 on subprogram calls and generic instantiations.
6586 Note that @option{-gnatE} is not necessary for safety, because in the
6587 default mode, GNAT ensures statically that the checks would not fail.
6588 For full details of the effect and use of this switch,
6589 @xref{Compiling Using gcc}.
6592 @cindex @option{-fstack-check} (@command{gcc})
6593 @cindex Stack Overflow Checking
6594 @cindex Checks, stack overflow checking
6595 Activates stack overflow checking. For full details of the effect and use of
6596 this switch see @ref{Stack Overflow Checking}.
6601 The setting of these switches only controls the default setting of the
6602 checks. You may modify them using either @code{Suppress} (to remove
6603 checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in
6606 @node Using gcc for Syntax Checking
6607 @subsection Using @command{gcc} for Syntax Checking
6610 @cindex @option{-gnats} (@command{gcc})
6614 The @code{s} stands for ``syntax''.
6617 Run GNAT in syntax checking only mode. For
6618 example, the command
6621 $ gcc -c -gnats x.adb
6625 compiles file @file{x.adb} in syntax-check-only mode. You can check a
6626 series of files in a single command
6628 , and can use wild cards to specify such a group of files.
6629 Note that you must specify the @option{-c} (compile
6630 only) flag in addition to the @option{-gnats} flag.
6633 You may use other switches in conjunction with @option{-gnats}. In
6634 particular, @option{-gnatl} and @option{-gnatv} are useful to control the
6635 format of any generated error messages.
6637 When the source file is empty or contains only empty lines and/or comments,
6638 the output is a warning:
6641 $ gcc -c -gnats -x ada toto.txt
6642 toto.txt:1:01: warning: empty file, contains no compilation units
6646 Otherwise, the output is simply the error messages, if any. No object file or
6647 ALI file is generated by a syntax-only compilation. Also, no units other
6648 than the one specified are accessed. For example, if a unit @code{X}
6649 @code{with}'s a unit @code{Y}, compiling unit @code{X} in syntax
6650 check only mode does not access the source file containing unit
6653 @cindex Multiple units, syntax checking
6654 Normally, GNAT allows only a single unit in a source file. However, this
6655 restriction does not apply in syntax-check-only mode, and it is possible
6656 to check a file containing multiple compilation units concatenated
6657 together. This is primarily used by the @code{gnatchop} utility
6658 (@pxref{Renaming Files Using gnatchop}).
6661 @node Using gcc for Semantic Checking
6662 @subsection Using @command{gcc} for Semantic Checking
6665 @cindex @option{-gnatc} (@command{gcc})
6669 The @code{c} stands for ``check''.
6671 Causes the compiler to operate in semantic check mode,
6672 with full checking for all illegalities specified in the
6673 Ada Reference Manual, but without generation of any object code
6674 (no object file is generated).
6676 Because dependent files must be accessed, you must follow the GNAT
6677 semantic restrictions on file structuring to operate in this mode:
6681 The needed source files must be accessible
6682 (@pxref{Search Paths and the Run-Time Library (RTL)}).
6685 Each file must contain only one compilation unit.
6688 The file name and unit name must match (@pxref{File Naming Rules}).
6691 The output consists of error messages as appropriate. No object file is
6692 generated. An @file{ALI} file is generated for use in the context of
6693 cross-reference tools, but this file is marked as not being suitable
6694 for binding (since no object file is generated).
6695 The checking corresponds exactly to the notion of
6696 legality in the Ada Reference Manual.
6698 Any unit can be compiled in semantics-checking-only mode, including
6699 units that would not normally be compiled (subunits,
6700 and specifications where a separate body is present).
6703 @node Compiling Different Versions of Ada
6704 @subsection Compiling Different Versions of Ada
6707 The switches described in this section allow you to explicitly specify
6708 the version of the Ada language that your programs are written in.
6709 By default @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
6710 but you can also specify @value{NONDEFAULTLANGUAGEVERSION} or
6711 indicate Ada 83 compatibility mode.
6714 @cindex Compatibility with Ada 83
6716 @item -gnat83 (Ada 83 Compatibility Mode)
6717 @cindex @option{-gnat83} (@command{gcc})
6718 @cindex ACVC, Ada 83 tests
6722 Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
6723 specifies that the program is to be compiled in Ada 83 mode. With
6724 @option{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83
6725 semantics where this can be done easily.
6726 It is not possible to guarantee this switch does a perfect
6727 job; some subtle tests, such as are
6728 found in earlier ACVC tests (and that have been removed from the ACATS suite
6729 for Ada 95), might not compile correctly.
6730 Nevertheless, this switch may be useful in some circumstances, for example
6731 where, due to contractual reasons, existing code needs to be maintained
6732 using only Ada 83 features.
6734 With few exceptions (most notably the need to use @code{<>} on
6735 @cindex Generic formal parameters
6736 unconstrained generic formal parameters, the use of the new Ada 95 / Ada 2005
6737 reserved words, and the use of packages
6738 with optional bodies), it is not necessary to specify the
6739 @option{-gnat83} switch when compiling Ada 83 programs, because, with rare
6740 exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
6741 a correct Ada 83 program is usually also a correct program
6742 in these later versions of the language standard.
6743 For further information, please refer to @ref{Compatibility and Porting Guide}.
6745 @item -gnat95 (Ada 95 mode)
6746 @cindex @option{-gnat95} (@command{gcc})
6750 This switch directs the compiler to implement the Ada 95 version of the
6752 Since Ada 95 is almost completely upwards
6753 compatible with Ada 83, Ada 83 programs may generally be compiled using
6754 this switch (see the description of the @option{-gnat83} switch for further
6755 information about Ada 83 mode).
6756 If an Ada 2005 program is compiled in Ada 95 mode,
6757 uses of the new Ada 2005 features will cause error
6758 messages or warnings.
6760 This switch also can be used to cancel the effect of a previous
6761 @option{-gnat83} or @option{-gnat05} switch earlier in the command line.
6763 @item -gnat05 (Ada 2005 mode)
6764 @cindex @option{-gnat05} (@command{gcc})
6765 @cindex Ada 2005 mode
6768 This switch directs the compiler to implement the Ada 2005 version of the
6770 Since Ada 2005 is almost completely upwards
6771 compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
6772 may generally be compiled using this switch (see the description of the
6773 @option{-gnat83} and @option{-gnat95} switches for further
6776 For information about the approved ``Ada Issues'' that have been incorporated
6777 into Ada 2005, see @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}.
6778 Included with GNAT releases is a file @file{features-ada0y} that describes
6779 the set of implemented Ada 2005 features.
6783 @node Character Set Control
6784 @subsection Character Set Control
6786 @item ^-gnati^/IDENTIFIER_CHARACTER_SET=^@var{c}
6787 @cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@command{gcc})
6790 Normally GNAT recognizes the Latin-1 character set in source program
6791 identifiers, as described in the Ada Reference Manual.
6793 GNAT to recognize alternate character sets in identifiers. @var{c} is a
6794 single character ^^or word^ indicating the character set, as follows:
6798 ISO 8859-1 (Latin-1) identifiers
6801 ISO 8859-2 (Latin-2) letters allowed in identifiers
6804 ISO 8859-3 (Latin-3) letters allowed in identifiers
6807 ISO 8859-4 (Latin-4) letters allowed in identifiers
6810 ISO 8859-5 (Cyrillic) letters allowed in identifiers
6813 ISO 8859-15 (Latin-9) letters allowed in identifiers
6816 IBM PC letters (code page 437) allowed in identifiers
6819 IBM PC letters (code page 850) allowed in identifiers
6821 @item ^f^FULL_UPPER^
6822 Full upper-half codes allowed in identifiers
6825 No upper-half codes allowed in identifiers
6828 Wide-character codes (that is, codes greater than 255)
6829 allowed in identifiers
6832 @xref{Foreign Language Representation}, for full details on the
6833 implementation of these character sets.
6835 @item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e}
6836 @cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@command{gcc})
6837 Specify the method of encoding for wide characters.
6838 @var{e} is one of the following:
6843 Hex encoding (brackets coding also recognized)
6846 Upper half encoding (brackets encoding also recognized)
6849 Shift/JIS encoding (brackets encoding also recognized)
6852 EUC encoding (brackets encoding also recognized)
6855 UTF-8 encoding (brackets encoding also recognized)
6858 Brackets encoding only (default value)
6860 For full details on these encoding
6861 methods see @ref{Wide Character Encodings}.
6862 Note that brackets coding is always accepted, even if one of the other
6863 options is specified, so for example @option{-gnatW8} specifies that both
6864 brackets and UTF-8 encodings will be recognized. The units that are
6865 with'ed directly or indirectly will be scanned using the specified
6866 representation scheme, and so if one of the non-brackets scheme is
6867 used, it must be used consistently throughout the program. However,
6868 since brackets encoding is always recognized, it may be conveniently
6869 used in standard libraries, allowing these libraries to be used with
6870 any of the available coding schemes.
6873 If no @option{-gnatW?} parameter is present, then the default
6874 representation is normally Brackets encoding only. However, if the
6875 first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
6876 byte order mark or BOM for UTF-8), then these three characters are
6877 skipped and the default representation for the file is set to UTF-8.
6879 Note that the wide character representation that is specified (explicitly
6880 or by default) for the main program also acts as the default encoding used
6881 for Wide_Text_IO files if not specifically overridden by a WCEM form
6885 @node File Naming Control
6886 @subsection File Naming Control
6889 @item ^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{n}
6890 @cindex @option{-gnatk} (@command{gcc})
6891 Activates file name ``krunching''. @var{n}, a decimal integer in the range
6892 1-999, indicates the maximum allowable length of a file name (not
6893 including the @file{.ads} or @file{.adb} extension). The default is not
6894 to enable file name krunching.
6896 For the source file naming rules, @xref{File Naming Rules}.
6899 @node Subprogram Inlining Control
6900 @subsection Subprogram Inlining Control
6905 @cindex @option{-gnatn} (@command{gcc})
6907 The @code{n} here is intended to suggest the first syllable of the
6910 GNAT recognizes and processes @code{Inline} pragmas. However, for the
6911 inlining to actually occur, optimization must be enabled. To enable
6912 inlining of subprograms specified by pragma @code{Inline},
6913 you must also specify this switch.
6914 In the absence of this switch, GNAT does not attempt
6915 inlining and does not need to access the bodies of
6916 subprograms for which @code{pragma Inline} is specified if they are not
6917 in the current unit.
6919 If you specify this switch the compiler will access these bodies,
6920 creating an extra source dependency for the resulting object file, and
6921 where possible, the call will be inlined.
6922 For further details on when inlining is possible
6923 see @ref{Inlining of Subprograms}.
6926 @cindex @option{-gnatN} (@command{gcc})
6927 This switch activates front-end inlining which also
6928 generates additional dependencies.
6930 When using a gcc-based back end (in practice this means using any version
6931 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
6932 @option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
6933 Historically front end inlining was more extensive than the gcc back end
6934 inlining, but that is no longer the case.
6937 @node Auxiliary Output Control
6938 @subsection Auxiliary Output Control
6942 @cindex @option{-gnatt} (@command{gcc})
6943 @cindex Writing internal trees
6944 @cindex Internal trees, writing to file
6945 Causes GNAT to write the internal tree for a unit to a file (with the
6946 extension @file{.adt}.
6947 This not normally required, but is used by separate analysis tools.
6949 these tools do the necessary compilations automatically, so you should
6950 not have to specify this switch in normal operation.
6953 @cindex @option{-gnatu} (@command{gcc})
6954 Print a list of units required by this compilation on @file{stdout}.
6955 The listing includes all units on which the unit being compiled depends
6956 either directly or indirectly.
6959 @item -pass-exit-codes
6960 @cindex @option{-pass-exit-codes} (@command{gcc})
6961 If this switch is not used, the exit code returned by @command{gcc} when
6962 compiling multiple files indicates whether all source files have
6963 been successfully used to generate object files or not.
6965 When @option{-pass-exit-codes} is used, @command{gcc} exits with an extended
6966 exit status and allows an integrated development environment to better
6967 react to a compilation failure. Those exit status are:
6971 There was an error in at least one source file.
6973 At least one source file did not generate an object file.
6975 The compiler died unexpectedly (internal error for example).
6977 An object file has been generated for every source file.
6982 @node Debugging Control
6983 @subsection Debugging Control
6987 @cindex Debugging options
6990 @cindex @option{-gnatd} (@command{gcc})
6991 Activate internal debugging switches. @var{x} is a letter or digit, or
6992 string of letters or digits, which specifies the type of debugging
6993 outputs desired. Normally these are used only for internal development
6994 or system debugging purposes. You can find full documentation for these
6995 switches in the body of the @code{Debug} unit in the compiler source
6996 file @file{debug.adb}.
7000 @cindex @option{-gnatG} (@command{gcc})
7001 This switch causes the compiler to generate auxiliary output containing
7002 a pseudo-source listing of the generated expanded code. Like most Ada
7003 compilers, GNAT works by first transforming the high level Ada code into
7004 lower level constructs. For example, tasking operations are transformed
7005 into calls to the tasking run-time routines. A unique capability of GNAT
7006 is to list this expanded code in a form very close to normal Ada source.
7007 This is very useful in understanding the implications of various Ada
7008 usage on the efficiency of the generated code. There are many cases in
7009 Ada (e.g.@: the use of controlled types), where simple Ada statements can
7010 generate a lot of run-time code. By using @option{-gnatG} you can identify
7011 these cases, and consider whether it may be desirable to modify the coding
7012 approach to improve efficiency.
7014 The optional parameter @code{nn} if present after -gnatG specifies an
7015 alternative maximum line length that overrides the normal default of 72.
7016 This value is in the range 40-999999, values less than 40 being silently
7017 reset to 40. The equal sign is optional.
7019 The format of the output is very similar to standard Ada source, and is
7020 easily understood by an Ada programmer. The following special syntactic
7021 additions correspond to low level features used in the generated code that
7022 do not have any exact analogies in pure Ada source form. The following
7023 is a partial list of these special constructions. See the spec
7024 of package @code{Sprint} in file @file{sprint.ads} for a full list.
7026 If the switch @option{-gnatL} is used in conjunction with
7027 @cindex @option{-gnatL} (@command{gcc})
7028 @option{-gnatG}, then the original source lines are interspersed
7029 in the expanded source (as comment lines with the original line number).
7032 @item new @var{xxx} @r{[}storage_pool = @var{yyy}@r{]}
7033 Shows the storage pool being used for an allocator.
7035 @item at end @var{procedure-name};
7036 Shows the finalization (cleanup) procedure for a scope.
7038 @item (if @var{expr} then @var{expr} else @var{expr})
7039 Conditional expression equivalent to the @code{x?y:z} construction in C.
7041 @item @var{target}^^^(@var{source})
7042 A conversion with floating-point truncation instead of rounding.
7044 @item @var{target}?(@var{source})
7045 A conversion that bypasses normal Ada semantic checking. In particular
7046 enumeration types and fixed-point types are treated simply as integers.
7048 @item @var{target}?^^^(@var{source})
7049 Combines the above two cases.
7051 @item @var{x} #/ @var{y}
7052 @itemx @var{x} #mod @var{y}
7053 @itemx @var{x} #* @var{y}
7054 @itemx @var{x} #rem @var{y}
7055 A division or multiplication of fixed-point values which are treated as
7056 integers without any kind of scaling.
7058 @item free @var{expr} @r{[}storage_pool = @var{xxx}@r{]}
7059 Shows the storage pool associated with a @code{free} statement.
7061 @item [subtype or type declaration]
7062 Used to list an equivalent declaration for an internally generated
7063 type that is referenced elsewhere in the listing.
7065 @item freeze @var{type-name} @ovar{actions}
7066 Shows the point at which @var{type-name} is frozen, with possible
7067 associated actions to be performed at the freeze point.
7069 @item reference @var{itype}
7070 Reference (and hence definition) to internal type @var{itype}.
7072 @item @var{function-name}! (@var{arg}, @var{arg}, @var{arg})
7073 Intrinsic function call.
7075 @item @var{label-name} : label
7076 Declaration of label @var{labelname}.
7078 @item #$ @var{subprogram-name}
7079 An implicit call to a run-time support routine
7080 (to meet the requirement of H.3.1(9) in a
7083 @item @var{expr} && @var{expr} && @var{expr} @dots{} && @var{expr}
7084 A multiple concatenation (same effect as @var{expr} & @var{expr} &
7085 @var{expr}, but handled more efficiently).
7087 @item [constraint_error]
7088 Raise the @code{Constraint_Error} exception.
7090 @item @var{expression}'reference
7091 A pointer to the result of evaluating @var{expression}.
7093 @item @var{target-type}!(@var{source-expression})
7094 An unchecked conversion of @var{source-expression} to @var{target-type}.
7096 @item [@var{numerator}/@var{denominator}]
7097 Used to represent internal real literals (that) have no exact
7098 representation in base 2-16 (for example, the result of compile time
7099 evaluation of the expression 1.0/27.0).
7103 @cindex @option{-gnatD} (@command{gcc})
7104 When used in conjunction with @option{-gnatG}, this switch causes
7105 the expanded source, as described above for
7106 @option{-gnatG} to be written to files with names
7107 @file{^xxx.dg^XXX_DG^}, where @file{xxx} is the normal file name,
7108 instead of to the standard output file. For
7109 example, if the source file name is @file{hello.adb}, then a file
7110 @file{^hello.adb.dg^HELLO.ADB_DG^} will be written. The debugging
7111 information generated by the @command{gcc} @option{^-g^/DEBUG^} switch
7112 will refer to the generated @file{^xxx.dg^XXX_DG^} file. This allows
7113 you to do source level debugging using the generated code which is
7114 sometimes useful for complex code, for example to find out exactly
7115 which part of a complex construction raised an exception. This switch
7116 also suppress generation of cross-reference information (see
7117 @option{-gnatx}) since otherwise the cross-reference information
7118 would refer to the @file{^.dg^.DG^} file, which would cause
7119 confusion since this is not the original source file.
7121 Note that @option{-gnatD} actually implies @option{-gnatG}
7122 automatically, so it is not necessary to give both options.
7123 In other words @option{-gnatD} is equivalent to @option{-gnatDG}).
7125 If the switch @option{-gnatL} is used in conjunction with
7126 @cindex @option{-gnatL} (@command{gcc})
7127 @option{-gnatDG}, then the original source lines are interspersed
7128 in the expanded source (as comment lines with the original line number).
7130 The optional parameter @code{nn} if present after -gnatD specifies an
7131 alternative maximum line length that overrides the normal default of 72.
7132 This value is in the range 40-999999, values less than 40 being silently
7133 reset to 40. The equal sign is optional.
7136 @cindex @option{-gnatr} (@command{gcc})
7137 @cindex pragma Restrictions
7138 This switch causes pragma Restrictions to be treated as Restriction_Warnings
7139 so that violation of restrictions causes warnings rather than illegalities.
7140 This is useful during the development process when new restrictions are added
7141 or investigated. The switch also causes pragma Profile to be treated as
7142 Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
7143 restriction warnings rather than restrictions.
7146 @item -gnatR@r{[}0@r{|}1@r{|}2@r{|}3@r{[}s@r{]]}
7147 @cindex @option{-gnatR} (@command{gcc})
7148 This switch controls output from the compiler of a listing showing
7149 representation information for declared types and objects. For
7150 @option{-gnatR0}, no information is output (equivalent to omitting
7151 the @option{-gnatR} switch). For @option{-gnatR1} (which is the default,
7152 so @option{-gnatR} with no parameter has the same effect), size and alignment
7153 information is listed for declared array and record types. For
7154 @option{-gnatR2}, size and alignment information is listed for all
7155 declared types and objects. Finally @option{-gnatR3} includes symbolic
7156 expressions for values that are computed at run time for
7157 variant records. These symbolic expressions have a mostly obvious
7158 format with #n being used to represent the value of the n'th
7159 discriminant. See source files @file{repinfo.ads/adb} in the
7160 @code{GNAT} sources for full details on the format of @option{-gnatR3}
7161 output. If the switch is followed by an s (e.g.@: @option{-gnatR2s}), then
7162 the output is to a file with the name @file{^file.rep^file_REP^} where
7163 file is the name of the corresponding source file.
7166 @item /REPRESENTATION_INFO
7167 @cindex @option{/REPRESENTATION_INFO} (@command{gcc})
7168 This qualifier controls output from the compiler of a listing showing
7169 representation information for declared types and objects. For
7170 @option{/REPRESENTATION_INFO=NONE}, no information is output
7171 (equivalent to omitting the @option{/REPRESENTATION_INFO} qualifier).
7172 @option{/REPRESENTATION_INFO} without option is equivalent to
7173 @option{/REPRESENTATION_INFO=ARRAYS}.
7174 For @option{/REPRESENTATION_INFO=ARRAYS}, size and alignment
7175 information is listed for declared array and record types. For
7176 @option{/REPRESENTATION_INFO=OBJECTS}, size and alignment information
7177 is listed for all expression information for values that are computed
7178 at run time for variant records. These symbolic expressions have a mostly
7179 obvious format with #n being used to represent the value of the n'th
7180 discriminant. See source files @file{REPINFO.ADS/ADB} in the
7181 @code{GNAT} sources for full details on the format of
7182 @option{/REPRESENTATION_INFO=SYMBOLIC} output.
7183 If _FILE is added at the end of an option
7184 (e.g.@: @option{/REPRESENTATION_INFO=ARRAYS_FILE}),
7185 then the output is to a file with the name @file{file_REP} where
7186 file is the name of the corresponding source file.
7188 Note that it is possible for record components to have zero size. In
7189 this case, the component clause uses an obvious extension of permitted
7190 Ada syntax, for example @code{at 0 range 0 .. -1}.
7192 Representation information requires that code be generated (since it is the
7193 code generator that lays out complex data structures). If an attempt is made
7194 to output representation information when no code is generated, for example
7195 when a subunit is compiled on its own, then no information can be generated
7196 and the compiler outputs a message to this effect.
7199 @cindex @option{-gnatS} (@command{gcc})
7200 The use of the switch @option{-gnatS} for an
7201 Ada compilation will cause the compiler to output a
7202 representation of package Standard in a form very
7203 close to standard Ada. It is not quite possible to
7204 do this entirely in standard Ada (since new
7205 numeric base types cannot be created in standard
7206 Ada), but the output is easily
7207 readable to any Ada programmer, and is useful to
7208 determine the characteristics of target dependent
7209 types in package Standard.
7212 @cindex @option{-gnatx} (@command{gcc})
7213 Normally the compiler generates full cross-referencing information in
7214 the @file{ALI} file. This information is used by a number of tools,
7215 including @code{gnatfind} and @code{gnatxref}. The @option{-gnatx} switch
7216 suppresses this information. This saves some space and may slightly
7217 speed up compilation, but means that these tools cannot be used.
7220 @node Exception Handling Control
7221 @subsection Exception Handling Control
7224 GNAT uses two methods for handling exceptions at run-time. The
7225 @code{setjmp/longjmp} method saves the context when entering
7226 a frame with an exception handler. Then when an exception is
7227 raised, the context can be restored immediately, without the
7228 need for tracing stack frames. This method provides very fast
7229 exception propagation, but introduces significant overhead for
7230 the use of exception handlers, even if no exception is raised.
7232 The other approach is called ``zero cost'' exception handling.
7233 With this method, the compiler builds static tables to describe
7234 the exception ranges. No dynamic code is required when entering
7235 a frame containing an exception handler. When an exception is
7236 raised, the tables are used to control a back trace of the
7237 subprogram invocation stack to locate the required exception
7238 handler. This method has considerably poorer performance for
7239 the propagation of exceptions, but there is no overhead for
7240 exception handlers if no exception is raised. Note that in this
7241 mode and in the context of mixed Ada and C/C++ programming,
7242 to propagate an exception through a C/C++ code, the C/C++ code
7243 must be compiled with the @option{-funwind-tables} GCC's
7246 The following switches may be used to control which of the
7247 two exception handling methods is used.
7253 @cindex @option{--RTS=sjlj} (@command{gnatmake})
7254 This switch causes the setjmp/longjmp run-time (when available) to be used
7255 for exception handling. If the default
7256 mechanism for the target is zero cost exceptions, then
7257 this switch can be used to modify this default, and must be
7258 used for all units in the partition.
7259 This option is rarely used. One case in which it may be
7260 advantageous is if you have an application where exception
7261 raising is common and the overall performance of the
7262 application is improved by favoring exception propagation.
7265 @cindex @option{--RTS=zcx} (@command{gnatmake})
7266 @cindex Zero Cost Exceptions
7267 This switch causes the zero cost approach to be used
7268 for exception handling. If this is the default mechanism for the
7269 target (see below), then this switch is unneeded. If the default
7270 mechanism for the target is setjmp/longjmp exceptions, then
7271 this switch can be used to modify this default, and must be
7272 used for all units in the partition.
7273 This option can only be used if the zero cost approach
7274 is available for the target in use, otherwise it will generate an error.
7278 The same option @option{--RTS} must be used both for @command{gcc}
7279 and @command{gnatbind}. Passing this option to @command{gnatmake}
7280 (@pxref{Switches for gnatmake}) will ensure the required consistency
7281 through the compilation and binding steps.
7283 @node Units to Sources Mapping Files
7284 @subsection Units to Sources Mapping Files
7288 @item -gnatem^^=^@var{path}
7289 @cindex @option{-gnatem} (@command{gcc})
7290 A mapping file is a way to communicate to the compiler two mappings:
7291 from unit names to file names (without any directory information) and from
7292 file names to path names (with full directory information). These mappings
7293 are used by the compiler to short-circuit the path search.
7295 The use of mapping files is not required for correct operation of the
7296 compiler, but mapping files can improve efficiency, particularly when
7297 sources are read over a slow network connection. In normal operation,
7298 you need not be concerned with the format or use of mapping files,
7299 and the @option{-gnatem} switch is not a switch that you would use
7300 explicitly. it is intended only for use by automatic tools such as
7301 @command{gnatmake} running under the project file facility. The
7302 description here of the format of mapping files is provided
7303 for completeness and for possible use by other tools.
7305 A mapping file is a sequence of sets of three lines. In each set,
7306 the first line is the unit name, in lower case, with ``@code{%s}''
7308 specs and ``@code{%b}'' appended for bodies; the second line is the
7309 file name; and the third line is the path name.
7315 /gnat/project1/sources/main.2.ada
7318 When the switch @option{-gnatem} is specified, the compiler will create
7319 in memory the two mappings from the specified file. If there is any problem
7320 (nonexistent file, truncated file or duplicate entries), no mapping will
7323 Several @option{-gnatem} switches may be specified; however, only the last
7324 one on the command line will be taken into account.
7326 When using a project file, @command{gnatmake} create a temporary mapping file
7327 and communicates it to the compiler using this switch.
7331 @node Integrated Preprocessing
7332 @subsection Integrated Preprocessing
7335 GNAT sources may be preprocessed immediately before compilation.
7336 In this case, the actual
7337 text of the source is not the text of the source file, but is derived from it
7338 through a process called preprocessing. Integrated preprocessing is specified
7339 through switches @option{-gnatep} and/or @option{-gnateD}. @option{-gnatep}
7340 indicates, through a text file, the preprocessing data to be used.
7341 @option{-gnateD} specifies or modifies the values of preprocessing symbol.
7344 Note that when integrated preprocessing is used, the output from the
7345 preprocessor is not written to any external file. Instead it is passed
7346 internally to the compiler. If you need to preserve the result of
7347 preprocessing in a file, then you should use @command{gnatprep}
7348 to perform the desired preprocessing in stand-alone mode.
7351 It is recommended that @command{gnatmake} switch ^-s^/SWITCH_CHECK^ should be
7352 used when Integrated Preprocessing is used. The reason is that preprocessing
7353 with another Preprocessing Data file without changing the sources will
7354 not trigger recompilation without this switch.
7357 Note that @command{gnatmake} switch ^-m^/MINIMAL_RECOMPILATION^ will almost
7358 always trigger recompilation for sources that are preprocessed,
7359 because @command{gnatmake} cannot compute the checksum of the source after
7363 The actual preprocessing function is described in details in section
7364 @ref{Preprocessing Using gnatprep}. This section only describes how integrated
7365 preprocessing is triggered and parameterized.
7369 @item -gnatep=@var{file}
7370 @cindex @option{-gnatep} (@command{gcc})
7371 This switch indicates to the compiler the file name (without directory
7372 information) of the preprocessor data file to use. The preprocessor data file
7373 should be found in the source directories.
7376 A preprocessing data file is a text file with significant lines indicating
7377 how should be preprocessed either a specific source or all sources not
7378 mentioned in other lines. A significant line is a nonempty, non-comment line.
7379 Comments are similar to Ada comments.
7382 Each significant line starts with either a literal string or the character '*'.
7383 A literal string is the file name (without directory information) of the source
7384 to preprocess. A character '*' indicates the preprocessing for all the sources
7385 that are not specified explicitly on other lines (order of the lines is not
7386 significant). It is an error to have two lines with the same file name or two
7387 lines starting with the character '*'.
7390 After the file name or the character '*', another optional literal string
7391 indicating the file name of the definition file to be used for preprocessing
7392 (@pxref{Form of Definitions File}). The definition files are found by the
7393 compiler in one of the source directories. In some cases, when compiling
7394 a source in a directory other than the current directory, if the definition
7395 file is in the current directory, it may be necessary to add the current
7396 directory as a source directory through switch ^-I.^/SEARCH=[]^, otherwise
7397 the compiler would not find the definition file.
7400 Then, optionally, ^switches^switches^ similar to those of @code{gnatprep} may
7401 be found. Those ^switches^switches^ are:
7406 Causes both preprocessor lines and the lines deleted by
7407 preprocessing to be replaced by blank lines, preserving the line number.
7408 This ^switch^switch^ is always implied; however, if specified after @option{-c}
7409 it cancels the effect of @option{-c}.
7412 Causes both preprocessor lines and the lines deleted
7413 by preprocessing to be retained as comments marked
7414 with the special string ``@code{--! }''.
7416 @item -Dsymbol=value
7417 Define or redefine a symbol, associated with value. A symbol is an Ada
7418 identifier, or an Ada reserved word, with the exception of @code{if},
7419 @code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
7420 @code{value} is either a literal string, an Ada identifier or any Ada reserved
7421 word. A symbol declared with this ^switch^switch^ replaces a symbol with the
7422 same name defined in a definition file.
7425 Causes a sorted list of symbol names and values to be
7426 listed on the standard output file.
7429 Causes undefined symbols to be treated as having the value @code{FALSE}
7431 of a preprocessor test. In the absence of this option, an undefined symbol in
7432 a @code{#if} or @code{#elsif} test will be treated as an error.
7437 Examples of valid lines in a preprocessor data file:
7440 "toto.adb" "prep.def" -u
7441 -- preprocess "toto.adb", using definition file "prep.def",
7442 -- undefined symbol are False.
7445 -- preprocess all other sources without a definition file;
7446 -- suppressed lined are commented; symbol VERSION has the value V101.
7448 "titi.adb" "prep2.def" -s
7449 -- preprocess "titi.adb", using definition file "prep2.def";
7450 -- list all symbols with their values.
7453 @item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=value@r{]}
7454 @cindex @option{-gnateD} (@command{gcc})
7455 Define or redefine a preprocessing symbol, associated with value. If no value
7456 is given on the command line, then the value of the symbol is @code{True}.
7457 A symbol is an identifier, following normal Ada (case-insensitive)
7458 rules for its syntax, and value is any sequence (including an empty sequence)
7459 of characters from the set (letters, digits, period, underline).
7460 Ada reserved words may be used as symbols, with the exceptions of @code{if},
7461 @code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
7464 A symbol declared with this ^switch^switch^ on the command line replaces a
7465 symbol with the same name either in a definition file or specified with a
7466 ^switch^switch^ -D in the preprocessor data file.
7469 This switch is similar to switch @option{^-D^/ASSOCIATE^} of @code{gnatprep}.
7472 When integrated preprocessing is performed and the preprocessor modifies
7473 the source text, write the result of this preprocessing into a file
7474 <source>^.prep^_prep^.
7478 @node Code Generation Control
7479 @subsection Code Generation Control
7483 The GCC technology provides a wide range of target dependent
7484 @option{-m} switches for controlling
7485 details of code generation with respect to different versions of
7486 architectures. This includes variations in instruction sets (e.g.@:
7487 different members of the power pc family), and different requirements
7488 for optimal arrangement of instructions (e.g.@: different members of
7489 the x86 family). The list of available @option{-m} switches may be
7490 found in the GCC documentation.
7492 Use of these @option{-m} switches may in some cases result in improved
7495 The GNAT Pro technology is tested and qualified without any
7496 @option{-m} switches,
7497 so generally the most reliable approach is to avoid the use of these
7498 switches. However, we generally expect most of these switches to work
7499 successfully with GNAT Pro, and many customers have reported successful
7500 use of these options.
7502 Our general advice is to avoid the use of @option{-m} switches unless
7503 special needs lead to requirements in this area. In particular,
7504 there is no point in using @option{-m} switches to improve performance
7505 unless you actually see a performance improvement.
7509 @subsection Return Codes
7510 @cindex Return Codes
7511 @cindex @option{/RETURN_CODES=VMS}
7514 On VMS, GNAT compiled programs return POSIX-style codes by default,
7515 e.g.@: @option{/RETURN_CODES=POSIX}.
7517 To enable VMS style return codes, use GNAT BIND and LINK with the option
7518 @option{/RETURN_CODES=VMS}. For example:
7521 GNAT BIND MYMAIN.ALI /RETURN_CODES=VMS
7522 GNAT LINK MYMAIN.ALI /RETURN_CODES=VMS
7526 Programs built with /RETURN_CODES=VMS are suitable to be called in
7527 VMS DCL scripts. Programs compiled with the default /RETURN_CODES=POSIX
7528 are suitable for spawning with appropriate GNAT RTL routines.
7532 @node Search Paths and the Run-Time Library (RTL)
7533 @section Search Paths and the Run-Time Library (RTL)
7536 With the GNAT source-based library system, the compiler must be able to
7537 find source files for units that are needed by the unit being compiled.
7538 Search paths are used to guide this process.
7540 The compiler compiles one source file whose name must be given
7541 explicitly on the command line. In other words, no searching is done
7542 for this file. To find all other source files that are needed (the most
7543 common being the specs of units), the compiler examines the following
7544 directories, in the following order:
7548 The directory containing the source file of the main unit being compiled
7549 (the file name on the command line).
7552 Each directory named by an @option{^-I^/SOURCE_SEARCH^} switch given on the
7553 @command{gcc} command line, in the order given.
7556 @findex ADA_PRJ_INCLUDE_FILE
7557 Each of the directories listed in the text file whose name is given
7558 by the @env{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
7561 @env{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
7562 driver when project files are used. It should not normally be set
7566 @findex ADA_INCLUDE_PATH
7567 Each of the directories listed in the value of the
7568 @env{ADA_INCLUDE_PATH} ^environment variable^logical name^.
7570 Construct this value
7571 exactly as the @env{PATH} environment variable: a list of directory
7572 names separated by colons (semicolons when working with the NT version).
7575 Normally, define this value as a logical name containing a comma separated
7576 list of directory names.
7578 This variable can also be defined by means of an environment string
7579 (an argument to the HP C exec* set of functions).
7583 DEFINE ANOTHER_PATH FOO:[BAG]
7584 DEFINE ADA_INCLUDE_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR]
7587 By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB]
7588 first, followed by the standard Ada
7589 libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADAINCLUDE].
7590 If this is not redefined, the user will obtain the HP Ada 83 IO packages
7591 (Text_IO, Sequential_IO, etc)
7592 instead of the standard Ada packages. Thus, in order to get the standard Ada
7593 packages by default, ADA_INCLUDE_PATH must be redefined.
7597 The content of the @file{ada_source_path} file which is part of the GNAT
7598 installation tree and is used to store standard libraries such as the
7599 GNAT Run Time Library (RTL) source files.
7601 @ref{Installing a library}
7606 Specifying the switch @option{^-I-^/NOCURRENT_DIRECTORY^}
7607 inhibits the use of the directory
7608 containing the source file named in the command line. You can still
7609 have this directory on your search path, but in this case it must be
7610 explicitly requested with a @option{^-I^/SOURCE_SEARCH^} switch.
7612 Specifying the switch @option{-nostdinc}
7613 inhibits the search of the default location for the GNAT Run Time
7614 Library (RTL) source files.
7616 The compiler outputs its object files and ALI files in the current
7619 Caution: The object file can be redirected with the @option{-o} switch;
7620 however, @command{gcc} and @code{gnat1} have not been coordinated on this
7621 so the @file{ALI} file will not go to the right place. Therefore, you should
7622 avoid using the @option{-o} switch.
7626 The packages @code{Ada}, @code{System}, and @code{Interfaces} and their
7627 children make up the GNAT RTL, together with the simple @code{System.IO}
7628 package used in the @code{"Hello World"} example. The sources for these units
7629 are needed by the compiler and are kept together in one directory. Not
7630 all of the bodies are needed, but all of the sources are kept together
7631 anyway. In a normal installation, you need not specify these directory
7632 names when compiling or binding. Either the environment variables or
7633 the built-in defaults cause these files to be found.
7635 In addition to the language-defined hierarchies (@code{System}, @code{Ada} and
7636 @code{Interfaces}), the GNAT distribution provides a fourth hierarchy,
7637 consisting of child units of @code{GNAT}. This is a collection of generally
7638 useful types, subprograms, etc. @xref{Top, GNAT Reference Manual, About
7639 This Guid, gnat_rm, GNAT Reference Manual}, for further details.
7641 Besides simplifying access to the RTL, a major use of search paths is
7642 in compiling sources from multiple directories. This can make
7643 development environments much more flexible.
7645 @node Order of Compilation Issues
7646 @section Order of Compilation Issues
7649 If, in our earlier example, there was a spec for the @code{hello}
7650 procedure, it would be contained in the file @file{hello.ads}; yet this
7651 file would not have to be explicitly compiled. This is the result of the
7652 model we chose to implement library management. Some of the consequences
7653 of this model are as follows:
7657 There is no point in compiling specs (except for package
7658 specs with no bodies) because these are compiled as needed by clients. If
7659 you attempt a useless compilation, you will receive an error message.
7660 It is also useless to compile subunits because they are compiled as needed
7664 There are no order of compilation requirements: performing a
7665 compilation never obsoletes anything. The only way you can obsolete
7666 something and require recompilations is to modify one of the
7667 source files on which it depends.
7670 There is no library as such, apart from the ALI files
7671 (@pxref{The Ada Library Information Files}, for information on the format
7672 of these files). For now we find it convenient to create separate ALI files,
7673 but eventually the information therein may be incorporated into the object
7677 When you compile a unit, the source files for the specs of all units
7678 that it @code{with}'s, all its subunits, and the bodies of any generics it
7679 instantiates must be available (reachable by the search-paths mechanism
7680 described above), or you will receive a fatal error message.
7687 The following are some typical Ada compilation command line examples:
7690 @item $ gcc -c xyz.adb
7691 Compile body in file @file{xyz.adb} with all default options.
7694 @item $ gcc -c -O2 -gnata xyz-def.adb
7697 @item $ GNAT COMPILE /OPTIMIZE=ALL -gnata xyz-def.adb
7700 Compile the child unit package in file @file{xyz-def.adb} with extensive
7701 optimizations, and pragma @code{Assert}/@code{Debug} statements
7704 @item $ gcc -c -gnatc abc-def.adb
7705 Compile the subunit in file @file{abc-def.adb} in semantic-checking-only
7709 @node Binding Using gnatbind
7710 @chapter Binding Using @code{gnatbind}
7714 * Running gnatbind::
7715 * Switches for gnatbind::
7716 * Command-Line Access::
7717 * Search Paths for gnatbind::
7718 * Examples of gnatbind Usage::
7722 This chapter describes the GNAT binder, @code{gnatbind}, which is used
7723 to bind compiled GNAT objects.
7725 Note: to invoke @code{gnatbind} with a project file, use the @code{gnat}
7726 driver (see @ref{The GNAT Driver and Project Files}).
7728 The @code{gnatbind} program performs four separate functions:
7732 Checks that a program is consistent, in accordance with the rules in
7733 Chapter 10 of the Ada Reference Manual. In particular, error
7734 messages are generated if a program uses inconsistent versions of a
7738 Checks that an acceptable order of elaboration exists for the program
7739 and issues an error message if it cannot find an order of elaboration
7740 that satisfies the rules in Chapter 10 of the Ada Language Manual.
7743 Generates a main program incorporating the given elaboration order.
7744 This program is a small Ada package (body and spec) that
7745 must be subsequently compiled
7746 using the GNAT compiler. The necessary compilation step is usually
7747 performed automatically by @command{gnatlink}. The two most important
7748 functions of this program
7749 are to call the elaboration routines of units in an appropriate order
7750 and to call the main program.
7753 Determines the set of object files required by the given main program.
7754 This information is output in the forms of comments in the generated program,
7755 to be read by the @command{gnatlink} utility used to link the Ada application.
7758 @node Running gnatbind
7759 @section Running @code{gnatbind}
7762 The form of the @code{gnatbind} command is
7765 $ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches}
7769 where @file{@var{mainprog}.adb} is the Ada file containing the main program
7770 unit body. If no switches are specified, @code{gnatbind} constructs an Ada
7771 package in two files whose names are
7772 @file{b~@var{mainprog}.ads}, and @file{b~@var{mainprog}.adb}.
7773 For example, if given the
7774 parameter @file{hello.ali}, for a main program contained in file
7775 @file{hello.adb}, the binder output files would be @file{b~hello.ads}
7776 and @file{b~hello.adb}.
7778 When doing consistency checking, the binder takes into consideration
7779 any source files it can locate. For example, if the binder determines
7780 that the given main program requires the package @code{Pack}, whose
7782 file is @file{pack.ali} and whose corresponding source spec file is
7783 @file{pack.ads}, it attempts to locate the source file @file{pack.ads}
7784 (using the same search path conventions as previously described for the
7785 @command{gcc} command). If it can locate this source file, it checks that
7787 or source checksums of the source and its references to in @file{ALI} files
7788 match. In other words, any @file{ALI} files that mentions this spec must have
7789 resulted from compiling this version of the source file (or in the case
7790 where the source checksums match, a version close enough that the
7791 difference does not matter).
7793 @cindex Source files, use by binder
7794 The effect of this consistency checking, which includes source files, is
7795 that the binder ensures that the program is consistent with the latest
7796 version of the source files that can be located at bind time. Editing a
7797 source file without compiling files that depend on the source file cause
7798 error messages to be generated by the binder.
7800 For example, suppose you have a main program @file{hello.adb} and a
7801 package @code{P}, from file @file{p.ads} and you perform the following
7806 Enter @code{gcc -c hello.adb} to compile the main program.
7809 Enter @code{gcc -c p.ads} to compile package @code{P}.
7812 Edit file @file{p.ads}.
7815 Enter @code{gnatbind hello}.
7819 At this point, the file @file{p.ali} contains an out-of-date time stamp
7820 because the file @file{p.ads} has been edited. The attempt at binding
7821 fails, and the binder generates the following error messages:
7824 error: "hello.adb" must be recompiled ("p.ads" has been modified)
7825 error: "p.ads" has been modified and must be recompiled
7829 Now both files must be recompiled as indicated, and then the bind can
7830 succeed, generating a main program. You need not normally be concerned
7831 with the contents of this file, but for reference purposes a sample
7832 binder output file is given in @ref{Example of Binder Output File}.
7834 In most normal usage, the default mode of @command{gnatbind} which is to
7835 generate the main package in Ada, as described in the previous section.
7836 In particular, this means that any Ada programmer can read and understand
7837 the generated main program. It can also be debugged just like any other
7838 Ada code provided the @option{^-g^/DEBUG^} switch is used for
7839 @command{gnatbind} and @command{gnatlink}.
7841 However for some purposes it may be convenient to generate the main
7842 program in C rather than Ada. This may for example be helpful when you
7843 are generating a mixed language program with the main program in C. The
7844 GNAT compiler itself is an example.
7845 The use of the @option{^-C^/BIND_FILE=C^} switch
7846 for both @code{gnatbind} and @command{gnatlink} will cause the program to
7847 be generated in C (and compiled using the gnu C compiler).
7849 @node Switches for gnatbind
7850 @section Switches for @command{gnatbind}
7853 The following switches are available with @code{gnatbind}; details will
7854 be presented in subsequent sections.
7857 * Consistency-Checking Modes::
7858 * Binder Error Message Control::
7859 * Elaboration Control::
7861 * Binding with Non-Ada Main Programs::
7862 * Binding Programs with No Main Subprogram::
7869 @cindex @option{--version} @command{gnatbind}
7870 Display Copyright and version, then exit disregarding all other options.
7873 @cindex @option{--help} @command{gnatbind}
7874 If @option{--version} was not used, display usage, then exit disregarding
7878 @cindex @option{-a} @command{gnatbind}
7879 Indicates that, if supported by the platform, the adainit procedure should
7880 be treated as an initialisation routine by the linker (a constructor). This
7881 is intended to be used by the Project Manager to automatically initialize
7882 shared Stand-Alone Libraries.
7884 @item ^-aO^/OBJECT_SEARCH^
7885 @cindex @option{^-aO^/OBJECT_SEARCH^} (@command{gnatbind})
7886 Specify directory to be searched for ALI files.
7888 @item ^-aI^/SOURCE_SEARCH^
7889 @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind})
7890 Specify directory to be searched for source file.
7892 @item ^-A^/BIND_FILE=ADA^
7893 @cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatbind})
7894 Generate binder program in Ada (default)
7896 @item ^-b^/REPORT_ERRORS=BRIEF^
7897 @cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@command{gnatbind})
7898 Generate brief messages to @file{stderr} even if verbose mode set.
7900 @item ^-c^/NOOUTPUT^
7901 @cindex @option{^-c^/NOOUTPUT^} (@command{gnatbind})
7902 Check only, no generation of binder output file.
7904 @item ^-C^/BIND_FILE=C^
7905 @cindex @option{^-C^/BIND_FILE=C^} (@command{gnatbind})
7906 Generate binder program in C
7908 @item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}
7909 @cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}} (@command{gnatbind})
7910 This switch can be used to change the default task stack size value
7911 to a specified size @var{nn}, which is expressed in bytes by default, or
7912 in kilobytes when suffixed with @var{k} or in megabytes when suffixed
7914 In the absence of a @samp{@r{[}k@r{|}m@r{]}} suffix, this switch is equivalent,
7915 in effect, to completing all task specs with
7916 @smallexample @c ada
7917 pragma Storage_Size (nn);
7919 When they do not already have such a pragma.
7921 @item ^-D^/DEFAULT_SECONDARY_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}
7922 @cindex @option{^-D^/DEFAULT_SECONDARY_STACK_SIZE=nnnnn^} (@command{gnatbind})
7923 This switch can be used to change the default secondary stack size value
7924 to a specified size @var{nn}, which is expressed in bytes by default, or
7925 in kilobytes when suffixed with @var{k} or in megabytes when suffixed
7928 The secondary stack is used to deal with functions that return a variable
7929 sized result, for example a function returning an unconstrained
7930 String. There are two ways in which this secondary stack is allocated.
7932 For most targets, the secondary stack is growing on demand and is allocated
7933 as a chain of blocks in the heap. The -D option is not very
7934 relevant. It only give some control over the size of the allocated
7935 blocks (whose size is the minimum of the default secondary stack size value,
7936 and the actual size needed for the current allocation request).
7938 For certain targets, notably VxWorks 653,
7939 the secondary stack is allocated by carving off a fixed ratio chunk of the
7940 primary task stack. The -D option is used to define the
7941 size of the environment task's secondary stack.
7943 @item ^-e^/ELABORATION_DEPENDENCIES^
7944 @cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@command{gnatbind})
7945 Output complete list of elaboration-order dependencies.
7947 @item ^-E^/STORE_TRACEBACKS^
7948 @cindex @option{^-E^/STORE_TRACEBACKS^} (@command{gnatbind})
7949 Store tracebacks in exception occurrences when the target supports it.
7950 This is the default with the zero cost exception mechanism.
7952 @c The following may get moved to an appendix
7953 This option is currently supported on the following targets:
7954 all x86 ports, Solaris, Windows, HP-UX, AIX, PowerPC VxWorks and Alpha VxWorks.
7956 See also the packages @code{GNAT.Traceback} and
7957 @code{GNAT.Traceback.Symbolic} for more information.
7959 Note that on x86 ports, you must not use @option{-fomit-frame-pointer}
7960 @command{gcc} option.
7963 @item ^-F^/FORCE_ELABS_FLAGS^
7964 @cindex @option{^-F^/FORCE_ELABS_FLAGS^} (@command{gnatbind})
7965 Force the checks of elaboration flags. @command{gnatbind} does not normally
7966 generate checks of elaboration flags for the main executable, except when
7967 a Stand-Alone Library is used. However, there are cases when this cannot be
7968 detected by gnatbind. An example is importing an interface of a Stand-Alone
7969 Library through a pragma Import and only specifying through a linker switch
7970 this Stand-Alone Library. This switch is used to guarantee that elaboration
7971 flag checks are generated.
7974 @cindex @option{^-h^/HELP^} (@command{gnatbind})
7975 Output usage (help) information
7978 @cindex @option{^-I^/SEARCH^} (@command{gnatbind})
7979 Specify directory to be searched for source and ALI files.
7981 @item ^-I-^/NOCURRENT_DIRECTORY^
7982 @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatbind})
7983 Do not look for sources in the current directory where @code{gnatbind} was
7984 invoked, and do not look for ALI files in the directory containing the
7985 ALI file named in the @code{gnatbind} command line.
7987 @item ^-l^/ORDER_OF_ELABORATION^
7988 @cindex @option{^-l^/ORDER_OF_ELABORATION^} (@command{gnatbind})
7989 Output chosen elaboration order.
7991 @item ^-L@var{xxx}^/BUILD_LIBRARY=@var{xxx}^
7992 @cindex @option{^-L^/BUILD_LIBRARY^} (@command{gnatbind})
7993 Bind the units for library building. In this case the adainit and
7994 adafinal procedures (@pxref{Binding with Non-Ada Main Programs})
7995 are renamed to ^@var{xxx}init^@var{XXX}INIT^ and
7996 ^@var{xxx}final^@var{XXX}FINAL^.
7997 Implies ^-n^/NOCOMPILE^.
7999 (@xref{GNAT and Libraries}, for more details.)
8002 On OpenVMS, these init and final procedures are exported in uppercase
8003 letters. For example if /BUILD_LIBRARY=toto is used, the exported name of
8004 the init procedure will be "TOTOINIT" and the exported name of the final
8005 procedure will be "TOTOFINAL".
8008 @item ^-Mxyz^/RENAME_MAIN=xyz^
8009 @cindex @option{^-M^/RENAME_MAIN^} (@command{gnatbind})
8010 Rename generated main program from main to xyz. This option is
8011 supported on cross environments only.
8013 @item ^-m^/ERROR_LIMIT=^@var{n}
8014 @cindex @option{^-m^/ERROR_LIMIT^} (@command{gnatbind})
8015 Limit number of detected errors or warnings to @var{n}, where @var{n} is
8016 in the range 1..999999. The default value if no switch is
8017 given is 9999. If the number of warnings reaches this limit, then a
8018 message is output and further warnings are suppressed, the bind
8019 continues in this case. If the number of errors reaches this
8020 limit, then a message is output and the bind is abandoned.
8021 A value of zero means that no limit is enforced. The equal
8025 Furthermore, under Windows, the sources pointed to by the libraries path
8026 set in the registry are not searched for.
8030 @cindex @option{^-n^/NOMAIN^} (@command{gnatbind})
8034 @cindex @option{-nostdinc} (@command{gnatbind})
8035 Do not look for sources in the system default directory.
8038 @cindex @option{-nostdlib} (@command{gnatbind})
8039 Do not look for library files in the system default directory.
8041 @item --RTS=@var{rts-path}
8042 @cindex @option{--RTS} (@code{gnatbind})
8043 Specifies the default location of the runtime library. Same meaning as the
8044 equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
8046 @item ^-o ^/OUTPUT=^@var{file}
8047 @cindex @option{^-o ^/OUTPUT^} (@command{gnatbind})
8048 Name the output file @var{file} (default is @file{b~@var{xxx}.adb}).
8049 Note that if this option is used, then linking must be done manually,
8050 gnatlink cannot be used.
8052 @item ^-O^/OBJECT_LIST^
8053 @cindex @option{^-O^/OBJECT_LIST^} (@command{gnatbind})
8056 @item ^-p^/PESSIMISTIC_ELABORATION^
8057 @cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@command{gnatbind})
8058 Pessimistic (worst-case) elaboration order
8061 @cindex @option{^-R^-R^} (@command{gnatbind})
8062 Output closure source list.
8064 @item ^-s^/READ_SOURCES=ALL^
8065 @cindex @option{^-s^/READ_SOURCES=ALL^} (@command{gnatbind})
8066 Require all source files to be present.
8068 @item ^-S@var{xxx}^/INITIALIZE_SCALARS=@var{xxx}^
8069 @cindex @option{^-S^/INITIALIZE_SCALARS^} (@command{gnatbind})
8070 Specifies the value to be used when detecting uninitialized scalar
8071 objects with pragma Initialize_Scalars.
8072 The @var{xxx} ^string specified with the switch^option^ may be either
8074 @item ``@option{^in^INVALID^}'' requesting an invalid value where possible
8075 @item ``@option{^lo^LOW^}'' for the lowest possible value
8076 @item ``@option{^hi^HIGH^}'' for the highest possible value
8077 @item ``@option{@var{xx}}'' for a value consisting of repeated bytes with the
8078 value @code{16#@var{xx}#} (i.e., @var{xx} is a string of two hexadecimal digits).
8081 In addition, you can specify @option{-Sev} to indicate that the value is
8082 to be set at run time. In this case, the program will look for an environment
8083 @cindex GNAT_INIT_SCALARS
8084 variable of the form @env{GNAT_INIT_SCALARS=@var{xx}}, where @var{xx} is one
8085 of @option{in/lo/hi/@var{xx}} with the same meanings as above.
8086 If no environment variable is found, or if it does not have a valid value,
8087 then the default is @option{in} (invalid values).
8091 @cindex @option{-static} (@code{gnatbind})
8092 Link against a static GNAT run time.
8095 @cindex @option{-shared} (@code{gnatbind})
8096 Link against a shared GNAT run time when available.
8099 @item ^-t^/NOTIME_STAMP_CHECK^
8100 @cindex @option{^-t^/NOTIME_STAMP_CHECK^} (@code{gnatbind})
8101 Tolerate time stamp and other consistency errors
8103 @item ^-T@var{n}^/TIME_SLICE=@var{n}^
8104 @cindex @option{^-T^/TIME_SLICE^} (@code{gnatbind})
8105 Set the time slice value to @var{n} milliseconds. If the system supports
8106 the specification of a specific time slice value, then the indicated value
8107 is used. If the system does not support specific time slice values, but
8108 does support some general notion of round-robin scheduling, then any
8109 nonzero value will activate round-robin scheduling.
8111 A value of zero is treated specially. It turns off time
8112 slicing, and in addition, indicates to the tasking run time that the
8113 semantics should match as closely as possible the Annex D
8114 requirements of the Ada RM, and in particular sets the default
8115 scheduling policy to @code{FIFO_Within_Priorities}.
8117 @item ^-u@var{n}^/DYNAMIC_STACK_USAGE=@var{n}^
8118 @cindex @option{^-u^/DYNAMIC_STACK_USAGE^} (@code{gnatbind})
8119 Enable dynamic stack usage, with @var{n} results stored and displayed
8120 at program termination. A result is generated when a task
8121 terminates. Results that can't be stored are displayed on the fly, at
8122 task termination. This option is currently not supported on Itanium
8123 platforms. (See @ref{Dynamic Stack Usage Analysis} for details.)
8125 @item ^-v^/REPORT_ERRORS=VERBOSE^
8126 @cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind})
8127 Verbose mode. Write error messages, header, summary output to
8132 @cindex @option{-w} (@code{gnatbind})
8133 Warning mode (@var{x}=s/e for suppress/treat as error)
8137 @item /WARNINGS=NORMAL
8138 @cindex @option{/WARNINGS} (@code{gnatbind})
8139 Normal warnings mode. Warnings are issued but ignored
8141 @item /WARNINGS=SUPPRESS
8142 @cindex @option{/WARNINGS} (@code{gnatbind})
8143 All warning messages are suppressed
8145 @item /WARNINGS=ERROR
8146 @cindex @option{/WARNINGS} (@code{gnatbind})
8147 Warning messages are treated as fatal errors
8150 @item ^-Wx^/WIDE_CHARACTER_ENCODING=^@var{e}
8151 @cindex @option{^-Wx^/WIDE_CHARACTER_ENCODING^} (@code{gnatbind})
8152 Override default wide character encoding for standard Text_IO files.
8154 @item ^-x^/READ_SOURCES=NONE^
8155 @cindex @option{^-x^/READ_SOURCES^} (@code{gnatbind})
8156 Exclude source files (check object consistency only).
8159 @item /READ_SOURCES=AVAILABLE
8160 @cindex @option{/READ_SOURCES} (@code{gnatbind})
8161 Default mode, in which sources are checked for consistency only if
8165 @item ^-y^/ENABLE_LEAP_SECONDS^
8166 @cindex @option{^-y^/ENABLE_LEAP_SECONDS^} (@code{gnatbind})
8167 Enable leap seconds support in @code{Ada.Calendar} and its children.
8169 @item ^-z^/ZERO_MAIN^
8170 @cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind})
8176 You may obtain this listing of switches by running @code{gnatbind} with
8180 @node Consistency-Checking Modes
8181 @subsection Consistency-Checking Modes
8184 As described earlier, by default @code{gnatbind} checks
8185 that object files are consistent with one another and are consistent
8186 with any source files it can locate. The following switches control binder
8191 @item ^-s^/READ_SOURCES=ALL^
8192 @cindex @option{^-s^/READ_SOURCES=ALL^} (@code{gnatbind})
8193 Require source files to be present. In this mode, the binder must be
8194 able to locate all source files that are referenced, in order to check
8195 their consistency. In normal mode, if a source file cannot be located it
8196 is simply ignored. If you specify this switch, a missing source
8199 @item ^-Wx^/WIDE_CHARACTER_ENCODING=^@var{e}
8200 @cindex @option{^-Wx^/WIDE_CHARACTER_ENCODING^} (@code{gnatbind})
8201 Override default wide character encoding for standard Text_IO files.
8202 Normally the default wide character encoding method used for standard
8203 [Wide_[Wide_]]Text_IO files is taken from the encoding specified for
8204 the main source input (see description of switch
8205 @option{^-gnatWx^/WIDE_CHARACTER_ENCODING^} for the compiler). The
8206 use of this switch for the binder (which has the same set of
8207 possible arguments) overrides this default as specified.
8209 @item ^-x^/READ_SOURCES=NONE^
8210 @cindex @option{^-x^/READ_SOURCES=NONE^} (@code{gnatbind})
8211 Exclude source files. In this mode, the binder only checks that ALI
8212 files are consistent with one another. Source files are not accessed.
8213 The binder runs faster in this mode, and there is still a guarantee that
8214 the resulting program is self-consistent.
8215 If a source file has been edited since it was last compiled, and you
8216 specify this switch, the binder will not detect that the object
8217 file is out of date with respect to the source file. Note that this is the
8218 mode that is automatically used by @command{gnatmake} because in this
8219 case the checking against sources has already been performed by
8220 @command{gnatmake} in the course of compilation (i.e.@: before binding).
8223 @item /READ_SOURCES=AVAILABLE
8224 @cindex @code{/READ_SOURCES=AVAILABLE} (@code{gnatbind})
8225 This is the default mode in which source files are checked if they are
8226 available, and ignored if they are not available.
8230 @node Binder Error Message Control
8231 @subsection Binder Error Message Control
8234 The following switches provide control over the generation of error
8235 messages from the binder:
8239 @item ^-v^/REPORT_ERRORS=VERBOSE^
8240 @cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind})
8241 Verbose mode. In the normal mode, brief error messages are generated to
8242 @file{stderr}. If this switch is present, a header is written
8243 to @file{stdout} and any error messages are directed to @file{stdout}.
8244 All that is written to @file{stderr} is a brief summary message.
8246 @item ^-b^/REPORT_ERRORS=BRIEF^
8247 @cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@code{gnatbind})
8248 Generate brief error messages to @file{stderr} even if verbose mode is
8249 specified. This is relevant only when used with the
8250 @option{^-v^/REPORT_ERRORS=VERBOSE^} switch.
8254 @cindex @option{-m} (@code{gnatbind})
8255 Limits the number of error messages to @var{n}, a decimal integer in the
8256 range 1-999. The binder terminates immediately if this limit is reached.
8259 @cindex @option{-M} (@code{gnatbind})
8260 Renames the generated main program from @code{main} to @code{xxx}.
8261 This is useful in the case of some cross-building environments, where
8262 the actual main program is separate from the one generated
8266 @item ^-ws^/WARNINGS=SUPPRESS^
8267 @cindex @option{^-ws^/WARNINGS=SUPPRESS^} (@code{gnatbind})
8269 Suppress all warning messages.
8271 @item ^-we^/WARNINGS=ERROR^
8272 @cindex @option{^-we^/WARNINGS=ERROR^} (@code{gnatbind})
8273 Treat any warning messages as fatal errors.
8276 @item /WARNINGS=NORMAL
8277 Standard mode with warnings generated, but warnings do not get treated
8281 @item ^-t^/NOTIME_STAMP_CHECK^
8282 @cindex @option{^-t^/NOTIME_STAMP_CHECK^} (@code{gnatbind})
8283 @cindex Time stamp checks, in binder
8284 @cindex Binder consistency checks
8285 @cindex Consistency checks, in binder
8286 The binder performs a number of consistency checks including:
8290 Check that time stamps of a given source unit are consistent
8292 Check that checksums of a given source unit are consistent
8294 Check that consistent versions of @code{GNAT} were used for compilation
8296 Check consistency of configuration pragmas as required
8300 Normally failure of such checks, in accordance with the consistency
8301 requirements of the Ada Reference Manual, causes error messages to be
8302 generated which abort the binder and prevent the output of a binder
8303 file and subsequent link to obtain an executable.
8305 The @option{^-t^/NOTIME_STAMP_CHECK^} switch converts these error messages
8306 into warnings, so that
8307 binding and linking can continue to completion even in the presence of such
8308 errors. The result may be a failed link (due to missing symbols), or a
8309 non-functional executable which has undefined semantics.
8310 @emph{This means that
8311 @option{^-t^/NOTIME_STAMP_CHECK^} should be used only in unusual situations,
8315 @node Elaboration Control
8316 @subsection Elaboration Control
8319 The following switches provide additional control over the elaboration
8320 order. For full details see @ref{Elaboration Order Handling in GNAT}.
8323 @item ^-p^/PESSIMISTIC_ELABORATION^
8324 @cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@code{gnatbind})
8325 Normally the binder attempts to choose an elaboration order that is
8326 likely to minimize the likelihood of an elaboration order error resulting
8327 in raising a @code{Program_Error} exception. This switch reverses the
8328 action of the binder, and requests that it deliberately choose an order
8329 that is likely to maximize the likelihood of an elaboration error.
8330 This is useful in ensuring portability and avoiding dependence on
8331 accidental fortuitous elaboration ordering.
8333 Normally it only makes sense to use the @option{^-p^/PESSIMISTIC_ELABORATION^}
8335 elaboration checking is used (@option{-gnatE} switch used for compilation).
8336 This is because in the default static elaboration mode, all necessary
8337 @code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted.
8338 These implicit pragmas are still respected by the binder in
8339 @option{^-p^/PESSIMISTIC_ELABORATION^} mode, so a
8340 safe elaboration order is assured.
8343 @node Output Control
8344 @subsection Output Control
8347 The following switches allow additional control over the output
8348 generated by the binder.
8353 @item ^-A^/BIND_FILE=ADA^
8354 @cindex @option{^-A^/BIND_FILE=ADA^} (@code{gnatbind})
8355 Generate binder program in Ada (default). The binder program is named
8356 @file{b~@var{mainprog}.adb} by default. This can be changed with
8357 @option{^-o^/OUTPUT^} @code{gnatbind} option.
8359 @item ^-c^/NOOUTPUT^
8360 @cindex @option{^-c^/NOOUTPUT^} (@code{gnatbind})
8361 Check only. Do not generate the binder output file. In this mode the
8362 binder performs all error checks but does not generate an output file.
8364 @item ^-C^/BIND_FILE=C^
8365 @cindex @option{^-C^/BIND_FILE=C^} (@code{gnatbind})
8366 Generate binder program in C. The binder program is named
8367 @file{b_@var{mainprog}.c}.
8368 This can be changed with @option{^-o^/OUTPUT^} @code{gnatbind}
8371 @item ^-e^/ELABORATION_DEPENDENCIES^
8372 @cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@code{gnatbind})
8373 Output complete list of elaboration-order dependencies, showing the
8374 reason for each dependency. This output can be rather extensive but may
8375 be useful in diagnosing problems with elaboration order. The output is
8376 written to @file{stdout}.
8379 @cindex @option{^-h^/HELP^} (@code{gnatbind})
8380 Output usage information. The output is written to @file{stdout}.
8382 @item ^-K^/LINKER_OPTION_LIST^
8383 @cindex @option{^-K^/LINKER_OPTION_LIST^} (@code{gnatbind})
8384 Output linker options to @file{stdout}. Includes library search paths,
8385 contents of pragmas Ident and Linker_Options, and libraries added
8388 @item ^-l^/ORDER_OF_ELABORATION^
8389 @cindex @option{^-l^/ORDER_OF_ELABORATION^} (@code{gnatbind})
8390 Output chosen elaboration order. The output is written to @file{stdout}.
8392 @item ^-O^/OBJECT_LIST^
8393 @cindex @option{^-O^/OBJECT_LIST^} (@code{gnatbind})
8394 Output full names of all the object files that must be linked to provide
8395 the Ada component of the program. The output is written to @file{stdout}.
8396 This list includes the files explicitly supplied and referenced by the user
8397 as well as implicitly referenced run-time unit files. The latter are
8398 omitted if the corresponding units reside in shared libraries. The
8399 directory names for the run-time units depend on the system configuration.
8401 @item ^-o ^/OUTPUT=^@var{file}
8402 @cindex @option{^-o^/OUTPUT^} (@code{gnatbind})
8403 Set name of output file to @var{file} instead of the normal
8404 @file{b~@var{mainprog}.adb} default. Note that @var{file} denote the Ada
8405 binder generated body filename. In C mode you would normally give
8406 @var{file} an extension of @file{.c} because it will be a C source program.
8407 Note that if this option is used, then linking must be done manually.
8408 It is not possible to use gnatlink in this case, since it cannot locate
8411 @item ^-r^/RESTRICTION_LIST^
8412 @cindex @option{^-r^/RESTRICTION_LIST^} (@code{gnatbind})
8413 Generate list of @code{pragma Restrictions} that could be applied to
8414 the current unit. This is useful for code audit purposes, and also may
8415 be used to improve code generation in some cases.
8419 @node Binding with Non-Ada Main Programs
8420 @subsection Binding with Non-Ada Main Programs
8423 In our description so far we have assumed that the main
8424 program is in Ada, and that the task of the binder is to generate a
8425 corresponding function @code{main} that invokes this Ada main
8426 program. GNAT also supports the building of executable programs where
8427 the main program is not in Ada, but some of the called routines are
8428 written in Ada and compiled using GNAT (@pxref{Mixed Language Programming}).
8429 The following switch is used in this situation:
8433 @cindex @option{^-n^/NOMAIN^} (@code{gnatbind})
8434 No main program. The main program is not in Ada.
8438 In this case, most of the functions of the binder are still required,
8439 but instead of generating a main program, the binder generates a file
8440 containing the following callable routines:
8445 You must call this routine to initialize the Ada part of the program by
8446 calling the necessary elaboration routines. A call to @code{adainit} is
8447 required before the first call to an Ada subprogram.
8449 Note that it is assumed that the basic execution environment must be setup
8450 to be appropriate for Ada execution at the point where the first Ada
8451 subprogram is called. In particular, if the Ada code will do any
8452 floating-point operations, then the FPU must be setup in an appropriate
8453 manner. For the case of the x86, for example, full precision mode is
8454 required. The procedure GNAT.Float_Control.Reset may be used to ensure
8455 that the FPU is in the right state.
8459 You must call this routine to perform any library-level finalization
8460 required by the Ada subprograms. A call to @code{adafinal} is required
8461 after the last call to an Ada subprogram, and before the program
8466 If the @option{^-n^/NOMAIN^} switch
8467 @cindex @option{^-n^/NOMAIN^} (@command{gnatbind})
8468 @cindex Binder, multiple input files
8469 is given, more than one ALI file may appear on
8470 the command line for @code{gnatbind}. The normal @dfn{closure}
8471 calculation is performed for each of the specified units. Calculating
8472 the closure means finding out the set of units involved by tracing
8473 @code{with} references. The reason it is necessary to be able to
8474 specify more than one ALI file is that a given program may invoke two or
8475 more quite separate groups of Ada units.
8477 The binder takes the name of its output file from the last specified ALI
8478 file, unless overridden by the use of the @option{^-o file^/OUTPUT=file^}.
8479 @cindex @option{^-o^/OUTPUT^} (@command{gnatbind})
8480 The output is an Ada unit in source form that can
8481 be compiled with GNAT unless the -C switch is used in which case the
8482 output is a C source file, which must be compiled using the C compiler.
8483 This compilation occurs automatically as part of the @command{gnatlink}
8486 Currently the GNAT run time requires a FPU using 80 bits mode
8487 precision. Under targets where this is not the default it is required to
8488 call GNAT.Float_Control.Reset before using floating point numbers (this
8489 include float computation, float input and output) in the Ada code. A
8490 side effect is that this could be the wrong mode for the foreign code
8491 where floating point computation could be broken after this call.
8493 @node Binding Programs with No Main Subprogram
8494 @subsection Binding Programs with No Main Subprogram
8497 It is possible to have an Ada program which does not have a main
8498 subprogram. This program will call the elaboration routines of all the
8499 packages, then the finalization routines.
8501 The following switch is used to bind programs organized in this manner:
8504 @item ^-z^/ZERO_MAIN^
8505 @cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind})
8506 Normally the binder checks that the unit name given on the command line
8507 corresponds to a suitable main subprogram. When this switch is used,
8508 a list of ALI files can be given, and the execution of the program
8509 consists of elaboration of these units in an appropriate order. Note
8510 that the default wide character encoding method for standard Text_IO
8511 files is always set to Brackets if this switch is set (you can use
8513 @option{^-Wx^WIDE_CHARACTER_ENCODING^} to override this default).
8516 @node Command-Line Access
8517 @section Command-Line Access
8520 The package @code{Ada.Command_Line} provides access to the command-line
8521 arguments and program name. In order for this interface to operate
8522 correctly, the two variables
8534 are declared in one of the GNAT library routines. These variables must
8535 be set from the actual @code{argc} and @code{argv} values passed to the
8536 main program. With no @option{^n^/NOMAIN^} present, @code{gnatbind}
8537 generates the C main program to automatically set these variables.
8538 If the @option{^n^/NOMAIN^} switch is used, there is no automatic way to
8539 set these variables. If they are not set, the procedures in
8540 @code{Ada.Command_Line} will not be available, and any attempt to use
8541 them will raise @code{Constraint_Error}. If command line access is
8542 required, your main program must set @code{gnat_argc} and
8543 @code{gnat_argv} from the @code{argc} and @code{argv} values passed to
8546 @node Search Paths for gnatbind
8547 @section Search Paths for @code{gnatbind}
8550 The binder takes the name of an ALI file as its argument and needs to
8551 locate source files as well as other ALI files to verify object consistency.
8553 For source files, it follows exactly the same search rules as @command{gcc}
8554 (@pxref{Search Paths and the Run-Time Library (RTL)}). For ALI files the
8555 directories searched are:
8559 The directory containing the ALI file named in the command line, unless
8560 the switch @option{^-I-^/NOCURRENT_DIRECTORY^} is specified.
8563 All directories specified by @option{^-I^/SEARCH^}
8564 switches on the @code{gnatbind}
8565 command line, in the order given.
8568 @findex ADA_PRJ_OBJECTS_FILE
8569 Each of the directories listed in the text file whose name is given
8570 by the @env{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
8573 @env{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
8574 driver when project files are used. It should not normally be set
8578 @findex ADA_OBJECTS_PATH
8579 Each of the directories listed in the value of the
8580 @env{ADA_OBJECTS_PATH} ^environment variable^logical name^.
8582 Construct this value
8583 exactly as the @env{PATH} environment variable: a list of directory
8584 names separated by colons (semicolons when working with the NT version
8588 Normally, define this value as a logical name containing a comma separated
8589 list of directory names.
8591 This variable can also be defined by means of an environment string
8592 (an argument to the HP C exec* set of functions).
8596 DEFINE ANOTHER_PATH FOO:[BAG]
8597 DEFINE ADA_OBJECTS_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR]
8600 By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB]
8601 first, followed by the standard Ada
8602 libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB].
8603 If this is not redefined, the user will obtain the HP Ada 83 IO packages
8604 (Text_IO, Sequential_IO, etc)
8605 instead of the standard Ada packages. Thus, in order to get the standard Ada
8606 packages by default, ADA_OBJECTS_PATH must be redefined.
8610 The content of the @file{ada_object_path} file which is part of the GNAT
8611 installation tree and is used to store standard libraries such as the
8612 GNAT Run Time Library (RTL) unless the switch @option{-nostdlib} is
8615 @ref{Installing a library}
8620 In the binder the switch @option{^-I^/SEARCH^}
8621 @cindex @option{^-I^/SEARCH^} (@command{gnatbind})
8622 is used to specify both source and
8623 library file paths. Use @option{^-aI^/SOURCE_SEARCH^}
8624 @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind})
8625 instead if you want to specify
8626 source paths only, and @option{^-aO^/LIBRARY_SEARCH^}
8627 @cindex @option{^-aO^/LIBRARY_SEARCH^} (@command{gnatbind})
8628 if you want to specify library paths
8629 only. This means that for the binder
8630 @option{^-I^/SEARCH=^}@var{dir} is equivalent to
8631 @option{^-aI^/SOURCE_SEARCH=^}@var{dir}
8632 @option{^-aO^/OBJECT_SEARCH=^}@var{dir}.
8633 The binder generates the bind file (a C language source file) in the
8634 current working directory.
8640 The packages @code{Ada}, @code{System}, and @code{Interfaces} and their
8641 children make up the GNAT Run-Time Library, together with the package
8642 GNAT and its children, which contain a set of useful additional
8643 library functions provided by GNAT. The sources for these units are
8644 needed by the compiler and are kept together in one directory. The ALI
8645 files and object files generated by compiling the RTL are needed by the
8646 binder and the linker and are kept together in one directory, typically
8647 different from the directory containing the sources. In a normal
8648 installation, you need not specify these directory names when compiling
8649 or binding. Either the environment variables or the built-in defaults
8650 cause these files to be found.
8652 Besides simplifying access to the RTL, a major use of search paths is
8653 in compiling sources from multiple directories. This can make
8654 development environments much more flexible.
8656 @node Examples of gnatbind Usage
8657 @section Examples of @code{gnatbind} Usage
8660 This section contains a number of examples of using the GNAT binding
8661 utility @code{gnatbind}.
8664 @item gnatbind hello
8665 The main program @code{Hello} (source program in @file{hello.adb}) is
8666 bound using the standard switch settings. The generated main program is
8667 @file{b~hello.adb}. This is the normal, default use of the binder.
8670 @item gnatbind hello -o mainprog.adb
8673 @item gnatbind HELLO.ALI /OUTPUT=Mainprog.ADB
8675 The main program @code{Hello} (source program in @file{hello.adb}) is
8676 bound using the standard switch settings. The generated main program is
8677 @file{mainprog.adb} with the associated spec in
8678 @file{mainprog.ads}. Note that you must specify the body here not the
8679 spec, in the case where the output is in Ada. Note that if this option
8680 is used, then linking must be done manually, since gnatlink will not
8681 be able to find the generated file.
8684 @item gnatbind main -C -o mainprog.c -x
8687 @item gnatbind MAIN.ALI /BIND_FILE=C /OUTPUT=Mainprog.C /READ_SOURCES=NONE
8689 The main program @code{Main} (source program in
8690 @file{main.adb}) is bound, excluding source files from the
8691 consistency checking, generating
8692 the file @file{mainprog.c}.
8695 @item gnatbind -x main_program -C -o mainprog.c
8696 This command is exactly the same as the previous example. Switches may
8697 appear anywhere in the command line, and single letter switches may be
8698 combined into a single switch.
8702 @item gnatbind -n math dbase -C -o ada-control.c
8705 @item gnatbind /NOMAIN math dbase /BIND_FILE=C /OUTPUT=ada-control.c
8707 The main program is in a language other than Ada, but calls to
8708 subprograms in packages @code{Math} and @code{Dbase} appear. This call
8709 to @code{gnatbind} generates the file @file{ada-control.c} containing
8710 the @code{adainit} and @code{adafinal} routines to be called before and
8711 after accessing the Ada units.
8714 @c ------------------------------------
8715 @node Linking Using gnatlink
8716 @chapter Linking Using @command{gnatlink}
8717 @c ------------------------------------
8721 This chapter discusses @command{gnatlink}, a tool that links
8722 an Ada program and builds an executable file. This utility
8723 invokes the system linker ^(via the @command{gcc} command)^^
8724 with a correct list of object files and library references.
8725 @command{gnatlink} automatically determines the list of files and
8726 references for the Ada part of a program. It uses the binder file
8727 generated by the @command{gnatbind} to determine this list.
8729 Note: to invoke @code{gnatlink} with a project file, use the @code{gnat}
8730 driver (see @ref{The GNAT Driver and Project Files}).
8733 * Running gnatlink::
8734 * Switches for gnatlink::
8737 @node Running gnatlink
8738 @section Running @command{gnatlink}
8741 The form of the @command{gnatlink} command is
8744 $ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]}
8745 @ovar{non-Ada objects} @ovar{linker options}
8749 The arguments of @command{gnatlink} (switches, main @file{ALI} file,
8751 or linker options) may be in any order, provided that no non-Ada object may
8752 be mistaken for a main @file{ALI} file.
8753 Any file name @file{F} without the @file{.ali}
8754 extension will be taken as the main @file{ALI} file if a file exists
8755 whose name is the concatenation of @file{F} and @file{.ali}.
8758 @file{@var{mainprog}.ali} references the ALI file of the main program.
8759 The @file{.ali} extension of this file can be omitted. From this
8760 reference, @command{gnatlink} locates the corresponding binder file
8761 @file{b~@var{mainprog}.adb} and, using the information in this file along
8762 with the list of non-Ada objects and linker options, constructs a
8763 linker command file to create the executable.
8765 The arguments other than the @command{gnatlink} switches and the main
8766 @file{ALI} file are passed to the linker uninterpreted.
8767 They typically include the names of
8768 object files for units written in other languages than Ada and any library
8769 references required to resolve references in any of these foreign language
8770 units, or in @code{Import} pragmas in any Ada units.
8772 @var{linker options} is an optional list of linker specific
8774 The default linker called by gnatlink is @command{gcc} which in
8775 turn calls the appropriate system linker.
8776 Standard options for the linker such as @option{-lmy_lib} or
8777 @option{-Ldir} can be added as is.
8778 For options that are not recognized by
8779 @command{gcc} as linker options, use the @command{gcc} switches
8780 @option{-Xlinker} or @option{-Wl,}.
8781 Refer to the GCC documentation for
8782 details. Here is an example showing how to generate a linker map:
8785 $ ^gnatlink my_prog -Wl,-Map,MAPFILE^GNAT LINK my_prog.ali /MAP^
8788 Using @var{linker options} it is possible to set the program stack and
8791 See @ref{Setting Stack Size from gnatlink} and
8792 @ref{Setting Heap Size from gnatlink}.
8795 @command{gnatlink} determines the list of objects required by the Ada
8796 program and prepends them to the list of objects passed to the linker.
8797 @command{gnatlink} also gathers any arguments set by the use of
8798 @code{pragma Linker_Options} and adds them to the list of arguments
8799 presented to the linker.
8802 @command{gnatlink} accepts the following types of extra files on the command
8803 line: objects (@file{.OBJ}), libraries (@file{.OLB}), sharable images
8804 (@file{.EXE}), and options files (@file{.OPT}). These are recognized and
8805 handled according to their extension.
8808 @node Switches for gnatlink
8809 @section Switches for @command{gnatlink}
8812 The following switches are available with the @command{gnatlink} utility:
8818 @cindex @option{--version} @command{gnatlink}
8819 Display Copyright and version, then exit disregarding all other options.
8822 @cindex @option{--help} @command{gnatlink}
8823 If @option{--version} was not used, display usage, then exit disregarding
8826 @item ^-A^/BIND_FILE=ADA^
8827 @cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatlink})
8828 The binder has generated code in Ada. This is the default.
8830 @item ^-C^/BIND_FILE=C^
8831 @cindex @option{^-C^/BIND_FILE=C^} (@command{gnatlink})
8832 If instead of generating a file in Ada, the binder has generated one in
8833 C, then the linker needs to know about it. Use this switch to signal
8834 to @command{gnatlink} that the binder has generated C code rather than
8837 @item ^-f^/FORCE_OBJECT_FILE_LIST^
8838 @cindex Command line length
8839 @cindex @option{^-f^/FORCE_OBJECT_FILE_LIST^} (@command{gnatlink})
8840 On some targets, the command line length is limited, and @command{gnatlink}
8841 will generate a separate file for the linker if the list of object files
8843 The @option{^-f^/FORCE_OBJECT_FILE_LIST^} switch forces this file
8844 to be generated even if
8845 the limit is not exceeded. This is useful in some cases to deal with
8846 special situations where the command line length is exceeded.
8849 @cindex Debugging information, including
8850 @cindex @option{^-g^/DEBUG^} (@command{gnatlink})
8851 The option to include debugging information causes the Ada bind file (in
8852 other words, @file{b~@var{mainprog}.adb}) to be compiled with
8853 @option{^-g^/DEBUG^}.
8854 In addition, the binder does not delete the @file{b~@var{mainprog}.adb},
8855 @file{b~@var{mainprog}.o} and @file{b~@var{mainprog}.ali} files.
8856 Without @option{^-g^/DEBUG^}, the binder removes these files by
8857 default. The same procedure apply if a C bind file was generated using
8858 @option{^-C^/BIND_FILE=C^} @code{gnatbind} option, in this case the filenames
8859 are @file{b_@var{mainprog}.c} and @file{b_@var{mainprog}.o}.
8861 @item ^-n^/NOCOMPILE^
8862 @cindex @option{^-n^/NOCOMPILE^} (@command{gnatlink})
8863 Do not compile the file generated by the binder. This may be used when
8864 a link is rerun with different options, but there is no need to recompile
8868 @cindex @option{^-v^/VERBOSE^} (@command{gnatlink})
8869 Causes additional information to be output, including a full list of the
8870 included object files. This switch option is most useful when you want
8871 to see what set of object files are being used in the link step.
8873 @item ^-v -v^/VERBOSE/VERBOSE^
8874 @cindex @option{^-v -v^/VERBOSE/VERBOSE^} (@command{gnatlink})
8875 Very verbose mode. Requests that the compiler operate in verbose mode when
8876 it compiles the binder file, and that the system linker run in verbose mode.
8878 @item ^-o ^/EXECUTABLE=^@var{exec-name}
8879 @cindex @option{^-o^/EXECUTABLE^} (@command{gnatlink})
8880 @var{exec-name} specifies an alternate name for the generated
8881 executable program. If this switch is omitted, the executable has the same
8882 name as the main unit. For example, @code{gnatlink try.ali} creates
8883 an executable called @file{^try^TRY.EXE^}.
8886 @item -b @var{target}
8887 @cindex @option{-b} (@command{gnatlink})
8888 Compile your program to run on @var{target}, which is the name of a
8889 system configuration. You must have a GNAT cross-compiler built if
8890 @var{target} is not the same as your host system.
8893 @cindex @option{-B} (@command{gnatlink})
8894 Load compiler executables (for example, @code{gnat1}, the Ada compiler)
8895 from @var{dir} instead of the default location. Only use this switch
8896 when multiple versions of the GNAT compiler are available.
8897 @xref{Directory Options,,, gcc, The GNU Compiler Collection},
8898 for further details. You would normally use the @option{-b} or
8899 @option{-V} switch instead.
8901 @item --GCC=@var{compiler_name}
8902 @cindex @option{--GCC=compiler_name} (@command{gnatlink})
8903 Program used for compiling the binder file. The default is
8904 @command{gcc}. You need to use quotes around @var{compiler_name} if
8905 @code{compiler_name} contains spaces or other separator characters.
8906 As an example @option{--GCC="foo -x -y"} will instruct @command{gnatlink} to
8907 use @code{foo -x -y} as your compiler. Note that switch @option{-c} is always
8908 inserted after your command name. Thus in the above example the compiler
8909 command that will be used by @command{gnatlink} will be @code{foo -c -x -y}.
8910 A limitation of this syntax is that the name and path name of the executable
8911 itself must not include any embedded spaces. If the compiler executable is
8912 different from the default one (gcc or <prefix>-gcc), then the back-end
8913 switches in the ALI file are not used to compile the binder generated source.
8914 For example, this is the case with @option{--GCC="foo -x -y"}. But the back end
8915 switches will be used for @option{--GCC="gcc -gnatv"}. If several
8916 @option{--GCC=compiler_name} are used, only the last @var{compiler_name}
8917 is taken into account. However, all the additional switches are also taken
8919 @option{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to
8920 @option{--GCC="bar -x -y -z -t"}.
8922 @item --LINK=@var{name}
8923 @cindex @option{--LINK=} (@command{gnatlink})
8924 @var{name} is the name of the linker to be invoked. This is especially
8925 useful in mixed language programs since languages such as C++ require
8926 their own linker to be used. When this switch is omitted, the default
8927 name for the linker is @command{gcc}. When this switch is used, the
8928 specified linker is called instead of @command{gcc} with exactly the same
8929 parameters that would have been passed to @command{gcc} so if the desired
8930 linker requires different parameters it is necessary to use a wrapper
8931 script that massages the parameters before invoking the real linker. It
8932 may be useful to control the exact invocation by using the verbose
8938 @item /DEBUG=TRACEBACK
8939 @cindex @code{/DEBUG=TRACEBACK} (@command{gnatlink})
8940 This qualifier causes sufficient information to be included in the
8941 executable file to allow a traceback, but does not include the full
8942 symbol information needed by the debugger.
8944 @item /IDENTIFICATION="<string>"
8945 @code{"<string>"} specifies the string to be stored in the image file
8946 identification field in the image header.
8947 It overrides any pragma @code{Ident} specified string.
8949 @item /NOINHIBIT-EXEC
8950 Generate the executable file even if there are linker warnings.
8952 @item /NOSTART_FILES
8953 Don't link in the object file containing the ``main'' transfer address.
8954 Used when linking with a foreign language main program compiled with an
8958 Prefer linking with object libraries over sharable images, even without
8964 @node The GNAT Make Program gnatmake
8965 @chapter The GNAT Make Program @command{gnatmake}
8969 * Running gnatmake::
8970 * Switches for gnatmake::
8971 * Mode Switches for gnatmake::
8972 * Notes on the Command Line::
8973 * How gnatmake Works::
8974 * Examples of gnatmake Usage::
8977 A typical development cycle when working on an Ada program consists of
8978 the following steps:
8982 Edit some sources to fix bugs.
8988 Compile all sources affected.
8998 The third step can be tricky, because not only do the modified files
8999 @cindex Dependency rules
9000 have to be compiled, but any files depending on these files must also be
9001 recompiled. The dependency rules in Ada can be quite complex, especially
9002 in the presence of overloading, @code{use} clauses, generics and inlined
9005 @command{gnatmake} automatically takes care of the third and fourth steps
9006 of this process. It determines which sources need to be compiled,
9007 compiles them, and binds and links the resulting object files.
9009 Unlike some other Ada make programs, the dependencies are always
9010 accurately recomputed from the new sources. The source based approach of
9011 the GNAT compilation model makes this possible. This means that if
9012 changes to the source program cause corresponding changes in
9013 dependencies, they will always be tracked exactly correctly by
9016 @node Running gnatmake
9017 @section Running @command{gnatmake}
9020 The usual form of the @command{gnatmake} command is
9023 $ gnatmake @ovar{switches} @var{file_name}
9024 @ovar{file_names} @ovar{mode_switches}
9028 The only required argument is one @var{file_name}, which specifies
9029 a compilation unit that is a main program. Several @var{file_names} can be
9030 specified: this will result in several executables being built.
9031 If @code{switches} are present, they can be placed before the first
9032 @var{file_name}, between @var{file_names} or after the last @var{file_name}.
9033 If @var{mode_switches} are present, they must always be placed after
9034 the last @var{file_name} and all @code{switches}.
9036 If you are using standard file extensions (@file{.adb} and @file{.ads}), then the
9037 extension may be omitted from the @var{file_name} arguments. However, if
9038 you are using non-standard extensions, then it is required that the
9039 extension be given. A relative or absolute directory path can be
9040 specified in a @var{file_name}, in which case, the input source file will
9041 be searched for in the specified directory only. Otherwise, the input
9042 source file will first be searched in the directory where
9043 @command{gnatmake} was invoked and if it is not found, it will be search on
9044 the source path of the compiler as described in
9045 @ref{Search Paths and the Run-Time Library (RTL)}.
9047 All @command{gnatmake} output (except when you specify
9048 @option{^-M^/DEPENDENCIES_LIST^}) is to
9049 @file{stderr}. The output produced by the
9050 @option{^-M^/DEPENDENCIES_LIST^} switch is send to
9053 @node Switches for gnatmake
9054 @section Switches for @command{gnatmake}
9057 You may specify any of the following switches to @command{gnatmake}:
9063 @cindex @option{--version} @command{gnatmake}
9064 Display Copyright and version, then exit disregarding all other options.
9067 @cindex @option{--help} @command{gnatmake}
9068 If @option{--version} was not used, display usage, then exit disregarding
9072 @item --GCC=@var{compiler_name}
9073 @cindex @option{--GCC=compiler_name} (@command{gnatmake})
9074 Program used for compiling. The default is `@command{gcc}'. You need to use
9075 quotes around @var{compiler_name} if @code{compiler_name} contains
9076 spaces or other separator characters. As an example @option{--GCC="foo -x
9077 -y"} will instruct @command{gnatmake} to use @code{foo -x -y} as your
9078 compiler. A limitation of this syntax is that the name and path name of
9079 the executable itself must not include any embedded spaces. Note that
9080 switch @option{-c} is always inserted after your command name. Thus in the
9081 above example the compiler command that will be used by @command{gnatmake}
9082 will be @code{foo -c -x -y}. If several @option{--GCC=compiler_name} are
9083 used, only the last @var{compiler_name} is taken into account. However,
9084 all the additional switches are also taken into account. Thus,
9085 @option{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to
9086 @option{--GCC="bar -x -y -z -t"}.
9088 @item --GNATBIND=@var{binder_name}
9089 @cindex @option{--GNATBIND=binder_name} (@command{gnatmake})
9090 Program used for binding. The default is `@code{gnatbind}'. You need to
9091 use quotes around @var{binder_name} if @var{binder_name} contains spaces
9092 or other separator characters. As an example @option{--GNATBIND="bar -x
9093 -y"} will instruct @command{gnatmake} to use @code{bar -x -y} as your
9094 binder. Binder switches that are normally appended by @command{gnatmake}
9095 to `@code{gnatbind}' are now appended to the end of @code{bar -x -y}.
9096 A limitation of this syntax is that the name and path name of the executable
9097 itself must not include any embedded spaces.
9099 @item --GNATLINK=@var{linker_name}
9100 @cindex @option{--GNATLINK=linker_name} (@command{gnatmake})
9101 Program used for linking. The default is `@command{gnatlink}'. You need to
9102 use quotes around @var{linker_name} if @var{linker_name} contains spaces
9103 or other separator characters. As an example @option{--GNATLINK="lan -x
9104 -y"} will instruct @command{gnatmake} to use @code{lan -x -y} as your
9105 linker. Linker switches that are normally appended by @command{gnatmake} to
9106 `@command{gnatlink}' are now appended to the end of @code{lan -x -y}.
9107 A limitation of this syntax is that the name and path name of the executable
9108 itself must not include any embedded spaces.
9112 @item ^-a^/ALL_FILES^
9113 @cindex @option{^-a^/ALL_FILES^} (@command{gnatmake})
9114 Consider all files in the make process, even the GNAT internal system
9115 files (for example, the predefined Ada library files), as well as any
9116 locked files. Locked files are files whose ALI file is write-protected.
9118 @command{gnatmake} does not check these files,
9119 because the assumption is that the GNAT internal files are properly up
9120 to date, and also that any write protected ALI files have been properly
9121 installed. Note that if there is an installation problem, such that one
9122 of these files is not up to date, it will be properly caught by the
9124 You may have to specify this switch if you are working on GNAT
9125 itself. The switch @option{^-a^/ALL_FILES^} is also useful
9126 in conjunction with @option{^-f^/FORCE_COMPILE^}
9127 if you need to recompile an entire application,
9128 including run-time files, using special configuration pragmas,
9129 such as a @code{Normalize_Scalars} pragma.
9132 @code{gnatmake ^-a^/ALL_FILES^} compiles all GNAT
9135 @code{gcc -c -gnatpg} rather than @code{gcc -c}.
9138 the @code{/CHECKS=SUPPRESS_ALL /STYLE_CHECKS=GNAT} switch.
9141 @item ^-b^/ACTIONS=BIND^
9142 @cindex @option{^-b^/ACTIONS=BIND^} (@command{gnatmake})
9143 Bind only. Can be combined with @option{^-c^/ACTIONS=COMPILE^} to do
9144 compilation and binding, but no link.
9145 Can be combined with @option{^-l^/ACTIONS=LINK^}
9146 to do binding and linking. When not combined with
9147 @option{^-c^/ACTIONS=COMPILE^}
9148 all the units in the closure of the main program must have been previously
9149 compiled and must be up to date. The root unit specified by @var{file_name}
9150 may be given without extension, with the source extension or, if no GNAT
9151 Project File is specified, with the ALI file extension.
9153 @item ^-c^/ACTIONS=COMPILE^
9154 @cindex @option{^-c^/ACTIONS=COMPILE^} (@command{gnatmake})
9155 Compile only. Do not perform binding, except when @option{^-b^/ACTIONS=BIND^}
9156 is also specified. Do not perform linking, except if both
9157 @option{^-b^/ACTIONS=BIND^} and
9158 @option{^-l^/ACTIONS=LINK^} are also specified.
9159 If the root unit specified by @var{file_name} is not a main unit, this is the
9160 default. Otherwise @command{gnatmake} will attempt binding and linking
9161 unless all objects are up to date and the executable is more recent than
9165 @cindex @option{^-C^/MAPPING^} (@command{gnatmake})
9166 Use a temporary mapping file. A mapping file is a way to communicate to the
9167 compiler two mappings: from unit names to file names (without any directory
9168 information) and from file names to path names (with full directory
9169 information). These mappings are used by the compiler to short-circuit the path
9170 search. When @command{gnatmake} is invoked with this switch, it will create
9171 a temporary mapping file, initially populated by the project manager,
9172 if @option{^-P^/PROJECT_FILE^} is used, otherwise initially empty.
9173 Each invocation of the compiler will add the newly accessed sources to the
9174 mapping file. This will improve the source search during the next invocation
9177 @item ^-C=^/USE_MAPPING_FILE=^@var{file}
9178 @cindex @option{^-C=^/USE_MAPPING^} (@command{gnatmake})
9179 Use a specific mapping file. The file, specified as a path name (absolute or
9180 relative) by this switch, should already exist, otherwise the switch is
9181 ineffective. The specified mapping file will be communicated to the compiler.
9182 This switch is not compatible with a project file
9183 (^-P^/PROJECT_FILE=^@var{file}) or with multiple compiling processes
9184 (^-j^/PROCESSES=^nnn, when nnn is greater than 1).
9186 @item ^-d^/DISPLAY_PROGRESS^
9187 @cindex @option{^-d^/DISPLAY_PROGRESS^} (@command{gnatmake})
9188 Display progress for each source, up to date or not, as a single line
9191 completed x out of y (zz%)
9194 If the file needs to be compiled this is displayed after the invocation of
9195 the compiler. These lines are displayed even in quiet output mode.
9197 @item ^-D ^/DIRECTORY_OBJECTS=^@var{dir}
9198 @cindex @option{^-D^/DIRECTORY_OBJECTS^} (@command{gnatmake})
9199 Put all object files and ALI file in directory @var{dir}.
9200 If the @option{^-D^/DIRECTORY_OBJECTS^} switch is not used, all object files
9201 and ALI files go in the current working directory.
9203 This switch cannot be used when using a project file.
9207 @cindex @option{-eL} (@command{gnatmake})
9208 Follow all symbolic links when processing project files.
9211 @item ^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^
9212 @cindex @option{^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^} (@command{gnatmake})
9213 Output the commands for the compiler, the binder and the linker
9214 on ^standard output^SYS$OUTPUT^,
9215 instead of ^standard error^SYS$ERROR^.
9217 @item ^-f^/FORCE_COMPILE^
9218 @cindex @option{^-f^/FORCE_COMPILE^} (@command{gnatmake})
9219 Force recompilations. Recompile all sources, even though some object
9220 files may be up to date, but don't recompile predefined or GNAT internal
9221 files or locked files (files with a write-protected ALI file),
9222 unless the @option{^-a^/ALL_FILES^} switch is also specified.
9224 @item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^
9225 @cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@command{gnatmake})
9226 When using project files, if some errors or warnings are detected during
9227 parsing and verbose mode is not in effect (no use of switch
9228 ^-v^/VERBOSE^), then error lines start with the full path name of the project
9229 file, rather than its simple file name.
9232 @cindex @option{^-g^/DEBUG^} (@command{gnatmake})
9233 Enable debugging. This switch is simply passed to the compiler and to the
9236 @item ^-i^/IN_PLACE^
9237 @cindex @option{^-i^/IN_PLACE^} (@command{gnatmake})
9238 In normal mode, @command{gnatmake} compiles all object files and ALI files
9239 into the current directory. If the @option{^-i^/IN_PLACE^} switch is used,
9240 then instead object files and ALI files that already exist are overwritten
9241 in place. This means that once a large project is organized into separate
9242 directories in the desired manner, then @command{gnatmake} will automatically
9243 maintain and update this organization. If no ALI files are found on the
9244 Ada object path (@ref{Search Paths and the Run-Time Library (RTL)}),
9245 the new object and ALI files are created in the
9246 directory containing the source being compiled. If another organization
9247 is desired, where objects and sources are kept in different directories,
9248 a useful technique is to create dummy ALI files in the desired directories.
9249 When detecting such a dummy file, @command{gnatmake} will be forced to
9250 recompile the corresponding source file, and it will be put the resulting
9251 object and ALI files in the directory where it found the dummy file.
9253 @item ^-j^/PROCESSES=^@var{n}
9254 @cindex @option{^-j^/PROCESSES^} (@command{gnatmake})
9255 @cindex Parallel make
9256 Use @var{n} processes to carry out the (re)compilations. On a
9257 multiprocessor machine compilations will occur in parallel. In the
9258 event of compilation errors, messages from various compilations might
9259 get interspersed (but @command{gnatmake} will give you the full ordered
9260 list of failing compiles at the end). If this is problematic, rerun
9261 the make process with n set to 1 to get a clean list of messages.
9263 @item ^-k^/CONTINUE_ON_ERROR^
9264 @cindex @option{^-k^/CONTINUE_ON_ERROR^} (@command{gnatmake})
9265 Keep going. Continue as much as possible after a compilation error. To
9266 ease the programmer's task in case of compilation errors, the list of
9267 sources for which the compile fails is given when @command{gnatmake}
9270 If @command{gnatmake} is invoked with several @file{file_names} and with this
9271 switch, if there are compilation errors when building an executable,
9272 @command{gnatmake} will not attempt to build the following executables.
9274 @item ^-l^/ACTIONS=LINK^
9275 @cindex @option{^-l^/ACTIONS=LINK^} (@command{gnatmake})
9276 Link only. Can be combined with @option{^-b^/ACTIONS=BIND^} to binding
9277 and linking. Linking will not be performed if combined with
9278 @option{^-c^/ACTIONS=COMPILE^}
9279 but not with @option{^-b^/ACTIONS=BIND^}.
9280 When not combined with @option{^-b^/ACTIONS=BIND^}
9281 all the units in the closure of the main program must have been previously
9282 compiled and must be up to date, and the main program needs to have been bound.
9283 The root unit specified by @var{file_name}
9284 may be given without extension, with the source extension or, if no GNAT
9285 Project File is specified, with the ALI file extension.
9287 @item ^-m^/MINIMAL_RECOMPILATION^
9288 @cindex @option{^-m^/MINIMAL_RECOMPILATION^} (@command{gnatmake})
9289 Specify that the minimum necessary amount of recompilations
9290 be performed. In this mode @command{gnatmake} ignores time
9291 stamp differences when the only
9292 modifications to a source file consist in adding/removing comments,
9293 empty lines, spaces or tabs. This means that if you have changed the
9294 comments in a source file or have simply reformatted it, using this
9295 switch will tell @command{gnatmake} not to recompile files that depend on it
9296 (provided other sources on which these files depend have undergone no
9297 semantic modifications). Note that the debugging information may be
9298 out of date with respect to the sources if the @option{-m} switch causes
9299 a compilation to be switched, so the use of this switch represents a
9300 trade-off between compilation time and accurate debugging information.
9302 @item ^-M^/DEPENDENCIES_LIST^
9303 @cindex Dependencies, producing list
9304 @cindex @option{^-M^/DEPENDENCIES_LIST^} (@command{gnatmake})
9305 Check if all objects are up to date. If they are, output the object
9306 dependences to @file{stdout} in a form that can be directly exploited in
9307 a @file{Makefile}. By default, each source file is prefixed with its
9308 (relative or absolute) directory name. This name is whatever you
9309 specified in the various @option{^-aI^/SOURCE_SEARCH^}
9310 and @option{^-I^/SEARCH^} switches. If you use
9311 @code{gnatmake ^-M^/DEPENDENCIES_LIST^}
9312 @option{^-q^/QUIET^}
9313 (see below), only the source file names,
9314 without relative paths, are output. If you just specify the
9315 @option{^-M^/DEPENDENCIES_LIST^}
9316 switch, dependencies of the GNAT internal system files are omitted. This
9317 is typically what you want. If you also specify
9318 the @option{^-a^/ALL_FILES^} switch,
9319 dependencies of the GNAT internal files are also listed. Note that
9320 dependencies of the objects in external Ada libraries (see switch
9321 @option{^-aL^/SKIP_MISSING=^}@var{dir} in the following list)
9324 @item ^-n^/DO_OBJECT_CHECK^
9325 @cindex @option{^-n^/DO_OBJECT_CHECK^} (@command{gnatmake})
9326 Don't compile, bind, or link. Checks if all objects are up to date.
9327 If they are not, the full name of the first file that needs to be
9328 recompiled is printed.
9329 Repeated use of this option, followed by compiling the indicated source
9330 file, will eventually result in recompiling all required units.
9332 @item ^-o ^/EXECUTABLE=^@var{exec_name}
9333 @cindex @option{^-o^/EXECUTABLE^} (@command{gnatmake})
9334 Output executable name. The name of the final executable program will be
9335 @var{exec_name}. If the @option{^-o^/EXECUTABLE^} switch is omitted the default
9336 name for the executable will be the name of the input file in appropriate form
9337 for an executable file on the host system.
9339 This switch cannot be used when invoking @command{gnatmake} with several
9342 @item ^-p or --create-missing-dirs^/CREATE_MISSING_DIRS^
9343 @cindex @option{^-p^/CREATE_MISSING_DIRS^} (@command{gnatmake})
9344 When using project files (^-P^/PROJECT_FILE=^@var{project}), create
9345 automatically missing object directories, library directories and exec
9348 @item ^-P^/PROJECT_FILE=^@var{project}
9349 @cindex @option{^-P^/PROJECT_FILE^} (@command{gnatmake})
9350 Use project file @var{project}. Only one such switch can be used.
9351 @xref{gnatmake and Project Files}.
9354 @cindex @option{^-q^/QUIET^} (@command{gnatmake})
9355 Quiet. When this flag is not set, the commands carried out by
9356 @command{gnatmake} are displayed.
9358 @item ^-s^/SWITCH_CHECK/^
9359 @cindex @option{^-s^/SWITCH_CHECK^} (@command{gnatmake})
9360 Recompile if compiler switches have changed since last compilation.
9361 All compiler switches but -I and -o are taken into account in the
9363 orders between different ``first letter'' switches are ignored, but
9364 orders between same switches are taken into account. For example,
9365 @option{-O -O2} is different than @option{-O2 -O}, but @option{-g -O}
9366 is equivalent to @option{-O -g}.
9368 This switch is recommended when Integrated Preprocessing is used.
9371 @cindex @option{^-u^/UNIQUE^} (@command{gnatmake})
9372 Unique. Recompile at most the main files. It implies -c. Combined with
9373 -f, it is equivalent to calling the compiler directly. Note that using
9374 ^-u^/UNIQUE^ with a project file and no main has a special meaning
9375 (@pxref{Project Files and Main Subprograms}).
9377 @item ^-U^/ALL_PROJECTS^
9378 @cindex @option{^-U^/ALL_PROJECTS^} (@command{gnatmake})
9379 When used without a project file or with one or several mains on the command
9380 line, is equivalent to ^-u^/UNIQUE^. When used with a project file and no main
9381 on the command line, all sources of all project files are checked and compiled
9382 if not up to date, and libraries are rebuilt, if necessary.
9385 @cindex @option{^-v^/REASONS^} (@command{gnatmake})
9386 Verbose. Display the reason for all recompilations @command{gnatmake}
9387 decides are necessary, with the highest verbosity level.
9389 @item ^-vl^/LOW_VERBOSITY^
9390 @cindex @option{^-vl^/LOW_VERBOSITY^} (@command{gnatmake})
9391 Verbosity level Low. Display fewer lines than in verbosity Medium.
9393 @item ^-vm^/MEDIUM_VERBOSITY^
9394 @cindex @option{^-vm^/MEDIUM_VERBOSITY^} (@command{gnatmake})
9395 Verbosity level Medium. Potentially display fewer lines than in verbosity High.
9397 @item ^-vh^/HIGH_VERBOSITY^
9398 @cindex @option{^-vm^/HIGH_VERBOSITY^} (@command{gnatmake})
9399 Verbosity level High. Equivalent to ^-v^/REASONS^.
9401 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
9402 Indicate the verbosity of the parsing of GNAT project files.
9403 @xref{Switches Related to Project Files}.
9405 @item ^-x^/NON_PROJECT_UNIT_COMPILATION^
9406 @cindex @option{^-x^/NON_PROJECT_UNIT_COMPILATION^} (@command{gnatmake})
9407 Indicate that sources that are not part of any Project File may be compiled.
9408 Normally, when using Project Files, only sources that are part of a Project
9409 File may be compile. When this switch is used, a source outside of all Project
9410 Files may be compiled. The ALI file and the object file will be put in the
9411 object directory of the main Project. The compilation switches used will only
9412 be those specified on the command line. Even when
9413 @option{^-x^/NON_PROJECT_UNIT_COMPILATION^} is used, mains specified on the
9414 command line need to be sources of a project file.
9416 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
9417 Indicate that external variable @var{name} has the value @var{value}.
9418 The Project Manager will use this value for occurrences of
9419 @code{external(name)} when parsing the project file.
9420 @xref{Switches Related to Project Files}.
9423 @cindex @option{^-z^/NOMAIN^} (@command{gnatmake})
9424 No main subprogram. Bind and link the program even if the unit name
9425 given on the command line is a package name. The resulting executable
9426 will execute the elaboration routines of the package and its closure,
9427 then the finalization routines.
9432 @item @command{gcc} @asis{switches}
9434 Any uppercase or multi-character switch that is not a @command{gnatmake} switch
9435 is passed to @command{gcc} (e.g.@: @option{-O}, @option{-gnato,} etc.)
9438 Any qualifier that cannot be recognized as a qualifier for @code{GNAT MAKE}
9439 but is recognizable as a valid qualifier for @code{GNAT COMPILE} is
9440 automatically treated as a compiler switch, and passed on to all
9441 compilations that are carried out.
9446 Source and library search path switches:
9450 @item ^-aI^/SOURCE_SEARCH=^@var{dir}
9451 @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatmake})
9452 When looking for source files also look in directory @var{dir}.
9453 The order in which source files search is undertaken is
9454 described in @ref{Search Paths and the Run-Time Library (RTL)}.
9456 @item ^-aL^/SKIP_MISSING=^@var{dir}
9457 @cindex @option{^-aL^/SKIP_MISSING^} (@command{gnatmake})
9458 Consider @var{dir} as being an externally provided Ada library.
9459 Instructs @command{gnatmake} to skip compilation units whose @file{.ALI}
9460 files have been located in directory @var{dir}. This allows you to have
9461 missing bodies for the units in @var{dir} and to ignore out of date bodies
9462 for the same units. You still need to specify
9463 the location of the specs for these units by using the switches
9464 @option{^-aI^/SOURCE_SEARCH=^@var{dir}}
9465 or @option{^-I^/SEARCH=^@var{dir}}.
9466 Note: this switch is provided for compatibility with previous versions
9467 of @command{gnatmake}. The easier method of causing standard libraries
9468 to be excluded from consideration is to write-protect the corresponding
9471 @item ^-aO^/OBJECT_SEARCH=^@var{dir}
9472 @cindex @option{^-aO^/OBJECT_SEARCH^} (@command{gnatmake})
9473 When searching for library and object files, look in directory
9474 @var{dir}. The order in which library files are searched is described in
9475 @ref{Search Paths for gnatbind}.
9477 @item ^-A^/CONDITIONAL_SOURCE_SEARCH=^@var{dir}
9478 @cindex Search paths, for @command{gnatmake}
9479 @cindex @option{^-A^/CONDITIONAL_SOURCE_SEARCH^} (@command{gnatmake})
9480 Equivalent to @option{^-aL^/SKIP_MISSING=^@var{dir}
9481 ^-aI^/SOURCE_SEARCH=^@var{dir}}.
9483 @item ^-I^/SEARCH=^@var{dir}
9484 @cindex @option{^-I^/SEARCH^} (@command{gnatmake})
9485 Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir}
9486 ^-aI^/SOURCE_SEARCH=^@var{dir}}.
9488 @item ^-I-^/NOCURRENT_DIRECTORY^
9489 @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatmake})
9490 @cindex Source files, suppressing search
9491 Do not look for source files in the directory containing the source
9492 file named in the command line.
9493 Do not look for ALI or object files in the directory
9494 where @command{gnatmake} was invoked.
9496 @item ^-L^/LIBRARY_SEARCH=^@var{dir}
9497 @cindex @option{^-L^/LIBRARY_SEARCH^} (@command{gnatmake})
9498 @cindex Linker libraries
9499 Add directory @var{dir} to the list of directories in which the linker
9500 will search for libraries. This is equivalent to
9501 @option{-largs ^-L^/LIBRARY_SEARCH=^}@var{dir}.
9503 Furthermore, under Windows, the sources pointed to by the libraries path
9504 set in the registry are not searched for.
9508 @cindex @option{-nostdinc} (@command{gnatmake})
9509 Do not look for source files in the system default directory.
9512 @cindex @option{-nostdlib} (@command{gnatmake})
9513 Do not look for library files in the system default directory.
9515 @item --RTS=@var{rts-path}
9516 @cindex @option{--RTS} (@command{gnatmake})
9517 Specifies the default location of the runtime library. GNAT looks for the
9519 in the following directories, and stops as soon as a valid runtime is found
9520 (@file{adainclude} or @file{ada_source_path}, and @file{adalib} or
9521 @file{ada_object_path} present):
9524 @item <current directory>/$rts_path
9526 @item <default-search-dir>/$rts_path
9528 @item <default-search-dir>/rts-$rts_path
9532 The selected path is handled like a normal RTS path.
9536 @node Mode Switches for gnatmake
9537 @section Mode Switches for @command{gnatmake}
9540 The mode switches (referred to as @code{mode_switches}) allow the
9541 inclusion of switches that are to be passed to the compiler itself, the
9542 binder or the linker. The effect of a mode switch is to cause all
9543 subsequent switches up to the end of the switch list, or up to the next
9544 mode switch, to be interpreted as switches to be passed on to the
9545 designated component of GNAT.
9549 @item -cargs @var{switches}
9550 @cindex @option{-cargs} (@command{gnatmake})
9551 Compiler switches. Here @var{switches} is a list of switches
9552 that are valid switches for @command{gcc}. They will be passed on to
9553 all compile steps performed by @command{gnatmake}.
9555 @item -bargs @var{switches}
9556 @cindex @option{-bargs} (@command{gnatmake})
9557 Binder switches. Here @var{switches} is a list of switches
9558 that are valid switches for @code{gnatbind}. They will be passed on to
9559 all bind steps performed by @command{gnatmake}.
9561 @item -largs @var{switches}
9562 @cindex @option{-largs} (@command{gnatmake})
9563 Linker switches. Here @var{switches} is a list of switches
9564 that are valid switches for @command{gnatlink}. They will be passed on to
9565 all link steps performed by @command{gnatmake}.
9567 @item -margs @var{switches}
9568 @cindex @option{-margs} (@command{gnatmake})
9569 Make switches. The switches are directly interpreted by @command{gnatmake},
9570 regardless of any previous occurrence of @option{-cargs}, @option{-bargs}
9574 @node Notes on the Command Line
9575 @section Notes on the Command Line
9578 This section contains some additional useful notes on the operation
9579 of the @command{gnatmake} command.
9583 @cindex Recompilation, by @command{gnatmake}
9584 If @command{gnatmake} finds no ALI files, it recompiles the main program
9585 and all other units required by the main program.
9586 This means that @command{gnatmake}
9587 can be used for the initial compile, as well as during subsequent steps of
9588 the development cycle.
9591 If you enter @code{gnatmake @var{file}.adb}, where @file{@var{file}.adb}
9592 is a subunit or body of a generic unit, @command{gnatmake} recompiles
9593 @file{@var{file}.adb} (because it finds no ALI) and stops, issuing a
9597 In @command{gnatmake} the switch @option{^-I^/SEARCH^}
9598 is used to specify both source and
9599 library file paths. Use @option{^-aI^/SOURCE_SEARCH^}
9600 instead if you just want to specify
9601 source paths only and @option{^-aO^/OBJECT_SEARCH^}
9602 if you want to specify library paths
9606 @command{gnatmake} will ignore any files whose ALI file is write-protected.
9607 This may conveniently be used to exclude standard libraries from
9608 consideration and in particular it means that the use of the
9609 @option{^-f^/FORCE_COMPILE^} switch will not recompile these files
9610 unless @option{^-a^/ALL_FILES^} is also specified.
9613 @command{gnatmake} has been designed to make the use of Ada libraries
9614 particularly convenient. Assume you have an Ada library organized
9615 as follows: @i{^obj-dir^[OBJ_DIR]^} contains the objects and ALI files for
9616 of your Ada compilation units,
9617 whereas @i{^include-dir^[INCLUDE_DIR]^} contains the
9618 specs of these units, but no bodies. Then to compile a unit
9619 stored in @code{main.adb}, which uses this Ada library you would just type
9623 $ gnatmake -aI@var{include-dir} -aL@var{obj-dir} main
9626 $ gnatmake /SOURCE_SEARCH=@i{[INCLUDE_DIR]}
9627 /SKIP_MISSING=@i{[OBJ_DIR]} main
9632 Using @command{gnatmake} along with the
9633 @option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}
9634 switch provides a mechanism for avoiding unnecessary recompilations. Using
9636 you can update the comments/format of your
9637 source files without having to recompile everything. Note, however, that
9638 adding or deleting lines in a source files may render its debugging
9639 info obsolete. If the file in question is a spec, the impact is rather
9640 limited, as that debugging info will only be useful during the
9641 elaboration phase of your program. For bodies the impact can be more
9642 significant. In all events, your debugger will warn you if a source file
9643 is more recent than the corresponding object, and alert you to the fact
9644 that the debugging information may be out of date.
9647 @node How gnatmake Works
9648 @section How @command{gnatmake} Works
9651 Generally @command{gnatmake} automatically performs all necessary
9652 recompilations and you don't need to worry about how it works. However,
9653 it may be useful to have some basic understanding of the @command{gnatmake}
9654 approach and in particular to understand how it uses the results of
9655 previous compilations without incorrectly depending on them.
9657 First a definition: an object file is considered @dfn{up to date} if the
9658 corresponding ALI file exists and if all the source files listed in the
9659 dependency section of this ALI file have time stamps matching those in
9660 the ALI file. This means that neither the source file itself nor any
9661 files that it depends on have been modified, and hence there is no need
9662 to recompile this file.
9664 @command{gnatmake} works by first checking if the specified main unit is up
9665 to date. If so, no compilations are required for the main unit. If not,
9666 @command{gnatmake} compiles the main program to build a new ALI file that
9667 reflects the latest sources. Then the ALI file of the main unit is
9668 examined to find all the source files on which the main program depends,
9669 and @command{gnatmake} recursively applies the above procedure on all these
9672 This process ensures that @command{gnatmake} only trusts the dependencies
9673 in an existing ALI file if they are known to be correct. Otherwise it
9674 always recompiles to determine a new, guaranteed accurate set of
9675 dependencies. As a result the program is compiled ``upside down'' from what may
9676 be more familiar as the required order of compilation in some other Ada
9677 systems. In particular, clients are compiled before the units on which
9678 they depend. The ability of GNAT to compile in any order is critical in
9679 allowing an order of compilation to be chosen that guarantees that
9680 @command{gnatmake} will recompute a correct set of new dependencies if
9683 When invoking @command{gnatmake} with several @var{file_names}, if a unit is
9684 imported by several of the executables, it will be recompiled at most once.
9686 Note: when using non-standard naming conventions
9687 (@pxref{Using Other File Names}), changing through a configuration pragmas
9688 file the version of a source and invoking @command{gnatmake} to recompile may
9689 have no effect, if the previous version of the source is still accessible
9690 by @command{gnatmake}. It may be necessary to use the switch
9691 ^-f^/FORCE_COMPILE^.
9693 @node Examples of gnatmake Usage
9694 @section Examples of @command{gnatmake} Usage
9697 @item gnatmake hello.adb
9698 Compile all files necessary to bind and link the main program
9699 @file{hello.adb} (containing unit @code{Hello}) and bind and link the
9700 resulting object files to generate an executable file @file{^hello^HELLO.EXE^}.
9702 @item gnatmake main1 main2 main3
9703 Compile all files necessary to bind and link the main programs
9704 @file{main1.adb} (containing unit @code{Main1}), @file{main2.adb}
9705 (containing unit @code{Main2}) and @file{main3.adb}
9706 (containing unit @code{Main3}) and bind and link the resulting object files
9707 to generate three executable files @file{^main1^MAIN1.EXE^},
9708 @file{^main2^MAIN2.EXE^}
9709 and @file{^main3^MAIN3.EXE^}.
9712 @item gnatmake -q Main_Unit -cargs -O2 -bargs -l
9716 @item gnatmake Main_Unit /QUIET
9717 /COMPILER_QUALIFIERS /OPTIMIZE=ALL
9718 /BINDER_QUALIFIERS /ORDER_OF_ELABORATION
9720 Compile all files necessary to bind and link the main program unit
9721 @code{Main_Unit} (from file @file{main_unit.adb}). All compilations will
9722 be done with optimization level 2 and the order of elaboration will be
9723 listed by the binder. @command{gnatmake} will operate in quiet mode, not
9724 displaying commands it is executing.
9727 @c *************************
9728 @node Improving Performance
9729 @chapter Improving Performance
9730 @cindex Improving performance
9733 This chapter presents several topics related to program performance.
9734 It first describes some of the tradeoffs that need to be considered
9735 and some of the techniques for making your program run faster.
9736 It then documents the @command{gnatelim} tool and unused subprogram/data
9737 elimination feature, which can reduce the size of program executables.
9739 Note: to invoke @command{gnatelim} with a project file, use the @code{gnat}
9740 driver (see @ref{The GNAT Driver and Project Files}).
9744 * Performance Considerations::
9745 * Text_IO Suggestions::
9746 * Reducing Size of Ada Executables with gnatelim::
9747 * Reducing Size of Executables with unused subprogram/data elimination::
9751 @c *****************************
9752 @node Performance Considerations
9753 @section Performance Considerations
9756 The GNAT system provides a number of options that allow a trade-off
9761 performance of the generated code
9764 speed of compilation
9767 minimization of dependences and recompilation
9770 the degree of run-time checking.
9774 The defaults (if no options are selected) aim at improving the speed
9775 of compilation and minimizing dependences, at the expense of performance
9776 of the generated code:
9783 no inlining of subprogram calls
9786 all run-time checks enabled except overflow and elaboration checks
9790 These options are suitable for most program development purposes. This
9791 chapter describes how you can modify these choices, and also provides
9792 some guidelines on debugging optimized code.
9795 * Controlling Run-Time Checks::
9796 * Use of Restrictions::
9797 * Optimization Levels::
9798 * Debugging Optimized Code::
9799 * Inlining of Subprograms::
9800 * Other Optimization Switches::
9801 * Optimization and Strict Aliasing::
9804 * Coverage Analysis::
9808 @node Controlling Run-Time Checks
9809 @subsection Controlling Run-Time Checks
9812 By default, GNAT generates all run-time checks, except integer overflow
9813 checks, stack overflow checks, and checks for access before elaboration on
9814 subprogram calls. The latter are not required in default mode, because all
9815 necessary checking is done at compile time.
9816 @cindex @option{-gnatp} (@command{gcc})
9817 @cindex @option{-gnato} (@command{gcc})
9818 Two gnat switches, @option{-gnatp} and @option{-gnato} allow this default to
9819 be modified. @xref{Run-Time Checks}.
9821 Our experience is that the default is suitable for most development
9824 We treat integer overflow specially because these
9825 are quite expensive and in our experience are not as important as other
9826 run-time checks in the development process. Note that division by zero
9827 is not considered an overflow check, and divide by zero checks are
9828 generated where required by default.
9830 Elaboration checks are off by default, and also not needed by default, since
9831 GNAT uses a static elaboration analysis approach that avoids the need for
9832 run-time checking. This manual contains a full chapter discussing the issue
9833 of elaboration checks, and if the default is not satisfactory for your use,
9834 you should read this chapter.
9836 For validity checks, the minimal checks required by the Ada Reference
9837 Manual (for case statements and assignments to array elements) are on
9838 by default. These can be suppressed by use of the @option{-gnatVn} switch.
9839 Note that in Ada 83, there were no validity checks, so if the Ada 83 mode
9840 is acceptable (or when comparing GNAT performance with an Ada 83 compiler),
9841 it may be reasonable to routinely use @option{-gnatVn}. Validity checks
9842 are also suppressed entirely if @option{-gnatp} is used.
9844 @cindex Overflow checks
9845 @cindex Checks, overflow
9848 @cindex pragma Suppress
9849 @cindex pragma Unsuppress
9850 Note that the setting of the switches controls the default setting of
9851 the checks. They may be modified using either @code{pragma Suppress} (to
9852 remove checks) or @code{pragma Unsuppress} (to add back suppressed
9853 checks) in the program source.
9855 @node Use of Restrictions
9856 @subsection Use of Restrictions
9859 The use of pragma Restrictions allows you to control which features are
9860 permitted in your program. Apart from the obvious point that if you avoid
9861 relatively expensive features like finalization (enforceable by the use
9862 of pragma Restrictions (No_Finalization), the use of this pragma does not
9863 affect the generated code in most cases.
9865 One notable exception to this rule is that the possibility of task abort
9866 results in some distributed overhead, particularly if finalization or
9867 exception handlers are used. The reason is that certain sections of code
9868 have to be marked as non-abortable.
9870 If you use neither the @code{abort} statement, nor asynchronous transfer
9871 of control (@code{select @dots{} then abort}), then this distributed overhead
9872 is removed, which may have a general positive effect in improving
9873 overall performance. Especially code involving frequent use of tasking
9874 constructs and controlled types will show much improved performance.
9875 The relevant restrictions pragmas are
9877 @smallexample @c ada
9878 pragma Restrictions (No_Abort_Statements);
9879 pragma Restrictions (Max_Asynchronous_Select_Nesting => 0);
9883 It is recommended that these restriction pragmas be used if possible. Note
9884 that this also means that you can write code without worrying about the
9885 possibility of an immediate abort at any point.
9887 @node Optimization Levels
9888 @subsection Optimization Levels
9889 @cindex @option{^-O^/OPTIMIZE^} (@command{gcc})
9892 Without any optimization ^option,^qualifier,^
9893 the compiler's goal is to reduce the cost of
9894 compilation and to make debugging produce the expected results.
9895 Statements are independent: if you stop the program with a breakpoint between
9896 statements, you can then assign a new value to any variable or change
9897 the program counter to any other statement in the subprogram and get exactly
9898 the results you would expect from the source code.
9900 Turning on optimization makes the compiler attempt to improve the
9901 performance and/or code size at the expense of compilation time and
9902 possibly the ability to debug the program.
9905 ^-O options, with or without level numbers,^/OPTIMIZE qualifiers,^
9906 the last such option is the one that is effective.
9909 The default is optimization off. This results in the fastest compile
9910 times, but GNAT makes absolutely no attempt to optimize, and the
9911 generated programs are considerably larger and slower than when
9912 optimization is enabled. You can use the
9914 @option{-O} switch (the permitted forms are @option{-O0}, @option{-O1}
9915 @option{-O2}, @option{-O3}, and @option{-Os})
9918 @code{OPTIMIZE} qualifier
9920 to @command{gcc} to control the optimization level:
9923 @item ^-O0^/OPTIMIZE=NONE^
9924 No optimization (the default);
9925 generates unoptimized code but has
9926 the fastest compilation time.
9928 Note that many other compilers do fairly extensive optimization
9929 even if ``no optimization'' is specified. With gcc, it is
9930 very unusual to use ^-O0^/OPTIMIZE=NONE^ for production if
9931 execution time is of any concern, since ^-O0^/OPTIMIZE=NONE^
9932 really does mean no optimization at all. This difference between
9933 gcc and other compilers should be kept in mind when doing
9934 performance comparisons.
9936 @item ^-O1^/OPTIMIZE=SOME^
9937 Moderate optimization;
9938 optimizes reasonably well but does not
9939 degrade compilation time significantly.
9941 @item ^-O2^/OPTIMIZE=ALL^
9943 @itemx /OPTIMIZE=DEVELOPMENT
9946 generates highly optimized code and has
9947 the slowest compilation time.
9949 @item ^-O3^/OPTIMIZE=INLINING^
9950 Full optimization as in @option{-O2},
9951 and also attempts automatic inlining of small
9952 subprograms within a unit (@pxref{Inlining of Subprograms}).
9954 @item ^-Os^/OPTIMIZE=SPACE^
9955 Optimize space usage of resulting program.
9959 Higher optimization levels perform more global transformations on the
9960 program and apply more expensive analysis algorithms in order to generate
9961 faster and more compact code. The price in compilation time, and the
9962 resulting improvement in execution time,
9963 both depend on the particular application and the hardware environment.
9964 You should experiment to find the best level for your application.
9966 Since the precise set of optimizations done at each level will vary from
9967 release to release (and sometime from target to target), it is best to think
9968 of the optimization settings in general terms.
9969 @xref{Optimize Options,, Options That Control Optimization, gcc, Using
9970 the GNU Compiler Collection (GCC)}, for details about
9971 ^the @option{-O} settings and a number of @option{-f} options that^how to^
9972 individually enable or disable specific optimizations.
9974 Unlike some other compilation systems, ^@command{gcc}^GNAT^ has
9975 been tested extensively at all optimization levels. There are some bugs
9976 which appear only with optimization turned on, but there have also been
9977 bugs which show up only in @emph{unoptimized} code. Selecting a lower
9978 level of optimization does not improve the reliability of the code
9979 generator, which in practice is highly reliable at all optimization
9982 Note regarding the use of @option{-O3}: The use of this optimization level
9983 is generally discouraged with GNAT, since it often results in larger
9984 executables which run more slowly. See further discussion of this point
9985 in @ref{Inlining of Subprograms}.
9987 @node Debugging Optimized Code
9988 @subsection Debugging Optimized Code
9989 @cindex Debugging optimized code
9990 @cindex Optimization and debugging
9993 Although it is possible to do a reasonable amount of debugging at
9995 nonzero optimization levels,
9996 the higher the level the more likely that
9999 @option{/OPTIMIZE} settings other than @code{NONE},
10000 such settings will make it more likely that
10002 source-level constructs will have been eliminated by optimization.
10003 For example, if a loop is strength-reduced, the loop
10004 control variable may be completely eliminated and thus cannot be
10005 displayed in the debugger.
10006 This can only happen at @option{-O2} or @option{-O3}.
10007 Explicit temporary variables that you code might be eliminated at
10008 ^level^setting^ @option{-O1} or higher.
10010 The use of the @option{^-g^/DEBUG^} switch,
10011 @cindex @option{^-g^/DEBUG^} (@command{gcc})
10012 which is needed for source-level debugging,
10013 affects the size of the program executable on disk,
10014 and indeed the debugging information can be quite large.
10015 However, it has no effect on the generated code (and thus does not
10016 degrade performance)
10018 Since the compiler generates debugging tables for a compilation unit before
10019 it performs optimizations, the optimizing transformations may invalidate some
10020 of the debugging data. You therefore need to anticipate certain
10021 anomalous situations that may arise while debugging optimized code.
10022 These are the most common cases:
10026 @i{The ``hopping Program Counter'':} Repeated @code{step} or @code{next}
10028 the PC bouncing back and forth in the code. This may result from any of
10029 the following optimizations:
10033 @i{Common subexpression elimination:} using a single instance of code for a
10034 quantity that the source computes several times. As a result you
10035 may not be able to stop on what looks like a statement.
10038 @i{Invariant code motion:} moving an expression that does not change within a
10039 loop, to the beginning of the loop.
10042 @i{Instruction scheduling:} moving instructions so as to
10043 overlap loads and stores (typically) with other code, or in
10044 general to move computations of values closer to their uses. Often
10045 this causes you to pass an assignment statement without the assignment
10046 happening and then later bounce back to the statement when the
10047 value is actually needed. Placing a breakpoint on a line of code
10048 and then stepping over it may, therefore, not always cause all the
10049 expected side-effects.
10053 @i{The ``big leap'':} More commonly known as @emph{cross-jumping}, in which
10054 two identical pieces of code are merged and the program counter suddenly
10055 jumps to a statement that is not supposed to be executed, simply because
10056 it (and the code following) translates to the same thing as the code
10057 that @emph{was} supposed to be executed. This effect is typically seen in
10058 sequences that end in a jump, such as a @code{goto}, a @code{return}, or
10059 a @code{break} in a C @code{^switch^switch^} statement.
10062 @i{The ``roving variable'':} The symptom is an unexpected value in a variable.
10063 There are various reasons for this effect:
10067 In a subprogram prologue, a parameter may not yet have been moved to its
10071 A variable may be dead, and its register re-used. This is
10072 probably the most common cause.
10075 As mentioned above, the assignment of a value to a variable may
10079 A variable may be eliminated entirely by value propagation or
10080 other means. In this case, GCC may incorrectly generate debugging
10081 information for the variable
10085 In general, when an unexpected value appears for a local variable or parameter
10086 you should first ascertain if that value was actually computed by
10087 your program, as opposed to being incorrectly reported by the debugger.
10089 array elements in an object designated by an access value
10090 are generally less of a problem, once you have ascertained that the access
10092 Typically, this means checking variables in the preceding code and in the
10093 calling subprogram to verify that the value observed is explainable from other
10094 values (one must apply the procedure recursively to those
10095 other values); or re-running the code and stopping a little earlier
10096 (perhaps before the call) and stepping to better see how the variable obtained
10097 the value in question; or continuing to step @emph{from} the point of the
10098 strange value to see if code motion had simply moved the variable's
10103 In light of such anomalies, a recommended technique is to use @option{-O0}
10104 early in the software development cycle, when extensive debugging capabilities
10105 are most needed, and then move to @option{-O1} and later @option{-O2} as
10106 the debugger becomes less critical.
10107 Whether to use the @option{^-g^/DEBUG^} switch in the release version is
10108 a release management issue.
10110 Note that if you use @option{-g} you can then use the @command{strip} program
10111 on the resulting executable,
10112 which removes both debugging information and global symbols.
10115 @node Inlining of Subprograms
10116 @subsection Inlining of Subprograms
10119 A call to a subprogram in the current unit is inlined if all the
10120 following conditions are met:
10124 The optimization level is at least @option{-O1}.
10127 The called subprogram is suitable for inlining: It must be small enough
10128 and not contain something that @command{gcc} cannot support in inlined
10132 @cindex pragma Inline
10134 Either @code{pragma Inline} applies to the subprogram, or it is local
10135 to the unit and called once from within it, or it is small and automatic
10136 inlining (optimization level @option{-O3}) is specified.
10140 Calls to subprograms in @code{with}'ed units are normally not inlined.
10141 To achieve actual inlining (that is, replacement of the call by the code
10142 in the body of the subprogram), the following conditions must all be true.
10146 The optimization level is at least @option{-O1}.
10149 The called subprogram is suitable for inlining: It must be small enough
10150 and not contain something that @command{gcc} cannot support in inlined
10154 The call appears in a body (not in a package spec).
10157 There is a @code{pragma Inline} for the subprogram.
10160 @cindex @option{-gnatn} (@command{gcc})
10161 The @option{^-gnatn^/INLINE^} switch
10162 is used in the @command{gcc} command line
10165 Even if all these conditions are met, it may not be possible for
10166 the compiler to inline the call, due to the length of the body,
10167 or features in the body that make it impossible for the compiler
10168 to do the inlining.
10170 Note that specifying the @option{-gnatn} switch causes additional
10171 compilation dependencies. Consider the following:
10173 @smallexample @c ada
10193 With the default behavior (no @option{-gnatn} switch specified), the
10194 compilation of the @code{Main} procedure depends only on its own source,
10195 @file{main.adb}, and the spec of the package in file @file{r.ads}. This
10196 means that editing the body of @code{R} does not require recompiling
10199 On the other hand, the call @code{R.Q} is not inlined under these
10200 circumstances. If the @option{-gnatn} switch is present when @code{Main}
10201 is compiled, the call will be inlined if the body of @code{Q} is small
10202 enough, but now @code{Main} depends on the body of @code{R} in
10203 @file{r.adb} as well as on the spec. This means that if this body is edited,
10204 the main program must be recompiled. Note that this extra dependency
10205 occurs whether or not the call is in fact inlined by @command{gcc}.
10207 The use of front end inlining with @option{-gnatN} generates similar
10208 additional dependencies.
10210 @cindex @option{^-fno-inline^/INLINE=SUPPRESS^} (@command{gcc})
10211 Note: The @option{^-fno-inline^/INLINE=SUPPRESS^} switch
10212 can be used to prevent
10213 all inlining. This switch overrides all other conditions and ensures
10214 that no inlining occurs. The extra dependences resulting from
10215 @option{-gnatn} will still be active, even if
10216 this switch is used to suppress the resulting inlining actions.
10218 @cindex @option{-fno-inline-functions} (@command{gcc})
10219 Note: The @option{-fno-inline-functions} switch can be used to prevent
10220 automatic inlining of small subprograms if @option{-O3} is used.
10222 @cindex @option{-fno-inline-functions-called-once} (@command{gcc})
10223 Note: The @option{-fno-inline-functions-called-once} switch
10224 can be used to prevent inlining of subprograms local to the unit
10225 and called once from within it if @option{-O1} is used.
10227 Note regarding the use of @option{-O3}: There is no difference in inlining
10228 behavior between @option{-O2} and @option{-O3} for subprograms with an explicit
10229 pragma @code{Inline} assuming the use of @option{-gnatn}
10230 or @option{-gnatN} (the switches that activate inlining). If you have used
10231 pragma @code{Inline} in appropriate cases, then it is usually much better
10232 to use @option{-O2} and @option{-gnatn} and avoid the use of @option{-O3} which
10233 in this case only has the effect of inlining subprograms you did not
10234 think should be inlined. We often find that the use of @option{-O3} slows
10235 down code by performing excessive inlining, leading to increased instruction
10236 cache pressure from the increased code size. So the bottom line here is
10237 that you should not automatically assume that @option{-O3} is better than
10238 @option{-O2}, and indeed you should use @option{-O3} only if tests show that
10239 it actually improves performance.
10241 @node Other Optimization Switches
10242 @subsection Other Optimization Switches
10243 @cindex Optimization Switches
10245 Since @code{GNAT} uses the @command{gcc} back end, all the specialized
10246 @command{gcc} optimization switches are potentially usable. These switches
10247 have not been extensively tested with GNAT but can generally be expected
10248 to work. Examples of switches in this category are
10249 @option{-funroll-loops} and
10250 the various target-specific @option{-m} options (in particular, it has been
10251 observed that @option{-march=pentium4} can significantly improve performance
10252 on appropriate machines). For full details of these switches, see
10253 @ref{Submodel Options,, Hardware Models and Configurations, gcc, Using
10254 the GNU Compiler Collection (GCC)}.
10256 @node Optimization and Strict Aliasing
10257 @subsection Optimization and Strict Aliasing
10259 @cindex Strict Aliasing
10260 @cindex No_Strict_Aliasing
10263 The strong typing capabilities of Ada allow an optimizer to generate
10264 efficient code in situations where other languages would be forced to
10265 make worst case assumptions preventing such optimizations. Consider
10266 the following example:
10268 @smallexample @c ada
10271 type Int1 is new Integer;
10272 type Int2 is new Integer;
10273 type Int1A is access Int1;
10274 type Int2A is access Int2;
10281 for J in Data'Range loop
10282 if Data (J) = Int1V.all then
10283 Int2V.all := Int2V.all + 1;
10292 In this example, since the variable @code{Int1V} can only access objects
10293 of type @code{Int1}, and @code{Int2V} can only access objects of type
10294 @code{Int2}, there is no possibility that the assignment to
10295 @code{Int2V.all} affects the value of @code{Int1V.all}. This means that
10296 the compiler optimizer can "know" that the value @code{Int1V.all} is constant
10297 for all iterations of the loop and avoid the extra memory reference
10298 required to dereference it each time through the loop.
10300 This kind of optimization, called strict aliasing analysis, is
10301 triggered by specifying an optimization level of @option{-O2} or
10302 higher or @option{-Os} and allows @code{GNAT} to generate more efficient code
10303 when access values are involved.
10305 However, although this optimization is always correct in terms of
10306 the formal semantics of the Ada Reference Manual, difficulties can
10307 arise if features like @code{Unchecked_Conversion} are used to break
10308 the typing system. Consider the following complete program example:
10310 @smallexample @c ada
10313 type int1 is new integer;
10314 type int2 is new integer;
10315 type a1 is access int1;
10316 type a2 is access int2;
10321 function to_a2 (Input : a1) return a2;
10324 with Unchecked_Conversion;
10326 function to_a2 (Input : a1) return a2 is
10328 new Unchecked_Conversion (a1, a2);
10330 return to_a2u (Input);
10336 with Text_IO; use Text_IO;
10338 v1 : a1 := new int1;
10339 v2 : a2 := to_a2 (v1);
10343 put_line (int1'image (v1.all));
10349 This program prints out 0 in @option{-O0} or @option{-O1}
10350 mode, but it prints out 1 in @option{-O2} mode. That's
10351 because in strict aliasing mode, the compiler can and
10352 does assume that the assignment to @code{v2.all} could not
10353 affect the value of @code{v1.all}, since different types
10356 This behavior is not a case of non-conformance with the standard, since
10357 the Ada RM specifies that an unchecked conversion where the resulting
10358 bit pattern is not a correct value of the target type can result in an
10359 abnormal value and attempting to reference an abnormal value makes the
10360 execution of a program erroneous. That's the case here since the result
10361 does not point to an object of type @code{int2}. This means that the
10362 effect is entirely unpredictable.
10364 However, although that explanation may satisfy a language
10365 lawyer, in practice an applications programmer expects an
10366 unchecked conversion involving pointers to create true
10367 aliases and the behavior of printing 1 seems plain wrong.
10368 In this case, the strict aliasing optimization is unwelcome.
10370 Indeed the compiler recognizes this possibility, and the
10371 unchecked conversion generates a warning:
10374 p2.adb:5:07: warning: possible aliasing problem with type "a2"
10375 p2.adb:5:07: warning: use -fno-strict-aliasing switch for references
10376 p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);"
10380 Unfortunately the problem is recognized when compiling the body of
10381 package @code{p2}, but the actual "bad" code is generated while
10382 compiling the body of @code{m} and this latter compilation does not see
10383 the suspicious @code{Unchecked_Conversion}.
10385 As implied by the warning message, there are approaches you can use to
10386 avoid the unwanted strict aliasing optimization in a case like this.
10388 One possibility is to simply avoid the use of @option{-O2}, but
10389 that is a bit drastic, since it throws away a number of useful
10390 optimizations that do not involve strict aliasing assumptions.
10392 A less drastic approach is to compile the program using the
10393 option @option{-fno-strict-aliasing}. Actually it is only the
10394 unit containing the dereferencing of the suspicious pointer
10395 that needs to be compiled. So in this case, if we compile
10396 unit @code{m} with this switch, then we get the expected
10397 value of zero printed. Analyzing which units might need
10398 the switch can be painful, so a more reasonable approach
10399 is to compile the entire program with options @option{-O2}
10400 and @option{-fno-strict-aliasing}. If the performance is
10401 satisfactory with this combination of options, then the
10402 advantage is that the entire issue of possible "wrong"
10403 optimization due to strict aliasing is avoided.
10405 To avoid the use of compiler switches, the configuration
10406 pragma @code{No_Strict_Aliasing} with no parameters may be
10407 used to specify that for all access types, the strict
10408 aliasing optimization should be suppressed.
10410 However, these approaches are still overkill, in that they causes
10411 all manipulations of all access values to be deoptimized. A more
10412 refined approach is to concentrate attention on the specific
10413 access type identified as problematic.
10415 First, if a careful analysis of uses of the pointer shows
10416 that there are no possible problematic references, then
10417 the warning can be suppressed by bracketing the
10418 instantiation of @code{Unchecked_Conversion} to turn
10421 @smallexample @c ada
10422 pragma Warnings (Off);
10424 new Unchecked_Conversion (a1, a2);
10425 pragma Warnings (On);
10429 Of course that approach is not appropriate for this particular
10430 example, since indeed there is a problematic reference. In this
10431 case we can take one of two other approaches.
10433 The first possibility is to move the instantiation of unchecked
10434 conversion to the unit in which the type is declared. In
10435 this example, we would move the instantiation of
10436 @code{Unchecked_Conversion} from the body of package
10437 @code{p2} to the spec of package @code{p1}. Now the
10438 warning disappears. That's because any use of the
10439 access type knows there is a suspicious unchecked
10440 conversion, and the strict aliasing optimization
10441 is automatically suppressed for the type.
10443 If it is not practical to move the unchecked conversion to the same unit
10444 in which the destination access type is declared (perhaps because the
10445 source type is not visible in that unit), you may use pragma
10446 @code{No_Strict_Aliasing} for the type. This pragma must occur in the
10447 same declarative sequence as the declaration of the access type:
10449 @smallexample @c ada
10450 type a2 is access int2;
10451 pragma No_Strict_Aliasing (a2);
10455 Here again, the compiler now knows that the strict aliasing optimization
10456 should be suppressed for any reference to type @code{a2} and the
10457 expected behavior is obtained.
10459 Finally, note that although the compiler can generate warnings for
10460 simple cases of unchecked conversions, there are tricker and more
10461 indirect ways of creating type incorrect aliases which the compiler
10462 cannot detect. Examples are the use of address overlays and unchecked
10463 conversions involving composite types containing access types as
10464 components. In such cases, no warnings are generated, but there can
10465 still be aliasing problems. One safe coding practice is to forbid the
10466 use of address clauses for type overlaying, and to allow unchecked
10467 conversion only for primitive types. This is not really a significant
10468 restriction since any possible desired effect can be achieved by
10469 unchecked conversion of access values.
10471 The aliasing analysis done in strict aliasing mode can certainly
10472 have significant benefits. We have seen cases of large scale
10473 application code where the time is increased by up to 5% by turning
10474 this optimization off. If you have code that includes significant
10475 usage of unchecked conversion, you might want to just stick with
10476 @option{-O1} and avoid the entire issue. If you get adequate
10477 performance at this level of optimization level, that's probably
10478 the safest approach. If tests show that you really need higher
10479 levels of optimization, then you can experiment with @option{-O2}
10480 and @option{-O2 -fno-strict-aliasing} to see how much effect this
10481 has on size and speed of the code. If you really need to use
10482 @option{-O2} with strict aliasing in effect, then you should
10483 review any uses of unchecked conversion of access types,
10484 particularly if you are getting the warnings described above.
10487 @node Coverage Analysis
10488 @subsection Coverage Analysis
10491 GNAT supports the HP Performance Coverage Analyzer (PCA), which allows
10492 the user to determine the distribution of execution time across a program,
10493 @pxref{Profiling} for details of usage.
10497 @node Text_IO Suggestions
10498 @section @code{Text_IO} Suggestions
10499 @cindex @code{Text_IO} and performance
10502 The @code{Ada.Text_IO} package has fairly high overheads due in part to
10503 the requirement of maintaining page and line counts. If performance
10504 is critical, a recommendation is to use @code{Stream_IO} instead of
10505 @code{Text_IO} for volume output, since this package has less overhead.
10507 If @code{Text_IO} must be used, note that by default output to the standard
10508 output and standard error files is unbuffered (this provides better
10509 behavior when output statements are used for debugging, or if the
10510 progress of a program is observed by tracking the output, e.g. by
10511 using the Unix @command{tail -f} command to watch redirected output.
10513 If you are generating large volumes of output with @code{Text_IO} and
10514 performance is an important factor, use a designated file instead
10515 of the standard output file, or change the standard output file to
10516 be buffered using @code{Interfaces.C_Streams.setvbuf}.
10520 @node Reducing Size of Ada Executables with gnatelim
10521 @section Reducing Size of Ada Executables with @code{gnatelim}
10525 This section describes @command{gnatelim}, a tool which detects unused
10526 subprograms and helps the compiler to create a smaller executable for your
10531 * Running gnatelim::
10532 * Correcting the List of Eliminate Pragmas::
10533 * Making Your Executables Smaller::
10534 * Summary of the gnatelim Usage Cycle::
10537 @node About gnatelim
10538 @subsection About @code{gnatelim}
10541 When a program shares a set of Ada
10542 packages with other programs, it may happen that this program uses
10543 only a fraction of the subprograms defined in these packages. The code
10544 created for these unused subprograms increases the size of the executable.
10546 @code{gnatelim} tracks unused subprograms in an Ada program and
10547 outputs a list of GNAT-specific pragmas @code{Eliminate} marking all the
10548 subprograms that are declared but never called. By placing the list of
10549 @code{Eliminate} pragmas in the GNAT configuration file @file{gnat.adc} and
10550 recompiling your program, you may decrease the size of its executable,
10551 because the compiler will not generate the code for 'eliminated' subprograms.
10552 @xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more
10553 information about this pragma.
10555 @code{gnatelim} needs as its input data the name of the main subprogram
10556 and a bind file for a main subprogram.
10558 To create a bind file for @code{gnatelim}, run @code{gnatbind} for
10559 the main subprogram. @code{gnatelim} can work with both Ada and C
10560 bind files; when both are present, it uses the Ada bind file.
10561 The following commands will build the program and create the bind file:
10564 $ gnatmake ^-c Main_Prog^/ACTIONS=COMPILE MAIN_PROG^
10565 $ gnatbind main_prog
10568 Note that @code{gnatelim} needs neither object nor ALI files.
10570 @node Running gnatelim
10571 @subsection Running @code{gnatelim}
10574 @code{gnatelim} has the following command-line interface:
10577 $ gnatelim @ovar{options} name
10581 @code{name} should be a name of a source file that contains the main subprogram
10582 of a program (partition).
10584 @code{gnatelim} has the following switches:
10589 @cindex @option{^-q^/QUIET^} (@command{gnatelim})
10590 Quiet mode: by default @code{gnatelim} outputs to the standard error
10591 stream the number of program units left to be processed. This option turns
10594 @item ^-v^/VERBOSE^
10595 @cindex @option{^-v^/VERBOSE^} (@command{gnatelim})
10596 Verbose mode: @code{gnatelim} version information is printed as Ada
10597 comments to the standard output stream. Also, in addition to the number of
10598 program units left @code{gnatelim} will output the name of the current unit
10602 @cindex @option{^-a^/ALL^} (@command{gnatelim})
10603 Also look for subprograms from the GNAT run time that can be eliminated. Note
10604 that when @file{gnat.adc} is produced using this switch, the entire program
10605 must be recompiled with switch @option{^-a^/ALL_FILES^} to @command{gnatmake}.
10607 @item ^-I^/INCLUDE_DIRS=^@var{dir}
10608 @cindex @option{^-I^/INCLUDE_DIRS^} (@command{gnatelim})
10609 When looking for source files also look in directory @var{dir}. Specifying
10610 @option{^-I-^/INCLUDE_DIRS=-^} instructs @code{gnatelim} not to look for
10611 sources in the current directory.
10613 @item ^-b^/BIND_FILE=^@var{bind_file}
10614 @cindex @option{^-b^/BIND_FILE^} (@command{gnatelim})
10615 Specifies @var{bind_file} as the bind file to process. If not set, the name
10616 of the bind file is computed from the full expanded Ada name
10617 of a main subprogram.
10619 @item ^-C^/CONFIG_FILE=^@var{config_file}
10620 @cindex @option{^-C^/CONFIG_FILE^} (@command{gnatelim})
10621 Specifies a file @var{config_file} that contains configuration pragmas. The
10622 file must be specified with full path.
10624 @item ^--GCC^/COMPILER^=@var{compiler_name}
10625 @cindex @option{^-GCC^/COMPILER^} (@command{gnatelim})
10626 Instructs @code{gnatelim} to use specific @command{gcc} compiler instead of one
10627 available on the path.
10629 @item ^--GNATMAKE^/GNATMAKE^=@var{gnatmake_name}
10630 @cindex @option{^--GNATMAKE^/GNATMAKE^} (@command{gnatelim})
10631 Instructs @code{gnatelim} to use specific @command{gnatmake} instead of one
10632 available on the path.
10636 @code{gnatelim} sends its output to the standard output stream, and all the
10637 tracing and debug information is sent to the standard error stream.
10638 In order to produce a proper GNAT configuration file
10639 @file{gnat.adc}, redirection must be used:
10643 $ PIPE GNAT ELIM MAIN_PROG.ADB > GNAT.ADC
10646 $ gnatelim main_prog.adb > gnat.adc
10655 $ gnatelim main_prog.adb >> gnat.adc
10659 in order to append the @code{gnatelim} output to the existing contents of
10663 @node Correcting the List of Eliminate Pragmas
10664 @subsection Correcting the List of Eliminate Pragmas
10667 In some rare cases @code{gnatelim} may try to eliminate
10668 subprograms that are actually called in the program. In this case, the
10669 compiler will generate an error message of the form:
10672 file.adb:106:07: cannot call eliminated subprogram "My_Prog"
10676 You will need to manually remove the wrong @code{Eliminate} pragmas from
10677 the @file{gnat.adc} file. You should recompile your program
10678 from scratch after that, because you need a consistent @file{gnat.adc} file
10679 during the entire compilation.
10681 @node Making Your Executables Smaller
10682 @subsection Making Your Executables Smaller
10685 In order to get a smaller executable for your program you now have to
10686 recompile the program completely with the new @file{gnat.adc} file
10687 created by @code{gnatelim} in your current directory:
10690 $ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^
10694 (Use the @option{^-f^/FORCE_COMPILE^} option for @command{gnatmake} to
10695 recompile everything
10696 with the set of pragmas @code{Eliminate} that you have obtained with
10697 @command{gnatelim}).
10699 Be aware that the set of @code{Eliminate} pragmas is specific to each
10700 program. It is not recommended to merge sets of @code{Eliminate}
10701 pragmas created for different programs in one @file{gnat.adc} file.
10703 @node Summary of the gnatelim Usage Cycle
10704 @subsection Summary of the gnatelim Usage Cycle
10707 Here is a quick summary of the steps to be taken in order to reduce
10708 the size of your executables with @code{gnatelim}. You may use
10709 other GNAT options to control the optimization level,
10710 to produce the debugging information, to set search path, etc.
10714 Produce a bind file
10717 $ gnatmake ^-c main_prog^/ACTIONS=COMPILE MAIN_PROG^
10718 $ gnatbind main_prog
10722 Generate a list of @code{Eliminate} pragmas
10725 $ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC
10728 $ gnatelim main_prog >@r{[}>@r{]} gnat.adc
10733 Recompile the application
10736 $ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^
10741 @node Reducing Size of Executables with unused subprogram/data elimination
10742 @section Reducing Size of Executables with Unused Subprogram/Data Elimination
10743 @findex unused subprogram/data elimination
10746 This section describes how you can eliminate unused subprograms and data from
10747 your executable just by setting options at compilation time.
10750 * About unused subprogram/data elimination::
10751 * Compilation options::
10752 * Example of unused subprogram/data elimination::
10755 @node About unused subprogram/data elimination
10756 @subsection About unused subprogram/data elimination
10759 By default, an executable contains all code and data of its composing objects
10760 (directly linked or coming from statically linked libraries), even data or code
10761 never used by this executable.
10763 This feature will allow you to eliminate such unused code from your
10764 executable, making it smaller (in disk and in memory).
10766 This functionality is available on all Linux platforms except for the IA-64
10767 architecture and on all cross platforms using the ELF binary file format.
10768 In both cases GNU binutils version 2.16 or later are required to enable it.
10770 @node Compilation options
10771 @subsection Compilation options
10774 The operation of eliminating the unused code and data from the final executable
10775 is directly performed by the linker.
10777 In order to do this, it has to work with objects compiled with the
10779 @option{-ffunction-sections} @option{-fdata-sections}.
10780 @cindex @option{-ffunction-sections} (@command{gcc})
10781 @cindex @option{-fdata-sections} (@command{gcc})
10782 These options are usable with C and Ada files.
10783 They will place respectively each
10784 function or data in a separate section in the resulting object file.
10786 Once the objects and static libraries are created with these options, the
10787 linker can perform the dead code elimination. You can do this by setting
10788 the @option{-Wl,--gc-sections} option to gcc command or in the
10789 @option{-largs} section of @command{gnatmake}. This will perform a
10790 garbage collection of code and data never referenced.
10792 If the linker performs a partial link (@option{-r} ld linker option), then you
10793 will need to provide one or several entry point using the
10794 @option{-e} / @option{--entry} ld option.
10796 Note that objects compiled without the @option{-ffunction-sections} and
10797 @option{-fdata-sections} options can still be linked with the executable.
10798 However, no dead code elimination will be performed on those objects (they will
10801 The GNAT static library is now compiled with -ffunction-sections and
10802 -fdata-sections on some platforms. This allows you to eliminate the unused code
10803 and data of the GNAT library from your executable.
10805 @node Example of unused subprogram/data elimination
10806 @subsection Example of unused subprogram/data elimination
10809 Here is a simple example:
10811 @smallexample @c ada
10820 Used_Data : Integer;
10821 Unused_Data : Integer;
10823 procedure Used (Data : Integer);
10824 procedure Unused (Data : Integer);
10827 package body Aux is
10828 procedure Used (Data : Integer) is
10833 procedure Unused (Data : Integer) is
10835 Unused_Data := Data;
10841 @code{Unused} and @code{Unused_Data} are never referenced in this code
10842 excerpt, and hence they may be safely removed from the final executable.
10847 $ nm test | grep used
10848 020015f0 T aux__unused
10849 02005d88 B aux__unused_data
10850 020015cc T aux__used
10851 02005d84 B aux__used_data
10853 $ gnatmake test -cargs -fdata-sections -ffunction-sections \
10854 -largs -Wl,--gc-sections
10856 $ nm test | grep used
10857 02005350 T aux__used
10858 0201ffe0 B aux__used_data
10862 It can be observed that the procedure @code{Unused} and the object
10863 @code{Unused_Data} are removed by the linker when using the
10864 appropriate options.
10866 @c ********************************
10867 @node Renaming Files Using gnatchop
10868 @chapter Renaming Files Using @code{gnatchop}
10872 This chapter discusses how to handle files with multiple units by using
10873 the @code{gnatchop} utility. This utility is also useful in renaming
10874 files to meet the standard GNAT default file naming conventions.
10877 * Handling Files with Multiple Units::
10878 * Operating gnatchop in Compilation Mode::
10879 * Command Line for gnatchop::
10880 * Switches for gnatchop::
10881 * Examples of gnatchop Usage::
10884 @node Handling Files with Multiple Units
10885 @section Handling Files with Multiple Units
10888 The basic compilation model of GNAT requires that a file submitted to the
10889 compiler have only one unit and there be a strict correspondence
10890 between the file name and the unit name.
10892 The @code{gnatchop} utility allows both of these rules to be relaxed,
10893 allowing GNAT to process files which contain multiple compilation units
10894 and files with arbitrary file names. @code{gnatchop}
10895 reads the specified file and generates one or more output files,
10896 containing one unit per file. The unit and the file name correspond,
10897 as required by GNAT.
10899 If you want to permanently restructure a set of ``foreign'' files so that
10900 they match the GNAT rules, and do the remaining development using the
10901 GNAT structure, you can simply use @command{gnatchop} once, generate the
10902 new set of files and work with them from that point on.
10904 Alternatively, if you want to keep your files in the ``foreign'' format,
10905 perhaps to maintain compatibility with some other Ada compilation
10906 system, you can set up a procedure where you use @command{gnatchop} each
10907 time you compile, regarding the source files that it writes as temporary
10908 files that you throw away.
10910 Note that if your file containing multiple units starts with a byte order
10911 mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop
10912 will each start with a copy of this BOM, meaning that they can be compiled
10913 automatically in UTF-8 mode without needing to specify an explicit encoding.
10915 @node Operating gnatchop in Compilation Mode
10916 @section Operating gnatchop in Compilation Mode
10919 The basic function of @code{gnatchop} is to take a file with multiple units
10920 and split it into separate files. The boundary between files is reasonably
10921 clear, except for the issue of comments and pragmas. In default mode, the
10922 rule is that any pragmas between units belong to the previous unit, except
10923 that configuration pragmas always belong to the following unit. Any comments
10924 belong to the following unit. These rules
10925 almost always result in the right choice of
10926 the split point without needing to mark it explicitly and most users will
10927 find this default to be what they want. In this default mode it is incorrect to
10928 submit a file containing only configuration pragmas, or one that ends in
10929 configuration pragmas, to @code{gnatchop}.
10931 However, using a special option to activate ``compilation mode'',
10933 can perform another function, which is to provide exactly the semantics
10934 required by the RM for handling of configuration pragmas in a compilation.
10935 In the absence of configuration pragmas (at the main file level), this
10936 option has no effect, but it causes such configuration pragmas to be handled
10937 in a quite different manner.
10939 First, in compilation mode, if @code{gnatchop} is given a file that consists of
10940 only configuration pragmas, then this file is appended to the
10941 @file{gnat.adc} file in the current directory. This behavior provides
10942 the required behavior described in the RM for the actions to be taken
10943 on submitting such a file to the compiler, namely that these pragmas
10944 should apply to all subsequent compilations in the same compilation
10945 environment. Using GNAT, the current directory, possibly containing a
10946 @file{gnat.adc} file is the representation
10947 of a compilation environment. For more information on the
10948 @file{gnat.adc} file, see @ref{Handling of Configuration Pragmas}.
10950 Second, in compilation mode, if @code{gnatchop}
10951 is given a file that starts with
10952 configuration pragmas, and contains one or more units, then these
10953 configuration pragmas are prepended to each of the chopped files. This
10954 behavior provides the required behavior described in the RM for the
10955 actions to be taken on compiling such a file, namely that the pragmas
10956 apply to all units in the compilation, but not to subsequently compiled
10959 Finally, if configuration pragmas appear between units, they are appended
10960 to the previous unit. This results in the previous unit being illegal,
10961 since the compiler does not accept configuration pragmas that follow
10962 a unit. This provides the required RM behavior that forbids configuration
10963 pragmas other than those preceding the first compilation unit of a
10966 For most purposes, @code{gnatchop} will be used in default mode. The
10967 compilation mode described above is used only if you need exactly
10968 accurate behavior with respect to compilations, and you have files
10969 that contain multiple units and configuration pragmas. In this
10970 circumstance the use of @code{gnatchop} with the compilation mode
10971 switch provides the required behavior, and is for example the mode
10972 in which GNAT processes the ACVC tests.
10974 @node Command Line for gnatchop
10975 @section Command Line for @code{gnatchop}
10978 The @code{gnatchop} command has the form:
10981 $ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]}
10986 The only required argument is the file name of the file to be chopped.
10987 There are no restrictions on the form of this file name. The file itself
10988 contains one or more Ada units, in normal GNAT format, concatenated
10989 together. As shown, more than one file may be presented to be chopped.
10991 When run in default mode, @code{gnatchop} generates one output file in
10992 the current directory for each unit in each of the files.
10994 @var{directory}, if specified, gives the name of the directory to which
10995 the output files will be written. If it is not specified, all files are
10996 written to the current directory.
10998 For example, given a
10999 file called @file{hellofiles} containing
11001 @smallexample @c ada
11006 with Text_IO; use Text_IO;
11009 Put_Line ("Hello");
11019 $ gnatchop ^hellofiles^HELLOFILES.^
11023 generates two files in the current directory, one called
11024 @file{hello.ads} containing the single line that is the procedure spec,
11025 and the other called @file{hello.adb} containing the remaining text. The
11026 original file is not affected. The generated files can be compiled in
11030 When gnatchop is invoked on a file that is empty or that contains only empty
11031 lines and/or comments, gnatchop will not fail, but will not produce any
11034 For example, given a
11035 file called @file{toto.txt} containing
11037 @smallexample @c ada
11049 $ gnatchop ^toto.txt^TOT.TXT^
11053 will not produce any new file and will result in the following warnings:
11056 toto.txt:1:01: warning: empty file, contains no compilation units
11057 no compilation units found
11058 no source files written
11061 @node Switches for gnatchop
11062 @section Switches for @code{gnatchop}
11065 @command{gnatchop} recognizes the following switches:
11071 @cindex @option{--version} @command{gnatchop}
11072 Display Copyright and version, then exit disregarding all other options.
11075 @cindex @option{--help} @command{gnatchop}
11076 If @option{--version} was not used, display usage, then exit disregarding
11079 @item ^-c^/COMPILATION^
11080 @cindex @option{^-c^/COMPILATION^} (@code{gnatchop})
11081 Causes @code{gnatchop} to operate in compilation mode, in which
11082 configuration pragmas are handled according to strict RM rules. See
11083 previous section for a full description of this mode.
11086 @item -gnat@var{xxx}
11087 This passes the given @option{-gnat@var{xxx}} switch to @code{gnat} which is
11088 used to parse the given file. Not all @var{xxx} options make sense,
11089 but for example, the use of @option{-gnati2} allows @code{gnatchop} to
11090 process a source file that uses Latin-2 coding for identifiers.
11094 Causes @code{gnatchop} to generate a brief help summary to the standard
11095 output file showing usage information.
11097 @item ^-k@var{mm}^/FILE_NAME_MAX_LENGTH=@var{mm}^
11098 @cindex @option{^-k^/FILE_NAME_MAX_LENGTH^} (@code{gnatchop})
11099 Limit generated file names to the specified number @code{mm}
11101 This is useful if the
11102 resulting set of files is required to be interoperable with systems
11103 which limit the length of file names.
11105 If no value is given, or
11106 if no @code{/FILE_NAME_MAX_LENGTH} qualifier is given,
11107 a default of 39, suitable for OpenVMS Alpha
11108 Systems, is assumed
11111 No space is allowed between the @option{-k} and the numeric value. The numeric
11112 value may be omitted in which case a default of @option{-k8},
11114 with DOS-like file systems, is used. If no @option{-k} switch
11116 there is no limit on the length of file names.
11119 @item ^-p^/PRESERVE^
11120 @cindex @option{^-p^/PRESERVE^} (@code{gnatchop})
11121 Causes the file ^modification^creation^ time stamp of the input file to be
11122 preserved and used for the time stamp of the output file(s). This may be
11123 useful for preserving coherency of time stamps in an environment where
11124 @code{gnatchop} is used as part of a standard build process.
11127 @cindex @option{^-q^/QUIET^} (@code{gnatchop})
11128 Causes output of informational messages indicating the set of generated
11129 files to be suppressed. Warnings and error messages are unaffected.
11131 @item ^-r^/REFERENCE^
11132 @cindex @option{^-r^/REFERENCE^} (@code{gnatchop})
11133 @findex Source_Reference
11134 Generate @code{Source_Reference} pragmas. Use this switch if the output
11135 files are regarded as temporary and development is to be done in terms
11136 of the original unchopped file. This switch causes
11137 @code{Source_Reference} pragmas to be inserted into each of the
11138 generated files to refers back to the original file name and line number.
11139 The result is that all error messages refer back to the original
11141 In addition, the debugging information placed into the object file (when
11142 the @option{^-g^/DEBUG^} switch of @command{gcc} or @command{gnatmake} is
11144 also refers back to this original file so that tools like profilers and
11145 debuggers will give information in terms of the original unchopped file.
11147 If the original file to be chopped itself contains
11148 a @code{Source_Reference}
11149 pragma referencing a third file, then gnatchop respects
11150 this pragma, and the generated @code{Source_Reference} pragmas
11151 in the chopped file refer to the original file, with appropriate
11152 line numbers. This is particularly useful when @code{gnatchop}
11153 is used in conjunction with @code{gnatprep} to compile files that
11154 contain preprocessing statements and multiple units.
11156 @item ^-v^/VERBOSE^
11157 @cindex @option{^-v^/VERBOSE^} (@code{gnatchop})
11158 Causes @code{gnatchop} to operate in verbose mode. The version
11159 number and copyright notice are output, as well as exact copies of
11160 the gnat1 commands spawned to obtain the chop control information.
11162 @item ^-w^/OVERWRITE^
11163 @cindex @option{^-w^/OVERWRITE^} (@code{gnatchop})
11164 Overwrite existing file names. Normally @code{gnatchop} regards it as a
11165 fatal error if there is already a file with the same name as a
11166 file it would otherwise output, in other words if the files to be
11167 chopped contain duplicated units. This switch bypasses this
11168 check, and causes all but the last instance of such duplicated
11169 units to be skipped.
11172 @item --GCC=@var{xxxx}
11173 @cindex @option{--GCC=} (@code{gnatchop})
11174 Specify the path of the GNAT parser to be used. When this switch is used,
11175 no attempt is made to add the prefix to the GNAT parser executable.
11179 @node Examples of gnatchop Usage
11180 @section Examples of @code{gnatchop} Usage
11184 @item gnatchop /OVERWRITE HELLO_S.ADA [PRERELEASE.FILES]
11187 @item gnatchop -w hello_s.ada prerelease/files
11190 Chops the source file @file{hello_s.ada}. The output files will be
11191 placed in the directory @file{^prerelease/files^[PRERELEASE.FILES]^},
11193 files with matching names in that directory (no files in the current
11194 directory are modified).
11196 @item gnatchop ^archive^ARCHIVE.^
11197 Chops the source file @file{^archive^ARCHIVE.^}
11198 into the current directory. One
11199 useful application of @code{gnatchop} is in sending sets of sources
11200 around, for example in email messages. The required sources are simply
11201 concatenated (for example, using a ^Unix @code{cat}^VMS @code{APPEND/NEW}^
11203 @command{gnatchop} is used at the other end to reconstitute the original
11206 @item gnatchop file1 file2 file3 direc
11207 Chops all units in files @file{file1}, @file{file2}, @file{file3}, placing
11208 the resulting files in the directory @file{direc}. Note that if any units
11209 occur more than once anywhere within this set of files, an error message
11210 is generated, and no files are written. To override this check, use the
11211 @option{^-w^/OVERWRITE^} switch,
11212 in which case the last occurrence in the last file will
11213 be the one that is output, and earlier duplicate occurrences for a given
11214 unit will be skipped.
11217 @node Configuration Pragmas
11218 @chapter Configuration Pragmas
11219 @cindex Configuration pragmas
11220 @cindex Pragmas, configuration
11223 Configuration pragmas include those pragmas described as
11224 such in the Ada Reference Manual, as well as
11225 implementation-dependent pragmas that are configuration pragmas.
11226 @xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
11227 for details on these additional GNAT-specific configuration pragmas.
11228 Most notably, the pragma @code{Source_File_Name}, which allows
11229 specifying non-default names for source files, is a configuration
11230 pragma. The following is a complete list of configuration pragmas
11231 recognized by GNAT:
11243 Compile_Time_Warning
11245 Component_Alignment
11252 External_Name_Casing
11255 Float_Representation
11268 Priority_Specific_Dispatching
11271 Propagate_Exceptions
11274 Restricted_Run_Time
11276 Restrictions_Warnings
11279 Source_File_Name_Project
11282 Suppress_Exception_Locations
11283 Task_Dispatching_Policy
11289 Wide_Character_Encoding
11294 * Handling of Configuration Pragmas::
11295 * The Configuration Pragmas Files::
11298 @node Handling of Configuration Pragmas
11299 @section Handling of Configuration Pragmas
11301 Configuration pragmas may either appear at the start of a compilation
11302 unit, in which case they apply only to that unit, or they may apply to
11303 all compilations performed in a given compilation environment.
11305 GNAT also provides the @code{gnatchop} utility to provide an automatic
11306 way to handle configuration pragmas following the semantics for
11307 compilations (that is, files with multiple units), described in the RM.
11308 See @ref{Operating gnatchop in Compilation Mode} for details.
11309 However, for most purposes, it will be more convenient to edit the
11310 @file{gnat.adc} file that contains configuration pragmas directly,
11311 as described in the following section.
11313 @node The Configuration Pragmas Files
11314 @section The Configuration Pragmas Files
11315 @cindex @file{gnat.adc}
11318 In GNAT a compilation environment is defined by the current
11319 directory at the time that a compile command is given. This current
11320 directory is searched for a file whose name is @file{gnat.adc}. If
11321 this file is present, it is expected to contain one or more
11322 configuration pragmas that will be applied to the current compilation.
11323 However, if the switch @option{-gnatA} is used, @file{gnat.adc} is not
11326 Configuration pragmas may be entered into the @file{gnat.adc} file
11327 either by running @code{gnatchop} on a source file that consists only of
11328 configuration pragmas, or more conveniently by
11329 direct editing of the @file{gnat.adc} file, which is a standard format
11332 In addition to @file{gnat.adc}, additional files containing configuration
11333 pragmas may be applied to the current compilation using the switch
11334 @option{-gnatec}@var{path}. @var{path} must designate an existing file that
11335 contains only configuration pragmas. These configuration pragmas are
11336 in addition to those found in @file{gnat.adc} (provided @file{gnat.adc}
11337 is present and switch @option{-gnatA} is not used).
11339 It is allowed to specify several switches @option{-gnatec}, all of which
11340 will be taken into account.
11342 If you are using project file, a separate mechanism is provided using
11343 project attributes, see @ref{Specifying Configuration Pragmas} for more
11347 Of special interest to GNAT OpenVMS Alpha is the following
11348 configuration pragma:
11350 @smallexample @c ada
11352 pragma Extend_System (Aux_DEC);
11357 In the presence of this pragma, GNAT adds to the definition of the
11358 predefined package SYSTEM all the additional types and subprograms that are
11359 defined in HP Ada. See @ref{Compatibility with HP Ada} for details.
11362 @node Handling Arbitrary File Naming Conventions Using gnatname
11363 @chapter Handling Arbitrary File Naming Conventions Using @code{gnatname}
11364 @cindex Arbitrary File Naming Conventions
11367 * Arbitrary File Naming Conventions::
11368 * Running gnatname::
11369 * Switches for gnatname::
11370 * Examples of gnatname Usage::
11373 @node Arbitrary File Naming Conventions
11374 @section Arbitrary File Naming Conventions
11377 The GNAT compiler must be able to know the source file name of a compilation
11378 unit. When using the standard GNAT default file naming conventions
11379 (@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler
11380 does not need additional information.
11383 When the source file names do not follow the standard GNAT default file naming
11384 conventions, the GNAT compiler must be given additional information through
11385 a configuration pragmas file (@pxref{Configuration Pragmas})
11387 When the non-standard file naming conventions are well-defined,
11388 a small number of pragmas @code{Source_File_Name} specifying a naming pattern
11389 (@pxref{Alternative File Naming Schemes}) may be sufficient. However,
11390 if the file naming conventions are irregular or arbitrary, a number
11391 of pragma @code{Source_File_Name} for individual compilation units
11393 To help maintain the correspondence between compilation unit names and
11394 source file names within the compiler,
11395 GNAT provides a tool @code{gnatname} to generate the required pragmas for a
11398 @node Running gnatname
11399 @section Running @code{gnatname}
11402 The usual form of the @code{gnatname} command is
11405 $ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}
11406 @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]}
11410 All of the arguments are optional. If invoked without any argument,
11411 @code{gnatname} will display its usage.
11414 When used with at least one naming pattern, @code{gnatname} will attempt to
11415 find all the compilation units in files that follow at least one of the
11416 naming patterns. To find these compilation units,
11417 @code{gnatname} will use the GNAT compiler in syntax-check-only mode on all
11421 One or several Naming Patterns may be given as arguments to @code{gnatname}.
11422 Each Naming Pattern is enclosed between double quotes.
11423 A Naming Pattern is a regular expression similar to the wildcard patterns
11424 used in file names by the Unix shells or the DOS prompt.
11427 @code{gnatname} may be called with several sections of directories/patterns.
11428 Sections are separated by switch @code{--and}. In each section, there must be
11429 at least one pattern. If no directory is specified in a section, the current
11430 directory (or the project directory is @code{-P} is used) is implied.
11431 The options other that the directory switches and the patterns apply globally
11432 even if they are in different sections.
11435 Examples of Naming Patterns are
11444 For a more complete description of the syntax of Naming Patterns,
11445 see the second kind of regular expressions described in @file{g-regexp.ads}
11446 (the ``Glob'' regular expressions).
11449 When invoked with no switch @code{-P}, @code{gnatname} will create a
11450 configuration pragmas file @file{gnat.adc} in the current working directory,
11451 with pragmas @code{Source_File_Name} for each file that contains a valid Ada
11454 @node Switches for gnatname
11455 @section Switches for @code{gnatname}
11458 Switches for @code{gnatname} must precede any specified Naming Pattern.
11461 You may specify any of the following switches to @code{gnatname}:
11467 @cindex @option{--version} @command{gnatname}
11468 Display Copyright and version, then exit disregarding all other options.
11471 @cindex @option{--help} @command{gnatname}
11472 If @option{--version} was not used, display usage, then exit disregarding
11476 Start another section of directories/patterns.
11478 @item ^-c^/CONFIG_FILE=^@file{file}
11479 @cindex @option{^-c^/CONFIG_FILE^} (@code{gnatname})
11480 Create a configuration pragmas file @file{file} (instead of the default
11483 There may be zero, one or more space between @option{-c} and
11486 @file{file} may include directory information. @file{file} must be
11487 writable. There may be only one switch @option{^-c^/CONFIG_FILE^}.
11488 When a switch @option{^-c^/CONFIG_FILE^} is
11489 specified, no switch @option{^-P^/PROJECT_FILE^} may be specified (see below).
11491 @item ^-d^/SOURCE_DIRS=^@file{dir}
11492 @cindex @option{^-d^/SOURCE_DIRS^} (@code{gnatname})
11493 Look for source files in directory @file{dir}. There may be zero, one or more
11494 spaces between @option{^-d^/SOURCE_DIRS=^} and @file{dir}.
11495 When a switch @option{^-d^/SOURCE_DIRS^}
11496 is specified, the current working directory will not be searched for source
11497 files, unless it is explicitly specified with a @option{^-d^/SOURCE_DIRS^}
11498 or @option{^-D^/DIR_FILES^} switch.
11499 Several switches @option{^-d^/SOURCE_DIRS^} may be specified.
11500 If @file{dir} is a relative path, it is relative to the directory of
11501 the configuration pragmas file specified with switch
11502 @option{^-c^/CONFIG_FILE^},
11503 or to the directory of the project file specified with switch
11504 @option{^-P^/PROJECT_FILE^} or,
11505 if neither switch @option{^-c^/CONFIG_FILE^}
11506 nor switch @option{^-P^/PROJECT_FILE^} are specified, it is relative to the
11507 current working directory. The directory
11508 specified with switch @option{^-d^/SOURCE_DIRS^} must exist and be readable.
11510 @item ^-D^/DIRS_FILE=^@file{file}
11511 @cindex @option{^-D^/DIRS_FILE^} (@code{gnatname})
11512 Look for source files in all directories listed in text file @file{file}.
11513 There may be zero, one or more spaces between @option{^-D^/DIRS_FILE=^}
11515 @file{file} must be an existing, readable text file.
11516 Each nonempty line in @file{file} must be a directory.
11517 Specifying switch @option{^-D^/DIRS_FILE^} is equivalent to specifying as many
11518 switches @option{^-d^/SOURCE_DIRS^} as there are nonempty lines in
11521 @item ^-f^/FOREIGN_PATTERN=^@file{pattern}
11522 @cindex @option{^-f^/FOREIGN_PATTERN^} (@code{gnatname})
11523 Foreign patterns. Using this switch, it is possible to add sources of languages
11524 other than Ada to the list of sources of a project file.
11525 It is only useful if a ^-P^/PROJECT_FILE^ switch is used.
11528 gnatname ^-Pprj -f"*.c"^/PROJECT_FILE=PRJ /FOREIGN_PATTERN=*.C^ "*.ada"
11531 will look for Ada units in all files with the @file{.ada} extension,
11532 and will add to the list of file for project @file{prj.gpr} the C files
11533 with extension @file{.^c^C^}.
11536 @cindex @option{^-h^/HELP^} (@code{gnatname})
11537 Output usage (help) information. The output is written to @file{stdout}.
11539 @item ^-P^/PROJECT_FILE=^@file{proj}
11540 @cindex @option{^-P^/PROJECT_FILE^} (@code{gnatname})
11541 Create or update project file @file{proj}. There may be zero, one or more space
11542 between @option{-P} and @file{proj}. @file{proj} may include directory
11543 information. @file{proj} must be writable.
11544 There may be only one switch @option{^-P^/PROJECT_FILE^}.
11545 When a switch @option{^-P^/PROJECT_FILE^} is specified,
11546 no switch @option{^-c^/CONFIG_FILE^} may be specified.
11548 @item ^-v^/VERBOSE^
11549 @cindex @option{^-v^/VERBOSE^} (@code{gnatname})
11550 Verbose mode. Output detailed explanation of behavior to @file{stdout}.
11551 This includes name of the file written, the name of the directories to search
11552 and, for each file in those directories whose name matches at least one of
11553 the Naming Patterns, an indication of whether the file contains a unit,
11554 and if so the name of the unit.
11556 @item ^-v -v^/VERBOSE /VERBOSE^
11557 @cindex @option{^-v -v^/VERBOSE /VERBOSE^} (@code{gnatname})
11558 Very Verbose mode. In addition to the output produced in verbose mode,
11559 for each file in the searched directories whose name matches none of
11560 the Naming Patterns, an indication is given that there is no match.
11562 @item ^-x^/EXCLUDED_PATTERN=^@file{pattern}
11563 @cindex @option{^-x^/EXCLUDED_PATTERN^} (@code{gnatname})
11564 Excluded patterns. Using this switch, it is possible to exclude some files
11565 that would match the name patterns. For example,
11567 gnatname ^-x "*_nt.ada"^/EXCLUDED_PATTERN=*_nt.ada^ "*.ada"
11570 will look for Ada units in all files with the @file{.ada} extension,
11571 except those whose names end with @file{_nt.ada}.
11575 @node Examples of gnatname Usage
11576 @section Examples of @code{gnatname} Usage
11580 $ gnatname /CONFIG_FILE=[HOME.ME]NAMES.ADC /SOURCE_DIRS=SOURCES "[a-z]*.ada*"
11586 $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"
11591 In this example, the directory @file{^/home/me^[HOME.ME]^} must already exist
11592 and be writable. In addition, the directory
11593 @file{^/home/me/sources^[HOME.ME.SOURCES]^} (specified by
11594 @option{^-d sources^/SOURCE_DIRS=SOURCES^}) must exist and be readable.
11597 Note the optional spaces after @option{-c} and @option{-d}.
11602 $ gnatname -P/home/me/proj -x "*_nt_body.ada"
11603 -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
11606 $ gnatname /PROJECT_FILE=[HOME.ME]PROJ
11607 /EXCLUDED_PATTERN=*_nt_body.ada
11608 /SOURCE_DIRS=(SOURCES,[SOURCES.PLUS])
11609 /DIRS_FILE=COMMON_DIRS.TXT "body_*" "spec_*"
11613 Note that several switches @option{^-d^/SOURCE_DIRS^} may be used,
11614 even in conjunction with one or several switches
11615 @option{^-D^/DIRS_FILE^}. Several Naming Patterns and one excluded pattern
11616 are used in this example.
11618 @c *****************************************
11619 @c * G N A T P r o j e c t M a n a g e r *
11620 @c *****************************************
11621 @node GNAT Project Manager
11622 @chapter GNAT Project Manager
11626 * Examples of Project Files::
11627 * Project File Syntax::
11628 * Objects and Sources in Project Files::
11629 * Importing Projects::
11630 * Project Extension::
11631 * Project Hierarchy Extension::
11632 * External References in Project Files::
11633 * Packages in Project Files::
11634 * Variables from Imported Projects::
11636 * Library Projects::
11637 * Stand-alone Library Projects::
11638 * Switches Related to Project Files::
11639 * Tools Supporting Project Files::
11640 * An Extended Example::
11641 * Project File Complete Syntax::
11644 @c ****************
11645 @c * Introduction *
11646 @c ****************
11649 @section Introduction
11652 This chapter describes GNAT's @emph{Project Manager}, a facility that allows
11653 you to manage complex builds involving a number of source files, directories,
11654 and compilation options for different system configurations. In particular,
11655 project files allow you to specify:
11658 The directory or set of directories containing the source files, and/or the
11659 names of the specific source files themselves
11661 The directory in which the compiler's output
11662 (@file{ALI} files, object files, tree files) is to be placed
11664 The directory in which the executable programs is to be placed
11666 ^Switch^Switch^ settings for any of the project-enabled tools
11667 (@command{gnatmake}, compiler, binder, linker, @code{gnatls}, @code{gnatxref},
11668 @code{gnatfind}); you can apply these settings either globally or to individual
11671 The source files containing the main subprogram(s) to be built
11673 The source programming language(s) (currently Ada and/or C)
11675 Source file naming conventions; you can specify these either globally or for
11676 individual compilation units
11683 @node Project Files
11684 @subsection Project Files
11687 Project files are written in a syntax close to that of Ada, using familiar
11688 notions such as packages, context clauses, declarations, default values,
11689 assignments, and inheritance. Finally, project files can be built
11690 hierarchically from other project files, simplifying complex system
11691 integration and project reuse.
11693 A @dfn{project} is a specific set of values for various compilation properties.
11694 The settings for a given project are described by means of
11695 a @dfn{project file}, which is a text file written in an Ada-like syntax.
11696 Property values in project files are either strings or lists of strings.
11697 Properties that are not explicitly set receive default values. A project
11698 file may interrogate the values of @dfn{external variables} (user-defined
11699 command-line switches or environment variables), and it may specify property
11700 settings conditionally, based on the value of such variables.
11702 In simple cases, a project's source files depend only on other source files
11703 in the same project, or on the predefined libraries. (@emph{Dependence} is
11705 the Ada technical sense; as in one Ada unit @code{with}ing another.) However,
11706 the Project Manager also allows more sophisticated arrangements,
11707 where the source files in one project depend on source files in other
11711 One project can @emph{import} other projects containing needed source files.
11713 You can organize GNAT projects in a hierarchy: a @emph{child} project
11714 can extend a @emph{parent} project, inheriting the parent's source files and
11715 optionally overriding any of them with alternative versions
11719 More generally, the Project Manager lets you structure large development
11720 efforts into hierarchical subsystems, where build decisions are delegated
11721 to the subsystem level, and thus different compilation environments
11722 (^switch^switch^ settings) used for different subsystems.
11724 The Project Manager is invoked through the
11725 @option{^-P^/PROJECT_FILE=^@emph{projectfile}}
11726 switch to @command{gnatmake} or to the @command{^gnat^GNAT^} front driver.
11728 There may be zero, one or more spaces between @option{-P} and
11729 @option{@emph{projectfile}}.
11731 If you want to define (on the command line) an external variable that is
11732 queried by the project file, you must use the
11733 @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch.
11734 The Project Manager parses and interprets the project file, and drives the
11735 invoked tool based on the project settings.
11737 The Project Manager supports a wide range of development strategies,
11738 for systems of all sizes. Here are some typical practices that are
11742 Using a common set of source files, but generating object files in different
11743 directories via different ^switch^switch^ settings
11745 Using a mostly-shared set of source files, but with different versions of
11750 The destination of an executable can be controlled inside a project file
11751 using the @option{^-o^-o^}
11753 In the absence of such a ^switch^switch^ either inside
11754 the project file or on the command line, any executable files generated by
11755 @command{gnatmake} are placed in the directory @code{Exec_Dir} specified
11756 in the project file. If no @code{Exec_Dir} is specified, they will be placed
11757 in the object directory of the project.
11759 You can use project files to achieve some of the effects of a source
11760 versioning system (for example, defining separate projects for
11761 the different sets of sources that comprise different releases) but the
11762 Project Manager is independent of any source configuration management tools
11763 that might be used by the developers.
11765 The next section introduces the main features of GNAT's project facility
11766 through a sequence of examples; subsequent sections will present the syntax
11767 and semantics in more detail. A more formal description of the project
11768 facility appears in @ref{Project File Reference,,, gnat_rm, GNAT
11771 @c *****************************
11772 @c * Examples of Project Files *
11773 @c *****************************
11775 @node Examples of Project Files
11776 @section Examples of Project Files
11778 This section illustrates some of the typical uses of project files and
11779 explains their basic structure and behavior.
11782 * Common Sources with Different ^Switches^Switches^ and Directories::
11783 * Using External Variables::
11784 * Importing Other Projects::
11785 * Extending a Project::
11788 @node Common Sources with Different ^Switches^Switches^ and Directories
11789 @subsection Common Sources with Different ^Switches^Switches^ and Directories
11793 * Specifying the Object Directory::
11794 * Specifying the Exec Directory::
11795 * Project File Packages::
11796 * Specifying ^Switch^Switch^ Settings::
11797 * Main Subprograms::
11798 * Executable File Names::
11799 * Source File Naming Conventions::
11800 * Source Language(s)::
11804 Suppose that the Ada source files @file{pack.ads}, @file{pack.adb}, and
11805 @file{proc.adb} are in the @file{/common} directory. The file
11806 @file{proc.adb} contains an Ada main subprogram @code{Proc} that @code{with}s
11807 package @code{Pack}. We want to compile these source files under two sets
11808 of ^switches^switches^:
11811 When debugging, we want to pass the @option{-g} switch to @command{gnatmake},
11812 and the @option{^-gnata^-gnata^},
11813 @option{^-gnato^-gnato^},
11814 and @option{^-gnatE^-gnatE^} switches to the
11815 compiler; the compiler's output is to appear in @file{/common/debug}
11817 When preparing a release version, we want to pass the @option{^-O2^O2^} switch
11818 to the compiler; the compiler's output is to appear in @file{/common/release}
11822 The GNAT project files shown below, respectively @file{debug.gpr} and
11823 @file{release.gpr} in the @file{/common} directory, achieve these effects.
11836 ^/common/debug^[COMMON.DEBUG]^
11841 ^/common/release^[COMMON.RELEASE]^
11846 Here are the corresponding project files:
11848 @smallexample @c projectfile
11851 for Object_Dir use "debug";
11852 for Main use ("proc");
11855 for ^Default_Switches^Default_Switches^ ("Ada")
11857 for Executable ("proc.adb") use "proc1";
11862 package Compiler is
11863 for ^Default_Switches^Default_Switches^ ("Ada")
11864 use ("-fstack-check",
11867 "^-gnatE^-gnatE^");
11873 @smallexample @c projectfile
11876 for Object_Dir use "release";
11877 for Exec_Dir use ".";
11878 for Main use ("proc");
11880 package Compiler is
11881 for ^Default_Switches^Default_Switches^ ("Ada")
11889 The name of the project defined by @file{debug.gpr} is @code{"Debug"} (case
11890 insensitive), and analogously the project defined by @file{release.gpr} is
11891 @code{"Release"}. For consistency the file should have the same name as the
11892 project, and the project file's extension should be @code{"gpr"}. These
11893 conventions are not required, but a warning is issued if they are not followed.
11895 If the current directory is @file{^/temp^[TEMP]^}, then the command
11897 gnatmake ^-P/common/debug.gpr^/PROJECT_FILE=[COMMON]DEBUG^
11901 generates object and ALI files in @file{^/common/debug^[COMMON.DEBUG]^},
11902 as well as the @code{^proc1^PROC1.EXE^} executable,
11903 using the ^switch^switch^ settings defined in the project file.
11905 Likewise, the command
11907 gnatmake ^-P/common/release.gpr^/PROJECT_FILE=[COMMON]RELEASE^
11911 generates object and ALI files in @file{^/common/release^[COMMON.RELEASE]^},
11912 and the @code{^proc^PROC.EXE^}
11913 executable in @file{^/common^[COMMON]^},
11914 using the ^switch^switch^ settings from the project file.
11917 @unnumberedsubsubsec Source Files
11920 If a project file does not explicitly specify a set of source directories or
11921 a set of source files, then by default the project's source files are the
11922 Ada source files in the project file directory. Thus @file{pack.ads},
11923 @file{pack.adb}, and @file{proc.adb} are the source files for both projects.
11925 @node Specifying the Object Directory
11926 @unnumberedsubsubsec Specifying the Object Directory
11929 Several project properties are modeled by Ada-style @emph{attributes};
11930 a property is defined by supplying the equivalent of an Ada attribute
11931 definition clause in the project file.
11932 A project's object directory is another such a property; the corresponding
11933 attribute is @code{Object_Dir}, and its value is also a string expression,
11934 specified either as absolute or relative. In the later case,
11935 it is relative to the project file directory. Thus the compiler's
11936 output is directed to @file{^/common/debug^[COMMON.DEBUG]^}
11937 (for the @code{Debug} project)
11938 and to @file{^/common/release^[COMMON.RELEASE]^}
11939 (for the @code{Release} project).
11940 If @code{Object_Dir} is not specified, then the default is the project file
11943 @node Specifying the Exec Directory
11944 @unnumberedsubsubsec Specifying the Exec Directory
11947 A project's exec directory is another property; the corresponding
11948 attribute is @code{Exec_Dir}, and its value is also a string expression,
11949 either specified as relative or absolute. If @code{Exec_Dir} is not specified,
11950 then the default is the object directory (which may also be the project file
11951 directory if attribute @code{Object_Dir} is not specified). Thus the executable
11952 is placed in @file{^/common/debug^[COMMON.DEBUG]^}
11953 for the @code{Debug} project (attribute @code{Exec_Dir} not specified)
11954 and in @file{^/common^[COMMON]^} for the @code{Release} project.
11956 @node Project File Packages
11957 @unnumberedsubsubsec Project File Packages
11960 A GNAT tool that is integrated with the Project Manager is modeled by a
11961 corresponding package in the project file. In the example above,
11962 The @code{Debug} project defines the packages @code{Builder}
11963 (for @command{gnatmake}) and @code{Compiler};
11964 the @code{Release} project defines only the @code{Compiler} package.
11966 The Ada-like package syntax is not to be taken literally. Although packages in
11967 project files bear a surface resemblance to packages in Ada source code, the
11968 notation is simply a way to convey a grouping of properties for a named
11969 entity. Indeed, the package names permitted in project files are restricted
11970 to a predefined set, corresponding to the project-aware tools, and the contents
11971 of packages are limited to a small set of constructs.
11972 The packages in the example above contain attribute definitions.
11974 @node Specifying ^Switch^Switch^ Settings
11975 @unnumberedsubsubsec Specifying ^Switch^Switch^ Settings
11978 ^Switch^Switch^ settings for a project-aware tool can be specified through
11979 attributes in the package that corresponds to the tool.
11980 The example above illustrates one of the relevant attributes,
11981 @code{^Default_Switches^Default_Switches^}, which is defined in packages
11982 in both project files.
11983 Unlike simple attributes like @code{Source_Dirs},
11984 @code{^Default_Switches^Default_Switches^} is
11985 known as an @emph{associative array}. When you define this attribute, you must
11986 supply an ``index'' (a literal string), and the effect of the attribute
11987 definition is to set the value of the array at the specified index.
11988 For the @code{^Default_Switches^Default_Switches^} attribute,
11989 the index is a programming language (in our case, Ada),
11990 and the value specified (after @code{use}) must be a list
11991 of string expressions.
11993 The attributes permitted in project files are restricted to a predefined set.
11994 Some may appear at project level, others in packages.
11995 For any attribute that is an associative array, the index must always be a
11996 literal string, but the restrictions on this string (e.g., a file name or a
11997 language name) depend on the individual attribute.
11998 Also depending on the attribute, its specified value will need to be either a
11999 string or a string list.
12001 In the @code{Debug} project, we set the switches for two tools,
12002 @command{gnatmake} and the compiler, and thus we include the two corresponding
12003 packages; each package defines the @code{^Default_Switches^Default_Switches^}
12004 attribute with index @code{"Ada"}.
12005 Note that the package corresponding to
12006 @command{gnatmake} is named @code{Builder}. The @code{Release} project is
12007 similar, but only includes the @code{Compiler} package.
12009 In project @code{Debug} above, the ^switches^switches^ starting with
12010 @option{-gnat} that are specified in package @code{Compiler}
12011 could have been placed in package @code{Builder}, since @command{gnatmake}
12012 transmits all such ^switches^switches^ to the compiler.
12014 @node Main Subprograms
12015 @unnumberedsubsubsec Main Subprograms
12018 One of the specifiable properties of a project is a list of files that contain
12019 main subprograms. This property is captured in the @code{Main} attribute,
12020 whose value is a list of strings. If a project defines the @code{Main}
12021 attribute, it is not necessary to identify the main subprogram(s) when
12022 invoking @command{gnatmake} (@pxref{gnatmake and Project Files}).
12024 @node Executable File Names
12025 @unnumberedsubsubsec Executable File Names
12028 By default, the executable file name corresponding to a main source is
12029 deduced from the main source file name. Through the attributes
12030 @code{Executable} and @code{Executable_Suffix} of package @code{Builder},
12031 it is possible to change this default.
12032 In project @code{Debug} above, the executable file name
12033 for main source @file{^proc.adb^PROC.ADB^} is
12034 @file{^proc1^PROC1.EXE^}.
12035 Attribute @code{Executable_Suffix}, when specified, may change the suffix
12036 of the executable files, when no attribute @code{Executable} applies:
12037 its value replace the platform-specific executable suffix.
12038 Attributes @code{Executable} and @code{Executable_Suffix} are the only ways to
12039 specify a non-default executable file name when several mains are built at once
12040 in a single @command{gnatmake} command.
12042 @node Source File Naming Conventions
12043 @unnumberedsubsubsec Source File Naming Conventions
12046 Since the project files above do not specify any source file naming
12047 conventions, the GNAT defaults are used. The mechanism for defining source
12048 file naming conventions -- a package named @code{Naming} --
12049 is described below (@pxref{Naming Schemes}).
12051 @node Source Language(s)
12052 @unnumberedsubsubsec Source Language(s)
12055 Since the project files do not specify a @code{Languages} attribute, by
12056 default the GNAT tools assume that the language of the project file is Ada.
12057 More generally, a project can comprise source files
12058 in Ada, C, and/or other languages.
12060 @node Using External Variables
12061 @subsection Using External Variables
12064 Instead of supplying different project files for debug and release, we can
12065 define a single project file that queries an external variable (set either
12066 on the command line or via an ^environment variable^logical name^) in order to
12067 conditionally define the appropriate settings. Again, assume that the
12068 source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are
12069 located in directory @file{^/common^[COMMON]^}. The following project file,
12070 @file{build.gpr}, queries the external variable named @code{STYLE} and
12071 defines an object directory and ^switch^switch^ settings based on whether
12072 the value is @code{"deb"} (debug) or @code{"rel"} (release), and where
12073 the default is @code{"deb"}.
12075 @smallexample @c projectfile
12078 for Main use ("proc");
12080 type Style_Type is ("deb", "rel");
12081 Style : Style_Type := external ("STYLE", "deb");
12085 for Object_Dir use "debug";
12088 for Object_Dir use "release";
12089 for Exec_Dir use ".";
12098 for ^Default_Switches^Default_Switches^ ("Ada")
12100 for Executable ("proc") use "proc1";
12109 package Compiler is
12113 for ^Default_Switches^Default_Switches^ ("Ada")
12114 use ("^-gnata^-gnata^",
12116 "^-gnatE^-gnatE^");
12119 for ^Default_Switches^Default_Switches^ ("Ada")
12130 @code{Style_Type} is an example of a @emph{string type}, which is the project
12131 file analog of an Ada enumeration type but whose components are string literals
12132 rather than identifiers. @code{Style} is declared as a variable of this type.
12134 The form @code{external("STYLE", "deb")} is known as an
12135 @emph{external reference}; its first argument is the name of an
12136 @emph{external variable}, and the second argument is a default value to be
12137 used if the external variable doesn't exist. You can define an external
12138 variable on the command line via the @option{^-X^/EXTERNAL_REFERENCE^} switch,
12139 or you can use ^an environment variable^a logical name^
12140 as an external variable.
12142 Each @code{case} construct is expanded by the Project Manager based on the
12143 value of @code{Style}. Thus the command
12146 gnatmake -P/common/build.gpr -XSTYLE=deb
12152 gnatmake /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=deb
12157 is equivalent to the @command{gnatmake} invocation using the project file
12158 @file{debug.gpr} in the earlier example. So is the command
12160 gnatmake ^-P/common/build.gpr^/PROJECT_FILE=[COMMON]BUILD.GPR^
12164 since @code{"deb"} is the default for @code{STYLE}.
12170 gnatmake -P/common/build.gpr -XSTYLE=rel
12176 GNAT MAKE /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=rel
12181 is equivalent to the @command{gnatmake} invocation using the project file
12182 @file{release.gpr} in the earlier example.
12184 @node Importing Other Projects
12185 @subsection Importing Other Projects
12186 @cindex @code{ADA_PROJECT_PATH}
12189 A compilation unit in a source file in one project may depend on compilation
12190 units in source files in other projects. To compile this unit under
12191 control of a project file, the
12192 dependent project must @emph{import} the projects containing the needed source
12194 This effect is obtained using syntax similar to an Ada @code{with} clause,
12195 but where @code{with}ed entities are strings that denote project files.
12197 As an example, suppose that the two projects @code{GUI_Proj} and
12198 @code{Comm_Proj} are defined in the project files @file{gui_proj.gpr} and
12199 @file{comm_proj.gpr} in directories @file{^/gui^[GUI]^}
12200 and @file{^/comm^[COMM]^}, respectively.
12201 Suppose that the source files for @code{GUI_Proj} are
12202 @file{gui.ads} and @file{gui.adb}, and that the source files for
12203 @code{Comm_Proj} are @file{comm.ads} and @file{comm.adb}, where each set of
12204 files is located in its respective project file directory. Schematically:
12223 We want to develop an application in directory @file{^/app^[APP]^} that
12224 @code{with} the packages @code{GUI} and @code{Comm}, using the properties of
12225 the corresponding project files (e.g.@: the ^switch^switch^ settings
12226 and object directory).
12227 Skeletal code for a main procedure might be something like the following:
12229 @smallexample @c ada
12232 procedure App_Main is
12241 Here is a project file, @file{app_proj.gpr}, that achieves the desired
12244 @smallexample @c projectfile
12246 with "/gui/gui_proj", "/comm/comm_proj";
12247 project App_Proj is
12248 for Main use ("app_main");
12254 Building an executable is achieved through the command:
12256 gnatmake ^-P/app/app_proj^/PROJECT_FILE=[APP]APP_PROJ^
12259 which will generate the @code{^app_main^APP_MAIN.EXE^} executable
12260 in the directory where @file{app_proj.gpr} resides.
12262 If an imported project file uses the standard extension (@code{^gpr^GPR^}) then
12263 (as illustrated above) the @code{with} clause can omit the extension.
12265 Our example specified an absolute path for each imported project file.
12266 Alternatively, the directory name of an imported object can be omitted
12270 The imported project file is in the same directory as the importing project
12273 You have defined ^an environment variable^a logical name^
12274 that includes the directory containing
12275 the needed project file. The syntax of @code{ADA_PROJECT_PATH} is the same as
12276 the syntax of @code{ADA_INCLUDE_PATH} and @code{ADA_OBJECTS_PATH}: a list of
12277 directory names separated by colons (semicolons on Windows).
12281 Thus, if we define @code{ADA_PROJECT_PATH} to include @file{^/gui^[GUI]^} and
12282 @file{^/comm^[COMM]^}, then our project file @file{app_proj.gpr} can be written
12285 @smallexample @c projectfile
12287 with "gui_proj", "comm_proj";
12288 project App_Proj is
12289 for Main use ("app_main");
12295 Importing other projects can create ambiguities.
12296 For example, the same unit might be present in different imported projects, or
12297 it might be present in both the importing project and in an imported project.
12298 Both of these conditions are errors. Note that in the current version of
12299 the Project Manager, it is illegal to have an ambiguous unit even if the
12300 unit is never referenced by the importing project. This restriction may be
12301 relaxed in a future release.
12303 @node Extending a Project
12304 @subsection Extending a Project
12307 In large software systems it is common to have multiple
12308 implementations of a common interface; in Ada terms, multiple versions of a
12309 package body for the same spec. For example, one implementation
12310 might be safe for use in tasking programs, while another might only be used
12311 in sequential applications. This can be modeled in GNAT using the concept
12312 of @emph{project extension}. If one project (the ``child'') @emph{extends}
12313 another project (the ``parent'') then by default all source files of the
12314 parent project are inherited by the child, but the child project can
12315 override any of the parent's source files with new versions, and can also
12316 add new files. This facility is the project analog of a type extension in
12317 Object-Oriented Programming. Project hierarchies are permitted (a child
12318 project may be the parent of yet another project), and a project that
12319 inherits one project can also import other projects.
12321 As an example, suppose that directory @file{^/seq^[SEQ]^} contains the project
12322 file @file{seq_proj.gpr} as well as the source files @file{pack.ads},
12323 @file{pack.adb}, and @file{proc.adb}:
12336 Note that the project file can simply be empty (that is, no attribute or
12337 package is defined):
12339 @smallexample @c projectfile
12341 project Seq_Proj is
12347 implying that its source files are all the Ada source files in the project
12350 Suppose we want to supply an alternate version of @file{pack.adb}, in
12351 directory @file{^/tasking^[TASKING]^}, but use the existing versions of
12352 @file{pack.ads} and @file{proc.adb}. We can define a project
12353 @code{Tasking_Proj} that inherits @code{Seq_Proj}:
12357 ^/tasking^[TASKING]^
12363 project Tasking_Proj extends "/seq/seq_proj" is
12369 The version of @file{pack.adb} used in a build depends on which project file
12372 Note that we could have obtained the desired behavior using project import
12373 rather than project inheritance; a @code{base} project would contain the
12374 sources for @file{pack.ads} and @file{proc.adb}, a sequential project would
12375 import @code{base} and add @file{pack.adb}, and likewise a tasking project
12376 would import @code{base} and add a different version of @file{pack.adb}. The
12377 choice depends on whether other sources in the original project need to be
12378 overridden. If they do, then project extension is necessary, otherwise,
12379 importing is sufficient.
12382 In a project file that extends another project file, it is possible to
12383 indicate that an inherited source is not part of the sources of the extending
12384 project. This is necessary sometimes when a package spec has been overloaded
12385 and no longer requires a body: in this case, it is necessary to indicate that
12386 the inherited body is not part of the sources of the project, otherwise there
12387 will be a compilation error when compiling the spec.
12389 For that purpose, the attribute @code{Excluded_Source_Files} is used.
12390 Its value is a string list: a list of file names. It is also possible to use
12391 attribute @code{Excluded_Source_List_File}. Its value is a single string:
12392 the file name of a text file containing a list of file names, one per line.
12394 @smallexample @c @projectfile
12395 project B extends "a" is
12396 for Source_Files use ("pkg.ads");
12397 -- New spec of Pkg does not need a completion
12398 for Excluded_Source_Files use ("pkg.adb");
12402 Attribute @code{Excluded_Source_Files} may also be used to check if a source
12403 is still needed: if it is possible to build using @command{gnatmake} when such
12404 a source is put in attribute @code{Excluded_Source_Files} of a project P, then
12405 it is possible to remove the source completely from a system that includes
12408 @c ***********************
12409 @c * Project File Syntax *
12410 @c ***********************
12412 @node Project File Syntax
12413 @section Project File Syntax
12417 * Qualified Projects::
12423 * Associative Array Attributes::
12424 * case Constructions::
12428 This section describes the structure of project files.
12430 A project may be an @emph{independent project}, entirely defined by a single
12431 project file. Any Ada source file in an independent project depends only
12432 on the predefined library and other Ada source files in the same project.
12435 A project may also @dfn{depend on} other projects, in either or both of
12436 the following ways:
12438 @item It may import any number of projects
12439 @item It may extend at most one other project
12443 The dependence relation is a directed acyclic graph (the subgraph reflecting
12444 the ``extends'' relation is a tree).
12446 A project's @dfn{immediate sources} are the source files directly defined by
12447 that project, either implicitly by residing in the project file's directory,
12448 or explicitly through any of the source-related attributes described below.
12449 More generally, a project @var{proj}'s @dfn{sources} are the immediate sources
12450 of @var{proj} together with the immediate sources (unless overridden) of any
12451 project on which @var{proj} depends (either directly or indirectly).
12454 @subsection Basic Syntax
12457 As seen in the earlier examples, project files have an Ada-like syntax.
12458 The minimal project file is:
12459 @smallexample @c projectfile
12468 The identifier @code{Empty} is the name of the project.
12469 This project name must be present after the reserved
12470 word @code{end} at the end of the project file, followed by a semi-colon.
12472 Any name in a project file, such as the project name or a variable name,
12473 has the same syntax as an Ada identifier.
12475 The reserved words of project files are the Ada 95 reserved words plus
12476 @code{extends}, @code{external}, and @code{project}. Note that the only Ada
12477 reserved words currently used in project file syntax are:
12513 Comments in project files have the same syntax as in Ada, two consecutive
12514 hyphens through the end of the line.
12516 @node Qualified Projects
12517 @subsection Qualified Projects
12520 Before the reserved @code{project}, there may be one or two "qualifiers", that
12521 is identifiers or other reserved words, to qualify the project.
12523 The current list of qualifiers is:
12527 @code{abstract}: qualify a project with no sources. An abstract project must
12528 have a declaration specifying that there are no sources in the project, and,
12529 if it extends another project, the project it extends must also be a qualified
12533 @code{standard}: a standard project is a non library project with sources.
12536 @code{aggregate}: for future extension
12539 @code{aggregate library}: for future extension
12542 @code{library}: a library project must declare both attributes
12543 @code{Library_Name} and @code{Library_Dir}.
12546 @code{configuration}: a configuration project cannot be in a project tree.
12550 @subsection Packages
12553 A project file may contain @emph{packages}. The name of a package must be one
12554 of the identifiers from the following list. A package
12555 with a given name may only appear once in a project file. Package names are
12556 case insensitive. The following package names are legal:
12572 @code{Cross_Reference}
12576 @code{Pretty_Printer}
12586 @code{Language_Processing}
12590 In its simplest form, a package may be empty:
12592 @smallexample @c projectfile
12602 A package may contain @emph{attribute declarations},
12603 @emph{variable declarations} and @emph{case constructions}, as will be
12606 When there is ambiguity between a project name and a package name,
12607 the name always designates the project. To avoid possible confusion, it is
12608 always a good idea to avoid naming a project with one of the
12609 names allowed for packages or any name that starts with @code{gnat}.
12612 @subsection Expressions
12615 An @emph{expression} is either a @emph{string expression} or a
12616 @emph{string list expression}.
12618 A @emph{string expression} is either a @emph{simple string expression} or a
12619 @emph{compound string expression}.
12621 A @emph{simple string expression} is one of the following:
12623 @item A literal string; e.g.@: @code{"comm/my_proj.gpr"}
12624 @item A string-valued variable reference (@pxref{Variables})
12625 @item A string-valued attribute reference (@pxref{Attributes})
12626 @item An external reference (@pxref{External References in Project Files})
12630 A @emph{compound string expression} is a concatenation of string expressions,
12631 using the operator @code{"&"}
12633 Path & "/" & File_Name & ".ads"
12637 A @emph{string list expression} is either a
12638 @emph{simple string list expression} or a
12639 @emph{compound string list expression}.
12641 A @emph{simple string list expression} is one of the following:
12643 @item A parenthesized list of zero or more string expressions,
12644 separated by commas
12646 File_Names := (File_Name, "gnat.adc", File_Name & ".orig");
12649 @item A string list-valued variable reference
12650 @item A string list-valued attribute reference
12654 A @emph{compound string list expression} is the concatenation (using
12655 @code{"&"}) of a simple string list expression and an expression. Note that
12656 each term in a compound string list expression, except the first, may be
12657 either a string expression or a string list expression.
12659 @smallexample @c projectfile
12661 File_Name_List := () & File_Name; -- One string in this list
12662 Extended_File_Name_List := File_Name_List & (File_Name & ".orig");
12664 Big_List := File_Name_List & Extended_File_Name_List;
12665 -- Concatenation of two string lists: three strings
12666 Illegal_List := "gnat.adc" & Extended_File_Name_List;
12667 -- Illegal: must start with a string list
12672 @subsection String Types
12675 A @emph{string type declaration} introduces a discrete set of string literals.
12676 If a string variable is declared to have this type, its value
12677 is restricted to the given set of literals.
12679 Here is an example of a string type declaration:
12681 @smallexample @c projectfile
12682 type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
12686 Variables of a string type are called @emph{typed variables}; all other
12687 variables are called @emph{untyped variables}. Typed variables are
12688 particularly useful in @code{case} constructions, to support conditional
12689 attribute declarations.
12690 (@pxref{case Constructions}).
12692 The string literals in the list are case sensitive and must all be different.
12693 They may include any graphic characters allowed in Ada, including spaces.
12695 A string type may only be declared at the project level, not inside a package.
12697 A string type may be referenced by its name if it has been declared in the same
12698 project file, or by an expanded name whose prefix is the name of the project
12699 in which it is declared.
12702 @subsection Variables
12705 A variable may be declared at the project file level, or within a package.
12706 Here are some examples of variable declarations:
12708 @smallexample @c projectfile
12710 This_OS : OS := external ("OS"); -- a typed variable declaration
12711 That_OS := "GNU/Linux"; -- an untyped variable declaration
12716 The syntax of a @emph{typed variable declaration} is identical to the Ada
12717 syntax for an object declaration. By contrast, the syntax of an untyped
12718 variable declaration is identical to an Ada assignment statement. In fact,
12719 variable declarations in project files have some of the characteristics of
12720 an assignment, in that successive declarations for the same variable are
12721 allowed. Untyped variable declarations do establish the expected kind of the
12722 variable (string or string list), and successive declarations for it must
12723 respect the initial kind.
12726 A string variable declaration (typed or untyped) declares a variable
12727 whose value is a string. This variable may be used as a string expression.
12728 @smallexample @c projectfile
12729 File_Name := "readme.txt";
12730 Saved_File_Name := File_Name & ".saved";
12734 A string list variable declaration declares a variable whose value is a list
12735 of strings. The list may contain any number (zero or more) of strings.
12737 @smallexample @c projectfile
12739 List_With_One_Element := ("^-gnaty^-gnaty^");
12740 List_With_Two_Elements := List_With_One_Element & "^-gnatg^-gnatg^";
12741 Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada"
12742 "pack2.ada", "util_.ada", "util.ada");
12746 The same typed variable may not be declared more than once at project level,
12747 and it may not be declared more than once in any package; it is in effect
12750 The same untyped variable may be declared several times. Declarations are
12751 elaborated in the order in which they appear, so the new value replaces
12752 the old one, and any subsequent reference to the variable uses the new value.
12753 However, as noted above, if a variable has been declared as a string, all
12755 declarations must give it a string value. Similarly, if a variable has
12756 been declared as a string list, all subsequent declarations
12757 must give it a string list value.
12759 A @emph{variable reference} may take several forms:
12762 @item The simple variable name, for a variable in the current package (if any)
12763 or in the current project
12764 @item An expanded name, whose prefix is a context name.
12768 A @emph{context} may be one of the following:
12771 @item The name of an existing package in the current project
12772 @item The name of an imported project of the current project
12773 @item The name of an ancestor project (i.e., a project extended by the current
12774 project, either directly or indirectly)
12775 @item An expanded name whose prefix is an imported/parent project name, and
12776 whose selector is a package name in that project.
12780 A variable reference may be used in an expression.
12783 @subsection Attributes
12786 A project (and its packages) may have @emph{attributes} that define
12787 the project's properties. Some attributes have values that are strings;
12788 others have values that are string lists.
12790 There are two categories of attributes: @emph{simple attributes}
12791 and @emph{associative arrays} (@pxref{Associative Array Attributes}).
12793 Legal project attribute names, and attribute names for each legal package are
12794 listed below. Attributes names are case-insensitive.
12796 The following attributes are defined on projects (all are simple attributes):
12798 @multitable @columnfractions .4 .3
12799 @item @emph{Attribute Name}
12801 @item @code{Source_Files}
12803 @item @code{Source_Dirs}
12805 @item @code{Source_List_File}
12807 @item @code{Object_Dir}
12809 @item @code{Exec_Dir}
12811 @item @code{Excluded_Source_Dirs}
12813 @item @code{Excluded_Source_Files}
12815 @item @code{Excluded_Source_List_File}
12817 @item @code{Languages}
12821 @item @code{Library_Dir}
12823 @item @code{Library_Name}
12825 @item @code{Library_Kind}
12827 @item @code{Library_Version}
12829 @item @code{Library_Interface}
12831 @item @code{Library_Auto_Init}
12833 @item @code{Library_Options}
12835 @item @code{Library_Src_Dir}
12837 @item @code{Library_ALI_Dir}
12839 @item @code{Library_GCC}
12841 @item @code{Library_Symbol_File}
12843 @item @code{Library_Symbol_Policy}
12845 @item @code{Library_Reference_Symbol_File}
12847 @item @code{Externally_Built}
12852 The following attributes are defined for package @code{Naming}
12853 (@pxref{Naming Schemes}):
12855 @multitable @columnfractions .4 .2 .2 .2
12856 @item Attribute Name @tab Category @tab Index @tab Value
12857 @item @code{Spec_Suffix}
12858 @tab associative array
12861 @item @code{Body_Suffix}
12862 @tab associative array
12865 @item @code{Separate_Suffix}
12866 @tab simple attribute
12869 @item @code{Casing}
12870 @tab simple attribute
12873 @item @code{Dot_Replacement}
12874 @tab simple attribute
12878 @tab associative array
12882 @tab associative array
12885 @item @code{Specification_Exceptions}
12886 @tab associative array
12889 @item @code{Implementation_Exceptions}
12890 @tab associative array
12896 The following attributes are defined for packages @code{Builder},
12897 @code{Compiler}, @code{Binder},
12898 @code{Linker}, @code{Cross_Reference}, and @code{Finder}
12899 (@pxref{^Switches^Switches^ and Project Files}).
12901 @multitable @columnfractions .4 .2 .2 .2
12902 @item Attribute Name @tab Category @tab Index @tab Value
12903 @item @code{^Default_Switches^Default_Switches^}
12904 @tab associative array
12907 @item @code{^Switches^Switches^}
12908 @tab associative array
12914 In addition, package @code{Compiler} has a single string attribute
12915 @code{Local_Configuration_Pragmas} and package @code{Builder} has a single
12916 string attribute @code{Global_Configuration_Pragmas}.
12919 Each simple attribute has a default value: the empty string (for string-valued
12920 attributes) and the empty list (for string list-valued attributes).
12922 An attribute declaration defines a new value for an attribute.
12924 Examples of simple attribute declarations:
12926 @smallexample @c projectfile
12927 for Object_Dir use "objects";
12928 for Source_Dirs use ("units", "test/drivers");
12932 The syntax of a @dfn{simple attribute declaration} is similar to that of an
12933 attribute definition clause in Ada.
12935 Attributes references may be appear in expressions.
12936 The general form for such a reference is @code{<entity>'<attribute>}:
12937 Associative array attributes are functions. Associative
12938 array attribute references must have an argument that is a string literal.
12942 @smallexample @c projectfile
12944 Naming'Dot_Replacement
12945 Imported_Project'Source_Dirs
12946 Imported_Project.Naming'Casing
12947 Builder'^Default_Switches^Default_Switches^("Ada")
12951 The prefix of an attribute may be:
12953 @item @code{project} for an attribute of the current project
12954 @item The name of an existing package of the current project
12955 @item The name of an imported project
12956 @item The name of a parent project that is extended by the current project
12957 @item An expanded name whose prefix is imported/parent project name,
12958 and whose selector is a package name
12963 @smallexample @c projectfile
12966 for Source_Dirs use project'Source_Dirs & "units";
12967 for Source_Dirs use project'Source_Dirs & "test/drivers"
12973 In the first attribute declaration, initially the attribute @code{Source_Dirs}
12974 has the default value: an empty string list. After this declaration,
12975 @code{Source_Dirs} is a string list of one element: @code{"units"}.
12976 After the second attribute declaration @code{Source_Dirs} is a string list of
12977 two elements: @code{"units"} and @code{"test/drivers"}.
12979 Note: this example is for illustration only. In practice,
12980 the project file would contain only one attribute declaration:
12982 @smallexample @c projectfile
12983 for Source_Dirs use ("units", "test/drivers");
12986 @node Associative Array Attributes
12987 @subsection Associative Array Attributes
12990 Some attributes are defined as @emph{associative arrays}. An associative
12991 array may be regarded as a function that takes a string as a parameter
12992 and delivers a string or string list value as its result.
12994 Here are some examples of single associative array attribute associations:
12996 @smallexample @c projectfile
12997 for Body ("main") use "Main.ada";
12998 for ^Switches^Switches^ ("main.ada")
13000 "^-gnatv^-gnatv^");
13001 for ^Switches^Switches^ ("main.ada")
13002 use Builder'^Switches^Switches^ ("main.ada")
13007 Like untyped variables and simple attributes, associative array attributes
13008 may be declared several times. Each declaration supplies a new value for the
13009 attribute, and replaces the previous setting.
13012 An associative array attribute may be declared as a full associative array
13013 declaration, with the value of the same attribute in an imported or extended
13016 @smallexample @c projectfile
13018 for Default_Switches use Default.Builder'Default_Switches;
13023 In this example, @code{Default} must be either a project imported by the
13024 current project, or the project that the current project extends. If the
13025 attribute is in a package (in this case, in package @code{Builder}), the same
13026 package needs to be specified.
13029 A full associative array declaration replaces any other declaration for the
13030 attribute, including other full associative array declaration. Single
13031 associative array associations may be declare after a full associative
13032 declaration, modifying the value for a single association of the attribute.
13034 @node case Constructions
13035 @subsection @code{case} Constructions
13038 A @code{case} construction is used in a project file to effect conditional
13040 Here is a typical example:
13042 @smallexample @c projectfile
13045 type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
13047 OS : OS_Type := external ("OS", "GNU/Linux");
13051 package Compiler is
13053 when "GNU/Linux" | "Unix" =>
13054 for ^Default_Switches^Default_Switches^ ("Ada")
13055 use ("^-gnath^-gnath^");
13057 for ^Default_Switches^Default_Switches^ ("Ada")
13058 use ("^-gnatP^-gnatP^");
13067 The syntax of a @code{case} construction is based on the Ada case statement
13068 (although there is no @code{null} construction for empty alternatives).
13070 The case expression must be a typed string variable.
13071 Each alternative comprises the reserved word @code{when}, either a list of
13072 literal strings separated by the @code{"|"} character or the reserved word
13073 @code{others}, and the @code{"=>"} token.
13074 Each literal string must belong to the string type that is the type of the
13076 An @code{others} alternative, if present, must occur last.
13078 After each @code{=>}, there are zero or more constructions. The only
13079 constructions allowed in a case construction are other case constructions,
13080 attribute declarations and variable declarations. String type declarations and
13081 package declarations are not allowed. Variable declarations are restricted to
13082 variables that have already been declared before the case construction.
13084 The value of the case variable is often given by an external reference
13085 (@pxref{External References in Project Files}).
13087 @c ****************************************
13088 @c * Objects and Sources in Project Files *
13089 @c ****************************************
13091 @node Objects and Sources in Project Files
13092 @section Objects and Sources in Project Files
13095 * Object Directory::
13097 * Source Directories::
13098 * Source File Names::
13102 Each project has exactly one object directory and one or more source
13103 directories. The source directories must contain at least one source file,
13104 unless the project file explicitly specifies that no source files are present
13105 (@pxref{Source File Names}).
13107 @node Object Directory
13108 @subsection Object Directory
13111 The object directory for a project is the directory containing the compiler's
13112 output (such as @file{ALI} files and object files) for the project's immediate
13115 The object directory is given by the value of the attribute @code{Object_Dir}
13116 in the project file.
13118 @smallexample @c projectfile
13119 for Object_Dir use "objects";
13123 The attribute @code{Object_Dir} has a string value, the path name of the object
13124 directory. The path name may be absolute or relative to the directory of the
13125 project file. This directory must already exist, and be readable and writable.
13127 By default, when the attribute @code{Object_Dir} is not given an explicit value
13128 or when its value is the empty string, the object directory is the same as the
13129 directory containing the project file.
13131 @node Exec Directory
13132 @subsection Exec Directory
13135 The exec directory for a project is the directory containing the executables
13136 for the project's main subprograms.
13138 The exec directory is given by the value of the attribute @code{Exec_Dir}
13139 in the project file.
13141 @smallexample @c projectfile
13142 for Exec_Dir use "executables";
13146 The attribute @code{Exec_Dir} has a string value, the path name of the exec
13147 directory. The path name may be absolute or relative to the directory of the
13148 project file. This directory must already exist, and be writable.
13150 By default, when the attribute @code{Exec_Dir} is not given an explicit value
13151 or when its value is the empty string, the exec directory is the same as the
13152 object directory of the project file.
13154 @node Source Directories
13155 @subsection Source Directories
13158 The source directories of a project are specified by the project file
13159 attribute @code{Source_Dirs}.
13161 This attribute's value is a string list. If the attribute is not given an
13162 explicit value, then there is only one source directory, the one where the
13163 project file resides.
13165 A @code{Source_Dirs} attribute that is explicitly defined to be the empty list,
13168 @smallexample @c projectfile
13169 for Source_Dirs use ();
13173 indicates that the project contains no source files.
13175 Otherwise, each string in the string list designates one or more
13176 source directories.
13178 @smallexample @c projectfile
13179 for Source_Dirs use ("sources", "test/drivers");
13183 If a string in the list ends with @code{"/**"}, then the directory whose path
13184 name precedes the two asterisks, as well as all its subdirectories
13185 (recursively), are source directories.
13187 @smallexample @c projectfile
13188 for Source_Dirs use ("/system/sources/**");
13192 Here the directory @code{/system/sources} and all of its subdirectories
13193 (recursively) are source directories.
13195 To specify that the source directories are the directory of the project file
13196 and all of its subdirectories, you can declare @code{Source_Dirs} as follows:
13197 @smallexample @c projectfile
13198 for Source_Dirs use ("./**");
13202 Each of the source directories must exist and be readable.
13204 @node Source File Names
13205 @subsection Source File Names
13208 In a project that contains source files, their names may be specified by the
13209 attributes @code{Source_Files} (a string list) or @code{Source_List_File}
13210 (a string). Source file names never include any directory information.
13212 If the attribute @code{Source_Files} is given an explicit value, then each
13213 element of the list is a source file name.
13215 @smallexample @c projectfile
13216 for Source_Files use ("main.adb");
13217 for Source_Files use ("main.adb", "pack1.ads", "pack2.adb");
13221 If the attribute @code{Source_Files} is not given an explicit value,
13222 but the attribute @code{Source_List_File} is given a string value,
13223 then the source file names are contained in the text file whose path name
13224 (absolute or relative to the directory of the project file) is the
13225 value of the attribute @code{Source_List_File}.
13227 Each line in the file that is not empty or is not a comment
13228 contains a source file name.
13230 @smallexample @c projectfile
13231 for Source_List_File use "source_list.txt";
13235 By default, if neither the attribute @code{Source_Files} nor the attribute
13236 @code{Source_List_File} is given an explicit value, then each file in the
13237 source directories that conforms to the project's naming scheme
13238 (@pxref{Naming Schemes}) is an immediate source of the project.
13240 A warning is issued if both attributes @code{Source_Files} and
13241 @code{Source_List_File} are given explicit values. In this case, the attribute
13242 @code{Source_Files} prevails.
13244 Each source file name must be the name of one existing source file
13245 in one of the source directories.
13247 A @code{Source_Files} attribute whose value is an empty list
13248 indicates that there are no source files in the project.
13250 If the order of the source directories is known statically, that is if
13251 @code{"/**"} is not used in the string list @code{Source_Dirs}, then there may
13252 be several files with the same source file name. In this case, only the file
13253 in the first directory is considered as an immediate source of the project
13254 file. If the order of the source directories is not known statically, it is
13255 an error to have several files with the same source file name.
13257 Projects can be specified to have no Ada source
13258 files: the value of (@code{Source_Dirs} or @code{Source_Files} may be an empty
13259 list, or the @code{"Ada"} may be absent from @code{Languages}:
13261 @smallexample @c projectfile
13262 for Source_Dirs use ();
13263 for Source_Files use ();
13264 for Languages use ("C", "C++");
13268 Otherwise, a project must contain at least one immediate source.
13270 Projects with no source files are useful as template packages
13271 (@pxref{Packages in Project Files}) for other projects; in particular to
13272 define a package @code{Naming} (@pxref{Naming Schemes}).
13274 @c ****************************
13275 @c * Importing Projects *
13276 @c ****************************
13278 @node Importing Projects
13279 @section Importing Projects
13280 @cindex @code{ADA_PROJECT_PATH}
13283 An immediate source of a project P may depend on source files that
13284 are neither immediate sources of P nor in the predefined library.
13285 To get this effect, P must @emph{import} the projects that contain the needed
13288 @smallexample @c projectfile
13290 with "project1", "utilities.gpr";
13291 with "/namings/apex.gpr";
13298 As can be seen in this example, the syntax for importing projects is similar
13299 to the syntax for importing compilation units in Ada. However, project files
13300 use literal strings instead of names, and the @code{with} clause identifies
13301 project files rather than packages.
13303 Each literal string is the file name or path name (absolute or relative) of a
13304 project file. If a string corresponds to a file name, with no path or a
13305 relative path, then its location is determined by the @emph{project path}. The
13306 latter can be queried using @code{gnatls -v}. It contains:
13310 In first position, the directory containing the current project file.
13312 In last position, the default project directory. This default project directory
13313 is part of the GNAT installation and is the standard place to install project
13314 files giving access to standard support libraries.
13316 @ref{Installing a library}
13320 In between, all the directories referenced in the
13321 ^environment variable^logical name^ @env{ADA_PROJECT_PATH} if it exists.
13325 If a relative pathname is used, as in
13327 @smallexample @c projectfile
13332 then the full path for the project is constructed by concatenating this
13333 relative path to those in the project path, in order, until a matching file is
13334 found. Any symbolic link will be fully resolved in the directory of the
13335 importing project file before the imported project file is examined.
13337 If the @code{with}'ed project file name does not have an extension,
13338 the default is @file{^.gpr^.GPR^}. If a file with this extension is not found,
13339 then the file name as specified in the @code{with} clause (no extension) will
13340 be used. In the above example, if a file @code{project1.gpr} is found, then it
13341 will be used; otherwise, if a file @code{^project1^PROJECT1^} exists
13342 then it will be used; if neither file exists, this is an error.
13344 A warning is issued if the name of the project file does not match the
13345 name of the project; this check is case insensitive.
13347 Any source file that is an immediate source of the imported project can be
13348 used by the immediate sources of the importing project, transitively. Thus
13349 if @code{A} imports @code{B}, and @code{B} imports @code{C}, the immediate
13350 sources of @code{A} may depend on the immediate sources of @code{C}, even if
13351 @code{A} does not import @code{C} explicitly. However, this is not recommended,
13352 because if and when @code{B} ceases to import @code{C}, some sources in
13353 @code{A} will no longer compile.
13355 A side effect of this capability is that normally cyclic dependencies are not
13356 permitted: if @code{A} imports @code{B} (directly or indirectly) then @code{B}
13357 is not allowed to import @code{A}. However, there are cases when cyclic
13358 dependencies would be beneficial. For these cases, another form of import
13359 between projects exists, the @code{limited with}: a project @code{A} that
13360 imports a project @code{B} with a straight @code{with} may also be imported,
13361 directly or indirectly, by @code{B} on the condition that imports from @code{B}
13362 to @code{A} include at least one @code{limited with}.
13364 @smallexample @c 0projectfile
13370 limited with "../a/a.gpr";
13378 limited with "../a/a.gpr";
13384 In the above legal example, there are two project cycles:
13387 @item A -> C -> D -> A
13391 In each of these cycle there is one @code{limited with}: import of @code{A}
13392 from @code{B} and import of @code{A} from @code{D}.
13394 The difference between straight @code{with} and @code{limited with} is that
13395 the name of a project imported with a @code{limited with} cannot be used in the
13396 project that imports it. In particular, its packages cannot be renamed and
13397 its variables cannot be referred to.
13399 An exception to the above rules for @code{limited with} is that for the main
13400 project specified to @command{gnatmake} or to the @command{GNAT} driver a
13401 @code{limited with} is equivalent to a straight @code{with}. For example,
13402 in the example above, projects @code{B} and @code{D} could not be main
13403 projects for @command{gnatmake} or to the @command{GNAT} driver, because they
13404 each have a @code{limited with} that is the only one in a cycle of importing
13407 @c *********************
13408 @c * Project Extension *
13409 @c *********************
13411 @node Project Extension
13412 @section Project Extension
13415 During development of a large system, it is sometimes necessary to use
13416 modified versions of some of the source files, without changing the original
13417 sources. This can be achieved through the @emph{project extension} facility.
13419 @smallexample @c projectfile
13420 project Modified_Utilities extends "/baseline/utilities.gpr" is @dots{}
13424 A project extension declaration introduces an extending project
13425 (the @emph{child}) and a project being extended (the @emph{parent}).
13427 By default, a child project inherits all the sources of its parent.
13428 However, inherited sources can be overridden: a unit in a parent is hidden
13429 by a unit of the same name in the child.
13431 Inherited sources are considered to be sources (but not immediate sources)
13432 of the child project; see @ref{Project File Syntax}.
13434 An inherited source file retains any switches specified in the parent project.
13436 For example if the project @code{Utilities} contains the spec and the
13437 body of an Ada package @code{Util_IO}, then the project
13438 @code{Modified_Utilities} can contain a new body for package @code{Util_IO}.
13439 The original body of @code{Util_IO} will not be considered in program builds.
13440 However, the package spec will still be found in the project
13443 A child project can have only one parent, except when it is qualified as
13444 abstract. But it may import any number of other projects.
13446 A project is not allowed to import directly or indirectly at the same time a
13447 child project and any of its ancestors.
13449 @c *******************************
13450 @c * Project Hierarchy Extension *
13451 @c *******************************
13453 @node Project Hierarchy Extension
13454 @section Project Hierarchy Extension
13457 When extending a large system spanning multiple projects, it is often
13458 inconvenient to extend every project in the hierarchy that is impacted by a
13459 small change introduced. In such cases, it is possible to create a virtual
13460 extension of entire hierarchy using @code{extends all} relationship.
13462 When the project is extended using @code{extends all} inheritance, all projects
13463 that are imported by it, both directly and indirectly, are considered virtually
13464 extended. That is, the Project Manager creates "virtual projects"
13465 that extend every project in the hierarchy; all these virtual projects have
13466 no sources of their own and have as object directory the object directory of
13467 the root of "extending all" project.
13469 It is possible to explicitly extend one or more projects in the hierarchy
13470 in order to modify the sources. These extending projects must be imported by
13471 the "extending all" project, which will replace the corresponding virtual
13472 projects with the explicit ones.
13474 When building such a project hierarchy extension, the Project Manager will
13475 ensure that both modified sources and sources in virtual extending projects
13476 that depend on them, are recompiled.
13478 By means of example, consider the following hierarchy of projects.
13482 project A, containing package P1
13484 project B importing A and containing package P2 which depends on P1
13486 project C importing B and containing package P3 which depends on P2
13490 We want to modify packages P1 and P3.
13492 This project hierarchy will need to be extended as follows:
13496 Create project A1 that extends A, placing modified P1 there:
13498 @smallexample @c 0projectfile
13499 project A1 extends "(@dots{})/A" is
13504 Create project C1 that "extends all" C and imports A1, placing modified
13507 @smallexample @c 0projectfile
13508 with "(@dots{})/A1";
13509 project C1 extends all "(@dots{})/C" is
13514 When you build project C1, your entire modified project space will be
13515 recompiled, including the virtual project B1 that has been impacted by the
13516 "extending all" inheritance of project C.
13518 Note that if a Library Project in the hierarchy is virtually extended,
13519 the virtual project that extends the Library Project is not a Library Project.
13521 @c ****************************************
13522 @c * External References in Project Files *
13523 @c ****************************************
13525 @node External References in Project Files
13526 @section External References in Project Files
13529 A project file may contain references to external variables; such references
13530 are called @emph{external references}.
13532 An external variable is either defined as part of the environment (an
13533 environment variable in Unix, for example) or else specified on the command
13534 line via the @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch.
13535 If both, then the command line value is used.
13537 The value of an external reference is obtained by means of the built-in
13538 function @code{external}, which returns a string value.
13539 This function has two forms:
13541 @item @code{external (external_variable_name)}
13542 @item @code{external (external_variable_name, default_value)}
13546 Each parameter must be a string literal. For example:
13548 @smallexample @c projectfile
13550 external ("OS", "GNU/Linux")
13554 In the form with one parameter, the function returns the value of
13555 the external variable given as parameter. If this name is not present in the
13556 environment, the function returns an empty string.
13558 In the form with two string parameters, the second argument is
13559 the value returned when the variable given as the first argument is not
13560 present in the environment. In the example above, if @code{"OS"} is not
13561 the name of ^an environment variable^a logical name^ and is not passed on
13562 the command line, then the returned value is @code{"GNU/Linux"}.
13564 An external reference may be part of a string expression or of a string
13565 list expression, and can therefore appear in a variable declaration or
13566 an attribute declaration.
13568 @smallexample @c projectfile
13570 type Mode_Type is ("Debug", "Release");
13571 Mode : Mode_Type := external ("MODE");
13578 @c *****************************
13579 @c * Packages in Project Files *
13580 @c *****************************
13582 @node Packages in Project Files
13583 @section Packages in Project Files
13586 A @emph{package} defines the settings for project-aware tools within a
13588 For each such tool one can declare a package; the names for these
13589 packages are preset (@pxref{Packages}).
13590 A package may contain variable declarations, attribute declarations, and case
13593 @smallexample @c projectfile
13596 package Builder is -- used by gnatmake
13597 for ^Default_Switches^Default_Switches^ ("Ada")
13606 The syntax of package declarations mimics that of package in Ada.
13608 Most of the packages have an attribute
13609 @code{^Default_Switches^Default_Switches^}.
13610 This attribute is an associative array, and its value is a string list.
13611 The index of the associative array is the name of a programming language (case
13612 insensitive). This attribute indicates the ^switch^switch^
13613 or ^switches^switches^ to be used
13614 with the corresponding tool.
13616 Some packages also have another attribute, @code{^Switches^Switches^},
13617 an associative array whose value is a string list.
13618 The index is the name of a source file.
13619 This attribute indicates the ^switch^switch^
13620 or ^switches^switches^ to be used by the corresponding
13621 tool when dealing with this specific file.
13623 Further information on these ^switch^switch^-related attributes is found in
13624 @ref{^Switches^Switches^ and Project Files}.
13626 A package may be declared as a @emph{renaming} of another package; e.g., from
13627 the project file for an imported project.
13629 @smallexample @c projectfile
13631 with "/global/apex.gpr";
13633 package Naming renames Apex.Naming;
13640 Packages that are renamed in other project files often come from project files
13641 that have no sources: they are just used as templates. Any modification in the
13642 template will be reflected automatically in all the project files that rename
13643 a package from the template.
13645 In addition to the tool-oriented packages, you can also declare a package
13646 named @code{Naming} to establish specialized source file naming conventions
13647 (@pxref{Naming Schemes}).
13649 @c ************************************
13650 @c * Variables from Imported Projects *
13651 @c ************************************
13653 @node Variables from Imported Projects
13654 @section Variables from Imported Projects
13657 An attribute or variable defined in an imported or parent project can
13658 be used in expressions in the importing / extending project.
13659 Such an attribute or variable is denoted by an expanded name whose prefix
13660 is either the name of the project or the expanded name of a package within
13663 @smallexample @c projectfile
13666 project Main extends "base" is
13667 Var1 := Imported.Var;
13668 Var2 := Base.Var & ".new";
13673 for ^Default_Switches^Default_Switches^ ("Ada")
13674 use Imported.Builder'Ada_^Switches^Switches^ &
13675 "^-gnatg^-gnatg^" &
13681 package Compiler is
13682 for ^Default_Switches^Default_Switches^ ("Ada")
13683 use Base.Compiler'Ada_^Switches^Switches^;
13694 The value of @code{Var1} is a copy of the variable @code{Var} defined
13695 in the project file @file{"imported.gpr"}
13697 the value of @code{Var2} is a copy of the value of variable @code{Var}
13698 defined in the project file @file{base.gpr}, concatenated with @code{".new"}
13700 attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package
13701 @code{Builder} is a string list that includes in its value a copy of the value
13702 of @code{Ada_^Switches^Switches^} defined in the @code{Builder} package
13703 in project file @file{imported.gpr} plus two new elements:
13704 @option{"^-gnatg^-gnatg^"}
13705 and @option{"^-v^-v^"};
13707 attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package
13708 @code{Compiler} is a copy of the variable @code{Ada_^Switches^Switches^}
13709 defined in the @code{Compiler} package in project file @file{base.gpr},
13710 the project being extended.
13713 @c ******************
13714 @c * Naming Schemes *
13715 @c ******************
13717 @node Naming Schemes
13718 @section Naming Schemes
13721 Sometimes an Ada software system is ported from a foreign compilation
13722 environment to GNAT, and the file names do not use the default GNAT
13723 conventions. Instead of changing all the file names (which for a variety
13724 of reasons might not be possible), you can define the relevant file
13725 naming scheme in the @code{Naming} package in your project file.
13728 Note that the use of pragmas described in
13729 @ref{Alternative File Naming Schemes} by mean of a configuration
13730 pragmas file is not supported when using project files. You must use
13731 the features described in this paragraph. You can however use specify
13732 other configuration pragmas (@pxref{Specifying Configuration Pragmas}).
13735 For example, the following
13736 package models the Apex file naming rules:
13738 @smallexample @c projectfile
13741 for Casing use "lowercase";
13742 for Dot_Replacement use ".";
13743 for Spec_Suffix ("Ada") use ".1.ada";
13744 for Body_Suffix ("Ada") use ".2.ada";
13751 For example, the following package models the HP Ada file naming rules:
13753 @smallexample @c projectfile
13756 for Casing use "lowercase";
13757 for Dot_Replacement use "__";
13758 for Spec_Suffix ("Ada") use "_.^ada^ada^";
13759 for Body_Suffix ("Ada") use ".^ada^ada^";
13765 (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
13766 names in lower case)
13770 You can define the following attributes in package @code{Naming}:
13774 @item @code{Casing}
13775 This must be a string with one of the three values @code{"lowercase"},
13776 @code{"uppercase"} or @code{"mixedcase"}; these strings are case insensitive.
13779 If @code{Casing} is not specified, then the default is @code{"lowercase"}.
13781 @item @code{Dot_Replacement}
13782 This must be a string whose value satisfies the following conditions:
13785 @item It must not be empty
13786 @item It cannot start or end with an alphanumeric character
13787 @item It cannot be a single underscore
13788 @item It cannot start with an underscore followed by an alphanumeric
13789 @item It cannot contain a dot @code{'.'} except if the entire string
13794 If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
13796 @item @code{Spec_Suffix}
13797 This is an associative array (indexed by the programming language name, case
13798 insensitive) whose value is a string that must satisfy the following
13802 @item It must not be empty
13803 @item It must include at least one dot
13806 If @code{Spec_Suffix ("Ada")} is not specified, then the default is
13807 @code{"^.ads^.ADS^"}.
13809 @item @code{Body_Suffix}
13810 This is an associative array (indexed by the programming language name, case
13811 insensitive) whose value is a string that must satisfy the following
13815 @item It must not be empty
13816 @item It must include at least one dot
13817 @item It cannot be the same as @code{Spec_Suffix ("Ada")}
13820 If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
13821 same string, then a file name that ends with the longest of these two suffixes
13822 will be a body if the longest suffix is @code{Body_Suffix ("Ada")} or a spec
13823 if the longest suffix is @code{Spec_Suffix ("Ada")}.
13825 If @code{Body_Suffix ("Ada")} is not specified, then the default is
13826 @code{"^.adb^.ADB^"}.
13828 @item @code{Separate_Suffix}
13829 This must be a string whose value satisfies the same conditions as
13830 @code{Body_Suffix}. The same "longest suffix" rules apply.
13833 If @code{Separate_Suffix ("Ada")} is not specified, then it defaults to same
13834 value as @code{Body_Suffix ("Ada")}.
13838 You can use the associative array attribute @code{Spec} to define
13839 the source file name for an individual Ada compilation unit's spec. The array
13840 index must be a string literal that identifies the Ada unit (case insensitive).
13841 The value of this attribute must be a string that identifies the file that
13842 contains this unit's spec (case sensitive or insensitive depending on the
13845 @smallexample @c projectfile
13846 for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
13849 When the source file contains several units, you can indicate at what
13850 position the unit occurs in the file, with the following. The first unit
13851 in the file has index 1
13853 @smallexample @c projectfile
13854 for Body ("top") use "foo.a" at 1;
13855 for Body ("foo") use "foo.a" at 2;
13860 You can use the associative array attribute @code{Body} to
13861 define the source file name for an individual Ada compilation unit's body
13862 (possibly a subunit). The array index must be a string literal that identifies
13863 the Ada unit (case insensitive). The value of this attribute must be a string
13864 that identifies the file that contains this unit's body or subunit (case
13865 sensitive or insensitive depending on the operating system).
13867 @smallexample @c projectfile
13868 for Body ("MyPack.MyChild") use "mypack.mychild.body";
13872 @c ********************
13873 @c * Library Projects *
13874 @c ********************
13876 @node Library Projects
13877 @section Library Projects
13880 @emph{Library projects} are projects whose object code is placed in a library.
13881 (Note that this facility is not yet supported on all platforms).
13883 @code{gnatmake} or @code{gprbuild} will collect all object files into a
13884 single archive, which might either be a shared or a static library. This
13885 library can later on be linked with multiple executables, potentially
13886 reducing their sizes.
13888 If your project file specifies languages other than Ada, but you are still
13889 using @code{gnatmake} to compile and link, the latter will not try to
13890 compile your sources other than Ada (you should use @code{gprbuild} if that
13891 is your intent). However, @code{gnatmake} will automatically link all object
13892 files found in the object directory, whether or not they were compiled from
13893 an Ada source file. This specific behavior only applies when multiple
13894 languages are specified.
13896 To create a library project, you need to define in its project file
13897 two project-level attributes: @code{Library_Name} and @code{Library_Dir}.
13898 Additionally, you may define other library-related attributes such as
13899 @code{Library_Kind}, @code{Library_Version}, @code{Library_Interface},
13900 @code{Library_Auto_Init}, @code{Library_Options} and @code{Library_GCC}.
13902 The @code{Library_Name} attribute has a string value. There is no restriction
13903 on the name of a library. It is the responsibility of the developer to
13904 choose a name that will be accepted by the platform. It is recommended to
13905 choose names that could be Ada identifiers; such names are almost guaranteed
13906 to be acceptable on all platforms.
13908 The @code{Library_Dir} attribute has a string value that designates the path
13909 (absolute or relative) of the directory where the library will reside.
13910 It must designate an existing directory, and this directory must be writable,
13911 different from the project's object directory and from any source directory
13912 in the project tree.
13914 If both @code{Library_Name} and @code{Library_Dir} are specified and
13915 are legal, then the project file defines a library project. The optional
13916 library-related attributes are checked only for such project files.
13918 The @code{Library_Kind} attribute has a string value that must be one of the
13919 following (case insensitive): @code{"static"}, @code{"dynamic"} or
13920 @code{"relocatable"} (which is a synonym for @code{"dynamic"}). If this
13921 attribute is not specified, the library is a static library, that is
13922 an archive of object files that can be potentially linked into a
13923 static executable. Otherwise, the library may be dynamic or
13924 relocatable, that is a library that is loaded only at the start of execution.
13926 If you need to build both a static and a dynamic library, you should use two
13927 different object directories, since in some cases some extra code needs to
13928 be generated for the latter. For such cases, it is recommended to either use
13929 two different project files, or a single one which uses external variables
13930 to indicate what kind of library should be build.
13932 The @code{Library_ALI_Dir} attribute may be specified to indicate the
13933 directory where the ALI files of the library will be copied. When it is
13934 not specified, the ALI files are copied to the directory specified in
13935 attribute @code{Library_Dir}. The directory specified by @code{Library_ALI_Dir}
13936 must be writable and different from the project's object directory and from
13937 any source directory in the project tree.
13939 The @code{Library_Version} attribute has a string value whose interpretation
13940 is platform dependent. It has no effect on VMS and Windows. On Unix, it is
13941 used only for dynamic/relocatable libraries as the internal name of the
13942 library (the @code{"soname"}). If the library file name (built from the
13943 @code{Library_Name}) is different from the @code{Library_Version}, then the
13944 library file will be a symbolic link to the actual file whose name will be
13945 @code{Library_Version}.
13949 @smallexample @c projectfile
13955 for Library_Dir use "lib_dir";
13956 for Library_Name use "dummy";
13957 for Library_Kind use "relocatable";
13958 for Library_Version use "libdummy.so." & Version;
13965 Directory @file{lib_dir} will contain the internal library file whose name
13966 will be @file{libdummy.so.1}, and @file{libdummy.so} will be a symbolic link to
13967 @file{libdummy.so.1}.
13969 When @command{gnatmake} detects that a project file
13970 is a library project file, it will check all immediate sources of the project
13971 and rebuild the library if any of the sources have been recompiled.
13973 Standard project files can import library project files. In such cases,
13974 the libraries will only be rebuilt if some of its sources are recompiled
13975 because they are in the closure of some other source in an importing project.
13976 Sources of the library project files that are not in such a closure will
13977 not be checked, unless the full library is checked, because one of its sources
13978 needs to be recompiled.
13980 For instance, assume the project file @code{A} imports the library project file
13981 @code{L}. The immediate sources of A are @file{a1.adb}, @file{a2.ads} and
13982 @file{a2.adb}. The immediate sources of L are @file{l1.ads}, @file{l1.adb},
13983 @file{l2.ads}, @file{l2.adb}.
13985 If @file{l1.adb} has been modified, then the library associated with @code{L}
13986 will be rebuilt when compiling all the immediate sources of @code{A} only
13987 if @file{a1.ads}, @file{a2.ads} or @file{a2.adb} includes a statement
13990 To be sure that all the sources in the library associated with @code{L} are
13991 up to date, and that all the sources of project @code{A} are also up to date,
13992 the following two commands needs to be used:
13999 When a library is built or rebuilt, an attempt is made first to delete all
14000 files in the library directory.
14001 All @file{ALI} files will also be copied from the object directory to the
14002 library directory. To build executables, @command{gnatmake} will use the
14003 library rather than the individual object files.
14006 It is also possible to create library project files for third-party libraries
14007 that are precompiled and cannot be compiled locally thanks to the
14008 @code{externally_built} attribute. (See @ref{Installing a library}).
14011 @c *******************************
14012 @c * Stand-alone Library Projects *
14013 @c *******************************
14015 @node Stand-alone Library Projects
14016 @section Stand-alone Library Projects
14019 A Stand-alone Library is a library that contains the necessary code to
14020 elaborate the Ada units that are included in the library. A Stand-alone
14021 Library is suitable to be used in an executable when the main is not
14022 in Ada. However, Stand-alone Libraries may also be used with an Ada main
14025 A Stand-alone Library Project is a Library Project where the library is
14026 a Stand-alone Library.
14028 To be a Stand-alone Library Project, in addition to the two attributes
14029 that make a project a Library Project (@code{Library_Name} and
14030 @code{Library_Dir}, see @ref{Library Projects}), the attribute
14031 @code{Library_Interface} must be defined.
14033 @smallexample @c projectfile
14035 for Library_Dir use "lib_dir";
14036 for Library_Name use "dummy";
14037 for Library_Interface use ("int1", "int1.child");
14041 Attribute @code{Library_Interface} has a nonempty string list value,
14042 each string in the list designating a unit contained in an immediate source
14043 of the project file.
14045 When a Stand-alone Library is built, first the binder is invoked to build
14046 a package whose name depends on the library name
14047 (^b~dummy.ads/b^B$DUMMY.ADS/B^ in the example above).
14048 This binder-generated package includes initialization and
14049 finalization procedures whose
14050 names depend on the library name (dummyinit and dummyfinal in the example
14051 above). The object corresponding to this package is included in the library.
14053 A dynamic or relocatable Stand-alone Library is automatically initialized
14054 if automatic initialization of Stand-alone Libraries is supported on the
14055 platform and if attribute @code{Library_Auto_Init} is not specified or
14056 is specified with the value "true". A static Stand-alone Library is never
14057 automatically initialized.
14059 Single string attribute @code{Library_Auto_Init} may be specified with only
14060 two possible values: "false" or "true" (case-insensitive). Specifying
14061 "false" for attribute @code{Library_Auto_Init} will prevent automatic
14062 initialization of dynamic or relocatable libraries.
14064 When a non-automatically initialized Stand-alone Library is used
14065 in an executable, its initialization procedure must be called before
14066 any service of the library is used.
14067 When the main subprogram is in Ada, it may mean that the initialization
14068 procedure has to be called during elaboration of another package.
14070 For a Stand-Alone Library, only the @file{ALI} files of the Interface Units
14071 (those that are listed in attribute @code{Library_Interface}) are copied to
14072 the Library Directory. As a consequence, only the Interface Units may be
14073 imported from Ada units outside of the library. If other units are imported,
14074 the binding phase will fail.
14076 When a Stand-Alone Library is bound, the switches that are specified in
14077 the attribute @code{Default_Switches ("Ada")} in package @code{Binder} are
14078 used in the call to @command{gnatbind}.
14080 The string list attribute @code{Library_Options} may be used to specified
14081 additional switches to the call to @command{gcc} to link the library.
14083 The attribute @code{Library_Src_Dir}, may be specified for a
14084 Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
14085 single string value. Its value must be the path (absolute or relative to the
14086 project directory) of an existing directory. This directory cannot be the
14087 object directory or one of the source directories, but it can be the same as
14088 the library directory. The sources of the Interface
14089 Units of the library, necessary to an Ada client of the library, will be
14090 copied to the designated directory, called Interface Copy directory.
14091 These sources includes the specs of the Interface Units, but they may also
14092 include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
14093 are used, or when there is a generic units in the spec. Before the sources
14094 are copied to the Interface Copy directory, an attempt is made to delete all
14095 files in the Interface Copy directory.
14097 @c *************************************
14098 @c * Switches Related to Project Files *
14099 @c *************************************
14100 @node Switches Related to Project Files
14101 @section Switches Related to Project Files
14104 The following switches are used by GNAT tools that support project files:
14108 @item ^-P^/PROJECT_FILE=^@var{project}
14109 @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
14110 Indicates the name of a project file. This project file will be parsed with
14111 the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
14112 if any, and using the external references indicated
14113 by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
14115 There may zero, one or more spaces between @option{-P} and @var{project}.
14119 There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
14122 Since the Project Manager parses the project file only after all the switches
14123 on the command line are checked, the order of the switches
14124 @option{^-P^/PROJECT_FILE^},
14125 @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
14126 or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
14128 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
14129 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
14130 Indicates that external variable @var{name} has the value @var{value}.
14131 The Project Manager will use this value for occurrences of
14132 @code{external(name)} when parsing the project file.
14136 If @var{name} or @var{value} includes a space, then @var{name=value} should be
14137 put between quotes.
14145 Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
14146 If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
14147 @var{name}, only the last one is used.
14150 An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
14151 takes precedence over the value of the same name in the environment.
14153 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
14154 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
14155 Indicates the verbosity of the parsing of GNAT project files.
14158 @option{-vP0} means Default;
14159 @option{-vP1} means Medium;
14160 @option{-vP2} means High.
14164 There are three possible options for this qualifier: DEFAULT, MEDIUM and
14169 The default is ^Default^DEFAULT^: no output for syntactically correct
14172 If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
14173 only the last one is used.
14175 @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
14176 @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
14177 Add directory <dir> at the beginning of the project search path, in order,
14178 after the current working directory.
14182 @cindex @option{-eL} (any project-aware tool)
14183 Follow all symbolic links when processing project files.
14186 @item ^--subdirs^/SUBDIRS^=<subdir>
14187 @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
14188 This switch is recognized by gnatmake and gnatclean. It indicate that the real
14189 directories (except the source directories) are the subdirectories <subdir>
14190 of the directories specified in the project files. This applies in particular
14191 to object directories, library directories and exec directories. If the
14192 subdirectories do not exist, they are created automatically.
14196 @c **********************************
14197 @c * Tools Supporting Project Files *
14198 @c **********************************
14200 @node Tools Supporting Project Files
14201 @section Tools Supporting Project Files
14204 * gnatmake and Project Files::
14205 * The GNAT Driver and Project Files::
14208 @node gnatmake and Project Files
14209 @subsection gnatmake and Project Files
14212 This section covers several topics related to @command{gnatmake} and
14213 project files: defining ^switches^switches^ for @command{gnatmake}
14214 and for the tools that it invokes; specifying configuration pragmas;
14215 the use of the @code{Main} attribute; building and rebuilding library project
14219 * ^Switches^Switches^ and Project Files::
14220 * Specifying Configuration Pragmas::
14221 * Project Files and Main Subprograms::
14222 * Library Project Files::
14225 @node ^Switches^Switches^ and Project Files
14226 @subsubsection ^Switches^Switches^ and Project Files
14229 It is not currently possible to specify VMS style qualifiers in the project
14230 files; only Unix style ^switches^switches^ may be specified.
14234 For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
14235 @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
14236 attribute, a @code{^Switches^Switches^} attribute, or both;
14237 as their names imply, these ^switch^switch^-related
14238 attributes affect the ^switches^switches^ that are used for each of these GNAT
14240 @command{gnatmake} is invoked. As will be explained below, these
14241 component-specific ^switches^switches^ precede
14242 the ^switches^switches^ provided on the @command{gnatmake} command line.
14244 The @code{^Default_Switches^Default_Switches^} attribute is an associative
14245 array indexed by language name (case insensitive) whose value is a string list.
14248 @smallexample @c projectfile
14250 package Compiler is
14251 for ^Default_Switches^Default_Switches^ ("Ada")
14252 use ("^-gnaty^-gnaty^",
14259 The @code{^Switches^Switches^} attribute is also an associative array,
14260 indexed by a file name (which may or may not be case sensitive, depending
14261 on the operating system) whose value is a string list. For example:
14263 @smallexample @c projectfile
14266 for ^Switches^Switches^ ("main1.adb")
14268 for ^Switches^Switches^ ("main2.adb")
14275 For the @code{Builder} package, the file names must designate source files
14276 for main subprograms. For the @code{Binder} and @code{Linker} packages, the
14277 file names must designate @file{ALI} or source files for main subprograms.
14278 In each case just the file name without an explicit extension is acceptable.
14280 For each tool used in a program build (@command{gnatmake}, the compiler, the
14281 binder, and the linker), the corresponding package @dfn{contributes} a set of
14282 ^switches^switches^ for each file on which the tool is invoked, based on the
14283 ^switch^switch^-related attributes defined in the package.
14284 In particular, the ^switches^switches^
14285 that each of these packages contributes for a given file @var{f} comprise:
14289 the value of attribute @code{^Switches^Switches^ (@var{f})},
14290 if it is specified in the package for the given file,
14292 otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
14293 if it is specified in the package.
14297 If neither of these attributes is defined in the package, then the package does
14298 not contribute any ^switches^switches^ for the given file.
14300 When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
14301 two sets, in the following order: those contributed for the file
14302 by the @code{Builder} package;
14303 and the switches passed on the command line.
14305 When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
14306 the ^switches^switches^ passed to the tool comprise three sets,
14307 in the following order:
14311 the applicable ^switches^switches^ contributed for the file
14312 by the @code{Builder} package in the project file supplied on the command line;
14315 those contributed for the file by the package (in the relevant project file --
14316 see below) corresponding to the tool; and
14319 the applicable switches passed on the command line.
14323 The term @emph{applicable ^switches^switches^} reflects the fact that
14324 @command{gnatmake} ^switches^switches^ may or may not be passed to individual
14325 tools, depending on the individual ^switch^switch^.
14327 @command{gnatmake} may invoke the compiler on source files from different
14328 projects. The Project Manager will use the appropriate project file to
14329 determine the @code{Compiler} package for each source file being compiled.
14330 Likewise for the @code{Binder} and @code{Linker} packages.
14332 As an example, consider the following package in a project file:
14334 @smallexample @c projectfile
14337 package Compiler is
14338 for ^Default_Switches^Default_Switches^ ("Ada")
14340 for ^Switches^Switches^ ("a.adb")
14342 for ^Switches^Switches^ ("b.adb")
14344 "^-gnaty^-gnaty^");
14351 If @command{gnatmake} is invoked with this project file, and it needs to
14352 compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
14353 @file{a.adb} will be compiled with the ^switch^switch^
14354 @option{^-O1^-O1^},
14355 @file{b.adb} with ^switches^switches^
14357 and @option{^-gnaty^-gnaty^},
14358 and @file{c.adb} with @option{^-g^-g^}.
14360 The following example illustrates the ordering of the ^switches^switches^
14361 contributed by different packages:
14363 @smallexample @c projectfile
14367 for ^Switches^Switches^ ("main.adb")
14375 package Compiler is
14376 for ^Switches^Switches^ ("main.adb")
14384 If you issue the command:
14387 gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
14391 then the compiler will be invoked on @file{main.adb} with the following
14392 sequence of ^switches^switches^
14395 ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
14398 with the last @option{^-O^-O^}
14399 ^switch^switch^ having precedence over the earlier ones;
14400 several other ^switches^switches^
14401 (such as @option{^-c^-c^}) are added implicitly.
14403 The ^switches^switches^
14405 and @option{^-O1^-O1^} are contributed by package
14406 @code{Builder}, @option{^-O2^-O2^} is contributed
14407 by the package @code{Compiler}
14408 and @option{^-O0^-O0^} comes from the command line.
14410 The @option{^-g^-g^}
14411 ^switch^switch^ will also be passed in the invocation of
14412 @command{Gnatlink.}
14414 A final example illustrates switch contributions from packages in different
14417 @smallexample @c projectfile
14420 for Source_Files use ("pack.ads", "pack.adb");
14421 package Compiler is
14422 for ^Default_Switches^Default_Switches^ ("Ada")
14423 use ("^-gnata^-gnata^");
14431 for Source_Files use ("foo_main.adb", "bar_main.adb");
14433 for ^Switches^Switches^ ("foo_main.adb")
14441 -- Ada source file:
14443 procedure Foo_Main is
14451 gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
14455 then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
14456 @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
14457 @option{^-gnato^-gnato^} (passed on the command line).
14458 When the imported package @code{Pack} is compiled, the ^switches^switches^ used
14459 are @option{^-g^-g^} from @code{Proj4.Builder},
14460 @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
14461 and @option{^-gnato^-gnato^} from the command line.
14464 When using @command{gnatmake} with project files, some ^switches^switches^ or
14465 arguments may be expressed as relative paths. As the working directory where
14466 compilation occurs may change, these relative paths are converted to absolute
14467 paths. For the ^switches^switches^ found in a project file, the relative paths
14468 are relative to the project file directory, for the switches on the command
14469 line, they are relative to the directory where @command{gnatmake} is invoked.
14470 The ^switches^switches^ for which this occurs are:
14476 ^-aI^-aI^, as well as all arguments that are not switches (arguments to
14478 ^-o^-o^, object files specified in package @code{Linker} or after
14479 -largs on the command line). The exception to this rule is the ^switch^switch^
14480 ^--RTS=^--RTS=^ for which a relative path argument is never converted.
14482 @node Specifying Configuration Pragmas
14483 @subsubsection Specifying Configuration Pragmas
14485 When using @command{gnatmake} with project files, if there exists a file
14486 @file{gnat.adc} that contains configuration pragmas, this file will be
14489 Configuration pragmas can be defined by means of the following attributes in
14490 project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
14491 and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
14493 Both these attributes are single string attributes. Their values is the path
14494 name of a file containing configuration pragmas. If a path name is relative,
14495 then it is relative to the project directory of the project file where the
14496 attribute is defined.
14498 When compiling a source, the configuration pragmas used are, in order,
14499 those listed in the file designated by attribute
14500 @code{Global_Configuration_Pragmas} in package @code{Builder} of the main
14501 project file, if it is specified, and those listed in the file designated by
14502 attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
14503 the project file of the source, if it exists.
14505 @node Project Files and Main Subprograms
14506 @subsubsection Project Files and Main Subprograms
14509 When using a project file, you can invoke @command{gnatmake}
14510 with one or several main subprograms, by specifying their source files on the
14514 gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3
14518 Each of these needs to be a source file of the same project, except
14519 when the switch ^-u^/UNIQUE^ is used.
14522 When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
14523 same project, one of the project in the tree rooted at the project specified
14524 on the command line. The package @code{Builder} of this common project, the
14525 "main project" is the one that is considered by @command{gnatmake}.
14528 When ^-u^/UNIQUE^ is used, the specified source files may be in projects
14529 imported directly or indirectly by the project specified on the command line.
14530 Note that if such a source file is not part of the project specified on the
14531 command line, the ^switches^switches^ found in package @code{Builder} of the
14532 project specified on the command line, if any, that are transmitted
14533 to the compiler will still be used, not those found in the project file of
14537 When using a project file, you can also invoke @command{gnatmake} without
14538 explicitly specifying any main, and the effect depends on whether you have
14539 defined the @code{Main} attribute. This attribute has a string list value,
14540 where each element in the list is the name of a source file (the file
14541 extension is optional) that contains a unit that can be a main subprogram.
14543 If the @code{Main} attribute is defined in a project file as a non-empty
14544 string list and the switch @option{^-u^/UNIQUE^} is not used on the command
14545 line, then invoking @command{gnatmake} with this project file but without any
14546 main on the command line is equivalent to invoking @command{gnatmake} with all
14547 the file names in the @code{Main} attribute on the command line.
14550 @smallexample @c projectfile
14553 for Main use ("main1", "main2", "main3");
14559 With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
14561 @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}.
14563 When the project attribute @code{Main} is not specified, or is specified
14564 as an empty string list, or when the switch @option{-u} is used on the command
14565 line, then invoking @command{gnatmake} with no main on the command line will
14566 result in all immediate sources of the project file being checked, and
14567 potentially recompiled. Depending on the presence of the switch @option{-u},
14568 sources from other project files on which the immediate sources of the main
14569 project file depend are also checked and potentially recompiled. In other
14570 words, the @option{-u} switch is applied to all of the immediate sources of the
14573 When no main is specified on the command line and attribute @code{Main} exists
14574 and includes several mains, or when several mains are specified on the
14575 command line, the default ^switches^switches^ in package @code{Builder} will
14576 be used for all mains, even if there are specific ^switches^switches^
14577 specified for one or several mains.
14579 But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
14580 the specific ^switches^switches^ for each main, if they are specified.
14582 @node Library Project Files
14583 @subsubsection Library Project Files
14586 When @command{gnatmake} is invoked with a main project file that is a library
14587 project file, it is not allowed to specify one or more mains on the command
14591 When a library project file is specified, switches ^-b^/ACTION=BIND^ and
14592 ^-l^/ACTION=LINK^ have special meanings.
14595 @item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
14596 to @command{gnatmake} that @command{gnatbind} should be invoked for the
14599 @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
14600 to @command{gnatmake} that the binder generated file should be compiled
14601 (in the case of a stand-alone library) and that the library should be built.
14605 @node The GNAT Driver and Project Files
14606 @subsection The GNAT Driver and Project Files
14609 A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
14610 can benefit from project files:
14611 @command{^gnatbind^gnatbind^},
14612 @command{^gnatcheck^gnatcheck^}),
14613 @command{^gnatclean^gnatclean^}),
14614 @command{^gnatelim^gnatelim^},
14615 @command{^gnatfind^gnatfind^},
14616 @command{^gnatlink^gnatlink^},
14617 @command{^gnatls^gnatls^},
14618 @command{^gnatmetric^gnatmetric^},
14619 @command{^gnatpp^gnatpp^},
14620 @command{^gnatstub^gnatstub^},
14621 and @command{^gnatxref^gnatxref^}. However, none of these tools can be invoked
14622 directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
14623 They must be invoked through the @command{gnat} driver.
14625 The @command{gnat} driver is a wrapper that accepts a number of commands and
14626 calls the corresponding tool. It was designed initially for VMS platforms (to
14627 convert VMS qualifiers to Unix-style switches), but it is now available on all
14630 On non-VMS platforms, the @command{gnat} driver accepts the following commands
14631 (case insensitive):
14635 BIND to invoke @command{^gnatbind^gnatbind^}
14637 CHOP to invoke @command{^gnatchop^gnatchop^}
14639 CLEAN to invoke @command{^gnatclean^gnatclean^}
14641 COMP or COMPILE to invoke the compiler
14643 ELIM to invoke @command{^gnatelim^gnatelim^}
14645 FIND to invoke @command{^gnatfind^gnatfind^}
14647 KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
14649 LINK to invoke @command{^gnatlink^gnatlink^}
14651 LS or LIST to invoke @command{^gnatls^gnatls^}
14653 MAKE to invoke @command{^gnatmake^gnatmake^}
14655 NAME to invoke @command{^gnatname^gnatname^}
14657 PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
14659 PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
14661 METRIC to invoke @command{^gnatmetric^gnatmetric^}
14663 STUB to invoke @command{^gnatstub^gnatstub^}
14665 XREF to invoke @command{^gnatxref^gnatxref^}
14669 (note that the compiler is invoked using the command
14670 @command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
14673 On non-VMS platforms, between @command{gnat} and the command, two
14674 special switches may be used:
14678 @command{-v} to display the invocation of the tool.
14680 @command{-dn} to prevent the @command{gnat} driver from removing
14681 the temporary files it has created. These temporary files are
14682 configuration files and temporary file list files.
14686 The command may be followed by switches and arguments for the invoked
14690 gnat bind -C main.ali
14696 Switches may also be put in text files, one switch per line, and the text
14697 files may be specified with their path name preceded by '@@'.
14700 gnat bind @@args.txt main.ali
14704 In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
14705 METRIC, PP or PRETTY, STUB and XREF, the project file related switches
14706 (@option{^-P^/PROJECT_FILE^},
14707 @option{^-X^/EXTERNAL_REFERENCE^} and
14708 @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
14709 the switches of the invoking tool.
14712 When GNAT PP or GNAT PRETTY is used with a project file, but with no source
14713 specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
14714 the immediate sources of the specified project file.
14717 When GNAT METRIC is used with a project file, but with no source
14718 specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
14719 with all the immediate sources of the specified project file and with
14720 @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
14724 In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
14725 a project file, no source is specified on the command line and
14726 switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
14727 the underlying tool (^gnatpp^gnatpp^ or
14728 ^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
14729 not only for the immediate sources of the main project.
14731 (-U stands for Universal or Union of the project files of the project tree)
14735 For each of the following commands, there is optionally a corresponding
14736 package in the main project.
14740 package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
14743 package @code{Check} for command CHECK (invoking
14744 @code{^gnatcheck^gnatcheck^})
14747 package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
14750 package @code{Cross_Reference} for command XREF (invoking
14751 @code{^gnatxref^gnatxref^})
14754 package @code{Eliminate} for command ELIM (invoking
14755 @code{^gnatelim^gnatelim^})
14758 package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
14761 package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
14764 package @code{Gnatstub} for command STUB
14765 (invoking @code{^gnatstub^gnatstub^})
14768 package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
14771 package @code{Metrics} for command METRIC
14772 (invoking @code{^gnatmetric^gnatmetric^})
14775 package @code{Pretty_Printer} for command PP or PRETTY
14776 (invoking @code{^gnatpp^gnatpp^})
14781 Package @code{Gnatls} has a unique attribute @code{^Switches^Switches^},
14782 a simple variable with a string list value. It contains ^switches^switches^
14783 for the invocation of @code{^gnatls^gnatls^}.
14785 @smallexample @c projectfile
14789 for ^Switches^Switches^
14798 All other packages have two attribute @code{^Switches^Switches^} and
14799 @code{^Default_Switches^Default_Switches^}.
14802 @code{^Switches^Switches^} is an associative array attribute, indexed by the
14803 source file name, that has a string list value: the ^switches^switches^ to be
14804 used when the tool corresponding to the package is invoked for the specific
14808 @code{^Default_Switches^Default_Switches^} is an associative array attribute,
14809 indexed by the programming language that has a string list value.
14810 @code{^Default_Switches^Default_Switches^ ("Ada")} contains the
14811 ^switches^switches^ for the invocation of the tool corresponding
14812 to the package, except if a specific @code{^Switches^Switches^} attribute
14813 is specified for the source file.
14815 @smallexample @c projectfile
14819 for Source_Dirs use ("./**");
14822 for ^Switches^Switches^ use
14829 package Compiler is
14830 for ^Default_Switches^Default_Switches^ ("Ada")
14831 use ("^-gnatv^-gnatv^",
14832 "^-gnatwa^-gnatwa^");
14838 for ^Default_Switches^Default_Switches^ ("Ada")
14846 for ^Default_Switches^Default_Switches^ ("Ada")
14848 for ^Switches^Switches^ ("main.adb")
14857 for ^Default_Switches^Default_Switches^ ("Ada")
14864 package Cross_Reference is
14865 for ^Default_Switches^Default_Switches^ ("Ada")
14870 end Cross_Reference;
14876 With the above project file, commands such as
14879 ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
14880 ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
14881 ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
14882 ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
14883 ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
14887 will set up the environment properly and invoke the tool with the switches
14888 found in the package corresponding to the tool:
14889 @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
14890 except @code{^Switches^Switches^ ("main.adb")}
14891 for @code{^gnatlink^gnatlink^}.
14892 It is also possible to invoke some of the tools,
14893 @code{^gnatcheck^gnatcheck^}),
14894 @code{^gnatmetric^gnatmetric^}),
14895 and @code{^gnatpp^gnatpp^})
14896 on a set of project units thanks to the combination of the switches
14897 @option{-P}, @option{-U} and possibly the main unit when one is interested
14898 in its closure. For instance,
14902 will compute the metrics for all the immediate units of project
14905 gnat metric -Pproj -U
14907 will compute the metrics for all the units of the closure of projects
14908 rooted at @code{proj}.
14910 gnat metric -Pproj -U main_unit
14912 will compute the metrics for the closure of units rooted at
14913 @code{main_unit}. This last possibility relies implicitly
14914 on @command{gnatbind}'s option @option{-R}.
14916 @c **********************
14917 @node An Extended Example
14918 @section An Extended Example
14921 Suppose that we have two programs, @var{prog1} and @var{prog2},
14922 whose sources are in corresponding directories. We would like
14923 to build them with a single @command{gnatmake} command, and we want to place
14924 their object files into @file{build} subdirectories of the source directories.
14925 Furthermore, we want to have to have two separate subdirectories
14926 in @file{build} -- @file{release} and @file{debug} -- which will contain
14927 the object files compiled with different set of compilation flags.
14929 In other words, we have the following structure:
14946 Here are the project files that we must place in a directory @file{main}
14947 to maintain this structure:
14951 @item We create a @code{Common} project with a package @code{Compiler} that
14952 specifies the compilation ^switches^switches^:
14957 @b{project} Common @b{is}
14959 @b{for} Source_Dirs @b{use} (); -- No source files
14963 @b{type} Build_Type @b{is} ("release", "debug");
14964 Build : Build_Type := External ("BUILD", "debug");
14967 @b{package} Compiler @b{is}
14968 @b{case} Build @b{is}
14969 @b{when} "release" =>
14970 @b{for} ^Default_Switches^Default_Switches^ ("Ada")
14971 @b{use} ("^-O2^-O2^");
14972 @b{when} "debug" =>
14973 @b{for} ^Default_Switches^Default_Switches^ ("Ada")
14974 @b{use} ("^-g^-g^");
14982 @item We create separate projects for the two programs:
14989 @b{project} Prog1 @b{is}
14991 @b{for} Source_Dirs @b{use} ("prog1");
14992 @b{for} Object_Dir @b{use} "prog1/build/" & Common.Build;
14994 @b{package} Compiler @b{renames} Common.Compiler;
15005 @b{project} Prog2 @b{is}
15007 @b{for} Source_Dirs @b{use} ("prog2");
15008 @b{for} Object_Dir @b{use} "prog2/build/" & Common.Build;
15010 @b{package} Compiler @b{renames} Common.Compiler;
15016 @item We create a wrapping project @code{Main}:
15025 @b{project} Main @b{is}
15027 @b{package} Compiler @b{renames} Common.Compiler;
15033 @item Finally we need to create a dummy procedure that @code{with}s (either
15034 explicitly or implicitly) all the sources of our two programs.
15039 Now we can build the programs using the command
15042 gnatmake ^-P^/PROJECT_FILE=^main dummy
15046 for the Debug mode, or
15050 gnatmake -Pmain -XBUILD=release
15056 GNAT MAKE /PROJECT_FILE=main /EXTERNAL_REFERENCE=BUILD=release
15061 for the Release mode.
15063 @c ********************************
15064 @c * Project File Complete Syntax *
15065 @c ********************************
15067 @node Project File Complete Syntax
15068 @section Project File Complete Syntax
15072 context_clause project_declaration
15078 @b{with} path_name @{ , path_name @} ;
15083 project_declaration ::=
15084 simple_project_declaration | project_extension
15086 simple_project_declaration ::=
15087 @b{project} <project_>simple_name @b{is}
15088 @{declarative_item@}
15089 @b{end} <project_>simple_name;
15091 project_extension ::=
15092 @b{project} <project_>simple_name @b{extends} path_name @b{is}
15093 @{declarative_item@}
15094 @b{end} <project_>simple_name;
15096 declarative_item ::=
15097 package_declaration |
15098 typed_string_declaration |
15099 other_declarative_item
15101 package_declaration ::=
15102 package_spec | package_renaming
15105 @b{package} package_identifier @b{is}
15106 @{simple_declarative_item@}
15107 @b{end} package_identifier ;
15109 package_identifier ::=
15110 @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
15111 @code{Linker} | @code{Finder} | @code{Cross_Reference} |
15112 @code{^gnatls^gnatls^} | @code{IDE} | @code{Pretty_Printer}
15114 package_renaming ::==
15115 @b{package} package_identifier @b{renames}
15116 <project_>simple_name.package_identifier ;
15118 typed_string_declaration ::=
15119 @b{type} <typed_string_>_simple_name @b{is}
15120 ( string_literal @{, string_literal@} );
15122 other_declarative_item ::=
15123 attribute_declaration |
15124 typed_variable_declaration |
15125 variable_declaration |
15128 attribute_declaration ::=
15129 full_associative_array_declaration |
15130 @b{for} attribute_designator @b{use} expression ;
15132 full_associative_array_declaration ::=
15133 @b{for} <associative_array_attribute_>simple_name @b{use}
15134 <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ;
15136 attribute_designator ::=
15137 <simple_attribute_>simple_name |
15138 <associative_array_attribute_>simple_name ( string_literal )
15140 typed_variable_declaration ::=
15141 <typed_variable_>simple_name : <typed_string_>name := string_expression ;
15143 variable_declaration ::=
15144 <variable_>simple_name := expression;
15154 attribute_reference
15160 ( <string_>expression @{ , <string_>expression @} )
15163 @b{external} ( string_literal [, string_literal] )
15165 attribute_reference ::=
15166 attribute_prefix ' <simple_attribute_>simple_name [ ( literal_string ) ]
15168 attribute_prefix ::=
15170 <project_>simple_name | package_identifier |
15171 <project_>simple_name . package_identifier
15173 case_construction ::=
15174 @b{case} <typed_variable_>name @b{is}
15179 @b{when} discrete_choice_list =>
15180 @{case_construction | attribute_declaration@}
15182 discrete_choice_list ::=
15183 string_literal @{| string_literal@} |
15187 simple_name @{. simple_name@}
15190 identifier (same as Ada)
15194 @node The Cross-Referencing Tools gnatxref and gnatfind
15195 @chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind}
15200 The compiler generates cross-referencing information (unless
15201 you set the @samp{-gnatx} switch), which are saved in the @file{.ali} files.
15202 This information indicates where in the source each entity is declared and
15203 referenced. Note that entities in package Standard are not included, but
15204 entities in all other predefined units are included in the output.
15206 Before using any of these two tools, you need to compile successfully your
15207 application, so that GNAT gets a chance to generate the cross-referencing
15210 The two tools @code{gnatxref} and @code{gnatfind} take advantage of this
15211 information to provide the user with the capability to easily locate the
15212 declaration and references to an entity. These tools are quite similar,
15213 the difference being that @code{gnatfind} is intended for locating
15214 definitions and/or references to a specified entity or entities, whereas
15215 @code{gnatxref} is oriented to generating a full report of all
15218 To use these tools, you must not compile your application using the
15219 @option{-gnatx} switch on the @command{gnatmake} command line
15220 (@pxref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing
15221 information will not be generated.
15223 Note: to invoke @code{gnatxref} or @code{gnatfind} with a project file,
15224 use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}).
15227 * gnatxref Switches::
15228 * gnatfind Switches::
15229 * Project Files for gnatxref and gnatfind::
15230 * Regular Expressions in gnatfind and gnatxref::
15231 * Examples of gnatxref Usage::
15232 * Examples of gnatfind Usage::
15235 @node gnatxref Switches
15236 @section @code{gnatxref} Switches
15239 The command invocation for @code{gnatxref} is:
15241 $ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
15250 identifies the source files for which a report is to be generated. The
15251 ``with''ed units will be processed too. You must provide at least one file.
15253 These file names are considered to be regular expressions, so for instance
15254 specifying @file{source*.adb} is the same as giving every file in the current
15255 directory whose name starts with @file{source} and whose extension is
15258 You shouldn't specify any directory name, just base names. @command{gnatxref}
15259 and @command{gnatfind} will be able to locate these files by themselves using
15260 the source path. If you specify directories, no result is produced.
15265 The switches can be:
15269 @cindex @option{--version} @command{gnatxref}
15270 Display Copyright and version, then exit disregarding all other options.
15273 @cindex @option{--help} @command{gnatxref}
15274 If @option{--version} was not used, display usage, then exit disregarding
15277 @item ^-a^/ALL_FILES^
15278 @cindex @option{^-a^/ALL_FILES^} (@command{gnatxref})
15279 If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
15280 the read-only files found in the library search path. Otherwise, these files
15281 will be ignored. This option can be used to protect Gnat sources or your own
15282 libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
15283 much faster, and their output much smaller. Read-only here refers to access
15284 or permissions status in the file system for the current user.
15287 @cindex @option{-aIDIR} (@command{gnatxref})
15288 When looking for source files also look in directory DIR. The order in which
15289 source file search is undertaken is the same as for @command{gnatmake}.
15292 @cindex @option{-aODIR} (@command{gnatxref})
15293 When searching for library and object files, look in directory
15294 DIR. The order in which library files are searched is the same as for
15295 @command{gnatmake}.
15298 @cindex @option{-nostdinc} (@command{gnatxref})
15299 Do not look for sources in the system default directory.
15302 @cindex @option{-nostdlib} (@command{gnatxref})
15303 Do not look for library files in the system default directory.
15305 @item --RTS=@var{rts-path}
15306 @cindex @option{--RTS} (@command{gnatxref})
15307 Specifies the default location of the runtime library. Same meaning as the
15308 equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
15310 @item ^-d^/DERIVED_TYPES^
15311 @cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref})
15312 If this switch is set @code{gnatxref} will output the parent type
15313 reference for each matching derived types.
15315 @item ^-f^/FULL_PATHNAME^
15316 @cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatxref})
15317 If this switch is set, the output file names will be preceded by their
15318 directory (if the file was found in the search path). If this switch is
15319 not set, the directory will not be printed.
15321 @item ^-g^/IGNORE_LOCALS^
15322 @cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatxref})
15323 If this switch is set, information is output only for library-level
15324 entities, ignoring local entities. The use of this switch may accelerate
15325 @code{gnatfind} and @code{gnatxref}.
15328 @cindex @option{-IDIR} (@command{gnatxref})
15329 Equivalent to @samp{-aODIR -aIDIR}.
15332 @cindex @option{-pFILE} (@command{gnatxref})
15333 Specify a project file to use @xref{Project Files}.
15334 If you need to use the @file{.gpr}
15335 project files, you should use gnatxref through the GNAT driver
15336 (@command{gnat xref -Pproject}).
15338 By default, @code{gnatxref} and @code{gnatfind} will try to locate a
15339 project file in the current directory.
15341 If a project file is either specified or found by the tools, then the content
15342 of the source directory and object directory lines are added as if they
15343 had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^}
15344 and @samp{^-aO^OBJECT_SEARCH^}.
15346 Output only unused symbols. This may be really useful if you give your
15347 main compilation unit on the command line, as @code{gnatxref} will then
15348 display every unused entity and 'with'ed package.
15352 Instead of producing the default output, @code{gnatxref} will generate a
15353 @file{tags} file that can be used by vi. For examples how to use this
15354 feature, see @ref{Examples of gnatxref Usage}. The tags file is output
15355 to the standard output, thus you will have to redirect it to a file.
15361 All these switches may be in any order on the command line, and may even
15362 appear after the file names. They need not be separated by spaces, thus
15363 you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of
15364 @samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}.
15366 @node gnatfind Switches
15367 @section @code{gnatfind} Switches
15370 The command line for @code{gnatfind} is:
15373 $ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
15374 @r{[}@var{file1} @var{file2} @dots{}]
15382 An entity will be output only if it matches the regular expression found
15383 in @var{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}.
15385 Omitting the pattern is equivalent to specifying @samp{*}, which
15386 will match any entity. Note that if you do not provide a pattern, you
15387 have to provide both a sourcefile and a line.
15389 Entity names are given in Latin-1, with uppercase/lowercase equivalence
15390 for matching purposes. At the current time there is no support for
15391 8-bit codes other than Latin-1, or for wide characters in identifiers.
15394 @code{gnatfind} will look for references, bodies or declarations
15395 of symbols referenced in @file{@var{sourcefile}}, at line @var{line}
15396 and column @var{column}. See @ref{Examples of gnatfind Usage}
15397 for syntax examples.
15400 is a decimal integer identifying the line number containing
15401 the reference to the entity (or entities) to be located.
15404 is a decimal integer identifying the exact location on the
15405 line of the first character of the identifier for the
15406 entity reference. Columns are numbered from 1.
15408 @item file1 file2 @dots{}
15409 The search will be restricted to these source files. If none are given, then
15410 the search will be done for every library file in the search path.
15411 These file must appear only after the pattern or sourcefile.
15413 These file names are considered to be regular expressions, so for instance
15414 specifying @file{source*.adb} is the same as giving every file in the current
15415 directory whose name starts with @file{source} and whose extension is
15418 The location of the spec of the entity will always be displayed, even if it
15419 isn't in one of @file{@var{file1}}, @file{@var{file2}},@enddots{} The
15420 occurrences of the entity in the separate units of the ones given on the
15421 command line will also be displayed.
15423 Note that if you specify at least one file in this part, @code{gnatfind} may
15424 sometimes not be able to find the body of the subprograms.
15429 At least one of 'sourcefile' or 'pattern' has to be present on
15432 The following switches are available:
15436 @cindex @option{--version} @command{gnatfind}
15437 Display Copyright and version, then exit disregarding all other options.
15440 @cindex @option{--help} @command{gnatfind}
15441 If @option{--version} was not used, display usage, then exit disregarding
15444 @item ^-a^/ALL_FILES^
15445 @cindex @option{^-a^/ALL_FILES^} (@command{gnatfind})
15446 If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
15447 the read-only files found in the library search path. Otherwise, these files
15448 will be ignored. This option can be used to protect Gnat sources or your own
15449 libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
15450 much faster, and their output much smaller. Read-only here refers to access
15451 or permission status in the file system for the current user.
15454 @cindex @option{-aIDIR} (@command{gnatfind})
15455 When looking for source files also look in directory DIR. The order in which
15456 source file search is undertaken is the same as for @command{gnatmake}.
15459 @cindex @option{-aODIR} (@command{gnatfind})
15460 When searching for library and object files, look in directory
15461 DIR. The order in which library files are searched is the same as for
15462 @command{gnatmake}.
15465 @cindex @option{-nostdinc} (@command{gnatfind})
15466 Do not look for sources in the system default directory.
15469 @cindex @option{-nostdlib} (@command{gnatfind})
15470 Do not look for library files in the system default directory.
15472 @item --RTS=@var{rts-path}
15473 @cindex @option{--RTS} (@command{gnatfind})
15474 Specifies the default location of the runtime library. Same meaning as the
15475 equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
15477 @item ^-d^/DERIVED_TYPE_INFORMATION^
15478 @cindex @option{^-d^/DERIVED_TYPE_INFORMATION^} (@code{gnatfind})
15479 If this switch is set, then @code{gnatfind} will output the parent type
15480 reference for each matching derived types.
15482 @item ^-e^/EXPRESSIONS^
15483 @cindex @option{^-e^/EXPRESSIONS^} (@command{gnatfind})
15484 By default, @code{gnatfind} accept the simple regular expression set for
15485 @samp{pattern}. If this switch is set, then the pattern will be
15486 considered as full Unix-style regular expression.
15488 @item ^-f^/FULL_PATHNAME^
15489 @cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatfind})
15490 If this switch is set, the output file names will be preceded by their
15491 directory (if the file was found in the search path). If this switch is
15492 not set, the directory will not be printed.
15494 @item ^-g^/IGNORE_LOCALS^
15495 @cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatfind})
15496 If this switch is set, information is output only for library-level
15497 entities, ignoring local entities. The use of this switch may accelerate
15498 @code{gnatfind} and @code{gnatxref}.
15501 @cindex @option{-IDIR} (@command{gnatfind})
15502 Equivalent to @samp{-aODIR -aIDIR}.
15505 @cindex @option{-pFILE} (@command{gnatfind})
15506 Specify a project file (@pxref{Project Files}) to use.
15507 By default, @code{gnatxref} and @code{gnatfind} will try to locate a
15508 project file in the current directory.
15510 If a project file is either specified or found by the tools, then the content
15511 of the source directory and object directory lines are added as if they
15512 had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} and
15513 @samp{^-aO^/OBJECT_SEARCH^}.
15515 @item ^-r^/REFERENCES^
15516 @cindex @option{^-r^/REFERENCES^} (@command{gnatfind})
15517 By default, @code{gnatfind} will output only the information about the
15518 declaration, body or type completion of the entities. If this switch is
15519 set, the @code{gnatfind} will locate every reference to the entities in
15520 the files specified on the command line (or in every file in the search
15521 path if no file is given on the command line).
15523 @item ^-s^/PRINT_LINES^
15524 @cindex @option{^-s^/PRINT_LINES^} (@command{gnatfind})
15525 If this switch is set, then @code{gnatfind} will output the content
15526 of the Ada source file lines were the entity was found.
15528 @item ^-t^/TYPE_HIERARCHY^
15529 @cindex @option{^-t^/TYPE_HIERARCHY^} (@command{gnatfind})
15530 If this switch is set, then @code{gnatfind} will output the type hierarchy for
15531 the specified type. It act like -d option but recursively from parent
15532 type to parent type. When this switch is set it is not possible to
15533 specify more than one file.
15538 All these switches may be in any order on the command line, and may even
15539 appear after the file names. They need not be separated by spaces, thus
15540 you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of
15541 @samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}.
15543 As stated previously, gnatfind will search in every directory in the
15544 search path. You can force it to look only in the current directory if
15545 you specify @code{*} at the end of the command line.
15547 @node Project Files for gnatxref and gnatfind
15548 @section Project Files for @command{gnatxref} and @command{gnatfind}
15551 Project files allow a programmer to specify how to compile its
15552 application, where to find sources, etc. These files are used
15554 primarily by GPS, but they can also be used
15557 @code{gnatxref} and @code{gnatfind}.
15559 A project file name must end with @file{.gpr}. If a single one is
15560 present in the current directory, then @code{gnatxref} and @code{gnatfind} will
15561 extract the information from it. If multiple project files are found, none of
15562 them is read, and you have to use the @samp{-p} switch to specify the one
15565 The following lines can be included, even though most of them have default
15566 values which can be used in most cases.
15567 The lines can be entered in any order in the file.
15568 Except for @file{src_dir} and @file{obj_dir}, you can only have one instance of
15569 each line. If you have multiple instances, only the last one is taken into
15574 [default: @code{"^./^[]^"}]
15575 specifies a directory where to look for source files. Multiple @code{src_dir}
15576 lines can be specified and they will be searched in the order they
15580 [default: @code{"^./^[]^"}]
15581 specifies a directory where to look for object and library files. Multiple
15582 @code{obj_dir} lines can be specified, and they will be searched in the order
15585 @item comp_opt=SWITCHES
15586 [default: @code{""}]
15587 creates a variable which can be referred to subsequently by using
15588 the @code{$@{comp_opt@}} notation. This is intended to store the default
15589 switches given to @command{gnatmake} and @command{gcc}.
15591 @item bind_opt=SWITCHES
15592 [default: @code{""}]
15593 creates a variable which can be referred to subsequently by using
15594 the @samp{$@{bind_opt@}} notation. This is intended to store the default
15595 switches given to @command{gnatbind}.
15597 @item link_opt=SWITCHES
15598 [default: @code{""}]
15599 creates a variable which can be referred to subsequently by using
15600 the @samp{$@{link_opt@}} notation. This is intended to store the default
15601 switches given to @command{gnatlink}.
15603 @item main=EXECUTABLE
15604 [default: @code{""}]
15605 specifies the name of the executable for the application. This variable can
15606 be referred to in the following lines by using the @samp{$@{main@}} notation.
15609 @item comp_cmd=COMMAND
15610 [default: @code{"GNAT COMPILE /SEARCH=$@{src_dir@} /DEBUG /TRY_SEMANTICS"}]
15613 @item comp_cmd=COMMAND
15614 [default: @code{"gcc -c -I$@{src_dir@} -g -gnatq"}]
15616 specifies the command used to compile a single file in the application.
15619 @item make_cmd=COMMAND
15620 [default: @code{"GNAT MAKE $@{main@}
15621 /SOURCE_SEARCH=$@{src_dir@} /OBJECT_SEARCH=$@{obj_dir@}
15622 /DEBUG /TRY_SEMANTICS /COMPILER_QUALIFIERS $@{comp_opt@}
15623 /BINDER_QUALIFIERS $@{bind_opt@} /LINKER_QUALIFIERS $@{link_opt@}"}]
15626 @item make_cmd=COMMAND
15627 [default: @code{"gnatmake $@{main@} -aI$@{src_dir@}
15628 -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@}
15629 -bargs $@{bind_opt@} -largs $@{link_opt@}"}]
15631 specifies the command used to recompile the whole application.
15633 @item run_cmd=COMMAND
15634 [default: @code{"$@{main@}"}]
15635 specifies the command used to run the application.
15637 @item debug_cmd=COMMAND
15638 [default: @code{"gdb $@{main@}"}]
15639 specifies the command used to debug the application
15644 @command{gnatxref} and @command{gnatfind} only take into account the
15645 @code{src_dir} and @code{obj_dir} lines, and ignore the others.
15647 @node Regular Expressions in gnatfind and gnatxref
15648 @section Regular Expressions in @code{gnatfind} and @code{gnatxref}
15651 As specified in the section about @command{gnatfind}, the pattern can be a
15652 regular expression. Actually, there are to set of regular expressions
15653 which are recognized by the program:
15656 @item globbing patterns
15657 These are the most usual regular expression. They are the same that you
15658 generally used in a Unix shell command line, or in a DOS session.
15660 Here is a more formal grammar:
15667 term ::= elmt -- matches elmt
15668 term ::= elmt elmt -- concatenation (elmt then elmt)
15669 term ::= * -- any string of 0 or more characters
15670 term ::= ? -- matches any character
15671 term ::= [char @{char@}] -- matches any character listed
15672 term ::= [char - char] -- matches any character in range
15676 @item full regular expression
15677 The second set of regular expressions is much more powerful. This is the
15678 type of regular expressions recognized by utilities such a @file{grep}.
15680 The following is the form of a regular expression, expressed in Ada
15681 reference manual style BNF is as follows
15688 regexp ::= term @{| term@} -- alternation (term or term @dots{})
15690 term ::= item @{item@} -- concatenation (item then item)
15692 item ::= elmt -- match elmt
15693 item ::= elmt * -- zero or more elmt's
15694 item ::= elmt + -- one or more elmt's
15695 item ::= elmt ? -- matches elmt or nothing
15698 elmt ::= nschar -- matches given character
15699 elmt ::= [nschar @{nschar@}] -- matches any character listed
15700 elmt ::= [^^^ nschar @{nschar@}] -- matches any character not listed
15701 elmt ::= [char - char] -- matches chars in given range
15702 elmt ::= \ char -- matches given character
15703 elmt ::= . -- matches any single character
15704 elmt ::= ( regexp ) -- parens used for grouping
15706 char ::= any character, including special characters
15707 nschar ::= any character except ()[].*+?^^^
15711 Following are a few examples:
15715 will match any of the two strings @samp{abcde} and @samp{fghi},
15718 will match any string like @samp{abd}, @samp{abcd}, @samp{abccd},
15719 @samp{abcccd}, and so on,
15722 will match any string which has only lowercase characters in it (and at
15723 least one character.
15728 @node Examples of gnatxref Usage
15729 @section Examples of @code{gnatxref} Usage
15731 @subsection General Usage
15734 For the following examples, we will consider the following units:
15736 @smallexample @c ada
15742 3: procedure Foo (B : in Integer);
15749 1: package body Main is
15750 2: procedure Foo (B : in Integer) is
15761 2: procedure Print (B : Integer);
15770 The first thing to do is to recompile your application (for instance, in
15771 that case just by doing a @samp{gnatmake main}, so that GNAT generates
15772 the cross-referencing information.
15773 You can then issue any of the following commands:
15775 @item gnatxref main.adb
15776 @code{gnatxref} generates cross-reference information for main.adb
15777 and every unit 'with'ed by main.adb.
15779 The output would be:
15787 Decl: main.ads 3:20
15788 Body: main.adb 2:20
15789 Ref: main.adb 4:13 5:13 6:19
15792 Ref: main.adb 6:8 7:8
15802 Decl: main.ads 3:15
15803 Body: main.adb 2:15
15806 Body: main.adb 1:14
15809 Ref: main.adb 6:12 7:12
15813 that is the entity @code{Main} is declared in main.ads, line 2, column 9,
15814 its body is in main.adb, line 1, column 14 and is not referenced any where.
15816 The entity @code{Print} is declared in bar.ads, line 2, column 15 and it
15817 it referenced in main.adb, line 6 column 12 and line 7 column 12.
15819 @item gnatxref package1.adb package2.ads
15820 @code{gnatxref} will generates cross-reference information for
15821 package1.adb, package2.ads and any other package 'with'ed by any
15827 @subsection Using gnatxref with vi
15829 @code{gnatxref} can generate a tags file output, which can be used
15830 directly from @command{vi}. Note that the standard version of @command{vi}
15831 will not work properly with overloaded symbols. Consider using another
15832 free implementation of @command{vi}, such as @command{vim}.
15835 $ gnatxref -v gnatfind.adb > tags
15839 will generate the tags file for @code{gnatfind} itself (if the sources
15840 are in the search path!).
15842 From @command{vi}, you can then use the command @samp{:tag @var{entity}}
15843 (replacing @var{entity} by whatever you are looking for), and vi will
15844 display a new file with the corresponding declaration of entity.
15847 @node Examples of gnatfind Usage
15848 @section Examples of @code{gnatfind} Usage
15852 @item gnatfind ^-f^/FULL_PATHNAME^ xyz:main.adb
15853 Find declarations for all entities xyz referenced at least once in
15854 main.adb. The references are search in every library file in the search
15857 The directories will be printed as well (as the @samp{^-f^/FULL_PATHNAME^}
15860 The output will look like:
15862 ^directory/^[directory]^main.ads:106:14: xyz <= declaration
15863 ^directory/^[directory]^main.adb:24:10: xyz <= body
15864 ^directory/^[directory]^foo.ads:45:23: xyz <= declaration
15868 that is to say, one of the entities xyz found in main.adb is declared at
15869 line 12 of main.ads (and its body is in main.adb), and another one is
15870 declared at line 45 of foo.ads
15872 @item gnatfind ^-fs^/FULL_PATHNAME/SOURCE_LINE^ xyz:main.adb
15873 This is the same command as the previous one, instead @code{gnatfind} will
15874 display the content of the Ada source file lines.
15876 The output will look like:
15879 ^directory/^[directory]^main.ads:106:14: xyz <= declaration
15881 ^directory/^[directory]^main.adb:24:10: xyz <= body
15883 ^directory/^[directory]^foo.ads:45:23: xyz <= declaration
15888 This can make it easier to find exactly the location your are looking
15891 @item gnatfind ^-r^/REFERENCES^ "*x*":main.ads:123 foo.adb
15892 Find references to all entities containing an x that are
15893 referenced on line 123 of main.ads.
15894 The references will be searched only in main.ads and foo.adb.
15896 @item gnatfind main.ads:123
15897 Find declarations and bodies for all entities that are referenced on
15898 line 123 of main.ads.
15900 This is the same as @code{gnatfind "*":main.adb:123}.
15902 @item gnatfind ^mydir/^[mydir]^main.adb:123:45
15903 Find the declaration for the entity referenced at column 45 in
15904 line 123 of file main.adb in directory mydir. Note that it
15905 is usual to omit the identifier name when the column is given,
15906 since the column position identifies a unique reference.
15908 The column has to be the beginning of the identifier, and should not
15909 point to any character in the middle of the identifier.
15913 @c *********************************
15914 @node The GNAT Pretty-Printer gnatpp
15915 @chapter The GNAT Pretty-Printer @command{gnatpp}
15917 @cindex Pretty-Printer
15920 ^The @command{gnatpp} tool^GNAT PRETTY^ is an ASIS-based utility
15921 for source reformatting / pretty-printing.
15922 It takes an Ada source file as input and generates a reformatted
15924 You can specify various style directives via switches; e.g.,
15925 identifier case conventions, rules of indentation, and comment layout.
15927 To produce a reformatted file, @command{gnatpp} generates and uses the ASIS
15928 tree for the input source and thus requires the input to be syntactically and
15929 semantically legal.
15930 If this condition is not met, @command{gnatpp} will terminate with an
15931 error message; no output file will be generated.
15933 If the source files presented to @command{gnatpp} contain
15934 preprocessing directives, then the output file will
15935 correspond to the generated source after all
15936 preprocessing is carried out. There is no way
15937 using @command{gnatpp} to obtain pretty printed files that
15938 include the preprocessing directives.
15940 If the compilation unit
15941 contained in the input source depends semantically upon units located
15942 outside the current directory, you have to provide the source search path
15943 when invoking @command{gnatpp}, if these units are contained in files with
15944 names that do not follow the GNAT file naming rules, you have to provide
15945 the configuration file describing the corresponding naming scheme;
15946 see the description of the @command{gnatpp}
15947 switches below. Another possibility is to use a project file and to
15948 call @command{gnatpp} through the @command{gnat} driver
15950 The @command{gnatpp} command has the form
15953 $ gnatpp @ovar{switches} @var{filename}
15960 @var{switches} is an optional sequence of switches defining such properties as
15961 the formatting rules, the source search path, and the destination for the
15965 @var{filename} is the name (including the extension) of the source file to
15966 reformat; ``wildcards'' or several file names on the same gnatpp command are
15967 allowed. The file name may contain path information; it does not have to
15968 follow the GNAT file naming rules
15972 * Switches for gnatpp::
15973 * Formatting Rules::
15976 @node Switches for gnatpp
15977 @section Switches for @command{gnatpp}
15980 The following subsections describe the various switches accepted by
15981 @command{gnatpp}, organized by category.
15984 You specify a switch by supplying a name and generally also a value.
15985 In many cases the values for a switch with a given name are incompatible with
15987 (for example the switch that controls the casing of a reserved word may have
15988 exactly one value: upper case, lower case, or
15989 mixed case) and thus exactly one such switch can be in effect for an
15990 invocation of @command{gnatpp}.
15991 If more than one is supplied, the last one is used.
15992 However, some values for the same switch are mutually compatible.
15993 You may supply several such switches to @command{gnatpp}, but then
15994 each must be specified in full, with both the name and the value.
15995 Abbreviated forms (the name appearing once, followed by each value) are
15997 For example, to set
15998 the alignment of the assignment delimiter both in declarations and in
15999 assignment statements, you must write @option{-A2A3}
16000 (or @option{-A2 -A3}), but not @option{-A23}.
16004 In many cases the set of options for a given qualifier are incompatible with
16005 each other (for example the qualifier that controls the casing of a reserved
16006 word may have exactly one option, which specifies either upper case, lower
16007 case, or mixed case), and thus exactly one such option can be in effect for
16008 an invocation of @command{gnatpp}.
16009 If more than one is supplied, the last one is used.
16010 However, some qualifiers have options that are mutually compatible,
16011 and then you may then supply several such options when invoking
16015 In most cases, it is obvious whether or not the
16016 ^values for a switch with a given name^options for a given qualifier^
16017 are compatible with each other.
16018 When the semantics might not be evident, the summaries below explicitly
16019 indicate the effect.
16022 * Alignment Control::
16024 * Construct Layout Control::
16025 * General Text Layout Control::
16026 * Other Formatting Options::
16027 * Setting the Source Search Path::
16028 * Output File Control::
16029 * Other gnatpp Switches::
16032 @node Alignment Control
16033 @subsection Alignment Control
16034 @cindex Alignment control in @command{gnatpp}
16037 Programs can be easier to read if certain constructs are vertically aligned.
16038 By default all alignments are set ON.
16039 Through the @option{^-A0^/ALIGN=OFF^} switch you may reset the default to
16040 OFF, and then use one or more of the other
16041 ^@option{-A@var{n}} switches^@option{/ALIGN} options^
16042 to activate alignment for specific constructs.
16045 @cindex @option{^-A@var{n}^/ALIGN^} (@command{gnatpp})
16049 Set all alignments to ON
16052 @item ^-A0^/ALIGN=OFF^
16053 Set all alignments to OFF
16055 @item ^-A1^/ALIGN=COLONS^
16056 Align @code{:} in declarations
16058 @item ^-A2^/ALIGN=DECLARATIONS^
16059 Align @code{:=} in initializations in declarations
16061 @item ^-A3^/ALIGN=STATEMENTS^
16062 Align @code{:=} in assignment statements
16064 @item ^-A4^/ALIGN=ARROWS^
16065 Align @code{=>} in associations
16067 @item ^-A5^/ALIGN=COMPONENT_CLAUSES^
16068 Align @code{at} keywords in the component clauses in record
16069 representation clauses
16073 The @option{^-A^/ALIGN^} switches are mutually compatible; any combination
16076 @node Casing Control
16077 @subsection Casing Control
16078 @cindex Casing control in @command{gnatpp}
16081 @command{gnatpp} allows you to specify the casing for reserved words,
16082 pragma names, attribute designators and identifiers.
16083 For identifiers you may define a
16084 general rule for name casing but also override this rule
16085 via a set of dictionary files.
16087 Three types of casing are supported: lower case, upper case, and mixed case.
16088 Lower and upper case are self-explanatory (but since some letters in
16089 Latin1 and other GNAT-supported character sets
16090 exist only in lower-case form, an upper case conversion will have no
16092 ``Mixed case'' means that the first letter, and also each letter immediately
16093 following an underscore, are converted to their uppercase forms;
16094 all the other letters are converted to their lowercase forms.
16097 @cindex @option{^-a@var{x}^/ATTRIBUTE^} (@command{gnatpp})
16098 @item ^-aL^/ATTRIBUTE_CASING=LOWER_CASE^
16099 Attribute designators are lower case
16101 @item ^-aU^/ATTRIBUTE_CASING=UPPER_CASE^
16102 Attribute designators are upper case
16104 @item ^-aM^/ATTRIBUTE_CASING=MIXED_CASE^
16105 Attribute designators are mixed case (this is the default)
16107 @cindex @option{^-k@var{x}^/KEYWORD_CASING^} (@command{gnatpp})
16108 @item ^-kL^/KEYWORD_CASING=LOWER_CASE^
16109 Keywords (technically, these are known in Ada as @emph{reserved words}) are
16110 lower case (this is the default)
16112 @item ^-kU^/KEYWORD_CASING=UPPER_CASE^
16113 Keywords are upper case
16115 @cindex @option{^-n@var{x}^/NAME_CASING^} (@command{gnatpp})
16116 @item ^-nD^/NAME_CASING=AS_DECLARED^
16117 Name casing for defining occurrences are as they appear in the source file
16118 (this is the default)
16120 @item ^-nU^/NAME_CASING=UPPER_CASE^
16121 Names are in upper case
16123 @item ^-nL^/NAME_CASING=LOWER_CASE^
16124 Names are in lower case
16126 @item ^-nM^/NAME_CASING=MIXED_CASE^
16127 Names are in mixed case
16129 @cindex @option{^-p@var{x}^/PRAGMA_CASING^} (@command{gnatpp})
16130 @item ^-pL^/PRAGMA_CASING=LOWER_CASE^
16131 Pragma names are lower case
16133 @item ^-pU^/PRAGMA_CASING=UPPER_CASE^
16134 Pragma names are upper case
16136 @item ^-pM^/PRAGMA_CASING=MIXED_CASE^
16137 Pragma names are mixed case (this is the default)
16139 @item ^-D@var{file}^/DICTIONARY=@var{file}^
16140 @cindex @option{^-D^/DICTIONARY^} (@command{gnatpp})
16141 Use @var{file} as a @emph{dictionary file} that defines
16142 the casing for a set of specified names,
16143 thereby overriding the effect on these names by
16144 any explicit or implicit
16145 ^-n^/NAME_CASING^ switch.
16146 To supply more than one dictionary file,
16147 use ^several @option{-D} switches^a list of files as options^.
16150 @option{gnatpp} implicitly uses a @emph{default dictionary file}
16151 to define the casing for the Ada predefined names and
16152 the names declared in the GNAT libraries.
16154 @item ^-D-^/SPECIFIC_CASING^
16155 @cindex @option{^-D-^/SPECIFIC_CASING^} (@command{gnatpp})
16156 Do not use the default dictionary file;
16157 instead, use the casing
16158 defined by a @option{^-n^/NAME_CASING^} switch and any explicit
16163 The structure of a dictionary file, and details on the conventions
16164 used in the default dictionary file, are defined in @ref{Name Casing}.
16166 The @option{^-D-^/SPECIFIC_CASING^} and
16167 @option{^-D@var{file}^/DICTIONARY=@var{file}^} switches are mutually
16170 @node Construct Layout Control
16171 @subsection Construct Layout Control
16172 @cindex Layout control in @command{gnatpp}
16175 This group of @command{gnatpp} switches controls the layout of comments and
16176 complex syntactic constructs. See @ref{Formatting Comments} for details
16180 @cindex @option{^-c@var{n}^/COMMENTS_LAYOUT^} (@command{gnatpp})
16181 @item ^-c0^/COMMENTS_LAYOUT=UNTOUCHED^
16182 All the comments remain unchanged
16184 @item ^-c1^/COMMENTS_LAYOUT=DEFAULT^
16185 GNAT-style comment line indentation (this is the default).
16187 @item ^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^
16188 Reference-manual comment line indentation.
16190 @item ^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^
16191 GNAT-style comment beginning
16193 @item ^-c4^/COMMENTS_LAYOUT=REFORMAT^
16194 Reformat comment blocks
16196 @item ^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^
16197 Keep unchanged special form comments
16199 Reformat comment blocks
16201 @cindex @option{^-l@var{n}^/CONSTRUCT_LAYOUT^} (@command{gnatpp})
16202 @item ^-l1^/CONSTRUCT_LAYOUT=GNAT^
16203 GNAT-style layout (this is the default)
16205 @item ^-l2^/CONSTRUCT_LAYOUT=COMPACT^
16208 @item ^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^
16211 @cindex @option{^-N^/NOTABS^} (@command{gnatpp})
16213 All the VT characters are removed from the comment text. All the HT characters
16214 are expanded with the sequences of space characters to get to the next tab
16217 @cindex @option{^--no-separate-is^/NO_SEPARATE_IS^} (@command{gnatpp})
16218 @item ^--no-separate-is^/NO_SEPARATE_IS^
16219 Do not place the keyword @code{is} on a separate line in a subprogram body in
16220 case if the spec occupies more then one line.
16222 @cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
16223 @item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
16224 Place the keyword @code{loop} in FOR and WHILE loop statements and the
16225 keyword @code{then} in IF statements on a separate line.
16227 @cindex @option{^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^} (@command{gnatpp})
16228 @item ^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^
16229 Do not place the keyword @code{loop} in FOR and WHILE loop statements and the
16230 keyword @code{then} in IF statements on a separate line. This option is
16231 incompatible with @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} option.
16233 @cindex @option{^--use-on-new-line^/USE_ON_NEW_LINE^} (@command{gnatpp})
16234 @item ^--use-on-new-line^/USE_ON_NEW_LINE^
16235 Start each USE clause in a context clause from a separate line.
16237 @cindex @option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^} (@command{gnatpp})
16238 @item ^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^
16239 Use a separate line for a loop or block statement name, but do not use an extra
16240 indentation level for the statement itself.
16246 The @option{-c1} and @option{-c2} switches are incompatible.
16247 The @option{-c3} and @option{-c4} switches are compatible with each other and
16248 also with @option{-c1} and @option{-c2}. The @option{-c0} switch disables all
16249 the other comment formatting switches.
16251 The @option{-l1}, @option{-l2}, and @option{-l3} switches are incompatible.
16256 For the @option{/COMMENTS_LAYOUT} qualifier:
16259 The @option{DEFAULT} and @option{STANDARD_INDENT} options are incompatible.
16261 The @option{GNAT_BEGINNING} and @option{REFORMAT} options are compatible with
16262 each other and also with @option{DEFAULT} and @option{STANDARD_INDENT}.
16266 The @option{GNAT}, @option{COMPACT}, and @option{UNCOMPACT} options for the
16267 @option{/CONSTRUCT_LAYOUT} qualifier are incompatible.
16270 @node General Text Layout Control
16271 @subsection General Text Layout Control
16274 These switches allow control over line length and indentation.
16277 @item ^-M@var{nnn}^/LINE_LENGTH_MAX=@var{nnn}^
16278 @cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp})
16279 Maximum line length, @var{nnn} from 32@dots{}256, the default value is 79
16281 @item ^-i@var{nnn}^/INDENTATION_LEVEL=@var{nnn}^
16282 @cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp})
16283 Indentation level, @var{nnn} from 1@dots{}9, the default value is 3
16285 @item ^-cl@var{nnn}^/CONTINUATION_INDENT=@var{nnn}^
16286 @cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp})
16287 Indentation level for continuation lines (relative to the line being
16288 continued), @var{nnn} from 1@dots{}9.
16290 value is one less then the (normal) indentation level, unless the
16291 indentation is set to 1 (in which case the default value for continuation
16292 line indentation is also 1)
16295 @node Other Formatting Options
16296 @subsection Other Formatting Options
16299 These switches control the inclusion of missing end/exit labels, and
16300 the indentation level in @b{case} statements.
16303 @item ^-e^/NO_MISSED_LABELS^
16304 @cindex @option{^-e^/NO_MISSED_LABELS^} (@command{gnatpp})
16305 Do not insert missing end/exit labels. An end label is the name of
16306 a construct that may optionally be repeated at the end of the
16307 construct's declaration;
16308 e.g., the names of packages, subprograms, and tasks.
16309 An exit label is the name of a loop that may appear as target
16310 of an exit statement within the loop.
16311 By default, @command{gnatpp} inserts these end/exit labels when
16312 they are absent from the original source. This option suppresses such
16313 insertion, so that the formatted source reflects the original.
16315 @item ^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^
16316 @cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp})
16317 Insert a Form Feed character after a pragma Page.
16319 @item ^-T@var{nnn}^/MAX_INDENT=@var{nnn}^
16320 @cindex @option{^-T^/MAX_INDENT^} (@command{gnatpp})
16321 Do not use an additional indentation level for @b{case} alternatives
16322 and variants if there are @var{nnn} or more (the default
16324 If @var{nnn} is 0, an additional indentation level is
16325 used for @b{case} alternatives and variants regardless of their number.
16328 @node Setting the Source Search Path
16329 @subsection Setting the Source Search Path
16332 To define the search path for the input source file, @command{gnatpp}
16333 uses the same switches as the GNAT compiler, with the same effects.
16336 @item ^-I^/SEARCH=^@var{dir}
16337 @cindex @option{^-I^/SEARCH^} (@code{gnatpp})
16338 The same as the corresponding gcc switch
16340 @item ^-I-^/NOCURRENT_DIRECTORY^
16341 @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatpp})
16342 The same as the corresponding gcc switch
16344 @item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE^=@var{path}
16345 @cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@code{gnatpp})
16346 The same as the corresponding gcc switch
16348 @item ^--RTS^/RUNTIME_SYSTEM^=@var{path}
16349 @cindex @option{^--RTS^/RUNTIME_SYSTEM^} (@code{gnatpp})
16350 The same as the corresponding gcc switch
16354 @node Output File Control
16355 @subsection Output File Control
16358 By default the output is sent to the file whose name is obtained by appending
16359 the ^@file{.pp}^@file{$PP}^ suffix to the name of the input file
16360 (if the file with this name already exists, it is unconditionally overwritten).
16361 Thus if the input file is @file{^my_ada_proc.adb^MY_ADA_PROC.ADB^} then
16362 @command{gnatpp} will produce @file{^my_ada_proc.adb.pp^MY_ADA_PROC.ADB$PP^}
16364 The output may be redirected by the following switches:
16367 @item ^-pipe^/STANDARD_OUTPUT^
16368 @cindex @option{^-pipe^/STANDARD_OUTPUT^} (@code{gnatpp})
16369 Send the output to @code{Standard_Output}
16371 @item ^-o @var{output_file}^/OUTPUT=@var{output_file}^
16372 @cindex @option{^-o^/OUTPUT^} (@code{gnatpp})
16373 Write the output into @var{output_file}.
16374 If @var{output_file} already exists, @command{gnatpp} terminates without
16375 reading or processing the input file.
16377 @item ^-of ^/FORCED_OUTPUT=^@var{output_file}
16378 @cindex @option{^-of^/FORCED_OUTPUT^} (@code{gnatpp})
16379 Write the output into @var{output_file}, overwriting the existing file
16380 (if one is present).
16382 @item ^-r^/REPLACE^
16383 @cindex @option{^-r^/REPLACE^} (@code{gnatpp})
16384 Replace the input source file with the reformatted output, and copy the
16385 original input source into the file whose name is obtained by appending the
16386 ^@file{.npp}^@file{$NPP}^ suffix to the name of the input file.
16387 If a file with this name already exists, @command{gnatpp} terminates without
16388 reading or processing the input file.
16390 @item ^-rf^/OVERRIDING_REPLACE^
16391 @cindex @option{^-rf^/OVERRIDING_REPLACE^} (@code{gnatpp})
16392 Like @option{^-r^/REPLACE^} except that if the file with the specified name
16393 already exists, it is overwritten.
16395 @item ^-rnb^/REPLACE_NO_BACKUP^
16396 @cindex @option{^-rnb^/REPLACE_NO_BACKUP^} (@code{gnatpp})
16397 Replace the input source file with the reformatted output without
16398 creating any backup copy of the input source.
16400 @item ^--eol=@var{xxx}^/END_OF_LINE=@var{xxx}^
16401 @cindex @option{^--eol^/END_OF_LINE^} (@code{gnatpp})
16402 Specifies the format of the reformatted output file. The @var{xxx}
16403 ^string specified with the switch^option^ may be either
16405 @item ``@option{^dos^DOS^}'' MS DOS style, lines end with CR LF characters
16406 @item ``@option{^crlf^CRLF^}''
16407 the same as @option{^crlf^CRLF^}
16408 @item ``@option{^unix^UNIX^}'' UNIX style, lines end with LF character
16409 @item ``@option{^lf^LF^}''
16410 the same as @option{^unix^UNIX^}
16413 @item ^-W^/RESULT_ENCODING=^@var{e}
16414 @cindex @option{^-W^/RESULT_ENCODING=^} (@command{gnatpp})
16415 Specify the wide character encoding method used to write the code in the
16417 @var{e} is one of the following:
16425 Upper half encoding
16427 @item ^s^SHIFT_JIS^
16437 Brackets encoding (default value)
16443 Options @option{^-pipe^/STANDARD_OUTPUT^},
16444 @option{^-o^/OUTPUT^} and
16445 @option{^-of^/FORCED_OUTPUT^} are allowed only if the call to gnatpp
16446 contains only one file to reformat.
16448 @option{^--eol^/END_OF_LINE^}
16450 @option{^-W^/RESULT_ENCODING^}
16451 cannot be used together
16452 with @option{^-pipe^/STANDARD_OUTPUT^} option.
16454 @node Other gnatpp Switches
16455 @subsection Other @code{gnatpp} Switches
16458 The additional @command{gnatpp} switches are defined in this subsection.
16461 @item ^-files @var{filename}^/FILES=@var{output_file}^
16462 @cindex @option{^-files^/FILES^} (@code{gnatpp})
16463 Take the argument source files from the specified file. This file should be an
16464 ordinary textual file containing file names separated by spaces or
16465 line breaks. You can use this switch more then once in the same call to
16466 @command{gnatpp}. You also can combine this switch with explicit list of
16469 @item ^-v^/VERBOSE^
16470 @cindex @option{^-v^/VERBOSE^} (@code{gnatpp})
16472 @command{gnatpp} generates version information and then
16473 a trace of the actions it takes to produce or obtain the ASIS tree.
16475 @item ^-w^/WARNINGS^
16476 @cindex @option{^-w^/WARNINGS^} (@code{gnatpp})
16478 @command{gnatpp} generates a warning whenever it cannot provide
16479 a required layout in the result source.
16482 @node Formatting Rules
16483 @section Formatting Rules
16486 The following subsections show how @command{gnatpp} treats ``white space'',
16487 comments, program layout, and name casing.
16488 They provide the detailed descriptions of the switches shown above.
16491 * White Space and Empty Lines::
16492 * Formatting Comments::
16493 * Construct Layout::
16497 @node White Space and Empty Lines
16498 @subsection White Space and Empty Lines
16501 @command{gnatpp} does not have an option to control space characters.
16502 It will add or remove spaces according to the style illustrated by the
16503 examples in the @cite{Ada Reference Manual}.
16505 The only format effectors
16506 (see @cite{Ada Reference Manual}, paragraph 2.1(13))
16507 that will appear in the output file are platform-specific line breaks,
16508 and also format effectors within (but not at the end of) comments.
16509 In particular, each horizontal tab character that is not inside
16510 a comment will be treated as a space and thus will appear in the
16511 output file as zero or more spaces depending on
16512 the reformatting of the line in which it appears.
16513 The only exception is a Form Feed character, which is inserted after a
16514 pragma @code{Page} when @option{-ff} is set.
16516 The output file will contain no lines with trailing ``white space'' (spaces,
16519 Empty lines in the original source are preserved
16520 only if they separate declarations or statements.
16521 In such contexts, a
16522 sequence of two or more empty lines is replaced by exactly one empty line.
16523 Note that a blank line will be removed if it separates two ``comment blocks''
16524 (a comment block is a sequence of whole-line comments).
16525 In order to preserve a visual separation between comment blocks, use an
16526 ``empty comment'' (a line comprising only hyphens) rather than an empty line.
16527 Likewise, if for some reason you wish to have a sequence of empty lines,
16528 use a sequence of empty comments instead.
16530 @node Formatting Comments
16531 @subsection Formatting Comments
16534 Comments in Ada code are of two kinds:
16537 a @emph{whole-line comment}, which appears by itself (possibly preceded by
16538 ``white space'') on a line
16541 an @emph{end-of-line comment}, which follows some other Ada lexical element
16546 The indentation of a whole-line comment is that of either
16547 the preceding or following line in
16548 the formatted source, depending on switch settings as will be described below.
16550 For an end-of-line comment, @command{gnatpp} leaves the same number of spaces
16551 between the end of the preceding Ada lexical element and the beginning
16552 of the comment as appear in the original source,
16553 unless either the comment has to be split to
16554 satisfy the line length limitation, or else the next line contains a
16555 whole line comment that is considered a continuation of this end-of-line
16556 comment (because it starts at the same position).
16558 cases, the start of the end-of-line comment is moved right to the nearest
16559 multiple of the indentation level.
16560 This may result in a ``line overflow'' (the right-shifted comment extending
16561 beyond the maximum line length), in which case the comment is split as
16564 There is a difference between @option{^-c1^/COMMENTS_LAYOUT=DEFAULT^}
16565 (GNAT-style comment line indentation)
16566 and @option{^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^}
16567 (reference-manual comment line indentation).
16568 With reference-manual style, a whole-line comment is indented as if it
16569 were a declaration or statement at the same place
16570 (i.e., according to the indentation of the preceding line(s)).
16571 With GNAT style, a whole-line comment that is immediately followed by an
16572 @b{if} or @b{case} statement alternative, a record variant, or the reserved
16573 word @b{begin}, is indented based on the construct that follows it.
16576 @smallexample @c ada
16588 Reference-manual indentation produces:
16590 @smallexample @c ada
16602 while GNAT-style indentation produces:
16604 @smallexample @c ada
16616 The @option{^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^} switch
16617 (GNAT style comment beginning) has the following
16622 For each whole-line comment that does not end with two hyphens,
16623 @command{gnatpp} inserts spaces if necessary after the starting two hyphens
16624 to ensure that there are at least two spaces between these hyphens and the
16625 first non-blank character of the comment.
16629 For an end-of-line comment, if in the original source the next line is a
16630 whole-line comment that starts at the same position
16631 as the end-of-line comment,
16632 then the whole-line comment (and all whole-line comments
16633 that follow it and that start at the same position)
16634 will start at this position in the output file.
16637 That is, if in the original source we have:
16639 @smallexample @c ada
16642 A := B + C; -- B must be in the range Low1..High1
16643 -- C must be in the range Low2..High2
16644 --B+C will be in the range Low1+Low2..High1+High2
16650 Then in the formatted source we get
16652 @smallexample @c ada
16655 A := B + C; -- B must be in the range Low1..High1
16656 -- C must be in the range Low2..High2
16657 -- B+C will be in the range Low1+Low2..High1+High2
16663 A comment that exceeds the line length limit will be split.
16665 @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} (reformat comment blocks) is set and
16666 the line belongs to a reformattable block, splitting the line generates a
16667 @command{gnatpp} warning.
16668 The @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} switch specifies that whole-line
16669 comments may be reformatted in typical
16670 word processor style (that is, moving words between lines and putting as
16671 many words in a line as possible).
16674 The @option{^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^} switch specifies, that comments
16675 that has a special format (that is, a character that is neither a letter nor digit
16676 not white space nor line break immediately following the leading @code{--} of
16677 the comment) should be without any change moved from the argument source
16678 into reformatted source. This switch allows to preserve comments that are used
16679 as a special marks in the code (e.g.@: SPARK annotation).
16681 @node Construct Layout
16682 @subsection Construct Layout
16685 In several cases the suggested layout in the Ada Reference Manual includes
16686 an extra level of indentation that many programmers prefer to avoid. The
16687 affected cases include:
16691 @item Record type declaration (RM 3.8)
16693 @item Record representation clause (RM 13.5.1)
16695 @item Loop statement in case if a loop has a statement identifier (RM 5.6)
16697 @item Block statement in case if a block has a statement identifier (RM 5.6)
16701 In compact mode (when GNAT style layout or compact layout is set),
16702 the pretty printer uses one level of indentation instead
16703 of two. This is achieved in the record definition and record representation
16704 clause cases by putting the @code{record} keyword on the same line as the
16705 start of the declaration or representation clause, and in the block and loop
16706 case by putting the block or loop header on the same line as the statement
16710 The difference between GNAT style @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^}
16711 and compact @option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^}
16712 layout on the one hand, and uncompact layout
16713 @option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} on the other hand,
16714 can be illustrated by the following examples:
16718 @multitable @columnfractions .5 .5
16719 @item @i{GNAT style, compact layout} @tab @i{Uncompact layout}
16722 @smallexample @c ada
16729 @smallexample @c ada
16738 @smallexample @c ada
16740 a at 0 range 0 .. 31;
16741 b at 4 range 0 .. 31;
16745 @smallexample @c ada
16748 a at 0 range 0 .. 31;
16749 b at 4 range 0 .. 31;
16754 @smallexample @c ada
16762 @smallexample @c ada
16772 @smallexample @c ada
16773 Clear : for J in 1 .. 10 loop
16778 @smallexample @c ada
16780 for J in 1 .. 10 loop
16791 GNAT style, compact layout Uncompact layout
16793 type q is record type q is
16794 a : integer; record
16795 b : integer; a : integer;
16796 end record; b : integer;
16799 for q use record for q use
16800 a at 0 range 0 .. 31; record
16801 b at 4 range 0 .. 31; a at 0 range 0 .. 31;
16802 end record; b at 4 range 0 .. 31;
16805 Block : declare Block :
16806 A : Integer := 3; declare
16807 begin A : Integer := 3;
16809 end Block; Proc (A, A);
16812 Clear : for J in 1 .. 10 loop Clear :
16813 A (J) := 0; for J in 1 .. 10 loop
16814 end loop Clear; A (J) := 0;
16821 A further difference between GNAT style layout and compact layout is that
16822 GNAT style layout inserts empty lines as separation for
16823 compound statements, return statements and bodies.
16825 Note that the layout specified by
16826 @option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^}
16827 for named block and loop statements overrides the layout defined by these
16828 constructs by @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^},
16829 @option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^} or
16830 @option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} option.
16833 @subsection Name Casing
16836 @command{gnatpp} always converts the usage occurrence of a (simple) name to
16837 the same casing as the corresponding defining identifier.
16839 You control the casing for defining occurrences via the
16840 @option{^-n^/NAME_CASING^} switch.
16842 With @option{-nD} (``as declared'', which is the default),
16845 With @option{/NAME_CASING=AS_DECLARED}, which is the default,
16847 defining occurrences appear exactly as in the source file
16848 where they are declared.
16849 The other ^values for this switch^options for this qualifier^ ---
16850 @option{^-nU^UPPER_CASE^},
16851 @option{^-nL^LOWER_CASE^},
16852 @option{^-nM^MIXED_CASE^} ---
16854 ^upper, lower, or mixed case, respectively^the corresponding casing^.
16855 If @command{gnatpp} changes the casing of a defining
16856 occurrence, it analogously changes the casing of all the
16857 usage occurrences of this name.
16859 If the defining occurrence of a name is not in the source compilation unit
16860 currently being processed by @command{gnatpp}, the casing of each reference to
16861 this name is changed according to the value of the @option{^-n^/NAME_CASING^}
16862 switch (subject to the dictionary file mechanism described below).
16863 Thus @command{gnatpp} acts as though the @option{^-n^/NAME_CASING^} switch
16865 casing for the defining occurrence of the name.
16867 Some names may need to be spelled with casing conventions that are not
16868 covered by the upper-, lower-, and mixed-case transformations.
16869 You can arrange correct casing by placing such names in a
16870 @emph{dictionary file},
16871 and then supplying a @option{^-D^/DICTIONARY^} switch.
16872 The casing of names from dictionary files overrides
16873 any @option{^-n^/NAME_CASING^} switch.
16875 To handle the casing of Ada predefined names and the names from GNAT libraries,
16876 @command{gnatpp} assumes a default dictionary file.
16877 The name of each predefined entity is spelled with the same casing as is used
16878 for the entity in the @cite{Ada Reference Manual}.
16879 The name of each entity in the GNAT libraries is spelled with the same casing
16880 as is used in the declaration of that entity.
16882 The @w{@option{^-D-^/SPECIFIC_CASING^}} switch suppresses the use of the
16883 default dictionary file.
16884 Instead, the casing for predefined and GNAT-defined names will be established
16885 by the @option{^-n^/NAME_CASING^} switch or explicit dictionary files.
16886 For example, by default the names @code{Ada.Text_IO} and @code{GNAT.OS_Lib}
16887 will appear as just shown,
16888 even in the presence of a @option{^-nU^/NAME_CASING=UPPER_CASE^} switch.
16889 To ensure that even such names are rendered in uppercase,
16890 additionally supply the @w{@option{^-D-^/SPECIFIC_CASING^}} switch
16891 (or else, less conveniently, place these names in upper case in a dictionary
16894 A dictionary file is
16895 a plain text file; each line in this file can be either a blank line
16896 (containing only space characters and ASCII.HT characters), an Ada comment
16897 line, or the specification of exactly one @emph{casing schema}.
16899 A casing schema is a string that has the following syntax:
16903 @var{casing_schema} ::= @var{identifier} | *@var{simple_identifier}*
16905 @var{simple_identifier} ::= @var{letter}@{@var{letter_or_digit}@}
16910 (See @cite{Ada Reference Manual}, Section 2.3) for the definition of the
16911 @var{identifier} lexical element and the @var{letter_or_digit} category.)
16913 The casing schema string can be followed by white space and/or an Ada-style
16914 comment; any amount of white space is allowed before the string.
16916 If a dictionary file is passed as
16918 the value of a @option{-D@var{file}} switch
16921 an option to the @option{/DICTIONARY} qualifier
16924 simple name and every identifier, @command{gnatpp} checks if the dictionary
16925 defines the casing for the name or for some of its parts (the term ``subword''
16926 is used below to denote the part of a name which is delimited by ``_'' or by
16927 the beginning or end of the word and which does not contain any ``_'' inside):
16931 if the whole name is in the dictionary, @command{gnatpp} uses for this name
16932 the casing defined by the dictionary; no subwords are checked for this word
16935 for every subword @command{gnatpp} checks if the dictionary contains the
16936 corresponding string of the form @code{*@var{simple_identifier}*},
16937 and if it does, the casing of this @var{simple_identifier} is used
16941 if the whole name does not contain any ``_'' inside, and if for this name
16942 the dictionary contains two entries - one of the form @var{identifier},
16943 and another - of the form *@var{simple_identifier}*, then the first one
16944 is applied to define the casing of this name
16947 if more than one dictionary file is passed as @command{gnatpp} switches, each
16948 dictionary adds new casing exceptions and overrides all the existing casing
16949 exceptions set by the previous dictionaries
16952 when @command{gnatpp} checks if the word or subword is in the dictionary,
16953 this check is not case sensitive
16957 For example, suppose we have the following source to reformat:
16959 @smallexample @c ada
16962 name1 : integer := 1;
16963 name4_name3_name2 : integer := 2;
16964 name2_name3_name4 : Boolean;
16967 name2_name3_name4 := name4_name3_name2 > name1;
16973 And suppose we have two dictionaries:
16990 If @command{gnatpp} is called with the following switches:
16994 @command{gnatpp -nM -D dict1 -D dict2 test.adb}
16997 @command{gnatpp test.adb /NAME_CASING=MIXED_CASE /DICTIONARY=(dict1, dict2)}
17002 then we will get the following name casing in the @command{gnatpp} output:
17004 @smallexample @c ada
17007 NAME1 : Integer := 1;
17008 Name4_NAME3_Name2 : Integer := 2;
17009 Name2_NAME3_Name4 : Boolean;
17012 Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
17017 @c *********************************
17018 @node The GNAT Metric Tool gnatmetric
17019 @chapter The GNAT Metric Tool @command{gnatmetric}
17021 @cindex Metric tool
17024 ^The @command{gnatmetric} tool^@command{GNAT METRIC}^ is an ASIS-based utility
17025 for computing various program metrics.
17026 It takes an Ada source file as input and generates a file containing the
17027 metrics data as output. Various switches control which
17028 metrics are computed and output.
17030 @command{gnatmetric} generates and uses the ASIS
17031 tree for the input source and thus requires the input to be syntactically and
17032 semantically legal.
17033 If this condition is not met, @command{gnatmetric} will generate
17034 an error message; no metric information for this file will be
17035 computed and reported.
17037 If the compilation unit contained in the input source depends semantically
17038 upon units in files located outside the current directory, you have to provide
17039 the source search path when invoking @command{gnatmetric}.
17040 If it depends semantically upon units that are contained
17041 in files with names that do not follow the GNAT file naming rules, you have to
17042 provide the configuration file describing the corresponding naming scheme (see
17043 the description of the @command{gnatmetric} switches below.)
17044 Alternatively, you may use a project file and invoke @command{gnatmetric}
17045 through the @command{gnat} driver.
17047 The @command{gnatmetric} command has the form
17050 $ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
17057 @var{switches} specify the metrics to compute and define the destination for
17061 Each @var{filename} is the name (including the extension) of a source
17062 file to process. ``Wildcards'' are allowed, and
17063 the file name may contain path information.
17064 If no @var{filename} is supplied, then the @var{switches} list must contain
17066 @option{-files} switch (@pxref{Other gnatmetric Switches}).
17067 Including both a @option{-files} switch and one or more
17068 @var{filename} arguments is permitted.
17071 @samp{-cargs @var{gcc_switches}} is a list of switches for
17072 @command{gcc}. They will be passed on to all compiler invocations made by
17073 @command{gnatmetric} to generate the ASIS trees. Here you can provide
17074 @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
17075 and use the @option{-gnatec} switch to set the configuration file.
17079 * Switches for gnatmetric::
17082 @node Switches for gnatmetric
17083 @section Switches for @command{gnatmetric}
17086 The following subsections describe the various switches accepted by
17087 @command{gnatmetric}, organized by category.
17090 * Output Files Control::
17091 * Disable Metrics For Local Units::
17092 * Specifying a set of metrics to compute::
17093 * Other gnatmetric Switches::
17094 * Generate project-wide metrics::
17097 @node Output Files Control
17098 @subsection Output File Control
17099 @cindex Output file control in @command{gnatmetric}
17102 @command{gnatmetric} has two output formats. It can generate a
17103 textual (human-readable) form, and also XML. By default only textual
17104 output is generated.
17106 When generating the output in textual form, @command{gnatmetric} creates
17107 for each Ada source file a corresponding text file
17108 containing the computed metrics, except for the case when the set of metrics
17109 specified by gnatmetric parameters consists only of metrics that are computed
17110 for the whole set of analyzed sources, but not for each Ada source.
17111 By default, this file is placed in the same directory as where the source
17112 file is located, and its name is obtained
17113 by appending the ^@file{.metrix}^@file{$METRIX}^ suffix to the name of the
17116 All the output information generated in XML format is placed in a single
17117 file. By default this file is placed in the current directory and has the
17118 name ^@file{metrix.xml}^@file{METRIX$XML}^.
17120 Some of the computed metrics are summed over the units passed to
17121 @command{gnatmetric}; for example, the total number of lines of code.
17122 By default this information is sent to @file{stdout}, but a file
17123 can be specified with the @option{-og} switch.
17125 The following switches control the @command{gnatmetric} output:
17128 @cindex @option{^-x^/XML^} (@command{gnatmetric})
17130 Generate the XML output
17132 @cindex @option{^-nt^/NO_TEXT^} (@command{gnatmetric})
17133 @item ^-nt^/NO_TEXT^
17134 Do not generate the output in text form (implies @option{^-x^/XML^})
17136 @cindex @option{^-d^/DIRECTORY^} (@command{gnatmetric})
17137 @item ^-d @var{output_dir}^/DIRECTORY=@var{output_dir}^
17138 Put textual files with detailed metrics into @var{output_dir}
17140 @cindex @option{^-o^/SUFFIX_DETAILS^} (@command{gnatmetric})
17141 @item ^-o @var{file_suffix}^/SUFFIX_DETAILS=@var{file_suffix}^
17142 Use @var{file_suffix}, instead of ^@file{.metrix}^@file{$METRIX}^
17143 in the name of the output file.
17145 @cindex @option{^-og^/GLOBAL_OUTPUT^} (@command{gnatmetric})
17146 @item ^-og @var{file_name}^/GLOBAL_OUTPUT=@var{file_name}^
17147 Put global metrics into @var{file_name}
17149 @cindex @option{^-ox^/XML_OUTPUT^} (@command{gnatmetric})
17150 @item ^-ox @var{file_name}^/XML_OUTPUT=@var{file_name}^
17151 Put the XML output into @var{file_name} (also implies @option{^-x^/XML^})
17153 @cindex @option{^-sfn^/SHORT_SOURCE_FILE_NAME^} (@command{gnatmetric})
17154 @item ^-sfn^/SHORT_SOURCE_FILE_NAME^
17155 Use ``short'' source file names in the output. (The @command{gnatmetric}
17156 output includes the name(s) of the Ada source file(s) from which the metrics
17157 are computed. By default each name includes the absolute path. The
17158 @option{^-sfn^/SHORT_SOURCE_FILE_NAME^} switch causes @command{gnatmetric}
17159 to exclude all directory information from the file names that are output.)
17163 @node Disable Metrics For Local Units
17164 @subsection Disable Metrics For Local Units
17165 @cindex Disable Metrics For Local Units in @command{gnatmetric}
17168 @command{gnatmetric} relies on the GNAT compilation model @minus{}
17170 unit per one source file. It computes line metrics for the whole source
17171 file, and it also computes syntax
17172 and complexity metrics for the file's outermost unit.
17174 By default, @command{gnatmetric} will also compute all metrics for certain
17175 kinds of locally declared program units:
17179 subprogram (and generic subprogram) bodies;
17182 package (and generic package) specs and bodies;
17185 task object and type specifications and bodies;
17188 protected object and type specifications and bodies.
17192 These kinds of entities will be referred to as
17193 @emph{eligible local program units}, or simply @emph{eligible local units},
17194 @cindex Eligible local unit (for @command{gnatmetric})
17195 in the discussion below.
17197 Note that a subprogram declaration, generic instantiation,
17198 or renaming declaration only receives metrics
17199 computation when it appear as the outermost entity
17202 Suppression of metrics computation for eligible local units can be
17203 obtained via the following switch:
17206 @cindex @option{^-n@var{x}^/SUPPRESS^} (@command{gnatmetric})
17207 @item ^-nolocal^/SUPPRESS=LOCAL_DETAILS^
17208 Do not compute detailed metrics for eligible local program units
17212 @node Specifying a set of metrics to compute
17213 @subsection Specifying a set of metrics to compute
17216 By default all the metrics are computed and reported. The switches
17217 described in this subsection allow you to control, on an individual
17218 basis, whether metrics are computed and
17219 reported. If at least one positive metric
17220 switch is specified (that is, a switch that defines that a given
17221 metric or set of metrics is to be computed), then only
17222 explicitly specified metrics are reported.
17225 * Line Metrics Control::
17226 * Syntax Metrics Control::
17227 * Complexity Metrics Control::
17228 * Object-Oriented Metrics Control::
17231 @node Line Metrics Control
17232 @subsubsection Line Metrics Control
17233 @cindex Line metrics control in @command{gnatmetric}
17236 For any (legal) source file, and for each of its
17237 eligible local program units, @command{gnatmetric} computes the following
17242 the total number of lines;
17245 the total number of code lines (i.e., non-blank lines that are not comments)
17248 the number of comment lines
17251 the number of code lines containing end-of-line comments;
17254 the comment percentage: the ratio between the number of lines that contain
17255 comments and the number of all non-blank lines, expressed as a percentage;
17258 the number of empty lines and lines containing only space characters and/or
17259 format effectors (blank lines)
17262 the average number of code lines in subprogram bodies, task bodies, entry
17263 bodies and statement sequences in package bodies (this metric is only computed
17264 across the whole set of the analyzed units)
17269 @command{gnatmetric} sums the values of the line metrics for all the
17270 files being processed and then generates the cumulative results. The tool
17271 also computes for all the files being processed the average number of code
17274 You can use the following switches to select the specific line metrics
17275 to be computed and reported.
17278 @cindex @option{^--lines@var{x}^/LINE_COUNT_METRICS^} (@command{gnatmetric})
17281 @cindex @option{--no-lines@var{x}}
17284 @item ^--lines-all^/LINE_COUNT_METRICS=ALL_ON^
17285 Report all the line metrics
17287 @item ^--no-lines-all^/LINE_COUNT_METRICS=ALL_OFF^
17288 Do not report any of line metrics
17290 @item ^--lines^/LINE_COUNT_METRICS=ALL_LINES_ON^
17291 Report the number of all lines
17293 @item ^--no-lines^/LINE_COUNT_METRICS=ALL_LINES_OFF^
17294 Do not report the number of all lines
17296 @item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES_ON^
17297 Report the number of code lines
17299 @item ^--no-lines-code^/LINE_COUNT_METRICS=CODE_LINES_OFF^
17300 Do not report the number of code lines
17302 @item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_ON^
17303 Report the number of comment lines
17305 @item ^--no-lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_OFF^
17306 Do not report the number of comment lines
17308 @item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_ON^
17309 Report the number of code lines containing
17310 end-of-line comments
17312 @item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_OFF^
17313 Do not report the number of code lines containing
17314 end-of-line comments
17316 @item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_ON^
17317 Report the comment percentage in the program text
17319 @item ^--no-lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_OFF^
17320 Do not report the comment percentage in the program text
17322 @item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_ON^
17323 Report the number of blank lines
17325 @item ^--no-lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_OFF^
17326 Do not report the number of blank lines
17328 @item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_ON^
17329 Report the average number of code lines in subprogram bodies, task bodies,
17330 entry bodies and statement sequences in package bodies. The metric is computed
17331 and reported for the whole set of processed Ada sources only.
17333 @item ^--no-lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_OFF^
17334 Do not report the average number of code lines in subprogram bodies,
17335 task bodies, entry bodies and statement sequences in package bodies.
17339 @node Syntax Metrics Control
17340 @subsubsection Syntax Metrics Control
17341 @cindex Syntax metrics control in @command{gnatmetric}
17344 @command{gnatmetric} computes various syntactic metrics for the
17345 outermost unit and for each eligible local unit:
17348 @item LSLOC (``Logical Source Lines Of Code'')
17349 The total number of declarations and the total number of statements
17351 @item Maximal static nesting level of inner program units
17353 @cite{Ada Reference Manual}, 10.1(1), ``A program unit is either a
17354 package, a task unit, a protected unit, a
17355 protected entry, a generic unit, or an explicitly declared subprogram other
17356 than an enumeration literal.''
17358 @item Maximal nesting level of composite syntactic constructs
17359 This corresponds to the notion of the
17360 maximum nesting level in the GNAT built-in style checks
17361 (@pxref{Style Checking})
17365 For the outermost unit in the file, @command{gnatmetric} additionally computes
17366 the following metrics:
17369 @item Public subprograms
17370 This metric is computed for package specs. It is the
17371 number of subprograms and generic subprograms declared in the visible
17372 part (including the visible part of nested packages, protected objects, and
17375 @item All subprograms
17376 This metric is computed for bodies and subunits. The
17377 metric is equal to a total number of subprogram bodies in the compilation
17379 Neither generic instantiations nor renamings-as-a-body nor body stubs
17380 are counted. Any subprogram body is counted, independently of its nesting
17381 level and enclosing constructs. Generic bodies and bodies of protected
17382 subprograms are counted in the same way as ``usual'' subprogram bodies.
17385 This metric is computed for package specs and
17386 generic package declarations. It is the total number of types
17387 that can be referenced from outside this compilation unit, plus the
17388 number of types from all the visible parts of all the visible generic
17389 packages. Generic formal types are not counted. Only types, not subtypes,
17393 Along with the total number of public types, the following
17394 types are counted and reported separately:
17401 Root tagged types (abstract, non-abstract, private, non-private). Type
17402 extensions are @emph{not} counted
17405 Private types (including private extensions)
17416 This metric is computed for any compilation unit. It is equal to the total
17417 number of the declarations of different types given in the compilation unit.
17418 The private and the corresponding full type declaration are counted as one
17419 type declaration. Incomplete type declarations and generic formal types
17421 No distinction is made among different kinds of types (abstract,
17422 private etc.); the total number of types is computed and reported.
17427 By default, all the syntax metrics are computed and reported. You can use the
17428 following switches to select specific syntax metrics.
17432 @cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric})
17435 @cindex @option{--no-syntax@var{x}} (@command{gnatmetric})
17438 @item ^--syntax-all^/SYNTAX_METRICS=ALL_ON^
17439 Report all the syntax metrics
17441 @item ^--no-syntax-all^/ALL_OFF^
17442 Do not report any of syntax metrics
17444 @item ^--declarations^/SYNTAX_METRICS=DECLARATIONS_ON^
17445 Report the total number of declarations
17447 @item ^--no-declarations^/SYNTAX_METRICS=DECLARATIONS_OFF^
17448 Do not report the total number of declarations
17450 @item ^--statements^/SYNTAX_METRICS=STATEMENTS_ON^
17451 Report the total number of statements
17453 @item ^--no-statements^/SYNTAX_METRICS=STATEMENTS_OFF^
17454 Do not report the total number of statements
17456 @item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_ON^
17457 Report the number of public subprograms in a compilation unit
17459 @item ^--no-public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_OFF^
17460 Do not report the number of public subprograms in a compilation unit
17462 @item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_ON^
17463 Report the number of all the subprograms in a compilation unit
17465 @item ^--no-all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_OFF^
17466 Do not report the number of all the subprograms in a compilation unit
17468 @item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES_ON^
17469 Report the number of public types in a compilation unit
17471 @item ^--no-public-types^/SYNTAX_METRICS=PUBLIC_TYPES_OFF^
17472 Do not report the number of public types in a compilation unit
17474 @item ^--all-types^/SYNTAX_METRICS=ALL_TYPES_ON^
17475 Report the number of all the types in a compilation unit
17477 @item ^--no-all-types^/SYNTAX_METRICS=ALL_TYPES_OFF^
17478 Do not report the number of all the types in a compilation unit
17480 @item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_ON^
17481 Report the maximal program unit nesting level
17483 @item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^
17484 Do not report the maximal program unit nesting level
17486 @item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_ON^
17487 Report the maximal construct nesting level
17489 @item ^--no-construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_OFF^
17490 Do not report the maximal construct nesting level
17494 @node Complexity Metrics Control
17495 @subsubsection Complexity Metrics Control
17496 @cindex Complexity metrics control in @command{gnatmetric}
17499 For a program unit that is an executable body (a subprogram body (including
17500 generic bodies), task body, entry body or a package body containing
17501 its own statement sequence) @command{gnatmetric} computes the following
17502 complexity metrics:
17506 McCabe cyclomatic complexity;
17509 McCabe essential complexity;
17512 maximal loop nesting level
17517 The McCabe complexity metrics are defined
17518 in @url{http://www.mccabe.com/pdf/nist235r.pdf}
17520 According to McCabe, both control statements and short-circuit control forms
17521 should be taken into account when computing cyclomatic complexity. For each
17522 body, we compute three metric values:
17526 the complexity introduced by control
17527 statements only, without taking into account short-circuit forms,
17530 the complexity introduced by short-circuit control forms only, and
17534 cyclomatic complexity, which is the sum of these two values.
17538 When computing cyclomatic and essential complexity, @command{gnatmetric} skips
17539 the code in the exception handlers and in all the nested program units.
17541 By default, all the complexity metrics are computed and reported.
17542 For more fine-grained control you can use
17543 the following switches:
17546 @cindex @option{^-complexity@var{x}^/COMPLEXITY_METRICS^} (@command{gnatmetric})
17549 @cindex @option{--no-complexity@var{x}}
17552 @item ^--complexity-all^/COMPLEXITY_METRICS=ALL_ON^
17553 Report all the complexity metrics
17555 @item ^--no-complexity-all^/COMPLEXITY_METRICS=ALL_OFF^
17556 Do not report any of complexity metrics
17558 @item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_ON^
17559 Report the McCabe Cyclomatic Complexity
17561 @item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_OFF^
17562 Do not report the McCabe Cyclomatic Complexity
17564 @item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_ON^
17565 Report the Essential Complexity
17567 @item ^--no-complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_OFF^
17568 Do not report the Essential Complexity
17570 @item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^
17571 Report maximal loop nesting level
17573 @item ^--no-loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_OFF^
17574 Do not report maximal loop nesting level
17576 @item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_ON^
17577 Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
17578 task bodies, entry bodies and statement sequences in package bodies.
17579 The metric is computed and reported for whole set of processed Ada sources
17582 @item ^--no-complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_OFF^
17583 Do not report the average McCabe Cyclomatic Complexity for all the subprogram
17584 bodies, task bodies, entry bodies and statement sequences in package bodies
17586 @cindex @option{^-ne^/NO_EXITS_AS_GOTOS^} (@command{gnatmetric})
17587 @item ^-ne^/NO_EXITS_AS_GOTOS^
17588 Do not consider @code{exit} statements as @code{goto}s when
17589 computing Essential Complexity
17594 @node Object-Oriented Metrics Control
17595 @subsubsection Object-Oriented Metrics Control
17596 @cindex Object-Oriented metrics control in @command{gnatmetric}
17599 @cindex Coupling metrics (in in @command{gnatmetric})
17600 Coupling metrics are object-oriented metrics that measure the
17601 dependencies between a given class (or a group of classes) and the
17602 ``external world'' (that is, the other classes in the program). In this
17603 subsection the term ``class'' is used in its
17604 traditional object-oriented programming sense
17605 (an instantiable module that contains data and/or method members).
17606 A @emph{category} (of classes)
17607 is a group of closely related classes that are reused and/or
17610 A class @code{K}'s @emph{efferent coupling} is the number of classes
17611 that @code{K} depends upon.
17612 A category's efferent coupling is the number of classes outside the
17613 category that the classes inside the category depend upon.
17615 A class @code{K}'s @emph{afferent coupling} is the number of classes
17616 that depend upon @code{K}.
17617 A category's afferent coupling is the number of classes outside the
17618 category that depend on classes belonging to the category.
17620 Ada's implementation of the object-oriented paradigm does not use the
17621 traditional class notion, so the definition of the coupling
17622 metrics for Ada maps the class and class category notions
17623 onto Ada constructs.
17625 For the coupling metrics, several kinds of modules -- a library package,
17626 a library generic package, and a library generic package instantiation --
17627 that define a tagged type or an interface type are
17628 considered to be a class. A category consists of a library package (or
17629 a library generic package) that defines a tagged or an interface type,
17630 together with all its descendant (generic) packages that define tagged
17631 or interface types. For any package counted as a class,
17632 its body (if any) is considered
17633 together with its spec when counting the dependencies. For dependencies
17634 between classes, the Ada semantic dependencies are considered.
17635 For coupling metrics, only dependencies on units that are considered as
17636 classes, are considered.
17638 When computing coupling metrics, @command{gnatmetric} counts only
17639 dependencies between units that are arguments of the gnatmetric call.
17640 Coupling metrics are program-wide (or project-wide) metrics, so to
17641 get a valid result, you should call @command{gnatmetric} for
17642 the whole set of sources that make up your program. It can be done
17643 by calling @command{gnatmetric} from the GNAT driver with @option{-U}
17644 option (see See @ref{The GNAT Driver and Project Files} for details.
17646 By default, all the coupling metrics are disabled. You can use the following
17647 switches to specify the coupling metrics to be computed and reported:
17652 @cindex @option{--package@var{x}} (@command{gnatmetric})
17653 @cindex @option{--no-package@var{x}} (@command{gnatmetric})
17654 @cindex @option{--category@var{x}} (@command{gnatmetric})
17655 @cindex @option{--no-category@var{x}} (@command{gnatmetric})
17659 @cindex @option{/COUPLING_METRICS} (@command{gnatmetric})
17662 @item ^--coupling-all^/COUPLING_METRICS=ALL_ON^
17663 Report all the coupling metrics
17665 @item ^--no-coupling-all^/COUPLING_METRICS=ALL_OFF^
17666 Do not report any of metrics
17668 @item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_ON^
17669 Report package efferent coupling
17671 @item ^--no-package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_OFF^
17672 Do not report package efferent coupling
17674 @item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_ON^
17675 Report package afferent coupling
17677 @item ^--no-package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_OFF^
17678 Do not report package afferent coupling
17680 @item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_ON^
17681 Report category efferent coupling
17683 @item ^--no-category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_OFF^
17684 Do not report category efferent coupling
17686 @item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_ON^
17687 Report category afferent coupling
17689 @item ^--no-category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_OFF^
17690 Do not report category afferent coupling
17694 @node Other gnatmetric Switches
17695 @subsection Other @code{gnatmetric} Switches
17698 Additional @command{gnatmetric} switches are as follows:
17701 @item ^-files @var{filename}^/FILES=@var{filename}^
17702 @cindex @option{^-files^/FILES^} (@code{gnatmetric})
17703 Take the argument source files from the specified file. This file should be an
17704 ordinary text file containing file names separated by spaces or
17705 line breaks. You can use this switch more then once in the same call to
17706 @command{gnatmetric}. You also can combine this switch with
17707 an explicit list of files.
17709 @item ^-v^/VERBOSE^
17710 @cindex @option{^-v^/VERBOSE^} (@code{gnatmetric})
17712 @command{gnatmetric} generates version information and then
17713 a trace of sources being processed.
17715 @item ^-dv^/DEBUG_OUTPUT^
17716 @cindex @option{^-dv^/DEBUG_OUTPUT^} (@code{gnatmetric})
17718 @command{gnatmetric} generates various messages useful to understand what
17719 happens during the metrics computation
17722 @cindex @option{^-q^/QUIET^} (@code{gnatmetric})
17726 @node Generate project-wide metrics
17727 @subsection Generate project-wide metrics
17729 In order to compute metrics on all units of a given project, you can use
17730 the @command{gnat} driver along with the @option{-P} option:
17736 If the project @code{proj} depends upon other projects, you can compute
17737 the metrics on the project closure using the @option{-U} option:
17739 gnat metric -Pproj -U
17743 Finally, if not all the units are relevant to a particular main
17744 program in the project closure, you can generate metrics for the set
17745 of units needed to create a given main program (unit closure) using
17746 the @option{-U} option followed by the name of the main unit:
17748 gnat metric -Pproj -U main
17752 @c ***********************************
17753 @node File Name Krunching Using gnatkr
17754 @chapter File Name Krunching Using @code{gnatkr}
17758 This chapter discusses the method used by the compiler to shorten
17759 the default file names chosen for Ada units so that they do not
17760 exceed the maximum length permitted. It also describes the
17761 @code{gnatkr} utility that can be used to determine the result of
17762 applying this shortening.
17766 * Krunching Method::
17767 * Examples of gnatkr Usage::
17771 @section About @code{gnatkr}
17774 The default file naming rule in GNAT
17775 is that the file name must be derived from
17776 the unit name. The exact default rule is as follows:
17779 Take the unit name and replace all dots by hyphens.
17781 If such a replacement occurs in the
17782 second character position of a name, and the first character is
17783 ^@samp{a}, @samp{g}, @samp{s}, or @samp{i}, ^@samp{A}, @samp{G}, @samp{S}, or @samp{I},^
17784 then replace the dot by the character
17785 ^@samp{~} (tilde)^@samp{$} (dollar sign)^
17786 instead of a minus.
17788 The reason for this exception is to avoid clashes
17789 with the standard names for children of System, Ada, Interfaces,
17790 and GNAT, which use the prefixes
17791 ^@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},^@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},^
17794 The @option{^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{nn}}
17795 switch of the compiler activates a ``krunching''
17796 circuit that limits file names to nn characters (where nn is a decimal
17797 integer). For example, using OpenVMS,
17798 where the maximum file name length is
17799 39, the value of nn is usually set to 39, but if you want to generate
17800 a set of files that would be usable if ported to a system with some
17801 different maximum file length, then a different value can be specified.
17802 The default value of 39 for OpenVMS need not be specified.
17804 The @code{gnatkr} utility can be used to determine the krunched name for
17805 a given file, when krunched to a specified maximum length.
17808 @section Using @code{gnatkr}
17811 The @code{gnatkr} command has the form
17815 $ gnatkr @var{name} @ovar{length}
17821 $ gnatkr @var{name} /COUNT=nn
17826 @var{name} is the uncrunched file name, derived from the name of the unit
17827 in the standard manner described in the previous section (i.e., in particular
17828 all dots are replaced by hyphens). The file name may or may not have an
17829 extension (defined as a suffix of the form period followed by arbitrary
17830 characters other than period). If an extension is present then it will
17831 be preserved in the output. For example, when krunching @file{hellofile.ads}
17832 to eight characters, the result will be hellofil.ads.
17834 Note: for compatibility with previous versions of @code{gnatkr} dots may
17835 appear in the name instead of hyphens, but the last dot will always be
17836 taken as the start of an extension. So if @code{gnatkr} is given an argument
17837 such as @file{Hello.World.adb} it will be treated exactly as if the first
17838 period had been a hyphen, and for example krunching to eight characters
17839 gives the result @file{hellworl.adb}.
17841 Note that the result is always all lower case (except on OpenVMS where it is
17842 all upper case). Characters of the other case are folded as required.
17844 @var{length} represents the length of the krunched name. The default
17845 when no argument is given is ^8^39^ characters. A length of zero stands for
17846 unlimited, in other words do not chop except for system files where the
17847 implied crunching length is always eight characters.
17850 The output is the krunched name. The output has an extension only if the
17851 original argument was a file name with an extension.
17853 @node Krunching Method
17854 @section Krunching Method
17857 The initial file name is determined by the name of the unit that the file
17858 contains. The name is formed by taking the full expanded name of the
17859 unit and replacing the separating dots with hyphens and
17860 using ^lowercase^uppercase^
17861 for all letters, except that a hyphen in the second character position is
17862 replaced by a ^tilde^dollar sign^ if the first character is
17863 ^@samp{a}, @samp{i}, @samp{g}, or @samp{s}^@samp{A}, @samp{I}, @samp{G}, or @samp{S}^.
17864 The extension is @code{.ads} for a
17865 spec and @code{.adb} for a body.
17866 Krunching does not affect the extension, but the file name is shortened to
17867 the specified length by following these rules:
17871 The name is divided into segments separated by hyphens, tildes or
17872 underscores and all hyphens, tildes, and underscores are
17873 eliminated. If this leaves the name short enough, we are done.
17876 If the name is too long, the longest segment is located (left-most
17877 if there are two of equal length), and shortened by dropping
17878 its last character. This is repeated until the name is short enough.
17880 As an example, consider the krunching of @*@file{our-strings-wide_fixed.adb}
17881 to fit the name into 8 characters as required by some operating systems.
17884 our-strings-wide_fixed 22
17885 our strings wide fixed 19
17886 our string wide fixed 18
17887 our strin wide fixed 17
17888 our stri wide fixed 16
17889 our stri wide fixe 15
17890 our str wide fixe 14
17891 our str wid fixe 13
17897 Final file name: oustwifi.adb
17901 The file names for all predefined units are always krunched to eight
17902 characters. The krunching of these predefined units uses the following
17903 special prefix replacements:
17907 replaced by @file{^a^A^-}
17910 replaced by @file{^g^G^-}
17913 replaced by @file{^i^I^-}
17916 replaced by @file{^s^S^-}
17919 These system files have a hyphen in the second character position. That
17920 is why normal user files replace such a character with a
17921 ^tilde^dollar sign^, to
17922 avoid confusion with system file names.
17924 As an example of this special rule, consider
17925 @*@file{ada-strings-wide_fixed.adb}, which gets krunched as follows:
17928 ada-strings-wide_fixed 22
17929 a- strings wide fixed 18
17930 a- string wide fixed 17
17931 a- strin wide fixed 16
17932 a- stri wide fixed 15
17933 a- stri wide fixe 14
17934 a- str wide fixe 13
17940 Final file name: a-stwifi.adb
17944 Of course no file shortening algorithm can guarantee uniqueness over all
17945 possible unit names, and if file name krunching is used then it is your
17946 responsibility to ensure that no name clashes occur. The utility
17947 program @code{gnatkr} is supplied for conveniently determining the
17948 krunched name of a file.
17950 @node Examples of gnatkr Usage
17951 @section Examples of @code{gnatkr} Usage
17958 $ gnatkr very_long_unit_name.ads --> velounna.ads
17959 $ gnatkr grandparent-parent-child.ads --> grparchi.ads
17960 $ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads
17961 $ gnatkr grandparent-parent-child --> grparchi
17963 $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
17964 $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads
17967 @node Preprocessing Using gnatprep
17968 @chapter Preprocessing Using @code{gnatprep}
17972 This chapter discusses how to use GNAT's @code{gnatprep} utility for simple
17974 Although designed for use with GNAT, @code{gnatprep} does not depend on any
17975 special GNAT features.
17976 For further discussion of conditional compilation in general, see
17977 @ref{Conditional Compilation}.
17980 * Preprocessing Symbols::
17982 * Switches for gnatprep::
17983 * Form of Definitions File::
17984 * Form of Input Text for gnatprep::
17987 @node Preprocessing Symbols
17988 @section Preprocessing Symbols
17991 Preprocessing symbols are defined in definition files and referred to in
17992 sources to be preprocessed. A Preprocessing symbol is an identifier, following
17993 normal Ada (case-insensitive) rules for its syntax, with the restriction that
17994 all characters need to be in the ASCII set (no accented letters).
17996 @node Using gnatprep
17997 @section Using @code{gnatprep}
18000 To call @code{gnatprep} use
18003 $ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile}
18010 is an optional sequence of switches as described in the next section.
18013 is the full name of the input file, which is an Ada source
18014 file containing preprocessor directives.
18017 is the full name of the output file, which is an Ada source
18018 in standard Ada form. When used with GNAT, this file name will
18019 normally have an ads or adb suffix.
18022 is the full name of a text file containing definitions of
18023 preprocessing symbols to be referenced by the preprocessor. This argument is
18024 optional, and can be replaced by the use of the @option{-D} switch.
18028 @node Switches for gnatprep
18029 @section Switches for @code{gnatprep}
18034 @item ^-b^/BLANK_LINES^
18035 @cindex @option{^-b^/BLANK_LINES^} (@command{gnatprep})
18036 Causes both preprocessor lines and the lines deleted by
18037 preprocessing to be replaced by blank lines in the output source file,
18038 preserving line numbers in the output file.
18040 @item ^-c^/COMMENTS^
18041 @cindex @option{^-c^/COMMENTS^} (@command{gnatprep})
18042 Causes both preprocessor lines and the lines deleted
18043 by preprocessing to be retained in the output source as comments marked
18044 with the special string @code{"--! "}. This option will result in line numbers
18045 being preserved in the output file.
18047 @item ^-C^/REPLACE_IN_COMMENTS^
18048 @cindex @option{^-C^/REPLACE_IN_COMMENTS^} (@command{gnatprep})
18049 Causes comments to be scanned. Normally comments are ignored by gnatprep.
18050 If this option is specified, then comments are scanned and any $symbol
18051 substitutions performed as in program text. This is particularly useful
18052 when structured comments are used (e.g., when writing programs in the
18053 SPARK dialect of Ada). Note that this switch is not available when
18054 doing integrated preprocessing (it would be useless in this context
18055 since comments are ignored by the compiler in any case).
18057 @item ^-Dsymbol=value^/ASSOCIATE="symbol=value"^
18058 @cindex @option{^-D^/ASSOCIATE^} (@command{gnatprep})
18059 Defines a new preprocessing symbol, associated with value. If no value is given
18060 on the command line, then symbol is considered to be @code{True}. This switch
18061 can be used in place of a definition file.
18065 @cindex @option{/REMOVE} (@command{gnatprep})
18066 This is the default setting which causes lines deleted by preprocessing
18067 to be entirely removed from the output file.
18070 @item ^-r^/REFERENCE^
18071 @cindex @option{^-r^/REFERENCE^} (@command{gnatprep})
18072 Causes a @code{Source_Reference} pragma to be generated that
18073 references the original input file, so that error messages will use
18074 the file name of this original file. The use of this switch implies
18075 that preprocessor lines are not to be removed from the file, so its
18076 use will force @option{^-b^/BLANK_LINES^} mode if
18077 @option{^-c^/COMMENTS^}
18078 has not been specified explicitly.
18080 Note that if the file to be preprocessed contains multiple units, then
18081 it will be necessary to @code{gnatchop} the output file from
18082 @code{gnatprep}. If a @code{Source_Reference} pragma is present
18083 in the preprocessed file, it will be respected by
18084 @code{gnatchop ^-r^/REFERENCE^}
18085 so that the final chopped files will correctly refer to the original
18086 input source file for @code{gnatprep}.
18088 @item ^-s^/SYMBOLS^
18089 @cindex @option{^-s^/SYMBOLS^} (@command{gnatprep})
18090 Causes a sorted list of symbol names and values to be
18091 listed on the standard output file.
18093 @item ^-u^/UNDEFINED^
18094 @cindex @option{^-u^/UNDEFINED^} (@command{gnatprep})
18095 Causes undefined symbols to be treated as having the value FALSE in the context
18096 of a preprocessor test. In the absence of this option, an undefined symbol in
18097 a @code{#if} or @code{#elsif} test will be treated as an error.
18103 Note: if neither @option{-b} nor @option{-c} is present,
18104 then preprocessor lines and
18105 deleted lines are completely removed from the output, unless -r is
18106 specified, in which case -b is assumed.
18109 @node Form of Definitions File
18110 @section Form of Definitions File
18113 The definitions file contains lines of the form
18120 where symbol is a preprocessing symbol, and value is one of the following:
18124 Empty, corresponding to a null substitution
18126 A string literal using normal Ada syntax
18128 Any sequence of characters from the set
18129 (letters, digits, period, underline).
18133 Comment lines may also appear in the definitions file, starting with
18134 the usual @code{--},
18135 and comments may be added to the definitions lines.
18137 @node Form of Input Text for gnatprep
18138 @section Form of Input Text for @code{gnatprep}
18141 The input text may contain preprocessor conditional inclusion lines,
18142 as well as general symbol substitution sequences.
18144 The preprocessor conditional inclusion commands have the form
18149 #if @i{expression} @r{[}then@r{]}
18151 #elsif @i{expression} @r{[}then@r{]}
18153 #elsif @i{expression} @r{[}then@r{]}
18164 In this example, @i{expression} is defined by the following grammar:
18166 @i{expression} ::= <symbol>
18167 @i{expression} ::= <symbol> = "<value>"
18168 @i{expression} ::= <symbol> = <symbol>
18169 @i{expression} ::= <symbol> 'Defined
18170 @i{expression} ::= not @i{expression}
18171 @i{expression} ::= @i{expression} and @i{expression}
18172 @i{expression} ::= @i{expression} or @i{expression}
18173 @i{expression} ::= @i{expression} and then @i{expression}
18174 @i{expression} ::= @i{expression} or else @i{expression}
18175 @i{expression} ::= ( @i{expression} )
18178 The following restriction exists: it is not allowed to have "and" or "or"
18179 following "not" in the same expression without parentheses. For example, this
18186 This should be one of the following:
18194 For the first test (@i{expression} ::= <symbol>) the symbol must have
18195 either the value true or false, that is to say the right-hand of the
18196 symbol definition must be one of the (case-insensitive) literals
18197 @code{True} or @code{False}. If the value is true, then the
18198 corresponding lines are included, and if the value is false, they are
18201 The test (@i{expression} ::= <symbol> @code{'Defined}) is true only if
18202 the symbol has been defined in the definition file or by a @option{-D}
18203 switch on the command line. Otherwise, the test is false.
18205 The equality tests are case insensitive, as are all the preprocessor lines.
18207 If the symbol referenced is not defined in the symbol definitions file,
18208 then the effect depends on whether or not switch @option{-u}
18209 is specified. If so, then the symbol is treated as if it had the value
18210 false and the test fails. If this switch is not specified, then
18211 it is an error to reference an undefined symbol. It is also an error to
18212 reference a symbol that is defined with a value other than @code{True}
18215 The use of the @code{not} operator inverts the sense of this logical test.
18216 The @code{not} operator cannot be combined with the @code{or} or @code{and}
18217 operators, without parentheses. For example, "if not X or Y then" is not
18218 allowed, but "if (not X) or Y then" and "if not (X or Y) then" are.
18220 The @code{then} keyword is optional as shown
18222 The @code{#} must be the first non-blank character on a line, but
18223 otherwise the format is free form. Spaces or tabs may appear between
18224 the @code{#} and the keyword. The keywords and the symbols are case
18225 insensitive as in normal Ada code. Comments may be used on a
18226 preprocessor line, but other than that, no other tokens may appear on a
18227 preprocessor line. Any number of @code{elsif} clauses can be present,
18228 including none at all. The @code{else} is optional, as in Ada.
18230 The @code{#} marking the start of a preprocessor line must be the first
18231 non-blank character on the line, i.e., it must be preceded only by
18232 spaces or horizontal tabs.
18234 Symbol substitution outside of preprocessor lines is obtained by using
18242 anywhere within a source line, except in a comment or within a
18243 string literal. The identifier
18244 following the @code{$} must match one of the symbols defined in the symbol
18245 definition file, and the result is to substitute the value of the
18246 symbol in place of @code{$symbol} in the output file.
18248 Note that although the substitution of strings within a string literal
18249 is not possible, it is possible to have a symbol whose defined value is
18250 a string literal. So instead of setting XYZ to @code{hello} and writing:
18253 Header : String := "$XYZ";
18257 you should set XYZ to @code{"hello"} and write:
18260 Header : String := $XYZ;
18264 and then the substitution will occur as desired.
18267 @node The GNAT Run-Time Library Builder gnatlbr
18268 @chapter The GNAT Run-Time Library Builder @code{gnatlbr}
18270 @cindex Library builder
18273 @code{gnatlbr} is a tool for rebuilding the GNAT run time with user
18274 supplied configuration pragmas.
18277 * Running gnatlbr::
18278 * Switches for gnatlbr::
18279 * Examples of gnatlbr Usage::
18282 @node Running gnatlbr
18283 @section Running @code{gnatlbr}
18286 The @code{gnatlbr} command has the form
18289 $ GNAT LIBRARY /@r{[}CREATE@r{|}SET@r{|}DELETE@r{]}=directory @r{[}/CONFIG=file@r{]}
18292 @node Switches for gnatlbr
18293 @section Switches for @code{gnatlbr}
18296 @code{gnatlbr} recognizes the following switches:
18300 @item /CREATE=directory
18301 @cindex @code{/CREATE} (@code{gnatlbr})
18302 Create the new run-time library in the specified directory.
18304 @item /SET=directory
18305 @cindex @code{/SET} (@code{gnatlbr})
18306 Make the library in the specified directory the current run-time library.
18308 @item /DELETE=directory
18309 @cindex @code{/DELETE} (@code{gnatlbr})
18310 Delete the run-time library in the specified directory.
18313 @cindex @code{/CONFIG} (@code{gnatlbr})
18314 With /CREATE: Use the configuration pragmas in the specified file when
18315 building the library.
18317 With /SET: Use the configuration pragmas in the specified file when
18322 @node Examples of gnatlbr Usage
18323 @section Example of @code{gnatlbr} Usage
18326 Contents of VAXFLOAT.ADC:
18327 pragma Float_Representation (VAX_Float);
18329 $ GNAT LIBRARY /CREATE=[.VAXFLOAT] /CONFIG=VAXFLOAT.ADC
18331 GNAT LIBRARY rebuilds the run-time library in directory [.VAXFLOAT]
18336 @node The GNAT Library Browser gnatls
18337 @chapter The GNAT Library Browser @code{gnatls}
18339 @cindex Library browser
18342 @code{gnatls} is a tool that outputs information about compiled
18343 units. It gives the relationship between objects, unit names and source
18344 files. It can also be used to check the source dependencies of a unit
18345 as well as various characteristics.
18347 Note: to invoke @code{gnatls} with a project file, use the @code{gnat}
18348 driver (see @ref{The GNAT Driver and Project Files}).
18352 * Switches for gnatls::
18353 * Examples of gnatls Usage::
18356 @node Running gnatls
18357 @section Running @code{gnatls}
18360 The @code{gnatls} command has the form
18363 $ gnatls switches @var{object_or_ali_file}
18367 The main argument is the list of object or @file{ali} files
18368 (@pxref{The Ada Library Information Files})
18369 for which information is requested.
18371 In normal mode, without additional option, @code{gnatls} produces a
18372 four-column listing. Each line represents information for a specific
18373 object. The first column gives the full path of the object, the second
18374 column gives the name of the principal unit in this object, the third
18375 column gives the status of the source and the fourth column gives the
18376 full path of the source representing this unit.
18377 Here is a simple example of use:
18381 ^./^[]^demo1.o demo1 DIF demo1.adb
18382 ^./^[]^demo2.o demo2 OK demo2.adb
18383 ^./^[]^hello.o h1 OK hello.adb
18384 ^./^[]^instr-child.o instr.child MOK instr-child.adb
18385 ^./^[]^instr.o instr OK instr.adb
18386 ^./^[]^tef.o tef DIF tef.adb
18387 ^./^[]^text_io_example.o text_io_example OK text_io_example.adb
18388 ^./^[]^tgef.o tgef DIF tgef.adb
18392 The first line can be interpreted as follows: the main unit which is
18394 object file @file{demo1.o} is demo1, whose main source is in
18395 @file{demo1.adb}. Furthermore, the version of the source used for the
18396 compilation of demo1 has been modified (DIF). Each source file has a status
18397 qualifier which can be:
18400 @item OK (unchanged)
18401 The version of the source file used for the compilation of the
18402 specified unit corresponds exactly to the actual source file.
18404 @item MOK (slightly modified)
18405 The version of the source file used for the compilation of the
18406 specified unit differs from the actual source file but not enough to
18407 require recompilation. If you use gnatmake with the qualifier
18408 @option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}, a file marked
18409 MOK will not be recompiled.
18411 @item DIF (modified)
18412 No version of the source found on the path corresponds to the source
18413 used to build this object.
18415 @item ??? (file not found)
18416 No source file was found for this unit.
18418 @item HID (hidden, unchanged version not first on PATH)
18419 The version of the source that corresponds exactly to the source used
18420 for compilation has been found on the path but it is hidden by another
18421 version of the same source that has been modified.
18425 @node Switches for gnatls
18426 @section Switches for @code{gnatls}
18429 @code{gnatls} recognizes the following switches:
18433 @cindex @option{--version} @command{gnatls}
18434 Display Copyright and version, then exit disregarding all other options.
18437 @cindex @option{--help} @command{gnatls}
18438 If @option{--version} was not used, display usage, then exit disregarding
18441 @item ^-a^/ALL_UNITS^
18442 @cindex @option{^-a^/ALL_UNITS^} (@code{gnatls})
18443 Consider all units, including those of the predefined Ada library.
18444 Especially useful with @option{^-d^/DEPENDENCIES^}.
18446 @item ^-d^/DEPENDENCIES^
18447 @cindex @option{^-d^/DEPENDENCIES^} (@code{gnatls})
18448 List sources from which specified units depend on.
18450 @item ^-h^/OUTPUT=OPTIONS^
18451 @cindex @option{^-h^/OUTPUT=OPTIONS^} (@code{gnatls})
18452 Output the list of options.
18454 @item ^-o^/OUTPUT=OBJECTS^
18455 @cindex @option{^-o^/OUTPUT=OBJECTS^} (@code{gnatls})
18456 Only output information about object files.
18458 @item ^-s^/OUTPUT=SOURCES^
18459 @cindex @option{^-s^/OUTPUT=SOURCES^} (@code{gnatls})
18460 Only output information about source files.
18462 @item ^-u^/OUTPUT=UNITS^
18463 @cindex @option{^-u^/OUTPUT=UNITS^} (@code{gnatls})
18464 Only output information about compilation units.
18466 @item ^-files^/FILES^=@var{file}
18467 @cindex @option{^-files^/FILES^} (@code{gnatls})
18468 Take as arguments the files listed in text file @var{file}.
18469 Text file @var{file} may contain empty lines that are ignored.
18470 Each nonempty line should contain the name of an existing file.
18471 Several such switches may be specified simultaneously.
18473 @item ^-aO^/OBJECT_SEARCH=^@var{dir}
18474 @itemx ^-aI^/SOURCE_SEARCH=^@var{dir}
18475 @itemx ^-I^/SEARCH=^@var{dir}
18476 @itemx ^-I-^/NOCURRENT_DIRECTORY^
18478 @cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatls})
18479 @cindex @option{^-aI^/SOURCE_SEARCH^} (@code{gnatls})
18480 @cindex @option{^-I^/SEARCH^} (@code{gnatls})
18481 @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatls})
18482 Source path manipulation. Same meaning as the equivalent @command{gnatmake}
18483 flags (@pxref{Switches for gnatmake}).
18485 @item --RTS=@var{rts-path}
18486 @cindex @option{--RTS} (@code{gnatls})
18487 Specifies the default location of the runtime library. Same meaning as the
18488 equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
18490 @item ^-v^/OUTPUT=VERBOSE^
18491 @cindex @option{^-v^/OUTPUT=VERBOSE^} (@code{gnatls})
18492 Verbose mode. Output the complete source, object and project paths. Do not use
18493 the default column layout but instead use long format giving as much as
18494 information possible on each requested units, including special
18495 characteristics such as:
18498 @item Preelaborable
18499 The unit is preelaborable in the Ada sense.
18502 No elaboration code has been produced by the compiler for this unit.
18505 The unit is pure in the Ada sense.
18507 @item Elaborate_Body
18508 The unit contains a pragma Elaborate_Body.
18511 The unit contains a pragma Remote_Types.
18513 @item Shared_Passive
18514 The unit contains a pragma Shared_Passive.
18517 This unit is part of the predefined environment and cannot be modified
18520 @item Remote_Call_Interface
18521 The unit contains a pragma Remote_Call_Interface.
18527 @node Examples of gnatls Usage
18528 @section Example of @code{gnatls} Usage
18532 Example of using the verbose switch. Note how the source and
18533 object paths are affected by the -I switch.
18536 $ gnatls -v -I.. demo1.o
18538 GNATLS 5.03w (20041123-34)
18539 Copyright 1997-2004 Free Software Foundation, Inc.
18541 Source Search Path:
18542 <Current_Directory>
18544 /home/comar/local/adainclude/
18546 Object Search Path:
18547 <Current_Directory>
18549 /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
18551 Project Search Path:
18552 <Current_Directory>
18553 /home/comar/local/lib/gnat/
18558 Kind => subprogram body
18559 Flags => No_Elab_Code
18560 Source => demo1.adb modified
18564 The following is an example of use of the dependency list.
18565 Note the use of the -s switch
18566 which gives a straight list of source files. This can be useful for
18567 building specialized scripts.
18570 $ gnatls -d demo2.o
18571 ./demo2.o demo2 OK demo2.adb
18577 $ gnatls -d -s -a demo1.o
18579 /home/comar/local/adainclude/ada.ads
18580 /home/comar/local/adainclude/a-finali.ads
18581 /home/comar/local/adainclude/a-filico.ads
18582 /home/comar/local/adainclude/a-stream.ads
18583 /home/comar/local/adainclude/a-tags.ads
18586 /home/comar/local/adainclude/gnat.ads
18587 /home/comar/local/adainclude/g-io.ads
18589 /home/comar/local/adainclude/system.ads
18590 /home/comar/local/adainclude/s-exctab.ads
18591 /home/comar/local/adainclude/s-finimp.ads
18592 /home/comar/local/adainclude/s-finroo.ads
18593 /home/comar/local/adainclude/s-secsta.ads
18594 /home/comar/local/adainclude/s-stalib.ads
18595 /home/comar/local/adainclude/s-stoele.ads
18596 /home/comar/local/adainclude/s-stratt.ads
18597 /home/comar/local/adainclude/s-tasoli.ads
18598 /home/comar/local/adainclude/s-unstyp.ads
18599 /home/comar/local/adainclude/unchconv.ads
18605 GNAT LIST /DEPENDENCIES /OUTPUT=SOURCES /ALL_UNITS DEMO1.ADB
18607 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]ada.ads
18608 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-finali.ads
18609 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-filico.ads
18610 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-stream.ads
18611 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-tags.ads
18615 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]gnat.ads
18616 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]g-io.ads
18618 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]system.ads
18619 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-exctab.ads
18620 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finimp.ads
18621 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finroo.ads
18622 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-secsta.ads
18623 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stalib.ads
18624 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stoele.ads
18625 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stratt.ads
18626 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-tasoli.ads
18627 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-unstyp.ads
18628 GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]unchconv.ads
18632 @node Cleaning Up Using gnatclean
18633 @chapter Cleaning Up Using @code{gnatclean}
18635 @cindex Cleaning tool
18638 @code{gnatclean} is a tool that allows the deletion of files produced by the
18639 compiler, binder and linker, including ALI files, object files, tree files,
18640 expanded source files, library files, interface copy source files, binder
18641 generated files and executable files.
18644 * Running gnatclean::
18645 * Switches for gnatclean::
18646 @c * Examples of gnatclean Usage::
18649 @node Running gnatclean
18650 @section Running @code{gnatclean}
18653 The @code{gnatclean} command has the form:
18656 $ gnatclean switches @var{names}
18660 @var{names} is a list of source file names. Suffixes @code{.^ads^ADS^} and
18661 @code{^adb^ADB^} may be omitted. If a project file is specified using switch
18662 @code{^-P^/PROJECT_FILE=^}, then @var{names} may be completely omitted.
18665 In normal mode, @code{gnatclean} delete the files produced by the compiler and,
18666 if switch @code{^-c^/COMPILER_FILES_ONLY^} is not specified, by the binder and
18667 the linker. In informative-only mode, specified by switch
18668 @code{^-n^/NODELETE^}, the list of files that would have been deleted in
18669 normal mode is listed, but no file is actually deleted.
18671 @node Switches for gnatclean
18672 @section Switches for @code{gnatclean}
18675 @code{gnatclean} recognizes the following switches:
18679 @cindex @option{--version} @command{gnatclean}
18680 Display Copyright and version, then exit disregarding all other options.
18683 @cindex @option{--help} @command{gnatclean}
18684 If @option{--version} was not used, display usage, then exit disregarding
18687 @item ^-c^/COMPILER_FILES_ONLY^
18688 @cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean})
18689 Only attempt to delete the files produced by the compiler, not those produced
18690 by the binder or the linker. The files that are not to be deleted are library
18691 files, interface copy files, binder generated files and executable files.
18693 @item ^-D ^/DIRECTORY_OBJECTS=^@var{dir}
18694 @cindex @option{^-D^/DIRECTORY_OBJECTS^} (@code{gnatclean})
18695 Indicate that ALI and object files should normally be found in directory
18698 @item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^
18699 @cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@code{gnatclean})
18700 When using project files, if some errors or warnings are detected during
18701 parsing and verbose mode is not in effect (no use of switch
18702 ^-v^/VERBOSE^), then error lines start with the full path name of the project
18703 file, rather than its simple file name.
18706 @cindex @option{^-h^/HELP^} (@code{gnatclean})
18707 Output a message explaining the usage of @code{^gnatclean^gnatclean^}.
18709 @item ^-n^/NODELETE^
18710 @cindex @option{^-n^/NODELETE^} (@code{gnatclean})
18711 Informative-only mode. Do not delete any files. Output the list of the files
18712 that would have been deleted if this switch was not specified.
18714 @item ^-P^/PROJECT_FILE=^@var{project}
18715 @cindex @option{^-P^/PROJECT_FILE^} (@code{gnatclean})
18716 Use project file @var{project}. Only one such switch can be used.
18717 When cleaning a project file, the files produced by the compilation of the
18718 immediate sources or inherited sources of the project files are to be
18719 deleted. This is not depending on the presence or not of executable names
18720 on the command line.
18723 @cindex @option{^-q^/QUIET^} (@code{gnatclean})
18724 Quiet output. If there are no errors, do not output anything, except in
18725 verbose mode (switch ^-v^/VERBOSE^) or in informative-only mode
18726 (switch ^-n^/NODELETE^).
18728 @item ^-r^/RECURSIVE^
18729 @cindex @option{^-r^/RECURSIVE^} (@code{gnatclean})
18730 When a project file is specified (using switch ^-P^/PROJECT_FILE=^),
18731 clean all imported and extended project files, recursively. If this switch
18732 is not specified, only the files related to the main project file are to be
18733 deleted. This switch has no effect if no project file is specified.
18735 @item ^-v^/VERBOSE^
18736 @cindex @option{^-v^/VERBOSE^} (@code{gnatclean})
18739 @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
18740 @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (@code{gnatclean})
18741 Indicates the verbosity of the parsing of GNAT project files.
18742 @xref{Switches Related to Project Files}.
18744 @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
18745 @cindex @option{^-X^/EXTERNAL_REFERENCE^} (@code{gnatclean})
18746 Indicates that external variable @var{name} has the value @var{value}.
18747 The Project Manager will use this value for occurrences of
18748 @code{external(name)} when parsing the project file.
18749 @xref{Switches Related to Project Files}.
18751 @item ^-aO^/OBJECT_SEARCH=^@var{dir}
18752 @cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatclean})
18753 When searching for ALI and object files, look in directory
18756 @item ^-I^/SEARCH=^@var{dir}
18757 @cindex @option{^-I^/SEARCH^} (@code{gnatclean})
18758 Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir}}.
18760 @item ^-I-^/NOCURRENT_DIRECTORY^
18761 @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatclean})
18762 @cindex Source files, suppressing search
18763 Do not look for ALI or object files in the directory
18764 where @code{gnatclean} was invoked.
18768 @c @node Examples of gnatclean Usage
18769 @c @section Examples of @code{gnatclean} Usage
18772 @node GNAT and Libraries
18773 @chapter GNAT and Libraries
18774 @cindex Library, building, installing, using
18777 This chapter describes how to build and use libraries with GNAT, and also shows
18778 how to recompile the GNAT run-time library. You should be familiar with the
18779 Project Manager facility (@pxref{GNAT Project Manager}) before reading this
18783 * Introduction to Libraries in GNAT::
18784 * General Ada Libraries::
18785 * Stand-alone Ada Libraries::
18786 * Rebuilding the GNAT Run-Time Library::
18789 @node Introduction to Libraries in GNAT
18790 @section Introduction to Libraries in GNAT
18793 A library is, conceptually, a collection of objects which does not have its
18794 own main thread of execution, but rather provides certain services to the
18795 applications that use it. A library can be either statically linked with the
18796 application, in which case its code is directly included in the application,
18797 or, on platforms that support it, be dynamically linked, in which case
18798 its code is shared by all applications making use of this library.
18800 GNAT supports both types of libraries.
18801 In the static case, the compiled code can be provided in different ways. The
18802 simplest approach is to provide directly the set of objects resulting from
18803 compilation of the library source files. Alternatively, you can group the
18804 objects into an archive using whatever commands are provided by the operating
18805 system. For the latter case, the objects are grouped into a shared library.
18807 In the GNAT environment, a library has three types of components:
18813 @xref{The Ada Library Information Files}.
18815 Object files, an archive or a shared library.
18819 A GNAT library may expose all its source files, which is useful for
18820 documentation purposes. Alternatively, it may expose only the units needed by
18821 an external user to make use of the library. That is to say, the specs
18822 reflecting the library services along with all the units needed to compile
18823 those specs, which can include generic bodies or any body implementing an
18824 inlined routine. In the case of @emph{stand-alone libraries} those exposed
18825 units are called @emph{interface units} (@pxref{Stand-alone Ada Libraries}).
18827 All compilation units comprising an application, including those in a library,
18828 need to be elaborated in an order partially defined by Ada's semantics. GNAT
18829 computes the elaboration order from the @file{ALI} files and this is why they
18830 constitute a mandatory part of GNAT libraries. Except in the case of
18831 @emph{stand-alone libraries}, where a specific library elaboration routine is
18832 produced independently of the application(s) using the library.
18834 @node General Ada Libraries
18835 @section General Ada Libraries
18838 * Building a library::
18839 * Installing a library::
18840 * Using a library::
18843 @node Building a library
18844 @subsection Building a library
18847 The easiest way to build a library is to use the Project Manager,
18848 which supports a special type of project called a @emph{Library Project}
18849 (@pxref{Library Projects}).
18851 A project is considered a library project, when two project-level attributes
18852 are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to
18853 control different aspects of library configuration, additional optional
18854 project-level attributes can be specified:
18857 This attribute controls whether the library is to be static or dynamic
18859 @item Library_Version
18860 This attribute specifies the library version; this value is used
18861 during dynamic linking of shared libraries to determine if the currently
18862 installed versions of the binaries are compatible.
18864 @item Library_Options
18866 These attributes specify additional low-level options to be used during
18867 library generation, and redefine the actual application used to generate
18872 The GNAT Project Manager takes full care of the library maintenance task,
18873 including recompilation of the source files for which objects do not exist
18874 or are not up to date, assembly of the library archive, and installation of
18875 the library (i.e., copying associated source, object and @file{ALI} files
18876 to the specified location).
18878 Here is a simple library project file:
18879 @smallexample @c ada
18881 for Source_Dirs use ("src1", "src2");
18882 for Object_Dir use "obj";
18883 for Library_Name use "mylib";
18884 for Library_Dir use "lib";
18885 for Library_Kind use "dynamic";
18890 and the compilation command to build and install the library:
18892 @smallexample @c ada
18893 $ gnatmake -Pmy_lib
18897 It is not entirely trivial to perform manually all the steps required to
18898 produce a library. We recommend that you use the GNAT Project Manager
18899 for this task. In special cases where this is not desired, the necessary
18900 steps are discussed below.
18902 There are various possibilities for compiling the units that make up the
18903 library: for example with a Makefile (@pxref{Using the GNU make Utility}) or
18904 with a conventional script. For simple libraries, it is also possible to create
18905 a dummy main program which depends upon all the packages that comprise the
18906 interface of the library. This dummy main program can then be given to
18907 @command{gnatmake}, which will ensure that all necessary objects are built.
18909 After this task is accomplished, you should follow the standard procedure
18910 of the underlying operating system to produce the static or shared library.
18912 Here is an example of such a dummy program:
18913 @smallexample @c ada
18915 with My_Lib.Service1;
18916 with My_Lib.Service2;
18917 with My_Lib.Service3;
18918 procedure My_Lib_Dummy is
18926 Here are the generic commands that will build an archive or a shared library.
18929 # compiling the library
18930 $ gnatmake -c my_lib_dummy.adb
18932 # we don't need the dummy object itself
18933 $ rm my_lib_dummy.o my_lib_dummy.ali
18935 # create an archive with the remaining objects
18936 $ ar rc libmy_lib.a *.o
18937 # some systems may require "ranlib" to be run as well
18939 # or create a shared library
18940 $ gcc -shared -o libmy_lib.so *.o
18941 # some systems may require the code to have been compiled with -fPIC
18943 # remove the object files that are now in the library
18946 # Make the ALI files read-only so that gnatmake will not try to
18947 # regenerate the objects that are in the library
18952 Please note that the library must have a name of the form @file{lib@var{xxx}.a}
18953 or @file{lib@var{xxx}.so} (or @file{lib@var{xxx}.dll} on Windows) in order to
18954 be accessed by the directive @option{-l@var{xxx}} at link time.
18956 @node Installing a library
18957 @subsection Installing a library
18958 @cindex @code{ADA_PROJECT_PATH}
18961 If you use project files, library installation is part of the library build
18962 process. Thus no further action is needed in order to make use of the
18963 libraries that are built as part of the general application build. A usable
18964 version of the library is installed in the directory specified by the
18965 @code{Library_Dir} attribute of the library project file.
18967 You may want to install a library in a context different from where the library
18968 is built. This situation arises with third party suppliers, who may want
18969 to distribute a library in binary form where the user is not expected to be
18970 able to recompile the library. The simplest option in this case is to provide
18971 a project file slightly different from the one used to build the library, by
18972 using the @code{externally_built} attribute. For instance, the project
18973 file used to build the library in the previous section can be changed into the
18974 following one when the library is installed:
18976 @smallexample @c projectfile
18978 for Source_Dirs use ("src1", "src2");
18979 for Library_Name use "mylib";
18980 for Library_Dir use "lib";
18981 for Library_Kind use "dynamic";
18982 for Externally_Built use "true";
18987 This project file assumes that the directories @file{src1},
18988 @file{src2}, and @file{lib} exist in
18989 the directory containing the project file. The @code{externally_built}
18990 attribute makes it clear to the GNAT builder that it should not attempt to
18991 recompile any of the units from this library. It allows the library provider to
18992 restrict the source set to the minimum necessary for clients to make use of the
18993 library as described in the first section of this chapter. It is the
18994 responsibility of the library provider to install the necessary sources, ALI
18995 files and libraries in the directories mentioned in the project file. For
18996 convenience, the user's library project file should be installed in a location
18997 that will be searched automatically by the GNAT
18998 builder. These are the directories referenced in the @env{ADA_PROJECT_PATH}
18999 environment variable (@pxref{Importing Projects}), and also the default GNAT
19000 library location that can be queried with @command{gnatls -v} and is usually of
19001 the form $gnat_install_root/lib/gnat.
19003 When project files are not an option, it is also possible, but not recommended,
19004 to install the library so that the sources needed to use the library are on the
19005 Ada source path and the ALI files & libraries be on the Ada Object path (see
19006 @ref{Search Paths and the Run-Time Library (RTL)}. Alternatively, the system
19007 administrator can place general-purpose libraries in the default compiler
19008 paths, by specifying the libraries' location in the configuration files
19009 @file{ada_source_path} and @file{ada_object_path}. These configuration files
19010 must be located in the GNAT installation tree at the same place as the gcc spec
19011 file. The location of the gcc spec file can be determined as follows:
19017 The configuration files mentioned above have a simple format: each line
19018 must contain one unique directory name.
19019 Those names are added to the corresponding path
19020 in their order of appearance in the file. The names can be either absolute
19021 or relative; in the latter case, they are relative to where theses files
19024 The files @file{ada_source_path} and @file{ada_object_path} might not be
19026 GNAT installation, in which case, GNAT will look for its run-time library in
19027 the directories @file{adainclude} (for the sources) and @file{adalib} (for the
19028 objects and @file{ALI} files). When the files exist, the compiler does not
19029 look in @file{adainclude} and @file{adalib}, and thus the
19030 @file{ada_source_path} file
19031 must contain the location for the GNAT run-time sources (which can simply
19032 be @file{adainclude}). In the same way, the @file{ada_object_path} file must
19033 contain the location for the GNAT run-time objects (which can simply
19036 You can also specify a new default path to the run-time library at compilation
19037 time with the switch @option{--RTS=rts-path}. You can thus choose / change
19038 the run-time library you want your program to be compiled with. This switch is
19039 recognized by @command{gcc}, @command{gnatmake}, @command{gnatbind},
19040 @command{gnatls}, @command{gnatfind} and @command{gnatxref}.
19042 It is possible to install a library before or after the standard GNAT
19043 library, by reordering the lines in the configuration files. In general, a
19044 library must be installed before the GNAT library if it redefines
19047 @node Using a library
19048 @subsection Using a library
19050 @noindent Once again, the project facility greatly simplifies the use of
19051 libraries. In this context, using a library is just a matter of adding a
19052 @code{with} clause in the user project. For instance, to make use of the
19053 library @code{My_Lib} shown in examples in earlier sections, you can
19056 @smallexample @c projectfile
19063 Even if you have a third-party, non-Ada library, you can still use GNAT's
19064 Project Manager facility to provide a wrapper for it. For example, the
19065 following project, when @code{with}ed by your main project, will link with the
19066 third-party library @file{liba.a}:
19068 @smallexample @c projectfile
19071 for Externally_Built use "true";
19072 for Source_Files use ();
19073 for Library_Dir use "lib";
19074 for Library_Name use "a";
19075 for Library_Kind use "static";
19079 This is an alternative to the use of @code{pragma Linker_Options}. It is
19080 especially interesting in the context of systems with several interdependent
19081 static libraries where finding a proper linker order is not easy and best be
19082 left to the tools having visibility over project dependence information.
19085 In order to use an Ada library manually, you need to make sure that this
19086 library is on both your source and object path
19087 (see @ref{Search Paths and the Run-Time Library (RTL)}
19088 and @ref{Search Paths for gnatbind}). Furthermore, when the objects are grouped
19089 in an archive or a shared library, you need to specify the desired
19090 library at link time.
19092 For example, you can use the library @file{mylib} installed in
19093 @file{/dir/my_lib_src} and @file{/dir/my_lib_obj} with the following commands:
19096 $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \
19101 This can be expressed more simply:
19106 when the following conditions are met:
19109 @file{/dir/my_lib_src} has been added by the user to the environment
19110 variable @env{ADA_INCLUDE_PATH}, or by the administrator to the file
19111 @file{ada_source_path}
19113 @file{/dir/my_lib_obj} has been added by the user to the environment
19114 variable @env{ADA_OBJECTS_PATH}, or by the administrator to the file
19115 @file{ada_object_path}
19117 a pragma @code{Linker_Options} has been added to one of the sources.
19120 @smallexample @c ada
19121 pragma Linker_Options ("-lmy_lib");
19125 @node Stand-alone Ada Libraries
19126 @section Stand-alone Ada Libraries
19127 @cindex Stand-alone library, building, using
19130 * Introduction to Stand-alone Libraries::
19131 * Building a Stand-alone Library::
19132 * Creating a Stand-alone Library to be used in a non-Ada context::
19133 * Restrictions in Stand-alone Libraries::
19136 @node Introduction to Stand-alone Libraries
19137 @subsection Introduction to Stand-alone Libraries
19140 A Stand-alone Library (abbreviated ``SAL'') is a library that contains the
19142 elaborate the Ada units that are included in the library. In contrast with
19143 an ordinary library, which consists of all sources, objects and @file{ALI}
19145 library, a SAL may specify a restricted subset of compilation units
19146 to serve as a library interface. In this case, the fully
19147 self-sufficient set of files will normally consist of an objects
19148 archive, the sources of interface units' specs, and the @file{ALI}
19149 files of interface units.
19150 If an interface spec contains a generic unit or an inlined subprogram,
19152 source must also be provided; if the units that must be provided in the source
19153 form depend on other units, the source and @file{ALI} files of those must
19156 The main purpose of a SAL is to minimize the recompilation overhead of client
19157 applications when a new version of the library is installed. Specifically,
19158 if the interface sources have not changed, client applications do not need to
19159 be recompiled. If, furthermore, a SAL is provided in the shared form and its
19160 version, controlled by @code{Library_Version} attribute, is not changed,
19161 then the clients do not need to be relinked.
19163 SALs also allow the library providers to minimize the amount of library source
19164 text exposed to the clients. Such ``information hiding'' might be useful or
19165 necessary for various reasons.
19167 Stand-alone libraries are also well suited to be used in an executable whose
19168 main routine is not written in Ada.
19170 @node Building a Stand-alone Library
19171 @subsection Building a Stand-alone Library
19174 GNAT's Project facility provides a simple way of building and installing
19175 stand-alone libraries; see @ref{Stand-alone Library Projects}.
19176 To be a Stand-alone Library Project, in addition to the two attributes
19177 that make a project a Library Project (@code{Library_Name} and
19178 @code{Library_Dir}; see @ref{Library Projects}), the attribute
19179 @code{Library_Interface} must be defined. For example:
19181 @smallexample @c projectfile
19183 for Library_Dir use "lib_dir";
19184 for Library_Name use "dummy";
19185 for Library_Interface use ("int1", "int1.child");
19190 Attribute @code{Library_Interface} has a non-empty string list value,
19191 each string in the list designating a unit contained in an immediate source
19192 of the project file.
19194 When a Stand-alone Library is built, first the binder is invoked to build
19195 a package whose name depends on the library name
19196 (@file{^b~dummy.ads/b^B$DUMMY.ADS/B^} in the example above).
19197 This binder-generated package includes initialization and
19198 finalization procedures whose
19199 names depend on the library name (@code{dummyinit} and @code{dummyfinal}
19201 above). The object corresponding to this package is included in the library.
19203 You must ensure timely (e.g., prior to any use of interfaces in the SAL)
19204 calling of these procedures if a static SAL is built, or if a shared SAL
19206 with the project-level attribute @code{Library_Auto_Init} set to
19209 For a Stand-Alone Library, only the @file{ALI} files of the Interface Units
19210 (those that are listed in attribute @code{Library_Interface}) are copied to
19211 the Library Directory. As a consequence, only the Interface Units may be
19212 imported from Ada units outside of the library. If other units are imported,
19213 the binding phase will fail.
19215 The attribute @code{Library_Src_Dir} may be specified for a
19216 Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
19217 single string value. Its value must be the path (absolute or relative to the
19218 project directory) of an existing directory. This directory cannot be the
19219 object directory or one of the source directories, but it can be the same as
19220 the library directory. The sources of the Interface
19221 Units of the library that are needed by an Ada client of the library will be
19222 copied to the designated directory, called the Interface Copy directory.
19223 These sources include the specs of the Interface Units, but they may also
19224 include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
19225 are used, or when there is a generic unit in the spec. Before the sources
19226 are copied to the Interface Copy directory, an attempt is made to delete all
19227 files in the Interface Copy directory.
19229 Building stand-alone libraries by hand is somewhat tedious, but for those
19230 occasions when it is necessary here are the steps that you need to perform:
19233 Compile all library sources.
19236 Invoke the binder with the switch @option{-n} (No Ada main program),
19237 with all the @file{ALI} files of the interfaces, and
19238 with the switch @option{-L} to give specific names to the @code{init}
19239 and @code{final} procedures. For example:
19241 gnatbind -n int1.ali int2.ali -Lsal1
19245 Compile the binder generated file:
19251 Link the dynamic library with all the necessary object files,
19252 indicating to the linker the names of the @code{init} (and possibly
19253 @code{final}) procedures for automatic initialization (and finalization).
19254 The built library should be placed in a directory different from
19255 the object directory.
19258 Copy the @code{ALI} files of the interface to the library directory,
19259 add in this copy an indication that it is an interface to a SAL
19260 (i.e., add a word @option{SL} on the line in the @file{ALI} file that starts
19261 with letter ``P'') and make the modified copy of the @file{ALI} file
19266 Using SALs is not different from using other libraries
19267 (see @ref{Using a library}).
19269 @node Creating a Stand-alone Library to be used in a non-Ada context
19270 @subsection Creating a Stand-alone Library to be used in a non-Ada context
19273 It is easy to adapt the SAL build procedure discussed above for use of a SAL in
19276 The only extra step required is to ensure that library interface subprograms
19277 are compatible with the main program, by means of @code{pragma Export}
19278 or @code{pragma Convention}.
19280 Here is an example of simple library interface for use with C main program:
19282 @smallexample @c ada
19283 package Interface is
19285 procedure Do_Something;
19286 pragma Export (C, Do_Something, "do_something");
19288 procedure Do_Something_Else;
19289 pragma Export (C, Do_Something_Else, "do_something_else");
19295 On the foreign language side, you must provide a ``foreign'' view of the
19296 library interface; remember that it should contain elaboration routines in
19297 addition to interface subprograms.
19299 The example below shows the content of @code{mylib_interface.h} (note
19300 that there is no rule for the naming of this file, any name can be used)
19302 /* the library elaboration procedure */
19303 extern void mylibinit (void);
19305 /* the library finalization procedure */
19306 extern void mylibfinal (void);
19308 /* the interface exported by the library */
19309 extern void do_something (void);
19310 extern void do_something_else (void);
19314 Libraries built as explained above can be used from any program, provided
19315 that the elaboration procedures (named @code{mylibinit} in the previous
19316 example) are called before the library services are used. Any number of
19317 libraries can be used simultaneously, as long as the elaboration
19318 procedure of each library is called.
19320 Below is an example of a C program that uses the @code{mylib} library.
19323 #include "mylib_interface.h"
19328 /* First, elaborate the library before using it */
19331 /* Main program, using the library exported entities */
19333 do_something_else ();
19335 /* Library finalization at the end of the program */
19342 Note that invoking any library finalization procedure generated by
19343 @code{gnatbind} shuts down the Ada run-time environment.
19345 finalization of all Ada libraries must be performed at the end of the program.
19346 No call to these libraries or to the Ada run-time library should be made
19347 after the finalization phase.
19349 @node Restrictions in Stand-alone Libraries
19350 @subsection Restrictions in Stand-alone Libraries
19353 The pragmas listed below should be used with caution inside libraries,
19354 as they can create incompatibilities with other Ada libraries:
19356 @item pragma @code{Locking_Policy}
19357 @item pragma @code{Queuing_Policy}
19358 @item pragma @code{Task_Dispatching_Policy}
19359 @item pragma @code{Unreserve_All_Interrupts}
19363 When using a library that contains such pragmas, the user must make sure
19364 that all libraries use the same pragmas with the same values. Otherwise,
19365 @code{Program_Error} will
19366 be raised during the elaboration of the conflicting
19367 libraries. The usage of these pragmas and its consequences for the user
19368 should therefore be well documented.
19370 Similarly, the traceback in the exception occurrence mechanism should be
19371 enabled or disabled in a consistent manner across all libraries.
19372 Otherwise, Program_Error will be raised during the elaboration of the
19373 conflicting libraries.
19375 If the @code{Version} or @code{Body_Version}
19376 attributes are used inside a library, then you need to
19377 perform a @code{gnatbind} step that specifies all @file{ALI} files in all
19378 libraries, so that version identifiers can be properly computed.
19379 In practice these attributes are rarely used, so this is unlikely
19380 to be a consideration.
19382 @node Rebuilding the GNAT Run-Time Library
19383 @section Rebuilding the GNAT Run-Time Library
19384 @cindex GNAT Run-Time Library, rebuilding
19385 @cindex Building the GNAT Run-Time Library
19386 @cindex Rebuilding the GNAT Run-Time Library
19387 @cindex Run-Time Library, rebuilding
19390 It may be useful to recompile the GNAT library in various contexts, the
19391 most important one being the use of partition-wide configuration pragmas
19392 such as @code{Normalize_Scalars}. A special Makefile called
19393 @code{Makefile.adalib} is provided to that effect and can be found in
19394 the directory containing the GNAT library. The location of this
19395 directory depends on the way the GNAT environment has been installed and can
19396 be determined by means of the command:
19403 The last entry in the object search path usually contains the
19404 gnat library. This Makefile contains its own documentation and in
19405 particular the set of instructions needed to rebuild a new library and
19408 @node Using the GNU make Utility
19409 @chapter Using the GNU @code{make} Utility
19413 This chapter offers some examples of makefiles that solve specific
19414 problems. It does not explain how to write a makefile (@pxref{Top,, GNU
19415 make, make, GNU @code{make}}), nor does it try to replace the
19416 @command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}).
19418 All the examples in this section are specific to the GNU version of
19419 make. Although @command{make} is a standard utility, and the basic language
19420 is the same, these examples use some advanced features found only in
19424 * Using gnatmake in a Makefile::
19425 * Automatically Creating a List of Directories::
19426 * Generating the Command Line Switches::
19427 * Overcoming Command Line Length Limits::
19430 @node Using gnatmake in a Makefile
19431 @section Using gnatmake in a Makefile
19436 Complex project organizations can be handled in a very powerful way by
19437 using GNU make combined with gnatmake. For instance, here is a Makefile
19438 which allows you to build each subsystem of a big project into a separate
19439 shared library. Such a makefile allows you to significantly reduce the link
19440 time of very big applications while maintaining full coherence at
19441 each step of the build process.
19443 The list of dependencies are handled automatically by
19444 @command{gnatmake}. The Makefile is simply used to call gnatmake in each of
19445 the appropriate directories.
19447 Note that you should also read the example on how to automatically
19448 create the list of directories
19449 (@pxref{Automatically Creating a List of Directories})
19450 which might help you in case your project has a lot of subdirectories.
19455 @font@heightrm=cmr8
19458 ## This Makefile is intended to be used with the following directory
19460 ## - The sources are split into a series of csc (computer software components)
19461 ## Each of these csc is put in its own directory.
19462 ## Their name are referenced by the directory names.
19463 ## They will be compiled into shared library (although this would also work
19464 ## with static libraries
19465 ## - The main program (and possibly other packages that do not belong to any
19466 ## csc is put in the top level directory (where the Makefile is).
19467 ## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
19468 ## \_ second_csc (sources) __ lib (will contain the library)
19470 ## Although this Makefile is build for shared library, it is easy to modify
19471 ## to build partial link objects instead (modify the lines with -shared and
19474 ## With this makefile, you can change any file in the system or add any new
19475 ## file, and everything will be recompiled correctly (only the relevant shared
19476 ## objects will be recompiled, and the main program will be re-linked).
19478 # The list of computer software component for your project. This might be
19479 # generated automatically.
19482 # Name of the main program (no extension)
19485 # If we need to build objects with -fPIC, uncomment the following line
19488 # The following variable should give the directory containing libgnat.so
19489 # You can get this directory through 'gnatls -v'. This is usually the last
19490 # directory in the Object_Path.
19493 # The directories for the libraries
19494 # (This macro expands the list of CSC to the list of shared libraries, you
19495 # could simply use the expanded form:
19496 # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
19497 LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@}
19499 $@{MAIN@}: objects $@{LIB_DIR@}
19500 gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared
19501 gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@}
19504 # recompile the sources
19505 gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@}
19507 # Note: In a future version of GNAT, the following commands will be simplified
19508 # by a new tool, gnatmlib
19510 mkdir -p $@{dir $@@ @}
19511 cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
19512 cd $@{dir $@@ @} && cp -f ../*.ali .
19514 # The dependencies for the modules
19515 # Note that we have to force the expansion of *.o, since in some cases
19516 # make won't be able to do it itself.
19517 aa/lib/libaa.so: $@{wildcard aa/*.o@}
19518 bb/lib/libbb.so: $@{wildcard bb/*.o@}
19519 cc/lib/libcc.so: $@{wildcard cc/*.o@}
19521 # Make sure all of the shared libraries are in the path before starting the
19524 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@}
19527 $@{RM@} -rf $@{CSC_LIST:%=%/lib@}
19528 $@{RM@} $@{CSC_LIST:%=%/*.ali@}
19529 $@{RM@} $@{CSC_LIST:%=%/*.o@}
19530 $@{RM@} *.o *.ali $@{MAIN@}
19533 @node Automatically Creating a List of Directories
19534 @section Automatically Creating a List of Directories
19537 In most makefiles, you will have to specify a list of directories, and
19538 store it in a variable. For small projects, it is often easier to
19539 specify each of them by hand, since you then have full control over what
19540 is the proper order for these directories, which ones should be
19543 However, in larger projects, which might involve hundreds of
19544 subdirectories, it might be more convenient to generate this list
19547 The example below presents two methods. The first one, although less
19548 general, gives you more control over the list. It involves wildcard
19549 characters, that are automatically expanded by @command{make}. Its
19550 shortcoming is that you need to explicitly specify some of the
19551 organization of your project, such as for instance the directory tree
19552 depth, whether some directories are found in a separate tree, @enddots{}
19554 The second method is the most general one. It requires an external
19555 program, called @command{find}, which is standard on all Unix systems. All
19556 the directories found under a given root directory will be added to the
19562 @font@heightrm=cmr8
19565 # The examples below are based on the following directory hierarchy:
19566 # All the directories can contain any number of files
19567 # ROOT_DIRECTORY -> a -> aa -> aaa
19570 # -> b -> ba -> baa
19573 # This Makefile creates a variable called DIRS, that can be reused any time
19574 # you need this list (see the other examples in this section)
19576 # The root of your project's directory hierarchy
19580 # First method: specify explicitly the list of directories
19581 # This allows you to specify any subset of all the directories you need.
19584 DIRS := a/aa/ a/ab/ b/ba/
19587 # Second method: use wildcards
19588 # Note that the argument(s) to wildcard below should end with a '/'.
19589 # Since wildcards also return file names, we have to filter them out
19590 # to avoid duplicate directory names.
19591 # We thus use make's @code{dir} and @code{sort} functions.
19592 # It sets DIRs to the following value (note that the directories aaa and baa
19593 # are not given, unless you change the arguments to wildcard).
19594 # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
19597 DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/
19598 $@{ROOT_DIRECTORY@}/*/*/@}@}@}
19601 # Third method: use an external program
19602 # This command is much faster if run on local disks, avoiding NFS slowdowns.
19603 # This is the most complete command: it sets DIRs to the following value:
19604 # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
19607 DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@}
19611 @node Generating the Command Line Switches
19612 @section Generating the Command Line Switches
19615 Once you have created the list of directories as explained in the
19616 previous section (@pxref{Automatically Creating a List of Directories}),
19617 you can easily generate the command line arguments to pass to gnatmake.
19619 For the sake of completeness, this example assumes that the source path
19620 is not the same as the object path, and that you have two separate lists
19624 # see "Automatically creating a list of directories" to create
19629 GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@}
19630 GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@}
19633 gnatmake $@{GNATMAKE_SWITCHES@} main_unit
19636 @node Overcoming Command Line Length Limits
19637 @section Overcoming Command Line Length Limits
19640 One problem that might be encountered on big projects is that many
19641 operating systems limit the length of the command line. It is thus hard to give
19642 gnatmake the list of source and object directories.
19644 This example shows how you can set up environment variables, which will
19645 make @command{gnatmake} behave exactly as if the directories had been
19646 specified on the command line, but have a much higher length limit (or
19647 even none on most systems).
19649 It assumes that you have created a list of directories in your Makefile,
19650 using one of the methods presented in
19651 @ref{Automatically Creating a List of Directories}.
19652 For the sake of completeness, we assume that the object
19653 path (where the ALI files are found) is different from the sources patch.
19655 Note a small trick in the Makefile below: for efficiency reasons, we
19656 create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
19657 expanded immediately by @code{make}. This way we overcome the standard
19658 make behavior which is to expand the variables only when they are
19661 On Windows, if you are using the standard Windows command shell, you must
19662 replace colons with semicolons in the assignments to these variables.
19667 @font@heightrm=cmr8
19670 # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH.
19671 # This is the same thing as putting the -I arguments on the command line.
19672 # (the equivalent of using -aI on the command line would be to define
19673 # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECT_PATH).
19674 # You can of course have different values for these variables.
19676 # Note also that we need to keep the previous values of these variables, since
19677 # they might have been set before running 'make' to specify where the GNAT
19678 # library is installed.
19680 # see "Automatically creating a list of directories" to create these
19686 space:=$@{empty@} $@{empty@}
19687 SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@}
19688 OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@}
19689 ADA_INCLUDE_PATH += $@{SOURCE_LIST@}
19690 ADA_OBJECT_PATH += $@{OBJECT_LIST@}
19691 export ADA_INCLUDE_PATH
19692 export ADA_OBJECT_PATH
19699 @node Memory Management Issues
19700 @chapter Memory Management Issues
19703 This chapter describes some useful memory pools provided in the GNAT library
19704 and in particular the GNAT Debug Pool facility, which can be used to detect
19705 incorrect uses of access values (including ``dangling references'').
19707 It also describes the @command{gnatmem} tool, which can be used to track down
19712 * Some Useful Memory Pools::
19713 * The GNAT Debug Pool Facility::
19715 * The gnatmem Tool::
19719 @node Some Useful Memory Pools
19720 @section Some Useful Memory Pools
19721 @findex Memory Pool
19722 @cindex storage, pool
19725 The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool
19726 storage pool. Allocations use the standard system call @code{malloc} while
19727 deallocations use the standard system call @code{free}. No reclamation is
19728 performed when the pool goes out of scope. For performance reasons, the
19729 standard default Ada allocators/deallocators do not use any explicit storage
19730 pools but if they did, they could use this storage pool without any change in
19731 behavior. That is why this storage pool is used when the user
19732 manages to make the default implicit allocator explicit as in this example:
19733 @smallexample @c ada
19734 type T1 is access Something;
19735 -- no Storage pool is defined for T2
19736 type T2 is access Something_Else;
19737 for T2'Storage_Pool use T1'Storage_Pool;
19738 -- the above is equivalent to
19739 for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object;
19743 The @code{System.Pool_Local} package offers the Unbounded_Reclaim_Pool storage
19744 pool. The allocation strategy is similar to @code{Pool_Local}'s
19745 except that the all
19746 storage allocated with this pool is reclaimed when the pool object goes out of
19747 scope. This pool provides a explicit mechanism similar to the implicit one
19748 provided by several Ada 83 compilers for allocations performed through a local
19749 access type and whose purpose was to reclaim memory when exiting the
19750 scope of a given local access. As an example, the following program does not
19751 leak memory even though it does not perform explicit deallocation:
19753 @smallexample @c ada
19754 with System.Pool_Local;
19755 procedure Pooloc1 is
19756 procedure Internal is
19757 type A is access Integer;
19758 X : System.Pool_Local.Unbounded_Reclaim_Pool;
19759 for A'Storage_Pool use X;
19762 for I in 1 .. 50 loop
19767 for I in 1 .. 100 loop
19774 The @code{System.Pool_Size} package implements the Stack_Bounded_Pool used when
19775 @code{Storage_Size} is specified for an access type.
19776 The whole storage for the pool is
19777 allocated at once, usually on the stack at the point where the access type is
19778 elaborated. It is automatically reclaimed when exiting the scope where the
19779 access type is defined. This package is not intended to be used directly by the
19780 user and it is implicitly used for each such declaration:
19782 @smallexample @c ada
19783 type T1 is access Something;
19784 for T1'Storage_Size use 10_000;
19787 @node The GNAT Debug Pool Facility
19788 @section The GNAT Debug Pool Facility
19790 @cindex storage, pool, memory corruption
19793 The use of unchecked deallocation and unchecked conversion can easily
19794 lead to incorrect memory references. The problems generated by such
19795 references are usually difficult to tackle because the symptoms can be
19796 very remote from the origin of the problem. In such cases, it is
19797 very helpful to detect the problem as early as possible. This is the
19798 purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}.
19800 In order to use the GNAT specific debugging pool, the user must
19801 associate a debug pool object with each of the access types that may be
19802 related to suspected memory problems. See Ada Reference Manual 13.11.
19803 @smallexample @c ada
19804 type Ptr is access Some_Type;
19805 Pool : GNAT.Debug_Pools.Debug_Pool;
19806 for Ptr'Storage_Pool use Pool;
19810 @code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of
19811 pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools,
19812 allow the user to redefine allocation and deallocation strategies. They
19813 also provide a checkpoint for each dereference, through the use of
19814 the primitive operation @code{Dereference} which is implicitly called at
19815 each dereference of an access value.
19817 Once an access type has been associated with a debug pool, operations on
19818 values of the type may raise four distinct exceptions,
19819 which correspond to four potential kinds of memory corruption:
19822 @code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
19824 @code{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
19826 @code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
19828 @code{GNAT.Debug_Pools.Freeing_Deallocated_Storage }
19832 For types associated with a Debug_Pool, dynamic allocation is performed using
19833 the standard GNAT allocation routine. References to all allocated chunks of
19834 memory are kept in an internal dictionary. Several deallocation strategies are
19835 provided, whereupon the user can choose to release the memory to the system,
19836 keep it allocated for further invalid access checks, or fill it with an easily
19837 recognizable pattern for debug sessions. The memory pattern is the old IBM
19838 hexadecimal convention: @code{16#DEADBEEF#}.
19840 See the documentation in the file g-debpoo.ads for more information on the
19841 various strategies.
19843 Upon each dereference, a check is made that the access value denotes a
19844 properly allocated memory location. Here is a complete example of use of
19845 @code{Debug_Pools}, that includes typical instances of memory corruption:
19846 @smallexample @c ada
19850 with Gnat.Io; use Gnat.Io;
19851 with Unchecked_Deallocation;
19852 with Unchecked_Conversion;
19853 with GNAT.Debug_Pools;
19854 with System.Storage_Elements;
19855 with Ada.Exceptions; use Ada.Exceptions;
19856 procedure Debug_Pool_Test is
19858 type T is access Integer;
19859 type U is access all T;
19861 P : GNAT.Debug_Pools.Debug_Pool;
19862 for T'Storage_Pool use P;
19864 procedure Free is new Unchecked_Deallocation (Integer, T);
19865 function UC is new Unchecked_Conversion (U, T);
19868 procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
19878 Put_Line (Integer'Image(B.all));
19880 when E : others => Put_Line ("raised: " & Exception_Name (E));
19885 when E : others => Put_Line ("raised: " & Exception_Name (E));
19889 Put_Line (Integer'Image(B.all));
19891 when E : others => Put_Line ("raised: " & Exception_Name (E));
19896 when E : others => Put_Line ("raised: " & Exception_Name (E));
19899 end Debug_Pool_Test;
19903 The debug pool mechanism provides the following precise diagnostics on the
19904 execution of this erroneous program:
19907 Total allocated bytes : 0
19908 Total deallocated bytes : 0
19909 Current Water Mark: 0
19913 Total allocated bytes : 8
19914 Total deallocated bytes : 0
19915 Current Water Mark: 8
19918 raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE
19919 raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE
19920 raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE
19921 raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE
19923 Total allocated bytes : 8
19924 Total deallocated bytes : 4
19925 Current Water Mark: 4
19930 @node The gnatmem Tool
19931 @section The @command{gnatmem} Tool
19935 The @code{gnatmem} utility monitors dynamic allocation and
19936 deallocation activity in a program, and displays information about
19937 incorrect deallocations and possible sources of memory leaks.
19938 It is designed to work in association with a static runtime library
19939 only and in this context provides three types of information:
19942 General information concerning memory management, such as the total
19943 number of allocations and deallocations, the amount of allocated
19944 memory and the high water mark, i.e.@: the largest amount of allocated
19945 memory in the course of program execution.
19948 Backtraces for all incorrect deallocations, that is to say deallocations
19949 which do not correspond to a valid allocation.
19952 Information on each allocation that is potentially the origin of a memory
19957 * Running gnatmem::
19958 * Switches for gnatmem::
19959 * Example of gnatmem Usage::
19962 @node Running gnatmem
19963 @subsection Running @code{gnatmem}
19966 @code{gnatmem} makes use of the output created by the special version of
19967 allocation and deallocation routines that record call information. This
19968 allows to obtain accurate dynamic memory usage history at a minimal cost to
19969 the execution speed. Note however, that @code{gnatmem} is not supported on
19970 all platforms (currently, it is supported on AIX, HP-UX, GNU/Linux,
19971 Solaris and Windows NT/2000/XP (x86).
19974 The @code{gnatmem} command has the form
19977 $ gnatmem @ovar{switches} user_program
19981 The program must have been linked with the instrumented version of the
19982 allocation and deallocation routines. This is done by linking with the
19983 @file{libgmem.a} library. For correct symbolic backtrace information,
19984 the user program should be compiled with debugging options
19985 (see @ref{Switches for gcc}). For example to build @file{my_program}:
19988 $ gnatmake -g my_program -largs -lgmem
19992 As library @file{libgmem.a} contains an alternate body for package
19993 @code{System.Memory}, @file{s-memory.adb} should not be compiled and linked
19994 when an executable is linked with library @file{libgmem.a}. It is then not
19995 recommended to use @command{gnatmake} with switch @option{^-a^/ALL_FILES^}.
19998 When @file{my_program} is executed, the file @file{gmem.out} is produced.
19999 This file contains information about all allocations and deallocations
20000 performed by the program. It is produced by the instrumented allocations and
20001 deallocations routines and will be used by @code{gnatmem}.
20003 In order to produce symbolic backtrace information for allocations and
20004 deallocations performed by the GNAT run-time library, you need to use a
20005 version of that library that has been compiled with the @option{-g} switch
20006 (see @ref{Rebuilding the GNAT Run-Time Library}).
20008 Gnatmem must be supplied with the @file{gmem.out} file and the executable to
20009 examine. If the location of @file{gmem.out} file was not explicitly supplied by
20010 @option{-i} switch, gnatmem will assume that this file can be found in the
20011 current directory. For example, after you have executed @file{my_program},
20012 @file{gmem.out} can be analyzed by @code{gnatmem} using the command:
20015 $ gnatmem my_program
20019 This will produce the output with the following format:
20021 *************** debut cc
20023 $ gnatmem my_program
20027 Total number of allocations : 45
20028 Total number of deallocations : 6
20029 Final Water Mark (non freed mem) : 11.29 Kilobytes
20030 High Water Mark : 11.40 Kilobytes
20035 Allocation Root # 2
20036 -------------------
20037 Number of non freed allocations : 11
20038 Final Water Mark (non freed mem) : 1.16 Kilobytes
20039 High Water Mark : 1.27 Kilobytes
20041 my_program.adb:23 my_program.alloc
20047 The first block of output gives general information. In this case, the
20048 Ada construct ``@code{@b{new}}'' was executed 45 times, and only 6 calls to an
20049 Unchecked_Deallocation routine occurred.
20052 Subsequent paragraphs display information on all allocation roots.
20053 An allocation root is a specific point in the execution of the program
20054 that generates some dynamic allocation, such as a ``@code{@b{new}}''
20055 construct. This root is represented by an execution backtrace (or subprogram
20056 call stack). By default the backtrace depth for allocations roots is 1, so
20057 that a root corresponds exactly to a source location. The backtrace can
20058 be made deeper, to make the root more specific.
20060 @node Switches for gnatmem
20061 @subsection Switches for @code{gnatmem}
20064 @code{gnatmem} recognizes the following switches:
20069 @cindex @option{-q} (@code{gnatmem})
20070 Quiet. Gives the minimum output needed to identify the origin of the
20071 memory leaks. Omits statistical information.
20074 @cindex @var{N} (@code{gnatmem})
20075 N is an integer literal (usually between 1 and 10) which controls the
20076 depth of the backtraces defining allocation root. The default value for
20077 N is 1. The deeper the backtrace, the more precise the localization of
20078 the root. Note that the total number of roots can depend on this
20079 parameter. This parameter must be specified @emph{before} the name of the
20080 executable to be analyzed, to avoid ambiguity.
20083 @cindex @option{-b} (@code{gnatmem})
20084 This switch has the same effect as just depth parameter.
20086 @item -i @var{file}
20087 @cindex @option{-i} (@code{gnatmem})
20088 Do the @code{gnatmem} processing starting from @file{file}, rather than
20089 @file{gmem.out} in the current directory.
20092 @cindex @option{-m} (@code{gnatmem})
20093 This switch causes @code{gnatmem} to mask the allocation roots that have less
20094 than n leaks. The default value is 1. Specifying the value of 0 will allow to
20095 examine even the roots that didn't result in leaks.
20098 @cindex @option{-s} (@code{gnatmem})
20099 This switch causes @code{gnatmem} to sort the allocation roots according to the
20100 specified order of sort criteria, each identified by a single letter. The
20101 currently supported criteria are @code{n, h, w} standing respectively for
20102 number of unfreed allocations, high watermark, and final watermark
20103 corresponding to a specific root. The default order is @code{nwh}.
20107 @node Example of gnatmem Usage
20108 @subsection Example of @code{gnatmem} Usage
20111 The following example shows the use of @code{gnatmem}
20112 on a simple memory-leaking program.
20113 Suppose that we have the following Ada program:
20115 @smallexample @c ada
20118 with Unchecked_Deallocation;
20119 procedure Test_Gm is
20121 type T is array (1..1000) of Integer;
20122 type Ptr is access T;
20123 procedure Free is new Unchecked_Deallocation (T, Ptr);
20126 procedure My_Alloc is
20131 procedure My_DeAlloc is
20139 for I in 1 .. 5 loop
20140 for J in I .. 5 loop
20151 The program needs to be compiled with debugging option and linked with
20152 @code{gmem} library:
20155 $ gnatmake -g test_gm -largs -lgmem
20159 Then we execute the program as usual:
20166 Then @code{gnatmem} is invoked simply with
20172 which produces the following output (result may vary on different platforms):
20177 Total number of allocations : 18
20178 Total number of deallocations : 5
20179 Final Water Mark (non freed mem) : 53.00 Kilobytes
20180 High Water Mark : 56.90 Kilobytes
20182 Allocation Root # 1
20183 -------------------
20184 Number of non freed allocations : 11
20185 Final Water Mark (non freed mem) : 42.97 Kilobytes
20186 High Water Mark : 46.88 Kilobytes
20188 test_gm.adb:11 test_gm.my_alloc
20190 Allocation Root # 2
20191 -------------------
20192 Number of non freed allocations : 1
20193 Final Water Mark (non freed mem) : 10.02 Kilobytes
20194 High Water Mark : 10.02 Kilobytes
20196 s-secsta.adb:81 system.secondary_stack.ss_init
20198 Allocation Root # 3
20199 -------------------
20200 Number of non freed allocations : 1
20201 Final Water Mark (non freed mem) : 12 Bytes
20202 High Water Mark : 12 Bytes
20204 s-secsta.adb:181 system.secondary_stack.ss_init
20208 Note that the GNAT run time contains itself a certain number of
20209 allocations that have no corresponding deallocation,
20210 as shown here for root #2 and root
20211 #3. This is a normal behavior when the number of non-freed allocations
20212 is one, it allocates dynamic data structures that the run time needs for
20213 the complete lifetime of the program. Note also that there is only one
20214 allocation root in the user program with a single line back trace:
20215 test_gm.adb:11 test_gm.my_alloc, whereas a careful analysis of the
20216 program shows that 'My_Alloc' is called at 2 different points in the
20217 source (line 21 and line 24). If those two allocation roots need to be
20218 distinguished, the backtrace depth parameter can be used:
20221 $ gnatmem 3 test_gm
20225 which will give the following output:
20230 Total number of allocations : 18
20231 Total number of deallocations : 5
20232 Final Water Mark (non freed mem) : 53.00 Kilobytes
20233 High Water Mark : 56.90 Kilobytes
20235 Allocation Root # 1
20236 -------------------
20237 Number of non freed allocations : 10
20238 Final Water Mark (non freed mem) : 39.06 Kilobytes
20239 High Water Mark : 42.97 Kilobytes
20241 test_gm.adb:11 test_gm.my_alloc
20242 test_gm.adb:24 test_gm
20243 b_test_gm.c:52 main
20245 Allocation Root # 2
20246 -------------------
20247 Number of non freed allocations : 1
20248 Final Water Mark (non freed mem) : 10.02 Kilobytes
20249 High Water Mark : 10.02 Kilobytes
20251 s-secsta.adb:81 system.secondary_stack.ss_init
20252 s-secsta.adb:283 <system__secondary_stack___elabb>
20253 b_test_gm.c:33 adainit
20255 Allocation Root # 3
20256 -------------------
20257 Number of non freed allocations : 1
20258 Final Water Mark (non freed mem) : 3.91 Kilobytes
20259 High Water Mark : 3.91 Kilobytes
20261 test_gm.adb:11 test_gm.my_alloc
20262 test_gm.adb:21 test_gm
20263 b_test_gm.c:52 main
20265 Allocation Root # 4
20266 -------------------
20267 Number of non freed allocations : 1
20268 Final Water Mark (non freed mem) : 12 Bytes
20269 High Water Mark : 12 Bytes
20271 s-secsta.adb:181 system.secondary_stack.ss_init
20272 s-secsta.adb:283 <system__secondary_stack___elabb>
20273 b_test_gm.c:33 adainit
20277 The allocation root #1 of the first example has been split in 2 roots #1
20278 and #3 thanks to the more precise associated backtrace.
20282 @node Stack Related Facilities
20283 @chapter Stack Related Facilities
20286 This chapter describes some useful tools associated with stack
20287 checking and analysis. In
20288 particular, it deals with dynamic and static stack usage measurements.
20291 * Stack Overflow Checking::
20292 * Static Stack Usage Analysis::
20293 * Dynamic Stack Usage Analysis::
20296 @node Stack Overflow Checking
20297 @section Stack Overflow Checking
20298 @cindex Stack Overflow Checking
20299 @cindex -fstack-check
20302 For most operating systems, @command{gcc} does not perform stack overflow
20303 checking by default. This means that if the main environment task or
20304 some other task exceeds the available stack space, then unpredictable
20305 behavior will occur. Most native systems offer some level of protection by
20306 adding a guard page at the end of each task stack. This mechanism is usually
20307 not enough for dealing properly with stack overflow situations because
20308 a large local variable could ``jump'' above the guard page.
20309 Furthermore, when the
20310 guard page is hit, there may not be any space left on the stack for executing
20311 the exception propagation code. Enabling stack checking avoids
20314 To activate stack checking, compile all units with the gcc option
20315 @option{-fstack-check}. For example:
20318 gcc -c -fstack-check package1.adb
20322 Units compiled with this option will generate extra instructions to check
20323 that any use of the stack (for procedure calls or for declaring local
20324 variables in declare blocks) does not exceed the available stack space.
20325 If the space is exceeded, then a @code{Storage_Error} exception is raised.
20327 For declared tasks, the stack size is controlled by the size
20328 given in an applicable @code{Storage_Size} pragma or by the value specified
20329 at bind time with @option{-d} (@pxref{Switches for gnatbind}) or is set to
20330 the default size as defined in the GNAT runtime otherwise.
20332 For the environment task, the stack size depends on
20333 system defaults and is unknown to the compiler. Stack checking
20334 may still work correctly if a fixed
20335 size stack is allocated, but this cannot be guaranteed.
20337 To ensure that a clean exception is signalled for stack
20338 overflow, set the environment variable
20339 @env{GNAT_STACK_LIMIT} to indicate the maximum
20340 stack area that can be used, as in:
20341 @cindex GNAT_STACK_LIMIT
20344 SET GNAT_STACK_LIMIT 1600
20348 The limit is given in kilobytes, so the above declaration would
20349 set the stack limit of the environment task to 1.6 megabytes.
20350 Note that the only purpose of this usage is to limit the amount
20351 of stack used by the environment task. If it is necessary to
20352 increase the amount of stack for the environment task, then this
20353 is an operating systems issue, and must be addressed with the
20354 appropriate operating systems commands.
20357 To have a fixed size stack in the environment task, the stack must be put
20358 in the P0 address space and its size specified. Use these switches to
20362 gnatmake my_progs -largs "-Wl,--opt=STACK=4000,/p0image"
20366 The quotes are required to keep case. The number after @samp{STACK=} is the
20367 size of the environmental task stack in pagelets (512 bytes). In this example
20368 the stack size is about 2 megabytes.
20371 A consequence of the @option{/p0image} qualifier is also to makes RMS buffers
20372 be placed in P0 space. Refer to @cite{HP OpenVMS Linker Utility Manual} for
20373 more details about the @option{/p0image} qualifier and the @option{stack}
20377 @node Static Stack Usage Analysis
20378 @section Static Stack Usage Analysis
20379 @cindex Static Stack Usage Analysis
20380 @cindex -fstack-usage
20383 A unit compiled with @option{-fstack-usage} will generate an extra file
20385 the maximum amount of stack used, on a per-function basis.
20386 The file has the same
20387 basename as the target object file with a @file{.su} extension.
20388 Each line of this file is made up of three fields:
20392 The name of the function.
20396 One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
20399 The second field corresponds to the size of the known part of the function
20402 The qualifier @code{static} means that the function frame size
20404 It usually means that all local variables have a static size.
20405 In this case, the second field is a reliable measure of the function stack
20408 The qualifier @code{dynamic} means that the function frame size is not static.
20409 It happens mainly when some local variables have a dynamic size. When this
20410 qualifier appears alone, the second field is not a reliable measure
20411 of the function stack analysis. When it is qualified with @code{bounded}, it
20412 means that the second field is a reliable maximum of the function stack
20415 @node Dynamic Stack Usage Analysis
20416 @section Dynamic Stack Usage Analysis
20419 It is possible to measure the maximum amount of stack used by a task, by
20420 adding a switch to @command{gnatbind}, as:
20423 $ gnatbind -u0 file
20427 With this option, at each task termination, its stack usage is output on
20429 It is not always convenient to output the stack usage when the program
20430 is still running. Hence, it is possible to delay this output until program
20431 termination. for a given number of tasks specified as the argument of the
20432 @option{-u} option. For instance:
20435 $ gnatbind -u100 file
20439 will buffer the stack usage information of the first 100 tasks to terminate and
20440 output this info at program termination. Results are displayed in four
20444 Index | Task Name | Stack Size | Stack Usage [Value +/- Variation]
20451 is a number associated with each task.
20454 is the name of the task analyzed.
20457 is the maximum size for the stack.
20460 is the measure done by the stack analyzer. In order to prevent overflow, the stack
20461 is not entirely analyzed, and it's not possible to know exactly how
20462 much has actually been used. The report thus contains the theoretical stack usage
20463 (Value) and the possible variation (Variation) around this value.
20468 The environment task stack, e.g., the stack that contains the main unit, is
20469 only processed when the environment variable GNAT_STACK_LIMIT is set.
20472 @c *********************************
20474 @c *********************************
20475 @node Verifying Properties Using gnatcheck
20476 @chapter Verifying Properties Using @command{gnatcheck}
20478 @cindex @command{gnatcheck}
20481 The @command{gnatcheck} tool is an ASIS-based utility that checks properties
20482 of Ada source files according to a given set of semantic rules.
20485 In order to check compliance with a given rule, @command{gnatcheck} has to
20486 semantically analyze the Ada sources.
20487 Therefore, checks can only be performed on
20488 legal Ada units. Moreover, when a unit depends semantically upon units located
20489 outside the current directory, the source search path has to be provided when
20490 calling @command{gnatcheck}, either through a specified project file or
20491 through @command{gnatcheck} switches as described below.
20493 A number of rules are predefined in @command{gnatcheck} and are described
20494 later in this chapter.
20495 You can also add new rules, by modifying the @command{gnatcheck} code and
20496 rebuilding the tool. In order to add a simple rule making some local checks,
20497 a small amount of straightforward ASIS-based programming is usually needed.
20499 Project support for @command{gnatcheck} is provided by the GNAT
20500 driver (see @ref{The GNAT Driver and Project Files}).
20502 Invoking @command{gnatcheck} on the command line has the form:
20505 $ gnatcheck @ovar{switches} @{@var{filename}@}
20506 @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
20507 @r{[}-cargs @var{gcc_switches}@r{]} @r{[}-rules @var{rule_options}@r{]}
20514 @var{switches} specify the general tool options
20517 Each @var{filename} is the name (including the extension) of a source
20518 file to process. ``Wildcards'' are allowed, and
20519 the file name may contain path information.
20522 Each @var{arg_list_filename} is the name (including the extension) of a text
20523 file containing the names of the source files to process, separated by spaces
20527 @var{gcc_switches} is a list of switches for
20528 @command{gcc}. They will be passed on to all compiler invocations made by
20529 @command{gnatcheck} to generate the ASIS trees. Here you can provide
20530 @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
20531 and use the @option{-gnatec} switch to set the configuration file.
20534 @var{rule_options} is a list of options for controlling a set of
20535 rules to be checked by @command{gnatcheck} (@pxref{gnatcheck Rule Options}).
20539 Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be supplied.
20542 * Format of the Report File::
20543 * General gnatcheck Switches::
20544 * gnatcheck Rule Options::
20545 * Adding the Results of Compiler Checks to gnatcheck Output::
20546 * Project-Wide Checks::
20547 * Predefined Rules::
20550 @node Format of the Report File
20551 @section Format of the Report File
20552 @cindex Report file (for @code{gnatcheck})
20555 The @command{gnatcheck} tool outputs on @file{stdout} all messages concerning
20557 It also creates a text file that
20558 contains the complete report of the last gnatcheck run. By default this file is
20559 named named @file{^gnatcheck.out^GNATCHECK.OUT^} and it is located in the current
20560 directory, @option{^-o^/OUTPUT^} option can be used to change the name and/or
20561 location of the report file. This report contains:
20563 @item a list of the Ada source files being checked,
20564 @item a list of enabled and disabled rules,
20565 @item a list of the diagnostic messages, ordered in three different ways
20566 and collected in three separate
20567 sections. Section 1 contains the raw list of diagnostic messages. It
20568 corresponds to the output going to @file{stdout}. Section 2 contains
20569 messages ordered by rules.
20570 Section 3 contains messages ordered by source files.
20573 @node General gnatcheck Switches
20574 @section General @command{gnatcheck} Switches
20577 The following switches control the general @command{gnatcheck} behavior
20581 @cindex @option{^-a^/ALL^} (@command{gnatcheck})
20583 Process all units including those with read-only ALI files such as
20584 those from GNAT Run-Time library.
20588 @cindex @option{-d} (@command{gnatcheck})
20593 @cindex @option{-dd} (@command{gnatcheck})
20595 Progress indicator mode (for use in GPS)
20598 @cindex @option{^-h^/HELP^} (@command{gnatcheck})
20600 List the predefined and user-defined rules. For more details see
20601 @ref{Predefined Rules}.
20603 @cindex @option{^-l^/LOCS^} (@command{gnatcheck})
20605 Use full source locations references in the report file. For a construct from
20606 a generic instantiation a full source location is a chain from the location
20607 of this construct in the generic unit to the place where this unit is
20610 @cindex @option{^-m^/DIAGNOSTIC_LIMIT^} (@command{gnatcheck})
20611 @item ^-m@i{nnn}^/DIAGNOSTIC_LIMIT=@i{nnn}^
20612 Maximum number of diagnoses to be sent to Stdout, @i{nnn} from o@dots{}1000,
20613 the default value is 500. Zero means that there is no limitation on
20614 the number of diagnostic messages to be printed into Stdout.
20616 @cindex @option{^-q^/QUIET^} (@command{gnatcheck})
20618 Quiet mode. All the diagnoses about rule violations are placed in the
20619 @command{gnatcheck} report file only, without duplicating in @file{stdout}.
20621 @cindex @option{^-s^/SHORT^} (@command{gnatcheck})
20623 Short format of the report file (no version information, no list of applied
20624 rules, no list of checked sources is included)
20626 @cindex @option{^-s1^/COMPILER_STYLE^} (@command{gnatcheck})
20627 @item ^-s1^/COMPILER_STYLE^
20628 Include the compiler-style section in the report file
20630 @cindex @option{^-s2^/BY_RULES^} (@command{gnatcheck})
20631 @item ^-s2^/BY_RULES^
20632 Include the section containing diagnoses ordered by rules in the report file
20634 @cindex @option{^-s3^/BY_FILES_BY_RULES^} (@command{gnatcheck})
20635 @item ^-s3^/BY_FILES_BY_RULES^
20636 Include the section containing diagnoses ordered by files and then by rules
20639 @cindex @option{^-v^/VERBOSE^} (@command{gnatcheck})
20640 @item ^-v^/VERBOSE^
20641 Verbose mode; @command{gnatcheck} generates version information and then
20642 a trace of sources being processed.
20645 @cindex @option{^-o ^/OUTPUT^} (@command{gnatcheck})
20646 @item ^-o ^/OUTPUT=^@var{report_file}
20647 Set name of report file file to @var{report_file} .
20652 Note that if any of the options @option{^-s1^/COMPILER_STYLE^},
20653 @option{^-s2^/BY_RULES^} or
20654 @option{^-s3^/BY_FILES_BY_RULES^} is specified,
20655 then the @command{gnatcheck} report file will only contain sections
20656 explicitly denoted by these options.
20658 @node gnatcheck Rule Options
20659 @section @command{gnatcheck} Rule Options
20662 The following options control the processing performed by
20663 @command{gnatcheck}.
20666 @cindex @option{+ALL} (@command{gnatcheck})
20668 Turn all the rule checks ON.
20670 @cindex @option{-ALL} (@command{gnatcheck})
20672 Turn all the rule checks OFF.
20674 @cindex @option{+R} (@command{gnatcheck})
20675 @item +R@var{rule_id}@r{[}:@var{param}@r{]}
20676 Turn on the check for a specified rule with the specified parameter, if any.
20677 @var{rule_id} must be the identifier of one of the currently implemented rules
20678 (use @option{^-h^/HELP^} for the list of implemented rules). Rule identifiers
20679 are not case-sensitive. The @var{param} item must
20680 be a string representing a valid parameter(s) for the specified rule.
20681 If it contains any space characters then this string must be enclosed in
20684 @cindex @option{-R} (@command{gnatcheck})
20685 @item -R@var{rule_id}@r{[}:@var{param}@r{]}
20686 Turn off the check for a specified rule with the specified parameter, if any.
20688 @cindex @option{-from} (@command{gnatcheck})
20689 @item -from=@var{rule_option_filename}
20690 Read the rule options from the text file @var{rule_option_filename}, referred as
20691 ``rule file'' below.
20696 The default behavior is that all the rule checks are disabled.
20698 A rule file is a text file containing a set of rule options.
20699 @cindex Rule file (for @code{gnatcheck})
20700 The file may contain empty lines and Ada-style comments (comment
20701 lines and end-of-line comments). The rule file has free format; that is,
20702 you do not have to start a new rule option on a new line.
20704 A rule file may contain other @option{-from=@var{rule_option_filename}}
20705 options, each such option being replaced with the content of the
20706 corresponding rule file during the rule files processing. In case a
20707 cycle is detected (that is, @file{@var{rule_file_1}} reads rule options
20708 from @file{@var{rule_file_2}}, and @file{@var{rule_file_2}} reads
20709 (directly or indirectly) rule options from @file{@var{rule_file_1}}),
20710 the processing of rule files is interrupted and a part of their content
20714 @node Adding the Results of Compiler Checks to gnatcheck Output
20715 @section Adding the Results of Compiler Checks to @command{gnatcheck} Output
20718 The @command{gnatcheck} tool can include in the generated diagnostic messages
20720 the report file the results of the checks performed by the compiler. Though
20721 disabled by default, this effect may be obtained by using @option{+R} with
20722 the following rule identifiers and parameters:
20726 To record restrictions violations (that are performed by the compiler if the
20727 pragma @code{Restrictions} or @code{Restriction_Warnings} are given),
20729 @code{Restrictions} with the same parameters as pragma
20730 @code{Restrictions} or @code{Restriction_Warnings}.
20733 To record compiler style checks(@pxref{Style Checking}), use the rule named
20734 @code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
20735 which enables all the standard style checks that corresponds to @option{-gnatyy}
20736 GNAT style check option, or a string that has exactly the same
20737 structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
20738 @code{Style_Checks} (for further information about this pragma,
20739 @pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
20742 To record compiler warnings (@pxref{Warning Message Control}), use the rule
20743 named @code{Warnings} with a parameter that is a valid
20744 @i{static_string_expression} argument of GNAT pragma @code{Warnings}
20745 (for further information about this pragma, @pxref{Pragma Warnings,,,
20746 gnat_rm, GNAT Reference Manual}). Note, that in case of gnatcheck
20747 's' parameter, that corresponds to the GNAT @option{-gnatws} option, disables
20748 all the specific warnings, but not suppresses the warning mode,
20749 and 'e' parameter, corresponding to @option{-gnatwe} that means
20750 "treat warnings as errors", does not have any effect.
20754 To disable a specific restriction check, use @code{-RStyle_Checks} gnatcheck
20755 option with the corresponding restriction name as a parameter. @code{-R} is
20756 not available for @code{Style_Checks} and @code{Warnings} options, to disable
20757 warnings and style checks, use the corresponding warning and style options.
20759 @node Project-Wide Checks
20760 @section Project-Wide Checks
20761 @cindex Project-wide checks (for @command{gnatcheck})
20764 In order to perform checks on all units of a given project, you can use
20765 the GNAT driver along with the @option{-P} option:
20767 gnat check -Pproj -rules -from=my_rules
20771 If the project @code{proj} depends upon other projects, you can perform
20772 checks on the project closure using the @option{-U} option:
20774 gnat check -Pproj -U -rules -from=my_rules
20778 Finally, if not all the units are relevant to a particular main
20779 program in the project closure, you can perform checks for the set
20780 of units needed to create a given main program (unit closure) using
20781 the @option{-U} option followed by the name of the main unit:
20783 gnat check -Pproj -U main -rules -from=my_rules
20787 @node Predefined Rules
20788 @section Predefined Rules
20789 @cindex Predefined rules (for @command{gnatcheck})
20792 @c (Jan 2007) Since the global rules are still under development and are not
20793 @c documented, there is no point in explaining the difference between
20794 @c global and local rules
20796 A rule in @command{gnatcheck} is either local or global.
20797 A @emph{local rule} is a rule that applies to a well-defined section
20798 of a program and that can be checked by analyzing only this section.
20799 A @emph{global rule} requires analysis of some global properties of the
20800 whole program (mostly related to the program call graph).
20801 As of @value{NOW}, the implementation of global rules should be
20802 considered to be at a preliminary stage. You can use the
20803 @option{+GLOBAL} option to enable all the global rules, and the
20804 @option{-GLOBAL} rule option to disable all the global rules.
20806 All the global rules in the list below are
20807 so indicated by marking them ``GLOBAL''.
20808 This +GLOBAL and -GLOBAL options are not
20809 included in the list of gnatcheck options above, because at the moment they
20810 are considered as a temporary debug options.
20812 @command{gnatcheck} performs rule checks for generic
20813 instances only for global rules. This limitation may be relaxed in a later
20818 The following subsections document the rules implemented in
20819 @command{gnatcheck}.
20820 The subsection title is the same as the rule identifier, which may be
20821 used as a parameter of the @option{+R} or @option{-R} options.
20825 * Abstract_Type_Declarations::
20826 * Anonymous_Arrays::
20827 * Anonymous_Subtypes::
20829 * Boolean_Relational_Operators::
20831 * Ceiling_Violations::
20833 * Controlled_Type_Declarations::
20834 * Declarations_In_Blocks::
20835 * Default_Parameters::
20836 * Discriminated_Records::
20837 * Enumeration_Ranges_In_CASE_Statements::
20838 * Exceptions_As_Control_Flow::
20839 * EXIT_Statements_With_No_Loop_Name::
20840 * Expanded_Loop_Exit_Names::
20841 * Explicit_Full_Discrete_Ranges::
20842 * Float_Equality_Checks::
20843 * Forbidden_Pragmas::
20844 * Function_Style_Procedures::
20845 * Generics_In_Subprograms::
20846 * GOTO_Statements::
20847 * Implicit_IN_Mode_Parameters::
20848 * Implicit_SMALL_For_Fixed_Point_Types::
20849 * Improperly_Located_Instantiations::
20850 * Improper_Returns::
20851 * Library_Level_Subprograms::
20854 * Improperly_Called_Protected_Entries::
20857 * Misnamed_Identifiers::
20858 * Multiple_Entries_In_Protected_Definitions::
20860 * Non_Qualified_Aggregates::
20861 * Non_Short_Circuit_Operators::
20862 * Non_SPARK_Attributes::
20863 * Non_Tagged_Derived_Types::
20864 * Non_Visible_Exceptions::
20865 * Numeric_Literals::
20866 * OTHERS_In_Aggregates::
20867 * OTHERS_In_CASE_Statements::
20868 * OTHERS_In_Exception_Handlers::
20869 * Outer_Loop_Exits::
20870 * Overloaded_Operators::
20871 * Overly_Nested_Control_Structures::
20872 * Parameters_Out_Of_Order::
20873 * Positional_Actuals_For_Defaulted_Generic_Parameters::
20874 * Positional_Actuals_For_Defaulted_Parameters::
20875 * Positional_Components::
20876 * Positional_Generic_Parameters::
20877 * Positional_Parameters::
20878 * Predefined_Numeric_Types::
20879 * Raising_External_Exceptions::
20880 * Raising_Predefined_Exceptions::
20881 * Separate_Numeric_Error_Handlers::
20884 * Side_Effect_Functions::
20887 * Unassigned_OUT_Parameters::
20888 * Uncommented_BEGIN_In_Package_Bodies::
20889 * Unconstrained_Array_Returns::
20890 * Universal_Ranges::
20891 * Unnamed_Blocks_And_Loops::
20893 * Unused_Subprograms::
20895 * USE_PACKAGE_Clauses::
20896 * Volatile_Objects_Without_Address_Clauses::
20900 @node Abstract_Type_Declarations
20901 @subsection @code{Abstract_Type_Declarations}
20902 @cindex @code{Abstract_Type_Declarations} rule (for @command{gnatcheck})
20905 Flag all declarations of abstract types. For an abstract private
20906 type, both the private and full type declarations are flagged.
20908 This rule has no parameters.
20911 @node Anonymous_Arrays
20912 @subsection @code{Anonymous_Arrays}
20913 @cindex @code{Anonymous_Arrays} rule (for @command{gnatcheck})
20916 Flag all anonymous array type definitions (by Ada semantics these can only
20917 occur in object declarations).
20919 This rule has no parameters.
20921 @node Anonymous_Subtypes
20922 @subsection @code{Anonymous_Subtypes}
20923 @cindex @code{Anonymous_Subtypes} rule (for @command{gnatcheck})
20926 Flag all uses of anonymous subtypes. A use of an anonymous subtype is
20927 any instance of a subtype indication with a constraint, other than one
20928 that occurs immediately within a subtype declaration. Any use of a range
20929 other than as a constraint used immediately within a subtype declaration
20930 is considered as an anonymous subtype.
20932 An effect of this rule is that @code{for} loops such as the following are
20933 flagged (since @code{1..N} is formally a ``range''):
20935 @smallexample @c ada
20936 for I in 1 .. N loop
20942 Declaring an explicit subtype solves the problem:
20944 @smallexample @c ada
20945 subtype S is Integer range 1..N;
20953 This rule has no parameters.
20956 @subsection @code{Blocks}
20957 @cindex @code{Blocks} rule (for @command{gnatcheck})
20960 Flag each block statement.
20962 This rule has no parameters.
20964 @node Boolean_Relational_Operators
20965 @subsection @code{Boolean_Relational_Operators}
20966 @cindex @code{Boolean_Relational_Operators} rule (for @command{gnatcheck})
20969 Flag each call to a predefined relational operator (``<'', ``>'', ``<='',
20970 ``>='', ``='' and ``/='') for the predefined Boolean type.
20971 (This rule is useful in enforcing the SPARK language restrictions.)
20973 Calls to predefined relational operators of any type derived from
20974 @code{Standard.Boolean} are not detected. Calls to user-defined functions
20975 with these designators, and uses of operators that are renamings
20976 of the predefined relational operators for @code{Standard.Boolean},
20977 are likewise not detected.
20979 This rule has no parameters.
20982 @node Ceiling_Violations
20983 @subsection @code{Ceiling_Violations} (under construction, GLOBAL)
20984 @cindex @code{Ceiling_Violations} rule (for @command{gnatcheck})
20987 Flag invocations of a protected operation by a task whose priority exceeds
20988 the protected object's ceiling.
20990 As of @value{NOW}, this rule has the following limitations:
20995 We consider only pragmas Priority and Interrupt_Priority as means to define
20996 a task/protected operation priority. We do not consider the effect of using
20997 Ada.Dynamic_Priorities.Set_Priority procedure;
21000 We consider only base task priorities, and no priority inheritance. That is,
21001 we do not make a difference between calls issued during task activation and
21002 execution of the sequence of statements from task body;
21005 Any situation when the priority of protected operation caller is set by a
21006 dynamic expression (that is, the corresponding Priority or
21007 Interrupt_Priority pragma has a non-static expression as an argument) we
21008 treat as a priority inconsistency (and, therefore, detect this situation).
21012 At the moment the notion of the main subprogram is not implemented in
21013 gnatcheck, so any pragma Priority in a library level subprogram body (in case
21014 if this subprogram can be a main subprogram of a partition) changes the
21015 priority of an environment task. So if we have more then one such pragma in
21016 the set of processed sources, the pragma that is processed last, defines the
21017 priority of an environment task.
21019 This rule has no parameters.
21022 @node Controlled_Type_Declarations
21023 @subsection @code{Controlled_Type_Declarations}
21024 @cindex @code{Controlled_Type_Declarations} rule (for @command{gnatcheck})
21027 Flag all declarations of controlled types. A declaration of a private type
21028 is flagged if its full declaration declares a controlled type. A declaration
21029 of a derived type is flagged if its ancestor type is controlled. Subtype
21030 declarations are not checked. A declaration of a type that itself is not a
21031 descendant of a type declared in @code{Ada.Finalization} but has a controlled
21032 component is not checked.
21034 This rule has no parameters.
21038 @node Declarations_In_Blocks
21039 @subsection @code{Declarations_In_Blocks}
21040 @cindex @code{Declarations_In_Blocks} rule (for @command{gnatcheck})
21043 Flag all block statements containing local declarations. A @code{declare}
21044 block with an empty @i{declarative_part} or with a @i{declarative part}
21045 containing only pragmas and/or @code{use} clauses is not flagged.
21047 This rule has no parameters.
21050 @node Default_Parameters
21051 @subsection @code{Default_Parameters}
21052 @cindex @code{Default_Parameters} rule (for @command{gnatcheck})
21055 Flag all default expressions for subprogram parameters. Parameter
21056 declarations of formal and generic subprograms are also checked.
21058 This rule has no parameters.
21061 @node Discriminated_Records
21062 @subsection @code{Discriminated_Records}
21063 @cindex @code{Discriminated_Records} rule (for @command{gnatcheck})
21066 Flag all declarations of record types with discriminants. Only the
21067 declarations of record and record extension types are checked. Incomplete,
21068 formal, private, derived and private extension type declarations are not
21069 checked. Task and protected type declarations also are not checked.
21071 This rule has no parameters.
21074 @node Enumeration_Ranges_In_CASE_Statements
21075 @subsection @code{Enumeration_Ranges_In_CASE_Statements}
21076 @cindex @code{Enumeration_Ranges_In_CASE_Statements} (for @command{gnatcheck})
21079 Flag each use of a range of enumeration literals as a choice in a
21080 @code{case} statement.
21081 All forms for specifying a range (explicit ranges
21082 such as @code{A .. B}, subtype marks and @code{'Range} attributes) are flagged.
21083 An enumeration range is
21084 flagged even if contains exactly one enumeration value or no values at all. A
21085 type derived from an enumeration type is considered as an enumeration type.
21087 This rule helps prevent maintenance problems arising from adding an
21088 enumeration value to a type and having it implicitly handled by an existing
21089 @code{case} statement with an enumeration range that includes the new literal.
21091 This rule has no parameters.
21094 @node Exceptions_As_Control_Flow
21095 @subsection @code{Exceptions_As_Control_Flow}
21096 @cindex @code{Exceptions_As_Control_Flow} (for @command{gnatcheck})
21099 Flag each place where an exception is explicitly raised and handled in the
21100 same subprogram body. A @code{raise} statement in an exception handler,
21101 package body, task body or entry body is not flagged.
21103 The rule has no parameters.
21105 @node EXIT_Statements_With_No_Loop_Name
21106 @subsection @code{EXIT_Statements_With_No_Loop_Name}
21107 @cindex @code{EXIT_Statements_With_No_Loop_Name} (for @command{gnatcheck})
21110 Flag each @code{exit} statement that does not specify the name of the loop
21113 The rule has no parameters.
21116 @node Expanded_Loop_Exit_Names
21117 @subsection @code{Expanded_Loop_Exit_Names}
21118 @cindex @code{Expanded_Loop_Exit_Names} rule (for @command{gnatcheck})
21121 Flag all expanded loop names in @code{exit} statements.
21123 This rule has no parameters.
21125 @node Explicit_Full_Discrete_Ranges
21126 @subsection @code{Explicit_Full_Discrete_Ranges}
21127 @cindex @code{Explicit_Full_Discrete_Ranges} rule (for @command{gnatcheck})
21130 Flag each discrete range that has the form @code{A'First .. A'Last}.
21132 This rule has no parameters.
21134 @node Float_Equality_Checks
21135 @subsection @code{Float_Equality_Checks}
21136 @cindex @code{Float_Equality_Checks} rule (for @command{gnatcheck})
21139 Flag all calls to the predefined equality operations for floating-point types.
21140 Both ``@code{=}'' and ``@code{/=}'' operations are checked.
21141 User-defined equality operations are not flagged, nor are ``@code{=}''
21142 and ``@code{/=}'' operations for fixed-point types.
21144 This rule has no parameters.
21147 @node Forbidden_Pragmas
21148 @subsection @code{Forbidden_Pragmas}
21149 @cindex @code{Forbidden_Pragmas} rule (for @command{gnatcheck})
21152 Flag each use of the specified pragmas. The pragmas to be detected
21153 are named in the rule's parameters.
21155 This rule has the following parameters:
21158 @item For the @option{+R} option
21161 @item @emph{Pragma_Name}
21162 Adds the specified pragma to the set of pragmas to be
21163 checked and sets the checks for all the specified pragmas
21164 ON. @emph{Pragma_Name} is treated as a name of a pragma. If it
21165 does not correspond to any pragma name defined in the Ada
21166 standard or to the name of a GNAT-specific pragma defined
21167 in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
21168 Manual}, it is treated as the name of unknown pragma.
21171 All the GNAT-specific pragmas are detected; this sets
21172 the checks for all the specified pragmas ON.
21175 All pragmas are detected; this sets the rule ON.
21178 @item For the @option{-R} option
21180 @item @emph{Pragma_Name}
21181 Removes the specified pragma from the set of pragmas to be
21182 checked without affecting checks for
21183 other pragmas. @emph{Pragma_Name} is treated as a name
21184 of a pragma. If it does not correspond to any pragma
21185 defined in the Ada standard or to any name defined in
21186 @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
21187 this option is treated as turning OFF detection of all unknown pragmas.
21190 Turn OFF detection of all GNAT-specific pragmas
21193 Clear the list of the pragmas to be detected and
21199 Parameters are not case sensitive. If @emph{Pragma_Name} does not have
21200 the syntax of an Ada identifier and therefore can not be considered
21201 as a pragma name, a diagnostic message is generated and the corresponding
21202 parameter is ignored.
21204 When more then one parameter is given in the same rule option, the parameters
21205 must be separated by a comma.
21207 If more then one option for this rule is specified for the @command{gnatcheck}
21208 call, a new option overrides the previous one(s).
21210 The @option{+R} option with no parameters turns the rule ON with the set of
21211 pragmas to be detected defined by the previous rule options.
21212 (By default this set is empty, so if the only option specified for the rule is
21213 @option{+RForbidden_Pragmas} (with
21214 no parameter), then the rule is enabled, but it does not detect anything).
21215 The @option{-R} option with no parameter turns the rule OFF, but it does not
21216 affect the set of pragmas to be detected.
21221 @node Function_Style_Procedures
21222 @subsection @code{Function_Style_Procedures}
21223 @cindex @code{Function_Style_Procedures} rule (for @command{gnatcheck})
21226 Flag each procedure that can be rewritten as a function. A procedure can be
21227 converted into a function if it has exactly one parameter of mode @code{out}
21228 and no parameters of mode @code{in out}. Procedure declarations,
21229 formal procedure declarations, and generic procedure declarations are always
21231 bodies and body stubs are flagged only if they do not have corresponding
21232 separate declarations. Procedure renamings and procedure instantiations are
21235 If a procedure can be rewritten as a function, but its @code{out} parameter is
21236 of a limited type, it is not flagged.
21238 Protected procedures are not flagged. Null procedures also are not flagged.
21240 This rule has no parameters.
21243 @node Generics_In_Subprograms
21244 @subsection @code{Generics_In_Subprograms}
21245 @cindex @code{Generics_In_Subprograms} rule (for @command{gnatcheck})
21248 Flag each declaration of a generic unit in a subprogram. Generic
21249 declarations in the bodies of generic subprograms are also flagged.
21250 A generic unit nested in another generic unit is not flagged.
21251 If a generic unit is
21252 declared in a local package that is declared in a subprogram body, the
21253 generic unit is flagged.
21255 This rule has no parameters.
21258 @node GOTO_Statements
21259 @subsection @code{GOTO_Statements}
21260 @cindex @code{GOTO_Statements} rule (for @command{gnatcheck})
21263 Flag each occurrence of a @code{goto} statement.
21265 This rule has no parameters.
21268 @node Implicit_IN_Mode_Parameters
21269 @subsection @code{Implicit_IN_Mode_Parameters}
21270 @cindex @code{Implicit_IN_Mode_Parameters} rule (for @command{gnatcheck})
21273 Flag each occurrence of a formal parameter with an implicit @code{in} mode.
21274 Note that @code{access} parameters, although they technically behave
21275 like @code{in} parameters, are not flagged.
21277 This rule has no parameters.
21280 @node Implicit_SMALL_For_Fixed_Point_Types
21281 @subsection @code{Implicit_SMALL_For_Fixed_Point_Types}
21282 @cindex @code{Implicit_SMALL_For_Fixed_Point_Types} rule (for @command{gnatcheck})
21285 Flag each fixed point type declaration that lacks an explicit
21286 representation clause to define its @code{'Small} value.
21287 Since @code{'Small} can be defined only for ordinary fixed point types,
21288 decimal fixed point type declarations are not checked.
21290 This rule has no parameters.
21293 @node Improperly_Located_Instantiations
21294 @subsection @code{Improperly_Located_Instantiations}
21295 @cindex @code{Improperly_Located_Instantiations} rule (for @command{gnatcheck})
21298 Flag all generic instantiations in library-level package specs
21299 (including library generic packages) and in all subprogram bodies.
21301 Instantiations in task and entry bodies are not flagged. Instantiations in the
21302 bodies of protected subprograms are flagged.
21304 This rule has no parameters.
21308 @node Improper_Returns
21309 @subsection @code{Improper_Returns}
21310 @cindex @code{Improper_Returns} rule (for @command{gnatcheck})
21313 Flag each explicit @code{return} statement in procedures, and
21314 multiple @code{return} statements in functions.
21315 Diagnostic messages are generated for all @code{return} statements
21316 in a procedure (thus each procedure must be written so that it
21317 returns implicitly at the end of its statement part),
21318 and for all @code{return} statements in a function after the first one.
21319 This rule supports the stylistic convention that each subprogram
21320 should have no more than one point of normal return.
21322 This rule has no parameters.
21325 @node Library_Level_Subprograms
21326 @subsection @code{Library_Level_Subprograms}
21327 @cindex @code{Library_Level_Subprograms} rule (for @command{gnatcheck})
21330 Flag all library-level subprograms (including generic subprogram instantiations).
21332 This rule has no parameters.
21335 @node Local_Packages
21336 @subsection @code{Local_Packages}
21337 @cindex @code{Local_Packages} rule (for @command{gnatcheck})
21340 Flag all local packages declared in package and generic package
21342 Local packages in bodies are not flagged.
21344 This rule has no parameters.
21347 @node Improperly_Called_Protected_Entries
21348 @subsection @code{Improperly_Called_Protected_Entries} (under construction, GLOBAL)
21349 @cindex @code{Improperly_Called_Protected_Entries} rule (for @command{gnatcheck})
21352 Flag each protected entry that can be called from more than one task.
21354 This rule has no parameters.
21358 @subsection @code{Metrics}
21359 @cindex @code{Metrics} rule (for @command{gnatcheck})
21362 There is a set of checks based on computing a metric value and comparing the
21363 result with the specified upper (or lower, depending on a specific metric)
21364 value specified for a given metric. A construct is flagged if a given metric
21365 is applicable (can be computed) for it and the computed value is greater
21366 then (lover then) the specified upper (lower) bound.
21368 The name of any metric-based rule consists of the prefix @code{Metrics_}
21369 followed by the name of the corresponding metric (see the table below).
21370 For @option{+R} option, each metric-based rule has a numeric parameter
21371 specifying the bound (integer or real, depending on a metric), @option{-R}
21372 option for metric rules does not have a parameter.
21374 The following table shows the metric names for that the corresponding
21375 metrics-based checks are supported by gnatcheck, including the
21376 constraint that must be satisfied by the bound that is specified for the check
21377 and what bound - upper (U) or lower (L) - should be specified.
21379 @multitable {@code{Cyclomatic_Complexity}}{Cyclomatic complexity}{Positive integer}
21381 @headitem Check Name @tab Description @tab Bounds Value
21384 @item @b{Check Name} @tab @b{Description} @tab @b{Bounds Value}
21386 @c Above conditional code is workaround to bug in texi2html (Feb 2008)
21387 @item @code{Essential_Complexity} @tab Essential complexity @tab Positive integer (U)
21388 @item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer (U)
21389 @item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer (U)
21393 The meaning and the computed values for all these metrics are exactly
21394 the same as for the corresponding metrics in @command{gnatmetric}.
21396 @emph{Example:} the rule
21398 +RMetrics_Cyclomatic_Complexity : 7
21401 means that all bodies with cyclomatic complexity exceeding 7 will be flagged.
21403 To turn OFF the check for cyclomatic complexity metric, use the following option:
21405 -RMetrics_Cyclomatic_Complexity
21408 @node Misnamed_Identifiers
21409 @subsection @code{Misnamed_Identifiers}
21410 @cindex @code{Misnamed_Identifiers} rule (for @command{gnatcheck})
21413 Flag the declaration of each identifier that does not have a suffix
21414 corresponding to the kind of entity being declared.
21415 The following declarations are checked:
21422 constant declarations (but not number declarations)
21425 package renaming declarations (but not generic package renaming
21430 This rule may have parameters. When used without parameters, the rule enforces
21431 the following checks:
21435 type-defining names end with @code{_T}, unless the type is an access type,
21436 in which case the suffix must be @code{_A}
21438 constant names end with @code{_C}
21440 names defining package renamings end with @code{_R}
21444 For a private or incomplete type declaration the following checks are
21445 made for the defining name suffix:
21449 For an incomplete type declaration: if the corresponding full type
21450 declaration is available, the defining identifier from the full type
21451 declaration is checked, but the defining identifier from the incomplete type
21452 declaration is not; otherwise the defining identifier from the incomplete
21453 type declaration is checked against the suffix specified for type
21457 For a private type declaration (including private extensions), the defining
21458 identifier from the private type declaration is checked against the type
21459 suffix (even if the corresponding full declaration is an access type
21460 declaration), and the defining identifier from the corresponding full type
21461 declaration is not checked.
21465 For a deferred constant, the defining name in the corresponding full constant
21466 declaration is not checked.
21468 Defining names of formal types are not checked.
21470 The rule may have the following parameters:
21474 For the @option{+R} option:
21477 Sets the default listed above for all the names to be checked.
21479 @item Type_Suffix=@emph{string}
21480 Specifies the suffix for a type name.
21482 @item Access_Suffix=@emph{string}
21483 Specifies the suffix for an access type name. If
21484 this parameter is set, it overrides for access
21485 types the suffix set by the @code{Type_Suffix} parameter.
21487 @item Constant_Suffix=@emph{string}
21488 Specifies the suffix for a constant name.
21490 @item Renaming_Suffix=@emph{string}
21491 Specifies the suffix for a package renaming name.
21495 For the @option{-R} option:
21498 Remove all the suffixes specified for the
21499 identifier suffix checks, whether by default or
21500 as specified by other rule parameters. All the
21501 checks for this rule are disabled as a result.
21504 Removes the suffix specified for types. This
21505 disables checks for types but does not disable
21506 any other checks for this rule (including the
21507 check for access type names if @code{Access_Suffix} is
21510 @item Access_Suffix
21511 Removes the suffix specified for access types.
21512 This disables checks for access type names but
21513 does not disable any other checks for this rule.
21514 If @code{Type_Suffix} is set, access type names are
21515 checked as ordinary type names.
21517 @item Constant_Suffix
21518 Removes the suffix specified for constants. This
21519 disables checks for constant names but does not
21520 disable any other checks for this rule.
21522 @item Renaming_Suffix
21523 Removes the suffix specified for package
21524 renamings. This disables checks for package
21525 renamings but does not disable any other checks
21531 If more than one parameter is used, parameters must be separated by commas.
21533 If more than one option is specified for the @command{gnatcheck} invocation,
21534 a new option overrides the previous one(s).
21536 The @option{+RMisnamed_Identifiers} option (with no parameter) enables
21538 name suffixes specified by previous options used for this rule.
21540 The @option{-RMisnamed_Identifiers} option (with no parameter) disables
21541 all the checks but keeps
21542 all the suffixes specified by previous options used for this rule.
21544 The @emph{string} value must be a valid suffix for an Ada identifier (after
21545 trimming all the leading and trailing space characters, if any).
21546 Parameters are not case sensitive, except the @emph{string} part.
21548 If any error is detected in a rule parameter, the parameter is ignored.
21549 In such a case the options that are set for the rule are not
21554 @node Multiple_Entries_In_Protected_Definitions
21555 @subsection @code{Multiple_Entries_In_Protected_Definitions}
21556 @cindex @code{Multiple_Entries_In_Protected_Definitions} rule (for @command{gnatcheck})
21559 Flag each protected definition (i.e., each protected object/type declaration)
21560 that defines more than one entry.
21561 Diagnostic messages are generated for all the entry declarations
21562 except the first one. An entry family is counted as one entry. Entries from
21563 the private part of the protected definition are also checked.
21565 This rule has no parameters.
21568 @subsection @code{Name_Clashes}
21569 @cindex @code{Name_Clashes} rule (for @command{gnatcheck})
21572 Check that certain names are not used as defining identifiers. To activate
21573 this rule, you need to supply a reference to the dictionary file(s) as a rule
21574 parameter(s) (more then one dictionary file can be specified). If no
21575 dictionary file is set, this rule will not cause anything to be flagged.
21576 Only defining occurrences, not references, are checked.
21577 The check is not case-sensitive.
21579 This rule is enabled by default, but without setting any corresponding
21580 dictionary file(s); thus the default effect is to do no checks.
21582 A dictionary file is a plain text file. The maximum line length for this file
21583 is 1024 characters. If the line is longer then this limit, extra characters
21586 Each line can be either an empty line, a comment line, or a line containing
21587 a list of identifiers separated by space or HT characters.
21588 A comment is an Ada-style comment (from @code{--} to end-of-line).
21589 Identifiers must follow the Ada syntax for identifiers.
21590 A line containing one or more identifiers may end with a comment.
21592 @node Non_Qualified_Aggregates
21593 @subsection @code{Non_Qualified_Aggregates}
21594 @cindex @code{Non_Qualified_Aggregates} rule (for @command{gnatcheck})
21597 Flag each non-qualified aggregate.
21598 A non-qualified aggregate is an
21599 aggregate that is not the expression of a qualified expression. A
21600 string literal is not considered an aggregate, but an array
21601 aggregate of a string type is considered as a normal aggregate.
21602 Aggregates of anonymous array types are not flagged.
21604 This rule has no parameters.
21607 @node Non_Short_Circuit_Operators
21608 @subsection @code{Non_Short_Circuit_Operators}
21609 @cindex @code{Non_Short_Circuit_Operators} rule (for @command{gnatcheck})
21612 Flag all calls to predefined @code{and} and @code{or} operators for
21613 any boolean type. Calls to
21614 user-defined @code{and} and @code{or} and to operators defined by renaming
21615 declarations are not flagged. Calls to predefined @code{and} and @code{or}
21616 operators for modular types or boolean array types are not flagged.
21618 This rule has no parameters.
21622 @node Non_SPARK_Attributes
21623 @subsection @code{Non_SPARK_Attributes}
21624 @cindex @code{Non_SPARK_Attributes} rule (for @command{gnatcheck})
21627 The SPARK language defines the following subset of Ada 95 attribute
21628 designators as those that can be used in SPARK programs. The use of
21629 any other attribute is flagged.
21632 @item @code{'Adjacent}
21635 @item @code{'Ceiling}
21636 @item @code{'Component_Size}
21637 @item @code{'Compose}
21638 @item @code{'Copy_Sign}
21639 @item @code{'Delta}
21640 @item @code{'Denorm}
21641 @item @code{'Digits}
21642 @item @code{'Exponent}
21643 @item @code{'First}
21644 @item @code{'Floor}
21646 @item @code{'Fraction}
21648 @item @code{'Leading_Part}
21649 @item @code{'Length}
21650 @item @code{'Machine}
21651 @item @code{'Machine_Emax}
21652 @item @code{'Machine_Emin}
21653 @item @code{'Machine_Mantissa}
21654 @item @code{'Machine_Overflows}
21655 @item @code{'Machine_Radix}
21656 @item @code{'Machine_Rounds}
21659 @item @code{'Model}
21660 @item @code{'Model_Emin}
21661 @item @code{'Model_Epsilon}
21662 @item @code{'Model_Mantissa}
21663 @item @code{'Model_Small}
21664 @item @code{'Modulus}
21667 @item @code{'Range}
21668 @item @code{'Remainder}
21669 @item @code{'Rounding}
21670 @item @code{'Safe_First}
21671 @item @code{'Safe_Last}
21672 @item @code{'Scaling}
21673 @item @code{'Signed_Zeros}
21675 @item @code{'Small}
21677 @item @code{'Truncation}
21678 @item @code{'Unbiased_Rounding}
21680 @item @code{'Valid}
21684 This rule has no parameters.
21687 @node Non_Tagged_Derived_Types
21688 @subsection @code{Non_Tagged_Derived_Types}
21689 @cindex @code{Non_Tagged_Derived_Types} rule (for @command{gnatcheck})
21692 Flag all derived type declarations that do not have a record extension part.
21694 This rule has no parameters.
21698 @node Non_Visible_Exceptions
21699 @subsection @code{Non_Visible_Exceptions}
21700 @cindex @code{Non_Visible_Exceptions} rule (for @command{gnatcheck})
21703 Flag constructs leading to the possibility of propagating an exception
21704 out of the scope in which the exception is declared.
21705 Two cases are detected:
21709 An exception declaration in a subprogram body, task body or block
21710 statement is flagged if the body or statement does not contain a handler for
21711 that exception or a handler with an @code{others} choice.
21714 A @code{raise} statement in an exception handler of a subprogram body,
21715 task body or block statement is flagged if it (re)raises a locally
21716 declared exception. This may occur under the following circumstances:
21719 it explicitly raises a locally declared exception, or
21721 it does not specify an exception name (i.e., it is simply @code{raise;})
21722 and the enclosing handler contains a locally declared exception in its
21728 Renamings of local exceptions are not flagged.
21730 This rule has no parameters.
21733 @node Numeric_Literals
21734 @subsection @code{Numeric_Literals}
21735 @cindex @code{Numeric_Literals} rule (for @command{gnatcheck})
21738 Flag each use of a numeric literal in an index expression, and in any
21739 circumstance except for the following:
21743 a literal occurring in the initialization expression for a constant
21744 declaration or a named number declaration, or
21747 an integer literal that is less than or equal to a value
21748 specified by the @option{N} rule parameter.
21752 This rule may have the following parameters for the @option{+R} option:
21756 @emph{N} is an integer literal used as the maximal value that is not flagged
21757 (i.e., integer literals not exceeding this value are allowed)
21760 All integer literals are flagged
21764 If no parameters are set, the maximum unflagged value is 1.
21766 The last specified check limit (or the fact that there is no limit at
21767 all) is used when multiple @option{+R} options appear.
21769 The @option{-R} option for this rule has no parameters.
21770 It disables the rule but retains the last specified maximum unflagged value.
21771 If the @option{+R} option subsequently appears, this value is used as the
21772 threshold for the check.
21775 @node OTHERS_In_Aggregates
21776 @subsection @code{OTHERS_In_Aggregates}
21777 @cindex @code{OTHERS_In_Aggregates} rule (for @command{gnatcheck})
21780 Flag each use of an @code{others} choice in extension aggregates.
21781 In record and array aggregates, an @code{others} choice is flagged unless
21782 it is used to refer to all components, or to all but one component.
21784 If, in case of a named array aggregate, there are two associations, one
21785 with an @code{others} choice and another with a discrete range, the
21786 @code{others} choice is flagged even if the discrete range specifies
21787 exactly one component; for example, @code{(1..1 => 0, others => 1)}.
21789 This rule has no parameters.
21791 @node OTHERS_In_CASE_Statements
21792 @subsection @code{OTHERS_In_CASE_Statements}
21793 @cindex @code{OTHERS_In_CASE_Statements} rule (for @command{gnatcheck})
21796 Flag any use of an @code{others} choice in a @code{case} statement.
21798 This rule has no parameters.
21800 @node OTHERS_In_Exception_Handlers
21801 @subsection @code{OTHERS_In_Exception_Handlers}
21802 @cindex @code{OTHERS_In_Exception_Handlers} rule (for @command{gnatcheck})
21805 Flag any use of an @code{others} choice in an exception handler.
21807 This rule has no parameters.
21810 @node Outer_Loop_Exits
21811 @subsection @code{Outer_Loop_Exits}
21812 @cindex @code{Outer_Loop_Exits} rule (for @command{gnatcheck})
21815 Flag each @code{exit} statement containing a loop name that is not the name
21816 of the immediately enclosing @code{loop} statement.
21818 This rule has no parameters.
21821 @node Overloaded_Operators
21822 @subsection @code{Overloaded_Operators}
21823 @cindex @code{Overloaded_Operators} rule (for @command{gnatcheck})
21826 Flag each function declaration that overloads an operator symbol.
21827 A function body is checked only if the body does not have a
21828 separate spec. Formal functions are also checked. For a
21829 renaming declaration, only renaming-as-declaration is checked
21831 This rule has no parameters.
21834 @node Overly_Nested_Control_Structures
21835 @subsection @code{Overly_Nested_Control_Structures}
21836 @cindex @code{Overly_Nested_Control_Structures} rule (for @command{gnatcheck})
21839 Flag each control structure whose nesting level exceeds the value provided
21840 in the rule parameter.
21842 The control structures checked are the following:
21845 @item @code{if} statement
21846 @item @code{case} statement
21847 @item @code{loop} statement
21848 @item Selective accept statement
21849 @item Timed entry call statement
21850 @item Conditional entry call
21851 @item Asynchronous select statement
21855 The rule has the following parameter for the @option{+R} option:
21859 Positive integer specifying the maximal control structure nesting
21860 level that is not flagged
21864 If the parameter for the @option{+R} option is not specified or
21865 if it is not a positive integer, @option{+R} option is ignored.
21867 If more then one option is specified for the gnatcheck call, the later option and
21868 new parameter override the previous one(s).
21871 @node Parameters_Out_Of_Order
21872 @subsection @code{Parameters_Out_Of_Order}
21873 @cindex @code{Parameters_Out_Of_Order} rule (for @command{gnatcheck})
21876 Flag each subprogram and entry declaration whose formal parameters are not
21877 ordered according to the following scheme:
21881 @item @code{in} and @code{access} parameters first,
21882 then @code{in out} parameters,
21883 and then @code{out} parameters;
21885 @item for @code{in} mode, parameters with default initialization expressions
21890 Only the first violation of the described order is flagged.
21892 The following constructs are checked:
21895 @item subprogram declarations (including null procedures);
21896 @item generic subprogram declarations;
21897 @item formal subprogram declarations;
21898 @item entry declarations;
21899 @item subprogram bodies and subprogram body stubs that do not
21900 have separate specifications
21904 Subprogram renamings are not checked.
21906 This rule has no parameters.
21909 @node Positional_Actuals_For_Defaulted_Generic_Parameters
21910 @subsection @code{Positional_Actuals_For_Defaulted_Generic_Parameters}
21911 @cindex @code{Positional_Actuals_For_Defaulted_Generic_Parameters} rule (for @command{gnatcheck})
21914 Flag each generic actual parameter corresponding to a generic formal
21915 parameter with a default initialization, if positional notation is used.
21917 This rule has no parameters.
21919 @node Positional_Actuals_For_Defaulted_Parameters
21920 @subsection @code{Positional_Actuals_For_Defaulted_Parameters}
21921 @cindex @code{Positional_Actuals_For_Defaulted_Parameters} rule (for @command{gnatcheck})
21924 Flag each actual parameter to a subprogram or entry call where the
21925 corresponding formal parameter has a default expression, if positional
21928 This rule has no parameters.
21930 @node Positional_Components
21931 @subsection @code{Positional_Components}
21932 @cindex @code{Positional_Components} rule (for @command{gnatcheck})
21935 Flag each array, record and extension aggregate that includes positional
21938 This rule has no parameters.
21941 @node Positional_Generic_Parameters
21942 @subsection @code{Positional_Generic_Parameters}
21943 @cindex @code{Positional_Generic_Parameters} rule (for @command{gnatcheck})
21946 Flag each instantiation using positional parameter notation.
21948 This rule has no parameters.
21951 @node Positional_Parameters
21952 @subsection @code{Positional_Parameters}
21953 @cindex @code{Positional_Parameters} rule (for @command{gnatcheck})
21956 Flag each subprogram or entry call using positional parameter notation,
21957 except for the following:
21961 Invocations of prefix or infix operators are not flagged
21963 If the called subprogram or entry has only one formal parameter,
21964 the call is not flagged;
21966 If a subprogram call uses the @emph{Object.Operation} notation, then
21969 the first parameter (that is, @emph{Object}) is not flagged;
21971 if the called subprogram has only two parameters, the second parameter
21972 of the call is not flagged;
21977 This rule has no parameters.
21982 @node Predefined_Numeric_Types
21983 @subsection @code{Predefined_Numeric_Types}
21984 @cindex @code{Predefined_Numeric_Types} rule (for @command{gnatcheck})
21987 Flag each explicit use of the name of any numeric type or subtype defined
21988 in package @code{Standard}.
21990 The rationale for this rule is to detect when the
21991 program may depend on platform-specific characteristics of the implementation
21992 of the predefined numeric types. Note that this rule is over-pessimistic;
21993 for example, a program that uses @code{String} indexing
21994 likely needs a variable of type @code{Integer}.
21995 Another example is the flagging of predefined numeric types with explicit
21998 @smallexample @c ada
21999 subtype My_Integer is Integer range Left .. Right;
22000 Vy_Var : My_Integer;
22004 This rule detects only numeric types and subtypes defined in
22005 @code{Standard}. The use of numeric types and subtypes defined in other
22006 predefined packages (such as @code{System.Any_Priority} or
22007 @code{Ada.Text_IO.Count}) is not flagged
22009 This rule has no parameters.
22013 @node Raising_External_Exceptions
22014 @subsection @code{Raising_External_Exceptions}
22015 @cindex @code{Raising_External_Exceptions} rule (for @command{gnatcheck})
22018 Flag any @code{raise} statement, in a program unit declared in a library
22019 package or in a generic library package, for an exception that is
22020 neither a predefined exception nor an exception that is also declared (or
22021 renamed) in the visible part of the package.
22023 This rule has no parameters.
22027 @node Raising_Predefined_Exceptions
22028 @subsection @code{Raising_Predefined_Exceptions}
22029 @cindex @code{Raising_Predefined_Exceptions} rule (for @command{gnatcheck})
22032 Flag each @code{raise} statement that raises a predefined exception
22033 (i.e., one of the exceptions @code{Constraint_Error}, @code{Numeric_Error},
22034 @code{Program_Error}, @code{Storage_Error}, or @code{Tasking_Error}).
22036 This rule has no parameters.
22038 @node Separate_Numeric_Error_Handlers
22039 @subsection @code{Separate_Numeric_Error_Handlers}
22040 @cindex @code{Separate_Numeric_Error_Handlers} rule (for @command{gnatcheck})
22043 Flags each exception handler that contains a choice for
22044 the predefined @code{Constraint_Error} exception, but does not contain
22045 the choice for the predefined @code{Numeric_Error} exception, or
22046 that contains the choice for @code{Numeric_Error}, but does not contain the
22047 choice for @code{Constraint_Error}.
22049 This rule has no parameters.
22053 @subsection @code{Recursion} (under construction, GLOBAL)
22054 @cindex @code{Recursion} rule (for @command{gnatcheck})
22057 Flag recursive subprograms (cycles in the call graph). Declarations, and not
22058 calls, of recursive subprograms are detected.
22060 This rule has no parameters.
22064 @node Side_Effect_Functions
22065 @subsection @code{Side_Effect_Functions} (under construction, GLOBAL)
22066 @cindex @code{Side_Effect_Functions} rule (for @command{gnatcheck})
22069 Flag functions with side effects.
22071 We define a side effect as changing any data object that is not local for the
22072 body of this function.
22074 At the moment, we do NOT consider a side effect any input-output operations
22075 (changing a state or a content of any file).
22077 We do not consider protected functions for this rule (???)
22079 There are the following sources of side effect:
22082 @item Explicit (or direct) side-effect:
22086 direct assignment to a non-local variable;
22089 direct call to an entity that is known to change some data object that is
22090 not local for the body of this function (Note, that if F1 calls F2 and F2
22091 does have a side effect, this does not automatically mean that F1 also
22092 have a side effect, because it may be the case that F2 is declared in
22093 F1's body and it changes some data object that is global for F2, but
22097 @item Indirect side-effect:
22100 Subprogram calls implicitly issued by:
22103 computing initialization expressions from type declarations as a part
22104 of object elaboration or allocator evaluation;
22106 computing implicit parameters of subprogram or entry calls or generic
22111 activation of a task that change some non-local data object (directly or
22115 elaboration code of a package that is a result of a package instantiation;
22118 controlled objects;
22121 @item Situations when we can suspect a side-effect, but the full static check
22122 is either impossible or too hard:
22125 assignment to access variables or to the objects pointed by access
22129 call to a subprogram pointed by access-to-subprogram value
22137 This rule has no parameters.
22141 @subsection @code{Slices}
22142 @cindex @code{Slices} rule (for @command{gnatcheck})
22145 Flag all uses of array slicing
22147 This rule has no parameters.
22150 @node Unassigned_OUT_Parameters
22151 @subsection @code{Unassigned_OUT_Parameters}
22152 @cindex @code{Unassigned_OUT_Parameters} rule (for @command{gnatcheck})
22155 Flags procedures' @code{out} parameters that are not assigned, and
22156 identifies the contexts in which the assignments are missing.
22158 An @code{out} parameter is flagged in the statements in the procedure
22159 body's handled sequence of statements (before the procedure body's
22160 @code{exception} part, if any) if this sequence of statements contains
22161 no assignments to the parameter.
22163 An @code{out} parameter is flagged in an exception handler in the exception
22164 part of the procedure body's handled sequence of statements if the handler
22165 contains no assignment to the parameter.
22167 Bodies of generic procedures are also considered.
22169 The following are treated as assignments to an @code{out} parameter:
22173 an assignment statement, with the parameter or some component as the target;
22176 passing the parameter (or one of its components) as an @code{out} or
22177 @code{in out} parameter.
22181 This rule does not have any parameters.
22185 @node Uncommented_BEGIN_In_Package_Bodies
22186 @subsection @code{Uncommented_BEGIN_In_Package_Bodies}
22187 @cindex @code{Uncommented_BEGIN_In_Package_Bodies} rule (for @command{gnatcheck})
22190 Flags each package body with declarations and a statement part that does not
22191 include a trailing comment on the line containing the @code{begin} keyword;
22192 this trailing comment needs to specify the package name and nothing else.
22193 The @code{begin} is not flagged if the package body does not
22194 contain any declarations.
22196 If the @code{begin} keyword is placed on the
22197 same line as the last declaration or the first statement, it is flagged
22198 independently of whether the line contains a trailing comment. The
22199 diagnostic message is attached to the line containing the first statement.
22201 This rule has no parameters.
22204 @node Unconstrained_Array_Returns
22205 @subsection @code{Unconstrained_Array_Returns}
22206 @cindex @code{Unconstrained_Array_Returns} rule (for @command{gnatcheck})
22209 Flag each function returning an unconstrained array. Function declarations,
22210 function bodies (and body stubs) having no separate specifications,
22211 and generic function instantiations are checked.
22212 Generic function declarations, function calls and function renamings are
22215 This rule has no parameters.
22217 @node Universal_Ranges
22218 @subsection @code{Universal_Ranges}
22219 @cindex @code{Universal_Ranges} rule (for @command{gnatcheck})
22222 Flag discrete ranges that are a part of an index constraint, constrained
22223 array definition, or @code{for}-loop parameter specification, and whose bounds
22224 are both of type @i{universal_integer}. Ranges that have at least one
22225 bound of a specific type (such as @code{1 .. N}, where @code{N} is a variable
22226 or an expression of non-universal type) are not flagged.
22228 This rule has no parameters.
22231 @node Unnamed_Blocks_And_Loops
22232 @subsection @code{Unnamed_Blocks_And_Loops}
22233 @cindex @code{Unnamed_Blocks_And_Loops} rule (for @command{gnatcheck})
22236 Flag each unnamed block statement and loop statement.
22238 The rule has no parameters.
22243 @node Unused_Subprograms
22244 @subsection @code{Unused_Subprograms} (under construction, GLOBAL)
22245 @cindex @code{Unused_Subprograms} rule (for @command{gnatcheck})
22248 Flag all unused subprograms.
22250 This rule has no parameters.
22256 @node USE_PACKAGE_Clauses
22257 @subsection @code{USE_PACKAGE_Clauses}
22258 @cindex @code{USE_PACKAGE_Clauses} rule (for @command{gnatcheck})
22261 Flag all @code{use} clauses for packages; @code{use type} clauses are
22264 This rule has no parameters.
22268 @node Volatile_Objects_Without_Address_Clauses
22269 @subsection @code{Volatile_Objects_Without_Address_Clauses}
22270 @cindex @code{Volatile_Objects_Without_Address_Clauses} rule (for @command{gnatcheck})
22273 Flag each volatile object that does not have an address clause.
22275 The following check is made: if the pragma @code{Volatile} is applied to a
22276 data object or to its type, then an address clause must
22277 be supplied for this object.
22279 This rule does not check the components of data objects,
22280 array components that are volatile as a result of the pragma
22281 @code{Volatile_Components}, or objects that are volatile because
22282 they are atomic as a result of pragmas @code{Atomic} or
22283 @code{Atomic_Components}.
22285 Only variable declarations, and not constant declarations, are checked.
22287 This rule has no parameters.
22290 @c *********************************
22291 @node Creating Sample Bodies Using gnatstub
22292 @chapter Creating Sample Bodies Using @command{gnatstub}
22296 @command{gnatstub} creates body stubs, that is, empty but compilable bodies
22297 for library unit declarations.
22299 Note: to invoke @code{gnatstub} with a project file, use the @code{gnat}
22300 driver (see @ref{The GNAT Driver and Project Files}).
22302 To create a body stub, @command{gnatstub} has to compile the library
22303 unit declaration. Therefore, bodies can be created only for legal
22304 library units. Moreover, if a library unit depends semantically upon
22305 units located outside the current directory, you have to provide
22306 the source search path when calling @command{gnatstub}, see the description
22307 of @command{gnatstub} switches below.
22309 By default, all the program unit body stubs generated by @code{gnatstub}
22310 raise the predefined @code{Program_Error} exception, which will catch
22311 accidental calls of generated stubs. This behavior can be changed with
22312 option @option{^--no-exception^/NO_EXCEPTION^} (see below).
22315 * Running gnatstub::
22316 * Switches for gnatstub::
22319 @node Running gnatstub
22320 @section Running @command{gnatstub}
22323 @command{gnatstub} has the command-line interface of the form
22326 $ gnatstub @ovar{switches} @var{filename} @ovar{directory}
22333 is the name of the source file that contains a library unit declaration
22334 for which a body must be created. The file name may contain the path
22336 The file name does not have to follow the GNAT file name conventions. If the
22338 does not follow GNAT file naming conventions, the name of the body file must
22340 explicitly as the value of the @option{^-o^/BODY=^@var{body-name}} option.
22341 If the file name follows the GNAT file naming
22342 conventions and the name of the body file is not provided,
22345 of the body file from the argument file name by replacing the @file{.ads}
22347 with the @file{.adb} suffix.
22350 indicates the directory in which the body stub is to be placed (the default
22355 is an optional sequence of switches as described in the next section
22358 @node Switches for gnatstub
22359 @section Switches for @command{gnatstub}
22365 @cindex @option{^-f^/FULL^} (@command{gnatstub})
22366 If the destination directory already contains a file with the name of the
22368 for the argument spec file, replace it with the generated body stub.
22370 @item ^-hs^/HEADER=SPEC^
22371 @cindex @option{^-hs^/HEADER=SPEC^} (@command{gnatstub})
22372 Put the comment header (i.e., all the comments preceding the
22373 compilation unit) from the source of the library unit declaration
22374 into the body stub.
22376 @item ^-hg^/HEADER=GENERAL^
22377 @cindex @option{^-hg^/HEADER=GENERAL^} (@command{gnatstub})
22378 Put a sample comment header into the body stub.
22380 @item ^--header-file=@var{filename}^/FROM_HEADER_FILE=@var{filename}^
22381 @cindex @option{^--header-file^/FROM_HEADER_FILE=^} (@command{gnatstub})
22382 Use the content of the file as the comment header for a generated body stub.
22386 @cindex @option{-IDIR} (@command{gnatstub})
22388 @cindex @option{-I-} (@command{gnatstub})
22391 @item /NOCURRENT_DIRECTORY
22392 @cindex @option{/NOCURRENT_DIRECTORY} (@command{gnatstub})
22394 ^These switches have ^This switch has^ the same meaning as in calls to
22396 ^They define ^It defines ^ the source search path in the call to
22397 @command{gcc} issued
22398 by @command{gnatstub} to compile an argument source file.
22400 @item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE=^@var{PATH}
22401 @cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@command{gnatstub})
22402 This switch has the same meaning as in calls to @command{gcc}.
22403 It defines the additional configuration file to be passed to the call to
22404 @command{gcc} issued
22405 by @command{gnatstub} to compile an argument source file.
22407 @item ^-gnatyM^/MAX_LINE_LENGTH=^@var{n}
22408 @cindex @option{^-gnatyM^/MAX_LINE_LENGTH^} (@command{gnatstub})
22409 (@var{n} is a non-negative integer). Set the maximum line length in the
22410 body stub to @var{n}; the default is 79. The maximum value that can be
22411 specified is 32767. Note that in the special case of configuration
22412 pragma files, the maximum is always 32767 regardless of whether or
22413 not this switch appears.
22415 @item ^-gnaty^/STYLE_CHECKS=^@var{n}
22416 @cindex @option{^-gnaty^/STYLE_CHECKS=^} (@command{gnatstub})
22417 (@var{n} is a non-negative integer from 1 to 9). Set the indentation level in
22418 the generated body sample to @var{n}.
22419 The default indentation is 3.
22421 @item ^-gnatyo^/ORDERED_SUBPROGRAMS^
22422 @cindex @option{^-gnato^/ORDERED_SUBPROGRAMS^} (@command{gnatstub})
22423 Order local bodies alphabetically. (By default local bodies are ordered
22424 in the same way as the corresponding local specs in the argument spec file.)
22426 @item ^-i^/INDENTATION=^@var{n}
22427 @cindex @option{^-i^/INDENTATION^} (@command{gnatstub})
22428 Same as @option{^-gnaty^/STYLE_CHECKS=^@var{n}}
22430 @item ^-k^/TREE_FILE=SAVE^
22431 @cindex @option{^-k^/TREE_FILE=SAVE^} (@command{gnatstub})
22432 Do not remove the tree file (i.e., the snapshot of the compiler internal
22433 structures used by @command{gnatstub}) after creating the body stub.
22435 @item ^-l^/LINE_LENGTH=^@var{n}
22436 @cindex @option{^-l^/LINE_LENGTH^} (@command{gnatstub})
22437 Same as @option{^-gnatyM^/MAX_LINE_LENGTH=^@var{n}}
22439 @item ^--no-exception^/NO_EXCEPTION^
22440 @cindex @option{^--no-exception^/NO_EXCEPTION^} (@command{gnatstub})
22441 Avoind raising PROGRAM_ERROR in the generated bodies of program unit stubs.
22442 This is not always possible for function stubs.
22444 @item ^-o ^/BODY=^@var{body-name}
22445 @cindex @option{^-o^/BODY^} (@command{gnatstub})
22446 Body file name. This should be set if the argument file name does not
22448 the GNAT file naming
22449 conventions. If this switch is omitted the default name for the body will be
22451 from the argument file name according to the GNAT file naming conventions.
22454 @cindex @option{^-q^/QUIET^} (@command{gnatstub})
22455 Quiet mode: do not generate a confirmation when a body is
22456 successfully created, and do not generate a message when a body is not
22460 @item ^-r^/TREE_FILE=REUSE^
22461 @cindex @option{^-r^/TREE_FILE=REUSE^} (@command{gnatstub})
22462 Reuse the tree file (if it exists) instead of creating it. Instead of
22463 creating the tree file for the library unit declaration, @command{gnatstub}
22464 tries to find it in the current directory and use it for creating
22465 a body. If the tree file is not found, no body is created. This option
22466 also implies @option{^-k^/SAVE^}, whether or not
22467 the latter is set explicitly.
22469 @item ^-t^/TREE_FILE=OVERWRITE^
22470 @cindex @option{^-t^/TREE_FILE=OVERWRITE^} (@command{gnatstub})
22471 Overwrite the existing tree file. If the current directory already
22472 contains the file which, according to the GNAT file naming rules should
22473 be considered as a tree file for the argument source file,
22475 will refuse to create the tree file needed to create a sample body
22476 unless this option is set.
22478 @item ^-v^/VERBOSE^
22479 @cindex @option{^-v^/VERBOSE^} (@command{gnatstub})
22480 Verbose mode: generate version information.
22484 @c *********************************
22485 @node Generating Ada Bindings for C and C++ headers
22486 @chapter Generating Ada Bindings for C and C++ headers
22490 GNAT now comes with a new experimental binding generator for C and C++
22491 headers which is intended to do 95% of the tedious work of generating
22492 Ada specs from C or C++ header files. Note that this still is a work in
22493 progress, not designed to generate 100% correct Ada specs.
22495 The code generated is using the Ada 2005 syntax, which makes it
22496 easier to interface with other languages than previous versions of Ada.
22499 * Running the binding generator::
22500 * Generating bindings for C++ headers::
22504 @node Running the binding generator
22505 @section Running the binding generator
22508 The binding generator is part of the @command{gcc} compiler and can be
22509 invoked via the @option{-fdump-ada-spec} switch, which will generate Ada
22510 spec files for the header files specified on the command line, and all
22511 header files needed by these files transitivitely. For example:
22514 $ g++ -c -fdump-ada-spec -C /usr/include/time.h
22515 $ gcc -c -gnat05 *.ads
22518 will generate, under GNU/Linux, the following files: @file{time_h.ads},
22519 @file{bits_time_h.ads}, @file{stddef_h.ads}, @file{bits_types_h.ads} which
22520 correspond to the files @file{/usr/include/time.h},
22521 @file{/usr/include/bits/time.h}, etc@dots{}, and will then compile in Ada 2005
22522 mode these Ada specs.
22524 The @code{-C} switch tells @command{gcc} to extract comments from headers,
22525 and will attempt to generate corresponding Ada comments.
22527 If you want to generate a single Ada file and not the transitive closure, you
22528 can use instead the @option{-fdump-ada-spec-slim} switch.
22530 Note that we recommend when possible to use the @command{g++} driver to
22531 generate bindings, even for most C headers, since this will in general
22532 generate better Ada specs. For generating bindings for C++ headers, it is
22533 mandatory to use the @command{g++} command, or @command{gcc -x c++} which
22534 is equivalent in this case. If @command{g++} cannot work on your C headers
22535 because of incompatibilities between C and C++, then you can fallback to
22536 @command{gcc} instead.
22538 For an example of better bindings generated from the C++ front-end,
22539 the name of the parameters (when available) are actually ignored by the C
22540 front-end. Consider the following C header:
22543 extern void foo (int variable);
22546 with the C front-end, @code{variable} is ignored, and the above is handled as:
22549 extern void foo (int);
22552 generating a generic:
22555 procedure foo (param1 : int);
22558 with the C++ front-end, the name is available, and we generate:
22561 procedure foo (variable : int);
22564 In some cases, the generated bindings will be more complete or more meaningful
22565 when defining some macros, which you can do via the @option{-D} switch. This
22566 is for example the case with @file{Xlib.h} under GNU/Linux:
22569 g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
22572 The above will generate more complete bindings than a straight call without
22573 the @option{-DXLIB_ILLEGAL_ACCESS} switch.
22575 In other cases, it is not possible to parse a header file in a stand alone
22576 manner, because other include files need to be included first. In this
22577 case, the solution is to create a small header file including the needed
22578 @code{#include} and possible @code{#define} directives. For example, to
22579 generate Ada bindings for @file{readline/readline.h}, you need to first
22580 include @file{stdio.h}, so you can create a file with the following two
22581 lines in e.g. @file{readline1.h}:
22585 #include <readline/readline.h>
22588 and then generate Ada bindings from this file:
22591 $ g++ -c -fdump-ada-spec readline1.h
22594 @node Generating bindings for C++ headers
22595 @section Generating bindings for C++ headers
22598 Generating bindings for C++ headers is done using the same options, always
22599 with the @command{g++} compiler.
22601 In this mode, C++ classes will be mapped to Ada tagged types, constructors
22602 will be mapped using the @code{CPP_Constructor} pragma, and when possible,
22603 multiple inheritance of abstract classes will be mapped to Ada interfaces
22604 (@xref{Interfacing to C++,,,gnat_rm, GNAT Reference Manual}, for additional
22605 information on interfacing to C++).
22607 For example, given the following C++ header file:
22614 virtual int Number_Of_Teeth () = 0;
22619 virtual void Set_Owner (char* Name) = 0;
22625 virtual void Set_Age (int New_Age);
22628 class Dog : Animal, Carnivore, Domestic @{
22633 virtual int Number_Of_Teeth ();
22634 virtual void Set_Owner (char* Name);
22642 The corresponding Ada code is generated:
22644 @smallexample @c ada
22647 package Class_Carnivore is
22648 type Carnivore is limited interface;
22649 pragma Import (CPP, Carnivore);
22651 function Number_Of_Teeth (this : access Carnivore) return int is abstract;
22653 use Class_Carnivore;
22655 package Class_Domestic is
22656 type Domestic is limited interface;
22657 pragma Import (CPP, Domestic);
22659 procedure Set_Owner
22660 (this : access Domestic;
22661 Name : Interfaces.C.Strings.chars_ptr) is abstract;
22663 use Class_Domestic;
22665 package Class_Animal is
22666 type Animal is tagged limited record
22667 Age_Count : aliased int;
22669 pragma Import (CPP, Animal);
22671 procedure Set_Age (this : access Animal; New_Age : int);
22672 pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi");
22676 package Class_Dog is
22677 type Dog is new Animal and Carnivore and Domestic with record
22678 Tooth_Count : aliased int;
22679 Owner : Interfaces.C.Strings.chars_ptr;
22681 pragma Import (CPP, Dog);
22683 function Number_Of_Teeth (this : access Dog) return int;
22684 pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv");
22686 procedure Set_Owner
22687 (this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
22688 pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");
22690 function New_Dog return Dog'Class;
22691 pragma CPP_Constructor (New_Dog);
22692 pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
22703 @item -fdump-ada-spec
22704 @cindex @option{-fdump-ada-spec} (@command{gcc})
22705 Generate Ada spec files for the given header files transitively (including
22706 all header files that these headers depend upon).
22708 @item -fdump-ada-spec-slim
22709 @cindex @option{-fdump-ada-spec-slim} (@command{gcc})
22710 Generate Ada spec files for the header files specified on the command line
22714 @cindex @option{-C} (@command{gcc})
22715 Extract comments from headers and generate Ada comments in the Ada spec files.
22718 @node Other Utility Programs
22719 @chapter Other Utility Programs
22722 This chapter discusses some other utility programs available in the Ada
22726 * Using Other Utility Programs with GNAT::
22727 * The External Symbol Naming Scheme of GNAT::
22728 * Converting Ada Files to html with gnathtml::
22729 * Installing gnathtml::
22736 @node Using Other Utility Programs with GNAT
22737 @section Using Other Utility Programs with GNAT
22740 The object files generated by GNAT are in standard system format and in
22741 particular the debugging information uses this format. This means
22742 programs generated by GNAT can be used with existing utilities that
22743 depend on these formats.
22746 In general, any utility program that works with C will also often work with
22747 Ada programs generated by GNAT. This includes software utilities such as
22748 gprof (a profiling program), @code{gdb} (the FSF debugger), and utilities such
22752 @node The External Symbol Naming Scheme of GNAT
22753 @section The External Symbol Naming Scheme of GNAT
22756 In order to interpret the output from GNAT, when using tools that are
22757 originally intended for use with other languages, it is useful to
22758 understand the conventions used to generate link names from the Ada
22761 All link names are in all lowercase letters. With the exception of library
22762 procedure names, the mechanism used is simply to use the full expanded
22763 Ada name with dots replaced by double underscores. For example, suppose
22764 we have the following package spec:
22766 @smallexample @c ada
22777 The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so
22778 the corresponding link name is @code{qrs__mn}.
22780 Of course if a @code{pragma Export} is used this may be overridden:
22782 @smallexample @c ada
22787 pragma Export (Var1, C, External_Name => "var1_name");
22789 pragma Export (Var2, C, Link_Name => "var2_link_name");
22796 In this case, the link name for @var{Var1} is whatever link name the
22797 C compiler would assign for the C function @var{var1_name}. This typically
22798 would be either @var{var1_name} or @var{_var1_name}, depending on operating
22799 system conventions, but other possibilities exist. The link name for
22800 @var{Var2} is @var{var2_link_name}, and this is not operating system
22804 One exception occurs for library level procedures. A potential ambiguity
22805 arises between the required name @code{_main} for the C main program,
22806 and the name we would otherwise assign to an Ada library level procedure
22807 called @code{Main} (which might well not be the main program).
22809 To avoid this ambiguity, we attach the prefix @code{_ada_} to such
22810 names. So if we have a library level procedure such as
22812 @smallexample @c ada
22815 procedure Hello (S : String);
22821 the external name of this procedure will be @var{_ada_hello}.
22824 @node Converting Ada Files to html with gnathtml
22825 @section Converting Ada Files to HTML with @code{gnathtml}
22828 This @code{Perl} script allows Ada source files to be browsed using
22829 standard Web browsers. For installation procedure, see the section
22830 @xref{Installing gnathtml}.
22832 Ada reserved keywords are highlighted in a bold font and Ada comments in
22833 a blue font. Unless your program was compiled with the gcc @option{-gnatx}
22834 switch to suppress the generation of cross-referencing information, user
22835 defined variables and types will appear in a different color; you will
22836 be able to click on any identifier and go to its declaration.
22838 The command line is as follow:
22840 $ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files}
22844 You can pass it as many Ada files as you want. @code{gnathtml} will generate
22845 an html file for every ada file, and a global file called @file{index.htm}.
22846 This file is an index of every identifier defined in the files.
22848 The available ^switches^options^ are the following ones:
22852 @cindex @option{-83} (@code{gnathtml})
22853 Only the Ada 83 subset of keywords will be highlighted.
22855 @item -cc @var{color}
22856 @cindex @option{-cc} (@code{gnathtml})
22857 This option allows you to change the color used for comments. The default
22858 value is green. The color argument can be any name accepted by html.
22861 @cindex @option{-d} (@code{gnathtml})
22862 If the Ada files depend on some other files (for instance through
22863 @code{with} clauses, the latter files will also be converted to html.
22864 Only the files in the user project will be converted to html, not the files
22865 in the run-time library itself.
22868 @cindex @option{-D} (@code{gnathtml})
22869 This command is the same as @option{-d} above, but @command{gnathtml} will
22870 also look for files in the run-time library, and generate html files for them.
22872 @item -ext @var{extension}
22873 @cindex @option{-ext} (@code{gnathtml})
22874 This option allows you to change the extension of the generated HTML files.
22875 If you do not specify an extension, it will default to @file{htm}.
22878 @cindex @option{-f} (@code{gnathtml})
22879 By default, gnathtml will generate html links only for global entities
22880 ('with'ed units, global variables and types,@dots{}). If you specify
22881 @option{-f} on the command line, then links will be generated for local
22884 @item -l @var{number}
22885 @cindex @option{-l} (@code{gnathtml})
22886 If this ^switch^option^ is provided and @var{number} is not 0, then
22887 @code{gnathtml} will number the html files every @var{number} line.
22890 @cindex @option{-I} (@code{gnathtml})
22891 Specify a directory to search for library files (@file{.ALI} files) and
22892 source files. You can provide several -I switches on the command line,
22893 and the directories will be parsed in the order of the command line.
22896 @cindex @option{-o} (@code{gnathtml})
22897 Specify the output directory for html files. By default, gnathtml will
22898 saved the generated html files in a subdirectory named @file{html/}.
22900 @item -p @var{file}
22901 @cindex @option{-p} (@code{gnathtml})
22902 If you are using Emacs and the most recent Emacs Ada mode, which provides
22903 a full Integrated Development Environment for compiling, checking,
22904 running and debugging applications, you may use @file{.gpr} files
22905 to give the directories where Emacs can find sources and object files.
22907 Using this ^switch^option^, you can tell gnathtml to use these files.
22908 This allows you to get an html version of your application, even if it
22909 is spread over multiple directories.
22911 @item -sc @var{color}
22912 @cindex @option{-sc} (@code{gnathtml})
22913 This ^switch^option^ allows you to change the color used for symbol
22915 The default value is red. The color argument can be any name accepted by html.
22917 @item -t @var{file}
22918 @cindex @option{-t} (@code{gnathtml})
22919 This ^switch^option^ provides the name of a file. This file contains a list of
22920 file names to be converted, and the effect is exactly as though they had
22921 appeared explicitly on the command line. This
22922 is the recommended way to work around the command line length limit on some
22927 @node Installing gnathtml
22928 @section Installing @code{gnathtml}
22931 @code{Perl} needs to be installed on your machine to run this script.
22932 @code{Perl} is freely available for almost every architecture and
22933 Operating System via the Internet.
22935 On Unix systems, you may want to modify the first line of the script
22936 @code{gnathtml}, to explicitly tell the Operating system where Perl
22937 is. The syntax of this line is:
22939 #!full_path_name_to_perl
22943 Alternatively, you may run the script using the following command line:
22946 $ perl gnathtml.pl @ovar{switches} @var{files}
22955 The GNAT distribution provides an Ada 95 template for the HP Language
22956 Sensitive Editor (LSE), a component of DECset. In order to
22957 access it, invoke LSE with the qualifier /ENVIRONMENT=GNU:[LIB]ADA95.ENV.
22964 GNAT supports The HP Performance Coverage Analyzer (PCA), a component
22965 of DECset. To use it proceed as outlined under ``HELP PCA'', except for running
22966 the collection phase with the /DEBUG qualifier.
22969 $ GNAT MAKE /DEBUG <PROGRAM_NAME>
22970 $ DEFINE LIB$DEBUG PCA$COLLECTOR
22971 $ RUN/DEBUG <PROGRAM_NAME>
22977 @c ******************************
22978 @node Code Coverage and Profiling
22979 @chapter Code Coverage and Profiling
22980 @cindex Code Coverage
22984 This chapter describes how to use @code{gcov} - coverage testing tool - and
22985 @code{gprof} - profiler tool - on your Ada programs.
22988 * Code Coverage of Ada Programs using gcov::
22989 * Profiling an Ada Program using gprof::
22992 @node Code Coverage of Ada Programs using gcov
22993 @section Code Coverage of Ada Programs using gcov
22995 @cindex -fprofile-arcs
22996 @cindex -ftest-coverage
22998 @cindex Code Coverage
23001 @code{gcov} is a test coverage program: it analyzes the execution of a given
23002 program on selected tests, to help you determine the portions of the program
23003 that are still untested.
23005 @code{gcov} is part of the GCC suite, and is described in detail in the GCC
23006 User's Guide. You can refer to this documentation for a more complete
23009 This chapter provides a quick startup guide, and
23010 details some Gnat-specific features.
23013 * Quick startup guide::
23017 @node Quick startup guide
23018 @subsection Quick startup guide
23020 In order to perform coverage analysis of a program using @code{gcov}, 3
23025 Code instrumentation during the compilation process
23027 Execution of the instrumented program
23029 Execution of the @code{gcov} tool to generate the result.
23032 The code instrumentation needed by gcov is created at the object level:
23033 The source code is not modified in any way, because the instrumentation code is
23034 inserted by gcc during the compilation process. To compile your code with code
23035 coverage activated, you need to recompile your whole project using the
23037 @code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using
23038 @code{-fprofile-arcs}.
23041 $ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \
23042 -largs -fprofile-arcs
23045 This compilation process will create @file{.gcno} files together with
23046 the usual object files.
23048 Once the program is compiled with coverage instrumentation, you can
23049 run it as many times as needed - on portions of a test suite for
23050 example. The first execution will produce @file{.gcda} files at the
23051 same location as the @file{.gcno} files. The following executions
23052 will update those files, so that a cumulative result of the covered
23053 portions of the program is generated.
23055 Finally, you need to call the @code{gcov} tool. The different options of
23056 @code{gcov} are available in the GCC User's Guide, section 'Invoking gcov'.
23058 This will create annotated source files with a @file{.gcov} extension:
23059 @file{my_main.adb} file will be analysed in @file{my_main.adb.gcov}.
23061 @node Gnat specifics
23062 @subsection Gnat specifics
23064 Because Ada semantics, portions of the source code may be shared among
23065 several object files. This is the case for example when generics are
23066 involved, when inlining is active or when declarations generate initialisation
23067 calls. In order to take
23068 into account this shared code, you need to call @code{gcov} on all
23069 source files of the tested program at once.
23071 The list of source files might exceed the system's maximum command line
23072 length. In order to bypass this limitation, a new mechanism has been
23073 implemented in @code{gcov}: you can now list all your project's files into a
23074 text file, and provide this file to gcov as a parameter, preceded by a @@
23075 (e.g. @samp{gcov @@mysrclist.txt}).
23077 Note that on AIX compiling a static library with @code{-fprofile-arcs} is
23078 not supported as there can be unresolved symbols during the final link.
23080 @node Profiling an Ada Program using gprof
23081 @section Profiling an Ada Program using gprof
23087 This section is not meant to be an exhaustive documentation of @code{gprof}.
23088 Full documentation for it can be found in the GNU Profiler User's Guide
23089 documentation that is part of this GNAT distribution.
23091 Profiling a program helps determine the parts of a program that are executed
23092 most often, and are therefore the most time-consuming.
23094 @code{gprof} is the standard GNU profiling tool; it has been enhanced to
23095 better handle Ada programs and multitasking.
23096 It is currently supported on the following platforms
23101 solaris sparc/sparc64/x86
23107 In order to profile a program using @code{gprof}, 3 steps are needed:
23111 Code instrumentation, requiring a full recompilation of the project with the
23114 Execution of the program under the analysis conditions, i.e. with the desired
23117 Analysis of the results using the @code{gprof} tool.
23121 The following sections detail the different steps, and indicate how
23122 to interpret the results:
23124 * Compilation for profiling::
23125 * Program execution::
23127 * Interpretation of profiling results::
23130 @node Compilation for profiling
23131 @subsection Compilation for profiling
23135 In order to profile a program the first step is to tell the compiler
23136 to generate the necessary profiling information. The compiler switch to be used
23137 is @code{-pg}, which must be added to other compilation switches. This
23138 switch needs to be specified both during compilation and link stages, and can
23139 be specified once when using gnatmake:
23142 gnatmake -f -pg -P my_project
23146 Note that only the objects that were compiled with the @samp{-pg} switch will be
23147 profiled; if you need to profile your whole project, use the
23148 @samp{-f} gnatmake switch to force full recompilation.
23150 @node Program execution
23151 @subsection Program execution
23154 Once the program has been compiled for profiling, you can run it as usual.
23156 The only constraint imposed by profiling is that the program must terminate
23157 normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
23160 Once the program completes execution, a data file called @file{gmon.out} is
23161 generated in the directory where the program was launched from. If this file
23162 already exists, it will be overwritten.
23164 @node Running gprof
23165 @subsection Running gprof
23168 The @code{gprof} tool is called as follow:
23171 gprof my_prog gmon.out
23182 The complete form of the gprof command line is the following:
23185 gprof [^switches^options^] [executable [data-file]]
23189 @code{gprof} supports numerous ^switch^options^. The order of these
23190 ^switch^options^ does not matter. The full list of options can be found in
23191 the GNU Profiler User's Guide documentation that comes with this documentation.
23193 The following is the subset of those switches that is most relevant:
23197 @item --demangle[=@var{style}]
23198 @itemx --no-demangle
23199 @cindex @option{--demangle} (@code{gprof})
23200 These options control whether symbol names should be demangled when
23201 printing output. The default is to demangle C++ symbols. The
23202 @code{--no-demangle} option may be used to turn off demangling. Different
23203 compilers have different mangling styles. The optional demangling style
23204 argument can be used to choose an appropriate demangling style for your
23205 compiler, in particular Ada symbols generated by GNAT can be demangled using
23206 @code{--demangle=gnat}.
23208 @item -e @var{function_name}
23209 @cindex @option{-e} (@code{gprof})
23210 The @samp{-e @var{function}} option tells @code{gprof} not to print
23211 information about the function @var{function_name} (and its
23212 children@dots{}) in the call graph. The function will still be listed
23213 as a child of any functions that call it, but its index number will be
23214 shown as @samp{[not printed]}. More than one @samp{-e} option may be
23215 given; only one @var{function_name} may be indicated with each @samp{-e}
23218 @item -E @var{function_name}
23219 @cindex @option{-E} (@code{gprof})
23220 The @code{-E @var{function}} option works like the @code{-e} option, but
23221 execution time spent in the function (and children who were not called from
23222 anywhere else), will not be used to compute the percentages-of-time for
23223 the call graph. More than one @samp{-E} option may be given; only one
23224 @var{function_name} may be indicated with each @samp{-E} option.
23226 @item -f @var{function_name}
23227 @cindex @option{-f} (@code{gprof})
23228 The @samp{-f @var{function}} option causes @code{gprof} to limit the
23229 call graph to the function @var{function_name} and its children (and
23230 their children@dots{}). More than one @samp{-f} option may be given;
23231 only one @var{function_name} may be indicated with each @samp{-f}
23234 @item -F @var{function_name}
23235 @cindex @option{-F} (@code{gprof})
23236 The @samp{-F @var{function}} option works like the @code{-f} option, but
23237 only time spent in the function and its children (and their
23238 children@dots{}) will be used to determine total-time and
23239 percentages-of-time for the call graph. More than one @samp{-F} option
23240 may be given; only one @var{function_name} may be indicated with each
23241 @samp{-F} option. The @samp{-F} option overrides the @samp{-E} option.
23245 @node Interpretation of profiling results
23246 @subsection Interpretation of profiling results
23250 The results of the profiling analysis are represented by two arrays: the
23251 'flat profile' and the 'call graph'. Full documentation of those outputs
23252 can be found in the GNU Profiler User's Guide.
23254 The flat profile shows the time spent in each function of the program, and how
23255 many time it has been called. This allows you to locate easily the most
23256 time-consuming functions.
23258 The call graph shows, for each subprogram, the subprograms that call it,
23259 and the subprograms that it calls. It also provides an estimate of the time
23260 spent in each of those callers/called subprograms.
23263 @c ******************************
23264 @node Running and Debugging Ada Programs
23265 @chapter Running and Debugging Ada Programs
23269 This chapter discusses how to debug Ada programs.
23271 It applies to GNAT on the Alpha OpenVMS platform;
23272 for I64 OpenVMS please refer to the @cite{OpenVMS Debugger Manual},
23273 since HP has implemented Ada support in the OpenVMS debugger on I64.
23276 An incorrect Ada program may be handled in three ways by the GNAT compiler:
23280 The illegality may be a violation of the static semantics of Ada. In
23281 that case GNAT diagnoses the constructs in the program that are illegal.
23282 It is then a straightforward matter for the user to modify those parts of
23286 The illegality may be a violation of the dynamic semantics of Ada. In
23287 that case the program compiles and executes, but may generate incorrect
23288 results, or may terminate abnormally with some exception.
23291 When presented with a program that contains convoluted errors, GNAT
23292 itself may terminate abnormally without providing full diagnostics on
23293 the incorrect user program.
23297 * The GNAT Debugger GDB::
23299 * Introduction to GDB Commands::
23300 * Using Ada Expressions::
23301 * Calling User-Defined Subprograms::
23302 * Using the Next Command in a Function::
23305 * Debugging Generic Units::
23306 * GNAT Abnormal Termination or Failure to Terminate::
23307 * Naming Conventions for GNAT Source Files::
23308 * Getting Internal Debugging Information::
23309 * Stack Traceback::
23315 @node The GNAT Debugger GDB
23316 @section The GNAT Debugger GDB
23319 @code{GDB} is a general purpose, platform-independent debugger that
23320 can be used to debug mixed-language programs compiled with @command{gcc},
23321 and in particular is capable of debugging Ada programs compiled with
23322 GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
23323 complex Ada data structures.
23325 @xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
23327 located in the GNU:[DOCS] directory,
23329 for full details on the usage of @code{GDB}, including a section on
23330 its usage on programs. This manual should be consulted for full
23331 details. The section that follows is a brief introduction to the
23332 philosophy and use of @code{GDB}.
23334 When GNAT programs are compiled, the compiler optionally writes debugging
23335 information into the generated object file, including information on
23336 line numbers, and on declared types and variables. This information is
23337 separate from the generated code. It makes the object files considerably
23338 larger, but it does not add to the size of the actual executable that
23339 will be loaded into memory, and has no impact on run-time performance. The
23340 generation of debug information is triggered by the use of the
23341 ^-g^/DEBUG^ switch in the @command{gcc} or @command{gnatmake} command
23342 used to carry out the compilations. It is important to emphasize that
23343 the use of these options does not change the generated code.
23345 The debugging information is written in standard system formats that
23346 are used by many tools, including debuggers and profilers. The format
23347 of the information is typically designed to describe C types and
23348 semantics, but GNAT implements a translation scheme which allows full
23349 details about Ada types and variables to be encoded into these
23350 standard C formats. Details of this encoding scheme may be found in
23351 the file exp_dbug.ads in the GNAT source distribution. However, the
23352 details of this encoding are, in general, of no interest to a user,
23353 since @code{GDB} automatically performs the necessary decoding.
23355 When a program is bound and linked, the debugging information is
23356 collected from the object files, and stored in the executable image of
23357 the program. Again, this process significantly increases the size of
23358 the generated executable file, but it does not increase the size of
23359 the executable program itself. Furthermore, if this program is run in
23360 the normal manner, it runs exactly as if the debug information were
23361 not present, and takes no more actual memory.
23363 However, if the program is run under control of @code{GDB}, the
23364 debugger is activated. The image of the program is loaded, at which
23365 point it is ready to run. If a run command is given, then the program
23366 will run exactly as it would have if @code{GDB} were not present. This
23367 is a crucial part of the @code{GDB} design philosophy. @code{GDB} is
23368 entirely non-intrusive until a breakpoint is encountered. If no
23369 breakpoint is ever hit, the program will run exactly as it would if no
23370 debugger were present. When a breakpoint is hit, @code{GDB} accesses
23371 the debugging information and can respond to user commands to inspect
23372 variables, and more generally to report on the state of execution.
23376 @section Running GDB
23379 This section describes how to initiate the debugger.
23380 @c The above sentence is really just filler, but it was otherwise
23381 @c clumsy to get the first paragraph nonindented given the conditional
23382 @c nature of the description
23385 The debugger can be launched from a @code{GPS} menu or
23386 directly from the command line. The description below covers the latter use.
23387 All the commands shown can be used in the @code{GPS} debug console window,
23388 but there are usually more GUI-based ways to achieve the same effect.
23391 The command to run @code{GDB} is
23394 $ ^gdb program^GDB PROGRAM^
23398 where @code{^program^PROGRAM^} is the name of the executable file. This
23399 activates the debugger and results in a prompt for debugger commands.
23400 The simplest command is simply @code{run}, which causes the program to run
23401 exactly as if the debugger were not present. The following section
23402 describes some of the additional commands that can be given to @code{GDB}.
23404 @c *******************************
23405 @node Introduction to GDB Commands
23406 @section Introduction to GDB Commands
23409 @code{GDB} contains a large repertoire of commands. @xref{Top,,
23410 Debugging with GDB, gdb, Debugging with GDB},
23412 located in the GNU:[DOCS] directory,
23414 for extensive documentation on the use
23415 of these commands, together with examples of their use. Furthermore,
23416 the command @command{help} invoked from within GDB activates a simple help
23417 facility which summarizes the available commands and their options.
23418 In this section we summarize a few of the most commonly
23419 used commands to give an idea of what @code{GDB} is about. You should create
23420 a simple program with debugging information and experiment with the use of
23421 these @code{GDB} commands on the program as you read through the
23425 @item set args @var{arguments}
23426 The @var{arguments} list above is a list of arguments to be passed to
23427 the program on a subsequent run command, just as though the arguments
23428 had been entered on a normal invocation of the program. The @code{set args}
23429 command is not needed if the program does not require arguments.
23432 The @code{run} command causes execution of the program to start from
23433 the beginning. If the program is already running, that is to say if
23434 you are currently positioned at a breakpoint, then a prompt will ask
23435 for confirmation that you want to abandon the current execution and
23438 @item breakpoint @var{location}
23439 The breakpoint command sets a breakpoint, that is to say a point at which
23440 execution will halt and @code{GDB} will await further
23441 commands. @var{location} is
23442 either a line number within a file, given in the format @code{file:linenumber},
23443 or it is the name of a subprogram. If you request that a breakpoint be set on
23444 a subprogram that is overloaded, a prompt will ask you to specify on which of
23445 those subprograms you want to breakpoint. You can also
23446 specify that all of them should be breakpointed. If the program is run
23447 and execution encounters the breakpoint, then the program
23448 stops and @code{GDB} signals that the breakpoint was encountered by
23449 printing the line of code before which the program is halted.
23451 @item breakpoint exception @var{name}
23452 A special form of the breakpoint command which breakpoints whenever
23453 exception @var{name} is raised.
23454 If @var{name} is omitted,
23455 then a breakpoint will occur when any exception is raised.
23457 @item print @var{expression}
23458 This will print the value of the given expression. Most simple
23459 Ada expression formats are properly handled by @code{GDB}, so the expression
23460 can contain function calls, variables, operators, and attribute references.
23463 Continues execution following a breakpoint, until the next breakpoint or the
23464 termination of the program.
23467 Executes a single line after a breakpoint. If the next statement
23468 is a subprogram call, execution continues into (the first statement of)
23469 the called subprogram.
23472 Executes a single line. If this line is a subprogram call, executes and
23473 returns from the call.
23476 Lists a few lines around the current source location. In practice, it
23477 is usually more convenient to have a separate edit window open with the
23478 relevant source file displayed. Successive applications of this command
23479 print subsequent lines. The command can be given an argument which is a
23480 line number, in which case it displays a few lines around the specified one.
23483 Displays a backtrace of the call chain. This command is typically
23484 used after a breakpoint has occurred, to examine the sequence of calls that
23485 leads to the current breakpoint. The display includes one line for each
23486 activation record (frame) corresponding to an active subprogram.
23489 At a breakpoint, @code{GDB} can display the values of variables local
23490 to the current frame. The command @code{up} can be used to
23491 examine the contents of other active frames, by moving the focus up
23492 the stack, that is to say from callee to caller, one frame at a time.
23495 Moves the focus of @code{GDB} down from the frame currently being
23496 examined to the frame of its callee (the reverse of the previous command),
23498 @item frame @var{n}
23499 Inspect the frame with the given number. The value 0 denotes the frame
23500 of the current breakpoint, that is to say the top of the call stack.
23505 The above list is a very short introduction to the commands that
23506 @code{GDB} provides. Important additional capabilities, including conditional
23507 breakpoints, the ability to execute command sequences on a breakpoint,
23508 the ability to debug at the machine instruction level and many other
23509 features are described in detail in @ref{Top,, Debugging with GDB, gdb,
23510 Debugging with GDB}. Note that most commands can be abbreviated
23511 (for example, c for continue, bt for backtrace).
23513 @node Using Ada Expressions
23514 @section Using Ada Expressions
23515 @cindex Ada expressions
23518 @code{GDB} supports a fairly large subset of Ada expression syntax, with some
23519 extensions. The philosophy behind the design of this subset is
23523 That @code{GDB} should provide basic literals and access to operations for
23524 arithmetic, dereferencing, field selection, indexing, and subprogram calls,
23525 leaving more sophisticated computations to subprograms written into the
23526 program (which therefore may be called from @code{GDB}).
23529 That type safety and strict adherence to Ada language restrictions
23530 are not particularly important to the @code{GDB} user.
23533 That brevity is important to the @code{GDB} user.
23537 Thus, for brevity, the debugger acts as if there were
23538 implicit @code{with} and @code{use} clauses in effect for all user-written
23539 packages, thus making it unnecessary to fully qualify most names with
23540 their packages, regardless of context. Where this causes ambiguity,
23541 @code{GDB} asks the user's intent.
23543 For details on the supported Ada syntax, see @ref{Top,, Debugging with
23544 GDB, gdb, Debugging with GDB}.
23546 @node Calling User-Defined Subprograms
23547 @section Calling User-Defined Subprograms
23550 An important capability of @code{GDB} is the ability to call user-defined
23551 subprograms while debugging. This is achieved simply by entering
23552 a subprogram call statement in the form:
23555 call subprogram-name (parameters)
23559 The keyword @code{call} can be omitted in the normal case where the
23560 @code{subprogram-name} does not coincide with any of the predefined
23561 @code{GDB} commands.
23563 The effect is to invoke the given subprogram, passing it the
23564 list of parameters that is supplied. The parameters can be expressions and
23565 can include variables from the program being debugged. The
23566 subprogram must be defined
23567 at the library level within your program, and @code{GDB} will call the
23568 subprogram within the environment of your program execution (which
23569 means that the subprogram is free to access or even modify variables
23570 within your program).
23572 The most important use of this facility is in allowing the inclusion of
23573 debugging routines that are tailored to particular data structures
23574 in your program. Such debugging routines can be written to provide a suitably
23575 high-level description of an abstract type, rather than a low-level dump
23576 of its physical layout. After all, the standard
23577 @code{GDB print} command only knows the physical layout of your
23578 types, not their abstract meaning. Debugging routines can provide information
23579 at the desired semantic level and are thus enormously useful.
23581 For example, when debugging GNAT itself, it is crucial to have access to
23582 the contents of the tree nodes used to represent the program internally.
23583 But tree nodes are represented simply by an integer value (which in turn
23584 is an index into a table of nodes).
23585 Using the @code{print} command on a tree node would simply print this integer
23586 value, which is not very useful. But the PN routine (defined in file
23587 treepr.adb in the GNAT sources) takes a tree node as input, and displays
23588 a useful high level representation of the tree node, which includes the
23589 syntactic category of the node, its position in the source, the integers
23590 that denote descendant nodes and parent node, as well as varied
23591 semantic information. To study this example in more detail, you might want to
23592 look at the body of the PN procedure in the stated file.
23594 @node Using the Next Command in a Function
23595 @section Using the Next Command in a Function
23598 When you use the @code{next} command in a function, the current source
23599 location will advance to the next statement as usual. A special case
23600 arises in the case of a @code{return} statement.
23602 Part of the code for a return statement is the ``epilog'' of the function.
23603 This is the code that returns to the caller. There is only one copy of
23604 this epilog code, and it is typically associated with the last return
23605 statement in the function if there is more than one return. In some
23606 implementations, this epilog is associated with the first statement
23609 The result is that if you use the @code{next} command from a return
23610 statement that is not the last return statement of the function you
23611 may see a strange apparent jump to the last return statement or to
23612 the start of the function. You should simply ignore this odd jump.
23613 The value returned is always that from the first return statement
23614 that was stepped through.
23616 @node Ada Exceptions
23617 @section Breaking on Ada Exceptions
23621 You can set breakpoints that trip when your program raises
23622 selected exceptions.
23625 @item break exception
23626 Set a breakpoint that trips whenever (any task in the) program raises
23629 @item break exception @var{name}
23630 Set a breakpoint that trips whenever (any task in the) program raises
23631 the exception @var{name}.
23633 @item break exception unhandled
23634 Set a breakpoint that trips whenever (any task in the) program raises an
23635 exception for which there is no handler.
23637 @item info exceptions
23638 @itemx info exceptions @var{regexp}
23639 The @code{info exceptions} command permits the user to examine all defined
23640 exceptions within Ada programs. With a regular expression, @var{regexp}, as
23641 argument, prints out only those exceptions whose name matches @var{regexp}.
23649 @code{GDB} allows the following task-related commands:
23653 This command shows a list of current Ada tasks, as in the following example:
23660 ID TID P-ID Thread Pri State Name
23661 1 8088000 0 807e000 15 Child Activation Wait main_task
23662 2 80a4000 1 80ae000 15 Accept/Select Wait b
23663 3 809a800 1 80a4800 15 Child Activation Wait a
23664 * 4 80ae800 3 80b8000 15 Running c
23668 In this listing, the asterisk before the first task indicates it to be the
23669 currently running task. The first column lists the task ID that is used
23670 to refer to tasks in the following commands.
23672 @item break @var{linespec} task @var{taskid}
23673 @itemx break @var{linespec} task @var{taskid} if @dots{}
23674 @cindex Breakpoints and tasks
23675 These commands are like the @code{break @dots{} thread @dots{}}.
23676 @var{linespec} specifies source lines.
23678 Use the qualifier @samp{task @var{taskid}} with a breakpoint command
23679 to specify that you only want @code{GDB} to stop the program when a
23680 particular Ada task reaches this breakpoint. @var{taskid} is one of the
23681 numeric task identifiers assigned by @code{GDB}, shown in the first
23682 column of the @samp{info tasks} display.
23684 If you do not specify @samp{task @var{taskid}} when you set a
23685 breakpoint, the breakpoint applies to @emph{all} tasks of your
23688 You can use the @code{task} qualifier on conditional breakpoints as
23689 well; in this case, place @samp{task @var{taskid}} before the
23690 breakpoint condition (before the @code{if}).
23692 @item task @var{taskno}
23693 @cindex Task switching
23695 This command allows to switch to the task referred by @var{taskno}. In
23696 particular, This allows to browse the backtrace of the specified
23697 task. It is advised to switch back to the original task before
23698 continuing execution otherwise the scheduling of the program may be
23703 For more detailed information on the tasking support,
23704 see @ref{Top,, Debugging with GDB, gdb, Debugging with GDB}.
23706 @node Debugging Generic Units
23707 @section Debugging Generic Units
23708 @cindex Debugging Generic Units
23712 GNAT always uses code expansion for generic instantiation. This means that
23713 each time an instantiation occurs, a complete copy of the original code is
23714 made, with appropriate substitutions of formals by actuals.
23716 It is not possible to refer to the original generic entities in
23717 @code{GDB}, but it is always possible to debug a particular instance of
23718 a generic, by using the appropriate expanded names. For example, if we have
23720 @smallexample @c ada
23725 generic package k is
23726 procedure kp (v1 : in out integer);
23730 procedure kp (v1 : in out integer) is
23736 package k1 is new k;
23737 package k2 is new k;
23739 var : integer := 1;
23752 Then to break on a call to procedure kp in the k2 instance, simply
23756 (gdb) break g.k2.kp
23760 When the breakpoint occurs, you can step through the code of the
23761 instance in the normal manner and examine the values of local variables, as for
23764 @node GNAT Abnormal Termination or Failure to Terminate
23765 @section GNAT Abnormal Termination or Failure to Terminate
23766 @cindex GNAT Abnormal Termination or Failure to Terminate
23769 When presented with programs that contain serious errors in syntax
23771 GNAT may on rare occasions experience problems in operation, such
23773 segmentation fault or illegal memory access, raising an internal
23774 exception, terminating abnormally, or failing to terminate at all.
23775 In such cases, you can activate
23776 various features of GNAT that can help you pinpoint the construct in your
23777 program that is the likely source of the problem.
23779 The following strategies are presented in increasing order of
23780 difficulty, corresponding to your experience in using GNAT and your
23781 familiarity with compiler internals.
23785 Run @command{gcc} with the @option{-gnatf}. This first
23786 switch causes all errors on a given line to be reported. In its absence,
23787 only the first error on a line is displayed.
23789 The @option{-gnatdO} switch causes errors to be displayed as soon as they
23790 are encountered, rather than after compilation is terminated. If GNAT
23791 terminates prematurely or goes into an infinite loop, the last error
23792 message displayed may help to pinpoint the culprit.
23795 Run @command{gcc} with the @option{^-v (verbose)^/VERBOSE^} switch. In this
23796 mode, @command{gcc} produces ongoing information about the progress of the
23797 compilation and provides the name of each procedure as code is
23798 generated. This switch allows you to find which Ada procedure was being
23799 compiled when it encountered a code generation problem.
23802 @cindex @option{-gnatdc} switch
23803 Run @command{gcc} with the @option{-gnatdc} switch. This is a GNAT specific
23804 switch that does for the front-end what @option{^-v^VERBOSE^} does
23805 for the back end. The system prints the name of each unit,
23806 either a compilation unit or nested unit, as it is being analyzed.
23808 Finally, you can start
23809 @code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the
23810 front-end of GNAT, and can be run independently (normally it is just
23811 called from @command{gcc}). You can use @code{gdb} on @code{gnat1} as you
23812 would on a C program (but @pxref{The GNAT Debugger GDB} for caveats). The
23813 @code{where} command is the first line of attack; the variable
23814 @code{lineno} (seen by @code{print lineno}), used by the second phase of
23815 @code{gnat1} and by the @command{gcc} backend, indicates the source line at
23816 which the execution stopped, and @code{input_file name} indicates the name of
23820 @node Naming Conventions for GNAT Source Files
23821 @section Naming Conventions for GNAT Source Files
23824 In order to examine the workings of the GNAT system, the following
23825 brief description of its organization may be helpful:
23829 Files with prefix @file{^sc^SC^} contain the lexical scanner.
23832 All files prefixed with @file{^par^PAR^} are components of the parser. The
23833 numbers correspond to chapters of the Ada Reference Manual. For example,
23834 parsing of select statements can be found in @file{par-ch9.adb}.
23837 All files prefixed with @file{^sem^SEM^} perform semantic analysis. The
23838 numbers correspond to chapters of the Ada standard. For example, all
23839 issues involving context clauses can be found in @file{sem_ch10.adb}. In
23840 addition, some features of the language require sufficient special processing
23841 to justify their own semantic files: sem_aggr for aggregates, sem_disp for
23842 dynamic dispatching, etc.
23845 All files prefixed with @file{^exp^EXP^} perform normalization and
23846 expansion of the intermediate representation (abstract syntax tree, or AST).
23847 these files use the same numbering scheme as the parser and semantics files.
23848 For example, the construction of record initialization procedures is done in
23849 @file{exp_ch3.adb}.
23852 The files prefixed with @file{^bind^BIND^} implement the binder, which
23853 verifies the consistency of the compilation, determines an order of
23854 elaboration, and generates the bind file.
23857 The files @file{atree.ads} and @file{atree.adb} detail the low-level
23858 data structures used by the front-end.
23861 The files @file{sinfo.ads} and @file{sinfo.adb} detail the structure of
23862 the abstract syntax tree as produced by the parser.
23865 The files @file{einfo.ads} and @file{einfo.adb} detail the attributes of
23866 all entities, computed during semantic analysis.
23869 Library management issues are dealt with in files with prefix
23875 Ada files with the prefix @file{^a-^A-^} are children of @code{Ada}, as
23876 defined in Annex A.
23881 Files with prefix @file{^i-^I-^} are children of @code{Interfaces}, as
23882 defined in Annex B.
23886 Files with prefix @file{^s-^S-^} are children of @code{System}. This includes
23887 both language-defined children and GNAT run-time routines.
23891 Files with prefix @file{^g-^G-^} are children of @code{GNAT}. These are useful
23892 general-purpose packages, fully documented in their specs. All
23893 the other @file{.c} files are modifications of common @command{gcc} files.
23896 @node Getting Internal Debugging Information
23897 @section Getting Internal Debugging Information
23900 Most compilers have internal debugging switches and modes. GNAT
23901 does also, except GNAT internal debugging switches and modes are not
23902 secret. A summary and full description of all the compiler and binder
23903 debug flags are in the file @file{debug.adb}. You must obtain the
23904 sources of the compiler to see the full detailed effects of these flags.
23906 The switches that print the source of the program (reconstructed from
23907 the internal tree) are of general interest for user programs, as are the
23909 the full internal tree, and the entity table (the symbol table
23910 information). The reconstructed source provides a readable version of the
23911 program after the front-end has completed analysis and expansion,
23912 and is useful when studying the performance of specific constructs.
23913 For example, constraint checks are indicated, complex aggregates
23914 are replaced with loops and assignments, and tasking primitives
23915 are replaced with run-time calls.
23917 @node Stack Traceback
23918 @section Stack Traceback
23920 @cindex stack traceback
23921 @cindex stack unwinding
23924 Traceback is a mechanism to display the sequence of subprogram calls that
23925 leads to a specified execution point in a program. Often (but not always)
23926 the execution point is an instruction at which an exception has been raised.
23927 This mechanism is also known as @i{stack unwinding} because it obtains
23928 its information by scanning the run-time stack and recovering the activation
23929 records of all active subprograms. Stack unwinding is one of the most
23930 important tools for program debugging.
23932 The first entry stored in traceback corresponds to the deepest calling level,
23933 that is to say the subprogram currently executing the instruction
23934 from which we want to obtain the traceback.
23936 Note that there is no runtime performance penalty when stack traceback
23937 is enabled, and no exception is raised during program execution.
23940 * Non-Symbolic Traceback::
23941 * Symbolic Traceback::
23944 @node Non-Symbolic Traceback
23945 @subsection Non-Symbolic Traceback
23946 @cindex traceback, non-symbolic
23949 Note: this feature is not supported on all platforms. See
23950 @file{GNAT.Traceback spec in g-traceb.ads} for a complete list of supported
23954 * Tracebacks From an Unhandled Exception::
23955 * Tracebacks From Exception Occurrences (non-symbolic)::
23956 * Tracebacks From Anywhere in a Program (non-symbolic)::
23959 @node Tracebacks From an Unhandled Exception
23960 @subsubsection Tracebacks From an Unhandled Exception
23963 A runtime non-symbolic traceback is a list of addresses of call instructions.
23964 To enable this feature you must use the @option{-E}
23965 @code{gnatbind}'s option. With this option a stack traceback is stored as part
23966 of exception information. You can retrieve this information using the
23967 @code{addr2line} tool.
23969 Here is a simple example:
23971 @smallexample @c ada
23977 raise Constraint_Error;
23992 $ gnatmake stb -bargs -E
23995 Execution terminated by unhandled exception
23996 Exception name: CONSTRAINT_ERROR
23998 Call stack traceback locations:
23999 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
24003 As we see the traceback lists a sequence of addresses for the unhandled
24004 exception @code{CONSTRAINT_ERROR} raised in procedure P1. It is easy to
24005 guess that this exception come from procedure P1. To translate these
24006 addresses into the source lines where the calls appear, the
24007 @code{addr2line} tool, described below, is invaluable. The use of this tool
24008 requires the program to be compiled with debug information.
24011 $ gnatmake -g stb -bargs -E
24014 Execution terminated by unhandled exception
24015 Exception name: CONSTRAINT_ERROR
24017 Call stack traceback locations:
24018 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
24020 $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4
24021 0x4011f1 0x77e892a4
24023 00401373 at d:/stb/stb.adb:5
24024 0040138B at d:/stb/stb.adb:10
24025 0040139C at d:/stb/stb.adb:14
24026 00401335 at d:/stb/b~stb.adb:104
24027 004011C4 at /build/@dots{}/crt1.c:200
24028 004011F1 at /build/@dots{}/crt1.c:222
24029 77E892A4 in ?? at ??:0
24033 The @code{addr2line} tool has several other useful options:
24037 to get the function name corresponding to any location
24039 @item --demangle=gnat
24040 to use the gnat decoding mode for the function names. Note that
24041 for binutils version 2.9.x the option is simply @option{--demangle}.
24045 $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b
24046 0x40139c 0x401335 0x4011c4 0x4011f1
24048 00401373 in stb.p1 at d:/stb/stb.adb:5
24049 0040138B in stb.p2 at d:/stb/stb.adb:10
24050 0040139C in stb at d:/stb/stb.adb:14
24051 00401335 in main at d:/stb/b~stb.adb:104
24052 004011C4 in <__mingw_CRTStartup> at /build/@dots{}/crt1.c:200
24053 004011F1 in <mainCRTStartup> at /build/@dots{}/crt1.c:222
24057 From this traceback we can see that the exception was raised in
24058 @file{stb.adb} at line 5, which was reached from a procedure call in
24059 @file{stb.adb} at line 10, and so on. The @file{b~std.adb} is the binder file,
24060 which contains the call to the main program.
24061 @xref{Running gnatbind}. The remaining entries are assorted runtime routines,
24062 and the output will vary from platform to platform.
24064 It is also possible to use @code{GDB} with these traceback addresses to debug
24065 the program. For example, we can break at a given code location, as reported
24066 in the stack traceback:
24072 Furthermore, this feature is not implemented inside Windows DLL. Only
24073 the non-symbolic traceback is reported in this case.
24076 (gdb) break *0x401373
24077 Breakpoint 1 at 0x401373: file stb.adb, line 5.
24081 It is important to note that the stack traceback addresses
24082 do not change when debug information is included. This is particularly useful
24083 because it makes it possible to release software without debug information (to
24084 minimize object size), get a field report that includes a stack traceback
24085 whenever an internal bug occurs, and then be able to retrieve the sequence
24086 of calls with the same program compiled with debug information.
24088 @node Tracebacks From Exception Occurrences (non-symbolic)
24089 @subsubsection Tracebacks From Exception Occurrences
24092 Non-symbolic tracebacks are obtained by using the @option{-E} binder argument.
24093 The stack traceback is attached to the exception information string, and can
24094 be retrieved in an exception handler within the Ada program, by means of the
24095 Ada facilities defined in @code{Ada.Exceptions}. Here is a simple example:
24097 @smallexample @c ada
24099 with Ada.Exceptions;
24104 use Ada.Exceptions;
24112 Text_IO.Put_Line (Exception_Information (E));
24126 This program will output:
24131 Exception name: CONSTRAINT_ERROR
24132 Message: stb.adb:12
24133 Call stack traceback locations:
24134 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4
24137 @node Tracebacks From Anywhere in a Program (non-symbolic)
24138 @subsubsection Tracebacks From Anywhere in a Program
24141 It is also possible to retrieve a stack traceback from anywhere in a
24142 program. For this you need to
24143 use the @code{GNAT.Traceback} API. This package includes a procedure called
24144 @code{Call_Chain} that computes a complete stack traceback, as well as useful
24145 display procedures described below. It is not necessary to use the
24146 @option{-E gnatbind} option in this case, because the stack traceback mechanism
24147 is invoked explicitly.
24150 In the following example we compute a traceback at a specific location in
24151 the program, and we display it using @code{GNAT.Debug_Utilities.Image} to
24152 convert addresses to strings:
24154 @smallexample @c ada
24156 with GNAT.Traceback;
24157 with GNAT.Debug_Utilities;
24163 use GNAT.Traceback;
24166 TB : Tracebacks_Array (1 .. 10);
24167 -- We are asking for a maximum of 10 stack frames.
24169 -- Len will receive the actual number of stack frames returned.
24171 Call_Chain (TB, Len);
24173 Text_IO.Put ("In STB.P1 : ");
24175 for K in 1 .. Len loop
24176 Text_IO.Put (Debug_Utilities.Image (TB (K)));
24197 In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C#
24198 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4#
24202 You can then get further information by invoking the @code{addr2line}
24203 tool as described earlier (note that the hexadecimal addresses
24204 need to be specified in C format, with a leading ``0x'').
24206 @node Symbolic Traceback
24207 @subsection Symbolic Traceback
24208 @cindex traceback, symbolic
24211 A symbolic traceback is a stack traceback in which procedure names are
24212 associated with each code location.
24215 Note that this feature is not supported on all platforms. See
24216 @file{GNAT.Traceback.Symbolic spec in g-trasym.ads} for a complete
24217 list of currently supported platforms.
24220 Note that the symbolic traceback requires that the program be compiled
24221 with debug information. If it is not compiled with debug information
24222 only the non-symbolic information will be valid.
24225 * Tracebacks From Exception Occurrences (symbolic)::
24226 * Tracebacks From Anywhere in a Program (symbolic)::
24229 @node Tracebacks From Exception Occurrences (symbolic)
24230 @subsubsection Tracebacks From Exception Occurrences
24232 @smallexample @c ada
24234 with GNAT.Traceback.Symbolic;
24240 raise Constraint_Error;
24257 Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E));
24262 $ gnatmake -g .\stb -bargs -E -largs -lgnat -laddr2line -lintl
24265 0040149F in stb.p1 at stb.adb:8
24266 004014B7 in stb.p2 at stb.adb:13
24267 004014CF in stb.p3 at stb.adb:18
24268 004015DD in ada.stb at stb.adb:22
24269 00401461 in main at b~stb.adb:168
24270 004011C4 in __mingw_CRTStartup at crt1.c:200
24271 004011F1 in mainCRTStartup at crt1.c:222
24272 77E892A4 in ?? at ??:0
24276 In the above example the ``.\'' syntax in the @command{gnatmake} command
24277 is currently required by @command{addr2line} for files that are in
24278 the current working directory.
24279 Moreover, the exact sequence of linker options may vary from platform
24281 The above @option{-largs} section is for Windows platforms. By contrast,
24282 under Unix there is no need for the @option{-largs} section.
24283 Differences across platforms are due to details of linker implementation.
24285 @node Tracebacks From Anywhere in a Program (symbolic)
24286 @subsubsection Tracebacks From Anywhere in a Program
24289 It is possible to get a symbolic stack traceback
24290 from anywhere in a program, just as for non-symbolic tracebacks.
24291 The first step is to obtain a non-symbolic
24292 traceback, and then call @code{Symbolic_Traceback} to compute the symbolic
24293 information. Here is an example:
24295 @smallexample @c ada
24297 with GNAT.Traceback;
24298 with GNAT.Traceback.Symbolic;
24303 use GNAT.Traceback;
24304 use GNAT.Traceback.Symbolic;
24307 TB : Tracebacks_Array (1 .. 10);
24308 -- We are asking for a maximum of 10 stack frames.
24310 -- Len will receive the actual number of stack frames returned.
24312 Call_Chain (TB, Len);
24313 Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len)));
24326 @c ******************************
24328 @node Compatibility with HP Ada
24329 @chapter Compatibility with HP Ada
24330 @cindex Compatibility
24335 @cindex Compatibility between GNAT and HP Ada
24336 This chapter compares HP Ada (formerly known as ``DEC Ada'')
24337 for OpenVMS Alpha and GNAT for OpenVMS for Alpha and for I64.
24338 GNAT is highly compatible
24339 with HP Ada, and it should generally be straightforward to port code
24340 from the HP Ada environment to GNAT. However, there are a few language
24341 and implementation differences of which the user must be aware. These
24342 differences are discussed in this chapter. In
24343 addition, the operating environment and command structure for the
24344 compiler are different, and these differences are also discussed.
24346 For further details on these and other compatibility issues,
24347 see Appendix E of the HP publication
24348 @cite{HP Ada, Technical Overview and Comparison on HP Platforms}.
24350 Except where otherwise indicated, the description of GNAT for OpenVMS
24351 applies to both the Alpha and I64 platforms.
24353 For information on porting Ada code from GNAT on Alpha OpenVMS to GNAT on
24354 I64 OpenVMS, see @ref{Transitioning to 64-Bit GNAT for OpenVMS}.
24356 The discussion in this chapter addresses specifically the implementation
24357 of Ada 83 for HP OpenVMS Alpha Systems. In cases where the implementation
24358 of HP Ada differs between OpenVMS Alpha Systems and OpenVMS VAX Systems,
24359 GNAT always follows the Alpha implementation.
24361 For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
24362 attributes are recognized, although only a subset of them can sensibly
24363 be implemented. The description of pragmas in
24364 @xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
24365 indicates whether or not they are applicable to non-VMS systems.
24368 * Ada Language Compatibility::
24369 * Differences in the Definition of Package System::
24370 * Language-Related Features::
24371 * The Package STANDARD::
24372 * The Package SYSTEM::
24373 * Tasking and Task-Related Features::
24374 * Pragmas and Pragma-Related Features::
24375 * Library of Predefined Units::
24377 * Main Program Definition::
24378 * Implementation-Defined Attributes::
24379 * Compiler and Run-Time Interfacing::
24380 * Program Compilation and Library Management::
24382 * Implementation Limits::
24383 * Tools and Utilities::
24386 @node Ada Language Compatibility
24387 @section Ada Language Compatibility
24390 GNAT handles Ada 95 and Ada 2005 as well as Ada 83, whereas HP Ada is only
24391 for Ada 83. Ada 95 and Ada 2005 are almost completely upwards compatible
24392 with Ada 83, and therefore Ada 83 programs will compile
24393 and run under GNAT with
24394 no changes or only minor changes. The @cite{Annotated Ada Reference Manual}
24395 provides details on specific incompatibilities.
24397 GNAT provides the switch @option{/83} on the @command{GNAT COMPILE} command,
24398 as well as the pragma @code{ADA_83}, to force the compiler to
24399 operate in Ada 83 mode. This mode does not guarantee complete
24400 conformance to Ada 83, but in practice is sufficient to
24401 eliminate most sources of incompatibilities.
24402 In particular, it eliminates the recognition of the
24403 additional Ada 95 and Ada 2005 keywords, so that their use as identifiers
24404 in Ada 83 programs is legal, and handles the cases of packages
24405 with optional bodies, and generics that instantiate unconstrained
24406 types without the use of @code{(<>)}.
24408 @node Differences in the Definition of Package System
24409 @section Differences in the Definition of Package @code{System}
24412 An Ada compiler is allowed to add
24413 implementation-dependent declarations to package @code{System}.
24415 GNAT does not take advantage of this permission, and the version of
24416 @code{System} provided by GNAT exactly matches that defined in the Ada
24419 However, HP Ada adds an extensive set of declarations to package
24421 as fully documented in the HP Ada manuals. To minimize changes required
24422 for programs that make use of these extensions, GNAT provides the pragma
24423 @code{Extend_System} for extending the definition of package System. By using:
24424 @cindex pragma @code{Extend_System}
24425 @cindex @code{Extend_System} pragma
24427 @smallexample @c ada
24430 pragma Extend_System (Aux_DEC);
24436 the set of definitions in @code{System} is extended to include those in
24437 package @code{System.Aux_DEC}.
24438 @cindex @code{System.Aux_DEC} package
24439 @cindex @code{Aux_DEC} package (child of @code{System})
24440 These definitions are incorporated directly into package @code{System},
24441 as though they had been declared there. For a
24442 list of the declarations added, see the spec of this package,
24443 which can be found in the file @file{s-auxdec.ads} in the GNAT library.
24444 @cindex @file{s-auxdec.ads} file
24445 The pragma @code{Extend_System} is a configuration pragma, which means that
24446 it can be placed in the file @file{gnat.adc}, so that it will automatically
24447 apply to all subsequent compilations. See @ref{Configuration Pragmas},
24448 for further details.
24450 An alternative approach that avoids the use of the non-standard
24451 @code{Extend_System} pragma is to add a context clause to the unit that
24452 references these facilities:
24454 @smallexample @c ada
24456 with System.Aux_DEC;
24457 use System.Aux_DEC;
24462 The effect is not quite semantically identical to incorporating
24463 the declarations directly into package @code{System},
24464 but most programs will not notice a difference
24465 unless they use prefix notation (e.g.@: @code{System.Integer_8})
24466 to reference the entities directly in package @code{System}.
24467 For units containing such references,
24468 the prefixes must either be removed, or the pragma @code{Extend_System}
24471 @node Language-Related Features
24472 @section Language-Related Features
24475 The following sections highlight differences in types,
24476 representations of types, operations, alignment, and
24480 * Integer Types and Representations::
24481 * Floating-Point Types and Representations::
24482 * Pragmas Float_Representation and Long_Float::
24483 * Fixed-Point Types and Representations::
24484 * Record and Array Component Alignment::
24485 * Address Clauses::
24486 * Other Representation Clauses::
24489 @node Integer Types and Representations
24490 @subsection Integer Types and Representations
24493 The set of predefined integer types is identical in HP Ada and GNAT.
24494 Furthermore the representation of these integer types is also identical,
24495 including the capability of size clauses forcing biased representation.
24498 HP Ada for OpenVMS Alpha systems has defined the
24499 following additional integer types in package @code{System}:
24516 @code{LARGEST_INTEGER}
24520 In GNAT, the first four of these types may be obtained from the
24521 standard Ada package @code{Interfaces}.
24522 Alternatively, by use of the pragma @code{Extend_System}, identical
24523 declarations can be referenced directly in package @code{System}.
24524 On both GNAT and HP Ada, the maximum integer size is 64 bits.
24526 @node Floating-Point Types and Representations
24527 @subsection Floating-Point Types and Representations
24528 @cindex Floating-Point types
24531 The set of predefined floating-point types is identical in HP Ada and GNAT.
24532 Furthermore the representation of these floating-point
24533 types is also identical. One important difference is that the default
24534 representation for HP Ada is @code{VAX_Float}, but the default representation
24537 Specific types may be declared to be @code{VAX_Float} or IEEE, using the
24538 pragma @code{Float_Representation} as described in the HP Ada
24540 For example, the declarations:
24542 @smallexample @c ada
24544 type F_Float is digits 6;
24545 pragma Float_Representation (VAX_Float, F_Float);
24550 declares a type @code{F_Float} that will be represented in @code{VAX_Float}
24552 This set of declarations actually appears in @code{System.Aux_DEC},
24554 the full set of additional floating-point declarations provided in
24555 the HP Ada version of package @code{System}.
24556 This and similar declarations may be accessed in a user program
24557 by using pragma @code{Extend_System}. The use of this
24558 pragma, and the related pragma @code{Long_Float} is described in further
24559 detail in the following section.
24561 @node Pragmas Float_Representation and Long_Float
24562 @subsection Pragmas @code{Float_Representation} and @code{Long_Float}
24565 HP Ada provides the pragma @code{Float_Representation}, which
24566 acts as a program library switch to allow control over
24567 the internal representation chosen for the predefined
24568 floating-point types declared in the package @code{Standard}.
24569 The format of this pragma is as follows:
24571 @smallexample @c ada
24573 pragma Float_Representation(VAX_Float | IEEE_Float);
24578 This pragma controls the representation of floating-point
24583 @code{VAX_Float} specifies that floating-point
24584 types are represented by default with the VAX system hardware types
24585 @code{F-floating}, @code{D-floating}, @code{G-floating}.
24586 Note that the @code{H-floating}
24587 type was available only on VAX systems, and is not available
24588 in either HP Ada or GNAT.
24591 @code{IEEE_Float} specifies that floating-point
24592 types are represented by default with the IEEE single and
24593 double floating-point types.
24597 GNAT provides an identical implementation of the pragma
24598 @code{Float_Representation}, except that it functions as a
24599 configuration pragma. Note that the
24600 notion of configuration pragma corresponds closely to the
24601 HP Ada notion of a program library switch.
24603 When no pragma is used in GNAT, the default is @code{IEEE_Float},
24605 from HP Ada 83, where the default is @code{VAX_Float}. In addition, the
24606 predefined libraries in GNAT are built using @code{IEEE_Float}, so it is not
24607 advisable to change the format of numbers passed to standard library
24608 routines, and if necessary explicit type conversions may be needed.
24610 The use of @code{IEEE_Float} is recommended in GNAT since it is more
24611 efficient, and (given that it conforms to an international standard)
24612 potentially more portable.
24613 The situation in which @code{VAX_Float} may be useful is in interfacing
24614 to existing code and data that expect the use of @code{VAX_Float}.
24615 In such a situation use the predefined @code{VAX_Float}
24616 types in package @code{System}, as extended by
24617 @code{Extend_System}. For example, use @code{System.F_Float}
24618 to specify the 32-bit @code{F-Float} format.
24621 On OpenVMS systems, HP Ada provides the pragma @code{Long_Float}
24622 to allow control over the internal representation chosen
24623 for the predefined type @code{Long_Float} and for floating-point
24624 type declarations with digits specified in the range 7 .. 15.
24625 The format of this pragma is as follows:
24627 @smallexample @c ada
24629 pragma Long_Float (D_FLOAT | G_FLOAT);
24633 @node Fixed-Point Types and Representations
24634 @subsection Fixed-Point Types and Representations
24637 On HP Ada for OpenVMS Alpha systems, rounding is
24638 away from zero for both positive and negative numbers.
24639 Therefore, @code{+0.5} rounds to @code{1},
24640 and @code{-0.5} rounds to @code{-1}.
24642 On GNAT the results of operations
24643 on fixed-point types are in accordance with the Ada
24644 rules. In particular, results of operations on decimal
24645 fixed-point types are truncated.
24647 @node Record and Array Component Alignment
24648 @subsection Record and Array Component Alignment
24651 On HP Ada for OpenVMS Alpha, all non-composite components
24652 are aligned on natural boundaries. For example, 1-byte
24653 components are aligned on byte boundaries, 2-byte
24654 components on 2-byte boundaries, 4-byte components on 4-byte
24655 byte boundaries, and so on. The OpenVMS Alpha hardware
24656 runs more efficiently with naturally aligned data.
24658 On GNAT, alignment rules are compatible
24659 with HP Ada for OpenVMS Alpha.
24661 @node Address Clauses
24662 @subsection Address Clauses
24665 In HP Ada and GNAT, address clauses are supported for
24666 objects and imported subprograms.
24667 The predefined type @code{System.Address} is a private type
24668 in both compilers on Alpha OpenVMS, with the same representation
24669 (it is simply a machine pointer). Addition, subtraction, and comparison
24670 operations are available in the standard Ada package
24671 @code{System.Storage_Elements}, or in package @code{System}
24672 if it is extended to include @code{System.Aux_DEC} using a
24673 pragma @code{Extend_System} as previously described.
24675 Note that code that @code{with}'s both this extended package @code{System}
24676 and the package @code{System.Storage_Elements} should not @code{use}
24677 both packages, or ambiguities will result. In general it is better
24678 not to mix these two sets of facilities. The Ada package was
24679 designed specifically to provide the kind of features that HP Ada
24680 adds directly to package @code{System}.
24682 The type @code{System.Address} is a 64-bit integer type in GNAT for
24683 I64 OpenVMS. For more information,
24684 see @ref{Transitioning to 64-Bit GNAT for OpenVMS}.
24686 GNAT is compatible with HP Ada in its handling of address
24687 clauses, except for some limitations in
24688 the form of address clauses for composite objects with
24689 initialization. Such address clauses are easily replaced
24690 by the use of an explicitly-defined constant as described
24691 in the Ada Reference Manual (13.1(22)). For example, the sequence
24694 @smallexample @c ada
24696 X, Y : Integer := Init_Func;
24697 Q : String (X .. Y) := "abc";
24699 for Q'Address use Compute_Address;
24704 will be rejected by GNAT, since the address cannot be computed at the time
24705 that @code{Q} is declared. To achieve the intended effect, write instead:
24707 @smallexample @c ada
24710 X, Y : Integer := Init_Func;
24711 Q_Address : constant Address := Compute_Address;
24712 Q : String (X .. Y) := "abc";
24714 for Q'Address use Q_Address;
24720 which will be accepted by GNAT (and other Ada compilers), and is also
24721 compatible with Ada 83. A fuller description of the restrictions
24722 on address specifications is found in @ref{Top, GNAT Reference Manual,
24723 About This Guide, gnat_rm, GNAT Reference Manual}.
24725 @node Other Representation Clauses
24726 @subsection Other Representation Clauses
24729 GNAT implements in a compatible manner all the representation
24730 clauses supported by HP Ada. In addition, GNAT
24731 implements the representation clause forms that were introduced in Ada 95,
24732 including @code{COMPONENT_SIZE} and @code{SIZE} clauses for objects.
24734 @node The Package STANDARD
24735 @section The Package @code{STANDARD}
24738 The package @code{STANDARD}, as implemented by HP Ada, is fully
24739 described in the @cite{Ada Reference Manual} and in the
24740 @cite{HP Ada Language Reference Manual}. As implemented by GNAT, the
24741 package @code{STANDARD} is described in the @cite{Ada Reference Manual}.
24743 In addition, HP Ada supports the Latin-1 character set in
24744 the type @code{CHARACTER}. GNAT supports the Latin-1 character set
24745 in the type @code{CHARACTER} and also Unicode (ISO 10646 BMP) in
24746 the type @code{WIDE_CHARACTER}.
24748 The floating-point types supported by GNAT are those
24749 supported by HP Ada, but the defaults are different, and are controlled by
24750 pragmas. See @ref{Floating-Point Types and Representations}, for details.
24752 @node The Package SYSTEM
24753 @section The Package @code{SYSTEM}
24756 HP Ada provides a specific version of the package
24757 @code{SYSTEM} for each platform on which the language is implemented.
24758 For the complete spec of the package @code{SYSTEM}, see
24759 Appendix F of the @cite{HP Ada Language Reference Manual}.
24761 On HP Ada, the package @code{SYSTEM} includes the following conversion
24764 @item @code{TO_ADDRESS(INTEGER)}
24766 @item @code{TO_ADDRESS(UNSIGNED_LONGWORD)}
24768 @item @code{TO_ADDRESS(}@i{universal_integer}@code{)}
24770 @item @code{TO_INTEGER(ADDRESS)}
24772 @item @code{TO_UNSIGNED_LONGWORD(ADDRESS)}
24774 @item Function @code{IMPORT_VALUE return UNSIGNED_LONGWORD} and the
24775 functions @code{IMPORT_ADDRESS} and @code{IMPORT_LARGEST_VALUE}
24779 By default, GNAT supplies a version of @code{SYSTEM} that matches
24780 the definition given in the @cite{Ada Reference Manual}.
24782 is a subset of the HP system definitions, which is as
24783 close as possible to the original definitions. The only difference
24784 is that the definition of @code{SYSTEM_NAME} is different:
24786 @smallexample @c ada
24788 type Name is (SYSTEM_NAME_GNAT);
24789 System_Name : constant Name := SYSTEM_NAME_GNAT;
24794 Also, GNAT adds the Ada declarations for
24795 @code{BIT_ORDER} and @code{DEFAULT_BIT_ORDER}.
24797 However, the use of the following pragma causes GNAT
24798 to extend the definition of package @code{SYSTEM} so that it
24799 encompasses the full set of HP-specific extensions,
24800 including the functions listed above:
24802 @smallexample @c ada
24804 pragma Extend_System (Aux_DEC);
24809 The pragma @code{Extend_System} is a configuration pragma that
24810 is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma
24811 Extend_System,,, gnat_rm, GNAT Reference Manual} for further details.
24813 HP Ada does not allow the recompilation of the package
24814 @code{SYSTEM}. Instead HP Ada provides several pragmas
24815 (@code{SYSTEM_NAME}, @code{STORAGE_UNIT}, and @code{MEMORY_SIZE})
24816 to modify values in the package @code{SYSTEM}.
24817 On OpenVMS Alpha systems, the pragma
24818 @code{SYSTEM_NAME} takes the enumeration literal @code{OPENVMS_AXP} as
24819 its single argument.
24821 GNAT does permit the recompilation of package @code{SYSTEM} using
24822 the special switch @option{-gnatg}, and this switch can be used if
24823 it is necessary to modify the definitions in @code{SYSTEM}. GNAT does
24824 not permit the specification of @code{SYSTEM_NAME}, @code{STORAGE_UNIT}
24825 or @code{MEMORY_SIZE} by any other means.
24827 On GNAT systems, the pragma @code{SYSTEM_NAME} takes the
24828 enumeration literal @code{SYSTEM_NAME_GNAT}.
24830 The definitions provided by the use of
24832 @smallexample @c ada
24833 pragma Extend_System (AUX_Dec);
24837 are virtually identical to those provided by the HP Ada 83 package
24838 @code{SYSTEM}. One important difference is that the name of the
24840 function for type @code{UNSIGNED_LONGWORD} is changed to
24841 @code{TO_ADDRESS_LONG}.
24842 @xref{Address Clauses,,, gnat_rm, GNAT Reference Manual} for a
24843 discussion of why this change was necessary.
24846 The version of @code{TO_ADDRESS} taking a @i{universal_integer} argument
24848 an extension to Ada 83 not strictly compatible with the reference manual.
24849 GNAT, in order to be exactly compatible with the standard,
24850 does not provide this capability. In HP Ada 83, the
24851 point of this definition is to deal with a call like:
24853 @smallexample @c ada
24854 TO_ADDRESS (16#12777#);
24858 Normally, according to Ada 83 semantics, one would expect this to be
24859 ambiguous, since it matches both the @code{INTEGER} and
24860 @code{UNSIGNED_LONGWORD} forms of @code{TO_ADDRESS}.
24861 However, in HP Ada 83, there is no ambiguity, since the
24862 definition using @i{universal_integer} takes precedence.
24864 In GNAT, since the version with @i{universal_integer} cannot be supplied,
24866 not possible to be 100% compatible. Since there are many programs using
24867 numeric constants for the argument to @code{TO_ADDRESS}, the decision in
24869 to change the name of the function in the @code{UNSIGNED_LONGWORD} case,
24870 so the declarations provided in the GNAT version of @code{AUX_Dec} are:
24872 @smallexample @c ada
24873 function To_Address (X : Integer) return Address;
24874 pragma Pure_Function (To_Address);
24876 function To_Address_Long (X : Unsigned_Longword) return Address;
24877 pragma Pure_Function (To_Address_Long);
24881 This means that programs using @code{TO_ADDRESS} for
24882 @code{UNSIGNED_LONGWORD} must change the name to @code{TO_ADDRESS_LONG}.
24884 @node Tasking and Task-Related Features
24885 @section Tasking and Task-Related Features
24888 This section compares the treatment of tasking in GNAT
24889 and in HP Ada for OpenVMS Alpha.
24890 The GNAT description applies to both Alpha and I64 OpenVMS.
24891 For detailed information on tasking in
24892 HP Ada, see the @cite{HP Ada Language Reference Manual} and the
24893 relevant run-time reference manual.
24896 * Implementation of Tasks in HP Ada for OpenVMS Alpha Systems::
24897 * Assigning Task IDs::
24898 * Task IDs and Delays::
24899 * Task-Related Pragmas::
24900 * Scheduling and Task Priority::
24902 * External Interrupts::
24905 @node Implementation of Tasks in HP Ada for OpenVMS Alpha Systems
24906 @subsection Implementation of Tasks in HP Ada for OpenVMS Alpha Systems
24909 On OpenVMS Alpha systems, each Ada task (except a passive
24910 task) is implemented as a single stream of execution
24911 that is created and managed by the kernel. On these
24912 systems, HP Ada tasking support is based on DECthreads,
24913 an implementation of the POSIX standard for threads.
24915 Also, on OpenVMS Alpha systems, HP Ada tasks and foreign
24916 code that calls DECthreads routines can be used together.
24917 The interaction between Ada tasks and DECthreads routines
24918 can have some benefits. For example when on OpenVMS Alpha,
24919 HP Ada can call C code that is already threaded.
24921 GNAT uses the facilities of DECthreads,
24922 and Ada tasks are mapped to threads.
24924 @node Assigning Task IDs
24925 @subsection Assigning Task IDs
24928 The HP Ada Run-Time Library always assigns @code{%TASK 1} to
24929 the environment task that executes the main program. On
24930 OpenVMS Alpha systems, @code{%TASK 0} is often used for tasks
24931 that have been created but are not yet activated.
24933 On OpenVMS Alpha systems, task IDs are assigned at
24934 activation. On GNAT systems, task IDs are also assigned at
24935 task creation but do not have the same form or values as
24936 task ID values in HP Ada. There is no null task, and the
24937 environment task does not have a specific task ID value.
24939 @node Task IDs and Delays
24940 @subsection Task IDs and Delays
24943 On OpenVMS Alpha systems, tasking delays are implemented
24944 using Timer System Services. The Task ID is used for the
24945 identification of the timer request (the @code{REQIDT} parameter).
24946 If Timers are used in the application take care not to use
24947 @code{0} for the identification, because cancelling such a timer
24948 will cancel all timers and may lead to unpredictable results.
24950 @node Task-Related Pragmas
24951 @subsection Task-Related Pragmas
24954 Ada supplies the pragma @code{TASK_STORAGE}, which allows
24955 specification of the size of the guard area for a task
24956 stack. (The guard area forms an area of memory that has no
24957 read or write access and thus helps in the detection of
24958 stack overflow.) On OpenVMS Alpha systems, if the pragma
24959 @code{TASK_STORAGE} specifies a value of zero, a minimal guard
24960 area is created. In the absence of a pragma @code{TASK_STORAGE},
24961 a default guard area is created.
24963 GNAT supplies the following task-related pragmas:
24966 @item @code{TASK_INFO}
24968 This pragma appears within a task definition and
24969 applies to the task in which it appears. The argument
24970 must be of type @code{SYSTEM.TASK_INFO.TASK_INFO_TYPE}.
24972 @item @code{TASK_STORAGE}
24974 GNAT implements pragma @code{TASK_STORAGE} in the same way as HP Ada.
24975 Both HP Ada and GNAT supply the pragmas @code{PASSIVE},
24976 @code{SUPPRESS}, and @code{VOLATILE}.
24978 @node Scheduling and Task Priority
24979 @subsection Scheduling and Task Priority
24982 HP Ada implements the Ada language requirement that
24983 when two tasks are eligible for execution and they have
24984 different priorities, the lower priority task does not
24985 execute while the higher priority task is waiting. The HP
24986 Ada Run-Time Library keeps a task running until either the
24987 task is suspended or a higher priority task becomes ready.
24989 On OpenVMS Alpha systems, the default strategy is round-
24990 robin with preemption. Tasks of equal priority take turns
24991 at the processor. A task is run for a certain period of
24992 time and then placed at the tail of the ready queue for
24993 its priority level.
24995 HP Ada provides the implementation-defined pragma @code{TIME_SLICE},
24996 which can be used to enable or disable round-robin
24997 scheduling of tasks with the same priority.
24998 See the relevant HP Ada run-time reference manual for
24999 information on using the pragmas to control HP Ada task
25002 GNAT follows the scheduling rules of Annex D (Real-Time
25003 Annex) of the @cite{Ada Reference Manual}. In general, this
25004 scheduling strategy is fully compatible with HP Ada
25005 although it provides some additional constraints (as
25006 fully documented in Annex D).
25007 GNAT implements time slicing control in a manner compatible with
25008 HP Ada 83, by means of the pragma @code{Time_Slice}, whose semantics
25009 are identical to the HP Ada 83 pragma of the same name.
25010 Note that it is not possible to mix GNAT tasking and
25011 HP Ada 83 tasking in the same program, since the two run-time
25012 libraries are not compatible.
25014 @node The Task Stack
25015 @subsection The Task Stack
25018 In HP Ada, a task stack is allocated each time a
25019 non-passive task is activated. As soon as the task is
25020 terminated, the storage for the task stack is deallocated.
25021 If you specify a size of zero (bytes) with @code{T'STORAGE_SIZE},
25022 a default stack size is used. Also, regardless of the size
25023 specified, some additional space is allocated for task
25024 management purposes. On OpenVMS Alpha systems, at least
25025 one page is allocated.
25027 GNAT handles task stacks in a similar manner. In accordance with
25028 the Ada rules, it provides the pragma @code{STORAGE_SIZE} as
25029 an alternative method for controlling the task stack size.
25030 The specification of the attribute @code{T'STORAGE_SIZE} is also
25031 supported in a manner compatible with HP Ada.
25033 @node External Interrupts
25034 @subsection External Interrupts
25037 On HP Ada, external interrupts can be associated with task entries.
25038 GNAT is compatible with HP Ada in its handling of external interrupts.
25040 @node Pragmas and Pragma-Related Features
25041 @section Pragmas and Pragma-Related Features
25044 Both HP Ada and GNAT supply all language-defined pragmas
25045 as specified by the Ada 83 standard. GNAT also supplies all
25046 language-defined pragmas introduced by Ada 95 and Ada 2005.
25047 In addition, GNAT implements the implementation-defined pragmas
25051 @item @code{AST_ENTRY}
25053 @item @code{COMMON_OBJECT}
25055 @item @code{COMPONENT_ALIGNMENT}
25057 @item @code{EXPORT_EXCEPTION}
25059 @item @code{EXPORT_FUNCTION}
25061 @item @code{EXPORT_OBJECT}
25063 @item @code{EXPORT_PROCEDURE}
25065 @item @code{EXPORT_VALUED_PROCEDURE}
25067 @item @code{FLOAT_REPRESENTATION}
25071 @item @code{IMPORT_EXCEPTION}
25073 @item @code{IMPORT_FUNCTION}
25075 @item @code{IMPORT_OBJECT}
25077 @item @code{IMPORT_PROCEDURE}
25079 @item @code{IMPORT_VALUED_PROCEDURE}
25081 @item @code{INLINE_GENERIC}
25083 @item @code{INTERFACE_NAME}
25085 @item @code{LONG_FLOAT}
25087 @item @code{MAIN_STORAGE}
25089 @item @code{PASSIVE}
25091 @item @code{PSECT_OBJECT}
25093 @item @code{SHARE_GENERIC}
25095 @item @code{SUPPRESS_ALL}
25097 @item @code{TASK_STORAGE}
25099 @item @code{TIME_SLICE}
25105 These pragmas are all fully implemented, with the exception of @code{TITLE},
25106 @code{PASSIVE}, and @code{SHARE_GENERIC}, which are
25107 recognized, but which have no
25108 effect in GNAT. The effect of @code{PASSIVE} may be obtained by the
25109 use of Ada protected objects. In GNAT, all generics are inlined.
25111 Unlike HP Ada, the GNAT ``@code{EXPORT_}@i{subprogram}'' pragmas require
25112 a separate subprogram specification which must appear before the
25115 GNAT also supplies a number of implementation-defined pragmas as follows:
25117 @item @code{ABORT_DEFER}
25119 @item @code{ADA_83}
25121 @item @code{ADA_95}
25123 @item @code{ADA_05}
25125 @item @code{ANNOTATE}
25127 @item @code{ASSERT}
25129 @item @code{C_PASS_BY_COPY}
25131 @item @code{CPP_CLASS}
25133 @item @code{CPP_CONSTRUCTOR}
25135 @item @code{CPP_DESTRUCTOR}
25139 @item @code{EXTEND_SYSTEM}
25141 @item @code{LINKER_ALIAS}
25143 @item @code{LINKER_SECTION}
25145 @item @code{MACHINE_ATTRIBUTE}
25147 @item @code{NO_RETURN}
25149 @item @code{PURE_FUNCTION}
25151 @item @code{SOURCE_FILE_NAME}
25153 @item @code{SOURCE_REFERENCE}
25155 @item @code{TASK_INFO}
25157 @item @code{UNCHECKED_UNION}
25159 @item @code{UNIMPLEMENTED_UNIT}
25161 @item @code{UNIVERSAL_DATA}
25163 @item @code{UNSUPPRESS}
25165 @item @code{WARNINGS}
25167 @item @code{WEAK_EXTERNAL}
25171 For full details on these GNAT implementation-defined pragmas,
25172 see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
25176 * Restrictions on the Pragma INLINE::
25177 * Restrictions on the Pragma INTERFACE::
25178 * Restrictions on the Pragma SYSTEM_NAME::
25181 @node Restrictions on the Pragma INLINE
25182 @subsection Restrictions on Pragma @code{INLINE}
25185 HP Ada enforces the following restrictions on the pragma @code{INLINE}:
25187 @item Parameters cannot have a task type.
25189 @item Function results cannot be task types, unconstrained
25190 array types, or unconstrained types with discriminants.
25192 @item Bodies cannot declare the following:
25194 @item Subprogram body or stub (imported subprogram is allowed)
25198 @item Generic declarations
25200 @item Instantiations
25204 @item Access types (types derived from access types allowed)
25206 @item Array or record types
25208 @item Dependent tasks
25210 @item Direct recursive calls of subprogram or containing
25211 subprogram, directly or via a renaming
25217 In GNAT, the only restriction on pragma @code{INLINE} is that the
25218 body must occur before the call if both are in the same
25219 unit, and the size must be appropriately small. There are
25220 no other specific restrictions which cause subprograms to
25221 be incapable of being inlined.
25223 @node Restrictions on the Pragma INTERFACE
25224 @subsection Restrictions on Pragma @code{INTERFACE}
25227 The following restrictions on pragma @code{INTERFACE}
25228 are enforced by both HP Ada and GNAT:
25230 @item Languages accepted: Ada, Bliss, C, Fortran, Default.
25231 Default is the default on OpenVMS Alpha systems.
25233 @item Parameter passing: Language specifies default
25234 mechanisms but can be overridden with an @code{EXPORT} pragma.
25237 @item Ada: Use internal Ada rules.
25239 @item Bliss, C: Parameters must be mode @code{in}; cannot be
25240 record or task type. Result cannot be a string, an
25241 array, or a record.
25243 @item Fortran: Parameters cannot have a task type. Result cannot
25244 be a string, an array, or a record.
25249 GNAT is entirely upwards compatible with HP Ada, and in addition allows
25250 record parameters for all languages.
25252 @node Restrictions on the Pragma SYSTEM_NAME
25253 @subsection Restrictions on Pragma @code{SYSTEM_NAME}
25256 For HP Ada for OpenVMS Alpha, the enumeration literal
25257 for the type @code{NAME} is @code{OPENVMS_AXP}.
25258 In GNAT, the enumeration
25259 literal for the type @code{NAME} is @code{SYSTEM_NAME_GNAT}.
25261 @node Library of Predefined Units
25262 @section Library of Predefined Units
25265 A library of predefined units is provided as part of the
25266 HP Ada and GNAT implementations. HP Ada does not provide
25267 the package @code{MACHINE_CODE} but instead recommends importing
25270 The GNAT versions of the HP Ada Run-Time Library (@code{ADA$PREDEFINED:})
25271 units are taken from the OpenVMS Alpha version, not the OpenVMS VAX
25273 The HP Ada Predefined Library units are modified to remove post-Ada 83
25274 incompatibilities and to make them interoperable with GNAT
25275 (@pxref{Changes to DECLIB}, for details).
25276 The units are located in the @file{DECLIB} directory.
25278 The GNAT RTL is contained in
25279 the @file{ADALIB} directory, and
25280 the default search path is set up to find @code{DECLIB} units in preference
25281 to @code{ADALIB} units with the same name (@code{TEXT_IO},
25282 @code{SEQUENTIAL_IO}, and @code{DIRECT_IO}, for example).
25285 * Changes to DECLIB::
25288 @node Changes to DECLIB
25289 @subsection Changes to @code{DECLIB}
25292 The changes made to the HP Ada predefined library for GNAT and post-Ada 83
25293 compatibility are minor and include the following:
25296 @item Adjusting the location of pragmas and record representation
25297 clauses to obey Ada 95 (and thus Ada 2005) rules
25299 @item Adding the proper notation to generic formal parameters
25300 that take unconstrained types in instantiation
25302 @item Adding pragma @code{ELABORATE_BODY} to package specs
25303 that have package bodies not otherwise allowed
25305 @item Replacing occurrences of the identifier ``@code{PROTECTED}'' by
25306 ``@code{PROTECTD}''.
25307 Currently these are found only in the @code{STARLET} package spec.
25309 @item Changing @code{SYSTEM.ADDRESS} to @code{SYSTEM.SHORT_ADDRESS}
25310 where the address size is constrained to 32 bits.
25314 None of the above changes is visible to users.
25320 On OpenVMS Alpha, HP Ada provides the following strongly-typed bindings:
25323 @item Command Language Interpreter (CLI interface)
25325 @item DECtalk Run-Time Library (DTK interface)
25327 @item Librarian utility routines (LBR interface)
25329 @item General Purpose Run-Time Library (LIB interface)
25331 @item Math Run-Time Library (MTH interface)
25333 @item National Character Set Run-Time Library (NCS interface)
25335 @item Compiled Code Support Run-Time Library (OTS interface)
25337 @item Parallel Processing Run-Time Library (PPL interface)
25339 @item Screen Management Run-Time Library (SMG interface)
25341 @item Sort Run-Time Library (SOR interface)
25343 @item String Run-Time Library (STR interface)
25345 @item STARLET System Library
25348 @item X Window System Version 11R4 and 11R5 (X, XLIB interface)
25350 @item X Windows Toolkit (XT interface)
25352 @item X/Motif Version 1.1.3 and 1.2 (XM interface)
25356 GNAT provides implementations of these HP bindings in the @code{DECLIB}
25357 directory, on both the Alpha and I64 OpenVMS platforms.
25359 The X/Motif bindings used to build @code{DECLIB} are whatever versions are
25361 HP Ada @file{ADA$PREDEFINED} directory with extension @file{.ADC}.
25362 A pragma @code{Linker_Options} has been added to packages @code{Xm},
25363 @code{Xt}, and @code{X_Lib}
25364 causing the default X/Motif sharable image libraries to be linked in. This
25365 is done via options files named @file{xm.opt}, @file{xt.opt}, and
25366 @file{x_lib.opt} (also located in the @file{DECLIB} directory).
25368 It may be necessary to edit these options files to update or correct the
25369 library names if, for example, the newer X/Motif bindings from
25370 @file{ADA$EXAMPLES}
25371 had been (previous to installing GNAT) copied and renamed to supersede the
25372 default @file{ADA$PREDEFINED} versions.
25375 * Shared Libraries and Options Files::
25376 * Interfaces to C::
25379 @node Shared Libraries and Options Files
25380 @subsection Shared Libraries and Options Files
25383 When using the HP Ada
25384 predefined X and Motif bindings, the linking with their sharable images is
25385 done automatically by @command{GNAT LINK}.
25386 When using other X and Motif bindings, you need
25387 to add the corresponding sharable images to the command line for
25388 @code{GNAT LINK}. When linking with shared libraries, or with
25389 @file{.OPT} files, you must
25390 also add them to the command line for @command{GNAT LINK}.
25392 A shared library to be used with GNAT is built in the same way as other
25393 libraries under VMS. The VMS Link command can be used in standard fashion.
25395 @node Interfaces to C
25396 @subsection Interfaces to C
25400 provides the following Ada types and operations:
25403 @item C types package (@code{C_TYPES})
25405 @item C strings (@code{C_TYPES.NULL_TERMINATED})
25407 @item Other_types (@code{SHORT_INT})
25411 Interfacing to C with GNAT, you can use the above approach
25412 described for HP Ada or the facilities of Annex B of
25413 the @cite{Ada Reference Manual} (packages @code{INTERFACES.C},
25414 @code{INTERFACES.C.STRINGS} and @code{INTERFACES.C.POINTERS}). For more
25415 information, see @ref{Interfacing to C,,, gnat_rm, GNAT Reference Manual}.
25417 The @option{-gnatF} qualifier forces default and explicit
25418 @code{External_Name} parameters in pragmas @code{Import} and @code{Export}
25419 to be uppercased for compatibility with the default behavior
25420 of HP C. The qualifier has no effect on @code{Link_Name} parameters.
25422 @node Main Program Definition
25423 @section Main Program Definition
25426 The following section discusses differences in the
25427 definition of main programs on HP Ada and GNAT.
25428 On HP Ada, main programs are defined to meet the
25429 following conditions:
25431 @item Procedure with no formal parameters (returns @code{0} upon
25434 @item Procedure with no formal parameters (returns @code{42} when
25435 an unhandled exception is raised)
25437 @item Function with no formal parameters whose returned value
25438 is of a discrete type
25440 @item Procedure with one @code{out} formal of a discrete type for
25441 which a specification of pragma @code{EXPORT_VALUED_PROCEDURE} is given.
25446 When declared with the pragma @code{EXPORT_VALUED_PROCEDURE},
25447 a main function or main procedure returns a discrete
25448 value whose size is less than 64 bits (32 on VAX systems),
25449 the value is zero- or sign-extended as appropriate.
25450 On GNAT, main programs are defined as follows:
25452 @item Must be a non-generic, parameterless subprogram that
25453 is either a procedure or function returning an Ada
25454 @code{STANDARD.INTEGER} (the predefined type)
25456 @item Cannot be a generic subprogram or an instantiation of a
25460 @node Implementation-Defined Attributes
25461 @section Implementation-Defined Attributes
25464 GNAT provides all HP Ada implementation-defined
25467 @node Compiler and Run-Time Interfacing
25468 @section Compiler and Run-Time Interfacing
25471 HP Ada provides the following qualifiers to pass options to the linker
25474 @item @option{/WAIT} and @option{/SUBMIT}
25476 @item @option{/COMMAND}
25478 @item @option{/@r{[}NO@r{]}MAP}
25480 @item @option{/OUTPUT=@var{file-spec}}
25482 @item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK}
25486 To pass options to the linker, GNAT provides the following
25490 @item @option{/EXECUTABLE=@var{exec-name}}
25492 @item @option{/VERBOSE}
25494 @item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK}
25498 For more information on these switches, see
25499 @ref{Switches for gnatlink}.
25500 In HP Ada, the command-line switch @option{/OPTIMIZE} is available
25501 to control optimization. HP Ada also supplies the
25504 @item @code{OPTIMIZE}
25506 @item @code{INLINE}
25508 @item @code{INLINE_GENERIC}
25510 @item @code{SUPPRESS_ALL}
25512 @item @code{PASSIVE}
25516 In GNAT, optimization is controlled strictly by command
25517 line parameters, as described in the corresponding section of this guide.
25518 The HP pragmas for control of optimization are
25519 recognized but ignored.
25521 Note that in GNAT, the default is optimization off, whereas in HP Ada
25522 the default is that optimization is turned on.
25524 @node Program Compilation and Library Management
25525 @section Program Compilation and Library Management
25528 HP Ada and GNAT provide a comparable set of commands to
25529 build programs. HP Ada also provides a program library,
25530 which is a concept that does not exist on GNAT. Instead,
25531 GNAT provides directories of sources that are compiled as
25534 The following table summarizes
25535 the HP Ada commands and provides
25536 equivalent GNAT commands. In this table, some GNAT
25537 equivalents reflect the fact that GNAT does not use the
25538 concept of a program library. Instead, it uses a model
25539 in which collections of source and object files are used
25540 in a manner consistent with other languages like C and
25541 Fortran. Therefore, standard system file commands are used
25542 to manipulate these elements. Those GNAT commands are marked with
25544 Note that, unlike HP Ada, none of the GNAT commands accepts wild cards.
25547 @multitable @columnfractions .35 .65
25549 @item @emph{HP Ada Command}
25550 @tab @emph{GNAT Equivalent / Description}
25552 @item @command{ADA}
25553 @tab @command{GNAT COMPILE}@*
25554 Invokes the compiler to compile one or more Ada source files.
25556 @item @command{ACS ATTACH}@*
25557 @tab [No equivalent]@*
25558 Switches control of terminal from current process running the program
25561 @item @command{ACS CHECK}
25562 @tab @command{GNAT MAKE /DEPENDENCY_LIST}@*
25563 Forms the execution closure of one
25564 or more compiled units and checks completeness and currency.
25566 @item @command{ACS COMPILE}
25567 @tab @command{GNAT MAKE /ACTIONS=COMPILE}@*
25568 Forms the execution closure of one or
25569 more specified units, checks completeness and currency,
25570 identifies units that have revised source files, compiles same,
25571 and recompiles units that are or will become obsolete.
25572 Also completes incomplete generic instantiations.
25574 @item @command{ACS COPY FOREIGN}
25576 Copies a foreign object file into the program library as a
25579 @item @command{ACS COPY UNIT}
25581 Copies a compiled unit from one program library to another.
25583 @item @command{ACS CREATE LIBRARY}
25584 @tab Create /directory (*)@*
25585 Creates a program library.
25587 @item @command{ACS CREATE SUBLIBRARY}
25588 @tab Create /directory (*)@*
25589 Creates a program sublibrary.
25591 @item @command{ACS DELETE LIBRARY}
25593 Deletes a program library and its contents.
25595 @item @command{ACS DELETE SUBLIBRARY}
25597 Deletes a program sublibrary and its contents.
25599 @item @command{ACS DELETE UNIT}
25600 @tab Delete file (*)@*
25601 On OpenVMS systems, deletes one or more compiled units from
25602 the current program library.
25604 @item @command{ACS DIRECTORY}
25605 @tab Directory (*)@*
25606 On OpenVMS systems, lists units contained in the current
25609 @item @command{ACS ENTER FOREIGN}
25611 Allows the import of a foreign body as an Ada library
25612 spec and enters a reference to a pointer.
25614 @item @command{ACS ENTER UNIT}
25616 Enters a reference (pointer) from the current program library to
25617 a unit compiled into another program library.
25619 @item @command{ACS EXIT}
25620 @tab [No equivalent]@*
25621 Exits from the program library manager.
25623 @item @command{ACS EXPORT}
25625 Creates an object file that contains system-specific object code
25626 for one or more units. With GNAT, object files can simply be copied
25627 into the desired directory.
25629 @item @command{ACS EXTRACT SOURCE}
25631 Allows access to the copied source file for each Ada compilation unit
25633 @item @command{ACS HELP}
25634 @tab @command{HELP GNAT}@*
25635 Provides online help.
25637 @item @command{ACS LINK}
25638 @tab @command{GNAT LINK}@*
25639 Links an object file containing Ada units into an executable file.
25641 @item @command{ACS LOAD}
25643 Loads (partially compiles) Ada units into the program library.
25644 Allows loading a program from a collection of files into a library
25645 without knowing the relationship among units.
25647 @item @command{ACS MERGE}
25649 Merges into the current program library, one or more units from
25650 another library where they were modified.
25652 @item @command{ACS RECOMPILE}
25653 @tab @command{GNAT MAKE /ACTIONS=COMPILE}@*
25654 Recompiles from external or copied source files any obsolete
25655 unit in the closure. Also, completes any incomplete generic
25658 @item @command{ACS REENTER}
25659 @tab @command{GNAT MAKE}@*
25660 Reenters current references to units compiled after last entered
25661 with the @command{ACS ENTER UNIT} command.
25663 @item @command{ACS SET LIBRARY}
25664 @tab Set default (*)@*
25665 Defines a program library to be the compilation context as well
25666 as the target library for compiler output and commands in general.
25668 @item @command{ACS SET PRAGMA}
25669 @tab Edit @file{gnat.adc} (*)@*
25670 Redefines specified values of the library characteristics
25671 @code{LONG_ FLOAT}, @code{MEMORY_SIZE}, @code{SYSTEM_NAME},
25672 and @code{Float_Representation}.
25674 @item @command{ACS SET SOURCE}
25675 @tab Define @code{ADA_INCLUDE_PATH} path (*)@*
25676 Defines the source file search list for the @command{ACS COMPILE} command.
25678 @item @command{ACS SHOW LIBRARY}
25679 @tab Directory (*)@*
25680 Lists information about one or more program libraries.
25682 @item @command{ACS SHOW PROGRAM}
25683 @tab [No equivalent]@*
25684 Lists information about the execution closure of one or
25685 more units in the program library.
25687 @item @command{ACS SHOW SOURCE}
25688 @tab Show logical @code{ADA_INCLUDE_PATH}@*
25689 Shows the source file search used when compiling units.
25691 @item @command{ACS SHOW VERSION}
25692 @tab Compile with @option{VERBOSE} option
25693 Displays the version number of the compiler and program library
25696 @item @command{ACS SPAWN}
25697 @tab [No equivalent]@*
25698 Creates a subprocess of the current process (same as @command{DCL SPAWN}
25701 @item @command{ACS VERIFY}
25702 @tab [No equivalent]@*
25703 Performs a series of consistency checks on a program library to
25704 determine whether the library structure and library files are in
25711 @section Input-Output
25714 On OpenVMS Alpha systems, HP Ada uses OpenVMS Record
25715 Management Services (RMS) to perform operations on
25719 HP Ada and GNAT predefine an identical set of input-
25720 output packages. To make the use of the
25721 generic @code{TEXT_IO} operations more convenient, HP Ada
25722 provides predefined library packages that instantiate the
25723 integer and floating-point operations for the predefined
25724 integer and floating-point types as shown in the following table.
25726 @multitable @columnfractions .45 .55
25727 @item @emph{Package Name} @tab Instantiation
25729 @item @code{INTEGER_TEXT_IO}
25730 @tab @code{INTEGER_IO(INTEGER)}
25732 @item @code{SHORT_INTEGER_TEXT_IO}
25733 @tab @code{INTEGER_IO(SHORT_INTEGER)}
25735 @item @code{SHORT_SHORT_INTEGER_TEXT_IO}
25736 @tab @code{INTEGER_IO(SHORT_SHORT_INTEGER)}
25738 @item @code{FLOAT_TEXT_IO}
25739 @tab @code{FLOAT_IO(FLOAT)}
25741 @item @code{LONG_FLOAT_TEXT_IO}
25742 @tab @code{FLOAT_IO(LONG_FLOAT)}
25746 The HP Ada predefined packages and their operations
25747 are implemented using OpenVMS Alpha files and input-output
25748 facilities. HP Ada supports asynchronous input-output on OpenVMS Alpha.
25749 Familiarity with the following is recommended:
25751 @item RMS file organizations and access methods
25753 @item OpenVMS file specifications and directories
25755 @item OpenVMS File Definition Language (FDL)
25759 GNAT provides I/O facilities that are completely
25760 compatible with HP Ada. The distribution includes the
25761 standard HP Ada versions of all I/O packages, operating
25762 in a manner compatible with HP Ada. In particular, the
25763 following packages are by default the HP Ada (Ada 83)
25764 versions of these packages rather than the renamings
25765 suggested in Annex J of the Ada Reference Manual:
25767 @item @code{TEXT_IO}
25769 @item @code{SEQUENTIAL_IO}
25771 @item @code{DIRECT_IO}
25775 The use of the standard child package syntax (for
25776 example, @code{ADA.TEXT_IO}) retrieves the post-Ada 83 versions of these
25778 GNAT provides HP-compatible predefined instantiations
25779 of the @code{TEXT_IO} packages, and also
25780 provides the standard predefined instantiations required
25781 by the @cite{Ada Reference Manual}.
25783 For further information on how GNAT interfaces to the file
25784 system or how I/O is implemented in programs written in
25785 mixed languages, see @ref{Implementation of the Standard I/O,,,
25786 gnat_rm, GNAT Reference Manual}.
25787 This chapter covers the following:
25789 @item Standard I/O packages
25791 @item @code{FORM} strings
25793 @item @code{ADA.DIRECT_IO}
25795 @item @code{ADA.SEQUENTIAL_IO}
25797 @item @code{ADA.TEXT_IO}
25799 @item Stream pointer positioning
25801 @item Reading and writing non-regular files
25803 @item @code{GET_IMMEDIATE}
25805 @item Treating @code{TEXT_IO} files as streams
25812 @node Implementation Limits
25813 @section Implementation Limits
25816 The following table lists implementation limits for HP Ada
25818 @multitable @columnfractions .60 .20 .20
25820 @item @emph{Compilation Parameter}
25825 @item In a subprogram or entry declaration, maximum number of
25826 formal parameters that are of an unconstrained record type
25831 @item Maximum identifier length (number of characters)
25836 @item Maximum number of characters in a source line
25841 @item Maximum collection size (number of bytes)
25846 @item Maximum number of discriminants for a record type
25851 @item Maximum number of formal parameters in an entry or
25852 subprogram declaration
25857 @item Maximum number of dimensions in an array type
25862 @item Maximum number of library units and subunits in a compilation.
25867 @item Maximum number of library units and subunits in an execution.
25872 @item Maximum number of objects declared with the pragma @code{COMMON_OBJECT}
25873 or @code{PSECT_OBJECT}
25878 @item Maximum number of enumeration literals in an enumeration type
25884 @item Maximum number of lines in a source file
25889 @item Maximum number of bits in any object
25894 @item Maximum size of the static portion of a stack frame (approximate)
25899 @node Tools and Utilities
25900 @section Tools and Utilities
25903 The following table lists some of the OpenVMS development tools
25904 available for HP Ada, and the corresponding tools for
25905 use with @value{EDITION} on Alpha and I64 platforms.
25906 Aside from the debugger, all the OpenVMS tools identified are part
25907 of the DECset package.
25910 @c Specify table in TeX since Texinfo does a poor job
25914 \settabs\+Language-Sensitive Editor\quad
25915 &Product with HP Ada\quad
25918 &\it Product with HP Ada
25919 & \it Product with GNAT Pro\cr
25921 \+Code Management System
25925 \+Language-Sensitive Editor
25927 & emacs or HP LSE (Alpha)\cr
25937 & OpenVMS Debug (I64)\cr
25939 \+Source Code Analyzer /
25956 \+Coverage Analyzer
25960 \+Module Management
25962 & Not applicable\cr
25972 @c This is the Texinfo version of the table. It renders poorly in pdf, hence
25973 @c the TeX version above for the printed version
25975 @c @multitable @columnfractions .3 .4 .4
25976 @multitable {Source Code Analyzer /}{Tool with HP Ada}{Tool with GNAT Pro}
25978 @tab @i{Tool with HP Ada}
25979 @tab @i{Tool with @value{EDITION}}
25980 @item Code Management@*System
25983 @item Language-Sensitive@*Editor
25985 @tab emacs or HP LSE (Alpha)
25994 @tab OpenVMS Debug (I64)
25995 @item Source Code Analyzer /@*Cross Referencer
25999 @tab HP Digital Test@*Manager (DTM)
26001 @item Performance and@*Coverage Analyzer
26004 @item Module Management@*System
26006 @tab Not applicable
26013 @c **************************************
26014 @node Platform-Specific Information for the Run-Time Libraries
26015 @appendix Platform-Specific Information for the Run-Time Libraries
26016 @cindex Tasking and threads libraries
26017 @cindex Threads libraries and tasking
26018 @cindex Run-time libraries (platform-specific information)
26021 The GNAT run-time implementation may vary with respect to both the
26022 underlying threads library and the exception handling scheme.
26023 For threads support, one or more of the following are supplied:
26025 @item @b{native threads library}, a binding to the thread package from
26026 the underlying operating system
26028 @item @b{pthreads library} (Sparc Solaris only), a binding to the Solaris
26029 POSIX thread package
26033 For exception handling, either or both of two models are supplied:
26035 @item @b{Zero-Cost Exceptions} (``ZCX''),@footnote{
26036 Most programs should experience a substantial speed improvement by
26037 being compiled with a ZCX run-time.
26038 This is especially true for
26039 tasking applications or applications with many exception handlers.}
26040 @cindex Zero-Cost Exceptions
26041 @cindex ZCX (Zero-Cost Exceptions)
26042 which uses binder-generated tables that
26043 are interrogated at run time to locate a handler
26045 @item @b{setjmp / longjmp} (``SJLJ''),
26046 @cindex setjmp/longjmp Exception Model
26047 @cindex SJLJ (setjmp/longjmp Exception Model)
26048 which uses dynamically-set data to establish
26049 the set of handlers
26053 This appendix summarizes which combinations of threads and exception support
26054 are supplied on various GNAT platforms.
26055 It then shows how to select a particular library either
26056 permanently or temporarily,
26057 explains the properties of (and tradeoffs among) the various threads
26058 libraries, and provides some additional
26059 information about several specific platforms.
26062 * Summary of Run-Time Configurations::
26063 * Specifying a Run-Time Library::
26064 * Choosing the Scheduling Policy::
26065 * Solaris-Specific Considerations::
26066 * Linux-Specific Considerations::
26067 * AIX-Specific Considerations::
26068 * Irix-Specific Considerations::
26069 * RTX-Specific Considerations::
26072 @node Summary of Run-Time Configurations
26073 @section Summary of Run-Time Configurations
26075 @multitable @columnfractions .30 .70
26076 @item @b{alpha-openvms}
26077 @item @code{@ @ }@i{rts-native (default)}
26078 @item @code{@ @ @ @ }Tasking @tab native VMS threads
26079 @item @code{@ @ @ @ }Exceptions @tab ZCX
26081 @item @b{alpha-tru64}
26082 @item @code{@ @ }@i{rts-native (default)}
26083 @item @code{@ @ @ @ }Tasking @tab native TRU64 threads
26084 @item @code{@ @ @ @ }Exceptions @tab ZCX
26086 @item @code{@ @ }@i{rts-sjlj}
26087 @item @code{@ @ @ @ }Tasking @tab native TRU64 threads
26088 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26090 @item @b{ia64-hp_linux}
26091 @item @code{@ @ }@i{rts-native (default)}
26092 @item @code{@ @ @ @ }Tasking @tab pthread library
26093 @item @code{@ @ @ @ }Exceptions @tab ZCX
26095 @item @b{ia64-hpux}
26096 @item @code{@ @ }@i{rts-native (default)}
26097 @item @code{@ @ @ @ }Tasking @tab native HP-UX threads
26098 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26100 @item @b{ia64-openvms}
26101 @item @code{@ @ }@i{rts-native (default)}
26102 @item @code{@ @ @ @ }Tasking @tab native VMS threads
26103 @item @code{@ @ @ @ }Exceptions @tab ZCX
26105 @item @b{ia64-sgi_linux}
26106 @item @code{@ @ }@i{rts-native (default)}
26107 @item @code{@ @ @ @ }Tasking @tab pthread library
26108 @item @code{@ @ @ @ }Exceptions @tab ZCX
26110 @item @b{mips-irix}
26111 @item @code{@ @ }@i{rts-native (default)}
26112 @item @code{@ @ @ @ }Tasking @tab native IRIX threads
26113 @item @code{@ @ @ @ }Exceptions @tab ZCX
26116 @item @code{@ @ }@i{rts-native (default)}
26117 @item @code{@ @ @ @ }Tasking @tab native HP-UX threads
26118 @item @code{@ @ @ @ }Exceptions @tab ZCX
26120 @item @code{@ @ }@i{rts-sjlj}
26121 @item @code{@ @ @ @ }Tasking @tab native HP-UX threads
26122 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26125 @item @code{@ @ }@i{rts-native (default)}
26126 @item @code{@ @ @ @ }Tasking @tab native AIX threads
26127 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26129 @item @b{ppc-darwin}
26130 @item @code{@ @ }@i{rts-native (default)}
26131 @item @code{@ @ @ @ }Tasking @tab native MacOS threads
26132 @item @code{@ @ @ @ }Exceptions @tab ZCX
26134 @item @b{sparc-solaris} @tab
26135 @item @code{@ @ }@i{rts-native (default)}
26136 @item @code{@ @ @ @ }Tasking @tab native Solaris threads library
26137 @item @code{@ @ @ @ }Exceptions @tab ZCX
26139 @item @code{@ @ }@i{rts-pthread}
26140 @item @code{@ @ @ @ }Tasking @tab pthread library
26141 @item @code{@ @ @ @ }Exceptions @tab ZCX
26143 @item @code{@ @ }@i{rts-sjlj}
26144 @item @code{@ @ @ @ }Tasking @tab native Solaris threads library
26145 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26147 @item @b{sparc64-solaris} @tab
26148 @item @code{@ @ }@i{rts-native (default)}
26149 @item @code{@ @ @ @ }Tasking @tab native Solaris threads library
26150 @item @code{@ @ @ @ }Exceptions @tab ZCX
26152 @item @b{x86-linux}
26153 @item @code{@ @ }@i{rts-native (default)}
26154 @item @code{@ @ @ @ }Tasking @tab pthread library
26155 @item @code{@ @ @ @ }Exceptions @tab ZCX
26157 @item @code{@ @ }@i{rts-sjlj}
26158 @item @code{@ @ @ @ }Tasking @tab pthread library
26159 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26162 @item @code{@ @ }@i{rts-native (default)}
26163 @item @code{@ @ @ @ }Tasking @tab native LynxOS threads
26164 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26166 @item @b{x86-solaris}
26167 @item @code{@ @ }@i{rts-native (default)}
26168 @item @code{@ @ @ @ }Tasking @tab native Solaris threads
26169 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26171 @item @b{x86-windows}
26172 @item @code{@ @ }@i{rts-native (default)}
26173 @item @code{@ @ @ @ }Tasking @tab native Win32 threads
26174 @item @code{@ @ @ @ }Exceptions @tab ZCX
26176 @item @code{@ @ }@i{rts-sjlj (default)}
26177 @item @code{@ @ @ @ }Tasking @tab native Win32 threads
26178 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26180 @item @b{x86-windows-rtx}
26181 @item @code{@ @ }@i{rts-rtx-rtss (default)}
26182 @item @code{@ @ @ @ }Tasking @tab RTX real-time subsystem RTSS threads (kernel mode)
26183 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26185 @item @code{@ @ }@i{rts-rtx-w32}
26186 @item @code{@ @ @ @ }Tasking @tab RTX Win32 threads (user mode)
26187 @item @code{@ @ @ @ }Exceptions @tab ZCX
26189 @item @b{x86_64-linux}
26190 @item @code{@ @ }@i{rts-native (default)}
26191 @item @code{@ @ @ @ }Tasking @tab pthread library
26192 @item @code{@ @ @ @ }Exceptions @tab ZCX
26194 @item @code{@ @ }@i{rts-sjlj}
26195 @item @code{@ @ @ @ }Tasking @tab pthread library
26196 @item @code{@ @ @ @ }Exceptions @tab SJLJ
26200 @node Specifying a Run-Time Library
26201 @section Specifying a Run-Time Library
26204 The @file{adainclude} subdirectory containing the sources of the GNAT
26205 run-time library, and the @file{adalib} subdirectory containing the
26206 @file{ALI} files and the static and/or shared GNAT library, are located
26207 in the gcc target-dependent area:
26210 target=$prefix/lib/gcc/gcc-@i{dumpmachine}/gcc-@i{dumpversion}/
26214 As indicated above, on some platforms several run-time libraries are supplied.
26215 These libraries are installed in the target dependent area and
26216 contain a complete source and binary subdirectory. The detailed description
26217 below explains the differences between the different libraries in terms of
26218 their thread support.
26220 The default run-time library (when GNAT is installed) is @emph{rts-native}.
26221 This default run time is selected by the means of soft links.
26222 For example on x86-linux:
26228 +--- adainclude----------+
26230 +--- adalib-----------+ |
26232 +--- rts-native | |
26234 | +--- adainclude <---+
26236 | +--- adalib <----+
26247 If the @i{rts-sjlj} library is to be selected on a permanent basis,
26248 these soft links can be modified with the following commands:
26252 $ rm -f adainclude adalib
26253 $ ln -s rts-sjlj/adainclude adainclude
26254 $ ln -s rts-sjlj/adalib adalib
26258 Alternatively, you can specify @file{rts-sjlj/adainclude} in the file
26259 @file{$target/ada_source_path} and @file{rts-sjlj/adalib} in
26260 @file{$target/ada_object_path}.
26262 Selecting another run-time library temporarily can be
26263 achieved by using the @option{--RTS} switch, e.g., @option{--RTS=sjlj}
26264 @cindex @option{--RTS} option
26266 @node Choosing the Scheduling Policy
26267 @section Choosing the Scheduling Policy
26270 When using a POSIX threads implementation, you have a choice of several
26271 scheduling policies: @code{SCHED_FIFO},
26272 @cindex @code{SCHED_FIFO} scheduling policy
26274 @cindex @code{SCHED_RR} scheduling policy
26275 and @code{SCHED_OTHER}.
26276 @cindex @code{SCHED_OTHER} scheduling policy
26277 Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO}
26278 or @code{SCHED_RR} requires special (e.g., root) privileges.
26280 By default, GNAT uses the @code{SCHED_OTHER} policy. To specify
26282 @cindex @code{SCHED_FIFO} scheduling policy
26283 you can use one of the following:
26287 @code{pragma Time_Slice (0.0)}
26288 @cindex pragma Time_Slice
26290 the corresponding binder option @option{-T0}
26291 @cindex @option{-T0} option
26293 @code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
26294 @cindex pragma Task_Dispatching_Policy
26298 To specify @code{SCHED_RR},
26299 @cindex @code{SCHED_RR} scheduling policy
26300 you should use @code{pragma Time_Slice} with a
26301 value greater than @code{0.0}, or else use the corresponding @option{-T}
26304 @node Solaris-Specific Considerations
26305 @section Solaris-Specific Considerations
26306 @cindex Solaris Sparc threads libraries
26309 This section addresses some topics related to the various threads libraries
26313 * Solaris Threads Issues::
26316 @node Solaris Threads Issues
26317 @subsection Solaris Threads Issues
26320 GNAT under Solaris/Sparc 32 bits comes with an alternate tasking run-time
26321 library based on POSIX threads --- @emph{rts-pthread}.
26322 @cindex rts-pthread threads library
26323 This run-time library has the advantage of being mostly shared across all
26324 POSIX-compliant thread implementations, and it also provides under
26325 @w{Solaris 8} the @code{PTHREAD_PRIO_INHERIT}
26326 @cindex @code{PTHREAD_PRIO_INHERIT} policy (under rts-pthread)
26327 and @code{PTHREAD_PRIO_PROTECT}
26328 @cindex @code{PTHREAD_PRIO_PROTECT} policy (under rts-pthread)
26329 semantics that can be selected using the predefined pragma
26330 @code{Locking_Policy}
26331 @cindex pragma Locking_Policy (under rts-pthread)
26333 @code{Inheritance_Locking} and @code{Ceiling_Locking} as the policy.
26334 @cindex @code{Inheritance_Locking} (under rts-pthread)
26335 @cindex @code{Ceiling_Locking} (under rts-pthread)
26337 As explained above, the native run-time library is based on the Solaris thread
26338 library (@code{libthread}) and is the default library.
26340 When the Solaris threads library is used (this is the default), programs
26341 compiled with GNAT can automatically take advantage of
26342 and can thus execute on multiple processors.
26343 The user can alternatively specify a processor on which the program should run
26344 to emulate a single-processor system. The multiprocessor / uniprocessor choice
26346 setting the environment variable @env{GNAT_PROCESSOR}
26347 @cindex @env{GNAT_PROCESSOR} environment variable (on Sparc Solaris)
26348 to one of the following:
26352 Use the default configuration (run the program on all
26353 available processors) - this is the same as having @code{GNAT_PROCESSOR}
26357 Let the run-time implementation choose one processor and run the program on
26360 @item 0 .. Last_Proc
26361 Run the program on the specified processor.
26362 @code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1}
26363 (where @code{_SC_NPROCESSORS_CONF} is a system variable).
26366 @node Linux-Specific Considerations
26367 @section Linux-Specific Considerations
26368 @cindex Linux threads libraries
26371 On GNU/Linux without NPTL support (usually system with GNU C Library
26372 older than 2.3), the signal model is not POSIX compliant, which means
26373 that to send a signal to the process, you need to send the signal to all
26374 threads, e.g.@: by using @code{killpg()}.
26376 @node AIX-Specific Considerations
26377 @section AIX-Specific Considerations
26378 @cindex AIX resolver library
26381 On AIX, the resolver library initializes some internal structure on
26382 the first call to @code{get*by*} functions, which are used to implement
26383 @code{GNAT.Sockets.Get_Host_By_Name} and
26384 @code{GNAT.Sockets.Get_Host_By_Address}.
26385 If such initialization occurs within an Ada task, and the stack size for
26386 the task is the default size, a stack overflow may occur.
26388 To avoid this overflow, the user should either ensure that the first call
26389 to @code{GNAT.Sockets.Get_Host_By_Name} or
26390 @code{GNAT.Sockets.Get_Host_By_Addrss}
26391 occurs in the environment task, or use @code{pragma Storage_Size} to
26392 specify a sufficiently large size for the stack of the task that contains
26395 @node Irix-Specific Considerations
26396 @section Irix-Specific Considerations
26397 @cindex Irix libraries
26400 The GCC support libraries coming with the Irix compiler have moved to
26401 their canonical place with respect to the general Irix ABI related
26402 conventions. Running applications built with the default shared GNAT
26403 run-time now requires the LD_LIBRARY_PATH environment variable to
26404 include this location. A possible way to achieve this is to issue the
26405 following command line on a bash prompt:
26409 $ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`dirname \`gcc --print-file-name=libgcc_s.so\``
26413 @node RTX-Specific Considerations
26414 @section RTX-Specific Considerations
26415 @cindex RTX libraries
26418 The Real-time Extension (RTX) to Windows is based on the Windows Win32
26419 API. Applications can be built to work in two different modes:
26423 Windows executables that run in Ring 3 to utilize memory protection
26424 (@emph{rts-rtx-w32}).
26427 Real-time subsystem (RTSS) executables that run in Ring 0, where
26428 performance can be optimized with RTSS applications taking precedent
26429 over all Windows applications (@emph{rts-rtx-rtss}).
26433 @c *******************************
26434 @node Example of Binder Output File
26435 @appendix Example of Binder Output File
26438 This Appendix displays the source code for @command{gnatbind}'s output
26439 file generated for a simple ``Hello World'' program.
26440 Comments have been added for clarification purposes.
26442 @smallexample @c adanocomment
26446 -- The package is called Ada_Main unless this name is actually used
26447 -- as a unit name in the partition, in which case some other unique
26451 package ada_main is
26453 Elab_Final_Code : Integer;
26454 pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code");
26456 -- The main program saves the parameters (argument count,
26457 -- argument values, environment pointer) in global variables
26458 -- for later access by other units including
26459 -- Ada.Command_Line.
26461 gnat_argc : Integer;
26462 gnat_argv : System.Address;
26463 gnat_envp : System.Address;
26465 -- The actual variables are stored in a library routine. This
26466 -- is useful for some shared library situations, where there
26467 -- are problems if variables are not in the library.
26469 pragma Import (C, gnat_argc);
26470 pragma Import (C, gnat_argv);
26471 pragma Import (C, gnat_envp);
26473 -- The exit status is similarly an external location
26475 gnat_exit_status : Integer;
26476 pragma Import (C, gnat_exit_status);
26478 GNAT_Version : constant String :=
26479 "GNAT Version: 6.0.0w (20061115)";
26480 pragma Export (C, GNAT_Version, "__gnat_version");
26482 -- This is the generated adafinal routine that performs
26483 -- finalization at the end of execution. In the case where
26484 -- Ada is the main program, this main program makes a call
26485 -- to adafinal at program termination.
26487 procedure adafinal;
26488 pragma Export (C, adafinal, "adafinal");
26490 -- This is the generated adainit routine that performs
26491 -- initialization at the start of execution. In the case
26492 -- where Ada is the main program, this main program makes
26493 -- a call to adainit at program startup.
26496 pragma Export (C, adainit, "adainit");
26498 -- This routine is called at the start of execution. It is
26499 -- a dummy routine that is used by the debugger to breakpoint
26500 -- at the start of execution.
26502 procedure Break_Start;
26503 pragma Import (C, Break_Start, "__gnat_break_start");
26505 -- This is the actual generated main program (it would be
26506 -- suppressed if the no main program switch were used). As
26507 -- required by standard system conventions, this program has
26508 -- the external name main.
26512 argv : System.Address;
26513 envp : System.Address)
26515 pragma Export (C, main, "main");
26517 -- The following set of constants give the version
26518 -- identification values for every unit in the bound
26519 -- partition. This identification is computed from all
26520 -- dependent semantic units, and corresponds to the
26521 -- string that would be returned by use of the
26522 -- Body_Version or Version attributes.
26524 type Version_32 is mod 2 ** 32;
26525 u00001 : constant Version_32 := 16#7880BEB3#;
26526 u00002 : constant Version_32 := 16#0D24CBD0#;
26527 u00003 : constant Version_32 := 16#3283DBEB#;
26528 u00004 : constant Version_32 := 16#2359F9ED#;
26529 u00005 : constant Version_32 := 16#664FB847#;
26530 u00006 : constant Version_32 := 16#68E803DF#;
26531 u00007 : constant Version_32 := 16#5572E604#;
26532 u00008 : constant Version_32 := 16#46B173D8#;
26533 u00009 : constant Version_32 := 16#156A40CF#;
26534 u00010 : constant Version_32 := 16#033DABE0#;
26535 u00011 : constant Version_32 := 16#6AB38FEA#;
26536 u00012 : constant Version_32 := 16#22B6217D#;
26537 u00013 : constant Version_32 := 16#68A22947#;
26538 u00014 : constant Version_32 := 16#18CC4A56#;
26539 u00015 : constant Version_32 := 16#08258E1B#;
26540 u00016 : constant Version_32 := 16#367D5222#;
26541 u00017 : constant Version_32 := 16#20C9ECA4#;
26542 u00018 : constant Version_32 := 16#50D32CB6#;
26543 u00019 : constant Version_32 := 16#39A8BB77#;
26544 u00020 : constant Version_32 := 16#5CF8FA2B#;
26545 u00021 : constant Version_32 := 16#2F1EB794#;
26546 u00022 : constant Version_32 := 16#31AB6444#;
26547 u00023 : constant Version_32 := 16#1574B6E9#;
26548 u00024 : constant Version_32 := 16#5109C189#;
26549 u00025 : constant Version_32 := 16#56D770CD#;
26550 u00026 : constant Version_32 := 16#02F9DE3D#;
26551 u00027 : constant Version_32 := 16#08AB6B2C#;
26552 u00028 : constant Version_32 := 16#3FA37670#;
26553 u00029 : constant Version_32 := 16#476457A0#;
26554 u00030 : constant Version_32 := 16#731E1B6E#;
26555 u00031 : constant Version_32 := 16#23C2E789#;
26556 u00032 : constant Version_32 := 16#0F1BD6A1#;
26557 u00033 : constant Version_32 := 16#7C25DE96#;
26558 u00034 : constant Version_32 := 16#39ADFFA2#;
26559 u00035 : constant Version_32 := 16#571DE3E7#;
26560 u00036 : constant Version_32 := 16#5EB646AB#;
26561 u00037 : constant Version_32 := 16#4249379B#;
26562 u00038 : constant Version_32 := 16#0357E00A#;
26563 u00039 : constant Version_32 := 16#3784FB72#;
26564 u00040 : constant Version_32 := 16#2E723019#;
26565 u00041 : constant Version_32 := 16#623358EA#;
26566 u00042 : constant Version_32 := 16#107F9465#;
26567 u00043 : constant Version_32 := 16#6843F68A#;
26568 u00044 : constant Version_32 := 16#63305874#;
26569 u00045 : constant Version_32 := 16#31E56CE1#;
26570 u00046 : constant Version_32 := 16#02917970#;
26571 u00047 : constant Version_32 := 16#6CCBA70E#;
26572 u00048 : constant Version_32 := 16#41CD4204#;
26573 u00049 : constant Version_32 := 16#572E3F58#;
26574 u00050 : constant Version_32 := 16#20729FF5#;
26575 u00051 : constant Version_32 := 16#1D4F93E8#;
26576 u00052 : constant Version_32 := 16#30B2EC3D#;
26577 u00053 : constant Version_32 := 16#34054F96#;
26578 u00054 : constant Version_32 := 16#5A199860#;
26579 u00055 : constant Version_32 := 16#0E7F912B#;
26580 u00056 : constant Version_32 := 16#5760634A#;
26581 u00057 : constant Version_32 := 16#5D851835#;
26583 -- The following Export pragmas export the version numbers
26584 -- with symbolic names ending in B (for body) or S
26585 -- (for spec) so that they can be located in a link. The
26586 -- information provided here is sufficient to track down
26587 -- the exact versions of units used in a given build.
26589 pragma Export (C, u00001, "helloB");
26590 pragma Export (C, u00002, "system__standard_libraryB");
26591 pragma Export (C, u00003, "system__standard_libraryS");
26592 pragma Export (C, u00004, "adaS");
26593 pragma Export (C, u00005, "ada__text_ioB");
26594 pragma Export (C, u00006, "ada__text_ioS");
26595 pragma Export (C, u00007, "ada__exceptionsB");
26596 pragma Export (C, u00008, "ada__exceptionsS");
26597 pragma Export (C, u00009, "gnatS");
26598 pragma Export (C, u00010, "gnat__heap_sort_aB");
26599 pragma Export (C, u00011, "gnat__heap_sort_aS");
26600 pragma Export (C, u00012, "systemS");
26601 pragma Export (C, u00013, "system__exception_tableB");
26602 pragma Export (C, u00014, "system__exception_tableS");
26603 pragma Export (C, u00015, "gnat__htableB");
26604 pragma Export (C, u00016, "gnat__htableS");
26605 pragma Export (C, u00017, "system__exceptionsS");
26606 pragma Export (C, u00018, "system__machine_state_operationsB");
26607 pragma Export (C, u00019, "system__machine_state_operationsS");
26608 pragma Export (C, u00020, "system__machine_codeS");
26609 pragma Export (C, u00021, "system__storage_elementsB");
26610 pragma Export (C, u00022, "system__storage_elementsS");
26611 pragma Export (C, u00023, "system__secondary_stackB");
26612 pragma Export (C, u00024, "system__secondary_stackS");
26613 pragma Export (C, u00025, "system__parametersB");
26614 pragma Export (C, u00026, "system__parametersS");
26615 pragma Export (C, u00027, "system__soft_linksB");
26616 pragma Export (C, u00028, "system__soft_linksS");
26617 pragma Export (C, u00029, "system__stack_checkingB");
26618 pragma Export (C, u00030, "system__stack_checkingS");
26619 pragma Export (C, u00031, "system__tracebackB");
26620 pragma Export (C, u00032, "system__tracebackS");
26621 pragma Export (C, u00033, "ada__streamsS");
26622 pragma Export (C, u00034, "ada__tagsB");
26623 pragma Export (C, u00035, "ada__tagsS");
26624 pragma Export (C, u00036, "system__string_opsB");
26625 pragma Export (C, u00037, "system__string_opsS");
26626 pragma Export (C, u00038, "interfacesS");
26627 pragma Export (C, u00039, "interfaces__c_streamsB");
26628 pragma Export (C, u00040, "interfaces__c_streamsS");
26629 pragma Export (C, u00041, "system__file_ioB");
26630 pragma Export (C, u00042, "system__file_ioS");
26631 pragma Export (C, u00043, "ada__finalizationB");
26632 pragma Export (C, u00044, "ada__finalizationS");
26633 pragma Export (C, u00045, "system__finalization_rootB");
26634 pragma Export (C, u00046, "system__finalization_rootS");
26635 pragma Export (C, u00047, "system__finalization_implementationB");
26636 pragma Export (C, u00048, "system__finalization_implementationS");
26637 pragma Export (C, u00049, "system__string_ops_concat_3B");
26638 pragma Export (C, u00050, "system__string_ops_concat_3S");
26639 pragma Export (C, u00051, "system__stream_attributesB");
26640 pragma Export (C, u00052, "system__stream_attributesS");
26641 pragma Export (C, u00053, "ada__io_exceptionsS");
26642 pragma Export (C, u00054, "system__unsigned_typesS");
26643 pragma Export (C, u00055, "system__file_control_blockS");
26644 pragma Export (C, u00056, "ada__finalization__list_controllerB");
26645 pragma Export (C, u00057, "ada__finalization__list_controllerS");
26647 -- BEGIN ELABORATION ORDER
26650 -- gnat.heap_sort_a (spec)
26651 -- gnat.heap_sort_a (body)
26652 -- gnat.htable (spec)
26653 -- gnat.htable (body)
26654 -- interfaces (spec)
26656 -- system.machine_code (spec)
26657 -- system.parameters (spec)
26658 -- system.parameters (body)
26659 -- interfaces.c_streams (spec)
26660 -- interfaces.c_streams (body)
26661 -- system.standard_library (spec)
26662 -- ada.exceptions (spec)
26663 -- system.exception_table (spec)
26664 -- system.exception_table (body)
26665 -- ada.io_exceptions (spec)
26666 -- system.exceptions (spec)
26667 -- system.storage_elements (spec)
26668 -- system.storage_elements (body)
26669 -- system.machine_state_operations (spec)
26670 -- system.machine_state_operations (body)
26671 -- system.secondary_stack (spec)
26672 -- system.stack_checking (spec)
26673 -- system.soft_links (spec)
26674 -- system.soft_links (body)
26675 -- system.stack_checking (body)
26676 -- system.secondary_stack (body)
26677 -- system.standard_library (body)
26678 -- system.string_ops (spec)
26679 -- system.string_ops (body)
26682 -- ada.streams (spec)
26683 -- system.finalization_root (spec)
26684 -- system.finalization_root (body)
26685 -- system.string_ops_concat_3 (spec)
26686 -- system.string_ops_concat_3 (body)
26687 -- system.traceback (spec)
26688 -- system.traceback (body)
26689 -- ada.exceptions (body)
26690 -- system.unsigned_types (spec)
26691 -- system.stream_attributes (spec)
26692 -- system.stream_attributes (body)
26693 -- system.finalization_implementation (spec)
26694 -- system.finalization_implementation (body)
26695 -- ada.finalization (spec)
26696 -- ada.finalization (body)
26697 -- ada.finalization.list_controller (spec)
26698 -- ada.finalization.list_controller (body)
26699 -- system.file_control_block (spec)
26700 -- system.file_io (spec)
26701 -- system.file_io (body)
26702 -- ada.text_io (spec)
26703 -- ada.text_io (body)
26705 -- END ELABORATION ORDER
26709 -- The following source file name pragmas allow the generated file
26710 -- names to be unique for different main programs. They are needed
26711 -- since the package name will always be Ada_Main.
26713 pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads");
26714 pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb");
26716 -- Generated package body for Ada_Main starts here
26718 package body ada_main is
26720 -- The actual finalization is performed by calling the
26721 -- library routine in System.Standard_Library.Adafinal
26723 procedure Do_Finalize;
26724 pragma Import (C, Do_Finalize, "system__standard_library__adafinal");
26731 procedure adainit is
26733 -- These booleans are set to True once the associated unit has
26734 -- been elaborated. It is also used to avoid elaborating the
26735 -- same unit twice.
26738 pragma Import (Ada, E040, "interfaces__c_streams_E");
26741 pragma Import (Ada, E008, "ada__exceptions_E");
26744 pragma Import (Ada, E014, "system__exception_table_E");
26747 pragma Import (Ada, E053, "ada__io_exceptions_E");
26750 pragma Import (Ada, E017, "system__exceptions_E");
26753 pragma Import (Ada, E024, "system__secondary_stack_E");
26756 pragma Import (Ada, E030, "system__stack_checking_E");
26759 pragma Import (Ada, E028, "system__soft_links_E");
26762 pragma Import (Ada, E035, "ada__tags_E");
26765 pragma Import (Ada, E033, "ada__streams_E");
26768 pragma Import (Ada, E046, "system__finalization_root_E");
26771 pragma Import (Ada, E048, "system__finalization_implementation_E");
26774 pragma Import (Ada, E044, "ada__finalization_E");
26777 pragma Import (Ada, E057, "ada__finalization__list_controller_E");
26780 pragma Import (Ada, E055, "system__file_control_block_E");
26783 pragma Import (Ada, E042, "system__file_io_E");
26786 pragma Import (Ada, E006, "ada__text_io_E");
26788 -- Set_Globals is a library routine that stores away the
26789 -- value of the indicated set of global values in global
26790 -- variables within the library.
26792 procedure Set_Globals
26793 (Main_Priority : Integer;
26794 Time_Slice_Value : Integer;
26795 WC_Encoding : Character;
26796 Locking_Policy : Character;
26797 Queuing_Policy : Character;
26798 Task_Dispatching_Policy : Character;
26799 Adafinal : System.Address;
26800 Unreserve_All_Interrupts : Integer;
26801 Exception_Tracebacks : Integer);
26802 @findex __gnat_set_globals
26803 pragma Import (C, Set_Globals, "__gnat_set_globals");
26805 -- SDP_Table_Build is a library routine used to build the
26806 -- exception tables. See unit Ada.Exceptions in files
26807 -- a-except.ads/adb for full details of how zero cost
26808 -- exception handling works. This procedure, the call to
26809 -- it, and the two following tables are all omitted if the
26810 -- build is in longjmp/setjmp exception mode.
26812 @findex SDP_Table_Build
26813 @findex Zero Cost Exceptions
26814 procedure SDP_Table_Build
26815 (SDP_Addresses : System.Address;
26816 SDP_Count : Natural;
26817 Elab_Addresses : System.Address;
26818 Elab_Addr_Count : Natural);
26819 pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build");
26821 -- Table of Unit_Exception_Table addresses. Used for zero
26822 -- cost exception handling to build the top level table.
26824 ST : aliased constant array (1 .. 23) of System.Address := (
26826 Ada.Text_Io'UET_Address,
26827 Ada.Exceptions'UET_Address,
26828 Gnat.Heap_Sort_A'UET_Address,
26829 System.Exception_Table'UET_Address,
26830 System.Machine_State_Operations'UET_Address,
26831 System.Secondary_Stack'UET_Address,
26832 System.Parameters'UET_Address,
26833 System.Soft_Links'UET_Address,
26834 System.Stack_Checking'UET_Address,
26835 System.Traceback'UET_Address,
26836 Ada.Streams'UET_Address,
26837 Ada.Tags'UET_Address,
26838 System.String_Ops'UET_Address,
26839 Interfaces.C_Streams'UET_Address,
26840 System.File_Io'UET_Address,
26841 Ada.Finalization'UET_Address,
26842 System.Finalization_Root'UET_Address,
26843 System.Finalization_Implementation'UET_Address,
26844 System.String_Ops_Concat_3'UET_Address,
26845 System.Stream_Attributes'UET_Address,
26846 System.File_Control_Block'UET_Address,
26847 Ada.Finalization.List_Controller'UET_Address);
26849 -- Table of addresses of elaboration routines. Used for
26850 -- zero cost exception handling to make sure these
26851 -- addresses are included in the top level procedure
26854 EA : aliased constant array (1 .. 23) of System.Address := (
26855 adainit'Code_Address,
26856 Do_Finalize'Code_Address,
26857 Ada.Exceptions'Elab_Spec'Address,
26858 System.Exceptions'Elab_Spec'Address,
26859 Interfaces.C_Streams'Elab_Spec'Address,
26860 System.Exception_Table'Elab_Body'Address,
26861 Ada.Io_Exceptions'Elab_Spec'Address,
26862 System.Stack_Checking'Elab_Spec'Address,
26863 System.Soft_Links'Elab_Body'Address,
26864 System.Secondary_Stack'Elab_Body'Address,
26865 Ada.Tags'Elab_Spec'Address,
26866 Ada.Tags'Elab_Body'Address,
26867 Ada.Streams'Elab_Spec'Address,
26868 System.Finalization_Root'Elab_Spec'Address,
26869 Ada.Exceptions'Elab_Body'Address,
26870 System.Finalization_Implementation'Elab_Spec'Address,
26871 System.Finalization_Implementation'Elab_Body'Address,
26872 Ada.Finalization'Elab_Spec'Address,
26873 Ada.Finalization.List_Controller'Elab_Spec'Address,
26874 System.File_Control_Block'Elab_Spec'Address,
26875 System.File_Io'Elab_Body'Address,
26876 Ada.Text_Io'Elab_Spec'Address,
26877 Ada.Text_Io'Elab_Body'Address);
26879 -- Start of processing for adainit
26883 -- Call SDP_Table_Build to build the top level procedure
26884 -- table for zero cost exception handling (omitted in
26885 -- longjmp/setjmp mode).
26887 SDP_Table_Build (ST'Address, 23, EA'Address, 23);
26889 -- Call Set_Globals to record various information for
26890 -- this partition. The values are derived by the binder
26891 -- from information stored in the ali files by the compiler.
26893 @findex __gnat_set_globals
26895 (Main_Priority => -1,
26896 -- Priority of main program, -1 if no pragma Priority used
26898 Time_Slice_Value => -1,
26899 -- Time slice from Time_Slice pragma, -1 if none used
26901 WC_Encoding => 'b',
26902 -- Wide_Character encoding used, default is brackets
26904 Locking_Policy => ' ',
26905 -- Locking_Policy used, default of space means not
26906 -- specified, otherwise it is the first character of
26907 -- the policy name.
26909 Queuing_Policy => ' ',
26910 -- Queuing_Policy used, default of space means not
26911 -- specified, otherwise it is the first character of
26912 -- the policy name.
26914 Task_Dispatching_Policy => ' ',
26915 -- Task_Dispatching_Policy used, default of space means
26916 -- not specified, otherwise first character of the
26919 Adafinal => System.Null_Address,
26920 -- Address of Adafinal routine, not used anymore
26922 Unreserve_All_Interrupts => 0,
26923 -- Set true if pragma Unreserve_All_Interrupts was used
26925 Exception_Tracebacks => 0);
26926 -- Indicates if exception tracebacks are enabled
26928 Elab_Final_Code := 1;
26930 -- Now we have the elaboration calls for all units in the partition.
26931 -- The Elab_Spec and Elab_Body attributes generate references to the
26932 -- implicit elaboration procedures generated by the compiler for
26933 -- each unit that requires elaboration.
26936 Interfaces.C_Streams'Elab_Spec;
26940 Ada.Exceptions'Elab_Spec;
26943 System.Exception_Table'Elab_Body;
26947 Ada.Io_Exceptions'Elab_Spec;
26951 System.Exceptions'Elab_Spec;
26955 System.Stack_Checking'Elab_Spec;
26958 System.Soft_Links'Elab_Body;
26963 System.Secondary_Stack'Elab_Body;
26967 Ada.Tags'Elab_Spec;
26970 Ada.Tags'Elab_Body;
26974 Ada.Streams'Elab_Spec;
26978 System.Finalization_Root'Elab_Spec;
26982 Ada.Exceptions'Elab_Body;
26986 System.Finalization_Implementation'Elab_Spec;
26989 System.Finalization_Implementation'Elab_Body;
26993 Ada.Finalization'Elab_Spec;
26997 Ada.Finalization.List_Controller'Elab_Spec;
27001 System.File_Control_Block'Elab_Spec;
27005 System.File_Io'Elab_Body;
27009 Ada.Text_Io'Elab_Spec;
27012 Ada.Text_Io'Elab_Body;
27016 Elab_Final_Code := 0;
27024 procedure adafinal is
27033 -- main is actually a function, as in the ANSI C standard,
27034 -- defined to return the exit status. The three parameters
27035 -- are the argument count, argument values and environment
27038 @findex Main Program
27041 argv : System.Address;
27042 envp : System.Address)
27045 -- The initialize routine performs low level system
27046 -- initialization using a standard library routine which
27047 -- sets up signal handling and performs any other
27048 -- required setup. The routine can be found in file
27051 @findex __gnat_initialize
27052 procedure initialize;
27053 pragma Import (C, initialize, "__gnat_initialize");
27055 -- The finalize routine performs low level system
27056 -- finalization using a standard library routine. The
27057 -- routine is found in file a-final.c and in the standard
27058 -- distribution is a dummy routine that does nothing, so
27059 -- really this is a hook for special user finalization.
27061 @findex __gnat_finalize
27062 procedure finalize;
27063 pragma Import (C, finalize, "__gnat_finalize");
27065 -- We get to the main program of the partition by using
27066 -- pragma Import because if we try to with the unit and
27067 -- call it Ada style, then not only do we waste time
27068 -- recompiling it, but also, we don't really know the right
27069 -- switches (e.g.@: identifier character set) to be used
27072 procedure Ada_Main_Program;
27073 pragma Import (Ada, Ada_Main_Program, "_ada_hello");
27075 -- Start of processing for main
27078 -- Save global variables
27084 -- Call low level system initialization
27088 -- Call our generated Ada initialization routine
27092 -- This is the point at which we want the debugger to get
27097 -- Now we call the main program of the partition
27101 -- Perform Ada finalization
27105 -- Perform low level system finalization
27109 -- Return the proper exit status
27110 return (gnat_exit_status);
27113 -- This section is entirely comments, so it has no effect on the
27114 -- compilation of the Ada_Main package. It provides the list of
27115 -- object files and linker options, as well as some standard
27116 -- libraries needed for the link. The gnatlink utility parses
27117 -- this b~hello.adb file to read these comment lines to generate
27118 -- the appropriate command line arguments for the call to the
27119 -- system linker. The BEGIN/END lines are used for sentinels for
27120 -- this parsing operation.
27122 -- The exact file names will of course depend on the environment,
27123 -- host/target and location of files on the host system.
27125 @findex Object file list
27126 -- BEGIN Object file/option list
27129 -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/
27130 -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a
27131 -- END Object file/option list
27137 The Ada code in the above example is exactly what is generated by the
27138 binder. We have added comments to more clearly indicate the function
27139 of each part of the generated @code{Ada_Main} package.
27141 The code is standard Ada in all respects, and can be processed by any
27142 tools that handle Ada. In particular, it is possible to use the debugger
27143 in Ada mode to debug the generated @code{Ada_Main} package. For example,
27144 suppose that for reasons that you do not understand, your program is crashing
27145 during elaboration of the body of @code{Ada.Text_IO}. To locate this bug,
27146 you can place a breakpoint on the call:
27148 @smallexample @c ada
27149 Ada.Text_Io'Elab_Body;
27153 and trace the elaboration routine for this package to find out where
27154 the problem might be (more usually of course you would be debugging
27155 elaboration code in your own application).
27157 @node Elaboration Order Handling in GNAT
27158 @appendix Elaboration Order Handling in GNAT
27159 @cindex Order of elaboration
27160 @cindex Elaboration control
27163 * Elaboration Code::
27164 * Checking the Elaboration Order::
27165 * Controlling the Elaboration Order::
27166 * Controlling Elaboration in GNAT - Internal Calls::
27167 * Controlling Elaboration in GNAT - External Calls::
27168 * Default Behavior in GNAT - Ensuring Safety::
27169 * Treatment of Pragma Elaborate::
27170 * Elaboration Issues for Library Tasks::
27171 * Mixing Elaboration Models::
27172 * What to Do If the Default Elaboration Behavior Fails::
27173 * Elaboration for Access-to-Subprogram Values::
27174 * Summary of Procedures for Elaboration Control::
27175 * Other Elaboration Order Considerations::
27179 This chapter describes the handling of elaboration code in Ada and
27180 in GNAT, and discusses how the order of elaboration of program units can
27181 be controlled in GNAT, either automatically or with explicit programming
27184 @node Elaboration Code
27185 @section Elaboration Code
27188 Ada provides rather general mechanisms for executing code at elaboration
27189 time, that is to say before the main program starts executing. Such code arises
27193 @item Initializers for variables.
27194 Variables declared at the library level, in package specs or bodies, can
27195 require initialization that is performed at elaboration time, as in:
27196 @smallexample @c ada
27198 Sqrt_Half : Float := Sqrt (0.5);
27202 @item Package initialization code
27203 Code in a @code{BEGIN-END} section at the outer level of a package body is
27204 executed as part of the package body elaboration code.
27206 @item Library level task allocators
27207 Tasks that are declared using task allocators at the library level
27208 start executing immediately and hence can execute at elaboration time.
27212 Subprogram calls are possible in any of these contexts, which means that
27213 any arbitrary part of the program may be executed as part of the elaboration
27214 code. It is even possible to write a program which does all its work at
27215 elaboration time, with a null main program, although stylistically this
27216 would usually be considered an inappropriate way to structure
27219 An important concern arises in the context of elaboration code:
27220 we have to be sure that it is executed in an appropriate order. What we
27221 have is a series of elaboration code sections, potentially one section
27222 for each unit in the program. It is important that these execute
27223 in the correct order. Correctness here means that, taking the above
27224 example of the declaration of @code{Sqrt_Half},
27225 if some other piece of
27226 elaboration code references @code{Sqrt_Half},
27227 then it must run after the
27228 section of elaboration code that contains the declaration of
27231 There would never be any order of elaboration problem if we made a rule
27232 that whenever you @code{with} a unit, you must elaborate both the spec and body
27233 of that unit before elaborating the unit doing the @code{with}'ing:
27235 @smallexample @c ada
27239 package Unit_2 is @dots{}
27245 would require that both the body and spec of @code{Unit_1} be elaborated
27246 before the spec of @code{Unit_2}. However, a rule like that would be far too
27247 restrictive. In particular, it would make it impossible to have routines
27248 in separate packages that were mutually recursive.
27250 You might think that a clever enough compiler could look at the actual
27251 elaboration code and determine an appropriate correct order of elaboration,
27252 but in the general case, this is not possible. Consider the following
27255 In the body of @code{Unit_1}, we have a procedure @code{Func_1}
27257 the variable @code{Sqrt_1}, which is declared in the elaboration code
27258 of the body of @code{Unit_1}:
27260 @smallexample @c ada
27262 Sqrt_1 : Float := Sqrt (0.1);
27267 The elaboration code of the body of @code{Unit_1} also contains:
27269 @smallexample @c ada
27272 if expression_1 = 1 then
27273 Q := Unit_2.Func_2;
27280 @code{Unit_2} is exactly parallel,
27281 it has a procedure @code{Func_2} that references
27282 the variable @code{Sqrt_2}, which is declared in the elaboration code of
27283 the body @code{Unit_2}:
27285 @smallexample @c ada
27287 Sqrt_2 : Float := Sqrt (0.1);
27292 The elaboration code of the body of @code{Unit_2} also contains:
27294 @smallexample @c ada
27297 if expression_2 = 2 then
27298 Q := Unit_1.Func_1;
27305 Now the question is, which of the following orders of elaboration is
27330 If you carefully analyze the flow here, you will see that you cannot tell
27331 at compile time the answer to this question.
27332 If @code{expression_1} is not equal to 1,
27333 and @code{expression_2} is not equal to 2,
27334 then either order is acceptable, because neither of the function calls is
27335 executed. If both tests evaluate to true, then neither order is acceptable
27336 and in fact there is no correct order.
27338 If one of the two expressions is true, and the other is false, then one
27339 of the above orders is correct, and the other is incorrect. For example,
27340 if @code{expression_1} /= 1 and @code{expression_2} = 2,
27341 then the call to @code{Func_1}
27342 will occur, but not the call to @code{Func_2.}
27343 This means that it is essential
27344 to elaborate the body of @code{Unit_1} before
27345 the body of @code{Unit_2}, so the first
27346 order of elaboration is correct and the second is wrong.
27348 By making @code{expression_1} and @code{expression_2}
27349 depend on input data, or perhaps
27350 the time of day, we can make it impossible for the compiler or binder
27351 to figure out which of these expressions will be true, and hence it
27352 is impossible to guarantee a safe order of elaboration at run time.
27354 @node Checking the Elaboration Order
27355 @section Checking the Elaboration Order
27358 In some languages that involve the same kind of elaboration problems,
27359 e.g.@: Java and C++, the programmer is expected to worry about these
27360 ordering problems himself, and it is common to
27361 write a program in which an incorrect elaboration order gives
27362 surprising results, because it references variables before they
27364 Ada is designed to be a safe language, and a programmer-beware approach is
27365 clearly not sufficient. Consequently, the language provides three lines
27369 @item Standard rules
27370 Some standard rules restrict the possible choice of elaboration
27371 order. In particular, if you @code{with} a unit, then its spec is always
27372 elaborated before the unit doing the @code{with}. Similarly, a parent
27373 spec is always elaborated before the child spec, and finally
27374 a spec is always elaborated before its corresponding body.
27376 @item Dynamic elaboration checks
27377 @cindex Elaboration checks
27378 @cindex Checks, elaboration
27379 Dynamic checks are made at run time, so that if some entity is accessed
27380 before it is elaborated (typically by means of a subprogram call)
27381 then the exception (@code{Program_Error}) is raised.
27383 @item Elaboration control
27384 Facilities are provided for the programmer to specify the desired order
27388 Let's look at these facilities in more detail. First, the rules for
27389 dynamic checking. One possible rule would be simply to say that the
27390 exception is raised if you access a variable which has not yet been
27391 elaborated. The trouble with this approach is that it could require
27392 expensive checks on every variable reference. Instead Ada has two
27393 rules which are a little more restrictive, but easier to check, and
27397 @item Restrictions on calls
27398 A subprogram can only be called at elaboration time if its body
27399 has been elaborated. The rules for elaboration given above guarantee
27400 that the spec of the subprogram has been elaborated before the
27401 call, but not the body. If this rule is violated, then the
27402 exception @code{Program_Error} is raised.
27404 @item Restrictions on instantiations
27405 A generic unit can only be instantiated if the body of the generic
27406 unit has been elaborated. Again, the rules for elaboration given above
27407 guarantee that the spec of the generic unit has been elaborated
27408 before the instantiation, but not the body. If this rule is
27409 violated, then the exception @code{Program_Error} is raised.
27413 The idea is that if the body has been elaborated, then any variables
27414 it references must have been elaborated; by checking for the body being
27415 elaborated we guarantee that none of its references causes any
27416 trouble. As we noted above, this is a little too restrictive, because a
27417 subprogram that has no non-local references in its body may in fact be safe
27418 to call. However, it really would be unsafe to rely on this, because
27419 it would mean that the caller was aware of details of the implementation
27420 in the body. This goes against the basic tenets of Ada.
27422 A plausible implementation can be described as follows.
27423 A Boolean variable is associated with each subprogram
27424 and each generic unit. This variable is initialized to False, and is set to
27425 True at the point body is elaborated. Every call or instantiation checks the
27426 variable, and raises @code{Program_Error} if the variable is False.
27428 Note that one might think that it would be good enough to have one Boolean
27429 variable for each package, but that would not deal with cases of trying
27430 to call a body in the same package as the call
27431 that has not been elaborated yet.
27432 Of course a compiler may be able to do enough analysis to optimize away
27433 some of the Boolean variables as unnecessary, and @code{GNAT} indeed
27434 does such optimizations, but still the easiest conceptual model is to
27435 think of there being one variable per subprogram.
27437 @node Controlling the Elaboration Order
27438 @section Controlling the Elaboration Order
27441 In the previous section we discussed the rules in Ada which ensure
27442 that @code{Program_Error} is raised if an incorrect elaboration order is
27443 chosen. This prevents erroneous executions, but we need mechanisms to
27444 specify a correct execution and avoid the exception altogether.
27445 To achieve this, Ada provides a number of features for controlling
27446 the order of elaboration. We discuss these features in this section.
27448 First, there are several ways of indicating to the compiler that a given
27449 unit has no elaboration problems:
27452 @item packages that do not require a body
27453 A library package that does not require a body does not permit
27454 a body (this rule was introduced in Ada 95).
27455 Thus if we have a such a package, as in:
27457 @smallexample @c ada
27460 package Definitions is
27462 type m is new integer;
27464 type a is array (1 .. 10) of m;
27465 type b is array (1 .. 20) of m;
27473 A package that @code{with}'s @code{Definitions} may safely instantiate
27474 @code{Definitions.Subp} because the compiler can determine that there
27475 definitely is no package body to worry about in this case
27478 @cindex pragma Pure
27480 Places sufficient restrictions on a unit to guarantee that
27481 no call to any subprogram in the unit can result in an
27482 elaboration problem. This means that the compiler does not need
27483 to worry about the point of elaboration of such units, and in
27484 particular, does not need to check any calls to any subprograms
27487 @item pragma Preelaborate
27488 @findex Preelaborate
27489 @cindex pragma Preelaborate
27490 This pragma places slightly less stringent restrictions on a unit than
27492 but these restrictions are still sufficient to ensure that there
27493 are no elaboration problems with any calls to the unit.
27495 @item pragma Elaborate_Body
27496 @findex Elaborate_Body
27497 @cindex pragma Elaborate_Body
27498 This pragma requires that the body of a unit be elaborated immediately
27499 after its spec. Suppose a unit @code{A} has such a pragma,
27500 and unit @code{B} does
27501 a @code{with} of unit @code{A}. Recall that the standard rules require
27502 the spec of unit @code{A}
27503 to be elaborated before the @code{with}'ing unit; given the pragma in
27504 @code{A}, we also know that the body of @code{A}
27505 will be elaborated before @code{B}, so
27506 that calls to @code{A} are safe and do not need a check.
27511 unlike pragma @code{Pure} and pragma @code{Preelaborate},
27513 @code{Elaborate_Body} does not guarantee that the program is
27514 free of elaboration problems, because it may not be possible
27515 to satisfy the requested elaboration order.
27516 Let's go back to the example with @code{Unit_1} and @code{Unit_2}.
27518 marks @code{Unit_1} as @code{Elaborate_Body},
27519 and not @code{Unit_2,} then the order of
27520 elaboration will be:
27532 Now that means that the call to @code{Func_1} in @code{Unit_2}
27533 need not be checked,
27534 it must be safe. But the call to @code{Func_2} in
27535 @code{Unit_1} may still fail if
27536 @code{Expression_1} is equal to 1,
27537 and the programmer must still take
27538 responsibility for this not being the case.
27540 If all units carry a pragma @code{Elaborate_Body}, then all problems are
27541 eliminated, except for calls entirely within a body, which are
27542 in any case fully under programmer control. However, using the pragma
27543 everywhere is not always possible.
27544 In particular, for our @code{Unit_1}/@code{Unit_2} example, if
27545 we marked both of them as having pragma @code{Elaborate_Body}, then
27546 clearly there would be no possible elaboration order.
27548 The above pragmas allow a server to guarantee safe use by clients, and
27549 clearly this is the preferable approach. Consequently a good rule
27550 is to mark units as @code{Pure} or @code{Preelaborate} if possible,
27551 and if this is not possible,
27552 mark them as @code{Elaborate_Body} if possible.
27553 As we have seen, there are situations where neither of these
27554 three pragmas can be used.
27555 So we also provide methods for clients to control the
27556 order of elaboration of the servers on which they depend:
27559 @item pragma Elaborate (unit)
27561 @cindex pragma Elaborate
27562 This pragma is placed in the context clause, after a @code{with} clause,
27563 and it requires that the body of the named unit be elaborated before
27564 the unit in which the pragma occurs. The idea is to use this pragma
27565 if the current unit calls at elaboration time, directly or indirectly,
27566 some subprogram in the named unit.
27568 @item pragma Elaborate_All (unit)
27569 @findex Elaborate_All
27570 @cindex pragma Elaborate_All
27571 This is a stronger version of the Elaborate pragma. Consider the
27575 Unit A @code{with}'s unit B and calls B.Func in elab code
27576 Unit B @code{with}'s unit C, and B.Func calls C.Func
27580 Now if we put a pragma @code{Elaborate (B)}
27581 in unit @code{A}, this ensures that the
27582 body of @code{B} is elaborated before the call, but not the
27583 body of @code{C}, so
27584 the call to @code{C.Func} could still cause @code{Program_Error} to
27587 The effect of a pragma @code{Elaborate_All} is stronger, it requires
27588 not only that the body of the named unit be elaborated before the
27589 unit doing the @code{with}, but also the bodies of all units that the
27590 named unit uses, following @code{with} links transitively. For example,
27591 if we put a pragma @code{Elaborate_All (B)} in unit @code{A},
27593 not only that the body of @code{B} be elaborated before @code{A},
27595 body of @code{C}, because @code{B} @code{with}'s @code{C}.
27599 We are now in a position to give a usage rule in Ada for avoiding
27600 elaboration problems, at least if dynamic dispatching and access to
27601 subprogram values are not used. We will handle these cases separately
27604 The rule is simple. If a unit has elaboration code that can directly or
27605 indirectly make a call to a subprogram in a @code{with}'ed unit, or instantiate
27606 a generic package in a @code{with}'ed unit,
27607 then if the @code{with}'ed unit does not have
27608 pragma @code{Pure} or @code{Preelaborate}, then the client should have
27609 a pragma @code{Elaborate_All}
27610 for the @code{with}'ed unit. By following this rule a client is
27611 assured that calls can be made without risk of an exception.
27613 For generic subprogram instantiations, the rule can be relaxed to
27614 require only a pragma @code{Elaborate} since elaborating the body
27615 of a subprogram cannot cause any transitive elaboration (we are
27616 not calling the subprogram in this case, just elaborating its
27619 If this rule is not followed, then a program may be in one of four
27623 @item No order exists
27624 No order of elaboration exists which follows the rules, taking into
27625 account any @code{Elaborate}, @code{Elaborate_All},
27626 or @code{Elaborate_Body} pragmas. In
27627 this case, an Ada compiler must diagnose the situation at bind
27628 time, and refuse to build an executable program.
27630 @item One or more orders exist, all incorrect
27631 One or more acceptable elaboration orders exist, and all of them
27632 generate an elaboration order problem. In this case, the binder
27633 can build an executable program, but @code{Program_Error} will be raised
27634 when the program is run.
27636 @item Several orders exist, some right, some incorrect
27637 One or more acceptable elaboration orders exists, and some of them
27638 work, and some do not. The programmer has not controlled
27639 the order of elaboration, so the binder may or may not pick one of
27640 the correct orders, and the program may or may not raise an
27641 exception when it is run. This is the worst case, because it means
27642 that the program may fail when moved to another compiler, or even
27643 another version of the same compiler.
27645 @item One or more orders exists, all correct
27646 One ore more acceptable elaboration orders exist, and all of them
27647 work. In this case the program runs successfully. This state of
27648 affairs can be guaranteed by following the rule we gave above, but
27649 may be true even if the rule is not followed.
27653 Note that one additional advantage of following our rules on the use
27654 of @code{Elaborate} and @code{Elaborate_All}
27655 is that the program continues to stay in the ideal (all orders OK) state
27656 even if maintenance
27657 changes some bodies of some units. Conversely, if a program that does
27658 not follow this rule happens to be safe at some point, this state of affairs
27659 may deteriorate silently as a result of maintenance changes.
27661 You may have noticed that the above discussion did not mention
27662 the use of @code{Elaborate_Body}. This was a deliberate omission. If you
27663 @code{with} an @code{Elaborate_Body} unit, it still may be the case that
27664 code in the body makes calls to some other unit, so it is still necessary
27665 to use @code{Elaborate_All} on such units.
27667 @node Controlling Elaboration in GNAT - Internal Calls
27668 @section Controlling Elaboration in GNAT - Internal Calls
27671 In the case of internal calls, i.e., calls within a single package, the
27672 programmer has full control over the order of elaboration, and it is up
27673 to the programmer to elaborate declarations in an appropriate order. For
27676 @smallexample @c ada
27679 function One return Float;
27683 function One return Float is
27692 will obviously raise @code{Program_Error} at run time, because function
27693 One will be called before its body is elaborated. In this case GNAT will
27694 generate a warning that the call will raise @code{Program_Error}:
27700 2. function One return Float;
27702 4. Q : Float := One;
27704 >>> warning: cannot call "One" before body is elaborated
27705 >>> warning: Program_Error will be raised at run time
27708 6. function One return Float is
27721 Note that in this particular case, it is likely that the call is safe, because
27722 the function @code{One} does not access any global variables.
27723 Nevertheless in Ada, we do not want the validity of the check to depend on
27724 the contents of the body (think about the separate compilation case), so this
27725 is still wrong, as we discussed in the previous sections.
27727 The error is easily corrected by rearranging the declarations so that the
27728 body of @code{One} appears before the declaration containing the call
27729 (note that in Ada 95 and Ada 2005,
27730 declarations can appear in any order, so there is no restriction that
27731 would prevent this reordering, and if we write:
27733 @smallexample @c ada
27736 function One return Float;
27738 function One return Float is
27749 then all is well, no warning is generated, and no
27750 @code{Program_Error} exception
27752 Things are more complicated when a chain of subprograms is executed:
27754 @smallexample @c ada
27757 function A return Integer;
27758 function B return Integer;
27759 function C return Integer;
27761 function B return Integer is begin return A; end;
27762 function C return Integer is begin return B; end;
27766 function A return Integer is begin return 1; end;
27772 Now the call to @code{C}
27773 at elaboration time in the declaration of @code{X} is correct, because
27774 the body of @code{C} is already elaborated,
27775 and the call to @code{B} within the body of
27776 @code{C} is correct, but the call
27777 to @code{A} within the body of @code{B} is incorrect, because the body
27778 of @code{A} has not been elaborated, so @code{Program_Error}
27779 will be raised on the call to @code{A}.
27780 In this case GNAT will generate a
27781 warning that @code{Program_Error} may be
27782 raised at the point of the call. Let's look at the warning:
27788 2. function A return Integer;
27789 3. function B return Integer;
27790 4. function C return Integer;
27792 6. function B return Integer is begin return A; end;
27794 >>> warning: call to "A" before body is elaborated may
27795 raise Program_Error
27796 >>> warning: "B" called at line 7
27797 >>> warning: "C" called at line 9
27799 7. function C return Integer is begin return B; end;
27801 9. X : Integer := C;
27803 11. function A return Integer is begin return 1; end;
27813 Note that the message here says ``may raise'', instead of the direct case,
27814 where the message says ``will be raised''. That's because whether
27816 actually called depends in general on run-time flow of control.
27817 For example, if the body of @code{B} said
27819 @smallexample @c ada
27822 function B return Integer is
27824 if some-condition-depending-on-input-data then
27835 then we could not know until run time whether the incorrect call to A would
27836 actually occur, so @code{Program_Error} might
27837 or might not be raised. It is possible for a compiler to
27838 do a better job of analyzing bodies, to
27839 determine whether or not @code{Program_Error}
27840 might be raised, but it certainly
27841 couldn't do a perfect job (that would require solving the halting problem
27842 and is provably impossible), and because this is a warning anyway, it does
27843 not seem worth the effort to do the analysis. Cases in which it
27844 would be relevant are rare.
27846 In practice, warnings of either of the forms given
27847 above will usually correspond to
27848 real errors, and should be examined carefully and eliminated.
27849 In the rare case where a warning is bogus, it can be suppressed by any of
27850 the following methods:
27854 Compile with the @option{-gnatws} switch set
27857 Suppress @code{Elaboration_Check} for the called subprogram
27860 Use pragma @code{Warnings_Off} to turn warnings off for the call
27864 For the internal elaboration check case,
27865 GNAT by default generates the
27866 necessary run-time checks to ensure
27867 that @code{Program_Error} is raised if any
27868 call fails an elaboration check. Of course this can only happen if a
27869 warning has been issued as described above. The use of pragma
27870 @code{Suppress (Elaboration_Check)} may (but is not guaranteed to) suppress
27871 some of these checks, meaning that it may be possible (but is not
27872 guaranteed) for a program to be able to call a subprogram whose body
27873 is not yet elaborated, without raising a @code{Program_Error} exception.
27875 @node Controlling Elaboration in GNAT - External Calls
27876 @section Controlling Elaboration in GNAT - External Calls
27879 The previous section discussed the case in which the execution of a
27880 particular thread of elaboration code occurred entirely within a
27881 single unit. This is the easy case to handle, because a programmer
27882 has direct and total control over the order of elaboration, and
27883 furthermore, checks need only be generated in cases which are rare
27884 and which the compiler can easily detect.
27885 The situation is more complex when separate compilation is taken into account.
27886 Consider the following:
27888 @smallexample @c ada
27892 function Sqrt (Arg : Float) return Float;
27895 package body Math is
27896 function Sqrt (Arg : Float) return Float is
27905 X : Float := Math.Sqrt (0.5);
27918 where @code{Main} is the main program. When this program is executed, the
27919 elaboration code must first be executed, and one of the jobs of the
27920 binder is to determine the order in which the units of a program are
27921 to be elaborated. In this case we have four units: the spec and body
27923 the spec of @code{Stuff} and the body of @code{Main}).
27924 In what order should the four separate sections of elaboration code
27927 There are some restrictions in the order of elaboration that the binder
27928 can choose. In particular, if unit U has a @code{with}
27929 for a package @code{X}, then you
27930 are assured that the spec of @code{X}
27931 is elaborated before U , but you are
27932 not assured that the body of @code{X}
27933 is elaborated before U.
27934 This means that in the above case, the binder is allowed to choose the
27945 but that's not good, because now the call to @code{Math.Sqrt}
27946 that happens during
27947 the elaboration of the @code{Stuff}
27948 spec happens before the body of @code{Math.Sqrt} is
27949 elaborated, and hence causes @code{Program_Error} exception to be raised.
27950 At first glance, one might say that the binder is misbehaving, because
27951 obviously you want to elaborate the body of something you @code{with}
27953 that is not a general rule that can be followed in all cases. Consider
27955 @smallexample @c ada
27958 package X is @dots{}
27960 package Y is @dots{}
27963 package body Y is @dots{}
27966 package body X is @dots{}
27972 This is a common arrangement, and, apart from the order of elaboration
27973 problems that might arise in connection with elaboration code, this works fine.
27974 A rule that says that you must first elaborate the body of anything you
27975 @code{with} cannot work in this case:
27976 the body of @code{X} @code{with}'s @code{Y},
27977 which means you would have to
27978 elaborate the body of @code{Y} first, but that @code{with}'s @code{X},
27980 you have to elaborate the body of @code{X} first, but @dots{} and we have a
27981 loop that cannot be broken.
27983 It is true that the binder can in many cases guess an order of elaboration
27984 that is unlikely to cause a @code{Program_Error}
27985 exception to be raised, and it tries to do so (in the
27986 above example of @code{Math/Stuff/Spec}, the GNAT binder will
27988 elaborate the body of @code{Math} right after its spec, so all will be well).
27990 However, a program that blindly relies on the binder to be helpful can
27991 get into trouble, as we discussed in the previous sections, so
27993 provides a number of facilities for assisting the programmer in
27994 developing programs that are robust with respect to elaboration order.
27996 @node Default Behavior in GNAT - Ensuring Safety
27997 @section Default Behavior in GNAT - Ensuring Safety
28000 The default behavior in GNAT ensures elaboration safety. In its
28001 default mode GNAT implements the
28002 rule we previously described as the right approach. Let's restate it:
28006 @emph{If a unit has elaboration code that can directly or indirectly make a
28007 call to a subprogram in a @code{with}'ed unit, or instantiate a generic
28008 package in a @code{with}'ed unit, then if the @code{with}'ed unit
28009 does not have pragma @code{Pure} or
28010 @code{Preelaborate}, then the client should have an
28011 @code{Elaborate_All} pragma for the @code{with}'ed unit.}
28013 @emph{In the case of instantiating a generic subprogram, it is always
28014 sufficient to have only an @code{Elaborate} pragma for the
28015 @code{with}'ed unit.}
28019 By following this rule a client is assured that calls and instantiations
28020 can be made without risk of an exception.
28022 In this mode GNAT traces all calls that are potentially made from
28023 elaboration code, and puts in any missing implicit @code{Elaborate}
28024 and @code{Elaborate_All} pragmas.
28025 The advantage of this approach is that no elaboration problems
28026 are possible if the binder can find an elaboration order that is
28027 consistent with these implicit @code{Elaborate} and
28028 @code{Elaborate_All} pragmas. The
28029 disadvantage of this approach is that no such order may exist.
28031 If the binder does not generate any diagnostics, then it means that it has
28032 found an elaboration order that is guaranteed to be safe. However, the binder
28033 may still be relying on implicitly generated @code{Elaborate} and
28034 @code{Elaborate_All} pragmas so portability to other compilers than GNAT is not
28037 If it is important to guarantee portability, then the compilations should
28040 (warn on elaboration problems) switch. This will cause warning messages
28041 to be generated indicating the missing @code{Elaborate} and
28042 @code{Elaborate_All} pragmas.
28043 Consider the following source program:
28045 @smallexample @c ada
28050 m : integer := k.r;
28057 where it is clear that there
28058 should be a pragma @code{Elaborate_All}
28059 for unit @code{k}. An implicit pragma will be generated, and it is
28060 likely that the binder will be able to honor it. However, if you want
28061 to port this program to some other Ada compiler than GNAT.
28062 it is safer to include the pragma explicitly in the source. If this
28063 unit is compiled with the
28065 switch, then the compiler outputs a warning:
28072 3. m : integer := k.r;
28074 >>> warning: call to "r" may raise Program_Error
28075 >>> warning: missing pragma Elaborate_All for "k"
28083 and these warnings can be used as a guide for supplying manually
28084 the missing pragmas. It is usually a bad idea to use this warning
28085 option during development. That's because it will warn you when
28086 you need to put in a pragma, but cannot warn you when it is time
28087 to take it out. So the use of pragma @code{Elaborate_All} may lead to
28088 unnecessary dependencies and even false circularities.
28090 This default mode is more restrictive than the Ada Reference
28091 Manual, and it is possible to construct programs which will compile
28092 using the dynamic model described there, but will run into a
28093 circularity using the safer static model we have described.
28095 Of course any Ada compiler must be able to operate in a mode
28096 consistent with the requirements of the Ada Reference Manual,
28097 and in particular must have the capability of implementing the
28098 standard dynamic model of elaboration with run-time checks.
28100 In GNAT, this standard mode can be achieved either by the use of
28101 the @option{-gnatE} switch on the compiler (@command{gcc} or
28102 @command{gnatmake}) command, or by the use of the configuration pragma:
28104 @smallexample @c ada
28105 pragma Elaboration_Checks (RM);
28109 Either approach will cause the unit affected to be compiled using the
28110 standard dynamic run-time elaboration checks described in the Ada
28111 Reference Manual. The static model is generally preferable, since it
28112 is clearly safer to rely on compile and link time checks rather than
28113 run-time checks. However, in the case of legacy code, it may be
28114 difficult to meet the requirements of the static model. This
28115 issue is further discussed in
28116 @ref{What to Do If the Default Elaboration Behavior Fails}.
28118 Note that the static model provides a strict subset of the allowed
28119 behavior and programs of the Ada Reference Manual, so if you do
28120 adhere to the static model and no circularities exist,
28121 then you are assured that your program will
28122 work using the dynamic model, providing that you remove any
28123 pragma Elaborate statements from the source.
28125 @node Treatment of Pragma Elaborate
28126 @section Treatment of Pragma Elaborate
28127 @cindex Pragma Elaborate
28130 The use of @code{pragma Elaborate}
28131 should generally be avoided in Ada 95 and Ada 2005 programs,
28132 since there is no guarantee that transitive calls
28133 will be properly handled. Indeed at one point, this pragma was placed
28134 in Annex J (Obsolescent Features), on the grounds that it is never useful.
28136 Now that's a bit restrictive. In practice, the case in which
28137 @code{pragma Elaborate} is useful is when the caller knows that there
28138 are no transitive calls, or that the called unit contains all necessary
28139 transitive @code{pragma Elaborate} statements, and legacy code often
28140 contains such uses.
28142 Strictly speaking the static mode in GNAT should ignore such pragmas,
28143 since there is no assurance at compile time that the necessary safety
28144 conditions are met. In practice, this would cause GNAT to be incompatible
28145 with correctly written Ada 83 code that had all necessary
28146 @code{pragma Elaborate} statements in place. Consequently, we made the
28147 decision that GNAT in its default mode will believe that if it encounters
28148 a @code{pragma Elaborate} then the programmer knows what they are doing,
28149 and it will trust that no elaboration errors can occur.
28151 The result of this decision is two-fold. First to be safe using the
28152 static mode, you should remove all @code{pragma Elaborate} statements.
28153 Second, when fixing circularities in existing code, you can selectively
28154 use @code{pragma Elaborate} statements to convince the static mode of
28155 GNAT that it need not generate an implicit @code{pragma Elaborate_All}
28158 When using the static mode with @option{-gnatwl}, any use of
28159 @code{pragma Elaborate} will generate a warning about possible
28162 @node Elaboration Issues for Library Tasks
28163 @section Elaboration Issues for Library Tasks
28164 @cindex Library tasks, elaboration issues
28165 @cindex Elaboration of library tasks
28168 In this section we examine special elaboration issues that arise for
28169 programs that declare library level tasks.
28171 Generally the model of execution of an Ada program is that all units are
28172 elaborated, and then execution of the program starts. However, the
28173 declaration of library tasks definitely does not fit this model. The
28174 reason for this is that library tasks start as soon as they are declared
28175 (more precisely, as soon as the statement part of the enclosing package
28176 body is reached), that is to say before elaboration
28177 of the program is complete. This means that if such a task calls a
28178 subprogram, or an entry in another task, the callee may or may not be
28179 elaborated yet, and in the standard
28180 Reference Manual model of dynamic elaboration checks, you can even
28181 get timing dependent Program_Error exceptions, since there can be
28182 a race between the elaboration code and the task code.
28184 The static model of elaboration in GNAT seeks to avoid all such
28185 dynamic behavior, by being conservative, and the conservative
28186 approach in this particular case is to assume that all the code
28187 in a task body is potentially executed at elaboration time if
28188 a task is declared at the library level.
28190 This can definitely result in unexpected circularities. Consider
28191 the following example
28193 @smallexample @c ada
28199 type My_Int is new Integer;
28201 function Ident (M : My_Int) return My_Int;
28205 package body Decls is
28206 task body Lib_Task is
28212 function Ident (M : My_Int) return My_Int is
28220 procedure Put_Val (Arg : Decls.My_Int);
28224 package body Utils is
28225 procedure Put_Val (Arg : Decls.My_Int) is
28227 Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg)));
28234 Decls.Lib_Task.Start;
28239 If the above example is compiled in the default static elaboration
28240 mode, then a circularity occurs. The circularity comes from the call
28241 @code{Utils.Put_Val} in the task body of @code{Decls.Lib_Task}. Since
28242 this call occurs in elaboration code, we need an implicit pragma
28243 @code{Elaborate_All} for @code{Utils}. This means that not only must
28244 the spec and body of @code{Utils} be elaborated before the body
28245 of @code{Decls}, but also the spec and body of any unit that is
28246 @code{with'ed} by the body of @code{Utils} must also be elaborated before
28247 the body of @code{Decls}. This is the transitive implication of
28248 pragma @code{Elaborate_All} and it makes sense, because in general
28249 the body of @code{Put_Val} might have a call to something in a
28250 @code{with'ed} unit.
28252 In this case, the body of Utils (actually its spec) @code{with's}
28253 @code{Decls}. Unfortunately this means that the body of @code{Decls}
28254 must be elaborated before itself, in case there is a call from the
28255 body of @code{Utils}.
28257 Here is the exact chain of events we are worrying about:
28261 In the body of @code{Decls} a call is made from within the body of a library
28262 task to a subprogram in the package @code{Utils}. Since this call may
28263 occur at elaboration time (given that the task is activated at elaboration
28264 time), we have to assume the worst, i.e., that the
28265 call does happen at elaboration time.
28268 This means that the body and spec of @code{Util} must be elaborated before
28269 the body of @code{Decls} so that this call does not cause an access before
28273 Within the body of @code{Util}, specifically within the body of
28274 @code{Util.Put_Val} there may be calls to any unit @code{with}'ed
28278 One such @code{with}'ed package is package @code{Decls}, so there
28279 might be a call to a subprogram in @code{Decls} in @code{Put_Val}.
28280 In fact there is such a call in this example, but we would have to
28281 assume that there was such a call even if it were not there, since
28282 we are not supposed to write the body of @code{Decls} knowing what
28283 is in the body of @code{Utils}; certainly in the case of the
28284 static elaboration model, the compiler does not know what is in
28285 other bodies and must assume the worst.
28288 This means that the spec and body of @code{Decls} must also be
28289 elaborated before we elaborate the unit containing the call, but
28290 that unit is @code{Decls}! This means that the body of @code{Decls}
28291 must be elaborated before itself, and that's a circularity.
28295 Indeed, if you add an explicit pragma @code{Elaborate_All} for @code{Utils} in
28296 the body of @code{Decls} you will get a true Ada Reference Manual
28297 circularity that makes the program illegal.
28299 In practice, we have found that problems with the static model of
28300 elaboration in existing code often arise from library tasks, so
28301 we must address this particular situation.
28303 Note that if we compile and run the program above, using the dynamic model of
28304 elaboration (that is to say use the @option{-gnatE} switch),
28305 then it compiles, binds,
28306 links, and runs, printing the expected result of 2. Therefore in some sense
28307 the circularity here is only apparent, and we need to capture
28308 the properties of this program that distinguish it from other library-level
28309 tasks that have real elaboration problems.
28311 We have four possible answers to this question:
28316 Use the dynamic model of elaboration.
28318 If we use the @option{-gnatE} switch, then as noted above, the program works.
28319 Why is this? If we examine the task body, it is apparent that the task cannot
28321 @code{accept} statement until after elaboration has been completed, because
28322 the corresponding entry call comes from the main program, not earlier.
28323 This is why the dynamic model works here. But that's really giving
28324 up on a precise analysis, and we prefer to take this approach only if we cannot
28326 problem in any other manner. So let us examine two ways to reorganize
28327 the program to avoid the potential elaboration problem.
28330 Split library tasks into separate packages.
28332 Write separate packages, so that library tasks are isolated from
28333 other declarations as much as possible. Let us look at a variation on
28336 @smallexample @c ada
28344 package body Decls1 is
28345 task body Lib_Task is
28353 type My_Int is new Integer;
28354 function Ident (M : My_Int) return My_Int;
28358 package body Decls2 is
28359 function Ident (M : My_Int) return My_Int is
28367 procedure Put_Val (Arg : Decls2.My_Int);
28371 package body Utils is
28372 procedure Put_Val (Arg : Decls2.My_Int) is
28374 Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg)));
28381 Decls1.Lib_Task.Start;
28386 All we have done is to split @code{Decls} into two packages, one
28387 containing the library task, and one containing everything else. Now
28388 there is no cycle, and the program compiles, binds, links and executes
28389 using the default static model of elaboration.
28392 Declare separate task types.
28394 A significant part of the problem arises because of the use of the
28395 single task declaration form. This means that the elaboration of
28396 the task type, and the elaboration of the task itself (i.e.@: the
28397 creation of the task) happen at the same time. A good rule
28398 of style in Ada is to always create explicit task types. By
28399 following the additional step of placing task objects in separate
28400 packages from the task type declaration, many elaboration problems
28401 are avoided. Here is another modified example of the example program:
28403 @smallexample @c ada
28405 task type Lib_Task_Type is
28409 type My_Int is new Integer;
28411 function Ident (M : My_Int) return My_Int;
28415 package body Decls is
28416 task body Lib_Task_Type is
28422 function Ident (M : My_Int) return My_Int is
28430 procedure Put_Val (Arg : Decls.My_Int);
28434 package body Utils is
28435 procedure Put_Val (Arg : Decls.My_Int) is
28437 Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg)));
28443 Lib_Task : Decls.Lib_Task_Type;
28449 Declst.Lib_Task.Start;
28454 What we have done here is to replace the @code{task} declaration in
28455 package @code{Decls} with a @code{task type} declaration. Then we
28456 introduce a separate package @code{Declst} to contain the actual
28457 task object. This separates the elaboration issues for
28458 the @code{task type}
28459 declaration, which causes no trouble, from the elaboration issues
28460 of the task object, which is also unproblematic, since it is now independent
28461 of the elaboration of @code{Utils}.
28462 This separation of concerns also corresponds to
28463 a generally sound engineering principle of separating declarations
28464 from instances. This version of the program also compiles, binds, links,
28465 and executes, generating the expected output.
28468 Use No_Entry_Calls_In_Elaboration_Code restriction.
28469 @cindex No_Entry_Calls_In_Elaboration_Code
28471 The previous two approaches described how a program can be restructured
28472 to avoid the special problems caused by library task bodies. in practice,
28473 however, such restructuring may be difficult to apply to existing legacy code,
28474 so we must consider solutions that do not require massive rewriting.
28476 Let us consider more carefully why our original sample program works
28477 under the dynamic model of elaboration. The reason is that the code
28478 in the task body blocks immediately on the @code{accept}
28479 statement. Now of course there is nothing to prohibit elaboration
28480 code from making entry calls (for example from another library level task),
28481 so we cannot tell in isolation that
28482 the task will not execute the accept statement during elaboration.
28484 However, in practice it is very unusual to see elaboration code
28485 make any entry calls, and the pattern of tasks starting
28486 at elaboration time and then immediately blocking on @code{accept} or
28487 @code{select} statements is very common. What this means is that
28488 the compiler is being too pessimistic when it analyzes the
28489 whole package body as though it might be executed at elaboration
28492 If we know that the elaboration code contains no entry calls, (a very safe
28493 assumption most of the time, that could almost be made the default
28494 behavior), then we can compile all units of the program under control
28495 of the following configuration pragma:
28498 pragma Restrictions (No_Entry_Calls_In_Elaboration_Code);
28502 This pragma can be placed in the @file{gnat.adc} file in the usual
28503 manner. If we take our original unmodified program and compile it
28504 in the presence of a @file{gnat.adc} containing the above pragma,
28505 then once again, we can compile, bind, link, and execute, obtaining
28506 the expected result. In the presence of this pragma, the compiler does
28507 not trace calls in a task body, that appear after the first @code{accept}
28508 or @code{select} statement, and therefore does not report a potential
28509 circularity in the original program.
28511 The compiler will check to the extent it can that the above
28512 restriction is not violated, but it is not always possible to do a
28513 complete check at compile time, so it is important to use this
28514 pragma only if the stated restriction is in fact met, that is to say
28515 no task receives an entry call before elaboration of all units is completed.
28519 @node Mixing Elaboration Models
28520 @section Mixing Elaboration Models
28522 So far, we have assumed that the entire program is either compiled
28523 using the dynamic model or static model, ensuring consistency. It
28524 is possible to mix the two models, but rules have to be followed
28525 if this mixing is done to ensure that elaboration checks are not
28528 The basic rule is that @emph{a unit compiled with the static model cannot
28529 be @code{with'ed} by a unit compiled with the dynamic model}. The
28530 reason for this is that in the static model, a unit assumes that
28531 its clients guarantee to use (the equivalent of) pragma
28532 @code{Elaborate_All} so that no elaboration checks are required
28533 in inner subprograms, and this assumption is violated if the
28534 client is compiled with dynamic checks.
28536 The precise rule is as follows. A unit that is compiled with dynamic
28537 checks can only @code{with} a unit that meets at least one of the
28538 following criteria:
28543 The @code{with'ed} unit is itself compiled with dynamic elaboration
28544 checks (that is with the @option{-gnatE} switch.
28547 The @code{with'ed} unit is an internal GNAT implementation unit from
28548 the System, Interfaces, Ada, or GNAT hierarchies.
28551 The @code{with'ed} unit has pragma Preelaborate or pragma Pure.
28554 The @code{with'ing} unit (that is the client) has an explicit pragma
28555 @code{Elaborate_All} for the @code{with'ed} unit.
28560 If this rule is violated, that is if a unit with dynamic elaboration
28561 checks @code{with's} a unit that does not meet one of the above four
28562 criteria, then the binder (@code{gnatbind}) will issue a warning
28563 similar to that in the following example:
28566 warning: "x.ads" has dynamic elaboration checks and with's
28567 warning: "y.ads" which has static elaboration checks
28571 These warnings indicate that the rule has been violated, and that as a result
28572 elaboration checks may be missed in the resulting executable file.
28573 This warning may be suppressed using the @option{-ws} binder switch
28574 in the usual manner.
28576 One useful application of this mixing rule is in the case of a subsystem
28577 which does not itself @code{with} units from the remainder of the
28578 application. In this case, the entire subsystem can be compiled with
28579 dynamic checks to resolve a circularity in the subsystem, while
28580 allowing the main application that uses this subsystem to be compiled
28581 using the more reliable default static model.
28583 @node What to Do If the Default Elaboration Behavior Fails
28584 @section What to Do If the Default Elaboration Behavior Fails
28587 If the binder cannot find an acceptable order, it outputs detailed
28588 diagnostics. For example:
28594 error: elaboration circularity detected
28595 info: "proc (body)" must be elaborated before "pack (body)"
28596 info: reason: Elaborate_All probably needed in unit "pack (body)"
28597 info: recompile "pack (body)" with -gnatwl
28598 info: for full details
28599 info: "proc (body)"
28600 info: is needed by its spec:
28601 info: "proc (spec)"
28602 info: which is withed by:
28603 info: "pack (body)"
28604 info: "pack (body)" must be elaborated before "proc (body)"
28605 info: reason: pragma Elaborate in unit "proc (body)"
28611 In this case we have a cycle that the binder cannot break. On the one
28612 hand, there is an explicit pragma Elaborate in @code{proc} for
28613 @code{pack}. This means that the body of @code{pack} must be elaborated
28614 before the body of @code{proc}. On the other hand, there is elaboration
28615 code in @code{pack} that calls a subprogram in @code{proc}. This means
28616 that for maximum safety, there should really be a pragma
28617 Elaborate_All in @code{pack} for @code{proc} which would require that
28618 the body of @code{proc} be elaborated before the body of
28619 @code{pack}. Clearly both requirements cannot be satisfied.
28620 Faced with a circularity of this kind, you have three different options.
28623 @item Fix the program
28624 The most desirable option from the point of view of long-term maintenance
28625 is to rearrange the program so that the elaboration problems are avoided.
28626 One useful technique is to place the elaboration code into separate
28627 child packages. Another is to move some of the initialization code to
28628 explicitly called subprograms, where the program controls the order
28629 of initialization explicitly. Although this is the most desirable option,
28630 it may be impractical and involve too much modification, especially in
28631 the case of complex legacy code.
28633 @item Perform dynamic checks
28634 If the compilations are done using the
28636 (dynamic elaboration check) switch, then GNAT behaves in a quite different
28637 manner. Dynamic checks are generated for all calls that could possibly result
28638 in raising an exception. With this switch, the compiler does not generate
28639 implicit @code{Elaborate} or @code{Elaborate_All} pragmas. The behavior then is
28640 exactly as specified in the @cite{Ada Reference Manual}.
28641 The binder will generate
28642 an executable program that may or may not raise @code{Program_Error}, and then
28643 it is the programmer's job to ensure that it does not raise an exception. Note
28644 that it is important to compile all units with the switch, it cannot be used
28647 @item Suppress checks
28648 The drawback of dynamic checks is that they generate a
28649 significant overhead at run time, both in space and time. If you
28650 are absolutely sure that your program cannot raise any elaboration
28651 exceptions, and you still want to use the dynamic elaboration model,
28652 then you can use the configuration pragma
28653 @code{Suppress (Elaboration_Check)} to suppress all such checks. For
28654 example this pragma could be placed in the @file{gnat.adc} file.
28656 @item Suppress checks selectively
28657 When you know that certain calls or instantiations in elaboration code cannot
28658 possibly lead to an elaboration error, and the binder nevertheless complains
28659 about implicit @code{Elaborate} and @code{Elaborate_All} pragmas that lead to
28660 elaboration circularities, it is possible to remove those warnings locally and
28661 obtain a program that will bind. Clearly this can be unsafe, and it is the
28662 responsibility of the programmer to make sure that the resulting program has no
28663 elaboration anomalies. The pragma @code{Suppress (Elaboration_Check)} can be
28664 used with different granularity to suppress warnings and break elaboration
28669 Place the pragma that names the called subprogram in the declarative part
28670 that contains the call.
28673 Place the pragma in the declarative part, without naming an entity. This
28674 disables warnings on all calls in the corresponding declarative region.
28677 Place the pragma in the package spec that declares the called subprogram,
28678 and name the subprogram. This disables warnings on all elaboration calls to
28682 Place the pragma in the package spec that declares the called subprogram,
28683 without naming any entity. This disables warnings on all elaboration calls to
28684 all subprograms declared in this spec.
28686 @item Use Pragma Elaborate
28687 As previously described in section @xref{Treatment of Pragma Elaborate},
28688 GNAT in static mode assumes that a @code{pragma} Elaborate indicates correctly
28689 that no elaboration checks are required on calls to the designated unit.
28690 There may be cases in which the caller knows that no transitive calls
28691 can occur, so that a @code{pragma Elaborate} will be sufficient in a
28692 case where @code{pragma Elaborate_All} would cause a circularity.
28696 These five cases are listed in order of decreasing safety, and therefore
28697 require increasing programmer care in their application. Consider the
28700 @smallexample @c adanocomment
28702 function F1 return Integer;
28707 function F2 return Integer;
28708 function Pure (x : integer) return integer;
28709 -- pragma Suppress (Elaboration_Check, On => Pure); -- (3)
28710 -- pragma Suppress (Elaboration_Check); -- (4)
28714 package body Pack1 is
28715 function F1 return Integer is
28719 Val : integer := Pack2.Pure (11); -- Elab. call (1)
28722 -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1)
28723 -- pragma Suppress(Elaboration_Check); -- (2)
28725 X1 := Pack2.F2 + 1; -- Elab. call (2)
28730 package body Pack2 is
28731 function F2 return Integer is
28735 function Pure (x : integer) return integer is
28737 return x ** 3 - 3 * x;
28741 with Pack1, Ada.Text_IO;
28744 Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101
28747 In the absence of any pragmas, an attempt to bind this program produces
28748 the following diagnostics:
28754 error: elaboration circularity detected
28755 info: "pack1 (body)" must be elaborated before "pack1 (body)"
28756 info: reason: Elaborate_All probably needed in unit "pack1 (body)"
28757 info: recompile "pack1 (body)" with -gnatwl for full details
28758 info: "pack1 (body)"
28759 info: must be elaborated along with its spec:
28760 info: "pack1 (spec)"
28761 info: which is withed by:
28762 info: "pack2 (body)"
28763 info: which must be elaborated along with its spec:
28764 info: "pack2 (spec)"
28765 info: which is withed by:
28766 info: "pack1 (body)"
28769 The sources of the circularity are the two calls to @code{Pack2.Pure} and
28770 @code{Pack2.F2} in the body of @code{Pack1}. We can see that the call to
28771 F2 is safe, even though F2 calls F1, because the call appears after the
28772 elaboration of the body of F1. Therefore the pragma (1) is safe, and will
28773 remove the warning on the call. It is also possible to use pragma (2)
28774 because there are no other potentially unsafe calls in the block.
28777 The call to @code{Pure} is safe because this function does not depend on the
28778 state of @code{Pack2}. Therefore any call to this function is safe, and it
28779 is correct to place pragma (3) in the corresponding package spec.
28782 Finally, we could place pragma (4) in the spec of @code{Pack2} to disable
28783 warnings on all calls to functions declared therein. Note that this is not
28784 necessarily safe, and requires more detailed examination of the subprogram
28785 bodies involved. In particular, a call to @code{F2} requires that @code{F1}
28786 be already elaborated.
28790 It is hard to generalize on which of these four approaches should be
28791 taken. Obviously if it is possible to fix the program so that the default
28792 treatment works, this is preferable, but this may not always be practical.
28793 It is certainly simple enough to use
28795 but the danger in this case is that, even if the GNAT binder
28796 finds a correct elaboration order, it may not always do so,
28797 and certainly a binder from another Ada compiler might not. A
28798 combination of testing and analysis (for which the warnings generated
28801 switch can be useful) must be used to ensure that the program is free
28802 of errors. One switch that is useful in this testing is the
28803 @option{^-p (pessimistic elaboration order)^/PESSIMISTIC_ELABORATION_ORDER^}
28806 Normally the binder tries to find an order that has the best chance
28807 of avoiding elaboration problems. However, if this switch is used, the binder
28808 plays a devil's advocate role, and tries to choose the order that
28809 has the best chance of failing. If your program works even with this
28810 switch, then it has a better chance of being error free, but this is still
28813 For an example of this approach in action, consider the C-tests (executable
28814 tests) from the ACVC suite. If these are compiled and run with the default
28815 treatment, then all but one of them succeed without generating any error
28816 diagnostics from the binder. However, there is one test that fails, and
28817 this is not surprising, because the whole point of this test is to ensure
28818 that the compiler can handle cases where it is impossible to determine
28819 a correct order statically, and it checks that an exception is indeed
28820 raised at run time.
28822 This one test must be compiled and run using the
28824 switch, and then it passes. Alternatively, the entire suite can
28825 be run using this switch. It is never wrong to run with the dynamic
28826 elaboration switch if your code is correct, and we assume that the
28827 C-tests are indeed correct (it is less efficient, but efficiency is
28828 not a factor in running the ACVC tests.)
28830 @node Elaboration for Access-to-Subprogram Values
28831 @section Elaboration for Access-to-Subprogram Values
28832 @cindex Access-to-subprogram
28835 Access-to-subprogram types (introduced in Ada 95) complicate
28836 the handling of elaboration. The trouble is that it becomes
28837 impossible to tell at compile time which procedure
28838 is being called. This means that it is not possible for the binder
28839 to analyze the elaboration requirements in this case.
28841 If at the point at which the access value is created
28842 (i.e., the evaluation of @code{P'Access} for a subprogram @code{P}),
28843 the body of the subprogram is
28844 known to have been elaborated, then the access value is safe, and its use
28845 does not require a check. This may be achieved by appropriate arrangement
28846 of the order of declarations if the subprogram is in the current unit,
28847 or, if the subprogram is in another unit, by using pragma
28848 @code{Pure}, @code{Preelaborate}, or @code{Elaborate_Body}
28849 on the referenced unit.
28851 If the referenced body is not known to have been elaborated at the point
28852 the access value is created, then any use of the access value must do a
28853 dynamic check, and this dynamic check will fail and raise a
28854 @code{Program_Error} exception if the body has not been elaborated yet.
28855 GNAT will generate the necessary checks, and in addition, if the
28857 switch is set, will generate warnings that such checks are required.
28859 The use of dynamic dispatching for tagged types similarly generates
28860 a requirement for dynamic checks, and premature calls to any primitive
28861 operation of a tagged type before the body of the operation has been
28862 elaborated, will result in the raising of @code{Program_Error}.
28864 @node Summary of Procedures for Elaboration Control
28865 @section Summary of Procedures for Elaboration Control
28866 @cindex Elaboration control
28869 First, compile your program with the default options, using none of
28870 the special elaboration control switches. If the binder successfully
28871 binds your program, then you can be confident that, apart from issues
28872 raised by the use of access-to-subprogram types and dynamic dispatching,
28873 the program is free of elaboration errors. If it is important that the
28874 program be portable, then use the
28876 switch to generate warnings about missing @code{Elaborate} or
28877 @code{Elaborate_All} pragmas, and supply the missing pragmas.
28879 If the program fails to bind using the default static elaboration
28880 handling, then you can fix the program to eliminate the binder
28881 message, or recompile the entire program with the
28882 @option{-gnatE} switch to generate dynamic elaboration checks,
28883 and, if you are sure there really are no elaboration problems,
28884 use a global pragma @code{Suppress (Elaboration_Check)}.
28886 @node Other Elaboration Order Considerations
28887 @section Other Elaboration Order Considerations
28889 This section has been entirely concerned with the issue of finding a valid
28890 elaboration order, as defined by the Ada Reference Manual. In a case
28891 where several elaboration orders are valid, the task is to find one
28892 of the possible valid elaboration orders (and the static model in GNAT
28893 will ensure that this is achieved).
28895 The purpose of the elaboration rules in the Ada Reference Manual is to
28896 make sure that no entity is accessed before it has been elaborated. For
28897 a subprogram, this means that the spec and body must have been elaborated
28898 before the subprogram is called. For an object, this means that the object
28899 must have been elaborated before its value is read or written. A violation
28900 of either of these two requirements is an access before elaboration order,
28901 and this section has been all about avoiding such errors.
28903 In the case where more than one order of elaboration is possible, in the
28904 sense that access before elaboration errors are avoided, then any one of
28905 the orders is ``correct'' in the sense that it meets the requirements of
28906 the Ada Reference Manual, and no such error occurs.
28908 However, it may be the case for a given program, that there are
28909 constraints on the order of elaboration that come not from consideration
28910 of avoiding elaboration errors, but rather from extra-lingual logic
28911 requirements. Consider this example:
28913 @smallexample @c ada
28914 with Init_Constants;
28915 package Constants is
28920 package Init_Constants is
28921 procedure P; -- require a body
28922 end Init_Constants;
28925 package body Init_Constants is
28926 procedure P is begin null; end;
28930 end Init_Constants;
28934 Z : Integer := Constants.X + Constants.Y;
28938 with Text_IO; use Text_IO;
28941 Put_Line (Calc.Z'Img);
28946 In this example, there is more than one valid order of elaboration. For
28947 example both the following are correct orders:
28950 Init_Constants spec
28953 Init_Constants body
28958 Init_Constants spec
28959 Init_Constants body
28966 There is no language rule to prefer one or the other, both are correct
28967 from an order of elaboration point of view. But the programmatic effects
28968 of the two orders are very different. In the first, the elaboration routine
28969 of @code{Calc} initializes @code{Z} to zero, and then the main program
28970 runs with this value of zero. But in the second order, the elaboration
28971 routine of @code{Calc} runs after the body of Init_Constants has set
28972 @code{X} and @code{Y} and thus @code{Z} is set to 7 before @code{Main}
28975 One could perhaps by applying pretty clever non-artificial intelligence
28976 to the situation guess that it is more likely that the second order of
28977 elaboration is the one desired, but there is no formal linguistic reason
28978 to prefer one over the other. In fact in this particular case, GNAT will
28979 prefer the second order, because of the rule that bodies are elaborated
28980 as soon as possible, but it's just luck that this is what was wanted
28981 (if indeed the second order was preferred).
28983 If the program cares about the order of elaboration routines in a case like
28984 this, it is important to specify the order required. In this particular
28985 case, that could have been achieved by adding to the spec of Calc:
28987 @smallexample @c ada
28988 pragma Elaborate_All (Constants);
28992 which requires that the body (if any) and spec of @code{Constants},
28993 as well as the body and spec of any unit @code{with}'ed by
28994 @code{Constants} be elaborated before @code{Calc} is elaborated.
28996 Clearly no automatic method can always guess which alternative you require,
28997 and if you are working with legacy code that had constraints of this kind
28998 which were not properly specified by adding @code{Elaborate} or
28999 @code{Elaborate_All} pragmas, then indeed it is possible that two different
29000 compilers can choose different orders.
29002 However, GNAT does attempt to diagnose the common situation where there
29003 are uninitialized variables in the visible part of a package spec, and the
29004 corresponding package body has an elaboration block that directly or
29005 indirectly initialized one or more of these variables. This is the situation
29006 in which a pragma Elaborate_Body is usually desirable, and GNAT will generate
29007 a warning that suggests this addition if it detects this situation.
29009 The @code{gnatbind}
29010 @option{^-p^/PESSIMISTIC_ELABORATION^} switch may be useful in smoking
29011 out problems. This switch causes bodies to be elaborated as late as possible
29012 instead of as early as possible. In the example above, it would have forced
29013 the choice of the first elaboration order. If you get different results
29014 when using this switch, and particularly if one set of results is right,
29015 and one is wrong as far as you are concerned, it shows that you have some
29016 missing @code{Elaborate} pragmas. For the example above, we have the
29020 gnatmake -f -q main
29023 gnatmake -f -q main -bargs -p
29029 It is of course quite unlikely that both these results are correct, so
29030 it is up to you in a case like this to investigate the source of the
29031 difference, by looking at the two elaboration orders that are chosen,
29032 and figuring out which is correct, and then adding the necessary
29033 @code{Elaborate} or @code{Elaborate_All} pragmas to ensure the desired order.
29037 @c *******************************
29038 @node Conditional Compilation
29039 @appendix Conditional Compilation
29040 @c *******************************
29041 @cindex Conditional compilation
29044 It is often necessary to arrange for a single source program
29045 to serve multiple purposes, where it is compiled in different
29046 ways to achieve these different goals. Some examples of the
29047 need for this feature are
29050 @item Adapting a program to a different hardware environment
29051 @item Adapting a program to a different target architecture
29052 @item Turning debugging features on and off
29053 @item Arranging for a program to compile with different compilers
29057 In C, or C++, the typical approach would be to use the preprocessor
29058 that is defined as part of the language. The Ada language does not
29059 contain such a feature. This is not an oversight, but rather a very
29060 deliberate design decision, based on the experience that overuse of
29061 the preprocessing features in C and C++ can result in programs that
29062 are extremely difficult to maintain. For example, if we have ten
29063 switches that can be on or off, this means that there are a thousand
29064 separate programs, any one of which might not even be syntactically
29065 correct, and even if syntactically correct, the resulting program
29066 might not work correctly. Testing all combinations can quickly become
29069 Nevertheless, the need to tailor programs certainly exists, and in
29070 this Appendix we will discuss how this can
29071 be achieved using Ada in general, and GNAT in particular.
29074 * Use of Boolean Constants::
29075 * Debugging - A Special Case::
29076 * Conditionalizing Declarations::
29077 * Use of Alternative Implementations::
29081 @node Use of Boolean Constants
29082 @section Use of Boolean Constants
29085 In the case where the difference is simply which code
29086 sequence is executed, the cleanest solution is to use Boolean
29087 constants to control which code is executed.
29089 @smallexample @c ada
29091 FP_Initialize_Required : constant Boolean := True;
29093 if FP_Initialize_Required then
29100 Not only will the code inside the @code{if} statement not be executed if
29101 the constant Boolean is @code{False}, but it will also be completely
29102 deleted from the program.
29103 However, the code is only deleted after the @code{if} statement
29104 has been checked for syntactic and semantic correctness.
29105 (In contrast, with preprocessors the code is deleted before the
29106 compiler ever gets to see it, so it is not checked until the switch
29108 @cindex Preprocessors (contrasted with conditional compilation)
29110 Typically the Boolean constants will be in a separate package,
29113 @smallexample @c ada
29116 FP_Initialize_Required : constant Boolean := True;
29117 Reset_Available : constant Boolean := False;
29124 The @code{Config} package exists in multiple forms for the various targets,
29125 with an appropriate script selecting the version of @code{Config} needed.
29126 Then any other unit requiring conditional compilation can do a @code{with}
29127 of @code{Config} to make the constants visible.
29130 @node Debugging - A Special Case
29131 @section Debugging - A Special Case
29134 A common use of conditional code is to execute statements (for example
29135 dynamic checks, or output of intermediate results) under control of a
29136 debug switch, so that the debugging behavior can be turned on and off.
29137 This can be done using a Boolean constant to control whether the code
29140 @smallexample @c ada
29143 Put_Line ("got to the first stage!");
29151 @smallexample @c ada
29153 if Debugging and then Temperature > 999.0 then
29154 raise Temperature_Crazy;
29160 Since this is a common case, there are special features to deal with
29161 this in a convenient manner. For the case of tests, Ada 2005 has added
29162 a pragma @code{Assert} that can be used for such tests. This pragma is modeled
29163 @cindex pragma @code{Assert}
29164 on the @code{Assert} pragma that has always been available in GNAT, so this
29165 feature may be used with GNAT even if you are not using Ada 2005 features.
29166 The use of pragma @code{Assert} is described in
29167 @ref{Pragma Assert,,, gnat_rm, GNAT Reference Manual}, but as an
29168 example, the last test could be written:
29170 @smallexample @c ada
29171 pragma Assert (Temperature <= 999.0, "Temperature Crazy");
29177 @smallexample @c ada
29178 pragma Assert (Temperature <= 999.0);
29182 In both cases, if assertions are active and the temperature is excessive,
29183 the exception @code{Assert_Failure} will be raised, with the given string in
29184 the first case or a string indicating the location of the pragma in the second
29185 case used as the exception message.
29187 You can turn assertions on and off by using the @code{Assertion_Policy}
29189 @cindex pragma @code{Assertion_Policy}
29190 This is an Ada 2005 pragma which is implemented in all modes by
29191 GNAT, but only in the latest versions of GNAT which include Ada 2005
29192 capability. Alternatively, you can use the @option{-gnata} switch
29193 @cindex @option{-gnata} switch
29194 to enable assertions from the command line (this is recognized by all versions
29197 For the example above with the @code{Put_Line}, the GNAT-specific pragma
29198 @code{Debug} can be used:
29199 @cindex pragma @code{Debug}
29201 @smallexample @c ada
29202 pragma Debug (Put_Line ("got to the first stage!"));
29206 If debug pragmas are enabled, the argument, which must be of the form of
29207 a procedure call, is executed (in this case, @code{Put_Line} will be called).
29208 Only one call can be present, but of course a special debugging procedure
29209 containing any code you like can be included in the program and then
29210 called in a pragma @code{Debug} argument as needed.
29212 One advantage of pragma @code{Debug} over the @code{if Debugging then}
29213 construct is that pragma @code{Debug} can appear in declarative contexts,
29214 such as at the very beginning of a procedure, before local declarations have
29217 Debug pragmas are enabled using either the @option{-gnata} switch that also
29218 controls assertions, or with a separate Debug_Policy pragma.
29219 @cindex pragma @code{Debug_Policy}
29220 The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used
29221 in Ada 95 and Ada 83 programs as well), and is analogous to
29222 pragma @code{Assertion_Policy} to control assertions.
29224 @code{Assertion_Policy} and @code{Debug_Policy} are configuration pragmas,
29225 and thus they can appear in @file{gnat.adc} if you are not using a
29226 project file, or in the file designated to contain configuration pragmas
29228 They then apply to all subsequent compilations. In practice the use of
29229 the @option{-gnata} switch is often the most convenient method of controlling
29230 the status of these pragmas.
29232 Note that a pragma is not a statement, so in contexts where a statement
29233 sequence is required, you can't just write a pragma on its own. You have
29234 to add a @code{null} statement.
29236 @smallexample @c ada
29239 @dots{} -- some statements
29241 pragma Assert (Num_Cases < 10);
29248 @node Conditionalizing Declarations
29249 @section Conditionalizing Declarations
29252 In some cases, it may be necessary to conditionalize declarations to meet
29253 different requirements. For example we might want a bit string whose length
29254 is set to meet some hardware message requirement.
29256 In some cases, it may be possible to do this using declare blocks controlled
29257 by conditional constants:
29259 @smallexample @c ada
29261 if Small_Machine then
29263 X : Bit_String (1 .. 10);
29269 X : Large_Bit_String (1 .. 1000);
29278 Note that in this approach, both declarations are analyzed by the
29279 compiler so this can only be used where both declarations are legal,
29280 even though one of them will not be used.
29282 Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word}, or
29283 Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations
29284 that are parameterized by these constants. For example
29286 @smallexample @c ada
29289 Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word;
29295 If @code{Bits_Per_Word} is set to 32, this generates either
29297 @smallexample @c ada
29300 Field1 at 0 range 0 .. 32;
29306 for the big endian case, or
29308 @smallexample @c ada
29311 Field1 at 0 range 10 .. 32;
29317 for the little endian case. Since a powerful subset of Ada expression
29318 notation is usable for creating static constants, clever use of this
29319 feature can often solve quite difficult problems in conditionalizing
29320 compilation (note incidentally that in Ada 95, the little endian
29321 constant was introduced as @code{System.Default_Bit_Order}, so you do not
29322 need to define this one yourself).
29325 @node Use of Alternative Implementations
29326 @section Use of Alternative Implementations
29329 In some cases, none of the approaches described above are adequate. This
29330 can occur for example if the set of declarations required is radically
29331 different for two different configurations.
29333 In this situation, the official Ada way of dealing with conditionalizing
29334 such code is to write separate units for the different cases. As long as
29335 this does not result in excessive duplication of code, this can be done
29336 without creating maintenance problems. The approach is to share common
29337 code as far as possible, and then isolate the code and declarations
29338 that are different. Subunits are often a convenient method for breaking
29339 out a piece of a unit that is to be conditionalized, with separate files
29340 for different versions of the subunit for different targets, where the
29341 build script selects the right one to give to the compiler.
29342 @cindex Subunits (and conditional compilation)
29344 As an example, consider a situation where a new feature in Ada 2005
29345 allows something to be done in a really nice way. But your code must be able
29346 to compile with an Ada 95 compiler. Conceptually you want to say:
29348 @smallexample @c ada
29351 @dots{} neat Ada 2005 code
29353 @dots{} not quite as neat Ada 95 code
29359 where @code{Ada_2005} is a Boolean constant.
29361 But this won't work when @code{Ada_2005} is set to @code{False},
29362 since the @code{then} clause will be illegal for an Ada 95 compiler.
29363 (Recall that although such unreachable code would eventually be deleted
29364 by the compiler, it still needs to be legal. If it uses features
29365 introduced in Ada 2005, it will be illegal in Ada 95.)
29367 So instead we write
29369 @smallexample @c ada
29370 procedure Insert is separate;
29374 Then we have two files for the subunit @code{Insert}, with the two sets of
29376 If the package containing this is called @code{File_Queries}, then we might
29380 @item @file{file_queries-insert-2005.adb}
29381 @item @file{file_queries-insert-95.adb}
29385 and the build script renames the appropriate file to
29388 file_queries-insert.adb
29392 and then carries out the compilation.
29394 This can also be done with project files' naming schemes. For example:
29396 @smallexample @c project
29397 For Body ("File_Queries.Insert") use "file_queries-insert-2005.ada";
29401 Note also that with project files it is desirable to use a different extension
29402 than @file{ads} / @file{adb} for alternative versions. Otherwise a naming
29403 conflict may arise through another commonly used feature: to declare as part
29404 of the project a set of directories containing all the sources obeying the
29405 default naming scheme.
29407 The use of alternative units is certainly feasible in all situations,
29408 and for example the Ada part of the GNAT run-time is conditionalized
29409 based on the target architecture using this approach. As a specific example,
29410 consider the implementation of the AST feature in VMS. There is one
29418 which is the same for all architectures, and three bodies:
29422 used for all non-VMS operating systems
29423 @item s-asthan-vms-alpha.adb
29424 used for VMS on the Alpha
29425 @item s-asthan-vms-ia64.adb
29426 used for VMS on the ia64
29430 The dummy version @file{s-asthan.adb} simply raises exceptions noting that
29431 this operating system feature is not available, and the two remaining
29432 versions interface with the corresponding versions of VMS to provide
29433 VMS-compatible AST handling. The GNAT build script knows the architecture
29434 and operating system, and automatically selects the right version,
29435 renaming it if necessary to @file{s-asthan.adb} before the run-time build.
29437 Another style for arranging alternative implementations is through Ada's
29438 access-to-subprogram facility.
29439 In case some functionality is to be conditionally included,
29440 you can declare an access-to-procedure variable @code{Ref} that is initialized
29441 to designate a ``do nothing'' procedure, and then invoke @code{Ref.all}
29443 In some library package, set @code{Ref} to @code{Proc'Access} for some
29444 procedure @code{Proc} that performs the relevant processing.
29445 The initialization only occurs if the library package is included in the
29447 The same idea can also be implemented using tagged types and dispatching
29451 @node Preprocessing
29452 @section Preprocessing
29453 @cindex Preprocessing
29456 Although it is quite possible to conditionalize code without the use of
29457 C-style preprocessing, as described earlier in this section, it is
29458 nevertheless convenient in some cases to use the C approach. Moreover,
29459 older Ada compilers have often provided some preprocessing capability,
29460 so legacy code may depend on this approach, even though it is not
29463 To accommodate such use, GNAT provides a preprocessor (modeled to a large
29464 extent on the various preprocessors that have been used
29465 with legacy code on other compilers, to enable easier transition).
29467 The preprocessor may be used in two separate modes. It can be used quite
29468 separately from the compiler, to generate a separate output source file
29469 that is then fed to the compiler as a separate step. This is the
29470 @code{gnatprep} utility, whose use is fully described in
29471 @ref{Preprocessing Using gnatprep}.
29472 @cindex @code{gnatprep}
29474 The preprocessing language allows such constructs as
29478 #if DEBUG or PRIORITY > 4 then
29479 bunch of declarations
29481 completely different bunch of declarations
29487 The values of the symbols @code{DEBUG} and @code{PRIORITY} can be
29488 defined either on the command line or in a separate file.
29490 The other way of running the preprocessor is even closer to the C style and
29491 often more convenient. In this approach the preprocessing is integrated into
29492 the compilation process. The compiler is fed the preprocessor input which
29493 includes @code{#if} lines etc, and then the compiler carries out the
29494 preprocessing internally and processes the resulting output.
29495 For more details on this approach, see @ref{Integrated Preprocessing}.
29498 @c *******************************
29499 @node Inline Assembler
29500 @appendix Inline Assembler
29501 @c *******************************
29504 If you need to write low-level software that interacts directly
29505 with the hardware, Ada provides two ways to incorporate assembly
29506 language code into your program. First, you can import and invoke
29507 external routines written in assembly language, an Ada feature fully
29508 supported by GNAT@. However, for small sections of code it may be simpler
29509 or more efficient to include assembly language statements directly
29510 in your Ada source program, using the facilities of the implementation-defined
29511 package @code{System.Machine_Code}, which incorporates the gcc
29512 Inline Assembler. The Inline Assembler approach offers a number of advantages,
29513 including the following:
29516 @item No need to use non-Ada tools
29517 @item Consistent interface over different targets
29518 @item Automatic usage of the proper calling conventions
29519 @item Access to Ada constants and variables
29520 @item Definition of intrinsic routines
29521 @item Possibility of inlining a subprogram comprising assembler code
29522 @item Code optimizer can take Inline Assembler code into account
29525 This chapter presents a series of examples to show you how to use
29526 the Inline Assembler. Although it focuses on the Intel x86,
29527 the general approach applies also to other processors.
29528 It is assumed that you are familiar with Ada
29529 and with assembly language programming.
29532 * Basic Assembler Syntax::
29533 * A Simple Example of Inline Assembler::
29534 * Output Variables in Inline Assembler::
29535 * Input Variables in Inline Assembler::
29536 * Inlining Inline Assembler Code::
29537 * Other Asm Functionality::
29540 @c ---------------------------------------------------------------------------
29541 @node Basic Assembler Syntax
29542 @section Basic Assembler Syntax
29545 The assembler used by GNAT and gcc is based not on the Intel assembly
29546 language, but rather on a language that descends from the AT&T Unix
29547 assembler @emph{as} (and which is often referred to as ``AT&T syntax'').
29548 The following table summarizes the main features of @emph{as} syntax
29549 and points out the differences from the Intel conventions.
29550 See the gcc @emph{as} and @emph{gas} (an @emph{as} macro
29551 pre-processor) documentation for further information.
29554 @item Register names
29555 gcc / @emph{as}: Prefix with ``%''; for example @code{%eax}
29557 Intel: No extra punctuation; for example @code{eax}
29559 @item Immediate operand
29560 gcc / @emph{as}: Prefix with ``$''; for example @code{$4}
29562 Intel: No extra punctuation; for example @code{4}
29565 gcc / @emph{as}: Prefix with ``$''; for example @code{$loc}
29567 Intel: No extra punctuation; for example @code{loc}
29569 @item Memory contents
29570 gcc / @emph{as}: No extra punctuation; for example @code{loc}
29572 Intel: Square brackets; for example @code{[loc]}
29574 @item Register contents
29575 gcc / @emph{as}: Parentheses; for example @code{(%eax)}
29577 Intel: Square brackets; for example @code{[eax]}
29579 @item Hexadecimal numbers
29580 gcc / @emph{as}: Leading ``0x'' (C language syntax); for example @code{0xA0}
29582 Intel: Trailing ``h''; for example @code{A0h}
29585 gcc / @emph{as}: Explicit in op code; for example @code{movw} to move
29588 Intel: Implicit, deduced by assembler; for example @code{mov}
29590 @item Instruction repetition
29591 gcc / @emph{as}: Split into two lines; for example
29597 Intel: Keep on one line; for example @code{rep stosl}
29599 @item Order of operands
29600 gcc / @emph{as}: Source first; for example @code{movw $4, %eax}
29602 Intel: Destination first; for example @code{mov eax, 4}
29605 @c ---------------------------------------------------------------------------
29606 @node A Simple Example of Inline Assembler
29607 @section A Simple Example of Inline Assembler
29610 The following example will generate a single assembly language statement,
29611 @code{nop}, which does nothing. Despite its lack of run-time effect,
29612 the example will be useful in illustrating the basics of
29613 the Inline Assembler facility.
29615 @smallexample @c ada
29617 with System.Machine_Code; use System.Machine_Code;
29618 procedure Nothing is
29625 @code{Asm} is a procedure declared in package @code{System.Machine_Code};
29626 here it takes one parameter, a @emph{template string} that must be a static
29627 expression and that will form the generated instruction.
29628 @code{Asm} may be regarded as a compile-time procedure that parses
29629 the template string and additional parameters (none here),
29630 from which it generates a sequence of assembly language instructions.
29632 The examples in this chapter will illustrate several of the forms
29633 for invoking @code{Asm}; a complete specification of the syntax
29634 is found in @ref{Machine Code Insertions,,, gnat_rm, GNAT Reference
29637 Under the standard GNAT conventions, the @code{Nothing} procedure
29638 should be in a file named @file{nothing.adb}.
29639 You can build the executable in the usual way:
29643 However, the interesting aspect of this example is not its run-time behavior
29644 but rather the generated assembly code.
29645 To see this output, invoke the compiler as follows:
29647 gcc -c -S -fomit-frame-pointer -gnatp @file{nothing.adb}
29649 where the options are:
29653 compile only (no bind or link)
29655 generate assembler listing
29656 @item -fomit-frame-pointer
29657 do not set up separate stack frames
29659 do not add runtime checks
29662 This gives a human-readable assembler version of the code. The resulting
29663 file will have the same name as the Ada source file, but with a @code{.s}
29664 extension. In our example, the file @file{nothing.s} has the following
29669 .file "nothing.adb"
29671 ___gnu_compiled_ada:
29674 .globl __ada_nothing
29686 The assembly code you included is clearly indicated by
29687 the compiler, between the @code{#APP} and @code{#NO_APP}
29688 delimiters. The character before the 'APP' and 'NOAPP'
29689 can differ on different targets. For example, GNU/Linux uses '#APP' while
29690 on NT you will see '/APP'.
29692 If you make a mistake in your assembler code (such as using the
29693 wrong size modifier, or using a wrong operand for the instruction) GNAT
29694 will report this error in a temporary file, which will be deleted when
29695 the compilation is finished. Generating an assembler file will help
29696 in such cases, since you can assemble this file separately using the
29697 @emph{as} assembler that comes with gcc.
29699 Assembling the file using the command
29702 as @file{nothing.s}
29705 will give you error messages whose lines correspond to the assembler
29706 input file, so you can easily find and correct any mistakes you made.
29707 If there are no errors, @emph{as} will generate an object file
29708 @file{nothing.out}.
29710 @c ---------------------------------------------------------------------------
29711 @node Output Variables in Inline Assembler
29712 @section Output Variables in Inline Assembler
29715 The examples in this section, showing how to access the processor flags,
29716 illustrate how to specify the destination operands for assembly language
29719 @smallexample @c ada
29721 with Interfaces; use Interfaces;
29722 with Ada.Text_IO; use Ada.Text_IO;
29723 with System.Machine_Code; use System.Machine_Code;
29724 procedure Get_Flags is
29725 Flags : Unsigned_32;
29728 Asm ("pushfl" & LF & HT & -- push flags on stack
29729 "popl %%eax" & LF & HT & -- load eax with flags
29730 "movl %%eax, %0", -- store flags in variable
29731 Outputs => Unsigned_32'Asm_Output ("=g", Flags));
29732 Put_Line ("Flags register:" & Flags'Img);
29737 In order to have a nicely aligned assembly listing, we have separated
29738 multiple assembler statements in the Asm template string with linefeed
29739 (ASCII.LF) and horizontal tab (ASCII.HT) characters.
29740 The resulting section of the assembly output file is:
29747 movl %eax, -40(%ebp)
29752 It would have been legal to write the Asm invocation as:
29755 Asm ("pushfl popl %%eax movl %%eax, %0")
29758 but in the generated assembler file, this would come out as:
29762 pushfl popl %eax movl %eax, -40(%ebp)
29766 which is not so convenient for the human reader.
29768 We use Ada comments
29769 at the end of each line to explain what the assembler instructions
29770 actually do. This is a useful convention.
29772 When writing Inline Assembler instructions, you need to precede each register
29773 and variable name with a percent sign. Since the assembler already requires
29774 a percent sign at the beginning of a register name, you need two consecutive
29775 percent signs for such names in the Asm template string, thus @code{%%eax}.
29776 In the generated assembly code, one of the percent signs will be stripped off.
29778 Names such as @code{%0}, @code{%1}, @code{%2}, etc., denote input or output
29779 variables: operands you later define using @code{Input} or @code{Output}
29780 parameters to @code{Asm}.
29781 An output variable is illustrated in
29782 the third statement in the Asm template string:
29786 The intent is to store the contents of the eax register in a variable that can
29787 be accessed in Ada. Simply writing @code{movl %%eax, Flags} would not
29788 necessarily work, since the compiler might optimize by using a register
29789 to hold Flags, and the expansion of the @code{movl} instruction would not be
29790 aware of this optimization. The solution is not to store the result directly
29791 but rather to advise the compiler to choose the correct operand form;
29792 that is the purpose of the @code{%0} output variable.
29794 Information about the output variable is supplied in the @code{Outputs}
29795 parameter to @code{Asm}:
29797 Outputs => Unsigned_32'Asm_Output ("=g", Flags));
29800 The output is defined by the @code{Asm_Output} attribute of the target type;
29801 the general format is
29803 Type'Asm_Output (constraint_string, variable_name)
29806 The constraint string directs the compiler how
29807 to store/access the associated variable. In the example
29809 Unsigned_32'Asm_Output ("=m", Flags);
29811 the @code{"m"} (memory) constraint tells the compiler that the variable
29812 @code{Flags} should be stored in a memory variable, thus preventing
29813 the optimizer from keeping it in a register. In contrast,
29815 Unsigned_32'Asm_Output ("=r", Flags);
29817 uses the @code{"r"} (register) constraint, telling the compiler to
29818 store the variable in a register.
29820 If the constraint is preceded by the equal character (@strong{=}), it tells
29821 the compiler that the variable will be used to store data into it.
29823 In the @code{Get_Flags} example, we used the @code{"g"} (global) constraint,
29824 allowing the optimizer to choose whatever it deems best.
29826 There are a fairly large number of constraints, but the ones that are
29827 most useful (for the Intel x86 processor) are the following:
29833 global (i.e.@: can be stored anywhere)
29851 use one of eax, ebx, ecx or edx
29853 use one of eax, ebx, ecx, edx, esi or edi
29856 The full set of constraints is described in the gcc and @emph{as}
29857 documentation; note that it is possible to combine certain constraints
29858 in one constraint string.
29860 You specify the association of an output variable with an assembler operand
29861 through the @code{%}@emph{n} notation, where @emph{n} is a non-negative
29863 @smallexample @c ada
29865 Asm ("pushfl" & LF & HT & -- push flags on stack
29866 "popl %%eax" & LF & HT & -- load eax with flags
29867 "movl %%eax, %0", -- store flags in variable
29868 Outputs => Unsigned_32'Asm_Output ("=g", Flags));
29872 @code{%0} will be replaced in the expanded code by the appropriate operand,
29874 the compiler decided for the @code{Flags} variable.
29876 In general, you may have any number of output variables:
29879 Count the operands starting at 0; thus @code{%0}, @code{%1}, etc.
29881 Specify the @code{Outputs} parameter as a parenthesized comma-separated list
29882 of @code{Asm_Output} attributes
29886 @smallexample @c ada
29888 Asm ("movl %%eax, %0" & LF & HT &
29889 "movl %%ebx, %1" & LF & HT &
29891 Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A
29892 Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B
29893 Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C
29897 where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables
29898 in the Ada program.
29900 As a variation on the @code{Get_Flags} example, we can use the constraints
29901 string to direct the compiler to store the eax register into the @code{Flags}
29902 variable, instead of including the store instruction explicitly in the
29903 @code{Asm} template string:
29905 @smallexample @c ada
29907 with Interfaces; use Interfaces;
29908 with Ada.Text_IO; use Ada.Text_IO;
29909 with System.Machine_Code; use System.Machine_Code;
29910 procedure Get_Flags_2 is
29911 Flags : Unsigned_32;
29914 Asm ("pushfl" & LF & HT & -- push flags on stack
29915 "popl %%eax", -- save flags in eax
29916 Outputs => Unsigned_32'Asm_Output ("=a", Flags));
29917 Put_Line ("Flags register:" & Flags'Img);
29923 The @code{"a"} constraint tells the compiler that the @code{Flags}
29924 variable will come from the eax register. Here is the resulting code:
29932 movl %eax,-40(%ebp)
29937 The compiler generated the store of eax into Flags after
29938 expanding the assembler code.
29940 Actually, there was no need to pop the flags into the eax register;
29941 more simply, we could just pop the flags directly into the program variable:
29943 @smallexample @c ada
29945 with Interfaces; use Interfaces;
29946 with Ada.Text_IO; use Ada.Text_IO;
29947 with System.Machine_Code; use System.Machine_Code;
29948 procedure Get_Flags_3 is
29949 Flags : Unsigned_32;
29952 Asm ("pushfl" & LF & HT & -- push flags on stack
29953 "pop %0", -- save flags in Flags
29954 Outputs => Unsigned_32'Asm_Output ("=g", Flags));
29955 Put_Line ("Flags register:" & Flags'Img);
29960 @c ---------------------------------------------------------------------------
29961 @node Input Variables in Inline Assembler
29962 @section Input Variables in Inline Assembler
29965 The example in this section illustrates how to specify the source operands
29966 for assembly language statements.
29967 The program simply increments its input value by 1:
29969 @smallexample @c ada
29971 with Interfaces; use Interfaces;
29972 with Ada.Text_IO; use Ada.Text_IO;
29973 with System.Machine_Code; use System.Machine_Code;
29974 procedure Increment is
29976 function Incr (Value : Unsigned_32) return Unsigned_32 is
29977 Result : Unsigned_32;
29980 Inputs => Unsigned_32'Asm_Input ("a", Value),
29981 Outputs => Unsigned_32'Asm_Output ("=a", Result));
29985 Value : Unsigned_32;
29989 Put_Line ("Value before is" & Value'Img);
29990 Value := Incr (Value);
29991 Put_Line ("Value after is" & Value'Img);
29996 The @code{Outputs} parameter to @code{Asm} specifies
29997 that the result will be in the eax register and that it is to be stored
29998 in the @code{Result} variable.
30000 The @code{Inputs} parameter looks much like the @code{Outputs} parameter,
30001 but with an @code{Asm_Input} attribute.
30002 The @code{"="} constraint, indicating an output value, is not present.
30004 You can have multiple input variables, in the same way that you can have more
30005 than one output variable.
30007 The parameter count (%0, %1) etc, now starts at the first input
30008 statement, and continues with the output statements.
30009 When both parameters use the same variable, the
30010 compiler will treat them as the same %n operand, which is the case here.
30012 Just as the @code{Outputs} parameter causes the register to be stored into the
30013 target variable after execution of the assembler statements, so does the
30014 @code{Inputs} parameter cause its variable to be loaded into the register
30015 before execution of the assembler statements.
30017 Thus the effect of the @code{Asm} invocation is:
30019 @item load the 32-bit value of @code{Value} into eax
30020 @item execute the @code{incl %eax} instruction
30021 @item store the contents of eax into the @code{Result} variable
30024 The resulting assembler file (with @option{-O2} optimization) contains:
30027 _increment__incr.1:
30040 @c ---------------------------------------------------------------------------
30041 @node Inlining Inline Assembler Code
30042 @section Inlining Inline Assembler Code
30045 For a short subprogram such as the @code{Incr} function in the previous
30046 section, the overhead of the call and return (creating / deleting the stack
30047 frame) can be significant, compared to the amount of code in the subprogram
30048 body. A solution is to apply Ada's @code{Inline} pragma to the subprogram,
30049 which directs the compiler to expand invocations of the subprogram at the
30050 point(s) of call, instead of setting up a stack frame for out-of-line calls.
30051 Here is the resulting program:
30053 @smallexample @c ada
30055 with Interfaces; use Interfaces;
30056 with Ada.Text_IO; use Ada.Text_IO;
30057 with System.Machine_Code; use System.Machine_Code;
30058 procedure Increment_2 is
30060 function Incr (Value : Unsigned_32) return Unsigned_32 is
30061 Result : Unsigned_32;
30064 Inputs => Unsigned_32'Asm_Input ("a", Value),
30065 Outputs => Unsigned_32'Asm_Output ("=a", Result));
30068 pragma Inline (Increment);
30070 Value : Unsigned_32;
30074 Put_Line ("Value before is" & Value'Img);
30075 Value := Increment (Value);
30076 Put_Line ("Value after is" & Value'Img);
30081 Compile the program with both optimization (@option{-O2}) and inlining
30082 (@option{-gnatn}) enabled.
30084 The @code{Incr} function is still compiled as usual, but at the
30085 point in @code{Increment} where our function used to be called:
30090 call _increment__incr.1
30095 the code for the function body directly appears:
30108 thus saving the overhead of stack frame setup and an out-of-line call.
30110 @c ---------------------------------------------------------------------------
30111 @node Other Asm Functionality
30112 @section Other @code{Asm} Functionality
30115 This section describes two important parameters to the @code{Asm}
30116 procedure: @code{Clobber}, which identifies register usage;
30117 and @code{Volatile}, which inhibits unwanted optimizations.
30120 * The Clobber Parameter::
30121 * The Volatile Parameter::
30124 @c ---------------------------------------------------------------------------
30125 @node The Clobber Parameter
30126 @subsection The @code{Clobber} Parameter
30129 One of the dangers of intermixing assembly language and a compiled language
30130 such as Ada is that the compiler needs to be aware of which registers are
30131 being used by the assembly code. In some cases, such as the earlier examples,
30132 the constraint string is sufficient to indicate register usage (e.g.,
30134 the eax register). But more generally, the compiler needs an explicit
30135 identification of the registers that are used by the Inline Assembly
30138 Using a register that the compiler doesn't know about
30139 could be a side effect of an instruction (like @code{mull}
30140 storing its result in both eax and edx).
30141 It can also arise from explicit register usage in your
30142 assembly code; for example:
30145 Asm ("movl %0, %%ebx" & LF & HT &
30147 Inputs => Unsigned_32'Asm_Input ("g", Var_In),
30148 Outputs => Unsigned_32'Asm_Output ("=g", Var_Out));
30152 where the compiler (since it does not analyze the @code{Asm} template string)
30153 does not know you are using the ebx register.
30155 In such cases you need to supply the @code{Clobber} parameter to @code{Asm},
30156 to identify the registers that will be used by your assembly code:
30160 Asm ("movl %0, %%ebx" & LF & HT &
30162 Inputs => Unsigned_32'Asm_Input ("g", Var_In),
30163 Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
30168 The Clobber parameter is a static string expression specifying the
30169 register(s) you are using. Note that register names are @emph{not} prefixed
30170 by a percent sign. Also, if more than one register is used then their names
30171 are separated by commas; e.g., @code{"eax, ebx"}
30173 The @code{Clobber} parameter has several additional uses:
30175 @item Use ``register'' name @code{cc} to indicate that flags might have changed
30176 @item Use ``register'' name @code{memory} if you changed a memory location
30179 @c ---------------------------------------------------------------------------
30180 @node The Volatile Parameter
30181 @subsection The @code{Volatile} Parameter
30182 @cindex Volatile parameter
30185 Compiler optimizations in the presence of Inline Assembler may sometimes have
30186 unwanted effects. For example, when an @code{Asm} invocation with an input
30187 variable is inside a loop, the compiler might move the loading of the input
30188 variable outside the loop, regarding it as a one-time initialization.
30190 If this effect is not desired, you can disable such optimizations by setting
30191 the @code{Volatile} parameter to @code{True}; for example:
30193 @smallexample @c ada
30195 Asm ("movl %0, %%ebx" & LF & HT &
30197 Inputs => Unsigned_32'Asm_Input ("g", Var_In),
30198 Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
30204 By default, @code{Volatile} is set to @code{False} unless there is no
30205 @code{Outputs} parameter.
30207 Although setting @code{Volatile} to @code{True} prevents unwanted
30208 optimizations, it will also disable other optimizations that might be
30209 important for efficiency. In general, you should set @code{Volatile}
30210 to @code{True} only if the compiler's optimizations have created
30212 @c END OF INLINE ASSEMBLER CHAPTER
30213 @c ===============================
30215 @c ***********************************
30216 @c * Compatibility and Porting Guide *
30217 @c ***********************************
30218 @node Compatibility and Porting Guide
30219 @appendix Compatibility and Porting Guide
30222 This chapter describes the compatibility issues that may arise between
30223 GNAT and other Ada compilation systems (including those for Ada 83),
30224 and shows how GNAT can expedite porting
30225 applications developed in other Ada environments.
30228 * Compatibility with Ada 83::
30229 * Compatibility between Ada 95 and Ada 2005::
30230 * Implementation-dependent characteristics::
30231 * Compatibility with Other Ada Systems::
30232 * Representation Clauses::
30234 @c Brief section is only in non-VMS version
30235 @c Full chapter is in VMS version
30236 * Compatibility with HP Ada 83::
30239 * Transitioning to 64-Bit GNAT for OpenVMS::
30243 @node Compatibility with Ada 83
30244 @section Compatibility with Ada 83
30245 @cindex Compatibility (between Ada 83 and Ada 95 / Ada 2005)
30248 Ada 95 and Ada 2005 are highly upwards compatible with Ada 83. In
30249 particular, the design intention was that the difficulties associated
30250 with moving from Ada 83 to Ada 95 or Ada 2005 should be no greater than those
30251 that occur when moving from one Ada 83 system to another.
30253 However, there are a number of points at which there are minor
30254 incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains
30255 full details of these issues,
30256 and should be consulted for a complete treatment.
30258 following subsections treat the most likely issues to be encountered.
30261 * Legal Ada 83 programs that are illegal in Ada 95::
30262 * More deterministic semantics::
30263 * Changed semantics::
30264 * Other language compatibility issues::
30267 @node Legal Ada 83 programs that are illegal in Ada 95
30268 @subsection Legal Ada 83 programs that are illegal in Ada 95
30270 Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in
30271 Ada 95 and thus also in Ada 2005:
30274 @item Character literals
30275 Some uses of character literals are ambiguous. Since Ada 95 has introduced
30276 @code{Wide_Character} as a new predefined character type, some uses of
30277 character literals that were legal in Ada 83 are illegal in Ada 95.
30279 @smallexample @c ada
30280 for Char in 'A' .. 'Z' loop @dots{} end loop;
30284 The problem is that @code{'A'} and @code{'Z'} could be from either
30285 @code{Character} or @code{Wide_Character}. The simplest correction
30286 is to make the type explicit; e.g.:
30287 @smallexample @c ada
30288 for Char in Character range 'A' .. 'Z' loop @dots{} end loop;
30291 @item New reserved words
30292 The identifiers @code{abstract}, @code{aliased}, @code{protected},
30293 @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95.
30294 Existing Ada 83 code using any of these identifiers must be edited to
30295 use some alternative name.
30297 @item Freezing rules
30298 The rules in Ada 95 are slightly different with regard to the point at
30299 which entities are frozen, and representation pragmas and clauses are
30300 not permitted past the freeze point. This shows up most typically in
30301 the form of an error message complaining that a representation item
30302 appears too late, and the appropriate corrective action is to move
30303 the item nearer to the declaration of the entity to which it refers.
30305 A particular case is that representation pragmas
30308 extended HP Ada 83 compatibility pragmas such as @code{Export_Procedure})
30310 cannot be applied to a subprogram body. If necessary, a separate subprogram
30311 declaration must be introduced to which the pragma can be applied.
30313 @item Optional bodies for library packages
30314 In Ada 83, a package that did not require a package body was nevertheless
30315 allowed to have one. This lead to certain surprises in compiling large
30316 systems (situations in which the body could be unexpectedly ignored by the
30317 binder). In Ada 95, if a package does not require a body then it is not
30318 permitted to have a body. To fix this problem, simply remove a redundant
30319 body if it is empty, or, if it is non-empty, introduce a dummy declaration
30320 into the spec that makes the body required. One approach is to add a private
30321 part to the package declaration (if necessary), and define a parameterless
30322 procedure called @code{Requires_Body}, which must then be given a dummy
30323 procedure body in the package body, which then becomes required.
30324 Another approach (assuming that this does not introduce elaboration
30325 circularities) is to add an @code{Elaborate_Body} pragma to the package spec,
30326 since one effect of this pragma is to require the presence of a package body.
30328 @item @code{Numeric_Error} is now the same as @code{Constraint_Error}
30329 In Ada 95, the exception @code{Numeric_Error} is a renaming of
30330 @code{Constraint_Error}.
30331 This means that it is illegal to have separate exception handlers for
30332 the two exceptions. The fix is simply to remove the handler for the
30333 @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise
30334 @code{Constraint_Error} in place of @code{Numeric_Error} in all cases).
30336 @item Indefinite subtypes in generics
30337 In Ada 83, it was permissible to pass an indefinite type (e.g.@: @code{String})
30338 as the actual for a generic formal private type, but then the instantiation
30339 would be illegal if there were any instances of declarations of variables
30340 of this type in the generic body. In Ada 95, to avoid this clear violation
30341 of the methodological principle known as the ``contract model'',
30342 the generic declaration explicitly indicates whether
30343 or not such instantiations are permitted. If a generic formal parameter
30344 has explicit unknown discriminants, indicated by using @code{(<>)} after the
30345 type name, then it can be instantiated with indefinite types, but no
30346 stand-alone variables can be declared of this type. Any attempt to declare
30347 such a variable will result in an illegality at the time the generic is
30348 declared. If the @code{(<>)} notation is not used, then it is illegal
30349 to instantiate the generic with an indefinite type.
30350 This is the potential incompatibility issue when porting Ada 83 code to Ada 95.
30351 It will show up as a compile time error, and
30352 the fix is usually simply to add the @code{(<>)} to the generic declaration.
30355 @node More deterministic semantics
30356 @subsection More deterministic semantics
30360 Conversions from real types to integer types round away from 0. In Ada 83
30361 the conversion Integer(2.5) could deliver either 2 or 3 as its value. This
30362 implementation freedom was intended to support unbiased rounding in
30363 statistical applications, but in practice it interfered with portability.
30364 In Ada 95 the conversion semantics are unambiguous, and rounding away from 0
30365 is required. Numeric code may be affected by this change in semantics.
30366 Note, though, that this issue is no worse than already existed in Ada 83
30367 when porting code from one vendor to another.
30370 The Real-Time Annex introduces a set of policies that define the behavior of
30371 features that were implementation dependent in Ada 83, such as the order in
30372 which open select branches are executed.
30375 @node Changed semantics
30376 @subsection Changed semantics
30379 The worst kind of incompatibility is one where a program that is legal in
30380 Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not
30381 possible in Ada 83. Fortunately this is extremely rare, but the one
30382 situation that you should be alert to is the change in the predefined type
30383 @code{Character} from 7-bit ASCII to 8-bit Latin-1.
30386 @item Range of type @code{Character}
30387 The range of @code{Standard.Character} is now the full 256 characters
30388 of Latin-1, whereas in most Ada 83 implementations it was restricted
30389 to 128 characters. Although some of the effects of
30390 this change will be manifest in compile-time rejection of legal
30391 Ada 83 programs it is possible for a working Ada 83 program to have
30392 a different effect in Ada 95, one that was not permitted in Ada 83.
30393 As an example, the expression
30394 @code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now
30395 delivers @code{255} as its value.
30396 In general, you should look at the logic of any
30397 character-processing Ada 83 program and see whether it needs to be adapted
30398 to work correctly with Latin-1. Note that the predefined Ada 95 API has a
30399 character handling package that may be relevant if code needs to be adapted
30400 to account for the additional Latin-1 elements.
30401 The desirable fix is to
30402 modify the program to accommodate the full character set, but in some cases
30403 it may be convenient to define a subtype or derived type of Character that
30404 covers only the restricted range.
30408 @node Other language compatibility issues
30409 @subsection Other language compatibility issues
30412 @item @option{-gnat83} switch
30413 All implementations of GNAT provide a switch that causes GNAT to operate
30414 in Ada 83 mode. In this mode, some but not all compatibility problems
30415 of the type described above are handled automatically. For example, the
30416 new reserved words introduced in Ada 95 and Ada 2005 are treated simply
30417 as identifiers as in Ada 83.
30419 in practice, it is usually advisable to make the necessary modifications
30420 to the program to remove the need for using this switch.
30421 See @ref{Compiling Different Versions of Ada}.
30423 @item Support for removed Ada 83 pragmas and attributes
30424 A number of pragmas and attributes from Ada 83 were removed from Ada 95,
30425 generally because they were replaced by other mechanisms. Ada 95 and Ada 2005
30426 compilers are allowed, but not required, to implement these missing
30427 elements. In contrast with some other compilers, GNAT implements all
30428 such pragmas and attributes, eliminating this compatibility concern. These
30429 include @code{pragma Interface} and the floating point type attributes
30430 (@code{Emax}, @code{Mantissa}, etc.), among other items.
30434 @node Compatibility between Ada 95 and Ada 2005
30435 @section Compatibility between Ada 95 and Ada 2005
30436 @cindex Compatibility between Ada 95 and Ada 2005
30439 Although Ada 2005 was designed to be upwards compatible with Ada 95, there are
30440 a number of incompatibilities. Several are enumerated below;
30441 for a complete description please see the
30442 Annotated Ada 2005 Reference Manual, or section 9.1.1 in
30443 @cite{Rationale for Ada 2005}.
30446 @item New reserved words.
30447 The words @code{interface}, @code{overriding} and @code{synchronized} are
30448 reserved in Ada 2005.
30449 A pre-Ada 2005 program that uses any of these as an identifier will be
30452 @item New declarations in predefined packages.
30453 A number of packages in the predefined environment contain new declarations:
30454 @code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings},
30455 @code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded},
30456 @code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed},
30457 @code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded},
30458 @code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}.
30459 If an Ada 95 program does a @code{with} and @code{use} of any of these
30460 packages, the new declarations may cause name clashes.
30462 @item Access parameters.
30463 A nondispatching subprogram with an access parameter cannot be renamed
30464 as a dispatching operation. This was permitted in Ada 95.
30466 @item Access types, discriminants, and constraints.
30467 Rule changes in this area have led to some incompatibilities; for example,
30468 constrained subtypes of some access types are not permitted in Ada 2005.
30470 @item Aggregates for limited types.
30471 The allowance of aggregates for limited types in Ada 2005 raises the
30472 possibility of ambiguities in legal Ada 95 programs, since additional types
30473 now need to be considered in expression resolution.
30475 @item Fixed-point multiplication and division.
30476 Certain expressions involving ``*'' or ``/'' for a fixed-point type, which
30477 were legal in Ada 95 and invoked the predefined versions of these operations,
30479 The ambiguity may be resolved either by applying a type conversion to the
30480 expression, or by explicitly invoking the operation from package
30483 @item Return-by-reference types.
30484 The Ada 95 return-by-reference mechanism has been removed. Instead, the user
30485 can declare a function returning a value from an anonymous access type.
30489 @node Implementation-dependent characteristics
30490 @section Implementation-dependent characteristics
30492 Although the Ada language defines the semantics of each construct as
30493 precisely as practical, in some situations (for example for reasons of
30494 efficiency, or where the effect is heavily dependent on the host or target
30495 platform) the implementation is allowed some freedom. In porting Ada 83
30496 code to GNAT, you need to be aware of whether / how the existing code
30497 exercised such implementation dependencies. Such characteristics fall into
30498 several categories, and GNAT offers specific support in assisting the
30499 transition from certain Ada 83 compilers.
30502 * Implementation-defined pragmas::
30503 * Implementation-defined attributes::
30505 * Elaboration order::
30506 * Target-specific aspects::
30509 @node Implementation-defined pragmas
30510 @subsection Implementation-defined pragmas
30513 Ada compilers are allowed to supplement the language-defined pragmas, and
30514 these are a potential source of non-portability. All GNAT-defined pragmas
30515 are described in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT
30516 Reference Manual}, and these include several that are specifically
30517 intended to correspond to other vendors' Ada 83 pragmas.
30518 For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
30519 For compatibility with HP Ada 83, GNAT supplies the pragmas
30520 @code{Extend_System}, @code{Ident}, @code{Inline_Generic},
30521 @code{Interface_Name}, @code{Passive}, @code{Suppress_All},
30522 and @code{Volatile}.
30523 Other relevant pragmas include @code{External} and @code{Link_With}.
30524 Some vendor-specific
30525 Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are
30527 avoiding compiler rejection of units that contain such pragmas; they are not
30528 relevant in a GNAT context and hence are not otherwise implemented.
30530 @node Implementation-defined attributes
30531 @subsection Implementation-defined attributes
30533 Analogous to pragmas, the set of attributes may be extended by an
30534 implementation. All GNAT-defined attributes are described in
30535 @ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference
30536 Manual}, and these include several that are specifically intended
30537 to correspond to other vendors' Ada 83 attributes. For migrating from VADS,
30538 the attribute @code{VADS_Size} may be useful. For compatibility with HP
30539 Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
30543 @subsection Libraries
30545 Vendors may supply libraries to supplement the standard Ada API. If Ada 83
30546 code uses vendor-specific libraries then there are several ways to manage
30547 this in Ada 95 or Ada 2005:
30550 If the source code for the libraries (specs and bodies) are
30551 available, then the libraries can be migrated in the same way as the
30554 If the source code for the specs but not the bodies are
30555 available, then you can reimplement the bodies.
30557 Some features introduced by Ada 95 obviate the need for library support. For
30558 example most Ada 83 vendors supplied a package for unsigned integers. The
30559 Ada 95 modular type feature is the preferred way to handle this need, so
30560 instead of migrating or reimplementing the unsigned integer package it may
30561 be preferable to retrofit the application using modular types.
30564 @node Elaboration order
30565 @subsection Elaboration order
30567 The implementation can choose any elaboration order consistent with the unit
30568 dependency relationship. This freedom means that some orders can result in
30569 Program_Error being raised due to an ``Access Before Elaboration'': an attempt
30570 to invoke a subprogram its body has been elaborated, or to instantiate a
30571 generic before the generic body has been elaborated. By default GNAT
30572 attempts to choose a safe order (one that will not encounter access before
30573 elaboration problems) by implicitly inserting @code{Elaborate} or
30574 @code{Elaborate_All} pragmas where
30575 needed. However, this can lead to the creation of elaboration circularities
30576 and a resulting rejection of the program by gnatbind. This issue is
30577 thoroughly described in @ref{Elaboration Order Handling in GNAT}.
30578 In brief, there are several
30579 ways to deal with this situation:
30583 Modify the program to eliminate the circularities, e.g.@: by moving
30584 elaboration-time code into explicitly-invoked procedures
30586 Constrain the elaboration order by including explicit @code{Elaborate_Body} or
30587 @code{Elaborate} pragmas, and then inhibit the generation of implicit
30588 @code{Elaborate_All}
30589 pragmas either globally (as an effect of the @option{-gnatE} switch) or locally
30590 (by selectively suppressing elaboration checks via pragma
30591 @code{Suppress(Elaboration_Check)} when it is safe to do so).
30594 @node Target-specific aspects
30595 @subsection Target-specific aspects
30597 Low-level applications need to deal with machine addresses, data
30598 representations, interfacing with assembler code, and similar issues. If
30599 such an Ada 83 application is being ported to different target hardware (for
30600 example where the byte endianness has changed) then you will need to
30601 carefully examine the program logic; the porting effort will heavily depend
30602 on the robustness of the original design. Moreover, Ada 95 (and thus
30603 Ada 2005) are sometimes
30604 incompatible with typical Ada 83 compiler practices regarding implicit
30605 packing, the meaning of the Size attribute, and the size of access values.
30606 GNAT's approach to these issues is described in @ref{Representation Clauses}.
30608 @node Compatibility with Other Ada Systems
30609 @section Compatibility with Other Ada Systems
30612 If programs avoid the use of implementation dependent and
30613 implementation defined features, as documented in the @cite{Ada
30614 Reference Manual}, there should be a high degree of portability between
30615 GNAT and other Ada systems. The following are specific items which
30616 have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95
30617 compilers, but do not affect porting code to GNAT@.
30618 (As of @value{NOW}, GNAT is the only compiler available for Ada 2005;
30619 the following issues may or may not arise for Ada 2005 programs
30620 when other compilers appear.)
30623 @item Ada 83 Pragmas and Attributes
30624 Ada 95 compilers are allowed, but not required, to implement the missing
30625 Ada 83 pragmas and attributes that are no longer defined in Ada 95.
30626 GNAT implements all such pragmas and attributes, eliminating this as
30627 a compatibility concern, but some other Ada 95 compilers reject these
30628 pragmas and attributes.
30630 @item Specialized Needs Annexes
30631 GNAT implements the full set of special needs annexes. At the
30632 current time, it is the only Ada 95 compiler to do so. This means that
30633 programs making use of these features may not be portable to other Ada
30634 95 compilation systems.
30636 @item Representation Clauses
30637 Some other Ada 95 compilers implement only the minimal set of
30638 representation clauses required by the Ada 95 reference manual. GNAT goes
30639 far beyond this minimal set, as described in the next section.
30642 @node Representation Clauses
30643 @section Representation Clauses
30646 The Ada 83 reference manual was quite vague in describing both the minimal
30647 required implementation of representation clauses, and also their precise
30648 effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the
30649 minimal set of capabilities required is still quite limited.
30651 GNAT implements the full required set of capabilities in
30652 Ada 95 and Ada 2005, but also goes much further, and in particular
30653 an effort has been made to be compatible with existing Ada 83 usage to the
30654 greatest extent possible.
30656 A few cases exist in which Ada 83 compiler behavior is incompatible with
30657 the requirements in Ada 95 (and thus also Ada 2005). These are instances of
30658 intentional or accidental dependence on specific implementation dependent
30659 characteristics of these Ada 83 compilers. The following is a list of
30660 the cases most likely to arise in existing Ada 83 code.
30663 @item Implicit Packing
30664 Some Ada 83 compilers allowed a Size specification to cause implicit
30665 packing of an array or record. This could cause expensive implicit
30666 conversions for change of representation in the presence of derived
30667 types, and the Ada design intends to avoid this possibility.
30668 Subsequent AI's were issued to make it clear that such implicit
30669 change of representation in response to a Size clause is inadvisable,
30670 and this recommendation is represented explicitly in the Ada 95 (and Ada 2005)
30671 Reference Manuals as implementation advice that is followed by GNAT@.
30672 The problem will show up as an error
30673 message rejecting the size clause. The fix is simply to provide
30674 the explicit pragma @code{Pack}, or for more fine tuned control, provide
30675 a Component_Size clause.
30677 @item Meaning of Size Attribute
30678 The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as
30679 the minimal number of bits required to hold values of the type. For example,
30680 on a 32-bit machine, the size of @code{Natural} will typically be 31 and not
30681 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and
30682 some 32 in this situation. This problem will usually show up as a compile
30683 time error, but not always. It is a good idea to check all uses of the
30684 'Size attribute when porting Ada 83 code. The GNAT specific attribute
30685 Object_Size can provide a useful way of duplicating the behavior of
30686 some Ada 83 compiler systems.
30688 @item Size of Access Types
30689 A common assumption in Ada 83 code is that an access type is in fact a pointer,
30690 and that therefore it will be the same size as a System.Address value. This
30691 assumption is true for GNAT in most cases with one exception. For the case of
30692 a pointer to an unconstrained array type (where the bounds may vary from one
30693 value of the access type to another), the default is to use a ``fat pointer'',
30694 which is represented as two separate pointers, one to the bounds, and one to
30695 the array. This representation has a number of advantages, including improved
30696 efficiency. However, it may cause some difficulties in porting existing Ada 83
30697 code which makes the assumption that, for example, pointers fit in 32 bits on
30698 a machine with 32-bit addressing.
30700 To get around this problem, GNAT also permits the use of ``thin pointers'' for
30701 access types in this case (where the designated type is an unconstrained array
30702 type). These thin pointers are indeed the same size as a System.Address value.
30703 To specify a thin pointer, use a size clause for the type, for example:
30705 @smallexample @c ada
30706 type X is access all String;
30707 for X'Size use Standard'Address_Size;
30711 which will cause the type X to be represented using a single pointer.
30712 When using this representation, the bounds are right behind the array.
30713 This representation is slightly less efficient, and does not allow quite
30714 such flexibility in the use of foreign pointers or in using the
30715 Unrestricted_Access attribute to create pointers to non-aliased objects.
30716 But for any standard portable use of the access type it will work in
30717 a functionally correct manner and allow porting of existing code.
30718 Note that another way of forcing a thin pointer representation
30719 is to use a component size clause for the element size in an array,
30720 or a record representation clause for an access field in a record.
30724 @c This brief section is only in the non-VMS version
30725 @c The complete chapter on HP Ada is in the VMS version
30726 @node Compatibility with HP Ada 83
30727 @section Compatibility with HP Ada 83
30730 The VMS version of GNAT fully implements all the pragmas and attributes
30731 provided by HP Ada 83, as well as providing the standard HP Ada 83
30732 libraries, including Starlet. In addition, data layouts and parameter
30733 passing conventions are highly compatible. This means that porting
30734 existing HP Ada 83 code to GNAT in VMS systems should be easier than
30735 most other porting efforts. The following are some of the most
30736 significant differences between GNAT and HP Ada 83.
30739 @item Default floating-point representation
30740 In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83,
30741 it is VMS format. GNAT does implement the necessary pragmas
30742 (Long_Float, Float_Representation) for changing this default.
30745 The package System in GNAT exactly corresponds to the definition in the
30746 Ada 95 reference manual, which means that it excludes many of the
30747 HP Ada 83 extensions. However, a separate package Aux_DEC is provided
30748 that contains the additional definitions, and a special pragma,
30749 Extend_System allows this package to be treated transparently as an
30750 extension of package System.
30753 The definitions provided by Aux_DEC are exactly compatible with those
30754 in the HP Ada 83 version of System, with one exception.
30755 HP Ada provides the following declarations:
30757 @smallexample @c ada
30758 TO_ADDRESS (INTEGER)
30759 TO_ADDRESS (UNSIGNED_LONGWORD)
30760 TO_ADDRESS (@i{universal_integer})
30764 The version of TO_ADDRESS taking a @i{universal integer} argument is in fact
30765 an extension to Ada 83 not strictly compatible with the reference manual.
30766 In GNAT, we are constrained to be exactly compatible with the standard,
30767 and this means we cannot provide this capability. In HP Ada 83, the
30768 point of this definition is to deal with a call like:
30770 @smallexample @c ada
30771 TO_ADDRESS (16#12777#);
30775 Normally, according to the Ada 83 standard, one would expect this to be
30776 ambiguous, since it matches both the INTEGER and UNSIGNED_LONGWORD forms
30777 of TO_ADDRESS@. However, in HP Ada 83, there is no ambiguity, since the
30778 definition using @i{universal_integer} takes precedence.
30780 In GNAT, since the version with @i{universal_integer} cannot be supplied, it
30781 is not possible to be 100% compatible. Since there are many programs using
30782 numeric constants for the argument to TO_ADDRESS, the decision in GNAT was
30783 to change the name of the function in the UNSIGNED_LONGWORD case, so the
30784 declarations provided in the GNAT version of AUX_Dec are:
30786 @smallexample @c ada
30787 function To_Address (X : Integer) return Address;
30788 pragma Pure_Function (To_Address);
30790 function To_Address_Long (X : Unsigned_Longword)
30792 pragma Pure_Function (To_Address_Long);
30796 This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must
30797 change the name to TO_ADDRESS_LONG@.
30799 @item Task_Id values
30800 The Task_Id values assigned will be different in the two systems, and GNAT
30801 does not provide a specified value for the Task_Id of the environment task,
30802 which in GNAT is treated like any other declared task.
30806 For full details on these and other less significant compatibility issues,
30807 see appendix E of the HP publication entitled @cite{HP Ada, Technical
30808 Overview and Comparison on HP Platforms}.
30810 For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
30811 attributes are recognized, although only a subset of them can sensibly
30812 be implemented. The description of pragmas in @ref{Implementation
30813 Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
30814 indicates whether or not they are applicable to non-VMS systems.
30818 @node Transitioning to 64-Bit GNAT for OpenVMS
30819 @section Transitioning to 64-Bit @value{EDITION} for OpenVMS
30822 This section is meant to assist users of pre-2006 @value{EDITION}
30823 for Alpha OpenVMS who are transitioning to 64-bit @value{EDITION},
30824 the version of the GNAT technology supplied in 2006 and later for
30825 OpenVMS on both Alpha and I64.
30828 * Introduction to transitioning::
30829 * Migration of 32 bit code::
30830 * Taking advantage of 64 bit addressing::
30831 * Technical details::
30834 @node Introduction to transitioning
30835 @subsection Introduction
30838 64-bit @value{EDITION} for Open VMS has been designed to meet
30843 Providing a full conforming implementation of Ada 95 and Ada 2005
30846 Allowing maximum backward compatibility, thus easing migration of existing
30850 Supplying a path for exploiting the full 64-bit address range
30854 Ada's strong typing semantics has made it
30855 impractical to have different 32-bit and 64-bit modes. As soon as
30856 one object could possibly be outside the 32-bit address space, this
30857 would make it necessary for the @code{System.Address} type to be 64 bits.
30858 In particular, this would cause inconsistencies if 32-bit code is
30859 called from 64-bit code that raises an exception.
30861 This issue has been resolved by always using 64-bit addressing
30862 at the system level, but allowing for automatic conversions between
30863 32-bit and 64-bit addresses where required. Thus users who
30864 do not currently require 64-bit addressing capabilities, can
30865 recompile their code with only minimal changes (and indeed
30866 if the code is written in portable Ada, with no assumptions about
30867 the size of the @code{Address} type, then no changes at all are necessary).
30869 this approach provides a simple, gradual upgrade path to future
30870 use of larger memories than available for 32-bit systems.
30871 Also, newly written applications or libraries will by default
30872 be fully compatible with future systems exploiting 64-bit
30873 addressing capabilities.
30875 @ref{Migration of 32 bit code}, will focus on porting applications
30876 that do not require more than 2 GB of
30877 addressable memory. This code will be referred to as
30878 @emph{32-bit code}.
30879 For applications intending to exploit the full 64-bit address space,
30880 @ref{Taking advantage of 64 bit addressing},
30881 will consider further changes that may be required.
30882 Such code will be referred to below as @emph{64-bit code}.
30884 @node Migration of 32 bit code
30885 @subsection Migration of 32-bit code
30890 * Unchecked conversions::
30891 * Predefined constants::
30892 * Interfacing with C::
30893 * Experience with source compatibility::
30896 @node Address types
30897 @subsubsection Address types
30900 To solve the problem of mixing 64-bit and 32-bit addressing,
30901 while maintaining maximum backward compatibility, the following
30902 approach has been taken:
30906 @code{System.Address} always has a size of 64 bits
30909 @code{System.Short_Address} is a 32-bit subtype of @code{System.Address}
30913 Since @code{System.Short_Address} is a subtype of @code{System.Address},
30914 a @code{Short_Address}
30915 may be used where an @code{Address} is required, and vice versa, without
30916 needing explicit type conversions.
30917 By virtue of the Open VMS parameter passing conventions,
30919 and exported subprograms that have 32-bit address parameters are
30920 compatible with those that have 64-bit address parameters.
30921 (See @ref{Making code 64 bit clean} for details.)
30923 The areas that may need attention are those where record types have
30924 been defined that contain components of the type @code{System.Address}, and
30925 where objects of this type are passed to code expecting a record layout with
30928 Different compilers on different platforms cannot be
30929 expected to represent the same type in the same way,
30930 since alignment constraints
30931 and other system-dependent properties affect the compiler's decision.
30932 For that reason, Ada code
30933 generally uses representation clauses to specify the expected
30934 layout where required.
30936 If such a representation clause uses 32 bits for a component having
30937 the type @code{System.Address}, 64-bit @value{EDITION} for OpenVMS
30938 will detect that error and produce a specific diagnostic message.
30939 The developer should then determine whether the representation
30940 should be 64 bits or not and make either of two changes:
30941 change the size to 64 bits and leave the type as @code{System.Address}, or
30942 leave the size as 32 bits and change the type to @code{System.Short_Address}.
30943 Since @code{Short_Address} is a subtype of @code{Address}, no changes are
30944 required in any code setting or accessing the field; the compiler will
30945 automatically perform any needed conversions between address
30949 @subsubsection Access types
30952 By default, objects designated by access values are always
30953 allocated in the 32-bit
30954 address space. Thus legacy code will never contain
30955 any objects that are not addressable with 32-bit addresses, and
30956 the compiler will never raise exceptions as result of mixing
30957 32-bit and 64-bit addresses.
30959 However, the access values themselves are represented in 64 bits, for optimum
30960 performance and future compatibility with 64-bit code. As was
30961 the case with @code{System.Address}, the compiler will give an error message
30962 if an object or record component has a representation clause that
30963 requires the access value to fit in 32 bits. In such a situation,
30964 an explicit size clause for the access type, specifying 32 bits,
30965 will have the desired effect.
30967 General access types (declared with @code{access all}) can never be
30968 32 bits, as values of such types must be able to refer to any object
30969 of the designated type,
30970 including objects residing outside the 32-bit address range.
30971 Existing Ada 83 code will not contain such type definitions,
30972 however, since general access types were introduced in Ada 95.
30974 @node Unchecked conversions
30975 @subsubsection Unchecked conversions
30978 In the case of an @code{Unchecked_Conversion} where the source type is a
30979 64-bit access type or the type @code{System.Address}, and the target
30980 type is a 32-bit type, the compiler will generate a warning.
30981 Even though the generated code will still perform the required
30982 conversions, it is highly recommended in these cases to use
30983 respectively a 32-bit access type or @code{System.Short_Address}
30984 as the source type.
30986 @node Predefined constants
30987 @subsubsection Predefined constants
30990 The following table shows the correspondence between pre-2006 versions of
30991 @value{EDITION} on Alpha OpenVMS (``Old'') and 64-bit @value{EDITION}
30994 @multitable {@code{System.Short_Memory_Size}} {2**32} {2**64}
30995 @item @b{Constant} @tab @b{Old} @tab @b{New}
30996 @item @code{System.Word_Size} @tab 32 @tab 64
30997 @item @code{System.Memory_Size} @tab 2**32 @tab 2**64
30998 @item @code{System.Short_Memory_Size} @tab 2**32 @tab 2**32
30999 @item @code{System.Address_Size} @tab 32 @tab 64
31003 If you need to refer to the specific
31004 memory size of a 32-bit implementation, instead of the
31005 actual memory size, use @code{System.Short_Memory_Size}
31006 rather than @code{System.Memory_Size}.
31007 Similarly, references to @code{System.Address_Size} may need
31008 to be replaced by @code{System.Short_Address'Size}.
31009 The program @command{gnatfind} may be useful for locating
31010 references to the above constants, so that you can verify that they
31013 @node Interfacing with C
31014 @subsubsection Interfacing with C
31017 In order to minimize the impact of the transition to 64-bit addresses on
31018 legacy programs, some fundamental types in the @code{Interfaces.C}
31019 package hierarchy continue to be represented in 32 bits.
31020 These types are: @code{ptrdiff_t}, @code{size_t}, and @code{chars_ptr}.
31021 This eases integration with the default HP C layout choices, for example
31022 as found in the system routines in @code{DECC$SHR.EXE}.
31023 Because of this implementation choice, the type fully compatible with
31024 @code{chars_ptr} is now @code{Short_Address} and not @code{Address}.
31025 Depending on the context the compiler will issue a
31026 warning or an error when type @code{Address} is used, alerting the user to a
31027 potential problem. Otherwise 32-bit programs that use
31028 @code{Interfaces.C} should normally not require code modifications
31030 The other issue arising with C interfacing concerns pragma @code{Convention}.
31031 For VMS 64-bit systems, there is an issue of the appropriate default size
31032 of C convention pointers in the absence of an explicit size clause. The HP
31033 C compiler can choose either 32 or 64 bits depending on compiler options.
31034 GNAT chooses 32-bits rather than 64-bits in the default case where no size
31035 clause is given. This proves a better choice for porting 32-bit legacy
31036 applications. In order to have a 64-bit representation, it is necessary to
31037 specify a size representation clause. For example:
31039 @smallexample @c ada
31040 type int_star is access Interfaces.C.int;
31041 pragma Convention(C, int_star);
31042 for int_star'Size use 64; -- Necessary to get 64 and not 32 bits
31045 @node Experience with source compatibility
31046 @subsubsection Experience with source compatibility
31049 The Security Server and STARLET on I64 provide an interesting ``test case''
31050 for source compatibility issues, since it is in such system code
31051 where assumptions about @code{Address} size might be expected to occur.
31052 Indeed, there were a small number of occasions in the Security Server
31053 file @file{jibdef.ads}
31054 where a representation clause for a record type specified
31055 32 bits for a component of type @code{Address}.
31056 All of these errors were detected by the compiler.
31057 The repair was obvious and immediate; to simply replace @code{Address} by
31058 @code{Short_Address}.
31060 In the case of STARLET, there were several record types that should
31061 have had representation clauses but did not. In these record types
31062 there was an implicit assumption that an @code{Address} value occupied
31064 These compiled without error, but their usage resulted in run-time error
31065 returns from STARLET system calls.
31066 Future GNAT technology enhancements may include a tool that detects and flags
31067 these sorts of potential source code porting problems.
31069 @c ****************************************
31070 @node Taking advantage of 64 bit addressing
31071 @subsection Taking advantage of 64-bit addressing
31074 * Making code 64 bit clean::
31075 * Allocating memory from the 64 bit storage pool::
31076 * Restrictions on use of 64 bit objects::
31077 * Using 64 bit storage pools by default::
31078 * General access types::
31079 * STARLET and other predefined libraries::
31082 @node Making code 64 bit clean
31083 @subsubsection Making code 64-bit clean
31086 In order to prevent problems that may occur when (parts of) a
31087 system start using memory outside the 32-bit address range,
31088 we recommend some additional guidelines:
31092 For imported subprograms that take parameters of the
31093 type @code{System.Address}, ensure that these subprograms can
31094 indeed handle 64-bit addresses. If not, or when in doubt,
31095 change the subprogram declaration to specify
31096 @code{System.Short_Address} instead.
31099 Resolve all warnings related to size mismatches in
31100 unchecked conversions. Failing to do so causes
31101 erroneous execution if the source object is outside
31102 the 32-bit address space.
31105 (optional) Explicitly use the 32-bit storage pool
31106 for access types used in a 32-bit context, or use
31107 generic access types where possible
31108 (@pxref{Restrictions on use of 64 bit objects}).
31112 If these rules are followed, the compiler will automatically insert
31113 any necessary checks to ensure that no addresses or access values
31114 passed to 32-bit code ever refer to objects outside the 32-bit
31116 Any attempt to do this will raise @code{Constraint_Error}.
31118 @node Allocating memory from the 64 bit storage pool
31119 @subsubsection Allocating memory from the 64-bit storage pool
31122 For any access type @code{T} that potentially requires memory allocations
31123 beyond the 32-bit address space,
31124 use the following representation clause:
31126 @smallexample @c ada
31127 for T'Storage_Pool use System.Pool_64;
31130 @node Restrictions on use of 64 bit objects
31131 @subsubsection Restrictions on use of 64-bit objects
31134 Taking the address of an object allocated from a 64-bit storage pool,
31135 and then passing this address to a subprogram expecting
31136 @code{System.Short_Address},
31137 or assigning it to a variable of type @code{Short_Address}, will cause
31138 @code{Constraint_Error} to be raised. In case the code is not 64-bit clean
31139 (@pxref{Making code 64 bit clean}), or checks are suppressed,
31140 no exception is raised and execution
31141 will become erroneous.
31143 @node Using 64 bit storage pools by default
31144 @subsubsection Using 64-bit storage pools by default
31147 In some cases it may be desirable to have the compiler allocate
31148 from 64-bit storage pools by default. This may be the case for
31149 libraries that are 64-bit clean, but may be used in both 32-bit
31150 and 64-bit contexts. For these cases the following configuration
31151 pragma may be specified:
31153 @smallexample @c ada
31154 pragma Pool_64_Default;
31158 Any code compiled in the context of this pragma will by default
31159 use the @code{System.Pool_64} storage pool. This default may be overridden
31160 for a specific access type @code{T} by the representation clause:
31162 @smallexample @c ada
31163 for T'Storage_Pool use System.Pool_32;
31167 Any object whose address may be passed to a subprogram with a
31168 @code{Short_Address} argument, or assigned to a variable of type
31169 @code{Short_Address}, needs to be allocated from this pool.
31171 @node General access types
31172 @subsubsection General access types
31175 Objects designated by access values from a
31176 general access type (declared with @code{access all}) are never allocated
31177 from a 64-bit storage pool. Code that uses general access types will
31178 accept objects allocated in either 32-bit or 64-bit address spaces,
31179 but never allocate objects outside the 32-bit address space.
31180 Using general access types ensures maximum compatibility with both
31181 32-bit and 64-bit code.
31183 @node STARLET and other predefined libraries
31184 @subsubsection STARLET and other predefined libraries
31187 All code that comes as part of GNAT is 64-bit clean, but the
31188 restrictions given in @ref{Restrictions on use of 64 bit objects},
31189 still apply. Look at the package
31190 specs to see in which contexts objects allocated
31191 in 64-bit address space are acceptable.
31193 @node Technical details
31194 @subsection Technical details
31197 64-bit @value{EDITION} for Open VMS takes advantage of the freedom given in the
31198 Ada standard with respect to the type of @code{System.Address}. Previous
31199 versions of GNAT Pro have defined this type as private and implemented it as a
31202 In order to allow defining @code{System.Short_Address} as a proper subtype,
31203 and to match the implicit sign extension in parameter passing,
31204 in 64-bit @value{EDITION} for Open VMS, @code{System.Address} is defined as a
31205 visible (i.e., non-private) integer type.
31206 Standard operations on the type, such as the binary operators ``+'', ``-'',
31207 etc., that take @code{Address} operands and return an @code{Address} result,
31208 have been hidden by declaring these
31209 @code{abstract}, a feature introduced in Ada 95 that helps avoid the potential
31210 ambiguities that would otherwise result from overloading.
31211 (Note that, although @code{Address} is a visible integer type,
31212 good programming practice dictates against exploiting the type's
31213 integer properties such as literals, since this will compromise
31216 Defining @code{Address} as a visible integer type helps achieve
31217 maximum compatibility for existing Ada code,
31218 without sacrificing the capabilities of the 64-bit architecture.
31221 @c ************************************************
31223 @node Microsoft Windows Topics
31224 @appendix Microsoft Windows Topics
31230 This chapter describes topics that are specific to the Microsoft Windows
31231 platforms (NT, 2000, and XP Professional).
31234 * Using GNAT on Windows::
31235 * Using a network installation of GNAT::
31236 * CONSOLE and WINDOWS subsystems::
31237 * Temporary Files::
31238 * Mixed-Language Programming on Windows::
31239 * Windows Calling Conventions::
31240 * Introduction to Dynamic Link Libraries (DLLs)::
31241 * Using DLLs with GNAT::
31242 * Building DLLs with GNAT::
31243 * Building DLLs with GNAT Project files::
31244 * Building DLLs with gnatdll::
31245 * GNAT and Windows Resources::
31246 * Debugging a DLL::
31247 * Setting Stack Size from gnatlink::
31248 * Setting Heap Size from gnatlink::
31251 @node Using GNAT on Windows
31252 @section Using GNAT on Windows
31255 One of the strengths of the GNAT technology is that its tool set
31256 (@command{gcc}, @command{gnatbind}, @command{gnatlink}, @command{gnatmake}, the
31257 @code{gdb} debugger, etc.) is used in the same way regardless of the
31260 On Windows this tool set is complemented by a number of Microsoft-specific
31261 tools that have been provided to facilitate interoperability with Windows
31262 when this is required. With these tools:
31267 You can build applications using the @code{CONSOLE} or @code{WINDOWS}
31271 You can use any Dynamically Linked Library (DLL) in your Ada code (both
31272 relocatable and non-relocatable DLLs are supported).
31275 You can build Ada DLLs for use in other applications. These applications
31276 can be written in a language other than Ada (e.g., C, C++, etc). Again both
31277 relocatable and non-relocatable Ada DLLs are supported.
31280 You can include Windows resources in your Ada application.
31283 You can use or create COM/DCOM objects.
31287 Immediately below are listed all known general GNAT-for-Windows restrictions.
31288 Other restrictions about specific features like Windows Resources and DLLs
31289 are listed in separate sections below.
31294 It is not possible to use @code{GetLastError} and @code{SetLastError}
31295 when tasking, protected records, or exceptions are used. In these
31296 cases, in order to implement Ada semantics, the GNAT run-time system
31297 calls certain Win32 routines that set the last error variable to 0 upon
31298 success. It should be possible to use @code{GetLastError} and
31299 @code{SetLastError} when tasking, protected record, and exception
31300 features are not used, but it is not guaranteed to work.
31303 It is not possible to link against Microsoft libraries except for
31304 import libraries. The library must be built to be compatible with
31305 @file{MSVCRT.LIB} (/MD Microsoft compiler option), @file{LIBC.LIB} and
31306 @file{LIBCMT.LIB} (/ML or /MT Microsoft compiler options) are known to
31307 not be compatible with the GNAT runtime. Even if the library is
31308 compatible with @file{MSVCRT.LIB} it is not guaranteed to work.
31311 When the compilation environment is located on FAT32 drives, users may
31312 experience recompilations of the source files that have not changed if
31313 Daylight Saving Time (DST) state has changed since the last time files
31314 were compiled. NTFS drives do not have this problem.
31317 No components of the GNAT toolset use any entries in the Windows
31318 registry. The only entries that can be created are file associations and
31319 PATH settings, provided the user has chosen to create them at installation
31320 time, as well as some minimal book-keeping information needed to correctly
31321 uninstall or integrate different GNAT products.
31324 @node Using a network installation of GNAT
31325 @section Using a network installation of GNAT
31328 Make sure the system on which GNAT is installed is accessible from the
31329 current machine, i.e., the install location is shared over the network.
31330 Shared resources are accessed on Windows by means of UNC paths, which
31331 have the format @code{\\server\sharename\path}
31333 In order to use such a network installation, simply add the UNC path of the
31334 @file{bin} directory of your GNAT installation in front of your PATH. For
31335 example, if GNAT is installed in @file{\GNAT} directory of a share location
31336 called @file{c-drive} on a machine @file{LOKI}, the following command will
31339 @code{@ @ @ path \\loki\c-drive\gnat\bin;%path%}
31341 Be aware that every compilation using the network installation results in the
31342 transfer of large amounts of data across the network and will likely cause
31343 serious performance penalty.
31345 @node CONSOLE and WINDOWS subsystems
31346 @section CONSOLE and WINDOWS subsystems
31347 @cindex CONSOLE Subsystem
31348 @cindex WINDOWS Subsystem
31352 There are two main subsystems under Windows. The @code{CONSOLE} subsystem
31353 (which is the default subsystem) will always create a console when
31354 launching the application. This is not something desirable when the
31355 application has a Windows GUI. To get rid of this console the
31356 application must be using the @code{WINDOWS} subsystem. To do so
31357 the @option{-mwindows} linker option must be specified.
31360 $ gnatmake winprog -largs -mwindows
31363 @node Temporary Files
31364 @section Temporary Files
31365 @cindex Temporary files
31368 It is possible to control where temporary files gets created by setting
31369 the @env{TMP} environment variable. The file will be created:
31372 @item Under the directory pointed to by the @env{TMP} environment variable if
31373 this directory exists.
31375 @item Under @file{c:\temp}, if the @env{TMP} environment variable is not
31376 set (or not pointing to a directory) and if this directory exists.
31378 @item Under the current working directory otherwise.
31382 This allows you to determine exactly where the temporary
31383 file will be created. This is particularly useful in networked
31384 environments where you may not have write access to some
31387 @node Mixed-Language Programming on Windows
31388 @section Mixed-Language Programming on Windows
31391 Developing pure Ada applications on Windows is no different than on
31392 other GNAT-supported platforms. However, when developing or porting an
31393 application that contains a mix of Ada and C/C++, the choice of your
31394 Windows C/C++ development environment conditions your overall
31395 interoperability strategy.
31397 If you use @command{gcc} to compile the non-Ada part of your application,
31398 there are no Windows-specific restrictions that affect the overall
31399 interoperability with your Ada code. If you plan to use
31400 Microsoft tools (e.g.@: Microsoft Visual C/C++), you should be aware of
31401 the following limitations:
31405 You cannot link your Ada code with an object or library generated with
31406 Microsoft tools if these use the @code{.tls} section (Thread Local
31407 Storage section) since the GNAT linker does not yet support this section.
31410 You cannot link your Ada code with an object or library generated with
31411 Microsoft tools if these use I/O routines other than those provided in
31412 the Microsoft DLL: @code{msvcrt.dll}. This is because the GNAT run time
31413 uses the services of @code{msvcrt.dll} for its I/Os. Use of other I/O
31414 libraries can cause a conflict with @code{msvcrt.dll} services. For
31415 instance Visual C++ I/O stream routines conflict with those in
31420 If you do want to use the Microsoft tools for your non-Ada code and hit one
31421 of the above limitations, you have two choices:
31425 Encapsulate your non-Ada code in a DLL to be linked with your Ada
31426 application. In this case, use the Microsoft or whatever environment to
31427 build the DLL and use GNAT to build your executable
31428 (@pxref{Using DLLs with GNAT}).
31431 Or you can encapsulate your Ada code in a DLL to be linked with the
31432 other part of your application. In this case, use GNAT to build the DLL
31433 (@pxref{Building DLLs with GNAT}) and use the Microsoft or whatever
31434 environment to build your executable.
31437 @node Windows Calling Conventions
31438 @section Windows Calling Conventions
31443 * C Calling Convention::
31444 * Stdcall Calling Convention::
31445 * Win32 Calling Convention::
31446 * DLL Calling Convention::
31450 When a subprogram @code{F} (caller) calls a subprogram @code{G}
31451 (callee), there are several ways to push @code{G}'s parameters on the
31452 stack and there are several possible scenarios to clean up the stack
31453 upon @code{G}'s return. A calling convention is an agreed upon software
31454 protocol whereby the responsibilities between the caller (@code{F}) and
31455 the callee (@code{G}) are clearly defined. Several calling conventions
31456 are available for Windows:
31460 @code{C} (Microsoft defined)
31463 @code{Stdcall} (Microsoft defined)
31466 @code{Win32} (GNAT specific)
31469 @code{DLL} (GNAT specific)
31472 @node C Calling Convention
31473 @subsection @code{C} Calling Convention
31476 This is the default calling convention used when interfacing to C/C++
31477 routines compiled with either @command{gcc} or Microsoft Visual C++.
31479 In the @code{C} calling convention subprogram parameters are pushed on the
31480 stack by the caller from right to left. The caller itself is in charge of
31481 cleaning up the stack after the call. In addition, the name of a routine
31482 with @code{C} calling convention is mangled by adding a leading underscore.
31484 The name to use on the Ada side when importing (or exporting) a routine
31485 with @code{C} calling convention is the name of the routine. For
31486 instance the C function:
31489 int get_val (long);
31493 should be imported from Ada as follows:
31495 @smallexample @c ada
31497 function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
31498 pragma Import (C, Get_Val, External_Name => "get_val");
31503 Note that in this particular case the @code{External_Name} parameter could
31504 have been omitted since, when missing, this parameter is taken to be the
31505 name of the Ada entity in lower case. When the @code{Link_Name} parameter
31506 is missing, as in the above example, this parameter is set to be the
31507 @code{External_Name} with a leading underscore.
31509 When importing a variable defined in C, you should always use the @code{C}
31510 calling convention unless the object containing the variable is part of a
31511 DLL (in which case you should use the @code{Stdcall} calling
31512 convention, @pxref{Stdcall Calling Convention}).
31514 @node Stdcall Calling Convention
31515 @subsection @code{Stdcall} Calling Convention
31518 This convention, which was the calling convention used for Pascal
31519 programs, is used by Microsoft for all the routines in the Win32 API for
31520 efficiency reasons. It must be used to import any routine for which this
31521 convention was specified.
31523 In the @code{Stdcall} calling convention subprogram parameters are pushed
31524 on the stack by the caller from right to left. The callee (and not the
31525 caller) is in charge of cleaning the stack on routine exit. In addition,
31526 the name of a routine with @code{Stdcall} calling convention is mangled by
31527 adding a leading underscore (as for the @code{C} calling convention) and a
31528 trailing @code{@@}@code{@var{nn}}, where @var{nn} is the overall size (in
31529 bytes) of the parameters passed to the routine.
31531 The name to use on the Ada side when importing a C routine with a
31532 @code{Stdcall} calling convention is the name of the C routine. The leading
31533 underscore and trailing @code{@@}@code{@var{nn}} are added automatically by
31534 the compiler. For instance the Win32 function:
31537 @b{APIENTRY} int get_val (long);
31541 should be imported from Ada as follows:
31543 @smallexample @c ada
31545 function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
31546 pragma Import (Stdcall, Get_Val);
31547 -- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4"
31552 As for the @code{C} calling convention, when the @code{External_Name}
31553 parameter is missing, it is taken to be the name of the Ada entity in lower
31554 case. If instead of writing the above import pragma you write:
31556 @smallexample @c ada
31558 function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
31559 pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val");
31564 then the imported routine is @code{_retrieve_val@@4}. However, if instead
31565 of specifying the @code{External_Name} parameter you specify the
31566 @code{Link_Name} as in the following example:
31568 @smallexample @c ada
31570 function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
31571 pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");
31576 then the imported routine is @code{retrieve_val}, that is, there is no
31577 decoration at all. No leading underscore and no Stdcall suffix
31578 @code{@@}@code{@var{nn}}.
31581 This is especially important as in some special cases a DLL's entry
31582 point name lacks a trailing @code{@@}@code{@var{nn}} while the exported
31583 name generated for a call has it.
31586 It is also possible to import variables defined in a DLL by using an
31587 import pragma for a variable. As an example, if a DLL contains a
31588 variable defined as:
31595 then, to access this variable from Ada you should write:
31597 @smallexample @c ada
31599 My_Var : Interfaces.C.int;
31600 pragma Import (Stdcall, My_Var);
31605 Note that to ease building cross-platform bindings this convention
31606 will be handled as a @code{C} calling convention on non-Windows platforms.
31608 @node Win32 Calling Convention
31609 @subsection @code{Win32} Calling Convention
31612 This convention, which is GNAT-specific is fully equivalent to the
31613 @code{Stdcall} calling convention described above.
31615 @node DLL Calling Convention
31616 @subsection @code{DLL} Calling Convention
31619 This convention, which is GNAT-specific is fully equivalent to the
31620 @code{Stdcall} calling convention described above.
31622 @node Introduction to Dynamic Link Libraries (DLLs)
31623 @section Introduction to Dynamic Link Libraries (DLLs)
31627 A Dynamically Linked Library (DLL) is a library that can be shared by
31628 several applications running under Windows. A DLL can contain any number of
31629 routines and variables.
31631 One advantage of DLLs is that you can change and enhance them without
31632 forcing all the applications that depend on them to be relinked or
31633 recompiled. However, you should be aware than all calls to DLL routines are
31634 slower since, as you will understand below, such calls are indirect.
31636 To illustrate the remainder of this section, suppose that an application
31637 wants to use the services of a DLL @file{API.dll}. To use the services
31638 provided by @file{API.dll} you must statically link against the DLL or
31639 an import library which contains a jump table with an entry for each
31640 routine and variable exported by the DLL. In the Microsoft world this
31641 import library is called @file{API.lib}. When using GNAT this import
31642 library is called either @file{libAPI.dll.a}, @file{libapi.dll.a},
31643 @file{libAPI.a} or @file{libapi.a} (names are case insensitive).
31645 After you have linked your application with the DLL or the import library
31646 and you run your application, here is what happens:
31650 Your application is loaded into memory.
31653 The DLL @file{API.dll} is mapped into the address space of your
31654 application. This means that:
31658 The DLL will use the stack of the calling thread.
31661 The DLL will use the virtual address space of the calling process.
31664 The DLL will allocate memory from the virtual address space of the calling
31668 Handles (pointers) can be safely exchanged between routines in the DLL
31669 routines and routines in the application using the DLL.
31673 The entries in the jump table (from the import library @file{libAPI.dll.a}
31674 or @file{API.lib} or automatically created when linking against a DLL)
31675 which is part of your application are initialized with the addresses
31676 of the routines and variables in @file{API.dll}.
31679 If present in @file{API.dll}, routines @code{DllMain} or
31680 @code{DllMainCRTStartup} are invoked. These routines typically contain
31681 the initialization code needed for the well-being of the routines and
31682 variables exported by the DLL.
31686 There is an additional point which is worth mentioning. In the Windows
31687 world there are two kind of DLLs: relocatable and non-relocatable
31688 DLLs. Non-relocatable DLLs can only be loaded at a very specific address
31689 in the target application address space. If the addresses of two
31690 non-relocatable DLLs overlap and these happen to be used by the same
31691 application, a conflict will occur and the application will run
31692 incorrectly. Hence, when possible, it is always preferable to use and
31693 build relocatable DLLs. Both relocatable and non-relocatable DLLs are
31694 supported by GNAT. Note that the @option{-s} linker option (see GNU Linker
31695 User's Guide) removes the debugging symbols from the DLL but the DLL can
31696 still be relocated.
31698 As a side note, an interesting difference between Microsoft DLLs and
31699 Unix shared libraries, is the fact that on most Unix systems all public
31700 routines are exported by default in a Unix shared library, while under
31701 Windows it is possible (but not required) to list exported routines in
31702 a definition file (@pxref{The Definition File}).
31704 @node Using DLLs with GNAT
31705 @section Using DLLs with GNAT
31708 * Creating an Ada Spec for the DLL Services::
31709 * Creating an Import Library::
31713 To use the services of a DLL, say @file{API.dll}, in your Ada application
31718 The Ada spec for the routines and/or variables you want to access in
31719 @file{API.dll}. If not available this Ada spec must be built from the C/C++
31720 header files provided with the DLL.
31723 The import library (@file{libAPI.dll.a} or @file{API.lib}). As previously
31724 mentioned an import library is a statically linked library containing the
31725 import table which will be filled at load time to point to the actual
31726 @file{API.dll} routines. Sometimes you don't have an import library for the
31727 DLL you want to use. The following sections will explain how to build
31728 one. Note that this is optional.
31731 The actual DLL, @file{API.dll}.
31735 Once you have all the above, to compile an Ada application that uses the
31736 services of @file{API.dll} and whose main subprogram is @code{My_Ada_App},
31737 you simply issue the command
31740 $ gnatmake my_ada_app -largs -lAPI
31744 The argument @option{-largs -lAPI} at the end of the @command{gnatmake} command
31745 tells the GNAT linker to look first for a library named @file{API.lib}
31746 (Microsoft-style name) and if not found for a libraries named
31747 @file{libAPI.dll.a}, @file{API.dll.a} or @file{libAPI.a}.
31748 (GNAT-style name). Note that if the Ada package spec for @file{API.dll}
31749 contains the following pragma
31751 @smallexample @c ada
31752 pragma Linker_Options ("-lAPI");
31756 you do not have to add @option{-largs -lAPI} at the end of the
31757 @command{gnatmake} command.
31759 If any one of the items above is missing you will have to create it
31760 yourself. The following sections explain how to do so using as an
31761 example a fictitious DLL called @file{API.dll}.
31763 @node Creating an Ada Spec for the DLL Services
31764 @subsection Creating an Ada Spec for the DLL Services
31767 A DLL typically comes with a C/C++ header file which provides the
31768 definitions of the routines and variables exported by the DLL. The Ada
31769 equivalent of this header file is a package spec that contains definitions
31770 for the imported entities. If the DLL you intend to use does not come with
31771 an Ada spec you have to generate one such spec yourself. For example if
31772 the header file of @file{API.dll} is a file @file{api.h} containing the
31773 following two definitions:
31785 then the equivalent Ada spec could be:
31787 @smallexample @c ada
31790 with Interfaces.C.Strings;
31795 function Get (Str : C.Strings.Chars_Ptr) return C.int;
31798 pragma Import (C, Get);
31799 pragma Import (DLL, Some_Var);
31806 Note that a variable is
31807 @strong{always imported with a Stdcall convention}. A function
31808 can have @code{C} or @code{Stdcall} convention.
31809 (@pxref{Windows Calling Conventions}).
31811 @node Creating an Import Library
31812 @subsection Creating an Import Library
31813 @cindex Import library
31816 * The Definition File::
31817 * GNAT-Style Import Library::
31818 * Microsoft-Style Import Library::
31822 If a Microsoft-style import library @file{API.lib} or a GNAT-style
31823 import library @file{libAPI.dll.a} or @file{libAPI.a} is available
31824 with @file{API.dll} you can skip this section. You can also skip this
31825 section if @file{API.dll} or @file{libAPI.dll} is built with GNU tools
31826 as in this case it is possible to link directly against the
31827 DLL. Otherwise read on.
31829 @node The Definition File
31830 @subsubsection The Definition File
31831 @cindex Definition file
31835 As previously mentioned, and unlike Unix systems, the list of symbols
31836 that are exported from a DLL must be provided explicitly in Windows.
31837 The main goal of a definition file is precisely that: list the symbols
31838 exported by a DLL. A definition file (usually a file with a @code{.def}
31839 suffix) has the following structure:
31844 @r{[}LIBRARY @var{name}@r{]}
31845 @r{[}DESCRIPTION @var{string}@r{]}
31855 @item LIBRARY @var{name}
31856 This section, which is optional, gives the name of the DLL.
31858 @item DESCRIPTION @var{string}
31859 This section, which is optional, gives a description string that will be
31860 embedded in the import library.
31863 This section gives the list of exported symbols (procedures, functions or
31864 variables). For instance in the case of @file{API.dll} the @code{EXPORTS}
31865 section of @file{API.def} looks like:
31879 Note that you must specify the correct suffix (@code{@@}@code{@var{nn}})
31880 (@pxref{Windows Calling Conventions}) for a Stdcall
31881 calling convention function in the exported symbols list.
31884 There can actually be other sections in a definition file, but these
31885 sections are not relevant to the discussion at hand.
31887 @node GNAT-Style Import Library
31888 @subsubsection GNAT-Style Import Library
31891 To create a static import library from @file{API.dll} with the GNAT tools
31892 you should proceed as follows:
31896 Create the definition file @file{API.def} (@pxref{The Definition File}).
31897 For that use the @code{dll2def} tool as follows:
31900 $ dll2def API.dll > API.def
31904 @code{dll2def} is a very simple tool: it takes as input a DLL and prints
31905 to standard output the list of entry points in the DLL. Note that if
31906 some routines in the DLL have the @code{Stdcall} convention
31907 (@pxref{Windows Calling Conventions}) with stripped @code{@@}@var{nn}
31908 suffix then you'll have to edit @file{api.def} to add it, and specify
31909 @option{-k} to @command{gnatdll} when creating the import library.
31912 Here are some hints to find the right @code{@@}@var{nn} suffix.
31916 If you have the Microsoft import library (.lib), it is possible to get
31917 the right symbols by using Microsoft @code{dumpbin} tool (see the
31918 corresponding Microsoft documentation for further details).
31921 $ dumpbin /exports api.lib
31925 If you have a message about a missing symbol at link time the compiler
31926 tells you what symbol is expected. You just have to go back to the
31927 definition file and add the right suffix.
31931 Build the import library @code{libAPI.dll.a}, using @code{gnatdll}
31932 (@pxref{Using gnatdll}) as follows:
31935 $ gnatdll -e API.def -d API.dll
31939 @code{gnatdll} takes as input a definition file @file{API.def} and the
31940 name of the DLL containing the services listed in the definition file
31941 @file{API.dll}. The name of the static import library generated is
31942 computed from the name of the definition file as follows: if the
31943 definition file name is @var{xyz}@code{.def}, the import library name will
31944 be @code{lib}@var{xyz}@code{.a}. Note that in the previous example option
31945 @option{-e} could have been removed because the name of the definition
31946 file (before the ``@code{.def}'' suffix) is the same as the name of the
31947 DLL (@pxref{Using gnatdll} for more information about @code{gnatdll}).
31950 @node Microsoft-Style Import Library
31951 @subsubsection Microsoft-Style Import Library
31954 With GNAT you can either use a GNAT-style or Microsoft-style import
31955 library. A Microsoft import library is needed only if you plan to make an
31956 Ada DLL available to applications developed with Microsoft
31957 tools (@pxref{Mixed-Language Programming on Windows}).
31959 To create a Microsoft-style import library for @file{API.dll} you
31960 should proceed as follows:
31964 Create the definition file @file{API.def} from the DLL. For this use either
31965 the @code{dll2def} tool as described above or the Microsoft @code{dumpbin}
31966 tool (see the corresponding Microsoft documentation for further details).
31969 Build the actual import library using Microsoft's @code{lib} utility:
31972 $ lib -machine:IX86 -def:API.def -out:API.lib
31976 If you use the above command the definition file @file{API.def} must
31977 contain a line giving the name of the DLL:
31984 See the Microsoft documentation for further details about the usage of
31988 @node Building DLLs with GNAT
31989 @section Building DLLs with GNAT
31990 @cindex DLLs, building
31993 This section explain how to build DLLs using the GNAT built-in DLL
31994 support. With the following procedure it is straight forward to build
31995 and use DLLs with GNAT.
31999 @item building object files
32001 The first step is to build all objects files that are to be included
32002 into the DLL. This is done by using the standard @command{gnatmake} tool.
32004 @item building the DLL
32006 To build the DLL you must use @command{gcc}'s @option{-shared}
32007 option. It is quite simple to use this method:
32010 $ gcc -shared -o api.dll obj1.o obj2.o @dots{}
32013 It is important to note that in this case all symbols found in the
32014 object files are automatically exported. It is possible to restrict
32015 the set of symbols to export by passing to @command{gcc} a definition
32016 file, @pxref{The Definition File}. For example:
32019 $ gcc -shared -o api.dll api.def obj1.o obj2.o @dots{}
32022 If you use a definition file you must export the elaboration procedures
32023 for every package that required one. Elaboration procedures are named
32024 using the package name followed by "_E".
32026 @item preparing DLL to be used
32028 For the DLL to be used by client programs the bodies must be hidden
32029 from it and the .ali set with read-only attribute. This is very important
32030 otherwise GNAT will recompile all packages and will not actually use
32031 the code in the DLL. For example:
32035 $ copy *.ads *.ali api.dll apilib
32036 $ attrib +R apilib\*.ali
32041 At this point it is possible to use the DLL by directly linking
32042 against it. Note that you must use the GNAT shared runtime when using
32043 GNAT shared libraries. This is achieved by using @option{-shared} binder's
32047 $ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI
32050 @node Building DLLs with GNAT Project files
32051 @section Building DLLs with GNAT Project files
32052 @cindex DLLs, building
32055 There is nothing specific to Windows in the build process.
32056 @pxref{Library Projects}.
32059 Due to a system limitation, it is not possible under Windows to create threads
32060 when inside the @code{DllMain} routine which is used for auto-initialization
32061 of shared libraries, so it is not possible to have library level tasks in SALs.
32063 @node Building DLLs with gnatdll
32064 @section Building DLLs with gnatdll
32065 @cindex DLLs, building
32068 * Limitations When Using Ada DLLs from Ada::
32069 * Exporting Ada Entities::
32070 * Ada DLLs and Elaboration::
32071 * Ada DLLs and Finalization::
32072 * Creating a Spec for Ada DLLs::
32073 * Creating the Definition File::
32078 Note that it is preferred to use the built-in GNAT DLL support
32079 (@pxref{Building DLLs with GNAT}) or GNAT Project files
32080 (@pxref{Building DLLs with GNAT Project files}) to build DLLs.
32082 This section explains how to build DLLs containing Ada code using
32083 @code{gnatdll}. These DLLs will be referred to as Ada DLLs in the
32084 remainder of this section.
32086 The steps required to build an Ada DLL that is to be used by Ada as well as
32087 non-Ada applications are as follows:
32091 You need to mark each Ada @i{entity} exported by the DLL with a @code{C} or
32092 @code{Stdcall} calling convention to avoid any Ada name mangling for the
32093 entities exported by the DLL (@pxref{Exporting Ada Entities}). You can
32094 skip this step if you plan to use the Ada DLL only from Ada applications.
32097 Your Ada code must export an initialization routine which calls the routine
32098 @code{adainit} generated by @command{gnatbind} to perform the elaboration of
32099 the Ada code in the DLL (@pxref{Ada DLLs and Elaboration}). The initialization
32100 routine exported by the Ada DLL must be invoked by the clients of the DLL
32101 to initialize the DLL.
32104 When useful, the DLL should also export a finalization routine which calls
32105 routine @code{adafinal} generated by @command{gnatbind} to perform the
32106 finalization of the Ada code in the DLL (@pxref{Ada DLLs and Finalization}).
32107 The finalization routine exported by the Ada DLL must be invoked by the
32108 clients of the DLL when the DLL services are no further needed.
32111 You must provide a spec for the services exported by the Ada DLL in each
32112 of the programming languages to which you plan to make the DLL available.
32115 You must provide a definition file listing the exported entities
32116 (@pxref{The Definition File}).
32119 Finally you must use @code{gnatdll} to produce the DLL and the import
32120 library (@pxref{Using gnatdll}).
32124 Note that a relocatable DLL stripped using the @code{strip}
32125 binutils tool will not be relocatable anymore. To build a DLL without
32126 debug information pass @code{-largs -s} to @code{gnatdll}. This
32127 restriction does not apply to a DLL built using a Library Project.
32128 @pxref{Library Projects}.
32130 @node Limitations When Using Ada DLLs from Ada
32131 @subsection Limitations When Using Ada DLLs from Ada
32134 When using Ada DLLs from Ada applications there is a limitation users
32135 should be aware of. Because on Windows the GNAT run time is not in a DLL of
32136 its own, each Ada DLL includes a part of the GNAT run time. Specifically,
32137 each Ada DLL includes the services of the GNAT run time that are necessary
32138 to the Ada code inside the DLL. As a result, when an Ada program uses an
32139 Ada DLL there are two independent GNAT run times: one in the Ada DLL and
32140 one in the main program.
32142 It is therefore not possible to exchange GNAT run-time objects between the
32143 Ada DLL and the main Ada program. Example of GNAT run-time objects are file
32144 handles (e.g.@: @code{Text_IO.File_Type}), tasks types, protected objects
32147 It is completely safe to exchange plain elementary, array or record types,
32148 Windows object handles, etc.
32150 @node Exporting Ada Entities
32151 @subsection Exporting Ada Entities
32152 @cindex Export table
32155 Building a DLL is a way to encapsulate a set of services usable from any
32156 application. As a result, the Ada entities exported by a DLL should be
32157 exported with the @code{C} or @code{Stdcall} calling conventions to avoid
32158 any Ada name mangling. As an example here is an Ada package
32159 @code{API}, spec and body, exporting two procedures, a function, and a
32162 @smallexample @c ada
32165 with Interfaces.C; use Interfaces;
32167 Count : C.int := 0;
32168 function Factorial (Val : C.int) return C.int;
32170 procedure Initialize_API;
32171 procedure Finalize_API;
32172 -- Initialization & Finalization routines. More in the next section.
32174 pragma Export (C, Initialize_API);
32175 pragma Export (C, Finalize_API);
32176 pragma Export (C, Count);
32177 pragma Export (C, Factorial);
32183 @smallexample @c ada
32186 package body API is
32187 function Factorial (Val : C.int) return C.int is
32190 Count := Count + 1;
32191 for K in 1 .. Val loop
32197 procedure Initialize_API is
32199 pragma Import (C, Adainit);
32202 end Initialize_API;
32204 procedure Finalize_API is
32205 procedure Adafinal;
32206 pragma Import (C, Adafinal);
32216 If the Ada DLL you are building will only be used by Ada applications
32217 you do not have to export Ada entities with a @code{C} or @code{Stdcall}
32218 convention. As an example, the previous package could be written as
32221 @smallexample @c ada
32225 Count : Integer := 0;
32226 function Factorial (Val : Integer) return Integer;
32228 procedure Initialize_API;
32229 procedure Finalize_API;
32230 -- Initialization and Finalization routines.
32236 @smallexample @c ada
32239 package body API is
32240 function Factorial (Val : Integer) return Integer is
32241 Fact : Integer := 1;
32243 Count := Count + 1;
32244 for K in 1 .. Val loop
32251 -- The remainder of this package body is unchanged.
32258 Note that if you do not export the Ada entities with a @code{C} or
32259 @code{Stdcall} convention you will have to provide the mangled Ada names
32260 in the definition file of the Ada DLL
32261 (@pxref{Creating the Definition File}).
32263 @node Ada DLLs and Elaboration
32264 @subsection Ada DLLs and Elaboration
32265 @cindex DLLs and elaboration
32268 The DLL that you are building contains your Ada code as well as all the
32269 routines in the Ada library that are needed by it. The first thing a
32270 user of your DLL must do is elaborate the Ada code
32271 (@pxref{Elaboration Order Handling in GNAT}).
32273 To achieve this you must export an initialization routine
32274 (@code{Initialize_API} in the previous example), which must be invoked
32275 before using any of the DLL services. This elaboration routine must call
32276 the Ada elaboration routine @code{adainit} generated by the GNAT binder
32277 (@pxref{Binding with Non-Ada Main Programs}). See the body of
32278 @code{Initialize_Api} for an example. Note that the GNAT binder is
32279 automatically invoked during the DLL build process by the @code{gnatdll}
32280 tool (@pxref{Using gnatdll}).
32282 When a DLL is loaded, Windows systematically invokes a routine called
32283 @code{DllMain}. It would therefore be possible to call @code{adainit}
32284 directly from @code{DllMain} without having to provide an explicit
32285 initialization routine. Unfortunately, it is not possible to call
32286 @code{adainit} from the @code{DllMain} if your program has library level
32287 tasks because access to the @code{DllMain} entry point is serialized by
32288 the system (that is, only a single thread can execute ``through'' it at a
32289 time), which means that the GNAT run time will deadlock waiting for the
32290 newly created task to complete its initialization.
32292 @node Ada DLLs and Finalization
32293 @subsection Ada DLLs and Finalization
32294 @cindex DLLs and finalization
32297 When the services of an Ada DLL are no longer needed, the client code should
32298 invoke the DLL finalization routine, if available. The DLL finalization
32299 routine is in charge of releasing all resources acquired by the DLL. In the
32300 case of the Ada code contained in the DLL, this is achieved by calling
32301 routine @code{adafinal} generated by the GNAT binder
32302 (@pxref{Binding with Non-Ada Main Programs}).
32303 See the body of @code{Finalize_Api} for an
32304 example. As already pointed out the GNAT binder is automatically invoked
32305 during the DLL build process by the @code{gnatdll} tool
32306 (@pxref{Using gnatdll}).
32308 @node Creating a Spec for Ada DLLs
32309 @subsection Creating a Spec for Ada DLLs
32312 To use the services exported by the Ada DLL from another programming
32313 language (e.g.@: C), you have to translate the specs of the exported Ada
32314 entities in that language. For instance in the case of @code{API.dll},
32315 the corresponding C header file could look like:
32320 extern int *_imp__count;
32321 #define count (*_imp__count)
32322 int factorial (int);
32328 It is important to understand that when building an Ada DLL to be used by
32329 other Ada applications, you need two different specs for the packages
32330 contained in the DLL: one for building the DLL and the other for using
32331 the DLL. This is because the @code{DLL} calling convention is needed to
32332 use a variable defined in a DLL, but when building the DLL, the variable
32333 must have either the @code{Ada} or @code{C} calling convention. As an
32334 example consider a DLL comprising the following package @code{API}:
32336 @smallexample @c ada
32340 Count : Integer := 0;
32342 -- Remainder of the package omitted.
32349 After producing a DLL containing package @code{API}, the spec that
32350 must be used to import @code{API.Count} from Ada code outside of the
32353 @smallexample @c ada
32358 pragma Import (DLL, Count);
32364 @node Creating the Definition File
32365 @subsection Creating the Definition File
32368 The definition file is the last file needed to build the DLL. It lists
32369 the exported symbols. As an example, the definition file for a DLL
32370 containing only package @code{API} (where all the entities are exported
32371 with a @code{C} calling convention) is:
32386 If the @code{C} calling convention is missing from package @code{API},
32387 then the definition file contains the mangled Ada names of the above
32388 entities, which in this case are:
32397 api__initialize_api
32402 @node Using gnatdll
32403 @subsection Using @code{gnatdll}
32407 * gnatdll Example::
32408 * gnatdll behind the Scenes::
32413 @code{gnatdll} is a tool to automate the DLL build process once all the Ada
32414 and non-Ada sources that make up your DLL have been compiled.
32415 @code{gnatdll} is actually in charge of two distinct tasks: build the
32416 static import library for the DLL and the actual DLL. The form of the
32417 @code{gnatdll} command is
32421 $ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
32426 where @var{list-of-files} is a list of ALI and object files. The object
32427 file list must be the exact list of objects corresponding to the non-Ada
32428 sources whose services are to be included in the DLL. The ALI file list
32429 must be the exact list of ALI files for the corresponding Ada sources
32430 whose services are to be included in the DLL. If @var{list-of-files} is
32431 missing, only the static import library is generated.
32434 You may specify any of the following switches to @code{gnatdll}:
32437 @item -a@ovar{address}
32438 @cindex @option{-a} (@code{gnatdll})
32439 Build a non-relocatable DLL at @var{address}. If @var{address} is not
32440 specified the default address @var{0x11000000} will be used. By default,
32441 when this switch is missing, @code{gnatdll} builds relocatable DLL. We
32442 advise the reader to build relocatable DLL.
32444 @item -b @var{address}
32445 @cindex @option{-b} (@code{gnatdll})
32446 Set the relocatable DLL base address. By default the address is
32449 @item -bargs @var{opts}
32450 @cindex @option{-bargs} (@code{gnatdll})
32451 Binder options. Pass @var{opts} to the binder.
32453 @item -d @var{dllfile}
32454 @cindex @option{-d} (@code{gnatdll})
32455 @var{dllfile} is the name of the DLL. This switch must be present for
32456 @code{gnatdll} to do anything. The name of the generated import library is
32457 obtained algorithmically from @var{dllfile} as shown in the following
32458 example: if @var{dllfile} is @code{xyz.dll}, the import library name is
32459 @code{libxyz.dll.a}. The name of the definition file to use (if not specified
32460 by option @option{-e}) is obtained algorithmically from @var{dllfile}
32461 as shown in the following example:
32462 if @var{dllfile} is @code{xyz.dll}, the definition
32463 file used is @code{xyz.def}.
32465 @item -e @var{deffile}
32466 @cindex @option{-e} (@code{gnatdll})
32467 @var{deffile} is the name of the definition file.
32470 @cindex @option{-g} (@code{gnatdll})
32471 Generate debugging information. This information is stored in the object
32472 file and copied from there to the final DLL file by the linker,
32473 where it can be read by the debugger. You must use the
32474 @option{-g} switch if you plan on using the debugger or the symbolic
32478 @cindex @option{-h} (@code{gnatdll})
32479 Help mode. Displays @code{gnatdll} switch usage information.
32482 @cindex @option{-I} (@code{gnatdll})
32483 Direct @code{gnatdll} to search the @var{dir} directory for source and
32484 object files needed to build the DLL.
32485 (@pxref{Search Paths and the Run-Time Library (RTL)}).
32488 @cindex @option{-k} (@code{gnatdll})
32489 Removes the @code{@@}@var{nn} suffix from the import library's exported
32490 names, but keeps them for the link names. You must specify this
32491 option if you want to use a @code{Stdcall} function in a DLL for which
32492 the @code{@@}@var{nn} suffix has been removed. This is the case for most
32493 of the Windows NT DLL for example. This option has no effect when
32494 @option{-n} option is specified.
32496 @item -l @var{file}
32497 @cindex @option{-l} (@code{gnatdll})
32498 The list of ALI and object files used to build the DLL are listed in
32499 @var{file}, instead of being given in the command line. Each line in
32500 @var{file} contains the name of an ALI or object file.
32503 @cindex @option{-n} (@code{gnatdll})
32504 No Import. Do not create the import library.
32507 @cindex @option{-q} (@code{gnatdll})
32508 Quiet mode. Do not display unnecessary messages.
32511 @cindex @option{-v} (@code{gnatdll})
32512 Verbose mode. Display extra information.
32514 @item -largs @var{opts}
32515 @cindex @option{-largs} (@code{gnatdll})
32516 Linker options. Pass @var{opts} to the linker.
32519 @node gnatdll Example
32520 @subsubsection @code{gnatdll} Example
32523 As an example the command to build a relocatable DLL from @file{api.adb}
32524 once @file{api.adb} has been compiled and @file{api.def} created is
32527 $ gnatdll -d api.dll api.ali
32531 The above command creates two files: @file{libapi.dll.a} (the import
32532 library) and @file{api.dll} (the actual DLL). If you want to create
32533 only the DLL, just type:
32536 $ gnatdll -d api.dll -n api.ali
32540 Alternatively if you want to create just the import library, type:
32543 $ gnatdll -d api.dll
32546 @node gnatdll behind the Scenes
32547 @subsubsection @code{gnatdll} behind the Scenes
32550 This section details the steps involved in creating a DLL. @code{gnatdll}
32551 does these steps for you. Unless you are interested in understanding what
32552 goes on behind the scenes, you should skip this section.
32554 We use the previous example of a DLL containing the Ada package @code{API},
32555 to illustrate the steps necessary to build a DLL. The starting point is a
32556 set of objects that will make up the DLL and the corresponding ALI
32557 files. In the case of this example this means that @file{api.o} and
32558 @file{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does
32563 @code{gnatdll} builds the base file (@file{api.base}). A base file gives
32564 the information necessary to generate relocation information for the
32570 $ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
32575 In addition to the base file, the @command{gnatlink} command generates an
32576 output file @file{api.jnk} which can be discarded. The @option{-mdll} switch
32577 asks @command{gnatlink} to generate the routines @code{DllMain} and
32578 @code{DllMainCRTStartup} that are called by the Windows loader when the DLL
32579 is loaded into memory.
32582 @code{gnatdll} uses @code{dlltool} (@pxref{Using dlltool}) to build the
32583 export table (@file{api.exp}). The export table contains the relocation
32584 information in a form which can be used during the final link to ensure
32585 that the Windows loader is able to place the DLL anywhere in memory.
32589 $ dlltool --dllname api.dll --def api.def --base-file api.base \
32590 --output-exp api.exp
32595 @code{gnatdll} builds the base file using the new export table. Note that
32596 @command{gnatbind} must be called once again since the binder generated file
32597 has been deleted during the previous call to @command{gnatlink}.
32602 $ gnatlink api -o api.jnk api.exp -mdll
32603 -Wl,--base-file,api.base
32608 @code{gnatdll} builds the new export table using the new base file and
32609 generates the DLL import library @file{libAPI.dll.a}.
32613 $ dlltool --dllname api.dll --def api.def --base-file api.base \
32614 --output-exp api.exp --output-lib libAPI.a
32619 Finally @code{gnatdll} builds the relocatable DLL using the final export
32625 $ gnatlink api api.exp -o api.dll -mdll
32630 @node Using dlltool
32631 @subsubsection Using @code{dlltool}
32634 @code{dlltool} is the low-level tool used by @code{gnatdll} to build
32635 DLLs and static import libraries. This section summarizes the most
32636 common @code{dlltool} switches. The form of the @code{dlltool} command
32640 $ dlltool @ovar{switches}
32644 @code{dlltool} switches include:
32647 @item --base-file @var{basefile}
32648 @cindex @option{--base-file} (@command{dlltool})
32649 Read the base file @var{basefile} generated by the linker. This switch
32650 is used to create a relocatable DLL.
32652 @item --def @var{deffile}
32653 @cindex @option{--def} (@command{dlltool})
32654 Read the definition file.
32656 @item --dllname @var{name}
32657 @cindex @option{--dllname} (@command{dlltool})
32658 Gives the name of the DLL. This switch is used to embed the name of the
32659 DLL in the static import library generated by @code{dlltool} with switch
32660 @option{--output-lib}.
32663 @cindex @option{-k} (@command{dlltool})
32664 Kill @code{@@}@var{nn} from exported names
32665 (@pxref{Windows Calling Conventions}
32666 for a discussion about @code{Stdcall}-style symbols.
32669 @cindex @option{--help} (@command{dlltool})
32670 Prints the @code{dlltool} switches with a concise description.
32672 @item --output-exp @var{exportfile}
32673 @cindex @option{--output-exp} (@command{dlltool})
32674 Generate an export file @var{exportfile}. The export file contains the
32675 export table (list of symbols in the DLL) and is used to create the DLL.
32677 @item --output-lib @var{libfile}
32678 @cindex @option{--output-lib} (@command{dlltool})
32679 Generate a static import library @var{libfile}.
32682 @cindex @option{-v} (@command{dlltool})
32685 @item --as @var{assembler-name}
32686 @cindex @option{--as} (@command{dlltool})
32687 Use @var{assembler-name} as the assembler. The default is @code{as}.
32690 @node GNAT and Windows Resources
32691 @section GNAT and Windows Resources
32692 @cindex Resources, windows
32695 * Building Resources::
32696 * Compiling Resources::
32697 * Using Resources::
32701 Resources are an easy way to add Windows specific objects to your
32702 application. The objects that can be added as resources include:
32731 This section explains how to build, compile and use resources.
32733 @node Building Resources
32734 @subsection Building Resources
32735 @cindex Resources, building
32738 A resource file is an ASCII file. By convention resource files have an
32739 @file{.rc} extension.
32740 The easiest way to build a resource file is to use Microsoft tools
32741 such as @code{imagedit.exe} to build bitmaps, icons and cursors and
32742 @code{dlgedit.exe} to build dialogs.
32743 It is always possible to build an @file{.rc} file yourself by writing a
32746 It is not our objective to explain how to write a resource file. A
32747 complete description of the resource script language can be found in the
32748 Microsoft documentation.
32750 @node Compiling Resources
32751 @subsection Compiling Resources
32754 @cindex Resources, compiling
32757 This section describes how to build a GNAT-compatible (COFF) object file
32758 containing the resources. This is done using the Resource Compiler
32759 @code{windres} as follows:
32762 $ windres -i myres.rc -o myres.o
32766 By default @code{windres} will run @command{gcc} to preprocess the @file{.rc}
32767 file. You can specify an alternate preprocessor (usually named
32768 @file{cpp.exe}) using the @code{windres} @option{--preprocessor}
32769 parameter. A list of all possible options may be obtained by entering
32770 the command @code{windres} @option{--help}.
32772 It is also possible to use the Microsoft resource compiler @code{rc.exe}
32773 to produce a @file{.res} file (binary resource file). See the
32774 corresponding Microsoft documentation for further details. In this case
32775 you need to use @code{windres} to translate the @file{.res} file to a
32776 GNAT-compatible object file as follows:
32779 $ windres -i myres.res -o myres.o
32782 @node Using Resources
32783 @subsection Using Resources
32784 @cindex Resources, using
32787 To include the resource file in your program just add the
32788 GNAT-compatible object file for the resource(s) to the linker
32789 arguments. With @command{gnatmake} this is done by using the @option{-largs}
32793 $ gnatmake myprog -largs myres.o
32796 @node Debugging a DLL
32797 @section Debugging a DLL
32798 @cindex DLL debugging
32801 * Program and DLL Both Built with GCC/GNAT::
32802 * Program Built with Foreign Tools and DLL Built with GCC/GNAT::
32806 Debugging a DLL is similar to debugging a standard program. But
32807 we have to deal with two different executable parts: the DLL and the
32808 program that uses it. We have the following four possibilities:
32812 The program and the DLL are built with @code{GCC/GNAT}.
32814 The program is built with foreign tools and the DLL is built with
32817 The program is built with @code{GCC/GNAT} and the DLL is built with
32823 In this section we address only cases one and two above.
32824 There is no point in trying to debug
32825 a DLL with @code{GNU/GDB}, if there is no GDB-compatible debugging
32826 information in it. To do so you must use a debugger compatible with the
32827 tools suite used to build the DLL.
32829 @node Program and DLL Both Built with GCC/GNAT
32830 @subsection Program and DLL Both Built with GCC/GNAT
32833 This is the simplest case. Both the DLL and the program have @code{GDB}
32834 compatible debugging information. It is then possible to break anywhere in
32835 the process. Let's suppose here that the main procedure is named
32836 @code{ada_main} and that in the DLL there is an entry point named
32840 The DLL (@pxref{Introduction to Dynamic Link Libraries (DLLs)}) and
32841 program must have been built with the debugging information (see GNAT -g
32842 switch). Here are the step-by-step instructions for debugging it:
32845 @item Launch @code{GDB} on the main program.
32851 @item Start the program and stop at the beginning of the main procedure
32858 This step is required to be able to set a breakpoint inside the DLL. As long
32859 as the program is not run, the DLL is not loaded. This has the
32860 consequence that the DLL debugging information is also not loaded, so it is not
32861 possible to set a breakpoint in the DLL.
32863 @item Set a breakpoint inside the DLL
32866 (gdb) break ada_dll
32873 At this stage a breakpoint is set inside the DLL. From there on
32874 you can use the standard approach to debug the whole program
32875 (@pxref{Running and Debugging Ada Programs}).
32878 @c This used to work, probably because the DLLs were non-relocatable
32879 @c keep this section around until the problem is sorted out.
32881 To break on the @code{DllMain} routine it is not possible to follow
32882 the procedure above. At the time the program stop on @code{ada_main}
32883 the @code{DllMain} routine as already been called. Either you can use
32884 the procedure below @pxref{Debugging the DLL Directly} or this procedure:
32887 @item Launch @code{GDB} on the main program.
32893 @item Load DLL symbols
32896 (gdb) add-sym api.dll
32899 @item Set a breakpoint inside the DLL
32902 (gdb) break ada_dll.adb:45
32905 Note that at this point it is not possible to break using the routine symbol
32906 directly as the program is not yet running. The solution is to break
32907 on the proper line (break in @file{ada_dll.adb} line 45).
32909 @item Start the program
32918 @node Program Built with Foreign Tools and DLL Built with GCC/GNAT
32919 @subsection Program Built with Foreign Tools and DLL Built with GCC/GNAT
32922 * Debugging the DLL Directly::
32923 * Attaching to a Running Process::
32927 In this case things are slightly more complex because it is not possible to
32928 start the main program and then break at the beginning to load the DLL and the
32929 associated DLL debugging information. It is not possible to break at the
32930 beginning of the program because there is no @code{GDB} debugging information,
32931 and therefore there is no direct way of getting initial control. This
32932 section addresses this issue by describing some methods that can be used
32933 to break somewhere in the DLL to debug it.
32936 First suppose that the main procedure is named @code{main} (this is for
32937 example some C code built with Microsoft Visual C) and that there is a
32938 DLL named @code{test.dll} containing an Ada entry point named
32942 The DLL (@pxref{Introduction to Dynamic Link Libraries (DLLs)}) must have
32943 been built with debugging information (see GNAT -g option).
32945 @node Debugging the DLL Directly
32946 @subsubsection Debugging the DLL Directly
32950 Find out the executable starting address
32953 $ objdump --file-header main.exe
32956 The starting address is reported on the last line. For example:
32959 main.exe: file format pei-i386
32960 architecture: i386, flags 0x0000010a:
32961 EXEC_P, HAS_DEBUG, D_PAGED
32962 start address 0x00401010
32966 Launch the debugger on the executable.
32973 Set a breakpoint at the starting address, and launch the program.
32976 $ (gdb) break *0x00401010
32980 The program will stop at the given address.
32983 Set a breakpoint on a DLL subroutine.
32986 (gdb) break ada_dll.adb:45
32989 Or if you want to break using a symbol on the DLL, you need first to
32990 select the Ada language (language used by the DLL).
32993 (gdb) set language ada
32994 (gdb) break ada_dll
32998 Continue the program.
33005 This will run the program until it reaches the breakpoint that has been
33006 set. From that point you can use the standard way to debug a program
33007 as described in (@pxref{Running and Debugging Ada Programs}).
33012 It is also possible to debug the DLL by attaching to a running process.
33014 @node Attaching to a Running Process
33015 @subsubsection Attaching to a Running Process
33016 @cindex DLL debugging, attach to process
33019 With @code{GDB} it is always possible to debug a running process by
33020 attaching to it. It is possible to debug a DLL this way. The limitation
33021 of this approach is that the DLL must run long enough to perform the
33022 attach operation. It may be useful for instance to insert a time wasting
33023 loop in the code of the DLL to meet this criterion.
33027 @item Launch the main program @file{main.exe}.
33033 @item Use the Windows @i{Task Manager} to find the process ID. Let's say
33034 that the process PID for @file{main.exe} is 208.
33042 @item Attach to the running process to be debugged.
33048 @item Load the process debugging information.
33051 (gdb) symbol-file main.exe
33054 @item Break somewhere in the DLL.
33057 (gdb) break ada_dll
33060 @item Continue process execution.
33069 This last step will resume the process execution, and stop at
33070 the breakpoint we have set. From there you can use the standard
33071 approach to debug a program as described in
33072 (@pxref{Running and Debugging Ada Programs}).
33074 @node Setting Stack Size from gnatlink
33075 @section Setting Stack Size from @command{gnatlink}
33078 It is possible to specify the program stack size at link time. On modern
33079 versions of Windows, starting with XP, this is mostly useful to set the size of
33080 the main stack (environment task). The other task stacks are set with pragma
33081 Storage_Size or with the @command{gnatbind -d} command.
33083 Since older versions of Windows (2000, NT4, etc.) do not allow setting the
33084 reserve size of individual tasks, the link-time stack size applies to all
33085 tasks, and pragma Storage_Size has no effect.
33086 In particular, Stack Overflow checks are made against this
33087 link-time specified size.
33089 This setting can be done with
33090 @command{gnatlink} using either:
33094 @item using @option{-Xlinker} linker option
33097 $ gnatlink hello -Xlinker --stack=0x10000,0x1000
33100 This sets the stack reserve size to 0x10000 bytes and the stack commit
33101 size to 0x1000 bytes.
33103 @item using @option{-Wl} linker option
33106 $ gnatlink hello -Wl,--stack=0x1000000
33109 This sets the stack reserve size to 0x1000000 bytes. Note that with
33110 @option{-Wl} option it is not possible to set the stack commit size
33111 because the coma is a separator for this option.
33115 @node Setting Heap Size from gnatlink
33116 @section Setting Heap Size from @command{gnatlink}
33119 Under Windows systems, it is possible to specify the program heap size from
33120 @command{gnatlink} using either:
33124 @item using @option{-Xlinker} linker option
33127 $ gnatlink hello -Xlinker --heap=0x10000,0x1000
33130 This sets the heap reserve size to 0x10000 bytes and the heap commit
33131 size to 0x1000 bytes.
33133 @item using @option{-Wl} linker option
33136 $ gnatlink hello -Wl,--heap=0x1000000
33139 This sets the heap reserve size to 0x1000000 bytes. Note that with
33140 @option{-Wl} option it is not possible to set the heap commit size
33141 because the coma is a separator for this option.
33147 @c **********************************
33148 @c * GNU Free Documentation License *
33149 @c **********************************
33151 @c GNU Free Documentation License
33153 @node Index,,GNU Free Documentation License, Top
33159 @c Put table of contents at end, otherwise it precedes the "title page" in
33160 @c the .txt version
33161 @c Edit the pdf file to move the contents to the beginning, after the title