]>
Commit | Line | Data |
---|---|---|
3bb3f6d6 | 1 | \input texinfo @c -*-texinfo-*- |
88e1739c | 2 | @c %**start of header |
70b1e376 | 3 | |
88e1739c FW |
4 | @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo |
5 | @c o | |
6 | @c GNAT DOCUMENTATION o | |
7 | @c o | |
7cd4527e | 8 | @c G N A T _ U G N o |
88e1739c | 9 | @c o |
98db73df | 10 | @c Copyright (C) 1992-2014, Free Software Foundation, Inc. o |
88e1739c | 11 | @c o |
88e1739c FW |
12 | @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo |
13 | ||
70b1e376 RW |
14 | @setfilename gnat_ugn.info |
15 | ||
16 | @copying | |
98db73df | 17 | Copyright @copyright{} 1995-2014 Free Software Foundation, |
70b1e376 RW |
18 | Inc. |
19 | ||
20 | Permission is granted to copy, distribute and/or modify this document | |
0f398cb4 | 21 | under the terms of the GNU Free Documentation License, Version 1.3 or |
70b1e376 RW |
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''. | |
26 | @end copying | |
27 | ||
88e1739c FW |
28 | @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo |
29 | @c | |
7cd4527e | 30 | @c GNAT_UGN Style Guide |
88e1739c FW |
31 | @c |
32 | @c 1. Always put a @noindent on the line before the first paragraph | |
33 | @c after any of these commands: | |
34 | @c | |
35 | @c @chapter | |
36 | @c @section | |
37 | @c @subsection | |
38 | @c @subsubsection | |
39 | @c @subsubsubsection | |
40 | @c | |
41 | @c @end smallexample | |
42 | @c @end itemize | |
43 | @c @end enumerate | |
44 | @c | |
45 | @c 2. DO NOT use @example. Use @smallexample instead. | |
7cd4527e AC |
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 | |
88e1739c FW |
60 | @c |
61 | @c 3. Each @chapter, @section, @subsection, @subsubsection, etc. | |
62 | @c command must be preceded by two empty lines | |
63 | @c | |
7cd4527e | 64 | @c 4. The @item command should be on a line of its own if it is in an |
88e1739c FW |
65 | @c @itemize or @enumerate command. |
66 | @c | |
67 | @c 5. When talking about ALI files use "ALI" (all uppercase), not "Ali" | |
68 | @c or "ali". | |
69 | @c | |
7cd4527e AC |
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. | |
72 | @c | |
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. | |
76 | @c | |
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 | |
79 | @c Windows. | |
80 | @c | |
88e1739c FW |
81 | @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo |
82 | ||
e08b38f5 VC |
83 | @set NOW January 2007 |
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}. | |
88e1739c | 89 | |
5d09245e AC |
90 | @set FSFEDITION |
91 | @set EDITION GNAT | |
92 | ||
93 | @ifset unw | |
87b3f81f | 94 | @set PLATFORM |
a1e16658 | 95 | @set TITLESUFFIX |
5d09245e AC |
96 | @end ifset |
97 | ||
7cd4527e | 98 | @ifset vms |
87b3f81f | 99 | @set PLATFORM OpenVMS |
a7942a0e | 100 | @set TITLESUFFIX for OpenVMS |
88e1739c FW |
101 | @end ifset |
102 | ||
66bfd481 RW |
103 | @c @ovar(ARG) |
104 | @c ---------- | |
105 | @c The ARG is an optional argument. To be used for macro arguments in | |
106 | @c their documentation (@defmac). | |
107 | @macro ovar{varname} | |
108 | @r{[}@var{\varname\}@r{]}@c | |
109 | @end macro | |
e074d476 AC |
110 | @c Status as of November 2009: |
111 | @c Unfortunately texi2pdf and texi2html treat the trailing "@c" | |
112 | @c differently, and faulty output is produced by one or the other | |
113 | @c depending on whether the "@c" is present or absent. | |
114 | @c As a result, the @ovar macro is not used, and all invocations | |
115 | @c of the @ovar macro have been expanded inline. | |
116 | ||
66bfd481 | 117 | |
a1e16658 | 118 | @settitle @value{EDITION} User's Guide @value{TITLESUFFIX} |
5d09245e | 119 | @dircategory GNU Ada tools |
6da7d579 | 120 | @direntry |
03e74118 | 121 | * @value{EDITION} User's Guide: (gnat_ugn). @value{PLATFORM} |
6da7d579 | 122 | @end direntry |
88e1739c | 123 | |
5321fb3e FW |
124 | @include gcc-common.texi |
125 | ||
88e1739c FW |
126 | @setchapternewpage odd |
127 | @syncodeindex fn cp | |
128 | @c %**end of header | |
129 | ||
130 | @titlepage | |
5d09245e | 131 | @title @value{EDITION} User's Guide |
e550819c AC |
132 | @ifset vms |
133 | @sp 1 | |
7cd4527e | 134 | @flushright |
5d09245e | 135 | @titlefont{@i{@value{PLATFORM}}} |
7cd4527e | 136 | @end flushright |
e550819c | 137 | @end ifset |
e08b38f5 VC |
138 | |
139 | @sp 2 | |
140 | ||
ec4e8e9a | 141 | @subtitle GNAT, The GNU Ada Development Environment |
7771bb62 | 142 | @versionsubtitle |
e08b38f5 VC |
143 | @author AdaCore |
144 | ||
88e1739c FW |
145 | @page |
146 | @vskip 0pt plus 1filll | |
147 | ||
bdefb2ab | 148 | @insertcopying |
88e1739c FW |
149 | |
150 | @end titlepage | |
151 | ||
6da7d579 | 152 | @ifnottex |
88e1739c | 153 | @node Top, About This Guide, (dir), (dir) |
5d09245e | 154 | @top @value{EDITION} User's Guide |
88e1739c | 155 | |
7cd4527e | 156 | @noindent |
87b3f81f | 157 | @value{EDITION} User's Guide @value{PLATFORM} |
88e1739c | 158 | |
7cd4527e | 159 | @noindent |
ec4e8e9a | 160 | GNAT, The GNU Ada Development Environment@* |
7cd4527e | 161 | GCC version @value{version-GCC}@* |
88e1739c | 162 | |
7cd4527e | 163 | @noindent |
87b3f81f | 164 | AdaCore@* |
88e1739c FW |
165 | |
166 | @menu | |
167 | * About This Guide:: | |
88e1739c FW |
168 | * Getting Started with GNAT:: |
169 | * The GNAT Compilation Model:: | |
c2658843 AC |
170 | * Compiling with gcc:: |
171 | * Binding with gnatbind:: | |
172 | * Linking with gnatlink:: | |
88e1739c | 173 | * The GNAT Make Program gnatmake:: |
7cd4527e | 174 | * Improving Performance:: |
c2658843 | 175 | * Renaming Files with gnatchop:: |
88e1739c | 176 | * Configuration Pragmas:: |
c2658843 | 177 | * Handling Arbitrary File Naming Conventions with gnatname:: |
88e1739c | 178 | * GNAT Project Manager:: |
b2cacbfe | 179 | * Tools Supporting Project Files:: |
88e1739c | 180 | * The Cross-Referencing Tools gnatxref and gnatfind:: |
1037b0f4 | 181 | @ifclear FSFEDITION |
7cd4527e | 182 | * The GNAT Pretty-Printer gnatpp:: |
c1645ac8 AC |
183 | @ifclear vms |
184 | * The Ada-to-XML converter gnat2xml:: | |
185 | @end ifclear | |
c2658843 | 186 | * The GNAT Metrics Tool gnatmetric:: |
1037b0f4 | 187 | @end ifclear |
c2658843 AC |
188 | * File Name Krunching with gnatkr:: |
189 | * Preprocessing with gnatprep:: | |
88e1739c | 190 | * The GNAT Library Browser gnatls:: |
c2658843 | 191 | * Cleaning Up with gnatclean:: |
88e1739c FW |
192 | @ifclear vms |
193 | * GNAT and Libraries:: | |
194 | * Using the GNU make Utility:: | |
88e1739c | 195 | @end ifclear |
f142e9fa | 196 | * Memory Management Issues:: |
7e3d710b | 197 | * Stack Related Facilities:: |
1037b0f4 | 198 | @ifclear FSFEDITION |
c2658843 AC |
199 | * Verifying Properties with gnatcheck:: |
200 | * Creating Sample Bodies with gnatstub:: | |
201 | * Creating Unit Tests with gnattest:: | |
1037b0f4 | 202 | @end ifclear |
5f44f0d4 | 203 | * Performing Dimensionality Analysis in GNAT:: |
c5d91669 | 204 | * Generating Ada Bindings for C and C++ headers:: |
88e1739c | 205 | * Other Utility Programs:: |
da508766 RD |
206 | @ifclear vms |
207 | * Code Coverage and Profiling:: | |
208 | @end ifclear | |
fce68ebe | 209 | * Running and Debugging Ada Programs:: |
88e1739c | 210 | @ifset vms |
32e209e4 | 211 | * Compatibility with HP Ada:: |
88e1739c | 212 | @end ifset |
7cd4527e AC |
213 | * Platform-Specific Information for the Run-Time Libraries:: |
214 | * Example of Binder Output File:: | |
215 | * Elaboration Order Handling in GNAT:: | |
6e6636ec | 216 | * Overflow Check Handling in GNAT:: |
c690a2ec | 217 | * Conditional Compilation:: |
88e1739c | 218 | * Inline Assembler:: |
7cd4527e | 219 | * Compatibility and Porting Guide:: |
88e1739c | 220 | * Microsoft Windows Topics:: |
2a328c94 | 221 | * Mac OS Topics:: |
88e1739c FW |
222 | * GNU Free Documentation License:: |
223 | * Index:: | |
88e1739c | 224 | @end menu |
6da7d579 | 225 | @end ifnottex |
88e1739c FW |
226 | |
227 | @node About This Guide | |
228 | @unnumbered About This Guide | |
229 | ||
230 | @noindent | |
231 | @ifset vms | |
87b3f81f | 232 | This guide describes the use of @value{EDITION}, |
e08b38f5 VC |
233 | a compiler and software development toolset for the full Ada |
234 | programming language, implemented on OpenVMS for HP's Alpha and | |
7e3d710b | 235 | Integrity server (I64) platforms. |
88e1739c FW |
236 | @end ifset |
237 | @ifclear vms | |
5d09245e AC |
238 | This guide describes the use of @value{EDITION}, |
239 | a compiler and software development | |
e08b38f5 | 240 | toolset for the full Ada programming language. |
88e1739c | 241 | @end ifclear |
e08b38f5 VC |
242 | It documents the features of the compiler and tools, and explains |
243 | how to use them to build Ada applications. | |
244 | ||
49eef89f AC |
245 | @value{EDITION} implements Ada 95, Ada 2005 and Ada 2012, and it may also be |
246 | invoked in Ada 83 compatibility mode. | |
247 | By default, @value{EDITION} assumes Ada 2012, but you can override with a | |
248 | compiler switch (@pxref{Compiling Different Versions of Ada}) | |
e08b38f5 VC |
249 | to explicitly specify the language version. |
250 | Throughout this manual, references to ``Ada'' without a year suffix | |
f0e7963f | 251 | apply to all Ada 95/2005/2012 versions of the language. |
e08b38f5 VC |
252 | |
253 | @ifclear FSFEDITION | |
254 | For ease of exposition, ``@value{EDITION}'' will be referred to simply as | |
5d09245e | 255 | ``GNAT'' in the remainder of this document. |
e08b38f5 VC |
256 | @end ifclear |
257 | ||
258 | ||
88e1739c FW |
259 | @menu |
260 | * What This Guide Contains:: | |
261 | * What You Should Know before Reading This Guide:: | |
262 | * Related Information:: | |
263 | * Conventions:: | |
264 | @end menu | |
265 | ||
266 | @node What This Guide Contains | |
267 | @unnumberedsec What This Guide Contains | |
268 | ||
269 | @noindent | |
270 | This guide contains the following chapters: | |
271 | @itemize @bullet | |
7cd4527e | 272 | |
88e1739c FW |
273 | @item |
274 | @ref{Getting Started with GNAT}, describes how to get started compiling | |
275 | and running Ada programs with the GNAT Ada programming environment. | |
276 | @item | |
277 | @ref{The GNAT Compilation Model}, describes the compilation model used | |
278 | by GNAT. | |
7cd4527e | 279 | |
88e1739c | 280 | @item |
c2658843 | 281 | @ref{Compiling with gcc}, describes how to compile |
984a64bc | 282 | Ada programs with @command{gcc}, the Ada compiler. |
7cd4527e | 283 | |
88e1739c | 284 | @item |
c2658843 | 285 | @ref{Binding with gnatbind}, describes how to |
88e1739c FW |
286 | perform binding of Ada programs with @code{gnatbind}, the GNAT binding |
287 | utility. | |
7cd4527e | 288 | |
88e1739c | 289 | @item |
c2658843 | 290 | @ref{Linking with gnatlink}, |
984a64bc | 291 | describes @command{gnatlink}, a |
88e1739c | 292 | program that provides for linking using the GNAT run-time library to |
984a64bc | 293 | construct a program. @command{gnatlink} can also incorporate foreign language |
88e1739c | 294 | object units into the executable. |
7cd4527e | 295 | |
88e1739c | 296 | @item |
984a64bc | 297 | @ref{The GNAT Make Program gnatmake}, describes @command{gnatmake}, a |
88e1739c FW |
298 | utility that automatically determines the set of sources |
299 | needed by an Ada compilation unit, and executes the necessary compilations | |
300 | binding and link. | |
7cd4527e AC |
301 | |
302 | @item | |
303 | @ref{Improving Performance}, shows various techniques for making your | |
1037b0f4 AC |
304 | Ada program run faster or take less space and describes the effect of |
305 | the compiler's optimization switch. | |
306 | It also describes | |
307 | @ifclear FSFEDITION | |
308 | the @command{gnatelim} tool and | |
309 | @end ifclear | |
310 | unused subprogram/data elimination. | |
7cd4527e | 311 | |
88e1739c | 312 | @item |
c2658843 | 313 | @ref{Renaming Files with gnatchop}, describes |
88e1739c FW |
314 | @code{gnatchop}, a utility that allows you to preprocess a file that |
315 | contains Ada source code, and split it into one or more new files, one | |
316 | for each compilation unit. | |
7cd4527e | 317 | |
88e1739c | 318 | @item |
7cd4527e AC |
319 | @ref{Configuration Pragmas}, describes the configuration pragmas |
320 | handled by GNAT. | |
321 | ||
88e1739c | 322 | @item |
c2658843 | 323 | @ref{Handling Arbitrary File Naming Conventions with gnatname}, |
7cd4527e AC |
324 | shows how to override the default GNAT file naming conventions, |
325 | either for an individual unit or globally. | |
326 | ||
88e1739c | 327 | @item |
7cd4527e AC |
328 | @ref{GNAT Project Manager}, describes how to use project files |
329 | to organize large projects. | |
330 | ||
88e1739c FW |
331 | @item |
332 | @ref{The Cross-Referencing Tools gnatxref and gnatfind}, discusses | |
333 | @code{gnatxref} and @code{gnatfind}, two tools that provide an easy | |
334 | way to navigate through sources. | |
7cd4527e | 335 | |
1037b0f4 | 336 | @ifclear FSFEDITION |
7cd4527e AC |
337 | @item |
338 | @ref{The GNAT Pretty-Printer gnatpp}, shows how to produce a reformatted | |
339 | version of an Ada source file with control over casing, indentation, | |
340 | comment placement, and other elements of program presentation style. | |
1037b0f4 | 341 | @end ifclear |
7cd4527e | 342 | |
1037b0f4 | 343 | @ifclear FSFEDITION |
c1645ac8 AC |
344 | @ifclear vms |
345 | @item | |
346 | @ref{The Ada-to-XML converter gnat2xml}, shows how to convert Ada | |
347 | source code into XML. | |
348 | @end ifclear | |
1037b0f4 | 349 | @end ifclear |
c1645ac8 | 350 | |
1037b0f4 | 351 | @ifclear FSFEDITION |
a5b62485 | 352 | @item |
c2658843 | 353 | @ref{The GNAT Metrics Tool gnatmetric}, shows how to compute various |
a5b62485 AC |
354 | metrics for an Ada source file, such as the number of types and subprograms, |
355 | and assorted complexity measures. | |
1037b0f4 | 356 | @end ifclear |
a5b62485 | 357 | |
88e1739c | 358 | @item |
c2658843 | 359 | @ref{File Name Krunching with gnatkr}, describes the @code{gnatkr} |
88e1739c FW |
360 | file name krunching utility, used to handle shortened |
361 | file names on operating systems with a limit on the length of names. | |
7cd4527e | 362 | |
88e1739c | 363 | @item |
c2658843 | 364 | @ref{Preprocessing with gnatprep}, describes @code{gnatprep}, a |
88e1739c | 365 | preprocessor utility that allows a single source file to be used to |
c690a2ec | 366 | generate multiple or parameterized source files by means of macro |
88e1739c | 367 | substitution. |
7cd4527e | 368 | |
88e1739c FW |
369 | @item |
370 | @ref{The GNAT Library Browser gnatls}, describes @code{gnatls}, a | |
371 | utility that displays information about compiled units, including dependences | |
372 | on the corresponding sources files, and consistency of compilations. | |
7cd4527e AC |
373 | |
374 | @item | |
c2658843 | 375 | @ref{Cleaning Up with gnatclean}, describes @code{gnatclean}, a utility |
7cd4527e AC |
376 | to delete files that are produced by the compiler, binder and linker. |
377 | ||
88e1739c FW |
378 | @ifclear vms |
379 | @item | |
380 | @ref{GNAT and Libraries}, describes the process of creating and using | |
381 | Libraries with GNAT. It also describes how to recompile the GNAT run-time | |
382 | library. | |
383 | ||
384 | @item | |
385 | @ref{Using the GNU make Utility}, describes some techniques for using | |
386 | the GNAT toolset in Makefiles. | |
7cd4527e | 387 | @end ifclear |
88e1739c | 388 | |
88e1739c | 389 | @item |
f142e9fa CC |
390 | @ref{Memory Management Issues}, describes some useful predefined storage pools |
391 | and in particular the GNAT Debug Pool facility, which helps detect incorrect | |
392 | memory references. | |
7cd4527e | 393 | @ifclear vms |
1037b0f4 | 394 | @ifclear FSFEDITION |
f142e9fa CC |
395 | It also describes @command{gnatmem}, a utility that monitors dynamic |
396 | allocation and deallocation and helps detect ``memory leaks''. | |
88e1739c | 397 | @end ifclear |
1037b0f4 | 398 | @end ifclear |
88e1739c | 399 | |
9c8457a7 | 400 | @item |
7e3d710b AC |
401 | @ref{Stack Related Facilities}, describes some useful tools associated with |
402 | stack checking and analysis. | |
403 | ||
1037b0f4 | 404 | @ifclear FSFEDITION |
7e3d710b | 405 | @item |
c2658843 | 406 | @ref{Verifying Properties with gnatcheck}, discusses @code{gnatcheck}, |
7e3d710b | 407 | a utility that checks Ada code against a set of rules. |
9c8457a7 | 408 | |
88e1739c | 409 | @item |
c2658843 | 410 | @ref{Creating Sample Bodies with gnatstub}, discusses @code{gnatstub}, |
88e1739c | 411 | a utility that generates empty but compilable bodies for library units. |
1037b0f4 | 412 | @end ifclear |
88e1739c | 413 | |
1037b0f4 | 414 | @ifclear FSFEDITION |
8417f4b2 | 415 | @item |
c2658843 | 416 | @ref{Creating Unit Tests with gnattest}, discusses @code{gnattest}, |
8417f4b2 | 417 | a utility that generates unit testing templates for library units. |
1037b0f4 | 418 | @end ifclear |
8417f4b2 | 419 | |
5f44f0d4 AC |
420 | @item |
421 | @ref{Performing Dimensionality Analysis in GNAT}, describes the Ada 2012 | |
422 | facilities used in GNAT to declare dimensioned objects, and to verify that | |
423 | uses of these objects are consistent with their given physical dimensions | |
424 | (so that meters cannot be assigned to kilograms, and so on). | |
425 | ||
c5d91669 AC |
426 | @item |
427 | @ref{Generating Ada Bindings for C and C++ headers}, describes how to | |
428 | generate automatically Ada bindings from C and C++ headers. | |
429 | ||
88e1739c FW |
430 | @item |
431 | @ref{Other Utility Programs}, discusses several other GNAT utilities, | |
7cd4527e | 432 | including @code{gnathtml}. |
88e1739c | 433 | |
da508766 RD |
434 | @ifclear vms |
435 | @item | |
436 | @ref{Code Coverage and Profiling}, describes how to perform a structural | |
437 | coverage and profile the execution of Ada programs. | |
438 | @end ifclear | |
439 | ||
88e1739c FW |
440 | @item |
441 | @ref{Running and Debugging Ada Programs}, describes how to run and debug | |
442 | Ada programs. | |
443 | ||
7cd4527e | 444 | @ifset vms |
88e1739c | 445 | @item |
32e209e4 CC |
446 | @ref{Compatibility with HP Ada}, details the compatibility of GNAT with |
447 | HP Ada 83 @footnote{``HP Ada'' refers to the legacy product originally | |
7cd4527e | 448 | developed by Digital Equipment Corporation and currently supported by HP.} |
7e3d710b AC |
449 | for OpenVMS Alpha. This product was formerly known as DEC Ada, |
450 | @cindex DEC Ada | |
451 | and for | |
32e209e4 CC |
452 | historical compatibility reasons, the relevant libraries still use the |
453 | DEC prefix. | |
7cd4527e | 454 | @end ifset |
88e1739c | 455 | |
88e1739c | 456 | @item |
7cd4527e AC |
457 | @ref{Platform-Specific Information for the Run-Time Libraries}, |
458 | describes the various run-time | |
459 | libraries supported by GNAT on various platforms and explains how to | |
460 | choose a particular library. | |
88e1739c FW |
461 | |
462 | @item | |
7cd4527e AC |
463 | @ref{Example of Binder Output File}, shows the source code for the binder |
464 | output file for a sample program. | |
88e1739c FW |
465 | |
466 | @item | |
7cd4527e AC |
467 | @ref{Elaboration Order Handling in GNAT}, describes how GNAT helps |
468 | you deal with elaboration order issues. | |
469 | ||
6e6636ec RD |
470 | @item |
471 | @ref{Overflow Check Handling in GNAT}, describes how GNAT helps | |
472 | you deal with arithmetic overflow issues. | |
473 | ||
c690a2ec RD |
474 | @item |
475 | @ref{Conditional Compilation}, describes how to model conditional compilation, | |
476 | both with Ada in general and with GNAT facilities in particular. | |
477 | ||
88e1739c | 478 | @item |
7cd4527e AC |
479 | @ref{Inline Assembler}, shows how to use the inline assembly facility |
480 | in an Ada program. | |
481 | ||
482 | @item | |
e08b38f5 VC |
483 | @ref{Compatibility and Porting Guide}, contains sections on compatibility |
484 | of GNAT with other Ada development environments (including Ada 83 systems), | |
485 | to assist in porting code from those environments. | |
7cd4527e AC |
486 | |
487 | @ifset unw | |
488 | @item | |
489 | @ref{Microsoft Windows Topics}, presents information relevant to the | |
490 | Microsoft Windows platform. | |
2a328c94 AC |
491 | |
492 | @item | |
493 | @ref{Mac OS Topics}, presents information relevant to Apple's OS X | |
494 | platform. | |
88e1739c FW |
495 | @end ifset |
496 | @end itemize | |
497 | ||
7cd4527e | 498 | @c ************************************************* |
88e1739c | 499 | @node What You Should Know before Reading This Guide |
7cd4527e | 500 | @c ************************************************* |
88e1739c FW |
501 | @unnumberedsec What You Should Know before Reading This Guide |
502 | ||
503 | @cindex Ada 95 Language Reference Manual | |
e08b38f5 | 504 | @cindex Ada 2005 Language Reference Manual |
88e1739c | 505 | @noindent |
e08b38f5 | 506 | This guide assumes a basic familiarity with the Ada 95 language, as |
7cd4527e | 507 | described in the International Standard ANSI/ISO/IEC-8652:1995, January |
88e1739c | 508 | 1995. |
e08b38f5 VC |
509 | It does not require knowledge of the new features introduced by Ada 2005, |
510 | (officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1 | |
511 | and Amendment 1). | |
512 | Both reference manuals are included in the GNAT documentation | |
513 | package. | |
88e1739c FW |
514 | |
515 | @node Related Information | |
516 | @unnumberedsec Related Information | |
517 | ||
518 | @noindent | |
519 | For further information about related tools, refer to the following | |
520 | documents: | |
521 | ||
522 | @itemize @bullet | |
523 | @item | |
b2e74434 RW |
524 | @xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT |
525 | Reference Manual}, which contains all reference material for the GNAT | |
526 | implementation of Ada. | |
88e1739c | 527 | |
7cd4527e AC |
528 | @ifset unw |
529 | @item | |
e08b38f5 VC |
530 | @cite{Using the GNAT Programming Studio}, which describes the GPS |
531 | Integrated Development Environment. | |
7cd4527e AC |
532 | |
533 | @item | |
e08b38f5 | 534 | @cite{GNAT Programming Studio Tutorial}, which introduces the |
7cd4527e AC |
535 | main GPS features through examples. |
536 | @end ifset | |
537 | ||
88e1739c | 538 | @item |
e08b38f5 | 539 | @cite{Ada 95 Reference Manual}, which contains reference |
88e1739c FW |
540 | material for the Ada 95 programming language. |
541 | ||
e08b38f5 VC |
542 | @item |
543 | @cite{Ada 2005 Reference Manual}, which contains reference | |
544 | material for the Ada 2005 programming language. | |
545 | ||
88e1739c | 546 | @item |
b2e74434 | 547 | @xref{Top,, Debugging with GDB, gdb, Debugging with GDB}, |
88e1739c | 548 | @ifset vms |
b2e74434 | 549 | in the GNU:[DOCS] directory, |
88e1739c | 550 | @end ifset |
b2e74434 | 551 | for all details on the use of the GNU source-level debugger. |
88e1739c FW |
552 | |
553 | @item | |
b2e74434 RW |
554 | @xref{Top,, The extensible self-documenting text editor, emacs, |
555 | GNU Emacs Manual}, | |
88e1739c | 556 | @ifset vms |
b2e74434 | 557 | located in the GNU:[DOCS] directory if the EMACS kit is installed, |
88e1739c | 558 | @end ifset |
b2e74434 | 559 | for full information on the extensible editor and programming |
88e1739c FW |
560 | environment Emacs. |
561 | ||
562 | @end itemize | |
563 | ||
7cd4527e | 564 | @c ************** |
88e1739c FW |
565 | @node Conventions |
566 | @unnumberedsec Conventions | |
567 | @cindex Conventions | |
568 | @cindex Typographical conventions | |
569 | ||
570 | @noindent | |
571 | Following are examples of the typographical and graphic conventions used | |
572 | in this guide: | |
573 | ||
574 | @itemize @bullet | |
575 | @item | |
443b3472 | 576 | @code{Functions}, @command{utility program names}, @code{standard names}, |
88e1739c FW |
577 | and @code{classes}. |
578 | ||
579 | @item | |
443b3472 | 580 | @option{Option flags} |
88e1739c FW |
581 | |
582 | @item | |
443b3472 | 583 | @file{File names}, @samp{button names}, and @samp{field names}. |
88e1739c FW |
584 | |
585 | @item | |
443b3472 RW |
586 | @code{Variables}, @env{environment variables}, and @var{metasyntactic |
587 | variables}. | |
88e1739c FW |
588 | |
589 | @item | |
590 | @emph{Emphasis}. | |
591 | ||
592 | @item | |
66bfd481 | 593 | @r{[}optional information or parameters@r{]} |
88e1739c FW |
594 | |
595 | @item | |
596 | Examples are described by text | |
597 | @smallexample | |
598 | and then shown this way. | |
599 | @end smallexample | |
600 | @end itemize | |
601 | ||
602 | @noindent | |
603 | Commands that are entered by the user are preceded in this manual by the | |
7cd4527e | 604 | characters @w{``@code{$ }''} (dollar sign followed by space). If your system |
88e1739c FW |
605 | uses this sequence as a prompt, then the commands will appear exactly as |
606 | you see them in the manual. If your system uses some other prompt, then | |
607 | the command will appear with the @code{$} replaced by whatever prompt | |
608 | character you are using. | |
609 | ||
7cd4527e AC |
610 | @ifset unw |
611 | Full file names are shown with the ``@code{/}'' character | |
612 | as the directory separator; e.g., @file{parent-dir/subdir/myfile.adb}. | |
613 | If you are using GNAT on a Windows platform, please note that | |
614 | the ``@code{\}'' character should be used instead. | |
88e1739c FW |
615 | @end ifset |
616 | ||
7cd4527e | 617 | @c **************************** |
88e1739c FW |
618 | @node Getting Started with GNAT |
619 | @chapter Getting Started with GNAT | |
620 | ||
88e1739c FW |
621 | @noindent |
622 | This chapter describes some simple ways of using GNAT to build | |
623 | executable Ada programs. | |
7cd4527e AC |
624 | @ifset unw |
625 | @ref{Running GNAT}, through @ref{Using the gnatmake Utility}, | |
626 | show how to use the command line environment. | |
e08b38f5 VC |
627 | @ref{Introduction to GPS}, provides a brief |
628 | introduction to the GNAT Programming Studio, a visually-oriented | |
629 | Integrated Development Environment for GNAT. | |
630 | GPS offers a graphical ``look and feel'', support for development in | |
631 | other programming languages, comprehensive browsing features, and | |
632 | many other capabilities. | |
7cd4527e | 633 | For information on GPS please refer to |
e08b38f5 | 634 | @cite{Using the GNAT Programming Studio}. |
88e1739c FW |
635 | @end ifset |
636 | ||
637 | @menu | |
638 | * Running GNAT:: | |
88e1739c | 639 | * Running a Simple Ada Program:: |
88e1739c | 640 | * Running a Program with Multiple Units:: |
88e1739c FW |
641 | * Using the gnatmake Utility:: |
642 | @ifset vms | |
643 | * Editing with Emacs:: | |
644 | @end ifset | |
645 | @ifclear vms | |
7cd4527e | 646 | * Introduction to GPS:: |
88e1739c FW |
647 | @end ifclear |
648 | @end menu | |
649 | ||
650 | @node Running GNAT | |
651 | @section Running GNAT | |
652 | ||
653 | @noindent | |
654 | Three steps are needed to create an executable file from an Ada source | |
655 | file: | |
656 | ||
657 | @enumerate | |
658 | @item | |
659 | The source file(s) must be compiled. | |
660 | @item | |
661 | The file(s) must be bound using the GNAT binder. | |
662 | @item | |
88e1739c | 663 | All appropriate object files must be linked to produce an executable. |
88e1739c FW |
664 | @end enumerate |
665 | ||
666 | @noindent | |
984a64bc | 667 | All three steps are most commonly handled by using the @command{gnatmake} |
88e1739c FW |
668 | utility program that, given the name of the main program, automatically |
669 | performs the necessary compilation, binding and linking steps. | |
670 | ||
88e1739c FW |
671 | @node Running a Simple Ada Program |
672 | @section Running a Simple Ada Program | |
88e1739c FW |
673 | |
674 | @noindent | |
7cd4527e | 675 | Any text editor may be used to prepare an Ada program. |
e08b38f5 VC |
676 | (If @code{Emacs} is |
677 | used, the optional Ada mode may be helpful in laying out the program.) | |
7cd4527e | 678 | The |
e08b38f5 | 679 | program text is a normal text file. We will assume in our initial |
88e1739c FW |
680 | example that you have used your editor to prepare the following |
681 | standard format text file: | |
682 | ||
7cd4527e | 683 | @smallexample @c ada |
88e1739c | 684 | @cartouche |
7cd4527e AC |
685 | with Ada.Text_IO; use Ada.Text_IO; |
686 | procedure Hello is | |
687 | begin | |
88e1739c | 688 | Put_Line ("Hello WORLD!"); |
7cd4527e | 689 | end Hello; |
88e1739c | 690 | @end cartouche |
88e1739c FW |
691 | @end smallexample |
692 | ||
693 | @noindent | |
694 | This file should be named @file{hello.adb}. | |
695 | With the normal default file naming conventions, GNAT requires | |
696 | that each file | |
697 | contain a single compilation unit whose file name is the | |
698 | unit name, | |
699 | with periods replaced by hyphens; the | |
700 | extension is @file{ads} for a | |
701 | spec and @file{adb} for a body. | |
702 | You can override this default file naming convention by use of the | |
703 | special pragma @code{Source_File_Name} (@pxref{Using Other File Names}). | |
704 | Alternatively, if you want to rename your files according to this default | |
705 | convention, which is probably more convenient if you will be using GNAT | |
706 | for all your compilations, then the @code{gnatchop} utility | |
707 | can be used to generate correctly-named source files | |
c2658843 | 708 | (@pxref{Renaming Files with gnatchop}). |
88e1739c FW |
709 | |
710 | You can compile the program using the following command (@code{$} is used | |
711 | as the command prompt in the examples in this document): | |
712 | ||
88e1739c FW |
713 | @smallexample |
714 | $ gcc -c hello.adb | |
715 | @end smallexample | |
88e1739c FW |
716 | |
717 | @noindent | |
984a64bc | 718 | @command{gcc} is the command used to run the compiler. This compiler is |
e08b38f5 | 719 | capable of compiling programs in several languages, including Ada and |
88e1739c | 720 | C. It assumes that you have given it an Ada program if the file extension is |
7cd4527e AC |
721 | either @file{.ads} or @file{.adb}, and it will then call |
722 | the GNAT compiler to compile the specified file. | |
88e1739c FW |
723 | |
724 | @ifclear vms | |
725 | The @option{-c} switch is required. It tells @command{gcc} to only do a | |
726 | compilation. (For C programs, @command{gcc} can also do linking, but this | |
727 | capability is not used directly for Ada programs, so the @option{-c} | |
728 | switch must always be present.) | |
729 | @end ifclear | |
730 | ||
731 | This compile command generates a file | |
732 | @file{hello.o}, which is the object | |
7cd4527e AC |
733 | file corresponding to your Ada program. It also generates |
734 | an ``Ada Library Information'' file @file{hello.ali}, | |
88e1739c FW |
735 | which contains additional information used to check |
736 | that an Ada program is consistent. | |
88e1739c | 737 | To build an executable file, |
88e1739c | 738 | use @code{gnatbind} to bind the program |
984a64bc AC |
739 | and @command{gnatlink} to link it. The |
740 | argument to both @code{gnatbind} and @command{gnatlink} is the name of the | |
7cd4527e | 741 | @file{ALI} file, but the default extension of @file{.ali} can |
88e1739c FW |
742 | be omitted. This means that in the most common case, the argument |
743 | is simply the name of the main program: | |
744 | ||
88e1739c FW |
745 | @smallexample |
746 | $ gnatbind hello | |
747 | $ gnatlink hello | |
748 | @end smallexample | |
88e1739c FW |
749 | |
750 | @noindent | |
751 | A simpler method of carrying out these steps is to use | |
752 | @command{gnatmake}, | |
753 | a master program that invokes all the required | |
754 | compilation, binding and linking tools in the correct order. In particular, | |
7cd4527e AC |
755 | @command{gnatmake} automatically recompiles any sources that have been |
756 | modified since they were last compiled, or sources that depend | |
757 | on such modified sources, so that ``version skew'' is avoided. | |
88e1739c FW |
758 | @cindex Version skew (avoided by @command{gnatmake}) |
759 | ||
88e1739c FW |
760 | @smallexample |
761 | $ gnatmake hello.adb | |
762 | @end smallexample | |
88e1739c | 763 | |
88e1739c FW |
764 | @noindent |
765 | The result is an executable program called @file{hello}, which can be | |
766 | run by entering: | |
767 | ||
88e1739c | 768 | @smallexample |
0453ca3d | 769 | $ ^hello^RUN HELLO^ |
88e1739c FW |
770 | @end smallexample |
771 | ||
772 | @noindent | |
7cd4527e AC |
773 | assuming that the current directory is on the search path |
774 | for executable programs. | |
88e1739c FW |
775 | |
776 | @noindent | |
777 | and, if all has gone well, you will see | |
778 | ||
779 | @smallexample | |
780 | Hello WORLD! | |
781 | @end smallexample | |
782 | ||
783 | @noindent | |
784 | appear in response to this command. | |
785 | ||
7cd4527e | 786 | @c **************************************** |
88e1739c FW |
787 | @node Running a Program with Multiple Units |
788 | @section Running a Program with Multiple Units | |
789 | ||
790 | @noindent | |
791 | Consider a slightly more complicated example that has three files: a | |
792 | main program, and the spec and body of a package: | |
793 | ||
7cd4527e | 794 | @smallexample @c ada |
88e1739c FW |
795 | @cartouche |
796 | @group | |
7cd4527e AC |
797 | package Greetings is |
798 | procedure Hello; | |
799 | procedure Goodbye; | |
800 | end Greetings; | |
801 | ||
802 | with Ada.Text_IO; use Ada.Text_IO; | |
803 | package body Greetings is | |
804 | procedure Hello is | |
805 | begin | |
88e1739c | 806 | Put_Line ("Hello WORLD!"); |
7cd4527e | 807 | end Hello; |
88e1739c | 808 | |
7cd4527e AC |
809 | procedure Goodbye is |
810 | begin | |
88e1739c | 811 | Put_Line ("Goodbye WORLD!"); |
7cd4527e AC |
812 | end Goodbye; |
813 | end Greetings; | |
88e1739c FW |
814 | @end group |
815 | ||
816 | @group | |
7cd4527e AC |
817 | with Greetings; |
818 | procedure Gmain is | |
819 | begin | |
88e1739c FW |
820 | Greetings.Hello; |
821 | Greetings.Goodbye; | |
7cd4527e | 822 | end Gmain; |
88e1739c FW |
823 | @end group |
824 | @end cartouche | |
825 | @end smallexample | |
826 | ||
827 | @noindent | |
828 | Following the one-unit-per-file rule, place this program in the | |
829 | following three separate files: | |
830 | ||
831 | @table @file | |
832 | @item greetings.ads | |
833 | spec of package @code{Greetings} | |
834 | ||
835 | @item greetings.adb | |
836 | body of package @code{Greetings} | |
837 | ||
838 | @item gmain.adb | |
839 | body of main program | |
840 | @end table | |
841 | ||
842 | @noindent | |
843 | To build an executable version of | |
844 | this program, we could use four separate steps to compile, bind, and link | |
845 | the program, as follows: | |
846 | ||
88e1739c FW |
847 | @smallexample |
848 | $ gcc -c gmain.adb | |
849 | $ gcc -c greetings.adb | |
850 | $ gnatbind gmain | |
851 | $ gnatlink gmain | |
852 | @end smallexample | |
88e1739c FW |
853 | |
854 | @noindent | |
855 | Note that there is no required order of compilation when using GNAT. | |
856 | In particular it is perfectly fine to compile the main program first. | |
857 | Also, it is not necessary to compile package specs in the case where | |
858 | there is an accompanying body; you only need to compile the body. If you want | |
7cd4527e AC |
859 | to submit these files to the compiler for semantic checking and not code |
860 | generation, then use the | |
88e1739c FW |
861 | @option{-gnatc} switch: |
862 | ||
88e1739c | 863 | @smallexample |
7cd4527e | 864 | $ gcc -c greetings.ads -gnatc |
88e1739c | 865 | @end smallexample |
88e1739c FW |
866 | |
867 | @noindent | |
868 | Although the compilation can be done in separate steps as in the | |
869 | above example, in practice it is almost always more convenient | |
984a64bc | 870 | to use the @command{gnatmake} tool. All you need to know in this case |
88e1739c FW |
871 | is the name of the main program's source file. The effect of the above four |
872 | commands can be achieved with a single one: | |
873 | ||
88e1739c FW |
874 | @smallexample |
875 | $ gnatmake gmain.adb | |
876 | @end smallexample | |
88e1739c FW |
877 | |
878 | @noindent | |
984a64bc | 879 | In the next section we discuss the advantages of using @command{gnatmake} in |
88e1739c FW |
880 | more detail. |
881 | ||
7cd4527e | 882 | @c ***************************** |
88e1739c FW |
883 | @node Using the gnatmake Utility |
884 | @section Using the @command{gnatmake} Utility | |
885 | ||
886 | @noindent | |
887 | If you work on a program by compiling single components at a time using | |
984a64bc | 888 | @command{gcc}, you typically keep track of the units you modify. In order to |
88e1739c FW |
889 | build a consistent system, you compile not only these units, but also any |
890 | units that depend on the units you have modified. | |
891 | For example, in the preceding case, | |
892 | if you edit @file{gmain.adb}, you only need to recompile that file. But if | |
893 | you edit @file{greetings.ads}, you must recompile both | |
894 | @file{greetings.adb} and @file{gmain.adb}, because both files contain | |
895 | units that depend on @file{greetings.ads}. | |
896 | ||
897 | @code{gnatbind} will warn you if you forget one of these compilation | |
898 | steps, so that it is impossible to generate an inconsistent program as a | |
899 | result of forgetting to do a compilation. Nevertheless it is tedious and | |
900 | error-prone to keep track of dependencies among units. | |
901 | One approach to handle the dependency-bookkeeping is to use a | |
902 | makefile. However, makefiles present maintenance problems of their own: | |
903 | if the dependencies change as you change the program, you must make | |
904 | sure that the makefile is kept up-to-date manually, which is also an | |
905 | error-prone process. | |
906 | ||
984a64bc | 907 | The @command{gnatmake} utility takes care of these details automatically. |
88e1739c FW |
908 | Invoke it using either one of the following forms: |
909 | ||
88e1739c FW |
910 | @smallexample |
911 | $ gnatmake gmain.adb | |
912 | $ gnatmake ^gmain^GMAIN^ | |
913 | @end smallexample | |
88e1739c FW |
914 | |
915 | @noindent | |
916 | The argument is the name of the file containing the main program; | |
984a64bc | 917 | you may omit the extension. @command{gnatmake} |
88e1739c FW |
918 | examines the environment, automatically recompiles any files that need |
919 | recompiling, and binds and links the resulting set of object files, | |
920 | generating the executable file, @file{^gmain^GMAIN.EXE^}. | |
921 | In a large program, it | |
984a64bc | 922 | can be extremely helpful to use @command{gnatmake}, because working out by hand |
88e1739c FW |
923 | what needs to be recompiled can be difficult. |
924 | ||
984a64bc | 925 | Note that @command{gnatmake} |
e08b38f5 | 926 | takes into account all the Ada rules that |
88e1739c FW |
927 | establish dependencies among units. These include dependencies that result |
928 | from inlining subprogram bodies, and from | |
929 | generic instantiation. Unlike some other | |
984a64bc | 930 | Ada make tools, @command{gnatmake} does not rely on the dependencies that were |
88e1739c | 931 | found by the compiler on a previous compilation, which may possibly |
984a64bc | 932 | be wrong when sources change. @command{gnatmake} determines the exact set of |
88e1739c FW |
933 | dependencies from scratch each time it is run. |
934 | ||
935 | @ifset vms | |
936 | @node Editing with Emacs | |
937 | @section Editing with Emacs | |
938 | @cindex Emacs | |
939 | ||
940 | @noindent | |
941 | Emacs is an extensible self-documenting text editor that is available in a | |
942 | separate VMSINSTAL kit. | |
943 | ||
7cd4527e | 944 | Invoke Emacs by typing @kbd{Emacs} at the command prompt. To get started, |
88e1739c | 945 | click on the Emacs Help menu and run the Emacs Tutorial. |
7cd4527e AC |
946 | In a character cell terminal, Emacs help is invoked with @kbd{Ctrl-h} (also |
947 | written as @kbd{C-h}), and the tutorial by @kbd{C-h t}. | |
88e1739c FW |
948 | |
949 | Documentation on Emacs and other tools is available in Emacs under the | |
7cd4527e | 950 | pull-down menu button: @code{Help - Info}. After selecting @code{Info}, |
8dd07840 | 951 | use the middle mouse button to select a topic (e.g.@: Emacs). |
88e1739c | 952 | |
7cd4527e AC |
953 | In a character cell terminal, do @kbd{C-h i} to invoke info, and then @kbd{m} |
954 | (stands for menu) followed by the menu item desired, as in @kbd{m Emacs}, to | |
955 | get to the Emacs manual. | |
956 | Help on Emacs is also available by typing @kbd{HELP EMACS} at the DCL command | |
88e1739c FW |
957 | prompt. |
958 | ||
959 | The tutorial is highly recommended in order to learn the intricacies of Emacs, | |
960 | which is sufficiently extensible to provide for a complete programming | |
961 | environment and shell for the sophisticated user. | |
962 | @end ifset | |
963 | ||
964 | @ifclear vms | |
7cd4527e AC |
965 | @node Introduction to GPS |
966 | @section Introduction to GPS | |
e08b38f5 VC |
967 | @cindex GPS (GNAT Programming Studio) |
968 | @cindex GNAT Programming Studio (GPS) | |
7cd4527e AC |
969 | @noindent |
970 | Although the command line interface (@command{gnatmake}, etc.) alone | |
971 | is sufficient, a graphical Interactive Development | |
972 | Environment can make it easier for you to compose, navigate, and debug | |
973 | programs. This section describes the main features of GPS | |
e08b38f5 | 974 | (``GNAT Programming Studio''), the GNAT graphical IDE. |
7cd4527e AC |
975 | You will see how to use GPS to build and debug an executable, and |
976 | you will also learn some of the basics of the GNAT ``project'' facility. | |
977 | ||
978 | GPS enables you to do much more than is presented here; | |
979 | e.g., you can produce a call graph, interface to a third-party | |
980 | Version Control System, and inspect the generated assembly language | |
981 | for a program. | |
982 | Indeed, GPS also supports languages other than Ada. | |
983 | Such additional information, and an explanation of all of the GPS menu | |
984 | items. may be found in the on-line help, which includes | |
985 | a user's guide and a tutorial (these are also accessible from the GNAT | |
986 | startup menu). | |
987 | ||
988 | @menu | |
989 | * Building a New Program with GPS:: | |
990 | * Simple Debugging with GPS:: | |
991 | @end menu | |
992 | ||
7cd4527e AC |
993 | @node Building a New Program with GPS |
994 | @subsection Building a New Program with GPS | |
995 | @noindent | |
996 | GPS invokes the GNAT compilation tools using information | |
997 | contained in a @emph{project} (also known as a @emph{project file}): | |
998 | a collection of properties such | |
999 | as source directories, identities of main subprograms, tool switches, etc., | |
1000 | and their associated values. | |
984a64bc | 1001 | See @ref{GNAT Project Manager} for details. |
7cd4527e AC |
1002 | In order to run GPS, you will need to either create a new project |
1003 | or else open an existing one. | |
1004 | ||
1005 | This section will explain how you can use GPS to create a project, | |
1006 | to associate Ada source files with a project, and to build and run | |
1007 | programs. | |
1008 | ||
1009 | @enumerate | |
1010 | @item @emph{Creating a project} | |
1011 | ||
1012 | Invoke GPS, either from the command line or the platform's IDE. | |
1013 | After it starts, GPS will display a ``Welcome'' screen with three | |
1014 | radio buttons: | |
1015 | ||
1016 | @itemize @bullet | |
1017 | @item | |
1018 | @code{Start with default project in directory} | |
1019 | ||
1020 | @item | |
1021 | @code{Create new project with wizard} | |
1022 | ||
1023 | @item | |
1024 | @code{Open existing project} | |
1025 | @end itemize | |
1026 | ||
1027 | @noindent | |
1028 | Select @code{Create new project with wizard} and press @code{OK}. | |
1029 | A new window will appear. In the text box labeled with | |
1030 | @code{Enter the name of the project to create}, type @file{sample} | |
1031 | as the project name. | |
1032 | In the next box, browse to choose the directory in which you | |
1033 | would like to create the project file. | |
1034 | After selecting an appropriate directory, press @code{Forward}. | |
1035 | ||
1036 | A window will appear with the title | |
1037 | @code{Version Control System Configuration}. | |
1038 | Simply press @code{Forward}. | |
1039 | ||
1040 | A window will appear with the title | |
1041 | @code{Please select the source directories for this project}. | |
1042 | The directory that you specified for the project file will be selected | |
1043 | by default as the one to use for sources; simply press @code{Forward}. | |
1044 | ||
1045 | A window will appear with the title | |
1046 | @code{Please select the build directory for this project}. | |
1047 | The directory that you specified for the project file will be selected | |
1048 | by default for object files and executables; | |
1049 | simply press @code{Forward}. | |
1050 | ||
1051 | A window will appear with the title | |
1052 | @code{Please select the main units for this project}. | |
1053 | You will supply this information later, after creating the source file. | |
1054 | Simply press @code{Forward} for now. | |
1055 | ||
1056 | A window will appear with the title | |
1057 | @code{Please select the switches to build the project}. | |
1058 | Press @code{Apply}. This will create a project file named | |
1059 | @file{sample.prj} in the directory that you had specified. | |
1060 | ||
1061 | @item @emph{Creating and saving the source file} | |
1062 | ||
1063 | After you create the new project, a GPS window will appear, which is | |
1064 | partitioned into two main sections: | |
1065 | ||
1066 | @itemize @bullet | |
1067 | @item | |
1068 | A @emph{Workspace area}, initially greyed out, which you will use for | |
1069 | creating and editing source files | |
1070 | ||
1071 | @item | |
1072 | Directly below, a @emph{Messages area}, which initially displays a | |
1073 | ``Welcome'' message. | |
1074 | (If the Messages area is not visible, drag its border upward to expand it.) | |
1075 | @end itemize | |
1076 | ||
1077 | @noindent | |
1078 | Select @code{File} on the menu bar, and then the @code{New} command. | |
1079 | The Workspace area will become white, and you can now | |
1080 | enter the source program explicitly. | |
1081 | Type the following text | |
1082 | ||
1083 | @smallexample @c ada | |
1084 | @group | |
1085 | with Ada.Text_IO; use Ada.Text_IO; | |
1086 | procedure Hello is | |
1087 | begin | |
1088 | Put_Line("Hello from GPS!"); | |
1089 | end Hello; | |
1090 | @end group | |
1091 | @end smallexample | |
1092 | ||
1093 | @noindent | |
1094 | Select @code{File}, then @code{Save As}, and enter the source file name | |
1095 | @file{hello.adb}. | |
1096 | The file will be saved in the same directory you specified as the | |
1097 | location of the default project file. | |
1098 | ||
7cd4527e AC |
1099 | @item @emph{Updating the project file} |
1100 | ||
1101 | You need to add the new source file to the project. | |
1102 | To do this, select | |
1103 | the @code{Project} menu and then @code{Edit project properties}. | |
1104 | Click the @code{Main files} tab on the left, and then the | |
1105 | @code{Add} button. | |
1106 | Choose @file{hello.adb} from the list, and press @code{Open}. | |
1107 | The project settings window will reflect this action. | |
1108 | Click @code{OK}. | |
1109 | ||
1110 | @item @emph{Building and running the program} | |
1111 | ||
1112 | In the main GPS window, now choose the @code{Build} menu, then @code{Make}, | |
1113 | and select @file{hello.adb}. | |
1114 | The Messages window will display the resulting invocations of @command{gcc}, | |
1115 | @command{gnatbind}, and @command{gnatlink} | |
1116 | (reflecting the default switch settings from the | |
1117 | project file that you created) and then a ``successful compilation/build'' | |
1118 | message. | |
1119 | ||
1120 | To run the program, choose the @code{Build} menu, then @code{Run}, and | |
1121 | select @command{hello}. | |
1122 | An @emph{Arguments Selection} window will appear. | |
1123 | There are no command line arguments, so just click @code{OK}. | |
1124 | ||
1125 | The Messages window will now display the program's output (the string | |
1126 | @code{Hello from GPS}), and at the bottom of the GPS window a status | |
1127 | update is displayed (@code{Run: hello}). | |
1128 | Close the GPS window (or select @code{File}, then @code{Exit}) to | |
1129 | terminate this GPS session. | |
1130 | @end enumerate | |
1131 | ||
7cd4527e AC |
1132 | @node Simple Debugging with GPS |
1133 | @subsection Simple Debugging with GPS | |
1134 | @noindent | |
1135 | This section illustrates basic debugging techniques (setting breakpoints, | |
1136 | examining/modifying variables, single stepping). | |
1137 | ||
1138 | @enumerate | |
1139 | @item @emph{Opening a project} | |
1140 | ||
1141 | Start GPS and select @code{Open existing project}; browse to | |
1142 | specify the project file @file{sample.prj} that you had created in the | |
1143 | earlier example. | |
1144 | ||
1145 | @item @emph{Creating a source file} | |
1146 | ||
1147 | Select @code{File}, then @code{New}, and type in the following program: | |
1148 | ||
1149 | @smallexample @c ada | |
1150 | @group | |
1151 | with Ada.Text_IO; use Ada.Text_IO; | |
1152 | procedure Example is | |
1153 | Line : String (1..80); | |
1154 | N : Natural; | |
1155 | begin | |
1156 | Put_Line("Type a line of text at each prompt; an empty line to exit"); | |
1157 | loop | |
1158 | Put(": "); | |
1159 | Get_Line (Line, N); | |
1160 | Put_Line (Line (1..N) ); | |
1161 | exit when N=0; | |
1162 | end loop; | |
1163 | end Example; | |
1164 | @end group | |
1165 | @end smallexample | |
1166 | ||
1167 | @noindent | |
1168 | Select @code{File}, then @code{Save as}, and enter the file name | |
1169 | @file{example.adb}. | |
1170 | ||
1171 | @item @emph{Updating the project file} | |
1172 | ||
1173 | Add @code{Example} as a new main unit for the project: | |
1174 | @enumerate a | |
1175 | @item | |
1176 | Select @code{Project}, then @code{Edit Project Properties}. | |
1177 | ||
1178 | @item | |
1179 | Select the @code{Main files} tab, click @code{Add}, then | |
1180 | select the file @file{example.adb} from the list, and | |
1181 | click @code{Open}. | |
1182 | You will see the file name appear in the list of main units | |
1183 | ||
1184 | @item | |
1185 | Click @code{OK} | |
1186 | @end enumerate | |
1187 | ||
1188 | @item @emph{Building/running the executable} | |
1189 | ||
1190 | To build the executable | |
1191 | select @code{Build}, then @code{Make}, and then choose @file{example.adb}. | |
1192 | ||
1193 | Run the program to see its effect (in the Messages area). | |
1194 | Each line that you enter is displayed; an empty line will | |
1195 | cause the loop to exit and the program to terminate. | |
1196 | ||
1197 | @item @emph{Debugging the program} | |
1198 | ||
1199 | Note that the @option{-g} switches to @command{gcc} and @command{gnatlink}, | |
1200 | which are required for debugging, are on by default when you create | |
1201 | a new project. | |
1202 | Thus unless you intentionally remove these settings, you will be able | |
1203 | to debug any program that you develop using GPS. | |
1204 | ||
1205 | @enumerate a | |
1206 | @item @emph{Initializing} | |
1207 | ||
1208 | Select @code{Debug}, then @code{Initialize}, then @file{example} | |
1209 | ||
1210 | @item @emph{Setting a breakpoint} | |
1211 | ||
1212 | After performing the initialization step, you will observe a small | |
1213 | icon to the right of each line number. | |
1214 | This serves as a toggle for breakpoints; clicking the icon will | |
1215 | set a breakpoint at the corresponding line (the icon will change to | |
1216 | a red circle with an ``x''), and clicking it again | |
1217 | will remove the breakpoint / reset the icon. | |
1218 | ||
1219 | For purposes of this example, set a breakpoint at line 10 (the | |
1220 | statement @code{Put_Line@ (Line@ (1..N));} | |
1221 | ||
1222 | @item @emph{Starting program execution} | |
1223 | ||
1224 | Select @code{Debug}, then @code{Run}. When the | |
1225 | @code{Program Arguments} window appears, click @code{OK}. | |
1226 | A console window will appear; enter some line of text, | |
8dd07840 | 1227 | e.g.@: @code{abcde}, at the prompt. |
7cd4527e AC |
1228 | The program will pause execution when it gets to the |
1229 | breakpoint, and the corresponding line is highlighted. | |
1230 | ||
1231 | @item @emph{Examining a variable} | |
1232 | ||
1233 | Move the mouse over one of the occurrences of the variable @code{N}. | |
1234 | You will see the value (5) displayed, in ``tool tip'' fashion. | |
1235 | Right click on @code{N}, select @code{Debug}, then select @code{Display N}. | |
1236 | You will see information about @code{N} appear in the @code{Debugger Data} | |
1237 | pane, showing the value as 5. | |
1238 | ||
7cd4527e AC |
1239 | @item @emph{Assigning a new value to a variable} |
1240 | ||
1241 | Right click on the @code{N} in the @code{Debugger Data} pane, and | |
1242 | select @code{Set value of N}. | |
1243 | When the input window appears, enter the value @code{4} and click | |
1244 | @code{OK}. | |
1245 | This value does not automatically appear in the @code{Debugger Data} | |
1246 | pane; to see it, right click again on the @code{N} in the | |
1247 | @code{Debugger Data} pane and select @code{Update value}. | |
1248 | The new value, 4, will appear in red. | |
1249 | ||
1250 | @item @emph{Single stepping} | |
1251 | ||
1252 | Select @code{Debug}, then @code{Next}. | |
1253 | This will cause the next statement to be executed, in this case the | |
1254 | call of @code{Put_Line} with the string slice. | |
1255 | Notice in the console window that the displayed string is simply | |
1256 | @code{abcd} and not @code{abcde} which you had entered. | |
1257 | This is because the upper bound of the slice is now 4 rather than 5. | |
1258 | ||
1259 | @item @emph{Removing a breakpoint} | |
1260 | ||
1261 | Toggle the breakpoint icon at line 10. | |
1262 | ||
1263 | @item @emph{Resuming execution from a breakpoint} | |
1264 | ||
1265 | Select @code{Debug}, then @code{Continue}. | |
1266 | The program will reach the next iteration of the loop, and | |
1267 | wait for input after displaying the prompt. | |
1268 | This time, just hit the @kbd{Enter} key. | |
1269 | The value of @code{N} will be 0, and the program will terminate. | |
1270 | The console window will disappear. | |
1271 | @end enumerate | |
1272 | @end enumerate | |
88e1739c FW |
1273 | @end ifclear |
1274 | ||
1275 | @node The GNAT Compilation Model | |
1276 | @chapter The GNAT Compilation Model | |
1277 | @cindex GNAT compilation model | |
1278 | @cindex Compilation model | |
1279 | ||
1280 | @menu | |
1281 | * Source Representation:: | |
1282 | * Foreign Language Representation:: | |
1283 | * File Naming Rules:: | |
1284 | * Using Other File Names:: | |
1285 | * Alternative File Naming Schemes:: | |
1286 | * Generating Object Files:: | |
1287 | * Source Dependencies:: | |
1288 | * The Ada Library Information Files:: | |
1289 | * Binding an Ada Program:: | |
1290 | * Mixed Language Programming:: | |
7e3d710b | 1291 | @ifclear vms |
88e1739c FW |
1292 | * Building Mixed Ada & C++ Programs:: |
1293 | * Comparison between GNAT and C/C++ Compilation Models:: | |
7e3d710b | 1294 | @end ifclear |
88e1739c | 1295 | * Comparison between GNAT and Conventional Ada Library Models:: |
7cd4527e AC |
1296 | @ifset vms |
1297 | * Placement of temporary files:: | |
1298 | @end ifset | |
88e1739c FW |
1299 | @end menu |
1300 | ||
1301 | @noindent | |
1302 | This chapter describes the compilation model used by GNAT. Although | |
1303 | similar to that used by other languages, such as C and C++, this model | |
1304 | is substantially different from the traditional Ada compilation models, | |
1305 | which are based on a library. The model is initially described without | |
1306 | reference to the library-based model. If you have not previously used an | |
1307 | Ada compiler, you need only read the first part of this chapter. The | |
1308 | last section describes and discusses the differences between the GNAT | |
1309 | model and the traditional Ada compiler models. If you have used other | |
1310 | Ada compilers, this section will help you to understand those | |
1311 | differences, and the advantages of the GNAT model. | |
1312 | ||
1313 | @node Source Representation | |
1314 | @section Source Representation | |
1315 | @cindex Latin-1 | |
1316 | ||
1317 | @noindent | |
1318 | Ada source programs are represented in standard text files, using | |
1319 | Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar | |
1320 | 7-bit ASCII set, plus additional characters used for | |
1321 | representing foreign languages (@pxref{Foreign Language Representation} | |
1322 | for support of non-USA character sets). The format effector characters | |
1323 | are represented using their standard ASCII encodings, as follows: | |
1324 | ||
1325 | @table @code | |
1326 | @item VT | |
1327 | @findex VT | |
1328 | Vertical tab, @code{16#0B#} | |
1329 | ||
1330 | @item HT | |
1331 | @findex HT | |
1332 | Horizontal tab, @code{16#09#} | |
1333 | ||
1334 | @item CR | |
1335 | @findex CR | |
1336 | Carriage return, @code{16#0D#} | |
1337 | ||
1338 | @item LF | |
1339 | @findex LF | |
1340 | Line feed, @code{16#0A#} | |
1341 | ||
1342 | @item FF | |
1343 | @findex FF | |
1344 | Form feed, @code{16#0C#} | |
1345 | @end table | |
1346 | ||
1347 | @noindent | |
1348 | Source files are in standard text file format. In addition, GNAT will | |
984a64bc | 1349 | recognize a wide variety of stream formats, in which the end of |
88e1739c FW |
1350 | physical lines is marked by any of the following sequences: |
1351 | @code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful | |
1352 | in accommodating files that are imported from other operating systems. | |
1353 | ||
1354 | @cindex End of source file | |
1355 | @cindex Source file, end | |
1356 | @findex SUB | |
1357 | The end of a source file is normally represented by the physical end of | |
1358 | file. However, the control character @code{16#1A#} (@code{SUB}) is also | |
1359 | recognized as signalling the end of the source file. Again, this is | |
1360 | provided for compatibility with other operating systems where this | |
1361 | code is used to represent the end of file. | |
1362 | ||
1363 | Each file contains a single Ada compilation unit, including any pragmas | |
1364 | associated with the unit. For example, this means you must place a | |
1365 | package declaration (a package @dfn{spec}) and the corresponding body in | |
1366 | separate files. An Ada @dfn{compilation} (which is a sequence of | |
1367 | compilation units) is represented using a sequence of files. Similarly, | |
1368 | you will place each subunit or child unit in a separate file. | |
1369 | ||
1370 | @node Foreign Language Representation | |
1371 | @section Foreign Language Representation | |
1372 | ||
1373 | @noindent | |
e08b38f5 | 1374 | GNAT supports the standard character sets defined in Ada as well as |
88e1739c FW |
1375 | several other non-standard character sets for use in localized versions |
1376 | of the compiler (@pxref{Character Set Control}). | |
1377 | @menu | |
1378 | * Latin-1:: | |
1379 | * Other 8-Bit Codes:: | |
1380 | * Wide Character Encodings:: | |
1381 | @end menu | |
1382 | ||
1383 | @node Latin-1 | |
1384 | @subsection Latin-1 | |
1385 | @cindex Latin-1 | |
1386 | ||
1387 | @noindent | |
1388 | The basic character set is Latin-1. This character set is defined by ISO | |
1389 | standard 8859, part 1. The lower half (character codes @code{16#00#} | |
aa0df10b VC |
1390 | @dots{} @code{16#7F#)} is identical to standard ASCII coding, but the upper |
1391 | half is used to represent additional characters. These include extended letters | |
88e1739c FW |
1392 | used by European languages, such as French accents, the vowels with umlauts |
1393 | used in German, and the extra letter A-ring used in Swedish. | |
1394 | ||
1395 | @findex Ada.Characters.Latin_1 | |
1396 | For a complete list of Latin-1 codes and their encodings, see the source | |
1397 | file of library unit @code{Ada.Characters.Latin_1} in file | |
1398 | @file{a-chlat1.ads}. | |
1399 | You may use any of these extended characters freely in character or | |
1400 | string literals. In addition, the extended characters that represent | |
1401 | letters can be used in identifiers. | |
1402 | ||
1403 | @node Other 8-Bit Codes | |
1404 | @subsection Other 8-Bit Codes | |
1405 | ||
1406 | @noindent | |
1407 | GNAT also supports several other 8-bit coding schemes: | |
1408 | ||
1409 | @table @asis | |
7cd4527e | 1410 | @item ISO 8859-2 (Latin-2) |
88e1739c | 1411 | @cindex Latin-2 |
7cd4527e | 1412 | @cindex ISO 8859-2 |
88e1739c FW |
1413 | Latin-2 letters allowed in identifiers, with uppercase and lowercase |
1414 | equivalence. | |
1415 | ||
7cd4527e | 1416 | @item ISO 8859-3 (Latin-3) |
88e1739c | 1417 | @cindex Latin-3 |
7cd4527e | 1418 | @cindex ISO 8859-3 |
88e1739c FW |
1419 | Latin-3 letters allowed in identifiers, with uppercase and lowercase |
1420 | equivalence. | |
1421 | ||
7cd4527e | 1422 | @item ISO 8859-4 (Latin-4) |
88e1739c | 1423 | @cindex Latin-4 |
7cd4527e | 1424 | @cindex ISO 8859-4 |
88e1739c FW |
1425 | Latin-4 letters allowed in identifiers, with uppercase and lowercase |
1426 | equivalence. | |
1427 | ||
7cd4527e AC |
1428 | @item ISO 8859-5 (Cyrillic) |
1429 | @cindex ISO 8859-5 | |
88e1739c | 1430 | @cindex Cyrillic |
7cd4527e AC |
1431 | ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and |
1432 | lowercase equivalence. | |
1433 | ||
1434 | @item ISO 8859-15 (Latin-9) | |
1435 | @cindex ISO 8859-15 | |
1436 | @cindex Latin-9 | |
1437 | ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and | |
1438 | lowercase equivalence | |
88e1739c FW |
1439 | |
1440 | @item IBM PC (code page 437) | |
1441 | @cindex code page 437 | |
1442 | This code page is the normal default for PCs in the U.S. It corresponds | |
1443 | to the original IBM PC character set. This set has some, but not all, of | |
1444 | the extended Latin-1 letters, but these letters do not have the same | |
1445 | encoding as Latin-1. In this mode, these letters are allowed in | |
1446 | identifiers with uppercase and lowercase equivalence. | |
1447 | ||
1448 | @item IBM PC (code page 850) | |
1449 | @cindex code page 850 | |
1450 | This code page is a modification of 437 extended to include all the | |
1451 | Latin-1 letters, but still not with the usual Latin-1 encoding. In this | |
1452 | mode, all these letters are allowed in identifiers with uppercase and | |
1453 | lowercase equivalence. | |
1454 | ||
1455 | @item Full Upper 8-bit | |
1456 | Any character in the range 80-FF allowed in identifiers, and all are | |
1457 | considered distinct. In other words, there are no uppercase and lowercase | |
1458 | equivalences in this range. This is useful in conjunction with | |
8dd07840 | 1459 | certain encoding schemes used for some foreign character sets (e.g., |
88e1739c FW |
1460 | the typical method of representing Chinese characters on the PC). |
1461 | ||
1462 | @item No Upper-Half | |
1463 | No upper-half characters in the range 80-FF are allowed in identifiers. | |
1464 | This gives Ada 83 compatibility for identifier names. | |
1465 | @end table | |
1466 | ||
1467 | @noindent | |
1468 | For precise data on the encodings permitted, and the uppercase and lowercase | |
1469 | equivalences that are recognized, see the file @file{csets.adb} in | |
1470 | the GNAT compiler sources. You will need to obtain a full source release | |
1471 | of GNAT to obtain this file. | |
1472 | ||
1473 | @node Wide Character Encodings | |
1474 | @subsection Wide Character Encodings | |
1475 | ||
1476 | @noindent | |
1477 | GNAT allows wide character codes to appear in character and string | |
1478 | literals, and also optionally in identifiers, by means of the following | |
1479 | possible encoding schemes: | |
1480 | ||
1481 | @table @asis | |
1482 | ||
1483 | @item Hex Coding | |
1484 | In this encoding, a wide character is represented by the following five | |
1485 | character sequence: | |
1486 | ||
1487 | @smallexample | |
1488 | ESC a b c d | |
1489 | @end smallexample | |
1490 | ||
1491 | @noindent | |
1492 | Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
1493 | characters (using uppercase letters) of the wide character code. For | |
1494 | example, ESC A345 is used to represent the wide character with code | |
1495 | @code{16#A345#}. | |
1496 | This scheme is compatible with use of the full Wide_Character set. | |
1497 | ||
1498 | @item Upper-Half Coding | |
1499 | @cindex Upper-Half Coding | |
7cd4527e AC |
1500 | The wide character with encoding @code{16#abcd#} where the upper bit is on |
1501 | (in other words, ``a'' is in the range 8-F) is represented as two bytes, | |
88e1739c FW |
1502 | @code{16#ab#} and @code{16#cd#}. The second byte cannot be a format control |
1503 | character, but is not required to be in the upper half. This method can | |
1504 | be also used for shift-JIS or EUC, where the internal coding matches the | |
1505 | external coding. | |
1506 | ||
1507 | @item Shift JIS Coding | |
1508 | @cindex Shift JIS Coding | |
1509 | A wide character is represented by a two-character sequence, | |
1510 | @code{16#ab#} and | |
1511 | @code{16#cd#}, with the restrictions described for upper-half encoding as | |
1512 | described above. The internal character code is the corresponding JIS | |
1513 | character according to the standard algorithm for Shift-JIS | |
1514 | conversion. Only characters defined in the JIS code set table can be | |
1515 | used with this encoding method. | |
1516 | ||
1517 | @item EUC Coding | |
1518 | @cindex EUC Coding | |
1519 | A wide character is represented by a two-character sequence | |
1520 | @code{16#ab#} and | |
1521 | @code{16#cd#}, with both characters being in the upper half. The internal | |
1522 | character code is the corresponding JIS character according to the EUC | |
1523 | encoding algorithm. Only characters defined in the JIS code set table | |
1524 | can be used with this encoding method. | |
1525 | ||
1526 | @item UTF-8 Coding | |
1527 | A wide character is represented using | |
1528 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
1529 | 10646-1/Am.2. Depending on the character value, the representation | |
1530 | is a one, two, or three byte sequence: | |
1531 | @smallexample | |
1532 | @iftex | |
1533 | @leftskip=.7cm | |
1534 | @end iftex | |
79f34d07 RW |
1535 | 16#0000#-16#007f#: 2#0@var{xxxxxxx}# |
1536 | 16#0080#-16#07ff#: 2#110@var{xxxxx}# 2#10@var{xxxxxx}# | |
1537 | 16#0800#-16#ffff#: 2#1110@var{xxxx}# 2#10@var{xxxxxx}# 2#10@var{xxxxxx}# | |
88e1739c FW |
1538 | |
1539 | @end smallexample | |
1540 | ||
1541 | @noindent | |
79f34d07 | 1542 | where the @var{xxx} bits correspond to the left-padded bits of the |
88e1739c FW |
1543 | 16-bit character value. Note that all lower half ASCII characters |
1544 | are represented as ASCII bytes and all upper half characters and | |
1545 | other wide characters are represented as sequences of upper-half | |
1546 | (The full UTF-8 scheme allows for encoding 31-bit characters as | |
1547 | 6-byte sequences, but in this implementation, all UTF-8 sequences | |
1548 | of four or more bytes length will be treated as illegal). | |
1549 | @item Brackets Coding | |
1550 | In this encoding, a wide character is represented by the following eight | |
1551 | character sequence: | |
1552 | ||
1553 | @smallexample | |
1554 | [ " a b c d " ] | |
1555 | @end smallexample | |
1556 | ||
1557 | @noindent | |
1558 | Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
1559 | characters (using uppercase letters) of the wide character code. For | |
7cd4527e | 1560 | example, [``A345''] is used to represent the wide character with code |
88e1739c FW |
1561 | @code{16#A345#}. It is also possible (though not required) to use the |
1562 | Brackets coding for upper half characters. For example, the code | |
7cd4527e | 1563 | @code{16#A3#} can be represented as @code{[``A3'']}. |
88e1739c FW |
1564 | |
1565 | This scheme is compatible with use of the full Wide_Character set, | |
1566 | and is also the method used for wide character encoding in the standard | |
1567 | ACVC (Ada Compiler Validation Capability) test suite distributions. | |
1568 | ||
1569 | @end table | |
1570 | ||
1571 | @noindent | |
1572 | Note: Some of these coding schemes do not permit the full use of the | |
e08b38f5 | 1573 | Ada character set. For example, neither Shift JIS, nor EUC allow the |
88e1739c FW |
1574 | use of the upper half of the Latin-1 set. |
1575 | ||
1576 | @node File Naming Rules | |
1577 | @section File Naming Rules | |
1578 | ||
1579 | @noindent | |
1580 | The default file name is determined by the name of the unit that the | |
1581 | file contains. The name is formed by taking the full expanded name of | |
1582 | the unit and replacing the separating dots with hyphens and using | |
1583 | ^lowercase^uppercase^ for all letters. | |
1584 | ||
1585 | An exception arises if the file name generated by the above rules starts | |
1586 | with one of the characters | |
1587 | @ifset vms | |
8dd07840 | 1588 | @samp{A}, @samp{G}, @samp{I}, or @samp{S}, |
88e1739c FW |
1589 | @end ifset |
1590 | @ifclear vms | |
8dd07840 | 1591 | @samp{a}, @samp{g}, @samp{i}, or @samp{s}, |
88e1739c FW |
1592 | @end ifclear |
1593 | and the second character is a | |
1594 | minus. In this case, the character ^tilde^dollar sign^ is used in place | |
1595 | of the minus. The reason for this special rule is to avoid clashes with | |
1596 | the standard names for child units of the packages System, Ada, | |
1597 | Interfaces, and GNAT, which use the prefixes | |
1598 | @ifset vms | |
8dd07840 | 1599 | @samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-}, |
88e1739c FW |
1600 | @end ifset |
1601 | @ifclear vms | |
8dd07840 | 1602 | @samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-}, |
88e1739c FW |
1603 | @end ifclear |
1604 | respectively. | |
1605 | ||
1606 | The file extension is @file{.ads} for a spec and | |
1607 | @file{.adb} for a body. The following list shows some | |
1608 | examples of these rules. | |
1609 | ||
1610 | @table @file | |
1611 | @item main.ads | |
1612 | Main (spec) | |
1613 | @item main.adb | |
1614 | Main (body) | |
1615 | @item arith_functions.ads | |
1616 | Arith_Functions (package spec) | |
1617 | @item arith_functions.adb | |
1618 | Arith_Functions (package body) | |
1619 | @item func-spec.ads | |
1620 | Func.Spec (child package spec) | |
1621 | @item func-spec.adb | |
1622 | Func.Spec (child package body) | |
1623 | @item main-sub.adb | |
1624 | Sub (subunit of Main) | |
1625 | @item ^a~bad.adb^A$BAD.ADB^ | |
1626 | A.Bad (child package body) | |
1627 | @end table | |
1628 | ||
1629 | @noindent | |
1630 | Following these rules can result in excessively long | |
1631 | file names if corresponding | |
1632 | unit names are long (for example, if child units or subunits are | |
1633 | heavily nested). An option is available to shorten such long file names | |
7cd4527e | 1634 | (called file name ``krunching''). This may be particularly useful when |
88e1739c FW |
1635 | programs being developed with GNAT are to be used on operating systems |
1636 | with limited file name lengths. @xref{Using gnatkr}. | |
1637 | ||
1638 | Of course, no file shortening algorithm can guarantee uniqueness over | |
1639 | all possible unit names; if file name krunching is used, it is your | |
1640 | responsibility to ensure no name clashes occur. Alternatively you | |
1641 | can specify the exact file names that you want used, as described | |
1642 | in the next section. Finally, if your Ada programs are migrating from a | |
1643 | compiler with a different naming convention, you can use the gnatchop | |
1644 | utility to produce source files that follow the GNAT naming conventions. | |
c2658843 | 1645 | (For details @pxref{Renaming Files with gnatchop}.) |
88e1739c | 1646 | |
7cd4527e AC |
1647 | Note: in the case of @code{Windows NT/XP} or @code{OpenVMS} operating |
1648 | systems, case is not significant. So for example on @code{Windows XP} | |
1649 | if the canonical name is @code{main-sub.adb}, you can use the file name | |
1650 | @code{Main-Sub.adb} instead. However, case is significant for other | |
1651 | operating systems, so for example, if you want to use other than | |
1652 | canonically cased file names on a Unix system, you need to follow | |
1653 | the procedures described in the next section. | |
1654 | ||
88e1739c FW |
1655 | @node Using Other File Names |
1656 | @section Using Other File Names | |
1657 | @cindex File names | |
1658 | ||
1659 | @noindent | |
1660 | In the previous section, we have described the default rules used by | |
1661 | GNAT to determine the file name in which a given unit resides. It is | |
1662 | often convenient to follow these default rules, and if you follow them, | |
1663 | the compiler knows without being explicitly told where to find all | |
1664 | the files it needs. | |
1665 | ||
1666 | However, in some cases, particularly when a program is imported from | |
1667 | another Ada compiler environment, it may be more convenient for the | |
1668 | programmer to specify which file names contain which units. GNAT allows | |
1669 | arbitrary file names to be used by means of the Source_File_Name pragma. | |
1670 | The form of this pragma is as shown in the following examples: | |
1671 | @cindex Source_File_Name pragma | |
1672 | ||
7cd4527e | 1673 | @smallexample @c ada |
88e1739c | 1674 | @cartouche |
7cd4527e | 1675 | pragma Source_File_Name (My_Utilities.Stacks, |
88e1739c | 1676 | Spec_File_Name => "myutilst_a.ada"); |
7cd4527e | 1677 | pragma Source_File_name (My_Utilities.Stacks, |
88e1739c FW |
1678 | Body_File_Name => "myutilst.ada"); |
1679 | @end cartouche | |
88e1739c FW |
1680 | @end smallexample |
1681 | ||
1682 | @noindent | |
1683 | As shown in this example, the first argument for the pragma is the unit | |
1684 | name (in this example a child unit). The second argument has the form | |
1685 | of a named association. The identifier | |
1686 | indicates whether the file name is for a spec or a body; | |
1687 | the file name itself is given by a string literal. | |
1688 | ||
1689 | The source file name pragma is a configuration pragma, which means that | |
1690 | normally it will be placed in the @file{gnat.adc} | |
1691 | file used to hold configuration | |
1692 | pragmas that apply to a complete compilation environment. | |
1693 | For more details on how the @file{gnat.adc} file is created and used | |
984a64bc | 1694 | see @ref{Handling of Configuration Pragmas}. |
88e1739c FW |
1695 | @cindex @file{gnat.adc} |
1696 | ||
1697 | @ifclear vms | |
1698 | GNAT allows completely arbitrary file names to be specified using the | |
1699 | source file name pragma. However, if the file name specified has an | |
7cd4527e AC |
1700 | extension other than @file{.ads} or @file{.adb} it is necessary to use |
1701 | a special syntax when compiling the file. The name in this case must be | |
1992bbd9 | 1702 | preceded by the special sequence @option{-x} followed by a space and the name |
7cd4527e | 1703 | of the language, here @code{ada}, as in: |
88e1739c FW |
1704 | |
1705 | @smallexample | |
1706 | $ gcc -c -x ada peculiar_file_name.sim | |
1707 | @end smallexample | |
1708 | @end ifclear | |
1709 | ||
1710 | @noindent | |
984a64bc | 1711 | @command{gnatmake} handles non-standard file names in the usual manner (the |
88e1739c FW |
1712 | non-standard file name for the main program is simply used as the |
1713 | argument to gnatmake). Note that if the extension is also non-standard, | |
1992bbd9 RW |
1714 | then it must be included in the @command{gnatmake} command, it may not |
1715 | be omitted. | |
88e1739c FW |
1716 | |
1717 | @node Alternative File Naming Schemes | |
1718 | @section Alternative File Naming Schemes | |
1719 | @cindex File naming schemes, alternative | |
1720 | @cindex File names | |
1721 | ||
1722 | In the previous section, we described the use of the @code{Source_File_Name} | |
1723 | pragma to allow arbitrary names to be assigned to individual source files. | |
1724 | However, this approach requires one pragma for each file, and especially in | |
1725 | large systems can result in very long @file{gnat.adc} files, and also create | |
1726 | a maintenance problem. | |
1727 | ||
1728 | GNAT also provides a facility for specifying systematic file naming schemes | |
1729 | other than the standard default naming scheme previously described. An | |
1730 | alternative scheme for naming is specified by the use of | |
1731 | @code{Source_File_Name} pragmas having the following format: | |
1732 | @cindex Source_File_Name pragma | |
1733 | ||
7cd4527e | 1734 | @smallexample @c ada |
88e1739c FW |
1735 | pragma Source_File_Name ( |
1736 | Spec_File_Name => FILE_NAME_PATTERN | |
66bfd481 RW |
1737 | @r{[},Casing => CASING_SPEC@r{]} |
1738 | @r{[},Dot_Replacement => STRING_LITERAL@r{]}); | |
88e1739c FW |
1739 | |
1740 | pragma Source_File_Name ( | |
1741 | Body_File_Name => FILE_NAME_PATTERN | |
66bfd481 RW |
1742 | @r{[},Casing => CASING_SPEC@r{]} |
1743 | @r{[},Dot_Replacement => STRING_LITERAL@r{]}); | |
88e1739c FW |
1744 | |
1745 | pragma Source_File_Name ( | |
1746 | Subunit_File_Name => FILE_NAME_PATTERN | |
66bfd481 RW |
1747 | @r{[},Casing => CASING_SPEC@r{]} |
1748 | @r{[},Dot_Replacement => STRING_LITERAL@r{]}); | |
88e1739c FW |
1749 | |
1750 | FILE_NAME_PATTERN ::= STRING_LITERAL | |
1751 | CASING_SPEC ::= Lowercase | Uppercase | Mixedcase | |
88e1739c FW |
1752 | @end smallexample |
1753 | ||
1754 | @noindent | |
1755 | The @code{FILE_NAME_PATTERN} string shows how the file name is constructed. | |
1756 | It contains a single asterisk character, and the unit name is substituted | |
1757 | systematically for this asterisk. The optional parameter | |
1758 | @code{Casing} indicates | |
1759 | whether the unit name is to be all upper-case letters, all lower-case letters, | |
1760 | or mixed-case. If no | |
1761 | @code{Casing} parameter is used, then the default is all | |
1762 | ^lower-case^upper-case^. | |
1763 | ||
1764 | The optional @code{Dot_Replacement} string is used to replace any periods | |
1765 | that occur in subunit or child unit names. If no @code{Dot_Replacement} | |
1766 | argument is used then separating dots appear unchanged in the resulting | |
1767 | file name. | |
1768 | Although the above syntax indicates that the | |
1769 | @code{Casing} argument must appear | |
1770 | before the @code{Dot_Replacement} argument, but it | |
1771 | is also permissible to write these arguments in the opposite order. | |
1772 | ||
1773 | As indicated, it is possible to specify different naming schemes for | |
1774 | bodies, specs, and subunits. Quite often the rule for subunits is the | |
1775 | same as the rule for bodies, in which case, there is no need to give | |
1776 | a separate @code{Subunit_File_Name} rule, and in this case the | |
1777 | @code{Body_File_name} rule is used for subunits as well. | |
1778 | ||
1779 | The separate rule for subunits can also be used to implement the rather | |
8dd07840 | 1780 | unusual case of a compilation environment (e.g.@: a single directory) which |
88e1739c FW |
1781 | contains a subunit and a child unit with the same unit name. Although |
1782 | both units cannot appear in the same partition, the Ada Reference Manual | |
1783 | allows (but does not require) the possibility of the two units coexisting | |
1784 | in the same environment. | |
1785 | ||
1786 | The file name translation works in the following steps: | |
1787 | ||
1788 | @itemize @bullet | |
1789 | ||
1790 | @item | |
1791 | If there is a specific @code{Source_File_Name} pragma for the given unit, | |
1792 | then this is always used, and any general pattern rules are ignored. | |
1793 | ||
1794 | @item | |
1795 | If there is a pattern type @code{Source_File_Name} pragma that applies to | |
1796 | the unit, then the resulting file name will be used if the file exists. If | |
1797 | more than one pattern matches, the latest one will be tried first, and the | |
1798 | first attempt resulting in a reference to a file that exists will be used. | |
1799 | ||
1800 | @item | |
1801 | If no pattern type @code{Source_File_Name} pragma that applies to the unit | |
1802 | for which the corresponding file exists, then the standard GNAT default | |
1803 | naming rules are used. | |
1804 | ||
1805 | @end itemize | |
1806 | ||
1807 | @noindent | |
1808 | As an example of the use of this mechanism, consider a commonly used scheme | |
1809 | in which file names are all lower case, with separating periods copied | |
7cd4527e AC |
1810 | unchanged to the resulting file name, and specs end with @file{.1.ada}, and |
1811 | bodies end with @file{.2.ada}. GNAT will follow this scheme if the following | |
88e1739c FW |
1812 | two pragmas appear: |
1813 | ||
7cd4527e | 1814 | @smallexample @c ada |
88e1739c FW |
1815 | pragma Source_File_Name |
1816 | (Spec_File_Name => "*.1.ada"); | |
1817 | pragma Source_File_Name | |
1818 | (Body_File_Name => "*.2.ada"); | |
1819 | @end smallexample | |
1820 | ||
1821 | @noindent | |
1822 | The default GNAT scheme is actually implemented by providing the following | |
1823 | default pragmas internally: | |
1824 | ||
7cd4527e | 1825 | @smallexample @c ada |
88e1739c FW |
1826 | pragma Source_File_Name |
1827 | (Spec_File_Name => "*.ads", Dot_Replacement => "-"); | |
1828 | pragma Source_File_Name | |
1829 | (Body_File_Name => "*.adb", Dot_Replacement => "-"); | |
1830 | @end smallexample | |
1831 | ||
1832 | @noindent | |
1833 | Our final example implements a scheme typically used with one of the | |
7cd4527e | 1834 | Ada 83 compilers, where the separator character for subunits was ``__'' |
88e1739c FW |
1835 | (two underscores), specs were identified by adding @file{_.ADA}, bodies |
1836 | by adding @file{.ADA}, and subunits by | |
1837 | adding @file{.SEP}. All file names were | |
1838 | upper case. Child units were not present of course since this was an | |
1839 | Ada 83 compiler, but it seems reasonable to extend this scheme to use | |
1840 | the same double underscore separator for child units. | |
1841 | ||
7cd4527e | 1842 | @smallexample @c ada |
88e1739c FW |
1843 | pragma Source_File_Name |
1844 | (Spec_File_Name => "*_.ADA", | |
1845 | Dot_Replacement => "__", | |
1846 | Casing = Uppercase); | |
1847 | pragma Source_File_Name | |
1848 | (Body_File_Name => "*.ADA", | |
1849 | Dot_Replacement => "__", | |
1850 | Casing = Uppercase); | |
1851 | pragma Source_File_Name | |
1852 | (Subunit_File_Name => "*.SEP", | |
1853 | Dot_Replacement => "__", | |
1854 | Casing = Uppercase); | |
1855 | @end smallexample | |
1856 | ||
1857 | @node Generating Object Files | |
1858 | @section Generating Object Files | |
1859 | ||
1860 | @noindent | |
1861 | An Ada program consists of a set of source files, and the first step in | |
1862 | compiling the program is to generate the corresponding object files. | |
1863 | These are generated by compiling a subset of these source files. | |
1864 | The files you need to compile are the following: | |
1865 | ||
1866 | @itemize @bullet | |
1867 | @item | |
1868 | If a package spec has no body, compile the package spec to produce the | |
1869 | object file for the package. | |
1870 | ||
1871 | @item | |
1872 | If a package has both a spec and a body, compile the body to produce the | |
1873 | object file for the package. The source file for the package spec need | |
1874 | not be compiled in this case because there is only one object file, which | |
1875 | contains the code for both the spec and body of the package. | |
1876 | ||
1877 | @item | |
1878 | For a subprogram, compile the subprogram body to produce the object file | |
1879 | for the subprogram. The spec, if one is present, is as usual in a | |
1880 | separate file, and need not be compiled. | |
1881 | ||
1882 | @item | |
1883 | @cindex Subunits | |
1884 | In the case of subunits, only compile the parent unit. A single object | |
1885 | file is generated for the entire subunit tree, which includes all the | |
1886 | subunits. | |
1887 | ||
1888 | @item | |
1889 | Compile child units independently of their parent units | |
1890 | (though, of course, the spec of all the ancestor unit must be present in order | |
1891 | to compile a child unit). | |
1892 | ||
1893 | @item | |
1894 | @cindex Generics | |
1895 | Compile generic units in the same manner as any other units. The object | |
1896 | files in this case are small dummy files that contain at most the | |
1897 | flag used for elaboration checking. This is because GNAT always handles generic | |
1898 | instantiation by means of macro expansion. However, it is still necessary to | |
1899 | compile generic units, for dependency checking and elaboration purposes. | |
1900 | @end itemize | |
1901 | ||
1902 | @noindent | |
1903 | The preceding rules describe the set of files that must be compiled to | |
1904 | generate the object files for a program. Each object file has the same | |
1905 | name as the corresponding source file, except that the extension is | |
1906 | @file{.o} as usual. | |
1907 | ||
1908 | You may wish to compile other files for the purpose of checking their | |
1909 | syntactic and semantic correctness. For example, in the case where a | |
1910 | package has a separate spec and body, you would not normally compile the | |
1911 | spec. However, it is convenient in practice to compile the spec to make | |
1912 | sure it is error-free before compiling clients of this spec, because such | |
1913 | compilations will fail if there is an error in the spec. | |
1914 | ||
1915 | GNAT provides an option for compiling such files purely for the | |
1916 | purposes of checking correctness; such compilations are not required as | |
1917 | part of the process of building a program. To compile a file in this | |
1918 | checking mode, use the @option{-gnatc} switch. | |
1919 | ||
1920 | @node Source Dependencies | |
1921 | @section Source Dependencies | |
1922 | ||
1923 | @noindent | |
1924 | A given object file clearly depends on the source file which is compiled | |
1925 | to produce it. Here we are using @dfn{depends} in the sense of a typical | |
1926 | @code{make} utility; in other words, an object file depends on a source | |
1927 | file if changes to the source file require the object file to be | |
1928 | recompiled. | |
1929 | In addition to this basic dependency, a given object may depend on | |
1930 | additional source files as follows: | |
1931 | ||
1932 | @itemize @bullet | |
1933 | @item | |
1934 | If a file being compiled @code{with}'s a unit @var{X}, the object file | |
1935 | depends on the file containing the spec of unit @var{X}. This includes | |
1936 | files that are @code{with}'ed implicitly either because they are parents | |
1937 | of @code{with}'ed child units or they are run-time units required by the | |
1938 | language constructs used in a particular unit. | |
1939 | ||
1940 | @item | |
1941 | If a file being compiled instantiates a library level generic unit, the | |
1942 | object file depends on both the spec and body files for this generic | |
1943 | unit. | |
1944 | ||
1945 | @item | |
1946 | If a file being compiled instantiates a generic unit defined within a | |
1947 | package, the object file depends on the body file for the package as | |
1948 | well as the spec file. | |
1949 | ||
1950 | @item | |
1951 | @findex Inline | |
1952 | @cindex @option{-gnatn} switch | |
1953 | If a file being compiled contains a call to a subprogram for which | |
1954 | pragma @code{Inline} applies and inlining is activated with the | |
1955 | @option{-gnatn} switch, the object file depends on the file containing the | |
1956 | body of this subprogram as well as on the file containing the spec. Note | |
1957 | that for inlining to actually occur as a result of the use of this switch, | |
1958 | it is necessary to compile in optimizing mode. | |
1959 | ||
1960 | @cindex @option{-gnatN} switch | |
d47f5232 | 1961 | The use of @option{-gnatN} activates inlining optimization |
88e1739c FW |
1962 | that is performed by the front end of the compiler. This inlining does |
1963 | not require that the code generation be optimized. Like @option{-gnatn}, | |
1964 | the use of this switch generates additional dependencies. | |
1965 | ||
d47f5232 RD |
1966 | When using a gcc-based back end (in practice this means using any version |
1967 | of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of | |
1968 | @option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred. | |
1969 | Historically front end inlining was more extensive than the gcc back end | |
1970 | inlining, but that is no longer the case. | |
1971 | ||
88e1739c | 1972 | @item |
e08b38f5 VC |
1973 | If an object file @file{O} depends on the proper body of a subunit through |
1974 | inlining or instantiation, it depends on the parent unit of the subunit. | |
1975 | This means that any modification of the parent unit or one of its subunits | |
1976 | affects the compilation of @file{O}. | |
88e1739c FW |
1977 | |
1978 | @item | |
1979 | The object file for a parent unit depends on all its subunit body files. | |
1980 | ||
1981 | @item | |
1982 | The previous two rules meant that for purposes of computing dependencies and | |
1983 | recompilation, a body and all its subunits are treated as an indivisible whole. | |
1984 | ||
1985 | @noindent | |
1986 | These rules are applied transitively: if unit @code{A} @code{with}'s | |
1987 | unit @code{B}, whose elaboration calls an inlined procedure in package | |
1988 | @code{C}, the object file for unit @code{A} will depend on the body of | |
1989 | @code{C}, in file @file{c.adb}. | |
1990 | ||
1991 | The set of dependent files described by these rules includes all the | |
e08b38f5 VC |
1992 | files on which the unit is semantically dependent, as dictated by the |
1993 | Ada language standard. However, it is a superset of what the | |
1994 | standard describes, because it includes generic, inline, and subunit | |
1995 | dependencies. | |
88e1739c FW |
1996 | |
1997 | An object file must be recreated by recompiling the corresponding source | |
1998 | file if any of the source files on which it depends are modified. For | |
1999 | example, if the @code{make} utility is used to control compilation, | |
2000 | the rule for an Ada object file must mention all the source files on | |
2001 | which the object file depends, according to the above definition. | |
2002 | The determination of the necessary | |
984a64bc | 2003 | recompilations is done automatically when one uses @command{gnatmake}. |
88e1739c FW |
2004 | @end itemize |
2005 | ||
2006 | @node The Ada Library Information Files | |
2007 | @section The Ada Library Information Files | |
2008 | @cindex Ada Library Information files | |
7cd4527e | 2009 | @cindex @file{ALI} files |
88e1739c FW |
2010 | |
2011 | @noindent | |
2012 | Each compilation actually generates two output files. The first of these | |
2013 | is the normal object file that has a @file{.o} extension. The second is a | |
2014 | text file containing full dependency information. It has the same | |
2015 | name as the source file, but an @file{.ali} extension. | |
7cd4527e AC |
2016 | This file is known as the Ada Library Information (@file{ALI}) file. |
2017 | The following information is contained in the @file{ALI} file. | |
88e1739c FW |
2018 | |
2019 | @itemize @bullet | |
2020 | @item | |
2021 | Version information (indicates which version of GNAT was used to compile | |
2022 | the unit(s) in question) | |
2023 | ||
2024 | @item | |
2025 | Main program information (including priority and time slice settings, | |
2026 | as well as the wide character encoding used during compilation). | |
2027 | ||
2028 | @item | |
984a64bc | 2029 | List of arguments used in the @command{gcc} command for the compilation |
88e1739c FW |
2030 | |
2031 | @item | |
2032 | Attributes of the unit, including configuration pragmas used, an indication | |
2033 | of whether the compilation was successful, exception model used etc. | |
2034 | ||
2035 | @item | |
2036 | A list of relevant restrictions applying to the unit (used for consistency) | |
2037 | checking. | |
2038 | ||
2039 | @item | |
8dd07840 | 2040 | Categorization information (e.g.@: use of pragma @code{Pure}). |
88e1739c FW |
2041 | |
2042 | @item | |
2043 | Information on all @code{with}'ed units, including presence of | |
2044 | @code{Elaborate} or @code{Elaborate_All} pragmas. | |
2045 | ||
2046 | @item | |
2047 | Information from any @code{Linker_Options} pragmas used in the unit | |
2048 | ||
2049 | @item | |
2050 | Information on the use of @code{Body_Version} or @code{Version} | |
2051 | attributes in the unit. | |
2052 | ||
2053 | @item | |
2054 | Dependency information. This is a list of files, together with | |
2055 | time stamp and checksum information. These are files on which | |
2056 | the unit depends in the sense that recompilation is required | |
2057 | if any of these units are modified. | |
2058 | ||
2059 | @item | |
2060 | Cross-reference data. Contains information on all entities referenced | |
2061 | in the unit. Used by tools like @code{gnatxref} and @code{gnatfind} to | |
2062 | provide cross-reference information. | |
2063 | ||
2064 | @end itemize | |
2065 | ||
2066 | @noindent | |
7cd4527e | 2067 | For a full detailed description of the format of the @file{ALI} file, |
88e1739c FW |
2068 | see the source of the body of unit @code{Lib.Writ}, contained in file |
2069 | @file{lib-writ.adb} in the GNAT compiler sources. | |
2070 | ||
2071 | @node Binding an Ada Program | |
2072 | @section Binding an Ada Program | |
2073 | ||
2074 | @noindent | |
2075 | When using languages such as C and C++, once the source files have been | |
2076 | compiled the only remaining step in building an executable program | |
2077 | is linking the object modules together. This means that it is possible to | |
2078 | link an inconsistent version of a program, in which two units have | |
2079 | included different versions of the same header. | |
2080 | ||
2081 | The rules of Ada do not permit such an inconsistent program to be built. | |
2082 | For example, if two clients have different versions of the same package, | |
2083 | it is illegal to build a program containing these two clients. | |
2084 | These rules are enforced by the GNAT binder, which also determines an | |
2085 | elaboration order consistent with the Ada rules. | |
2086 | ||
2087 | The GNAT binder is run after all the object files for a program have | |
2088 | been created. It is given the name of the main program unit, and from | |
2089 | this it determines the set of units required by the program, by reading the | |
2090 | corresponding ALI files. It generates error messages if the program is | |
2091 | inconsistent or if no valid order of elaboration exists. | |
2092 | ||
2093 | If no errors are detected, the binder produces a main program, in Ada by | |
2094 | default, that contains calls to the elaboration procedures of those | |
2095 | compilation unit that require them, followed by | |
2096 | a call to the main program. This Ada program is compiled to generate the | |
2097 | object file for the main program. The name of | |
2098 | the Ada file is @file{b~@var{xxx}.adb} (with the corresponding spec | |
2099 | @file{b~@var{xxx}.ads}) where @var{xxx} is the name of the | |
2100 | main program unit. | |
2101 | ||
2102 | Finally, the linker is used to build the resulting executable program, | |
2103 | using the object from the main program from the bind step as well as the | |
2104 | object files for the Ada units of the program. | |
2105 | ||
2106 | @node Mixed Language Programming | |
2107 | @section Mixed Language Programming | |
2108 | @cindex Mixed Language Programming | |
2109 | ||
7cd4527e AC |
2110 | @noindent |
2111 | This section describes how to develop a mixed-language program, | |
2112 | specifically one that comprises units in both Ada and C. | |
2113 | ||
88e1739c FW |
2114 | @menu |
2115 | * Interfacing to C:: | |
2116 | * Calling Conventions:: | |
2117 | @end menu | |
2118 | ||
2119 | @node Interfacing to C | |
2120 | @subsection Interfacing to C | |
2121 | @noindent | |
7cd4527e AC |
2122 | Interfacing Ada with a foreign language such as C involves using |
2123 | compiler directives to import and/or export entity definitions in each | |
2124 | language---using @code{extern} statements in C, for instance, and the | |
e08b38f5 VC |
2125 | @code{Import}, @code{Export}, and @code{Convention} pragmas in Ada. |
2126 | A full treatment of these topics is provided in Appendix B, section 1 | |
2127 | of the Ada Reference Manual. | |
7cd4527e AC |
2128 | |
2129 | There are two ways to build a program using GNAT that contains some Ada | |
2130 | sources and some foreign language sources, depending on whether or not | |
2131 | the main subprogram is written in Ada. Here is a source example with | |
2132 | the main subprogram in Ada: | |
2133 | ||
2134 | @smallexample | |
2135 | /* file1.c */ | |
2136 | #include <stdio.h> | |
2137 | ||
2138 | void print_num (int num) | |
2139 | @{ | |
2140 | printf ("num is %d.\n", num); | |
2141 | return; | |
2142 | @} | |
2143 | ||
2144 | /* file2.c */ | |
2145 | ||
2146 | /* num_from_Ada is declared in my_main.adb */ | |
2147 | extern int num_from_Ada; | |
2148 | ||
2149 | int get_num (void) | |
2150 | @{ | |
2151 | return num_from_Ada; | |
2152 | @} | |
2153 | @end smallexample | |
2154 | ||
2155 | @smallexample @c ada | |
2156 | -- my_main.adb | |
2157 | procedure My_Main is | |
2158 | ||
2159 | -- Declare then export an Integer entity called num_from_Ada | |
2160 | My_Num : Integer := 10; | |
2161 | pragma Export (C, My_Num, "num_from_Ada"); | |
2162 | ||
2163 | -- Declare an Ada function spec for Get_Num, then use | |
2164 | -- C function get_num for the implementation. | |
2165 | function Get_Num return Integer; | |
2166 | pragma Import (C, Get_Num, "get_num"); | |
2167 | ||
2168 | -- Declare an Ada procedure spec for Print_Num, then use | |
2169 | -- C function print_num for the implementation. | |
2170 | procedure Print_Num (Num : Integer); | |
2171 | pragma Import (C, Print_Num, "print_num"); | |
2172 | ||
2173 | begin | |
2174 | Print_Num (Get_Num); | |
2175 | end My_Main; | |
2176 | @end smallexample | |
88e1739c FW |
2177 | |
2178 | @enumerate | |
2179 | @item | |
7cd4527e AC |
2180 | To build this example, first compile the foreign language files to |
2181 | generate object files: | |
88e1739c | 2182 | @smallexample |
7e3d710b AC |
2183 | ^gcc -c file1.c^gcc -c FILE1.C^ |
2184 | ^gcc -c file2.c^gcc -c FILE2.C^ | |
88e1739c FW |
2185 | @end smallexample |
2186 | ||
2187 | @item | |
7cd4527e AC |
2188 | Then, compile the Ada units to produce a set of object files and ALI |
2189 | files: | |
88e1739c FW |
2190 | @smallexample |
2191 | gnatmake ^-c^/ACTIONS=COMPILE^ my_main.adb | |
2192 | @end smallexample | |
2193 | ||
2194 | @item | |
7cd4527e | 2195 | Run the Ada binder on the Ada main program: |
88e1739c FW |
2196 | @smallexample |
2197 | gnatbind my_main.ali | |
2198 | @end smallexample | |
2199 | ||
2200 | @item | |
2201 | Link the Ada main program, the Ada objects and the other language | |
7cd4527e | 2202 | objects: |
88e1739c FW |
2203 | @smallexample |
2204 | gnatlink my_main.ali file1.o file2.o | |
2205 | @end smallexample | |
2206 | @end enumerate | |
2207 | ||
7cd4527e | 2208 | The last three steps can be grouped in a single command: |
88e1739c FW |
2209 | @smallexample |
2210 | gnatmake my_main.adb -largs file1.o file2.o | |
2211 | @end smallexample | |
2212 | ||
2213 | @cindex Binder output file | |
2214 | @noindent | |
7cd4527e AC |
2215 | If the main program is in a language other than Ada, then you may have |
2216 | more than one entry point into the Ada subsystem. You must use a special | |
2217 | binder option to generate callable routines that initialize and | |
2218 | finalize the Ada units (@pxref{Binding with Non-Ada Main Programs}). | |
2219 | Calls to the initialization and finalization routines must be inserted | |
2220 | in the main program, or some other appropriate point in the code. The | |
2221 | call to initialize the Ada units must occur before the first Ada | |
2222 | subprogram is called, and the call to finalize the Ada units must occur | |
2223 | after the last Ada subprogram returns. The binder will place the | |
2224 | initialization and finalization subprograms into the | |
2225 | @file{b~@var{xxx}.adb} file where they can be accessed by your C | |
2226 | sources. To illustrate, we have the following example: | |
2227 | ||
2228 | @smallexample | |
2229 | /* main.c */ | |
2230 | extern void adainit (void); | |
2231 | extern void adafinal (void); | |
2232 | extern int add (int, int); | |
2233 | extern int sub (int, int); | |
2234 | ||
2235 | int main (int argc, char *argv[]) | |
2236 | @{ | |
2237 | int a = 21, b = 7; | |
2238 | ||
2239 | adainit(); | |
2240 | ||
2241 | /* Should print "21 + 7 = 28" */ | |
2242 | printf ("%d + %d = %d\n", a, b, add (a, b)); | |
2243 | /* Should print "21 - 7 = 14" */ | |
2244 | printf ("%d - %d = %d\n", a, b, sub (a, b)); | |
2245 | ||
2246 | adafinal(); | |
2247 | @} | |
2248 | @end smallexample | |
2249 | ||
2250 | @smallexample @c ada | |
2251 | -- unit1.ads | |
2252 | package Unit1 is | |
2253 | function Add (A, B : Integer) return Integer; | |
2254 | pragma Export (C, Add, "add"); | |
2255 | end Unit1; | |
2256 | ||
2257 | -- unit1.adb | |
2258 | package body Unit1 is | |
2259 | function Add (A, B : Integer) return Integer is | |
2260 | begin | |
2261 | return A + B; | |
2262 | end Add; | |
2263 | end Unit1; | |
2264 | ||
2265 | -- unit2.ads | |
2266 | package Unit2 is | |
2267 | function Sub (A, B : Integer) return Integer; | |
2268 | pragma Export (C, Sub, "sub"); | |
2269 | end Unit2; | |
2270 | ||
2271 | -- unit2.adb | |
2272 | package body Unit2 is | |
2273 | function Sub (A, B : Integer) return Integer is | |
2274 | begin | |
2275 | return A - B; | |
2276 | end Sub; | |
2277 | end Unit2; | |
2278 | @end smallexample | |
88e1739c FW |
2279 | |
2280 | @enumerate | |
2281 | @item | |
7cd4527e AC |
2282 | The build procedure for this application is similar to the last |
2283 | example's. First, compile the foreign language files to generate object | |
2284 | files: | |
88e1739c | 2285 | @smallexample |
4edb2be0 | 2286 | ^gcc -c main.c^gcc -c main.c^ |
88e1739c FW |
2287 | @end smallexample |
2288 | ||
2289 | @item | |
7cd4527e AC |
2290 | Next, compile the Ada units to produce a set of object files and ALI |
2291 | files: | |
88e1739c | 2292 | @smallexample |
7cd4527e AC |
2293 | gnatmake ^-c^/ACTIONS=COMPILE^ unit1.adb |
2294 | gnatmake ^-c^/ACTIONS=COMPILE^ unit2.adb | |
88e1739c FW |
2295 | @end smallexample |
2296 | ||
2297 | @item | |
7cd4527e AC |
2298 | Run the Ada binder on every generated ALI file. Make sure to use the |
2299 | @option{-n} option to specify a foreign main program: | |
88e1739c | 2300 | @smallexample |
7cd4527e | 2301 | gnatbind ^-n^/NOMAIN^ unit1.ali unit2.ali |
88e1739c FW |
2302 | @end smallexample |
2303 | ||
2304 | @item | |
7cd4527e AC |
2305 | Link the Ada main program, the Ada objects and the foreign language |
2306 | objects. You need only list the last ALI file here: | |
88e1739c | 2307 | @smallexample |
7cd4527e | 2308 | gnatlink unit2.ali main.o -o exec_file |
88e1739c | 2309 | @end smallexample |
7cd4527e AC |
2310 | |
2311 | This procedure yields a binary executable called @file{exec_file}. | |
88e1739c FW |
2312 | @end enumerate |
2313 | ||
0916df6a RD |
2314 | @noindent |
2315 | Depending on the circumstances (for example when your non-Ada main object | |
2316 | does not provide symbol @code{main}), you may also need to instruct the | |
2317 | GNAT linker not to include the standard startup objects by passing the | |
2318 | @option{^-nostartfiles^/NOSTART_FILES^} switch to @command{gnatlink}. | |
2319 | ||
88e1739c FW |
2320 | @node Calling Conventions |
2321 | @subsection Calling Conventions | |
2322 | @cindex Foreign Languages | |
2323 | @cindex Calling Conventions | |
2324 | GNAT follows standard calling sequence conventions and will thus interface | |
2325 | to any other language that also follows these conventions. The following | |
2326 | Convention identifiers are recognized by GNAT: | |
2327 | ||
7cd4527e | 2328 | @table @code |
88e1739c FW |
2329 | @cindex Interfacing to Ada |
2330 | @cindex Other Ada compilers | |
2331 | @cindex Convention Ada | |
7cd4527e AC |
2332 | @item Ada |
2333 | This indicates that the standard Ada calling sequence will be | |
88e1739c FW |
2334 | used and all Ada data items may be passed without any limitations in the |
2335 | case where GNAT is used to generate both the caller and callee. It is also | |
2336 | possible to mix GNAT generated code and code generated by another Ada | |
2337 | compiler. In this case, the data types should be restricted to simple | |
2338 | cases, including primitive types. Whether complex data types can be passed | |
2339 | depends on the situation. Probably it is safe to pass simple arrays, such | |
2340 | as arrays of integers or floats. Records may or may not work, depending | |
2341 | on whether both compilers lay them out identically. Complex structures | |
2342 | involving variant records, access parameters, tasks, or protected types, | |
2343 | are unlikely to be able to be passed. | |
2344 | ||
2345 | Note that in the case of GNAT running | |
32e209e4 | 2346 | on a platform that supports HP Ada 83, a higher degree of compatibility |
d4aef883 | 2347 | can be guaranteed, and in particular records are laid out in an identical |
88e1739c FW |
2348 | manner in the two compilers. Note also that if output from two different |
2349 | compilers is mixed, the program is responsible for dealing with elaboration | |
2350 | issues. Probably the safest approach is to write the main program in the | |
2351 | version of Ada other than GNAT, so that it takes care of its own elaboration | |
2352 | requirements, and then call the GNAT-generated adainit procedure to ensure | |
2353 | elaboration of the GNAT components. Consult the documentation of the other | |
2354 | Ada compiler for further details on elaboration. | |
2355 | ||
2356 | However, it is not possible to mix the tasking run time of GNAT and | |
32e209e4 CC |
2357 | HP Ada 83, All the tasking operations must either be entirely within |
2358 | GNAT compiled sections of the program, or entirely within HP Ada 83 | |
88e1739c FW |
2359 | compiled sections of the program. |
2360 | ||
2361 | @cindex Interfacing to Assembly | |
2362 | @cindex Convention Assembler | |
7cd4527e AC |
2363 | @item Assembler |
2364 | Specifies assembler as the convention. In practice this has the | |
88e1739c FW |
2365 | same effect as convention Ada (but is not equivalent in the sense of being |
2366 | considered the same convention). | |
2367 | ||
2368 | @cindex Convention Asm | |
2369 | @findex Asm | |
7cd4527e AC |
2370 | @item Asm |
2371 | Equivalent to Assembler. | |
88e1739c FW |
2372 | |
2373 | @cindex Interfacing to COBOL | |
2374 | @cindex Convention COBOL | |
2375 | @findex COBOL | |
7cd4527e AC |
2376 | @item COBOL |
2377 | Data will be passed according to the conventions described | |
e08b38f5 | 2378 | in section B.4 of the Ada Reference Manual. |
88e1739c FW |
2379 | |
2380 | @findex C | |
2381 | @cindex Interfacing to C | |
2382 | @cindex Convention C | |
7cd4527e AC |
2383 | @item C |
2384 | Data will be passed according to the conventions described | |
e08b38f5 | 2385 | in section B.3 of the Ada Reference Manual. |
88e1739c | 2386 | |
7e3d710b | 2387 | A note on interfacing to a C ``varargs'' function: |
7cd4527e | 2388 | @findex C varargs function |
7e3d710b | 2389 | @cindex Interfacing to C varargs function |
bde83138 | 2390 | @cindex varargs function interfaces |
7e3d710b AC |
2391 | |
2392 | @itemize @bullet | |
2393 | @item | |
7cd4527e AC |
2394 | In C, @code{varargs} allows a function to take a variable number of |
2395 | arguments. There is no direct equivalent in this to Ada. One | |
2396 | approach that can be used is to create a C wrapper for each | |
2397 | different profile and then interface to this C wrapper. For | |
2398 | example, to print an @code{int} value using @code{printf}, | |
2399 | create a C function @code{printfi} that takes two arguments, a | |
2400 | pointer to a string and an int, and calls @code{printf}. | |
2401 | Then in the Ada program, use pragma @code{Import} to | |
7e3d710b | 2402 | interface to @code{printfi}. |
7cd4527e | 2403 | |
7e3d710b | 2404 | @item |
7cd4527e AC |
2405 | It may work on some platforms to directly interface to |
2406 | a @code{varargs} function by providing a specific Ada profile | |
ce2e12c2 | 2407 | for a particular call. However, this does not work on |
7cd4527e AC |
2408 | all platforms, since there is no guarantee that the |
2409 | calling sequence for a two argument normal C function | |
2410 | is the same as for calling a @code{varargs} C function with | |
2411 | the same two arguments. | |
7e3d710b | 2412 | @end itemize |
7cd4527e | 2413 | |
88e1739c FW |
2414 | @cindex Convention Default |
2415 | @findex Default | |
7cd4527e AC |
2416 | @item Default |
2417 | Equivalent to C. | |
88e1739c FW |
2418 | |
2419 | @cindex Convention External | |
2420 | @findex External | |
7cd4527e AC |
2421 | @item External |
2422 | Equivalent to C. | |
88e1739c | 2423 | |
7e3d710b | 2424 | @ifclear vms |
88e1739c FW |
2425 | @findex C++ |
2426 | @cindex Interfacing to C++ | |
2427 | @cindex Convention C++ | |
0916df6a | 2428 | @item C_Plus_Plus (or CPP) |
7cd4527e | 2429 | This stands for C++. For most purposes this is identical to C. |
88e1739c FW |
2430 | See the separate description of the specialized GNAT pragmas relating to |
2431 | C++ interfacing for further details. | |
7e3d710b | 2432 | @end ifclear |
88e1739c FW |
2433 | |
2434 | @findex Fortran | |
2435 | @cindex Interfacing to Fortran | |
2436 | @cindex Convention Fortran | |
7cd4527e AC |
2437 | @item Fortran |
2438 | Data will be passed according to the conventions described | |
e08b38f5 | 2439 | in section B.5 of the Ada Reference Manual. |
88e1739c | 2440 | |
7cd4527e | 2441 | @item Intrinsic |
e08b38f5 | 2442 | This applies to an intrinsic operation, as defined in the Ada |
ce2e12c2 | 2443 | Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram, |
88e1739c FW |
2444 | this means that the body of the subprogram is provided by the compiler itself, |
2445 | usually by means of an efficient code sequence, and that the user does not | |
2e1c9cb4 OH |
2446 | supply an explicit body for it. In an application program, the pragma may |
2447 | be applied to the following sets of names: | |
7cd4527e | 2448 | |
88e1739c FW |
2449 | @itemize @bullet |
2450 | @item | |
7e3d710b AC |
2451 | Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, |
2452 | Shift_Right_Arithmetic. The corresponding subprogram declaration must have | |
88e1739c FW |
2453 | two formal parameters. The |
2454 | first one must be a signed integer type or a modular type with a binary | |
2455 | modulus, and the second parameter must be of type Natural. | |
2456 | The return type must be the same as the type of the first argument. The size | |
2457 | of this type can only be 8, 16, 32, or 64. | |
2e1c9cb4 OH |
2458 | |
2459 | @item | |
2460 | Binary arithmetic operators: ``+'', ``-'', ``*'', ``/'' | |
88e1739c FW |
2461 | The corresponding operator declaration must have parameters and result type |
2462 | that have the same root numeric type (for example, all three are long_float | |
2463 | types). This simplifies the definition of operations that use type checking | |
2464 | to perform dimensional checks: | |
7cd4527e AC |
2465 | |
2466 | @smallexample @c ada | |
88e1739c FW |
2467 | type Distance is new Long_Float; |
2468 | type Time is new Long_Float; | |
2469 | type Velocity is new Long_Float; | |
2470 | function "/" (D : Distance; T : Time) | |
2471 | return Velocity; | |
2472 | pragma Import (Intrinsic, "/"); | |
2473 | @end smallexample | |
7cd4527e | 2474 | |
88e1739c | 2475 | @noindent |
7cd4527e AC |
2476 | This common idiom is often programmed with a generic definition and an |
2477 | explicit body. The pragma makes it simpler to introduce such declarations. | |
2478 | It incurs no overhead in compilation time or code size, because it is | |
2479 | implemented as a single machine instruction. | |
2e1c9cb4 OH |
2480 | |
2481 | @item | |
2482 | General subprogram entities, to bind an Ada subprogram declaration to | |
2483 | a compiler builtin by name with back-ends where such interfaces are | |
2484 | available. A typical example is the set of ``__builtin'' functions | |
2485 | exposed by the GCC back-end, as in the following example: | |
2486 | ||
2487 | @smallexample @c ada | |
2488 | function builtin_sqrt (F : Float) return Float; | |
2489 | pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf"); | |
2490 | @end smallexample | |
2491 | ||
2492 | Most of the GCC builtins are accessible this way, and as for other | |
2493 | import conventions (e.g. C), it is the user's responsibility to ensure | |
2494 | that the Ada subprogram profile matches the underlying builtin | |
2495 | expectations. | |
88e1739c | 2496 | @end itemize |
2e1c9cb4 | 2497 | |
88e1739c FW |
2498 | @noindent |
2499 | ||
7cd4527e | 2500 | @ifset unw |
88e1739c FW |
2501 | @findex Stdcall |
2502 | @cindex Convention Stdcall | |
7cd4527e | 2503 | @item Stdcall |
e08b38f5 | 2504 | This is relevant only to Windows XP/2000/NT implementations of GNAT, |
32e209e4 CC |
2505 | and specifies that the @code{Stdcall} calling sequence will be used, |
2506 | as defined by the NT API. Nevertheless, to ease building | |
2507 | cross-platform bindings this convention will be handled as a @code{C} calling | |
4d0e4612 | 2508 | convention on non-Windows platforms. |
88e1739c FW |
2509 | |
2510 | @findex DLL | |
2511 | @cindex Convention DLL | |
7cd4527e | 2512 | @item DLL |
32e209e4 | 2513 | This is equivalent to @code{Stdcall}. |
88e1739c FW |
2514 | |
2515 | @findex Win32 | |
2516 | @cindex Convention Win32 | |
7cd4527e | 2517 | @item Win32 |
32e209e4 | 2518 | This is equivalent to @code{Stdcall}. |
7cd4527e | 2519 | @end ifset |
88e1739c FW |
2520 | |
2521 | @findex Stubbed | |
2522 | @cindex Convention Stubbed | |
7cd4527e AC |
2523 | @item Stubbed |
2524 | This is a special convention that indicates that the compiler | |
88e1739c | 2525 | should provide a stub body that raises @code{Program_Error}. |
7cd4527e | 2526 | @end table |
88e1739c FW |
2527 | |
2528 | @noindent | |
2529 | GNAT additionally provides a useful pragma @code{Convention_Identifier} | |
dcffd515 | 2530 | that can be used to parameterize conventions and allow additional synonyms |
88e1739c FW |
2531 | to be specified. For example if you have legacy code in which the convention |
2532 | identifier Fortran77 was used for Fortran, you can use the configuration | |
2533 | pragma: | |
2534 | ||
7cd4527e AC |
2535 | @smallexample @c ada |
2536 | pragma Convention_Identifier (Fortran77, Fortran); | |
88e1739c FW |
2537 | @end smallexample |
2538 | ||
2539 | @noindent | |
2540 | And from now on the identifier Fortran77 may be used as a convention | |
2541 | identifier (for example in an @code{Import} pragma) with the same | |
2542 | meaning as Fortran. | |
2543 | ||
7e3d710b | 2544 | @ifclear vms |
88e1739c | 2545 | @node Building Mixed Ada & C++ Programs |
7e3d710b | 2546 | @section Building Mixed Ada and C++ Programs |
88e1739c FW |
2547 | |
2548 | @noindent | |
7cd4527e AC |
2549 | A programmer inexperienced with mixed-language development may find that |
2550 | building an application containing both Ada and C++ code can be a | |
e08b38f5 | 2551 | challenge. This section gives a few |
7cd4527e | 2552 | hints that should make this task easier. The first section addresses |
e08b38f5 VC |
2553 | the differences between interfacing with C and interfacing with C++. |
2554 | The second section | |
7cd4527e AC |
2555 | looks into the delicate problem of linking the complete application from |
2556 | its Ada and C++ parts. The last section gives some hints on how the GNAT | |
e08b38f5 | 2557 | run-time library can be adapted in order to allow inter-language dispatching |
7cd4527e | 2558 | with a new C++ compiler. |
88e1739c FW |
2559 | |
2560 | @menu | |
2561 | * Interfacing to C++:: | |
2562 | * Linking a Mixed C++ & Ada Program:: | |
2563 | * A Simple Example:: | |
9e895ab5 | 2564 | * Interfacing with C++ constructors:: |
0916df6a | 2565 | * Interfacing with C++ at the Class Level:: |
88e1739c FW |
2566 | @end menu |
2567 | ||
2568 | @node Interfacing to C++ | |
2569 | @subsection Interfacing to C++ | |
2570 | ||
2571 | @noindent | |
0916df6a RD |
2572 | GNAT supports interfacing with the G++ compiler (or any C++ compiler |
2573 | generating code that is compatible with the G++ Application Binary | |
2574 | Interface ---see http://www.codesourcery.com/archives/cxx-abi). | |
88e1739c FW |
2575 | |
2576 | @noindent | |
7cd4527e | 2577 | Interfacing can be done at 3 levels: simple data, subprograms, and |
1992bbd9 RW |
2578 | classes. In the first two cases, GNAT offers a specific @code{Convention |
2579 | C_Plus_Plus} (or @code{CPP}) that behaves exactly like @code{Convention C}. | |
51ec70b8 AC |
2580 | Usually, C++ mangles the names of subprograms. To generate proper mangled |
2581 | names automatically, see @ref{Generating Ada Bindings for C and C++ headers}). | |
2582 | This problem can also be addressed manually in two ways: | |
2583 | ||
88e1739c FW |
2584 | @itemize @bullet |
2585 | @item | |
2586 | by modifying the C++ code in order to force a C convention using | |
7cd4527e | 2587 | the @code{extern "C"} syntax. |
88e1739c FW |
2588 | |
2589 | @item | |
51ec70b8 AC |
2590 | by figuring out the mangled name (using e.g. @command{nm}) and using it as the |
2591 | Link_Name argument of the pragma import. | |
88e1739c FW |
2592 | @end itemize |
2593 | ||
2594 | @noindent | |
2595 | Interfacing at the class level can be achieved by using the GNAT specific | |
b2e74434 RW |
2596 | pragmas such as @code{CPP_Constructor}. @xref{Interfacing to C++,,, |
2597 | gnat_rm, GNAT Reference Manual}, for additional information. | |
88e1739c FW |
2598 | |
2599 | @node Linking a Mixed C++ & Ada Program | |
2600 | @subsection Linking a Mixed C++ & Ada Program | |
2601 | ||
2602 | @noindent | |
2603 | Usually the linker of the C++ development system must be used to link | |
2604 | mixed applications because most C++ systems will resolve elaboration | |
2605 | issues (such as calling constructors on global class instances) | |
2606 | transparently during the link phase. GNAT has been adapted to ease the | |
2607 | use of a foreign linker for the last phase. Three cases can be | |
2608 | considered: | |
2609 | @enumerate | |
2610 | ||
2611 | @item | |
7cd4527e AC |
2612 | Using GNAT and G++ (GNU C++ compiler) from the same GCC installation: |
2613 | The C++ linker can simply be called by using the C++ specific driver | |
51ec70b8 AC |
2614 | called @code{g++}. |
2615 | ||
2616 | Note that if the C++ code uses inline functions, you will need to | |
2617 | compile your C++ code with the @code{-fkeep-inline-functions} switch in | |
2618 | order to provide an existing function implementation that the Ada code can | |
2619 | link with. | |
88e1739c FW |
2620 | |
2621 | @smallexample | |
51ec70b8 AC |
2622 | $ g++ -c -fkeep-inline-functions file1.C |
2623 | $ g++ -c -fkeep-inline-functions file2.C | |
2624 | $ gnatmake ada_unit -largs file1.o file2.o --LINK=g++ | |
88e1739c FW |
2625 | @end smallexample |
2626 | ||
2627 | @item | |
7cd4527e | 2628 | Using GNAT and G++ from two different GCC installations: If both |
443b3472 RW |
2629 | compilers are on the @env{PATH}, the previous method may be used. It is |
2630 | important to note that environment variables such as | |
2631 | @env{C_INCLUDE_PATH}, @env{GCC_EXEC_PREFIX}, @env{BINUTILS_ROOT}, and | |
2632 | @env{GCC_ROOT} will affect both compilers | |
7cd4527e AC |
2633 | at the same time and may make one of the two compilers operate |
2634 | improperly if set during invocation of the wrong compiler. It is also | |
2635 | very important that the linker uses the proper @file{libgcc.a} GCC | |
2636 | library -- that is, the one from the C++ compiler installation. The | |
1992bbd9 RW |
2637 | implicit link command as suggested in the @command{gnatmake} command |
2638 | from the former example can be replaced by an explicit link command with | |
2639 | the full-verbosity option in order to verify which library is used: | |
88e1739c FW |
2640 | @smallexample |
2641 | $ gnatbind ada_unit | |
2642 | $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ | |
2643 | @end smallexample | |
2644 | If there is a problem due to interfering environment variables, it can | |
7cd4527e | 2645 | be worked around by using an intermediate script. The following example |
88e1739c FW |
2646 | shows the proper script to use when GNAT has not been installed at its |
2647 | default location and g++ has been installed at its default location: | |
2648 | ||
2649 | @smallexample | |
88e1739c FW |
2650 | $ cat ./my_script |
2651 | #!/bin/sh | |
2652 | unset BINUTILS_ROOT | |
2653 | unset GCC_ROOT | |
2654 | c++ $* | |
7cd4527e | 2655 | $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script |
88e1739c FW |
2656 | @end smallexample |
2657 | ||
2658 | @item | |
7cd4527e AC |
2659 | Using a non-GNU C++ compiler: The commands previously described can be |
2660 | used to insure that the C++ linker is used. Nonetheless, you need to add | |
0453ca3d RD |
2661 | a few more parameters to the link command line, depending on the exception |
2662 | mechanism used. | |
2663 | ||
2664 | If the @code{setjmp/longjmp} exception mechanism is used, only the paths | |
2665 | to the libgcc libraries are required: | |
88e1739c FW |
2666 | |
2667 | @smallexample | |
88e1739c FW |
2668 | $ cat ./my_script |
2669 | #!/bin/sh | |
984a64bc | 2670 | CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` |
7cd4527e | 2671 | $ gnatlink ada_unit file1.o file2.o --LINK=./my_script |
88e1739c FW |
2672 | @end smallexample |
2673 | ||
7cd4527e | 2674 | Where CC is the name of the non-GNU C++ compiler. |
88e1739c | 2675 | |
0453ca3d | 2676 | If the @code{zero cost} exception mechanism is used, and the platform |
a1e16658 | 2677 | supports automatic registration of exception tables (e.g.@: Solaris), |
0453ca3d RD |
2678 | paths to more objects are required: |
2679 | ||
2680 | @smallexample | |
2681 | $ cat ./my_script | |
2682 | #!/bin/sh | |
2683 | CC `gcc -print-file-name=crtbegin.o` $* \ | |
2684 | `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \ | |
2685 | `gcc -print-file-name=crtend.o` | |
2686 | $ gnatlink ada_unit file1.o file2.o --LINK=./my_script | |
2687 | @end smallexample | |
2688 | ||
2689 | If the @code{zero cost} exception mechanism is used, and the platform | |
f307415a | 2690 | doesn't support automatic registration of exception tables (e.g.@: HP-UX |
5c30094f | 2691 | or AIX), the simple approach described above will not work and |
0453ca3d RD |
2692 | a pre-linking phase using GNAT will be necessary. |
2693 | ||
88e1739c FW |
2694 | @end enumerate |
2695 | ||
51ec70b8 AC |
2696 | Another alternative is to use the @command{gprbuild} multi-language builder |
2697 | which has a large knowledge base and knows how to link Ada and C++ code | |
2698 | together automatically in most cases. | |
2699 | ||
88e1739c FW |
2700 | @node A Simple Example |
2701 | @subsection A Simple Example | |
2702 | @noindent | |
7cd4527e | 2703 | The following example, provided as part of the GNAT examples, shows how |
88e1739c | 2704 | to achieve procedural interfacing between Ada and C++ in both |
7cd4527e | 2705 | directions. The C++ class A has two methods. The first method is exported |
88e1739c | 2706 | to Ada by the means of an extern C wrapper function. The second method |
7cd4527e | 2707 | calls an Ada subprogram. On the Ada side, The C++ calls are modelled by |
88e1739c | 2708 | a limited record with a layout comparable to the C++ class. The Ada |
7cd4527e AC |
2709 | subprogram, in turn, calls the C++ method. So, starting from the C++ |
2710 | main program, the process passes back and forth between the two | |
2711 | languages. | |
88e1739c FW |
2712 | |
2713 | @noindent | |
7cd4527e | 2714 | Here are the compilation commands: |
88e1739c FW |
2715 | @smallexample |
2716 | $ gnatmake -c simple_cpp_interface | |
51ec70b8 AC |
2717 | $ g++ -c cpp_main.C |
2718 | $ g++ -c ex7.C | |
88e1739c | 2719 | $ gnatbind -n simple_cpp_interface |
51ec70b8 | 2720 | $ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ |
88e1739c FW |
2721 | -lstdc++ ex7.o cpp_main.o |
2722 | @end smallexample | |
7cd4527e | 2723 | |
88e1739c FW |
2724 | @noindent |
2725 | Here are the corresponding sources: | |
2726 | @smallexample | |
2727 | ||
2728 | //cpp_main.C | |
2729 | ||
2730 | #include "ex7.h" | |
2731 | ||
2732 | extern "C" @{ | |
2733 | void adainit (void); | |
2734 | void adafinal (void); | |
2735 | void method1 (A *t); | |
2736 | @} | |
2737 | ||
2738 | void method1 (A *t) | |
2739 | @{ | |
2740 | t->method1 (); | |
2741 | @} | |
2742 | ||
2743 | int main () | |
2744 | @{ | |
2745 | A obj; | |
2746 | adainit (); | |
2747 | obj.method2 (3030); | |
2748 | adafinal (); | |
2749 | @} | |
2750 | ||
2751 | //ex7.h | |
2752 | ||
2753 | class Origin @{ | |
2754 | public: | |
2755 | int o_value; | |
2756 | @}; | |
2757 | class A : public Origin @{ | |
2758 | public: | |
2759 | void method1 (void); | |
f142e9fa | 2760 | void method2 (int v); |
88e1739c FW |
2761 | A(); |
2762 | int a_value; | |
2763 | @}; | |
2764 | ||
2765 | //ex7.C | |
2766 | ||
2767 | #include "ex7.h" | |
2768 | #include <stdio.h> | |
2769 | ||
2770 | extern "C" @{ void ada_method2 (A *t, int v);@} | |
2771 | ||
2772 | void A::method1 (void) | |
2773 | @{ | |
2774 | a_value = 2020; | |
2775 | printf ("in A::method1, a_value = %d \n",a_value); | |
2776 | ||
2777 | @} | |
2778 | ||
2779 | void A::method2 (int v) | |
2780 | @{ | |
2781 | ada_method2 (this, v); | |
2782 | printf ("in A::method2, a_value = %d \n",a_value); | |
2783 | ||
2784 | @} | |
2785 | ||
2786 | A::A(void) | |
2787 | @{ | |
2788 | a_value = 1010; | |
2789 | printf ("in A::A, a_value = %d \n",a_value); | |
2790 | @} | |
e08b38f5 | 2791 | @end smallexample |
88e1739c | 2792 | |
e08b38f5 | 2793 | @smallexample @c ada |
88e1739c | 2794 | -- Ada sources |
e08b38f5 | 2795 | package body Simple_Cpp_Interface is |
88e1739c | 2796 | |
e08b38f5 VC |
2797 | procedure Ada_Method2 (This : in out A; V : Integer) is |
2798 | begin | |
88e1739c FW |
2799 | Method1 (This); |
2800 | This.A_Value := V; | |
e08b38f5 | 2801 | end Ada_Method2; |
88e1739c | 2802 | |
e08b38f5 | 2803 | end Simple_Cpp_Interface; |
88e1739c | 2804 | |
e08b38f5 VC |
2805 | with System; |
2806 | package Simple_Cpp_Interface is | |
2807 | type A is limited | |
2808 | record | |
0916df6a | 2809 | Vptr : System.Address; |
88e1739c FW |
2810 | O_Value : Integer; |
2811 | A_Value : Integer; | |
e08b38f5 VC |
2812 | end record; |
2813 | pragma Convention (C, A); | |
88e1739c | 2814 | |
e08b38f5 VC |
2815 | procedure Method1 (This : in out A); |
2816 | pragma Import (C, Method1); | |
88e1739c | 2817 | |
e08b38f5 VC |
2818 | procedure Ada_Method2 (This : in out A; V : Integer); |
2819 | pragma Export (C, Ada_Method2); | |
88e1739c | 2820 | |
e08b38f5 | 2821 | end Simple_Cpp_Interface; |
88e1739c FW |
2822 | @end smallexample |
2823 | ||
9e895ab5 AC |
2824 | @node Interfacing with C++ constructors |
2825 | @subsection Interfacing with C++ constructors | |
2826 | @noindent | |
2827 | ||
2828 | In order to interface with C++ constructors GNAT provides the | |
2829 | @code{pragma CPP_Constructor} (@xref{Interfacing to C++,,, | |
2830 | gnat_rm, GNAT Reference Manual}, for additional information). | |
2831 | In this section we present some common uses of C++ constructors | |
2832 | in mixed-languages programs in GNAT. | |
2833 | ||
2834 | Let us assume that we need to interface with the following | |
2835 | C++ class: | |
2836 | ||
2837 | @smallexample | |
2838 | @b{class} Root @{ | |
2839 | @b{public}: | |
2840 | int a_value; | |
2841 | int b_value; | |
2842 | @b{virtual} int Get_Value (); | |
2843 | Root(); // Default constructor | |
2844 | Root(int v); // 1st non-default constructor | |
2845 | Root(int v, int w); // 2nd non-default constructor | |
2846 | @}; | |
2847 | @end smallexample | |
2848 | ||
2849 | For this purpose we can write the following package spec (further | |
2850 | information on how to build this spec is available in | |
2851 | @ref{Interfacing with C++ at the Class Level} and | |
2852 | @ref{Generating Ada Bindings for C and C++ headers}). | |
2853 | ||
2854 | @smallexample @c ada | |
2855 | with Interfaces.C; use Interfaces.C; | |
2856 | package Pkg_Root is | |
2857 | type Root is tagged limited record | |
2858 | A_Value : int; | |
2859 | B_Value : int; | |
2860 | end record; | |
2861 | pragma Import (CPP, Root); | |
2862 | ||
2863 | function Get_Value (Obj : Root) return int; | |
2864 | pragma Import (CPP, Get_Value); | |
2865 | ||
7b4db06c | 2866 | function Constructor return Root; |
9e895ab5 AC |
2867 | pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev"); |
2868 | ||
7b4db06c | 2869 | function Constructor (v : Integer) return Root; |
9e895ab5 AC |
2870 | pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei"); |
2871 | ||
7b4db06c | 2872 | function Constructor (v, w : Integer) return Root; |
9e895ab5 AC |
2873 | pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii"); |
2874 | end Pkg_Root; | |
2875 | @end smallexample | |
2876 | ||
2877 | On the Ada side the constructor is represented by a function (whose | |
2878 | name is arbitrary) that returns the classwide type corresponding to | |
3743d5bd AC |
2879 | the imported C++ class. Although the constructor is described as a |
2880 | function, it is typically a procedure with an extra implicit argument | |
2881 | (the object being initialized) at the implementation level. GNAT | |
2882 | issues the appropriate call, whatever it is, to get the object | |
2883 | properly initialized. | |
9e895ab5 | 2884 | |
3743d5bd AC |
2885 | Constructors can only appear in the following contexts: |
2886 | ||
2887 | @itemize @bullet | |
2888 | @item | |
2889 | On the right side of an initialization of an object of type @var{T}. | |
2890 | @item | |
2891 | On the right side of an initialization of a record component of type @var{T}. | |
2892 | @item | |
2893 | In an Ada 2005 limited aggregate. | |
2894 | @item | |
2895 | In an Ada 2005 nested limited aggregate. | |
2896 | @item | |
2897 | In an Ada 2005 limited aggregate that initializes an object built in | |
2898 | place by an extended return statement. | |
2899 | @end itemize | |
2900 | ||
2901 | @noindent | |
9e895ab5 AC |
2902 | In a declaration of an object whose type is a class imported from C++, |
2903 | either the default C++ constructor is implicitly called by GNAT, or | |
2904 | else the required C++ constructor must be explicitly called in the | |
2905 | expression that initializes the object. For example: | |
2906 | ||
2907 | @smallexample @c ada | |
2908 | Obj1 : Root; | |
2909 | Obj2 : Root := Constructor; | |
2910 | Obj3 : Root := Constructor (v => 10); | |
2911 | Obj4 : Root := Constructor (30, 40); | |
2912 | @end smallexample | |
2913 | ||
2914 | The first two declarations are equivalent: in both cases the default C++ | |
2915 | constructor is invoked (in the former case the call to the constructor is | |
2916 | implicit, and in the latter case the call is explicit in the object | |
2917 | declaration). @code{Obj3} is initialized by the C++ non-default constructor | |
2918 | that takes an integer argument, and @code{Obj4} is initialized by the | |
2919 | non-default C++ constructor that takes two integers. | |
2920 | ||
2921 | Let us derive the imported C++ class in the Ada side. For example: | |
2922 | ||
2923 | @smallexample @c ada | |
2924 | type DT is new Root with record | |
2925 | C_Value : Natural := 2009; | |
2926 | end record; | |
2927 | @end smallexample | |
2928 | ||
2929 | In this case the components DT inherited from the C++ side must be | |
2930 | initialized by a C++ constructor, and the additional Ada components | |
2931 | of type DT are initialized by GNAT. The initialization of such an | |
2932 | object is done either by default, or by means of a function returning | |
69a0c174 | 2933 | an aggregate of type DT, or by means of an extension aggregate. |
9e895ab5 AC |
2934 | |
2935 | @smallexample @c ada | |
2936 | Obj5 : DT; | |
2937 | Obj6 : DT := Function_Returning_DT (50); | |
4e0d20ca | 2938 | Obj7 : DT := (Constructor (30,40) with C_Value => 50); |
9e895ab5 AC |
2939 | @end smallexample |
2940 | ||
2941 | The declaration of @code{Obj5} invokes the default constructors: the | |
2942 | C++ default constructor of the parent type takes care of the initialization | |
2943 | of the components inherited from Root, and GNAT takes care of the default | |
2944 | initialization of the additional Ada components of type DT (that is, | |
2945 | @code{C_Value} is initialized to value 2009). The order of invocation of | |
2946 | the constructors is consistent with the order of elaboration required by | |
2947 | Ada and C++. That is, the constructor of the parent type is always called | |
2948 | before the constructor of the derived type. | |
2949 | ||
2950 | Let us now consider a record that has components whose type is imported | |
2951 | from C++. For example: | |
2952 | ||
2953 | @smallexample @c ada | |
2954 | type Rec1 is limited record | |
2955 | Data1 : Root := Constructor (10); | |
2956 | Value : Natural := 1000; | |
2957 | end record; | |
2958 | ||
2959 | type Rec2 (D : Integer := 20) is limited record | |
2960 | Rec : Rec1; | |
2961 | Data2 : Root := Constructor (D, 30); | |
2962 | end record; | |
2963 | @end smallexample | |
2964 | ||
2965 | The initialization of an object of type @code{Rec2} will call the | |
2966 | non-default C++ constructors specified for the imported components. | |
2967 | For example: | |
2968 | ||
2969 | @smallexample @c ada | |
4e0d20ca | 2970 | Obj8 : Rec2 (40); |
9e895ab5 AC |
2971 | @end smallexample |
2972 | ||
2973 | Using Ada 2005 we can use limited aggregates to initialize an object | |
2974 | invoking C++ constructors that differ from those specified in the type | |
2975 | declarations. For example: | |
2976 | ||
2977 | @smallexample @c ada | |
4e0d20ca | 2978 | Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16), |
9e895ab5 AC |
2979 | others => <>), |
2980 | others => <>); | |
2981 | @end smallexample | |
2982 | ||
2983 | The above declaration uses an Ada 2005 limited aggregate to | |
4e0d20ca | 2984 | initialize @code{Obj9}, and the C++ constructor that has two integer |
9e895ab5 AC |
2985 | arguments is invoked to initialize the @code{Data1} component instead |
2986 | of the constructor specified in the declaration of type @code{Rec1}. In | |
2987 | Ada 2005 the box in the aggregate indicates that unspecified components | |
2988 | are initialized using the expression (if any) available in the component | |
2989 | declaration. That is, in this case discriminant @code{D} is initialized | |
2990 | to value @code{20}, @code{Value} is initialized to value 1000, and the | |
2991 | non-default C++ constructor that handles two integers takes care of | |
2992 | initializing component @code{Data2} with values @code{20,30}. | |
2993 | ||
2994 | In Ada 2005 we can use the extended return statement to build the Ada | |
2995 | equivalent to C++ non-default constructors. For example: | |
2996 | ||
2997 | @smallexample @c ada | |
2998 | function Constructor (V : Integer) return Rec2 is | |
2999 | begin | |
3000 | return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20), | |
3001 | others => <>), | |
3002 | others => <>) do | |
3003 | -- Further actions required for construction of | |
3004 | -- objects of type Rec2 | |
3005 | ... | |
3006 | end record; | |
3007 | end Constructor; | |
3008 | @end smallexample | |
3009 | ||
3010 | In this example the extended return statement construct is used to | |
3011 | build in place the returned object whose components are initialized | |
3012 | by means of a limited aggregate. Any further action associated with | |
3013 | the constructor can be placed inside the construct. | |
3014 | ||
0916df6a RD |
3015 | @node Interfacing with C++ at the Class Level |
3016 | @subsection Interfacing with C++ at the Class Level | |
88e1739c | 3017 | @noindent |
0916df6a RD |
3018 | In this section we demonstrate the GNAT features for interfacing with |
3019 | C++ by means of an example making use of Ada 2005 abstract interface | |
3020 | types. This example consists of a classification of animals; classes | |
3021 | have been used to model our main classification of animals, and | |
3022 | interfaces provide support for the management of secondary | |
3023 | classifications. We first demonstrate a case in which the types and | |
3024 | constructors are defined on the C++ side and imported from the Ada | |
3025 | side, and latter the reverse case. | |
3026 | ||
3027 | The root of our derivation will be the @code{Animal} class, with a | |
3028 | single private attribute (the @code{Age} of the animal) and two public | |
3029 | primitives to set and get the value of this attribute. | |
3030 | ||
3031 | @smallexample | |
3032 | @b{class} Animal @{ | |
3033 | @b{public}: | |
3034 | @b{virtual} void Set_Age (int New_Age); | |
3035 | @b{virtual} int Age (); | |
3036 | @b{private}: | |
3037 | int Age_Count; | |
3038 | @}; | |
3039 | @end smallexample | |
3040 | ||
3041 | Abstract interface types are defined in C++ by means of classes with pure | |
3042 | virtual functions and no data members. In our example we will use two | |
3043 | interfaces that provide support for the common management of @code{Carnivore} | |
3044 | and @code{Domestic} animals: | |
3045 | ||
3046 | @smallexample | |
3047 | @b{class} Carnivore @{ | |
3048 | @b{public}: | |
3049 | @b{virtual} int Number_Of_Teeth () = 0; | |
3050 | @}; | |
3051 | ||
3052 | @b{class} Domestic @{ | |
3053 | @b{public}: | |
3054 | @b{virtual void} Set_Owner (char* Name) = 0; | |
3055 | @}; | |
3056 | @end smallexample | |
3057 | ||
3058 | Using these declarations, we can now say that a @code{Dog} is an animal that is | |
3059 | both Carnivore and Domestic, that is: | |
3060 | ||
3061 | @smallexample | |
3062 | @b{class} Dog : Animal, Carnivore, Domestic @{ | |
3063 | @b{public}: | |
3064 | @b{virtual} int Number_Of_Teeth (); | |
3065 | @b{virtual} void Set_Owner (char* Name); | |
3066 | ||
3067 | Dog(); // Constructor | |
3068 | @b{private}: | |
3069 | int Tooth_Count; | |
3070 | char *Owner; | |
3071 | @}; | |
3072 | @end smallexample | |
3073 | ||
3074 | In the following examples we will assume that the previous declarations are | |
3075 | located in a file named @code{animals.h}. The following package demonstrates | |
3076 | how to import these C++ declarations from the Ada side: | |
3077 | ||
e08b38f5 VC |
3078 | @smallexample @c ada |
3079 | with Interfaces.C.Strings; use Interfaces.C.Strings; | |
3080 | package Animals is | |
3081 | type Carnivore is interface; | |
3082 | pragma Convention (C_Plus_Plus, Carnivore); | |
3083 | function Number_Of_Teeth (X : Carnivore) | |
3084 | return Natural is abstract; | |
3085 | ||
3086 | type Domestic is interface; | |
3087 | pragma Convention (C_Plus_Plus, Set_Owner); | |
3088 | procedure Set_Owner | |
3089 | (X : in out Domestic; | |
3090 | Name : Chars_Ptr) is abstract; | |
3091 | ||
3092 | type Animal is tagged record | |
0916df6a | 3093 | Age : Natural := 0; |
e08b38f5 VC |
3094 | end record; |
3095 | pragma Import (C_Plus_Plus, Animal); | |
0916df6a | 3096 | |
e08b38f5 VC |
3097 | procedure Set_Age (X : in out Animal; Age : Integer); |
3098 | pragma Import (C_Plus_Plus, Set_Age); | |
0916df6a | 3099 | |
e08b38f5 VC |
3100 | function Age (X : Animal) return Integer; |
3101 | pragma Import (C_Plus_Plus, Age); | |
0916df6a | 3102 | |
e08b38f5 | 3103 | type Dog is new Animal and Carnivore and Domestic with record |
0916df6a RD |
3104 | Tooth_Count : Natural; |
3105 | Owner : String (1 .. 30); | |
e08b38f5 VC |
3106 | end record; |
3107 | pragma Import (C_Plus_Plus, Dog); | |
0916df6a | 3108 | |
e08b38f5 VC |
3109 | function Number_Of_Teeth (A : Dog) return Integer; |
3110 | pragma Import (C_Plus_Plus, Number_Of_Teeth); | |
0916df6a | 3111 | |
e08b38f5 VC |
3112 | procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); |
3113 | pragma Import (C_Plus_Plus, Set_Owner); | |
0916df6a | 3114 | |
7b4db06c | 3115 | function New_Dog return Dog; |
e08b38f5 VC |
3116 | pragma CPP_Constructor (New_Dog); |
3117 | pragma Import (CPP, New_Dog, "_ZN3DogC2Ev"); | |
3118 | end Animals; | |
0916df6a RD |
3119 | @end smallexample |
3120 | ||
3121 | Thanks to the compatibility between GNAT run-time structures and the C++ ABI, | |
3122 | interfacing with these C++ classes is easy. The only requirement is that all | |
3123 | the primitives and components must be declared exactly in the same order in | |
3124 | the two languages. | |
3125 | ||
3126 | Regarding the abstract interfaces, we must indicate to the GNAT compiler by | |
3127 | means of a @code{pragma Convention (C_Plus_Plus)}, the convention used to pass | |
3128 | the arguments to the called primitives will be the same as for C++. For the | |
3129 | imported classes we use @code{pragma Import} with convention @code{C_Plus_Plus} | |
3130 | to indicate that they have been defined on the C++ side; this is required | |
3131 | because the dispatch table associated with these tagged types will be built | |
3132 | in the C++ side and therefore will not contain the predefined Ada primitives | |
3133 | which Ada would otherwise expect. | |
3134 | ||
3135 | As the reader can see there is no need to indicate the C++ mangled names | |
3136 | associated with each subprogram because it is assumed that all the calls to | |
3137 | these primitives will be dispatching calls. The only exception is the | |
3138 | constructor, which must be registered with the compiler by means of | |
3139 | @code{pragma CPP_Constructor} and needs to provide its associated C++ | |
3140 | mangled name because the Ada compiler generates direct calls to it. | |
3141 | ||
3142 | With the above packages we can now declare objects of type Dog on the Ada side | |
3143 | and dispatch calls to the corresponding subprograms on the C++ side. We can | |
3144 | also extend the tagged type Dog with further fields and primitives, and | |
3145 | override some of its C++ primitives on the Ada side. For example, here we have | |
3146 | a type derivation defined on the Ada side that inherits all the dispatching | |
3147 | primitives of the ancestor from the C++ side. | |
3148 | ||
3149 | @smallexample | |
3150 | @b{with} Animals; @b{use} Animals; | |
3151 | @b{package} Vaccinated_Animals @b{is} | |
3152 | @b{type} Vaccinated_Dog @b{is new} Dog @b{with null record}; | |
3153 | @b{function} Vaccination_Expired (A : Vaccinated_Dog) @b{return} Boolean; | |
3154 | @b{end} Vaccinated_Animals; | |
3155 | @end smallexample | |
3156 | ||
3157 | It is important to note that, because of the ABI compatibility, the programmer | |
3158 | does not need to add any further information to indicate either the object | |
3159 | layout or the dispatch table entry associated with each dispatching operation. | |
3160 | ||
3161 | Now let us define all the types and constructors on the Ada side and export | |
3162 | them to C++, using the same hierarchy of our previous example: | |
3163 | ||
e08b38f5 VC |
3164 | @smallexample @c ada |
3165 | with Interfaces.C.Strings; | |
3166 | use Interfaces.C.Strings; | |
3167 | package Animals is | |
3168 | type Carnivore is interface; | |
3169 | pragma Convention (C_Plus_Plus, Carnivore); | |
3170 | function Number_Of_Teeth (X : Carnivore) | |
3171 | return Natural is abstract; | |
3172 | ||
3173 | type Domestic is interface; | |
3174 | pragma Convention (C_Plus_Plus, Set_Owner); | |
3175 | procedure Set_Owner | |
3176 | (X : in out Domestic; | |
3177 | Name : Chars_Ptr) is abstract; | |
3178 | ||
3179 | type Animal is tagged record | |
0916df6a | 3180 | Age : Natural := 0; |
e08b38f5 VC |
3181 | end record; |
3182 | pragma Convention (C_Plus_Plus, Animal); | |
0916df6a | 3183 | |
e08b38f5 VC |
3184 | procedure Set_Age (X : in out Animal; Age : Integer); |
3185 | pragma Export (C_Plus_Plus, Set_Age); | |
0916df6a | 3186 | |
e08b38f5 VC |
3187 | function Age (X : Animal) return Integer; |
3188 | pragma Export (C_Plus_Plus, Age); | |
0916df6a | 3189 | |
e08b38f5 | 3190 | type Dog is new Animal and Carnivore and Domestic with record |
0916df6a RD |
3191 | Tooth_Count : Natural; |
3192 | Owner : String (1 .. 30); | |
e08b38f5 VC |
3193 | end record; |
3194 | pragma Convention (C_Plus_Plus, Dog); | |
0916df6a | 3195 | |
e08b38f5 VC |
3196 | function Number_Of_Teeth (A : Dog) return Integer; |
3197 | pragma Export (C_Plus_Plus, Number_Of_Teeth); | |
0916df6a | 3198 | |
e08b38f5 VC |
3199 | procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); |
3200 | pragma Export (C_Plus_Plus, Set_Owner); | |
0916df6a | 3201 | |
e08b38f5 VC |
3202 | function New_Dog return Dog'Class; |
3203 | pragma Export (C_Plus_Plus, New_Dog); | |
3204 | end Animals; | |
0916df6a RD |
3205 | @end smallexample |
3206 | ||
3207 | Compared with our previous example the only difference is the use of | |
3208 | @code{pragma Export} to indicate to the GNAT compiler that the primitives will | |
3209 | be available to C++. Thanks to the ABI compatibility, on the C++ side there is | |
3210 | nothing else to be done; as explained above, the only requirement is that all | |
3211 | the primitives and components are declared in exactly the same order. | |
3212 | ||
3213 | For completeness, let us see a brief C++ main program that uses the | |
3214 | declarations available in @code{animals.h} (presented in our first example) to | |
3215 | import and use the declarations from the Ada side, properly initializing and | |
3216 | finalizing the Ada run-time system along the way: | |
3217 | ||
3218 | @smallexample | |
3219 | @b{#include} "animals.h" | |
3220 | @b{#include} <iostream> | |
3221 | @b{using namespace} std; | |
3222 | ||
d488f6ea RW |
3223 | void Check_Carnivore (Carnivore *obj) @{@dots{}@} |
3224 | void Check_Domestic (Domestic *obj) @{@dots{}@} | |
3225 | void Check_Animal (Animal *obj) @{@dots{}@} | |
3226 | void Check_Dog (Dog *obj) @{@dots{}@} | |
0916df6a RD |
3227 | |
3228 | @b{extern} "C" @{ | |
3229 | void adainit (void); | |
3230 | void adafinal (void); | |
3231 | Dog* new_dog (); | |
3232 | @} | |
3233 | ||
3234 | void test () | |
3235 | @{ | |
3236 | Dog *obj = new_dog(); // Ada constructor | |
3237 | Check_Carnivore (obj); // Check secondary DT | |
3238 | Check_Domestic (obj); // Check secondary DT | |
3239 | Check_Animal (obj); // Check primary DT | |
3240 | Check_Dog (obj); // Check primary DT | |
3241 | @} | |
3242 | ||
3243 | int main () | |
3244 | @{ | |
3245 | adainit (); test(); adafinal (); | |
3246 | return 0; | |
3247 | @} | |
3248 | @end smallexample | |
88e1739c FW |
3249 | |
3250 | @node Comparison between GNAT and C/C++ Compilation Models | |
3251 | @section Comparison between GNAT and C/C++ Compilation Models | |
3252 | ||
3253 | @noindent | |
3254 | The GNAT model of compilation is close to the C and C++ models. You can | |
3255 | think of Ada specs as corresponding to header files in C. As in C, you | |
3256 | don't need to compile specs; they are compiled when they are used. The | |
3257 | Ada @code{with} is similar in effect to the @code{#include} of a C | |
3258 | header. | |
3259 | ||
3260 | One notable difference is that, in Ada, you may compile specs separately | |
3261 | to check them for semantic and syntactic accuracy. This is not always | |
3262 | possible with C headers because they are fragments of programs that have | |
3263 | less specific syntactic or semantic rules. | |
3264 | ||
3265 | The other major difference is the requirement for running the binder, | |
3266 | which performs two important functions. First, it checks for | |
3267 | consistency. In C or C++, the only defense against assembling | |
3268 | inconsistent programs lies outside the compiler, in a makefile, for | |
3269 | example. The binder satisfies the Ada requirement that it be impossible | |
3270 | to construct an inconsistent program when the compiler is used in normal | |
3271 | mode. | |
3272 | ||
3273 | @cindex Elaboration order control | |
3274 | The other important function of the binder is to deal with elaboration | |
3275 | issues. There are also elaboration issues in C++ that are handled | |
3276 | automatically. This automatic handling has the advantage of being | |
3277 | simpler to use, but the C++ programmer has no control over elaboration. | |
3278 | Where @code{gnatbind} might complain there was no valid order of | |
3279 | elaboration, a C++ compiler would simply construct a program that | |
3280 | malfunctioned at run time. | |
7e3d710b | 3281 | @end ifclear |
88e1739c FW |
3282 | |
3283 | @node Comparison between GNAT and Conventional Ada Library Models | |
3284 | @section Comparison between GNAT and Conventional Ada Library Models | |
3285 | ||
3286 | @noindent | |
7e3d710b AC |
3287 | This section is intended for Ada programmers who have |
3288 | used an Ada compiler implementing the traditional Ada library | |
e08b38f5 | 3289 | model, as described in the Ada Reference Manual. |
88e1739c FW |
3290 | |
3291 | @cindex GNAT library | |
7e3d710b | 3292 | In GNAT, there is no ``library'' in the normal sense. Instead, the set of |
88e1739c FW |
3293 | source files themselves acts as the library. Compiling Ada programs does |
3294 | not generate any centralized information, but rather an object file and | |
3295 | a ALI file, which are of interest only to the binder and linker. | |
3296 | In a traditional system, the compiler reads information not only from | |
3297 | the source file being compiled, but also from the centralized library. | |
3298 | This means that the effect of a compilation depends on what has been | |
3299 | previously compiled. In particular: | |
3300 | ||
3301 | @itemize @bullet | |
3302 | @item | |
3303 | When a unit is @code{with}'ed, the unit seen by the compiler corresponds | |
3304 | to the version of the unit most recently compiled into the library. | |
3305 | ||
3306 | @item | |
3307 | Inlining is effective only if the necessary body has already been | |
3308 | compiled into the library. | |
3309 | ||
3310 | @item | |
3311 | Compiling a unit may obsolete other units in the library. | |
3312 | @end itemize | |
3313 | ||
3314 | @noindent | |
3315 | In GNAT, compiling one unit never affects the compilation of any other | |
3316 | units because the compiler reads only source files. Only changes to source | |
3317 | files can affect the results of a compilation. In particular: | |
3318 | ||
3319 | @itemize @bullet | |
3320 | @item | |
3321 | When a unit is @code{with}'ed, the unit seen by the compiler corresponds | |
3322 | to the source version of the unit that is currently accessible to the | |
3323 | compiler. | |
3324 | ||
3325 | @item | |
3326 | @cindex Inlining | |
3327 | Inlining requires the appropriate source files for the package or | |
3328 | subprogram bodies to be available to the compiler. Inlining is always | |
3329 | effective, independent of the order in which units are complied. | |
3330 | ||
3331 | @item | |
3332 | Compiling a unit never affects any other compilations. The editing of | |
3333 | sources may cause previous compilations to be out of date if they | |
3334 | depended on the source file being modified. | |
3335 | @end itemize | |
3336 | ||
3337 | @noindent | |
3338 | The most important result of these differences is that order of compilation | |
3339 | is never significant in GNAT. There is no situation in which one is | |
3340 | required to do one compilation before another. What shows up as order of | |
3341 | compilation requirements in the traditional Ada library becomes, in | |
3342 | GNAT, simple source dependencies; in other words, there is only a set | |
3343 | of rules saying what source files must be present when a file is | |
3344 | compiled. | |
3345 | ||
7cd4527e AC |
3346 | @ifset vms |
3347 | @node Placement of temporary files | |
3348 | @section Placement of temporary files | |
3349 | @cindex Temporary files (user control over placement) | |
3350 | ||
3351 | @noindent | |
3352 | GNAT creates temporary files in the directory designated by the environment | |
3353 | variable @env{TMPDIR}. | |
3354 | (See the HP @emph{C RTL Reference Manual} on the function @code{getenv()} | |
3355 | for detailed information on how environment variables are resolved. | |
3356 | For most users the easiest way to make use of this feature is to simply | |
3357 | define @env{TMPDIR} as a job level logical name). | |
3358 | For example, if you wish to use a Ramdisk (assuming DECRAM is installed) | |
3359 | for compiler temporary files, then you can include something like the | |
3360 | following command in your @file{LOGIN.COM} file: | |
3361 | ||
3362 | @smallexample | |
3363 | $ define/job TMPDIR "/disk$scratchram/000000/temp/" | |
3364 | @end smallexample | |
3365 | ||
3366 | @noindent | |
3367 | If @env{TMPDIR} is not defined, then GNAT uses the directory designated by | |
3368 | @env{TMP}; if @env{TMP} is not defined, then GNAT uses the directory | |
3369 | designated by @env{TEMP}. | |
3370 | If none of these environment variables are defined then GNAT uses the | |
3371 | directory designated by the logical name @code{SYS$SCRATCH:} | |
3372 | (by default the user's home directory). If all else fails | |
3373 | GNAT uses the current directory for temporary files. | |
3374 | @end ifset | |
3375 | ||
7cd4527e | 3376 | @c ************************* |
c2658843 AC |
3377 | @node Compiling with gcc |
3378 | @chapter Compiling with @command{gcc} | |
88e1739c FW |
3379 | |
3380 | @noindent | |
984a64bc | 3381 | This chapter discusses how to compile Ada programs using the @command{gcc} |
88e1739c FW |
3382 | command. It also describes the set of switches |
3383 | that can be used to control the behavior of the compiler. | |
3384 | @menu | |
3385 | * Compiling Programs:: | |
3386 | * Switches for gcc:: | |
3387 | * Search Paths and the Run-Time Library (RTL):: | |
3388 | * Order of Compilation Issues:: | |
3389 | * Examples:: | |
3390 | @end menu | |
3391 | ||
3392 | @node Compiling Programs | |
3393 | @section Compiling Programs | |
3394 | ||
3395 | @noindent | |
3396 | The first step in creating an executable program is to compile the units | |
984a64bc | 3397 | of the program using the @command{gcc} command. You must compile the |
88e1739c FW |
3398 | following files: |
3399 | ||
3400 | @itemize @bullet | |
3401 | @item | |
3402 | the body file (@file{.adb}) for a library level subprogram or generic | |
3403 | subprogram | |
3404 | ||
3405 | @item | |
3406 | the spec file (@file{.ads}) for a library level package or generic | |
3407 | package that has no body | |
3408 | ||
3409 | @item | |
3410 | the body file (@file{.adb}) for a library level package | |
3411 | or generic package that has a body | |
3412 | ||
3413 | @end itemize | |
3414 | ||
3415 | @noindent | |
3416 | You need @emph{not} compile the following files | |
3417 | ||
3418 | @itemize @bullet | |
3419 | ||
3420 | @item | |
3421 | the spec of a library unit which has a body | |
3422 | ||
3423 | @item | |
3424 | subunits | |
3425 | @end itemize | |
3426 | ||
3427 | @noindent | |
3428 | because they are compiled as part of compiling related units. GNAT | |
3429 | package specs | |
3430 | when the corresponding body is compiled, and subunits when the parent is | |
3431 | compiled. | |
7cd4527e AC |
3432 | |
3433 | @cindex cannot generate code | |
88e1739c | 3434 | If you attempt to compile any of these files, you will get one of the |
aa0df10b VC |
3435 | following error messages (where @var{fff} is the name of the file you |
3436 | compiled): | |
88e1739c FW |
3437 | |
3438 | @smallexample | |
7cd4527e AC |
3439 | cannot generate code for file @var{fff} (package spec) |
3440 | to check package spec, use -gnatc | |
3441 | ||
3442 | cannot generate code for file @var{fff} (missing subunits) | |
3443 | to check parent unit, use -gnatc | |
3444 | ||
3445 | cannot generate code for file @var{fff} (subprogram spec) | |
3446 | to check subprogram spec, use -gnatc | |
3447 | ||
3448 | cannot generate code for file @var{fff} (subunit) | |
3449 | to check subunit, use -gnatc | |
88e1739c FW |
3450 | @end smallexample |
3451 | ||
3452 | @noindent | |
7cd4527e AC |
3453 | As indicated by the above error messages, if you want to submit |
3454 | one of these files to the compiler to check for correct semantics | |
3455 | without generating code, then use the @option{-gnatc} switch. | |
3456 | ||
88e1739c FW |
3457 | The basic command for compiling a file containing an Ada unit is |
3458 | ||
3459 | @smallexample | |
e074d476 AC |
3460 | @c $ gcc -c @ovar{switches} @file{file name} |
3461 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
3462 | $ gcc -c @r{[}@var{switches}@r{]} @file{file name} | |
88e1739c FW |
3463 | @end smallexample |
3464 | ||
3465 | @noindent | |
3466 | where @var{file name} is the name of the Ada file (usually | |
3467 | having an extension | |
3468 | @file{.ads} for a spec or @file{.adb} for a body). | |
3469 | @ifclear vms | |
3470 | You specify the | |
984a64bc | 3471 | @option{-c} switch to tell @command{gcc} to compile, but not link, the file. |
88e1739c FW |
3472 | @end ifclear |
3473 | The result of a successful compilation is an object file, which has the | |
3474 | same name as the source file but an extension of @file{.o} and an Ada | |
3475 | Library Information (ALI) file, which also has the same name as the | |
3476 | source file, but with @file{.ali} as the extension. GNAT creates these | |
3477 | two output files in the current directory, but you may specify a source | |
3478 | file in any directory using an absolute or relative path specification | |
3479 | containing the directory information. | |
3480 | ||
3481 | @findex gnat1 | |
984a64bc | 3482 | @command{gcc} is actually a driver program that looks at the extensions of |
88e1739c FW |
3483 | the file arguments and loads the appropriate compiler. For example, the |
3484 | GNU C compiler is @file{cc1}, and the Ada compiler is @file{gnat1}. | |
3485 | These programs are in directories known to the driver program (in some | |
3486 | configurations via environment variables you set), but need not be in | |
984a64bc | 3487 | your path. The @command{gcc} driver also calls the assembler and any other |
88e1739c FW |
3488 | utilities needed to complete the generation of the required object |
3489 | files. | |
3490 | ||
984a64bc AC |
3491 | It is possible to supply several file names on the same @command{gcc} |
3492 | command. This causes @command{gcc} to call the appropriate compiler for | |
afb4a8cd | 3493 | each file. For example, the following command lists two separate |
88e1739c FW |
3494 | files to be compiled: |
3495 | ||
3496 | @smallexample | |
afb4a8cd | 3497 | $ gcc -c x.adb y.adb |
88e1739c FW |
3498 | @end smallexample |
3499 | ||
3500 | @noindent | |
3501 | calls @code{gnat1} (the Ada compiler) twice to compile @file{x.adb} and | |
afb4a8cd AC |
3502 | @file{y.adb}. |
3503 | The compiler generates two object files @file{x.o} and @file{y.o} | |
3504 | and the two ALI files @file{x.ali} and @file{y.ali}. | |
3505 | Any switches apply to all the files ^listed,^listed.^ | |
88e1739c FW |
3506 | |
3507 | @node Switches for gcc | |
984a64bc | 3508 | @section Switches for @command{gcc} |
88e1739c FW |
3509 | |
3510 | @noindent | |
984a64bc | 3511 | The @command{gcc} command accepts switches that control the |
88e1739c FW |
3512 | compilation process. These switches are fully described in this section. |
3513 | First we briefly list all the switches, in alphabetical order, then we | |
3514 | describe the switches in more detail in functionally grouped sections. | |
3515 | ||
0f1b0456 GB |
3516 | More switches exist for GCC than those documented here, especially |
3517 | for specific targets. However, their use is not recommended as | |
3518 | they may change code generation in ways that are incompatible with | |
3519 | the Ada run-time library, or can cause inconsistencies between | |
3520 | compilation units. | |
3521 | ||
88e1739c FW |
3522 | @menu |
3523 | * Output and Error Message Control:: | |
7cd4527e | 3524 | * Warning Message Control:: |
88e1739c | 3525 | * Debugging and Assertion Control:: |
88e1739c FW |
3526 | * Validity Checking:: |
3527 | * Style Checking:: | |
5453d5bd | 3528 | * Run-Time Checks:: |
88e1739c FW |
3529 | * Using gcc for Syntax Checking:: |
3530 | * Using gcc for Semantic Checking:: | |
0f1b0456 | 3531 | * Compiling Different Versions of Ada:: |
88e1739c FW |
3532 | * Character Set Control:: |
3533 | * File Naming Control:: | |
3534 | * Subprogram Inlining Control:: | |
3535 | * Auxiliary Output Control:: | |
3536 | * Debugging Control:: | |
7cd4527e | 3537 | * Exception Handling Control:: |
88e1739c | 3538 | * Units to Sources Mapping Files:: |
7cd4527e | 3539 | * Integrated Preprocessing:: |
0fb2ea01 | 3540 | * Code Generation Control:: |
7cd4527e AC |
3541 | @ifset vms |
3542 | * Return Codes:: | |
3543 | @end ifset | |
88e1739c FW |
3544 | @end menu |
3545 | ||
7cd4527e AC |
3546 | @table @option |
3547 | @c !sort! | |
88e1739c | 3548 | @ifclear vms |
984a64bc | 3549 | @cindex @option{-b} (@command{gcc}) |
88e1739c FW |
3550 | @item -b @var{target} |
3551 | Compile your program to run on @var{target}, which is the name of a | |
3552 | system configuration. You must have a GNAT cross-compiler built if | |
3553 | @var{target} is not the same as your host system. | |
3554 | ||
3555 | @item -B@var{dir} | |
984a64bc | 3556 | @cindex @option{-B} (@command{gcc}) |
88e1739c FW |
3557 | Load compiler executables (for example, @code{gnat1}, the Ada compiler) |
3558 | from @var{dir} instead of the default location. Only use this switch | |
b2e74434 RW |
3559 | when multiple versions of the GNAT compiler are available. |
3560 | @xref{Directory Options,, Options for Directory Search, gcc, Using the | |
3561 | GNU Compiler Collection (GCC)}, for further details. You would normally | |
3562 | use the @option{-b} or @option{-V} switch instead. | |
88e1739c FW |
3563 | |
3564 | @item -c | |
984a64bc | 3565 | @cindex @option{-c} (@command{gcc}) |
88e1739c FW |
3566 | Compile. Always use this switch when compiling Ada programs. |
3567 | ||
984a64bc | 3568 | Note: for some other languages when using @command{gcc}, notably in |
88e1739c | 3569 | the case of C and C++, it is possible to use |
984a64bc | 3570 | use @command{gcc} without a @option{-c} switch to |
88e1739c FW |
3571 | compile and link in one step. In the case of GNAT, you |
3572 | cannot use this approach, because the binder must be run | |
984a64bc | 3573 | and @command{gcc} cannot be used to run the GNAT binder. |
88e1739c FW |
3574 | @end ifclear |
3575 | ||
af31bd57 AC |
3576 | @item -fcallgraph-info@r{[}=su,da@r{]} |
3577 | @cindex @option{-fcallgraph-info} (@command{gcc}) | |
3578 | Makes the compiler output callgraph information for the program, on a | |
3579 | per-file basis. The information is generated in the VCG format. It can | |
3580 | be decorated with additional, per-node and/or per-edge information, if a | |
3581 | list of comma-separated markers is additionally specified. When the | |
3582 | @var{su} marker is specified, the callgraph is decorated with stack usage information; it is equivalent to @option{-fstack-usage}. When the @var{da} | |
3583 | marker is specified, the callgraph is decorated with information about | |
3584 | dynamically allocated objects. | |
3585 | ||
3586 | @item -fdump-scos | |
3587 | @cindex @option{-fdump-scos} (@command{gcc}) | |
3588 | Generates SCO (Source Coverage Obligation) information in the ALI file. | |
3589 | This information is used by advanced coverage tools. See unit @file{SCOs} | |
3590 | in the compiler sources for details in files @file{scos.ads} and | |
3591 | @file{scos.adb}. | |
3592 | ||
497716fe AC |
3593 | @item -fdump-xref |
3594 | @cindex @option{-fdump-xref} (@command{gcc}) | |
3595 | Generates cross reference information in GLI files for C and C++ sources. | |
3596 | The GLI files have the same syntax as the ALI files for Ada, and can be used | |
3597 | for source navigation in IDEs and on the command line using e.g. gnatxref | |
3598 | and the @option{--ext=gli} switch. | |
3599 | ||
af31bd57 AC |
3600 | @item -flto@r{[}=n@r{]} |
3601 | @cindex @option{-flto} (@command{gcc}) | |
3602 | Enables Link Time Optimization. This switch must be used in conjunction | |
3603 | with the traditional @option{-Ox} switches and instructs the compiler to | |
3604 | defer most optimizations until the link stage. The advantage of this | |
3605 | approach is that the compiler can do a whole-program analysis and choose | |
3606 | the best interprocedural optimization strategy based on a complete view | |
3607 | of the program, instead of a fragmentary view with the usual approach. | |
3608 | This can also speed up the compilation of huge programs and reduce the | |
3609 | size of the final executable, compared with a per-unit compilation with | |
3610 | full inlining across modules enabled with the @option{-gnatn2} switch. | |
3611 | The drawback of this approach is that it may require much more memory. | |
3612 | The switch, as well as the accompanying @option{-Ox} switches, must be | |
3613 | specified both for the compilation and the link phases. | |
3614 | If the @var{n} parameter is specified, the optimization and final code | |
3615 | generation at link time are executed using @var{n} parallel jobs by | |
3616 | means of an installed @command{make} program. | |
3617 | ||
7cd4527e | 3618 | @item -fno-inline |
984a64bc | 3619 | @cindex @option{-fno-inline} (@command{gcc}) |
4317e442 AC |
3620 | Suppresses all inlining, even if other optimization or inlining |
3621 | switches are set. This includes suppression of inlining that | |
3622 | results from the use of the pragma @code{Inline_Always}. | |
a2ad1f79 RD |
3623 | Any occurrences of pragma @code{Inline} or @code{Inline_Always} |
3624 | are ignored, and @option{-gnatn} and @option{-gnatN} have no | |
42ae3870 AC |
3625 | effects if this switch is present. Note that inlining can also |
3626 | be suppressed on a finer-grained basis with pragma @code{No_Inline}. | |
7cd4527e | 3627 | |
1a5f40e1 VC |
3628 | @item -fno-inline-functions |
3629 | @cindex @option{-fno-inline-functions} (@command{gcc}) | |
9d983bbf | 3630 | Suppresses automatic inlining of subprograms, which is enabled |
1a5f40e1 VC |
3631 | if @option{-O3} is used. |
3632 | ||
c09a557e AC |
3633 | @item -fno-inline-small-functions |
3634 | @cindex @option{-fno-inline-small-functions} (@command{gcc}) | |
3635 | Suppresses automatic inlining of small subprograms, which is enabled | |
3636 | if @option{-O2} is used. | |
3637 | ||
1a5f40e1 VC |
3638 | @item -fno-inline-functions-called-once |
3639 | @cindex @option{-fno-inline-functions-called-once} (@command{gcc}) | |
3640 | Suppresses inlining of subprograms local to the unit and called once | |
3641 | from within it, which is enabled if @option{-O1} is used. | |
3642 | ||
7289b80c AC |
3643 | @item -fno-ivopts |
3644 | @cindex @option{-fno-ivopts} (@command{gcc}) | |
3645 | Suppresses high-level loop induction variable optimizations, which are | |
3646 | enabled if @option{-O1} is used. These optimizations are generally | |
3647 | profitable but, for some specific cases of loops with numerous uses | |
3648 | of the iteration variable that follow a common pattern, they may end | |
3649 | up destroying the regularity that could be exploited at a lower level | |
3650 | and thus producing inferior code. | |
3651 | ||
7cd4527e | 3652 | @item -fno-strict-aliasing |
984a64bc | 3653 | @cindex @option{-fno-strict-aliasing} (@command{gcc}) |
7cd4527e | 3654 | Causes the compiler to avoid assumptions regarding non-aliasing |
984a64bc AC |
3655 | of objects of different types. See |
3656 | @ref{Optimization and Strict Aliasing} for details. | |
7cd4527e AC |
3657 | |
3658 | @item -fstack-check | |
984a64bc | 3659 | @cindex @option{-fstack-check} (@command{gcc}) |
7cd4527e | 3660 | Activates stack checking. |
7e3d710b | 3661 | See @ref{Stack Overflow Checking} for details. |
7cd4527e | 3662 | |
0453ca3d RD |
3663 | @item -fstack-usage |
3664 | @cindex @option{-fstack-usage} (@command{gcc}) | |
3665 | Makes the compiler output stack usage information for the program, on a | |
56e94186 | 3666 | per-subprogram basis. See @ref{Static Stack Usage Analysis} for details. |
0453ca3d | 3667 | |
88e1739c | 3668 | @item ^-g^/DEBUG^ |
984a64bc | 3669 | @cindex @option{^-g^/DEBUG^} (@command{gcc}) |
88e1739c FW |
3670 | Generate debugging information. This information is stored in the object |
3671 | file and copied from there to the final executable file by the linker, | |
3672 | where it can be read by the debugger. You must use the | |
7cd4527e | 3673 | @option{^-g^/DEBUG^} switch if you plan on using the debugger. |
88e1739c | 3674 | |
7cd4527e | 3675 | @item -gnat83 |
984a64bc | 3676 | @cindex @option{-gnat83} (@command{gcc}) |
7cd4527e | 3677 | Enforce Ada 83 restrictions. |
88e1739c | 3678 | |
0f1b0456 GB |
3679 | @item -gnat95 |
3680 | @cindex @option{-gnat95} (@command{gcc}) | |
3681 | Enforce Ada 95 restrictions. | |
3682 | ||
3683 | @item -gnat05 | |
3684 | @cindex @option{-gnat05} (@command{gcc}) | |
3685 | Allow full Ada 2005 features. | |
3686 | ||
0eed45bb AC |
3687 | @item -gnat2005 |
3688 | @cindex @option{-gnat2005} (@command{gcc}) | |
3fd9f17c | 3689 | Allow full Ada 2005 features (same as @option{-gnat05}) |
0eed45bb AC |
3690 | |
3691 | @item -gnat12 | |
3692 | @cindex @option{-gnat12} (@command{gcc}) | |
3693 | ||
3694 | @item -gnat2012 | |
3695 | @cindex @option{-gnat2012} (@command{gcc}) | |
3fd9f17c | 3696 | Allow full Ada 2012 features (same as @option{-gnat12}) |
0eed45bb | 3697 | |
88e1739c | 3698 | @item -gnata |
984a64bc | 3699 | @cindex @option{-gnata} (@command{gcc}) |
88e1739c | 3700 | Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be |
c1cd0d96 RD |
3701 | activated. Note that these pragmas can also be controlled using the |
3702 | configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}. | |
1a5f40e1 VC |
3703 | It also activates pragmas @code{Check}, @code{Precondition}, and |
3704 | @code{Postcondition}. Note that these pragmas can also be controlled | |
de94a7e7 AC |
3705 | using the configuration pragma @code{Check_Policy}. In Ada 2012, it |
3706 | also activates all assertions defined in the RM as aspects: preconditions, | |
3707 | postconditions, type invariants and (sub)type predicates. In all Ada modes, | |
3708 | corresponding pragmas for type invariants and (sub)type predicates are | |
3709 | also activated. | |
88e1739c FW |
3710 | |
3711 | @item -gnatA | |
984a64bc | 3712 | @cindex @option{-gnatA} (@command{gcc}) |
443b3472 | 3713 | Avoid processing @file{gnat.adc}. If a @file{gnat.adc} file is present, |
7cd4527e | 3714 | it will be ignored. |
88e1739c FW |
3715 | |
3716 | @item -gnatb | |
984a64bc | 3717 | @cindex @option{-gnatb} (@command{gcc}) |
88e1739c FW |
3718 | Generate brief messages to @file{stderr} even if verbose mode set. |
3719 | ||
c800f862 RD |
3720 | @item -gnatB |
3721 | @cindex @option{-gnatB} (@command{gcc}) | |
e1aca343 AC |
3722 | Assume no invalid (bad) values except for 'Valid attribute use |
3723 | (@pxref{Validity Checking}). | |
c800f862 | 3724 | |
88e1739c | 3725 | @item -gnatc |
984a64bc | 3726 | @cindex @option{-gnatc} (@command{gcc}) |
e03c5253 VC |
3727 | Check syntax and semantics only (no code generation attempted). When the |
3728 | compiler is invoked by @command{gnatmake}, if the switch @option{-gnatc} is | |
3729 | only given to the compiler (after @option{-cargs} or in package Compiler of | |
3730 | the project file, @command{gnatmake} will fail because it will not find the | |
3731 | object file after compilation. If @command{gnatmake} is called with | |
3732 | @option{-gnatc} as a builder switch (before @option{-cargs} or in package | |
3733 | Builder of the project file) then @command{gnatmake} will not fail because | |
3734 | it will not look for the object files after compilation, and it will not try | |
cdcf1c7a AC |
3735 | to build and link. This switch may not be given if a previous @code{-gnatR} |
3736 | switch has been given, since @code{-gnatR} requires that the code generator | |
3737 | be called to complete determination of representation information. | |
88e1739c | 3738 | |
76efd572 AC |
3739 | @item -gnatC |
3740 | @cindex @option{-gnatC} (@command{gcc}) | |
3741 | Generate CodePeer information (no code generation attempted). | |
3742 | This switch will generate an intermediate representation suitable for | |
3743 | use by CodePeer (@file{.scil} files). This switch is not compatible with | |
3744 | code generation (it will, among other things, disable some switches such | |
3745 | as -gnatn, and enable others such as -gnata). | |
3746 | ||
7cd4527e | 3747 | @item -gnatd |
984a64bc | 3748 | @cindex @option{-gnatd} (@command{gcc}) |
7cd4527e AC |
3749 | Specify debug options for the compiler. The string of characters after |
3750 | the @option{-gnatd} specify the specific debug options. The possible | |
3751 | characters are 0-9, a-z, A-Z, optionally preceded by a dot. See | |
3752 | compiler source file @file{debug.adb} for details of the implemented | |
3753 | debug options. Certain debug options are relevant to applications | |
3754 | programmers, and these are documented at appropriate points in this | |
3755 | users guide. | |
88e1739c | 3756 | |
59f3dd0a | 3757 | @ifclear vms |
88e1739c | 3758 | @item -gnatD |
dcd8728b | 3759 | @cindex @option{-gnatD[nn]} (@command{gcc}) |
59f3dd0a AC |
3760 | @end ifclear |
3761 | @ifset vms | |
3762 | @item /XDEBUG /LXDEBUG=nnn | |
3763 | @end ifset | |
7cd4527e AC |
3764 | Create expanded source files for source level debugging. This switch |
3765 | also suppress generation of cross-reference information | |
a1390a6e AC |
3766 | (see @option{-gnatx}). Note that this switch is not allowed if a previous |
3767 | -gnatR switch has been given, since these two switches are not compatible. | |
7cd4527e | 3768 | |
33decf81 VC |
3769 | @item ^-gnateA^/ALIASING_CHECK^ |
3770 | @cindex @option{-gnateA} (@command{gcc}) | |
3771 | Check that there is no aliasing between two parameters of the same subprogram. | |
3772 | ||
7cd4527e | 3773 | @item -gnatec=@var{path} |
984a64bc | 3774 | @cindex @option{-gnatec} (@command{gcc}) |
7cd4527e AC |
3775 | Specify a configuration pragma file |
3776 | @ifclear vms | |
3777 | (the equal sign is optional) | |
3778 | @end ifclear | |
984a64bc | 3779 | (@pxref{The Configuration Pragmas Files}). |
7cd4527e | 3780 | |
33decf81 VC |
3781 | @item ^-gnated^/DISABLE_ATOMIC_SYNCHRONIZATION^ |
3782 | @cindex @option{-gnated} (@command{gcc}) | |
3783 | Disable atomic synchronization | |
3784 | ||
66bfd481 | 3785 | @item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=@var{value}@r{]} |
984a64bc | 3786 | @cindex @option{-gnateD} (@command{gcc}) |
66bfd481 | 3787 | Defines a symbol, associated with @var{value}, for preprocessing. |
984a64bc | 3788 | (@pxref{Integrated Preprocessing}). |
7cd4527e | 3789 | |
437f8c1e AC |
3790 | @item -gnateE |
3791 | @cindex @option{-gnateE} (@command{gcc}) | |
4fdebd93 | 3792 | Generate extra information in exception messages. In particular, display |
437f8c1e AC |
3793 | extra column information and the value and range associated with index and |
3794 | range check failures, and extra column information for access checks. | |
4fdebd93 AC |
3795 | In cases where the compiler is able to determine at compile time that |
3796 | a check will fail, it gives a warning, and the extra information is not | |
3797 | produced at run time. | |
437f8c1e | 3798 | |
7cd4527e | 3799 | @item -gnatef |
984a64bc | 3800 | @cindex @option{-gnatef} (@command{gcc}) |
7cd4527e | 3801 | Display full source path name in brief error messages. |
88e1739c | 3802 | |
2dbdd821 RD |
3803 | @item -gnateF |
3804 | @cindex @option{-gnateF} (@command{gcc}) | |
3805 | Check for overflow on all floating-point operations, including those | |
3806 | for unconstrained predefined types. See description of pragma | |
3807 | @code{Check_Float_Overflow} in GNAT RM. | |
3808 | ||
1a9a686e VC |
3809 | @item -gnateG |
3810 | @cindex @option{-gnateG} (@command{gcc}) | |
3811 | Save result of preprocessing in a text file. | |
3812 | ||
119e3be6 | 3813 | @item -gnatei@var{nnn} |
a4956515 AC |
3814 | @cindex @option{-gnatei} (@command{gcc}) |
3815 | Set maximum number of instantiations during compilation of a single unit to | |
3816 | @var{nnn}. This may be useful in increasing the default maximum of 8000 for | |
3817 | the rare case when a single unit legitimately exceeds this limit. | |
3818 | ||
119e3be6 | 3819 | @item -gnateI@var{nnn} |
97ed5872 AC |
3820 | @cindex @option{-gnateI} (@command{gcc}) |
3821 | Indicates that the source is a multi-unit source and that the index of the | |
bd0bc43e AC |
3822 | unit to compile is @var{nnn}. @var{nnn} needs to be a positive number and need |
3823 | to be a valid index in the multi-unit source. | |
97ed5872 | 3824 | |
7cd4527e | 3825 | @item -gnatem=@var{path} |
984a64bc | 3826 | @cindex @option{-gnatem} (@command{gcc}) |
7cd4527e AC |
3827 | Specify a mapping file |
3828 | @ifclear vms | |
3829 | (the equal sign is optional) | |
3830 | @end ifclear | |
984a64bc | 3831 | (@pxref{Units to Sources Mapping Files}). |
88e1739c | 3832 | |
7cd4527e | 3833 | @item -gnatep=@var{file} |
984a64bc | 3834 | @cindex @option{-gnatep} (@command{gcc}) |
7cd4527e AC |
3835 | Specify a preprocessing data file |
3836 | @ifclear vms | |
3837 | (the equal sign is optional) | |
3838 | @end ifclear | |
984a64bc | 3839 | (@pxref{Integrated Preprocessing}). |
88e1739c | 3840 | |
878f708a RD |
3841 | @item -gnateP |
3842 | @cindex @option{-gnateP} (@command{gcc}) | |
3843 | Turn categorization dependency errors into warnings. | |
3844 | Ada requires that units that WITH one another have compatible categories, for | |
383e179e | 3845 | example a Pure unit cannot WITH a Preelaborate unit. If this switch is used, |
878f708a RD |
3846 | these errors become warnings (which can be ignored, or suppressed in the usual |
3847 | manner). This can be useful in some specialized circumstances such as the | |
3848 | temporary use of special test software. | |
70f4ad20 | 3849 | |
240fe2a4 AC |
3850 | @item -gnateS |
3851 | @cindex @option{-gnateS} (@command{gcc}) | |
818b578d | 3852 | Synonym of @option{-fdump-scos}, kept for backwards compatibility. |
240fe2a4 | 3853 | |
8a7c0400 | 3854 | @item -gnatet=@var{path} |
5114f3ff AC |
3855 | @cindex @option{-gnatet=file} (@command{gcc}) |
3856 | Generate target dependent information. The format of the output file is | |
3857 | described in the section about switch @option{-gnateT}. | |
3858 | ||
8a7c0400 | 3859 | @item -gnateT=@var{path} |
5114f3ff AC |
3860 | @cindex @option{-gnateT} (@command{gcc}) |
3861 | Read target dependent information, such as endianness or sizes and alignments | |
3862 | of base type. If this switch is passed, the default target dependent | |
3863 | information of the compiler is replaced by the one read from the input file. | |
3864 | This is used by tools other than the compiler, e.g. to do | |
3865 | semantic analysis of programs that will run on some other target than | |
3866 | the machine on which the tool is run. | |
3867 | ||
3868 | The following target dependent values should be defined, | |
3869 | where @code{Nat} denotes a natural integer value, @code{Pos} denotes a | |
3870 | positive integer value, and fields marked with a question mark are | |
3871 | boolean fields, where a value of 0 is False, and a value of 1 is True: | |
3872 | ||
3873 | @smallexample | |
3874 | Bits_BE : Nat; -- Bits stored big-endian? | |
3875 | Bits_Per_Unit : Pos; -- Bits in a storage unit | |
3876 | Bits_Per_Word : Pos; -- Bits in a word | |
3877 | Bytes_BE : Nat; -- Bytes stored big-endian? | |
3878 | Char_Size : Pos; -- Standard.Character'Size | |
3879 | Double_Float_Alignment : Nat; -- Alignment of double float | |
3880 | Double_Scalar_Alignment : Nat; -- Alignment of double length scalar | |
3881 | Double_Size : Pos; -- Standard.Long_Float'Size | |
3882 | Float_Size : Pos; -- Standard.Float'Size | |
3883 | Float_Words_BE : Nat; -- Float words stored big-endian? | |
3884 | Int_Size : Pos; -- Standard.Integer'Size | |
3885 | Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size | |
3886 | Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size | |
3887 | Long_Size : Pos; -- Standard.Long_Integer'Size | |
3888 | Maximum_Alignment : Pos; -- Maximum permitted alignment | |
3889 | Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field | |
3890 | Pointer_Size : Pos; -- System.Address'Size | |
42959b0c | 3891 | Short_Enums : Nat; -- Short foreign convention enums? |
5114f3ff AC |
3892 | Short_Size : Pos; -- Standard.Short_Integer'Size |
3893 | Strict_Alignment : Nat; -- Strict alignment? | |
3894 | System_Allocator_Alignment : Nat; -- Alignment for malloc calls | |
3895 | Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size | |
3896 | Words_BE : Nat; -- Words stored big-endian? | |
3897 | @end smallexample | |
3898 | ||
3899 | The format of the input file is as follows. First come the values of | |
3900 | the variables defined above, with one line per value: | |
3901 | ||
3902 | @smallexample | |
3903 | name value | |
3904 | @end smallexample | |
3905 | ||
3906 | where @code{name} is the name of the parameter, spelled out in full, | |
3907 | and cased as in the above list, and @code{value} is an unsigned decimal | |
3908 | integer. Two or more blanks separates the name from the value. | |
3909 | ||
3910 | All the variables must be present, in alphabetical order (i.e. the | |
3911 | same order as the list above). | |
3912 | ||
3913 | Then there is a blank line to separate the two parts of the file. Then | |
3914 | come the lines showing the floating-point types to be registered, with | |
3915 | one line per registered mode: | |
3916 | ||
3917 | @smallexample | |
3918 | name digs float_rep size alignment | |
3919 | @end smallexample | |
3920 | ||
3921 | where @code{name} is the string name of the type (which can have | |
3922 | single spaces embedded in the name (e.g. long double), @code{digs} is | |
3923 | the number of digits for the floating-point type, @code{float_rep} is | |
3924 | the float representation (I/V/A for IEEE-754-Binary, Vax_Native, | |
3925 | AAMP), @code{size} is the size in bits, @code{alignment} is the | |
3926 | alignment in bits. The name is followed by at least two blanks, fields | |
3927 | are separated by at least one blank, and a LF character immediately | |
3928 | follows the alignment field. | |
3929 | ||
97027f64 | 3930 | Here is an example of a target parameterization file: |
5114f3ff AC |
3931 | |
3932 | @smallexample | |
3933 | Bits_BE 0 | |
3934 | Bits_Per_Unit 8 | |
3935 | Bits_Per_Word 64 | |
3936 | Bytes_BE 0 | |
3937 | Char_Size 8 | |
3938 | Double_Float_Alignment 0 | |
3939 | Double_Scalar_Alignment 0 | |
3940 | Double_Size 64 | |
3941 | Float_Size 32 | |
3942 | Float_Words_BE 0 | |
3943 | Int_Size 64 | |
3944 | Long_Double_Size 128 | |
3945 | Long_Long_Size 64 | |
3946 | Long_Size 64 | |
3947 | Maximum_Alignment 16 | |
3948 | Max_Unaligned_Field 64 | |
3949 | Pointer_Size 64 | |
3950 | Short_Size 16 | |
3951 | Strict_Alignment 0 | |
3952 | System_Allocator_Alignment 16 | |
3953 | Wchar_T_Size 32 | |
3954 | Words_BE 0 | |
3955 | ||
3956 | float 15 I 64 64 | |
3957 | double 15 I 64 64 | |
3958 | long double 18 I 80 128 | |
3959 | TF 33 I 128 128 | |
3960 | @end smallexample | |
33decf81 | 3961 | |
d48cd424 RD |
3962 | @item -gnateu |
3963 | @cindex @option{-gnateu} (@command{gcc}) | |
3964 | Ignore unrecognized validity, warning, and style switches that | |
7c821eff | 3965 | appear after this switch is given. This may be useful when |
d48cd424 RD |
3966 | compiling sources developed on a later version of the compiler |
3967 | with an earlier version. Of course the earlier version must | |
3968 | support this switch. | |
3969 | ||
33decf81 VC |
3970 | @item ^-gnateV^/PARAMETER_VALIDITY_CHECK^ |
3971 | @cindex @option{-gnateV} (@command{gcc}) | |
3972 | Check validity of subprogram parameters. | |
3973 | ||
42f1d661 AC |
3974 | @item ^-gnateY^/IGNORE_SUPPRESS_SYLE_CHECK_PRAGMAS^ |
3975 | @cindex @option{-gnateY} (@command{gcc}) | |
3976 | Ignore all STYLE_CHECKS pragmas. Full legality checks | |
3977 | are still carried out, but the pragmas have no effect | |
3978 | on what style checks are active. This allows all style | |
3979 | checking options to be controlled from the command line. | |
3980 | ||
88e1739c | 3981 | @item -gnatE |
984a64bc | 3982 | @cindex @option{-gnatE} (@command{gcc}) |
88e1739c FW |
3983 | Full dynamic elaboration checks. |
3984 | ||
3985 | @item -gnatf | |
984a64bc | 3986 | @cindex @option{-gnatf} (@command{gcc}) |
7cd4527e AC |
3987 | Full errors. Multiple errors per line, all undefined references, do not |
3988 | attempt to suppress cascaded errors. | |
88e1739c FW |
3989 | |
3990 | @item -gnatF | |
984a64bc | 3991 | @cindex @option{-gnatF} (@command{gcc}) |
88e1739c FW |
3992 | Externals names are folded to all uppercase. |
3993 | ||
e08b38f5 VC |
3994 | @item ^-gnatg^/GNAT_INTERNAL^ |
3995 | @cindex @option{^-gnatg^/GNAT_INTERNAL^} (@command{gcc}) | |
88e1739c FW |
3996 | Internal GNAT implementation mode. This should not be used for |
3997 | applications programs, it is intended only for use by the compiler | |
3998 | and its run-time library. For documentation, see the GNAT sources. | |
e08b38f5 VC |
3999 | Note that @option{^-gnatg^/GNAT_INTERNAL^} implies |
4000 | @option{^-gnatwae^/WARNINGS=ALL,ERRORS^} and | |
4001 | @option{^-gnatyg^/STYLE_CHECKS=GNAT^} | |
4002 | so that all standard warnings and all standard style options are turned on. | |
9cbfc269 | 4003 | All warnings and style messages are treated as errors. |
88e1739c | 4004 | |
59f3dd0a | 4005 | @ifclear vms |
f7d7bb51 | 4006 | @item -gnatG=nn |
dcd8728b | 4007 | @cindex @option{-gnatG[nn]} (@command{gcc}) |
59f3dd0a AC |
4008 | @end ifclear |
4009 | @ifset vms | |
4010 | @item /EXPAND_SOURCE, /LEXPAND_SOURCE=nnn | |
4011 | @end ifset | |
88e1739c FW |
4012 | List generated expanded code in source form. |
4013 | ||
7cd4527e | 4014 | @item ^-gnath^/HELP^ |
984a64bc | 4015 | @cindex @option{^-gnath^/HELP^} (@command{gcc}) |
7cd4527e AC |
4016 | Output usage information. The output is written to @file{stdout}. |
4017 | ||
88e1739c | 4018 | @item ^-gnati^/IDENTIFIER_CHARACTER_SET=^@var{c} |
984a64bc | 4019 | @cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@command{gcc}) |
88e1739c FW |
4020 | Identifier character set |
4021 | @ifclear vms | |
4022 | (@var{c}=1/2/3/4/8/9/p/f/n/w). | |
4023 | @end ifclear | |
88e1739c | 4024 | For details of the possible selections for @var{c}, |
984a64bc | 4025 | see @ref{Character Set Control}. |
c690a2ec | 4026 | |
a2ad1f79 | 4027 | @item ^-gnatI^/IGNORE_REP_CLAUSES^ |
c690a2ec | 4028 | @cindex @option{^-gnatI^IGNORE_REP_CLAUSES^} (@command{gcc}) |
70b70ce8 | 4029 | Ignore representation clauses. When this switch is used, |
c690a2ec RD |
4030 | representation clauses are treated as comments. This is useful |
4031 | when initially porting code where you want to ignore rep clause | |
4032 | problems, and also for compiling foreign code (particularly | |
70b70ce8 AC |
4033 | for use with ASIS). The representation clauses that are ignored |
4034 | are: enumeration_representation_clause, record_representation_clause, | |
4035 | and attribute_definition_clause for the following attributes: | |
4036 | Address, Alignment, Bit_Order, Component_Size, Machine_Radix, | |
4037 | Object_Size, Size, Small, Stream_Size, and Value_Size. | |
4038 | Note that this option should be used only for compiling -- the | |
4039 | code is likely to malfunction at run time. | |
88e1739c | 4040 | |
ba1cbfb9 RD |
4041 | @item -gnatjnn |
4042 | @cindex @option{-gnatjnn} (@command{gcc}) | |
4043 | Reformat error messages to fit on nn character lines | |
4044 | ||
7cd4527e | 4045 | @item -gnatk=@var{n} |
984a64bc | 4046 | @cindex @option{-gnatk} (@command{gcc}) |
88e1739c FW |
4047 | Limit file names to @var{n} (1-999) characters ^(@code{k} = krunch)^^. |
4048 | ||
4049 | @item -gnatl | |
984a64bc | 4050 | @cindex @option{-gnatl} (@command{gcc}) |
88e1739c FW |
4051 | Output full source listing with embedded error messages. |
4052 | ||
ba1cbfb9 RD |
4053 | @item -gnatL |
4054 | @cindex @option{-gnatL} (@command{gcc}) | |
4055 | Used in conjunction with -gnatG or -gnatD to intersperse original | |
4056 | source lines (as comment lines with line numbers) in the expanded | |
4057 | source output. | |
4058 | ||
7cd4527e | 4059 | @item -gnatm=@var{n} |
984a64bc | 4060 | @cindex @option{-gnatm} (@command{gcc}) |
7cd4527e | 4061 | Limit number of detected error or warning messages to @var{n} |
923e6ff3 RD |
4062 | where @var{n} is in the range 1..999999. The default setting if |
4063 | no switch is given is 9999. If the number of warnings reaches this | |
4064 | limit, then a message is output and further warnings are suppressed, | |
4065 | but the compilation is continued. If the number of error messages | |
4066 | reaches this limit, then a message is output and the compilation | |
4067 | is abandoned. The equal sign here is optional. A value of zero | |
4068 | means that no limit applies. | |
88e1739c | 4069 | |
4c7be310 | 4070 | @item -gnatn[12] |
984a64bc | 4071 | @cindex @option{-gnatn} (@command{gcc}) |
4c7be310 AC |
4072 | Activate inlining for subprograms for which pragma @code{Inline} is |
4073 | specified. This inlining is performed by the GCC back-end. An optional | |
21791d97 AC |
4074 | digit sets the inlining level: 1 for moderate inlining across modules |
4075 | or 2 for full inlining across modules. If no inlining level is specified, | |
4c7be310 | 4076 | the compiler will pick it based on the optimization level. |
88e1739c FW |
4077 | |
4078 | @item -gnatN | |
984a64bc | 4079 | @cindex @option{-gnatN} (@command{gcc}) |
7cd4527e AC |
4080 | Activate front end inlining for subprograms for which |
4081 | pragma @code{Inline} is specified. This inlining is performed | |
4082 | by the front end and will be visible in the | |
4083 | @option{-gnatG} output. | |
f17889b3 RD |
4084 | |
4085 | When using a gcc-based back end (in practice this means using any version | |
4086 | of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of | |
4087 | @option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred. | |
4088 | Historically front end inlining was more extensive than the gcc back end | |
4089 | inlining, but that is no longer the case. | |
88e1739c | 4090 | |
538dbb56 AC |
4091 | @item -gnato?? |
4092 | @cindex @option{-gnato??} (@command{gcc}) | |
d8192289 AC |
4093 | Set default mode for handling generation of code to avoid intermediate |
4094 | arithmetic overflow. Here `@code{??}' is two digits, a | |
4095 | single digit, or nothing. Each digit is one of the digits `@code{1}' | |
6e6636ec | 4096 | through `@code{3}': |
538dbb56 | 4097 | |
6e6636ec | 4098 | @itemize @bullet |
6e6636ec | 4099 | @item @code{1}: |
d8192289 | 4100 | all intermediate overflows checked against base type (@code{STRICT}) |
6e6636ec RD |
4101 | @item @code{2}: |
4102 | minimize intermediate overflows (@code{MINIMIZED}) | |
4103 | @item @code{3}: | |
4104 | eliminate intermediate overflows (@code{ELIMINATED}) | |
4105 | @end itemize | |
538dbb56 | 4106 | |
6e6636ec RD |
4107 | If only one digit appears then it applies to all |
4108 | cases; if two digits are given, then the first applies outside | |
4109 | assertions, and the second within assertions. | |
538dbb56 | 4110 | |
6e6636ec | 4111 | If no digits follow the @option{-gnato}, then it is equivalent to |
354c3840 | 4112 | @option{^-gnato11^/OVERFLOW_CHECKS=11^}, |
d8192289 AC |
4113 | causing all intermediate overflows to be handled in strict mode. |
4114 | ||
4115 | This switch also causes arithmetic overflow checking to be performed | |
ceee0bde | 4116 | (as though pragma @code{Unsuppress (Overflow_Mode)} has been specified. |
d8192289 AC |
4117 | |
4118 | The default if no option @option{-gnato} is given is that overflow handling | |
4119 | is in @code{STRICT} mode (computations done using the base type), and that | |
ceee0bde | 4120 | overflow checking is suppressed. |
6e6636ec | 4121 | |
6e6636ec | 4122 | Note that division by zero is a separate check that is not |
88e1739c | 4123 | controlled by this switch (division by zero checking is on by default). |
6e6636ec RD |
4124 | |
4125 | See also @ref{Specifying the Desired Mode}. | |
88e1739c FW |
4126 | |
4127 | @item -gnatp | |
984a64bc | 4128 | @cindex @option{-gnatp} (@command{gcc}) |
3f165ff2 AC |
4129 | Suppress all checks. See @ref{Run-Time Checks} for details. This switch |
4130 | has no effect if cancelled by a subsequent @option{-gnat-p} switch. | |
4131 | ||
4132 | @item -gnat-p | |
4133 | @cindex @option{-gnat-p} (@command{gcc}) | |
4134 | Cancel effect of previous @option{-gnatp} switch. | |
88e1739c | 4135 | |
88e1739c | 4136 | @item -gnatP |
984a64bc | 4137 | @cindex @option{-gnatP} (@command{gcc}) |
88e1739c FW |
4138 | Enable polling. This is required on some systems (notably Windows NT) to |
4139 | obtain asynchronous abort and asynchronous transfer of control capability. | |
b2e74434 RW |
4140 | @xref{Pragma Polling,,, gnat_rm, GNAT Reference Manual}, for full |
4141 | details. | |
88e1739c | 4142 | |
7cd4527e | 4143 | @item -gnatq |
984a64bc | 4144 | @cindex @option{-gnatq} (@command{gcc}) |
a4d4806f | 4145 | Don't quit. Try semantics, even if parse errors. |
7cd4527e AC |
4146 | |
4147 | @item -gnatQ | |
984a64bc | 4148 | @cindex @option{-gnatQ} (@command{gcc}) |
a4d4806f | 4149 | Don't quit. Generate @file{ALI} and tree files even if illegalities. |
7cd4527e | 4150 | |
8436e37c RD |
4151 | @item -gnatr |
4152 | @cindex @option{-gnatr} (@command{gcc}) | |
4153 | Treat pragma Restrictions as Restriction_Warnings. | |
4154 | ||
66bfd481 | 4155 | @item ^-gnatR@r{[}0@r{/}1@r{/}2@r{/}3@r{[}s@r{]]}^/REPRESENTATION_INFO^ |
984a64bc | 4156 | @cindex @option{-gnatR} (@command{gcc}) |
88e1739c | 4157 | Output representation information for declared types and objects. |
cdcf1c7a AC |
4158 | Note that this switch is not allowed if a previous @code{-gnatD} switch has |
4159 | been given, since these two switches are not compatible. It is also not allowed | |
4160 | if a previous @code{-gnatc} switch has been given, since we must be generating | |
4161 | code to be able to determine representation information. | |
88e1739c | 4162 | |
4bb9c7b9 AC |
4163 | @item ^-gnatRm[s]^/REPRESENTATION_INFO^ |
4164 | Output convention and parameter passing mechanisms for all subprograms. | |
4165 | This form is also incompatible with the use of @code{-gnatc}. | |
4166 | ||
88e1739c | 4167 | @item -gnats |
984a64bc | 4168 | @cindex @option{-gnats} (@command{gcc}) |
88e1739c FW |
4169 | Syntax check only. |
4170 | ||
7cd4527e | 4171 | @item -gnatS |
984a64bc | 4172 | @cindex @option{-gnatS} (@command{gcc}) |
7cd4527e AC |
4173 | Print package Standard. |
4174 | ||
88e1739c | 4175 | @item -gnatt |
984a64bc | 4176 | @cindex @option{-gnatt} (@command{gcc}) |
7cd4527e | 4177 | Generate tree output file. |
88e1739c | 4178 | |
7cd4527e | 4179 | @item ^-gnatT^/TABLE_MULTIPLIER=^@var{nnn} |
984a64bc | 4180 | @cindex @option{^-gnatT^/TABLE_MULTIPLIER^} (@command{gcc}) |
7cd4527e | 4181 | All compiler tables start at @var{nnn} times usual starting size. |
88e1739c FW |
4182 | |
4183 | @item -gnatu | |
984a64bc | 4184 | @cindex @option{-gnatu} (@command{gcc}) |
88e1739c FW |
4185 | List units for this compilation. |
4186 | ||
4187 | @item -gnatU | |
984a64bc | 4188 | @cindex @option{-gnatU} (@command{gcc}) |
7cd4527e | 4189 | Tag all error messages with the unique string ``error:'' |
88e1739c FW |
4190 | |
4191 | @item -gnatv | |
984a64bc | 4192 | @cindex @option{-gnatv} (@command{gcc}) |
88e1739c FW |
4193 | Verbose mode. Full error output with source lines to @file{stdout}. |
4194 | ||
4195 | @item -gnatV | |
984a64bc | 4196 | @cindex @option{-gnatV} (@command{gcc}) |
e1aca343 | 4197 | Control level of validity checking (@pxref{Validity Checking}). |
88e1739c | 4198 | |
66bfd481 | 4199 | @item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}@r{[},@dots{}@r{]})^ |
984a64bc | 4200 | @cindex @option{^-gnatw^/WARNINGS^} (@command{gcc}) |
88e1739c | 4201 | Warning mode where |
7cd4527e AC |
4202 | ^@var{xxx} is a string of option letters that^the list of options^ denotes |
4203 | the exact warnings that | |
984a64bc | 4204 | are enabled or disabled (@pxref{Warning Message Control}). |
88e1739c FW |
4205 | |
4206 | @item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e} | |
984a64bc | 4207 | @cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@command{gcc}) |
88e1739c FW |
4208 | Wide character encoding method |
4209 | @ifclear vms | |
4210 | (@var{e}=n/h/u/s/e/8). | |
4211 | @end ifclear | |
4212 | @ifset vms | |
4213 | (@var{e}=@code{BRACKETS, NONE, HEX, UPPER, SHIFT_JIS, EUC, UTF8}) | |
4214 | @end ifset | |
4215 | ||
4216 | @item -gnatx | |
984a64bc | 4217 | @cindex @option{-gnatx} (@command{gcc}) |
88e1739c FW |
4218 | Suppress generation of cross-reference information. |
4219 | ||
0eed45bb AC |
4220 | @item -gnatX |
4221 | @cindex @option{-gnatX} (@command{gcc}) | |
4222 | Enable GNAT implementation extensions and latest Ada version. | |
4223 | ||
d488f6ea | 4224 | @item ^-gnaty^/STYLE_CHECKS=(option,option@dots{})^ |
984a64bc AC |
4225 | @cindex @option{^-gnaty^/STYLE_CHECKS^} (@command{gcc}) |
4226 | Enable built-in style checks (@pxref{Style Checking}). | |
88e1739c FW |
4227 | |
4228 | @item ^-gnatz^/DISTRIBUTION_STUBS=^@var{m} | |
984a64bc | 4229 | @cindex @option{^-gnatz^/DISTRIBUTION_STUBS^} (@command{gcc}) |
88e1739c FW |
4230 | Distribution stub generation and compilation |
4231 | @ifclear vms | |
4232 | (@var{m}=r/c for receiver/caller stubs). | |
4233 | @end ifclear | |
4234 | @ifset vms | |
4235 | (@var{m}=@code{RECEIVER} or @code{CALLER} to specify the type of stubs | |
4236 | to be generated and compiled). | |
4237 | @end ifset | |
4238 | ||
7cd4527e | 4239 | @item ^-I^/SEARCH=^@var{dir} |
984a64bc | 4240 | @cindex @option{^-I^/SEARCH^} (@command{gcc}) |
7cd4527e AC |
4241 | @cindex RTL |
4242 | Direct GNAT to search the @var{dir} directory for source files needed by | |
4243 | the current compilation | |
4244 | (@pxref{Search Paths and the Run-Time Library (RTL)}). | |
4245 | ||
4246 | @item ^-I-^/NOCURRENT_DIRECTORY^ | |
984a64bc | 4247 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gcc}) |
7cd4527e AC |
4248 | @cindex RTL |
4249 | Except for the source file named in the command line, do not look for source | |
4250 | files in the directory containing the source file named in the command line | |
4251 | (@pxref{Search Paths and the Run-Time Library (RTL)}). | |
88e1739c FW |
4252 | |
4253 | @ifclear vms | |
7cd4527e AC |
4254 | @item -mbig-switch |
4255 | @cindex @option{-mbig-switch} (@command{gcc}) | |
4256 | @cindex @code{case} statement (effect of @option{-mbig-switch} option) | |
4257 | This standard gcc switch causes the compiler to use larger offsets in its | |
4258 | jump table representation for @code{case} statements. | |
4259 | This may result in less efficient code, but is sometimes necessary | |
4260 | (for example on HP-UX targets) | |
4261 | @cindex HP-UX and @option{-mbig-switch} option | |
4262 | in order to compile large and/or nested @code{case} statements. | |
4263 | ||
4264 | @item -o @var{file} | |
984a64bc AC |
4265 | @cindex @option{-o} (@command{gcc}) |
4266 | This switch is used in @command{gcc} to redirect the generated object file | |
7cd4527e AC |
4267 | and its associated ALI file. Beware of this switch with GNAT, because it may |
4268 | cause the object file and ALI file to have different names which in turn | |
4269 | may confuse the binder and the linker. | |
88e1739c | 4270 | @end ifclear |
7cd4527e AC |
4271 | |
4272 | @item -nostdinc | |
4273 | @cindex @option{-nostdinc} (@command{gcc}) | |
4274 | Inhibit the search of the default location for the GNAT Run Time | |
4275 | Library (RTL) source files. | |
4276 | ||
4277 | @item -nostdlib | |
4278 | @cindex @option{-nostdlib} (@command{gcc}) | |
4279 | Inhibit the search of the default location for the GNAT Run Time | |
4280 | Library (RTL) ALI files. | |
88e1739c FW |
4281 | |
4282 | @ifclear vms | |
e074d476 AC |
4283 | @c @item -O@ovar{n} |
4284 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
4285 | @item -O@r{[}@var{n}@r{]} | |
984a64bc | 4286 | @cindex @option{-O} (@command{gcc}) |
7cd4527e | 4287 | @var{n} controls the optimization level. |
88e1739c | 4288 | |
7cd4527e AC |
4289 | @table @asis |
4290 | @item n = 0 | |
4291 | No optimization, the default setting if no @option{-O} appears | |
88e1739c | 4292 | |
7cd4527e AC |
4293 | @item n = 1 |
4294 | Normal optimization, the default if you specify @option{-O} without | |
c1cd0d96 RD |
4295 | an operand. A good compromise between code quality and compilation |
4296 | time. | |
88e1739c | 4297 | |
7cd4527e | 4298 | @item n = 2 |
c1cd0d96 RD |
4299 | Extensive optimization, may improve execution time, possibly at the cost of |
4300 | substantially increased compilation time. | |
88e1739c | 4301 | |
e08b38f5 VC |
4302 | @item n = 3 |
4303 | Same as @option{-O2}, and also includes inline expansion for small subprograms | |
4304 | in the same unit. | |
4305 | ||
4306 | @item n = s | |
4307 | Optimize space usage | |
7cd4527e | 4308 | @end table |
e08b38f5 VC |
4309 | |
4310 | @noindent | |
4311 | See also @ref{Optimization Levels}. | |
7cd4527e | 4312 | @end ifclear |
88e1739c | 4313 | |
7cd4527e AC |
4314 | @ifset vms |
4315 | @item /NOOPTIMIZE | |
4316 | @cindex @option{/NOOPTIMIZE} (@code{GNAT COMPILE}) | |
4317 | Equivalent to @option{/OPTIMIZE=NONE}. | |
e08b38f5 | 4318 | This is the default behavior in the absence of an @option{/OPTIMIZE} |
7cd4527e AC |
4319 | qualifier. |
4320 | ||
66bfd481 | 4321 | @item /OPTIMIZE@r{[}=(keyword@r{[},@dots{}@r{]})@r{]} |
7cd4527e AC |
4322 | @cindex @option{/OPTIMIZE} (@code{GNAT COMPILE}) |
4323 | Selects the level of optimization for your program. The supported | |
4324 | keywords are as follows: | |
4325 | @table @code | |
4326 | @item ALL | |
4327 | Perform most optimizations, including those that | |
4328 | are expensive. | |
e08b38f5 | 4329 | This is the default if the @option{/OPTIMIZE} qualifier is supplied |
7cd4527e | 4330 | without keyword options. |
88e1739c | 4331 | |
7cd4527e AC |
4332 | @item NONE |
4333 | Do not do any optimizations. Same as @code{/NOOPTIMIZE}. | |
88e1739c | 4334 | |
7cd4527e AC |
4335 | @item SOME |
4336 | Perform some optimizations, but omit ones that are costly. | |
88e1739c | 4337 | |
7cd4527e AC |
4338 | @item DEVELOPMENT |
4339 | Same as @code{SOME}. | |
4340 | ||
e08b38f5 VC |
4341 | @item INLINING |
4342 | Full optimization as in @option{/OPTIMIZE=ALL}, and also attempts | |
4343 | automatic inlining of small subprograms within a unit | |
4344 | ||
7cd4527e AC |
4345 | @item UNROLL_LOOPS |
4346 | Try to unroll loops. This keyword may be specified together with | |
4347 | any keyword above other than @code{NONE}. Loop unrolling | |
4348 | usually, but not always, improves the performance of programs. | |
e08b38f5 VC |
4349 | |
4350 | @item SPACE | |
4351 | Optimize space usage | |
7cd4527e | 4352 | @end table |
e08b38f5 VC |
4353 | |
4354 | @noindent | |
4355 | See also @ref{Optimization Levels}. | |
7cd4527e AC |
4356 | @end ifset |
4357 | ||
4358 | @ifclear vms | |
4359 | @item -pass-exit-codes | |
984a64bc | 4360 | @cindex @option{-pass-exit-codes} (@command{gcc}) |
7cd4527e AC |
4361 | Catch exit codes from the compiler and use the most meaningful as |
4362 | exit status. | |
4363 | @end ifclear | |
4364 | ||
4365 | @item --RTS=@var{rts-path} | |
984a64bc | 4366 | @cindex @option{--RTS} (@command{gcc}) |
7cd4527e | 4367 | Specifies the default location of the runtime library. Same meaning as the |
984a64bc | 4368 | equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). |
7cd4527e AC |
4369 | |
4370 | @item ^-S^/ASM^ | |
984a64bc | 4371 | @cindex @option{^-S^/ASM^} (@command{gcc}) |
7cd4527e AC |
4372 | ^Used in place of @option{-c} to^Used to^ |
4373 | cause the assembler source file to be | |
4374 | generated, using @file{^.s^.S^} as the extension, | |
4375 | instead of the object file. | |
4376 | This may be useful if you need to examine the generated assembly code. | |
4377 | ||
6cdb2c6e | 4378 | @item ^-fverbose-asm^/VERBOSE_ASM^ |
984a64bc | 4379 | @cindex @option{^-fverbose-asm^/VERBOSE_ASM^} (@command{gcc}) |
6cdb2c6e AC |
4380 | ^Used in conjunction with @option{-S}^Used in place of @option{/ASM}^ |
4381 | to cause the generated assembly code file to be annotated with variable | |
4382 | names, making it significantly easier to follow. | |
4383 | ||
7cd4527e | 4384 | @item ^-v^/VERBOSE^ |
984a64bc AC |
4385 | @cindex @option{^-v^/VERBOSE^} (@command{gcc}) |
4386 | Show commands generated by the @command{gcc} driver. Normally used only for | |
7cd4527e AC |
4387 | debugging purposes or if you need to be sure what version of the |
4388 | compiler you are executing. | |
4389 | ||
4390 | @ifclear vms | |
4391 | @item -V @var{ver} | |
984a64bc AC |
4392 | @cindex @option{-V} (@command{gcc}) |
4393 | Execute @var{ver} version of the compiler. This is the @command{gcc} | |
7cd4527e AC |
4394 | version, not the GNAT version. |
4395 | @end ifclear | |
4396 | ||
a2ad1f79 | 4397 | @item ^-w^/NO_BACK_END_WARNINGS^ |
32e209e4 CC |
4398 | @cindex @option{-w} (@command{gcc}) |
4399 | Turn off warnings generated by the back end of the compiler. Use of | |
4400 | this switch also causes the default for front end warnings to be set | |
4401 | to suppress (as though @option{-gnatws} had appeared at the start of | |
1a5f40e1 | 4402 | the options). |
32e209e4 | 4403 | |
7cd4527e AC |
4404 | @end table |
4405 | ||
4406 | @ifclear vms | |
7e3d710b | 4407 | @c Combining qualifiers does not work on VMS |
7cd4527e AC |
4408 | You may combine a sequence of GNAT switches into a single switch. For |
4409 | example, the combined switch | |
4410 | ||
4411 | @cindex Combining GNAT switches | |
4412 | @smallexample | |
4413 | -gnatofi3 | |
4414 | @end smallexample | |
4415 | ||
4416 | @noindent | |
4417 | is equivalent to specifying the following sequence of switches: | |
4418 | ||
4419 | @smallexample | |
4420 | -gnato -gnatf -gnati3 | |
4421 | @end smallexample | |
4422 | @end ifclear | |
4423 | ||
7cd4527e AC |
4424 | @noindent |
4425 | The following restrictions apply to the combination of switches | |
4426 | in this manner: | |
4427 | ||
4428 | @itemize @bullet | |
4429 | @item | |
4430 | The switch @option{-gnatc} if combined with other switches must come | |
4431 | first in the string. | |
4432 | ||
4433 | @item | |
4434 | The switch @option{-gnats} if combined with other switches must come | |
4435 | first in the string. | |
4436 | ||
4437 | @item | |
4438 | The switches | |
c94a0b9d AC |
4439 | ^^@option{/DISTRIBUTION_STUBS=},^ |
4440 | @option{-gnatzc} and @option{-gnatzr} may not be combined with any other | |
4441 | switches, and only one of them may appear in the command line. | |
7cd4527e | 4442 | |
3f165ff2 AC |
4443 | @item |
4444 | The switch @option{-gnat-p} may not be combined with any other switch. | |
4445 | ||
7cd4527e AC |
4446 | @ifclear vms |
4447 | @item | |
4448 | Once a ``y'' appears in the string (that is a use of the @option{-gnaty} | |
4449 | switch), then all further characters in the switch are interpreted | |
4450 | as style modifiers (see description of @option{-gnaty}). | |
4451 | ||
4452 | @item | |
4453 | Once a ``d'' appears in the string (that is a use of the @option{-gnatd} | |
4454 | switch), then all further characters in the switch are interpreted | |
4455 | as debug flags (see description of @option{-gnatd}). | |
88e1739c FW |
4456 | |
4457 | @item | |
7cd4527e | 4458 | Once a ``w'' appears in the string (that is a use of the @option{-gnatw} |
88e1739c FW |
4459 | switch), then all further characters in the switch are interpreted |
4460 | as warning mode modifiers (see description of @option{-gnatw}). | |
4461 | ||
4462 | @item | |
7cd4527e | 4463 | Once a ``V'' appears in the string (that is a use of the @option{-gnatV} |
88e1739c | 4464 | switch), then all further characters in the switch are interpreted |
e1aca343 | 4465 | as validity checking options (@pxref{Validity Checking}). |
1a105488 AC |
4466 | |
4467 | @item | |
4468 | Option ``em'', ``ec'', ``ep'', ``l='' and ``R'' must be the last options in | |
4469 | a combined list of options. | |
7cd4527e | 4470 | @end ifclear |
88e1739c FW |
4471 | @end itemize |
4472 | ||
4473 | @node Output and Error Message Control | |
4474 | @subsection Output and Error Message Control | |
4475 | @findex stderr | |
4476 | ||
4477 | @noindent | |
7cd4527e | 4478 | The standard default format for error messages is called ``brief format''. |
88e1739c FW |
4479 | Brief format messages are written to @file{stderr} (the standard error |
4480 | file) and have the following form: | |
4481 | ||
4482 | @smallexample | |
88e1739c FW |
4483 | e.adb:3:04: Incorrect spelling of keyword "function" |
4484 | e.adb:4:20: ";" should be "is" | |
4485 | @end smallexample | |
4486 | ||
4487 | @noindent | |
4488 | The first integer after the file name is the line number in the file, | |
4489 | and the second integer is the column number within the line. | |
e08b38f5 VC |
4490 | @ifclear vms |
4491 | @code{GPS} can parse the error messages | |
88e1739c | 4492 | and point to the referenced character. |
e08b38f5 | 4493 | @end ifclear |
88e1739c FW |
4494 | The following switches provide control over the error message |
4495 | format: | |
4496 | ||
7cd4527e AC |
4497 | @table @option |
4498 | @c !sort! | |
88e1739c | 4499 | @item -gnatv |
984a64bc | 4500 | @cindex @option{-gnatv} (@command{gcc}) |
88e1739c FW |
4501 | @findex stdout |
4502 | @ifclear vms | |
4503 | The v stands for verbose. | |
4504 | @end ifclear | |
4505 | The effect of this setting is to write long-format error | |
4506 | messages to @file{stdout} (the standard output file. | |
4507 | The same program compiled with the | |
4508 | @option{-gnatv} switch would generate: | |
4509 | ||
4510 | @smallexample | |
88e1739c FW |
4511 | @cartouche |
4512 | 3. funcion X (Q : Integer) | |
4513 | | | |
4514 | >>> Incorrect spelling of keyword "function" | |
4515 | 4. return Integer; | |
4516 | | | |
4517 | >>> ";" should be "is" | |
4518 | @end cartouche | |
88e1739c FW |
4519 | @end smallexample |
4520 | ||
4521 | @noindent | |
4522 | The vertical bar indicates the location of the error, and the @samp{>>>} | |
4523 | prefix can be used to search for error messages. When this switch is | |
4524 | used the only source lines output are those with errors. | |
4525 | ||
4526 | @item -gnatl | |
984a64bc | 4527 | @cindex @option{-gnatl} (@command{gcc}) |
88e1739c FW |
4528 | @ifclear vms |
4529 | The @code{l} stands for list. | |
4530 | @end ifclear | |
4531 | This switch causes a full listing of | |
ba1cbfb9 RD |
4532 | the file to be generated. In the case where a body is |
4533 | compiled, the corresponding spec is also listed, along | |
4534 | with any subunits. Typical output from compiling a package | |
4535 | body @file{p.adb} might look like: | |
88e1739c | 4536 | |
ba1cbfb9 | 4537 | @smallexample @c ada |
88e1739c | 4538 | @cartouche |
ba1cbfb9 RD |
4539 | Compiling: p.adb |
4540 | ||
4541 | 1. package body p is | |
4542 | 2. procedure a; | |
4543 | 3. procedure a is separate; | |
4544 | 4. begin | |
4545 | 5. null | |
4546 | | | |
4547 | >>> missing ";" | |
4548 | ||
4549 | 6. end; | |
4550 | ||
4551 | Compiling: p.ads | |
4552 | ||
4553 | 1. package p is | |
4554 | 2. pragma Elaborate_Body | |
4555 | | | |
4556 | >>> missing ";" | |
4557 | ||
4558 | 3. end p; | |
4559 | ||
4560 | Compiling: p-a.adb | |
4561 | ||
4562 | 1. separate p | |
4563 | | | |
4564 | >>> missing "(" | |
4565 | ||
4566 | 2. procedure a is | |
4567 | 3. begin | |
4568 | 4. null | |
4569 | | | |
4570 | >>> missing ";" | |
4571 | ||
4572 | 5. end; | |
88e1739c | 4573 | @end cartouche |
88e1739c FW |
4574 | @end smallexample |
4575 | ||
4576 | @noindent | |
4577 | @findex stderr | |
4578 | When you specify the @option{-gnatv} or @option{-gnatl} switches and | |
4579 | standard output is redirected, a brief summary is written to | |
4580 | @file{stderr} (standard error) giving the number of error messages and | |
4581 | warning messages generated. | |
4582 | ||
3fd9f17c AC |
4583 | @item ^-gnatl^/OUTPUT_FILE^=file |
4584 | @cindex @option{^-gnatl^/OUTPUT_FILE^=fname} (@command{gcc}) | |
1992bbd9 | 4585 | This has the same effect as @option{-gnatl} except that the output is |
ba1cbfb9 RD |
4586 | written to a file instead of to standard output. If the given name |
4587 | @file{fname} does not start with a period, then it is the full name | |
4588 | of the file to be written. If @file{fname} is an extension, it is | |
4589 | appended to the name of the file being compiled. For example, if | |
3fd9f17c | 4590 | file @file{xyz.adb} is compiled with @option{^-gnatl^/OUTPUT_FILE^=.lst}, |
ba1cbfb9 RD |
4591 | then the output is written to file ^xyz.adb.lst^xyz.adb_lst^. |
4592 | ||
88e1739c | 4593 | @item -gnatU |
984a64bc | 4594 | @cindex @option{-gnatU} (@command{gcc}) |
88e1739c | 4595 | This switch forces all error messages to be preceded by the unique |
7cd4527e | 4596 | string ``error:''. This means that error messages take a few more |
88e1739c FW |
4597 | characters in space, but allows easy searching for and identification |
4598 | of error messages. | |
4599 | ||
4600 | @item -gnatb | |
984a64bc | 4601 | @cindex @option{-gnatb} (@command{gcc}) |
88e1739c FW |
4602 | @ifclear vms |
4603 | The @code{b} stands for brief. | |
4604 | @end ifclear | |
4605 | This switch causes GNAT to generate the | |
4606 | brief format error messages to @file{stderr} (the standard error | |
4607 | file) as well as the verbose | |
4608 | format message or full listing (which as usual is written to | |
4609 | @file{stdout} (the standard output file). | |
4610 | ||
32e209e4 | 4611 | @item -gnatm=@var{n} |
984a64bc | 4612 | @cindex @option{-gnatm} (@command{gcc}) |
88e1739c FW |
4613 | @ifclear vms |
4614 | The @code{m} stands for maximum. | |
4615 | @end ifclear | |
4616 | @var{n} is a decimal integer in the | |
923e6ff3 RD |
4617 | range of 1 to 999999 and limits the number of error or warning |
4618 | messages to be generated. For example, using | |
4619 | @option{-gnatm2} might yield | |
88e1739c FW |
4620 | |
4621 | @smallexample | |
88e1739c FW |
4622 | e.adb:3:04: Incorrect spelling of keyword "function" |
4623 | e.adb:5:35: missing ".." | |
923e6ff3 | 4624 | fatal error: maximum number of errors detected |
88e1739c FW |
4625 | compilation abandoned |
4626 | @end smallexample | |
4627 | ||
923e6ff3 RD |
4628 | @noindent |
4629 | The default setting if | |
4630 | no switch is given is 9999. If the number of warnings reaches this | |
4631 | limit, then a message is output and further warnings are suppressed, | |
4632 | but the compilation is continued. If the number of error messages | |
4633 | reaches this limit, then a message is output and the compilation | |
4634 | is abandoned. A value of zero means that no limit applies. | |
4635 | ||
32e209e4 CC |
4636 | @noindent |
4637 | Note that the equal sign is optional, so the switches | |
4638 | @option{-gnatm2} and @option{-gnatm=2} are equivalent. | |
4639 | ||
88e1739c | 4640 | @item -gnatf |
984a64bc | 4641 | @cindex @option{-gnatf} (@command{gcc}) |
88e1739c FW |
4642 | @cindex Error messages, suppressing |
4643 | @ifclear vms | |
4644 | The @code{f} stands for full. | |
4645 | @end ifclear | |
4646 | Normally, the compiler suppresses error messages that are likely to be | |
4647 | redundant. This switch causes all error | |
4648 | messages to be generated. In particular, in the case of | |
4649 | references to undefined variables. If a given variable is referenced | |
4650 | several times, the normal format of messages is | |
4651 | @smallexample | |
88e1739c FW |
4652 | e.adb:7:07: "V" is undefined (more references follow) |
4653 | @end smallexample | |
4654 | ||
4655 | @noindent | |
4656 | where the parenthetical comment warns that there are additional | |
4657 | references to the variable @code{V}. Compiling the same program with the | |
4658 | @option{-gnatf} switch yields | |
4659 | ||
4660 | @smallexample | |
4661 | e.adb:7:07: "V" is undefined | |
4662 | e.adb:8:07: "V" is undefined | |
4663 | e.adb:8:12: "V" is undefined | |
4664 | e.adb:8:16: "V" is undefined | |
4665 | e.adb:9:07: "V" is undefined | |
4666 | e.adb:9:12: "V" is undefined | |
4667 | @end smallexample | |
4668 | ||
7cd4527e AC |
4669 | @noindent |
4670 | The @option{-gnatf} switch also generates additional information for | |
4671 | some error messages. Some examples are: | |
4672 | ||
4673 | @itemize @bullet | |
4674 | @item | |
7cd4527e AC |
4675 | Details on possibly non-portable unchecked conversion |
4676 | @item | |
4677 | List possible interpretations for ambiguous calls | |
4678 | @item | |
4679 | Additional details on incorrect parameters | |
4680 | @end itemize | |
4681 | ||
ba1cbfb9 RD |
4682 | @item -gnatjnn |
4683 | @cindex @option{-gnatjnn} (@command{gcc}) | |
5af46aa9 | 4684 | In normal operation mode (or if @option{-gnatj0} is used), then error messages |
ba1cbfb9 RD |
4685 | with continuation lines are treated as though the continuation lines were |
4686 | separate messages (and so a warning with two continuation lines counts as | |
4687 | three warnings, and is listed as three separate messages). | |
4688 | ||
4689 | If the @option{-gnatjnn} switch is used with a positive value for nn, then | |
4690 | messages are output in a different manner. A message and all its continuation | |
4691 | lines are treated as a unit, and count as only one warning or message in the | |
4692 | statistics totals. Furthermore, the message is reformatted so that no line | |
4693 | is longer than nn characters. | |
4694 | ||
88e1739c | 4695 | @item -gnatq |
984a64bc | 4696 | @cindex @option{-gnatq} (@command{gcc}) |
88e1739c | 4697 | @ifclear vms |
7cd4527e | 4698 | The @code{q} stands for quit (really ``don't quit''). |
88e1739c FW |
4699 | @end ifclear |
4700 | In normal operation mode, the compiler first parses the program and | |
4701 | determines if there are any syntax errors. If there are, appropriate | |
4702 | error messages are generated and compilation is immediately terminated. | |
4703 | This switch tells | |
4704 | GNAT to continue with semantic analysis even if syntax errors have been | |
4705 | found. This may enable the detection of more errors in a single run. On | |
4706 | the other hand, the semantic analyzer is more likely to encounter some | |
4707 | internal fatal error when given a syntactically invalid tree. | |
4708 | ||
4709 | @item -gnatQ | |
984a64bc | 4710 | @cindex @option{-gnatQ} (@command{gcc}) |
7cd4527e | 4711 | In normal operation mode, the @file{ALI} file is not generated if any |
88e1739c | 4712 | illegalities are detected in the program. The use of @option{-gnatQ} forces |
7cd4527e | 4713 | generation of the @file{ALI} file. This file is marked as being in |
88e1739c FW |
4714 | error, so it cannot be used for binding purposes, but it does contain |
4715 | reasonably complete cross-reference information, and thus may be useful | |
8dd07840 | 4716 | for use by tools (e.g., semantic browsing tools or integrated development |
7cd4527e AC |
4717 | environments) that are driven from the @file{ALI} file. This switch |
4718 | implies @option{-gnatq}, since the semantic phase must be run to get a | |
4719 | meaningful ALI file. | |
88e1739c FW |
4720 | |
4721 | In addition, if @option{-gnatt} is also specified, then the tree file is | |
4722 | generated even if there are illegalities. It may be useful in this case | |
4723 | to also specify @option{-gnatq} to ensure that full semantic processing | |
4724 | occurs. The resulting tree file can be processed by ASIS, for the purpose | |
4725 | of providing partial information about illegal units, but if the error | |
4726 | causes the tree to be badly malformed, then ASIS may crash during the | |
4727 | analysis. | |
4728 | ||
7cd4527e | 4729 | When @option{-gnatQ} is used and the generated @file{ALI} file is marked as |
984a64bc | 4730 | being in error, @command{gnatmake} will attempt to recompile the source when it |
7cd4527e AC |
4731 | finds such an @file{ALI} file, including with switch @option{-gnatc}. |
4732 | ||
4733 | Note that @option{-gnatQ} has no effect if @option{-gnats} is specified, | |
4734 | since ALI files are never generated if @option{-gnats} is set. | |
4735 | ||
88e1739c FW |
4736 | @end table |
4737 | ||
7cd4527e AC |
4738 | @node Warning Message Control |
4739 | @subsection Warning Message Control | |
4740 | @cindex Warning messages | |
88e1739c FW |
4741 | @noindent |
4742 | In addition to error messages, which correspond to illegalities as defined | |
e08b38f5 | 4743 | in the Ada Reference Manual, the compiler detects two kinds of warning |
88e1739c FW |
4744 | situations. |
4745 | ||
88e1739c FW |
4746 | First, the compiler considers some constructs suspicious and generates a |
4747 | warning message to alert you to a possible error. Second, if the | |
4748 | compiler detects a situation that is sure to raise an exception at | |
4749 | run time, it generates a warning message. The following shows an example | |
4750 | of warning messages: | |
4751 | @smallexample | |
88e1739c FW |
4752 | e.adb:4:24: warning: creation of object may raise Storage_Error |
4753 | e.adb:10:17: warning: static value out of range | |
4754 | e.adb:10:17: warning: "Constraint_Error" will be raised at run time | |
88e1739c FW |
4755 | @end smallexample |
4756 | ||
4757 | @noindent | |
4758 | GNAT considers a large number of situations as appropriate | |
4759 | for the generation of warning messages. As always, warnings are not | |
4760 | definite indications of errors. For example, if you do an out-of-range | |
4761 | assignment with the deliberate intention of raising a | |
4762 | @code{Constraint_Error} exception, then the warning that may be | |
4763 | issued does not indicate an error. Some of the situations for which GNAT | |
4764 | issues warnings (at least some of the time) are given in the following | |
7cd4527e AC |
4765 | list. This list is not complete, and new warnings are often added to |
4766 | subsequent versions of GNAT. The list is intended to give a general idea | |
4767 | of the kinds of warnings that are generated. | |
88e1739c FW |
4768 | |
4769 | @itemize @bullet | |
4770 | @item | |
4771 | Possible infinitely recursive calls | |
4772 | ||
4773 | @item | |
4774 | Out-of-range values being assigned | |
4775 | ||
4776 | @item | |
4777 | Possible order of elaboration problems | |
4778 | ||
a2ad1f79 RD |
4779 | @item |
4780 | Assertions (pragma Assert) that are sure to fail | |
4781 | ||
88e1739c FW |
4782 | @item |
4783 | Unreachable code | |
4784 | ||
ba1cbfb9 RD |
4785 | @item |
4786 | Address clauses with possibly unaligned values, or where an attempt is | |
4787 | made to overlay a smaller variable with a larger one. | |
4788 | ||
88e1739c FW |
4789 | @item |
4790 | Fixed-point type declarations with a null range | |
4791 | ||
523456db AC |
4792 | @item |
4793 | Direct_IO or Sequential_IO instantiated with a type that has access values | |
4794 | ||
88e1739c FW |
4795 | @item |
4796 | Variables that are never assigned a value | |
4797 | ||
4798 | @item | |
4799 | Variables that are referenced before being initialized | |
4800 | ||
4801 | @item | |
7cd4527e | 4802 | Task entries with no corresponding @code{accept} statement |
88e1739c FW |
4803 | |
4804 | @item | |
7cd4527e | 4805 | Duplicate accepts for the same task entry in a @code{select} |
88e1739c FW |
4806 | |
4807 | @item | |
4808 | Objects that take too much storage | |
4809 | ||
4810 | @item | |
4811 | Unchecked conversion between types of differing sizes | |
4812 | ||
4813 | @item | |
7cd4527e | 4814 | Missing @code{return} statement along some execution path in a function |
88e1739c FW |
4815 | |
4816 | @item | |
4817 | Incorrect (unrecognized) pragmas | |
4818 | ||
4819 | @item | |
4820 | Incorrect external names | |
4821 | ||
4822 | @item | |
4823 | Allocation from empty storage pool | |
4824 | ||
4825 | @item | |
7cd4527e | 4826 | Potentially blocking operation in protected type |
88e1739c FW |
4827 | |
4828 | @item | |
4829 | Suspicious parenthesization of expressions | |
4830 | ||
4831 | @item | |
4832 | Mismatching bounds in an aggregate | |
4833 | ||
4834 | @item | |
4835 | Attempt to return local value by reference | |
4836 | ||
88e1739c FW |
4837 | @item |
4838 | Premature instantiation of a generic body | |
4839 | ||
4840 | @item | |
4841 | Attempt to pack aliased components | |
4842 | ||
4843 | @item | |
4844 | Out of bounds array subscripts | |
4845 | ||
4846 | @item | |
4847 | Wrong length on string assignment | |
4848 | ||
4849 | @item | |
4850 | Violations of style rules if style checking is enabled | |
4851 | ||
4852 | @item | |
7cd4527e | 4853 | Unused @code{with} clauses |
88e1739c FW |
4854 | |
4855 | @item | |
7cd4527e | 4856 | @code{Bit_Order} usage that does not have any effect |
88e1739c FW |
4857 | |
4858 | @item | |
7cd4527e | 4859 | @code{Standard.Duration} used to resolve universal fixed expression |
88e1739c FW |
4860 | |
4861 | @item | |
4862 | Dereference of possibly null value | |
4863 | ||
4864 | @item | |
4865 | Declaration that is likely to cause storage error | |
4866 | ||
4867 | @item | |
7cd4527e | 4868 | Internal GNAT unit @code{with}'ed by application unit |
88e1739c FW |
4869 | |
4870 | @item | |
4871 | Values known to be out of range at compile time | |
4872 | ||
4873 | @item | |
0f361206 AC |
4874 | Unreferenced or unmodified variables. Note that a special |
4875 | exemption applies to variables which contain any of the substrings | |
4876 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED}, in any casing. Such variables | |
4877 | are considered likely to be intentionally used in a situation where | |
4878 | otherwise a warning would be given, so warnings of this kind are | |
4879 | always suppressed for such variables. | |
88e1739c FW |
4880 | |
4881 | @item | |
4882 | Address overlays that could clobber memory | |
4883 | ||
4884 | @item | |
4885 | Unexpected initialization when address clause present | |
4886 | ||
4887 | @item | |
4888 | Bad alignment for address clause | |
4889 | ||
4890 | @item | |
4891 | Useless type conversions | |
4892 | ||
4893 | @item | |
7cd4527e | 4894 | Redundant assignment statements and other redundant constructs |
88e1739c FW |
4895 | |
4896 | @item | |
7cd4527e | 4897 | Useless exception handlers |
88e1739c FW |
4898 | |
4899 | @item | |
7cd4527e AC |
4900 | Accidental hiding of name by child unit |
4901 | ||
88e1739c FW |
4902 | @item |
4903 | Access before elaboration detected at compile time | |
4904 | ||
4905 | @item | |
4906 | A range in a @code{for} loop that is known to be null or might be null | |
4907 | ||
4908 | @end itemize | |
4909 | ||
4910 | @noindent | |
ba1cbfb9 RD |
4911 | The following section lists compiler switches that are available |
4912 | to control the handling of warning messages. It is also possible | |
d3c56bc8 | 4913 | to exercise much finer control over what warnings are issued and |
b2e74434 RW |
4914 | suppressed using the GNAT pragma Warnings, @xref{Pragma Warnings,,, |
4915 | gnat_rm, GNAT Reference manual}. | |
88e1739c | 4916 | |
7cd4527e AC |
4917 | @table @option |
4918 | @c !sort! | |
4919 | @item -gnatwa | |
1928f450 | 4920 | @emph{Activate most optional warnings.} |
984a64bc | 4921 | @cindex @option{-gnatwa} (@command{gcc}) |
1928f450 | 4922 | This switch activates most optional warning messages. See the remaining list |
88e1739c | 4923 | in this section for details on optional warning messages that can be |
7cd4527e AC |
4924 | individually controlled. The warnings that are not turned on by this |
4925 | switch are | |
88e1739c | 4926 | @option{-gnatwd} (implicit dereferencing), |
7cd4527e | 4927 | @option{-gnatwh} (hiding), |
7fcd29e0 | 4928 | @option{-gnatw.d} (tag warnings with -gnatw switch) |
9a1bc6d5 | 4929 | @option{-gnatw.h} (holes (gaps) in record layouts) |
b688e030 | 4930 | @option{-gnatw.i} (overlapping actuals), |
a5a809b2 | 4931 | @option{-gnatw.k} (redefinition of names in standard), |
ba1cbfb9 | 4932 | @option{-gnatwl} (elaboration warnings), |
b2009d46 | 4933 | @option{-gnatw.l} (inherited aspects), |
b688e030 AC |
4934 | @option{-gnatw.o} (warn on values set by out parameters ignored), |
4935 | @option{-gnatwt} (tracking of deleted conditional code) | |
4936 | and @option{-gnatw.u} (unordered enumeration), | |
7cd4527e | 4937 | All other optional warnings are turned on. |
88e1739c | 4938 | |
7cd4527e AC |
4939 | @item -gnatwA |
4940 | @emph{Suppress all optional errors.} | |
984a64bc | 4941 | @cindex @option{-gnatwA} (@command{gcc}) |
88e1739c FW |
4942 | This switch suppresses all optional warning messages, see remaining list |
4943 | in this section for details on optional warning messages that can be | |
f6205414 AC |
4944 | individually controlled. Note that unlike switch @option{-gnatws}, the |
4945 | use of switch @option{-gnatwA} does not suppress warnings that are | |
4946 | normally given unconditionally and cannot be individually controlled | |
4947 | (for example, the warning about a missing exit path in a function). | |
4948 | Also, again unlike switch @option{-gnatws}, warnings suppressed by | |
4949 | the use of switch @option{-gnatwA} can be individually turned back | |
4950 | on. For example the use of switch @option{-gnatwA} followed by | |
4951 | switch @option{-gnatwd} will suppress all optional warnings except | |
4952 | the warnings for implicit dereferencing. | |
88e1739c | 4953 | |
a2ad1f79 RD |
4954 | @item -gnatw.a |
4955 | @emph{Activate warnings on failing assertions.} | |
4956 | @cindex @option{-gnatw.a} (@command{gcc}) | |
4957 | @cindex Assert failures | |
4958 | This switch activates warnings for assertions where the compiler can tell at | |
4959 | compile time that the assertion will fail. Note that this warning is given | |
4960 | even if assertions are disabled. The default is that such warnings are | |
4961 | generated. | |
4962 | ||
4963 | @item -gnatw.A | |
4964 | @emph{Suppress warnings on failing assertions.} | |
4965 | @cindex @option{-gnatw.A} (@command{gcc}) | |
4966 | @cindex Assert failures | |
4967 | This switch suppresses warnings for assertions where the compiler can tell at | |
4968 | compile time that the assertion will fail. | |
4969 | ||
debe0ab6 RD |
4970 | @item -gnatwb |
4971 | @emph{Activate warnings on bad fixed values.} | |
4972 | @cindex @option{-gnatwb} (@command{gcc}) | |
4973 | @cindex Bad fixed values | |
4974 | @cindex Fixed-point Small value | |
4975 | @cindex Small value | |
4976 | This switch activates warnings for static fixed-point expressions whose | |
4977 | value is not an exact multiple of Small. Such values are implementation | |
4978 | dependent, since an implementation is free to choose either of the multiples | |
4979 | that surround the value. GNAT always chooses the closer one, but this is not | |
4980 | required behavior, and it is better to specify a value that is an exact | |
4981 | multiple, ensuring predictable execution. The default is that such warnings | |
4982 | are not generated. | |
4983 | ||
4984 | @item -gnatwB | |
4985 | @emph{Suppress warnings on bad fixed values.} | |
4986 | @cindex @option{-gnatwB} (@command{gcc}) | |
4987 | This switch suppresses warnings for static fixed-point expressions whose | |
4988 | value is not an exact multiple of Small. | |
4989 | ||
c1bacb90 SR |
4990 | @item -gnatw.b |
4991 | @emph{Activate warnings on biased representation.} | |
4992 | @cindex @option{-gnatw.b} (@command{gcc}) | |
4993 | @cindex Biased representation | |
4994 | This switch activates warnings when a size clause, value size clause, component | |
4995 | clause, or component size clause forces the use of biased representation for an | |
4996 | integer type (e.g. representing a range of 10..11 in a single bit by using 0/1 | |
4997 | to represent 10/11). The default is that such warnings are generated. | |
4998 | ||
4999 | @item -gnatw.B | |
5000 | @emph{Suppress warnings on biased representation.} | |
5001 | @cindex @option{-gnatwB} (@command{gcc}) | |
5002 | This switch suppresses warnings for representation clauses that force the use | |
5003 | of biased representation. | |
5004 | ||
7cd4527e AC |
5005 | @item -gnatwc |
5006 | @emph{Activate warnings on conditionals.} | |
984a64bc | 5007 | @cindex @option{-gnatwc} (@command{gcc}) |
88e1739c FW |
5008 | @cindex Conditionals, constant |
5009 | This switch activates warnings for conditional expressions used in | |
5010 | tests that are known to be True or False at compile time. The default | |
5011 | is that such warnings are not generated. | |
7cd4527e AC |
5012 | Note that this warning does |
5013 | not get issued for the use of boolean variables or constants whose | |
5014 | values are known at compile time, since this is a standard technique | |
5015 | for conditional compilation in Ada, and this would generate too many | |
ba1cbfb9 | 5016 | false positive warnings. |
32e209e4 CC |
5017 | |
5018 | This warning option also activates a special test for comparisons using | |
7e3d710b AC |
5019 | the operators ``>='' and`` <=''. |
5020 | If the compiler can tell that only the equality condition is possible, | |
5021 | then it will warn that the ``>'' or ``<'' part of the test | |
5022 | is useless and that the operator could be replaced by ``=''. | |
5023 | An example would be comparing a @code{Natural} variable <= 0. | |
32e209e4 | 5024 | |
c690a2ec RD |
5025 | This warning option also generates warnings if |
5026 | one or both tests is optimized away in a membership test for integer | |
5027 | values if the result can be determined at compile time. Range tests on | |
5028 | enumeration types are not included, since it is common for such tests | |
5029 | to include an end point. | |
5030 | ||
88e1739c FW |
5031 | This warning can also be turned on using @option{-gnatwa}. |
5032 | ||
7cd4527e AC |
5033 | @item -gnatwC |
5034 | @emph{Suppress warnings on conditionals.} | |
984a64bc | 5035 | @cindex @option{-gnatwC} (@command{gcc}) |
88e1739c FW |
5036 | This switch suppresses warnings for conditional expressions used in |
5037 | tests that are known to be True or False at compile time. | |
5038 | ||
e08b38f5 VC |
5039 | @item -gnatw.c |
5040 | @emph{Activate warnings on missing component clauses.} | |
5041 | @cindex @option{-gnatw.c} (@command{gcc}) | |
5042 | @cindex Component clause, missing | |
5043 | This switch activates warnings for record components where a record | |
5044 | representation clause is present and has component clauses for the | |
5045 | majority, but not all, of the components. A warning is given for each | |
5046 | component for which no component clause is present. | |
5047 | ||
5048 | This warning can also be turned on using @option{-gnatwa}. | |
5049 | ||
5050 | @item -gnatw.C | |
5051 | @emph{Suppress warnings on missing component clauses.} | |
5052 | @cindex @option{-gnatwC} (@command{gcc}) | |
5053 | This switch suppresses warnings for record components that are | |
5054 | missing a component clause in the situation described above. | |
5055 | ||
7cd4527e AC |
5056 | @item -gnatwd |
5057 | @emph{Activate warnings on implicit dereferencing.} | |
984a64bc | 5058 | @cindex @option{-gnatwd} (@command{gcc}) |
88e1739c FW |
5059 | If this switch is set, then the use of a prefix of an access type |
5060 | in an indexed component, slice, or selected component without an | |
5061 | explicit @code{.all} will generate a warning. With this warning | |
5062 | enabled, access checks occur only at points where an explicit | |
5063 | @code{.all} appears in the source code (assuming no warnings are | |
5064 | generated as a result of this switch). The default is that such | |
5065 | warnings are not generated. | |
5066 | Note that @option{-gnatwa} does not affect the setting of | |
5067 | this warning option. | |
5068 | ||
7cd4527e AC |
5069 | @item -gnatwD |
5070 | @emph{Suppress warnings on implicit dereferencing.} | |
984a64bc | 5071 | @cindex @option{-gnatwD} (@command{gcc}) |
88e1739c FW |
5072 | @cindex Implicit dereferencing |
5073 | @cindex Dereferencing, implicit | |
7cd4527e | 5074 | This switch suppresses warnings for implicit dereferences in |
88e1739c FW |
5075 | indexed components, slices, and selected components. |
5076 | ||
7fcd29e0 RD |
5077 | @item -gnatw.d |
5078 | @emph{Activate tagging of warning messages.} | |
5079 | @cindex @option{-gnatw.d} (@command{gcc}) | |
5080 | If this switch is set, then warning messages are tagged, either with | |
5081 | the string ``@option{-gnatw?}'' showing which switch controls the warning, | |
5082 | or with ``[enabled by default]'' if the warning is not under control of a | |
5083 | specific @option{-gnatw?} switch. This mode is off by default, and is not | |
5084 | affected by the use of @code{-gnatwa}. | |
5085 | ||
5086 | @item -gnatw.D | |
5087 | @emph{Deactivate tagging of warning messages.} | |
5088 | @cindex @option{-gnatw.d} (@command{gcc}) | |
5089 | If this switch is set, then warning messages return to the default | |
5090 | mode in which warnings are not tagged as described above for | |
5091 | @code{-gnatw.d}. | |
882eadaf | 5092 | |
7cd4527e | 5093 | @item -gnatwe |
9cbfc269 | 5094 | @emph{Treat warnings and style checks as errors.} |
984a64bc | 5095 | @cindex @option{-gnatwe} (@command{gcc}) |
88e1739c | 5096 | @cindex Warnings, treat as error |
9cbfc269 AC |
5097 | This switch causes warning messages and style check messages to be |
5098 | treated as errors. | |
88e1739c | 5099 | The warning string still appears, but the warning messages are counted |
9cbfc269 AC |
5100 | as errors, and prevent the generation of an object file. Note that this |
5101 | is the only -gnatw switch that affects the handling of style check messages. | |
88e1739c | 5102 | |
1a5f40e1 VC |
5103 | @item -gnatw.e |
5104 | @emph{Activate every optional warning} | |
5105 | @cindex @option{-gnatw.e} (@command{gcc}) | |
5106 | @cindex Warnings, activate every optional warning | |
5107 | This switch activates all optional warnings, including those which | |
76264f60 AC |
5108 | are not activated by @code{-gnatwa}. The use of this switch is not |
5109 | recommended for normal use. If you turn this switch on, it is almost | |
5110 | certain that you will get large numbers of useless warnings. The | |
5111 | warnings that are excluded from @code{-gnatwa} are typically highly | |
5112 | specialized warnings that are suitable for use only in code that has | |
5113 | been specifically designed according to specialized coding rules. | |
1a5f40e1 | 5114 | |
7cd4527e AC |
5115 | @item -gnatwf |
5116 | @emph{Activate warnings on unreferenced formals.} | |
984a64bc | 5117 | @cindex @option{-gnatwf} (@command{gcc}) |
88e1739c FW |
5118 | @cindex Formals, unreferenced |
5119 | This switch causes a warning to be generated if a formal parameter | |
5120 | is not referenced in the body of the subprogram. This warning can | |
ba1cbfb9 RD |
5121 | also be turned on using @option{-gnatwa} or @option{-gnatwu}. The |
5122 | default is that these warnings are not generated. | |
88e1739c | 5123 | |
7cd4527e AC |
5124 | @item -gnatwF |
5125 | @emph{Suppress warnings on unreferenced formals.} | |
984a64bc | 5126 | @cindex @option{-gnatwF} (@command{gcc}) |
88e1739c FW |
5127 | This switch suppresses warnings for unreferenced formal |
5128 | parameters. Note that the | |
5129 | combination @option{-gnatwu} followed by @option{-gnatwF} has the | |
5130 | effect of warning on unreferenced entities other than subprogram | |
5131 | formals. | |
5132 | ||
7cd4527e AC |
5133 | @item -gnatwg |
5134 | @emph{Activate warnings on unrecognized pragmas.} | |
984a64bc | 5135 | @cindex @option{-gnatwg} (@command{gcc}) |
7cd4527e AC |
5136 | @cindex Pragmas, unrecognized |
5137 | This switch causes a warning to be generated if an unrecognized | |
5138 | pragma is encountered. Apart from issuing this warning, the | |
5139 | pragma is ignored and has no effect. This warning can | |
5140 | also be turned on using @option{-gnatwa}. The default | |
5141 | is that such warnings are issued (satisfying the Ada Reference | |
5142 | Manual requirement that such warnings appear). | |
5143 | ||
5144 | @item -gnatwG | |
5145 | @emph{Suppress warnings on unrecognized pragmas.} | |
984a64bc | 5146 | @cindex @option{-gnatwG} (@command{gcc}) |
7cd4527e AC |
5147 | This switch suppresses warnings for unrecognized pragmas. |
5148 | ||
5149 | @item -gnatwh | |
5150 | @emph{Activate warnings on hiding.} | |
984a64bc | 5151 | @cindex @option{-gnatwh} (@command{gcc}) |
88e1739c FW |
5152 | @cindex Hiding of Declarations |
5153 | This switch activates warnings on hiding declarations. | |
5154 | A declaration is considered hiding | |
5155 | if it is for a non-overloadable entity, and it declares an entity with the | |
5156 | same name as some other entity that is directly or use-visible. The default | |
5157 | is that such warnings are not generated. | |
5158 | Note that @option{-gnatwa} does not affect the setting of this warning option. | |
5159 | ||
7cd4527e AC |
5160 | @item -gnatwH |
5161 | @emph{Suppress warnings on hiding.} | |
984a64bc | 5162 | @cindex @option{-gnatwH} (@command{gcc}) |
88e1739c FW |
5163 | This switch suppresses warnings on hiding declarations. |
5164 | ||
9a1bc6d5 AC |
5165 | @item -gnatw.h |
5166 | @emph{Activate warnings on holes/gaps in records.} | |
5167 | @cindex @option{-gnatw.h} (@command{gcc}) | |
5168 | @cindex Record Representation (gaps) | |
5169 | This switch activates warnings on component clauses in record | |
5170 | representation clauses that leave holes (gaps) in the record layout. | |
5171 | If this warning option is active, then record representation clauses | |
5172 | should specify a contiguous layout, adding unused fill fields if needed. | |
5173 | Note that @option{-gnatwa} does not affect the setting of this warning option. | |
5174 | ||
5175 | @item -gnatw.H | |
5176 | @emph{Suppress warnings on holes/gaps in records.} | |
5177 | @cindex @option{-gnatw.H} (@command{gcc}) | |
5178 | This switch suppresses warnings on component clauses in record | |
5179 | representation clauses that leave holes (haps) in the record layout. | |
5180 | ||
7cd4527e AC |
5181 | @item -gnatwi |
5182 | @emph{Activate warnings on implementation units.} | |
984a64bc | 5183 | @cindex @option{-gnatwi} (@command{gcc}) |
88e1739c FW |
5184 | This switch activates warnings for a @code{with} of an internal GNAT |
5185 | implementation unit, defined as any unit from the @code{Ada}, | |
5186 | @code{Interfaces}, @code{GNAT}, | |
5187 | ^^@code{DEC},^ or @code{System} | |
5188 | hierarchies that is not | |
5189 | documented in either the Ada Reference Manual or the GNAT | |
5190 | Programmer's Reference Manual. Such units are intended only | |
5191 | for internal implementation purposes and should not be @code{with}'ed | |
5192 | by user programs. The default is that such warnings are generated | |
5193 | This warning can also be turned on using @option{-gnatwa}. | |
5194 | ||
7cd4527e AC |
5195 | @item -gnatwI |
5196 | @emph{Disable warnings on implementation units.} | |
984a64bc | 5197 | @cindex @option{-gnatwI} (@command{gcc}) |
88e1739c FW |
5198 | This switch disables warnings for a @code{with} of an internal GNAT |
5199 | implementation unit. | |
5200 | ||
110fcc77 AC |
5201 | @item -gnatw.i |
5202 | @emph{Activate warnings on overlapping actuals.} | |
5203 | @cindex @option{-gnatw.i} (@command{gcc}) | |
5fd3fd79 AC |
5204 | This switch enables a warning on statically detectable overlapping actuals in |
5205 | a subprogram call, when one of the actuals is an in-out parameter, and the | |
5206 | types of the actuals are not by-copy types. The warning is off by default, | |
5207 | and is not included under -gnatwa. | |
5208 | ||
5209 | @item -gnatw.I | |
5210 | @emph{Disable warnings on overlapping actuals.} | |
5211 | @cindex @option{-gnatw.I} (@command{gcc}) | |
5212 | This switch disables warnings on overlapping actuals in a call.. | |
110fcc77 | 5213 | |
7cd4527e AC |
5214 | @item -gnatwj |
5215 | @emph{Activate warnings on obsolescent features (Annex J).} | |
984a64bc | 5216 | @cindex @option{-gnatwj} (@command{gcc}) |
7cd4527e AC |
5217 | @cindex Features, obsolescent |
5218 | @cindex Obsolescent features | |
5219 | If this warning option is activated, then warnings are generated for | |
5220 | calls to subprograms marked with @code{pragma Obsolescent} and | |
5221 | for use of features in Annex J of the Ada Reference Manual. In the | |
5222 | case of Annex J, not all features are flagged. In particular use | |
5223 | of the renamed packages (like @code{Text_IO}) and use of package | |
5224 | @code{ASCII} are not flagged, since these are very common and | |
5225 | would generate many annoying positive warnings. The default is that | |
ba1cbfb9 RD |
5226 | such warnings are not generated. This warning is also turned on by |
5227 | the use of @option{-gnatwa}. | |
7cd4527e | 5228 | |
87b3f81f AC |
5229 | In addition to the above cases, warnings are also generated for |
5230 | GNAT features that have been provided in past versions but which | |
bde83138 | 5231 | have been superseded (typically by features in the new Ada standard). |
87b3f81f | 5232 | For example, @code{pragma Ravenscar} will be flagged since its |
477cfc5b AC |
5233 | function is replaced by @code{pragma Profile(Ravenscar)}, and |
5234 | @code{pragma Interface_Name} will be flagged since its function | |
5235 | is replaced by @code{pragma Import}. | |
87b3f81f AC |
5236 | |
5237 | Note that this warning option functions differently from the | |
5238 | restriction @code{No_Obsolescent_Features} in two respects. | |
5239 | First, the restriction applies only to annex J features. | |
5240 | Second, the restriction does flag uses of package @code{ASCII}. | |
5241 | ||
7cd4527e AC |
5242 | @item -gnatwJ |
5243 | @emph{Suppress warnings on obsolescent features (Annex J).} | |
984a64bc | 5244 | @cindex @option{-gnatwJ} (@command{gcc}) |
7cd4527e AC |
5245 | This switch disables warnings on use of obsolescent features. |
5246 | ||
5247 | @item -gnatwk | |
5248 | @emph{Activate warnings on variables that could be constants.} | |
984a64bc | 5249 | @cindex @option{-gnatwk} (@command{gcc}) |
7cd4527e | 5250 | This switch activates warnings for variables that are initialized but |
ba1cbfb9 RD |
5251 | never modified, and then could be declared constants. The default is that |
5252 | such warnings are not given. | |
5253 | This warning can also be turned on using @option{-gnatwa}. | |
7cd4527e AC |
5254 | |
5255 | @item -gnatwK | |
5256 | @emph{Suppress warnings on variables that could be constants.} | |
984a64bc | 5257 | @cindex @option{-gnatwK} (@command{gcc}) |
7cd4527e AC |
5258 | This switch disables warnings on variables that could be declared constants. |
5259 | ||
a5a809b2 AC |
5260 | @item -gnatw.k |
5261 | @emph{Activate warnings on redefinition of names in standard.} | |
5262 | @cindex @option{-gnatw.k} (@command{gcc}) | |
5263 | This switch activates warnings for declarations that declare a name that | |
5264 | is defined in package Standard. Such declarations can be confusing, | |
5265 | especially since the names in package Standard continue to be directly | |
5266 | visible, meaning that use visibiliy on such redeclared names does not | |
5267 | work as expected. Names of discriminants and components in records are | |
5268 | not included in this check. | |
5269 | This warning is not part of the warnings activated by @option{-gnatwa}. | |
5270 | It must be explicitly activated. | |
5271 | ||
5272 | @item -gnatw.K | |
5273 | @emph{Suppress warnings on variables that could be constants.} | |
5274 | @cindex @option{-gnatwK} (@command{gcc}) | |
5275 | This switch activates warnings for declarations that declare a name that | |
5276 | is defined in package Standard. | |
5277 | ||
7cd4527e | 5278 | @item -gnatwl |
1a5f40e1 | 5279 | @emph{Activate warnings for elaboration pragmas.} |
984a64bc | 5280 | @cindex @option{-gnatwl} (@command{gcc}) |
88e1739c | 5281 | @cindex Elaboration, warnings |
7cd4527e | 5282 | This switch activates warnings on missing |
32e209e4 | 5283 | @code{Elaborate_All} and @code{Elaborate} pragmas. |
88e1739c | 5284 | See the section in this guide on elaboration checking for details on |
1a5f40e1 VC |
5285 | when such pragmas should be used. In dynamic elaboration mode, this switch |
5286 | generations warnings about the need to add elaboration pragmas. Note however, | |
5287 | that if you blindly follow these warnings, and add @code{Elaborate_All} | |
5288 | warnings wherever they are recommended, you basically end up with the | |
5289 | equivalent of the static elaboration model, which may not be what you want for | |
5290 | legacy code for which the static model does not work. | |
5291 | ||
5292 | For the static model, the messages generated are labeled "info:" (for | |
5293 | information messages). They are not warnings to add elaboration pragmas, | |
5294 | merely informational messages showing what implicit elaboration pragmas | |
5295 | have been added, for use in analyzing elaboration circularity problems. | |
5296 | ||
5297 | Warnings are also generated if you | |
7cd4527e AC |
5298 | are using the static mode of elaboration, and a @code{pragma Elaborate} |
5299 | is encountered. The default is that such warnings | |
88e1739c | 5300 | are not generated. |
7cd4527e | 5301 | This warning is not automatically turned on by the use of @option{-gnatwa}. |
88e1739c | 5302 | |
7cd4527e | 5303 | @item -gnatwL |
1a5f40e1 | 5304 | @emph{Suppress warnings for elaboration pragmas.} |
984a64bc | 5305 | @cindex @option{-gnatwL} (@command{gcc}) |
32e209e4 | 5306 | This switch suppresses warnings on missing Elaborate and Elaborate_All pragmas. |
88e1739c | 5307 | See the section in this guide on elaboration checking for details on |
32e209e4 | 5308 | when such pragmas should be used. |
88e1739c | 5309 | |
b2009d46 AC |
5310 | @item -gnatw.l |
5311 | @emph{List inherited aspects.} | |
5312 | @cindex @option{-gnatw.l} (@command{gcc}) | |
5313 | This switch causes the compiler to list inherited invariants, | |
f307415a AC |
5314 | preconditions, and postconditions from Type_Invariant'Class, Invariant'Class, |
5315 | Pre'Class, and Post'Class aspects. Also list inherited subtype predicates. | |
b2009d46 AC |
5316 | These messages are not automatically turned on by the use of @option{-gnatwa}. |
5317 | ||
5318 | @item -gnatw.L | |
5319 | @emph{Suppress listing of inherited aspects.} | |
5320 | @cindex @option{-gnatw.L} (@command{gcc}) | |
5321 | This switch suppresses listing of inherited aspects. | |
5322 | ||
7cd4527e AC |
5323 | @item -gnatwm |
5324 | @emph{Activate warnings on modified but unreferenced variables.} | |
984a64bc | 5325 | @cindex @option{-gnatwm} (@command{gcc}) |
7cd4527e AC |
5326 | This switch activates warnings for variables that are assigned (using |
5327 | an initialization value or with one or more assignment statements) but | |
5328 | whose value is never read. The warning is suppressed for volatile | |
5329 | variables and also for variables that are renamings of other variables | |
5330 | or for which an address clause is given. | |
5331 | This warning can also be turned on using @option{-gnatwa}. | |
ba1cbfb9 | 5332 | The default is that these warnings are not given. |
7cd4527e AC |
5333 | |
5334 | @item -gnatwM | |
5335 | @emph{Disable warnings on modified but unreferenced variables.} | |
984a64bc | 5336 | @cindex @option{-gnatwM} (@command{gcc}) |
7cd4527e AC |
5337 | This switch disables warnings for variables that are assigned or |
5338 | initialized, but never read. | |
5339 | ||
79afa047 AC |
5340 | @item -gnatw.m |
5341 | @emph{Activate warnings on suspicious modulus values.} | |
5342 | @cindex @option{-gnatw.m} (@command{gcc}) | |
5343 | This switch activates warnings for modulus values that seem suspicious. | |
5344 | The cases caught are where the size is the same as the modulus (e.g. | |
5345 | a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64 | |
5346 | with no size clause. The guess in both cases is that 2**x was intended | |
2293611f AC |
5347 | rather than x. In addition expressions of the form 2*x for small x |
5348 | generate a warning (the almost certainly accurate guess being that | |
5349 | 2**x was intended). The default is that these warnings are given. | |
79afa047 AC |
5350 | |
5351 | @item -gnatw.M | |
5352 | @emph{Disable warnings on suspicious modulus values.} | |
5353 | @cindex @option{-gnatw.M} (@command{gcc}) | |
5354 | This switch disables warnings for suspicious modulus values. | |
5355 | ||
7cd4527e AC |
5356 | @item -gnatwn |
5357 | @emph{Set normal warnings mode.} | |
984a64bc | 5358 | @cindex @option{-gnatwn} (@command{gcc}) |
7cd4527e AC |
5359 | This switch sets normal warning mode, in which enabled warnings are |
5360 | issued and treated as warnings rather than errors. This is the default | |
5361 | mode. the switch @option{-gnatwn} can be used to cancel the effect of | |
5362 | an explicit @option{-gnatws} or | |
5363 | @option{-gnatwe}. It also cancels the effect of the | |
5364 | implicit @option{-gnatwe} that is activated by the | |
5365 | use of @option{-gnatg}. | |
5366 | ||
1250f802 RD |
5367 | @item -gnatw.n |
5368 | @emph{Activate warnings on atomic synchronization.} | |
5369 | @cindex @option{-gnatw.n} (@command{gcc}) | |
5370 | @cindex Atomic Synchronization, warnings | |
5371 | This switch actives warnings when an access to an atomic variable | |
5372 | requires the generation of atomic synchronization code. These | |
5373 | warnings are off by default and this warning is not included | |
5374 | in @code{-gnatwa}. | |
5375 | ||
5376 | @item -gnatw.N | |
5377 | @emph{Suppress warnings on atomic synchronization.} | |
5378 | @cindex @option{-gnatw.n} (@command{gcc}) | |
5379 | @cindex Atomic Synchronization, warnings | |
5380 | This switch suppresses warnings when an access to an atomic variable | |
5381 | requires the generation of atomic synchronization code. | |
5382 | ||
7cd4527e AC |
5383 | @item -gnatwo |
5384 | @emph{Activate warnings on address clause overlays.} | |
984a64bc | 5385 | @cindex @option{-gnatwo} (@command{gcc}) |
88e1739c FW |
5386 | @cindex Address Clauses, warnings |
5387 | This switch activates warnings for possibly unintended initialization | |
5388 | effects of defining address clauses that cause one variable to overlap | |
5389 | another. The default is that such warnings are generated. | |
5390 | This warning can also be turned on using @option{-gnatwa}. | |
5391 | ||
7cd4527e AC |
5392 | @item -gnatwO |
5393 | @emph{Suppress warnings on address clause overlays.} | |
984a64bc | 5394 | @cindex @option{-gnatwO} (@command{gcc}) |
88e1739c FW |
5395 | This switch suppresses warnings on possibly unintended initialization |
5396 | effects of defining address clauses that cause one variable to overlap | |
5397 | another. | |
5398 | ||
54df6fd9 VC |
5399 | @item -gnatw.o |
5400 | @emph{Activate warnings on modified but unreferenced out parameters.} | |
5401 | @cindex @option{-gnatw.o} (@command{gcc}) | |
5402 | This switch activates warnings for variables that are modified by using | |
5403 | them as actuals for a call to a procedure with an out mode formal, where | |
482434dc RD |
5404 | the resulting assigned value is never read. It is applicable in the case |
5405 | where there is more than one out mode formal. If there is only one out | |
e69044cb | 5406 | mode formal, the warning is issued by default (controlled by -gnatwu). |
54df6fd9 VC |
5407 | The warning is suppressed for volatile |
5408 | variables and also for variables that are renamings of other variables | |
5409 | or for which an address clause is given. | |
5410 | The default is that these warnings are not given. Note that this warning | |
5411 | is not included in -gnatwa, it must be activated explicitly. | |
5412 | ||
5413 | @item -gnatw.O | |
5414 | @emph{Disable warnings on modified but unreferenced out parameters.} | |
5415 | @cindex @option{-gnatw.O} (@command{gcc}) | |
5416 | This switch suppresses warnings for variables that are modified by using | |
5417 | them as actuals for a call to a procedure with an out mode formal, where | |
5418 | the resulting assigned value is never read. | |
5419 | ||
7cd4527e AC |
5420 | @item -gnatwp |
5421 | @emph{Activate warnings on ineffective pragma Inlines.} | |
984a64bc | 5422 | @cindex @option{-gnatwp} (@command{gcc}) |
88e1739c FW |
5423 | @cindex Inlining, warnings |
5424 | This switch activates warnings for failure of front end inlining | |
5425 | (activated by @option{-gnatN}) to inline a particular call. There are | |
5426 | many reasons for not being able to inline a call, including most | |
ba1cbfb9 RD |
5427 | commonly that the call is too complex to inline. The default is |
5428 | that such warnings are not given. | |
88e1739c | 5429 | This warning can also be turned on using @option{-gnatwa}. |
e08b38f5 VC |
5430 | Warnings on ineffective inlining by the gcc back-end can be activated |
5431 | separately, using the gcc switch -Winline. | |
88e1739c | 5432 | |
7cd4527e AC |
5433 | @item -gnatwP |
5434 | @emph{Suppress warnings on ineffective pragma Inlines.} | |
984a64bc | 5435 | @cindex @option{-gnatwP} (@command{gcc}) |
88e1739c FW |
5436 | This switch suppresses warnings on ineffective pragma Inlines. If the |
5437 | inlining mechanism cannot inline a call, it will simply ignore the | |
5438 | request silently. | |
5439 | ||
1a5f40e1 VC |
5440 | @item -gnatw.p |
5441 | @emph{Activate warnings on parameter ordering.} | |
5442 | @cindex @option{-gnatw.p} (@command{gcc}) | |
5443 | @cindex Parameter order, warnings | |
5444 | This switch activates warnings for cases of suspicious parameter | |
5445 | ordering when the list of arguments are all simple identifiers that | |
5446 | match the names of the formals, but are in a different order. The | |
5447 | warning is suppressed if any use of named parameter notation is used, | |
5448 | so this is the appropriate way to suppress a false positive (and | |
5449 | serves to emphasize that the "misordering" is deliberate). The | |
5450 | default is | |
5451 | that such warnings are not given. | |
5452 | This warning can also be turned on using @option{-gnatwa}. | |
5453 | ||
5454 | @item -gnatw.P | |
5455 | @emph{Suppress warnings on parameter ordering.} | |
5456 | @cindex @option{-gnatw.P} (@command{gcc}) | |
5457 | This switch suppresses warnings on cases of suspicious parameter | |
5458 | ordering. | |
5459 | ||
ba1cbfb9 RD |
5460 | @item -gnatwq |
5461 | @emph{Activate warnings on questionable missing parentheses.} | |
5462 | @cindex @option{-gnatwq} (@command{gcc}) | |
5463 | @cindex Parentheses, warnings | |
5464 | This switch activates warnings for cases where parentheses are not used and | |
5465 | the result is potential ambiguity from a readers point of view. For example | |
0916df6a | 5466 | (not a > b) when a and b are modular means ((not a) > b) and very likely the |
ba1cbfb9 RD |
5467 | programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and |
5468 | quite likely ((-x) mod 5) was intended. In such situations it seems best to | |
5469 | follow the rule of always parenthesizing to make the association clear, and | |
5470 | this warning switch warns if such parentheses are not present. The default | |
0916df6a | 5471 | is that these warnings are given. |
ba1cbfb9 RD |
5472 | This warning can also be turned on using @option{-gnatwa}. |
5473 | ||
5474 | @item -gnatwQ | |
5475 | @emph{Suppress warnings on questionable missing parentheses.} | |
5476 | @cindex @option{-gnatwQ} (@command{gcc}) | |
5477 | This switch suppresses warnings for cases where the association is not | |
5478 | clear and the use of parentheses is preferred. | |
5479 | ||
7cd4527e AC |
5480 | @item -gnatwr |
5481 | @emph{Activate warnings on redundant constructs.} | |
984a64bc | 5482 | @cindex @option{-gnatwr} (@command{gcc}) |
88e1739c FW |
5483 | This switch activates warnings for redundant constructs. The following |
5484 | is the current list of constructs regarded as redundant: | |
88e1739c FW |
5485 | |
5486 | @itemize @bullet | |
5487 | @item | |
5488 | Assignment of an item to itself. | |
5489 | @item | |
5490 | Type conversion that converts an expression to its own type. | |
5491 | @item | |
5492 | Use of the attribute @code{Base} where @code{typ'Base} is the same | |
5493 | as @code{typ}. | |
5494 | @item | |
5495 | Use of pragma @code{Pack} when all components are placed by a record | |
5496 | representation clause. | |
7cd4527e AC |
5497 | @item |
5498 | Exception handler containing only a reraise statement (raise with no | |
5499 | operand) which has no effect. | |
5500 | @item | |
5501 | Use of the operator abs on an operand that is known at compile time | |
5502 | to be non-negative | |
5503 | @item | |
7cd4527e | 5504 | Comparison of boolean expressions to an explicit True value. |
88e1739c FW |
5505 | @end itemize |
5506 | ||
ba1cbfb9 RD |
5507 | This warning can also be turned on using @option{-gnatwa}. |
5508 | The default is that warnings for redundant constructs are not given. | |
5509 | ||
7cd4527e AC |
5510 | @item -gnatwR |
5511 | @emph{Suppress warnings on redundant constructs.} | |
984a64bc | 5512 | @cindex @option{-gnatwR} (@command{gcc}) |
88e1739c FW |
5513 | This switch suppresses warnings for redundant constructs. |
5514 | ||
4e0d20ca BD |
5515 | @item -gnatw.r |
5516 | @emph{Activate warnings for object renaming function.} | |
5517 | @cindex @option{-gnatw.r} (@command{gcc}) | |
5518 | This switch activates warnings for an object renaming that renames a | |
5519 | function call, which is equivalent to a constant declaration (as | |
5520 | opposed to renaming the function itself). The default is that these | |
5521 | warnings are given. This warning can also be turned on using | |
5522 | @option{-gnatwa}. | |
5523 | ||
5524 | @item -gnatw.R | |
5525 | @emph{Suppress warnings for object renaming function.} | |
5526 | @cindex @option{-gnatwT} (@command{gcc}) | |
5527 | This switch suppresses warnings for object renaming function. | |
5528 | ||
7cd4527e AC |
5529 | @item -gnatws |
5530 | @emph{Suppress all warnings.} | |
984a64bc | 5531 | @cindex @option{-gnatws} (@command{gcc}) |
88e1739c | 5532 | This switch completely suppresses the |
f6205414 AC |
5533 | output of all warning messages from the GNAT front end, including |
5534 | both warnings that can be controlled by switches described in this | |
5535 | section, and those that are normally given unconditionally. The | |
5536 | effect of this suppress action can only be cancelled by a subsequent | |
5537 | use of the switch @option{-gnatwn}. | |
5538 | ||
5539 | Note that switch @option{-gnatws} does not suppress | |
5540 | warnings from the @command{gcc} back end. | |
7cd4527e | 5541 | To suppress these back end warnings as well, use the switch @option{-w} |
9cbfc269 AC |
5542 | in addition to @option{-gnatws}. Also this switch has no effect on the |
5543 | handling of style check messages. | |
88e1739c | 5544 | |
b3f48fd4 AC |
5545 | @item -gnatw.s |
5546 | @emph{Activate warnings on overridden size clauses.} | |
5547 | @cindex @option{-gnatw.s} (@command{gcc}) | |
5548 | @cindex Record Representation (component sizes) | |
5549 | This switch activates warnings on component clauses in record | |
5550 | representation clauses where the length given overrides that | |
5551 | specified by an explicit size clause for the component type. A | |
5552 | warning is similarly given in the array case if a specified | |
5553 | component size overrides an explicit size clause for the array | |
5554 | component type. | |
5555 | Note that @option{-gnatwa} does not affect the setting of this warning option. | |
5556 | ||
5557 | @item -gnatw.S | |
308e6f3a | 5558 | @emph{Suppress warnings on overridden size clauses.} |
b3f48fd4 AC |
5559 | @cindex @option{-gnatw.S} (@command{gcc}) |
5560 | This switch suppresses warnings on component clauses in record | |
5561 | representation clauses that override size clauses, and similar | |
5562 | warnings when an array component size overrides a size clause. | |
5563 | ||
ba1cbfb9 RD |
5564 | @item -gnatwt |
5565 | @emph{Activate warnings for tracking of deleted conditional code.} | |
5566 | @cindex @option{-gnatwt} (@command{gcc}) | |
5567 | @cindex Deactivated code, warnings | |
5568 | @cindex Deleted code, warnings | |
5569 | This switch activates warnings for tracking of code in conditionals (IF and | |
5570 | CASE statements) that is detected to be dead code which cannot be executed, and | |
5571 | which is removed by the front end. This warning is off by default, and is not | |
5572 | turned on by @option{-gnatwa}, it has to be turned on explicitly. This may be | |
5573 | useful for detecting deactivated code in certified applications. | |
5574 | ||
5575 | @item -gnatwT | |
5576 | @emph{Suppress warnings for tracking of deleted conditional code.} | |
5577 | @cindex @option{-gnatwT} (@command{gcc}) | |
5578 | This switch suppresses warnings for tracking of deleted conditional code. | |
5579 | ||
b688e030 AC |
5580 | @item -gnatw.t |
5581 | @emph{Activate warnings on suspicious contracts.} | |
5582 | @cindex @option{-gnatw.t} (@command{gcc}) | |
5583 | This switch activates warnings on suspicious postconditions (whether a | |
22f46473 | 5584 | pragma @code{Postcondition} or a @code{Post} aspect in Ada 2012) |
541fb4d9 | 5585 | and suspicious contract cases (pragma @code{Contract_Cases}). A |
22f46473 AC |
5586 | function postcondition or contract case is suspicious when no postcondition |
5587 | or contract case for this function mentions the result of the function. | |
5588 | A procedure postcondition or contract case is suspicious when it only | |
b688e030 | 5589 | refers to the pre-state of the procedure, because in that case it should |
6d9e03cb AC |
5590 | rather be expressed as a precondition. The default is that such warnings |
5591 | are not generated. This warning can also be turned on using @option{-gnatwa}. | |
b688e030 AC |
5592 | |
5593 | @item -gnatw.T | |
5594 | @emph{Suppress warnings on suspicious contracts.} | |
5595 | @cindex @option{-gnatw.T} (@command{gcc}) | |
5596 | This switch suppresses warnings on suspicious postconditions. | |
5597 | ||
7cd4527e AC |
5598 | @item -gnatwu |
5599 | @emph{Activate warnings on unused entities.} | |
984a64bc | 5600 | @cindex @option{-gnatwu} (@command{gcc}) |
88e1739c | 5601 | This switch activates warnings to be generated for entities that |
7cd4527e | 5602 | are declared but not referenced, and for units that are @code{with}'ed |
88e1739c FW |
5603 | and not |
5604 | referenced. In the case of packages, a warning is also generated if | |
4c9fe6c7 AC |
5605 | no entities in the package are referenced. This means that if a with'ed |
5606 | package is referenced but the only references are in @code{use} | |
88e1739c FW |
5607 | clauses or @code{renames} |
5608 | declarations, a warning is still generated. A warning is also generated | |
5609 | for a generic package that is @code{with}'ed but never instantiated. | |
5610 | In the case where a package or subprogram body is compiled, and there | |
5611 | is a @code{with} on the corresponding spec | |
5612 | that is only referenced in the body, | |
5613 | a warning is also generated, noting that the | |
5614 | @code{with} can be moved to the body. The default is that | |
5615 | such warnings are not generated. | |
5616 | This switch also activates warnings on unreferenced formals | |
984a64bc | 5617 | (it includes the effect of @option{-gnatwf}). |
88e1739c FW |
5618 | This warning can also be turned on using @option{-gnatwa}. |
5619 | ||
7cd4527e AC |
5620 | @item -gnatwU |
5621 | @emph{Suppress warnings on unused entities.} | |
984a64bc | 5622 | @cindex @option{-gnatwU} (@command{gcc}) |
88e1739c FW |
5623 | This switch suppresses warnings for unused entities and packages. |
5624 | It also turns off warnings on unreferenced formals (and thus includes | |
5625 | the effect of @option{-gnatwF}). | |
5626 | ||
bd29d519 AC |
5627 | @item -gnatw.u |
5628 | @emph{Activate warnings on unordered enumeration types.} | |
5629 | @cindex @option{-gnatw.u} (@command{gcc}) | |
5630 | This switch causes enumeration types to be considered as conceptually | |
913eb73e AC |
5631 | unordered, unless an explicit pragma @code{Ordered} is given for the type. |
5632 | The effect is to generate warnings in clients that use explicit comparisons | |
bd29d519 | 5633 | or subranges, since these constructs both treat objects of the type as |
913eb73e AC |
5634 | ordered. (A @emph{client} is defined as a unit that is other than the unit in |
5635 | which the type is declared, or its body or subunits.) Please refer to | |
5636 | the description of pragma @code{Ordered} in the | |
5637 | @cite{@value{EDITION} Reference Manual} for further details. | |
6d9e03cb AC |
5638 | The default is that such warnings are not generated. |
5639 | This warning is not automatically turned on by the use of @option{-gnatwa}. | |
bd29d519 AC |
5640 | |
5641 | @item -gnatw.U | |
5642 | @emph{Deactivate warnings on unordered enumeration types.} | |
5643 | @cindex @option{-gnatw.U} (@command{gcc}) | |
5644 | This switch causes all enumeration types to be considered as ordered, so | |
5645 | that no warnings are given for comparisons or subranges for any type. | |
5646 | ||
7cd4527e AC |
5647 | @item -gnatwv |
5648 | @emph{Activate warnings on unassigned variables.} | |
984a64bc | 5649 | @cindex @option{-gnatwv} (@command{gcc}) |
7cd4527e AC |
5650 | @cindex Unassigned variable warnings |
5651 | This switch activates warnings for access to variables which | |
5652 | may not be properly initialized. The default is that | |
5653 | such warnings are generated. | |
ba1cbfb9 | 5654 | This warning can also be turned on using @option{-gnatwa}. |
7cd4527e AC |
5655 | |
5656 | @item -gnatwV | |
5657 | @emph{Suppress warnings on unassigned variables.} | |
984a64bc | 5658 | @cindex @option{-gnatwV} (@command{gcc}) |
7cd4527e AC |
5659 | This switch suppresses warnings for access to variables which |
5660 | may not be properly initialized. | |
e08b38f5 VC |
5661 | For variables of a composite type, the warning can also be suppressed in |
5662 | Ada 2005 by using a default initialization with a box. For example, if | |
5663 | Table is an array of records whose components are only partially uninitialized, | |
5664 | then the following code: | |
5665 | ||
5666 | @smallexample @c ada | |
5667 | Tab : Table := (others => <>); | |
5668 | @end smallexample | |
5669 | ||
5670 | will suppress warnings on subsequent statements that access components | |
5671 | of variable Tab. | |
7cd4527e | 5672 | |
02f58834 AC |
5673 | @item -gnatw.v |
5674 | @emph{Activate info messages for non-default bit order.} | |
5675 | @cindex @option{-gnatw.v} (@command{gcc}) | |
5676 | @cindex bit order warnings | |
5677 | This switch activates messages (labeled "info", they are not warnings, | |
5678 | just informational messages) about the effects of non-default bit-order | |
5679 | on records to which a component clause is applied. The effect of specifying | |
5680 | non-default bit ordering is a bit subtle (and changed with Ada 2005), so | |
5681 | these messages, which are given by default, are useful in understanding the | |
5682 | exact consequences of using this feature. These messages | |
5683 | can also be turned on using @option{-gnatwa} | |
5684 | ||
5685 | @item -gnatw.V | |
5686 | @emph{Suppress info messages for non-default bit order.} | |
5687 | @cindex @option{-gnatw.V} (@command{gcc}) | |
5688 | This switch suppresses information messages for the effects of specifying | |
5689 | non-default bit order on record components with component clauses. | |
5690 | ||
ba1cbfb9 RD |
5691 | @item -gnatww |
5692 | @emph{Activate warnings on wrong low bound assumption.} | |
5693 | @cindex @option{-gnatww} (@command{gcc}) | |
5694 | @cindex String indexing warnings | |
5695 | This switch activates warnings for indexing an unconstrained string parameter | |
5696 | with a literal or S'Length. This is a case where the code is assuming that the | |
5697 | low bound is one, which is in general not true (for example when a slice is | |
5698 | passed). The default is that such warnings are generated. | |
5699 | This warning can also be turned on using @option{-gnatwa}. | |
0453ca3d | 5700 | |
ba1cbfb9 RD |
5701 | @item -gnatwW |
5702 | @emph{Suppress warnings on wrong low bound assumption.} | |
5703 | @cindex @option{-gnatwW} (@command{gcc}) | |
da508766 RD |
5704 | This switch suppresses warnings for indexing an unconstrained string parameter |
5705 | with a literal or S'Length. Note that this warning can also be suppressed | |
5706 | in a particular case by adding an | |
5707 | assertion that the lower bound is 1, | |
5708 | as shown in the following example. | |
ba1cbfb9 RD |
5709 | |
5710 | @smallexample @c ada | |
5711 | procedure K (S : String) is | |
5712 | pragma Assert (S'First = 1); | |
d488f6ea | 5713 | @dots{} |
ba1cbfb9 | 5714 | @end smallexample |
0453ca3d | 5715 | |
da508766 | 5716 | @item -gnatw.w |
74c10109 | 5717 | @emph{Activate warnings on Warnings Off pragmas} |
da508766 RD |
5718 | @cindex @option{-gnatw.w} (@command{gcc}) |
5719 | @cindex Warnings Off control | |
6b81741c | 5720 | This switch activates warnings for use of @code{pragma Warnings (Off, entity)} |
da508766 RD |
5721 | where either the pragma is entirely useless (because it suppresses no |
5722 | warnings), or it could be replaced by @code{pragma Unreferenced} or | |
a3068ca6 | 5723 | @code{pragma Unmodified}. The default is that these warnings are not given. |
da508766 | 5724 | Note that this warning is not included in -gnatwa, it must be |
74c10109 AC |
5725 | activated explicitly. Also activates warnings for the case of |
5726 | Warnings (Off, String), where either there is no matching | |
5727 | Warnings (On, String), or the Warnings (Off) did not suppress any warning. | |
da508766 RD |
5728 | |
5729 | @item -gnatw.W | |
5730 | @emph{Suppress warnings on unnecessary Warnings Off pragmas} | |
5731 | @cindex @option{-gnatw.W} (@command{gcc}) | |
74c10109 | 5732 | This switch suppresses warnings for use of @code{pragma Warnings (Off, ...)}. |
da508766 | 5733 | |
7cd4527e AC |
5734 | @item -gnatwx |
5735 | @emph{Activate warnings on Export/Import pragmas.} | |
984a64bc | 5736 | @cindex @option{-gnatwx} (@command{gcc}) |
7cd4527e AC |
5737 | @cindex Export/Import pragma warnings |
5738 | This switch activates warnings on Export/Import pragmas when | |
5739 | the compiler detects a possible conflict between the Ada and | |
5740 | foreign language calling sequences. For example, the use of | |
5741 | default parameters in a convention C procedure is dubious | |
5742 | because the C compiler cannot supply the proper default, so | |
5743 | a warning is issued. The default is that such warnings are | |
5744 | generated. | |
ba1cbfb9 | 5745 | This warning can also be turned on using @option{-gnatwa}. |
7cd4527e AC |
5746 | |
5747 | @item -gnatwX | |
5748 | @emph{Suppress warnings on Export/Import pragmas.} | |
984a64bc | 5749 | @cindex @option{-gnatwX} (@command{gcc}) |
7cd4527e AC |
5750 | This switch suppresses warnings on Export/Import pragmas. |
5751 | The sense of this is that you are telling the compiler that | |
5752 | you know what you are doing in writing the pragma, and it | |
5753 | should not complain at you. | |
5754 | ||
e08b38f5 VC |
5755 | @item -gnatw.x |
5756 | @emph{Activate warnings for No_Exception_Propagation mode.} | |
5757 | @cindex @option{-gnatwm} (@command{gcc}) | |
5758 | This switch activates warnings for exception usage when pragma Restrictions | |
5759 | (No_Exception_Propagation) is in effect. Warnings are given for implicit or | |
5760 | explicit exception raises which are not covered by a local handler, and for | |
5761 | exception handlers which do not cover a local raise. The default is that these | |
c690a2ec | 5762 | warnings are not given. |
e08b38f5 VC |
5763 | |
5764 | @item -gnatw.X | |
5765 | @emph{Disable warnings for No_Exception_Propagation mode.} | |
5766 | This switch disables warnings for exception usage when pragma Restrictions | |
5767 | (No_Exception_Propagation) is in effect. | |
5768 | ||
ba1cbfb9 | 5769 | @item -gnatwy |
ff4f0ed0 | 5770 | @emph{Activate warnings for Ada compatibility issues.} |
ba1cbfb9 | 5771 | @cindex @option{-gnatwy} (@command{gcc}) |
ff4f0ed0 AC |
5772 | @cindex Ada compatibility issues warnings |
5773 | For the most part, newer versions of Ada are upwards compatible | |
5774 | with older versions. For example, Ada 2005 programs will almost | |
5775 | always work when compiled as Ada 2012. | |
5776 | However there are some exceptions (for example the fact that | |
5777 | @code{some} is now a reserved word in Ada 2012). This | |
ba1cbfb9 RD |
5778 | switch activates several warnings to help in identifying |
5779 | and correcting such incompatibilities. The default is that | |
5780 | these warnings are generated. Note that at one point Ada 2005 | |
5781 | was called Ada 0Y, hence the choice of character. | |
5782 | This warning can also be turned on using @option{-gnatwa}. | |
5783 | ||
5784 | @item -gnatwY | |
ff4f0ed0 | 5785 | @emph{Disable warnings for Ada compatibility issues.} |
ba1cbfb9 | 5786 | @cindex @option{-gnatwY} (@command{gcc}) |
ff4f0ed0 AC |
5787 | @cindex Ada compatibility issues warnings |
5788 | This switch suppresses the warnings intended to help in identifying | |
5789 | incompatibilities between Ada language versions. | |
ba1cbfb9 | 5790 | |
98779361 RD |
5791 | @item -gnatw.y |
5792 | @emph{Activate information messages for why package spec needs body} | |
5793 | @cindex @option{-gnatw.y} (@command{gcc}) | |
5794 | @cindex Package spec needing body | |
5795 | There are a number of cases in which a package spec needs a body. | |
5796 | For example, the use of pragma Elaborate_Body, or the declaration | |
5797 | of a procedure specification requiring a completion. This switch | |
5798 | causes information messages to be output showing why a package | |
5799 | specification requires a body. This can be useful in the case of | |
5800 | a large package specification which is unexpectedly requiring a | |
5801 | body. The default is that such information messages are not output. | |
5802 | ||
5803 | @item -gnatw.Y | |
5804 | @emph{Disable information messages for why package spec needs body} | |
5805 | @cindex @option{-gnatw.Y} (@command{gcc}) | |
5806 | @cindex No information messages for why package spec needs body | |
5807 | This switch suppresses the output of information messages showing why | |
5808 | a package specification needs a body. | |
5809 | ||
7cd4527e AC |
5810 | @item -gnatwz |
5811 | @emph{Activate warnings on unchecked conversions.} | |
984a64bc | 5812 | @cindex @option{-gnatwz} (@command{gcc}) |
7cd4527e AC |
5813 | @cindex Unchecked_Conversion warnings |
5814 | This switch activates warnings for unchecked conversions | |
5815 | where the types are known at compile time to have different | |
5816 | sizes. The default | |
da508766 RD |
5817 | is that such warnings are generated. Warnings are also |
5818 | generated for subprogram pointers with different conventions, | |
5819 | and, on VMS only, for data pointers with different conventions. | |
ba1cbfb9 | 5820 | This warning can also be turned on using @option{-gnatwa}. |
7cd4527e AC |
5821 | |
5822 | @item -gnatwZ | |
5823 | @emph{Suppress warnings on unchecked conversions.} | |
984a64bc | 5824 | @cindex @option{-gnatwZ} (@command{gcc}) |
7cd4527e AC |
5825 | This switch suppresses warnings for unchecked conversions |
5826 | where the types are known at compile time to have different | |
da508766 | 5827 | sizes or conventions. |
7cd4527e | 5828 | |
1a5f40e1 VC |
5829 | @item ^-Wunused^WARNINGS=UNUSED^ |
5830 | @cindex @option{-Wunused} | |
5831 | The warnings controlled by the @option{-gnatw} switch are generated by | |
5832 | the front end of the compiler. The @option{GCC} back end can provide | |
5833 | additional warnings and they are controlled by the @option{-W} switch. | |
5834 | For example, @option{^-Wunused^WARNINGS=UNUSED^} activates back end | |
5835 | warnings for entities that are declared but not referenced. | |
5836 | ||
7cd4527e AC |
5837 | @item ^-Wuninitialized^WARNINGS=UNINITIALIZED^ |
5838 | @cindex @option{-Wuninitialized} | |
1a5f40e1 VC |
5839 | Similarly, @option{^-Wuninitialized^WARNINGS=UNINITIALIZED^} activates |
5840 | the back end warning for uninitialized variables. This switch must be | |
5841 | used in conjunction with an optimization level greater than zero. | |
5842 | ||
56e94186 AC |
5843 | @item -Wstack-usage=@var{len} |
5844 | @cindex @option{-Wstack-usage} | |
5845 | Warn if the stack usage of a subprogram might be larger than @var{len} bytes. | |
5846 | See @ref{Static Stack Usage Analysis} for details. | |
5847 | ||
1a5f40e1 VC |
5848 | @item ^-Wall^/ALL_BACK_END_WARNINGS^ |
5849 | @cindex @option{-Wall} | |
56e94186 | 5850 | This switch enables most warnings from the @option{GCC} back end. |
1a5f40e1 VC |
5851 | The code generator detects a number of warning situations that are missed |
5852 | by the @option{GNAT} front end, and this switch can be used to activate them. | |
5853 | The use of this switch also sets the default front end warning mode to | |
5854 | @option{-gnatwa}, that is, most front end warnings activated as well. | |
7cd4527e AC |
5855 | |
5856 | @item ^-w^/NO_BACK_END_WARNINGS^ | |
5857 | @cindex @option{-w} | |
1a5f40e1 | 5858 | Conversely, this switch suppresses warnings from the @option{GCC} back end. |
32e209e4 CC |
5859 | The use of this switch also sets the default front end warning mode to |
5860 | @option{-gnatws}, that is, front end warnings suppressed as well. | |
7cd4527e AC |
5861 | |
5862 | @end table | |
5863 | ||
88e1739c | 5864 | @noindent |
7cd4527e | 5865 | @ifclear vms |
88e1739c FW |
5866 | A string of warning parameters can be used in the same parameter. For example: |
5867 | ||
5868 | @smallexample | |
6d9e03cb | 5869 | -gnatwaGe |
88e1739c FW |
5870 | @end smallexample |
5871 | ||
5872 | @noindent | |
6d9e03cb | 5873 | will turn on all optional warnings except for unrecognized pragma warnings, |
88e1739c | 5874 | and also specify that warnings should be treated as errors. |
7cd4527e | 5875 | @end ifclear |
6d9e03cb | 5876 | |
7cd4527e AC |
5877 | When no switch @option{^-gnatw^/WARNINGS^} is used, this is equivalent to: |
5878 | ||
5879 | @table @option | |
5880 | @c !sort! | |
62db841a | 5881 | @item -gnatw.a |
6d9e03cb AC |
5882 | @item -gnatwB |
5883 | @item -gnatw.b | |
7cd4527e | 5884 | @item -gnatwC |
6d9e03cb | 5885 | @item -gnatw.C |
7cd4527e AC |
5886 | @item -gnatwD |
5887 | @item -gnatwF | |
5888 | @item -gnatwg | |
5889 | @item -gnatwH | |
5890 | @item -gnatwi | |
6d9e03cb | 5891 | @item -gnatw.I |
7cd4527e AC |
5892 | @item -gnatwJ |
5893 | @item -gnatwK | |
5894 | @item -gnatwL | |
6d9e03cb | 5895 | @item -gnatw.L |
7cd4527e | 5896 | @item -gnatwM |
6d9e03cb | 5897 | @item -gnatw.m |
7cd4527e AC |
5898 | @item -gnatwn |
5899 | @item -gnatwo | |
6d9e03cb | 5900 | @item -gnatw.O |
7cd4527e | 5901 | @item -gnatwP |
6d9e03cb AC |
5902 | @item -gnatw.P |
5903 | @item -gnatwq | |
7cd4527e | 5904 | @item -gnatwR |
6d9e03cb AC |
5905 | @item -gnatw.R |
5906 | @item -gnatw.S | |
5907 | @item -gnatwT | |
5908 | @item -gnatw.T | |
7cd4527e AC |
5909 | @item -gnatwU |
5910 | @item -gnatwv | |
6d9e03cb AC |
5911 | @item -gnatww |
5912 | @item -gnatw.W | |
7cd4527e | 5913 | @item -gnatwx |
6d9e03cb AC |
5914 | @item -gnatw.X |
5915 | @item -gnatwy | |
5916 | @item -gnatwz | |
88e1739c FW |
5917 | |
5918 | @end table | |
5919 | ||
5920 | @node Debugging and Assertion Control | |
5921 | @subsection Debugging and Assertion Control | |
5922 | ||
7cd4527e | 5923 | @table @option |
88e1739c | 5924 | @item -gnata |
984a64bc | 5925 | @cindex @option{-gnata} (@command{gcc}) |
88e1739c FW |
5926 | @findex Assert |
5927 | @findex Debug | |
5928 | @cindex Assertions | |
5929 | ||
5930 | @noindent | |
5931 | The pragmas @code{Assert} and @code{Debug} normally have no effect and | |
5932 | are ignored. This switch, where @samp{a} stands for assert, causes | |
5933 | @code{Assert} and @code{Debug} pragmas to be activated. | |
5934 | ||
5935 | The pragmas have the form: | |
5936 | ||
5937 | @smallexample | |
88e1739c | 5938 | @cartouche |
66bfd481 RW |
5939 | @b{pragma} Assert (@var{Boolean-expression} @r{[}, |
5940 | @var{static-string-expression}@r{]}) | |
88e1739c FW |
5941 | @b{pragma} Debug (@var{procedure call}) |
5942 | @end cartouche | |
88e1739c FW |
5943 | @end smallexample |
5944 | ||
5945 | @noindent | |
5946 | The @code{Assert} pragma causes @var{Boolean-expression} to be tested. | |
5947 | If the result is @code{True}, the pragma has no effect (other than | |
5948 | possible side effects from evaluating the expression). If the result is | |
5949 | @code{False}, the exception @code{Assert_Failure} declared in the package | |
5950 | @code{System.Assertions} is | |
5951 | raised (passing @var{static-string-expression}, if present, as the | |
5952 | message associated with the exception). If no string expression is | |
5953 | given the default is a string giving the file name and line number | |
5954 | of the pragma. | |
5955 | ||
5956 | The @code{Debug} pragma causes @var{procedure} to be called. Note that | |
5957 | @code{pragma Debug} may appear within a declaration sequence, allowing | |
5958 | debugging procedures to be called between declarations. | |
5959 | ||
5960 | @ifset vms | |
66bfd481 | 5961 | @item /DEBUG@r{[}=debug-level@r{]} |
88e1739c FW |
5962 | @itemx /NODEBUG |
5963 | Specifies how much debugging information is to be included in | |
5964 | the resulting object file where 'debug-level' is one of the following: | |
5965 | @table @code | |
7cd4527e | 5966 | @item TRACEBACK |
88e1739c FW |
5967 | Include both debugger symbol records and traceback |
5968 | the object file. | |
7cd4527e | 5969 | This is the default setting. |
88e1739c FW |
5970 | @item ALL |
5971 | Include both debugger symbol records and traceback in | |
5972 | object file. | |
5973 | @item NONE | |
5974 | Excludes both debugger symbol records and traceback | |
5975 | the object file. Same as /NODEBUG. | |
5976 | @item SYMBOLS | |
5977 | Includes only debugger symbol records in the object | |
5978 | file. Note that this doesn't include traceback information. | |
5979 | @end table | |
5980 | @end ifset | |
5981 | @end table | |
5982 | ||
5983 | @node Validity Checking | |
5984 | @subsection Validity Checking | |
5985 | @findex Validity Checking | |
5986 | ||
5987 | @noindent | |
e1aca343 AC |
5988 | The Ada Reference Manual defines the concept of invalid values (see |
5989 | RM 13.9.1). The primary source of invalid values is uninitialized | |
5990 | variables. A scalar variable that is left uninitialized may contain | |
5991 | an invalid value; the concept of invalid does not apply to access or | |
5992 | composite types. | |
5993 | ||
5994 | It is an error to read an invalid value, but the RM does not require | |
5995 | run-time checks to detect such errors, except for some minimal | |
5996 | checking to prevent erroneous execution (i.e. unpredictable | |
5997 | behavior). This corresponds to the @option{-gnatVd} switch below, | |
5998 | which is the default. For example, by default, if the expression of a | |
5999 | case statement is invalid, it will raise Constraint_Error rather than | |
6000 | causing a wild jump, and if an array index on the left-hand side of an | |
6001 | assignment is invalid, it will raise Constraint_Error rather than | |
6002 | overwriting an arbitrary memory location. | |
6003 | ||
6004 | The @option{-gnatVa} may be used to enable additional validity checks, | |
6005 | which are not required by the RM. These checks are often very | |
6006 | expensive (which is why the RM does not require them). These checks | |
6007 | are useful in tracking down uninitialized variables, but they are | |
6008 | not usually recommended for production builds. | |
6009 | ||
6010 | The other @option{-gnatV^@var{x}^^} switches below allow finer-grained | |
6011 | control; you can enable whichever validity checks you desire. However, | |
6012 | for most debugging purposes, @option{-gnatVa} is sufficient, and the | |
6013 | default @option{-gnatVd} (i.e. standard Ada behavior) is usually | |
6014 | sufficient for non-debugging use. | |
88e1739c | 6015 | |
c800f862 RD |
6016 | The @option{-gnatB} switch tells the compiler to assume that all |
6017 | values are valid (that is, within their declared subtype range) | |
6018 | except in the context of a use of the Valid attribute. This means | |
6019 | the compiler can generate more efficient code, since the range | |
e1aca343 AC |
6020 | of values is better known at compile time. However, an uninitialized |
6021 | variable can cause wild jumps and memory corruption in this mode. | |
c800f862 | 6022 | |
e1aca343 AC |
6023 | The @option{-gnatV^@var{x}^^} switch allows control over the validity |
6024 | checking mode as described below. | |
7cd4527e AC |
6025 | @ifclear vms |
6026 | The @code{x} argument is a string of letters that | |
6027 | indicate validity checks that are performed or not performed in addition | |
e1aca343 | 6028 | to the default checks required by Ada as described above. |
7cd4527e AC |
6029 | @end ifclear |
6030 | @ifset vms | |
6031 | The options allowed for this qualifier | |
6032 | indicate validity checks that are performed or not performed in addition | |
e1aca343 | 6033 | to the default checks required by Ada as described above. |
7cd4527e AC |
6034 | @end ifset |
6035 | ||
7cd4527e AC |
6036 | @table @option |
6037 | @c !sort! | |
6038 | @item -gnatVa | |
6039 | @emph{All validity checks.} | |
984a64bc | 6040 | @cindex @option{-gnatVa} (@command{gcc}) |
7cd4527e AC |
6041 | All validity checks are turned on. |
6042 | @ifclear vms | |
6043 | That is, @option{-gnatVa} is | |
6044 | equivalent to @option{gnatVcdfimorst}. | |
6045 | @end ifclear | |
88e1739c | 6046 | |
7cd4527e AC |
6047 | @item -gnatVc |
6048 | @emph{Validity checks for copies.} | |
984a64bc | 6049 | @cindex @option{-gnatVc} (@command{gcc}) |
88e1739c FW |
6050 | The right hand side of assignments, and the initializing values of |
6051 | object declarations are validity checked. | |
6052 | ||
7cd4527e AC |
6053 | @item -gnatVd |
6054 | @emph{Default (RM) validity checks.} | |
984a64bc | 6055 | @cindex @option{-gnatVd} (@command{gcc}) |
88e1739c FW |
6056 | Some validity checks are done by default following normal Ada semantics |
6057 | (RM 13.9.1 (9-11)). | |
6058 | A check is done in case statements that the expression is within the range | |
6059 | of the subtype. If it is not, Constraint_Error is raised. | |
6060 | For assignments to array components, a check is done that the expression used | |
6061 | as index is within the range. If it is not, Constraint_Error is raised. | |
6062 | Both these validity checks may be turned off using switch @option{-gnatVD}. | |
6063 | They are turned on by default. If @option{-gnatVD} is specified, a subsequent | |
6064 | switch @option{-gnatVd} will leave the checks turned on. | |
6065 | Switch @option{-gnatVD} should be used only if you are sure that all such | |
6066 | expressions have valid values. If you use this switch and invalid values | |
6067 | are present, then the program is erroneous, and wild jumps or memory | |
6068 | overwriting may occur. | |
6069 | ||
ba1cbfb9 RD |
6070 | @item -gnatVe |
6071 | @emph{Validity checks for elementary components.} | |
6072 | @cindex @option{-gnatVe} (@command{gcc}) | |
6073 | In the absence of this switch, assignments to record or array components are | |
6074 | not validity checked, even if validity checks for assignments generally | |
6075 | (@option{-gnatVc}) are turned on. In Ada, assignment of composite values do not | |
6076 | require valid data, but assignment of individual components does. So for | |
6077 | example, there is a difference between copying the elements of an array with a | |
6078 | slice assignment, compared to assigning element by element in a loop. This | |
6079 | switch allows you to turn off validity checking for components, even when they | |
6080 | are assigned component by component. | |
6081 | ||
7cd4527e AC |
6082 | @item -gnatVf |
6083 | @emph{Validity checks for floating-point values.} | |
984a64bc | 6084 | @cindex @option{-gnatVf} (@command{gcc}) |
7cd4527e AC |
6085 | In the absence of this switch, validity checking occurs only for discrete |
6086 | values. If @option{-gnatVf} is specified, then validity checking also applies | |
e69044cb | 6087 | for floating-point values, and NaNs and infinities are considered invalid, |
7cd4527e | 6088 | as well as out of range values for constrained types. Note that this means |
e69044cb | 6089 | that standard IEEE infinity mode is not allowed. The exact contexts |
7cd4527e AC |
6090 | in which floating-point values are checked depends on the setting of other |
6091 | options. For example, | |
6092 | @option{^-gnatVif^VALIDITY_CHECKING=(IN_PARAMS,FLOATS)^} or | |
6093 | @option{^-gnatVfi^VALIDITY_CHECKING=(FLOATS,IN_PARAMS)^} | |
6094 | (the order does not matter) specifies that floating-point parameters of mode | |
6095 | @code{in} should be validity checked. | |
6096 | ||
6097 | @item -gnatVi | |
6098 | @emph{Validity checks for @code{in} mode parameters} | |
984a64bc | 6099 | @cindex @option{-gnatVi} (@command{gcc}) |
88e1739c FW |
6100 | Arguments for parameters of mode @code{in} are validity checked in function |
6101 | and procedure calls at the point of call. | |
6102 | ||
7cd4527e AC |
6103 | @item -gnatVm |
6104 | @emph{Validity checks for @code{in out} mode parameters.} | |
984a64bc | 6105 | @cindex @option{-gnatVm} (@command{gcc}) |
88e1739c FW |
6106 | Arguments for parameters of mode @code{in out} are validity checked in |
6107 | procedure calls at the point of call. The @code{'m'} here stands for | |
6108 | modify, since this concerns parameters that can be modified by the call. | |
6109 | Note that there is no specific option to test @code{out} parameters, | |
6110 | but any reference within the subprogram will be tested in the usual | |
6111 | manner, and if an invalid value is copied back, any reference to it | |
6112 | will be subject to validity checking. | |
6113 | ||
7cd4527e AC |
6114 | @item -gnatVn |
6115 | @emph{No validity checks.} | |
984a64bc | 6116 | @cindex @option{-gnatVn} (@command{gcc}) |
7cd4527e AC |
6117 | This switch turns off all validity checking, including the default checking |
6118 | for case statements and left hand side subscripts. Note that the use of | |
6119 | the switch @option{-gnatp} suppresses all run-time checks, including | |
6120 | validity checks, and thus implies @option{-gnatVn}. When this switch | |
6121 | is used, it cancels any other @option{-gnatV} previously issued. | |
88e1739c | 6122 | |
7cd4527e AC |
6123 | @item -gnatVo |
6124 | @emph{Validity checks for operator and attribute operands.} | |
984a64bc | 6125 | @cindex @option{-gnatVo} (@command{gcc}) |
88e1739c FW |
6126 | Arguments for predefined operators and attributes are validity checked. |
6127 | This includes all operators in package @code{Standard}, | |
6128 | the shift operators defined as intrinsic in package @code{Interfaces} | |
7cd4527e | 6129 | and operands for attributes such as @code{Pos}. Checks are also made |
f813ac73 | 6130 | on individual component values for composite comparisons, and on the |
ba1cbfb9 | 6131 | expressions in type conversions and qualified expressions. Checks are |
8dd07840 | 6132 | also made on explicit ranges using @samp{..} (e.g.@: slices, loops etc). |
7cd4527e AC |
6133 | |
6134 | @item -gnatVp | |
6135 | @emph{Validity checks for parameters.} | |
984a64bc | 6136 | @cindex @option{-gnatVp} (@command{gcc}) |
7cd4527e AC |
6137 | This controls the treatment of parameters within a subprogram (as opposed |
6138 | to @option{-gnatVi} and @option{-gnatVm} which control validity testing | |
6139 | of parameters on a call. If either of these call options is used, then | |
6140 | normally an assumption is made within a subprogram that the input arguments | |
6141 | have been validity checking at the point of call, and do not need checking | |
6142 | again within a subprogram). If @option{-gnatVp} is set, then this assumption | |
6143 | is not made, and parameters are not assumed to be valid, so their validity | |
6144 | will be checked (or rechecked) within the subprogram. | |
6145 | ||
6146 | @item -gnatVr | |
6147 | @emph{Validity checks for function returns.} | |
984a64bc | 6148 | @cindex @option{-gnatVr} (@command{gcc}) |
88e1739c FW |
6149 | The expression in @code{return} statements in functions is validity |
6150 | checked. | |
6151 | ||
7cd4527e AC |
6152 | @item -gnatVs |
6153 | @emph{Validity checks for subscripts.} | |
984a64bc | 6154 | @cindex @option{-gnatVs} (@command{gcc}) |
88e1739c FW |
6155 | All subscripts expressions are checked for validity, whether they appear |
6156 | on the right side or left side (in default mode only left side subscripts | |
6157 | are validity checked). | |
6158 | ||
7cd4527e AC |
6159 | @item -gnatVt |
6160 | @emph{Validity checks for tests.} | |
984a64bc | 6161 | @cindex @option{-gnatVt} (@command{gcc}) |
88e1739c FW |
6162 | Expressions used as conditions in @code{if}, @code{while} or @code{exit} |
6163 | statements are checked, as well as guard expressions in entry calls. | |
6164 | ||
7cd4527e | 6165 | @end table |
88e1739c | 6166 | |
7cd4527e AC |
6167 | @noindent |
6168 | The @option{-gnatV} switch may be followed by | |
6169 | ^a string of letters^a list of options^ | |
6170 | to turn on a series of validity checking options. | |
6171 | For example, | |
6172 | @option{^-gnatVcr^/VALIDITY_CHECKING=(COPIES, RETURNS)^} | |
6173 | specifies that in addition to the default validity checking, copies and | |
6174 | function return expressions are to be validity checked. | |
6175 | In order to make it easier | |
6176 | to specify the desired combination of effects, | |
6177 | @ifclear vms | |
6178 | the upper case letters @code{CDFIMORST} may | |
6179 | be used to turn off the corresponding lower case option. | |
6180 | @end ifclear | |
6181 | @ifset vms | |
6182 | the prefix @code{NO} on an option turns off the corresponding validity | |
6183 | checking: | |
6184 | @itemize @bullet | |
6185 | @item @code{NOCOPIES} | |
6186 | @item @code{NODEFAULT} | |
6187 | @item @code{NOFLOATS} | |
6188 | @item @code{NOIN_PARAMS} | |
6189 | @item @code{NOMOD_PARAMS} | |
6190 | @item @code{NOOPERANDS} | |
6191 | @item @code{NORETURNS} | |
6192 | @item @code{NOSUBSCRIPTS} | |
6193 | @item @code{NOTESTS} | |
88e1739c | 6194 | @end itemize |
7cd4527e AC |
6195 | @end ifset |
6196 | Thus | |
6197 | @option{^-gnatVaM^/VALIDITY_CHECKING=(ALL, NOMOD_PARAMS)^} | |
6198 | turns on all validity checking options except for | |
6199 | checking of @code{@b{in out}} procedure arguments. | |
88e1739c FW |
6200 | |
6201 | The specification of additional validity checking generates extra code (and | |
8436e37c | 6202 | in the case of @option{-gnatVa} the code expansion can be substantial). |
7cd4527e | 6203 | However, these additional checks can be very useful in detecting |
88e1739c FW |
6204 | uninitialized variables, incorrect use of unchecked conversion, and other |
6205 | errors leading to invalid values. The use of pragma @code{Initialize_Scalars} | |
6206 | is useful in conjunction with the extra validity checking, since this | |
6207 | ensures that wherever possible uninitialized variables have invalid values. | |
6208 | ||
6209 | See also the pragma @code{Validity_Checks} which allows modification of | |
6210 | the validity checking mode at the program source level, and also allows for | |
6211 | temporary disabling of validity checks. | |
6212 | ||
6213 | @node Style Checking | |
6214 | @subsection Style Checking | |
6215 | @findex Style checking | |
6216 | ||
6217 | @noindent | |
d488f6ea | 6218 | The @option{-gnaty^x^(option,option,@dots{})^} switch |
984a64bc | 6219 | @cindex @option{-gnaty} (@command{gcc}) |
7cd4527e | 6220 | causes the compiler to |
88e1739c FW |
6221 | enforce specified style rules. A limited set of style rules has been used |
6222 | in writing the GNAT sources themselves. This switch allows user programs | |
6223 | to activate all or some of these checks. If the source program fails a | |
9cbfc269 AC |
6224 | specified style check, an appropriate message is given, preceded by |
6225 | the character sequence ``(style)''. This message does not prevent | |
6226 | successful compilation (unless the @option{-gnatwe} switch is used). | |
6227 | ||
46256d9d AC |
6228 | Note that this is by no means intended to be a general facility for |
6229 | checking arbitrary coding standards. It is simply an embedding of the | |
6230 | style rules we have chosen for the GNAT sources. If you are starting | |
6231 | a project which does not have established style standards, you may | |
6232 | find it useful to adopt the entire set of GNAT coding standards, or | |
1037b0f4 AC |
6233 | some subset of them. |
6234 | @ifclear FSFEDITION | |
6235 | If you already have an established set of coding | |
6236 | standards, then the selected style checking options may | |
46256d9d AC |
6237 | indeed correspond to choices you have made, but for general checking |
6238 | of an existing set of coding rules, you should look to the gnatcheck | |
6239 | tool, which is designed for that purpose. | |
1037b0f4 | 6240 | @end ifclear |
46256d9d | 6241 | |
88e1739c | 6242 | @ifset vms |
d488f6ea | 6243 | @code{(option,option,@dots{})} is a sequence of keywords |
88e1739c FW |
6244 | @end ifset |
6245 | @ifclear vms | |
6246 | The string @var{x} is a sequence of letters or digits | |
6247 | @end ifclear | |
6248 | indicating the particular style | |
6249 | checks to be performed. The following checks are defined: | |
6250 | ||
7cd4527e AC |
6251 | @table @option |
6252 | @c !sort! | |
1a5f40e1 | 6253 | @item 0-9 |
7cd4527e AC |
6254 | @emph{Specify indentation level.} |
6255 | If a digit from 1-9 appears | |
6256 | ^in the string after @option{-gnaty}^as an option for /STYLE_CHECKS^ | |
6257 | then proper indentation is checked, with the digit indicating the | |
1a5f40e1 | 6258 | indentation level required. A value of zero turns off this style check. |
7cd4527e | 6259 | The general style of required indentation is as specified by |
88e1739c FW |
6260 | the examples in the Ada Reference Manual. Full line comments must be |
6261 | aligned with the @code{--} starting on a column that is a multiple of | |
a2ad1f79 RD |
6262 | the alignment level, or they may be aligned the same way as the following |
6263 | non-blank line (this is useful when full line comments appear in the middle | |
67a90476 AC |
6264 | of a statement, or they may be aligned with the source line on the previous |
6265 | non-blank line. | |
88e1739c | 6266 | |
7cd4527e AC |
6267 | @item ^a^ATTRIBUTE^ |
6268 | @emph{Check attribute casing.} | |
1a5f40e1 | 6269 | Attribute names, including the case of keywords such as @code{digits} |
88e1739c FW |
6270 | used as attributes names, must be written in mixed case, that is, the |
6271 | initial letter and any letter following an underscore must be uppercase. | |
6272 | All other letters must be lowercase. | |
6273 | ||
0916df6a RD |
6274 | @item ^A^ARRAY_INDEXES^ |
6275 | @emph{Use of array index numbers in array attributes.} | |
1a5f40e1 | 6276 | When using the array attributes First, Last, Range, |
0916df6a RD |
6277 | or Length, the index number must be omitted for one-dimensional arrays |
6278 | and is required for multi-dimensional arrays. | |
6279 | ||
7cd4527e AC |
6280 | @item ^b^BLANKS^ |
6281 | @emph{Blanks not allowed at statement end.} | |
1a5f40e1 | 6282 | Trailing blanks are not allowed at the end of statements. The purpose of this |
88e1739c FW |
6283 | rule, together with h (no horizontal tabs), is to enforce a canonical format |
6284 | for the use of blanks to separate source tokens. | |
6285 | ||
a36c1c3e RD |
6286 | @item ^B^BOOLEAN_OPERATORS^ |
6287 | @emph{Check Boolean operators.} | |
6288 | The use of AND/OR operators is not permitted except in the cases of modular | |
6289 | operands, array operands, and simple stand-alone boolean variables or | |
6d9e03cb AC |
6290 | boolean constants. In all other cases @code{and then}/@code{or else} are |
6291 | required. | |
a36c1c3e | 6292 | |
6d9e03cb | 6293 | @item ^c^COMMENTS^ |
a2773bd3 | 6294 | @emph{Check comments, double space.} |
1a5f40e1 | 6295 | Comments must meet the following set of rules: |
88e1739c FW |
6296 | |
6297 | @itemize @bullet | |
6298 | ||
6299 | @item | |
7cd4527e AC |
6300 | The ``@code{--}'' that starts the column must either start in column one, |
6301 | or else at least one blank must precede this sequence. | |
88e1739c FW |
6302 | |
6303 | @item | |
6304 | Comments that follow other tokens on a line must have at least one blank | |
7cd4527e | 6305 | following the ``@code{--}'' at the start of the comment. |
88e1739c FW |
6306 | |
6307 | @item | |
e5dc610e AC |
6308 | Full line comments must have at least two blanks following the |
6309 | ``@code{--}'' that starts the comment, with the following exceptions. | |
88e1739c FW |
6310 | |
6311 | @item | |
7cd4527e AC |
6312 | A line consisting only of the ``@code{--}'' characters, possibly preceded |
6313 | by blanks is permitted. | |
88e1739c FW |
6314 | |
6315 | @item | |
7cd4527e AC |
6316 | A comment starting with ``@code{--x}'' where @code{x} is a special character |
6317 | is permitted. | |
6318 | This allows proper processing of the output generated by specialized tools | |
6319 | including @command{gnatprep} (where ``@code{--!}'' is used) and the SPARK | |
6320 | annotation | |
6321 | language (where ``@code{--#}'' is used). For the purposes of this rule, a | |
6322 | special character is defined as being in one of the ASCII ranges | |
d488f6ea | 6323 | @code{16#21#@dots{}16#2F#} or @code{16#3A#@dots{}16#3F#}. |
7cd4527e | 6324 | Note that this usage is not permitted |
8dd07840 | 6325 | in GNAT implementation units (i.e., when @option{-gnatg} is used). |
88e1739c FW |
6326 | |
6327 | @item | |
6328 | A line consisting entirely of minus signs, possibly preceded by blanks, is | |
6329 | permitted. This allows the construction of box comments where lines of minus | |
6330 | signs are used to form the top and bottom of the box. | |
6331 | ||
6332 | @item | |
984a64bc | 6333 | A comment that starts and ends with ``@code{--}'' is permitted as long as at |
7cd4527e AC |
6334 | least one blank follows the initial ``@code{--}''. Together with the preceding |
6335 | rule, this allows the construction of box comments, as shown in the following | |
88e1739c FW |
6336 | example: |
6337 | @smallexample | |
6338 | --------------------------- | |
6339 | -- This is a box comment -- | |
6340 | -- with two text lines. -- | |
6341 | --------------------------- | |
6342 | @end smallexample | |
6343 | @end itemize | |
6344 | ||
6d9e03cb | 6345 | @item ^C^COMMENTS1^ |
a2773bd3 | 6346 | @emph{Check comments, single space.} |
23b6deca | 6347 | This is identical to @code{^c^COMMENTS^} except that only one space |
a2773bd3 AC |
6348 | is required following the @code{--} of a comment instead of two. |
6349 | ||
debe0ab6 RD |
6350 | @item ^d^DOS_LINE_ENDINGS^ |
6351 | @emph{Check no DOS line terminators present.} | |
1a5f40e1 | 6352 | All lines must be terminated by a single ASCII.LF |
0453ca3d RD |
6353 | character (in particular the DOS line terminator sequence CR/LF is not |
6354 | allowed). | |
debe0ab6 | 6355 | |
7cd4527e AC |
6356 | @item ^e^END^ |
6357 | @emph{Check end/exit labels.} | |
1a5f40e1 | 6358 | Optional labels on @code{end} statements ending subprograms and on |
88e1739c FW |
6359 | @code{exit} statements exiting named loops, are required to be present. |
6360 | ||
7cd4527e AC |
6361 | @item ^f^VTABS^ |
6362 | @emph{No form feeds or vertical tabs.} | |
1a5f40e1 | 6363 | Neither form feeds nor vertical tab characters are permitted |
88e1739c FW |
6364 | in the source text. |
6365 | ||
e08b38f5 | 6366 | @item ^g^GNAT^ |
6d9e03cb | 6367 | @emph{GNAT style mode.} |
1a5f40e1 | 6368 | The set of style check switches is set to match that used by the GNAT sources. |
e08b38f5 VC |
6369 | This may be useful when developing code that is eventually intended to be |
6370 | incorporated into GNAT. For further details, see GNAT sources. | |
6371 | ||
7cd4527e AC |
6372 | @item ^h^HTABS^ |
6373 | @emph{No horizontal tabs.} | |
1a5f40e1 | 6374 | Horizontal tab characters are not permitted in the source text. |
88e1739c FW |
6375 | Together with the b (no blanks at end of line) check, this |
6376 | enforces a canonical form for the use of blanks to separate | |
6377 | source tokens. | |
6378 | ||
7cd4527e AC |
6379 | @item ^i^IF_THEN^ |
6380 | @emph{Check if-then layout.} | |
1a5f40e1 | 6381 | The keyword @code{then} must appear either on the same |
88e1739c | 6382 | line as corresponding @code{if}, or on a line on its own, lined |
0b7f0f0e | 6383 | up under the @code{if}. |
88e1739c | 6384 | |
7e3d710b | 6385 | @item ^I^IN_MODE^ |
6d9e03cb | 6386 | @emph{check mode IN keywords.} |
1a5f40e1 | 6387 | Mode @code{in} (the default mode) is not |
7e3d710b AC |
6388 | allowed to be given explicitly. @code{in out} is fine, |
6389 | but not @code{in} on its own. | |
6390 | ||
7cd4527e AC |
6391 | @item ^k^KEYWORD^ |
6392 | @emph{Check keyword casing.} | |
1a5f40e1 | 6393 | All keywords must be in lower case (with the exception of keywords |
88e1739c FW |
6394 | such as @code{digits} used as attribute names to which this check |
6395 | does not apply). | |
6396 | ||
7cd4527e AC |
6397 | @item ^l^LAYOUT^ |
6398 | @emph{Check layout.} | |
1a5f40e1 | 6399 | Layout of statement and declaration constructs must follow the |
88e1739c FW |
6400 | recommendations in the Ada Reference Manual, as indicated by the |
6401 | form of the syntax rules. For example an @code{else} keyword must | |
6402 | be lined up with the corresponding @code{if} keyword. | |
6403 | ||
6404 | There are two respects in which the style rule enforced by this check | |
6405 | option are more liberal than those in the Ada Reference Manual. First | |
6406 | in the case of record declarations, it is permissible to put the | |
6407 | @code{record} keyword on the same line as the @code{type} keyword, and | |
6408 | then the @code{end} in @code{end record} must line up under @code{type}. | |
0916df6a RD |
6409 | This is also permitted when the type declaration is split on two lines. |
6410 | For example, any of the following three layouts is acceptable: | |
88e1739c | 6411 | |
7cd4527e | 6412 | @smallexample @c ada |
88e1739c | 6413 | @cartouche |
7cd4527e | 6414 | type q is record |
88e1739c FW |
6415 | a : integer; |
6416 | b : integer; | |
7cd4527e | 6417 | end record; |
88e1739c | 6418 | |
7cd4527e AC |
6419 | type q is |
6420 | record | |
88e1739c FW |
6421 | a : integer; |
6422 | b : integer; | |
7cd4527e | 6423 | end record; |
0916df6a RD |
6424 | |
6425 | type q is | |
6426 | record | |
6427 | a : integer; | |
6428 | b : integer; | |
6429 | end record; | |
6430 | ||
88e1739c | 6431 | @end cartouche |
88e1739c FW |
6432 | @end smallexample |
6433 | ||
6434 | @noindent | |
6435 | Second, in the case of a block statement, a permitted alternative | |
6436 | is to put the block label on the same line as the @code{declare} or | |
6437 | @code{begin} keyword, and then line the @code{end} keyword up under | |
6438 | the block label. For example both the following are permitted: | |
6439 | ||
7cd4527e | 6440 | @smallexample @c ada |
88e1739c | 6441 | @cartouche |
7cd4527e | 6442 | Block : declare |
88e1739c | 6443 | A : Integer := 3; |
7cd4527e | 6444 | begin |
88e1739c | 6445 | Proc (A, A); |
7cd4527e | 6446 | end Block; |
88e1739c FW |
6447 | |
6448 | Block : | |
7cd4527e | 6449 | declare |
88e1739c | 6450 | A : Integer := 3; |
7cd4527e | 6451 | begin |
88e1739c | 6452 | Proc (A, A); |
7cd4527e | 6453 | end Block; |
88e1739c | 6454 | @end cartouche |
88e1739c FW |
6455 | @end smallexample |
6456 | ||
6457 | @noindent | |
6458 | The same alternative format is allowed for loops. For example, both of | |
6459 | the following are permitted: | |
6460 | ||
7cd4527e | 6461 | @smallexample @c ada |
88e1739c | 6462 | @cartouche |
7cd4527e | 6463 | Clear : while J < 10 loop |
88e1739c | 6464 | A (J) := 0; |
7cd4527e | 6465 | end loop Clear; |
88e1739c FW |
6466 | |
6467 | Clear : | |
7cd4527e | 6468 | while J < 10 loop |
88e1739c | 6469 | A (J) := 0; |
7cd4527e | 6470 | end loop Clear; |
88e1739c | 6471 | @end cartouche |
88e1739c FW |
6472 | @end smallexample |
6473 | ||
0da2c8ac | 6474 | @item ^Lnnn^MAX_NESTING=nnn^ |
6d9e03cb | 6475 | @emph{Set maximum nesting level.} |
1a5f40e1 VC |
6476 | The maximum level of nesting of constructs (including subprograms, loops, |
6477 | blocks, packages, and conditionals) may not exceed the given value | |
6478 | @option{nnn}. A value of zero disconnects this style check. | |
0da2c8ac | 6479 | |
7cd4527e AC |
6480 | @item ^m^LINE_LENGTH^ |
6481 | @emph{Check maximum line length.} | |
1a5f40e1 | 6482 | The length of source lines must not exceed 79 characters, including |
88e1739c FW |
6483 | any trailing blanks. The value of 79 allows convenient display on an |
6484 | 80 character wide device or window, allowing for possible special | |
c1cd0d96 | 6485 | treatment of 80 character lines. Note that this count is of |
7cd4527e | 6486 | characters in the source text. This means that a tab character counts |
43254605 | 6487 | as one character in this count and a wide character sequence counts as |
c1cd0d96 | 6488 | a single character (however many bytes are needed in the encoding). |
88e1739c | 6489 | |
7cd4527e AC |
6490 | @item ^Mnnn^MAX_LENGTH=nnn^ |
6491 | @emph{Set maximum line length.} | |
1a5f40e1 VC |
6492 | The length of lines must not exceed the |
6493 | given value @option{nnn}. The maximum value that can be specified is 32767. | |
43254605 AC |
6494 | If neither style option for setting the line length is used, then the |
6495 | default is 255. This also controls the maximum length of lexical elements, | |
6496 | where the only restriction is that they must fit on a single line. | |
88e1739c | 6497 | |
7cd4527e AC |
6498 | @item ^n^STANDARD_CASING^ |
6499 | @emph{Check casing of entities in Standard.} | |
1a5f40e1 | 6500 | Any identifier from Standard must be cased |
88e1739c FW |
6501 | to match the presentation in the Ada Reference Manual (for example, |
6502 | @code{Integer} and @code{ASCII.NUL}). | |
6503 | ||
1a5f40e1 | 6504 | @item ^N^NONE^ |
6d9e03cb | 6505 | @emph{Turn off all style checks.} |
1a5f40e1 VC |
6506 | All style check options are turned off. |
6507 | ||
7cd4527e AC |
6508 | @item ^o^ORDERED_SUBPROGRAMS^ |
6509 | @emph{Check order of subprogram bodies.} | |
1a5f40e1 | 6510 | All subprogram bodies in a given scope |
8dd07840 | 6511 | (e.g.@: a package body) must be in alphabetical order. The ordering |
88e1739c FW |
6512 | rule uses normal Ada rules for comparing strings, ignoring casing |
6513 | of letters, except that if there is a trailing numeric suffix, then | |
8dd07840 | 6514 | the value of this suffix is used in the ordering (e.g.@: Junk2 comes |
88e1739c FW |
6515 | before Junk10). |
6516 | ||
ed57136d AC |
6517 | @item ^O^OVERRIDING_INDICATORS^ |
6518 | @emph{Check that overriding subprograms are explicitly marked as such.} | |
6519 | The declaration of a primitive operation of a type extension that overrides | |
6520 | an inherited operation must carry an overriding indicator. | |
6521 | ||
7cd4527e AC |
6522 | @item ^p^PRAGMA^ |
6523 | @emph{Check pragma casing.} | |
1a5f40e1 | 6524 | Pragma names must be written in mixed case, that is, the |
88e1739c | 6525 | initial letter and any letter following an underscore must be uppercase. |
e09a5598 AC |
6526 | All other letters must be lowercase. An exception is that SPARK_Mode is |
6527 | allowed as an alternative for Spark_Mode. | |
88e1739c | 6528 | |
7cd4527e AC |
6529 | @item ^r^REFERENCES^ |
6530 | @emph{Check references.} | |
1a5f40e1 | 6531 | All identifier references must be cased in the same way as the |
88e1739c FW |
6532 | corresponding declaration. No specific casing style is imposed on |
6533 | identifiers. The only requirement is for consistency of references | |
6534 | with declarations. | |
6535 | ||
7cd4527e AC |
6536 | @item ^s^SPECS^ |
6537 | @emph{Check separate specs.} | |
1a5f40e1 | 6538 | Separate declarations (``specs'') are required for subprograms (a |
88e1739c FW |
6539 | body is not allowed to serve as its own declaration). The only |
6540 | exception is that parameterless library level procedures are | |
6541 | not required to have a separate declaration. This exception covers | |
6542 | the most frequent form of main program procedures. | |
6543 | ||
6d9e03cb AC |
6544 | @item ^S^STATEMENTS_AFTER_THEN_ELSE^ |
6545 | @emph{Check no statements after @code{then}/@code{else}.} | |
6546 | No statements are allowed | |
6547 | on the same line as a @code{then} or @code{else} keyword following the | |
6548 | keyword in an @code{if} statement. @code{or else} and @code{and then} are not | |
6549 | affected, and a special exception allows a pragma to appear after @code{else}. | |
6550 | ||
7cd4527e AC |
6551 | @item ^t^TOKEN^ |
6552 | @emph{Check token spacing.} | |
1a5f40e1 | 6553 | The following token spacing rules are enforced: |
88e1739c FW |
6554 | |
6555 | @itemize @bullet | |
6556 | ||
6557 | @item | |
6d9e03cb | 6558 | The keywords @code{abs} and @code{not} must be followed by a space. |
88e1739c FW |
6559 | |
6560 | @item | |
6561 | The token @code{=>} must be surrounded by spaces. | |
6562 | ||
6563 | @item | |
6564 | The token @code{<>} must be preceded by a space or a left parenthesis. | |
6565 | ||
6566 | @item | |
6567 | Binary operators other than @code{**} must be surrounded by spaces. | |
6568 | There is no restriction on the layout of the @code{**} binary operator. | |
6569 | ||
6570 | @item | |
6571 | Colon must be surrounded by spaces. | |
6572 | ||
6573 | @item | |
7cd4527e | 6574 | Colon-equal (assignment, initialization) must be surrounded by spaces. |
88e1739c FW |
6575 | |
6576 | @item | |
6577 | Comma must be the first non-blank character on the line, or be | |
6578 | immediately preceded by a non-blank character, and must be followed | |
6579 | by a space. | |
6580 | ||
6581 | @item | |
7cd4527e | 6582 | If the token preceding a left parenthesis ends with a letter or digit, then |
88e1739c FW |
6583 | a space must separate the two tokens. |
6584 | ||
68523ddb AC |
6585 | @item |
6586 | if the token following a right parenthesis starts with a letter or digit, then | |
6587 | a space must separate the two tokens. | |
6588 | ||
88e1739c FW |
6589 | @item |
6590 | A right parenthesis must either be the first non-blank character on | |
6591 | a line, or it must be preceded by a non-blank character. | |
6592 | ||
6593 | @item | |
6594 | A semicolon must not be preceded by a space, and must not be followed by | |
6595 | a non-blank character. | |
6596 | ||
6597 | @item | |
6598 | A unary plus or minus may not be followed by a space. | |
6599 | ||
6600 | @item | |
6601 | A vertical bar must be surrounded by spaces. | |
6602 | @end itemize | |
6603 | ||
9a6dc470 RD |
6604 | @item |
6605 | Exactly one blank (and no other white space) must appear between | |
6606 | a @code{not} token and a following @code{in} token. | |
6607 | ||
0453ca3d RD |
6608 | @item ^u^UNNECESSARY_BLANK_LINES^ |
6609 | @emph{Check unnecessary blank lines.} | |
1a5f40e1 | 6610 | Unnecessary blank lines are not allowed. A blank line is considered |
0453ca3d RD |
6611 | unnecessary if it appears at the end of the file, or if more than |
6612 | one blank line occurs in sequence. | |
6613 | ||
80298b89 AC |
6614 | @item ^x^XTRA_PARENS^ |
6615 | @emph{Check extra parentheses.} | |
1a5f40e1 | 6616 | Unnecessary extra level of parentheses (C-style) are not allowed |
80298b89 AC |
6617 | around conditions in @code{if} statements, @code{while} statements and |
6618 | @code{exit} statements. | |
6619 | ||
1a5f40e1 VC |
6620 | @item ^y^ALL_BUILTIN^ |
6621 | @emph{Set all standard style check options} | |
6622 | This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking | |
6d9e03cb AC |
6623 | options enabled with the exception of @option{-gnatyB}, @option{-gnatyd}, |
6624 | @option{-gnatyI}, @option{-gnatyLnnn}, @option{-gnatyo}, @option{-gnatyO}, | |
6625 | @option{-gnatyS}, @option{-gnatyu}, and @option{-gnatyx}. | |
1a5f40e1 VC |
6626 | |
6627 | @ifclear vms | |
6628 | @item - | |
6629 | @emph{Remove style check options} | |
6630 | This causes any subsequent options in the string to act as canceling the | |
8436e37c RD |
6631 | corresponding style check option. To cancel maximum nesting level control, |
6632 | use @option{L} parameter witout any integer value after that, because any | |
6633 | digit following @option{-} in the parameter string of the @option{-gnaty} | |
6634 | option will be threated as canceling indentation check. The same is true | |
6635 | for @option{M} parameter. @option{y} and @option{N} parameters are not | |
30783513 | 6636 | allowed after @option{-}. |
1a5f40e1 VC |
6637 | |
6638 | @item + | |
6639 | This causes any subsequent options in the string to enable the corresponding | |
8436e37c RD |
6640 | style check option. That is, it cancels the effect of a previous ^-^REMOVE^, |
6641 | if any. | |
1a5f40e1 VC |
6642 | @end ifclear |
6643 | ||
6644 | @ifset vms | |
6645 | @item NOxxx | |
6646 | @emph{Removing style check options} | |
6647 | If the name of a style check is preceded by @option{NO} then the corresponding | |
6648 | style check is turned off. For example @option{NOCOMMENTS} turns off style | |
6649 | checking for comments. | |
6650 | @end ifset | |
80298b89 AC |
6651 | @end table |
6652 | ||
88e1739c FW |
6653 | @noindent |
6654 | In the above rules, appearing in column one is always permitted, that is, | |
6655 | counts as meeting either a requirement for a required preceding space, | |
6656 | or as meeting a requirement for no preceding space. | |
6657 | ||
6658 | Appearing at the end of a line is also always permitted, that is, counts | |
6659 | as meeting either a requirement for a following space, or as meeting | |
6660 | a requirement for no following space. | |
6661 | ||
88e1739c FW |
6662 | @noindent |
6663 | If any of these style rules is violated, a message is generated giving | |
6664 | details on the violation. The initial characters of such messages are | |
7cd4527e | 6665 | always ``@code{(style)}''. Note that these messages are treated as warning |
88e1739c FW |
6666 | messages, so they normally do not prevent the generation of an object |
6667 | file. The @option{-gnatwe} switch can be used to treat warning messages, | |
6668 | including style messages, as fatal errors. | |
6669 | ||
88e1739c | 6670 | The switch |
7cd4527e AC |
6671 | @ifclear vms |
6672 | @option{-gnaty} on its own (that is not | |
6d9e03cb AC |
6673 | followed by any letters or digits) is equivalent |
6674 | to the use of @option{-gnatyy} as described above, that is all | |
1a5f40e1 VC |
6675 | built-in standard style check options are enabled. |
6676 | ||
7cd4527e AC |
6677 | @end ifclear |
6678 | @ifset vms | |
6679 | /STYLE_CHECKS=ALL_BUILTIN enables all checking options with | |
0453ca3d RD |
6680 | the exception of ORDERED_SUBPROGRAMS, UNNECESSARY_BLANK_LINES, |
6681 | XTRA_PARENS, and DOS_LINE_ENDINGS. In addition | |
7cd4527e | 6682 | @end ifset |
8436e37c | 6683 | |
7cd4527e AC |
6684 | The switch |
6685 | @ifclear vms | |
6686 | @option{-gnatyN} | |
6687 | @end ifclear | |
6688 | @ifset vms | |
6689 | /STYLE_CHECKS=NONE | |
6690 | @end ifset | |
6691 | clears any previously set style checks. | |
6692 | ||
88e1739c FW |
6693 | @node Run-Time Checks |
6694 | @subsection Run-Time Checks | |
6695 | @cindex Division by zero | |
6696 | @cindex Access before elaboration | |
6697 | @cindex Checks, division by zero | |
6698 | @cindex Checks, access before elaboration | |
32e209e4 | 6699 | @cindex Checks, stack overflow checking |
88e1739c FW |
6700 | |
6701 | @noindent | |
a3ea9137 AC |
6702 | By default, the following checks are suppressed: integer overflow |
6703 | checks, stack overflow checks, and checks for access before | |
6704 | elaboration on subprogram calls. All other checks, including range | |
6705 | checks and array bounds checks, are turned on by default. The | |
6706 | following @command{gcc} switches refine this default behavior. | |
88e1739c | 6707 | |
7cd4527e AC |
6708 | @table @option |
6709 | @c !sort! | |
88e1739c | 6710 | @item -gnatp |
984a64bc | 6711 | @cindex @option{-gnatp} (@command{gcc}) |
88e1739c FW |
6712 | @cindex Suppressing checks |
6713 | @cindex Checks, suppressing | |
6714 | @findex Suppress | |
d175a2fa AC |
6715 | This switch causes the unit to be compiled |
6716 | as though @code{pragma Suppress (All_checks)} | |
6717 | had been present in the source. Validity checks are also eliminated (in | |
88e1739c FW |
6718 | other words @option{-gnatp} also implies @option{-gnatVn}. |
6719 | Use this switch to improve the performance | |
6720 | of the code at the expense of safety in the presence of invalid data or | |
6721 | program bugs. | |
6722 | ||
a3ea9137 AC |
6723 | Note that when checks are suppressed, the compiler is allowed, but not |
6724 | required, to omit the checking code. If the run-time cost of the | |
6725 | checking code is zero or near-zero, the compiler will generate it even | |
6726 | if checks are suppressed. In particular, if the compiler can prove | |
6727 | that a certain check will necessarily fail, it will generate code to | |
6728 | do an unconditional ``raise'', even if checks are suppressed. The | |
d175a2fa AC |
6729 | compiler warns in this case. Another case in which checks may not be |
6730 | eliminated is when they are embedded in certain run time routines such | |
6731 | as math library routines. | |
a3ea9137 AC |
6732 | |
6733 | Of course, run-time checks are omitted whenever the compiler can prove | |
6734 | that they will not fail, whether or not checks are suppressed. | |
6735 | ||
6736 | Note that if you suppress a check that would have failed, program | |
6737 | execution is erroneous, which means the behavior is totally | |
6738 | unpredictable. The program might crash, or print wrong answers, or | |
6739 | do anything else. It might even do exactly what you wanted it to do | |
6740 | (and then it might start failing mysteriously next week or next | |
6741 | year). The compiler will generate code based on the assumption that | |
6742 | the condition being checked is true, which can result in disaster if | |
6743 | that assumption is wrong. | |
6744 | ||
0088ba92 RD |
6745 | The checks subject to suppression include all the checks defined by |
6746 | the Ada standard, the additional implementation defined checks | |
6747 | @code{Alignment_Check}, @code{Atomic_Synchronization}, and | |
6748 | @code{Validity_Check}, as well as any checks introduced using | |
6749 | @code{pragma Check_Name}. | |
6750 | ||
3f165ff2 AC |
6751 | The @option{-gnatp} switch has no effect if a subsequent |
6752 | @option{-gnat-p} switch appears. | |
6753 | ||
6754 | @item -gnat-p | |
6755 | @cindex @option{-gnat-p} (@command{gcc}) | |
6756 | @cindex Suppressing checks | |
6757 | @cindex Checks, suppressing | |
6758 | @findex Suppress | |
6759 | This switch cancels the effect of a previous @option{gnatp} switch. | |
6760 | ||
6e6636ec RD |
6761 | @item -gnato?? |
6762 | @cindex @option{-gnato??} (@command{gcc}) | |
88e1739c | 6763 | @cindex Overflow checks |
ceee0bde | 6764 | @cindex Overflow mode |
88e1739c | 6765 | @cindex Check, overflow |
ceee0bde AC |
6766 | This switch controls the mode used for computing intermediate |
6767 | arithmetic integer operations, and also enables overflow checking. | |
6768 | For a full description of overflow mode and checking control, see | |
6769 | the ``Overflow Check Handling in GNAT'' appendix in this | |
6770 | User's Guide. | |
88e1739c | 6771 | |
ceee0bde AC |
6772 | Overflow checks are always enabled by this switch. The argument |
6773 | controls the mode, using the codes | |
6774 | ||
6775 | @itemize | |
6776 | @item 1 = STRICT | |
6777 | In STRICT mode, intermediate operations are always done using the | |
6778 | base type, and overflow checking ensures that the result is within | |
6779 | the base type range. | |
6780 | ||
6781 | @item 2 = MINIMIZED | |
6782 | In MINIMIZED mode, overflows in intermediate operations are avoided | |
6783 | where possible by using a larger integer type for the computation | |
03a2b9ed | 6784 | (typically @code{Long_Long_Integer}). Overflow checking ensures that |
ceee0bde AC |
6785 | the result fits in this larger integer type. |
6786 | ||
6787 | @item 3 = ELIMINATED | |
6788 | In ELIMINATED mode, overflows in intermediate operations are avoided | |
6789 | by using multi-precision arithmetic. In this case, overflow checking | |
6790 | has no effect on intermediate operations (since overflow is impossible). | |
6791 | @end itemize | |
6792 | ||
6793 | If two digits are present after @option{-gnato} then the first digit | |
6794 | sets the mode for expressions outside assertions, and the second digit | |
6795 | sets the mode for expressions within assertions. Here assertions is used | |
6796 | in the technical sense (which includes for example precondition and | |
6797 | postcondition expressions). | |
6798 | ||
6799 | If one digit is present, the corresponding mode is applicable to both | |
6800 | expressions within and outside assertion expressions. | |
6801 | ||
6802 | If no digits are present, the default is to enable overflow checks | |
6803 | and set STRICT mode for both kinds of expressions. This is compatible | |
6804 | with the use of @option{-gnato} in previous versions of GNAT. | |
88e1739c FW |
6805 | |
6806 | @findex Machine_Overflows | |
6e6636ec | 6807 | Note that the @option{-gnato??} switch does not affect the code generated |
354c3840 | 6808 | for any floating-point operations; it applies only to integer semantics. |
6e6636ec | 6809 | For floating-point, @value{EDITION} has the @code{Machine_Overflows} |
88e1739c FW |
6810 | attribute set to @code{False} and the normal mode of operation is to |
6811 | generate IEEE NaN and infinite values on overflow or invalid operations | |
6812 | (such as dividing 0.0 by 0.0). | |
6813 | ||
6814 | The reason that we distinguish overflow checking from other kinds of | |
1a5f40e1 VC |
6815 | range constraint checking is that a failure of an overflow check, unlike |
6816 | for example the failure of a range check, can result in an incorrect | |
6817 | value, but cannot cause random memory destruction (like an out of range | |
6818 | subscript), or a wild jump (from an out of range case value). Overflow | |
6819 | checking is also quite expensive in time and space, since in general it | |
6820 | requires the use of double length arithmetic. | |
88e1739c | 6821 | |
354c3840 AC |
6822 | Note again that the default is @option{^-gnato00^/OVERFLOW_CHECKS=00^}, |
6823 | so overflow checking is not performed in default mode. This means that out of | |
6824 | the box, with the default settings, @value{EDITION} does not do all the checks | |
6825 | expected from the language description in the Ada Reference Manual. | |
6826 | If you want all constraint checks to be performed, as described in this Manual, | |
6827 | then you must explicitly use the @option{-gnato??} | |
6828 | switch either on the @command{gnatmake} or @command{gcc} command. | |
88e1739c FW |
6829 | |
6830 | @item -gnatE | |
984a64bc | 6831 | @cindex @option{-gnatE} (@command{gcc}) |
88e1739c FW |
6832 | @cindex Elaboration checks |
6833 | @cindex Check, elaboration | |
6834 | Enables dynamic checks for access-before-elaboration | |
6835 | on subprogram calls and generic instantiations. | |
a3ea9137 AC |
6836 | Note that @option{-gnatE} is not necessary for safety, because in the |
6837 | default mode, GNAT ensures statically that the checks would not fail. | |
88e1739c | 6838 | For full details of the effect and use of this switch, |
c2658843 | 6839 | @xref{Compiling with gcc}. |
32e209e4 CC |
6840 | |
6841 | @item -fstack-check | |
6842 | @cindex @option{-fstack-check} (@command{gcc}) | |
6843 | @cindex Stack Overflow Checking | |
6844 | @cindex Checks, stack overflow checking | |
6845 | Activates stack overflow checking. For full details of the effect and use of | |
6846 | this switch see @ref{Stack Overflow Checking}. | |
88e1739c FW |
6847 | @end table |
6848 | ||
6849 | @findex Unsuppress | |
6850 | @noindent | |
6851 | The setting of these switches only controls the default setting of the | |
6852 | checks. You may modify them using either @code{Suppress} (to remove | |
6853 | checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in | |
6854 | the program source. | |
6855 | ||
88e1739c | 6856 | @node Using gcc for Syntax Checking |
984a64bc | 6857 | @subsection Using @command{gcc} for Syntax Checking |
7cd4527e | 6858 | @table @option |
88e1739c | 6859 | @item -gnats |
984a64bc | 6860 | @cindex @option{-gnats} (@command{gcc}) |
88e1739c FW |
6861 | @ifclear vms |
6862 | ||
6863 | @noindent | |
7cd4527e | 6864 | The @code{s} stands for ``syntax''. |
88e1739c FW |
6865 | @end ifclear |
6866 | ||
6867 | Run GNAT in syntax checking only mode. For | |
6868 | example, the command | |
6869 | ||
6870 | @smallexample | |
6871 | $ gcc -c -gnats x.adb | |
6872 | @end smallexample | |
6873 | ||
6874 | @noindent | |
6875 | compiles file @file{x.adb} in syntax-check-only mode. You can check a | |
6876 | series of files in a single command | |
6877 | @ifclear vms | |
6878 | , and can use wild cards to specify such a group of files. | |
7cd4527e | 6879 | Note that you must specify the @option{-c} (compile |
88e1739c FW |
6880 | only) flag in addition to the @option{-gnats} flag. |
6881 | @end ifclear | |
6882 | . | |
88e1739c FW |
6883 | You may use other switches in conjunction with @option{-gnats}. In |
6884 | particular, @option{-gnatl} and @option{-gnatv} are useful to control the | |
6885 | format of any generated error messages. | |
6886 | ||
7cd4527e AC |
6887 | When the source file is empty or contains only empty lines and/or comments, |
6888 | the output is a warning: | |
6889 | ||
6890 | @smallexample | |
6891 | $ gcc -c -gnats -x ada toto.txt | |
6892 | toto.txt:1:01: warning: empty file, contains no compilation units | |
6893 | $ | |
6894 | @end smallexample | |
6895 | ||
6896 | Otherwise, the output is simply the error messages, if any. No object file or | |
6897 | ALI file is generated by a syntax-only compilation. Also, no units other | |
88e1739c FW |
6898 | than the one specified are accessed. For example, if a unit @code{X} |
6899 | @code{with}'s a unit @code{Y}, compiling unit @code{X} in syntax | |
6900 | check only mode does not access the source file containing unit | |
6901 | @code{Y}. | |
6902 | ||
6903 | @cindex Multiple units, syntax checking | |
6904 | Normally, GNAT allows only a single unit in a source file. However, this | |
6905 | restriction does not apply in syntax-check-only mode, and it is possible | |
6906 | to check a file containing multiple compilation units concatenated | |
6907 | together. This is primarily used by the @code{gnatchop} utility | |
c2658843 | 6908 | (@pxref{Renaming Files with gnatchop}). |
88e1739c FW |
6909 | @end table |
6910 | ||
6911 | @node Using gcc for Semantic Checking | |
984a64bc | 6912 | @subsection Using @command{gcc} for Semantic Checking |
7cd4527e | 6913 | @table @option |
88e1739c | 6914 | @item -gnatc |
984a64bc | 6915 | @cindex @option{-gnatc} (@command{gcc}) |
88e1739c FW |
6916 | |
6917 | @ifclear vms | |
6918 | @noindent | |
7cd4527e | 6919 | The @code{c} stands for ``check''. |
88e1739c FW |
6920 | @end ifclear |
6921 | Causes the compiler to operate in semantic check mode, | |
6922 | with full checking for all illegalities specified in the | |
e08b38f5 | 6923 | Ada Reference Manual, but without generation of any object code |
88e1739c FW |
6924 | (no object file is generated). |
6925 | ||
6926 | Because dependent files must be accessed, you must follow the GNAT | |
6927 | semantic restrictions on file structuring to operate in this mode: | |
6928 | ||
6929 | @itemize @bullet | |
6930 | @item | |
6931 | The needed source files must be accessible | |
6932 | (@pxref{Search Paths and the Run-Time Library (RTL)}). | |
6933 | ||
6934 | @item | |
6935 | Each file must contain only one compilation unit. | |
6936 | ||
6937 | @item | |
6938 | The file name and unit name must match (@pxref{File Naming Rules}). | |
6939 | @end itemize | |
6940 | ||
6941 | The output consists of error messages as appropriate. No object file is | |
6942 | generated. An @file{ALI} file is generated for use in the context of | |
6943 | cross-reference tools, but this file is marked as not being suitable | |
6944 | for binding (since no object file is generated). | |
6945 | The checking corresponds exactly to the notion of | |
e08b38f5 | 6946 | legality in the Ada Reference Manual. |
88e1739c FW |
6947 | |
6948 | Any unit can be compiled in semantics-checking-only mode, including | |
6949 | units that would not normally be compiled (subunits, | |
6950 | and specifications where a separate body is present). | |
6951 | @end table | |
6952 | ||
0f1b0456 GB |
6953 | @node Compiling Different Versions of Ada |
6954 | @subsection Compiling Different Versions of Ada | |
e08b38f5 VC |
6955 | |
6956 | @noindent | |
6957 | The switches described in this section allow you to explicitly specify | |
6958 | the version of the Ada language that your programs are written in. | |
49eef89f AC |
6959 | The default mode is Ada 2012, |
6960 | but you can also specify Ada 95, Ada 2005 mode, or | |
e08b38f5 VC |
6961 | indicate Ada 83 compatibility mode. |
6962 | ||
7cd4527e | 6963 | @table @option |
0f1b0456 | 6964 | @cindex Compatibility with Ada 83 |
0f1b0456 GB |
6965 | |
6966 | @item -gnat83 (Ada 83 Compatibility Mode) | |
984a64bc | 6967 | @cindex @option{-gnat83} (@command{gcc}) |
88e1739c | 6968 | @cindex ACVC, Ada 83 tests |
e08b38f5 | 6969 | @cindex Ada 83 mode |
88e1739c FW |
6970 | |
6971 | @noindent | |
e08b38f5 VC |
6972 | Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch |
6973 | specifies that the program is to be compiled in Ada 83 mode. With | |
6974 | @option{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83 | |
6975 | semantics where this can be done easily. | |
88e1739c | 6976 | It is not possible to guarantee this switch does a perfect |
e08b38f5 | 6977 | job; some subtle tests, such as are |
7cd4527e AC |
6978 | found in earlier ACVC tests (and that have been removed from the ACATS suite |
6979 | for Ada 95), might not compile correctly. | |
6980 | Nevertheless, this switch may be useful in some circumstances, for example | |
e08b38f5 | 6981 | where, due to contractual reasons, existing code needs to be maintained |
7cd4527e | 6982 | using only Ada 83 features. |
88e1739c FW |
6983 | |
6984 | With few exceptions (most notably the need to use @code{<>} on | |
6985 | @cindex Generic formal parameters | |
e08b38f5 | 6986 | unconstrained generic formal parameters, the use of the new Ada 95 / Ada 2005 |
7cd4527e | 6987 | reserved words, and the use of packages |
e08b38f5 | 6988 | with optional bodies), it is not necessary to specify the |
88e1739c | 6989 | @option{-gnat83} switch when compiling Ada 83 programs, because, with rare |
e08b38f5 VC |
6990 | exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus |
6991 | a correct Ada 83 program is usually also a correct program | |
6992 | in these later versions of the language standard. | |
7cd4527e | 6993 | For further information, please refer to @ref{Compatibility and Porting Guide}. |
88e1739c | 6994 | |
0f1b0456 GB |
6995 | @item -gnat95 (Ada 95 mode) |
6996 | @cindex @option{-gnat95} (@command{gcc}) | |
e08b38f5 | 6997 | @cindex Ada 95 mode |
0f1b0456 GB |
6998 | |
6999 | @noindent | |
e08b38f5 VC |
7000 | This switch directs the compiler to implement the Ada 95 version of the |
7001 | language. | |
7002 | Since Ada 95 is almost completely upwards | |
7003 | compatible with Ada 83, Ada 83 programs may generally be compiled using | |
7004 | this switch (see the description of the @option{-gnat83} switch for further | |
7005 | information about Ada 83 mode). | |
7006 | If an Ada 2005 program is compiled in Ada 95 mode, | |
7007 | uses of the new Ada 2005 features will cause error | |
7008 | messages or warnings. | |
0f1b0456 | 7009 | |
e08b38f5 | 7010 | This switch also can be used to cancel the effect of a previous |
0eed45bb AC |
7011 | @option{-gnat83}, @option{-gnat05/2005}, or @option{-gnat12/2012} |
7012 | switch earlier in the command line. | |
0f1b0456 | 7013 | |
0eed45bb | 7014 | @item -gnat05 or -gnat2005 (Ada 2005 mode) |
0f1b0456 | 7015 | @cindex @option{-gnat05} (@command{gcc}) |
0eed45bb | 7016 | @cindex @option{-gnat2005} (@command{gcc}) |
e08b38f5 | 7017 | @cindex Ada 2005 mode |
0f1b0456 GB |
7018 | |
7019 | @noindent | |
e08b38f5 | 7020 | This switch directs the compiler to implement the Ada 2005 version of the |
0eed45bb | 7021 | language, as documented in the official Ada standards document. |
e08b38f5 VC |
7022 | Since Ada 2005 is almost completely upwards |
7023 | compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs | |
7024 | may generally be compiled using this switch (see the description of the | |
7025 | @option{-gnat83} and @option{-gnat95} switches for further | |
7026 | information). | |
0f1b0456 | 7027 | |
0eed45bb AC |
7028 | @item -gnat12 or -gnat2012 (Ada 2012 mode) |
7029 | @cindex @option{-gnat12} (@command{gcc}) | |
7030 | @cindex @option{-gnat2012} (@command{gcc}) | |
7031 | @cindex Ada 2012 mode | |
7032 | ||
7033 | @noindent | |
7034 | This switch directs the compiler to implement the Ada 2012 version of the | |
49eef89f | 7035 | language (also the default). |
0eed45bb AC |
7036 | Since Ada 2012 is almost completely upwards |
7037 | compatible with Ada 2005 (and thus also with Ada 83, and Ada 95), | |
7038 | Ada 83 and Ada 95 programs | |
7039 | may generally be compiled using this switch (see the description of the | |
7040 | @option{-gnat83}, @option{-gnat95}, and @option{-gnat05/2005} switches | |
7041 | for further information). | |
7042 | ||
0eed45bb AC |
7043 | @item -gnatX (Enable GNAT Extensions) |
7044 | @cindex @option{-gnatX} (@command{gcc}) | |
7045 | @cindex Ada language extensions | |
7046 | @cindex GNAT extensions | |
7047 | ||
7048 | @noindent | |
7049 | This switch directs the compiler to implement the latest version of the | |
7050 | language (currently Ada 2012) and also to enable certain GNAT implementation | |
7051 | extensions that are not part of any Ada standard. For a full list of these | |
7052 | extensions, see the GNAT reference manual. | |
88e1739c | 7053 | |
0eed45bb | 7054 | @end table |
e08b38f5 | 7055 | |
88e1739c FW |
7056 | @node Character Set Control |
7057 | @subsection Character Set Control | |
7cd4527e | 7058 | @table @option |
88e1739c | 7059 | @item ^-gnati^/IDENTIFIER_CHARACTER_SET=^@var{c} |
984a64bc | 7060 | @cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@command{gcc}) |
88e1739c FW |
7061 | |
7062 | @noindent | |
7063 | Normally GNAT recognizes the Latin-1 character set in source program | |
e08b38f5 | 7064 | identifiers, as described in the Ada Reference Manual. |
88e1739c FW |
7065 | This switch causes |
7066 | GNAT to recognize alternate character sets in identifiers. @var{c} is a | |
7067 | single character ^^or word^ indicating the character set, as follows: | |
7068 | ||
7069 | @table @code | |
7070 | @item 1 | |
7cd4527e | 7071 | ISO 8859-1 (Latin-1) identifiers |
88e1739c FW |
7072 | |
7073 | @item 2 | |
7cd4527e | 7074 | ISO 8859-2 (Latin-2) letters allowed in identifiers |
88e1739c FW |
7075 | |
7076 | @item 3 | |
7cd4527e | 7077 | ISO 8859-3 (Latin-3) letters allowed in identifiers |
88e1739c FW |
7078 | |
7079 | @item 4 | |
7cd4527e | 7080 | ISO 8859-4 (Latin-4) letters allowed in identifiers |
88e1739c FW |
7081 | |
7082 | @item 5 | |
7cd4527e | 7083 | ISO 8859-5 (Cyrillic) letters allowed in identifiers |
88e1739c FW |
7084 | |
7085 | @item 9 | |
7cd4527e | 7086 | ISO 8859-15 (Latin-9) letters allowed in identifiers |
88e1739c FW |
7087 | |
7088 | @item ^p^PC^ | |
7089 | IBM PC letters (code page 437) allowed in identifiers | |
7090 | ||
7091 | @item ^8^PC850^ | |
7092 | IBM PC letters (code page 850) allowed in identifiers | |
7093 | ||
7094 | @item ^f^FULL_UPPER^ | |
7095 | Full upper-half codes allowed in identifiers | |
7096 | ||
7097 | @item ^n^NO_UPPER^ | |
7098 | No upper-half codes allowed in identifiers | |
7099 | ||
7100 | @item ^w^WIDE^ | |
7101 | Wide-character codes (that is, codes greater than 255) | |
7102 | allowed in identifiers | |
7103 | @end table | |
7104 | ||
7105 | @xref{Foreign Language Representation}, for full details on the | |
7106 | implementation of these character sets. | |
7107 | ||
7108 | @item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e} | |
984a64bc | 7109 | @cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@command{gcc}) |
88e1739c FW |
7110 | Specify the method of encoding for wide characters. |
7111 | @var{e} is one of the following: | |
7112 | ||
7113 | @table @code | |
7114 | ||
7115 | @item ^h^HEX^ | |
7116 | Hex encoding (brackets coding also recognized) | |
7117 | ||
7118 | @item ^u^UPPER^ | |
7119 | Upper half encoding (brackets encoding also recognized) | |
7120 | ||
7121 | @item ^s^SHIFT_JIS^ | |
7122 | Shift/JIS encoding (brackets encoding also recognized) | |
7123 | ||
7124 | @item ^e^EUC^ | |
7125 | EUC encoding (brackets encoding also recognized) | |
7126 | ||
7127 | @item ^8^UTF8^ | |
7128 | UTF-8 encoding (brackets encoding also recognized) | |
7129 | ||
7130 | @item ^b^BRACKETS^ | |
7131 | Brackets encoding only (default value) | |
7132 | @end table | |
7e3d710b | 7133 | For full details on these encoding |
984a64bc | 7134 | methods see @ref{Wide Character Encodings}. |
88e1739c FW |
7135 | Note that brackets coding is always accepted, even if one of the other |
7136 | options is specified, so for example @option{-gnatW8} specifies that both | |
e69044cb | 7137 | brackets and UTF-8 encodings will be recognized. The units that are |
88e1739c FW |
7138 | with'ed directly or indirectly will be scanned using the specified |
7139 | representation scheme, and so if one of the non-brackets scheme is | |
7140 | used, it must be used consistently throughout the program. However, | |
7141 | since brackets encoding is always recognized, it may be conveniently | |
7142 | used in standard libraries, allowing these libraries to be used with | |
7143 | any of the available coding schemes. | |
b5bf3335 AC |
7144 | |
7145 | Note that brackets encoding only applies to program text. Within comments, | |
7146 | brackets are considered to be normal graphic characters, and bracket sequences | |
7147 | are never recognized as wide characters. | |
a2ad1f79 RD |
7148 | |
7149 | If no @option{-gnatW?} parameter is present, then the default | |
7150 | representation is normally Brackets encoding only. However, if the | |
7151 | first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard | |
7152 | byte order mark or BOM for UTF-8), then these three characters are | |
7153 | skipped and the default representation for the file is set to UTF-8. | |
88e1739c FW |
7154 | |
7155 | Note that the wide character representation that is specified (explicitly | |
7156 | or by default) for the main program also acts as the default encoding used | |
7157 | for Wide_Text_IO files if not specifically overridden by a WCEM form | |
7158 | parameter. | |
7159 | ||
7160 | @end table | |
b5bf3335 AC |
7161 | |
7162 | When no @option{-gnatW?} is specified, then characters (other than wide | |
7163 | characters represented using brackets notation) are treated as 8-bit | |
7164 | Latin-1 codes. The codes recognized are the Latin-1 graphic characters, | |
7165 | and ASCII format effectors (CR, LF, HT, VT). Other lower half control | |
7166 | characters in the range 16#00#..16#1F# are not accepted in program text | |
7167 | or in comments. Upper half control characters (16#80#..16#9F#) are rejected | |
7168 | in program text, but allowed and ignored in comments. Note in particular | |
7169 | that the Next Line (NEL) character whose encoding is 16#85# is not recognized | |
7170 | as an end of line in this default mode. If your source program contains | |
7171 | instances of the NEL character used as a line terminator, | |
7172 | you must use UTF-8 encoding for the whole | |
7173 | source program. In default mode, all lines must be ended by a standard | |
7174 | end of line sequence (CR, CR/LF, or LF). | |
7175 | ||
7176 | Note that the convention of simply accepting all upper half characters in | |
7177 | comments means that programs that use standard ASCII for program text, but | |
7178 | UTF-8 encoding for comments are accepted in default mode, providing that the | |
7179 | comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator. | |
7180 | This is a common mode for many programs with foreign language comments. | |
7181 | ||
88e1739c FW |
7182 | @node File Naming Control |
7183 | @subsection File Naming Control | |
7184 | ||
7cd4527e | 7185 | @table @option |
88e1739c | 7186 | @item ^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{n} |
984a64bc | 7187 | @cindex @option{-gnatk} (@command{gcc}) |
7cd4527e | 7188 | Activates file name ``krunching''. @var{n}, a decimal integer in the range |
88e1739c FW |
7189 | 1-999, indicates the maximum allowable length of a file name (not |
7190 | including the @file{.ads} or @file{.adb} extension). The default is not | |
7191 | to enable file name krunching. | |
7192 | ||
7193 | For the source file naming rules, @xref{File Naming Rules}. | |
7194 | @end table | |
7195 | ||
7196 | @node Subprogram Inlining Control | |
7197 | @subsection Subprogram Inlining Control | |
7198 | ||
7cd4527e AC |
7199 | @table @option |
7200 | @c !sort! | |
21791d97 | 7201 | @item -gnatn[12] |
984a64bc | 7202 | @cindex @option{-gnatn} (@command{gcc}) |
88e1739c FW |
7203 | @ifclear vms |
7204 | The @code{n} here is intended to suggest the first syllable of the | |
7cd4527e | 7205 | word ``inline''. |
88e1739c FW |
7206 | @end ifclear |
7207 | GNAT recognizes and processes @code{Inline} pragmas. However, for the | |
21791d97 AC |
7208 | inlining to actually occur, optimization must be enabled and, in order |
7209 | to enable inlining of subprograms specified by pragma @code{Inline}, | |
7cd4527e | 7210 | you must also specify this switch. |
88e1739c | 7211 | In the absence of this switch, GNAT does not attempt |
7cd4527e | 7212 | inlining and does not need to access the bodies of |
88e1739c FW |
7213 | subprograms for which @code{pragma Inline} is specified if they are not |
7214 | in the current unit. | |
7215 | ||
21791d97 AC |
7216 | You can optionally specify the inlining level: 1 for moderate inlining across |
7217 | modules, which is a good compromise between compilation times and performances | |
7218 | at run time, or 2 for full inlining across modules, which may bring about | |
7219 | longer compilation times. If no inlining level is specified, the compiler will | |
7220 | pick it based on the optimization level: 1 for @option{-O1}, @option{-O2} or | |
7221 | @option{-Os} and 2 for @option{-O3}. | |
7222 | ||
88e1739c FW |
7223 | If you specify this switch the compiler will access these bodies, |
7224 | creating an extra source dependency for the resulting object file, and | |
7225 | where possible, the call will be inlined. | |
7226 | For further details on when inlining is possible | |
984a64bc | 7227 | see @ref{Inlining of Subprograms}. |
88e1739c FW |
7228 | |
7229 | @item -gnatN | |
984a64bc | 7230 | @cindex @option{-gnatN} (@command{gcc}) |
f17889b3 RD |
7231 | This switch activates front-end inlining which also |
7232 | generates additional dependencies. | |
7233 | ||
7234 | When using a gcc-based back end (in practice this means using any version | |
7235 | of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of | |
7236 | @option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred. | |
7237 | Historically front end inlining was more extensive than the gcc back end | |
7238 | inlining, but that is no longer the case. | |
88e1739c FW |
7239 | @end table |
7240 | ||
7241 | @node Auxiliary Output Control | |
7242 | @subsection Auxiliary Output Control | |
7243 | ||
7cd4527e | 7244 | @table @option |
88e1739c | 7245 | @item -gnatt |
984a64bc | 7246 | @cindex @option{-gnatt} (@command{gcc}) |
88e1739c FW |
7247 | @cindex Writing internal trees |
7248 | @cindex Internal trees, writing to file | |
7249 | Causes GNAT to write the internal tree for a unit to a file (with the | |
7250 | extension @file{.adt}. | |
7251 | This not normally required, but is used by separate analysis tools. | |
7252 | Typically | |
7253 | these tools do the necessary compilations automatically, so you should | |
7254 | not have to specify this switch in normal operation. | |
d175a2fa | 7255 | Note that the combination of switches @option{-gnatct} |
7a5debc9 | 7256 | generates a tree in the form required by ASIS applications. |
88e1739c FW |
7257 | |
7258 | @item -gnatu | |
984a64bc | 7259 | @cindex @option{-gnatu} (@command{gcc}) |
88e1739c FW |
7260 | Print a list of units required by this compilation on @file{stdout}. |
7261 | The listing includes all units on which the unit being compiled depends | |
7262 | either directly or indirectly. | |
7263 | ||
7264 | @ifclear vms | |
7265 | @item -pass-exit-codes | |
984a64bc AC |
7266 | @cindex @option{-pass-exit-codes} (@command{gcc}) |
7267 | If this switch is not used, the exit code returned by @command{gcc} when | |
88e1739c FW |
7268 | compiling multiple files indicates whether all source files have |
7269 | been successfully used to generate object files or not. | |
7270 | ||
984a64bc | 7271 | When @option{-pass-exit-codes} is used, @command{gcc} exits with an extended |
88e1739c FW |
7272 | exit status and allows an integrated development environment to better |
7273 | react to a compilation failure. Those exit status are: | |
7274 | ||
7275 | @table @asis | |
7276 | @item 5 | |
7277 | There was an error in at least one source file. | |
7278 | @item 3 | |
7279 | At least one source file did not generate an object file. | |
7280 | @item 2 | |
7281 | The compiler died unexpectedly (internal error for example). | |
7282 | @item 0 | |
7283 | An object file has been generated for every source file. | |
7284 | @end table | |
7285 | @end ifclear | |
7286 | @end table | |
7287 | ||
7288 | @node Debugging Control | |
7289 | @subsection Debugging Control | |
7290 | ||
7cd4527e AC |
7291 | @table @option |
7292 | @c !sort! | |
88e1739c FW |
7293 | @cindex Debugging options |
7294 | @ifclear vms | |
7295 | @item -gnatd@var{x} | |
984a64bc | 7296 | @cindex @option{-gnatd} (@command{gcc}) |
88e1739c FW |
7297 | Activate internal debugging switches. @var{x} is a letter or digit, or |
7298 | string of letters or digits, which specifies the type of debugging | |
7299 | outputs desired. Normally these are used only for internal development | |
7300 | or system debugging purposes. You can find full documentation for these | |
7301 | switches in the body of the @code{Debug} unit in the compiler source | |
7302 | file @file{debug.adb}. | |
7303 | @end ifclear | |
7304 | ||
f7d7bb51 | 7305 | @item -gnatG[=nn] |
984a64bc | 7306 | @cindex @option{-gnatG} (@command{gcc}) |
88e1739c FW |
7307 | This switch causes the compiler to generate auxiliary output containing |
7308 | a pseudo-source listing of the generated expanded code. Like most Ada | |
7309 | compilers, GNAT works by first transforming the high level Ada code into | |
7310 | lower level constructs. For example, tasking operations are transformed | |
7311 | into calls to the tasking run-time routines. A unique capability of GNAT | |
7312 | is to list this expanded code in a form very close to normal Ada source. | |
7313 | This is very useful in understanding the implications of various Ada | |
7314 | usage on the efficiency of the generated code. There are many cases in | |
8dd07840 | 7315 | Ada (e.g.@: the use of controlled types), where simple Ada statements can |
88e1739c FW |
7316 | generate a lot of run-time code. By using @option{-gnatG} you can identify |
7317 | these cases, and consider whether it may be desirable to modify the coding | |
7318 | approach to improve efficiency. | |
7319 | ||
dcd8728b RD |
7320 | The optional parameter @code{nn} if present after -gnatG specifies an |
7321 | alternative maximum line length that overrides the normal default of 72. | |
7322 | This value is in the range 40-999999, values less than 40 being silently | |
f7d7bb51 | 7323 | reset to 40. The equal sign is optional. |
dcd8728b | 7324 | |
88e1739c FW |
7325 | The format of the output is very similar to standard Ada source, and is |
7326 | easily understood by an Ada programmer. The following special syntactic | |
7327 | additions correspond to low level features used in the generated code that | |
7328 | do not have any exact analogies in pure Ada source form. The following | |
1a5f40e1 | 7329 | is a partial list of these special constructions. See the spec |
88e1739c FW |
7330 | of package @code{Sprint} in file @file{sprint.ads} for a full list. |
7331 | ||
ba1cbfb9 RD |
7332 | If the switch @option{-gnatL} is used in conjunction with |
7333 | @cindex @option{-gnatL} (@command{gcc}) | |
7334 | @option{-gnatG}, then the original source lines are interspersed | |
7335 | in the expanded source (as comment lines with the original line number). | |
7336 | ||
88e1739c | 7337 | @table @code |
66bfd481 | 7338 | @item new @var{xxx} @r{[}storage_pool = @var{yyy}@r{]} |
88e1739c FW |
7339 | Shows the storage pool being used for an allocator. |
7340 | ||
7341 | @item at end @var{procedure-name}; | |
7342 | Shows the finalization (cleanup) procedure for a scope. | |
7343 | ||
7344 | @item (if @var{expr} then @var{expr} else @var{expr}) | |
7345 | Conditional expression equivalent to the @code{x?y:z} construction in C. | |
7346 | ||
7347 | @item @var{target}^^^(@var{source}) | |
7348 | A conversion with floating-point truncation instead of rounding. | |
7349 | ||
7350 | @item @var{target}?(@var{source}) | |
7351 | A conversion that bypasses normal Ada semantic checking. In particular | |
7352 | enumeration types and fixed-point types are treated simply as integers. | |
7353 | ||
7354 | @item @var{target}?^^^(@var{source}) | |
7355 | Combines the above two cases. | |
7356 | ||
7357 | @item @var{x} #/ @var{y} | |
7358 | @itemx @var{x} #mod @var{y} | |
7359 | @itemx @var{x} #* @var{y} | |
7360 | @itemx @var{x} #rem @var{y} | |
7361 | A division or multiplication of fixed-point values which are treated as | |
7362 | integers without any kind of scaling. | |
7363 | ||
66bfd481 | 7364 | @item free @var{expr} @r{[}storage_pool = @var{xxx}@r{]} |
88e1739c FW |
7365 | Shows the storage pool associated with a @code{free} statement. |
7366 | ||
9c8457a7 QO |
7367 | @item [subtype or type declaration] |
7368 | Used to list an equivalent declaration for an internally generated | |
7369 | type that is referenced elsewhere in the listing. | |
7370 | ||
e074d476 AC |
7371 | @c @item freeze @var{type-name} @ovar{actions} |
7372 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
7373 | @item freeze @var{type-name} @r{[}@var{actions}@r{]} | |
7e3d710b | 7374 | Shows the point at which @var{type-name} is frozen, with possible |
88e1739c FW |
7375 | associated actions to be performed at the freeze point. |
7376 | ||
7377 | @item reference @var{itype} | |
7378 | Reference (and hence definition) to internal type @var{itype}. | |
7379 | ||
7380 | @item @var{function-name}! (@var{arg}, @var{arg}, @var{arg}) | |
7381 | Intrinsic function call. | |
7382 | ||
7e3d710b | 7383 | @item @var{label-name} : label |
88e1739c FW |
7384 | Declaration of label @var{labelname}. |
7385 | ||
7e3d710b AC |
7386 | @item #$ @var{subprogram-name} |
7387 | An implicit call to a run-time support routine | |
7388 | (to meet the requirement of H.3.1(9) in a | |
7389 | convenient manner). | |
7390 | ||
d488f6ea | 7391 | @item @var{expr} && @var{expr} && @var{expr} @dots{} && @var{expr} |
88e1739c FW |
7392 | A multiple concatenation (same effect as @var{expr} & @var{expr} & |
7393 | @var{expr}, but handled more efficiently). | |
7394 | ||
7395 | @item [constraint_error] | |
7396 | Raise the @code{Constraint_Error} exception. | |
7397 | ||
7398 | @item @var{expression}'reference | |
7399 | A pointer to the result of evaluating @var{expression}. | |
7400 | ||
7401 | @item @var{target-type}!(@var{source-expression}) | |
7402 | An unchecked conversion of @var{source-expression} to @var{target-type}. | |
7403 | ||
7404 | @item [@var{numerator}/@var{denominator}] | |
7405 | Used to represent internal real literals (that) have no exact | |
7406 | representation in base 2-16 (for example, the result of compile time | |
7407 | evaluation of the expression 1.0/27.0). | |
7cd4527e | 7408 | @end table |
88e1739c | 7409 | |
f7d7bb51 | 7410 | @item -gnatD[=nn] |
984a64bc | 7411 | @cindex @option{-gnatD} (@command{gcc}) |
7cd4527e AC |
7412 | When used in conjunction with @option{-gnatG}, this switch causes |
7413 | the expanded source, as described above for | |
7414 | @option{-gnatG} to be written to files with names | |
88e1739c | 7415 | @file{^xxx.dg^XXX_DG^}, where @file{xxx} is the normal file name, |
7e3d710b | 7416 | instead of to the standard output file. For |
7cd4527e AC |
7417 | example, if the source file name is @file{hello.adb}, then a file |
7418 | @file{^hello.adb.dg^HELLO.ADB_DG^} will be written. The debugging | |
984a64bc | 7419 | information generated by the @command{gcc} @option{^-g^/DEBUG^} switch |
7cd4527e AC |
7420 | will refer to the generated @file{^xxx.dg^XXX_DG^} file. This allows |
7421 | you to do source level debugging using the generated code which is | |
7422 | sometimes useful for complex code, for example to find out exactly | |
7423 | which part of a complex construction raised an exception. This switch | |
7424 | also suppress generation of cross-reference information (see | |
7425 | @option{-gnatx}) since otherwise the cross-reference information | |
7426 | would refer to the @file{^.dg^.DG^} file, which would cause | |
7427 | confusion since this is not the original source file. | |
7428 | ||
7429 | Note that @option{-gnatD} actually implies @option{-gnatG} | |
7430 | automatically, so it is not necessary to give both options. | |
7431 | In other words @option{-gnatD} is equivalent to @option{-gnatDG}). | |
88e1739c | 7432 | |
ba1cbfb9 RD |
7433 | If the switch @option{-gnatL} is used in conjunction with |
7434 | @cindex @option{-gnatL} (@command{gcc}) | |
7435 | @option{-gnatDG}, then the original source lines are interspersed | |
7436 | in the expanded source (as comment lines with the original line number). | |
7437 | ||
dcd8728b RD |
7438 | The optional parameter @code{nn} if present after -gnatD specifies an |
7439 | alternative maximum line length that overrides the normal default of 72. | |
7440 | This value is in the range 40-999999, values less than 40 being silently | |
f7d7bb51 | 7441 | reset to 40. The equal sign is optional. |
dcd8728b | 7442 | |
8436e37c RD |
7443 | @item -gnatr |
7444 | @cindex @option{-gnatr} (@command{gcc}) | |
7445 | @cindex pragma Restrictions | |
7446 | This switch causes pragma Restrictions to be treated as Restriction_Warnings | |
7447 | so that violation of restrictions causes warnings rather than illegalities. | |
7448 | This is useful during the development process when new restrictions are added | |
7449 | or investigated. The switch also causes pragma Profile to be treated as | |
7450 | Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set | |
7451 | restriction warnings rather than restrictions. | |
7452 | ||
7cd4527e | 7453 | @ifclear vms |
66bfd481 | 7454 | @item -gnatR@r{[}0@r{|}1@r{|}2@r{|}3@r{[}s@r{]]} |
984a64bc | 7455 | @cindex @option{-gnatR} (@command{gcc}) |
88e1739c FW |
7456 | This switch controls output from the compiler of a listing showing |
7457 | representation information for declared types and objects. For | |
7458 | @option{-gnatR0}, no information is output (equivalent to omitting | |
7459 | the @option{-gnatR} switch). For @option{-gnatR1} (which is the default, | |
7460 | so @option{-gnatR} with no parameter has the same effect), size and alignment | |
7461 | information is listed for declared array and record types. For | |
7462 | @option{-gnatR2}, size and alignment information is listed for all | |
19992053 AC |
7463 | declared types and objects. The @code{Linker_Section} is also listed for any |
7464 | entity for which the @code{Linker_Section} is set explicitly or implicitly (the | |
7465 | latter case occurs for objects of a type for which a @code{Linker_Section} | |
7466 | is set). | |
7467 | ||
7468 | Finally @option{-gnatR3} includes symbolic | |
ba1cbfb9 | 7469 | expressions for values that are computed at run time for |
88e1739c FW |
7470 | variant records. These symbolic expressions have a mostly obvious |
7471 | format with #n being used to represent the value of the n'th | |
7472 | discriminant. See source files @file{repinfo.ads/adb} in the | |
7cd4527e | 7473 | @code{GNAT} sources for full details on the format of @option{-gnatR3} |
8dd07840 | 7474 | output. If the switch is followed by an s (e.g.@: @option{-gnatR2s}), then |
88e1739c FW |
7475 | the output is to a file with the name @file{^file.rep^file_REP^} where |
7476 | file is the name of the corresponding source file. | |
4bb9c7b9 AC |
7477 | |
7478 | @item -gnatRm[s] | |
7479 | This form of the switch controls output of subprogram conventions | |
7480 | and parameter passing mechanisms for all subprograms. A following | |
7481 | @code{s} means output to a file as described above. | |
7cd4527e AC |
7482 | @end ifclear |
7483 | @ifset vms | |
7484 | @item /REPRESENTATION_INFO | |
984a64bc | 7485 | @cindex @option{/REPRESENTATION_INFO} (@command{gcc}) |
7cd4527e AC |
7486 | This qualifier controls output from the compiler of a listing showing |
7487 | representation information for declared types and objects. For | |
7488 | @option{/REPRESENTATION_INFO=NONE}, no information is output | |
7489 | (equivalent to omitting the @option{/REPRESENTATION_INFO} qualifier). | |
7490 | @option{/REPRESENTATION_INFO} without option is equivalent to | |
7491 | @option{/REPRESENTATION_INFO=ARRAYS}. | |
7492 | For @option{/REPRESENTATION_INFO=ARRAYS}, size and alignment | |
7493 | information is listed for declared array and record types. For | |
7494 | @option{/REPRESENTATION_INFO=OBJECTS}, size and alignment information | |
7495 | is listed for all expression information for values that are computed | |
7496 | at run time for variant records. These symbolic expressions have a mostly | |
7497 | obvious format with #n being used to represent the value of the n'th | |
7498 | discriminant. See source files @file{REPINFO.ADS/ADB} in the | |
7499 | @code{GNAT} sources for full details on the format of | |
7500 | @option{/REPRESENTATION_INFO=SYMBOLIC} output. | |
7501 | If _FILE is added at the end of an option | |
8dd07840 | 7502 | (e.g.@: @option{/REPRESENTATION_INFO=ARRAYS_FILE}), |
7cd4527e AC |
7503 | then the output is to a file with the name @file{file_REP} where |
7504 | file is the name of the corresponding source file. | |
4bb9c7b9 AC |
7505 | |
7506 | @item /REPRESENTATION_INFO=MECHANISMS | |
7507 | This qualifier form controls output of subprogram conventions | |
7508 | and parameter passing mechanisms for all subprograms. It is | |
7509 | possible to append _FILE as described above to cause information | |
7510 | to be written to a file. | |
7cd4527e | 7511 | @end ifset |
4bb9c7b9 | 7512 | |
32e209e4 CC |
7513 | Note that it is possible for record components to have zero size. In |
7514 | this case, the component clause uses an obvious extension of permitted | |
7515 | Ada syntax, for example @code{at 0 range 0 .. -1}. | |
7cd4527e | 7516 | |
e08b38f5 VC |
7517 | Representation information requires that code be generated (since it is the |
7518 | code generator that lays out complex data structures). If an attempt is made | |
7519 | to output representation information when no code is generated, for example | |
7520 | when a subunit is compiled on its own, then no information can be generated | |
7521 | and the compiler outputs a message to this effect. | |
7522 | ||
7cd4527e | 7523 | @item -gnatS |
984a64bc | 7524 | @cindex @option{-gnatS} (@command{gcc}) |
7cd4527e AC |
7525 | The use of the switch @option{-gnatS} for an |
7526 | Ada compilation will cause the compiler to output a | |
7527 | representation of package Standard in a form very | |
7528 | close to standard Ada. It is not quite possible to | |
9bc856dd | 7529 | do this entirely in standard Ada (since new |
7cd4527e AC |
7530 | numeric base types cannot be created in standard |
7531 | Ada), but the output is easily | |
7532 | readable to any Ada programmer, and is useful to | |
7533 | determine the characteristics of target dependent | |
7534 | types in package Standard. | |
88e1739c FW |
7535 | |
7536 | @item -gnatx | |
984a64bc | 7537 | @cindex @option{-gnatx} (@command{gcc}) |
88e1739c FW |
7538 | Normally the compiler generates full cross-referencing information in |
7539 | the @file{ALI} file. This information is used by a number of tools, | |
7cd4527e | 7540 | including @code{gnatfind} and @code{gnatxref}. The @option{-gnatx} switch |
88e1739c FW |
7541 | suppresses this information. This saves some space and may slightly |
7542 | speed up compilation, but means that these tools cannot be used. | |
7543 | @end table | |
7544 | ||
7cd4527e AC |
7545 | @node Exception Handling Control |
7546 | @subsection Exception Handling Control | |
7547 | ||
7548 | @noindent | |
7549 | GNAT uses two methods for handling exceptions at run-time. The | |
0f1b0456 | 7550 | @code{setjmp/longjmp} method saves the context when entering |
7cd4527e AC |
7551 | a frame with an exception handler. Then when an exception is |
7552 | raised, the context can be restored immediately, without the | |
7553 | need for tracing stack frames. This method provides very fast | |
7554 | exception propagation, but introduces significant overhead for | |
7555 | the use of exception handlers, even if no exception is raised. | |
7556 | ||
7557 | The other approach is called ``zero cost'' exception handling. | |
7558 | With this method, the compiler builds static tables to describe | |
7559 | the exception ranges. No dynamic code is required when entering | |
7560 | a frame containing an exception handler. When an exception is | |
7561 | raised, the tables are used to control a back trace of the | |
7562 | subprogram invocation stack to locate the required exception | |
7563 | handler. This method has considerably poorer performance for | |
7564 | the propagation of exceptions, but there is no overhead for | |
984a64bc AC |
7565 | exception handlers if no exception is raised. Note that in this |
7566 | mode and in the context of mixed Ada and C/C++ programming, | |
7567 | to propagate an exception through a C/C++ code, the C/C++ code | |
7568 | must be compiled with the @option{-funwind-tables} GCC's | |
7569 | option. | |
7cd4527e | 7570 | |
0916df6a | 7571 | The following switches may be used to control which of the |
7cd4527e AC |
7572 | two exception handling methods is used. |
7573 | ||
7574 | @table @option | |
7575 | @c !sort! | |
7576 | ||
0f1b0456 GB |
7577 | @item --RTS=sjlj |
7578 | @cindex @option{--RTS=sjlj} (@command{gnatmake}) | |
0916df6a RD |
7579 | This switch causes the setjmp/longjmp run-time (when available) to be used |
7580 | for exception handling. If the default | |
7cd4527e | 7581 | mechanism for the target is zero cost exceptions, then |
0f1b0456 GB |
7582 | this switch can be used to modify this default, and must be |
7583 | used for all units in the partition. | |
7cd4527e AC |
7584 | This option is rarely used. One case in which it may be |
7585 | advantageous is if you have an application where exception | |
7586 | raising is common and the overall performance of the | |
7587 | application is improved by favoring exception propagation. | |
7588 | ||
0f1b0456 GB |
7589 | @item --RTS=zcx |
7590 | @cindex @option{--RTS=zcx} (@command{gnatmake}) | |
7cd4527e | 7591 | @cindex Zero Cost Exceptions |
0f1b0456 | 7592 | This switch causes the zero cost approach to be used |
7cd4527e | 7593 | for exception handling. If this is the default mechanism for the |
0916df6a | 7594 | target (see below), then this switch is unneeded. If the default |
0f1b0456 GB |
7595 | mechanism for the target is setjmp/longjmp exceptions, then |
7596 | this switch can be used to modify this default, and must be | |
7597 | used for all units in the partition. | |
7cd4527e | 7598 | This option can only be used if the zero cost approach |
0916df6a | 7599 | is available for the target in use, otherwise it will generate an error. |
7cd4527e AC |
7600 | @end table |
7601 | ||
7602 | @noindent | |
ba1cbfb9 RD |
7603 | The same option @option{--RTS} must be used both for @command{gcc} |
7604 | and @command{gnatbind}. Passing this option to @command{gnatmake} | |
7605 | (@pxref{Switches for gnatmake}) will ensure the required consistency | |
7606 | through the compilation and binding steps. | |
7607 | ||
88e1739c FW |
7608 | @node Units to Sources Mapping Files |
7609 | @subsection Units to Sources Mapping Files | |
7610 | ||
7cd4527e | 7611 | @table @option |
88e1739c | 7612 | |
6465b6a7 | 7613 | @item -gnatem=@var{path} |
984a64bc | 7614 | @cindex @option{-gnatem} (@command{gcc}) |
88e1739c FW |
7615 | A mapping file is a way to communicate to the compiler two mappings: |
7616 | from unit names to file names (without any directory information) and from | |
7617 | file names to path names (with full directory information). These mappings | |
7618 | are used by the compiler to short-circuit the path search. | |
7619 | ||
7cd4527e AC |
7620 | The use of mapping files is not required for correct operation of the |
7621 | compiler, but mapping files can improve efficiency, particularly when | |
7622 | sources are read over a slow network connection. In normal operation, | |
7623 | you need not be concerned with the format or use of mapping files, | |
7624 | and the @option{-gnatem} switch is not a switch that you would use | |
6465b6a7 | 7625 | explicitly. It is intended primarily for use by automatic tools such as |
984a64bc | 7626 | @command{gnatmake} running under the project file facility. The |
7cd4527e AC |
7627 | description here of the format of mapping files is provided |
7628 | for completeness and for possible use by other tools. | |
7629 | ||
6465b6a7 AC |
7630 | A mapping file is a sequence of sets of three lines. In each set, the |
7631 | first line is the unit name, in lower case, with @code{%s} appended | |
7632 | for specs and @code{%b} appended for bodies; the second line is the | |
7cd4527e | 7633 | file name; and the third line is the path name. |
88e1739c FW |
7634 | |
7635 | Example: | |
7636 | @smallexample | |
7637 | main%b | |
7638 | main.2.ada | |
7639 | /gnat/project1/sources/main.2.ada | |
7640 | @end smallexample | |
7641 | ||
6465b6a7 AC |
7642 | When the switch @option{-gnatem} is specified, the compiler will |
7643 | create in memory the two mappings from the specified file. If there is | |
7644 | any problem (nonexistent file, truncated file or duplicate entries), | |
7645 | no mapping will be created. | |
88e1739c | 7646 | |
6465b6a7 AC |
7647 | Several @option{-gnatem} switches may be specified; however, only the |
7648 | last one on the command line will be taken into account. | |
88e1739c | 7649 | |
6465b6a7 AC |
7650 | When using a project file, @command{gnatmake} creates a temporary |
7651 | mapping file and communicates it to the compiler using this switch. | |
88e1739c FW |
7652 | |
7653 | @end table | |
7654 | ||
7cd4527e AC |
7655 | @node Integrated Preprocessing |
7656 | @subsection Integrated Preprocessing | |
7657 | ||
7658 | @noindent | |
cd3cd5b1 AC |
7659 | GNAT sources may be preprocessed immediately before compilation. |
7660 | In this case, the actual | |
7cd4527e AC |
7661 | text of the source is not the text of the source file, but is derived from it |
7662 | through a process called preprocessing. Integrated preprocessing is specified | |
7663 | through switches @option{-gnatep} and/or @option{-gnateD}. @option{-gnatep} | |
7664 | indicates, through a text file, the preprocessing data to be used. | |
7665 | @option{-gnateD} specifies or modifies the values of preprocessing symbol. | |
7666 | ||
cd3cd5b1 AC |
7667 | @noindent |
7668 | Note that when integrated preprocessing is used, the output from the | |
7669 | preprocessor is not written to any external file. Instead it is passed | |
7670 | internally to the compiler. If you need to preserve the result of | |
7671 | preprocessing in a file, then you should use @command{gnatprep} | |
7672 | to perform the desired preprocessing in stand-alone mode. | |
7673 | ||
7cd4527e | 7674 | @noindent |
984a64bc | 7675 | It is recommended that @command{gnatmake} switch ^-s^/SWITCH_CHECK^ should be |
7cd4527e AC |
7676 | used when Integrated Preprocessing is used. The reason is that preprocessing |
7677 | with another Preprocessing Data file without changing the sources will | |
7678 | not trigger recompilation without this switch. | |
7679 | ||
7680 | @noindent | |
984a64bc | 7681 | Note that @command{gnatmake} switch ^-m^/MINIMAL_RECOMPILATION^ will almost |
7cd4527e | 7682 | always trigger recompilation for sources that are preprocessed, |
984a64bc | 7683 | because @command{gnatmake} cannot compute the checksum of the source after |
7cd4527e AC |
7684 | preprocessing. |
7685 | ||
7686 | @noindent | |
7687 | The actual preprocessing function is described in details in section | |
c2658843 | 7688 | @ref{Preprocessing with gnatprep}. This section only describes how integrated |
7cd4527e AC |
7689 | preprocessing is triggered and parameterized. |
7690 | ||
7691 | @table @code | |
7692 | ||
7693 | @item -gnatep=@var{file} | |
984a64bc | 7694 | @cindex @option{-gnatep} (@command{gcc}) |
7cd4527e AC |
7695 | This switch indicates to the compiler the file name (without directory |
7696 | information) of the preprocessor data file to use. The preprocessor data file | |
d986066d | 7697 | should be found in the source directories. Note that when the compiler is |
8b1011c0 | 7698 | called by a builder such as (@command{gnatmake} with a project |
d986066d AC |
7699 | file, if the object directory is not also a source directory, the builder needs |
7700 | to be called with @option{-x}. | |
7cd4527e AC |
7701 | |
7702 | @noindent | |
7703 | A preprocessing data file is a text file with significant lines indicating | |
7704 | how should be preprocessed either a specific source or all sources not | |
4d0e4612 | 7705 | mentioned in other lines. A significant line is a nonempty, non-comment line. |
7cd4527e AC |
7706 | Comments are similar to Ada comments. |
7707 | ||
7708 | @noindent | |
7709 | Each significant line starts with either a literal string or the character '*'. | |
7710 | A literal string is the file name (without directory information) of the source | |
7711 | to preprocess. A character '*' indicates the preprocessing for all the sources | |
7712 | that are not specified explicitly on other lines (order of the lines is not | |
7713 | significant). It is an error to have two lines with the same file name or two | |
7714 | lines starting with the character '*'. | |
7715 | ||
7716 | @noindent | |
7717 | After the file name or the character '*', another optional literal string | |
984a64bc AC |
7718 | indicating the file name of the definition file to be used for preprocessing |
7719 | (@pxref{Form of Definitions File}). The definition files are found by the | |
7cd4527e AC |
7720 | compiler in one of the source directories. In some cases, when compiling |
7721 | a source in a directory other than the current directory, if the definition | |
7722 | file is in the current directory, it may be necessary to add the current | |
7723 | directory as a source directory through switch ^-I.^/SEARCH=[]^, otherwise | |
7724 | the compiler would not find the definition file. | |
7725 | ||
7726 | @noindent | |
7727 | Then, optionally, ^switches^switches^ similar to those of @code{gnatprep} may | |
7728 | be found. Those ^switches^switches^ are: | |
7729 | ||
7730 | @table @code | |
7731 | ||
7732 | @item -b | |
7733 | Causes both preprocessor lines and the lines deleted by | |
7734 | preprocessing to be replaced by blank lines, preserving the line number. | |
7735 | This ^switch^switch^ is always implied; however, if specified after @option{-c} | |
7736 | it cancels the effect of @option{-c}. | |
7737 | ||
7738 | @item -c | |
7739 | Causes both preprocessor lines and the lines deleted | |
7740 | by preprocessing to be retained as comments marked | |
7741 | with the special string ``@code{--! }''. | |
7742 | ||
7743 | @item -Dsymbol=value | |
7744 | Define or redefine a symbol, associated with value. A symbol is an Ada | |
7745 | identifier, or an Ada reserved word, with the exception of @code{if}, | |
7746 | @code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. | |
7747 | @code{value} is either a literal string, an Ada identifier or any Ada reserved | |
7748 | word. A symbol declared with this ^switch^switch^ replaces a symbol with the | |
7749 | same name defined in a definition file. | |
7750 | ||
7751 | @item -s | |
7752 | Causes a sorted list of symbol names and values to be | |
7753 | listed on the standard output file. | |
7754 | ||
7755 | @item -u | |
7756 | Causes undefined symbols to be treated as having the value @code{FALSE} | |
7757 | in the context | |
7758 | of a preprocessor test. In the absence of this option, an undefined symbol in | |
7759 | a @code{#if} or @code{#elsif} test will be treated as an error. | |
7760 | ||
7761 | @end table | |
7762 | ||
7763 | @noindent | |
7764 | Examples of valid lines in a preprocessor data file: | |
7765 | ||
7766 | @smallexample | |
7767 | "toto.adb" "prep.def" -u | |
7768 | -- preprocess "toto.adb", using definition file "prep.def", | |
7769 | -- undefined symbol are False. | |
7770 | ||
7771 | * -c -DVERSION=V101 | |
7772 | -- preprocess all other sources without a definition file; | |
7773 | -- suppressed lined are commented; symbol VERSION has the value V101. | |
7774 | ||
7775 | "titi.adb" "prep2.def" -s | |
7776 | -- preprocess "titi.adb", using definition file "prep2.def"; | |
7777 | -- list all symbols with their values. | |
7778 | @end smallexample | |
7779 | ||
66bfd481 | 7780 | @item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=value@r{]} |
984a64bc | 7781 | @cindex @option{-gnateD} (@command{gcc}) |
7cd4527e AC |
7782 | Define or redefine a preprocessing symbol, associated with value. If no value |
7783 | is given on the command line, then the value of the symbol is @code{True}. | |
7784 | A symbol is an identifier, following normal Ada (case-insensitive) | |
455f3336 AC |
7785 | rules for its syntax, and value is either an arbitrary string between double |
7786 | quotes or any sequence (including an empty sequence) of characters from the | |
7787 | set (letters, digits, period, underline). | |
7cd4527e AC |
7788 | Ada reserved words may be used as symbols, with the exceptions of @code{if}, |
7789 | @code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. | |
7790 | ||
455f3336 AC |
7791 | @ifclear vms |
7792 | @noindent | |
7793 | Examples: | |
7794 | ||
7795 | @smallexample | |
7796 | -gnateDToto=Titi | |
7797 | -gnateDFoo | |
7798 | -gnateDFoo=\"Foo-Bar\" | |
7799 | @end smallexample | |
7800 | @end ifclear | |
7801 | ||
7cd4527e AC |
7802 | @noindent |
7803 | A symbol declared with this ^switch^switch^ on the command line replaces a | |
7804 | symbol with the same name either in a definition file or specified with a | |
7805 | ^switch^switch^ -D in the preprocessor data file. | |
7806 | ||
7807 | @noindent | |
7808 | This switch is similar to switch @option{^-D^/ASSOCIATE^} of @code{gnatprep}. | |
7809 | ||
1a9a686e VC |
7810 | @item -gnateG |
7811 | When integrated preprocessing is performed and the preprocessor modifies | |
7812 | the source text, write the result of this preprocessing into a file | |
7813 | <source>^.prep^_prep^. | |
7814 | ||
7cd4527e AC |
7815 | @end table |
7816 | ||
0fb2ea01 AC |
7817 | @node Code Generation Control |
7818 | @subsection Code Generation Control | |
7819 | ||
7820 | @noindent | |
7821 | ||
7822 | The GCC technology provides a wide range of target dependent | |
7823 | @option{-m} switches for controlling | |
7824 | details of code generation with respect to different versions of | |
8dd07840 | 7825 | architectures. This includes variations in instruction sets (e.g.@: |
0fb2ea01 | 7826 | different members of the power pc family), and different requirements |
8dd07840 | 7827 | for optimal arrangement of instructions (e.g.@: different members of |
0fb2ea01 AC |
7828 | the x86 family). The list of available @option{-m} switches may be |
7829 | found in the GCC documentation. | |
7830 | ||
7e3d710b | 7831 | Use of these @option{-m} switches may in some cases result in improved |
0fb2ea01 AC |
7832 | code performance. |
7833 | ||
164e06c6 | 7834 | The @value{EDITION} technology is tested and qualified without any |
0fb2ea01 AC |
7835 | @option{-m} switches, |
7836 | so generally the most reliable approach is to avoid the use of these | |
7837 | switches. However, we generally expect most of these switches to work | |
164e06c6 | 7838 | successfully with @value{EDITION}, and many customers have reported successful |
0fb2ea01 AC |
7839 | use of these options. |
7840 | ||
7841 | Our general advice is to avoid the use of @option{-m} switches unless | |
7842 | special needs lead to requirements in this area. In particular, | |
7843 | there is no point in using @option{-m} switches to improve performance | |
7844 | unless you actually see a performance improvement. | |
7845 | ||
7cd4527e AC |
7846 | @ifset vms |
7847 | @node Return Codes | |
7848 | @subsection Return Codes | |
7849 | @cindex Return Codes | |
7850 | @cindex @option{/RETURN_CODES=VMS} | |
7851 | ||
7852 | @noindent | |
7853 | On VMS, GNAT compiled programs return POSIX-style codes by default, | |
8dd07840 | 7854 | e.g.@: @option{/RETURN_CODES=POSIX}. |
7cd4527e | 7855 | |
984a64bc | 7856 | To enable VMS style return codes, use GNAT BIND and LINK with the option |
7cd4527e AC |
7857 | @option{/RETURN_CODES=VMS}. For example: |
7858 | ||
7859 | @smallexample | |
984a64bc | 7860 | GNAT BIND MYMAIN.ALI /RETURN_CODES=VMS |
7cd4527e AC |
7861 | GNAT LINK MYMAIN.ALI /RETURN_CODES=VMS |
7862 | @end smallexample | |
7863 | ||
7864 | @noindent | |
7865 | Programs built with /RETURN_CODES=VMS are suitable to be called in | |
7866 | VMS DCL scripts. Programs compiled with the default /RETURN_CODES=POSIX | |
7867 | are suitable for spawning with appropriate GNAT RTL routines. | |
7868 | ||
7869 | @end ifset | |
7870 | ||
88e1739c FW |
7871 | @node Search Paths and the Run-Time Library (RTL) |
7872 | @section Search Paths and the Run-Time Library (RTL) | |
7873 | ||
7874 | @noindent | |
7875 | With the GNAT source-based library system, the compiler must be able to | |
7876 | find source files for units that are needed by the unit being compiled. | |
7877 | Search paths are used to guide this process. | |
7878 | ||
7879 | The compiler compiles one source file whose name must be given | |
7880 | explicitly on the command line. In other words, no searching is done | |
7881 | for this file. To find all other source files that are needed (the most | |
7882 | common being the specs of units), the compiler examines the following | |
7883 | directories, in the following order: | |
7884 | ||
7885 | @enumerate | |
7886 | @item | |
7887 | The directory containing the source file of the main unit being compiled | |
7888 | (the file name on the command line). | |
7889 | ||
7890 | @item | |
7cd4527e | 7891 | Each directory named by an @option{^-I^/SOURCE_SEARCH^} switch given on the |
984a64bc | 7892 | @command{gcc} command line, in the order given. |
88e1739c | 7893 | |
0453ca3d RD |
7894 | @item |
7895 | @findex ADA_PRJ_INCLUDE_FILE | |
7896 | Each of the directories listed in the text file whose name is given | |
443b3472 | 7897 | by the @env{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^. |
0453ca3d RD |
7898 | |
7899 | @noindent | |
443b3472 | 7900 | @env{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^ |
0453ca3d RD |
7901 | driver when project files are used. It should not normally be set |
7902 | by other means. | |
7903 | ||
88e1739c FW |
7904 | @item |
7905 | @findex ADA_INCLUDE_PATH | |
7906 | Each of the directories listed in the value of the | |
443b3472 | 7907 | @env{ADA_INCLUDE_PATH} ^environment variable^logical name^. |
88e1739c FW |
7908 | @ifclear vms |
7909 | Construct this value | |
443b3472 | 7910 | exactly as the @env{PATH} environment variable: a list of directory |
88e1739c FW |
7911 | names separated by colons (semicolons when working with the NT version). |
7912 | @end ifclear | |
7913 | @ifset vms | |
7914 | Normally, define this value as a logical name containing a comma separated | |
7915 | list of directory names. | |
7916 | ||
7917 | This variable can also be defined by means of an environment string | |
32e209e4 | 7918 | (an argument to the HP C exec* set of functions). |
88e1739c FW |
7919 | |
7920 | Logical Name: | |
7921 | @smallexample | |
7922 | DEFINE ANOTHER_PATH FOO:[BAG] | |
7923 | DEFINE ADA_INCLUDE_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR] | |
7924 | @end smallexample | |
7925 | ||
7926 | By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] | |
e08b38f5 | 7927 | first, followed by the standard Ada |
88e1739c | 7928 | libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADAINCLUDE]. |
32e209e4 | 7929 | If this is not redefined, the user will obtain the HP Ada 83 IO packages |
88e1739c | 7930 | (Text_IO, Sequential_IO, etc) |
e08b38f5 | 7931 | instead of the standard Ada packages. Thus, in order to get the standard Ada |
88e1739c FW |
7932 | packages by default, ADA_INCLUDE_PATH must be redefined. |
7933 | @end ifset | |
7cd4527e | 7934 | |
88e1739c | 7935 | @item |
7cd4527e | 7936 | The content of the @file{ada_source_path} file which is part of the GNAT |
88e1739c FW |
7937 | installation tree and is used to store standard libraries such as the |
7938 | GNAT Run Time Library (RTL) source files. | |
7939 | @ifclear vms | |
87b3f81f | 7940 | @ref{Installing a library} |
88e1739c FW |
7941 | @end ifclear |
7942 | @end enumerate | |
7943 | ||
7944 | @noindent | |
7cd4527e | 7945 | Specifying the switch @option{^-I-^/NOCURRENT_DIRECTORY^} |
88e1739c FW |
7946 | inhibits the use of the directory |
7947 | containing the source file named in the command line. You can still | |
7948 | have this directory on your search path, but in this case it must be | |
7cd4527e | 7949 | explicitly requested with a @option{^-I^/SOURCE_SEARCH^} switch. |
88e1739c | 7950 | |
7cd4527e | 7951 | Specifying the switch @option{-nostdinc} |
88e1739c FW |
7952 | inhibits the search of the default location for the GNAT Run Time |
7953 | Library (RTL) source files. | |
7954 | ||
7955 | The compiler outputs its object files and ALI files in the current | |
7956 | working directory. | |
7957 | @ifclear vms | |
7cd4527e | 7958 | Caution: The object file can be redirected with the @option{-o} switch; |
984a64bc | 7959 | however, @command{gcc} and @code{gnat1} have not been coordinated on this |
7cd4527e AC |
7960 | so the @file{ALI} file will not go to the right place. Therefore, you should |
7961 | avoid using the @option{-o} switch. | |
88e1739c FW |
7962 | @end ifclear |
7963 | ||
7964 | @findex System.IO | |
7965 | The packages @code{Ada}, @code{System}, and @code{Interfaces} and their | |
7966 | children make up the GNAT RTL, together with the simple @code{System.IO} | |
7cd4527e | 7967 | package used in the @code{"Hello World"} example. The sources for these units |
88e1739c FW |
7968 | are needed by the compiler and are kept together in one directory. Not |
7969 | all of the bodies are needed, but all of the sources are kept together | |
7970 | anyway. In a normal installation, you need not specify these directory | |
7971 | names when compiling or binding. Either the environment variables or | |
7972 | the built-in defaults cause these files to be found. | |
7973 | ||
7cd4527e AC |
7974 | In addition to the language-defined hierarchies (@code{System}, @code{Ada} and |
7975 | @code{Interfaces}), the GNAT distribution provides a fourth hierarchy, | |
7976 | consisting of child units of @code{GNAT}. This is a collection of generally | |
b2e74434 RW |
7977 | useful types, subprograms, etc. @xref{Top, GNAT Reference Manual, About |
7978 | This Guid, gnat_rm, GNAT Reference Manual}, for further details. | |
88e1739c FW |
7979 | |
7980 | Besides simplifying access to the RTL, a major use of search paths is | |
7981 | in compiling sources from multiple directories. This can make | |
7982 | development environments much more flexible. | |
7983 | ||
7984 | @node Order of Compilation Issues | |
7985 | @section Order of Compilation Issues | |
7986 | ||
7987 | @noindent | |
7988 | If, in our earlier example, there was a spec for the @code{hello} | |
7989 | procedure, it would be contained in the file @file{hello.ads}; yet this | |
7990 | file would not have to be explicitly compiled. This is the result of the | |
7991 | model we chose to implement library management. Some of the consequences | |
7992 | of this model are as follows: | |
7993 | ||
7994 | @itemize @bullet | |
7995 | @item | |
7996 | There is no point in compiling specs (except for package | |
7997 | specs with no bodies) because these are compiled as needed by clients. If | |
7998 | you attempt a useless compilation, you will receive an error message. | |
7999 | It is also useless to compile subunits because they are compiled as needed | |
8000 | by the parent. | |
8001 | ||
8002 | @item | |
8003 | There are no order of compilation requirements: performing a | |
8004 | compilation never obsoletes anything. The only way you can obsolete | |
8005 | something and require recompilations is to modify one of the | |
8006 | source files on which it depends. | |
8007 | ||
8008 | @item | |
8009 | There is no library as such, apart from the ALI files | |
7cd4527e AC |
8010 | (@pxref{The Ada Library Information Files}, for information on the format |
8011 | of these files). For now we find it convenient to create separate ALI files, | |
8012 | but eventually the information therein may be incorporated into the object | |
88e1739c FW |
8013 | file directly. |
8014 | ||
8015 | @item | |
8016 | When you compile a unit, the source files for the specs of all units | |
8017 | that it @code{with}'s, all its subunits, and the bodies of any generics it | |
8018 | instantiates must be available (reachable by the search-paths mechanism | |
8019 | described above), or you will receive a fatal error message. | |
8020 | @end itemize | |
8021 | ||
8022 | @node Examples | |
8023 | @section Examples | |
8024 | ||
8025 | @noindent | |
8026 | The following are some typical Ada compilation command line examples: | |
8027 | ||
8028 | @table @code | |
8029 | @item $ gcc -c xyz.adb | |
8030 | Compile body in file @file{xyz.adb} with all default options. | |
8031 | ||
8032 | @ifclear vms | |
8033 | @item $ gcc -c -O2 -gnata xyz-def.adb | |
8034 | @end ifclear | |
8035 | @ifset vms | |
8036 | @item $ GNAT COMPILE /OPTIMIZE=ALL -gnata xyz-def.adb | |
8037 | @end ifset | |
8038 | ||
8039 | Compile the child unit package in file @file{xyz-def.adb} with extensive | |
8040 | optimizations, and pragma @code{Assert}/@code{Debug} statements | |
8041 | enabled. | |
8042 | ||
8043 | @item $ gcc -c -gnatc abc-def.adb | |
8044 | Compile the subunit in file @file{abc-def.adb} in semantic-checking-only | |
8045 | mode. | |
8046 | @end table | |
8047 | ||
c2658843 AC |
8048 | @node Binding with gnatbind |
8049 | @chapter Binding with @code{gnatbind} | |
88e1739c FW |
8050 | @findex gnatbind |
8051 | ||
8052 | @menu | |
8053 | * Running gnatbind:: | |
7cd4527e | 8054 | * Switches for gnatbind:: |
88e1739c FW |
8055 | * Command-Line Access:: |
8056 | * Search Paths for gnatbind:: | |
8057 | * Examples of gnatbind Usage:: | |
8058 | @end menu | |
8059 | ||
8060 | @noindent | |
8061 | This chapter describes the GNAT binder, @code{gnatbind}, which is used | |
e08b38f5 VC |
8062 | to bind compiled GNAT objects. |
8063 | ||
8064 | Note: to invoke @code{gnatbind} with a project file, use the @code{gnat} | |
8065 | driver (see @ref{The GNAT Driver and Project Files}). | |
8066 | ||
8067 | The @code{gnatbind} program performs four separate functions: | |
88e1739c FW |
8068 | |
8069 | @enumerate | |
8070 | @item | |
8071 | Checks that a program is consistent, in accordance with the rules in | |
e08b38f5 | 8072 | Chapter 10 of the Ada Reference Manual. In particular, error |
88e1739c FW |
8073 | messages are generated if a program uses inconsistent versions of a |
8074 | given unit. | |
8075 | ||
8076 | @item | |
8077 | Checks that an acceptable order of elaboration exists for the program | |
8078 | and issues an error message if it cannot find an order of elaboration | |
e08b38f5 | 8079 | that satisfies the rules in Chapter 10 of the Ada Language Manual. |
88e1739c FW |
8080 | |
8081 | @item | |
8082 | Generates a main program incorporating the given elaboration order. | |
8083 | This program is a small Ada package (body and spec) that | |
8084 | must be subsequently compiled | |
8085 | using the GNAT compiler. The necessary compilation step is usually | |
984a64bc | 8086 | performed automatically by @command{gnatlink}. The two most important |
88e1739c FW |
8087 | functions of this program |
8088 | are to call the elaboration routines of units in an appropriate order | |
8089 | and to call the main program. | |
8090 | ||
8091 | @item | |
8092 | Determines the set of object files required by the given main program. | |
8093 | This information is output in the forms of comments in the generated program, | |
984a64bc | 8094 | to be read by the @command{gnatlink} utility used to link the Ada application. |
88e1739c FW |
8095 | @end enumerate |
8096 | ||
8097 | @node Running gnatbind | |
8098 | @section Running @code{gnatbind} | |
8099 | ||
8100 | @noindent | |
8101 | The form of the @code{gnatbind} command is | |
8102 | ||
8103 | @smallexample | |
e074d476 AC |
8104 | @c $ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches} |
8105 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
8106 | $ gnatbind @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]} @r{[}@var{switches}@r{]} | |
88e1739c FW |
8107 | @end smallexample |
8108 | ||
8109 | @noindent | |
66bfd481 | 8110 | where @file{@var{mainprog}.adb} is the Ada file containing the main program |
e1b871e9 | 8111 | unit body. @code{gnatbind} constructs an Ada |
7cd4527e | 8112 | package in two files whose names are |
66bfd481 | 8113 | @file{b~@var{mainprog}.ads}, and @file{b~@var{mainprog}.adb}. |
88e1739c | 8114 | For example, if given the |
7cd4527e | 8115 | parameter @file{hello.ali}, for a main program contained in file |
88e1739c FW |
8116 | @file{hello.adb}, the binder output files would be @file{b~hello.ads} |
8117 | and @file{b~hello.adb}. | |
8118 | ||
8119 | When doing consistency checking, the binder takes into consideration | |
8120 | any source files it can locate. For example, if the binder determines | |
8121 | that the given main program requires the package @code{Pack}, whose | |
7cd4527e | 8122 | @file{.ALI} |
88e1739c FW |
8123 | file is @file{pack.ali} and whose corresponding source spec file is |
8124 | @file{pack.ads}, it attempts to locate the source file @file{pack.ads} | |
8125 | (using the same search path conventions as previously described for the | |
984a64bc | 8126 | @command{gcc} command). If it can locate this source file, it checks that |
88e1739c | 8127 | the time stamps |
7cd4527e AC |
8128 | or source checksums of the source and its references to in @file{ALI} files |
8129 | match. In other words, any @file{ALI} files that mentions this spec must have | |
88e1739c FW |
8130 | resulted from compiling this version of the source file (or in the case |
8131 | where the source checksums match, a version close enough that the | |
8132 | difference does not matter). | |
8133 | ||
8134 | @cindex Source files, use by binder | |
8135 | The effect of this consistency checking, which includes source files, is | |
8136 | that the binder ensures that the program is consistent with the latest | |
8137 | version of the source files that can be located at bind time. Editing a | |
8138 | source file without compiling files that depend on the source file cause | |
8139 | error messages to be generated by the binder. | |
8140 | ||
8141 | For example, suppose you have a main program @file{hello.adb} and a | |
8142 | package @code{P}, from file @file{p.ads} and you perform the following | |
8143 | steps: | |
8144 | ||
8145 | @enumerate | |
8146 | @item | |
8147 | Enter @code{gcc -c hello.adb} to compile the main program. | |
8148 | ||
8149 | @item | |
8150 | Enter @code{gcc -c p.ads} to compile package @code{P}. | |
8151 | ||
8152 | @item | |
8153 | Edit file @file{p.ads}. | |
8154 | ||
8155 | @item | |
8156 | Enter @code{gnatbind hello}. | |
8157 | @end enumerate | |
8158 | ||
7cd4527e | 8159 | @noindent |
88e1739c FW |
8160 | At this point, the file @file{p.ali} contains an out-of-date time stamp |
8161 | because the file @file{p.ads} has been edited. The attempt at binding | |
8162 | fails, and the binder generates the following error messages: | |
8163 | ||
8164 | @smallexample | |
8165 | error: "hello.adb" must be recompiled ("p.ads" has been modified) | |
8166 | error: "p.ads" has been modified and must be recompiled | |
8167 | @end smallexample | |
8168 | ||
8169 | @noindent | |
8170 | Now both files must be recompiled as indicated, and then the bind can | |
8171 | succeed, generating a main program. You need not normally be concerned | |
7cd4527e AC |
8172 | with the contents of this file, but for reference purposes a sample |
8173 | binder output file is given in @ref{Example of Binder Output File}. | |
88e1739c | 8174 | |
7cd4527e AC |
8175 | In most normal usage, the default mode of @command{gnatbind} which is to |
8176 | generate the main package in Ada, as described in the previous section. | |
8177 | In particular, this means that any Ada programmer can read and understand | |
8178 | the generated main program. It can also be debugged just like any other | |
8179 | Ada code provided the @option{^-g^/DEBUG^} switch is used for | |
8180 | @command{gnatbind} and @command{gnatlink}. | |
88e1739c | 8181 | |
7cd4527e AC |
8182 | @node Switches for gnatbind |
8183 | @section Switches for @command{gnatbind} | |
88e1739c | 8184 | |
7cd4527e AC |
8185 | @noindent |
8186 | The following switches are available with @code{gnatbind}; details will | |
8187 | be presented in subsequent sections. | |
88e1739c | 8188 | |
7cd4527e AC |
8189 | @menu |
8190 | * Consistency-Checking Modes:: | |
8191 | * Binder Error Message Control:: | |
8192 | * Elaboration Control:: | |
8193 | * Output Control:: | |
08564036 | 8194 | * Dynamic Allocation Control:: |
7cd4527e AC |
8195 | * Binding with Non-Ada Main Programs:: |
8196 | * Binding Programs with No Main Subprogram:: | |
8197 | @end menu | |
88e1739c | 8198 | |
7cd4527e AC |
8199 | @table @option |
8200 | @c !sort! | |
e08b38f5 | 8201 | |
54df6fd9 VC |
8202 | @item --version |
8203 | @cindex @option{--version} @command{gnatbind} | |
8204 | Display Copyright and version, then exit disregarding all other options. | |
8205 | ||
8206 | @item --help | |
8207 | @cindex @option{--help} @command{gnatbind} | |
8208 | If @option{--version} was not used, display usage, then exit disregarding | |
8209 | all other options. | |
8210 | ||
e08b38f5 VC |
8211 | @item -a |
8212 | @cindex @option{-a} @command{gnatbind} | |
8213 | Indicates that, if supported by the platform, the adainit procedure should | |
8214 | be treated as an initialisation routine by the linker (a constructor). This | |
8215 | is intended to be used by the Project Manager to automatically initialize | |
8216 | shared Stand-Alone Libraries. | |
8217 | ||
7cd4527e AC |
8218 | @item ^-aO^/OBJECT_SEARCH^ |
8219 | @cindex @option{^-aO^/OBJECT_SEARCH^} (@command{gnatbind}) | |
8220 | Specify directory to be searched for ALI files. | |
88e1739c | 8221 | |
7cd4527e AC |
8222 | @item ^-aI^/SOURCE_SEARCH^ |
8223 | @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind}) | |
8224 | Specify directory to be searched for source file. | |
88e1739c | 8225 | |
12577815 TQ |
8226 | @item ^-A^/ALI_LIST^@r{[=}@var{filename}@r{]} |
8227 | @cindex @option{^-A^/ALI_LIST^} (@command{gnatbind}) | |
8228 | Output ALI list (to standard output or to the named file). | |
8229 | ||
7cd4527e AC |
8230 | @item ^-b^/REPORT_ERRORS=BRIEF^ |
8231 | @cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@command{gnatbind}) | |
8232 | Generate brief messages to @file{stderr} even if verbose mode set. | |
88e1739c | 8233 | |
7cd4527e AC |
8234 | @item ^-c^/NOOUTPUT^ |
8235 | @cindex @option{^-c^/NOOUTPUT^} (@command{gnatbind}) | |
8236 | Check only, no generation of binder output file. | |
88e1739c | 8237 | |
66bfd481 RW |
8238 | @item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]} |
8239 | @cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}} (@command{gnatbind}) | |
7e3d710b AC |
8240 | This switch can be used to change the default task stack size value |
8241 | to a specified size @var{nn}, which is expressed in bytes by default, or | |
8242 | in kilobytes when suffixed with @var{k} or in megabytes when suffixed | |
8243 | with @var{m}. | |
66bfd481 RW |
8244 | In the absence of a @samp{@r{[}k@r{|}m@r{]}} suffix, this switch is equivalent, |
8245 | in effect, to completing all task specs with | |
7e3d710b AC |
8246 | @smallexample @c ada |
8247 | pragma Storage_Size (nn); | |
8248 | @end smallexample | |
8249 | When they do not already have such a pragma. | |
8250 | ||
66bfd481 | 8251 | @item ^-D^/DEFAULT_SECONDARY_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]} |
9c8457a7 QO |
8252 | @cindex @option{^-D^/DEFAULT_SECONDARY_STACK_SIZE=nnnnn^} (@command{gnatbind}) |
8253 | This switch can be used to change the default secondary stack size value | |
7e3d710b AC |
8254 | to a specified size @var{nn}, which is expressed in bytes by default, or |
8255 | in kilobytes when suffixed with @var{k} or in megabytes when suffixed | |
8256 | with @var{m}. | |
9c8457a7 QO |
8257 | |
8258 | The secondary stack is used to deal with functions that return a variable | |
8259 | sized result, for example a function returning an unconstrained | |
8260 | String. There are two ways in which this secondary stack is allocated. | |
8261 | ||
7e3d710b AC |
8262 | For most targets, the secondary stack is growing on demand and is allocated |
8263 | as a chain of blocks in the heap. The -D option is not very | |
8264 | relevant. It only give some control over the size of the allocated | |
8265 | blocks (whose size is the minimum of the default secondary stack size value, | |
8266 | and the actual size needed for the current allocation request). | |
9c8457a7 | 8267 | |
7e3d710b | 8268 | For certain targets, notably VxWorks 653, |
9c8457a7 | 8269 | the secondary stack is allocated by carving off a fixed ratio chunk of the |
c690a2ec | 8270 | primary task stack. The -D option is used to define the |
7e3d710b | 8271 | size of the environment task's secondary stack. |
9c8457a7 | 8272 | |
7cd4527e AC |
8273 | @item ^-e^/ELABORATION_DEPENDENCIES^ |
8274 | @cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@command{gnatbind}) | |
8275 | Output complete list of elaboration-order dependencies. | |
88e1739c | 8276 | |
7cd4527e AC |
8277 | @item ^-E^/STORE_TRACEBACKS^ |
8278 | @cindex @option{^-E^/STORE_TRACEBACKS^} (@command{gnatbind}) | |
8279 | Store tracebacks in exception occurrences when the target supports it. | |
7cd4527e AC |
8280 | @ignore |
8281 | @c The following may get moved to an appendix | |
8282 | This option is currently supported on the following targets: | |
8283 | all x86 ports, Solaris, Windows, HP-UX, AIX, PowerPC VxWorks and Alpha VxWorks. | |
8284 | @end ignore | |
8285 | See also the packages @code{GNAT.Traceback} and | |
8286 | @code{GNAT.Traceback.Symbolic} for more information. | |
8287 | @ifclear vms | |
8288 | Note that on x86 ports, you must not use @option{-fomit-frame-pointer} | |
984a64bc | 8289 | @command{gcc} option. |
d935a36e | 8290 | @end ifclear |
7cd4527e AC |
8291 | |
8292 | @item ^-F^/FORCE_ELABS_FLAGS^ | |
8293 | @cindex @option{^-F^/FORCE_ELABS_FLAGS^} (@command{gnatbind}) | |
8294 | Force the checks of elaboration flags. @command{gnatbind} does not normally | |
8295 | generate checks of elaboration flags for the main executable, except when | |
8296 | a Stand-Alone Library is used. However, there are cases when this cannot be | |
8297 | detected by gnatbind. An example is importing an interface of a Stand-Alone | |
8298 | Library through a pragma Import and only specifying through a linker switch | |
8299 | this Stand-Alone Library. This switch is used to guarantee that elaboration | |
8300 | flag checks are generated. | |
88e1739c | 8301 | |
7cd4527e AC |
8302 | @item ^-h^/HELP^ |
8303 | @cindex @option{^-h^/HELP^} (@command{gnatbind}) | |
8304 | Output usage (help) information | |
88e1739c | 8305 | |
08564036 AC |
8306 | @item ^-H32^/32_MALLOC^ |
8307 | @cindex @option{^-H32^/32_MALLOC^} (@command{gnatbind}) | |
8308 | Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types). | |
8309 | For further details see @ref{Dynamic Allocation Control}. | |
8310 | ||
8311 | @item ^-H64^/64_MALLOC^ | |
308e6f3a | 8312 | @cindex @option{^-H64^/64_MALLOC^} (@command{gnatbind}) |
08564036 AC |
8313 | Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types). |
8314 | @cindex @code{__gnat_malloc} | |
8315 | For further details see @ref{Dynamic Allocation Control}. | |
8316 | ||
7cd4527e AC |
8317 | @item ^-I^/SEARCH^ |
8318 | @cindex @option{^-I^/SEARCH^} (@command{gnatbind}) | |
8319 | Specify directory to be searched for source and ALI files. | |
88e1739c | 8320 | |
7cd4527e AC |
8321 | @item ^-I-^/NOCURRENT_DIRECTORY^ |
8322 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatbind}) | |
8323 | Do not look for sources in the current directory where @code{gnatbind} was | |
8324 | invoked, and do not look for ALI files in the directory containing the | |
8325 | ALI file named in the @code{gnatbind} command line. | |
88e1739c | 8326 | |
7cd4527e AC |
8327 | @item ^-l^/ORDER_OF_ELABORATION^ |
8328 | @cindex @option{^-l^/ORDER_OF_ELABORATION^} (@command{gnatbind}) | |
8329 | Output chosen elaboration order. | |
88e1739c | 8330 | |
79f34d07 | 8331 | @item ^-L@var{xxx}^/BUILD_LIBRARY=@var{xxx}^ |
7cd4527e | 8332 | @cindex @option{^-L^/BUILD_LIBRARY^} (@command{gnatbind}) |
984a64bc AC |
8333 | Bind the units for library building. In this case the adainit and |
8334 | adafinal procedures (@pxref{Binding with Non-Ada Main Programs}) | |
79f34d07 RW |
8335 | are renamed to ^@var{xxx}init^@var{XXX}INIT^ and |
8336 | ^@var{xxx}final^@var{XXX}FINAL^. | |
7cd4527e AC |
8337 | Implies ^-n^/NOCOMPILE^. |
8338 | @ifclear vms | |
984a64bc | 8339 | (@xref{GNAT and Libraries}, for more details.) |
7cd4527e AC |
8340 | @end ifclear |
8341 | @ifset vms | |
8342 | On OpenVMS, these init and final procedures are exported in uppercase | |
8343 | letters. For example if /BUILD_LIBRARY=toto is used, the exported name of | |
8344 | the init procedure will be "TOTOINIT" and the exported name of the final | |
8345 | procedure will be "TOTOFINAL". | |
8346 | @end ifset | |
88e1739c | 8347 | |
7cd4527e AC |
8348 | @item ^-Mxyz^/RENAME_MAIN=xyz^ |
8349 | @cindex @option{^-M^/RENAME_MAIN^} (@command{gnatbind}) | |
7e3d710b AC |
8350 | Rename generated main program from main to xyz. This option is |
8351 | supported on cross environments only. | |
88e1739c | 8352 | |
7cd4527e AC |
8353 | @item ^-m^/ERROR_LIMIT=^@var{n} |
8354 | @cindex @option{^-m^/ERROR_LIMIT^} (@command{gnatbind}) | |
923e6ff3 RD |
8355 | Limit number of detected errors or warnings to @var{n}, where @var{n} is |
8356 | in the range 1..999999. The default value if no switch is | |
8357 | given is 9999. If the number of warnings reaches this limit, then a | |
8358 | message is output and further warnings are suppressed, the bind | |
8359 | continues in this case. If the number of errors reaches this | |
8360 | limit, then a message is output and the bind is abandoned. | |
8361 | A value of zero means that no limit is enforced. The equal | |
8362 | sign is optional. | |
8363 | ||
7cd4527e AC |
8364 | @ifset unw |
8365 | Furthermore, under Windows, the sources pointed to by the libraries path | |
8366 | set in the registry are not searched for. | |
8367 | @end ifset | |
88e1739c | 8368 | |
7cd4527e AC |
8369 | @item ^-n^/NOMAIN^ |
8370 | @cindex @option{^-n^/NOMAIN^} (@command{gnatbind}) | |
8371 | No main program. | |
88e1739c | 8372 | |
7cd4527e AC |
8373 | @item -nostdinc |
8374 | @cindex @option{-nostdinc} (@command{gnatbind}) | |
8375 | Do not look for sources in the system default directory. | |
88e1739c | 8376 | |
7cd4527e AC |
8377 | @item -nostdlib |
8378 | @cindex @option{-nostdlib} (@command{gnatbind}) | |
8379 | Do not look for library files in the system default directory. | |
88e1739c | 8380 | |
7cd4527e AC |
8381 | @item --RTS=@var{rts-path} |
8382 | @cindex @option{--RTS} (@code{gnatbind}) | |
8383 | Specifies the default location of the runtime library. Same meaning as the | |
984a64bc | 8384 | equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). |
88e1739c | 8385 | |
7cd4527e AC |
8386 | @item ^-o ^/OUTPUT=^@var{file} |
8387 | @cindex @option{^-o ^/OUTPUT^} (@command{gnatbind}) | |
8388 | Name the output file @var{file} (default is @file{b~@var{xxx}.adb}). | |
8389 | Note that if this option is used, then linking must be done manually, | |
8390 | gnatlink cannot be used. | |
88e1739c | 8391 | |
12577815 | 8392 | @item ^-O^/OBJECT_LIST^@r{[=}@var{filename}@r{]} |
7cd4527e | 8393 | @cindex @option{^-O^/OBJECT_LIST^} (@command{gnatbind}) |
12577815 | 8394 | Output object list (to standard output or to the named file). |
88e1739c | 8395 | |
7cd4527e AC |
8396 | @item ^-p^/PESSIMISTIC_ELABORATION^ |
8397 | @cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@command{gnatbind}) | |
8398 | Pessimistic (worst-case) elaboration order | |
88e1739c | 8399 | |
c2db4b32 AC |
8400 | @item ^-P^-P^ |
8401 | @cindex @option{^-P^/CODEPEER^} (@command{gnatbind}) | |
8402 | Generate binder file suitable for CodePeer. | |
8403 | ||
e08b38f5 VC |
8404 | @item ^-R^-R^ |
8405 | @cindex @option{^-R^-R^} (@command{gnatbind}) | |
8406 | Output closure source list. | |
8407 | ||
7cd4527e AC |
8408 | @item ^-s^/READ_SOURCES=ALL^ |
8409 | @cindex @option{^-s^/READ_SOURCES=ALL^} (@command{gnatbind}) | |
8410 | Require all source files to be present. | |
88e1739c | 8411 | |
7cd4527e AC |
8412 | @item ^-S@var{xxx}^/INITIALIZE_SCALARS=@var{xxx}^ |
8413 | @cindex @option{^-S^/INITIALIZE_SCALARS^} (@command{gnatbind}) | |
8414 | Specifies the value to be used when detecting uninitialized scalar | |
8415 | objects with pragma Initialize_Scalars. | |
8416 | The @var{xxx} ^string specified with the switch^option^ may be either | |
8417 | @itemize @bullet | |
8418 | @item ``@option{^in^INVALID^}'' requesting an invalid value where possible | |
8419 | @item ``@option{^lo^LOW^}'' for the lowest possible value | |
7cd4527e | 8420 | @item ``@option{^hi^HIGH^}'' for the highest possible value |
79f34d07 RW |
8421 | @item ``@option{@var{xx}}'' for a value consisting of repeated bytes with the |
8422 | value @code{16#@var{xx}#} (i.e., @var{xx} is a string of two hexadecimal digits). | |
7cd4527e | 8423 | @end itemize |
88e1739c | 8424 | |
7cd4527e AC |
8425 | In addition, you can specify @option{-Sev} to indicate that the value is |
8426 | to be set at run time. In this case, the program will look for an environment | |
8427 | @cindex GNAT_INIT_SCALARS | |
79f34d07 RW |
8428 | variable of the form @env{GNAT_INIT_SCALARS=@var{xx}}, where @var{xx} is one |
8429 | of @option{in/lo/hi/@var{xx}} with the same meanings as above. | |
7cd4527e AC |
8430 | If no environment variable is found, or if it does not have a valid value, |
8431 | then the default is @option{in} (invalid values). | |
88e1739c | 8432 | |
7cd4527e AC |
8433 | @ifclear vms |
8434 | @item -static | |
8435 | @cindex @option{-static} (@code{gnatbind}) | |
8436 | Link against a static GNAT run time. | |
88e1739c | 8437 | |
7cd4527e AC |
8438 | @item -shared |
8439 | @cindex @option{-shared} (@code{gnatbind}) | |
8440 | Link against a shared GNAT run time when available. | |
8441 | @end ifclear | |
88e1739c | 8442 | |
7cd4527e AC |
8443 | @item ^-t^/NOTIME_STAMP_CHECK^ |
8444 | @cindex @option{^-t^/NOTIME_STAMP_CHECK^} (@code{gnatbind}) | |
8445 | Tolerate time stamp and other consistency errors | |
88e1739c | 8446 | |
7cd4527e AC |
8447 | @item ^-T@var{n}^/TIME_SLICE=@var{n}^ |
8448 | @cindex @option{^-T^/TIME_SLICE^} (@code{gnatbind}) | |
8449 | Set the time slice value to @var{n} milliseconds. If the system supports | |
8450 | the specification of a specific time slice value, then the indicated value | |
8451 | is used. If the system does not support specific time slice values, but | |
8452 | does support some general notion of round-robin scheduling, then any | |
ce2e12c2 | 8453 | nonzero value will activate round-robin scheduling. |
88e1739c | 8454 | |
7cd4527e AC |
8455 | A value of zero is treated specially. It turns off time |
8456 | slicing, and in addition, indicates to the tasking run time that the | |
8457 | semantics should match as closely as possible the Annex D | |
8458 | requirements of the Ada RM, and in particular sets the default | |
8459 | scheduling policy to @code{FIFO_Within_Priorities}. | |
88e1739c | 8460 | |
7e3d710b AC |
8461 | @item ^-u@var{n}^/DYNAMIC_STACK_USAGE=@var{n}^ |
8462 | @cindex @option{^-u^/DYNAMIC_STACK_USAGE^} (@code{gnatbind}) | |
54df6fd9 VC |
8463 | Enable dynamic stack usage, with @var{n} results stored and displayed |
8464 | at program termination. A result is generated when a task | |
8465 | terminates. Results that can't be stored are displayed on the fly, at | |
8466 | task termination. This option is currently not supported on Itanium | |
8467 | platforms. (See @ref{Dynamic Stack Usage Analysis} for details.) | |
7e3d710b | 8468 | |
7cd4527e AC |
8469 | @item ^-v^/REPORT_ERRORS=VERBOSE^ |
8470 | @cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind}) | |
8471 | Verbose mode. Write error messages, header, summary output to | |
8472 | @file{stdout}. | |
88e1739c | 8473 | |
7cd4527e AC |
8474 | @ifclear vms |
8475 | @item -w@var{x} | |
8476 | @cindex @option{-w} (@code{gnatbind}) | |
8477 | Warning mode (@var{x}=s/e for suppress/treat as error) | |
8478 | @end ifclear | |
88e1739c | 8479 | |
7cd4527e AC |
8480 | @ifset vms |
8481 | @item /WARNINGS=NORMAL | |
8482 | @cindex @option{/WARNINGS} (@code{gnatbind}) | |
8483 | Normal warnings mode. Warnings are issued but ignored | |
88e1739c | 8484 | |
7cd4527e AC |
8485 | @item /WARNINGS=SUPPRESS |
8486 | @cindex @option{/WARNINGS} (@code{gnatbind}) | |
8487 | All warning messages are suppressed | |
88e1739c | 8488 | |
7cd4527e AC |
8489 | @item /WARNINGS=ERROR |
8490 | @cindex @option{/WARNINGS} (@code{gnatbind}) | |
8491 | Warning messages are treated as fatal errors | |
8492 | @end ifset | |
88e1739c | 8493 | |
a2ad1f79 RD |
8494 | @item ^-Wx^/WIDE_CHARACTER_ENCODING=^@var{e} |
8495 | @cindex @option{^-Wx^/WIDE_CHARACTER_ENCODING^} (@code{gnatbind}) | |
8496 | Override default wide character encoding for standard Text_IO files. | |
8497 | ||
7cd4527e AC |
8498 | @item ^-x^/READ_SOURCES=NONE^ |
8499 | @cindex @option{^-x^/READ_SOURCES^} (@code{gnatbind}) | |
8500 | Exclude source files (check object consistency only). | |
88e1739c | 8501 | |
7cd4527e AC |
8502 | @ifset vms |
8503 | @item /READ_SOURCES=AVAILABLE | |
8504 | @cindex @option{/READ_SOURCES} (@code{gnatbind}) | |
8505 | Default mode, in which sources are checked for consistency only if | |
8506 | they are available. | |
8507 | @end ifset | |
88e1739c | 8508 | |
308aab0b AC |
8509 | @item ^-X@var{nnn}^/RETURN_CODES=POSIX^ |
8510 | @cindex @option{^-X@var{nnn}^/RETURN_CODES=POSIX^} (@code{gnatbind}) | |
8511 | Set default exit status value, normally 0 for POSIX compliance. | |
8512 | ||
8513 | @ifset vms | |
8514 | @item /RETURN_CODES=VMS | |
8515 | @cindex @option{/RETURN_CODES=VMS} (@code{gnatbind}) | |
8516 | VMS default normal successful return value is 1. | |
8517 | @end ifset | |
8518 | ||
7954ad60 SR |
8519 | @item ^-y^/ENABLE_LEAP_SECONDS^ |
8520 | @cindex @option{^-y^/ENABLE_LEAP_SECONDS^} (@code{gnatbind}) | |
8521 | Enable leap seconds support in @code{Ada.Calendar} and its children. | |
8522 | ||
7cd4527e AC |
8523 | @item ^-z^/ZERO_MAIN^ |
8524 | @cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind}) | |
8525 | No main subprogram. | |
8526 | @end table | |
88e1739c | 8527 | |
7cd4527e AC |
8528 | @ifclear vms |
8529 | @noindent | |
8530 | You may obtain this listing of switches by running @code{gnatbind} with | |
8531 | no arguments. | |
8532 | @end ifclear | |
88e1739c | 8533 | |
7cd4527e AC |
8534 | @node Consistency-Checking Modes |
8535 | @subsection Consistency-Checking Modes | |
88e1739c | 8536 | |
7cd4527e AC |
8537 | @noindent |
8538 | As described earlier, by default @code{gnatbind} checks | |
8539 | that object files are consistent with one another and are consistent | |
8540 | with any source files it can locate. The following switches control binder | |
8541 | access to sources. | |
88e1739c | 8542 | |
7cd4527e AC |
8543 | @table @option |
8544 | @c !sort! | |
8545 | @item ^-s^/READ_SOURCES=ALL^ | |
8546 | @cindex @option{^-s^/READ_SOURCES=ALL^} (@code{gnatbind}) | |
8547 | Require source files to be present. In this mode, the binder must be | |
8548 | able to locate all source files that are referenced, in order to check | |
8549 | their consistency. In normal mode, if a source file cannot be located it | |
8550 | is simply ignored. If you specify this switch, a missing source | |
8551 | file is an error. | |
88e1739c | 8552 | |
a2ad1f79 RD |
8553 | @item ^-Wx^/WIDE_CHARACTER_ENCODING=^@var{e} |
8554 | @cindex @option{^-Wx^/WIDE_CHARACTER_ENCODING^} (@code{gnatbind}) | |
8555 | Override default wide character encoding for standard Text_IO files. | |
8556 | Normally the default wide character encoding method used for standard | |
8557 | [Wide_[Wide_]]Text_IO files is taken from the encoding specified for | |
8558 | the main source input (see description of switch | |
8559 | @option{^-gnatWx^/WIDE_CHARACTER_ENCODING^} for the compiler). The | |
8560 | use of this switch for the binder (which has the same set of | |
8561 | possible arguments) overrides this default as specified. | |
8562 | ||
7cd4527e AC |
8563 | @item ^-x^/READ_SOURCES=NONE^ |
8564 | @cindex @option{^-x^/READ_SOURCES=NONE^} (@code{gnatbind}) | |
8565 | Exclude source files. In this mode, the binder only checks that ALI | |
8566 | files are consistent with one another. Source files are not accessed. | |
8567 | The binder runs faster in this mode, and there is still a guarantee that | |
8568 | the resulting program is self-consistent. | |
8569 | If a source file has been edited since it was last compiled, and you | |
8570 | specify this switch, the binder will not detect that the object | |
8571 | file is out of date with respect to the source file. Note that this is the | |
984a64bc | 8572 | mode that is automatically used by @command{gnatmake} because in this |
7cd4527e | 8573 | case the checking against sources has already been performed by |
8dd07840 | 8574 | @command{gnatmake} in the course of compilation (i.e.@: before binding). |
88e1739c | 8575 | |
7cd4527e AC |
8576 | @ifset vms |
8577 | @item /READ_SOURCES=AVAILABLE | |
8578 | @cindex @code{/READ_SOURCES=AVAILABLE} (@code{gnatbind}) | |
8579 | This is the default mode in which source files are checked if they are | |
8580 | available, and ignored if they are not available. | |
8581 | @end ifset | |
8582 | @end table | |
88e1739c | 8583 | |
7cd4527e AC |
8584 | @node Binder Error Message Control |
8585 | @subsection Binder Error Message Control | |
88e1739c | 8586 | |
7cd4527e AC |
8587 | @noindent |
8588 | The following switches provide control over the generation of error | |
8589 | messages from the binder: | |
88e1739c | 8590 | |
7cd4527e AC |
8591 | @table @option |
8592 | @c !sort! | |
8593 | @item ^-v^/REPORT_ERRORS=VERBOSE^ | |
8594 | @cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind}) | |
8595 | Verbose mode. In the normal mode, brief error messages are generated to | |
8596 | @file{stderr}. If this switch is present, a header is written | |
8597 | to @file{stdout} and any error messages are directed to @file{stdout}. | |
8598 | All that is written to @file{stderr} is a brief summary message. | |
88e1739c | 8599 | |
7cd4527e AC |
8600 | @item ^-b^/REPORT_ERRORS=BRIEF^ |
8601 | @cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@code{gnatbind}) | |
8602 | Generate brief error messages to @file{stderr} even if verbose mode is | |
8603 | specified. This is relevant only when used with the | |
8604 | @option{^-v^/REPORT_ERRORS=VERBOSE^} switch. | |
88e1739c | 8605 | |
7cd4527e AC |
8606 | @ifclear vms |
8607 | @item -m@var{n} | |
8608 | @cindex @option{-m} (@code{gnatbind}) | |
8609 | Limits the number of error messages to @var{n}, a decimal integer in the | |
8610 | range 1-999. The binder terminates immediately if this limit is reached. | |
88e1739c | 8611 | |
7cd4527e AC |
8612 | @item -M@var{xxx} |
8613 | @cindex @option{-M} (@code{gnatbind}) | |
8614 | Renames the generated main program from @code{main} to @code{xxx}. | |
8615 | This is useful in the case of some cross-building environments, where | |
8616 | the actual main program is separate from the one generated | |
8617 | by @code{gnatbind}. | |
8618 | @end ifclear | |
88e1739c | 8619 | |
7cd4527e AC |
8620 | @item ^-ws^/WARNINGS=SUPPRESS^ |
8621 | @cindex @option{^-ws^/WARNINGS=SUPPRESS^} (@code{gnatbind}) | |
8622 | @cindex Warnings | |
8623 | Suppress all warning messages. | |
88e1739c | 8624 | |
7cd4527e AC |
8625 | @item ^-we^/WARNINGS=ERROR^ |
8626 | @cindex @option{^-we^/WARNINGS=ERROR^} (@code{gnatbind}) | |
8627 | Treat any warning messages as fatal errors. | |
88e1739c | 8628 | |
7cd4527e AC |
8629 | @ifset vms |
8630 | @item /WARNINGS=NORMAL | |
8631 | Standard mode with warnings generated, but warnings do not get treated | |
8632 | as errors. | |
8633 | @end ifset | |
88e1739c | 8634 | |
7cd4527e AC |
8635 | @item ^-t^/NOTIME_STAMP_CHECK^ |
8636 | @cindex @option{^-t^/NOTIME_STAMP_CHECK^} (@code{gnatbind}) | |
8637 | @cindex Time stamp checks, in binder | |
8638 | @cindex Binder consistency checks | |
8639 | @cindex Consistency checks, in binder | |
8640 | The binder performs a number of consistency checks including: | |
88e1739c FW |
8641 | |
8642 | @itemize @bullet | |
8643 | @item | |
8644 | Check that time stamps of a given source unit are consistent | |
8645 | @item | |
8646 | Check that checksums of a given source unit are consistent | |
8647 | @item | |
8648 | Check that consistent versions of @code{GNAT} were used for compilation | |
8649 | @item | |
8650 | Check consistency of configuration pragmas as required | |
8651 | @end itemize | |
8652 | ||
8653 | @noindent | |
8654 | Normally failure of such checks, in accordance with the consistency | |
8655 | requirements of the Ada Reference Manual, causes error messages to be | |
8656 | generated which abort the binder and prevent the output of a binder | |
8657 | file and subsequent link to obtain an executable. | |
8658 | ||
7cd4527e | 8659 | The @option{^-t^/NOTIME_STAMP_CHECK^} switch converts these error messages |
88e1739c FW |
8660 | into warnings, so that |
8661 | binding and linking can continue to completion even in the presence of such | |
8662 | errors. The result may be a failed link (due to missing symbols), or a | |
8663 | non-functional executable which has undefined semantics. | |
8664 | @emph{This means that | |
7cd4527e | 8665 | @option{^-t^/NOTIME_STAMP_CHECK^} should be used only in unusual situations, |
88e1739c FW |
8666 | with extreme care.} |
8667 | @end table | |
8668 | ||
8669 | @node Elaboration Control | |
7cd4527e | 8670 | @subsection Elaboration Control |
88e1739c FW |
8671 | |
8672 | @noindent | |
8673 | The following switches provide additional control over the elaboration | |
984a64bc | 8674 | order. For full details see @ref{Elaboration Order Handling in GNAT}. |
88e1739c | 8675 | |
7cd4527e | 8676 | @table @option |
88e1739c | 8677 | @item ^-p^/PESSIMISTIC_ELABORATION^ |
7cd4527e | 8678 | @cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@code{gnatbind}) |
88e1739c FW |
8679 | Normally the binder attempts to choose an elaboration order that is |
8680 | likely to minimize the likelihood of an elaboration order error resulting | |
8681 | in raising a @code{Program_Error} exception. This switch reverses the | |
8682 | action of the binder, and requests that it deliberately choose an order | |
8683 | that is likely to maximize the likelihood of an elaboration error. | |
8684 | This is useful in ensuring portability and avoiding dependence on | |
8685 | accidental fortuitous elaboration ordering. | |
8686 | ||
7cd4527e AC |
8687 | Normally it only makes sense to use the @option{^-p^/PESSIMISTIC_ELABORATION^} |
8688 | switch if dynamic | |
88e1739c FW |
8689 | elaboration checking is used (@option{-gnatE} switch used for compilation). |
8690 | This is because in the default static elaboration mode, all necessary | |
32e209e4 | 8691 | @code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted. |
7cd4527e AC |
8692 | These implicit pragmas are still respected by the binder in |
8693 | @option{^-p^/PESSIMISTIC_ELABORATION^} mode, so a | |
88e1739c | 8694 | safe elaboration order is assured. |
414b312e AC |
8695 | |
8696 | Note that @option{^-p^/PESSIMISTIC_ELABORATION^} is not intended for | |
8697 | production use; it is more for debugging/experimental use. | |
88e1739c FW |
8698 | @end table |
8699 | ||
8700 | @node Output Control | |
7cd4527e | 8701 | @subsection Output Control |
88e1739c FW |
8702 | |
8703 | @noindent | |
8704 | The following switches allow additional control over the output | |
8705 | generated by the binder. | |
8706 | ||
7cd4527e AC |
8707 | @table @option |
8708 | @c !sort! | |
88e1739c | 8709 | |
88e1739c | 8710 | @item ^-c^/NOOUTPUT^ |
7cd4527e | 8711 | @cindex @option{^-c^/NOOUTPUT^} (@code{gnatbind}) |
88e1739c FW |
8712 | Check only. Do not generate the binder output file. In this mode the |
8713 | binder performs all error checks but does not generate an output file. | |
8714 | ||
88e1739c | 8715 | @item ^-e^/ELABORATION_DEPENDENCIES^ |
7cd4527e | 8716 | @cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@code{gnatbind}) |
88e1739c FW |
8717 | Output complete list of elaboration-order dependencies, showing the |
8718 | reason for each dependency. This output can be rather extensive but may | |
8719 | be useful in diagnosing problems with elaboration order. The output is | |
8720 | written to @file{stdout}. | |
8721 | ||
8722 | @item ^-h^/HELP^ | |
7cd4527e | 8723 | @cindex @option{^-h^/HELP^} (@code{gnatbind}) |
88e1739c FW |
8724 | Output usage information. The output is written to @file{stdout}. |
8725 | ||
8726 | @item ^-K^/LINKER_OPTION_LIST^ | |
7cd4527e | 8727 | @cindex @option{^-K^/LINKER_OPTION_LIST^} (@code{gnatbind}) |
88e1739c FW |
8728 | Output linker options to @file{stdout}. Includes library search paths, |
8729 | contents of pragmas Ident and Linker_Options, and libraries added | |
8730 | by @code{gnatbind}. | |
8731 | ||
8732 | @item ^-l^/ORDER_OF_ELABORATION^ | |
7cd4527e | 8733 | @cindex @option{^-l^/ORDER_OF_ELABORATION^} (@code{gnatbind}) |
88e1739c FW |
8734 | Output chosen elaboration order. The output is written to @file{stdout}. |
8735 | ||
8736 | @item ^-O^/OBJECT_LIST^ | |
7cd4527e | 8737 | @cindex @option{^-O^/OBJECT_LIST^} (@code{gnatbind}) |
88e1739c FW |
8738 | Output full names of all the object files that must be linked to provide |
8739 | the Ada component of the program. The output is written to @file{stdout}. | |
8740 | This list includes the files explicitly supplied and referenced by the user | |
8741 | as well as implicitly referenced run-time unit files. The latter are | |
8742 | omitted if the corresponding units reside in shared libraries. The | |
8743 | directory names for the run-time units depend on the system configuration. | |
8744 | ||
8745 | @item ^-o ^/OUTPUT=^@var{file} | |
7cd4527e | 8746 | @cindex @option{^-o^/OUTPUT^} (@code{gnatbind}) |
88e1739c FW |
8747 | Set name of output file to @var{file} instead of the normal |
8748 | @file{b~@var{mainprog}.adb} default. Note that @var{file} denote the Ada | |
e1b871e9 | 8749 | binder generated body filename. |
88e1739c FW |
8750 | Note that if this option is used, then linking must be done manually. |
8751 | It is not possible to use gnatlink in this case, since it cannot locate | |
8752 | the binder file. | |
8753 | ||
8754 | @item ^-r^/RESTRICTION_LIST^ | |
7cd4527e AC |
8755 | @cindex @option{^-r^/RESTRICTION_LIST^} (@code{gnatbind}) |
8756 | Generate list of @code{pragma Restrictions} that could be applied to | |
88e1739c FW |
8757 | the current unit. This is useful for code audit purposes, and also may |
8758 | be used to improve code generation in some cases. | |
8759 | ||
8760 | @end table | |
8761 | ||
08564036 AC |
8762 | @node Dynamic Allocation Control |
8763 | @subsection Dynamic Allocation Control | |
8764 | ||
8765 | @noindent | |
8766 | The heap control switches -- @option{-H32} and @option{-H64} -- | |
8767 | determine whether dynamic allocation uses 32-bit or 64-bit memory. | |
8768 | They only affect compiler-generated allocations via @code{__gnat_malloc}; | |
8769 | explicit calls to @code{malloc} and related functions from the C | |
8770 | run-time library are unaffected. | |
8771 | ||
8772 | @table @option | |
8773 | @item -H32 | |
8774 | Allocate memory on 32-bit heap | |
8775 | ||
8776 | @item -H64 | |
8777 | Allocate memory on 64-bit heap. This is the default | |
8778 | unless explicitly overridden by a @code{'Size} clause on the access type. | |
8779 | @end table | |
8780 | ||
8781 | @ifset vms | |
8782 | @noindent | |
8783 | See also @ref{Access types and 32/64-bit allocation}. | |
8784 | @end ifset | |
8785 | @ifclear vms | |
8786 | @noindent | |
8787 | These switches are only effective on VMS platforms. | |
8788 | @end ifclear | |
8789 | ||
8790 | ||
88e1739c | 8791 | @node Binding with Non-Ada Main Programs |
7cd4527e | 8792 | @subsection Binding with Non-Ada Main Programs |
88e1739c FW |
8793 | |
8794 | @noindent | |
8795 | In our description so far we have assumed that the main | |
8796 | program is in Ada, and that the task of the binder is to generate a | |
8797 | corresponding function @code{main} that invokes this Ada main | |
8798 | program. GNAT also supports the building of executable programs where | |
8799 | the main program is not in Ada, but some of the called routines are | |
8800 | written in Ada and compiled using GNAT (@pxref{Mixed Language Programming}). | |
8801 | The following switch is used in this situation: | |
8802 | ||
7cd4527e | 8803 | @table @option |
88e1739c | 8804 | @item ^-n^/NOMAIN^ |
7cd4527e | 8805 | @cindex @option{^-n^/NOMAIN^} (@code{gnatbind}) |
88e1739c FW |
8806 | No main program. The main program is not in Ada. |
8807 | @end table | |
8808 | ||
8809 | @noindent | |
8810 | In this case, most of the functions of the binder are still required, | |
8811 | but instead of generating a main program, the binder generates a file | |
8812 | containing the following callable routines: | |
8813 | ||
8814 | @table @code | |
8815 | @item adainit | |
8816 | @findex adainit | |
8817 | You must call this routine to initialize the Ada part of the program by | |
8818 | calling the necessary elaboration routines. A call to @code{adainit} is | |
8819 | required before the first call to an Ada subprogram. | |
8820 | ||
8821 | Note that it is assumed that the basic execution environment must be setup | |
8822 | to be appropriate for Ada execution at the point where the first Ada | |
8823 | subprogram is called. In particular, if the Ada code will do any | |
8824 | floating-point operations, then the FPU must be setup in an appropriate | |
8825 | manner. For the case of the x86, for example, full precision mode is | |
8826 | required. The procedure GNAT.Float_Control.Reset may be used to ensure | |
8827 | that the FPU is in the right state. | |
8828 | ||
8829 | @item adafinal | |
8830 | @findex adafinal | |
8831 | You must call this routine to perform any library-level finalization | |
8832 | required by the Ada subprograms. A call to @code{adafinal} is required | |
8833 | after the last call to an Ada subprogram, and before the program | |
8834 | terminates. | |
8835 | @end table | |
8836 | ||
8837 | @noindent | |
7cd4527e AC |
8838 | If the @option{^-n^/NOMAIN^} switch |
8839 | @cindex @option{^-n^/NOMAIN^} (@command{gnatbind}) | |
88e1739c FW |
8840 | @cindex Binder, multiple input files |
8841 | is given, more than one ALI file may appear on | |
8842 | the command line for @code{gnatbind}. The normal @dfn{closure} | |
8843 | calculation is performed for each of the specified units. Calculating | |
8844 | the closure means finding out the set of units involved by tracing | |
8845 | @code{with} references. The reason it is necessary to be able to | |
8846 | specify more than one ALI file is that a given program may invoke two or | |
8847 | more quite separate groups of Ada units. | |
8848 | ||
8849 | The binder takes the name of its output file from the last specified ALI | |
7cd4527e AC |
8850 | file, unless overridden by the use of the @option{^-o file^/OUTPUT=file^}. |
8851 | @cindex @option{^-o^/OUTPUT^} (@command{gnatbind}) | |
e1b871e9 | 8852 | The output is an Ada unit in source form that can be compiled with GNAT. |
984a64bc | 8853 | This compilation occurs automatically as part of the @command{gnatlink} |
88e1739c FW |
8854 | processing. |
8855 | ||
8856 | Currently the GNAT run time requires a FPU using 80 bits mode | |
8857 | precision. Under targets where this is not the default it is required to | |
8858 | call GNAT.Float_Control.Reset before using floating point numbers (this | |
8859 | include float computation, float input and output) in the Ada code. A | |
8860 | side effect is that this could be the wrong mode for the foreign code | |
8861 | where floating point computation could be broken after this call. | |
8862 | ||
8863 | @node Binding Programs with No Main Subprogram | |
7cd4527e | 8864 | @subsection Binding Programs with No Main Subprogram |
88e1739c FW |
8865 | |
8866 | @noindent | |
8867 | It is possible to have an Ada program which does not have a main | |
8868 | subprogram. This program will call the elaboration routines of all the | |
8869 | packages, then the finalization routines. | |
8870 | ||
8871 | The following switch is used to bind programs organized in this manner: | |
8872 | ||
7cd4527e | 8873 | @table @option |
88e1739c | 8874 | @item ^-z^/ZERO_MAIN^ |
7cd4527e | 8875 | @cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind}) |
88e1739c FW |
8876 | Normally the binder checks that the unit name given on the command line |
8877 | corresponds to a suitable main subprogram. When this switch is used, | |
8878 | a list of ALI files can be given, and the execution of the program | |
a2ad1f79 RD |
8879 | consists of elaboration of these units in an appropriate order. Note |
8880 | that the default wide character encoding method for standard Text_IO | |
8881 | files is always set to Brackets if this switch is set (you can use | |
8882 | the binder switch | |
8883 | @option{^-Wx^WIDE_CHARACTER_ENCODING^} to override this default). | |
88e1739c FW |
8884 | @end table |
8885 | ||
7cd4527e AC |
8886 | @node Command-Line Access |
8887 | @section Command-Line Access | |
88e1739c FW |
8888 | |
8889 | @noindent | |
7cd4527e AC |
8890 | The package @code{Ada.Command_Line} provides access to the command-line |
8891 | arguments and program name. In order for this interface to operate | |
8892 | correctly, the two variables | |
88e1739c | 8893 | |
7cd4527e AC |
8894 | @smallexample |
8895 | @group | |
8896 | int gnat_argc; | |
8897 | char **gnat_argv; | |
8898 | @end group | |
8899 | @end smallexample | |
88e1739c FW |
8900 | |
8901 | @noindent | |
8902 | @findex gnat_argv | |
8903 | @findex gnat_argc | |
8904 | are declared in one of the GNAT library routines. These variables must | |
8905 | be set from the actual @code{argc} and @code{argv} values passed to the | |
7cd4527e | 8906 | main program. With no @option{^n^/NOMAIN^} present, @code{gnatbind} |
88e1739c | 8907 | generates the C main program to automatically set these variables. |
7cd4527e | 8908 | If the @option{^n^/NOMAIN^} switch is used, there is no automatic way to |
88e1739c FW |
8909 | set these variables. If they are not set, the procedures in |
8910 | @code{Ada.Command_Line} will not be available, and any attempt to use | |
8911 | them will raise @code{Constraint_Error}. If command line access is | |
8912 | required, your main program must set @code{gnat_argc} and | |
8913 | @code{gnat_argv} from the @code{argc} and @code{argv} values passed to | |
8914 | it. | |
8915 | ||
8916 | @node Search Paths for gnatbind | |
8917 | @section Search Paths for @code{gnatbind} | |
8918 | ||
8919 | @noindent | |
8920 | The binder takes the name of an ALI file as its argument and needs to | |
8921 | locate source files as well as other ALI files to verify object consistency. | |
8922 | ||
984a64bc | 8923 | For source files, it follows exactly the same search rules as @command{gcc} |
88e1739c FW |
8924 | (@pxref{Search Paths and the Run-Time Library (RTL)}). For ALI files the |
8925 | directories searched are: | |
8926 | ||
8927 | @enumerate | |
8928 | @item | |
8929 | The directory containing the ALI file named in the command line, unless | |
7cd4527e | 8930 | the switch @option{^-I-^/NOCURRENT_DIRECTORY^} is specified. |
88e1739c FW |
8931 | |
8932 | @item | |
7cd4527e | 8933 | All directories specified by @option{^-I^/SEARCH^} |
88e1739c FW |
8934 | switches on the @code{gnatbind} |
8935 | command line, in the order given. | |
8936 | ||
0453ca3d RD |
8937 | @item |
8938 | @findex ADA_PRJ_OBJECTS_FILE | |
8939 | Each of the directories listed in the text file whose name is given | |
443b3472 | 8940 | by the @env{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^. |
0453ca3d RD |
8941 | |
8942 | @noindent | |
443b3472 | 8943 | @env{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^ |
0453ca3d RD |
8944 | driver when project files are used. It should not normally be set |
8945 | by other means. | |
8946 | ||
88e1739c FW |
8947 | @item |
8948 | @findex ADA_OBJECTS_PATH | |
8949 | Each of the directories listed in the value of the | |
443b3472 | 8950 | @env{ADA_OBJECTS_PATH} ^environment variable^logical name^. |
7cd4527e | 8951 | @ifset unw |
88e1739c | 8952 | Construct this value |
443b3472 | 8953 | exactly as the @env{PATH} environment variable: a list of directory |
88e1739c FW |
8954 | names separated by colons (semicolons when working with the NT version |
8955 | of GNAT). | |
7cd4527e | 8956 | @end ifset |
88e1739c FW |
8957 | @ifset vms |
8958 | Normally, define this value as a logical name containing a comma separated | |
8959 | list of directory names. | |
8960 | ||
8961 | This variable can also be defined by means of an environment string | |
32e209e4 | 8962 | (an argument to the HP C exec* set of functions). |
88e1739c FW |
8963 | |
8964 | Logical Name: | |
8965 | @smallexample | |
8966 | DEFINE ANOTHER_PATH FOO:[BAG] | |
8967 | DEFINE ADA_OBJECTS_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR] | |
8968 | @end smallexample | |
8969 | ||
8970 | By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] | |
e08b38f5 | 8971 | first, followed by the standard Ada |
88e1739c | 8972 | libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB]. |
32e209e4 | 8973 | If this is not redefined, the user will obtain the HP Ada 83 IO packages |
88e1739c | 8974 | (Text_IO, Sequential_IO, etc) |
e08b38f5 | 8975 | instead of the standard Ada packages. Thus, in order to get the standard Ada |
88e1739c FW |
8976 | packages by default, ADA_OBJECTS_PATH must be redefined. |
8977 | @end ifset | |
8978 | ||
7cd4527e AC |
8979 | @item |
8980 | The content of the @file{ada_object_path} file which is part of the GNAT | |
88e1739c | 8981 | installation tree and is used to store standard libraries such as the |
7cd4527e | 8982 | GNAT Run Time Library (RTL) unless the switch @option{-nostdlib} is |
88e1739c FW |
8983 | specified. |
8984 | @ifclear vms | |
87b3f81f | 8985 | @ref{Installing a library} |
88e1739c FW |
8986 | @end ifclear |
8987 | @end enumerate | |
8988 | ||
8989 | @noindent | |
7cd4527e AC |
8990 | In the binder the switch @option{^-I^/SEARCH^} |
8991 | @cindex @option{^-I^/SEARCH^} (@command{gnatbind}) | |
88e1739c | 8992 | is used to specify both source and |
7cd4527e AC |
8993 | library file paths. Use @option{^-aI^/SOURCE_SEARCH^} |
8994 | @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind}) | |
88e1739c | 8995 | instead if you want to specify |
7cd4527e AC |
8996 | source paths only, and @option{^-aO^/LIBRARY_SEARCH^} |
8997 | @cindex @option{^-aO^/LIBRARY_SEARCH^} (@command{gnatbind}) | |
88e1739c FW |
8998 | if you want to specify library paths |
8999 | only. This means that for the binder | |
7cd4527e AC |
9000 | @option{^-I^/SEARCH=^}@var{dir} is equivalent to |
9001 | @option{^-aI^/SOURCE_SEARCH=^}@var{dir} | |
9002 | @option{^-aO^/OBJECT_SEARCH=^}@var{dir}. | |
88e1739c FW |
9003 | The binder generates the bind file (a C language source file) in the |
9004 | current working directory. | |
9005 | ||
9006 | @findex Ada | |
9007 | @findex System | |
9008 | @findex Interfaces | |
9009 | @findex GNAT | |
9010 | The packages @code{Ada}, @code{System}, and @code{Interfaces} and their | |
9011 | children make up the GNAT Run-Time Library, together with the package | |
9012 | GNAT and its children, which contain a set of useful additional | |
9013 | library functions provided by GNAT. The sources for these units are | |
9014 | needed by the compiler and are kept together in one directory. The ALI | |
9015 | files and object files generated by compiling the RTL are needed by the | |
9016 | binder and the linker and are kept together in one directory, typically | |
9017 | different from the directory containing the sources. In a normal | |
9018 | installation, you need not specify these directory names when compiling | |
9019 | or binding. Either the environment variables or the built-in defaults | |
9020 | cause these files to be found. | |
9021 | ||
9022 | Besides simplifying access to the RTL, a major use of search paths is | |
9023 | in compiling sources from multiple directories. This can make | |
9024 | development environments much more flexible. | |
9025 | ||
9026 | @node Examples of gnatbind Usage | |
9027 | @section Examples of @code{gnatbind} Usage | |
9028 | ||
9029 | @noindent | |
9030 | This section contains a number of examples of using the GNAT binding | |
9031 | utility @code{gnatbind}. | |
9032 | ||
9033 | @table @code | |
9034 | @item gnatbind hello | |
9035 | The main program @code{Hello} (source program in @file{hello.adb}) is | |
9036 | bound using the standard switch settings. The generated main program is | |
9037 | @file{b~hello.adb}. This is the normal, default use of the binder. | |
9038 | ||
9039 | @ifclear vms | |
9040 | @item gnatbind hello -o mainprog.adb | |
9041 | @end ifclear | |
9042 | @ifset vms | |
9043 | @item gnatbind HELLO.ALI /OUTPUT=Mainprog.ADB | |
9044 | @end ifset | |
9045 | The main program @code{Hello} (source program in @file{hello.adb}) is | |
9046 | bound using the standard switch settings. The generated main program is | |
9047 | @file{mainprog.adb} with the associated spec in | |
9048 | @file{mainprog.ads}. Note that you must specify the body here not the | |
e1b871e9 AC |
9049 | spec. Note that if this option is used, then linking must be done manually, |
9050 | since gnatlink will not be able to find the generated file. | |
88e1739c FW |
9051 | @end table |
9052 | ||
7cd4527e | 9053 | @c ------------------------------------ |
c2658843 AC |
9054 | @node Linking with gnatlink |
9055 | @chapter Linking with @command{gnatlink} | |
7cd4527e | 9056 | @c ------------------------------------ |
88e1739c FW |
9057 | @findex gnatlink |
9058 | ||
9059 | @noindent | |
984a64bc | 9060 | This chapter discusses @command{gnatlink}, a tool that links |
7cd4527e | 9061 | an Ada program and builds an executable file. This utility |
984a64bc | 9062 | invokes the system linker ^(via the @command{gcc} command)^^ |
7cd4527e | 9063 | with a correct list of object files and library references. |
984a64bc | 9064 | @command{gnatlink} automatically determines the list of files and |
88e1739c | 9065 | references for the Ada part of a program. It uses the binder file |
7cd4527e | 9066 | generated by the @command{gnatbind} to determine this list. |
88e1739c | 9067 | |
e08b38f5 VC |
9068 | Note: to invoke @code{gnatlink} with a project file, use the @code{gnat} |
9069 | driver (see @ref{The GNAT Driver and Project Files}). | |
9070 | ||
88e1739c FW |
9071 | @menu |
9072 | * Running gnatlink:: | |
9073 | * Switches for gnatlink:: | |
88e1739c FW |
9074 | @end menu |
9075 | ||
9076 | @node Running gnatlink | |
984a64bc | 9077 | @section Running @command{gnatlink} |
88e1739c FW |
9078 | |
9079 | @noindent | |
984a64bc | 9080 | The form of the @command{gnatlink} command is |
88e1739c FW |
9081 | |
9082 | @smallexample | |
e074d476 AC |
9083 | @c $ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]} |
9084 | @c @ovar{non-Ada objects} @ovar{linker options} | |
9085 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
9086 | $ gnatlink @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]} | |
9087 | @r{[}@var{non-Ada objects}@r{]} @r{[}@var{linker options}@r{]} | |
9088 | ||
88e1739c FW |
9089 | @end smallexample |
9090 | ||
7cd4527e | 9091 | @noindent |
984a64bc | 9092 | The arguments of @command{gnatlink} (switches, main @file{ALI} file, |
7cd4527e AC |
9093 | non-Ada objects |
9094 | or linker options) may be in any order, provided that no non-Ada object may | |
9095 | be mistaken for a main @file{ALI} file. | |
9096 | Any file name @file{F} without the @file{.ali} | |
9097 | extension will be taken as the main @file{ALI} file if a file exists | |
9098 | whose name is the concatenation of @file{F} and @file{.ali}. | |
9099 | ||
88e1739c FW |
9100 | @noindent |
9101 | @file{@var{mainprog}.ali} references the ALI file of the main program. | |
9102 | The @file{.ali} extension of this file can be omitted. From this | |
984a64bc | 9103 | reference, @command{gnatlink} locates the corresponding binder file |
88e1739c | 9104 | @file{b~@var{mainprog}.adb} and, using the information in this file along |
7cd4527e | 9105 | with the list of non-Ada objects and linker options, constructs a |
88e1739c FW |
9106 | linker command file to create the executable. |
9107 | ||
984a64bc AC |
9108 | The arguments other than the @command{gnatlink} switches and the main |
9109 | @file{ALI} file are passed to the linker uninterpreted. | |
7cd4527e AC |
9110 | They typically include the names of |
9111 | object files for units written in other languages than Ada and any library | |
9112 | references required to resolve references in any of these foreign language | |
9113 | units, or in @code{Import} pragmas in any Ada units. | |
88e1739c FW |
9114 | |
9115 | @var{linker options} is an optional list of linker specific | |
7cd4527e | 9116 | switches. |
1992bbd9 | 9117 | The default linker called by gnatlink is @command{gcc} which in |
7cd4527e | 9118 | turn calls the appropriate system linker. |
7675ad4f AC |
9119 | |
9120 | One useful option for the linker is @option{-s}: it reduces the size of the | |
9121 | executable by removing all symbol table and relocation information from the | |
9122 | executable. | |
9123 | ||
7cd4527e AC |
9124 | Standard options for the linker such as @option{-lmy_lib} or |
9125 | @option{-Ldir} can be added as is. | |
9126 | For options that are not recognized by | |
1992bbd9 RW |
9127 | @command{gcc} as linker options, use the @command{gcc} switches |
9128 | @option{-Xlinker} or @option{-Wl,}. | |
7675ad4f | 9129 | |
7cd4527e | 9130 | Refer to the GCC documentation for |
7675ad4f AC |
9131 | details. |
9132 | ||
9133 | Here is an example showing how to generate a linker map: | |
88e1739c FW |
9134 | |
9135 | @smallexample | |
7e3d710b | 9136 | $ ^gnatlink my_prog -Wl,-Map,MAPFILE^GNAT LINK my_prog.ali /MAP^ |
88e1739c FW |
9137 | @end smallexample |
9138 | ||
9139 | Using @var{linker options} it is possible to set the program stack and | |
7e3d710b | 9140 | heap size. |
1a5f40e1 | 9141 | @ifset unw |
7e3d710b | 9142 | See @ref{Setting Stack Size from gnatlink} and |
7cd4527e | 9143 | @ref{Setting Heap Size from gnatlink}. |
1a5f40e1 | 9144 | @end ifset |
88e1739c | 9145 | |
984a64bc | 9146 | @command{gnatlink} determines the list of objects required by the Ada |
88e1739c | 9147 | program and prepends them to the list of objects passed to the linker. |
984a64bc | 9148 | @command{gnatlink} also gathers any arguments set by the use of |
88e1739c FW |
9149 | @code{pragma Linker_Options} and adds them to the list of arguments |
9150 | presented to the linker. | |
9151 | ||
9152 | @ifset vms | |
984a64bc | 9153 | @command{gnatlink} accepts the following types of extra files on the command |
443b3472 RW |
9154 | line: objects (@file{.OBJ}), libraries (@file{.OLB}), sharable images |
9155 | (@file{.EXE}), and options files (@file{.OPT}). These are recognized and | |
9156 | handled according to their extension. | |
88e1739c FW |
9157 | @end ifset |
9158 | ||
9159 | @node Switches for gnatlink | |
984a64bc | 9160 | @section Switches for @command{gnatlink} |
88e1739c FW |
9161 | |
9162 | @noindent | |
984a64bc | 9163 | The following switches are available with the @command{gnatlink} utility: |
88e1739c | 9164 | |
7cd4527e AC |
9165 | @table @option |
9166 | @c !sort! | |
88e1739c | 9167 | |
54df6fd9 VC |
9168 | @item --version |
9169 | @cindex @option{--version} @command{gnatlink} | |
9170 | Display Copyright and version, then exit disregarding all other options. | |
9171 | ||
9172 | @item --help | |
9173 | @cindex @option{--help} @command{gnatlink} | |
9174 | If @option{--version} was not used, display usage, then exit disregarding | |
9175 | all other options. | |
9176 | ||
7cd4527e | 9177 | @item ^-f^/FORCE_OBJECT_FILE_LIST^ |
88e1739c | 9178 | @cindex Command line length |
984a64bc AC |
9179 | @cindex @option{^-f^/FORCE_OBJECT_FILE_LIST^} (@command{gnatlink}) |
9180 | On some targets, the command line length is limited, and @command{gnatlink} | |
88e1739c | 9181 | will generate a separate file for the linker if the list of object files |
7cd4527e AC |
9182 | is too long. |
9183 | The @option{^-f^/FORCE_OBJECT_FILE_LIST^} switch forces this file | |
9184 | to be generated even if | |
88e1739c FW |
9185 | the limit is not exceeded. This is useful in some cases to deal with |
9186 | special situations where the command line length is exceeded. | |
9187 | ||
9188 | @item ^-g^/DEBUG^ | |
9189 | @cindex Debugging information, including | |
984a64bc | 9190 | @cindex @option{^-g^/DEBUG^} (@command{gnatlink}) |
88e1739c FW |
9191 | The option to include debugging information causes the Ada bind file (in |
9192 | other words, @file{b~@var{mainprog}.adb}) to be compiled with | |
7cd4527e | 9193 | @option{^-g^/DEBUG^}. |
88e1739c FW |
9194 | In addition, the binder does not delete the @file{b~@var{mainprog}.adb}, |
9195 | @file{b~@var{mainprog}.o} and @file{b~@var{mainprog}.ali} files. | |
7cd4527e | 9196 | Without @option{^-g^/DEBUG^}, the binder removes these files by |
88e1739c | 9197 | default. The same procedure apply if a C bind file was generated using |
7cd4527e AC |
9198 | @option{^-C^/BIND_FILE=C^} @code{gnatbind} option, in this case the filenames |
9199 | are @file{b_@var{mainprog}.c} and @file{b_@var{mainprog}.o}. | |
88e1739c | 9200 | |
7cd4527e | 9201 | @item ^-n^/NOCOMPILE^ |
984a64bc | 9202 | @cindex @option{^-n^/NOCOMPILE^} (@command{gnatlink}) |
88e1739c FW |
9203 | Do not compile the file generated by the binder. This may be used when |
9204 | a link is rerun with different options, but there is no need to recompile | |
9205 | the binder file. | |
88e1739c FW |
9206 | |
9207 | @item ^-v^/VERBOSE^ | |
984a64bc | 9208 | @cindex @option{^-v^/VERBOSE^} (@command{gnatlink}) |
88e1739c FW |
9209 | Causes additional information to be output, including a full list of the |
9210 | included object files. This switch option is most useful when you want | |
9211 | to see what set of object files are being used in the link step. | |
9212 | ||
7cd4527e | 9213 | @item ^-v -v^/VERBOSE/VERBOSE^ |
984a64bc | 9214 | @cindex @option{^-v -v^/VERBOSE/VERBOSE^} (@command{gnatlink}) |
88e1739c FW |
9215 | Very verbose mode. Requests that the compiler operate in verbose mode when |
9216 | it compiles the binder file, and that the system linker run in verbose mode. | |
88e1739c FW |
9217 | |
9218 | @item ^-o ^/EXECUTABLE=^@var{exec-name} | |
984a64bc | 9219 | @cindex @option{^-o^/EXECUTABLE^} (@command{gnatlink}) |
88e1739c FW |
9220 | @var{exec-name} specifies an alternate name for the generated |
9221 | executable program. If this switch is omitted, the executable has the same | |
9222 | name as the main unit. For example, @code{gnatlink try.ali} creates | |
9223 | an executable called @file{^try^TRY.EXE^}. | |
9224 | ||
9225 | @ifclear vms | |
9226 | @item -b @var{target} | |
984a64bc | 9227 | @cindex @option{-b} (@command{gnatlink}) |
88e1739c FW |
9228 | Compile your program to run on @var{target}, which is the name of a |
9229 | system configuration. You must have a GNAT cross-compiler built if | |
9230 | @var{target} is not the same as your host system. | |
9231 | ||
9232 | @item -B@var{dir} | |
984a64bc | 9233 | @cindex @option{-B} (@command{gnatlink}) |
88e1739c FW |
9234 | Load compiler executables (for example, @code{gnat1}, the Ada compiler) |
9235 | from @var{dir} instead of the default location. Only use this switch | |
b2e74434 RW |
9236 | when multiple versions of the GNAT compiler are available. |
9237 | @xref{Directory Options,,, gcc, The GNU Compiler Collection}, | |
9238 | for further details. You would normally use the @option{-b} or | |
9239 | @option{-V} switch instead. | |
88e1739c | 9240 | |
f5fc5b9d AC |
9241 | @item -M |
9242 | When linking an executable, create a map file. The name of the map file | |
9243 | has the same name as the executable with extension ".map". | |
9244 | ||
9245 | @item -M=mapfile | |
9246 | When linking an executable, create a map file. The name of the map file is | |
9247 | "mapfile". | |
9248 | ||
88e1739c | 9249 | @item --GCC=@var{compiler_name} |
984a64bc | 9250 | @cindex @option{--GCC=compiler_name} (@command{gnatlink}) |
88e1739c | 9251 | Program used for compiling the binder file. The default is |
984a64bc | 9252 | @command{gcc}. You need to use quotes around @var{compiler_name} if |
32e209e4 CC |
9253 | @code{compiler_name} contains spaces or other separator characters. |
9254 | As an example @option{--GCC="foo -x -y"} will instruct @command{gnatlink} to | |
9255 | use @code{foo -x -y} as your compiler. Note that switch @option{-c} is always | |
88e1739c | 9256 | inserted after your command name. Thus in the above example the compiler |
984a64bc | 9257 | command that will be used by @command{gnatlink} will be @code{foo -c -x -y}. |
32e209e4 | 9258 | A limitation of this syntax is that the name and path name of the executable |
d313a1b6 VC |
9259 | itself must not include any embedded spaces. If the compiler executable is |
9260 | different from the default one (gcc or <prefix>-gcc), then the back-end | |
9261 | switches in the ALI file are not used to compile the binder generated source. | |
9262 | For example, this is the case with @option{--GCC="foo -x -y"}. But the back end | |
9263 | switches will be used for @option{--GCC="gcc -gnatv"}. If several | |
32e209e4 CC |
9264 | @option{--GCC=compiler_name} are used, only the last @var{compiler_name} |
9265 | is taken into account. However, all the additional switches are also taken | |
9266 | into account. Thus, | |
7cd4527e AC |
9267 | @option{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to |
9268 | @option{--GCC="bar -x -y -z -t"}. | |
88e1739c FW |
9269 | |
9270 | @item --LINK=@var{name} | |
984a64bc | 9271 | @cindex @option{--LINK=} (@command{gnatlink}) |
88e1739c | 9272 | @var{name} is the name of the linker to be invoked. This is especially |
7cd4527e | 9273 | useful in mixed language programs since languages such as C++ require |
88e1739c | 9274 | their own linker to be used. When this switch is omitted, the default |
984a64bc AC |
9275 | name for the linker is @command{gcc}. When this switch is used, the |
9276 | specified linker is called instead of @command{gcc} with exactly the same | |
9277 | parameters that would have been passed to @command{gcc} so if the desired | |
88e1739c FW |
9278 | linker requires different parameters it is necessary to use a wrapper |
9279 | script that massages the parameters before invoking the real linker. It | |
9280 | may be useful to control the exact invocation by using the verbose | |
9281 | switch. | |
9282 | ||
9283 | @end ifclear | |
9284 | ||
9285 | @ifset vms | |
9286 | @item /DEBUG=TRACEBACK | |
984a64bc | 9287 | @cindex @code{/DEBUG=TRACEBACK} (@command{gnatlink}) |
88e1739c FW |
9288 | This qualifier causes sufficient information to be included in the |
9289 | executable file to allow a traceback, but does not include the full | |
9290 | symbol information needed by the debugger. | |
9291 | ||
9292 | @item /IDENTIFICATION="<string>" | |
7cd4527e AC |
9293 | @code{"<string>"} specifies the string to be stored in the image file |
9294 | identification field in the image header. | |
9295 | It overrides any pragma @code{Ident} specified string. | |
88e1739c FW |
9296 | |
9297 | @item /NOINHIBIT-EXEC | |
9298 | Generate the executable file even if there are linker warnings. | |
9299 | ||
9300 | @item /NOSTART_FILES | |
7cd4527e | 9301 | Don't link in the object file containing the ``main'' transfer address. |
32e209e4 CC |
9302 | Used when linking with a foreign language main program compiled with an |
9303 | HP compiler. | |
88e1739c FW |
9304 | |
9305 | @item /STATIC | |
7cd4527e | 9306 | Prefer linking with object libraries over sharable images, even without |
88e1739c FW |
9307 | /DEBUG. |
9308 | @end ifset | |
9309 | ||
9310 | @end table | |
9311 | ||
88e1739c | 9312 | @node The GNAT Make Program gnatmake |
984a64bc | 9313 | @chapter The GNAT Make Program @command{gnatmake} |
88e1739c FW |
9314 | @findex gnatmake |
9315 | ||
9316 | @menu | |
9317 | * Running gnatmake:: | |
9318 | * Switches for gnatmake:: | |
9319 | * Mode Switches for gnatmake:: | |
9320 | * Notes on the Command Line:: | |
9321 | * How gnatmake Works:: | |
9322 | * Examples of gnatmake Usage:: | |
9323 | @end menu | |
9324 | @noindent | |
9325 | A typical development cycle when working on an Ada program consists of | |
9326 | the following steps: | |
9327 | ||
9328 | @enumerate | |
9329 | @item | |
9330 | Edit some sources to fix bugs. | |
9331 | ||
9332 | @item | |
9333 | Add enhancements. | |
9334 | ||
9335 | @item | |
9336 | Compile all sources affected. | |
9337 | ||
9338 | @item | |
9339 | Rebind and relink. | |
9340 | ||
9341 | @item | |
9342 | Test. | |
9343 | @end enumerate | |
9344 | ||
9345 | @noindent | |
9346 | The third step can be tricky, because not only do the modified files | |
9347 | @cindex Dependency rules | |
9348 | have to be compiled, but any files depending on these files must also be | |
9349 | recompiled. The dependency rules in Ada can be quite complex, especially | |
9350 | in the presence of overloading, @code{use} clauses, generics and inlined | |
9351 | subprograms. | |
9352 | ||
984a64bc | 9353 | @command{gnatmake} automatically takes care of the third and fourth steps |
88e1739c FW |
9354 | of this process. It determines which sources need to be compiled, |
9355 | compiles them, and binds and links the resulting object files. | |
9356 | ||
9357 | Unlike some other Ada make programs, the dependencies are always | |
9358 | accurately recomputed from the new sources. The source based approach of | |
9359 | the GNAT compilation model makes this possible. This means that if | |
9360 | changes to the source program cause corresponding changes in | |
9361 | dependencies, they will always be tracked exactly correctly by | |
984a64bc | 9362 | @command{gnatmake}. |
88e1739c FW |
9363 | |
9364 | @node Running gnatmake | |
984a64bc | 9365 | @section Running @command{gnatmake} |
88e1739c FW |
9366 | |
9367 | @noindent | |
984a64bc | 9368 | The usual form of the @command{gnatmake} command is |
88e1739c FW |
9369 | |
9370 | @smallexample | |
e074d476 AC |
9371 | @c $ gnatmake @ovar{switches} @var{file_name} |
9372 | @c @ovar{file_names} @ovar{mode_switches} | |
9373 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
9374 | $ gnatmake @r{[}@var{switches}@r{]} @var{file_name} | |
9375 | @r{[}@var{file_names}@r{]} @r{[}@var{mode_switches}@r{]} | |
88e1739c FW |
9376 | @end smallexample |
9377 | ||
9378 | @noindent | |
9379 | The only required argument is one @var{file_name}, which specifies | |
9380 | a compilation unit that is a main program. Several @var{file_names} can be | |
9381 | specified: this will result in several executables being built. | |
9382 | If @code{switches} are present, they can be placed before the first | |
9383 | @var{file_name}, between @var{file_names} or after the last @var{file_name}. | |
9384 | If @var{mode_switches} are present, they must always be placed after | |
9385 | the last @var{file_name} and all @code{switches}. | |
9386 | ||
443b3472 | 9387 | If you are using standard file extensions (@file{.adb} and @file{.ads}), then the |
88e1739c FW |
9388 | extension may be omitted from the @var{file_name} arguments. However, if |
9389 | you are using non-standard extensions, then it is required that the | |
9390 | extension be given. A relative or absolute directory path can be | |
9391 | specified in a @var{file_name}, in which case, the input source file will | |
9392 | be searched for in the specified directory only. Otherwise, the input | |
9393 | source file will first be searched in the directory where | |
984a64bc | 9394 | @command{gnatmake} was invoked and if it is not found, it will be search on |
88e1739c FW |
9395 | the source path of the compiler as described in |
9396 | @ref{Search Paths and the Run-Time Library (RTL)}. | |
9397 | ||
984a64bc | 9398 | All @command{gnatmake} output (except when you specify |
7cd4527e | 9399 | @option{^-M^/DEPENDENCIES_LIST^}) is to |
88e1739c | 9400 | @file{stderr}. The output produced by the |
7cd4527e | 9401 | @option{^-M^/DEPENDENCIES_LIST^} switch is send to |
88e1739c FW |
9402 | @file{stdout}. |
9403 | ||
9404 | @node Switches for gnatmake | |
984a64bc | 9405 | @section Switches for @command{gnatmake} |
88e1739c FW |
9406 | |
9407 | @noindent | |
984a64bc | 9408 | You may specify any of the following switches to @command{gnatmake}: |
88e1739c | 9409 | |
7cd4527e AC |
9410 | @table @option |
9411 | @c !sort! | |
54df6fd9 VC |
9412 | |
9413 | @item --version | |
9414 | @cindex @option{--version} @command{gnatmake} | |
9415 | Display Copyright and version, then exit disregarding all other options. | |
9416 | ||
9417 | @item --help | |
9418 | @cindex @option{--help} @command{gnatmake} | |
9419 | If @option{--version} was not used, display usage, then exit disregarding | |
9420 | all other options. | |
9421 | ||
88e1739c FW |
9422 | @ifclear vms |
9423 | @item --GCC=@var{compiler_name} | |
984a64bc AC |
9424 | @cindex @option{--GCC=compiler_name} (@command{gnatmake}) |
9425 | Program used for compiling. The default is `@command{gcc}'. You need to use | |
88e1739c | 9426 | quotes around @var{compiler_name} if @code{compiler_name} contains |
7cd4527e | 9427 | spaces or other separator characters. As an example @option{--GCC="foo -x |
984a64bc | 9428 | -y"} will instruct @command{gnatmake} to use @code{foo -x -y} as your |
32e209e4 CC |
9429 | compiler. A limitation of this syntax is that the name and path name of |
9430 | the executable itself must not include any embedded spaces. Note that | |
9431 | switch @option{-c} is always inserted after your command name. Thus in the | |
9432 | above example the compiler command that will be used by @command{gnatmake} | |
9433 | will be @code{foo -c -x -y}. If several @option{--GCC=compiler_name} are | |
9434 | used, only the last @var{compiler_name} is taken into account. However, | |
9435 | all the additional switches are also taken into account. Thus, | |
7cd4527e AC |
9436 | @option{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to |
9437 | @option{--GCC="bar -x -y -z -t"}. | |
88e1739c FW |
9438 | |
9439 | @item --GNATBIND=@var{binder_name} | |
984a64bc | 9440 | @cindex @option{--GNATBIND=binder_name} (@command{gnatmake}) |
88e1739c FW |
9441 | Program used for binding. The default is `@code{gnatbind}'. You need to |
9442 | use quotes around @var{binder_name} if @var{binder_name} contains spaces | |
7cd4527e | 9443 | or other separator characters. As an example @option{--GNATBIND="bar -x |
984a64bc | 9444 | -y"} will instruct @command{gnatmake} to use @code{bar -x -y} as your |
32e209e4 CC |
9445 | binder. Binder switches that are normally appended by @command{gnatmake} |
9446 | to `@code{gnatbind}' are now appended to the end of @code{bar -x -y}. | |
9447 | A limitation of this syntax is that the name and path name of the executable | |
9448 | itself must not include any embedded spaces. | |
88e1739c FW |
9449 | |
9450 | @item --GNATLINK=@var{linker_name} | |
984a64bc AC |
9451 | @cindex @option{--GNATLINK=linker_name} (@command{gnatmake}) |
9452 | Program used for linking. The default is `@command{gnatlink}'. You need to | |
88e1739c | 9453 | use quotes around @var{linker_name} if @var{linker_name} contains spaces |
7cd4527e | 9454 | or other separator characters. As an example @option{--GNATLINK="lan -x |
984a64bc AC |
9455 | -y"} will instruct @command{gnatmake} to use @code{lan -x -y} as your |
9456 | linker. Linker switches that are normally appended by @command{gnatmake} to | |
9457 | `@command{gnatlink}' are now appended to the end of @code{lan -x -y}. | |
32e209e4 CC |
9458 | A limitation of this syntax is that the name and path name of the executable |
9459 | itself must not include any embedded spaces. | |
88e1739c FW |
9460 | |
9461 | @end ifclear | |
9462 | ||
eeb41f01 VC |
9463 | @item ^--subdirs^/SUBDIRS^=subdir |
9464 | Actual object directory of each project file is the subdirectory subdir of the | |
02954c25 AC |
9465 | object directory specified or defaulted in the project file. |
9466 | ||
9467 | @item ^--single-compile-per-obj-dir^/SINGLE_COMPILE_PER_OBJ_DIR^ | |
9468 | Disallow simultaneous compilations in the same object directory when | |
9469 | project files are used. | |
eeb41f01 VC |
9470 | |
9471 | @item ^--unchecked-shared-lib-imports^/UNCHECKED_SHARED_LIB_IMPORTS^ | |
9472 | By default, shared library projects are not allowed to import static library | |
9473 | projects. When this switch is used on the command line, this restriction is | |
9474 | relaxed. | |
9475 | ||
610ef7c0 VC |
9476 | @item ^--source-info=<source info file>^/SRC_INFO=source-info-file^ |
9477 | Specify a source info file. This switch is active only when project files | |
9478 | are used. If the source info file is specified as a relative path, then it is | |
9479 | relative to the object directory of the main project. If the source info file | |
9480 | does not exist, then after the Project Manager has successfully parsed and | |
9481 | processed the project files and found the sources, it creates the source info | |
9482 | file. If the source info file already exists and can be read successfully, | |
9483 | then the Project Manager will get all the needed information about the sources | |
9484 | from the source info file and will not look for them. This reduces the time | |
9485 | to process the project files, especially when looking for sources that take a | |
9486 | long time. If the source info file exists but cannot be parsed successfully, | |
9487 | the Project Manager will attempt to recreate it. If the Project Manager fails | |
9488 | to create the source info file, a message is issued, but gnatmake does not | |
6a2e5d0f AC |
9489 | fail. @command{gnatmake} "trusts" the source info file. This means that |
9490 | if the source files have changed (addition, deletion, moving to a different | |
9491 | source directory), then the source info file need to be deleted and recreated. | |
610ef7c0 | 9492 | |
aa0df10b VC |
9493 | @ifclear vms |
9494 | @item --create-map-file | |
9495 | When linking an executable, create a map file. The name of the map file | |
9496 | has the same name as the executable with extension ".map". | |
9497 | ||
9498 | @item --create-map-file=mapfile | |
9499 | When linking an executable, create a map file. The name of the map file is | |
9500 | "mapfile". | |
9501 | ||
9502 | @end ifclear | |
9503 | ||
88e1739c | 9504 | @item ^-a^/ALL_FILES^ |
984a64bc | 9505 | @cindex @option{^-a^/ALL_FILES^} (@command{gnatmake}) |
88e1739c FW |
9506 | Consider all files in the make process, even the GNAT internal system |
9507 | files (for example, the predefined Ada library files), as well as any | |
9508 | locked files. Locked files are files whose ALI file is write-protected. | |
9509 | By default, | |
984a64bc | 9510 | @command{gnatmake} does not check these files, |
88e1739c FW |
9511 | because the assumption is that the GNAT internal files are properly up |
9512 | to date, and also that any write protected ALI files have been properly | |
9513 | installed. Note that if there is an installation problem, such that one | |
9514 | of these files is not up to date, it will be properly caught by the | |
9515 | binder. | |
9516 | You may have to specify this switch if you are working on GNAT | |
7cd4527e AC |
9517 | itself. The switch @option{^-a^/ALL_FILES^} is also useful |
9518 | in conjunction with @option{^-f^/FORCE_COMPILE^} | |
88e1739c | 9519 | if you need to recompile an entire application, |
7cd4527e AC |
9520 | including run-time files, using special configuration pragmas, |
9521 | such as a @code{Normalize_Scalars} pragma. | |
9522 | ||
88e1739c FW |
9523 | By default |
9524 | @code{gnatmake ^-a^/ALL_FILES^} compiles all GNAT | |
9525 | internal files with | |
9526 | @ifclear vms | |
9527 | @code{gcc -c -gnatpg} rather than @code{gcc -c}. | |
9528 | @end ifclear | |
9529 | @ifset vms | |
9530 | the @code{/CHECKS=SUPPRESS_ALL /STYLE_CHECKS=GNAT} switch. | |
9531 | @end ifset | |
9532 | ||
9533 | @item ^-b^/ACTIONS=BIND^ | |
984a64bc | 9534 | @cindex @option{^-b^/ACTIONS=BIND^} (@command{gnatmake}) |
7cd4527e AC |
9535 | Bind only. Can be combined with @option{^-c^/ACTIONS=COMPILE^} to do |
9536 | compilation and binding, but no link. | |
9537 | Can be combined with @option{^-l^/ACTIONS=LINK^} | |
9538 | to do binding and linking. When not combined with | |
9539 | @option{^-c^/ACTIONS=COMPILE^} | |
88e1739c FW |
9540 | all the units in the closure of the main program must have been previously |
9541 | compiled and must be up to date. The root unit specified by @var{file_name} | |
9542 | may be given without extension, with the source extension or, if no GNAT | |
9543 | Project File is specified, with the ALI file extension. | |
9544 | ||
9545 | @item ^-c^/ACTIONS=COMPILE^ | |
984a64bc | 9546 | @cindex @option{^-c^/ACTIONS=COMPILE^} (@command{gnatmake}) |
7cd4527e | 9547 | Compile only. Do not perform binding, except when @option{^-b^/ACTIONS=BIND^} |
88e1739c | 9548 | is also specified. Do not perform linking, except if both |
7cd4527e | 9549 | @option{^-b^/ACTIONS=BIND^} and |
6ccde948 | 9550 | @option{^-l^/ACTIONS=LINK^} are also specified. |
88e1739c | 9551 | If the root unit specified by @var{file_name} is not a main unit, this is the |
984a64bc | 9552 | default. Otherwise @command{gnatmake} will attempt binding and linking |
88e1739c FW |
9553 | unless all objects are up to date and the executable is more recent than |
9554 | the objects. | |
9555 | ||
9556 | @item ^-C^/MAPPING^ | |
984a64bc | 9557 | @cindex @option{^-C^/MAPPING^} (@command{gnatmake}) |
6465b6a7 AC |
9558 | Use a temporary mapping file. A mapping file is a way to communicate |
9559 | to the compiler two mappings: from unit names to file names (without | |
9560 | any directory information) and from file names to path names (with | |
9561 | full directory information). A mapping file can make the compiler's | |
9562 | file searches faster, especially if there are many source directories, | |
9563 | or the sources are read over a slow network connection. If | |
9564 | @option{^-P^/PROJECT_FILE^} is used, a mapping file is always used, so | |
9565 | @option{^-C^/MAPPING^} is unnecessary; in this case the mapping file | |
9566 | is initially populated based on the project file. If | |
9567 | @option{^-C^/MAPPING^} is used without | |
9568 | @option{^-P^/PROJECT_FILE^}, | |
9569 | the mapping file is initially empty. Each invocation of the compiler | |
9570 | will add any newly accessed sources to the mapping file. | |
7cd4527e AC |
9571 | |
9572 | @item ^-C=^/USE_MAPPING_FILE=^@var{file} | |
984a64bc | 9573 | @cindex @option{^-C=^/USE_MAPPING^} (@command{gnatmake}) |
7cd4527e AC |
9574 | Use a specific mapping file. The file, specified as a path name (absolute or |
9575 | relative) by this switch, should already exist, otherwise the switch is | |
9576 | ineffective. The specified mapping file will be communicated to the compiler. | |
9577 | This switch is not compatible with a project file | |
9578 | (^-P^/PROJECT_FILE=^@var{file}) or with multiple compiling processes | |
9579 | (^-j^/PROCESSES=^nnn, when nnn is greater than 1). | |
9580 | ||
8436e37c RD |
9581 | @item ^-d^/DISPLAY_PROGRESS^ |
9582 | @cindex @option{^-d^/DISPLAY_PROGRESS^} (@command{gnatmake}) | |
9583 | Display progress for each source, up to date or not, as a single line | |
9584 | ||
6ccde948 RW |
9585 | @smallexample |
9586 | completed x out of y (zz%) | |
9587 | @end smallexample | |
8436e37c RD |
9588 | |
9589 | If the file needs to be compiled this is displayed after the invocation of | |
9590 | the compiler. These lines are displayed even in quiet output mode. | |
9591 | ||
7cd4527e | 9592 | @item ^-D ^/DIRECTORY_OBJECTS=^@var{dir} |
984a64bc | 9593 | @cindex @option{^-D^/DIRECTORY_OBJECTS^} (@command{gnatmake}) |
7cd4527e AC |
9594 | Put all object files and ALI file in directory @var{dir}. |
9595 | If the @option{^-D^/DIRECTORY_OBJECTS^} switch is not used, all object files | |
9596 | and ALI files go in the current working directory. | |
9597 | ||
9598 | This switch cannot be used when using a project file. | |
88e1739c | 9599 | |
97ed5872 AC |
9600 | @item -eInnn |
9601 | @cindex @option{-eI} (@command{gnatmake}) | |
9602 | Indicates that the main source is a multi-unit source and the rank of the unit | |
9603 | in the source file is nnn. nnn needs to be a positive number and a valid | |
9604 | index in the source. This switch cannot be used when @command{gnatmake} is | |
9605 | invoked for several mains. | |
9606 | ||
cc4f0de1 AC |
9607 | @ifclear vms |
9608 | @item -eL | |
984a64bc | 9609 | @cindex @option{-eL} (@command{gnatmake}) |
c3ed1992 | 9610 | @cindex symbolic links |
cc4f0de1 | 9611 | Follow all symbolic links when processing project files. |
c3ed1992 AC |
9612 | This should be used if your project uses symbolic links for files or |
9613 | directories, but is not needed in other cases. | |
9614 | ||
9615 | @cindex naming scheme | |
9616 | This also assumes that no directory matches the naming scheme for files (for | |
9617 | instance that you do not have a directory called "sources.ads" when using the | |
9618 | default GNAT naming scheme). | |
9619 | ||
308e6f3a | 9620 | When you do not have to use this switch (i.e.@: by default), gnatmake is able to |
c3ed1992 AC |
9621 | save a lot of system calls (several per source file and object file), which |
9622 | can result in a significant speed up to load and manipulate a project file, | |
9623 | especially when using source files from a remote system. | |
9624 | ||
cc4f0de1 AC |
9625 | @end ifclear |
9626 | ||
0916df6a RD |
9627 | @item ^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^ |
9628 | @cindex @option{^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^} (@command{gnatmake}) | |
9629 | Output the commands for the compiler, the binder and the linker | |
9630 | on ^standard output^SYS$OUTPUT^, | |
9631 | instead of ^standard error^SYS$ERROR^. | |
9632 | ||
88e1739c | 9633 | @item ^-f^/FORCE_COMPILE^ |
984a64bc | 9634 | @cindex @option{^-f^/FORCE_COMPILE^} (@command{gnatmake}) |
88e1739c FW |
9635 | Force recompilations. Recompile all sources, even though some object |
9636 | files may be up to date, but don't recompile predefined or GNAT internal | |
9637 | files or locked files (files with a write-protected ALI file), | |
7cd4527e AC |
9638 | unless the @option{^-a^/ALL_FILES^} switch is also specified. |
9639 | ||
9640 | @item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^ | |
984a64bc | 9641 | @cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@command{gnatmake}) |
7cd4527e AC |
9642 | When using project files, if some errors or warnings are detected during |
9643 | parsing and verbose mode is not in effect (no use of switch | |
9644 | ^-v^/VERBOSE^), then error lines start with the full path name of the project | |
9645 | file, rather than its simple file name. | |
88e1739c | 9646 | |
e08b38f5 VC |
9647 | @item ^-g^/DEBUG^ |
9648 | @cindex @option{^-g^/DEBUG^} (@command{gnatmake}) | |
9649 | Enable debugging. This switch is simply passed to the compiler and to the | |
9650 | linker. | |
9651 | ||
88e1739c | 9652 | @item ^-i^/IN_PLACE^ |
984a64bc AC |
9653 | @cindex @option{^-i^/IN_PLACE^} (@command{gnatmake}) |
9654 | In normal mode, @command{gnatmake} compiles all object files and ALI files | |
7cd4527e | 9655 | into the current directory. If the @option{^-i^/IN_PLACE^} switch is used, |
88e1739c FW |
9656 | then instead object files and ALI files that already exist are overwritten |
9657 | in place. This means that once a large project is organized into separate | |
984a64bc | 9658 | directories in the desired manner, then @command{gnatmake} will automatically |
88e1739c FW |
9659 | maintain and update this organization. If no ALI files are found on the |
9660 | Ada object path (@ref{Search Paths and the Run-Time Library (RTL)}), | |
9661 | the new object and ALI files are created in the | |
9662 | directory containing the source being compiled. If another organization | |
9663 | is desired, where objects and sources are kept in different directories, | |
9664 | a useful technique is to create dummy ALI files in the desired directories. | |
984a64bc AC |
9665 | When detecting such a dummy file, @command{gnatmake} will be forced to |
9666 | recompile the corresponding source file, and it will be put the resulting | |
9667 | object and ALI files in the directory where it found the dummy file. | |
88e1739c FW |
9668 | |
9669 | @item ^-j^/PROCESSES=^@var{n} | |
984a64bc | 9670 | @cindex @option{^-j^/PROCESSES^} (@command{gnatmake}) |
88e1739c | 9671 | @cindex Parallel make |
5af46aa9 AC |
9672 | Use @var{n} processes to carry out the (re)compilations. On a multiprocessor |
9673 | machine compilations will occur in parallel. If @var{n} is 0, then the | |
9674 | maximum number of parallel compilations is the number of core processors | |
9675 | on the platform. In the event of compilation errors, messages from various | |
9676 | compilations might get interspersed (but @command{gnatmake} will give you the | |
9677 | full ordered list of failing compiles at the end). If this is problematic, | |
9678 | rerun the make process with n set to 1 to get a clean list of messages. | |
88e1739c FW |
9679 | |
9680 | @item ^-k^/CONTINUE_ON_ERROR^ | |
984a64bc | 9681 | @cindex @option{^-k^/CONTINUE_ON_ERROR^} (@command{gnatmake}) |
88e1739c FW |
9682 | Keep going. Continue as much as possible after a compilation error. To |
9683 | ease the programmer's task in case of compilation errors, the list of | |
984a64bc | 9684 | sources for which the compile fails is given when @command{gnatmake} |
88e1739c FW |
9685 | terminates. |
9686 | ||
984a64bc | 9687 | If @command{gnatmake} is invoked with several @file{file_names} and with this |
88e1739c | 9688 | switch, if there are compilation errors when building an executable, |
984a64bc | 9689 | @command{gnatmake} will not attempt to build the following executables. |
88e1739c FW |
9690 | |
9691 | @item ^-l^/ACTIONS=LINK^ | |
984a64bc | 9692 | @cindex @option{^-l^/ACTIONS=LINK^} (@command{gnatmake}) |
7cd4527e | 9693 | Link only. Can be combined with @option{^-b^/ACTIONS=BIND^} to binding |
88e1739c | 9694 | and linking. Linking will not be performed if combined with |
7cd4527e AC |
9695 | @option{^-c^/ACTIONS=COMPILE^} |
9696 | but not with @option{^-b^/ACTIONS=BIND^}. | |
9697 | When not combined with @option{^-b^/ACTIONS=BIND^} | |
88e1739c | 9698 | all the units in the closure of the main program must have been previously |
984a64bc | 9699 | compiled and must be up to date, and the main program needs to have been bound. |
88e1739c FW |
9700 | The root unit specified by @var{file_name} |
9701 | may be given without extension, with the source extension or, if no GNAT | |
9702 | Project File is specified, with the ALI file extension. | |
9703 | ||
9704 | @item ^-m^/MINIMAL_RECOMPILATION^ | |
984a64bc AC |
9705 | @cindex @option{^-m^/MINIMAL_RECOMPILATION^} (@command{gnatmake}) |
9706 | Specify that the minimum necessary amount of recompilations | |
9707 | be performed. In this mode @command{gnatmake} ignores time | |
88e1739c FW |
9708 | stamp differences when the only |
9709 | modifications to a source file consist in adding/removing comments, | |
9710 | empty lines, spaces or tabs. This means that if you have changed the | |
9711 | comments in a source file or have simply reformatted it, using this | |
1992bbd9 | 9712 | switch will tell @command{gnatmake} not to recompile files that depend on it |
88e1739c FW |
9713 | (provided other sources on which these files depend have undergone no |
9714 | semantic modifications). Note that the debugging information may be | |
7cd4527e | 9715 | out of date with respect to the sources if the @option{-m} switch causes |
88e1739c FW |
9716 | a compilation to be switched, so the use of this switch represents a |
9717 | trade-off between compilation time and accurate debugging information. | |
9718 | ||
9719 | @item ^-M^/DEPENDENCIES_LIST^ | |
9720 | @cindex Dependencies, producing list | |
984a64bc | 9721 | @cindex @option{^-M^/DEPENDENCIES_LIST^} (@command{gnatmake}) |
88e1739c FW |
9722 | Check if all objects are up to date. If they are, output the object |
9723 | dependences to @file{stdout} in a form that can be directly exploited in | |
9724 | a @file{Makefile}. By default, each source file is prefixed with its | |
9725 | (relative or absolute) directory name. This name is whatever you | |
7cd4527e AC |
9726 | specified in the various @option{^-aI^/SOURCE_SEARCH^} |
9727 | and @option{^-I^/SEARCH^} switches. If you use | |
88e1739c | 9728 | @code{gnatmake ^-M^/DEPENDENCIES_LIST^} |
7cd4527e | 9729 | @option{^-q^/QUIET^} |
88e1739c FW |
9730 | (see below), only the source file names, |
9731 | without relative paths, are output. If you just specify the | |
7cd4527e | 9732 | @option{^-M^/DEPENDENCIES_LIST^} |
88e1739c FW |
9733 | switch, dependencies of the GNAT internal system files are omitted. This |
9734 | is typically what you want. If you also specify | |
7cd4527e | 9735 | the @option{^-a^/ALL_FILES^} switch, |
88e1739c FW |
9736 | dependencies of the GNAT internal files are also listed. Note that |
9737 | dependencies of the objects in external Ada libraries (see switch | |
7cd4527e AC |
9738 | @option{^-aL^/SKIP_MISSING=^}@var{dir} in the following list) |
9739 | are never reported. | |
88e1739c FW |
9740 | |
9741 | @item ^-n^/DO_OBJECT_CHECK^ | |
984a64bc | 9742 | @cindex @option{^-n^/DO_OBJECT_CHECK^} (@command{gnatmake}) |
88e1739c FW |
9743 | Don't compile, bind, or link. Checks if all objects are up to date. |
9744 | If they are not, the full name of the first file that needs to be | |
9745 | recompiled is printed. | |
9746 | Repeated use of this option, followed by compiling the indicated source | |
9747 | file, will eventually result in recompiling all required units. | |
9748 | ||
9749 | @item ^-o ^/EXECUTABLE=^@var{exec_name} | |
984a64bc | 9750 | @cindex @option{^-o^/EXECUTABLE^} (@command{gnatmake}) |
88e1739c | 9751 | Output executable name. The name of the final executable program will be |
7cd4527e | 9752 | @var{exec_name}. If the @option{^-o^/EXECUTABLE^} switch is omitted the default |
88e1739c FW |
9753 | name for the executable will be the name of the input file in appropriate form |
9754 | for an executable file on the host system. | |
9755 | ||
984a64bc | 9756 | This switch cannot be used when invoking @command{gnatmake} with several |
88e1739c FW |
9757 | @file{file_names}. |
9758 | ||
0916df6a RD |
9759 | @item ^-p or --create-missing-dirs^/CREATE_MISSING_DIRS^ |
9760 | @cindex @option{^-p^/CREATE_MISSING_DIRS^} (@command{gnatmake}) | |
9761 | When using project files (^-P^/PROJECT_FILE=^@var{project}), create | |
9762 | automatically missing object directories, library directories and exec | |
9763 | directories. | |
9764 | ||
7cd4527e | 9765 | @item ^-P^/PROJECT_FILE=^@var{project} |
984a64bc | 9766 | @cindex @option{^-P^/PROJECT_FILE^} (@command{gnatmake}) |
7cd4527e | 9767 | Use project file @var{project}. Only one such switch can be used. |
a3da92f9 | 9768 | @xref{gnatmake and Project Files}. |
7cd4527e | 9769 | |
88e1739c | 9770 | @item ^-q^/QUIET^ |
984a64bc | 9771 | @cindex @option{^-q^/QUIET^} (@command{gnatmake}) |
88e1739c | 9772 | Quiet. When this flag is not set, the commands carried out by |
984a64bc | 9773 | @command{gnatmake} are displayed. |
88e1739c FW |
9774 | |
9775 | @item ^-s^/SWITCH_CHECK/^ | |
984a64bc | 9776 | @cindex @option{^-s^/SWITCH_CHECK^} (@command{gnatmake}) |
88e1739c FW |
9777 | Recompile if compiler switches have changed since last compilation. |
9778 | All compiler switches but -I and -o are taken into account in the | |
9779 | following way: | |
9780 | orders between different ``first letter'' switches are ignored, but | |
9781 | orders between same switches are taken into account. For example, | |
7cd4527e AC |
9782 | @option{-O -O2} is different than @option{-O2 -O}, but @option{-g -O} |
9783 | is equivalent to @option{-O -g}. | |
9784 | ||
9785 | This switch is recommended when Integrated Preprocessing is used. | |
88e1739c FW |
9786 | |
9787 | @item ^-u^/UNIQUE^ | |
984a64bc | 9788 | @cindex @option{^-u^/UNIQUE^} (@command{gnatmake}) |
7cd4527e AC |
9789 | Unique. Recompile at most the main files. It implies -c. Combined with |
9790 | -f, it is equivalent to calling the compiler directly. Note that using | |
9791 | ^-u^/UNIQUE^ with a project file and no main has a special meaning | |
984a64bc | 9792 | (@pxref{Project Files and Main Subprograms}). |
7cd4527e AC |
9793 | |
9794 | @item ^-U^/ALL_PROJECTS^ | |
984a64bc | 9795 | @cindex @option{^-U^/ALL_PROJECTS^} (@command{gnatmake}) |
7cd4527e AC |
9796 | When used without a project file or with one or several mains on the command |
9797 | line, is equivalent to ^-u^/UNIQUE^. When used with a project file and no main | |
9798 | on the command line, all sources of all project files are checked and compiled | |
9799 | if not up to date, and libraries are rebuilt, if necessary. | |
88e1739c FW |
9800 | |
9801 | @item ^-v^/REASONS^ | |
984a64bc AC |
9802 | @cindex @option{^-v^/REASONS^} (@command{gnatmake}) |
9803 | Verbose. Display the reason for all recompilations @command{gnatmake} | |
32e209e4 CC |
9804 | decides are necessary, with the highest verbosity level. |
9805 | ||
9806 | @item ^-vl^/LOW_VERBOSITY^ | |
9807 | @cindex @option{^-vl^/LOW_VERBOSITY^} (@command{gnatmake}) | |
9808 | Verbosity level Low. Display fewer lines than in verbosity Medium. | |
9809 | ||
9810 | @item ^-vm^/MEDIUM_VERBOSITY^ | |
9811 | @cindex @option{^-vm^/MEDIUM_VERBOSITY^} (@command{gnatmake}) | |
9812 | Verbosity level Medium. Potentially display fewer lines than in verbosity High. | |
9813 | ||
9814 | @item ^-vh^/HIGH_VERBOSITY^ | |
9815 | @cindex @option{^-vm^/HIGH_VERBOSITY^} (@command{gnatmake}) | |
9816 | Verbosity level High. Equivalent to ^-v^/REASONS^. | |
88e1739c | 9817 | |
7cd4527e | 9818 | @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} |
984a64bc | 9819 | Indicate the verbosity of the parsing of GNAT project files. |
a3da92f9 | 9820 | @xref{Switches Related to Project Files}. |
7cd4527e | 9821 | |
5950a3ac | 9822 | @item ^-x^/NON_PROJECT_UNIT_COMPILATION^ |
984a64bc AC |
9823 | @cindex @option{^-x^/NON_PROJECT_UNIT_COMPILATION^} (@command{gnatmake}) |
9824 | Indicate that sources that are not part of any Project File may be compiled. | |
5950a3ac AC |
9825 | Normally, when using Project Files, only sources that are part of a Project |
9826 | File may be compile. When this switch is used, a source outside of all Project | |
9827 | Files may be compiled. The ALI file and the object file will be put in the | |
9828 | object directory of the main Project. The compilation switches used will only | |
1a5f40e1 VC |
9829 | be those specified on the command line. Even when |
9830 | @option{^-x^/NON_PROJECT_UNIT_COMPILATION^} is used, mains specified on the | |
9831 | command line need to be sources of a project file. | |
5950a3ac | 9832 | |
7cd4527e | 9833 | @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} |
984a64bc | 9834 | Indicate that external variable @var{name} has the value @var{value}. |
7cd4527e AC |
9835 | The Project Manager will use this value for occurrences of |
9836 | @code{external(name)} when parsing the project file. | |
a3da92f9 | 9837 | @xref{Switches Related to Project Files}. |
7cd4527e | 9838 | |
88e1739c | 9839 | @item ^-z^/NOMAIN^ |
984a64bc | 9840 | @cindex @option{^-z^/NOMAIN^} (@command{gnatmake}) |
88e1739c FW |
9841 | No main subprogram. Bind and link the program even if the unit name |
9842 | given on the command line is a package name. The resulting executable | |
9843 | will execute the elaboration routines of the package and its closure, | |
9844 | then the finalization routines. | |
9845 | ||
7cd4527e AC |
9846 | @end table |
9847 | ||
9848 | @table @asis | |
984a64bc | 9849 | @item @command{gcc} @asis{switches} |
88e1739c | 9850 | @ifclear vms |
984a64bc | 9851 | Any uppercase or multi-character switch that is not a @command{gnatmake} switch |
8dd07840 | 9852 | is passed to @command{gcc} (e.g.@: @option{-O}, @option{-gnato,} etc.) |
88e1739c FW |
9853 | @end ifclear |
9854 | @ifset vms | |
9855 | Any qualifier that cannot be recognized as a qualifier for @code{GNAT MAKE} | |
9856 | but is recognizable as a valid qualifier for @code{GNAT COMPILE} is | |
9857 | automatically treated as a compiler switch, and passed on to all | |
9858 | compilations that are carried out. | |
9859 | @end ifset | |
9860 | @end table | |
9861 | ||
9862 | @noindent | |
9863 | Source and library search path switches: | |
9864 | ||
7cd4527e AC |
9865 | @table @option |
9866 | @c !sort! | |
88e1739c | 9867 | @item ^-aI^/SOURCE_SEARCH=^@var{dir} |
984a64bc | 9868 | @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatmake}) |
88e1739c FW |
9869 | When looking for source files also look in directory @var{dir}. |
9870 | The order in which source files search is undertaken is | |
9871 | described in @ref{Search Paths and the Run-Time Library (RTL)}. | |
9872 | ||
9873 | @item ^-aL^/SKIP_MISSING=^@var{dir} | |
984a64bc | 9874 | @cindex @option{^-aL^/SKIP_MISSING^} (@command{gnatmake}) |
88e1739c | 9875 | Consider @var{dir} as being an externally provided Ada library. |
984a64bc | 9876 | Instructs @command{gnatmake} to skip compilation units whose @file{.ALI} |
88e1739c FW |
9877 | files have been located in directory @var{dir}. This allows you to have |
9878 | missing bodies for the units in @var{dir} and to ignore out of date bodies | |
9879 | for the same units. You still need to specify | |
9880 | the location of the specs for these units by using the switches | |
7cd4527e AC |
9881 | @option{^-aI^/SOURCE_SEARCH=^@var{dir}} |
9882 | or @option{^-I^/SEARCH=^@var{dir}}. | |
88e1739c | 9883 | Note: this switch is provided for compatibility with previous versions |
984a64bc | 9884 | of @command{gnatmake}. The easier method of causing standard libraries |
88e1739c FW |
9885 | to be excluded from consideration is to write-protect the corresponding |
9886 | ALI files. | |
9887 | ||
9888 | @item ^-aO^/OBJECT_SEARCH=^@var{dir} | |
984a64bc | 9889 | @cindex @option{^-aO^/OBJECT_SEARCH^} (@command{gnatmake}) |
88e1739c FW |
9890 | When searching for library and object files, look in directory |
9891 | @var{dir}. The order in which library files are searched is described in | |
9892 | @ref{Search Paths for gnatbind}. | |
9893 | ||
9894 | @item ^-A^/CONDITIONAL_SOURCE_SEARCH=^@var{dir} | |
984a64bc AC |
9895 | @cindex Search paths, for @command{gnatmake} |
9896 | @cindex @option{^-A^/CONDITIONAL_SOURCE_SEARCH^} (@command{gnatmake}) | |
7cd4527e | 9897 | Equivalent to @option{^-aL^/SKIP_MISSING=^@var{dir} |
88e1739c FW |
9898 | ^-aI^/SOURCE_SEARCH=^@var{dir}}. |
9899 | ||
9900 | @item ^-I^/SEARCH=^@var{dir} | |
984a64bc | 9901 | @cindex @option{^-I^/SEARCH^} (@command{gnatmake}) |
7cd4527e | 9902 | Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir} |
88e1739c FW |
9903 | ^-aI^/SOURCE_SEARCH=^@var{dir}}. |
9904 | ||
9905 | @item ^-I-^/NOCURRENT_DIRECTORY^ | |
984a64bc | 9906 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatmake}) |
88e1739c FW |
9907 | @cindex Source files, suppressing search |
9908 | Do not look for source files in the directory containing the source | |
9909 | file named in the command line. | |
9910 | Do not look for ALI or object files in the directory | |
984a64bc | 9911 | where @command{gnatmake} was invoked. |
88e1739c FW |
9912 | |
9913 | @item ^-L^/LIBRARY_SEARCH=^@var{dir} | |
984a64bc | 9914 | @cindex @option{^-L^/LIBRARY_SEARCH^} (@command{gnatmake}) |
88e1739c FW |
9915 | @cindex Linker libraries |
9916 | Add directory @var{dir} to the list of directories in which the linker | |
7cd4527e AC |
9917 | will search for libraries. This is equivalent to |
9918 | @option{-largs ^-L^/LIBRARY_SEARCH=^}@var{dir}. | |
9919 | @ifclear vms | |
88e1739c FW |
9920 | Furthermore, under Windows, the sources pointed to by the libraries path |
9921 | set in the registry are not searched for. | |
7cd4527e | 9922 | @end ifclear |
88e1739c FW |
9923 | |
9924 | @item -nostdinc | |
984a64bc | 9925 | @cindex @option{-nostdinc} (@command{gnatmake}) |
88e1739c FW |
9926 | Do not look for source files in the system default directory. |
9927 | ||
9928 | @item -nostdlib | |
984a64bc | 9929 | @cindex @option{-nostdlib} (@command{gnatmake}) |
88e1739c FW |
9930 | Do not look for library files in the system default directory. |
9931 | ||
9932 | @item --RTS=@var{rts-path} | |
984a64bc | 9933 | @cindex @option{--RTS} (@command{gnatmake}) |
7cd4527e AC |
9934 | Specifies the default location of the runtime library. GNAT looks for the |
9935 | runtime | |
9936 | in the following directories, and stops as soon as a valid runtime is found | |
9937 | (@file{adainclude} or @file{ada_source_path}, and @file{adalib} or | |
9938 | @file{ada_object_path} present): | |
88e1739c FW |
9939 | |
9940 | @itemize @bullet | |
9941 | @item <current directory>/$rts_path | |
9942 | ||
9943 | @item <default-search-dir>/$rts_path | |
9944 | ||
9945 | @item <default-search-dir>/rts-$rts_path | |
9946 | @end itemize | |
9947 | ||
9948 | @noindent | |
9949 | The selected path is handled like a normal RTS path. | |
9950 | ||
9951 | @end table | |
9952 | ||
9953 | @node Mode Switches for gnatmake | |
984a64bc | 9954 | @section Mode Switches for @command{gnatmake} |
88e1739c FW |
9955 | |
9956 | @noindent | |
9957 | The mode switches (referred to as @code{mode_switches}) allow the | |
9958 | inclusion of switches that are to be passed to the compiler itself, the | |
9959 | binder or the linker. The effect of a mode switch is to cause all | |
9960 | subsequent switches up to the end of the switch list, or up to the next | |
9961 | mode switch, to be interpreted as switches to be passed on to the | |
9962 | designated component of GNAT. | |
9963 | ||
7cd4527e AC |
9964 | @table @option |
9965 | @c !sort! | |
88e1739c | 9966 | @item -cargs @var{switches} |
984a64bc | 9967 | @cindex @option{-cargs} (@command{gnatmake}) |
88e1739c | 9968 | Compiler switches. Here @var{switches} is a list of switches |
984a64bc AC |
9969 | that are valid switches for @command{gcc}. They will be passed on to |
9970 | all compile steps performed by @command{gnatmake}. | |
88e1739c FW |
9971 | |
9972 | @item -bargs @var{switches} | |
984a64bc | 9973 | @cindex @option{-bargs} (@command{gnatmake}) |
88e1739c | 9974 | Binder switches. Here @var{switches} is a list of switches |
7cd4527e | 9975 | that are valid switches for @code{gnatbind}. They will be passed on to |
984a64bc | 9976 | all bind steps performed by @command{gnatmake}. |
88e1739c FW |
9977 | |
9978 | @item -largs @var{switches} | |
984a64bc | 9979 | @cindex @option{-largs} (@command{gnatmake}) |
88e1739c | 9980 | Linker switches. Here @var{switches} is a list of switches |
984a64bc AC |
9981 | that are valid switches for @command{gnatlink}. They will be passed on to |
9982 | all link steps performed by @command{gnatmake}. | |
7cd4527e AC |
9983 | |
9984 | @item -margs @var{switches} | |
984a64bc AC |
9985 | @cindex @option{-margs} (@command{gnatmake}) |
9986 | Make switches. The switches are directly interpreted by @command{gnatmake}, | |
7cd4527e AC |
9987 | regardless of any previous occurrence of @option{-cargs}, @option{-bargs} |
9988 | or @option{-largs}. | |
88e1739c FW |
9989 | @end table |
9990 | ||
9991 | @node Notes on the Command Line | |
9992 | @section Notes on the Command Line | |
9993 | ||
9994 | @noindent | |
9995 | This section contains some additional useful notes on the operation | |
984a64bc | 9996 | of the @command{gnatmake} command. |
88e1739c FW |
9997 | |
9998 | @itemize @bullet | |
9999 | @item | |
984a64bc AC |
10000 | @cindex Recompilation, by @command{gnatmake} |
10001 | If @command{gnatmake} finds no ALI files, it recompiles the main program | |
88e1739c | 10002 | and all other units required by the main program. |
984a64bc | 10003 | This means that @command{gnatmake} |
88e1739c FW |
10004 | can be used for the initial compile, as well as during subsequent steps of |
10005 | the development cycle. | |
10006 | ||
10007 | @item | |
10008 | If you enter @code{gnatmake @var{file}.adb}, where @file{@var{file}.adb} | |
984a64bc | 10009 | is a subunit or body of a generic unit, @command{gnatmake} recompiles |
88e1739c FW |
10010 | @file{@var{file}.adb} (because it finds no ALI) and stops, issuing a |
10011 | warning. | |
10012 | ||
10013 | @item | |
984a64bc | 10014 | In @command{gnatmake} the switch @option{^-I^/SEARCH^} |
88e1739c | 10015 | is used to specify both source and |
7cd4527e | 10016 | library file paths. Use @option{^-aI^/SOURCE_SEARCH^} |
88e1739c | 10017 | instead if you just want to specify |
7cd4527e | 10018 | source paths only and @option{^-aO^/OBJECT_SEARCH^} |
88e1739c FW |
10019 | if you want to specify library paths |
10020 | only. | |
10021 | ||
88e1739c | 10022 | @item |
984a64bc | 10023 | @command{gnatmake} will ignore any files whose ALI file is write-protected. |
88e1739c FW |
10024 | This may conveniently be used to exclude standard libraries from |
10025 | consideration and in particular it means that the use of the | |
7cd4527e AC |
10026 | @option{^-f^/FORCE_COMPILE^} switch will not recompile these files |
10027 | unless @option{^-a^/ALL_FILES^} is also specified. | |
88e1739c FW |
10028 | |
10029 | @item | |
984a64bc | 10030 | @command{gnatmake} has been designed to make the use of Ada libraries |
88e1739c | 10031 | particularly convenient. Assume you have an Ada library organized |
7cd4527e | 10032 | as follows: @i{^obj-dir^[OBJ_DIR]^} contains the objects and ALI files for |
88e1739c | 10033 | of your Ada compilation units, |
7cd4527e | 10034 | whereas @i{^include-dir^[INCLUDE_DIR]^} contains the |
88e1739c FW |
10035 | specs of these units, but no bodies. Then to compile a unit |
10036 | stored in @code{main.adb}, which uses this Ada library you would just type | |
10037 | ||
10038 | @smallexample | |
10039 | @ifclear vms | |
10040 | $ gnatmake -aI@var{include-dir} -aL@var{obj-dir} main | |
10041 | @end ifclear | |
10042 | @ifset vms | |
7cd4527e AC |
10043 | $ gnatmake /SOURCE_SEARCH=@i{[INCLUDE_DIR]} |
10044 | /SKIP_MISSING=@i{[OBJ_DIR]} main | |
88e1739c FW |
10045 | @end ifset |
10046 | @end smallexample | |
10047 | ||
10048 | @item | |
984a64bc | 10049 | Using @command{gnatmake} along with the |
7cd4527e | 10050 | @option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^} |
e69044cb | 10051 | switch provides a mechanism for avoiding unnecessary recompilations. Using |
88e1739c FW |
10052 | this switch, |
10053 | you can update the comments/format of your | |
10054 | source files without having to recompile everything. Note, however, that | |
10055 | adding or deleting lines in a source files may render its debugging | |
10056 | info obsolete. If the file in question is a spec, the impact is rather | |
10057 | limited, as that debugging info will only be useful during the | |
10058 | elaboration phase of your program. For bodies the impact can be more | |
10059 | significant. In all events, your debugger will warn you if a source file | |
10060 | is more recent than the corresponding object, and alert you to the fact | |
10061 | that the debugging information may be out of date. | |
10062 | @end itemize | |
10063 | ||
10064 | @node How gnatmake Works | |
984a64bc | 10065 | @section How @command{gnatmake} Works |
88e1739c FW |
10066 | |
10067 | @noindent | |
984a64bc | 10068 | Generally @command{gnatmake} automatically performs all necessary |
88e1739c | 10069 | recompilations and you don't need to worry about how it works. However, |
984a64bc | 10070 | it may be useful to have some basic understanding of the @command{gnatmake} |
88e1739c FW |
10071 | approach and in particular to understand how it uses the results of |
10072 | previous compilations without incorrectly depending on them. | |
10073 | ||
10074 | First a definition: an object file is considered @dfn{up to date} if the | |
c885d7a1 | 10075 | corresponding ALI file exists and if all the source files listed in the |
88e1739c FW |
10076 | dependency section of this ALI file have time stamps matching those in |
10077 | the ALI file. This means that neither the source file itself nor any | |
10078 | files that it depends on have been modified, and hence there is no need | |
10079 | to recompile this file. | |
10080 | ||
984a64bc | 10081 | @command{gnatmake} works by first checking if the specified main unit is up |
88e1739c | 10082 | to date. If so, no compilations are required for the main unit. If not, |
984a64bc | 10083 | @command{gnatmake} compiles the main program to build a new ALI file that |
88e1739c FW |
10084 | reflects the latest sources. Then the ALI file of the main unit is |
10085 | examined to find all the source files on which the main program depends, | |
984a64bc AC |
10086 | and @command{gnatmake} recursively applies the above procedure on all these |
10087 | files. | |
88e1739c | 10088 | |
984a64bc | 10089 | This process ensures that @command{gnatmake} only trusts the dependencies |
88e1739c FW |
10090 | in an existing ALI file if they are known to be correct. Otherwise it |
10091 | always recompiles to determine a new, guaranteed accurate set of | |
7cd4527e | 10092 | dependencies. As a result the program is compiled ``upside down'' from what may |
88e1739c FW |
10093 | be more familiar as the required order of compilation in some other Ada |
10094 | systems. In particular, clients are compiled before the units on which | |
10095 | they depend. The ability of GNAT to compile in any order is critical in | |
10096 | allowing an order of compilation to be chosen that guarantees that | |
984a64bc | 10097 | @command{gnatmake} will recompute a correct set of new dependencies if |
88e1739c FW |
10098 | necessary. |
10099 | ||
984a64bc | 10100 | When invoking @command{gnatmake} with several @var{file_names}, if a unit is |
88e1739c FW |
10101 | imported by several of the executables, it will be recompiled at most once. |
10102 | ||
7cd4527e | 10103 | Note: when using non-standard naming conventions |
984a64bc AC |
10104 | (@pxref{Using Other File Names}), changing through a configuration pragmas |
10105 | file the version of a source and invoking @command{gnatmake} to recompile may | |
7cd4527e | 10106 | have no effect, if the previous version of the source is still accessible |
984a64bc AC |
10107 | by @command{gnatmake}. It may be necessary to use the switch |
10108 | ^-f^/FORCE_COMPILE^. | |
7cd4527e | 10109 | |
88e1739c | 10110 | @node Examples of gnatmake Usage |
984a64bc | 10111 | @section Examples of @command{gnatmake} Usage |
88e1739c FW |
10112 | |
10113 | @table @code | |
10114 | @item gnatmake hello.adb | |
10115 | Compile all files necessary to bind and link the main program | |
10116 | @file{hello.adb} (containing unit @code{Hello}) and bind and link the | |
10117 | resulting object files to generate an executable file @file{^hello^HELLO.EXE^}. | |
10118 | ||
10119 | @item gnatmake main1 main2 main3 | |
10120 | Compile all files necessary to bind and link the main programs | |
10121 | @file{main1.adb} (containing unit @code{Main1}), @file{main2.adb} | |
10122 | (containing unit @code{Main2}) and @file{main3.adb} | |
10123 | (containing unit @code{Main3}) and bind and link the resulting object files | |
10124 | to generate three executable files @file{^main1^MAIN1.EXE^}, | |
10125 | @file{^main2^MAIN2.EXE^} | |
10126 | and @file{^main3^MAIN3.EXE^}. | |
10127 | ||
10128 | @ifclear vms | |
10129 | @item gnatmake -q Main_Unit -cargs -O2 -bargs -l | |
10130 | @end ifclear | |
10131 | ||
10132 | @ifset vms | |
7cd4527e | 10133 | @item gnatmake Main_Unit /QUIET |
6ccde948 RW |
10134 | /COMPILER_QUALIFIERS /OPTIMIZE=ALL |
10135 | /BINDER_QUALIFIERS /ORDER_OF_ELABORATION | |
88e1739c FW |
10136 | @end ifset |
10137 | Compile all files necessary to bind and link the main program unit | |
10138 | @code{Main_Unit} (from file @file{main_unit.adb}). All compilations will | |
10139 | be done with optimization level 2 and the order of elaboration will be | |
984a64bc | 10140 | listed by the binder. @command{gnatmake} will operate in quiet mode, not |
88e1739c FW |
10141 | displaying commands it is executing. |
10142 | @end table | |
10143 | ||
7cd4527e AC |
10144 | @c ************************* |
10145 | @node Improving Performance | |
10146 | @chapter Improving Performance | |
10147 | @cindex Improving performance | |
88e1739c FW |
10148 | |
10149 | @noindent | |
7cd4527e AC |
10150 | This chapter presents several topics related to program performance. |
10151 | It first describes some of the tradeoffs that need to be considered | |
10152 | and some of the techniques for making your program run faster. | |
1037b0f4 AC |
10153 | It then documents |
10154 | @ifclear FSFEDITION | |
10155 | the @command{gnatelim} tool and | |
10156 | @end ifclear | |
10157 | unused subprogram/data | |
7e3d710b | 10158 | elimination feature, which can reduce the size of program executables. |
88e1739c | 10159 | |
6da7d579 | 10160 | @ifnottex |
88e1739c | 10161 | @menu |
7cd4527e | 10162 | * Performance Considerations:: |
1a5f40e1 | 10163 | * Text_IO Suggestions:: |
1037b0f4 | 10164 | @ifclear FSFEDITION |
ba1cbfb9 | 10165 | * Reducing Size of Ada Executables with gnatelim:: |
1037b0f4 | 10166 | @end ifclear |
ba1cbfb9 | 10167 | * Reducing Size of Executables with unused subprogram/data elimination:: |
88e1739c | 10168 | @end menu |
6da7d579 | 10169 | @end ifnottex |
88e1739c | 10170 | |
7cd4527e AC |
10171 | @c ***************************** |
10172 | @node Performance Considerations | |
10173 | @section Performance Considerations | |
88e1739c FW |
10174 | |
10175 | @noindent | |
7cd4527e AC |
10176 | The GNAT system provides a number of options that allow a trade-off |
10177 | between | |
88e1739c | 10178 | |
7cd4527e AC |
10179 | @itemize @bullet |
10180 | @item | |
10181 | performance of the generated code | |
88e1739c | 10182 | |
7cd4527e AC |
10183 | @item |
10184 | speed of compilation | |
88e1739c | 10185 | |
7cd4527e AC |
10186 | @item |
10187 | minimization of dependences and recompilation | |
88e1739c | 10188 | |
7cd4527e AC |
10189 | @item |
10190 | the degree of run-time checking. | |
10191 | @end itemize | |
88e1739c FW |
10192 | |
10193 | @noindent | |
7cd4527e AC |
10194 | The defaults (if no options are selected) aim at improving the speed |
10195 | of compilation and minimizing dependences, at the expense of performance | |
10196 | of the generated code: | |
88e1739c | 10197 | |
7cd4527e AC |
10198 | @itemize @bullet |
10199 | @item | |
10200 | no optimization | |
88e1739c | 10201 | |
7cd4527e AC |
10202 | @item |
10203 | no inlining of subprogram calls | |
88e1739c | 10204 | |
7cd4527e AC |
10205 | @item |
10206 | all run-time checks enabled except overflow and elaboration checks | |
10207 | @end itemize | |
88e1739c | 10208 | |
7cd4527e AC |
10209 | @noindent |
10210 | These options are suitable for most program development purposes. This | |
10211 | chapter describes how you can modify these choices, and also provides | |
10212 | some guidelines on debugging optimized code. | |
88e1739c | 10213 | |
7cd4527e AC |
10214 | @menu |
10215 | * Controlling Run-Time Checks:: | |
10216 | * Use of Restrictions:: | |
10217 | * Optimization Levels:: | |
10218 | * Debugging Optimized Code:: | |
10219 | * Inlining of Subprograms:: | |
8daa1407 | 10220 | * Vectorization of loops:: |
c1cd0d96 | 10221 | * Other Optimization Switches:: |
7cd4527e | 10222 | * Optimization and Strict Aliasing:: |
124092ee | 10223 | * Aliased Variables and Optimization:: |
d0e69402 | 10224 | * Atomic Variables and Optimization:: |
54533a0b | 10225 | * Passive Task Optimization:: |
c1cd0d96 | 10226 | |
7cd4527e AC |
10227 | @ifset vms |
10228 | * Coverage Analysis:: | |
10229 | @end ifset | |
10230 | @end menu | |
88e1739c | 10231 | |
7cd4527e AC |
10232 | @node Controlling Run-Time Checks |
10233 | @subsection Controlling Run-Time Checks | |
88e1739c FW |
10234 | |
10235 | @noindent | |
a3ea9137 AC |
10236 | By default, GNAT generates all run-time checks, except integer overflow |
10237 | checks, stack overflow checks, and checks for access before elaboration on | |
7cd4527e AC |
10238 | subprogram calls. The latter are not required in default mode, because all |
10239 | necessary checking is done at compile time. | |
984a64bc AC |
10240 | @cindex @option{-gnatp} (@command{gcc}) |
10241 | @cindex @option{-gnato} (@command{gcc}) | |
7cd4527e AC |
10242 | Two gnat switches, @option{-gnatp} and @option{-gnato} allow this default to |
10243 | be modified. @xref{Run-Time Checks}. | |
88e1739c | 10244 | |
7cd4527e AC |
10245 | Our experience is that the default is suitable for most development |
10246 | purposes. | |
88e1739c | 10247 | |
7cd4527e AC |
10248 | We treat integer overflow specially because these |
10249 | are quite expensive and in our experience are not as important as other | |
10250 | run-time checks in the development process. Note that division by zero | |
10251 | is not considered an overflow check, and divide by zero checks are | |
10252 | generated where required by default. | |
88e1739c | 10253 | |
7cd4527e AC |
10254 | Elaboration checks are off by default, and also not needed by default, since |
10255 | GNAT uses a static elaboration analysis approach that avoids the need for | |
10256 | run-time checking. This manual contains a full chapter discussing the issue | |
10257 | of elaboration checks, and if the default is not satisfactory for your use, | |
10258 | you should read this chapter. | |
88e1739c | 10259 | |
7cd4527e AC |
10260 | For validity checks, the minimal checks required by the Ada Reference |
10261 | Manual (for case statements and assignments to array elements) are on | |
10262 | by default. These can be suppressed by use of the @option{-gnatVn} switch. | |
10263 | Note that in Ada 83, there were no validity checks, so if the Ada 83 mode | |
10264 | is acceptable (or when comparing GNAT performance with an Ada 83 compiler), | |
10265 | it may be reasonable to routinely use @option{-gnatVn}. Validity checks | |
10266 | are also suppressed entirely if @option{-gnatp} is used. | |
88e1739c | 10267 | |
7cd4527e AC |
10268 | @cindex Overflow checks |
10269 | @cindex Checks, overflow | |
10270 | @findex Suppress | |
10271 | @findex Unsuppress | |
10272 | @cindex pragma Suppress | |
10273 | @cindex pragma Unsuppress | |
10274 | Note that the setting of the switches controls the default setting of | |
10275 | the checks. They may be modified using either @code{pragma Suppress} (to | |
10276 | remove checks) or @code{pragma Unsuppress} (to add back suppressed | |
10277 | checks) in the program source. | |
88e1739c | 10278 | |
7cd4527e AC |
10279 | @node Use of Restrictions |
10280 | @subsection Use of Restrictions | |
88e1739c FW |
10281 | |
10282 | @noindent | |
7cd4527e AC |
10283 | The use of pragma Restrictions allows you to control which features are |
10284 | permitted in your program. Apart from the obvious point that if you avoid | |
10285 | relatively expensive features like finalization (enforceable by the use | |
10286 | of pragma Restrictions (No_Finalization), the use of this pragma does not | |
10287 | affect the generated code in most cases. | |
10288 | ||
10289 | One notable exception to this rule is that the possibility of task abort | |
10290 | results in some distributed overhead, particularly if finalization or | |
10291 | exception handlers are used. The reason is that certain sections of code | |
10292 | have to be marked as non-abortable. | |
10293 | ||
10294 | If you use neither the @code{abort} statement, nor asynchronous transfer | |
d488f6ea | 10295 | of control (@code{select @dots{} then abort}), then this distributed overhead |
7cd4527e AC |
10296 | is removed, which may have a general positive effect in improving |
10297 | overall performance. Especially code involving frequent use of tasking | |
10298 | constructs and controlled types will show much improved performance. | |
10299 | The relevant restrictions pragmas are | |
88e1739c | 10300 | |
7e3d710b | 10301 | @smallexample @c ada |
7cd4527e AC |
10302 | pragma Restrictions (No_Abort_Statements); |
10303 | pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); | |
88e1739c FW |
10304 | @end smallexample |
10305 | ||
10306 | @noindent | |
7cd4527e AC |
10307 | It is recommended that these restriction pragmas be used if possible. Note |
10308 | that this also means that you can write code without worrying about the | |
10309 | possibility of an immediate abort at any point. | |
88e1739c | 10310 | |
7cd4527e AC |
10311 | @node Optimization Levels |
10312 | @subsection Optimization Levels | |
984a64bc | 10313 | @cindex @option{^-O^/OPTIMIZE^} (@command{gcc}) |
88e1739c | 10314 | |
1a5f40e1 VC |
10315 | @noindent |
10316 | Without any optimization ^option,^qualifier,^ | |
10317 | the compiler's goal is to reduce the cost of | |
10318 | compilation and to make debugging produce the expected results. | |
10319 | Statements are independent: if you stop the program with a breakpoint between | |
10320 | statements, you can then assign a new value to any variable or change | |
10321 | the program counter to any other statement in the subprogram and get exactly | |
10322 | the results you would expect from the source code. | |
10323 | ||
10324 | Turning on optimization makes the compiler attempt to improve the | |
10325 | performance and/or code size at the expense of compilation time and | |
10326 | possibly the ability to debug the program. | |
10327 | ||
10328 | If you use multiple | |
10329 | ^-O options, with or without level numbers,^/OPTIMIZE qualifiers,^ | |
10330 | the last such option is the one that is effective. | |
10331 | ||
88e1739c | 10332 | @noindent |
7cd4527e AC |
10333 | The default is optimization off. This results in the fastest compile |
10334 | times, but GNAT makes absolutely no attempt to optimize, and the | |
10335 | generated programs are considerably larger and slower than when | |
10336 | optimization is enabled. You can use the | |
88e1739c | 10337 | @ifclear vms |
e08b38f5 VC |
10338 | @option{-O} switch (the permitted forms are @option{-O0}, @option{-O1} |
10339 | @option{-O2}, @option{-O3}, and @option{-Os}) | |
88e1739c | 10340 | @end ifclear |
7cd4527e AC |
10341 | @ifset vms |
10342 | @code{OPTIMIZE} qualifier | |
10343 | @end ifset | |
984a64bc | 10344 | to @command{gcc} to control the optimization level: |
88e1739c | 10345 | |
7cd4527e AC |
10346 | @table @option |
10347 | @item ^-O0^/OPTIMIZE=NONE^ | |
10348 | No optimization (the default); | |
10349 | generates unoptimized code but has | |
10350 | the fastest compilation time. | |
88e1739c | 10351 | |
c1cd0d96 | 10352 | Note that many other compilers do fairly extensive optimization |
1a5f40e1 | 10353 | even if ``no optimization'' is specified. With gcc, it is |
c1cd0d96 RD |
10354 | very unusual to use ^-O0^/OPTIMIZE=NONE^ for production if |
10355 | execution time is of any concern, since ^-O0^/OPTIMIZE=NONE^ | |
10356 | really does mean no optimization at all. This difference between | |
10357 | gcc and other compilers should be kept in mind when doing | |
10358 | performance comparisons. | |
10359 | ||
7cd4527e | 10360 | @item ^-O1^/OPTIMIZE=SOME^ |
c1cd0d96 | 10361 | Moderate optimization; |
7cd4527e AC |
10362 | optimizes reasonably well but does not |
10363 | degrade compilation time significantly. | |
10364 | ||
10365 | @item ^-O2^/OPTIMIZE=ALL^ | |
88e1739c | 10366 | @ifset vms |
7cd4527e | 10367 | @itemx /OPTIMIZE=DEVELOPMENT |
88e1739c | 10368 | @end ifset |
7cd4527e AC |
10369 | Full optimization; |
10370 | generates highly optimized code and has | |
10371 | the slowest compilation time. | |
88e1739c | 10372 | |
7cd4527e | 10373 | @item ^-O3^/OPTIMIZE=INLINING^ |
9d983bbf | 10374 | Full optimization as in @option{-O2}; |
4fb0b3f0 | 10375 | also uses more aggressive automatic inlining of subprograms within a unit |
308e6f3a | 10376 | (@pxref{Inlining of Subprograms}) and attempts to vectorize loops. |
e08b38f5 VC |
10377 | |
10378 | @item ^-Os^/OPTIMIZE=SPACE^ | |
9d983bbf | 10379 | Optimize space usage (code and data) of resulting program. |
7cd4527e | 10380 | @end table |
88e1739c | 10381 | |
7cd4527e AC |
10382 | @noindent |
10383 | Higher optimization levels perform more global transformations on the | |
10384 | program and apply more expensive analysis algorithms in order to generate | |
10385 | faster and more compact code. The price in compilation time, and the | |
10386 | resulting improvement in execution time, | |
10387 | both depend on the particular application and the hardware environment. | |
10388 | You should experiment to find the best level for your application. | |
88e1739c | 10389 | |
7cd4527e AC |
10390 | Since the precise set of optimizations done at each level will vary from |
10391 | release to release (and sometime from target to target), it is best to think | |
10392 | of the optimization settings in general terms. | |
b2e74434 RW |
10393 | @xref{Optimize Options,, Options That Control Optimization, gcc, Using |
10394 | the GNU Compiler Collection (GCC)}, for details about | |
7cd4527e AC |
10395 | ^the @option{-O} settings and a number of @option{-f} options that^how to^ |
10396 | individually enable or disable specific optimizations. | |
88e1739c | 10397 | |
7cd4527e AC |
10398 | Unlike some other compilation systems, ^@command{gcc}^GNAT^ has |
10399 | been tested extensively at all optimization levels. There are some bugs | |
10400 | which appear only with optimization turned on, but there have also been | |
10401 | bugs which show up only in @emph{unoptimized} code. Selecting a lower | |
10402 | level of optimization does not improve the reliability of the code | |
10403 | generator, which in practice is highly reliable at all optimization | |
10404 | levels. | |
88e1739c | 10405 | |
7cd4527e AC |
10406 | Note regarding the use of @option{-O3}: The use of this optimization level |
10407 | is generally discouraged with GNAT, since it often results in larger | |
9d983bbf | 10408 | executables which may run more slowly. See further discussion of this point |
984a64bc | 10409 | in @ref{Inlining of Subprograms}. |
88e1739c | 10410 | |
7cd4527e AC |
10411 | @node Debugging Optimized Code |
10412 | @subsection Debugging Optimized Code | |
10413 | @cindex Debugging optimized code | |
10414 | @cindex Optimization and debugging | |
10415 | ||
10416 | @noindent | |
10417 | Although it is possible to do a reasonable amount of debugging at | |
88e1739c | 10418 | @ifclear vms |
ce2e12c2 | 10419 | nonzero optimization levels, |
7cd4527e | 10420 | the higher the level the more likely that |
88e1739c | 10421 | @end ifclear |
88e1739c | 10422 | @ifset vms |
7cd4527e AC |
10423 | @option{/OPTIMIZE} settings other than @code{NONE}, |
10424 | such settings will make it more likely that | |
88e1739c | 10425 | @end ifset |
7cd4527e AC |
10426 | source-level constructs will have been eliminated by optimization. |
10427 | For example, if a loop is strength-reduced, the loop | |
10428 | control variable may be completely eliminated and thus cannot be | |
10429 | displayed in the debugger. | |
10430 | This can only happen at @option{-O2} or @option{-O3}. | |
10431 | Explicit temporary variables that you code might be eliminated at | |
10432 | ^level^setting^ @option{-O1} or higher. | |
10433 | ||
10434 | The use of the @option{^-g^/DEBUG^} switch, | |
984a64bc | 10435 | @cindex @option{^-g^/DEBUG^} (@command{gcc}) |
7cd4527e AC |
10436 | which is needed for source-level debugging, |
10437 | affects the size of the program executable on disk, | |
10438 | and indeed the debugging information can be quite large. | |
10439 | However, it has no effect on the generated code (and thus does not | |
10440 | degrade performance) | |
88e1739c | 10441 | |
7cd4527e AC |
10442 | Since the compiler generates debugging tables for a compilation unit before |
10443 | it performs optimizations, the optimizing transformations may invalidate some | |
10444 | of the debugging data. You therefore need to anticipate certain | |
10445 | anomalous situations that may arise while debugging optimized code. | |
10446 | These are the most common cases: | |
88e1739c | 10447 | |
7cd4527e AC |
10448 | @enumerate |
10449 | @item | |
10450 | @i{The ``hopping Program Counter'':} Repeated @code{step} or @code{next} | |
10451 | commands show | |
10452 | the PC bouncing back and forth in the code. This may result from any of | |
10453 | the following optimizations: | |
88e1739c | 10454 | |
7cd4527e AC |
10455 | @itemize @bullet |
10456 | @item | |
10457 | @i{Common subexpression elimination:} using a single instance of code for a | |
10458 | quantity that the source computes several times. As a result you | |
10459 | may not be able to stop on what looks like a statement. | |
88e1739c | 10460 | |
7cd4527e AC |
10461 | @item |
10462 | @i{Invariant code motion:} moving an expression that does not change within a | |
10463 | loop, to the beginning of the loop. | |
88e1739c | 10464 | |
7cd4527e AC |
10465 | @item |
10466 | @i{Instruction scheduling:} moving instructions so as to | |
10467 | overlap loads and stores (typically) with other code, or in | |
10468 | general to move computations of values closer to their uses. Often | |
10469 | this causes you to pass an assignment statement without the assignment | |
10470 | happening and then later bounce back to the statement when the | |
10471 | value is actually needed. Placing a breakpoint on a line of code | |
10472 | and then stepping over it may, therefore, not always cause all the | |
10473 | expected side-effects. | |
10474 | @end itemize | |
88e1739c | 10475 | |
7cd4527e AC |
10476 | @item |
10477 | @i{The ``big leap'':} More commonly known as @emph{cross-jumping}, in which | |
10478 | two identical pieces of code are merged and the program counter suddenly | |
10479 | jumps to a statement that is not supposed to be executed, simply because | |
10480 | it (and the code following) translates to the same thing as the code | |
10481 | that @emph{was} supposed to be executed. This effect is typically seen in | |
10482 | sequences that end in a jump, such as a @code{goto}, a @code{return}, or | |
10483 | a @code{break} in a C @code{^switch^switch^} statement. | |
88e1739c | 10484 | |
7cd4527e AC |
10485 | @item |
10486 | @i{The ``roving variable'':} The symptom is an unexpected value in a variable. | |
10487 | There are various reasons for this effect: | |
88e1739c | 10488 | |
7cd4527e AC |
10489 | @itemize @bullet |
10490 | @item | |
10491 | In a subprogram prologue, a parameter may not yet have been moved to its | |
10492 | ``home''. | |
88e1739c | 10493 | |
7cd4527e AC |
10494 | @item |
10495 | A variable may be dead, and its register re-used. This is | |
10496 | probably the most common cause. | |
88e1739c | 10497 | |
7cd4527e AC |
10498 | @item |
10499 | As mentioned above, the assignment of a value to a variable may | |
10500 | have been moved. | |
88e1739c | 10501 | |
7cd4527e AC |
10502 | @item |
10503 | A variable may be eliminated entirely by value propagation or | |
10504 | other means. In this case, GCC may incorrectly generate debugging | |
10505 | information for the variable | |
10506 | @end itemize | |
88e1739c FW |
10507 | |
10508 | @noindent | |
7cd4527e AC |
10509 | In general, when an unexpected value appears for a local variable or parameter |
10510 | you should first ascertain if that value was actually computed by | |
10511 | your program, as opposed to being incorrectly reported by the debugger. | |
10512 | Record fields or | |
10513 | array elements in an object designated by an access value | |
10514 | are generally less of a problem, once you have ascertained that the access | |
10515 | value is sensible. | |
10516 | Typically, this means checking variables in the preceding code and in the | |
10517 | calling subprogram to verify that the value observed is explainable from other | |
10518 | values (one must apply the procedure recursively to those | |
10519 | other values); or re-running the code and stopping a little earlier | |
10520 | (perhaps before the call) and stepping to better see how the variable obtained | |
10521 | the value in question; or continuing to step @emph{from} the point of the | |
10522 | strange value to see if code motion had simply moved the variable's | |
10523 | assignments later. | |
10524 | @end enumerate | |
88e1739c | 10525 | |
7cd4527e AC |
10526 | @noindent |
10527 | In light of such anomalies, a recommended technique is to use @option{-O0} | |
10528 | early in the software development cycle, when extensive debugging capabilities | |
10529 | are most needed, and then move to @option{-O1} and later @option{-O2} as | |
10530 | the debugger becomes less critical. | |
10531 | Whether to use the @option{^-g^/DEBUG^} switch in the release version is | |
10532 | a release management issue. | |
10533 | @ifclear vms | |
10534 | Note that if you use @option{-g} you can then use the @command{strip} program | |
10535 | on the resulting executable, | |
10536 | which removes both debugging information and global symbols. | |
10537 | @end ifclear | |
88e1739c | 10538 | |
7cd4527e AC |
10539 | @node Inlining of Subprograms |
10540 | @subsection Inlining of Subprograms | |
88e1739c FW |
10541 | |
10542 | @noindent | |
7cd4527e AC |
10543 | A call to a subprogram in the current unit is inlined if all the |
10544 | following conditions are met: | |
88e1739c | 10545 | |
7cd4527e AC |
10546 | @itemize @bullet |
10547 | @item | |
10548 | The optimization level is at least @option{-O1}. | |
88e1739c | 10549 | |
7cd4527e AC |
10550 | @item |
10551 | The called subprogram is suitable for inlining: It must be small enough | |
1a5f40e1 VC |
10552 | and not contain something that @command{gcc} cannot support in inlined |
10553 | subprograms. | |
88e1739c | 10554 | |
7cd4527e AC |
10555 | @item |
10556 | @cindex pragma Inline | |
10557 | @findex Inline | |
1928f450 AC |
10558 | Any one of the following applies: @code{pragma Inline} is applied to the |
10559 | subprogram and the @option{^-gnatn^/INLINE^} switch is specified; the | |
10560 | subprogram is local to the unit and called once from within it; the | |
10561 | subprogram is small and optimization level @option{-O2} is specified; | |
586ecbf3 | 10562 | optimization level @option{-O3} is specified. |
7cd4527e | 10563 | @end itemize |
88e1739c FW |
10564 | |
10565 | @noindent | |
7cd4527e | 10566 | Calls to subprograms in @code{with}'ed units are normally not inlined. |
ba1cbfb9 | 10567 | To achieve actual inlining (that is, replacement of the call by the code |
586ecbf3 | 10568 | in the body of the subprogram), the following conditions must all be true: |
88e1739c | 10569 | |
7cd4527e AC |
10570 | @itemize @bullet |
10571 | @item | |
10572 | The optimization level is at least @option{-O1}. | |
88e1739c | 10573 | |
7cd4527e AC |
10574 | @item |
10575 | The called subprogram is suitable for inlining: It must be small enough | |
1a5f40e1 VC |
10576 | and not contain something that @command{gcc} cannot support in inlined |
10577 | subprograms. | |
88e1739c | 10578 | |
7cd4527e AC |
10579 | @item |
10580 | The call appears in a body (not in a package spec). | |
88e1739c | 10581 | |
7cd4527e AC |
10582 | @item |
10583 | There is a @code{pragma Inline} for the subprogram. | |
88e1739c | 10584 | |
7cd4527e | 10585 | @item |
a3f2babd | 10586 | The @option{^-gnatn^/INLINE^} switch is used on the command line. |
7cd4527e | 10587 | @end itemize |
88e1739c | 10588 | |
ba1cbfb9 RD |
10589 | Even if all these conditions are met, it may not be possible for |
10590 | the compiler to inline the call, due to the length of the body, | |
10591 | or features in the body that make it impossible for the compiler | |
10592 | to do the inlining. | |
10593 | ||
7cd4527e AC |
10594 | Note that specifying the @option{-gnatn} switch causes additional |
10595 | compilation dependencies. Consider the following: | |
88e1739c | 10596 | |
7cd4527e AC |
10597 | @smallexample @c ada |
10598 | @cartouche | |
10599 | package R is | |
10600 | procedure Q; | |
10601 | pragma Inline (Q); | |
10602 | end R; | |
10603 | package body R is | |
d488f6ea | 10604 | @dots{} |
7cd4527e | 10605 | end R; |
88e1739c | 10606 | |
7cd4527e AC |
10607 | with R; |
10608 | procedure Main is | |
10609 | begin | |
d488f6ea | 10610 | @dots{} |
7cd4527e AC |
10611 | R.Q; |
10612 | end Main; | |
10613 | @end cartouche | |
10614 | @end smallexample | |
88e1739c FW |
10615 | |
10616 | @noindent | |
7cd4527e AC |
10617 | With the default behavior (no @option{-gnatn} switch specified), the |
10618 | compilation of the @code{Main} procedure depends only on its own source, | |
10619 | @file{main.adb}, and the spec of the package in file @file{r.ads}. This | |
10620 | means that editing the body of @code{R} does not require recompiling | |
10621 | @code{Main}. | |
88e1739c | 10622 | |
7cd4527e AC |
10623 | On the other hand, the call @code{R.Q} is not inlined under these |
10624 | circumstances. If the @option{-gnatn} switch is present when @code{Main} | |
10625 | is compiled, the call will be inlined if the body of @code{Q} is small | |
10626 | enough, but now @code{Main} depends on the body of @code{R} in | |
10627 | @file{r.adb} as well as on the spec. This means that if this body is edited, | |
10628 | the main program must be recompiled. Note that this extra dependency | |
984a64bc | 10629 | occurs whether or not the call is in fact inlined by @command{gcc}. |
88e1739c | 10630 | |
7cd4527e AC |
10631 | The use of front end inlining with @option{-gnatN} generates similar |
10632 | additional dependencies. | |
88e1739c | 10633 | |
984a64bc | 10634 | @cindex @option{^-fno-inline^/INLINE=SUPPRESS^} (@command{gcc}) |
7cd4527e AC |
10635 | Note: The @option{^-fno-inline^/INLINE=SUPPRESS^} switch |
10636 | can be used to prevent | |
10637 | all inlining. This switch overrides all other conditions and ensures | |
10638 | that no inlining occurs. The extra dependences resulting from | |
10639 | @option{-gnatn} will still be active, even if | |
10640 | this switch is used to suppress the resulting inlining actions. | |
88e1739c | 10641 | |
1a5f40e1 VC |
10642 | @cindex @option{-fno-inline-functions} (@command{gcc}) |
10643 | Note: The @option{-fno-inline-functions} switch can be used to prevent | |
9d983bbf AC |
10644 | automatic inlining of subprograms if @option{-O3} is used. |
10645 | ||
10646 | @cindex @option{-fno-inline-small-functions} (@command{gcc}) | |
10647 | Note: The @option{-fno-inline-small-functions} switch can be used to prevent | |
10648 | automatic inlining of small subprograms if @option{-O2} is used. | |
1a5f40e1 VC |
10649 | |
10650 | @cindex @option{-fno-inline-functions-called-once} (@command{gcc}) | |
10651 | Note: The @option{-fno-inline-functions-called-once} switch | |
10652 | can be used to prevent inlining of subprograms local to the unit | |
10653 | and called once from within it if @option{-O1} is used. | |
10654 | ||
21791d97 AC |
10655 | Note regarding the use of @option{-O3}: @option{-gnatn} is made up of two |
10656 | sub-switches @option{-gnatn1} and @option{-gnatn2} that can be directly | |
10657 | specified in lieu of it, @option{-gnatn} being translated into one of them | |
10658 | based on the optimization level. With @option{-O2} or below, @option{-gnatn} | |
10659 | is equivalent to @option{-gnatn1} which activates pragma @code{Inline} with | |
10660 | moderate inlining across modules. With @option{-O3}, @option{-gnatn} is | |
10661 | equivalent to @option{-gnatn2} which activates pragma @code{Inline} with | |
10662 | full inlining across modules. If you have used pragma @code{Inline} in appropriate cases, then it is usually much better to use @option{-O2} and @option{-gnatn} and avoid the use of @option{-O3} which has the additional | |
10663 | effect of inlining subprograms you did not think should be inlined. We have | |
10664 | found that the use of @option{-O3} may slow down the compilation and increase | |
10665 | the code size by performing excessive inlining, leading to increased | |
10666 | instruction cache pressure from the increased code size and thus minor | |
10667 | performance improvements. So the bottom line here is that you should not | |
10668 | automatically assume that @option{-O3} is better than @option{-O2}, and | |
10669 | indeed you should use @option{-O3} only if tests show that it actually | |
10670 | improves performance for your program. | |
88e1739c | 10671 | |
8daa1407 EB |
10672 | @node Vectorization of loops |
10673 | @subsection Vectorization of loops | |
10674 | @cindex Optimization Switches | |
10675 | ||
10676 | You can take advantage of the auto-vectorizer present in the @command{gcc} | |
10677 | back end to vectorize loops with GNAT. The corresponding command line switch | |
10678 | is @option{-ftree-vectorize} but, as it is enabled by default at @option{-O3} | |
10679 | and other aggressive optimizations helpful for vectorization also are enabled | |
10680 | by default at this level, using @option{-O3} directly is recommended. | |
10681 | ||
10682 | You also need to make sure that the target architecture features a supported | |
10683 | SIMD instruction set. For example, for the x86 architecture, you should at | |
10684 | least specify @option{-msse2} to get significant vectorization (but you don't | |
10685 | need to specify it for x86-64 as it is part of the base 64-bit architecture). | |
10686 | Similarly, for the PowerPC architecture, you should specify @option{-maltivec}. | |
10687 | ||
10688 | The preferred loop form for vectorization is the @code{for} iteration scheme. | |
10689 | Loops with a @code{while} iteration scheme can also be vectorized if they are | |
10690 | very simple, but the vectorizer will quickly give up otherwise. With either | |
10691 | iteration scheme, the flow of control must be straight, in particular no | |
10692 | @code{exit} statement may appear in the loop body. The loop may however | |
10693 | contain a single nested loop, if it can be vectorized when considered alone: | |
10694 | ||
10695 | @smallexample @c ada | |
10696 | @cartouche | |
10697 | A : array (1..4, 1..4) of Long_Float; | |
10698 | S : array (1..4) of Long_Float; | |
10699 | ||
10700 | procedure Sum is | |
10701 | begin | |
10702 | for I in A'Range(1) loop | |
10703 | for J in A'Range(2) loop | |
10704 | S (I) := S (I) + A (I, J); | |
10705 | end loop; | |
10706 | end loop; | |
10707 | end Sum; | |
10708 | @end cartouche | |
10709 | @end smallexample | |
10710 | ||
10711 | The vectorizable operations depend on the targeted SIMD instruction set, but | |
10712 | the adding and some of the multiplying operators are generally supported, as | |
10713 | well as the logical operators for modular types. Note that, in the former | |
10714 | case, enabling overflow checks, for example with @option{-gnato}, totally | |
10715 | disables vectorization. The other checks are not supposed to have the same | |
10716 | definitive effect, although compiling with @option{-gnatp} might well reveal | |
10717 | cases where some checks do thwart vectorization. | |
10718 | ||
10719 | Type conversions may also prevent vectorization if they involve semantics that | |
10720 | are not directly supported by the code generator or the SIMD instruction set. | |
10721 | A typical example is direct conversion from floating-point to integer types. | |
10722 | The solution in this case is to use the following idiom: | |
10723 | ||
10724 | @smallexample @c ada | |
10725 | Integer (S'Truncation (F)) | |
10726 | @end smallexample | |
10727 | ||
10728 | @noindent | |
10729 | if @code{S} is the subtype of floating-point object @code{F}. | |
10730 | ||
10731 | In most cases, the vectorizable loops are loops that iterate over arrays. | |
10732 | All kinds of array types are supported, i.e. constrained array types with | |
10733 | static bounds: | |
10734 | ||
10735 | @smallexample @c ada | |
10736 | type Array_Type is array (1 .. 4) of Long_Float; | |
10737 | @end smallexample | |
10738 | ||
10739 | @noindent | |
10740 | constrained array types with dynamic bounds: | |
10741 | ||
10742 | @smallexample @c ada | |
10743 | type Array_Type is array (1 .. Q.N) of Long_Float; | |
10744 | ||
10745 | type Array_Type is array (Q.K .. 4) of Long_Float; | |
10746 | ||
10747 | type Array_Type is array (Q.K .. Q.N) of Long_Float; | |
10748 | @end smallexample | |
10749 | ||
10750 | @noindent | |
10751 | or unconstrained array types: | |
10752 | ||
10753 | @smallexample @c ada | |
10754 | type Array_Type is array (Positive range <>) of Long_Float; | |
10755 | @end smallexample | |
10756 | ||
10757 | @noindent | |
10758 | The quality of the generated code decreases when the dynamic aspect of the | |
10759 | array type increases, the worst code being generated for unconstrained array | |
10760 | types. This is so because, the less information the compiler has about the | |
10761 | bounds of the array, the more fallback code it needs to generate in order to | |
10762 | fix things up at run time. | |
10763 | ||
a75ea295 EB |
10764 | It is possible to specify that a given loop should be subject to vectorization |
10765 | preferably to other optimizations by means of pragma @code{Loop_Optimize}: | |
10766 | ||
10767 | @smallexample @c ada | |
10768 | pragma Loop_Optimize (Vector); | |
10769 | @end smallexample | |
10770 | ||
10771 | @noindent | |
10772 | placed immediately within the loop will convey the appropriate hint to the | |
10773 | compiler for this loop. | |
10774 | ||
c1cd0d96 RD |
10775 | @node Other Optimization Switches |
10776 | @subsection Other Optimization Switches | |
10777 | @cindex Optimization Switches | |
10778 | ||
1992bbd9 RW |
10779 | Since @code{GNAT} uses the @command{gcc} back end, all the specialized |
10780 | @command{gcc} optimization switches are potentially usable. These switches | |
c1cd0d96 | 10781 | have not been extensively tested with GNAT but can generally be expected |
8daa1407 EB |
10782 | to work. Examples of switches in this category are @option{-funroll-loops} |
10783 | and the various target-specific @option{-m} options (in particular, it has | |
10784 | been observed that @option{-march=xxx} can significantly improve performance | |
b2e74434 RW |
10785 | on appropriate machines). For full details of these switches, see |
10786 | @ref{Submodel Options,, Hardware Models and Configurations, gcc, Using | |
10787 | the GNU Compiler Collection (GCC)}. | |
c1cd0d96 | 10788 | |
7cd4527e AC |
10789 | @node Optimization and Strict Aliasing |
10790 | @subsection Optimization and Strict Aliasing | |
10791 | @cindex Aliasing | |
10792 | @cindex Strict Aliasing | |
10793 | @cindex No_Strict_Aliasing | |
88e1739c | 10794 | |
7cd4527e AC |
10795 | @noindent |
10796 | The strong typing capabilities of Ada allow an optimizer to generate | |
10797 | efficient code in situations where other languages would be forced to | |
10798 | make worst case assumptions preventing such optimizations. Consider | |
10799 | the following example: | |
88e1739c | 10800 | |
7cd4527e AC |
10801 | @smallexample @c ada |
10802 | @cartouche | |
10803 | procedure R is | |
10804 | type Int1 is new Integer; | |
10805 | type Int2 is new Integer; | |
10806 | type Int1A is access Int1; | |
10807 | type Int2A is access Int2; | |
10808 | Int1V : Int1A; | |
10809 | Int2V : Int2A; | |
d488f6ea | 10810 | @dots{} |
88e1739c | 10811 | |
7cd4527e | 10812 | begin |
d488f6ea | 10813 | @dots{} |
7cd4527e AC |
10814 | for J in Data'Range loop |
10815 | if Data (J) = Int1V.all then | |
10816 | Int2V.all := Int2V.all + 1; | |
10817 | end if; | |
10818 | end loop; | |
d488f6ea | 10819 | @dots{} |
7cd4527e AC |
10820 | end R; |
10821 | @end cartouche | |
88e1739c FW |
10822 | @end smallexample |
10823 | ||
7cd4527e AC |
10824 | @noindent |
10825 | In this example, since the variable @code{Int1V} can only access objects | |
10826 | of type @code{Int1}, and @code{Int2V} can only access objects of type | |
10827 | @code{Int2}, there is no possibility that the assignment to | |
10828 | @code{Int2V.all} affects the value of @code{Int1V.all}. This means that | |
10829 | the compiler optimizer can "know" that the value @code{Int1V.all} is constant | |
10830 | for all iterations of the loop and avoid the extra memory reference | |
10831 | required to dereference it each time through the loop. | |
88e1739c | 10832 | |
bde83138 | 10833 | This kind of optimization, called strict aliasing analysis, is |
7cd4527e | 10834 | triggered by specifying an optimization level of @option{-O2} or |
d9c0e057 | 10835 | higher or @option{-Os} and allows @code{GNAT} to generate more efficient code |
7cd4527e | 10836 | when access values are involved. |
88e1739c | 10837 | |
7cd4527e AC |
10838 | However, although this optimization is always correct in terms of |
10839 | the formal semantics of the Ada Reference Manual, difficulties can | |
10840 | arise if features like @code{Unchecked_Conversion} are used to break | |
10841 | the typing system. Consider the following complete program example: | |
88e1739c | 10842 | |
7cd4527e AC |
10843 | @smallexample @c ada |
10844 | @cartouche | |
10845 | package p1 is | |
10846 | type int1 is new integer; | |
10847 | type int2 is new integer; | |
10848 | type a1 is access int1; | |
10849 | type a2 is access int2; | |
10850 | end p1; | |
10851 | ||
10852 | with p1; use p1; | |
10853 | package p2 is | |
10854 | function to_a2 (Input : a1) return a2; | |
10855 | end p2; | |
10856 | ||
10857 | with Unchecked_Conversion; | |
10858 | package body p2 is | |
10859 | function to_a2 (Input : a1) return a2 is | |
10860 | function to_a2u is | |
10861 | new Unchecked_Conversion (a1, a2); | |
10862 | begin | |
10863 | return to_a2u (Input); | |
10864 | end to_a2; | |
10865 | end p2; | |
88e1739c | 10866 | |
7cd4527e AC |
10867 | with p2; use p2; |
10868 | with p1; use p1; | |
10869 | with Text_IO; use Text_IO; | |
10870 | procedure m is | |
10871 | v1 : a1 := new int1; | |
10872 | v2 : a2 := to_a2 (v1); | |
10873 | begin | |
10874 | v1.all := 1; | |
10875 | v2.all := 0; | |
10876 | put_line (int1'image (v1.all)); | |
10877 | end; | |
10878 | @end cartouche | |
10879 | @end smallexample | |
88e1739c | 10880 | |
7cd4527e | 10881 | @noindent |
1992bbd9 RW |
10882 | This program prints out 0 in @option{-O0} or @option{-O1} |
10883 | mode, but it prints out 1 in @option{-O2} mode. That's | |
7cd4527e AC |
10884 | because in strict aliasing mode, the compiler can and |
10885 | does assume that the assignment to @code{v2.all} could not | |
10886 | affect the value of @code{v1.all}, since different types | |
10887 | are involved. | |
88e1739c | 10888 | |
7cd4527e AC |
10889 | This behavior is not a case of non-conformance with the standard, since |
10890 | the Ada RM specifies that an unchecked conversion where the resulting | |
10891 | bit pattern is not a correct value of the target type can result in an | |
10892 | abnormal value and attempting to reference an abnormal value makes the | |
10893 | execution of a program erroneous. That's the case here since the result | |
10894 | does not point to an object of type @code{int2}. This means that the | |
10895 | effect is entirely unpredictable. | |
10896 | ||
10897 | However, although that explanation may satisfy a language | |
10898 | lawyer, in practice an applications programmer expects an | |
10899 | unchecked conversion involving pointers to create true | |
10900 | aliases and the behavior of printing 1 seems plain wrong. | |
10901 | In this case, the strict aliasing optimization is unwelcome. | |
10902 | ||
10903 | Indeed the compiler recognizes this possibility, and the | |
10904 | unchecked conversion generates a warning: | |
10905 | ||
10906 | @smallexample | |
10907 | p2.adb:5:07: warning: possible aliasing problem with type "a2" | |
10908 | p2.adb:5:07: warning: use -fno-strict-aliasing switch for references | |
10909 | p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);" | |
10910 | @end smallexample | |
10911 | ||
10912 | @noindent | |
10913 | Unfortunately the problem is recognized when compiling the body of | |
10914 | package @code{p2}, but the actual "bad" code is generated while | |
10915 | compiling the body of @code{m} and this latter compilation does not see | |
10916 | the suspicious @code{Unchecked_Conversion}. | |
10917 | ||
10918 | As implied by the warning message, there are approaches you can use to | |
10919 | avoid the unwanted strict aliasing optimization in a case like this. | |
10920 | ||
1992bbd9 | 10921 | One possibility is to simply avoid the use of @option{-O2}, but |
7cd4527e AC |
10922 | that is a bit drastic, since it throws away a number of useful |
10923 | optimizations that do not involve strict aliasing assumptions. | |
10924 | ||
10925 | A less drastic approach is to compile the program using the | |
1992bbd9 | 10926 | option @option{-fno-strict-aliasing}. Actually it is only the |
7cd4527e AC |
10927 | unit containing the dereferencing of the suspicious pointer |
10928 | that needs to be compiled. So in this case, if we compile | |
10929 | unit @code{m} with this switch, then we get the expected | |
10930 | value of zero printed. Analyzing which units might need | |
10931 | the switch can be painful, so a more reasonable approach | |
1992bbd9 RW |
10932 | is to compile the entire program with options @option{-O2} |
10933 | and @option{-fno-strict-aliasing}. If the performance is | |
7cd4527e AC |
10934 | satisfactory with this combination of options, then the |
10935 | advantage is that the entire issue of possible "wrong" | |
10936 | optimization due to strict aliasing is avoided. | |
10937 | ||
10938 | To avoid the use of compiler switches, the configuration | |
10939 | pragma @code{No_Strict_Aliasing} with no parameters may be | |
10940 | used to specify that for all access types, the strict | |
10941 | aliasing optimization should be suppressed. | |
10942 | ||
10943 | However, these approaches are still overkill, in that they causes | |
10944 | all manipulations of all access values to be deoptimized. A more | |
10945 | refined approach is to concentrate attention on the specific | |
10946 | access type identified as problematic. | |
10947 | ||
10948 | First, if a careful analysis of uses of the pointer shows | |
10949 | that there are no possible problematic references, then | |
10950 | the warning can be suppressed by bracketing the | |
10951 | instantiation of @code{Unchecked_Conversion} to turn | |
10952 | the warning off: | |
10953 | ||
10954 | @smallexample @c ada | |
10955 | pragma Warnings (Off); | |
10956 | function to_a2u is | |
10957 | new Unchecked_Conversion (a1, a2); | |
10958 | pragma Warnings (On); | |
10959 | @end smallexample | |
10960 | ||
10961 | @noindent | |
10962 | Of course that approach is not appropriate for this particular | |
10963 | example, since indeed there is a problematic reference. In this | |
10964 | case we can take one of two other approaches. | |
10965 | ||
10966 | The first possibility is to move the instantiation of unchecked | |
10967 | conversion to the unit in which the type is declared. In | |
10968 | this example, we would move the instantiation of | |
10969 | @code{Unchecked_Conversion} from the body of package | |
10970 | @code{p2} to the spec of package @code{p1}. Now the | |
10971 | warning disappears. That's because any use of the | |
10972 | access type knows there is a suspicious unchecked | |
10973 | conversion, and the strict aliasing optimization | |
10974 | is automatically suppressed for the type. | |
10975 | ||
10976 | If it is not practical to move the unchecked conversion to the same unit | |
10977 | in which the destination access type is declared (perhaps because the | |
10978 | source type is not visible in that unit), you may use pragma | |
10979 | @code{No_Strict_Aliasing} for the type. This pragma must occur in the | |
10980 | same declarative sequence as the declaration of the access type: | |
10981 | ||
10982 | @smallexample @c ada | |
10983 | type a2 is access int2; | |
10984 | pragma No_Strict_Aliasing (a2); | |
10985 | @end smallexample | |
10986 | ||
10987 | @noindent | |
10988 | Here again, the compiler now knows that the strict aliasing optimization | |
10989 | should be suppressed for any reference to type @code{a2} and the | |
10990 | expected behavior is obtained. | |
10991 | ||
10992 | Finally, note that although the compiler can generate warnings for | |
10993 | simple cases of unchecked conversions, there are tricker and more | |
10994 | indirect ways of creating type incorrect aliases which the compiler | |
10995 | cannot detect. Examples are the use of address overlays and unchecked | |
10996 | conversions involving composite types containing access types as | |
10997 | components. In such cases, no warnings are generated, but there can | |
10998 | still be aliasing problems. One safe coding practice is to forbid the | |
10999 | use of address clauses for type overlaying, and to allow unchecked | |
11000 | conversion only for primitive types. This is not really a significant | |
11001 | restriction since any possible desired effect can be achieved by | |
11002 | unchecked conversion of access values. | |
88e1739c | 11003 | |
d9c0e057 AC |
11004 | The aliasing analysis done in strict aliasing mode can certainly |
11005 | have significant benefits. We have seen cases of large scale | |
11006 | application code where the time is increased by up to 5% by turning | |
11007 | this optimization off. If you have code that includes significant | |
11008 | usage of unchecked conversion, you might want to just stick with | |
11009 | @option{-O1} and avoid the entire issue. If you get adequate | |
11010 | performance at this level of optimization level, that's probably | |
11011 | the safest approach. If tests show that you really need higher | |
11012 | levels of optimization, then you can experiment with @option{-O2} | |
11013 | and @option{-O2 -fno-strict-aliasing} to see how much effect this | |
11014 | has on size and speed of the code. If you really need to use | |
11015 | @option{-O2} with strict aliasing in effect, then you should | |
11016 | review any uses of unchecked conversion of access types, | |
11017 | particularly if you are getting the warnings described above. | |
11018 | ||
124092ee AC |
11019 | @node Aliased Variables and Optimization |
11020 | @subsection Aliased Variables and Optimization | |
11021 | @cindex Aliasing | |
11022 | There are scenarios in which programs may | |
11023 | use low level techniques to modify variables | |
11024 | that otherwise might be considered to be unassigned. For example, | |
11025 | a variable can be passed to a procedure by reference, which takes | |
11026 | the address of the parameter and uses the address to modify the | |
11027 | variable's value, even though it is passed as an IN parameter. | |
11028 | Consider the following example: | |
11029 | ||
11030 | @smallexample @c ada | |
11031 | procedure P is | |
11032 | Max_Length : constant Natural := 16; | |
11033 | type Char_Ptr is access all Character; | |
11034 | ||
11035 | procedure Get_String(Buffer: Char_Ptr; Size : Integer); | |
11036 | pragma Import (C, Get_String, "get_string"); | |
11037 | ||
11038 | Name : aliased String (1 .. Max_Length) := (others => ' '); | |
11039 | Temp : Char_Ptr; | |
11040 | ||
11041 | function Addr (S : String) return Char_Ptr is | |
11042 | function To_Char_Ptr is | |
11043 | new Ada.Unchecked_Conversion (System.Address, Char_Ptr); | |
11044 | begin | |
11045 | return To_Char_Ptr (S (S'First)'Address); | |
11046 | end; | |
11047 | ||
11048 | begin | |
11049 | Temp := Addr (Name); | |
11050 | Get_String (Temp, Max_Length); | |
11051 | end; | |
11052 | @end smallexample | |
11053 | ||
11054 | @noindent | |
11055 | where Get_String is a C function that uses the address in Temp to | |
11056 | modify the variable @code{Name}. This code is dubious, and arguably | |
11057 | erroneous, and the compiler would be entitled to assume that | |
11058 | @code{Name} is never modified, and generate code accordingly. | |
11059 | ||
11060 | However, in practice, this would cause some existing code that | |
11061 | seems to work with no optimization to start failing at high | |
11062 | levels of optimzization. | |
11063 | ||
11064 | What the compiler does for such cases is to assume that marking | |
11065 | a variable as aliased indicates that some "funny business" may | |
11066 | be going on. The optimizer recognizes the aliased keyword and | |
11067 | inhibits optimizations that assume the value cannot be assigned. | |
11068 | This means that the above example will in fact "work" reliably, | |
11069 | that is, it will produce the expected results. | |
11070 | ||
d0e69402 RD |
11071 | @node Atomic Variables and Optimization |
11072 | @subsection Atomic Variables and Optimization | |
11073 | @cindex Atomic | |
11074 | There are two considerations with regard to performance when | |
11075 | atomic variables are used. | |
11076 | ||
11077 | First, the RM only guarantees that access to atomic variables | |
11078 | be atomic, it has nothing to say about how this is achieved, | |
11079 | though there is a strong implication that this should not be | |
11080 | achieved by explicit locking code. Indeed GNAT will never | |
11081 | generate any locking code for atomic variable access (it will | |
11082 | simply reject any attempt to make a variable or type atomic | |
11083 | if the atomic access cannot be achieved without such locking code). | |
11084 | ||
11085 | That being said, it is important to understand that you cannot | |
11086 | assume that the entire variable will always be accessed. Consider | |
11087 | this example: | |
11088 | ||
11089 | @smallexample @c ada | |
11090 | type R is record | |
11091 | A,B,C,D : Character; | |
11092 | end record; | |
11093 | for R'Size use 32; | |
11094 | for R'Alignment use 4; | |
11095 | ||
11096 | RV : R; | |
11097 | pragma Atomic (RV); | |
11098 | X : Character; | |
11099 | ... | |
11100 | X := RV.B; | |
11101 | @end smallexample | |
11102 | ||
11103 | @noindent | |
11104 | You cannot assume that the reference to @code{RV.B} | |
11105 | will read the entire 32-bit | |
11106 | variable with a single load instruction. It is perfectly legitimate if | |
11107 | the hardware allows it to do a byte read of just the B field. This read | |
11108 | is still atomic, which is all the RM requires. GNAT can and does take | |
11109 | advantage of this, depending on the architecture and optimization level. | |
11110 | Any assumption to the contrary is non-portable and risky. Even if you | |
11111 | examine the assembly language and see a full 32-bit load, this might | |
11112 | change in a future version of the compiler. | |
11113 | ||
11114 | If your application requires that all accesses to @code{RV} in this | |
11115 | example be full 32-bit loads, you need to make a copy for the access | |
11116 | as in: | |
11117 | ||
11118 | @smallexample @c ada | |
11119 | declare | |
11120 | RV_Copy : constant R := RV; | |
11121 | begin | |
11122 | X := RV_Copy.B; | |
11123 | end; | |
11124 | @end smallexample | |
11125 | ||
11126 | ||
11127 | @noindent | |
11128 | Now the reference to RV must read the whole variable. | |
11129 | Actually one can imagine some compiler which figures | |
11130 | out that the whole copy is not required (because only | |
11131 | the B field is actually accessed), but GNAT | |
11132 | certainly won't do that, and we don't know of any | |
11133 | compiler that would not handle this right, and the | |
11134 | above code will in practice work portably across | |
11135 | all architectures (that permit the Atomic declaration). | |
11136 | ||
11137 | The second issue with atomic variables has to do with | |
11138 | the possible requirement of generating synchronization | |
11139 | code. For more details on this, consult the sections on | |
11140 | the pragmas Enable/Disable_Atomic_Synchronization in the | |
11141 | GNAT Reference Manual. If performance is critical, and | |
11142 | such synchronization code is not required, it may be | |
11143 | useful to disable it. | |
11144 | ||
54533a0b AC |
11145 | @node Passive Task Optimization |
11146 | @subsection Passive Task Optimization | |
11147 | @cindex Passive Task | |
11148 | ||
11149 | A passive task is one which is sufficiently simple that | |
11150 | in theory a compiler could recognize it an implement it | |
11151 | efficiently without creating a new thread. The original design | |
11152 | of Ada 83 had in mind this kind of passive task optimization, but | |
11153 | only a few Ada 83 compilers attempted it. The problem was that | |
11154 | it was difficult to determine the exact conditions under which | |
11155 | the optimization was possible. The result is a very fragile | |
11156 | optimization where a very minor change in the program can | |
11157 | suddenly silently make a task non-optimizable. | |
11158 | ||
11159 | With the revisiting of this issue in Ada 95, there was general | |
11160 | agreement that this approach was fundamentally flawed, and the | |
11161 | notion of protected types was introduced. When using protected | |
11162 | types, the restrictions are well defined, and you KNOW that the | |
11163 | operations will be optimized, and furthermore this optimized | |
11164 | performance is fully portable. | |
11165 | ||
11166 | Although it would theoretically be possible for GNAT to attempt to | |
11167 | do this optimization, but it really doesn't make sense in the | |
11168 | context of Ada 95, and none of the Ada 95 compilers implement | |
11169 | this optimization as far as we know. In particular GNAT never | |
11170 | attempts to perform this optimization. | |
11171 | ||
11172 | In any new Ada 95 code that is written, you should always | |
11173 | use protected types in place of tasks that might be able to | |
11174 | be optimized in this manner. | |
11175 | Of course this does not help if you have legacy Ada 83 code | |
11176 | that depends on this optimization, but it is unusual to encounter | |
11177 | a case where the performance gains from this optimization | |
11178 | are significant. | |
11179 | ||
11180 | Your program should work correctly without this optimization. If | |
11181 | you have performance problems, then the most practical | |
11182 | approach is to figure out exactly where these performance problems | |
11183 | arise, and update those particular tasks to be protected types. Note | |
11184 | that typically clients of the tasks who call entries, will not have | |
11185 | to be modified, only the task definition itself. | |
11186 | ||
7cd4527e AC |
11187 | @ifset vms |
11188 | @node Coverage Analysis | |
11189 | @subsection Coverage Analysis | |
88e1739c | 11190 | |
7cd4527e | 11191 | @noindent |
32e209e4 | 11192 | GNAT supports the HP Performance Coverage Analyzer (PCA), which allows |
7cd4527e AC |
11193 | the user to determine the distribution of execution time across a program, |
11194 | @pxref{Profiling} for details of usage. | |
11195 | @end ifset | |
11196 | ||
1a5f40e1 VC |
11197 | |
11198 | @node Text_IO Suggestions | |
11199 | @section @code{Text_IO} Suggestions | |
11200 | @cindex @code{Text_IO} and performance | |
11201 | ||
11202 | @noindent | |
11203 | The @code{Ada.Text_IO} package has fairly high overheads due in part to | |
11204 | the requirement of maintaining page and line counts. If performance | |
11205 | is critical, a recommendation is to use @code{Stream_IO} instead of | |
11206 | @code{Text_IO} for volume output, since this package has less overhead. | |
11207 | ||
11208 | If @code{Text_IO} must be used, note that by default output to the standard | |
11209 | output and standard error files is unbuffered (this provides better | |
11210 | behavior when output statements are used for debugging, or if the | |
11211 | progress of a program is observed by tracking the output, e.g. by | |
11212 | using the Unix @command{tail -f} command to watch redirected output. | |
11213 | ||
11214 | If you are generating large volumes of output with @code{Text_IO} and | |
11215 | performance is an important factor, use a designated file instead | |
11216 | of the standard output file, or change the standard output file to | |
11217 | be buffered using @code{Interfaces.C_Streams.setvbuf}. | |
11218 | ||
11219 | ||
1037b0f4 | 11220 | @ifclear FSFEDITION |
ba1cbfb9 RD |
11221 | @node Reducing Size of Ada Executables with gnatelim |
11222 | @section Reducing Size of Ada Executables with @code{gnatelim} | |
7cd4527e | 11223 | @findex gnatelim |
88e1739c FW |
11224 | |
11225 | @noindent | |
7cd4527e AC |
11226 | This section describes @command{gnatelim}, a tool which detects unused |
11227 | subprograms and helps the compiler to create a smaller executable for your | |
11228 | program. | |
88e1739c FW |
11229 | |
11230 | @menu | |
7cd4527e AC |
11231 | * About gnatelim:: |
11232 | * Running gnatelim:: | |
395993ce | 11233 | * Processing Precompiled Libraries:: |
7cd4527e AC |
11234 | * Correcting the List of Eliminate Pragmas:: |
11235 | * Making Your Executables Smaller:: | |
11236 | * Summary of the gnatelim Usage Cycle:: | |
88e1739c FW |
11237 | @end menu |
11238 | ||
7cd4527e AC |
11239 | @node About gnatelim |
11240 | @subsection About @code{gnatelim} | |
88e1739c FW |
11241 | |
11242 | @noindent | |
7cd4527e AC |
11243 | When a program shares a set of Ada |
11244 | packages with other programs, it may happen that this program uses | |
11245 | only a fraction of the subprograms defined in these packages. The code | |
11246 | created for these unused subprograms increases the size of the executable. | |
88e1739c | 11247 | |
7cd4527e AC |
11248 | @code{gnatelim} tracks unused subprograms in an Ada program and |
11249 | outputs a list of GNAT-specific pragmas @code{Eliminate} marking all the | |
11250 | subprograms that are declared but never called. By placing the list of | |
11251 | @code{Eliminate} pragmas in the GNAT configuration file @file{gnat.adc} and | |
11252 | recompiling your program, you may decrease the size of its executable, | |
11253 | because the compiler will not generate the code for 'eliminated' subprograms. | |
b2e74434 RW |
11254 | @xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more |
11255 | information about this pragma. | |
88e1739c | 11256 | |
395993ce | 11257 | @code{gnatelim} needs as its input data the name of the main subprogram. |
88e1739c | 11258 | |
395993ce SR |
11259 | If a set of source files is specified as @code{gnatelim} arguments, it |
11260 | treats these files as a complete set of sources making up a program to | |
11261 | analyse, and analyses only these sources. | |
11262 | ||
11263 | After a full successful build of the main subprogram @code{gnatelim} can be | |
11264 | called without specifying sources to analyse, in this case it computes | |
11265 | the source closure of the main unit from the @file{ALI} files. | |
11266 | ||
11267 | The following command will create the set of @file{ALI} files needed for | |
11268 | @code{gnatelim}: | |
88e1739c | 11269 | |
7cd4527e AC |
11270 | @smallexample |
11271 | $ gnatmake ^-c Main_Prog^/ACTIONS=COMPILE MAIN_PROG^ | |
7cd4527e AC |
11272 | @end smallexample |
11273 | ||
395993ce | 11274 | Note that @code{gnatelim} does not need object files. |
7cd4527e AC |
11275 | |
11276 | @node Running gnatelim | |
11277 | @subsection Running @code{gnatelim} | |
88e1739c FW |
11278 | |
11279 | @noindent | |
7cd4527e | 11280 | @code{gnatelim} has the following command-line interface: |
88e1739c | 11281 | |
7cd4527e | 11282 | @smallexample |
395993ce | 11283 | $ gnatelim [@var{switches}] ^-main^?MAIN^=@var{main_unit_name} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} |
7cd4527e | 11284 | @end smallexample |
88e1739c | 11285 | |
7cd4527e | 11286 | @noindent |
395993ce SR |
11287 | @var{main_unit_name} should be a name of a source file that contains the main |
11288 | subprogram of a program (partition). | |
11289 | ||
11290 | Each @var{filename} is the name (including the extension) of a source | |
11291 | file to process. ``Wildcards'' are allowed, and | |
11292 | the file name may contain path information. | |
11293 | ||
5875f8d6 | 11294 | @samp{@var{gcc_switches}} is a list of switches for |
395993ce SR |
11295 | @command{gcc}. They will be passed on to all compiler invocations made by |
11296 | @command{gnatelim} to generate the ASIS trees. Here you can provide | |
11297 | @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, | |
4b6133ea AC |
11298 | use the @option{-gnatec} switch to set the configuration file, |
11299 | use the @option{-gnat05} switch if sources should be compiled in | |
11300 | Ada 2005 mode etc. | |
88e1739c | 11301 | |
7cd4527e | 11302 | @code{gnatelim} has the following switches: |
88e1739c | 11303 | |
7cd4527e AC |
11304 | @table @option |
11305 | @c !sort! | |
327b1ba4 AC |
11306 | @item --version |
11307 | @cindex @option{--version} @command{gnatelim} | |
11308 | Display Copyright and version, then exit disregarding all other options. | |
11309 | ||
11310 | @item --help | |
11311 | @cindex @option{--help} @command{gnatelim} | |
11312 | Display usage, then exit disregarding all other options. | |
11313 | ||
350b83cc AC |
11314 | @item -P @var{file} |
11315 | @cindex @option{-P} @command{gnatelim} | |
11316 | Indicates the name of the project file that describes the set of sources | |
11317 | to be processed. | |
11318 | ||
11319 | @item -X@var{name}=@var{value} | |
11320 | @cindex @option{-X} @command{gnatelim} | |
11321 | Indicates that external variable @var{name} in the argument project | |
f1a3590e | 11322 | has the value @var{value}. Has no effect if no project is specified as |
350b83cc AC |
11323 | tool argument. |
11324 | ||
395993ce SR |
11325 | @item ^-files^/FILES^=@var{filename} |
11326 | @cindex @option{^-files^/FILES^} (@code{gnatelim}) | |
11327 | Take the argument source files from the specified file. This file should be an | |
11328 | ordinary text file containing file names separated by spaces or | |
11329 | line breaks. You can use this switch more than once in the same call to | |
11330 | @command{gnatelim}. You also can combine this switch with | |
11331 | an explicit list of files. | |
11332 | ||
11333 | @item ^-log^/LOG^ | |
11334 | @cindex @option{^-log^/LOG^} (@command{gnatelim}) | |
11335 | Duplicate all the output sent to @file{stderr} into a log file. The log file | |
11336 | is named @file{gnatelim.log} and is located in the current directory. | |
11337 | ||
350b83cc | 11338 | @ignore |
395993ce SR |
11339 | @item ^-log^/LOGFILE^=@var{filename} |
11340 | @cindex @option{^-log^/LOGFILE^} (@command{gnatelim}) | |
11341 | Duplicate all the output sent to @file{stderr} into a specified log file. | |
350b83cc | 11342 | @end ignore |
395993ce | 11343 | |
c77599d5 AC |
11344 | @cindex @option{^--no-elim-dispatch^/NO_DISPATCH^} (@command{gnatelim}) |
11345 | @item ^--no-elim-dispatch^/NO_DISPATCH^ | |
11346 | Do not generate pragmas for dispatching operations. | |
11347 | ||
b4ca2d2c AC |
11348 | @item ^--ignore^/IGNORE^=@var{filename} |
11349 | @cindex @option{^--ignore^/IGNORE^} (@command{gnatelim}) | |
11350 | Do not generate pragmas for subprograms declared in the sources | |
11351 | listed in a specified file | |
11352 | ||
395993ce SR |
11353 | @cindex @option{^-o^/OUTPUT^} (@command{gnatelim}) |
11354 | @item ^-o^/OUTPUT^=@var{report_file} | |
11355 | Put @command{gnatelim} output into a specified file. If this file already exists, | |
11356 | it is overridden. If this switch is not used, @command{gnatelim} outputs its results | |
11357 | into @file{stderr} | |
11358 | ||
8c7ff9a0 AC |
11359 | @item ^-j^/PROCESSES=^@var{n} |
11360 | @cindex @option{^-j^/PROCESSES^} (@command{gnatelim}) | |
11361 | Use @var{n} processes to carry out the tree creations (internal representations | |
11362 | of the argument sources). On a multiprocessor machine this speeds up processing | |
11363 | of big sets of argument sources. If @var{n} is 0, then the maximum number of | |
11364 | parallel tree creations is the number of core processors on the platform. | |
11365 | ||
7cd4527e AC |
11366 | @item ^-q^/QUIET^ |
11367 | @cindex @option{^-q^/QUIET^} (@command{gnatelim}) | |
11368 | Quiet mode: by default @code{gnatelim} outputs to the standard error | |
11369 | stream the number of program units left to be processed. This option turns | |
11370 | this trace off. | |
88e1739c | 11371 | |
395993ce SR |
11372 | @cindex @option{^-t^/TIME^} (@command{gnatelim}) |
11373 | @item ^-t^/TIME^ | |
11374 | Print out execution time. | |
11375 | ||
7cd4527e AC |
11376 | @item ^-v^/VERBOSE^ |
11377 | @cindex @option{^-v^/VERBOSE^} (@command{gnatelim}) | |
11378 | Verbose mode: @code{gnatelim} version information is printed as Ada | |
11379 | comments to the standard output stream. Also, in addition to the number of | |
11380 | program units left @code{gnatelim} will output the name of the current unit | |
11381 | being processed. | |
88e1739c | 11382 | |
395993ce SR |
11383 | @item ^-wq^/WARNINGS=QUIET^ |
11384 | @cindex @option{^-wq^/WARNINGS=QUIET^} (@command{gnatelim}) | |
308e6f3a | 11385 | Quiet warning mode - some warnings are suppressed. In particular warnings that |
395993ce SR |
11386 | indicate that the analysed set of sources is incomplete to make up a |
11387 | partition and that some subprogram bodies are missing are not generated. | |
7cd4527e | 11388 | @end table |
88e1739c | 11389 | |
86f0e17a AC |
11390 | @noindent |
11391 | Note: to invoke @command{gnatelim} with a project file, use the @code{gnat} | |
11392 | driver (see @ref{The GNAT Driver and Project Files}). | |
11393 | ||
395993ce SR |
11394 | @node Processing Precompiled Libraries |
11395 | @subsection Processing Precompiled Libraries | |
88e1739c FW |
11396 | |
11397 | @noindent | |
395993ce SR |
11398 | If some program uses a precompiled Ada library, it can be processed by |
11399 | @code{gnatelim} in a usual way. @code{gnatelim} will newer generate an | |
11400 | Eliminate pragma for a subprogram if the body of this subprogram has not | |
11401 | been analysed, this is a typical case for subprograms from precompiled | |
11402 | libraries. Switch @option{^-wq^/WARNINGS=QUIET^} may be used to suppress | |
11403 | warnings about missing source files and non-analyzed subprogram bodies | |
11404 | that can be generated when processing precompiled Ada libraries. | |
88e1739c | 11405 | |
7cd4527e AC |
11406 | @node Correcting the List of Eliminate Pragmas |
11407 | @subsection Correcting the List of Eliminate Pragmas | |
88e1739c FW |
11408 | |
11409 | @noindent | |
7cd4527e AC |
11410 | In some rare cases @code{gnatelim} may try to eliminate |
11411 | subprograms that are actually called in the program. In this case, the | |
11412 | compiler will generate an error message of the form: | |
88e1739c | 11413 | |
88e1739c | 11414 | @smallexample |
395993ce | 11415 | main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5 |
88e1739c FW |
11416 | @end smallexample |
11417 | ||
11418 | @noindent | |
7cd4527e | 11419 | You will need to manually remove the wrong @code{Eliminate} pragmas from |
395993ce SR |
11420 | the configuration file indicated in the error message. You should recompile |
11421 | your program from scratch after that, because you need a consistent | |
11422 | configuration file(s) during the entire compilation. | |
88e1739c | 11423 | |
7cd4527e AC |
11424 | @node Making Your Executables Smaller |
11425 | @subsection Making Your Executables Smaller | |
88e1739c FW |
11426 | |
11427 | @noindent | |
7cd4527e | 11428 | In order to get a smaller executable for your program you now have to |
395993ce SR |
11429 | recompile the program completely with the configuration file containing |
11430 | pragmas Eliminate generated by gnatelim. If these pragmas are placed in | |
11431 | @file{gnat.adc} file located in your current directory, just do: | |
88e1739c | 11432 | |
7cd4527e AC |
11433 | @smallexample |
11434 | $ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^ | |
11435 | @end smallexample | |
88e1739c FW |
11436 | |
11437 | @noindent | |
7cd4527e AC |
11438 | (Use the @option{^-f^/FORCE_COMPILE^} option for @command{gnatmake} to |
11439 | recompile everything | |
11440 | with the set of pragmas @code{Eliminate} that you have obtained with | |
11441 | @command{gnatelim}). | |
88e1739c | 11442 | |
7cd4527e AC |
11443 | Be aware that the set of @code{Eliminate} pragmas is specific to each |
11444 | program. It is not recommended to merge sets of @code{Eliminate} | |
395993ce | 11445 | pragmas created for different programs in one configuration file. |
7cd4527e AC |
11446 | |
11447 | @node Summary of the gnatelim Usage Cycle | |
395993ce | 11448 | @subsection Summary of the @code{gnatelim} Usage Cycle |
88e1739c FW |
11449 | |
11450 | @noindent | |
7cd4527e AC |
11451 | Here is a quick summary of the steps to be taken in order to reduce |
11452 | the size of your executables with @code{gnatelim}. You may use | |
11453 | other GNAT options to control the optimization level, | |
11454 | to produce the debugging information, to set search path, etc. | |
88e1739c | 11455 | |
7cd4527e AC |
11456 | @enumerate |
11457 | @item | |
395993ce SR |
11458 | Create a complete set of @file{ALI} files (if the program has not been |
11459 | built already) | |
88e1739c | 11460 | |
7cd4527e AC |
11461 | @smallexample |
11462 | $ gnatmake ^-c main_prog^/ACTIONS=COMPILE MAIN_PROG^ | |
7cd4527e | 11463 | @end smallexample |
88e1739c | 11464 | |
7cd4527e | 11465 | @item |
395993ce SR |
11466 | Generate a list of @code{Eliminate} pragmas in default configuration file |
11467 | @file{gnat.adc} in the current directory | |
7cd4527e AC |
11468 | @smallexample |
11469 | @ifset vms | |
11470 | $ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC | |
11471 | @end ifset | |
11472 | @ifclear vms | |
66bfd481 | 11473 | $ gnatelim main_prog >@r{[}>@r{]} gnat.adc |
7cd4527e AC |
11474 | @end ifclear |
11475 | @end smallexample | |
88e1739c | 11476 | |
7cd4527e AC |
11477 | @item |
11478 | Recompile the application | |
88e1739c | 11479 | |
7cd4527e AC |
11480 | @smallexample |
11481 | $ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^ | |
11482 | @end smallexample | |
88e1739c | 11483 | |
7cd4527e | 11484 | @end enumerate |
1037b0f4 | 11485 | @end ifclear |
88e1739c | 11486 | |
ba1cbfb9 RD |
11487 | @node Reducing Size of Executables with unused subprogram/data elimination |
11488 | @section Reducing Size of Executables with Unused Subprogram/Data Elimination | |
7e3d710b AC |
11489 | @findex unused subprogram/data elimination |
11490 | ||
11491 | @noindent | |
11492 | This section describes how you can eliminate unused subprograms and data from | |
11493 | your executable just by setting options at compilation time. | |
11494 | ||
11495 | @menu | |
11496 | * About unused subprogram/data elimination:: | |
11497 | * Compilation options:: | |
ba1cbfb9 | 11498 | * Example of unused subprogram/data elimination:: |
7e3d710b AC |
11499 | @end menu |
11500 | ||
11501 | @node About unused subprogram/data elimination | |
11502 | @subsection About unused subprogram/data elimination | |
11503 | ||
11504 | @noindent | |
11505 | By default, an executable contains all code and data of its composing objects | |
11506 | (directly linked or coming from statically linked libraries), even data or code | |
11507 | never used by this executable. | |
11508 | ||
11509 | This feature will allow you to eliminate such unused code from your | |
11510 | executable, making it smaller (in disk and in memory). | |
11511 | ||
89893302 AC |
11512 | This functionality is available on all Linux platforms except for the IA-64 |
11513 | architecture and on all cross platforms using the ELF binary file format. | |
11514 | In both cases GNU binutils version 2.16 or later are required to enable it. | |
7e3d710b AC |
11515 | |
11516 | @node Compilation options | |
11517 | @subsection Compilation options | |
11518 | ||
11519 | @noindent | |
11520 | The operation of eliminating the unused code and data from the final executable | |
11521 | is directly performed by the linker. | |
11522 | ||
11523 | In order to do this, it has to work with objects compiled with the | |
11524 | following options: | |
11525 | @option{-ffunction-sections} @option{-fdata-sections}. | |
11526 | @cindex @option{-ffunction-sections} (@command{gcc}) | |
11527 | @cindex @option{-fdata-sections} (@command{gcc}) | |
11528 | These options are usable with C and Ada files. | |
11529 | They will place respectively each | |
11530 | function or data in a separate section in the resulting object file. | |
11531 | ||
11532 | Once the objects and static libraries are created with these options, the | |
11533 | linker can perform the dead code elimination. You can do this by setting | |
11534 | the @option{-Wl,--gc-sections} option to gcc command or in the | |
1992bbd9 RW |
11535 | @option{-largs} section of @command{gnatmake}. This will perform a |
11536 | garbage collection of code and data never referenced. | |
ba1cbfb9 RD |
11537 | |
11538 | If the linker performs a partial link (@option{-r} ld linker option), then you | |
11539 | will need to provide one or several entry point using the | |
11540 | @option{-e} / @option{--entry} ld option. | |
7e3d710b AC |
11541 | |
11542 | Note that objects compiled without the @option{-ffunction-sections} and | |
11543 | @option{-fdata-sections} options can still be linked with the executable. | |
11544 | However, no dead code elimination will be performed on those objects (they will | |
11545 | be linked as is). | |
11546 | ||
11547 | The GNAT static library is now compiled with -ffunction-sections and | |
ba1cbfb9 RD |
11548 | -fdata-sections on some platforms. This allows you to eliminate the unused code |
11549 | and data of the GNAT library from your executable. | |
11550 | ||
11551 | @node Example of unused subprogram/data elimination | |
11552 | @subsection Example of unused subprogram/data elimination | |
11553 | ||
11554 | @noindent | |
11555 | Here is a simple example: | |
11556 | ||
11557 | @smallexample @c ada | |
11558 | with Aux; | |
11559 | ||
11560 | procedure Test is | |
11561 | begin | |
11562 | Aux.Used (10); | |
11563 | end Test; | |
11564 | ||
11565 | package Aux is | |
11566 | Used_Data : Integer; | |
11567 | Unused_Data : Integer; | |
11568 | ||
11569 | procedure Used (Data : Integer); | |
11570 | procedure Unused (Data : Integer); | |
11571 | end Aux; | |
11572 | ||
11573 | package body Aux is | |
11574 | procedure Used (Data : Integer) is | |
11575 | begin | |
11576 | Used_Data := Data; | |
11577 | end Used; | |
11578 | ||
11579 | procedure Unused (Data : Integer) is | |
11580 | begin | |
11581 | Unused_Data := Data; | |
11582 | end Unused; | |
11583 | end Aux; | |
11584 | @end smallexample | |
11585 | ||
11586 | @noindent | |
11587 | @code{Unused} and @code{Unused_Data} are never referenced in this code | |
11588 | excerpt, and hence they may be safely removed from the final executable. | |
11589 | ||
11590 | @smallexample | |
11591 | $ gnatmake test | |
11592 | ||
11593 | $ nm test | grep used | |
11594 | 020015f0 T aux__unused | |
11595 | 02005d88 B aux__unused_data | |
11596 | 020015cc T aux__used | |
11597 | 02005d84 B aux__used_data | |
11598 | ||
11599 | $ gnatmake test -cargs -fdata-sections -ffunction-sections \ | |
11600 | -largs -Wl,--gc-sections | |
11601 | ||
11602 | $ nm test | grep used | |
11603 | 02005350 T aux__used | |
11604 | 0201ffe0 B aux__used_data | |
11605 | @end smallexample | |
11606 | ||
11607 | @noindent | |
11608 | It can be observed that the procedure @code{Unused} and the object | |
11609 | @code{Unused_Data} are removed by the linker when using the | |
11610 | appropriate options. | |
7e3d710b | 11611 | |
7cd4527e | 11612 | @c ******************************** |
c2658843 AC |
11613 | @node Renaming Files with gnatchop |
11614 | @chapter Renaming Files with @code{gnatchop} | |
7cd4527e | 11615 | @findex gnatchop |
88e1739c FW |
11616 | |
11617 | @noindent | |
7cd4527e AC |
11618 | This chapter discusses how to handle files with multiple units by using |
11619 | the @code{gnatchop} utility. This utility is also useful in renaming | |
11620 | files to meet the standard GNAT default file naming conventions. | |
88e1739c | 11621 | |
7cd4527e AC |
11622 | @menu |
11623 | * Handling Files with Multiple Units:: | |
11624 | * Operating gnatchop in Compilation Mode:: | |
11625 | * Command Line for gnatchop:: | |
11626 | * Switches for gnatchop:: | |
11627 | * Examples of gnatchop Usage:: | |
11628 | @end menu | |
88e1739c | 11629 | |
7cd4527e AC |
11630 | @node Handling Files with Multiple Units |
11631 | @section Handling Files with Multiple Units | |
88e1739c FW |
11632 | |
11633 | @noindent | |
7cd4527e AC |
11634 | The basic compilation model of GNAT requires that a file submitted to the |
11635 | compiler have only one unit and there be a strict correspondence | |
11636 | between the file name and the unit name. | |
88e1739c | 11637 | |
7cd4527e AC |
11638 | The @code{gnatchop} utility allows both of these rules to be relaxed, |
11639 | allowing GNAT to process files which contain multiple compilation units | |
11640 | and files with arbitrary file names. @code{gnatchop} | |
11641 | reads the specified file and generates one or more output files, | |
11642 | containing one unit per file. The unit and the file name correspond, | |
11643 | as required by GNAT. | |
88e1739c | 11644 | |
7cd4527e AC |
11645 | If you want to permanently restructure a set of ``foreign'' files so that |
11646 | they match the GNAT rules, and do the remaining development using the | |
11647 | GNAT structure, you can simply use @command{gnatchop} once, generate the | |
11648 | new set of files and work with them from that point on. | |
88e1739c | 11649 | |
7cd4527e AC |
11650 | Alternatively, if you want to keep your files in the ``foreign'' format, |
11651 | perhaps to maintain compatibility with some other Ada compilation | |
11652 | system, you can set up a procedure where you use @command{gnatchop} each | |
11653 | time you compile, regarding the source files that it writes as temporary | |
11654 | files that you throw away. | |
88e1739c | 11655 | |
1f07382d AC |
11656 | Note that if your file containing multiple units starts with a byte order |
11657 | mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop | |
11658 | will each start with a copy of this BOM, meaning that they can be compiled | |
11659 | automatically in UTF-8 mode without needing to specify an explicit encoding. | |
11660 | ||
7cd4527e AC |
11661 | @node Operating gnatchop in Compilation Mode |
11662 | @section Operating gnatchop in Compilation Mode | |
88e1739c | 11663 | |
7cd4527e AC |
11664 | @noindent |
11665 | The basic function of @code{gnatchop} is to take a file with multiple units | |
11666 | and split it into separate files. The boundary between files is reasonably | |
11667 | clear, except for the issue of comments and pragmas. In default mode, the | |
11668 | rule is that any pragmas between units belong to the previous unit, except | |
11669 | that configuration pragmas always belong to the following unit. Any comments | |
11670 | belong to the following unit. These rules | |
11671 | almost always result in the right choice of | |
11672 | the split point without needing to mark it explicitly and most users will | |
11673 | find this default to be what they want. In this default mode it is incorrect to | |
11674 | submit a file containing only configuration pragmas, or one that ends in | |
11675 | configuration pragmas, to @code{gnatchop}. | |
88e1739c | 11676 | |
7cd4527e AC |
11677 | However, using a special option to activate ``compilation mode'', |
11678 | @code{gnatchop} | |
11679 | can perform another function, which is to provide exactly the semantics | |
11680 | required by the RM for handling of configuration pragmas in a compilation. | |
11681 | In the absence of configuration pragmas (at the main file level), this | |
11682 | option has no effect, but it causes such configuration pragmas to be handled | |
11683 | in a quite different manner. | |
88e1739c | 11684 | |
7cd4527e AC |
11685 | First, in compilation mode, if @code{gnatchop} is given a file that consists of |
11686 | only configuration pragmas, then this file is appended to the | |
11687 | @file{gnat.adc} file in the current directory. This behavior provides | |
11688 | the required behavior described in the RM for the actions to be taken | |
11689 | on submitting such a file to the compiler, namely that these pragmas | |
11690 | should apply to all subsequent compilations in the same compilation | |
11691 | environment. Using GNAT, the current directory, possibly containing a | |
11692 | @file{gnat.adc} file is the representation | |
11693 | of a compilation environment. For more information on the | |
984a64bc | 11694 | @file{gnat.adc} file, see @ref{Handling of Configuration Pragmas}. |
88e1739c | 11695 | |
7cd4527e AC |
11696 | Second, in compilation mode, if @code{gnatchop} |
11697 | is given a file that starts with | |
11698 | configuration pragmas, and contains one or more units, then these | |
11699 | configuration pragmas are prepended to each of the chopped files. This | |
11700 | behavior provides the required behavior described in the RM for the | |
11701 | actions to be taken on compiling such a file, namely that the pragmas | |
11702 | apply to all units in the compilation, but not to subsequently compiled | |
11703 | units. | |
88e1739c | 11704 | |
7cd4527e AC |
11705 | Finally, if configuration pragmas appear between units, they are appended |
11706 | to the previous unit. This results in the previous unit being illegal, | |
11707 | since the compiler does not accept configuration pragmas that follow | |
11708 | a unit. This provides the required RM behavior that forbids configuration | |
11709 | pragmas other than those preceding the first compilation unit of a | |
11710 | compilation. | |
88e1739c | 11711 | |
7cd4527e AC |
11712 | For most purposes, @code{gnatchop} will be used in default mode. The |
11713 | compilation mode described above is used only if you need exactly | |
11714 | accurate behavior with respect to compilations, and you have files | |
11715 | that contain multiple units and configuration pragmas. In this | |
11716 | circumstance the use of @code{gnatchop} with the compilation mode | |
11717 | switch provides the required behavior, and is for example the mode | |
11718 | in which GNAT processes the ACVC tests. | |
88e1739c | 11719 | |
7cd4527e AC |
11720 | @node Command Line for gnatchop |
11721 | @section Command Line for @code{gnatchop} | |
88e1739c FW |
11722 | |
11723 | @noindent | |
7cd4527e | 11724 | The @code{gnatchop} command has the form: |
88e1739c | 11725 | |
88e1739c | 11726 | @smallexample |
e074d476 AC |
11727 | @c $ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]} |
11728 | @c @ovar{directory} | |
11729 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
66bfd481 | 11730 | $ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]} |
e074d476 | 11731 | @r{[}@var{directory}@r{]} |
88e1739c FW |
11732 | @end smallexample |
11733 | ||
11734 | @noindent | |
7cd4527e AC |
11735 | The only required argument is the file name of the file to be chopped. |
11736 | There are no restrictions on the form of this file name. The file itself | |
11737 | contains one or more Ada units, in normal GNAT format, concatenated | |
11738 | together. As shown, more than one file may be presented to be chopped. | |
88e1739c | 11739 | |
7cd4527e AC |
11740 | When run in default mode, @code{gnatchop} generates one output file in |
11741 | the current directory for each unit in each of the files. | |
88e1739c | 11742 | |
7cd4527e AC |
11743 | @var{directory}, if specified, gives the name of the directory to which |
11744 | the output files will be written. If it is not specified, all files are | |
11745 | written to the current directory. | |
88e1739c | 11746 | |
7cd4527e AC |
11747 | For example, given a |
11748 | file called @file{hellofiles} containing | |
88e1739c | 11749 | |
7cd4527e | 11750 | @smallexample @c ada |
88e1739c | 11751 | @group |
7cd4527e AC |
11752 | @cartouche |
11753 | procedure hello; | |
88e1739c | 11754 | |
7cd4527e AC |
11755 | with Text_IO; use Text_IO; |
11756 | procedure hello is | |
88e1739c | 11757 | begin |
7cd4527e AC |
11758 | Put_Line ("Hello"); |
11759 | end hello; | |
11760 | @end cartouche | |
88e1739c FW |
11761 | @end group |
11762 | @end smallexample | |
11763 | ||
11764 | @noindent | |
7cd4527e | 11765 | the command |
88e1739c FW |
11766 | |
11767 | @smallexample | |
7cd4527e | 11768 | $ gnatchop ^hellofiles^HELLOFILES.^ |
88e1739c FW |
11769 | @end smallexample |
11770 | ||
11771 | @noindent | |
7cd4527e AC |
11772 | generates two files in the current directory, one called |
11773 | @file{hello.ads} containing the single line that is the procedure spec, | |
11774 | and the other called @file{hello.adb} containing the remaining text. The | |
11775 | original file is not affected. The generated files can be compiled in | |
11776 | the normal manner. | |
88e1739c FW |
11777 | |
11778 | @noindent | |
7cd4527e AC |
11779 | When gnatchop is invoked on a file that is empty or that contains only empty |
11780 | lines and/or comments, gnatchop will not fail, but will not produce any | |
11781 | new sources. | |
88e1739c | 11782 | |
7cd4527e AC |
11783 | For example, given a |
11784 | file called @file{toto.txt} containing | |
88e1739c | 11785 | |
7cd4527e | 11786 | @smallexample @c ada |
88e1739c | 11787 | @group |
7cd4527e AC |
11788 | @cartouche |
11789 | -- Just a comment | |
11790 | @end cartouche | |
88e1739c FW |
11791 | @end group |
11792 | @end smallexample | |
11793 | ||
11794 | @noindent | |
7cd4527e | 11795 | the command |
88e1739c FW |
11796 | |
11797 | @smallexample | |
7cd4527e | 11798 | $ gnatchop ^toto.txt^TOT.TXT^ |
88e1739c FW |
11799 | @end smallexample |
11800 | ||
11801 | @noindent | |
7cd4527e | 11802 | will not produce any new file and will result in the following warnings: |
88e1739c FW |
11803 | |
11804 | @smallexample | |
7cd4527e AC |
11805 | toto.txt:1:01: warning: empty file, contains no compilation units |
11806 | no compilation units found | |
11807 | no source files written | |
88e1739c FW |
11808 | @end smallexample |
11809 | ||
7cd4527e AC |
11810 | @node Switches for gnatchop |
11811 | @section Switches for @code{gnatchop} | |
88e1739c | 11812 | |
7cd4527e AC |
11813 | @noindent |
11814 | @command{gnatchop} recognizes the following switches: | |
88e1739c | 11815 | |
7cd4527e AC |
11816 | @table @option |
11817 | @c !sort! | |
88e1739c | 11818 | |
54df6fd9 VC |
11819 | @item --version |
11820 | @cindex @option{--version} @command{gnatchop} | |
11821 | Display Copyright and version, then exit disregarding all other options. | |
11822 | ||
11823 | @item --help | |
11824 | @cindex @option{--help} @command{gnatchop} | |
11825 | If @option{--version} was not used, display usage, then exit disregarding | |
11826 | all other options. | |
11827 | ||
7cd4527e AC |
11828 | @item ^-c^/COMPILATION^ |
11829 | @cindex @option{^-c^/COMPILATION^} (@code{gnatchop}) | |
11830 | Causes @code{gnatchop} to operate in compilation mode, in which | |
11831 | configuration pragmas are handled according to strict RM rules. See | |
11832 | previous section for a full description of this mode. | |
88e1739c | 11833 | |
7cd4527e | 11834 | @ifclear vms |
79f34d07 RW |
11835 | @item -gnat@var{xxx} |
11836 | This passes the given @option{-gnat@var{xxx}} switch to @code{gnat} which is | |
11837 | used to parse the given file. Not all @var{xxx} options make sense, | |
7cd4527e AC |
11838 | but for example, the use of @option{-gnati2} allows @code{gnatchop} to |
11839 | process a source file that uses Latin-2 coding for identifiers. | |
11840 | @end ifclear | |
88e1739c | 11841 | |
7cd4527e AC |
11842 | @item ^-h^/HELP^ |
11843 | Causes @code{gnatchop} to generate a brief help summary to the standard | |
11844 | output file showing usage information. | |
88e1739c | 11845 | |
7cd4527e AC |
11846 | @item ^-k@var{mm}^/FILE_NAME_MAX_LENGTH=@var{mm}^ |
11847 | @cindex @option{^-k^/FILE_NAME_MAX_LENGTH^} (@code{gnatchop}) | |
11848 | Limit generated file names to the specified number @code{mm} | |
11849 | of characters. | |
11850 | This is useful if the | |
11851 | resulting set of files is required to be interoperable with systems | |
11852 | which limit the length of file names. | |
11853 | @ifset vms | |
11854 | If no value is given, or | |
11855 | if no @code{/FILE_NAME_MAX_LENGTH} qualifier is given, | |
11856 | a default of 39, suitable for OpenVMS Alpha | |
11857 | Systems, is assumed | |
11858 | @end ifset | |
11859 | @ifclear vms | |
11860 | No space is allowed between the @option{-k} and the numeric value. The numeric | |
11861 | value may be omitted in which case a default of @option{-k8}, | |
11862 | suitable for use | |
11863 | with DOS-like file systems, is used. If no @option{-k} switch | |
11864 | is present then | |
11865 | there is no limit on the length of file names. | |
11866 | @end ifclear | |
88e1739c | 11867 | |
7cd4527e AC |
11868 | @item ^-p^/PRESERVE^ |
11869 | @cindex @option{^-p^/PRESERVE^} (@code{gnatchop}) | |
11870 | Causes the file ^modification^creation^ time stamp of the input file to be | |
11871 | preserved and used for the time stamp of the output file(s). This may be | |
11872 | useful for preserving coherency of time stamps in an environment where | |
11873 | @code{gnatchop} is used as part of a standard build process. | |
88e1739c | 11874 | |
7cd4527e AC |
11875 | @item ^-q^/QUIET^ |
11876 | @cindex @option{^-q^/QUIET^} (@code{gnatchop}) | |
11877 | Causes output of informational messages indicating the set of generated | |
11878 | files to be suppressed. Warnings and error messages are unaffected. | |
88e1739c | 11879 | |
7cd4527e AC |
11880 | @item ^-r^/REFERENCE^ |
11881 | @cindex @option{^-r^/REFERENCE^} (@code{gnatchop}) | |
11882 | @findex Source_Reference | |
11883 | Generate @code{Source_Reference} pragmas. Use this switch if the output | |
11884 | files are regarded as temporary and development is to be done in terms | |
11885 | of the original unchopped file. This switch causes | |
11886 | @code{Source_Reference} pragmas to be inserted into each of the | |
11887 | generated files to refers back to the original file name and line number. | |
11888 | The result is that all error messages refer back to the original | |
11889 | unchopped file. | |
11890 | In addition, the debugging information placed into the object file (when | |
984a64bc AC |
11891 | the @option{^-g^/DEBUG^} switch of @command{gcc} or @command{gnatmake} is |
11892 | specified) | |
7cd4527e AC |
11893 | also refers back to this original file so that tools like profilers and |
11894 | debuggers will give information in terms of the original unchopped file. | |
88e1739c | 11895 | |
7cd4527e AC |
11896 | If the original file to be chopped itself contains |
11897 | a @code{Source_Reference} | |
11898 | pragma referencing a third file, then gnatchop respects | |
11899 | this pragma, and the generated @code{Source_Reference} pragmas | |
11900 | in the chopped file refer to the original file, with appropriate | |
11901 | line numbers. This is particularly useful when @code{gnatchop} | |
11902 | is used in conjunction with @code{gnatprep} to compile files that | |
11903 | contain preprocessing statements and multiple units. | |
88e1739c | 11904 | |
7cd4527e AC |
11905 | @item ^-v^/VERBOSE^ |
11906 | @cindex @option{^-v^/VERBOSE^} (@code{gnatchop}) | |
11907 | Causes @code{gnatchop} to operate in verbose mode. The version | |
11908 | number and copyright notice are output, as well as exact copies of | |
11909 | the gnat1 commands spawned to obtain the chop control information. | |
88e1739c | 11910 | |
7cd4527e AC |
11911 | @item ^-w^/OVERWRITE^ |
11912 | @cindex @option{^-w^/OVERWRITE^} (@code{gnatchop}) | |
11913 | Overwrite existing file names. Normally @code{gnatchop} regards it as a | |
11914 | fatal error if there is already a file with the same name as a | |
11915 | file it would otherwise output, in other words if the files to be | |
11916 | chopped contain duplicated units. This switch bypasses this | |
11917 | check, and causes all but the last instance of such duplicated | |
11918 | units to be skipped. | |
88e1739c | 11919 | |
7cd4527e | 11920 | @ifclear vms |
79f34d07 | 11921 | @item --GCC=@var{xxxx} |
7cd4527e AC |
11922 | @cindex @option{--GCC=} (@code{gnatchop}) |
11923 | Specify the path of the GNAT parser to be used. When this switch is used, | |
11924 | no attempt is made to add the prefix to the GNAT parser executable. | |
11925 | @end ifclear | |
11926 | @end table | |
88e1739c | 11927 | |
7cd4527e AC |
11928 | @node Examples of gnatchop Usage |
11929 | @section Examples of @code{gnatchop} Usage | |
88e1739c | 11930 | |
7cd4527e AC |
11931 | @table @code |
11932 | @ifset vms | |
11933 | @item gnatchop /OVERWRITE HELLO_S.ADA [PRERELEASE.FILES] | |
11934 | @end ifset | |
11935 | @ifclear vms | |
11936 | @item gnatchop -w hello_s.ada prerelease/files | |
11937 | @end ifclear | |
88e1739c | 11938 | |
7cd4527e AC |
11939 | Chops the source file @file{hello_s.ada}. The output files will be |
11940 | placed in the directory @file{^prerelease/files^[PRERELEASE.FILES]^}, | |
11941 | overwriting any | |
11942 | files with matching names in that directory (no files in the current | |
11943 | directory are modified). | |
88e1739c | 11944 | |
7cd4527e AC |
11945 | @item gnatchop ^archive^ARCHIVE.^ |
11946 | Chops the source file @file{^archive^ARCHIVE.^} | |
11947 | into the current directory. One | |
11948 | useful application of @code{gnatchop} is in sending sets of sources | |
11949 | around, for example in email messages. The required sources are simply | |
11950 | concatenated (for example, using a ^Unix @code{cat}^VMS @code{APPEND/NEW}^ | |
11951 | command), and then | |
e08b38f5 | 11952 | @command{gnatchop} is used at the other end to reconstitute the original |
7cd4527e | 11953 | file names. |
88e1739c | 11954 | |
7cd4527e AC |
11955 | @item gnatchop file1 file2 file3 direc |
11956 | Chops all units in files @file{file1}, @file{file2}, @file{file3}, placing | |
11957 | the resulting files in the directory @file{direc}. Note that if any units | |
11958 | occur more than once anywhere within this set of files, an error message | |
11959 | is generated, and no files are written. To override this check, use the | |
11960 | @option{^-w^/OVERWRITE^} switch, | |
11961 | in which case the last occurrence in the last file will | |
11962 | be the one that is output, and earlier duplicate occurrences for a given | |
11963 | unit will be skipped. | |
11964 | @end table | |
88e1739c | 11965 | |
7cd4527e AC |
11966 | @node Configuration Pragmas |
11967 | @chapter Configuration Pragmas | |
11968 | @cindex Configuration pragmas | |
11969 | @cindex Pragmas, configuration | |
88e1739c | 11970 | |
c2658843 AC |
11971 | @menu |
11972 | * Handling of Configuration Pragmas:: | |
11973 | * The Configuration Pragmas Files:: | |
11974 | @end menu | |
11975 | ||
88e1739c | 11976 | @noindent |
e08b38f5 VC |
11977 | Configuration pragmas include those pragmas described as |
11978 | such in the Ada Reference Manual, as well as | |
b2e74434 RW |
11979 | implementation-dependent pragmas that are configuration pragmas. |
11980 | @xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}, | |
11981 | for details on these additional GNAT-specific configuration pragmas. | |
11982 | Most notably, the pragma @code{Source_File_Name}, which allows | |
7cd4527e AC |
11983 | specifying non-default names for source files, is a configuration |
11984 | pragma. The following is a complete list of configuration pragmas | |
e08b38f5 | 11985 | recognized by GNAT: |
88e1739c FW |
11986 | |
11987 | @smallexample | |
7cd4527e AC |
11988 | Ada_83 |
11989 | Ada_95 | |
0f1b0456 | 11990 | Ada_05 |
1a5f40e1 | 11991 | Ada_2005 |
0eed45bb AC |
11992 | Ada_12 |
11993 | Ada_2012 | |
818b578d | 11994 | Allow_Integer_Address |
a3068ca6 | 11995 | Annotate |
1a5f40e1 | 11996 | Assertion_Policy |
4cd029c7 | 11997 | Assume_No_Invalid_Values |
7cd4527e | 11998 | C_Pass_By_Copy |
1a5f40e1 VC |
11999 | Check_Name |
12000 | Check_Policy | |
12001 | Compile_Time_Error | |
12002 | Compile_Time_Warning | |
12003 | Compiler_Unit | |
7cd4527e | 12004 | Component_Alignment |
4cd029c7 | 12005 | Convention_Identifier |
1a5f40e1 | 12006 | Debug_Policy |
c885d7a1 | 12007 | Detect_Blocking |
fab2daeb | 12008 | Default_Storage_Pool |
7cd4527e AC |
12009 | Discard_Names |
12010 | Elaboration_Checks | |
12011 | Eliminate | |
12012 | Extend_System | |
4cd029c7 | 12013 | Extensions_Allowed |
7cd4527e | 12014 | External_Name_Casing |
1a5f40e1 VC |
12015 | Fast_Math |
12016 | Favor_Top_Level | |
7cd4527e | 12017 | Float_Representation |
1a5f40e1 | 12018 | Implicit_Packing |
7cd4527e | 12019 | Initialize_Scalars |
9c8457a7 | 12020 | Interrupt_State |
7cd4527e AC |
12021 | License |
12022 | Locking_Policy | |
12023 | Long_Float | |
1a5f40e1 VC |
12024 | No_Run_Time |
12025 | No_Strict_Aliasing | |
7cd4527e | 12026 | Normalize_Scalars |
1a5f40e1 | 12027 | Optimize_Alignment |
9c8457a7 | 12028 | Persistent_BSS |
7cd4527e | 12029 | Polling |
1a5f40e1 | 12030 | Priority_Specific_Dispatching |
8a36a0cc | 12031 | Profile |
cc335f43 | 12032 | Profile_Warnings |
7cd4527e AC |
12033 | Propagate_Exceptions |
12034 | Queuing_Policy | |
cc335f43 | 12035 | Ravenscar |
7cd4527e AC |
12036 | Restricted_Run_Time |
12037 | Restrictions | |
cc335f43 | 12038 | Restrictions_Warnings |
7cd4527e | 12039 | Reviewable |
0eed45bb | 12040 | Short_Circuit_And_Or |
7cd4527e | 12041 | Source_File_Name |
1a5f40e1 | 12042 | Source_File_Name_Project |
1c6269d3 | 12043 | SPARK_Mode |
7cd4527e AC |
12044 | Style_Checks |
12045 | Suppress | |
1a5f40e1 | 12046 | Suppress_Exception_Locations |
7cd4527e AC |
12047 | Task_Dispatching_Policy |
12048 | Universal_Data | |
12049 | Unsuppress | |
12050 | Use_VADS_Size | |
7cd4527e | 12051 | Validity_Checks |
1a5f40e1 VC |
12052 | Warnings |
12053 | Wide_Character_Encoding | |
88e1739c FW |
12054 | @end smallexample |
12055 | ||
7cd4527e AC |
12056 | @node Handling of Configuration Pragmas |
12057 | @section Handling of Configuration Pragmas | |
88e1739c | 12058 | |
7cd4527e | 12059 | Configuration pragmas may either appear at the start of a compilation |
51fb9b73 | 12060 | unit, or they can appear in a configuration pragma file to apply to |
7cd4527e | 12061 | all compilations performed in a given compilation environment. |
88e1739c | 12062 | |
7cd4527e AC |
12063 | GNAT also provides the @code{gnatchop} utility to provide an automatic |
12064 | way to handle configuration pragmas following the semantics for | |
12065 | compilations (that is, files with multiple units), described in the RM. | |
984a64bc | 12066 | See @ref{Operating gnatchop in Compilation Mode} for details. |
7cd4527e AC |
12067 | However, for most purposes, it will be more convenient to edit the |
12068 | @file{gnat.adc} file that contains configuration pragmas directly, | |
12069 | as described in the following section. | |
88e1739c | 12070 | |
51fb9b73 RD |
12071 | In the case of @code{Restrictions} pragmas appearing as configuration |
12072 | pragmas in individual compilation units, the exact handling depends on | |
12073 | the type of restriction. | |
12074 | ||
12075 | Restrictions that require partition-wide consistency (like | |
12076 | @code{No_Tasking}) are | |
12077 | recognized wherever they appear | |
12078 | and can be freely inherited, e.g. from a with'ed unit to the with'ing | |
12079 | unit. This makes sense since the binder will in any case insist on seeing | |
12080 | consistent use, so any unit not conforming to any restrictions that are | |
12081 | anywhere in the partition will be rejected, and you might as well find | |
12082 | that out at compile time rather than at bind time. | |
12083 | ||
12084 | For restrictions that do not require partition-wide consistency, e.g. | |
12085 | SPARK or No_Implementation_Attributes, in general the restriction applies | |
12086 | only to the unit in which the pragma appears, and not to any other units. | |
12087 | ||
12088 | The exception is No_Elaboration_Code which always applies to the entire | |
12089 | object file from a compilation, i.e. to the body, spec, and all subunits. | |
12090 | This restriction can be specified in a configuration pragma file, or it | |
12091 | can be on the body and/or the spec (in eithe case it applies to all the | |
12092 | relevant units). It can appear on a subunit only if it has previously | |
12093 | appeared in the body of spec. | |
12094 | ||
7cd4527e AC |
12095 | @node The Configuration Pragmas Files |
12096 | @section The Configuration Pragmas Files | |
12097 | @cindex @file{gnat.adc} | |
88e1739c FW |
12098 | |
12099 | @noindent | |
7cd4527e AC |
12100 | In GNAT a compilation environment is defined by the current |
12101 | directory at the time that a compile command is given. This current | |
12102 | directory is searched for a file whose name is @file{gnat.adc}. If | |
12103 | this file is present, it is expected to contain one or more | |
12104 | configuration pragmas that will be applied to the current compilation. | |
12105 | However, if the switch @option{-gnatA} is used, @file{gnat.adc} is not | |
12106 | considered. | |
88e1739c | 12107 | |
7cd4527e AC |
12108 | Configuration pragmas may be entered into the @file{gnat.adc} file |
12109 | either by running @code{gnatchop} on a source file that consists only of | |
12110 | configuration pragmas, or more conveniently by | |
12111 | direct editing of the @file{gnat.adc} file, which is a standard format | |
12112 | source file. | |
88e1739c | 12113 | |
e08b38f5 | 12114 | In addition to @file{gnat.adc}, additional files containing configuration |
7cd4527e AC |
12115 | pragmas may be applied to the current compilation using the switch |
12116 | @option{-gnatec}@var{path}. @var{path} must designate an existing file that | |
12117 | contains only configuration pragmas. These configuration pragmas are | |
12118 | in addition to those found in @file{gnat.adc} (provided @file{gnat.adc} | |
12119 | is present and switch @option{-gnatA} is not used). | |
12120 | ||
e08b38f5 VC |
12121 | It is allowed to specify several switches @option{-gnatec}, all of which |
12122 | will be taken into account. | |
7cd4527e AC |
12123 | |
12124 | If you are using project file, a separate mechanism is provided using | |
12125 | project attributes, see @ref{Specifying Configuration Pragmas} for more | |
12126 | details. | |
12127 | ||
12128 | @ifset vms | |
12129 | Of special interest to GNAT OpenVMS Alpha is the following | |
12130 | configuration pragma: | |
12131 | ||
12132 | @smallexample @c ada | |
12133 | @cartouche | |
12134 | pragma Extend_System (Aux_DEC); | |
12135 | @end cartouche | |
88e1739c | 12136 | @end smallexample |
88e1739c FW |
12137 | |
12138 | @noindent | |
7cd4527e AC |
12139 | In the presence of this pragma, GNAT adds to the definition of the |
12140 | predefined package SYSTEM all the additional types and subprograms that are | |
32e209e4 | 12141 | defined in HP Ada. See @ref{Compatibility with HP Ada} for details. |
7cd4527e AC |
12142 | @end ifset |
12143 | ||
c2658843 AC |
12144 | @node Handling Arbitrary File Naming Conventions with gnatname |
12145 | @chapter Handling Arbitrary File Naming Conventions with @code{gnatname} | |
7cd4527e AC |
12146 | @cindex Arbitrary File Naming Conventions |
12147 | ||
12148 | @menu | |
12149 | * Arbitrary File Naming Conventions:: | |
12150 | * Running gnatname:: | |
12151 | * Switches for gnatname:: | |
12152 | * Examples of gnatname Usage:: | |
12153 | @end menu | |
12154 | ||
12155 | @node Arbitrary File Naming Conventions | |
12156 | @section Arbitrary File Naming Conventions | |
12157 | ||
12158 | @noindent | |
12159 | The GNAT compiler must be able to know the source file name of a compilation | |
12160 | unit. When using the standard GNAT default file naming conventions | |
12161 | (@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler | |
12162 | does not need additional information. | |
12163 | ||
12164 | @noindent | |
12165 | When the source file names do not follow the standard GNAT default file naming | |
12166 | conventions, the GNAT compiler must be given additional information through | |
984a64bc | 12167 | a configuration pragmas file (@pxref{Configuration Pragmas}) |
7cd4527e | 12168 | or a project file. |
4d0e4612 | 12169 | When the non-standard file naming conventions are well-defined, |
7cd4527e | 12170 | a small number of pragmas @code{Source_File_Name} specifying a naming pattern |
984a64bc | 12171 | (@pxref{Alternative File Naming Schemes}) may be sufficient. However, |
7cd4527e AC |
12172 | if the file naming conventions are irregular or arbitrary, a number |
12173 | of pragma @code{Source_File_Name} for individual compilation units | |
12174 | must be defined. | |
12175 | To help maintain the correspondence between compilation unit names and | |
12176 | source file names within the compiler, | |
12177 | GNAT provides a tool @code{gnatname} to generate the required pragmas for a | |
12178 | set of files. | |
12179 | ||
12180 | @node Running gnatname | |
12181 | @section Running @code{gnatname} | |
12182 | ||
12183 | @noindent | |
12184 | The usual form of the @code{gnatname} command is | |
88e1739c FW |
12185 | |
12186 | @smallexample | |
e074d476 AC |
12187 | @c $ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns} |
12188 | @c @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]} | |
12189 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
12190 | $ gnatname @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]} | |
12191 | @r{[}--and @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]}@r{]} | |
88e1739c FW |
12192 | @end smallexample |
12193 | ||
7cd4527e AC |
12194 | @noindent |
12195 | All of the arguments are optional. If invoked without any argument, | |
12196 | @code{gnatname} will display its usage. | |
88e1739c | 12197 | |
7cd4527e AC |
12198 | @noindent |
12199 | When used with at least one naming pattern, @code{gnatname} will attempt to | |
12200 | find all the compilation units in files that follow at least one of the | |
12201 | naming patterns. To find these compilation units, | |
12202 | @code{gnatname} will use the GNAT compiler in syntax-check-only mode on all | |
12203 | regular files. | |
88e1739c FW |
12204 | |
12205 | @noindent | |
7cd4527e | 12206 | One or several Naming Patterns may be given as arguments to @code{gnatname}. |
48b351d9 AC |
12207 | Each Naming Pattern is enclosed between double quotes (or single |
12208 | quotes on Windows). | |
7cd4527e AC |
12209 | A Naming Pattern is a regular expression similar to the wildcard patterns |
12210 | used in file names by the Unix shells or the DOS prompt. | |
88e1739c | 12211 | |
8436e37c RD |
12212 | @noindent |
12213 | @code{gnatname} may be called with several sections of directories/patterns. | |
12214 | Sections are separated by switch @code{--and}. In each section, there must be | |
12215 | at least one pattern. If no directory is specified in a section, the current | |
12216 | directory (or the project directory is @code{-P} is used) is implied. | |
12217 | The options other that the directory switches and the patterns apply globally | |
12218 | even if they are in different sections. | |
12219 | ||
7cd4527e AC |
12220 | @noindent |
12221 | Examples of Naming Patterns are | |
88e1739c FW |
12222 | |
12223 | @smallexample | |
7cd4527e AC |
12224 | "*.[12].ada" |
12225 | "*.ad[sb]*" | |
12226 | "body_*" "spec_*" | |
88e1739c FW |
12227 | @end smallexample |
12228 | ||
12229 | @noindent | |
7cd4527e AC |
12230 | For a more complete description of the syntax of Naming Patterns, |
12231 | see the second kind of regular expressions described in @file{g-regexp.ads} | |
12232 | (the ``Glob'' regular expressions). | |
88e1739c | 12233 | |
7cd4527e | 12234 | @noindent |
8436e37c RD |
12235 | When invoked with no switch @code{-P}, @code{gnatname} will create a |
12236 | configuration pragmas file @file{gnat.adc} in the current working directory, | |
12237 | with pragmas @code{Source_File_Name} for each file that contains a valid Ada | |
12238 | unit. | |
88e1739c | 12239 | |
7cd4527e AC |
12240 | @node Switches for gnatname |
12241 | @section Switches for @code{gnatname} | |
88e1739c | 12242 | |
7cd4527e AC |
12243 | @noindent |
12244 | Switches for @code{gnatname} must precede any specified Naming Pattern. | |
88e1739c | 12245 | |
7cd4527e AC |
12246 | @noindent |
12247 | You may specify any of the following switches to @code{gnatname}: | |
88e1739c | 12248 | |
7cd4527e AC |
12249 | @table @option |
12250 | @c !sort! | |
88e1739c | 12251 | |
54df6fd9 VC |
12252 | @item --version |
12253 | @cindex @option{--version} @command{gnatname} | |
12254 | Display Copyright and version, then exit disregarding all other options. | |
12255 | ||
12256 | @item --help | |
12257 | @cindex @option{--help} @command{gnatname} | |
12258 | If @option{--version} was not used, display usage, then exit disregarding | |
12259 | all other options. | |
12260 | ||
303fbb20 AC |
12261 | @item --subdirs=<dir> |
12262 | Real object, library or exec directories are subdirectories <dir> of the | |
12263 | specified ones. | |
12264 | ||
12265 | @item --no-backup | |
12266 | Do not create a backup copy of an existing project file. | |
12267 | ||
8436e37c RD |
12268 | @item --and |
12269 | Start another section of directories/patterns. | |
12270 | ||
7cd4527e AC |
12271 | @item ^-c^/CONFIG_FILE=^@file{file} |
12272 | @cindex @option{^-c^/CONFIG_FILE^} (@code{gnatname}) | |
12273 | Create a configuration pragmas file @file{file} (instead of the default | |
12274 | @file{gnat.adc}). | |
12275 | @ifclear vms | |
12276 | There may be zero, one or more space between @option{-c} and | |
12277 | @file{file}. | |
12278 | @end ifclear | |
12279 | @file{file} may include directory information. @file{file} must be | |
12280 | writable. There may be only one switch @option{^-c^/CONFIG_FILE^}. | |
12281 | When a switch @option{^-c^/CONFIG_FILE^} is | |
12282 | specified, no switch @option{^-P^/PROJECT_FILE^} may be specified (see below). | |
12283 | ||
12284 | @item ^-d^/SOURCE_DIRS=^@file{dir} | |
12285 | @cindex @option{^-d^/SOURCE_DIRS^} (@code{gnatname}) | |
12286 | Look for source files in directory @file{dir}. There may be zero, one or more | |
12287 | spaces between @option{^-d^/SOURCE_DIRS=^} and @file{dir}. | |
e6425869 AC |
12288 | @file{dir} may end with @code{/**}, that is it may be of the form |
12289 | @code{root_dir/**}. In this case, the directory @code{root_dir} and all of its | |
12290 | subdirectories, recursively, have to be searched for sources. | |
7cd4527e AC |
12291 | When a switch @option{^-d^/SOURCE_DIRS^} |
12292 | is specified, the current working directory will not be searched for source | |
12293 | files, unless it is explicitly specified with a @option{^-d^/SOURCE_DIRS^} | |
12294 | or @option{^-D^/DIR_FILES^} switch. | |
12295 | Several switches @option{^-d^/SOURCE_DIRS^} may be specified. | |
12296 | If @file{dir} is a relative path, it is relative to the directory of | |
12297 | the configuration pragmas file specified with switch | |
12298 | @option{^-c^/CONFIG_FILE^}, | |
12299 | or to the directory of the project file specified with switch | |
12300 | @option{^-P^/PROJECT_FILE^} or, | |
12301 | if neither switch @option{^-c^/CONFIG_FILE^} | |
12302 | nor switch @option{^-P^/PROJECT_FILE^} are specified, it is relative to the | |
12303 | current working directory. The directory | |
12304 | specified with switch @option{^-d^/SOURCE_DIRS^} must exist and be readable. | |
12305 | ||
12306 | @item ^-D^/DIRS_FILE=^@file{file} | |
12307 | @cindex @option{^-D^/DIRS_FILE^} (@code{gnatname}) | |
12308 | Look for source files in all directories listed in text file @file{file}. | |
12309 | There may be zero, one or more spaces between @option{^-D^/DIRS_FILE=^} | |
12310 | and @file{file}. | |
12311 | @file{file} must be an existing, readable text file. | |
4d0e4612 | 12312 | Each nonempty line in @file{file} must be a directory. |
7cd4527e | 12313 | Specifying switch @option{^-D^/DIRS_FILE^} is equivalent to specifying as many |
4d0e4612 | 12314 | switches @option{^-d^/SOURCE_DIRS^} as there are nonempty lines in |
7cd4527e AC |
12315 | @file{file}. |
12316 | ||
303fbb20 AC |
12317 | @item -eL |
12318 | Follow symbolic links when processing project files. | |
12319 | ||
7cd4527e AC |
12320 | @item ^-f^/FOREIGN_PATTERN=^@file{pattern} |
12321 | @cindex @option{^-f^/FOREIGN_PATTERN^} (@code{gnatname}) | |
12322 | Foreign patterns. Using this switch, it is possible to add sources of languages | |
12323 | other than Ada to the list of sources of a project file. | |
12324 | It is only useful if a ^-P^/PROJECT_FILE^ switch is used. | |
12325 | For example, | |
12326 | @smallexample | |
12327 | gnatname ^-Pprj -f"*.c"^/PROJECT_FILE=PRJ /FOREIGN_PATTERN=*.C^ "*.ada" | |
12328 | @end smallexample | |
12329 | @noindent | |
12330 | will look for Ada units in all files with the @file{.ada} extension, | |
12331 | and will add to the list of file for project @file{prj.gpr} the C files | |
443b3472 | 12332 | with extension @file{.^c^C^}. |
88e1739c | 12333 | |
7cd4527e AC |
12334 | @item ^-h^/HELP^ |
12335 | @cindex @option{^-h^/HELP^} (@code{gnatname}) | |
12336 | Output usage (help) information. The output is written to @file{stdout}. | |
12337 | ||
12338 | @item ^-P^/PROJECT_FILE=^@file{proj} | |
12339 | @cindex @option{^-P^/PROJECT_FILE^} (@code{gnatname}) | |
12340 | Create or update project file @file{proj}. There may be zero, one or more space | |
12341 | between @option{-P} and @file{proj}. @file{proj} may include directory | |
12342 | information. @file{proj} must be writable. | |
12343 | There may be only one switch @option{^-P^/PROJECT_FILE^}. | |
12344 | When a switch @option{^-P^/PROJECT_FILE^} is specified, | |
12345 | no switch @option{^-c^/CONFIG_FILE^} may be specified. | |
303fbb20 AC |
12346 | On all platforms, except on VMS, when @code{gnatname} is invoked for an |
12347 | existing project file <proj>.gpr, a backup copy of the project file is created | |
12348 | in the project directory with file name <proj>.gpr.saved_x. 'x' is the first | |
12349 | non negative number that makes this backup copy a new file. | |
88e1739c | 12350 | |
7cd4527e AC |
12351 | @item ^-v^/VERBOSE^ |
12352 | @cindex @option{^-v^/VERBOSE^} (@code{gnatname}) | |
12353 | Verbose mode. Output detailed explanation of behavior to @file{stdout}. | |
12354 | This includes name of the file written, the name of the directories to search | |
12355 | and, for each file in those directories whose name matches at least one of | |
12356 | the Naming Patterns, an indication of whether the file contains a unit, | |
12357 | and if so the name of the unit. | |
12358 | ||
12359 | @item ^-v -v^/VERBOSE /VERBOSE^ | |
12360 | @cindex @option{^-v -v^/VERBOSE /VERBOSE^} (@code{gnatname}) | |
12361 | Very Verbose mode. In addition to the output produced in verbose mode, | |
12362 | for each file in the searched directories whose name matches none of | |
12363 | the Naming Patterns, an indication is given that there is no match. | |
12364 | ||
12365 | @item ^-x^/EXCLUDED_PATTERN=^@file{pattern} | |
12366 | @cindex @option{^-x^/EXCLUDED_PATTERN^} (@code{gnatname}) | |
12367 | Excluded patterns. Using this switch, it is possible to exclude some files | |
12368 | that would match the name patterns. For example, | |
88e1739c | 12369 | @smallexample |
7cd4527e | 12370 | gnatname ^-x "*_nt.ada"^/EXCLUDED_PATTERN=*_nt.ada^ "*.ada" |
88e1739c | 12371 | @end smallexample |
88e1739c | 12372 | @noindent |
7cd4527e AC |
12373 | will look for Ada units in all files with the @file{.ada} extension, |
12374 | except those whose names end with @file{_nt.ada}. | |
88e1739c | 12375 | |
7cd4527e | 12376 | @end table |
88e1739c | 12377 | |
7cd4527e AC |
12378 | @node Examples of gnatname Usage |
12379 | @section Examples of @code{gnatname} Usage | |
12380 | ||
12381 | @ifset vms | |
88e1739c | 12382 | @smallexample |
7cd4527e AC |
12383 | $ gnatname /CONFIG_FILE=[HOME.ME]NAMES.ADC /SOURCE_DIRS=SOURCES "[a-z]*.ada*" |
12384 | @end smallexample | |
12385 | @end ifset | |
12386 | ||
12387 | @ifclear vms | |
12388 | @smallexample | |
12389 | $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" | |
88e1739c | 12390 | @end smallexample |
7cd4527e | 12391 | @end ifclear |
88e1739c FW |
12392 | |
12393 | @noindent | |
7cd4527e AC |
12394 | In this example, the directory @file{^/home/me^[HOME.ME]^} must already exist |
12395 | and be writable. In addition, the directory | |
12396 | @file{^/home/me/sources^[HOME.ME.SOURCES]^} (specified by | |
12397 | @option{^-d sources^/SOURCE_DIRS=SOURCES^}) must exist and be readable. | |
12398 | ||
12399 | @ifclear vms | |
12400 | Note the optional spaces after @option{-c} and @option{-d}. | |
12401 | @end ifclear | |
88e1739c FW |
12402 | |
12403 | @smallexample | |
7cd4527e AC |
12404 | @ifclear vms |
12405 | $ gnatname -P/home/me/proj -x "*_nt_body.ada" | |
12406 | -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" | |
12407 | @end ifclear | |
12408 | @ifset vms | |
12409 | $ gnatname /PROJECT_FILE=[HOME.ME]PROJ | |
12410 | /EXCLUDED_PATTERN=*_nt_body.ada | |
12411 | /SOURCE_DIRS=(SOURCES,[SOURCES.PLUS]) | |
12412 | /DIRS_FILE=COMMON_DIRS.TXT "body_*" "spec_*" | |
12413 | @end ifset | |
88e1739c FW |
12414 | @end smallexample |
12415 | ||
7cd4527e AC |
12416 | Note that several switches @option{^-d^/SOURCE_DIRS^} may be used, |
12417 | even in conjunction with one or several switches | |
12418 | @option{^-D^/DIRS_FILE^}. Several Naming Patterns and one excluded pattern | |
12419 | are used in this example. | |
88e1739c | 12420 | |
7cd4527e AC |
12421 | @c ***************************************** |
12422 | @c * G N A T P r o j e c t M a n a g e r * | |
12423 | @c ***************************************** | |
7cd4527e | 12424 | |
8f443da5 AC |
12425 | @c ------ macros for projects.texi |
12426 | @c These macros are needed when building the gprbuild documentation, but | |
12427 | @c should have no effect in the gnat user's guide | |
12428 | ||
12429 | @macro CODESAMPLE{TXT} | |
12430 | @smallexample | |
12431 | @group | |
12432 | \TXT\ | |
12433 | @end group | |
12434 | @end smallexample | |
12435 | @end macro | |
12436 | ||
12437 | @macro PROJECTFILE{TXT} | |
12438 | @CODESAMPLE{\TXT\} | |
12439 | @end macro | |
12440 | ||
12441 | @c simulates a newline when in a @CODESAMPLE | |
12442 | @macro NL{} | |
12443 | @end macro | |
12444 | ||
12445 | @macro TIP{TXT} | |
12446 | @quotation | |
12447 | @noindent | |
12448 | \TXT\ | |
12449 | @end quotation | |
12450 | @end macro | |
12451 | ||
12452 | @macro TIPHTML{TXT} | |
12453 | \TXT\ | |
12454 | @end macro | |
12455 | ||
12456 | @macro IMPORTANT{TXT} | |
12457 | @quotation | |
12458 | @noindent | |
12459 | \TXT\ | |
12460 | @end quotation | |
12461 | ||
12462 | @end macro | |
12463 | ||
12464 | @macro NOTE{TXT} | |
12465 | @quotation | |
12466 | @noindent | |
12467 | \TXT\ | |
12468 | @end quotation | |
12469 | @end macro | |
12470 | ||
b2cacbfe | 12471 | @include projects.texi |
88e1739c | 12472 | |
b671e31b VC |
12473 | @c --------------------------------------------- |
12474 | @c Tools Supporting Project Files | |
12475 | @c --------------------------------------------- | |
12476 | ||
12477 | @node Tools Supporting Project Files | |
12478 | @chapter Tools Supporting Project Files | |
12479 | ||
12480 | @noindent | |
12481 | ||
12482 | @menu | |
12483 | * gnatmake and Project Files:: | |
12484 | * The GNAT Driver and Project Files:: | |
b671e31b VC |
12485 | @end menu |
12486 | ||
12487 | @c --------------------------------------------- | |
12488 | @node gnatmake and Project Files | |
12489 | @section gnatmake and Project Files | |
12490 | @c --------------------------------------------- | |
12491 | ||
12492 | @noindent | |
12493 | This section covers several topics related to @command{gnatmake} and | |
12494 | project files: defining ^switches^switches^ for @command{gnatmake} | |
12495 | and for the tools that it invokes; specifying configuration pragmas; | |
12496 | the use of the @code{Main} attribute; building and rebuilding library project | |
12497 | files. | |
12498 | ||
12499 | @menu | |
12500 | * Switches Related to Project Files:: | |
12501 | * Switches and Project Files:: | |
12502 | * Specifying Configuration Pragmas:: | |
12503 | * Project Files and Main Subprograms:: | |
12504 | * Library Project Files:: | |
12505 | @end menu | |
12506 | ||
12507 | @c --------------------------------------------- | |
12508 | @node Switches Related to Project Files | |
12509 | @subsection Switches Related to Project Files | |
12510 | @c --------------------------------------------- | |
12511 | ||
12512 | @noindent | |
12513 | The following switches are used by GNAT tools that support project files: | |
12514 | ||
12515 | @table @option | |
12516 | ||
12517 | @item ^-P^/PROJECT_FILE=^@var{project} | |
12518 | @cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool) | |
12519 | Indicates the name of a project file. This project file will be parsed with | |
12520 | the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}}, | |
12521 | if any, and using the external references indicated | |
12522 | by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any. | |
12523 | @ifclear vms | |
12524 | There may zero, one or more spaces between @option{-P} and @var{project}. | |
12525 | @end ifclear | |
12526 | ||
12527 | There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line. | |
12528 | ||
12529 | Since the Project Manager parses the project file only after all the switches | |
12530 | on the command line are checked, the order of the switches | |
12531 | @option{^-P^/PROJECT_FILE^}, | |
12532 | @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} | |
12533 | or @option{^-X^/EXTERNAL_REFERENCE^} is not significant. | |
12534 | ||
12535 | @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} | |
12536 | @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool) | |
12537 | Indicates that external variable @var{name} has the value @var{value}. | |
12538 | The Project Manager will use this value for occurrences of | |
12539 | @code{external(name)} when parsing the project file. | |
12540 | ||
12541 | @ifclear vms | |
12542 | If @var{name} or @var{value} includes a space, then @var{name=value} should be | |
12543 | put between quotes. | |
12544 | @smallexample | |
12545 | -XOS=NT | |
12546 | -X"user=John Doe" | |
12547 | @end smallexample | |
12548 | @end ifclear | |
12549 | ||
12550 | Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously. | |
12551 | If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same | |
12552 | @var{name}, only the last one is used. | |
12553 | ||
12554 | An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch | |
12555 | takes precedence over the value of the same name in the environment. | |
12556 | ||
12557 | @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} | |
12558 | @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool) | |
12559 | Indicates the verbosity of the parsing of GNAT project files. | |
12560 | ||
12561 | @ifclear vms | |
12562 | @option{-vP0} means Default; | |
12563 | @option{-vP1} means Medium; | |
12564 | @option{-vP2} means High. | |
12565 | @end ifclear | |
12566 | ||
12567 | @ifset vms | |
12568 | There are three possible options for this qualifier: DEFAULT, MEDIUM and | |
12569 | HIGH. | |
12570 | @end ifset | |
12571 | ||
12572 | The default is ^Default^DEFAULT^: no output for syntactically correct | |
12573 | project files. | |
12574 | If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present, | |
12575 | only the last one is used. | |
12576 | ||
12577 | @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir> | |
12578 | @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool) | |
12579 | Add directory <dir> at the beginning of the project search path, in order, | |
12580 | after the current working directory. | |
12581 | ||
12582 | @ifclear vms | |
12583 | @item -eL | |
12584 | @cindex @option{-eL} (any project-aware tool) | |
12585 | Follow all symbolic links when processing project files. | |
12586 | @end ifclear | |
12587 | ||
12588 | @item ^--subdirs^/SUBDIRS^=<subdir> | |
12589 | @cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean) | |
12590 | This switch is recognized by @command{gnatmake} and @command{gnatclean}. It | |
12591 | indicate that the real directories (except the source directories) are the | |
12592 | subdirectories <subdir> of the directories specified in the project files. | |
12593 | This applies in particular to object directories, library directories and | |
12594 | exec directories. If the subdirectories do not exist, they are created | |
12595 | automatically. | |
12596 | ||
12597 | @end table | |
12598 | ||
12599 | @c --------------------------------------------- | |
12600 | @node Switches and Project Files | |
12601 | @subsection Switches and Project Files | |
12602 | @c --------------------------------------------- | |
12603 | ||
12604 | @noindent | |
12605 | @ifset vms | |
12606 | It is not currently possible to specify VMS style qualifiers in the project | |
12607 | files; only Unix style ^switches^switches^ may be specified. | |
12608 | @end ifset | |
12609 | ||
12610 | For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and | |
12611 | @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^} | |
12612 | attribute, a @code{Switches} attribute, or both; | |
12613 | as their names imply, these ^switch^switch^-related | |
12614 | attributes affect the ^switches^switches^ that are used for each of these GNAT | |
12615 | components when | |
12616 | @command{gnatmake} is invoked. As will be explained below, these | |
12617 | component-specific ^switches^switches^ precede | |
12618 | the ^switches^switches^ provided on the @command{gnatmake} command line. | |
12619 | ||
12620 | The @code{^Default_Switches^Default_Switches^} attribute is an attribute | |
12621 | indexed by language name (case insensitive) whose value is a string list. | |
12622 | For example: | |
12623 | ||
12624 | @smallexample @c projectfile | |
12625 | @group | |
12626 | package Compiler is | |
12627 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12628 | use ("^-gnaty^-gnaty^", | |
12629 | "^-v^-v^"); | |
12630 | end Compiler; | |
12631 | @end group | |
12632 | @end smallexample | |
12633 | ||
12634 | @noindent | |
12635 | The @code{Switches} attribute is indexed on a file name (which may or may | |
12636 | not be case sensitive, depending | |
12637 | on the operating system) whose value is a string list. For example: | |
12638 | ||
12639 | @smallexample @c projectfile | |
12640 | @group | |
12641 | package Builder is | |
12642 | for Switches ("main1.adb") | |
12643 | use ("^-O2^-O2^"); | |
12644 | for Switches ("main2.adb") | |
12645 | use ("^-g^-g^"); | |
12646 | end Builder; | |
12647 | @end group | |
12648 | @end smallexample | |
12649 | ||
12650 | @noindent | |
12651 | For the @code{Builder} package, the file names must designate source files | |
12652 | for main subprograms. For the @code{Binder} and @code{Linker} packages, the | |
12653 | file names must designate @file{ALI} or source files for main subprograms. | |
12654 | In each case just the file name without an explicit extension is acceptable. | |
12655 | ||
12656 | For each tool used in a program build (@command{gnatmake}, the compiler, the | |
12657 | binder, and the linker), the corresponding package @dfn{contributes} a set of | |
12658 | ^switches^switches^ for each file on which the tool is invoked, based on the | |
12659 | ^switch^switch^-related attributes defined in the package. | |
12660 | In particular, the ^switches^switches^ | |
12661 | that each of these packages contributes for a given file @var{f} comprise: | |
12662 | ||
12663 | @itemize @bullet | |
12664 | @item the value of attribute @code{Switches (@var{f})}, | |
12665 | if it is specified in the package for the given file, | |
12666 | @item otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")}, | |
12667 | if it is specified in the package. | |
12668 | ||
12669 | @end itemize | |
12670 | ||
12671 | @noindent | |
12672 | If neither of these attributes is defined in the package, then the package does | |
12673 | not contribute any ^switches^switches^ for the given file. | |
12674 | ||
12675 | When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise | |
12676 | two sets, in the following order: those contributed for the file | |
12677 | by the @code{Builder} package; | |
12678 | and the switches passed on the command line. | |
12679 | ||
12680 | When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file, | |
12681 | the ^switches^switches^ passed to the tool comprise three sets, | |
12682 | in the following order: | |
12683 | ||
12684 | @enumerate | |
12685 | @item | |
12686 | the applicable ^switches^switches^ contributed for the file | |
12687 | by the @code{Builder} package in the project file supplied on the command line; | |
12688 | ||
12689 | @item | |
12690 | those contributed for the file by the package (in the relevant project file -- | |
12691 | see below) corresponding to the tool; and | |
12692 | ||
12693 | @item | |
12694 | the applicable switches passed on the command line. | |
12695 | @end enumerate | |
12696 | ||
12697 | The term @emph{applicable ^switches^switches^} reflects the fact that | |
12698 | @command{gnatmake} ^switches^switches^ may or may not be passed to individual | |
12699 | tools, depending on the individual ^switch^switch^. | |
12700 | ||
12701 | @command{gnatmake} may invoke the compiler on source files from different | |
12702 | projects. The Project Manager will use the appropriate project file to | |
12703 | determine the @code{Compiler} package for each source file being compiled. | |
12704 | Likewise for the @code{Binder} and @code{Linker} packages. | |
12705 | ||
12706 | As an example, consider the following package in a project file: | |
12707 | ||
12708 | @smallexample @c projectfile | |
12709 | @group | |
12710 | project Proj1 is | |
12711 | package Compiler is | |
12712 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12713 | use ("^-g^-g^"); | |
12714 | for Switches ("a.adb") | |
12715 | use ("^-O1^-O1^"); | |
12716 | for Switches ("b.adb") | |
12717 | use ("^-O2^-O2^", | |
12718 | "^-gnaty^-gnaty^"); | |
12719 | end Compiler; | |
12720 | end Proj1; | |
12721 | @end group | |
12722 | @end smallexample | |
12723 | ||
12724 | @noindent | |
12725 | If @command{gnatmake} is invoked with this project file, and it needs to | |
12726 | compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then | |
12727 | @file{a.adb} will be compiled with the ^switch^switch^ | |
12728 | @option{^-O1^-O1^}, | |
12729 | @file{b.adb} with ^switches^switches^ | |
12730 | @option{^-O2^-O2^} | |
12731 | and @option{^-gnaty^-gnaty^}, | |
12732 | and @file{c.adb} with @option{^-g^-g^}. | |
12733 | ||
12734 | The following example illustrates the ordering of the ^switches^switches^ | |
12735 | contributed by different packages: | |
12736 | ||
12737 | @smallexample @c projectfile | |
12738 | @group | |
12739 | project Proj2 is | |
12740 | package Builder is | |
12741 | for Switches ("main.adb") | |
12742 | use ("^-g^-g^", | |
12743 | "^-O1^-)1^", | |
12744 | "^-f^-f^"); | |
12745 | end Builder; | |
12746 | @end group | |
12747 | ||
12748 | @group | |
12749 | package Compiler is | |
12750 | for Switches ("main.adb") | |
12751 | use ("^-O2^-O2^"); | |
12752 | end Compiler; | |
12753 | end Proj2; | |
12754 | @end group | |
12755 | @end smallexample | |
12756 | ||
12757 | @noindent | |
12758 | If you issue the command: | |
12759 | ||
12760 | @smallexample | |
12761 | gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main | |
12762 | @end smallexample | |
12763 | ||
12764 | @noindent | |
12765 | then the compiler will be invoked on @file{main.adb} with the following | |
12766 | sequence of ^switches^switches^ | |
12767 | ||
12768 | @smallexample | |
12769 | ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^ | |
12770 | @end smallexample | |
12771 | ||
12772 | @noindent | |
12773 | with the last @option{^-O^-O^} | |
12774 | ^switch^switch^ having precedence over the earlier ones; | |
12775 | several other ^switches^switches^ | |
12776 | (such as @option{^-c^-c^}) are added implicitly. | |
12777 | ||
12778 | The ^switches^switches^ | |
12779 | @option{^-g^-g^} | |
12780 | and @option{^-O1^-O1^} are contributed by package | |
12781 | @code{Builder}, @option{^-O2^-O2^} is contributed | |
12782 | by the package @code{Compiler} | |
12783 | and @option{^-O0^-O0^} comes from the command line. | |
12784 | ||
12785 | The @option{^-g^-g^} | |
12786 | ^switch^switch^ will also be passed in the invocation of | |
12787 | @command{Gnatlink.} | |
12788 | ||
12789 | A final example illustrates switch contributions from packages in different | |
12790 | project files: | |
12791 | ||
12792 | @smallexample @c projectfile | |
12793 | @group | |
12794 | project Proj3 is | |
12795 | for Source_Files use ("pack.ads", "pack.adb"); | |
12796 | package Compiler is | |
12797 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12798 | use ("^-gnata^-gnata^"); | |
12799 | end Compiler; | |
12800 | end Proj3; | |
12801 | @end group | |
12802 | ||
12803 | @group | |
12804 | with "Proj3"; | |
12805 | project Proj4 is | |
12806 | for Source_Files use ("foo_main.adb", "bar_main.adb"); | |
12807 | package Builder is | |
12808 | for Switches ("foo_main.adb") | |
12809 | use ("^-s^-s^", | |
12810 | "^-g^-g^"); | |
12811 | end Builder; | |
12812 | end Proj4; | |
12813 | @end group | |
12814 | ||
12815 | @group | |
12816 | -- Ada source file: | |
12817 | with Pack; | |
12818 | procedure Foo_Main is | |
12819 | @dots{} | |
12820 | end Foo_Main; | |
12821 | @end group | |
12822 | @end smallexample | |
12823 | ||
12824 | @noindent | |
12825 | If the command is | |
12826 | @smallexample | |
12827 | gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato | |
12828 | @end smallexample | |
12829 | ||
12830 | @noindent | |
12831 | then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are | |
12832 | @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and | |
12833 | @option{^-gnato^-gnato^} (passed on the command line). | |
12834 | When the imported package @code{Pack} is compiled, the ^switches^switches^ used | |
12835 | are @option{^-g^-g^} from @code{Proj4.Builder}, | |
12836 | @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler}, | |
12837 | and @option{^-gnato^-gnato^} from the command line. | |
12838 | ||
12839 | When using @command{gnatmake} with project files, some ^switches^switches^ or | |
12840 | arguments may be expressed as relative paths. As the working directory where | |
12841 | compilation occurs may change, these relative paths are converted to absolute | |
12842 | paths. For the ^switches^switches^ found in a project file, the relative paths | |
12843 | are relative to the project file directory, for the switches on the command | |
12844 | line, they are relative to the directory where @command{gnatmake} is invoked. | |
12845 | The ^switches^switches^ for which this occurs are: | |
12846 | ^-I^-I^, | |
12847 | ^-A^-A^, | |
12848 | ^-L^-L^, | |
12849 | ^-aO^-aO^, | |
12850 | ^-aL^-aL^, | |
12851 | ^-aI^-aI^, as well as all arguments that are not switches (arguments to | |
12852 | ^switch^switch^ | |
12853 | ^-o^-o^, object files specified in package @code{Linker} or after | |
12854 | -largs on the command line). The exception to this rule is the ^switch^switch^ | |
12855 | ^--RTS=^--RTS=^ for which a relative path argument is never converted. | |
12856 | ||
12857 | @c --------------------------------------------- | |
12858 | @node Specifying Configuration Pragmas | |
12859 | @subsection Specifying Configuration Pragmas | |
12860 | @c --------------------------------------------- | |
12861 | ||
12862 | @noindent | |
12863 | When using @command{gnatmake} with project files, if there exists a file | |
12864 | @file{gnat.adc} that contains configuration pragmas, this file will be | |
12865 | ignored. | |
12866 | ||
12867 | Configuration pragmas can be defined by means of the following attributes in | |
12868 | project files: @code{Global_Configuration_Pragmas} in package @code{Builder} | |
12869 | and @code{Local_Configuration_Pragmas} in package @code{Compiler}. | |
12870 | ||
12871 | Both these attributes are single string attributes. Their values is the path | |
12872 | name of a file containing configuration pragmas. If a path name is relative, | |
12873 | then it is relative to the project directory of the project file where the | |
12874 | attribute is defined. | |
12875 | ||
12876 | When compiling a source, the configuration pragmas used are, in order, | |
12877 | those listed in the file designated by attribute | |
12878 | @code{Global_Configuration_Pragmas} in package @code{Builder} of the main | |
12879 | project file, if it is specified, and those listed in the file designated by | |
12880 | attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of | |
12881 | the project file of the source, if it exists. | |
12882 | ||
12883 | @c --------------------------------------------- | |
12884 | @node Project Files and Main Subprograms | |
12885 | @subsection Project Files and Main Subprograms | |
12886 | @c --------------------------------------------- | |
12887 | ||
12888 | @noindent | |
12889 | When using a project file, you can invoke @command{gnatmake} | |
12890 | with one or several main subprograms, by specifying their source files on the | |
12891 | command line. | |
12892 | ||
12893 | @smallexample | |
12894 | gnatmake ^-P^/PROJECT_FILE=^prj main1.adb main2.adb main3.adb | |
12895 | @end smallexample | |
12896 | ||
12897 | @noindent | |
12898 | Each of these needs to be a source file of the same project, except | |
12899 | when the switch ^-u^/UNIQUE^ is used. | |
12900 | ||
12901 | When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the | |
12902 | same project, one of the project in the tree rooted at the project specified | |
12903 | on the command line. The package @code{Builder} of this common project, the | |
12904 | "main project" is the one that is considered by @command{gnatmake}. | |
12905 | ||
12906 | When ^-u^/UNIQUE^ is used, the specified source files may be in projects | |
12907 | imported directly or indirectly by the project specified on the command line. | |
12908 | Note that if such a source file is not part of the project specified on the | |
12909 | command line, the ^switches^switches^ found in package @code{Builder} of the | |
12910 | project specified on the command line, if any, that are transmitted | |
12911 | to the compiler will still be used, not those found in the project file of | |
12912 | the source file. | |
12913 | ||
12914 | When using a project file, you can also invoke @command{gnatmake} without | |
12915 | explicitly specifying any main, and the effect depends on whether you have | |
12916 | defined the @code{Main} attribute. This attribute has a string list value, | |
12917 | where each element in the list is the name of a source file (the file | |
12918 | extension is optional) that contains a unit that can be a main subprogram. | |
12919 | ||
12920 | If the @code{Main} attribute is defined in a project file as a non-empty | |
12921 | string list and the switch @option{^-u^/UNIQUE^} is not used on the command | |
12922 | line, then invoking @command{gnatmake} with this project file but without any | |
12923 | main on the command line is equivalent to invoking @command{gnatmake} with all | |
12924 | the file names in the @code{Main} attribute on the command line. | |
12925 | ||
12926 | Example: | |
12927 | @smallexample @c projectfile | |
12928 | @group | |
12929 | project Prj is | |
12930 | for Main use ("main1.adb", "main2.adb", "main3.adb"); | |
12931 | end Prj; | |
12932 | @end group | |
12933 | @end smallexample | |
12934 | ||
12935 | @noindent | |
12936 | With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"} | |
12937 | is equivalent to | |
12938 | @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1.adb main2.adb main3.adb"}. | |
12939 | ||
12940 | When the project attribute @code{Main} is not specified, or is specified | |
12941 | as an empty string list, or when the switch @option{-u} is used on the command | |
12942 | line, then invoking @command{gnatmake} with no main on the command line will | |
12943 | result in all immediate sources of the project file being checked, and | |
12944 | potentially recompiled. Depending on the presence of the switch @option{-u}, | |
12945 | sources from other project files on which the immediate sources of the main | |
12946 | project file depend are also checked and potentially recompiled. In other | |
12947 | words, the @option{-u} switch is applied to all of the immediate sources of the | |
12948 | main project file. | |
12949 | ||
12950 | When no main is specified on the command line and attribute @code{Main} exists | |
12951 | and includes several mains, or when several mains are specified on the | |
12952 | command line, the default ^switches^switches^ in package @code{Builder} will | |
12953 | be used for all mains, even if there are specific ^switches^switches^ | |
12954 | specified for one or several mains. | |
12955 | ||
12956 | But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be | |
12957 | the specific ^switches^switches^ for each main, if they are specified. | |
12958 | ||
12959 | @c --------------------------------------------- | |
12960 | @node Library Project Files | |
12961 | @subsection Library Project Files | |
12962 | @c --------------------------------------------- | |
12963 | ||
12964 | @noindent | |
12965 | When @command{gnatmake} is invoked with a main project file that is a library | |
12966 | project file, it is not allowed to specify one or more mains on the command | |
12967 | line. | |
12968 | ||
12969 | When a library project file is specified, switches ^-b^/ACTION=BIND^ and | |
12970 | ^-l^/ACTION=LINK^ have special meanings. | |
12971 | ||
12972 | @itemize @bullet | |
12973 | @item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates | |
12974 | to @command{gnatmake} that @command{gnatbind} should be invoked for the | |
12975 | library. | |
12976 | ||
12977 | @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates | |
12978 | to @command{gnatmake} that the binder generated file should be compiled | |
12979 | (in the case of a stand-alone library) and that the library should be built. | |
12980 | @end itemize | |
12981 | ||
12982 | @c --------------------------------------------- | |
12983 | @node The GNAT Driver and Project Files | |
12984 | @section The GNAT Driver and Project Files | |
12985 | @c --------------------------------------------- | |
12986 | ||
12987 | @noindent | |
12988 | A number of GNAT tools, other than @command{^gnatmake^gnatmake^} | |
12989 | can benefit from project files: | |
12990 | (@command{^gnatbind^gnatbind^}, | |
1037b0f4 | 12991 | @ifclear FSFEDITION |
b671e31b | 12992 | @command{^gnatcheck^gnatcheck^}, |
1037b0f4 | 12993 | @end ifclear |
b671e31b | 12994 | @command{^gnatclean^gnatclean^}, |
1037b0f4 | 12995 | @ifclear FSFEDITION |
b671e31b | 12996 | @command{^gnatelim^gnatelim^}, |
1037b0f4 | 12997 | @end ifclear |
b671e31b VC |
12998 | @command{^gnatfind^gnatfind^}, |
12999 | @command{^gnatlink^gnatlink^}, | |
13000 | @command{^gnatls^gnatls^}, | |
1037b0f4 | 13001 | @ifclear FSFEDITION |
b671e31b VC |
13002 | @command{^gnatmetric^gnatmetric^}, |
13003 | @command{^gnatpp^gnatpp^}, | |
13004 | @command{^gnatstub^gnatstub^}, | |
1037b0f4 | 13005 | @end ifclear |
b671e31b VC |
13006 | and @command{^gnatxref^gnatxref^}). However, none of these tools can be invoked |
13007 | directly with a project file switch (@option{^-P^/PROJECT_FILE=^}). | |
13008 | They must be invoked through the @command{gnat} driver. | |
13009 | ||
13010 | The @command{gnat} driver is a wrapper that accepts a number of commands and | |
13011 | calls the corresponding tool. It was designed initially for VMS platforms (to | |
13012 | convert VMS qualifiers to Unix-style switches), but it is now available on all | |
13013 | GNAT platforms. | |
13014 | ||
13015 | On non-VMS platforms, the @command{gnat} driver accepts the following commands | |
13016 | (case insensitive): | |
13017 | ||
13018 | @itemize @bullet | |
13019 | @item BIND to invoke @command{^gnatbind^gnatbind^} | |
13020 | @item CHOP to invoke @command{^gnatchop^gnatchop^} | |
13021 | @item CLEAN to invoke @command{^gnatclean^gnatclean^} | |
13022 | @item COMP or COMPILE to invoke the compiler | |
1037b0f4 | 13023 | @ifclear FSFEDITION |
b671e31b | 13024 | @item ELIM to invoke @command{^gnatelim^gnatelim^} |
1037b0f4 | 13025 | @end ifclear |
b671e31b VC |
13026 | @item FIND to invoke @command{^gnatfind^gnatfind^} |
13027 | @item KR or KRUNCH to invoke @command{^gnatkr^gnatkr^} | |
13028 | @item LINK to invoke @command{^gnatlink^gnatlink^} | |
13029 | @item LS or LIST to invoke @command{^gnatls^gnatls^} | |
13030 | @item MAKE to invoke @command{^gnatmake^gnatmake^} | |
13031 | @item NAME to invoke @command{^gnatname^gnatname^} | |
13032 | @item PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^} | |
1037b0f4 | 13033 | @ifclear FSFEDITION |
b671e31b VC |
13034 | @item PP or PRETTY to invoke @command{^gnatpp^gnatpp^} |
13035 | @item METRIC to invoke @command{^gnatmetric^gnatmetric^} | |
13036 | @item STUB to invoke @command{^gnatstub^gnatstub^} | |
1037b0f4 | 13037 | @end ifclear |
b671e31b VC |
13038 | @item XREF to invoke @command{^gnatxref^gnatxref^} |
13039 | ||
13040 | @end itemize | |
13041 | ||
13042 | @noindent | |
13043 | (note that the compiler is invoked using the command | |
13044 | @command{^gnatmake -f -u -c^gnatmake -f -u -c^}). | |
13045 | ||
13046 | On non-VMS platforms, between @command{gnat} and the command, two | |
13047 | special switches may be used: | |
13048 | ||
13049 | @itemize @bullet | |
13050 | @item @command{-v} to display the invocation of the tool. | |
13051 | @item @command{-dn} to prevent the @command{gnat} driver from removing | |
13052 | the temporary files it has created. These temporary files are | |
13053 | configuration files and temporary file list files. | |
13054 | ||
13055 | @end itemize | |
13056 | ||
13057 | @noindent | |
13058 | The command may be followed by switches and arguments for the invoked | |
13059 | tool. | |
13060 | ||
13061 | @smallexample | |
13062 | gnat bind -C main.ali | |
13063 | gnat ls -a main | |
13064 | gnat chop foo.txt | |
13065 | @end smallexample | |
13066 | ||
13067 | @noindent | |
13068 | Switches may also be put in text files, one switch per line, and the text | |
13069 | files may be specified with their path name preceded by '@@'. | |
13070 | ||
13071 | @smallexample | |
13072 | gnat bind @@args.txt main.ali | |
13073 | @end smallexample | |
13074 | ||
13075 | @noindent | |
1037b0f4 AC |
13076 | In addition, for commands BIND, COMP or COMPILE, FIND, |
13077 | @ifclear FSFEDITION | |
13078 | ELIM, | |
13079 | @end ifclear | |
13080 | LS or LIST, LINK, | |
13081 | @ifclear FSFEDITION | |
13082 | METRIC, | |
13083 | PP or PRETTY, | |
13084 | STUB, | |
13085 | @end ifclear | |
13086 | and XREF, the project file related switches | |
b671e31b VC |
13087 | (@option{^-P^/PROJECT_FILE^}, |
13088 | @option{^-X^/EXTERNAL_REFERENCE^} and | |
13089 | @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to | |
13090 | the switches of the invoking tool. | |
13091 | ||
1037b0f4 | 13092 | @ifclear FSFEDITION |
b671e31b VC |
13093 | When GNAT PP or GNAT PRETTY is used with a project file, but with no source |
13094 | specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all | |
13095 | the immediate sources of the specified project file. | |
1037b0f4 | 13096 | @end ifclear |
b671e31b | 13097 | |
1037b0f4 | 13098 | @ifclear FSFEDITION |
b671e31b VC |
13099 | When GNAT METRIC is used with a project file, but with no source |
13100 | specified on the command line, it invokes @command{^gnatmetric^gnatmetric^} | |
13101 | with all the immediate sources of the specified project file and with | |
13102 | @option{^-d^/DIRECTORY^} with the parameter pointing to the object directory | |
13103 | of the project. | |
1037b0f4 | 13104 | @end ifclear |
b671e31b | 13105 | |
1037b0f4 | 13106 | @ifclear FSFEDITION |
b671e31b VC |
13107 | In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with |
13108 | a project file, no source is specified on the command line and | |
13109 | switch ^-U^/ALL_PROJECTS^ is specified on the command line, then | |
13110 | the underlying tool (^gnatpp^gnatpp^ or | |
13111 | ^gnatmetric^gnatmetric^) is invoked for all sources of all projects, | |
13112 | not only for the immediate sources of the main project. | |
13113 | @ifclear vms | |
13114 | (-U stands for Universal or Union of the project files of the project tree) | |
13115 | @end ifclear | |
1037b0f4 | 13116 | @end ifclear |
b671e31b VC |
13117 | |
13118 | For each of the following commands, there is optionally a corresponding | |
13119 | package in the main project. | |
13120 | ||
13121 | @itemize @bullet | |
13122 | @item package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^}) | |
13123 | ||
1037b0f4 | 13124 | @ifclear FSFEDITION |
b671e31b VC |
13125 | @item package @code{Check} for command CHECK (invoking |
13126 | @code{^gnatcheck^gnatcheck^}) | |
1037b0f4 | 13127 | @end ifclear |
b671e31b VC |
13128 | |
13129 | @item package @code{Compiler} for command COMP or COMPILE (invoking the compiler) | |
13130 | ||
13131 | @item package @code{Cross_Reference} for command XREF (invoking | |
13132 | @code{^gnatxref^gnatxref^}) | |
13133 | ||
1037b0f4 | 13134 | @ifclear FSFEDITION |
b671e31b VC |
13135 | @item package @code{Eliminate} for command ELIM (invoking |
13136 | @code{^gnatelim^gnatelim^}) | |
1037b0f4 | 13137 | @end ifclear |
b671e31b VC |
13138 | |
13139 | @item package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^}) | |
13140 | ||
13141 | @item package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^}) | |
13142 | ||
1037b0f4 | 13143 | @ifclear FSFEDITION |
b671e31b VC |
13144 | @item package @code{Gnatstub} for command STUB |
13145 | (invoking @code{^gnatstub^gnatstub^}) | |
1037b0f4 | 13146 | @end ifclear |
b671e31b VC |
13147 | |
13148 | @item package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^}) | |
13149 | ||
1037b0f4 | 13150 | @ifclear FSFEDITION |
b671e31b VC |
13151 | @item package @code{Check} for command CHECK |
13152 | (invoking @code{^gnatcheck^gnatcheck^}) | |
1037b0f4 | 13153 | @end ifclear |
b671e31b | 13154 | |
1037b0f4 | 13155 | @ifclear FSFEDITION |
b671e31b VC |
13156 | @item package @code{Metrics} for command METRIC |
13157 | (invoking @code{^gnatmetric^gnatmetric^}) | |
1037b0f4 | 13158 | @end ifclear |
b671e31b | 13159 | |
1037b0f4 | 13160 | @ifclear FSFEDITION |
b671e31b VC |
13161 | @item package @code{Pretty_Printer} for command PP or PRETTY |
13162 | (invoking @code{^gnatpp^gnatpp^}) | |
1037b0f4 | 13163 | @end ifclear |
b671e31b VC |
13164 | |
13165 | @end itemize | |
13166 | ||
13167 | @noindent | |
13168 | Package @code{Gnatls} has a unique attribute @code{Switches}, | |
13169 | a simple variable with a string list value. It contains ^switches^switches^ | |
13170 | for the invocation of @code{^gnatls^gnatls^}. | |
13171 | ||
13172 | @smallexample @c projectfile | |
13173 | @group | |
13174 | project Proj1 is | |
13175 | package gnatls is | |
13176 | for Switches | |
13177 | use ("^-a^-a^", | |
13178 | "^-v^-v^"); | |
13179 | end gnatls; | |
13180 | end Proj1; | |
13181 | @end group | |
13182 | @end smallexample | |
13183 | ||
13184 | @noindent | |
13185 | All other packages have two attribute @code{Switches} and | |
13186 | @code{^Default_Switches^Default_Switches^}. | |
13187 | ||
13188 | @code{Switches} is an indexed attribute, indexed by the | |
13189 | source file name, that has a string list value: the ^switches^switches^ to be | |
13190 | used when the tool corresponding to the package is invoked for the specific | |
13191 | source file. | |
13192 | ||
13193 | @code{^Default_Switches^Default_Switches^} is an attribute, | |
13194 | indexed by the programming language that has a string list value. | |
13195 | @code{^Default_Switches^Default_Switches^ ("Ada")} contains the | |
13196 | ^switches^switches^ for the invocation of the tool corresponding | |
13197 | to the package, except if a specific @code{Switches} attribute | |
13198 | is specified for the source file. | |
13199 | ||
13200 | @smallexample @c projectfile | |
13201 | @group | |
13202 | project Proj is | |
13203 | ||
13204 | for Source_Dirs use ("**"); | |
13205 | ||
13206 | package gnatls is | |
13207 | for Switches use | |
13208 | ("^-a^-a^", | |
13209 | "^-v^-v^"); | |
13210 | end gnatls; | |
13211 | @end group | |
13212 | @group | |
13213 | ||
13214 | package Compiler is | |
13215 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13216 | use ("^-gnatv^-gnatv^", | |
13217 | "^-gnatwa^-gnatwa^"); | |
13218 | end Binder; | |
13219 | @end group | |
13220 | @group | |
13221 | ||
13222 | package Binder is | |
13223 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13224 | use ("^-C^-C^", | |
13225 | "^-e^-e^"); | |
13226 | end Binder; | |
13227 | @end group | |
13228 | @group | |
13229 | ||
13230 | package Linker is | |
13231 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13232 | use ("^-C^-C^"); | |
13233 | for Switches ("main.adb") | |
13234 | use ("^-C^-C^", | |
13235 | "^-v^-v^", | |
13236 | "^-v^-v^"); | |
13237 | end Linker; | |
13238 | @end group | |
13239 | @group | |
13240 | ||
13241 | package Finder is | |
13242 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13243 | use ("^-a^-a^", | |
13244 | "^-f^-f^"); | |
13245 | end Finder; | |
13246 | @end group | |
13247 | @group | |
13248 | ||
13249 | package Cross_Reference is | |
13250 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13251 | use ("^-a^-a^", | |
13252 | "^-f^-f^", | |
13253 | "^-d^-d^", | |
13254 | "^-u^-u^"); | |
13255 | end Cross_Reference; | |
13256 | end Proj; | |
13257 | @end group | |
13258 | @end smallexample | |
13259 | ||
13260 | @noindent | |
13261 | With the above project file, commands such as | |
13262 | ||
13263 | @smallexample | |
13264 | ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^ | |
13265 | ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^ | |
13266 | ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^ | |
13267 | ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^ | |
13268 | ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^ | |
13269 | @end smallexample | |
13270 | ||
13271 | @noindent | |
13272 | will set up the environment properly and invoke the tool with the switches | |
13273 | found in the package corresponding to the tool: | |
13274 | @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools, | |
13275 | except @code{Switches ("main.adb")} | |
13276 | for @code{^gnatlink^gnatlink^}. | |
1037b0f4 | 13277 | @ifclear FSFEDITION |
b671e31b VC |
13278 | It is also possible to invoke some of the tools, |
13279 | (@code{^gnatcheck^gnatcheck^}, | |
13280 | @code{^gnatmetric^gnatmetric^}, | |
13281 | and @code{^gnatpp^gnatpp^}) | |
13282 | on a set of project units thanks to the combination of the switches | |
13283 | @option{-P}, @option{-U} and possibly the main unit when one is interested | |
13284 | in its closure. For instance, | |
13285 | @smallexample | |
13286 | gnat metric -Pproj | |
13287 | @end smallexample | |
13288 | ||
13289 | @noindent | |
13290 | will compute the metrics for all the immediate units of project | |
13291 | @code{proj}. | |
13292 | @smallexample | |
13293 | gnat metric -Pproj -U | |
13294 | @end smallexample | |
13295 | ||
13296 | @noindent | |
13297 | will compute the metrics for all the units of the closure of projects | |
13298 | rooted at @code{proj}. | |
13299 | @smallexample | |
13300 | gnat metric -Pproj -U main_unit | |
13301 | @end smallexample | |
13302 | ||
13303 | @noindent | |
13304 | will compute the metrics for the closure of units rooted at | |
13305 | @code{main_unit}. This last possibility relies implicitly | |
13306 | on @command{gnatbind}'s option @option{-R}. But if the argument files for the | |
13307 | tool invoked by the @command{gnat} driver are explicitly specified | |
13308 | either directly or through the tool @option{-files} option, then the tool | |
13309 | is called only for these explicitly specified files. | |
1037b0f4 | 13310 | @end ifclear |
b671e31b | 13311 | |
b2cacbfe AC |
13312 | @c ***************************************** |
13313 | @c * Cross-referencing tools | |
13314 | @c ***************************************** | |
88e1739c | 13315 | |
b2cacbfe AC |
13316 | @node The Cross-Referencing Tools gnatxref and gnatfind |
13317 | @chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind} | |
13318 | @findex gnatxref | |
13319 | @findex gnatfind | |
88e1739c FW |
13320 | |
13321 | @noindent | |
b2cacbfe AC |
13322 | The compiler generates cross-referencing information (unless |
13323 | you set the @samp{-gnatx} switch), which are saved in the @file{.ali} files. | |
13324 | This information indicates where in the source each entity is declared and | |
13325 | referenced. Note that entities in package Standard are not included, but | |
13326 | entities in all other predefined units are included in the output. | |
88e1739c | 13327 | |
b2cacbfe AC |
13328 | Before using any of these two tools, you need to compile successfully your |
13329 | application, so that GNAT gets a chance to generate the cross-referencing | |
13330 | information. | |
88e1739c | 13331 | |
b2cacbfe AC |
13332 | The two tools @code{gnatxref} and @code{gnatfind} take advantage of this |
13333 | information to provide the user with the capability to easily locate the | |
13334 | declaration and references to an entity. These tools are quite similar, | |
13335 | the difference being that @code{gnatfind} is intended for locating | |
13336 | definitions and/or references to a specified entity or entities, whereas | |
13337 | @code{gnatxref} is oriented to generating a full report of all | |
13338 | cross-references. | |
88e1739c | 13339 | |
b2cacbfe AC |
13340 | To use these tools, you must not compile your application using the |
13341 | @option{-gnatx} switch on the @command{gnatmake} command line | |
13342 | (@pxref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing | |
13343 | information will not be generated. | |
88e1739c | 13344 | |
b2cacbfe AC |
13345 | Note: to invoke @code{gnatxref} or @code{gnatfind} with a project file, |
13346 | use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}). | |
88e1739c | 13347 | |
7cd4527e | 13348 | @menu |
b2cacbfe AC |
13349 | * Switches for gnatxref:: |
13350 | * Switches for gnatfind:: | |
13351 | * Project Files for gnatxref and gnatfind:: | |
13352 | * Regular Expressions in gnatfind and gnatxref:: | |
13353 | * Examples of gnatxref Usage:: | |
13354 | * Examples of gnatfind Usage:: | |
7cd4527e | 13355 | @end menu |
88e1739c | 13356 | |
b2cacbfe AC |
13357 | @node Switches for gnatxref |
13358 | @section @code{gnatxref} Switches | |
88e1739c FW |
13359 | |
13360 | @noindent | |
b2cacbfe | 13361 | The command invocation for @code{gnatxref} is: |
7cd4527e | 13362 | @smallexample |
b2cacbfe AC |
13363 | @c $ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} |
13364 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
13365 | $ gnatxref @r{[}@var{switches}@r{]} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} | |
7cd4527e | 13366 | @end smallexample |
88e1739c | 13367 | |
b2cacbfe AC |
13368 | @noindent |
13369 | where | |
88e1739c | 13370 | |
b2cacbfe AC |
13371 | @table @var |
13372 | @item sourcefile1 | |
13373 | @itemx sourcefile2 | |
13374 | identifies the source files for which a report is to be generated. The | |
13375 | ``with''ed units will be processed too. You must provide at least one file. | |
88e1739c | 13376 | |
b2cacbfe AC |
13377 | These file names are considered to be regular expressions, so for instance |
13378 | specifying @file{source*.adb} is the same as giving every file in the current | |
13379 | directory whose name starts with @file{source} and whose extension is | |
13380 | @file{adb}. | |
88e1739c | 13381 | |
b2cacbfe AC |
13382 | You shouldn't specify any directory name, just base names. @command{gnatxref} |
13383 | and @command{gnatfind} will be able to locate these files by themselves using | |
13384 | the source path. If you specify directories, no result is produced. | |
88e1739c | 13385 | |
b2cacbfe | 13386 | @end table |
88e1739c FW |
13387 | |
13388 | @noindent | |
b2cacbfe AC |
13389 | The switches can be: |
13390 | @table @option | |
13391 | @c !sort! | |
13392 | @item --version | |
13393 | @cindex @option{--version} @command{gnatxref} | |
13394 | Display Copyright and version, then exit disregarding all other options. | |
88e1739c | 13395 | |
b2cacbfe AC |
13396 | @item --help |
13397 | @cindex @option{--help} @command{gnatxref} | |
13398 | If @option{--version} was not used, display usage, then exit disregarding | |
13399 | all other options. | |
88e1739c | 13400 | |
b2cacbfe AC |
13401 | @item ^-a^/ALL_FILES^ |
13402 | @cindex @option{^-a^/ALL_FILES^} (@command{gnatxref}) | |
13403 | If this switch is present, @code{gnatfind} and @code{gnatxref} will parse | |
13404 | the read-only files found in the library search path. Otherwise, these files | |
13405 | will be ignored. This option can be used to protect Gnat sources or your own | |
13406 | libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref} | |
13407 | much faster, and their output much smaller. Read-only here refers to access | |
13408 | or permissions status in the file system for the current user. | |
88e1739c | 13409 | |
b2cacbfe AC |
13410 | @item -aIDIR |
13411 | @cindex @option{-aIDIR} (@command{gnatxref}) | |
13412 | When looking for source files also look in directory DIR. The order in which | |
13413 | source file search is undertaken is the same as for @command{gnatmake}. | |
88e1739c | 13414 | |
b2cacbfe AC |
13415 | @item -aODIR |
13416 | @cindex @option{-aODIR} (@command{gnatxref}) | |
13417 | When searching for library and object files, look in directory | |
13418 | DIR. The order in which library files are searched is the same as for | |
13419 | @command{gnatmake}. | |
88e1739c | 13420 | |
b2cacbfe AC |
13421 | @item -nostdinc |
13422 | @cindex @option{-nostdinc} (@command{gnatxref}) | |
13423 | Do not look for sources in the system default directory. | |
88e1739c | 13424 | |
b2cacbfe AC |
13425 | @item -nostdlib |
13426 | @cindex @option{-nostdlib} (@command{gnatxref}) | |
13427 | Do not look for library files in the system default directory. | |
88e1739c | 13428 | |
b4d7b435 AC |
13429 | @item --ext=@var{extension} |
13430 | @cindex @option{--ext} (@command{gnatxref}) | |
13431 | Specify an alternate ali file extension. The default is @code{ali} and other | |
497716fe AC |
13432 | extensions (e.g. @code{gli} for C/C++ sources when using @option{-fdump-xref}) |
13433 | may be specified via this switch. Note that if this switch overrides the | |
13434 | default, which means that only the new extension will be considered. | |
b4d7b435 | 13435 | |
b2cacbfe AC |
13436 | @item --RTS=@var{rts-path} |
13437 | @cindex @option{--RTS} (@command{gnatxref}) | |
13438 | Specifies the default location of the runtime library. Same meaning as the | |
13439 | equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). | |
13440 | ||
13441 | @item ^-d^/DERIVED_TYPES^ | |
13442 | @cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref}) | |
13443 | If this switch is set @code{gnatxref} will output the parent type | |
13444 | reference for each matching derived types. | |
88e1739c | 13445 | |
b2cacbfe AC |
13446 | @item ^-f^/FULL_PATHNAME^ |
13447 | @cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatxref}) | |
13448 | If this switch is set, the output file names will be preceded by their | |
13449 | directory (if the file was found in the search path). If this switch is | |
13450 | not set, the directory will not be printed. | |
88e1739c | 13451 | |
b2cacbfe AC |
13452 | @item ^-g^/IGNORE_LOCALS^ |
13453 | @cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatxref}) | |
13454 | If this switch is set, information is output only for library-level | |
13455 | entities, ignoring local entities. The use of this switch may accelerate | |
13456 | @code{gnatfind} and @code{gnatxref}. | |
88e1739c | 13457 | |
b2cacbfe AC |
13458 | @item -IDIR |
13459 | @cindex @option{-IDIR} (@command{gnatxref}) | |
13460 | Equivalent to @samp{-aODIR -aIDIR}. | |
88e1739c | 13461 | |
b2cacbfe AC |
13462 | @item -pFILE |
13463 | @cindex @option{-pFILE} (@command{gnatxref}) | |
13464 | Specify a project file to use @xref{GNAT Project Manager}. | |
13465 | If you need to use the @file{.gpr} | |
13466 | project files, you should use gnatxref through the GNAT driver | |
13467 | (@command{gnat xref -Pproject}). | |
88e1739c | 13468 | |
b2cacbfe AC |
13469 | By default, @code{gnatxref} and @code{gnatfind} will try to locate a |
13470 | project file in the current directory. | |
88e1739c | 13471 | |
b2cacbfe AC |
13472 | If a project file is either specified or found by the tools, then the content |
13473 | of the source directory and object directory lines are added as if they | |
13474 | had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} | |
13475 | and @samp{^-aO^OBJECT_SEARCH^}. | |
13476 | @item ^-u^/UNUSED^ | |
13477 | Output only unused symbols. This may be really useful if you give your | |
13478 | main compilation unit on the command line, as @code{gnatxref} will then | |
13479 | display every unused entity and 'with'ed package. | |
88e1739c | 13480 | |
7cd4527e | 13481 | @ifclear vms |
b2cacbfe AC |
13482 | @item -v |
13483 | Instead of producing the default output, @code{gnatxref} will generate a | |
13484 | @file{tags} file that can be used by vi. For examples how to use this | |
13485 | feature, see @ref{Examples of gnatxref Usage}. The tags file is output | |
13486 | to the standard output, thus you will have to redirect it to a file. | |
7cd4527e | 13487 | @end ifclear |
88e1739c | 13488 | |
b2cacbfe | 13489 | @end table |
88e1739c FW |
13490 | |
13491 | @noindent | |
b2cacbfe AC |
13492 | All these switches may be in any order on the command line, and may even |
13493 | appear after the file names. They need not be separated by spaces, thus | |
13494 | you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of | |
13495 | @samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}. | |
7cd4527e | 13496 | |
b2cacbfe AC |
13497 | @node Switches for gnatfind |
13498 | @section @code{gnatfind} Switches | |
88e1739c | 13499 | |
b2cacbfe AC |
13500 | @noindent |
13501 | The command line for @code{gnatfind} is: | |
88e1739c | 13502 | |
88e1739c | 13503 | @smallexample |
b2cacbfe AC |
13504 | @c $ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} |
13505 | @c @r{[}@var{file1} @var{file2} @dots{}] | |
13506 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
13507 | $ gnatfind @r{[}@var{switches}@r{]} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} | |
13508 | @r{[}@var{file1} @var{file2} @dots{}@r{]} | |
88e1739c FW |
13509 | @end smallexample |
13510 | ||
13511 | @noindent | |
b2cacbfe | 13512 | where |
88e1739c | 13513 | |
b2cacbfe AC |
13514 | @table @var |
13515 | @item pattern | |
13516 | An entity will be output only if it matches the regular expression found | |
13517 | in @var{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}. | |
88e1739c | 13518 | |
b2cacbfe AC |
13519 | Omitting the pattern is equivalent to specifying @samp{*}, which |
13520 | will match any entity. Note that if you do not provide a pattern, you | |
13521 | have to provide both a sourcefile and a line. | |
88e1739c | 13522 | |
b2cacbfe AC |
13523 | Entity names are given in Latin-1, with uppercase/lowercase equivalence |
13524 | for matching purposes. At the current time there is no support for | |
13525 | 8-bit codes other than Latin-1, or for wide characters in identifiers. | |
88e1739c | 13526 | |
7cd4527e AC |
13527 | @item sourcefile |
13528 | @code{gnatfind} will look for references, bodies or declarations | |
66bfd481 RW |
13529 | of symbols referenced in @file{@var{sourcefile}}, at line @var{line} |
13530 | and column @var{column}. See @ref{Examples of gnatfind Usage} | |
7cd4527e | 13531 | for syntax examples. |
88e1739c | 13532 | |
7cd4527e AC |
13533 | @item line |
13534 | is a decimal integer identifying the line number containing | |
13535 | the reference to the entity (or entities) to be located. | |
88e1739c | 13536 | |
7cd4527e AC |
13537 | @item column |
13538 | is a decimal integer identifying the exact location on the | |
13539 | line of the first character of the identifier for the | |
13540 | entity reference. Columns are numbered from 1. | |
88e1739c | 13541 | |
d488f6ea | 13542 | @item file1 file2 @dots{} |
7cd4527e AC |
13543 | The search will be restricted to these source files. If none are given, then |
13544 | the search will be done for every library file in the search path. | |
13545 | These file must appear only after the pattern or sourcefile. | |
88e1739c | 13546 | |
7cd4527e | 13547 | These file names are considered to be regular expressions, so for instance |
443b3472 RW |
13548 | specifying @file{source*.adb} is the same as giving every file in the current |
13549 | directory whose name starts with @file{source} and whose extension is | |
13550 | @file{adb}. | |
88e1739c | 13551 | |
7cd4527e | 13552 | The location of the spec of the entity will always be displayed, even if it |
66bfd481 RW |
13553 | isn't in one of @file{@var{file1}}, @file{@var{file2}},@enddots{} The |
13554 | occurrences of the entity in the separate units of the ones given on the | |
13555 | command line will also be displayed. | |
88e1739c | 13556 | |
7cd4527e | 13557 | Note that if you specify at least one file in this part, @code{gnatfind} may |
d488f6ea | 13558 | sometimes not be able to find the body of the subprograms. |
88e1739c | 13559 | |
88e1739c FW |
13560 | @end table |
13561 | ||
13562 | @noindent | |
7cd4527e AC |
13563 | At least one of 'sourcefile' or 'pattern' has to be present on |
13564 | the command line. | |
88e1739c | 13565 | |
7cd4527e AC |
13566 | The following switches are available: |
13567 | @table @option | |
13568 | @c !sort! | |
88e1739c | 13569 | |
54df6fd9 VC |
13570 | @cindex @option{--version} @command{gnatfind} |
13571 | Display Copyright and version, then exit disregarding all other options. | |
13572 | ||
13573 | @item --help | |
13574 | @cindex @option{--help} @command{gnatfind} | |
13575 | If @option{--version} was not used, display usage, then exit disregarding | |
13576 | all other options. | |
13577 | ||
7cd4527e AC |
13578 | @item ^-a^/ALL_FILES^ |
13579 | @cindex @option{^-a^/ALL_FILES^} (@command{gnatfind}) | |
13580 | If this switch is present, @code{gnatfind} and @code{gnatxref} will parse | |
13581 | the read-only files found in the library search path. Otherwise, these files | |
13582 | will be ignored. This option can be used to protect Gnat sources or your own | |
13583 | libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref} | |
13584 | much faster, and their output much smaller. Read-only here refers to access | |
13585 | or permission status in the file system for the current user. | |
88e1739c | 13586 | |
7cd4527e AC |
13587 | @item -aIDIR |
13588 | @cindex @option{-aIDIR} (@command{gnatfind}) | |
13589 | When looking for source files also look in directory DIR. The order in which | |
984a64bc | 13590 | source file search is undertaken is the same as for @command{gnatmake}. |
88e1739c | 13591 | |
7cd4527e AC |
13592 | @item -aODIR |
13593 | @cindex @option{-aODIR} (@command{gnatfind}) | |
13594 | When searching for library and object files, look in directory | |
13595 | DIR. The order in which library files are searched is the same as for | |
984a64bc | 13596 | @command{gnatmake}. |
88e1739c | 13597 | |
7cd4527e AC |
13598 | @item -nostdinc |
13599 | @cindex @option{-nostdinc} (@command{gnatfind}) | |
13600 | Do not look for sources in the system default directory. | |
88e1739c | 13601 | |
7cd4527e AC |
13602 | @item -nostdlib |
13603 | @cindex @option{-nostdlib} (@command{gnatfind}) | |
13604 | Do not look for library files in the system default directory. | |
88e1739c | 13605 | |
0e47ff5c AC |
13606 | @item --ext=@var{extension} |
13607 | @cindex @option{--ext} (@command{gnatfind}) | |
13608 | Specify an alternate ali file extension. The default is @code{ali} and other | |
497716fe AC |
13609 | extensions (e.g. @code{gli} for C/C++ sources when using @option{-fdump-xref}) |
13610 | may be specified via this switch. Note that if this switch overrides the | |
13611 | default, which means that only the new extension will be considered. | |
0e47ff5c | 13612 | |
7cd4527e AC |
13613 | @item --RTS=@var{rts-path} |
13614 | @cindex @option{--RTS} (@command{gnatfind}) | |
13615 | Specifies the default location of the runtime library. Same meaning as the | |
984a64bc | 13616 | equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). |
88e1739c | 13617 | |
7cd4527e AC |
13618 | @item ^-d^/DERIVED_TYPE_INFORMATION^ |
13619 | @cindex @option{^-d^/DERIVED_TYPE_INFORMATION^} (@code{gnatfind}) | |
13620 | If this switch is set, then @code{gnatfind} will output the parent type | |
13621 | reference for each matching derived types. | |
88e1739c | 13622 | |
7cd4527e AC |
13623 | @item ^-e^/EXPRESSIONS^ |
13624 | @cindex @option{^-e^/EXPRESSIONS^} (@command{gnatfind}) | |
13625 | By default, @code{gnatfind} accept the simple regular expression set for | |
13626 | @samp{pattern}. If this switch is set, then the pattern will be | |
13627 | considered as full Unix-style regular expression. | |
88e1739c | 13628 | |
7cd4527e AC |
13629 | @item ^-f^/FULL_PATHNAME^ |
13630 | @cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatfind}) | |
13631 | If this switch is set, the output file names will be preceded by their | |
13632 | directory (if the file was found in the search path). If this switch is | |
13633 | not set, the directory will not be printed. | |
88e1739c | 13634 | |
7cd4527e AC |
13635 | @item ^-g^/IGNORE_LOCALS^ |
13636 | @cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatfind}) | |
13637 | If this switch is set, information is output only for library-level | |
13638 | entities, ignoring local entities. The use of this switch may accelerate | |
13639 | @code{gnatfind} and @code{gnatxref}. | |
88e1739c | 13640 | |
7cd4527e AC |
13641 | @item -IDIR |
13642 | @cindex @option{-IDIR} (@command{gnatfind}) | |
13643 | Equivalent to @samp{-aODIR -aIDIR}. | |
88e1739c | 13644 | |
7cd4527e AC |
13645 | @item -pFILE |
13646 | @cindex @option{-pFILE} (@command{gnatfind}) | |
b2cacbfe | 13647 | Specify a project file (@pxref{GNAT Project Manager}) to use. |
7cd4527e AC |
13648 | By default, @code{gnatxref} and @code{gnatfind} will try to locate a |
13649 | project file in the current directory. | |
88e1739c | 13650 | |
7cd4527e AC |
13651 | If a project file is either specified or found by the tools, then the content |
13652 | of the source directory and object directory lines are added as if they | |
13653 | had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} and | |
13654 | @samp{^-aO^/OBJECT_SEARCH^}. | |
88e1739c | 13655 | |
7cd4527e AC |
13656 | @item ^-r^/REFERENCES^ |
13657 | @cindex @option{^-r^/REFERENCES^} (@command{gnatfind}) | |
13658 | By default, @code{gnatfind} will output only the information about the | |
13659 | declaration, body or type completion of the entities. If this switch is | |
13660 | set, the @code{gnatfind} will locate every reference to the entities in | |
13661 | the files specified on the command line (or in every file in the search | |
13662 | path if no file is given on the command line). | |
88e1739c | 13663 | |
7cd4527e AC |
13664 | @item ^-s^/PRINT_LINES^ |
13665 | @cindex @option{^-s^/PRINT_LINES^} (@command{gnatfind}) | |
13666 | If this switch is set, then @code{gnatfind} will output the content | |
13667 | of the Ada source file lines were the entity was found. | |
88e1739c | 13668 | |
7cd4527e AC |
13669 | @item ^-t^/TYPE_HIERARCHY^ |
13670 | @cindex @option{^-t^/TYPE_HIERARCHY^} (@command{gnatfind}) | |
13671 | If this switch is set, then @code{gnatfind} will output the type hierarchy for | |
13672 | the specified type. It act like -d option but recursively from parent | |
13673 | type to parent type. When this switch is set it is not possible to | |
13674 | specify more than one file. | |
88e1739c | 13675 | |
7cd4527e | 13676 | @end table |
88e1739c FW |
13677 | |
13678 | @noindent | |
7cd4527e AC |
13679 | All these switches may be in any order on the command line, and may even |
13680 | appear after the file names. They need not be separated by spaces, thus | |
13681 | you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of | |
13682 | @samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}. | |
88e1739c | 13683 | |
7cd4527e AC |
13684 | As stated previously, gnatfind will search in every directory in the |
13685 | search path. You can force it to look only in the current directory if | |
13686 | you specify @code{*} at the end of the command line. | |
88e1739c | 13687 | |
7cd4527e AC |
13688 | @node Project Files for gnatxref and gnatfind |
13689 | @section Project Files for @command{gnatxref} and @command{gnatfind} | |
88e1739c FW |
13690 | |
13691 | @noindent | |
7cd4527e AC |
13692 | Project files allow a programmer to specify how to compile its |
13693 | application, where to find sources, etc. These files are used | |
13694 | @ifclear vms | |
e08b38f5 | 13695 | primarily by GPS, but they can also be used |
7cd4527e AC |
13696 | @end ifclear |
13697 | by the two tools | |
13698 | @code{gnatxref} and @code{gnatfind}. | |
88e1739c | 13699 | |
7cd4527e AC |
13700 | A project file name must end with @file{.gpr}. If a single one is |
13701 | present in the current directory, then @code{gnatxref} and @code{gnatfind} will | |
13702 | extract the information from it. If multiple project files are found, none of | |
13703 | them is read, and you have to use the @samp{-p} switch to specify the one | |
13704 | you want to use. | |
88e1739c | 13705 | |
7cd4527e AC |
13706 | The following lines can be included, even though most of them have default |
13707 | values which can be used in most cases. | |
13708 | The lines can be entered in any order in the file. | |
13709 | Except for @file{src_dir} and @file{obj_dir}, you can only have one instance of | |
13710 | each line. If you have multiple instances, only the last one is taken into | |
13711 | account. | |
88e1739c | 13712 | |
7cd4527e AC |
13713 | @table @code |
13714 | @item src_dir=DIR | |
13715 | [default: @code{"^./^[]^"}] | |
13716 | specifies a directory where to look for source files. Multiple @code{src_dir} | |
13717 | lines can be specified and they will be searched in the order they | |
13718 | are specified. | |
88e1739c | 13719 | |
7cd4527e AC |
13720 | @item obj_dir=DIR |
13721 | [default: @code{"^./^[]^"}] | |
13722 | specifies a directory where to look for object and library files. Multiple | |
13723 | @code{obj_dir} lines can be specified, and they will be searched in the order | |
13724 | they are specified | |
88e1739c | 13725 | |
7cd4527e AC |
13726 | @item comp_opt=SWITCHES |
13727 | [default: @code{""}] | |
13728 | creates a variable which can be referred to subsequently by using | |
13729 | the @code{$@{comp_opt@}} notation. This is intended to store the default | |
13730 | switches given to @command{gnatmake} and @command{gcc}. | |
88e1739c | 13731 | |
7cd4527e AC |
13732 | @item bind_opt=SWITCHES |
13733 | [default: @code{""}] | |
13734 | creates a variable which can be referred to subsequently by using | |
13735 | the @samp{$@{bind_opt@}} notation. This is intended to store the default | |
13736 | switches given to @command{gnatbind}. | |
88e1739c | 13737 | |
7cd4527e AC |
13738 | @item link_opt=SWITCHES |
13739 | [default: @code{""}] | |
13740 | creates a variable which can be referred to subsequently by using | |
13741 | the @samp{$@{link_opt@}} notation. This is intended to store the default | |
13742 | switches given to @command{gnatlink}. | |
88e1739c | 13743 | |
7cd4527e AC |
13744 | @item main=EXECUTABLE |
13745 | [default: @code{""}] | |
13746 | specifies the name of the executable for the application. This variable can | |
13747 | be referred to in the following lines by using the @samp{$@{main@}} notation. | |
88e1739c | 13748 | |
7cd4527e AC |
13749 | @ifset vms |
13750 | @item comp_cmd=COMMAND | |
13751 | [default: @code{"GNAT COMPILE /SEARCH=$@{src_dir@} /DEBUG /TRY_SEMANTICS"}] | |
13752 | @end ifset | |
13753 | @ifclear vms | |
13754 | @item comp_cmd=COMMAND | |
13755 | [default: @code{"gcc -c -I$@{src_dir@} -g -gnatq"}] | |
13756 | @end ifclear | |
13757 | specifies the command used to compile a single file in the application. | |
88e1739c | 13758 | |
7cd4527e AC |
13759 | @ifset vms |
13760 | @item make_cmd=COMMAND | |
13761 | [default: @code{"GNAT MAKE $@{main@} | |
13762 | /SOURCE_SEARCH=$@{src_dir@} /OBJECT_SEARCH=$@{obj_dir@} | |
13763 | /DEBUG /TRY_SEMANTICS /COMPILER_QUALIFIERS $@{comp_opt@} | |
13764 | /BINDER_QUALIFIERS $@{bind_opt@} /LINKER_QUALIFIERS $@{link_opt@}"}] | |
13765 | @end ifset | |
13766 | @ifclear vms | |
13767 | @item make_cmd=COMMAND | |
13768 | [default: @code{"gnatmake $@{main@} -aI$@{src_dir@} | |
6ccde948 RW |
13769 | -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@} |
13770 | -bargs $@{bind_opt@} -largs $@{link_opt@}"}] | |
7cd4527e AC |
13771 | @end ifclear |
13772 | specifies the command used to recompile the whole application. | |
88e1739c | 13773 | |
7cd4527e AC |
13774 | @item run_cmd=COMMAND |
13775 | [default: @code{"$@{main@}"}] | |
13776 | specifies the command used to run the application. | |
88e1739c | 13777 | |
7cd4527e AC |
13778 | @item debug_cmd=COMMAND |
13779 | [default: @code{"gdb $@{main@}"}] | |
13780 | specifies the command used to debug the application | |
88e1739c | 13781 | |
7cd4527e | 13782 | @end table |
88e1739c FW |
13783 | |
13784 | @noindent | |
7cd4527e AC |
13785 | @command{gnatxref} and @command{gnatfind} only take into account the |
13786 | @code{src_dir} and @code{obj_dir} lines, and ignore the others. | |
13787 | ||
13788 | @node Regular Expressions in gnatfind and gnatxref | |
13789 | @section Regular Expressions in @code{gnatfind} and @code{gnatxref} | |
88e1739c FW |
13790 | |
13791 | @noindent | |
7cd4527e AC |
13792 | As specified in the section about @command{gnatfind}, the pattern can be a |
13793 | regular expression. Actually, there are to set of regular expressions | |
e69044cb | 13794 | which are recognized by the program: |
88e1739c FW |
13795 | |
13796 | @table @code | |
7cd4527e AC |
13797 | @item globbing patterns |
13798 | These are the most usual regular expression. They are the same that you | |
13799 | generally used in a Unix shell command line, or in a DOS session. | |
88e1739c | 13800 | |
e69044cb | 13801 | Here is a more formal grammar: |
7cd4527e AC |
13802 | @smallexample |
13803 | @group | |
13804 | @iftex | |
13805 | @leftskip=.5cm | |
13806 | @end iftex | |
13807 | regexp ::= term | |
13808 | term ::= elmt -- matches elmt | |
13809 | term ::= elmt elmt -- concatenation (elmt then elmt) | |
13810 | term ::= * -- any string of 0 or more characters | |
13811 | term ::= ? -- matches any character | |
e69044cb | 13812 | term ::= [char @{char@}] -- matches any character listed |
7cd4527e AC |
13813 | term ::= [char - char] -- matches any character in range |
13814 | @end group | |
13815 | @end smallexample | |
88e1739c | 13816 | |
7cd4527e AC |
13817 | @item full regular expression |
13818 | The second set of regular expressions is much more powerful. This is the | |
13819 | type of regular expressions recognized by utilities such a @file{grep}. | |
88e1739c | 13820 | |
7cd4527e AC |
13821 | The following is the form of a regular expression, expressed in Ada |
13822 | reference manual style BNF is as follows | |
88e1739c | 13823 | |
7cd4527e AC |
13824 | @smallexample |
13825 | @iftex | |
13826 | @leftskip=.5cm | |
13827 | @end iftex | |
13828 | @group | |
d488f6ea | 13829 | regexp ::= term @{| term@} -- alternation (term or term @dots{}) |
88e1739c | 13830 | |
e69044cb | 13831 | term ::= item @{item@} -- concatenation (item then item) |
88e1739c | 13832 | |
7cd4527e AC |
13833 | item ::= elmt -- match elmt |
13834 | item ::= elmt * -- zero or more elmt's | |
13835 | item ::= elmt + -- one or more elmt's | |
13836 | item ::= elmt ? -- matches elmt or nothing | |
13837 | @end group | |
13838 | @group | |
13839 | elmt ::= nschar -- matches given character | |
13840 | elmt ::= [nschar @{nschar@}] -- matches any character listed | |
13841 | elmt ::= [^^^ nschar @{nschar@}] -- matches any character not listed | |
13842 | elmt ::= [char - char] -- matches chars in given range | |
13843 | elmt ::= \ char -- matches given character | |
13844 | elmt ::= . -- matches any single character | |
13845 | elmt ::= ( regexp ) -- parens used for grouping | |
88e1739c | 13846 | |
7cd4527e AC |
13847 | char ::= any character, including special characters |
13848 | nschar ::= any character except ()[].*+?^^^ | |
13849 | @end group | |
13850 | @end smallexample | |
88e1739c | 13851 | |
e69044cb | 13852 | Following are a few examples: |
88e1739c | 13853 | |
7cd4527e AC |
13854 | @table @samp |
13855 | @item abcde|fghi | |
443b3472 | 13856 | will match any of the two strings @samp{abcde} and @samp{fghi}, |
88e1739c | 13857 | |
7cd4527e | 13858 | @item abc*d |
443b3472 RW |
13859 | will match any string like @samp{abd}, @samp{abcd}, @samp{abccd}, |
13860 | @samp{abcccd}, and so on, | |
88e1739c | 13861 | |
7cd4527e AC |
13862 | @item [a-z]+ |
13863 | will match any string which has only lowercase characters in it (and at | |
e69044cb | 13864 | least one character. |
88e1739c | 13865 | |
7cd4527e AC |
13866 | @end table |
13867 | @end table | |
88e1739c | 13868 | |
7cd4527e AC |
13869 | @node Examples of gnatxref Usage |
13870 | @section Examples of @code{gnatxref} Usage | |
88e1739c | 13871 | |
7cd4527e | 13872 | @subsection General Usage |
88e1739c | 13873 | |
7cd4527e | 13874 | @noindent |
e69044cb | 13875 | For the following examples, we will consider the following units: |
88e1739c | 13876 | |
7cd4527e AC |
13877 | @smallexample @c ada |
13878 | @group | |
13879 | @cartouche | |
13880 | main.ads: | |
13881 | 1: with Bar; | |
13882 | 2: package Main is | |
13883 | 3: procedure Foo (B : in Integer); | |
13884 | 4: C : Integer; | |
13885 | 5: private | |
13886 | 6: D : Integer; | |
13887 | 7: end Main; | |
88e1739c | 13888 | |
7cd4527e AC |
13889 | main.adb: |
13890 | 1: package body Main is | |
13891 | 2: procedure Foo (B : in Integer) is | |
13892 | 3: begin | |
13893 | 4: C := B; | |
13894 | 5: D := B; | |
13895 | 6: Bar.Print (B); | |
13896 | 7: Bar.Print (C); | |
13897 | 8: end Foo; | |
13898 | 9: end Main; | |
13899 | ||
13900 | bar.ads: | |
13901 | 1: package Bar is | |
13902 | 2: procedure Print (B : Integer); | |
13903 | 3: end bar; | |
13904 | @end cartouche | |
13905 | @end group | |
13906 | @end smallexample | |
13907 | ||
13908 | @table @code | |
88e1739c FW |
13909 | |
13910 | @noindent | |
7cd4527e AC |
13911 | The first thing to do is to recompile your application (for instance, in |
13912 | that case just by doing a @samp{gnatmake main}, so that GNAT generates | |
13913 | the cross-referencing information. | |
13914 | You can then issue any of the following commands: | |
13915 | ||
13916 | @item gnatxref main.adb | |
13917 | @code{gnatxref} generates cross-reference information for main.adb | |
13918 | and every unit 'with'ed by main.adb. | |
88e1739c | 13919 | |
7cd4527e | 13920 | The output would be: |
88e1739c | 13921 | @smallexample |
7cd4527e AC |
13922 | @iftex |
13923 | @leftskip=0cm | |
13924 | @end iftex | |
13925 | B Type: Integer | |
13926 | Decl: bar.ads 2:22 | |
13927 | B Type: Integer | |
13928 | Decl: main.ads 3:20 | |
13929 | Body: main.adb 2:20 | |
13930 | Ref: main.adb 4:13 5:13 6:19 | |
13931 | Bar Type: Unit | |
13932 | Decl: bar.ads 1:9 | |
13933 | Ref: main.adb 6:8 7:8 | |
13934 | main.ads 1:6 | |
13935 | C Type: Integer | |
13936 | Decl: main.ads 4:5 | |
13937 | Modi: main.adb 4:8 | |
13938 | Ref: main.adb 7:19 | |
13939 | D Type: Integer | |
13940 | Decl: main.ads 6:5 | |
13941 | Modi: main.adb 5:8 | |
13942 | Foo Type: Unit | |
13943 | Decl: main.ads 3:15 | |
13944 | Body: main.adb 2:15 | |
13945 | Main Type: Unit | |
13946 | Decl: main.ads 2:9 | |
13947 | Body: main.adb 1:14 | |
13948 | Print Type: Unit | |
13949 | Decl: bar.ads 2:15 | |
13950 | Ref: main.adb 6:12 7:12 | |
88e1739c FW |
13951 | @end smallexample |
13952 | ||
13953 | @noindent | |
7cd4527e AC |
13954 | that is the entity @code{Main} is declared in main.ads, line 2, column 9, |
13955 | its body is in main.adb, line 1, column 14 and is not referenced any where. | |
88e1739c | 13956 | |
7cd4527e | 13957 | The entity @code{Print} is declared in bar.ads, line 2, column 15 and it |
770937fd | 13958 | is referenced in main.adb, line 6 column 12 and line 7 column 12. |
88e1739c | 13959 | |
7cd4527e AC |
13960 | @item gnatxref package1.adb package2.ads |
13961 | @code{gnatxref} will generates cross-reference information for | |
13962 | package1.adb, package2.ads and any other package 'with'ed by any | |
13963 | of these. | |
88e1739c | 13964 | |
7cd4527e | 13965 | @end table |
88e1739c | 13966 | |
7cd4527e AC |
13967 | @ifclear vms |
13968 | @subsection Using gnatxref with vi | |
88e1739c | 13969 | |
7cd4527e | 13970 | @code{gnatxref} can generate a tags file output, which can be used |
e69044cb | 13971 | directly from @command{vi}. Note that the standard version of @command{vi} |
7cd4527e | 13972 | will not work properly with overloaded symbols. Consider using another |
e69044cb | 13973 | free implementation of @command{vi}, such as @command{vim}. |
88e1739c | 13974 | |
7cd4527e AC |
13975 | @smallexample |
13976 | $ gnatxref -v gnatfind.adb > tags | |
13977 | @end smallexample | |
88e1739c | 13978 | |
7cd4527e AC |
13979 | @noindent |
13980 | will generate the tags file for @code{gnatfind} itself (if the sources | |
13981 | are in the search path!). | |
88e1739c | 13982 | |
66bfd481 RW |
13983 | From @command{vi}, you can then use the command @samp{:tag @var{entity}} |
13984 | (replacing @var{entity} by whatever you are looking for), and vi will | |
7cd4527e AC |
13985 | display a new file with the corresponding declaration of entity. |
13986 | @end ifclear | |
88e1739c | 13987 | |
7cd4527e AC |
13988 | @node Examples of gnatfind Usage |
13989 | @section Examples of @code{gnatfind} Usage | |
88e1739c | 13990 | |
88e1739c FW |
13991 | @table @code |
13992 | ||
7cd4527e AC |
13993 | @item gnatfind ^-f^/FULL_PATHNAME^ xyz:main.adb |
13994 | Find declarations for all entities xyz referenced at least once in | |
13995 | main.adb. The references are search in every library file in the search | |
13996 | path. | |
88e1739c | 13997 | |
7cd4527e AC |
13998 | The directories will be printed as well (as the @samp{^-f^/FULL_PATHNAME^} |
13999 | switch is set) | |
88e1739c | 14000 | |
7cd4527e AC |
14001 | The output will look like: |
14002 | @smallexample | |
14003 | ^directory/^[directory]^main.ads:106:14: xyz <= declaration | |
14004 | ^directory/^[directory]^main.adb:24:10: xyz <= body | |
14005 | ^directory/^[directory]^foo.ads:45:23: xyz <= declaration | |
14006 | @end smallexample | |
88e1739c | 14007 | |
7cd4527e AC |
14008 | @noindent |
14009 | that is to say, one of the entities xyz found in main.adb is declared at | |
14010 | line 12 of main.ads (and its body is in main.adb), and another one is | |
14011 | declared at line 45 of foo.ads | |
88e1739c | 14012 | |
7cd4527e AC |
14013 | @item gnatfind ^-fs^/FULL_PATHNAME/SOURCE_LINE^ xyz:main.adb |
14014 | This is the same command as the previous one, instead @code{gnatfind} will | |
14015 | display the content of the Ada source file lines. | |
88e1739c | 14016 | |
7cd4527e | 14017 | The output will look like: |
88e1739c | 14018 | |
7cd4527e AC |
14019 | @smallexample |
14020 | ^directory/^[directory]^main.ads:106:14: xyz <= declaration | |
14021 | procedure xyz; | |
14022 | ^directory/^[directory]^main.adb:24:10: xyz <= body | |
14023 | procedure xyz is | |
14024 | ^directory/^[directory]^foo.ads:45:23: xyz <= declaration | |
14025 | xyz : Integer; | |
14026 | @end smallexample | |
88e1739c | 14027 | |
7cd4527e AC |
14028 | @noindent |
14029 | This can make it easier to find exactly the location your are looking | |
14030 | for. | |
88e1739c | 14031 | |
7cd4527e AC |
14032 | @item gnatfind ^-r^/REFERENCES^ "*x*":main.ads:123 foo.adb |
14033 | Find references to all entities containing an x that are | |
14034 | referenced on line 123 of main.ads. | |
14035 | The references will be searched only in main.ads and foo.adb. | |
88e1739c | 14036 | |
7cd4527e AC |
14037 | @item gnatfind main.ads:123 |
14038 | Find declarations and bodies for all entities that are referenced on | |
14039 | line 123 of main.ads. | |
88e1739c | 14040 | |
7cd4527e | 14041 | This is the same as @code{gnatfind "*":main.adb:123}. |
88e1739c | 14042 | |
7cd4527e AC |
14043 | @item gnatfind ^mydir/^[mydir]^main.adb:123:45 |
14044 | Find the declaration for the entity referenced at column 45 in | |
14045 | line 123 of file main.adb in directory mydir. Note that it | |
14046 | is usual to omit the identifier name when the column is given, | |
14047 | since the column position identifies a unique reference. | |
88e1739c | 14048 | |
7cd4527e AC |
14049 | The column has to be the beginning of the identifier, and should not |
14050 | point to any character in the middle of the identifier. | |
88e1739c | 14051 | |
7cd4527e | 14052 | @end table |
88e1739c | 14053 | |
1037b0f4 | 14054 | @ifclear FSFEDITION |
7cd4527e AC |
14055 | @c ********************************* |
14056 | @node The GNAT Pretty-Printer gnatpp | |
14057 | @chapter The GNAT Pretty-Printer @command{gnatpp} | |
14058 | @findex gnatpp | |
14059 | @cindex Pretty-Printer | |
88e1739c | 14060 | |
c2658843 AC |
14061 | @menu |
14062 | * Switches for gnatpp:: | |
14063 | * Formatting Rules:: | |
14064 | @end menu | |
14065 | ||
7cd4527e AC |
14066 | @noindent |
14067 | ^The @command{gnatpp} tool^GNAT PRETTY^ is an ASIS-based utility | |
14068 | for source reformatting / pretty-printing. | |
14069 | It takes an Ada source file as input and generates a reformatted | |
14070 | version as output. | |
14071 | You can specify various style directives via switches; e.g., | |
14072 | identifier case conventions, rules of indentation, and comment layout. | |
88e1739c | 14073 | |
7b56a91b AC |
14074 | Note: A newly-redesigned set of formatting algorithms used by gnatpp |
14075 | is now available. | |
2838fa93 | 14076 | To invoke the old formatting algorithms, use the @option{--pp-old} switch. |
90b51aaf | 14077 | Support for @option{--pp-old} will be removed in some future version. |
7b56a91b | 14078 | |
f1a3590e AC |
14079 | To produce a reformatted file, @command{gnatpp} invokes the Ada |
14080 | compiler and generates and uses the ASIS tree for the input source; | |
14081 | thus the input must be legal Ada code. | |
88e1739c | 14082 | |
bde73c6b AC |
14083 | @command{gnatpp} cannot process sources that contain |
14084 | preprocessing directives. | |
0916df6a | 14085 | |
f1a3590e AC |
14086 | If the compilation unit contained in the input source depends |
14087 | semantically upon units located outside the current directory, you | |
14088 | have to provide the source search path when invoking | |
14089 | @command{gnatpp}. If these units are contained in files with names | |
14090 | that do not follow the GNAT file naming rules, you have to provide a | |
14091 | configuration file describing the corresponding naming scheme; see the | |
14092 | description of the @command{gnatpp} switches below. Another | |
14093 | possibility is to use a project file and to call @command{gnatpp} | |
14094 | through the @command{gnat} driver (see @ref{The GNAT Driver and | |
14095 | Project Files}). | |
88e1739c | 14096 | |
7cd4527e | 14097 | The @command{gnatpp} command has the form |
88e1739c | 14098 | |
7cd4527e | 14099 | @smallexample |
e074d476 AC |
14100 | @c $ gnatpp @ovar{switches} @var{filename} |
14101 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
5875f8d6 | 14102 | $ gnatpp @r{[}@var{switches}@r{]} @var{filename} @r{[}-cargs @var{gcc_switches}@r{]} |
7cd4527e | 14103 | @end smallexample |
88e1739c FW |
14104 | |
14105 | @noindent | |
7cd4527e AC |
14106 | where |
14107 | @itemize @bullet | |
14108 | @item | |
14109 | @var{switches} is an optional sequence of switches defining such properties as | |
14110 | the formatting rules, the source search path, and the destination for the | |
14111 | output source file | |
88e1739c | 14112 | |
7cd4527e AC |
14113 | @item |
14114 | @var{filename} is the name (including the extension) of the source file to | |
f1a3590e AC |
14115 | reformat; wildcards or several file names on the same gnatpp command are |
14116 | allowed. The file name may contain path information; it does not have to | |
9bc856dd | 14117 | follow the GNAT file naming rules |
5875f8d6 AC |
14118 | |
14119 | @item | |
14120 | @samp{@var{gcc_switches}} is a list of switches for | |
14121 | @command{gcc}. They will be passed on to all compiler invocations made by | |
f1a3590e | 14122 | @command{gnatpp} to generate the ASIS trees. Here you can provide |
5875f8d6 | 14123 | @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, |
f1a3590e | 14124 | use the @option{-gnatec} switch to set the configuration file, etc. |
7cd4527e | 14125 | @end itemize |
88e1739c | 14126 | |
7cd4527e AC |
14127 | @node Switches for gnatpp |
14128 | @section Switches for @command{gnatpp} | |
88e1739c | 14129 | |
7cd4527e AC |
14130 | @noindent |
14131 | The following subsections describe the various switches accepted by | |
14132 | @command{gnatpp}, organized by category. | |
88e1739c | 14133 | |
7cd4527e AC |
14134 | @ifclear vms |
14135 | You specify a switch by supplying a name and generally also a value. | |
14136 | In many cases the values for a switch with a given name are incompatible with | |
14137 | each other | |
14138 | (for example the switch that controls the casing of a reserved word may have | |
14139 | exactly one value: upper case, lower case, or | |
14140 | mixed case) and thus exactly one such switch can be in effect for an | |
14141 | invocation of @command{gnatpp}. | |
14142 | If more than one is supplied, the last one is used. | |
14143 | However, some values for the same switch are mutually compatible. | |
14144 | You may supply several such switches to @command{gnatpp}, but then | |
14145 | each must be specified in full, with both the name and the value. | |
14146 | Abbreviated forms (the name appearing once, followed by each value) are | |
14147 | not permitted. | |
7cd4527e | 14148 | @end ifclear |
88e1739c FW |
14149 | |
14150 | @ifset vms | |
7cd4527e AC |
14151 | In many cases the set of options for a given qualifier are incompatible with |
14152 | each other (for example the qualifier that controls the casing of a reserved | |
14153 | word may have exactly one option, which specifies either upper case, lower | |
14154 | case, or mixed case), and thus exactly one such option can be in effect for | |
14155 | an invocation of @command{gnatpp}. | |
14156 | If more than one is supplied, the last one is used. | |
88e1739c | 14157 | @end ifset |
7cd4527e | 14158 | |
7cd4527e AC |
14159 | @menu |
14160 | * Alignment Control:: | |
14161 | * Casing Control:: | |
7cd4527e AC |
14162 | * General Text Layout Control:: |
14163 | * Other Formatting Options:: | |
14164 | * Setting the Source Search Path:: | |
14165 | * Output File Control:: | |
14166 | * Other gnatpp Switches:: | |
14167 | @end menu | |
14168 | ||
7cd4527e AC |
14169 | @node Alignment Control |
14170 | @subsection Alignment Control | |
14171 | @cindex Alignment control in @command{gnatpp} | |
14172 | ||
14173 | @noindent | |
14174 | Programs can be easier to read if certain constructs are vertically aligned. | |
f1a3590e AC |
14175 | By default alignment of the following constructs is set ON: |
14176 | @code{:} in declarations, @code{:=} in initializations in declarations | |
14177 | @code{:=} in assignment statements, @code{=>} in associations, and | |
14178 | @code{at} keywords in the component clauses in record | |
14179 | representation clauses. | |
7cd4527e AC |
14180 | |
14181 | @table @option | |
14182 | @cindex @option{^-A@var{n}^/ALIGN^} (@command{gnatpp}) | |
88e1739c | 14183 | |
7cd4527e | 14184 | @item ^-A0^/ALIGN=OFF^ |
f1a3590e | 14185 | Set alignment to OFF |
88e1739c | 14186 | |
f1a3590e AC |
14187 | @item ^-A1^/ALIGN=ON^ |
14188 | Set alignment to ON | |
7cd4527e | 14189 | @end table |
88e1739c | 14190 | |
7cd4527e AC |
14191 | @node Casing Control |
14192 | @subsection Casing Control | |
14193 | @cindex Casing control in @command{gnatpp} | |
88e1739c | 14194 | |
7cd4527e AC |
14195 | @noindent |
14196 | @command{gnatpp} allows you to specify the casing for reserved words, | |
14197 | pragma names, attribute designators and identifiers. | |
14198 | For identifiers you may define a | |
14199 | general rule for name casing but also override this rule | |
14200 | via a set of dictionary files. | |
88e1739c | 14201 | |
7cd4527e | 14202 | Three types of casing are supported: lower case, upper case, and mixed case. |
7cd4527e AC |
14203 | ``Mixed case'' means that the first letter, and also each letter immediately |
14204 | following an underscore, are converted to their uppercase forms; | |
14205 | all the other letters are converted to their lowercase forms. | |
88e1739c | 14206 | |
7cd4527e AC |
14207 | @table @option |
14208 | @cindex @option{^-a@var{x}^/ATTRIBUTE^} (@command{gnatpp}) | |
14209 | @item ^-aL^/ATTRIBUTE_CASING=LOWER_CASE^ | |
14210 | Attribute designators are lower case | |
88e1739c | 14211 | |
7cd4527e AC |
14212 | @item ^-aU^/ATTRIBUTE_CASING=UPPER_CASE^ |
14213 | Attribute designators are upper case | |
88e1739c | 14214 | |
7cd4527e AC |
14215 | @item ^-aM^/ATTRIBUTE_CASING=MIXED_CASE^ |
14216 | Attribute designators are mixed case (this is the default) | |
88e1739c | 14217 | |
7cd4527e AC |
14218 | @cindex @option{^-k@var{x}^/KEYWORD_CASING^} (@command{gnatpp}) |
14219 | @item ^-kL^/KEYWORD_CASING=LOWER_CASE^ | |
14220 | Keywords (technically, these are known in Ada as @emph{reserved words}) are | |
14221 | lower case (this is the default) | |
88e1739c | 14222 | |
7cd4527e AC |
14223 | @item ^-kU^/KEYWORD_CASING=UPPER_CASE^ |
14224 | Keywords are upper case | |
88e1739c | 14225 | |
7cd4527e AC |
14226 | @cindex @option{^-n@var{x}^/NAME_CASING^} (@command{gnatpp}) |
14227 | @item ^-nD^/NAME_CASING=AS_DECLARED^ | |
14228 | Name casing for defining occurrences are as they appear in the source file | |
14229 | (this is the default) | |
88e1739c | 14230 | |
7cd4527e AC |
14231 | @item ^-nU^/NAME_CASING=UPPER_CASE^ |
14232 | Names are in upper case | |
88e1739c | 14233 | |
7cd4527e AC |
14234 | @item ^-nL^/NAME_CASING=LOWER_CASE^ |
14235 | Names are in lower case | |
88e1739c | 14236 | |
7cd4527e AC |
14237 | @item ^-nM^/NAME_CASING=MIXED_CASE^ |
14238 | Names are in mixed case | |
88e1739c | 14239 | |
9f8d1e5c AC |
14240 | @cindex @option{^-ne@var{x}^/ENUM_CASING^} (@command{gnatpp}) |
14241 | @item ^-neD^/ENUM_CASING=AS_DECLARED^ | |
14242 | Enumeration literal casing for defining occurrences are as they appear in the | |
14243 | source file. Overrides ^-n^/NAME_CASING^ casing setting. | |
14244 | ||
14245 | @item ^-neU^/ENUM_CASING=UPPER_CASE^ | |
14246 | Enumeration literals are in upper case. Overrides ^-n^/NAME_CASING^ casing | |
14247 | setting. | |
14248 | ||
14249 | @item ^-neL^/ENUM_CASING=LOWER_CASE^ | |
14250 | Enumeration literals are in lower case. Overrides ^-n^/NAME_CASING^ casing | |
14251 | setting. | |
14252 | ||
14253 | @item ^-neM^/ENUM_CASING=MIXED_CASE^ | |
14254 | Enumeration literals are in mixed case. Overrides ^-n^/NAME_CASING^ casing | |
14255 | setting. | |
14256 | ||
ef992452 AC |
14257 | @cindex @option{^-nt@var{x}^/TYPE_CASING^} (@command{gnatpp}) |
14258 | @item ^-neD^/TYPE_CASING=AS_DECLARED^ | |
7a6c40a6 RD |
14259 | Names introduced by type and subtype declarations are always |
14260 | cased as they appear in the declaration in the source file. | |
14261 | Overrides ^-n^/NAME_CASING^ casing setting. | |
ef992452 AC |
14262 | |
14263 | @item ^-ntU^/TYPE_CASING=UPPER_CASE^ | |
7a6c40a6 RD |
14264 | Names introduced by type and subtype declarations are always in |
14265 | upper case. Overrides ^-n^/NAME_CASING^ casing setting. | |
ef992452 AC |
14266 | |
14267 | @item ^-ntL^/TYPE_CASING=LOWER_CASE^ | |
7a6c40a6 RD |
14268 | Names introduced by type and subtype declarations are always in |
14269 | lower case. Overrides ^-n^/NAME_CASING^ casing setting. | |
ef992452 AC |
14270 | |
14271 | @item ^-ntM^/TYPE_CASING=MIXED_CASE^ | |
7a6c40a6 RD |
14272 | Names introduced by type and subtype declarations are always in |
14273 | mixed case. Overrides ^-n^/NAME_CASING^ casing setting. | |
ef992452 | 14274 | |
be4c5193 AC |
14275 | @item ^-nnU^/NUMBER_CASING=UPPER_CASE^ |
14276 | Names introduced by number declarations are always in | |
14277 | upper case. Overrides ^-n^/NAME_CASING^ casing setting. | |
14278 | ||
14279 | @item ^-nnL^/NUMBER_CASING=LOWER_CASE^ | |
14280 | Names introduced by number declarations are always in | |
14281 | lower case. Overrides ^-n^/NAME_CASING^ casing setting. | |
14282 | ||
14283 | @item ^-nnM^/NUMBER_CASING=MIXED_CASE^ | |
14284 | Names introduced by number declarations are always in | |
14285 | mixed case. Overrides ^-n^/NAME_CASING^ casing setting. | |
14286 | ||
7cd4527e AC |
14287 | @cindex @option{^-p@var{x}^/PRAGMA_CASING^} (@command{gnatpp}) |
14288 | @item ^-pL^/PRAGMA_CASING=LOWER_CASE^ | |
14289 | Pragma names are lower case | |
88e1739c | 14290 | |
7cd4527e AC |
14291 | @item ^-pU^/PRAGMA_CASING=UPPER_CASE^ |
14292 | Pragma names are upper case | |
14293 | ||
14294 | @item ^-pM^/PRAGMA_CASING=MIXED_CASE^ | |
14295 | Pragma names are mixed case (this is the default) | |
14296 | ||
14297 | @item ^-D@var{file}^/DICTIONARY=@var{file}^ | |
14298 | @cindex @option{^-D^/DICTIONARY^} (@command{gnatpp}) | |
14299 | Use @var{file} as a @emph{dictionary file} that defines | |
14300 | the casing for a set of specified names, | |
14301 | thereby overriding the effect on these names by | |
14302 | any explicit or implicit | |
14303 | ^-n^/NAME_CASING^ switch. | |
14304 | To supply more than one dictionary file, | |
14305 | use ^several @option{-D} switches^a list of files as options^. | |
88e1739c FW |
14306 | |
14307 | @noindent | |
7cd4527e AC |
14308 | @option{gnatpp} implicitly uses a @emph{default dictionary file} |
14309 | to define the casing for the Ada predefined names and | |
14310 | the names declared in the GNAT libraries. | |
88e1739c | 14311 | |
7cd4527e AC |
14312 | @item ^-D-^/SPECIFIC_CASING^ |
14313 | @cindex @option{^-D-^/SPECIFIC_CASING^} (@command{gnatpp}) | |
14314 | Do not use the default dictionary file; | |
14315 | instead, use the casing | |
14316 | defined by a @option{^-n^/NAME_CASING^} switch and any explicit | |
14317 | dictionary file(s) | |
14318 | @end table | |
88e1739c | 14319 | |
7cd4527e AC |
14320 | @noindent |
14321 | The structure of a dictionary file, and details on the conventions | |
14322 | used in the default dictionary file, are defined in @ref{Name Casing}. | |
88e1739c | 14323 | |
7cd4527e AC |
14324 | The @option{^-D-^/SPECIFIC_CASING^} and |
14325 | @option{^-D@var{file}^/DICTIONARY=@var{file}^} switches are mutually | |
14326 | compatible. | |
88e1739c | 14327 | |
88e1739c | 14328 | @noindent |
7cd4527e | 14329 | This group of @command{gnatpp} switches controls the layout of comments and |
984a64bc | 14330 | complex syntactic constructs. See @ref{Formatting Comments} for details |
7cd4527e | 14331 | on their effect. |
88e1739c | 14332 | |
7cd4527e AC |
14333 | @table @option |
14334 | @cindex @option{^-c@var{n}^/COMMENTS_LAYOUT^} (@command{gnatpp}) | |
8a36a0cc | 14335 | @item ^-c0^/COMMENTS_LAYOUT=UNTOUCHED^ |
f1a3590e | 14336 | All comments remain unchanged. |
8a36a0cc | 14337 | |
7cd4527e | 14338 | @item ^-c1^/COMMENTS_LAYOUT=DEFAULT^ |
f1a3590e AC |
14339 | GNAT-style comment line indentation. |
14340 | This is the default. | |
88e1739c | 14341 | |
7cd4527e | 14342 | @item ^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^ |
f1a3590e | 14343 | GNAT-style comment beginning. |
88e1739c | 14344 | |
7cd4527e | 14345 | @item ^-c4^/COMMENTS_LAYOUT=REFORMAT^ |
f1a3590e | 14346 | Fill comment blocks. |
88e1739c | 14347 | |
c690a2ec | 14348 | @item ^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^ |
f1a3590e AC |
14349 | Keep unchanged special form comments. |
14350 | This is the default. | |
c690a2ec | 14351 | |
4058ddcc AC |
14352 | @item --comments-only |
14353 | @cindex @option{--comments-only} @command{gnatpp} | |
14354 | Format just the comments. | |
14355 | ||
2d43d3fe SR |
14356 | @cindex @option{^--no-separate-is^/NO_SEPARATE_IS^} (@command{gnatpp}) |
14357 | @item ^--no-separate-is^/NO_SEPARATE_IS^ | |
14358 | Do not place the keyword @code{is} on a separate line in a subprogram body in | |
d99ff0f4 | 14359 | case if the spec occupies more than one line. |
2d43d3fe | 14360 | |
c690a2ec RD |
14361 | @cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp}) |
14362 | @item ^--separate-loop-then^/SEPARATE_LOOP_THEN^ | |
14363 | Place the keyword @code{loop} in FOR and WHILE loop statements and the | |
a2ad1f79 RD |
14364 | keyword @code{then} in IF statements on a separate line. |
14365 | ||
14366 | @cindex @option{^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^} (@command{gnatpp}) | |
14367 | @item ^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^ | |
14368 | Do not place the keyword @code{loop} in FOR and WHILE loop statements and the | |
e69044cb | 14369 | keyword @code{then} in IF statements on a separate line. This option is |
a2ad1f79 | 14370 | incompatible with @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} option. |
c690a2ec | 14371 | |
a2c20cfa AC |
14372 | @cindex @option{^--use-on-new-line^/USE_ON_NEW_LINE^} (@command{gnatpp}) |
14373 | @item ^--use-on-new-line^/USE_ON_NEW_LINE^ | |
14374 | Start each USE clause in a context clause from a separate line. | |
14375 | ||
5216b599 AC |
14376 | @cindex @option{^--insert-blank-lines^/INSERT_BLANK_LINES^} (@command{gnatpp}) |
14377 | @item ^--insert-blank-lines^/INSERT_BLANK_LINES^ | |
14378 | Insert blank lines where appropriate (between bodies and other large | |
14379 | constructs). | |
14380 | ||
14381 | @cindex @option{^--preserve-blank-lines^/PRESERVE_BLANK_LINES^} (@command{gnatpp}) | |
14382 | @item ^--preserve-blank-lines^/PRESERVE_BLANK_LINES^ | |
14383 | Preserve blank lines in the input. By default, gnatpp will squeeze | |
14384 | multiple blank lines down to one. | |
14385 | ||
88e1739c FW |
14386 | @end table |
14387 | ||
14388 | @ifclear vms | |
7cd4527e | 14389 | @noindent |
f1a3590e AC |
14390 | The @option{-c} switches are compatible with one another, except that |
14391 | the @option{-c0} switch disables all other comment formatting | |
14392 | switches. | |
7cd4527e | 14393 | @end ifclear |
88e1739c | 14394 | |
7cd4527e AC |
14395 | @ifset vms |
14396 | @noindent | |
f1a3590e AC |
14397 | For the @option{/COMMENTS_LAYOUT} qualifier, |
14398 | The @option{GNAT_BEGINNING}, @option{REFORMAT}, and @option{DEFAULT} | |
14399 | options are compatible with one another. | |
7cd4527e | 14400 | @end ifset |
88e1739c | 14401 | |
7cd4527e AC |
14402 | @node General Text Layout Control |
14403 | @subsection General Text Layout Control | |
88e1739c | 14404 | |
7cd4527e AC |
14405 | @noindent |
14406 | These switches allow control over line length and indentation. | |
88e1739c | 14407 | |
7cd4527e | 14408 | @table @option |
66bfd481 | 14409 | @item ^-M@var{nnn}^/LINE_LENGTH_MAX=@var{nnn}^ |
7cd4527e | 14410 | @cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp}) |
66bfd481 | 14411 | Maximum line length, @var{nnn} from 32@dots{}256, the default value is 79 |
88e1739c | 14412 | |
66bfd481 | 14413 | @item ^-i@var{nnn}^/INDENTATION_LEVEL=@var{nnn}^ |
7cd4527e | 14414 | @cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp}) |
66bfd481 | 14415 | Indentation level, @var{nnn} from 1@dots{}9, the default value is 3 |
88e1739c | 14416 | |
66bfd481 | 14417 | @item ^-cl@var{nnn}^/CONTINUATION_INDENT=@var{nnn}^ |
7cd4527e AC |
14418 | @cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp}) |
14419 | Indentation level for continuation lines (relative to the line being | |
66bfd481 | 14420 | continued), @var{nnn} from 1@dots{}9. |
7cd4527e | 14421 | The default |
d99ff0f4 | 14422 | value is one less than the (normal) indentation level, unless the |
7cd4527e AC |
14423 | indentation is set to 1 (in which case the default value for continuation |
14424 | line indentation is also 1) | |
14425 | @end table | |
88e1739c | 14426 | |
7cd4527e AC |
14427 | @node Other Formatting Options |
14428 | @subsection Other Formatting Options | |
14429 | ||
14430 | @noindent | |
f1a3590e | 14431 | These switches control other formatting not listed above. |
7cd4527e AC |
14432 | |
14433 | @table @option | |
ab986406 AC |
14434 | @item --decimal-grouping=@var{n} |
14435 | @cindex @option{--decimal-grouping} @command{gnatpp} | |
14436 | Put underscores in decimal literals (numeric literals without a base) | |
14437 | every @var{n} characters. If a literal already has one or more | |
14438 | underscores, it is not modified. For example, with | |
14439 | @code{--decimal-grouping=3}, @code{1000000} will be changed to | |
14440 | @code{1_000_000}. | |
14441 | ||
14442 | @item --based-grouping=@var{n} | |
14443 | @cindex @option{--based-grouping} @command{gnatpp} | |
14444 | Same as @code{--decimal-grouping}, but for based literals. For | |
14445 | example, with @code{--based-grouping=4}, @code{16#0001FFFE#} will be | |
14446 | changed to @code{16#0001_FFFE#}. | |
14447 | ||
f1a3590e AC |
14448 | @item ^--RM-style-spacing^/RM_STYLE_SPACING^ |
14449 | @cindex @option{^--RM-style-spacing^/RM_STYLE_SPACING^} (@command{gnatpp}) | |
14450 | Do not insert an extra blank before various occurrences of | |
14451 | `(' and `:'. This also turns off alignment. | |
7cd4527e AC |
14452 | |
14453 | @item ^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^ | |
14454 | @cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp}) | |
14455 | Insert a Form Feed character after a pragma Page. | |
14456 | ||
a4901c08 AC |
14457 | @item ^--call_threshold=@var{nnn}^/MAX_ACT=@var{nnn}^ |
14458 | @cindex @option{^--call_threshold^/MAX_ACT^} (@command{gnatpp}) | |
14459 | If the number of parameter associations is greater than @var{nnn} and if at | |
14460 | least one association uses named notation, start each association from | |
14461 | a new line. If @var{nnn} is 0, no check for the number of associations | |
f1a3590e | 14462 | is made; this is the default. |
a4901c08 AC |
14463 | |
14464 | @item ^--par_threshold=@var{nnn}^/MAX_PAR=@var{nnn}^ | |
14465 | @cindex @option{^--par_threshold^/MAX_PAR^} (@command{gnatpp}) | |
14466 | If the number of parameter specifications is greater than @var{nnn} | |
14467 | (or equal to @var{nnn} in case of a function), start each specification from | |
14468 | a new line. The default for @var{nnn} is 3. | |
7cd4527e AC |
14469 | @end table |
14470 | ||
14471 | @node Setting the Source Search Path | |
14472 | @subsection Setting the Source Search Path | |
88e1739c FW |
14473 | |
14474 | @noindent | |
7cd4527e | 14475 | To define the search path for the input source file, @command{gnatpp} |
f1a3590e | 14476 | uses the same switches as the GNAT compiler, with the same effects: |
88e1739c | 14477 | |
7cd4527e AC |
14478 | @table @option |
14479 | @item ^-I^/SEARCH=^@var{dir} | |
2c9f8c0a | 14480 | @cindex @option{^-I^/SEARCH^} (@command{gnatpp}) |
88e1739c | 14481 | |
7cd4527e | 14482 | @item ^-I-^/NOCURRENT_DIRECTORY^ |
2c9f8c0a | 14483 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatpp}) |
88e1739c | 14484 | |
7cd4527e | 14485 | @item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE^=@var{path} |
2c9f8c0a | 14486 | @cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@command{gnatpp}) |
88e1739c | 14487 | |
7cd4527e | 14488 | @item ^--RTS^/RUNTIME_SYSTEM^=@var{path} |
2c9f8c0a | 14489 | @cindex @option{^--RTS^/RUNTIME_SYSTEM^} (@command{gnatpp}) |
88e1739c | 14490 | |
7cd4527e | 14491 | @end table |
88e1739c | 14492 | |
7cd4527e AC |
14493 | @node Output File Control |
14494 | @subsection Output File Control | |
14495 | ||
14496 | @noindent | |
f1a3590e AC |
14497 | By default the output is sent to a file whose name is obtained by appending |
14498 | the ^@file{.pp}^@file{$PP}^ suffix to the name of the input file. | |
14499 | If the file with this name already exists, it is overwritten. | |
7cd4527e AC |
14500 | Thus if the input file is @file{^my_ada_proc.adb^MY_ADA_PROC.ADB^} then |
14501 | @command{gnatpp} will produce @file{^my_ada_proc.adb.pp^MY_ADA_PROC.ADB$PP^} | |
14502 | as output file. | |
14503 | The output may be redirected by the following switches: | |
14504 | ||
14505 | @table @option | |
14506 | @item ^-pipe^/STANDARD_OUTPUT^ | |
2c9f8c0a | 14507 | @cindex @option{^-pipe^/STANDARD_OUTPUT^} (@command{gnatpp}) |
7cd4527e AC |
14508 | Send the output to @code{Standard_Output} |
14509 | ||
14510 | @item ^-o @var{output_file}^/OUTPUT=@var{output_file}^ | |
14511 | @cindex @option{^-o^/OUTPUT^} (@code{gnatpp}) | |
14512 | Write the output into @var{output_file}. | |
14513 | If @var{output_file} already exists, @command{gnatpp} terminates without | |
14514 | reading or processing the input file. | |
14515 | ||
14516 | @item ^-of ^/FORCED_OUTPUT=^@var{output_file} | |
2c9f8c0a | 14517 | @cindex @option{^-of^/FORCED_OUTPUT^} (@command{gnatpp}) |
7cd4527e AC |
14518 | Write the output into @var{output_file}, overwriting the existing file |
14519 | (if one is present). | |
14520 | ||
14521 | @item ^-r^/REPLACE^ | |
2c9f8c0a | 14522 | @cindex @option{^-r^/REPLACE^} (@command{gnatpp}) |
7cd4527e AC |
14523 | Replace the input source file with the reformatted output, and copy the |
14524 | original input source into the file whose name is obtained by appending the | |
14525 | ^@file{.npp}^@file{$NPP}^ suffix to the name of the input file. | |
14526 | If a file with this name already exists, @command{gnatpp} terminates without | |
14527 | reading or processing the input file. | |
14528 | ||
14529 | @item ^-rf^/OVERRIDING_REPLACE^ | |
14530 | @cindex @option{^-rf^/OVERRIDING_REPLACE^} (@code{gnatpp}) | |
14531 | Like @option{^-r^/REPLACE^} except that if the file with the specified name | |
14532 | already exists, it is overwritten. | |
8a36a0cc | 14533 | |
1a5f40e1 | 14534 | @item ^-rnb^/REPLACE_NO_BACKUP^ |
2c9f8c0a | 14535 | @cindex @option{^-rnb^/REPLACE_NO_BACKUP^} (@command{gnatpp}) |
8a36a0cc AC |
14536 | Replace the input source file with the reformatted output without |
14537 | creating any backup copy of the input source. | |
4edb2be0 AC |
14538 | |
14539 | @item ^--eol=@var{xxx}^/END_OF_LINE=@var{xxx}^ | |
14540 | @cindex @option{^--eol^/END_OF_LINE^} (@code{gnatpp}) | |
f1a3590e AC |
14541 | Specifies the line-ending style of the reformatted output file. The @var{xxx} |
14542 | ^string specified with the switch^option^ may be: | |
4edb2be0 AC |
14543 | @itemize @bullet |
14544 | @item ``@option{^dos^DOS^}'' MS DOS style, lines end with CR LF characters | |
14545 | @item ``@option{^crlf^CRLF^}'' | |
f1a3590e | 14546 | the same as @option{^dos^DOS^} |
4edb2be0 AC |
14547 | @item ``@option{^unix^UNIX^}'' UNIX style, lines end with LF character |
14548 | @item ``@option{^lf^LF^}'' | |
14549 | the same as @option{^unix^UNIX^} | |
14550 | @end itemize | |
14551 | ||
e08b38f5 VC |
14552 | @item ^-W^/RESULT_ENCODING=^@var{e} |
14553 | @cindex @option{^-W^/RESULT_ENCODING=^} (@command{gnatpp}) | |
f1a3590e | 14554 | Specify the wide character encoding method for the input and output files. |
e08b38f5 VC |
14555 | @var{e} is one of the following: |
14556 | ||
14557 | @itemize @bullet | |
14558 | ||
14559 | @item ^h^HEX^ | |
14560 | Hex encoding | |
14561 | ||
14562 | @item ^u^UPPER^ | |
14563 | Upper half encoding | |
14564 | ||
14565 | @item ^s^SHIFT_JIS^ | |
14566 | Shift/JIS encoding | |
14567 | ||
14568 | @item ^e^EUC^ | |
14569 | EUC encoding | |
14570 | ||
14571 | @item ^8^UTF8^ | |
14572 | UTF-8 encoding | |
14573 | ||
14574 | @item ^b^BRACKETS^ | |
14575 | Brackets encoding (default value) | |
14576 | @end itemize | |
14577 | ||
7cd4527e | 14578 | @end table |
88e1739c | 14579 | |
7cd4527e | 14580 | @noindent |
f1a3590e | 14581 | Options @option{^-o^/OUTPUT^} and |
7cd4527e | 14582 | @option{^-of^/FORCED_OUTPUT^} are allowed only if the call to gnatpp |
4edb2be0 AC |
14583 | contains only one file to reformat. |
14584 | Option | |
14585 | @option{^--eol^/END_OF_LINE^} | |
e08b38f5 VC |
14586 | and |
14587 | @option{^-W^/RESULT_ENCODING^} | |
32e209e4 | 14588 | cannot be used together |
4edb2be0 | 14589 | with @option{^-pipe^/STANDARD_OUTPUT^} option. |
88e1739c | 14590 | |
7cd4527e AC |
14591 | @node Other gnatpp Switches |
14592 | @subsection Other @code{gnatpp} Switches | |
14593 | ||
14594 | @noindent | |
14595 | The additional @command{gnatpp} switches are defined in this subsection. | |
88e1739c | 14596 | |
7cd4527e | 14597 | @table @option |
327b1ba4 AC |
14598 | @item --version |
14599 | @cindex @option{--version} @command{gnatpp} | |
f1a3590e | 14600 | Display copyright and version, then exit disregarding all other options. |
327b1ba4 AC |
14601 | |
14602 | @item --help | |
14603 | @cindex @option{--help} @command{gnatpp} | |
14604 | Display usage, then exit disregarding all other options. | |
14605 | ||
c97d7285 AC |
14606 | @item -P @var{file} |
14607 | @cindex @option{-P} @command{gnatpp} | |
14608 | Indicates the name of the project file that describes the set of sources | |
14609 | to be processed. The exact set of argument sources depends on other options | |
f1a3590e | 14610 | specified; see below. |
c97d7285 AC |
14611 | |
14612 | @item -U | |
14613 | @cindex @option{-U} @command{gnatpp} | |
14614 | If a project file is specified and no argument source is explicitly | |
14615 | specified (either directly or by means of @option{-files} option), process | |
14616 | all the units of the closure of the argument project. Otherwise this option | |
14617 | has no effect. | |
14618 | ||
14619 | @item -U @var{main_unit} | |
14620 | If a project file is specified and no argument source is explicitly | |
14621 | specified (either directly or by means of @option{-files} option), process | |
14622 | the closure of units rooted at @var{main_unit}. Otherwise this option | |
14623 | has no effect. | |
14624 | ||
14625 | @item -X@var{name}=@var{value} | |
14626 | @cindex @option{-X} @command{gnatpp} | |
14627 | Indicates that external variable @var{name} in the argument project | |
f1a3590e | 14628 | has the value @var{value}. Has no effect if no project is specified as |
c97d7285 AC |
14629 | tool argument. |
14630 | ||
8bdc02c2 BD |
14631 | @item --pp-off=@var{xxx} |
14632 | @cindex @option{--pp-off} @command{gnatpp} | |
14633 | Use @code{--xxx} as the command to turn off pretty printing, instead | |
c733429f | 14634 | of the default @code{--!pp off}. |
8bdc02c2 BD |
14635 | |
14636 | @item --pp-on=@var{xxx} | |
14637 | @cindex @option{--pp-on} @command{gnatpp} | |
14638 | Use @code{--xxx} as the command to turn pretty printing back on, instead | |
c733429f | 14639 | of the default @code{--!pp on}. |
8bdc02c2 | 14640 | |
7b56a91b AC |
14641 | @item --pp-old |
14642 | @cindex @option{--pp-old} @command{gnatpp} | |
2838fa93 | 14643 | Use the old formatting algorithms. |
7b56a91b | 14644 | |
395993ce | 14645 | @item ^-files @var{filename}^/FILES=@var{filename}^ |
0da2c8ac AC |
14646 | @cindex @option{^-files^/FILES^} (@code{gnatpp}) |
14647 | Take the argument source files from the specified file. This file should be an | |
7415029d AC |
14648 | ordinary text file containing file names separated by spaces or |
14649 | line breaks. You can use this switch more than once in the same call to | |
14650 | @command{gnatpp}. You also can combine this switch with an explicit list of | |
0da2c8ac AC |
14651 | files. |
14652 | ||
c3b266d6 AC |
14653 | @item ^-j^/PROCESSES=^@var{n} |
14654 | @cindex @option{^-j^/PROCESSES^} (@command{gnatpp}) | |
14655 | Use @var{n} processes to carry out the tree creations (internal representations | |
14656 | of the argument sources). On a multiprocessor machine this speeds up processing | |
14657 | of big sets of argument sources. If @var{n} is 0, then the maximum number of | |
14658 | parallel tree creations is the number of core processors on the platform. | |
2c9f8c0a AC |
14659 | This option cannot be used together with @option{^-r^/REPLACE^}, |
14660 | @option{^-rf^/OVERRIDING_REPLACE^} or | |
14661 | @option{^-rnb^/REPLACE_NO_BACKUP^} option. | |
c3b266d6 AC |
14662 | |
14663 | @cindex @option{^-t^/TIME^} (@command{gnatpp}) | |
14664 | @item ^-t^/TIME^ | |
14665 | Print out execution time. | |
14666 | ||
7cd4527e | 14667 | @item ^-v^/VERBOSE^ |
f1a3590e AC |
14668 | @cindex @option{^-v^/VERBOSE^} (@command{gnatpp}) |
14669 | Verbose mode | |
14670 | ||
14671 | @item ^-q^/QUIET^ | |
14672 | @cindex @option{^-q^/QUIET^} (@command{gnatpp}) | |
14673 | Quiet mode | |
88e1739c FW |
14674 | @end table |
14675 | ||
c97d7285 AC |
14676 | @noindent |
14677 | If a project file is specified and no argument source is explicitly | |
14678 | specified (either directly or by means of @option{-files} option), and no | |
14679 | @option{-U} is specified, then the set of processed sources is | |
14680 | all the immediate units of the argument project. | |
14681 | ||
14682 | ||
7cd4527e AC |
14683 | @node Formatting Rules |
14684 | @section Formatting Rules | |
88e1739c FW |
14685 | |
14686 | @noindent | |
f1a3590e | 14687 | The following subsections show how @command{gnatpp} treats white space, |
7cd4527e | 14688 | comments, program layout, and name casing. |
f1a3590e | 14689 | They provide detailed descriptions of the switches shown above. |
7cd4527e | 14690 | |
88e1739c | 14691 | @menu |
8bdc02c2 | 14692 | * Disabling Pretty Printing:: |
7cd4527e AC |
14693 | * White Space and Empty Lines:: |
14694 | * Formatting Comments:: | |
7cd4527e | 14695 | * Name Casing:: |
88e1739c FW |
14696 | @end menu |
14697 | ||
8bdc02c2 BD |
14698 | @node Disabling Pretty Printing |
14699 | @subsection Disabling Pretty Printing | |
14700 | ||
14701 | @noindent | |
14702 | Pretty printing is highly heuristic in nature, and sometimes doesn't | |
14703 | do exactly what you want. If you wish to format a certain region of | |
14704 | code by hand, you can turn off pretty printing in that region by | |
c733429f AC |
14705 | surrounding it with special comments that start with @code{--!pp off} |
14706 | and @code{--!pp on}. The text in that region will then be reproduced | |
8bdc02c2 BD |
14707 | verbatim in the output with no formatting. |
14708 | ||
c733429f AC |
14709 | To disable pretty printing for the whole file, put @code{--!pp off} at |
14710 | the top, with no following @code{--!pp on}. | |
8bdc02c2 BD |
14711 | |
14712 | The comments must appear on a line by themselves, with nothing | |
c733429f AC |
14713 | preceding except spaces. The initial text of the comment must be |
14714 | exactly @code{--!pp off} or @code{--!pp on} (case sensitive), but may | |
14715 | be followed by arbitrary additional text. For example: | |
14716 | ||
14717 | @smallexample @c ada | |
14718 | @cartouche | |
14719 | package Interrupts is | |
14720 | --!pp off -- turn off pretty printing so "Interrupt_Kind" lines up | |
f1a3590e | 14721 | type Interrupt_Kind is |
c733429f AC |
14722 | (Asynchronous_Interrupt_Kind, |
14723 | Synchronous_Interrupt_Kind, | |
14724 | Green_Interrupt_Kind); | |
14725 | --!pp on -- reenable pretty printing | |
14726 | ||
14727 | ... | |
14728 | @end cartouche | |
14729 | @end smallexample | |
8bdc02c2 | 14730 | |
f1a3590e AC |
14731 | You can specify different comment strings using the @code{--pp-off} |
14732 | and @code{--pp-on} switches. For example, if you say @code{gnatpp | |
14733 | --pp-off=' pp-' *.ad?} then gnatpp will recognize comments of the form | |
14734 | @code{-- pp-} instead of @code{--!pp off} for disabling pretty | |
14735 | printing. Note that the leading @code{--} of the comment is not | |
14736 | included in the argument to these switches. | |
8bdc02c2 | 14737 | |
7cd4527e AC |
14738 | @node White Space and Empty Lines |
14739 | @subsection White Space and Empty Lines | |
88e1739c FW |
14740 | |
14741 | @noindent | |
7cd4527e AC |
14742 | @command{gnatpp} does not have an option to control space characters. |
14743 | It will add or remove spaces according to the style illustrated by the | |
14744 | examples in the @cite{Ada Reference Manual}. | |
f1a3590e AC |
14745 | The output file will contain no lines with trailing white space. |
14746 | ||
14747 | By default, a sequence of one or more blank lines in the input is | |
14748 | converted to a single blank line in the output; multiple blank lines | |
14749 | are squeezed down to one. | |
14750 | The @option{^--preserve-blank-lines^/PRESERVE_BLANK_LINES^} option | |
14751 | turns off the squeezing; each blank line in the input is copied | |
14752 | to the output. | |
14753 | The @option{^--insert-blank-lines^/INSERT_BLANK_LINES^} option | |
14754 | causes additional blank lines to be inserted if not already | |
14755 | present in the input (e.g. between bodies). | |
7cd4527e | 14756 | |
7cd4527e AC |
14757 | @node Formatting Comments |
14758 | @subsection Formatting Comments | |
14759 | ||
14760 | @noindent | |
14761 | Comments in Ada code are of two kinds: | |
88e1739c FW |
14762 | @itemize @bullet |
14763 | @item | |
7cd4527e | 14764 | a @emph{whole-line comment}, which appears by itself (possibly preceded by |
f1a3590e | 14765 | white space) on a line |
7cd4527e | 14766 | |
88e1739c | 14767 | @item |
f1a3590e AC |
14768 | an @emph{end-of-line comment}, which follows some other Ada code on |
14769 | the same line. | |
88e1739c | 14770 | @end itemize |
88e1739c FW |
14771 | |
14772 | @noindent | |
f1a3590e AC |
14773 | A whole-line comment is indented according to the surrounding code, |
14774 | with some exceptions. | |
14775 | Comments that start in column 1 are kept there. | |
14776 | If possible, comments are not moved so far to the right that the maximum | |
14777 | line length is exceeded. | |
14778 | The @option{^-c0^/COMMENTS_LAYOUT=UNTOUCHED^} option | |
14779 | turns off comment formatting. | |
14780 | Special-form comments such as SPARK-style @code{--#...} are left alone. | |
88e1739c | 14781 | |
f1a3590e AC |
14782 | For an end-of-line comment, @command{gnatpp} tries to leave the same |
14783 | number of spaces between the end of the preceding Ada code and the | |
14784 | beginning of the comment as appear in the original source. | |
88e1739c FW |
14785 | |
14786 | @noindent | |
7cd4527e AC |
14787 | The @option{^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^} switch |
14788 | (GNAT style comment beginning) has the following | |
14789 | effect: | |
88e1739c FW |
14790 | |
14791 | @itemize @bullet | |
14792 | @item | |
7cd4527e AC |
14793 | For each whole-line comment that does not end with two hyphens, |
14794 | @command{gnatpp} inserts spaces if necessary after the starting two hyphens | |
14795 | to ensure that there are at least two spaces between these hyphens and the | |
14796 | first non-blank character of the comment. | |
14797 | @end itemize | |
88e1739c | 14798 | |
7cd4527e | 14799 | @noindent |
f1a3590e AC |
14800 | The @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} switch specifies that |
14801 | whole-line comments that form a paragraph will be filled in typical | |
14802 | word processor style (that is, moving words between lines to make the | |
14803 | lines other than the last similar in length ). | |
c690a2ec | 14804 | |
4058ddcc AC |
14805 | @noindent |
14806 | The @option{--comments-only} switch specifies that only the comments | |
14807 | are formatted; the rest of the program text is left alone. The | |
14808 | comments are formatted according to the -c3 and -c4 switches; other | |
14809 | formatting switches are ignored. For example, @option{--comments-only | |
14810 | -c4} means to fill comment paragraphs, and do nothing else. Likewise, | |
14811 | @option{--comments-only -c3} ensures comments start with at least two | |
14812 | spaces after @code{--}, and @option{--comments-only -c3 -c4} does | |
14813 | both. If @option{--comments-only} is given without @option{-c3} or | |
14814 | @option{-c4}, then gnatpp doesn't format anything. | |
14815 | ||
7cd4527e AC |
14816 | @node Name Casing |
14817 | @subsection Name Casing | |
14818 | ||
14819 | @noindent | |
14820 | @command{gnatpp} always converts the usage occurrence of a (simple) name to | |
14821 | the same casing as the corresponding defining identifier. | |
14822 | ||
14823 | You control the casing for defining occurrences via the | |
14824 | @option{^-n^/NAME_CASING^} switch. | |
14825 | @ifclear vms | |
14826 | With @option{-nD} (``as declared'', which is the default), | |
14827 | @end ifclear | |
14828 | @ifset vms | |
14829 | With @option{/NAME_CASING=AS_DECLARED}, which is the default, | |
14830 | @end ifset | |
14831 | defining occurrences appear exactly as in the source file | |
14832 | where they are declared. | |
14833 | The other ^values for this switch^options for this qualifier^ --- | |
14834 | @option{^-nU^UPPER_CASE^}, | |
14835 | @option{^-nL^LOWER_CASE^}, | |
14836 | @option{^-nM^MIXED_CASE^} --- | |
14837 | result in | |
14838 | ^upper, lower, or mixed case, respectively^the corresponding casing^. | |
14839 | If @command{gnatpp} changes the casing of a defining | |
14840 | occurrence, it analogously changes the casing of all the | |
14841 | usage occurrences of this name. | |
14842 | ||
14843 | If the defining occurrence of a name is not in the source compilation unit | |
14844 | currently being processed by @command{gnatpp}, the casing of each reference to | |
14845 | this name is changed according to the value of the @option{^-n^/NAME_CASING^} | |
14846 | switch (subject to the dictionary file mechanism described below). | |
14847 | Thus @command{gnatpp} acts as though the @option{^-n^/NAME_CASING^} switch | |
14848 | had affected the | |
14849 | casing for the defining occurrence of the name. | |
14850 | ||
f1a3590e AC |
14851 | The options |
14852 | @option{^-a@var{x}^/ATTRIBUTE^}, | |
14853 | @option{^-k@var{x}^/KEYWORD_CASING^}, | |
14854 | @option{^-ne@var{x}^/ENUM_CASING^}, | |
14855 | @option{^-nt@var{x}^/TYPE_CASING^}, | |
14856 | @option{^-nn@var{x}^/NUMBER_CASING^}, and | |
14857 | @option{^-p@var{x}^/PRAGMA_CASING^} | |
14858 | allow finer-grained control over casing for | |
14859 | attributes, keywords, enumeration literals, | |
14860 | types, named numbers and pragmas, respectively. | |
14861 | @option{^-nt@var{x}^/TYPE_CASING^} covers subtypes and | |
14862 | task and protected bodies as well. | |
14863 | ||
7cd4527e AC |
14864 | Some names may need to be spelled with casing conventions that are not |
14865 | covered by the upper-, lower-, and mixed-case transformations. | |
14866 | You can arrange correct casing by placing such names in a | |
14867 | @emph{dictionary file}, | |
14868 | and then supplying a @option{^-D^/DICTIONARY^} switch. | |
14869 | The casing of names from dictionary files overrides | |
14870 | any @option{^-n^/NAME_CASING^} switch. | |
14871 | ||
14872 | To handle the casing of Ada predefined names and the names from GNAT libraries, | |
14873 | @command{gnatpp} assumes a default dictionary file. | |
14874 | The name of each predefined entity is spelled with the same casing as is used | |
f1a3590e | 14875 | for the entity in the @cite{Ada Reference Manual} (usually mixed case). |
7cd4527e AC |
14876 | The name of each entity in the GNAT libraries is spelled with the same casing |
14877 | as is used in the declaration of that entity. | |
14878 | ||
f1a3590e AC |
14879 | The @w{@option{^-D-^/SPECIFIC_CASING^}} switch suppresses the use of |
14880 | the default dictionary file. Instead, the casing for predefined and | |
14881 | GNAT-defined names will be established by the | |
14882 | @option{^-n^/NAME_CASING^} switch or explicit dictionary files. For | |
14883 | example, by default the names @code{Ada.Text_IO} and | |
14884 | @code{GNAT.OS_Lib} will appear as just shown, even in the presence of | |
14885 | a @option{^-nU^/NAME_CASING=UPPER_CASE^} switch. To ensure that even | |
14886 | such names are rendered in uppercase, additionally supply the | |
14887 | @w{@option{^-D-^/SPECIFIC_CASING^}} switch (or else place these names | |
14888 | in upper case in a dictionary file). | |
14889 | ||
14890 | A dictionary file is a plain text file; each line in this file can be | |
14891 | either a blank line (containing only space characters), an Ada comment | |
7cd4527e AC |
14892 | line, or the specification of exactly one @emph{casing schema}. |
14893 | ||
14894 | A casing schema is a string that has the following syntax: | |
14895 | ||
14896 | @smallexample | |
14897 | @cartouche | |
0f1b0456 | 14898 | @var{casing_schema} ::= @var{identifier} | *@var{simple_identifier}* |
7cd4527e AC |
14899 | |
14900 | @var{simple_identifier} ::= @var{letter}@{@var{letter_or_digit}@} | |
14901 | @end cartouche | |
14902 | @end smallexample | |
14903 | ||
14904 | @noindent | |
0f1b0456 GB |
14905 | (See @cite{Ada Reference Manual}, Section 2.3) for the definition of the |
14906 | @var{identifier} lexical element and the @var{letter_or_digit} category.) | |
7cd4527e AC |
14907 | |
14908 | The casing schema string can be followed by white space and/or an Ada-style | |
14909 | comment; any amount of white space is allowed before the string. | |
14910 | ||
14911 | If a dictionary file is passed as | |
14912 | @ifclear vms | |
14913 | the value of a @option{-D@var{file}} switch | |
14914 | @end ifclear | |
14915 | @ifset vms | |
14916 | an option to the @option{/DICTIONARY} qualifier | |
14917 | @end ifset | |
14918 | then for every | |
14919 | simple name and every identifier, @command{gnatpp} checks if the dictionary | |
14920 | defines the casing for the name or for some of its parts (the term ``subword'' | |
14921 | is used below to denote the part of a name which is delimited by ``_'' or by | |
14922 | the beginning or end of the word and which does not contain any ``_'' inside): | |
14923 | ||
14924 | @itemize @bullet | |
14925 | @item | |
14926 | if the whole name is in the dictionary, @command{gnatpp} uses for this name | |
14927 | the casing defined by the dictionary; no subwords are checked for this word | |
14928 | ||
14929 | @item | |
0f1b0456 | 14930 | for every subword @command{gnatpp} checks if the dictionary contains the |
debe0ab6 RD |
14931 | corresponding string of the form @code{*@var{simple_identifier}*}, |
14932 | and if it does, the casing of this @var{simple_identifier} is used | |
14933 | for this subword | |
7cd4527e AC |
14934 | |
14935 | @item | |
0f1b0456 | 14936 | if the whole name does not contain any ``_'' inside, and if for this name |
bde83138 | 14937 | the dictionary contains two entries - one of the form @var{identifier}, |
0f1b0456 GB |
14938 | and another - of the form *@var{simple_identifier}*, then the first one |
14939 | is applied to define the casing of this name | |
7cd4527e AC |
14940 | |
14941 | @item | |
14942 | if more than one dictionary file is passed as @command{gnatpp} switches, each | |
14943 | dictionary adds new casing exceptions and overrides all the existing casing | |
14944 | exceptions set by the previous dictionaries | |
14945 | ||
14946 | @item | |
14947 | when @command{gnatpp} checks if the word or subword is in the dictionary, | |
14948 | this check is not case sensitive | |
14949 | @end itemize | |
14950 | ||
14951 | @noindent | |
14952 | For example, suppose we have the following source to reformat: | |
14953 | ||
14954 | @smallexample @c ada | |
14955 | @cartouche | |
14956 | procedure test is | |
14957 | name1 : integer := 1; | |
14958 | name4_name3_name2 : integer := 2; | |
14959 | name2_name3_name4 : Boolean; | |
14960 | name1_var : Float; | |
14961 | begin | |
14962 | name2_name3_name4 := name4_name3_name2 > name1; | |
14963 | end; | |
14964 | @end cartouche | |
14965 | @end smallexample | |
14966 | ||
14967 | @noindent | |
14968 | And suppose we have two dictionaries: | |
14969 | ||
14970 | @smallexample | |
14971 | @cartouche | |
14972 | @i{dict1:} | |
14973 | NAME1 | |
14974 | *NaMe3* | |
0f1b0456 | 14975 | *Name1* |
7cd4527e AC |
14976 | @end cartouche |
14977 | ||
14978 | @cartouche | |
14979 | @i{dict2:} | |
14980 | *NAME3* | |
14981 | @end cartouche | |
14982 | @end smallexample | |
14983 | ||
14984 | @noindent | |
14985 | If @command{gnatpp} is called with the following switches: | |
14986 | ||
14987 | @smallexample | |
14988 | @ifclear vms | |
14989 | @command{gnatpp -nM -D dict1 -D dict2 test.adb} | |
14990 | @end ifclear | |
14991 | @ifset vms | |
14992 | @command{gnatpp test.adb /NAME_CASING=MIXED_CASE /DICTIONARY=(dict1, dict2)} | |
14993 | @end ifset | |
14994 | @end smallexample | |
14995 | ||
14996 | @noindent | |
14997 | then we will get the following name casing in the @command{gnatpp} output: | |
14998 | ||
14999 | @smallexample @c ada | |
15000 | @cartouche | |
15001 | procedure Test is | |
15002 | NAME1 : Integer := 1; | |
0f1b0456 | 15003 | Name4_NAME3_Name2 : Integer := 2; |
7cd4527e AC |
15004 | Name2_NAME3_Name4 : Boolean; |
15005 | Name1_Var : Float; | |
15006 | begin | |
0f1b0456 | 15007 | Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1; |
7cd4527e AC |
15008 | end Test; |
15009 | @end cartouche | |
15010 | @end smallexample | |
1037b0f4 | 15011 | @end ifclear |
7cd4527e | 15012 | |
1037b0f4 | 15013 | @ifclear FSFEDITION |
c1645ac8 AC |
15014 | @ifclear vms |
15015 | @c ********************************* | |
15016 | @node The Ada-to-XML converter gnat2xml | |
15017 | @chapter The Ada-to-XML converter @command{gnat2xml} | |
15018 | @findex gnat2xml | |
15019 | @cindex XML generation | |
15020 | ||
15021 | @noindent | |
15022 | The @command{gnat2xml} tool is an ASIS-based utility that converts | |
15023 | Ada source code into XML. | |
15024 | ||
15025 | @menu | |
15026 | * Switches for gnat2xml:: | |
15027 | * Driving gnat2xml with gnatmake or gprbuild:: | |
15028 | * Other Programs:: | |
15029 | * Structure of the XML:: | |
15030 | @end menu | |
15031 | ||
15032 | @node Switches for gnat2xml | |
15033 | @section Switches for @command{gnat2xml} | |
15034 | ||
15035 | @noindent | |
15036 | @command{gnat2xml} takes Ada source code as input, and produces XML | |
15037 | that conforms to the schema. | |
15038 | ||
15039 | Usage: | |
15040 | ||
15041 | @smallexample | |
15042 | gnat2xml [options] files | |
15043 | @end smallexample | |
15044 | ||
15045 | ``files'' are the Ada source file names. | |
15046 | ||
15047 | @noindent | |
15048 | Options: | |
15049 | @smallexample | |
15050 | -h | |
15051 | --help -- generate usage information and quit, ignoring all other options | |
15052 | ||
c97d7285 AC |
15053 | -P @file{file} -- indicates the name of the project file that describes |
15054 | the set of sources to be processed. The exact set of argument | |
15055 | sources depends on other options specified, see below. | |
15056 | ||
15057 | -U -- if a project file is specified and no argument source is explicitly | |
15058 | specified, process all the units of the closure of the argument project. | |
15059 | Otherwise this option has no effect. | |
15060 | ||
15061 | -U @var{main_unit} -- if a project file is specified and no argument source | |
15062 | is explicitly specified (either directly or by means of @option{-files} | |
15063 | option), process the closure of units rooted at @var{main_unit}. | |
15064 | Otherwise this option has no effect. | |
15065 | ||
15066 | -X@var{name}=@var{value} -- indicates that external variable @var{name} in | |
f1a3590e | 15067 | the argument project has the value @var{value}. Has no effect if no |
c97d7285 AC |
15068 | project is specified as tool argument. |
15069 | ||
c1645ac8 AC |
15070 | -mdir -- generate one .xml file for each Ada source file, in directory |
15071 | @file{dir}. (Default is to generate the XML to standard output.) | |
15072 | ||
f3920a13 | 15073 | --compact -- debugging version, with interspersed source, and a more |
c1645ac8 AC |
15074 | compact representation of "sloc". This version does not conform |
15075 | to any schema. | |
15076 | ||
15077 | -I <include-dir> | |
15078 | directories to search for dependencies | |
15079 | You can also set the ADA_INCLUDE_PATH environment variable for this. | |
15080 | ||
f3920a13 AC |
15081 | -q -- quiet |
15082 | ||
c1645ac8 AC |
15083 | -v -- verbose (print out the command line options, and the names of |
15084 | output files as they are generated). | |
15085 | ||
15086 | -t -- do not delete tree files when done (they are deleted by default). | |
15087 | ||
15088 | -cargs ... -- options to pass to gcc | |
15089 | @end smallexample | |
15090 | ||
15091 | @noindent | |
c97d7285 AC |
15092 | If a project file is specified and no argument source is explicitly |
15093 | specified, and no @option{-U} is specified, then the set of processed | |
15094 | sources is all the immediate units of the argument project. | |
15095 | ||
15096 | ||
c1645ac8 AC |
15097 | You can generate the ``tree files'' ahead of time using the -gnatct switch: |
15098 | ||
15099 | @smallexample | |
15100 | gnatmake -gnat2012 -gnatct *.ad[sb] | |
15101 | @end smallexample | |
15102 | ||
15103 | @noindent | |
15104 | If tree files do not exist, @command{gnat2xml} will create them by running gcc. | |
15105 | See the ASIS documentation for more information on tree files. | |
15106 | ||
15107 | Example: | |
15108 | ||
15109 | @smallexample | |
15110 | mkdir xml-files | |
15111 | gnat2xml -v -mxml-files *.ad[sb] -cargs -gnat2012 | |
15112 | @end smallexample | |
15113 | ||
15114 | @noindent | |
15115 | The above will create *.xml files in the @file{xml-files} subdirectory. | |
15116 | For example, if there is an Ada package Mumble.Dumble, whose spec and | |
15117 | body source code lives in mumble-dumble.ads and mumble-dumble.adb, | |
15118 | the above will produce xml-files/mumble-dumble.ads.xml and | |
15119 | xml-files/mumble-dumble.adb.xml. | |
15120 | ||
15121 | @node Driving gnat2xml with gnatmake or gprbuild | |
15122 | @section Driving @command{gnat2xml} with @command{gnatmake} or @command{gprbuild} | |
15123 | ||
15124 | @noindent | |
15125 | You can use gnatmake or gprbuild to drive @command{gnat2xml} to get | |
15126 | incremental updates of the XML files on a per-source-file basis. For | |
15127 | example, if you already have a bunch of XML files, and then you change | |
15128 | one source file, it will regenerate XML files only for that source | |
15129 | file, and other source files that depend on it. Gnatmake and gprbuild | |
15130 | take care of tracking inter-file dependencies. For example, if | |
15131 | this.adb says @code{with That;}, then this.adb depends on that.ads. | |
15132 | ||
15133 | To do this, you tell gnatmake/gprbuild to pretend that | |
15134 | @command{gnat2xml} is the Ada compiler (instead of using gcc as the | |
15135 | Ada compiler, as is normal). | |
15136 | ||
15137 | To tell gnatmake to use @command{gnat2xml} instead of gcc as the | |
15138 | ``compiler'', for example: | |
15139 | ||
15140 | @smallexample | |
15141 | gnatmake -gnatc *.adb --GCC="gnat2xml -t -mxml" | |
15142 | @end smallexample | |
15143 | ||
15144 | @noindent | |
15145 | The @option{--GCC=} switch tells gnatmake that the ``compiler'' to run | |
15146 | is @command{gnat2xml -t -mxml}. The @option{-t} switch means to keep the tree | |
15147 | files, so they can be reused on the next run. (@command{gnat2xml} | |
15148 | deletes them by default.) As usual, @option{-mxml} means to put the | |
15149 | XML files in the @file{xml} subdirectory. | |
15150 | ||
15151 | You must give the @option{-gnatc} switch to gnatmake, which means | |
15152 | ``compile only; do not generate object code''. Otherwise, gnatmake will | |
15153 | complain about missing object (*.o) files; @command{gnat2xml} of | |
15154 | course does not generate *.o files. | |
15155 | ||
15156 | Using gprbuild is similar: you tell it to use @command{gnat2xml} | |
15157 | instead of gcc. First write a project file, such as my_project.gpr: | |
15158 | ||
15159 | @smallexample @c projectfile | |
15160 | project My_Project is | |
15161 | ||
15162 | package Compiler is | |
15163 | for Driver ("ada") use "gnat2xml"; | |
15164 | -- Use gnat2xml instead of the usual gcc. | |
15165 | ||
15166 | for Default_Switches ("ada") use ("-t", "-mxml"); | |
15167 | -- Same switches as in the gnatmake case. | |
15168 | end Compiler; | |
15169 | ||
15170 | end My_Project; | |
15171 | @end smallexample | |
15172 | ||
15173 | @noindent | |
15174 | Then: | |
15175 | ||
15176 | @smallexample @c projectfile | |
15177 | gprbuild --no-object-check -P my_project.gpr | |
15178 | @end smallexample | |
15179 | ||
15180 | @noindent | |
15181 | The @option{--no-object-check} switch serves the same purpose as | |
15182 | @option{-gnatc} in the gnatmake case --- it tells gprbuild not to | |
15183 | expect that the ``compiler'' (really @command{gnat2xml}) will produce | |
15184 | *.o files. | |
15185 | ||
15186 | See the gprbuild documentation for information on many other things | |
15187 | you can put in the project file, such as telling it where to find | |
15188 | the source files. | |
15189 | ||
15190 | @node Other Programs | |
15191 | @section Other Programs | |
15192 | ||
15193 | @noindent | |
15194 | The distribution includes two other programs that are related to | |
15195 | @command{gnat2xml}: | |
15196 | ||
15197 | @command{gnat2xsd} is the schema generator, which generates the schema | |
15198 | to standard output, based on the structure of Ada as encoded by | |
15199 | ASIS. You don't need to run @command{gnat2xsd} in order to use | |
15200 | @command{gnat2xml}. To generate the schema, type: | |
15201 | ||
15202 | @smallexample | |
15203 | gnat2xsd > ada-schema.xsd | |
15204 | @end smallexample | |
15205 | ||
15206 | @noindent | |
15207 | @command{gnat2xml} generates XML files that will validate against | |
15208 | @file{ada-schema.xsd}. | |
15209 | ||
15210 | @command{xml2gnat} is a back-translator that translates the XML back | |
15211 | into Ada source code. The Ada generated by @command{xml2gnat} has | |
15212 | identical semantics to the original Ada code passed to | |
15213 | @command{gnat2xml}. It is not textually identical, however --- for | |
15214 | example, no attempt is made to preserve the original indentation. | |
15215 | ||
15216 | @node Structure of the XML | |
15217 | @section Structure of the XML | |
15218 | ||
15219 | @noindent | |
15220 | The primary documentation for the structure of the XML generated by | |
15221 | @command{gnat2xml} is the schema (see @command{gnat2xsd} above). The | |
15222 | following documentation gives additional details needed to understand | |
15223 | the schema and therefore the XML. | |
15224 | ||
15225 | The elements listed under Defining Occurrences, Usage Occurrences, and | |
15226 | Other Elements represent the syntactic structure of the Ada program. | |
15227 | Element names are given in lower case, with the corresponding element | |
15228 | type Capitalized_Like_This. The element and element type names are | |
15229 | derived directly from the ASIS enumeration type Flat_Element_Kinds, | |
15230 | declared in Asis.Extensions.Flat_Kinds, with the leading ``An_'' or ``A_'' | |
15231 | removed. For example, the ASIS enumeration literal | |
15232 | An_Assignment_Statement corresponds to the XML element | |
15233 | assignment_statement of XML type Assignment_Statement. | |
15234 | ||
15235 | To understand the details of the schema and the corresponding XML, it is | |
15236 | necessary to understand the ASIS standard, as well as the GNAT-specific | |
15237 | extension to ASIS. | |
15238 | ||
15239 | A defining occurrence is an identifier (or character literal or operator | |
15240 | symbol) declared by a declaration. A usage occurrence is an identifier | |
15241 | (or ...) that references such a declared entity. For example, in: | |
15242 | ||
15243 | @smallexample | |
15244 | type T is range 1..10; | |
15245 | X, Y : constant T := 1; | |
15246 | @end smallexample | |
15247 | ||
15248 | @noindent | |
15249 | The first ``T'' is the defining occurrence of a type. The ``X'' is the | |
15250 | defining occurrence of a constant, as is the ``Y'', and the second ``T'' is | |
15251 | a usage occurrence referring to the defining occurrence of T. | |
15252 | ||
15253 | Each element has a 'sloc' (source location), and subelements for each | |
15254 | syntactic subtree, reflecting the Ada grammar as implemented by ASIS. | |
15255 | The types of subelements are as defined in the ASIS standard. For | |
15256 | example, for the right-hand side of an assignment_statement we have | |
15257 | the following comment in asis-statements.ads: | |
15258 | ||
15259 | @smallexample | |
15260 | ------------------------------------------------------------------------------ | |
15261 | -- 18.3 function Assignment_Expression | |
15262 | ------------------------------------------------------------------------------ | |
15263 | ||
15264 | function Assignment_Expression | |
15265 | (Statement : Asis.Statement) | |
15266 | return Asis.Expression; | |
15267 | ||
15268 | ------------------------------------------------------------------------------ | |
15269 | ... | |
15270 | -- Returns the expression from the right hand side of the assignment. | |
15271 | ... | |
15272 | -- Returns Element_Kinds: | |
15273 | -- An_Expression | |
15274 | @end smallexample | |
15275 | ||
15276 | @noindent | |
15277 | The corresponding sub-element of type Assignment_Statement is: | |
15278 | ||
15279 | @smallexample | |
15280 | <xsd:element name="assignment_expression_q" type="Expression_Class"/> | |
15281 | @end smallexample | |
15282 | ||
15283 | @noindent | |
15284 | where Expression_Class is defined by an xsd:choice of all the | |
15285 | various kinds of expression. | |
15286 | ||
15287 | The 'sloc' of each element indicates the starting and ending line and | |
15288 | column numbers. Column numbers are character counts; that is, a tab | |
15289 | counts as 1, not as however many spaces it might expand to. | |
15290 | ||
15291 | Subelements of type Element have names ending in ``_q'' (for ASIS | |
15292 | ``Query''), and those of type Element_List end in ``_ql'' (``Query returning | |
15293 | List''). | |
15294 | ||
15295 | Some subelements are ``Boolean''. For example, Private_Type_Definition | |
15296 | has has_abstract_q and has_limited_q, to indicate whether those | |
15297 | keywords are present, as in @code{type T is abstract limited | |
15298 | private;}. False is represented by a Nil_Element. True is represented | |
15299 | by an element type specific to that query (for example, Abstract and | |
15300 | Limited). | |
15301 | ||
15302 | The root of the tree is a Compilation_Unit, with attributes: | |
15303 | ||
15304 | @itemize @bullet | |
15305 | @item | |
15306 | unit_kind, unit_class, and unit_origin. These are strings that match the | |
15307 | enumeration literals of types Unit_Kinds, Unit_Classes, and Unit_Origins | |
15308 | in package Asis. | |
15309 | ||
15310 | @item | |
15311 | unit_full_name is the full expanded name of the unit, starting from a | |
15312 | root library unit. So for @code{package P.Q.R is ...}, | |
15313 | @code{unit_full_name="P.Q.R"}. Same for @code{separate (P.Q) package R is ...}. | |
15314 | ||
15315 | @item | |
15316 | def_name is the same as unit_full_name for library units; for subunits, | |
15317 | it is just the simple name. | |
15318 | ||
15319 | @item | |
15320 | source_file is the name of the Ada source file. For example, for | |
15321 | the spec of @code{P.Q.R}, @code{source_file="p-q-r.ads"}. This allows one to | |
15322 | interpret the source locations --- the ``sloc'' of all elements | |
15323 | within this Compilation_Unit refers to line and column numbers | |
15324 | within the named file. | |
15325 | @end itemize | |
15326 | ||
15327 | @noindent | |
15328 | Defining occurrences have these attributes: | |
15329 | ||
15330 | @itemize @bullet | |
15331 | @item | |
15332 | def_name is the simple name of the declared entity, as written in the Ada | |
15333 | source code. | |
15334 | ||
15335 | @item | |
15336 | def is a unique URI of the form: | |
15337 | ||
15338 | ada://kind/fully/qualified/name | |
15339 | ||
15340 | where: | |
15341 | ||
15342 | kind indicates the kind of Ada entity being declared (see below), and | |
15343 | ||
15344 | fully/qualified/name, is the fully qualified name of the Ada | |
15345 | entity, with each of ``fully'', ``qualified'', and ``name'' being | |
15346 | mangled for uniqueness. We do not document the mangling | |
15347 | algorithm, which is subject to change; we just guarantee that the | |
15348 | names are unique in the face of overloading. | |
15349 | ||
15350 | @item | |
15351 | type is the type of the declared object, or @code{null} for | |
15352 | declarations of things other than objects. | |
15353 | @end itemize | |
15354 | ||
15355 | @noindent | |
15356 | Usage occurrences have these attributes: | |
15357 | ||
15358 | @itemize @bullet | |
15359 | @item | |
15360 | ref_name is the same as the def_name of the corresponding defining | |
15361 | occurrence. This attribute is not of much use, because of | |
15362 | overloading; use ref for lookups, instead. | |
15363 | ||
15364 | @item | |
15365 | ref is the same as the def of the corresponding defining | |
15366 | occurrence. | |
15367 | @end itemize | |
15368 | ||
15369 | @noindent | |
15370 | In summary, @code{def_name} and @code{ref_name} are as in the source | |
15371 | code of the declaration, possibly overloaded, whereas @code{def} and | |
15372 | @code{ref} are unique-ified. | |
15373 | ||
15374 | Literal elements have this attribute: | |
15375 | ||
15376 | @itemize @bullet | |
15377 | @item | |
15378 | lit_val is the value of the literal as written in the source text, | |
15379 | appropriately escaped (e.g. @code{"} ---> @code{"}). This applies | |
15380 | only to numeric and string literals. Enumeration literals in Ada are | |
15381 | not really "literals" in the usual sense; they are usage occurrences, | |
15382 | and have ref_name and ref as described above. Note also that string | |
15383 | literals used as operator symbols are treated as defining or usage | |
15384 | occurrences, not as literals. | |
15385 | @end itemize | |
15386 | ||
15387 | @noindent | |
15388 | Elements that can syntactically represent names and expressions (which | |
15389 | includes usage occurrences, plus function calls and so forth) have this | |
15390 | attribute: | |
15391 | ||
15392 | @itemize @bullet | |
15393 | @item | |
15394 | type. If the element represents an expression or the name of an object, | |
15395 | 'type' is the 'def' for the defining occurrence of the type of that | |
15396 | expression or name. Names of other kinds of entities, such as package | |
15397 | names and type names, do not have a type in Ada; these have type="null" | |
15398 | in the XML. | |
15399 | @end itemize | |
15400 | ||
15401 | @noindent | |
15402 | Pragma elements have this attribute: | |
15403 | ||
15404 | @itemize @bullet | |
15405 | @item | |
15406 | pragma_name is the name of the pragma. For language-defined pragmas, the | |
15407 | pragma name is redundant with the element kind (for example, an | |
15408 | assert_pragma element necessarily has pragma_name="Assert"). However, all | |
15409 | implementation-defined pragmas are lumped together in ASIS as a single | |
15410 | element kind (for example, the GNAT-specific pragma Unreferenced is | |
15411 | represented by an implementation_defined_pragma element with | |
15412 | pragma_name="Unreferenced"). | |
15413 | @end itemize | |
15414 | ||
15415 | @noindent | |
15416 | Defining occurrences of formal parameters and generic formal objects have this | |
15417 | attribute: | |
15418 | ||
15419 | @itemize @bullet | |
15420 | @item | |
15421 | mode indicates that the parameter is of mode 'in', 'in out', or 'out'. | |
15422 | @end itemize | |
15423 | ||
579847c2 AC |
15424 | @noindent |
15425 | All elements other than Not_An_Element have this attribute: | |
15426 | ||
15427 | @itemize @bullet | |
15428 | @item | |
15429 | checks is a comma-separated list of run-time checks that are needed | |
15430 | for that element. The possible checks are: do_accessibility_check, | |
15431 | do_discriminant_check,do_division_check,do_length_check, | |
15432 | do_overflow_check,do_range_check,do_storage_check,do_tag_check. | |
15433 | @end itemize | |
15434 | ||
c1645ac8 AC |
15435 | @noindent |
15436 | The "kind" part of the "def" and "ref" attributes is taken from the ASIS | |
15437 | enumeration type Flat_Declaration_Kinds, declared in | |
15438 | Asis.Extensions.Flat_Kinds, with the leading "An_" or "A_" removed, and | |
15439 | any trailing "_Declaration" or "_Specification" removed. Thus, the | |
15440 | possible kinds are as follows: | |
15441 | ||
15442 | @smallexample | |
15443 | ordinary_type | |
15444 | task_type | |
15445 | protected_type | |
15446 | incomplete_type | |
15447 | tagged_incomplete_type | |
15448 | private_type | |
15449 | private_extension | |
15450 | subtype | |
15451 | variable | |
15452 | constant | |
15453 | deferred_constant | |
15454 | single_task | |
15455 | single_protected | |
15456 | integer_number | |
15457 | real_number | |
15458 | enumeration_literal | |
15459 | discriminant | |
15460 | component | |
15461 | loop_parameter | |
15462 | generalized_iterator | |
15463 | element_iterator | |
15464 | procedure | |
15465 | function | |
15466 | parameter | |
15467 | procedure_body | |
15468 | function_body | |
15469 | return_variable | |
15470 | return_constant | |
15471 | null_procedure | |
15472 | expression_function | |
15473 | package | |
15474 | package_body | |
15475 | object_renaming | |
15476 | exception_renaming | |
15477 | package_renaming | |
15478 | procedure_renaming | |
15479 | function_renaming | |
15480 | generic_package_renaming | |
15481 | generic_procedure_renaming | |
15482 | generic_function_renaming | |
15483 | task_body | |
15484 | protected_body | |
15485 | entry | |
15486 | entry_body | |
15487 | entry_index | |
15488 | procedure_body_stub | |
15489 | function_body_stub | |
15490 | package_body_stub | |
15491 | task_body_stub | |
15492 | protected_body_stub | |
15493 | exception | |
15494 | choice_parameter | |
15495 | generic_procedure | |
15496 | generic_function | |
15497 | generic_package | |
15498 | package_instantiation | |
15499 | procedure_instantiation | |
15500 | function_instantiation | |
15501 | formal_object | |
15502 | formal_type | |
15503 | formal_incomplete_type | |
15504 | formal_procedure | |
15505 | formal_function | |
15506 | formal_package | |
15507 | formal_package_declaration_with_box | |
15508 | @end smallexample | |
15509 | @end ifclear | |
1037b0f4 AC |
15510 | @end ifclear |
15511 | ||
c1645ac8 | 15512 | |
1037b0f4 | 15513 | @ifclear FSFEDITION |
a5b62485 | 15514 | @c ********************************* |
c2658843 AC |
15515 | @node The GNAT Metrics Tool gnatmetric |
15516 | @chapter The GNAT Metrics Tool @command{gnatmetric} | |
a5b62485 AC |
15517 | @findex gnatmetric |
15518 | @cindex Metric tool | |
15519 | ||
15520 | @noindent | |
984a64bc | 15521 | ^The @command{gnatmetric} tool^@command{GNAT METRIC}^ is an ASIS-based utility |
a5b62485 AC |
15522 | for computing various program metrics. |
15523 | It takes an Ada source file as input and generates a file containing the | |
15524 | metrics data as output. Various switches control which | |
15525 | metrics are computed and output. | |
15526 | ||
c2658843 AC |
15527 | @menu |
15528 | * Switches for gnatmetric:: | |
15529 | @end menu | |
15530 | ||
a5b62485 AC |
15531 | @command{gnatmetric} generates and uses the ASIS |
15532 | tree for the input source and thus requires the input to be syntactically and | |
15533 | semantically legal. | |
15534 | If this condition is not met, @command{gnatmetric} will generate | |
15535 | an error message; no metric information for this file will be | |
15536 | computed and reported. | |
15537 | ||
15538 | If the compilation unit contained in the input source depends semantically | |
984a64bc AC |
15539 | upon units in files located outside the current directory, you have to provide |
15540 | the source search path when invoking @command{gnatmetric}. | |
15541 | If it depends semantically upon units that are contained | |
15542 | in files with names that do not follow the GNAT file naming rules, you have to | |
0453ca3d RD |
15543 | provide the configuration file describing the corresponding naming scheme (see |
15544 | the description of the @command{gnatmetric} switches below.) | |
984a64bc | 15545 | Alternatively, you may use a project file and invoke @command{gnatmetric} |
46de64ca AC |
15546 | through the @command{gnat} driver (see @ref{The GNAT Driver and Project Files}), |
15547 | or you can directly specify a project file as a @command{gnatmetric} parameter. | |
984a64bc | 15548 | |
a5b62485 AC |
15549 | The @command{gnatmetric} command has the form |
15550 | ||
15551 | @smallexample | |
e074d476 AC |
15552 | @c $ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} |
15553 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
15554 | $ gnatmetric @r{[}@var{switches}@r{]} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} | |
a5b62485 AC |
15555 | @end smallexample |
15556 | ||
15557 | @noindent | |
15558 | where | |
15559 | @itemize @bullet | |
15560 | @item | |
66bfd481 | 15561 | @var{switches} specify the metrics to compute and define the destination for |
87b3f81f | 15562 | the output |
a5b62485 AC |
15563 | |
15564 | @item | |
66bfd481 | 15565 | Each @var{filename} is the name (including the extension) of a source |
984a64bc AC |
15566 | file to process. ``Wildcards'' are allowed, and |
15567 | the file name may contain path information. | |
66bfd481 | 15568 | If no @var{filename} is supplied, then the @var{switches} list must contain |
984a64bc AC |
15569 | at least one |
15570 | @option{-files} switch (@pxref{Other gnatmetric Switches}). | |
15571 | Including both a @option{-files} switch and one or more | |
66bfd481 | 15572 | @var{filename} arguments is permitted. |
a5b62485 AC |
15573 | |
15574 | @item | |
5875f8d6 | 15575 | @samp{@var{gcc_switches}} is a list of switches for |
a5b62485 AC |
15576 | @command{gcc}. They will be passed on to all compiler invocations made by |
15577 | @command{gnatmetric} to generate the ASIS trees. Here you can provide | |
984a64bc | 15578 | @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, |
4b6133ea AC |
15579 | and use the @option{-gnatec} switch to set the configuration file, |
15580 | use the @option{-gnat05} switch if sources should be compiled in | |
15581 | Ada 2005 mode etc. | |
a5b62485 AC |
15582 | @end itemize |
15583 | ||
a5b62485 AC |
15584 | @node Switches for gnatmetric |
15585 | @section Switches for @command{gnatmetric} | |
15586 | ||
15587 | @noindent | |
15588 | The following subsections describe the various switches accepted by | |
15589 | @command{gnatmetric}, organized by category. | |
15590 | ||
15591 | @menu | |
15592 | * Output Files Control:: | |
15593 | * Disable Metrics For Local Units:: | |
7954ad60 | 15594 | * Specifying a set of metrics to compute:: |
a5b62485 | 15595 | * Other gnatmetric Switches:: |
46de64ca | 15596 | @ignore |
e08b38f5 | 15597 | * Generate project-wide metrics:: |
46de64ca | 15598 | @end ignore |
a5b62485 AC |
15599 | @end menu |
15600 | ||
15601 | @node Output Files Control | |
15602 | @subsection Output File Control | |
15603 | @cindex Output file control in @command{gnatmetric} | |
15604 | ||
15605 | @noindent | |
87b3f81f AC |
15606 | @command{gnatmetric} has two output formats. It can generate a |
15607 | textual (human-readable) form, and also XML. By default only textual | |
a5b62485 AC |
15608 | output is generated. |
15609 | ||
15610 | When generating the output in textual form, @command{gnatmetric} creates | |
15611 | for each Ada source file a corresponding text file | |
7954ad60 SR |
15612 | containing the computed metrics, except for the case when the set of metrics |
15613 | specified by gnatmetric parameters consists only of metrics that are computed | |
15614 | for the whole set of analyzed sources, but not for each Ada source. | |
46de64ca AC |
15615 | By default, the name of the file containing metric information for a source |
15616 | is obtained by appending the ^@file{.metrix}^@file{$METRIX}^ suffix to the | |
15617 | name of the input source file. If not otherwise specified and no project file | |
15618 | is specified as @command{gnatmetric} option this file is placed in the same | |
15619 | directory as where the source file is located. If @command{gnatmetric} has a | |
15620 | project file as its parameter, it places all the generated files in the | |
15621 | object directory of the project (or in the project source directory if the | |
15622 | project does not define an objects directory), if @option{--subdirs} option | |
15623 | is specified, the files are placed in the subrirectory of this directory | |
15624 | specified by this option. | |
a5b62485 AC |
15625 | |
15626 | All the output information generated in XML format is placed in a single | |
46de64ca AC |
15627 | file. By default the name of this file is ^@file{metrix.xml}^@file{METRIX$XML}^. |
15628 | If not otherwise specified and if no project file is specified | |
15629 | as @command{gnatmetric} option this file is placed in the | |
15630 | current directory. | |
a5b62485 AC |
15631 | |
15632 | Some of the computed metrics are summed over the units passed to | |
15633 | @command{gnatmetric}; for example, the total number of lines of code. | |
15634 | By default this information is sent to @file{stdout}, but a file | |
15635 | can be specified with the @option{-og} switch. | |
15636 | ||
87b3f81f | 15637 | The following switches control the @command{gnatmetric} output: |
a5b62485 AC |
15638 | |
15639 | @table @option | |
15640 | @cindex @option{^-x^/XML^} (@command{gnatmetric}) | |
15641 | @item ^-x^/XML^ | |
15642 | Generate the XML output | |
15643 | ||
c38e990f SR |
15644 | @cindex @option{^-xs^/XSD^} (@command{gnatmetric}) |
15645 | @item ^-xs^/XSD^ | |
15646 | Generate the XML output and the XML schema file that describes the structure | |
15647 | of the XML metric report, this schema is assigned to the XML file. The schema | |
15648 | file has the same name as the XML output file with @file{.xml} suffix replaced | |
15649 | with @file{.xsd} | |
15650 | ||
a5b62485 AC |
15651 | @cindex @option{^-nt^/NO_TEXT^} (@command{gnatmetric}) |
15652 | @item ^-nt^/NO_TEXT^ | |
15653 | Do not generate the output in text form (implies @option{^-x^/XML^}) | |
15654 | ||
15655 | @cindex @option{^-d^/DIRECTORY^} (@command{gnatmetric}) | |
15656 | @item ^-d @var{output_dir}^/DIRECTORY=@var{output_dir}^ | |
7415029d | 15657 | Put text files with detailed metrics into @var{output_dir} |
a5b62485 AC |
15658 | |
15659 | @cindex @option{^-o^/SUFFIX_DETAILS^} (@command{gnatmetric}) | |
15660 | @item ^-o @var{file_suffix}^/SUFFIX_DETAILS=@var{file_suffix}^ | |
87b3f81f AC |
15661 | Use @var{file_suffix}, instead of ^@file{.metrix}^@file{$METRIX}^ |
15662 | in the name of the output file. | |
a5b62485 AC |
15663 | |
15664 | @cindex @option{^-og^/GLOBAL_OUTPUT^} (@command{gnatmetric}) | |
15665 | @item ^-og @var{file_name}^/GLOBAL_OUTPUT=@var{file_name}^ | |
87b3f81f | 15666 | Put global metrics into @var{file_name} |
a5b62485 AC |
15667 | |
15668 | @cindex @option{^-ox^/XML_OUTPUT^} (@command{gnatmetric}) | |
15669 | @item ^-ox @var{file_name}^/XML_OUTPUT=@var{file_name}^ | |
15670 | Put the XML output into @var{file_name} (also implies @option{^-x^/XML^}) | |
15671 | ||
15672 | @cindex @option{^-sfn^/SHORT_SOURCE_FILE_NAME^} (@command{gnatmetric}) | |
15673 | @item ^-sfn^/SHORT_SOURCE_FILE_NAME^ | |
984a64bc AC |
15674 | Use ``short'' source file names in the output. (The @command{gnatmetric} |
15675 | output includes the name(s) of the Ada source file(s) from which the metrics | |
15676 | are computed. By default each name includes the absolute path. The | |
15677 | @option{^-sfn^/SHORT_SOURCE_FILE_NAME^} switch causes @command{gnatmetric} | |
15678 | to exclude all directory information from the file names that are output.) | |
a5b62485 AC |
15679 | |
15680 | @end table | |
15681 | ||
15682 | @node Disable Metrics For Local Units | |
15683 | @subsection Disable Metrics For Local Units | |
15684 | @cindex Disable Metrics For Local Units in @command{gnatmetric} | |
15685 | ||
15686 | @noindent | |
15687 | @command{gnatmetric} relies on the GNAT compilation model @minus{} | |
15688 | one compilation | |
984a64bc AC |
15689 | unit per one source file. It computes line metrics for the whole source |
15690 | file, and it also computes syntax | |
15691 | and complexity metrics for the file's outermost unit. | |
a5b62485 | 15692 | |
984a64bc AC |
15693 | By default, @command{gnatmetric} will also compute all metrics for certain |
15694 | kinds of locally declared program units: | |
a5b62485 AC |
15695 | |
15696 | @itemize @bullet | |
15697 | @item | |
984a64bc | 15698 | subprogram (and generic subprogram) bodies; |
a5b62485 AC |
15699 | |
15700 | @item | |
1a5f40e1 | 15701 | package (and generic package) specs and bodies; |
a5b62485 AC |
15702 | |
15703 | @item | |
984a64bc | 15704 | task object and type specifications and bodies; |
a5b62485 | 15705 | |
984a64bc AC |
15706 | @item |
15707 | protected object and type specifications and bodies. | |
a5b62485 AC |
15708 | @end itemize |
15709 | ||
15710 | @noindent | |
984a64bc AC |
15711 | These kinds of entities will be referred to as |
15712 | @emph{eligible local program units}, or simply @emph{eligible local units}, | |
15713 | @cindex Eligible local unit (for @command{gnatmetric}) | |
15714 | in the discussion below. | |
15715 | ||
15716 | Note that a subprogram declaration, generic instantiation, | |
15717 | or renaming declaration only receives metrics | |
15718 | computation when it appear as the outermost entity | |
15719 | in a source file. | |
15720 | ||
15721 | Suppression of metrics computation for eligible local units can be | |
15722 | obtained via the following switch: | |
a5b62485 AC |
15723 | |
15724 | @table @option | |
1037b0f4 | 15725 | @cindex @option{^-nolocal^/SUPPRESS^} (@command{gnatmetric}) |
a5b62485 | 15726 | @item ^-nolocal^/SUPPRESS=LOCAL_DETAILS^ |
984a64bc | 15727 | Do not compute detailed metrics for eligible local program units |
a5b62485 AC |
15728 | |
15729 | @end table | |
15730 | ||
7954ad60 SR |
15731 | @node Specifying a set of metrics to compute |
15732 | @subsection Specifying a set of metrics to compute | |
15733 | ||
15734 | @noindent | |
15735 | By default all the metrics are computed and reported. The switches | |
15736 | described in this subsection allow you to control, on an individual | |
15737 | basis, whether metrics are computed and | |
15738 | reported. If at least one positive metric | |
15739 | switch is specified (that is, a switch that defines that a given | |
15740 | metric or set of metrics is to be computed), then only | |
15741 | explicitly specified metrics are reported. | |
15742 | ||
15743 | @menu | |
15744 | * Line Metrics Control:: | |
15745 | * Syntax Metrics Control:: | |
15746 | * Complexity Metrics Control:: | |
0da80d7d | 15747 | * Coupling Metrics Control:: |
7954ad60 SR |
15748 | @end menu |
15749 | ||
a5b62485 | 15750 | @node Line Metrics Control |
7954ad60 | 15751 | @subsubsection Line Metrics Control |
a5b62485 AC |
15752 | @cindex Line metrics control in @command{gnatmetric} |
15753 | ||
15754 | @noindent | |
984a64bc AC |
15755 | For any (legal) source file, and for each of its |
15756 | eligible local program units, @command{gnatmetric} computes the following | |
15757 | metrics: | |
a5b62485 AC |
15758 | |
15759 | @itemize @bullet | |
15760 | @item | |
984a64bc | 15761 | the total number of lines; |
a5b62485 AC |
15762 | |
15763 | @item | |
15764 | the total number of code lines (i.e., non-blank lines that are not comments) | |
15765 | ||
15766 | @item | |
15767 | the number of comment lines | |
15768 | ||
15769 | @item | |
15770 | the number of code lines containing end-of-line comments; | |
15771 | ||
89893302 | 15772 | @item |
7954ad60 SR |
15773 | the comment percentage: the ratio between the number of lines that contain |
15774 | comments and the number of all non-blank lines, expressed as a percentage; | |
89893302 | 15775 | |
a5b62485 AC |
15776 | @item |
15777 | the number of empty lines and lines containing only space characters and/or | |
15778 | format effectors (blank lines) | |
15779 | ||
7954ad60 SR |
15780 | @item |
15781 | the average number of code lines in subprogram bodies, task bodies, entry | |
15782 | bodies and statement sequences in package bodies (this metric is only computed | |
15783 | across the whole set of the analyzed units) | |
15784 | ||
a5b62485 AC |
15785 | @end itemize |
15786 | ||
7954ad60 SR |
15787 | @noindent |
15788 | @command{gnatmetric} sums the values of the line metrics for all the | |
15789 | files being processed and then generates the cumulative results. The tool | |
15790 | also computes for all the files being processed the average number of code | |
15791 | lines in bodies. | |
a5b62485 | 15792 | |
7954ad60 SR |
15793 | You can use the following switches to select the specific line metrics |
15794 | to be computed and reported. | |
a5b62485 AC |
15795 | |
15796 | @table @option | |
7954ad60 | 15797 | @cindex @option{^--lines@var{x}^/LINE_COUNT_METRICS^} (@command{gnatmetric}) |
a5b62485 | 15798 | |
7954ad60 SR |
15799 | @ifclear vms |
15800 | @cindex @option{--no-lines@var{x}} | |
15801 | @end ifclear | |
15802 | ||
1abad480 | 15803 | @item ^--lines-all^/LINE_COUNT_METRICS=ALL^ |
7954ad60 SR |
15804 | Report all the line metrics |
15805 | ||
1abad480 | 15806 | @item ^--no-lines-all^/LINE_COUNT_METRICS=NONE^ |
7954ad60 SR |
15807 | Do not report any of line metrics |
15808 | ||
1abad480 | 15809 | @item ^--lines^/LINE_COUNT_METRICS=ALL_LINES^ |
7954ad60 SR |
15810 | Report the number of all lines |
15811 | ||
1abad480 | 15812 | @item ^--no-lines^/LINE_COUNT_METRICS=NOALL_LINES^ |
7954ad60 SR |
15813 | Do not report the number of all lines |
15814 | ||
1abad480 | 15815 | @item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES^ |
7954ad60 SR |
15816 | Report the number of code lines |
15817 | ||
1abad480 | 15818 | @item ^--no-lines-code^/LINE_COUNT_METRICS=NOCODE_LINES^ |
7954ad60 | 15819 | Do not report the number of code lines |
a5b62485 | 15820 | |
1abad480 | 15821 | @item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES^ |
7954ad60 | 15822 | Report the number of comment lines |
a5b62485 | 15823 | |
1abad480 | 15824 | @item ^--no-lines-comment^/LINE_COUNT_METRICS=NOCOMMENT_LINES^ |
7954ad60 SR |
15825 | Do not report the number of comment lines |
15826 | ||
1abad480 | 15827 | @item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES^ |
7954ad60 SR |
15828 | Report the number of code lines containing |
15829 | end-of-line comments | |
15830 | ||
1abad480 | 15831 | @item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=NOCODE_COMMENT_LINES^ |
7954ad60 | 15832 | Do not report the number of code lines containing |
a5b62485 AC |
15833 | end-of-line comments |
15834 | ||
1abad480 | 15835 | @item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE^ |
7954ad60 SR |
15836 | Report the comment percentage in the program text |
15837 | ||
1abad480 | 15838 | @item ^--no-lines-ratio^/LINE_COUNT_METRICS=NOCOMMENT_PERCENTAGE^ |
7954ad60 | 15839 | Do not report the comment percentage in the program text |
89893302 | 15840 | |
1abad480 | 15841 | @item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES^ |
7954ad60 SR |
15842 | Report the number of blank lines |
15843 | ||
1abad480 | 15844 | @item ^--no-lines-blank^/LINE_COUNT_METRICS=NOBLANK_LINES^ |
7954ad60 SR |
15845 | Do not report the number of blank lines |
15846 | ||
1abad480 | 15847 | @item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES^ |
7954ad60 SR |
15848 | Report the average number of code lines in subprogram bodies, task bodies, |
15849 | entry bodies and statement sequences in package bodies. The metric is computed | |
15850 | and reported for the whole set of processed Ada sources only. | |
15851 | ||
1abad480 | 15852 | @item ^--no-lines-average^/LINE_COUNT_METRICS=NOAVERAGE_BODY_LINES^ |
7954ad60 SR |
15853 | Do not report the average number of code lines in subprogram bodies, |
15854 | task bodies, entry bodies and statement sequences in package bodies. | |
a5b62485 AC |
15855 | |
15856 | @end table | |
15857 | ||
15858 | @node Syntax Metrics Control | |
7954ad60 | 15859 | @subsubsection Syntax Metrics Control |
a5b62485 AC |
15860 | @cindex Syntax metrics control in @command{gnatmetric} |
15861 | ||
15862 | @noindent | |
984a64bc AC |
15863 | @command{gnatmetric} computes various syntactic metrics for the |
15864 | outermost unit and for each eligible local unit: | |
15865 | ||
15866 | @table @emph | |
15867 | @item LSLOC (``Logical Source Lines Of Code'') | |
08f8a983 AC |
15868 | The total number of declarations and the total number of statements. Note |
15869 | that the definition of declarations is the one given in the reference | |
15870 | manual: | |
15871 | ||
15872 | @noindent | |
15873 | ``Each of the following is defined to be a declaration: any basic_declaration; | |
15874 | an enumeration_literal_specification; a discriminant_specification; | |
15875 | a component_declaration; a loop_parameter_specification; a | |
15876 | parameter_specification; a subprogram_body; an entry_declaration; | |
15877 | an entry_index_specification; a choice_parameter_specification; | |
15878 | a generic_formal_parameter_declaration.'' | |
15879 | ||
15880 | This means for example that each enumeration literal adds one to the count, | |
15881 | as well as each subprogram parameter. | |
15882 | ||
15883 | Thus the results from this metric will be significantly greater than might | |
15884 | be expected from a naive view of counting semicolons. | |
a5b62485 | 15885 | |
984a64bc | 15886 | @item Maximal static nesting level of inner program units |
87b3f81f | 15887 | According to |
e08b38f5 | 15888 | @cite{Ada Reference Manual}, 10.1(1), ``A program unit is either a |
a5b62485 AC |
15889 | package, a task unit, a protected unit, a |
15890 | protected entry, a generic unit, or an explicitly declared subprogram other | |
15891 | than an enumeration literal.'' | |
15892 | ||
984a64bc AC |
15893 | @item Maximal nesting level of composite syntactic constructs |
15894 | This corresponds to the notion of the | |
a5b62485 | 15895 | maximum nesting level in the GNAT built-in style checks |
984a64bc AC |
15896 | (@pxref{Style Checking}) |
15897 | @end table | |
a5b62485 | 15898 | |
984a64bc AC |
15899 | @noindent |
15900 | For the outermost unit in the file, @command{gnatmetric} additionally computes | |
a5b62485 AC |
15901 | the following metrics: |
15902 | ||
15903 | @table @emph | |
15904 | @item Public subprograms | |
1a5f40e1 | 15905 | This metric is computed for package specs. It is the |
984a64bc | 15906 | number of subprograms and generic subprograms declared in the visible |
7954ad60 | 15907 | part (including the visible part of nested packages, protected objects, and |
984a64bc | 15908 | protected types). |
a5b62485 AC |
15909 | |
15910 | @item All subprograms | |
984a64bc AC |
15911 | This metric is computed for bodies and subunits. The |
15912 | metric is equal to a total number of subprogram bodies in the compilation | |
15913 | unit. | |
a5b62485 AC |
15914 | Neither generic instantiations nor renamings-as-a-body nor body stubs |
15915 | are counted. Any subprogram body is counted, independently of its nesting | |
15916 | level and enclosing constructs. Generic bodies and bodies of protected | |
15917 | subprograms are counted in the same way as ``usual'' subprogram bodies. | |
15918 | ||
15919 | @item Public types | |
1a5f40e1 | 15920 | This metric is computed for package specs and |
a5b62485 AC |
15921 | generic package declarations. It is the total number of types |
15922 | that can be referenced from outside this compilation unit, plus the | |
7954ad60 SR |
15923 | number of types from all the visible parts of all the visible generic |
15924 | packages. Generic formal types are not counted. Only types, not subtypes, | |
984a64bc | 15925 | are included. |
a5b62485 AC |
15926 | |
15927 | @noindent | |
984a64bc | 15928 | Along with the total number of public types, the following |
a5b62485 AC |
15929 | types are counted and reported separately: |
15930 | ||
15931 | @itemize @bullet | |
15932 | @item | |
87b3f81f | 15933 | Abstract types |
a5b62485 AC |
15934 | |
15935 | @item | |
87b3f81f AC |
15936 | Root tagged types (abstract, non-abstract, private, non-private). Type |
15937 | extensions are @emph{not} counted | |
a5b62485 AC |
15938 | |
15939 | @item | |
87b3f81f | 15940 | Private types (including private extensions) |
a5b62485 AC |
15941 | |
15942 | @item | |
87b3f81f | 15943 | Task types |
a5b62485 AC |
15944 | |
15945 | @item | |
87b3f81f | 15946 | Protected types |
a5b62485 AC |
15947 | |
15948 | @end itemize | |
15949 | ||
15950 | @item All types | |
15951 | This metric is computed for any compilation unit. It is equal to the total | |
15952 | number of the declarations of different types given in the compilation unit. | |
15953 | The private and the corresponding full type declaration are counted as one | |
15954 | type declaration. Incomplete type declarations and generic formal types | |
15955 | are not counted. | |
15956 | No distinction is made among different kinds of types (abstract, | |
15957 | private etc.); the total number of types is computed and reported. | |
15958 | ||
15959 | @end table | |
15960 | ||
15961 | @noindent | |
15962 | By default, all the syntax metrics are computed and reported. You can use the | |
7954ad60 | 15963 | following switches to select specific syntax metrics. |
a5b62485 AC |
15964 | |
15965 | @table @option | |
a5b62485 | 15966 | |
7954ad60 | 15967 | @cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric}) |
a5b62485 | 15968 | |
7954ad60 | 15969 | @ifclear vms |
1a5f40e1 | 15970 | @cindex @option{--no-syntax@var{x}} (@command{gnatmetric}) |
7954ad60 SR |
15971 | @end ifclear |
15972 | ||
1abad480 | 15973 | @item ^--syntax-all^/SYNTAX_METRICS=ALL^ |
7954ad60 SR |
15974 | Report all the syntax metrics |
15975 | ||
1abad480 | 15976 | @item ^--no-syntax-all^/SYNTAX_METRICS=NONE^ |
7954ad60 SR |
15977 | Do not report any of syntax metrics |
15978 | ||
1abad480 | 15979 | @item ^--declarations^/SYNTAX_METRICS=DECLARATIONS^ |
7954ad60 SR |
15980 | Report the total number of declarations |
15981 | ||
1abad480 | 15982 | @item ^--no-declarations^/SYNTAX_METRICS=NODECLARATIONS^ |
7954ad60 SR |
15983 | Do not report the total number of declarations |
15984 | ||
1abad480 | 15985 | @item ^--statements^/SYNTAX_METRICS=STATEMENTS^ |
7954ad60 SR |
15986 | Report the total number of statements |
15987 | ||
1abad480 | 15988 | @item ^--no-statements^/SYNTAX_METRICS=NOSTATEMENTS^ |
7954ad60 SR |
15989 | Do not report the total number of statements |
15990 | ||
1abad480 | 15991 | @item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS^ |
7954ad60 | 15992 | Report the number of public subprograms in a compilation unit |
a5b62485 | 15993 | |
1abad480 | 15994 | @item ^--no-public-subprograms^/SYNTAX_METRICS=NOPUBLIC_SUBPROGRAMS^ |
7954ad60 | 15995 | Do not report the number of public subprograms in a compilation unit |
a5b62485 | 15996 | |
1abad480 | 15997 | @item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS^ |
7954ad60 | 15998 | Report the number of all the subprograms in a compilation unit |
a5b62485 | 15999 | |
1abad480 | 16000 | @item ^--no-all-subprograms^/SYNTAX_METRICS=NOALL_SUBPROGRAMS^ |
7954ad60 | 16001 | Do not report the number of all the subprograms in a compilation unit |
a5b62485 | 16002 | |
1abad480 | 16003 | @item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES^ |
7954ad60 | 16004 | Report the number of public types in a compilation unit |
a5b62485 | 16005 | |
1abad480 | 16006 | @item ^--no-public-types^/SYNTAX_METRICS=NOPUBLIC_TYPES^ |
7954ad60 SR |
16007 | Do not report the number of public types in a compilation unit |
16008 | ||
1abad480 | 16009 | @item ^--all-types^/SYNTAX_METRICS=ALL_TYPES^ |
7954ad60 SR |
16010 | Report the number of all the types in a compilation unit |
16011 | ||
1abad480 | 16012 | @item ^--no-all-types^/SYNTAX_METRICS=NOALL_TYPES^ |
7954ad60 SR |
16013 | Do not report the number of all the types in a compilation unit |
16014 | ||
1abad480 | 16015 | @item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING^ |
7954ad60 SR |
16016 | Report the maximal program unit nesting level |
16017 | ||
16018 | @item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^ | |
16019 | Do not report the maximal program unit nesting level | |
16020 | ||
1abad480 | 16021 | @item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING^ |
7954ad60 SR |
16022 | Report the maximal construct nesting level |
16023 | ||
1abad480 | 16024 | @item ^--no-construct-nesting^/SYNTAX_METRICS=NOCONSTRUCT_NESTING^ |
7954ad60 | 16025 | Do not report the maximal construct nesting level |
a5b62485 AC |
16026 | |
16027 | @end table | |
16028 | ||
16029 | @node Complexity Metrics Control | |
7954ad60 | 16030 | @subsubsection Complexity Metrics Control |
a5b62485 AC |
16031 | @cindex Complexity metrics control in @command{gnatmetric} |
16032 | ||
16033 | @noindent | |
16034 | For a program unit that is an executable body (a subprogram body (including | |
16035 | generic bodies), task body, entry body or a package body containing | |
7954ad60 | 16036 | its own statement sequence) @command{gnatmetric} computes the following |
a5b62485 AC |
16037 | complexity metrics: |
16038 | ||
16039 | @itemize @bullet | |
16040 | @item | |
16041 | McCabe cyclomatic complexity; | |
16042 | ||
16043 | @item | |
16044 | McCabe essential complexity; | |
16045 | ||
16046 | @item | |
b5ea9143 | 16047 | maximal loop nesting level; |
a5b62485 | 16048 | |
b5ea9143 AC |
16049 | @item |
16050 | extra exit points (for subprograms); | |
a5b62485 AC |
16051 | @end itemize |
16052 | ||
16053 | @noindent | |
b5ea9143 | 16054 | The McCabe cyclomatic complexity metric is defined |
8d6a2f69 | 16055 | in @url{http://www.mccabe.com/pdf/mccabe-nist235r.pdf} |
a5b62485 AC |
16056 | |
16057 | According to McCabe, both control statements and short-circuit control forms | |
9b7424a7 AC |
16058 | should be taken into account when computing cyclomatic complexity. |
16059 | For Ada 2012 we have also take into account conditional expressions | |
16060 | and quantified expressions. For each body, we compute three metric values: | |
a5b62485 AC |
16061 | |
16062 | @itemize @bullet | |
16063 | @item | |
16064 | the complexity introduced by control | |
16065 | statements only, without taking into account short-circuit forms, | |
16066 | ||
16067 | @item | |
16068 | the complexity introduced by short-circuit control forms only, and | |
16069 | ||
16070 | @item | |
16071 | the total | |
16072 | cyclomatic complexity, which is the sum of these two values. | |
16073 | @end itemize | |
16074 | ||
16075 | @noindent | |
b5ea9143 | 16076 | |
9b7424a7 AC |
16077 | The cyclomatic complexity is also computed for Ada 2012 expression functions. |
16078 | An expression function cannot have statements as its components, so only one | |
16079 | metric value is computed as a cyclomatic complexity of an expression function. | |
16080 | ||
b5ea9143 AC |
16081 | The origin of cyclomatic complexity metric is the need to estimate the number |
16082 | of independent paths in the control flow graph that in turn gives the number | |
16083 | of tests needed to satisfy paths coverage testing completeness criterion. | |
16084 | Considered from the testing point of view, a static Ada @code{loop} (that is, | |
16085 | the @code{loop} statement having static subtype in loop parameter | |
16086 | specification) does not add to cyclomatic complexity. By providing | |
16087 | @option{^--no-static-loop^NO_STATIC_LOOP^} option a user | |
16088 | may specify that such loops should not be counted when computing the | |
16089 | cyclomatic complexity metric | |
16090 | ||
16091 | The Ada essential complexity metric is a McCabe cyclomatic complexity metric | |
16092 | counted for the code that is reduced by excluding all the pure structural Ada | |
16093 | control statements. An compound statement is considered as a non-structural | |
16094 | if it contains a @code{raise} or @code{return} statement as it subcomponent, | |
16095 | or if it contains a @code{goto} statement that transfers the control outside | |
16096 | the operator. A selective accept statement with @code{terminate} alternative | |
16097 | is considered as non-structural statement. When computing this metric, | |
16098 | @code{exit} statements are treated in the same way as @code{goto} | |
16099 | statements unless @option{^-ne^NO_EXITS_AS_GOTOS^} option is specified. | |
16100 | ||
16101 | The Ada essential complexity metric defined here is intended to quantify | |
16102 | the extent to which the software is unstructured. It is adapted from | |
16103 | the McCabe essential complexity metric defined in | |
3ee8dde5 | 16104 | @url{http://www.mccabe.com/pdf/mccabe-nist235r.pdf} but is modified to be more |
b5ea9143 AC |
16105 | suitable for typical Ada usage. For example, short circuit forms |
16106 | are not penalized as unstructured in the Ada essential complexity metric. | |
16107 | ||
a5b62485 | 16108 | When computing cyclomatic and essential complexity, @command{gnatmetric} skips |
9b7424a7 AC |
16109 | the code in the exception handlers and in all the nested program units. The |
16110 | code of assertions and predicates (that is, subprogram preconditions and | |
16111 | postconditions, subtype predicates and type invariants) is also skipped. | |
a5b62485 AC |
16112 | |
16113 | By default, all the complexity metrics are computed and reported. | |
7954ad60 | 16114 | For more fine-grained control you can use |
a5b62485 AC |
16115 | the following switches: |
16116 | ||
16117 | @table @option | |
7954ad60 | 16118 | @cindex @option{^-complexity@var{x}^/COMPLEXITY_METRICS^} (@command{gnatmetric}) |
a5b62485 | 16119 | |
7954ad60 SR |
16120 | @ifclear vms |
16121 | @cindex @option{--no-complexity@var{x}} | |
16122 | @end ifclear | |
16123 | ||
1abad480 | 16124 | @item ^--complexity-all^/COMPLEXITY_METRICS=ALL^ |
7954ad60 SR |
16125 | Report all the complexity metrics |
16126 | ||
1abad480 | 16127 | @item ^--no-complexity-all^/COMPLEXITY_METRICS=NONE^ |
7954ad60 SR |
16128 | Do not report any of complexity metrics |
16129 | ||
1abad480 | 16130 | @item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC^ |
7954ad60 | 16131 | Report the McCabe Cyclomatic Complexity |
a5b62485 | 16132 | |
1abad480 | 16133 | @item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=NOCYCLOMATIC^ |
7954ad60 | 16134 | Do not report the McCabe Cyclomatic Complexity |
a5b62485 | 16135 | |
1abad480 | 16136 | @item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL^ |
7954ad60 | 16137 | Report the Essential Complexity |
a5b62485 | 16138 | |
1abad480 | 16139 | @item ^--no-complexity-essential^/COMPLEXITY_METRICS=NOESSENTIAL^ |
7954ad60 SR |
16140 | Do not report the Essential Complexity |
16141 | ||
16142 | @item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^ | |
16143 | Report maximal loop nesting level | |
16144 | ||
1abad480 | 16145 | @item ^--no-loop-nesting^/COMPLEXITY_METRICS=NOLOOP_NESTING^ |
7954ad60 SR |
16146 | Do not report maximal loop nesting level |
16147 | ||
1abad480 | 16148 | @item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY^ |
7954ad60 SR |
16149 | Report the average McCabe Cyclomatic Complexity for all the subprogram bodies, |
16150 | task bodies, entry bodies and statement sequences in package bodies. | |
16151 | The metric is computed and reported for whole set of processed Ada sources | |
16152 | only. | |
16153 | ||
1abad480 | 16154 | @item ^--no-complexity-average^/COMPLEXITY_METRICS=NOAVERAGE_COMPLEXITY^ |
7954ad60 SR |
16155 | Do not report the average McCabe Cyclomatic Complexity for all the subprogram |
16156 | bodies, task bodies, entry bodies and statement sequences in package bodies | |
16157 | ||
16158 | @cindex @option{^-ne^/NO_EXITS_AS_GOTOS^} (@command{gnatmetric}) | |
16159 | @item ^-ne^/NO_EXITS_AS_GOTOS^ | |
a5b62485 AC |
16160 | Do not consider @code{exit} statements as @code{goto}s when |
16161 | computing Essential Complexity | |
16162 | ||
b5ea9143 AC |
16163 | @cindex @option{^--no-static-loop^/NO_STATIC_LOOP^} (@command{gnatmetric}) |
16164 | @item ^--no-static-loop^/NO_STATIC_LOOP^ | |
16165 | Do not consider static loops when computing cyclomatic complexity | |
16166 | ||
1abad480 | 16167 | @item ^--extra-exit-points^/EXTRA_EXIT_POINTS^ |
35117aa8 AC |
16168 | Report the extra exit points for subprogram bodies. As an exit point, this |
16169 | metric counts @code{return} statements and raise statements in case when the | |
16170 | raised exception is not handled in the same body. In case of a function this | |
16171 | metric subtracts 1 from the number of exit points, because a function body | |
16172 | must contain at least one @code{return} statement. | |
0c020dde | 16173 | |
1abad480 | 16174 | @item ^--no-extra-exit-points^/NOEXTRA_EXIT_POINTS^ |
0c020dde | 16175 | Do not report the extra exit points for subprogram bodies |
a5b62485 AC |
16176 | @end table |
16177 | ||
1a5f40e1 | 16178 | |
0da80d7d AC |
16179 | @node Coupling Metrics Control |
16180 | @subsubsection Coupling Metrics Control | |
16181 | @cindex Coupling metrics control in @command{gnatmetric} | |
1a5f40e1 VC |
16182 | |
16183 | @noindent | |
16184 | @cindex Coupling metrics (in in @command{gnatmetric}) | |
0da80d7d AC |
16185 | Coupling metrics measure the dependencies between a given entity and other |
16186 | entities the program consists of. The goal of these metrics is to estimate the | |
16187 | stability of the whole program considered as the collection of entities | |
16188 | (modules, classes etc.). | |
16189 | ||
16190 | Gnatmetric computes the following coupling metrics: | |
16191 | ||
16192 | @itemize @bullet | |
16193 | ||
16194 | @item | |
16195 | @emph{object-oriented coupling} - for classes in traditional object-oriented | |
16196 | sense; | |
16197 | ||
16198 | @item | |
00332244 | 16199 | @emph{unit coupling} - for all the program units making up a program; |
0da80d7d AC |
16200 | |
16201 | @item | |
00332244 | 16202 | @emph{control coupling} - this metric counts dependencies between a unit and |
0da80d7d AC |
16203 | only those units that define subprograms; |
16204 | @end itemize | |
16205 | ||
16206 | @noindent | |
16207 | Two kinds of coupling metrics are computed: | |
16208 | ||
16209 | @table @asis | |
16210 | @item fan-out coupling (efferent coupling) | |
16211 | @cindex fan-out coupling | |
16212 | @cindex efferent coupling | |
16213 | the number of entities the given entity depends upon. It | |
16214 | estimates in what extent the given entity depends on the changes in | |
16215 | ``external world'' | |
16216 | ||
16217 | @item fan-in coupling (afferent coupling) | |
16218 | @cindex fan-in coupling | |
16219 | @cindex afferent coupling | |
16220 | the number of entities that depend on a given entity. | |
16221 | It estimates in what extent the ``external world'' depends on the changes in a | |
16222 | given entity | |
16223 | @end table | |
16224 | ||
16225 | @noindent | |
16226 | ||
16227 | Object-oriented coupling metrics are metrics that measure the dependencies | |
16228 | between a given class (or a group of classes) and the other classes in the | |
16229 | program. In this subsection the term ``class'' is used in its traditional | |
16230 | object-oriented programming sense (an instantiable module that contains data | |
16231 | and/or method members). A @emph{category} (of classes) is a group of closely | |
16232 | related classes that are reused and/or modified together. | |
16233 | ||
16234 | A class @code{K}'s fan-out coupling is the number of classes | |
1a5f40e1 | 16235 | that @code{K} depends upon. |
0da80d7d | 16236 | A category's fan-out coupling is the number of classes outside the |
1a5f40e1 VC |
16237 | category that the classes inside the category depend upon. |
16238 | ||
0da80d7d | 16239 | A class @code{K}'s fan-in coupling is the number of classes |
1a5f40e1 | 16240 | that depend upon @code{K}. |
0da80d7d | 16241 | A category's fan-in coupling is the number of classes outside the |
1a5f40e1 VC |
16242 | category that depend on classes belonging to the category. |
16243 | ||
16244 | Ada's implementation of the object-oriented paradigm does not use the | |
16245 | traditional class notion, so the definition of the coupling | |
16246 | metrics for Ada maps the class and class category notions | |
16247 | onto Ada constructs. | |
16248 | ||
16249 | For the coupling metrics, several kinds of modules -- a library package, | |
16250 | a library generic package, and a library generic package instantiation -- | |
16251 | that define a tagged type or an interface type are | |
16252 | considered to be a class. A category consists of a library package (or | |
16253 | a library generic package) that defines a tagged or an interface type, | |
16254 | together with all its descendant (generic) packages that define tagged | |
0da80d7d AC |
16255 | or interface types. That is a |
16256 | category is an Ada hierarchy of library-level program units. So class coupling | |
16257 | in case of Ada is called as tagged coupling, and category coupling - as | |
16258 | hierarchy coupling. | |
16259 | ||
16260 | For any package counted as a class, its body and subunits (if any) are | |
16261 | considered together with its spec when counting the dependencies, and coupling | |
16262 | metrics are reported for spec units only. For dependencies between classes, | |
16263 | the Ada semantic dependencies are considered. For object-oriented coupling | |
16264 | metrics, only dependencies on units that are considered as classes, are | |
16265 | considered. | |
16266 | ||
16267 | For unit and control coupling also not compilation units but program units are | |
16268 | counted. That is, for a package, its spec, its body and its subunits (if any) | |
16269 | are considered as making up one unit, and the dependencies that are counted | |
16270 | are the dependencies of all these compilation units collected together as | |
16271 | the dependencies as a (whole) unit. And metrics are reported for spec | |
16272 | compilation units only (or for a subprogram body unit in case if there is no | |
16273 | separate spec for the given subprogram). | |
16274 | ||
16275 | For unit coupling, dependencies between all kinds of program units are | |
16276 | considered. For control coupling, for each unit the dependencies of this unit | |
16277 | upon units that define subprograms are counted, so control fan-out coupling | |
16278 | is reported for all units, but control fan-in coupling - only for the units | |
16279 | that define subprograms. | |
16280 | ||
bb9c600b AC |
16281 | The following simple example illustrates the difference between unit coupling |
16282 | and control coupling metrics: | |
0da80d7d | 16283 | |
bb9c600b AC |
16284 | @smallexample @c ada |
16285 | package Lib_1 is | |
16286 | function F_1 (I : Integer) return Integer; | |
16287 | end Lib_1; | |
16288 | ||
16289 | package Lib_2 is | |
16290 | type T_2 is new Integer; | |
16291 | end Lib_2; | |
0da80d7d | 16292 | |
bb9c600b AC |
16293 | package body Lib_1 is |
16294 | function F_1 (I : Integer) return Integer is | |
16295 | begin | |
16296 | return I + 1; | |
16297 | end F_1; | |
16298 | end Lib_1; | |
0da80d7d | 16299 | |
bb9c600b AC |
16300 | with Lib_2; use Lib_2; |
16301 | package Pack is | |
16302 | Var : T_2; | |
16303 | function Fun (I : Integer) return Integer; | |
16304 | end Pack; | |
16305 | ||
16306 | with Lib_1; use Lib_1; | |
16307 | package body Pack is | |
16308 | function Fun (I : Integer) return Integer is | |
16309 | begin | |
16310 | return F_1 (I); | |
16311 | end Fun; | |
16312 | end Pack; | |
16313 | @end smallexample | |
0da80d7d | 16314 | |
bb9c600b AC |
16315 | @noindent |
16316 | if we apply @command{gnatmetric} with @code{--coupling-all} option to these | |
16317 | units, the result will be: | |
16318 | ||
16319 | @smallexample | |
16320 | Coupling metrics: | |
16321 | ================= | |
16322 | Unit Lib_1 (C:\customers\662\L406-007\lib_1.ads) | |
16323 | control fan-out coupling : 0 | |
16324 | control fan-in coupling : 1 | |
16325 | unit fan-out coupling : 0 | |
16326 | unit fan-in coupling : 1 | |
16327 | ||
16328 | Unit Pack (C:\customers\662\L406-007\pack.ads) | |
16329 | control fan-out coupling : 1 | |
16330 | control fan-in coupling : 0 | |
16331 | unit fan-out coupling : 2 | |
16332 | unit fan-in coupling : 0 | |
16333 | ||
16334 | Unit Lib_2 (C:\customers\662\L406-007\lib_2.ads) | |
16335 | control fan-out coupling : 0 | |
16336 | unit fan-out coupling : 0 | |
16337 | unit fan-in coupling : 1 | |
16338 | @end smallexample | |
16339 | ||
16340 | @noindent | |
16341 | The result does not contain values for object-oriented | |
16342 | coupling because none of the argument unit contains a tagged type and | |
16343 | therefore none of these units can be treated as a class. | |
16344 | ||
16345 | @code{Pack} (considered as a program unit, that is spec+body) depends on two | |
16346 | units - @code{Lib_1} @code{and Lib_2}, therefore it has unit fan-out coupling | |
16347 | equals to 2. And nothing depend on it, so its unit fan-in coupling is 0 as | |
16348 | well as control fan-in coupling. Only one of the units @code{Pack} depends | |
16349 | upon defines a subprogram, so its control fan-out coupling is 1. | |
16350 | ||
16351 | @code{Lib_2} depends on nothing, so fan-out metrics for it are 0. It does | |
16352 | not define a subprogram, so control fan-in metric cannot be applied to it, | |
16353 | and there is one unit that depends on it (@code{Pack}), so it has | |
16354 | unit fan-in coupling equals to 1. | |
16355 | ||
16356 | @code{Lib_1} is similar to @code{Lib_2}, but it does define a subprogram. | |
16357 | So it has control fan-in coupling equals to 1 (because there is a unit | |
16358 | depending on it). | |
1a5f40e1 VC |
16359 | |
16360 | When computing coupling metrics, @command{gnatmetric} counts only | |
bb9c600b AC |
16361 | dependencies between units that are arguments of the @command{gnatmetric} |
16362 | call. Coupling metrics are program-wide (or project-wide) metrics, so to | |
1a5f40e1 VC |
16363 | get a valid result, you should call @command{gnatmetric} for |
16364 | the whole set of sources that make up your program. It can be done | |
16365 | by calling @command{gnatmetric} from the GNAT driver with @option{-U} | |
0da80d7d | 16366 | option (see @ref{The GNAT Driver and Project Files} for details). |
1a5f40e1 VC |
16367 | |
16368 | By default, all the coupling metrics are disabled. You can use the following | |
16369 | switches to specify the coupling metrics to be computed and reported: | |
16370 | ||
16371 | @table @option | |
16372 | ||
16373 | @ifclear vms | |
0da80d7d AC |
16374 | @cindex @option{--tagged-coupling@var{x}} (@command{gnatmetric}) |
16375 | @cindex @option{--hierarchy-coupling@var{x}} (@command{gnatmetric}) | |
16376 | @cindex @option{--unit-coupling@var{x}} (@command{gnatmetric}) | |
16377 | @cindex @option{--control-coupling@var{x}} (@command{gnatmetric}) | |
1a5f40e1 VC |
16378 | @end ifclear |
16379 | ||
16380 | @ifset vms | |
16381 | @cindex @option{/COUPLING_METRICS} (@command{gnatmetric}) | |
16382 | @end ifset | |
16383 | ||
1abad480 | 16384 | @item ^--coupling-all^/COUPLING_METRICS=ALL^ |
1a5f40e1 VC |
16385 | Report all the coupling metrics |
16386 | ||
0da80d7d AC |
16387 | @item ^--tagged-coupling-out^/COUPLING_METRICS=TAGGED_OUT^ |
16388 | Report tagged (class) fan-out coupling | |
1a5f40e1 | 16389 | |
0da80d7d AC |
16390 | @item ^--tagged-coupling-in^/COUPLING_METRICS=TAGGED_IN^ |
16391 | Report tagged (class) fan-in coupling | |
1a5f40e1 | 16392 | |
0da80d7d AC |
16393 | @item ^--hierarchy-coupling-out^/COUPLING_METRICS=HIERARCHY_OUT^ |
16394 | Report hierarchy (category) fan-out coupling | |
1a5f40e1 | 16395 | |
0da80d7d AC |
16396 | @item ^--hierarchy-coupling-in^/COUPLING_METRICS=HIERARCHY_IN^ |
16397 | Report hierarchy (category) fan-in coupling | |
1a5f40e1 | 16398 | |
0da80d7d AC |
16399 | @item ^--unit-coupling-out^/COUPLING_METRICS=UNIT_OUT^ |
16400 | Report unit fan-out coupling | |
1a5f40e1 | 16401 | |
0da80d7d AC |
16402 | @item ^--unit-coupling-in^/COUPLING_METRICS=UNIT_IN^ |
16403 | Report unit fan-in coupling | |
1a5f40e1 | 16404 | |
0da80d7d AC |
16405 | @item ^--control-coupling-out^/COUPLING_METRICS=CONTROL_OUT^ |
16406 | Report control fan-out coupling | |
1a5f40e1 | 16407 | |
0da80d7d AC |
16408 | @item ^--control-coupling-in^/COUPLING_METRICS=CONTROL_IN^ |
16409 | Report control fan-in coupling | |
1a5f40e1 VC |
16410 | @end table |
16411 | ||
a5b62485 AC |
16412 | @node Other gnatmetric Switches |
16413 | @subsection Other @code{gnatmetric} Switches | |
16414 | ||
16415 | @noindent | |
16416 | Additional @command{gnatmetric} switches are as follows: | |
16417 | ||
16418 | @table @option | |
327b1ba4 AC |
16419 | @item --version |
16420 | @cindex @option{--version} @command{gnatmetric} | |
16421 | Display Copyright and version, then exit disregarding all other options. | |
16422 | ||
16423 | @item --help | |
16424 | @cindex @option{--help} @command{gnatmetric} | |
16425 | Display usage, then exit disregarding all other options. | |
16426 | ||
46de64ca | 16427 | @item -P @var{file} |
350b83cc | 16428 | @cindex @option{-P} @command{gnatmetric} |
46de64ca AC |
16429 | Indicates the name of the project file that describes the set of sources |
16430 | to be processed. The exact set of argument sources depends on other options | |
16431 | specified, see below. | |
16432 | ||
16433 | @item -U | |
16434 | @cindex @option{-U} @command{gnatmetric} | |
16435 | If a project file is specified and no argument source is explicitly | |
16436 | specified (either directly or by means of @option{-files} option), process | |
16437 | all the units of the closure of the argument project. Otherwise this option | |
16438 | has no effect. | |
16439 | ||
16440 | @item -U @var{main_unit} | |
46de64ca AC |
16441 | If a project file is specified and no argument source is explicitly |
16442 | specified (either directly or by means of @option{-files} option), process | |
16443 | the closure of units rooted at @var{main_unit}. Otherwise this option | |
16444 | has no effect. | |
16445 | ||
16446 | @item -X@var{name}=@var{value} | |
350b83cc | 16447 | @cindex @option{-X} @command{gnatmetric} |
46de64ca | 16448 | Indicates that external variable @var{name} in the argument project |
f1a3590e | 16449 | has the value @var{value}. Has no effect if no project is specified as |
46de64ca AC |
16450 | tool argument. |
16451 | ||
16452 | @item --subdirs=@var{dir} | |
16453 | @cindex @option{--subdirs=@var{dir}} @command{gnatmetric} | |
16454 | Use the specified subdirectory of the project objects file (or of the | |
16455 | project file directory if the project does not specify an object directory) | |
16456 | for tool output files. Has no effect if no project is specified as | |
c97d7285 AC |
16457 | tool argument r if @option{--no_objects_dir} is specified. |
16458 | ||
16459 | @item --no_objects_dir | |
16460 | @cindex @option{--no_objects_dir} @command{gnatmetric} | |
16461 | Place all the result files into the current directory instead of | |
16462 | project objects directory. This corresponds to the @command{gnatcheck} | |
16463 | behavior when it is called with the project file from the | |
16464 | GNAT driver. Has no effect if no project is specified. | |
46de64ca | 16465 | |
a5b62485 AC |
16466 | @item ^-files @var{filename}^/FILES=@var{filename}^ |
16467 | @cindex @option{^-files^/FILES^} (@code{gnatmetric}) | |
16468 | Take the argument source files from the specified file. This file should be an | |
7954ad60 | 16469 | ordinary text file containing file names separated by spaces or |
7415029d | 16470 | line breaks. You can use this switch more than once in the same call to |
87b3f81f AC |
16471 | @command{gnatmetric}. You also can combine this switch with |
16472 | an explicit list of files. | |
a5b62485 | 16473 | |
e09a5598 AC |
16474 | @item ^-j^/PROCESSES=^@var{n} |
16475 | @cindex @option{^-j^/PROCESSES^} (@command{gnatmetric}) | |
16476 | Use @var{n} processes to carry out the tree creations (internal representations | |
16477 | of the argument sources). On a multiprocessor machine this speeds up processing | |
16478 | of big sets of argument sources. If @var{n} is 0, then the maximum number of | |
16479 | parallel tree creations is the number of core processors on the platform. | |
16480 | ||
c3b266d6 AC |
16481 | @cindex @option{^-t^/TIME^} (@command{gnatmetric}) |
16482 | @item ^-t^/TIME^ | |
16483 | Print out execution time. | |
16484 | ||
a5b62485 | 16485 | @item ^-v^/VERBOSE^ |
e09a5598 | 16486 | @cindex @option{^-v^/VERBOSE^} (@command{gnatmetric}) |
a5b62485 AC |
16487 | Verbose mode; |
16488 | @command{gnatmetric} generates version information and then | |
bde83138 | 16489 | a trace of sources being processed. |
a5b62485 | 16490 | |
a5b62485 | 16491 | @item ^-q^/QUIET^ |
e09a5598 | 16492 | @cindex @option{^-q^/QUIET^} (@command{gnatmetric}) |
a5b62485 AC |
16493 | Quiet mode. |
16494 | @end table | |
16495 | ||
46de64ca AC |
16496 | @noindent |
16497 | If a project file is specified and no argument source is explicitly | |
16498 | specified (either directly or by means of @option{-files} option), and no | |
16499 | @option{-U} is specified, then the set of processed sources is | |
16500 | all the immediate units of the argument project. | |
16501 | ||
16502 | ||
16503 | @ignore | |
e08b38f5 VC |
16504 | @node Generate project-wide metrics |
16505 | @subsection Generate project-wide metrics | |
16506 | ||
7954ad60 | 16507 | In order to compute metrics on all units of a given project, you can use |
e08b38f5 VC |
16508 | the @command{gnat} driver along with the @option{-P} option: |
16509 | @smallexample | |
16510 | gnat metric -Pproj | |
16511 | @end smallexample | |
7954ad60 SR |
16512 | |
16513 | @noindent | |
16514 | If the project @code{proj} depends upon other projects, you can compute | |
e08b38f5 VC |
16515 | the metrics on the project closure using the @option{-U} option: |
16516 | @smallexample | |
16517 | gnat metric -Pproj -U | |
16518 | @end smallexample | |
7954ad60 SR |
16519 | |
16520 | @noindent | |
e08b38f5 | 16521 | Finally, if not all the units are relevant to a particular main |
7954ad60 | 16522 | program in the project closure, you can generate metrics for the set |
e08b38f5 VC |
16523 | of units needed to create a given main program (unit closure) using |
16524 | the @option{-U} option followed by the name of the main unit: | |
16525 | @smallexample | |
16526 | gnat metric -Pproj -U main | |
16527 | @end smallexample | |
46de64ca | 16528 | @end ignore |
1037b0f4 | 16529 | @end ifclear |
e08b38f5 VC |
16530 | |
16531 | ||
7cd4527e | 16532 | @c *********************************** |
c2658843 AC |
16533 | @node File Name Krunching with gnatkr |
16534 | @chapter File Name Krunching with @code{gnatkr} | |
7cd4527e AC |
16535 | @findex gnatkr |
16536 | ||
16537 | @noindent | |
16538 | This chapter discusses the method used by the compiler to shorten | |
16539 | the default file names chosen for Ada units so that they do not | |
16540 | exceed the maximum length permitted. It also describes the | |
16541 | @code{gnatkr} utility that can be used to determine the result of | |
16542 | applying this shortening. | |
16543 | @menu | |
16544 | * About gnatkr:: | |
16545 | * Using gnatkr:: | |
16546 | * Krunching Method:: | |
16547 | * Examples of gnatkr Usage:: | |
16548 | @end menu | |
16549 | ||
16550 | @node About gnatkr | |
16551 | @section About @code{gnatkr} | |
16552 | ||
16553 | @noindent | |
16554 | The default file naming rule in GNAT | |
16555 | is that the file name must be derived from | |
16556 | the unit name. The exact default rule is as follows: | |
16557 | @itemize @bullet | |
16558 | @item | |
16559 | Take the unit name and replace all dots by hyphens. | |
16560 | @item | |
16561 | If such a replacement occurs in the | |
16562 | second character position of a name, and the first character is | |
8dd07840 RW |
16563 | ^@samp{a}, @samp{g}, @samp{s}, or @samp{i}, ^@samp{A}, @samp{G}, @samp{S}, or @samp{I},^ |
16564 | then replace the dot by the character | |
16565 | ^@samp{~} (tilde)^@samp{$} (dollar sign)^ | |
7cd4527e AC |
16566 | instead of a minus. |
16567 | @end itemize | |
16568 | The reason for this exception is to avoid clashes | |
16569 | with the standard names for children of System, Ada, Interfaces, | |
8dd07840 RW |
16570 | and GNAT, which use the prefixes |
16571 | ^@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},^@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},^ | |
7cd4527e AC |
16572 | respectively. |
16573 | ||
16574 | The @option{^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{nn}} | |
16575 | switch of the compiler activates a ``krunching'' | |
16576 | circuit that limits file names to nn characters (where nn is a decimal | |
16577 | integer). For example, using OpenVMS, | |
16578 | where the maximum file name length is | |
16579 | 39, the value of nn is usually set to 39, but if you want to generate | |
16580 | a set of files that would be usable if ported to a system with some | |
16581 | different maximum file length, then a different value can be specified. | |
16582 | The default value of 39 for OpenVMS need not be specified. | |
16583 | ||
16584 | The @code{gnatkr} utility can be used to determine the krunched name for | |
16585 | a given file, when krunched to a specified maximum length. | |
16586 | ||
16587 | @node Using gnatkr | |
16588 | @section Using @code{gnatkr} | |
16589 | ||
16590 | @noindent | |
16591 | The @code{gnatkr} command has the form | |
16592 | ||
16593 | @ifclear vms | |
16594 | @smallexample | |
e074d476 AC |
16595 | @c $ gnatkr @var{name} @ovar{length} |
16596 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
16597 | $ gnatkr @var{name} @r{[}@var{length}@r{]} | |
7cd4527e AC |
16598 | @end smallexample |
16599 | @end ifclear | |
16600 | ||
16601 | @ifset vms | |
16602 | @smallexample | |
16603 | $ gnatkr @var{name} /COUNT=nn | |
16604 | @end smallexample | |
16605 | @end ifset | |
16606 | ||
16607 | @noindent | |
16608 | @var{name} is the uncrunched file name, derived from the name of the unit | |
8dd07840 | 16609 | in the standard manner described in the previous section (i.e., in particular |
7cd4527e AC |
16610 | all dots are replaced by hyphens). The file name may or may not have an |
16611 | extension (defined as a suffix of the form period followed by arbitrary | |
16612 | characters other than period). If an extension is present then it will | |
16613 | be preserved in the output. For example, when krunching @file{hellofile.ads} | |
16614 | to eight characters, the result will be hellofil.ads. | |
16615 | ||
16616 | Note: for compatibility with previous versions of @code{gnatkr} dots may | |
16617 | appear in the name instead of hyphens, but the last dot will always be | |
16618 | taken as the start of an extension. So if @code{gnatkr} is given an argument | |
16619 | such as @file{Hello.World.adb} it will be treated exactly as if the first | |
16620 | period had been a hyphen, and for example krunching to eight characters | |
16621 | gives the result @file{hellworl.adb}. | |
16622 | ||
16623 | Note that the result is always all lower case (except on OpenVMS where it is | |
16624 | all upper case). Characters of the other case are folded as required. | |
16625 | ||
16626 | @var{length} represents the length of the krunched name. The default | |
16627 | when no argument is given is ^8^39^ characters. A length of zero stands for | |
16628 | unlimited, in other words do not chop except for system files where the | |
5ff62c2e | 16629 | implied crunching length is always eight characters. |
7cd4527e AC |
16630 | |
16631 | @noindent | |
16632 | The output is the krunched name. The output has an extension only if the | |
16633 | original argument was a file name with an extension. | |
16634 | ||
16635 | @node Krunching Method | |
16636 | @section Krunching Method | |
16637 | ||
16638 | @noindent | |
16639 | The initial file name is determined by the name of the unit that the file | |
16640 | contains. The name is formed by taking the full expanded name of the | |
16641 | unit and replacing the separating dots with hyphens and | |
16642 | using ^lowercase^uppercase^ | |
16643 | for all letters, except that a hyphen in the second character position is | |
16644 | replaced by a ^tilde^dollar sign^ if the first character is | |
8dd07840 | 16645 | ^@samp{a}, @samp{i}, @samp{g}, or @samp{s}^@samp{A}, @samp{I}, @samp{G}, or @samp{S}^. |
7cd4527e | 16646 | The extension is @code{.ads} for a |
1a5f40e1 | 16647 | spec and @code{.adb} for a body. |
7cd4527e AC |
16648 | Krunching does not affect the extension, but the file name is shortened to |
16649 | the specified length by following these rules: | |
16650 | ||
16651 | @itemize @bullet | |
16652 | @item | |
16653 | The name is divided into segments separated by hyphens, tildes or | |
16654 | underscores and all hyphens, tildes, and underscores are | |
16655 | eliminated. If this leaves the name short enough, we are done. | |
16656 | ||
16657 | @item | |
16658 | If the name is too long, the longest segment is located (left-most | |
16659 | if there are two of equal length), and shortened by dropping | |
16660 | its last character. This is repeated until the name is short enough. | |
16661 | ||
16662 | As an example, consider the krunching of @*@file{our-strings-wide_fixed.adb} | |
16663 | to fit the name into 8 characters as required by some operating systems. | |
16664 | ||
16665 | @smallexample | |
16666 | our-strings-wide_fixed 22 | |
16667 | our strings wide fixed 19 | |
16668 | our string wide fixed 18 | |
16669 | our strin wide fixed 17 | |
16670 | our stri wide fixed 16 | |
16671 | our stri wide fixe 15 | |
16672 | our str wide fixe 14 | |
16673 | our str wid fixe 13 | |
16674 | our str wid fix 12 | |
16675 | ou str wid fix 11 | |
16676 | ou st wid fix 10 | |
16677 | ou st wi fix 9 | |
16678 | ou st wi fi 8 | |
16679 | Final file name: oustwifi.adb | |
16680 | @end smallexample | |
16681 | ||
16682 | @item | |
16683 | The file names for all predefined units are always krunched to eight | |
16684 | characters. The krunching of these predefined units uses the following | |
16685 | special prefix replacements: | |
16686 | ||
16687 | @table @file | |
16688 | @item ada- | |
16689 | replaced by @file{^a^A^-} | |
16690 | ||
16691 | @item gnat- | |
88e1739c FW |
16692 | replaced by @file{^g^G^-} |
16693 | ||
16694 | @item interfaces- | |
16695 | replaced by @file{^i^I^-} | |
16696 | ||
16697 | @item system- | |
16698 | replaced by @file{^s^S^-} | |
16699 | @end table | |
16700 | ||
16701 | These system files have a hyphen in the second character position. That | |
16702 | is why normal user files replace such a character with a | |
16703 | ^tilde^dollar sign^, to | |
16704 | avoid confusion with system file names. | |
16705 | ||
16706 | As an example of this special rule, consider | |
16707 | @*@file{ada-strings-wide_fixed.adb}, which gets krunched as follows: | |
16708 | ||
16709 | @smallexample | |
16710 | ada-strings-wide_fixed 22 | |
16711 | a- strings wide fixed 18 | |
16712 | a- string wide fixed 17 | |
16713 | a- strin wide fixed 16 | |
16714 | a- stri wide fixed 15 | |
16715 | a- stri wide fixe 14 | |
16716 | a- str wide fixe 13 | |
16717 | a- str wid fixe 12 | |
16718 | a- str wid fix 11 | |
16719 | a- st wid fix 10 | |
16720 | a- st wi fix 9 | |
16721 | a- st wi fi 8 | |
16722 | Final file name: a-stwifi.adb | |
16723 | @end smallexample | |
16724 | @end itemize | |
16725 | ||
16726 | Of course no file shortening algorithm can guarantee uniqueness over all | |
16727 | possible unit names, and if file name krunching is used then it is your | |
16728 | responsibility to ensure that no name clashes occur. The utility | |
16729 | program @code{gnatkr} is supplied for conveniently determining the | |
16730 | krunched name of a file. | |
16731 | ||
16732 | @node Examples of gnatkr Usage | |
16733 | @section Examples of @code{gnatkr} Usage | |
16734 | ||
16735 | @smallexample | |
16736 | @iftex | |
16737 | @leftskip=0cm | |
16738 | @end iftex | |
16739 | @ifclear vms | |
16740 | $ gnatkr very_long_unit_name.ads --> velounna.ads | |
16741 | $ gnatkr grandparent-parent-child.ads --> grparchi.ads | |
7cd4527e AC |
16742 | $ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads |
16743 | $ gnatkr grandparent-parent-child --> grparchi | |
88e1739c FW |
16744 | @end ifclear |
16745 | $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads | |
16746 | $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads | |
16747 | @end smallexample | |
16748 | ||
c2658843 AC |
16749 | @node Preprocessing with gnatprep |
16750 | @chapter Preprocessing with @code{gnatprep} | |
88e1739c FW |
16751 | @findex gnatprep |
16752 | ||
16753 | @noindent | |
c690a2ec RD |
16754 | This chapter discusses how to use GNAT's @code{gnatprep} utility for simple |
16755 | preprocessing. | |
16756 | Although designed for use with GNAT, @code{gnatprep} does not depend on any | |
16757 | special GNAT features. | |
16758 | For further discussion of conditional compilation in general, see | |
16759 | @ref{Conditional Compilation}. | |
88e1739c FW |
16760 | |
16761 | @menu | |
1a5f40e1 | 16762 | * Preprocessing Symbols:: |
88e1739c FW |
16763 | * Using gnatprep:: |
16764 | * Switches for gnatprep:: | |
16765 | * Form of Definitions File:: | |
16766 | * Form of Input Text for gnatprep:: | |
16767 | @end menu | |
16768 | ||
1a5f40e1 VC |
16769 | @node Preprocessing Symbols |
16770 | @section Preprocessing Symbols | |
16771 | ||
16772 | @noindent | |
16773 | Preprocessing symbols are defined in definition files and referred to in | |
16774 | sources to be preprocessed. A Preprocessing symbol is an identifier, following | |
16775 | normal Ada (case-insensitive) rules for its syntax, with the restriction that | |
16776 | all characters need to be in the ASCII set (no accented letters). | |
c690a2ec | 16777 | |
88e1739c FW |
16778 | @node Using gnatprep |
16779 | @section Using @code{gnatprep} | |
16780 | ||
16781 | @noindent | |
16782 | To call @code{gnatprep} use | |
16783 | ||
16784 | @smallexample | |
e074d476 AC |
16785 | @c $ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile} |
16786 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
16787 | $ gnatprep @r{[}@var{switches}@r{]} @var{infile} @var{outfile} @r{[}@var{deffile}@r{]} | |
88e1739c FW |
16788 | @end smallexample |
16789 | ||
16790 | @noindent | |
16791 | where | |
66bfd481 | 16792 | @table @var |
7e3d710b AC |
16793 | @item switches |
16794 | is an optional sequence of switches as described in the next section. | |
16795 | ||
88e1739c FW |
16796 | @item infile |
16797 | is the full name of the input file, which is an Ada source | |
16798 | file containing preprocessor directives. | |
16799 | ||
16800 | @item outfile | |
16801 | is the full name of the output file, which is an Ada source | |
16802 | in standard Ada form. When used with GNAT, this file name will | |
16803 | normally have an ads or adb suffix. | |
16804 | ||
16805 | @item deffile | |
16806 | is the full name of a text file containing definitions of | |
1a5f40e1 | 16807 | preprocessing symbols to be referenced by the preprocessor. This argument is |
7cd4527e | 16808 | optional, and can be replaced by the use of the @option{-D} switch. |
88e1739c | 16809 | |
88e1739c FW |
16810 | @end table |
16811 | ||
16812 | @node Switches for gnatprep | |
16813 | @section Switches for @code{gnatprep} | |
16814 | ||
7cd4527e AC |
16815 | @table @option |
16816 | @c !sort! | |
88e1739c FW |
16817 | |
16818 | @item ^-b^/BLANK_LINES^ | |
7cd4527e | 16819 | @cindex @option{^-b^/BLANK_LINES^} (@command{gnatprep}) |
88e1739c FW |
16820 | Causes both preprocessor lines and the lines deleted by |
16821 | preprocessing to be replaced by blank lines in the output source file, | |
16822 | preserving line numbers in the output file. | |
16823 | ||
16824 | @item ^-c^/COMMENTS^ | |
7cd4527e | 16825 | @cindex @option{^-c^/COMMENTS^} (@command{gnatprep}) |
88e1739c FW |
16826 | Causes both preprocessor lines and the lines deleted |
16827 | by preprocessing to be retained in the output source as comments marked | |
7cd4527e | 16828 | with the special string @code{"--! "}. This option will result in line numbers |
88e1739c FW |
16829 | being preserved in the output file. |
16830 | ||
32e209e4 CC |
16831 | @item ^-C^/REPLACE_IN_COMMENTS^ |
16832 | @cindex @option{^-C^/REPLACE_IN_COMMENTS^} (@command{gnatprep}) | |
16833 | Causes comments to be scanned. Normally comments are ignored by gnatprep. | |
16834 | If this option is specified, then comments are scanned and any $symbol | |
16835 | substitutions performed as in program text. This is particularly useful | |
8dd07840 | 16836 | when structured comments are used (e.g., when writing programs in the |
32e209e4 CC |
16837 | SPARK dialect of Ada). Note that this switch is not available when |
16838 | doing integrated preprocessing (it would be useless in this context | |
16839 | since comments are ignored by the compiler in any case). | |
16840 | ||
7cd4527e AC |
16841 | @item ^-Dsymbol=value^/ASSOCIATE="symbol=value"^ |
16842 | @cindex @option{^-D^/ASSOCIATE^} (@command{gnatprep}) | |
1a5f40e1 VC |
16843 | Defines a new preprocessing symbol, associated with value. If no value is given |
16844 | on the command line, then symbol is considered to be @code{True}. This switch | |
88e1739c FW |
16845 | can be used in place of a definition file. |
16846 | ||
16847 | @ifset vms | |
7cd4527e AC |
16848 | @item /REMOVE |
16849 | @cindex @option{/REMOVE} (@command{gnatprep}) | |
88e1739c FW |
16850 | This is the default setting which causes lines deleted by preprocessing |
16851 | to be entirely removed from the output file. | |
16852 | @end ifset | |
16853 | ||
16854 | @item ^-r^/REFERENCE^ | |
7cd4527e | 16855 | @cindex @option{^-r^/REFERENCE^} (@command{gnatprep}) |
88e1739c FW |
16856 | Causes a @code{Source_Reference} pragma to be generated that |
16857 | references the original input file, so that error messages will use | |
16858 | the file name of this original file. The use of this switch implies | |
16859 | that preprocessor lines are not to be removed from the file, so its | |
7cd4527e AC |
16860 | use will force @option{^-b^/BLANK_LINES^} mode if |
16861 | @option{^-c^/COMMENTS^} | |
88e1739c FW |
16862 | has not been specified explicitly. |
16863 | ||
16864 | Note that if the file to be preprocessed contains multiple units, then | |
16865 | it will be necessary to @code{gnatchop} the output file from | |
16866 | @code{gnatprep}. If a @code{Source_Reference} pragma is present | |
16867 | in the preprocessed file, it will be respected by | |
16868 | @code{gnatchop ^-r^/REFERENCE^} | |
16869 | so that the final chopped files will correctly refer to the original | |
16870 | input source file for @code{gnatprep}. | |
16871 | ||
16872 | @item ^-s^/SYMBOLS^ | |
7cd4527e | 16873 | @cindex @option{^-s^/SYMBOLS^} (@command{gnatprep}) |
88e1739c FW |
16874 | Causes a sorted list of symbol names and values to be |
16875 | listed on the standard output file. | |
16876 | ||
16877 | @item ^-u^/UNDEFINED^ | |
7cd4527e | 16878 | @cindex @option{^-u^/UNDEFINED^} (@command{gnatprep}) |
88e1739c FW |
16879 | Causes undefined symbols to be treated as having the value FALSE in the context |
16880 | of a preprocessor test. In the absence of this option, an undefined symbol in | |
16881 | a @code{#if} or @code{#elsif} test will be treated as an error. | |
16882 | ||
16883 | @end table | |
16884 | ||
16885 | @ifclear vms | |
16886 | @noindent | |
7cd4527e | 16887 | Note: if neither @option{-b} nor @option{-c} is present, |
88e1739c FW |
16888 | then preprocessor lines and |
16889 | deleted lines are completely removed from the output, unless -r is | |
16890 | specified, in which case -b is assumed. | |
16891 | @end ifclear | |
16892 | ||
16893 | @node Form of Definitions File | |
16894 | @section Form of Definitions File | |
16895 | ||
16896 | @noindent | |
16897 | The definitions file contains lines of the form | |
16898 | ||
16899 | @smallexample | |
16900 | symbol := value | |
16901 | @end smallexample | |
16902 | ||
16903 | @noindent | |
1a5f40e1 | 16904 | where symbol is a preprocessing symbol, and value is one of the following: |
88e1739c FW |
16905 | |
16906 | @itemize @bullet | |
16907 | @item | |
16908 | Empty, corresponding to a null substitution | |
16909 | @item | |
16910 | A string literal using normal Ada syntax | |
16911 | @item | |
16912 | Any sequence of characters from the set | |
16913 | (letters, digits, period, underline). | |
16914 | @end itemize | |
16915 | ||
16916 | @noindent | |
16917 | Comment lines may also appear in the definitions file, starting with | |
16918 | the usual @code{--}, | |
16919 | and comments may be added to the definitions lines. | |
16920 | ||
16921 | @node Form of Input Text for gnatprep | |
16922 | @section Form of Input Text for @code{gnatprep} | |
16923 | ||
16924 | @noindent | |
16925 | The input text may contain preprocessor conditional inclusion lines, | |
16926 | as well as general symbol substitution sequences. | |
16927 | ||
16928 | The preprocessor conditional inclusion commands have the form | |
16929 | ||
16930 | @smallexample | |
16931 | @group | |
16932 | @cartouche | |
66bfd481 | 16933 | #if @i{expression} @r{[}then@r{]} |
88e1739c | 16934 | lines |
66bfd481 | 16935 | #elsif @i{expression} @r{[}then@r{]} |
88e1739c | 16936 | lines |
66bfd481 | 16937 | #elsif @i{expression} @r{[}then@r{]} |
88e1739c | 16938 | lines |
d488f6ea | 16939 | @dots{} |
88e1739c FW |
16940 | #else |
16941 | lines | |
16942 | #end if; | |
16943 | @end cartouche | |
16944 | @end group | |
16945 | @end smallexample | |
16946 | ||
16947 | @noindent | |
16948 | In this example, @i{expression} is defined by the following grammar: | |
16949 | @smallexample | |
16950 | @i{expression} ::= <symbol> | |
16951 | @i{expression} ::= <symbol> = "<value>" | |
16952 | @i{expression} ::= <symbol> = <symbol> | |
5c211bfd AC |
16953 | @i{expression} ::= <symbol> = <integer> |
16954 | @i{expression} ::= <symbol> > <integer> | |
16955 | @i{expression} ::= <symbol> >= <integer> | |
16956 | @i{expression} ::= <symbol> < <integer> | |
16957 | @i{expression} ::= <symbol> <= <integer> | |
88e1739c FW |
16958 | @i{expression} ::= <symbol> 'Defined |
16959 | @i{expression} ::= not @i{expression} | |
16960 | @i{expression} ::= @i{expression} and @i{expression} | |
16961 | @i{expression} ::= @i{expression} or @i{expression} | |
16962 | @i{expression} ::= @i{expression} and then @i{expression} | |
16963 | @i{expression} ::= @i{expression} or else @i{expression} | |
16964 | @i{expression} ::= ( @i{expression} ) | |
16965 | @end smallexample | |
16966 | ||
3fdd06e1 VC |
16967 | The following restriction exists: it is not allowed to have "and" or "or" |
16968 | following "not" in the same expression without parentheses. For example, this | |
16969 | is not allowed: | |
16970 | ||
16971 | @smallexample | |
16972 | not X or Y | |
16973 | @end smallexample | |
16974 | ||
16975 | This should be one of the following: | |
16976 | ||
16977 | @smallexample | |
16978 | (not X) or Y | |
16979 | not (X or Y) | |
16980 | @end smallexample | |
16981 | ||
88e1739c FW |
16982 | @noindent |
16983 | For the first test (@i{expression} ::= <symbol>) the symbol must have | |
16984 | either the value true or false, that is to say the right-hand of the | |
16985 | symbol definition must be one of the (case-insensitive) literals | |
16986 | @code{True} or @code{False}. If the value is true, then the | |
16987 | corresponding lines are included, and if the value is false, they are | |
16988 | excluded. | |
16989 | ||
5c211bfd AC |
16990 | When comparing a symbol to an integer, the integer is any non negative |
16991 | literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or | |
16992 | 2#11#. The symbol value must also be a non negative integer. Integer values | |
16993 | in the range 0 .. 2**31-1 are supported. | |
16994 | ||
88e1739c | 16995 | The test (@i{expression} ::= <symbol> @code{'Defined}) is true only if |
7cd4527e | 16996 | the symbol has been defined in the definition file or by a @option{-D} |
88e1739c FW |
16997 | switch on the command line. Otherwise, the test is false. |
16998 | ||
16999 | The equality tests are case insensitive, as are all the preprocessor lines. | |
17000 | ||
17001 | If the symbol referenced is not defined in the symbol definitions file, | |
7cd4527e | 17002 | then the effect depends on whether or not switch @option{-u} |
88e1739c FW |
17003 | is specified. If so, then the symbol is treated as if it had the value |
17004 | false and the test fails. If this switch is not specified, then | |
17005 | it is an error to reference an undefined symbol. It is also an error to | |
17006 | reference a symbol that is defined with a value other than @code{True} | |
17007 | or @code{False}. | |
17008 | ||
e08b38f5 VC |
17009 | The use of the @code{not} operator inverts the sense of this logical test. |
17010 | The @code{not} operator cannot be combined with the @code{or} or @code{and} | |
17011 | operators, without parentheses. For example, "if not X or Y then" is not | |
17012 | allowed, but "if (not X) or Y then" and "if not (X or Y) then" are. | |
17013 | ||
88e1739c FW |
17014 | The @code{then} keyword is optional as shown |
17015 | ||
17016 | The @code{#} must be the first non-blank character on a line, but | |
17017 | otherwise the format is free form. Spaces or tabs may appear between | |
17018 | the @code{#} and the keyword. The keywords and the symbols are case | |
17019 | insensitive as in normal Ada code. Comments may be used on a | |
17020 | preprocessor line, but other than that, no other tokens may appear on a | |
17021 | preprocessor line. Any number of @code{elsif} clauses can be present, | |
17022 | including none at all. The @code{else} is optional, as in Ada. | |
17023 | ||
17024 | The @code{#} marking the start of a preprocessor line must be the first | |
8dd07840 | 17025 | non-blank character on the line, i.e., it must be preceded only by |
88e1739c FW |
17026 | spaces or horizontal tabs. |
17027 | ||
17028 | Symbol substitution outside of preprocessor lines is obtained by using | |
17029 | the sequence | |
17030 | ||
17031 | @smallexample | |
17032 | $symbol | |
17033 | @end smallexample | |
17034 | ||
17035 | @noindent | |
17036 | anywhere within a source line, except in a comment or within a | |
17037 | string literal. The identifier | |
17038 | following the @code{$} must match one of the symbols defined in the symbol | |
17039 | definition file, and the result is to substitute the value of the | |
17040 | symbol in place of @code{$symbol} in the output file. | |
17041 | ||
17042 | Note that although the substitution of strings within a string literal | |
17043 | is not possible, it is possible to have a symbol whose defined value is | |
17044 | a string literal. So instead of setting XYZ to @code{hello} and writing: | |
17045 | ||
17046 | @smallexample | |
17047 | Header : String := "$XYZ"; | |
17048 | @end smallexample | |
17049 | ||
17050 | @noindent | |
17051 | you should set XYZ to @code{"hello"} and write: | |
17052 | ||
17053 | @smallexample | |
17054 | Header : String := $XYZ; | |
17055 | @end smallexample | |
17056 | ||
17057 | @noindent | |
17058 | and then the substitution will occur as desired. | |
17059 | ||
88e1739c FW |
17060 | @node The GNAT Library Browser gnatls |
17061 | @chapter The GNAT Library Browser @code{gnatls} | |
17062 | @findex gnatls | |
17063 | @cindex Library browser | |
17064 | ||
17065 | @noindent | |
17066 | @code{gnatls} is a tool that outputs information about compiled | |
17067 | units. It gives the relationship between objects, unit names and source | |
17068 | files. It can also be used to check the source dependencies of a unit | |
17069 | as well as various characteristics. | |
17070 | ||
e08b38f5 VC |
17071 | Note: to invoke @code{gnatls} with a project file, use the @code{gnat} |
17072 | driver (see @ref{The GNAT Driver and Project Files}). | |
17073 | ||
88e1739c FW |
17074 | @menu |
17075 | * Running gnatls:: | |
17076 | * Switches for gnatls:: | |
17077 | * Examples of gnatls Usage:: | |
17078 | @end menu | |
17079 | ||
17080 | @node Running gnatls | |
17081 | @section Running @code{gnatls} | |
17082 | ||
17083 | @noindent | |
17084 | The @code{gnatls} command has the form | |
17085 | ||
17086 | @smallexample | |
17087 | $ gnatls switches @var{object_or_ali_file} | |
17088 | @end smallexample | |
17089 | ||
17090 | @noindent | |
17091 | The main argument is the list of object or @file{ali} files | |
17092 | (@pxref{The Ada Library Information Files}) | |
17093 | for which information is requested. | |
17094 | ||
17095 | In normal mode, without additional option, @code{gnatls} produces a | |
17096 | four-column listing. Each line represents information for a specific | |
17097 | object. The first column gives the full path of the object, the second | |
17098 | column gives the name of the principal unit in this object, the third | |
17099 | column gives the status of the source and the fourth column gives the | |
17100 | full path of the source representing this unit. | |
17101 | Here is a simple example of use: | |
17102 | ||
17103 | @smallexample | |
17104 | $ gnatls *.o | |
17105 | ^./^[]^demo1.o demo1 DIF demo1.adb | |
17106 | ^./^[]^demo2.o demo2 OK demo2.adb | |
17107 | ^./^[]^hello.o h1 OK hello.adb | |
17108 | ^./^[]^instr-child.o instr.child MOK instr-child.adb | |
17109 | ^./^[]^instr.o instr OK instr.adb | |
17110 | ^./^[]^tef.o tef DIF tef.adb | |
17111 | ^./^[]^text_io_example.o text_io_example OK text_io_example.adb | |
17112 | ^./^[]^tgef.o tgef DIF tgef.adb | |
17113 | @end smallexample | |
17114 | ||
17115 | @noindent | |
17116 | The first line can be interpreted as follows: the main unit which is | |
17117 | contained in | |
17118 | object file @file{demo1.o} is demo1, whose main source is in | |
17119 | @file{demo1.adb}. Furthermore, the version of the source used for the | |
17120 | compilation of demo1 has been modified (DIF). Each source file has a status | |
17121 | qualifier which can be: | |
17122 | ||
17123 | @table @code | |
17124 | @item OK (unchanged) | |
17125 | The version of the source file used for the compilation of the | |
17126 | specified unit corresponds exactly to the actual source file. | |
17127 | ||
17128 | @item MOK (slightly modified) | |
17129 | The version of the source file used for the compilation of the | |
17130 | specified unit differs from the actual source file but not enough to | |
17131 | require recompilation. If you use gnatmake with the qualifier | |
7cd4527e | 17132 | @option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}, a file marked |
88e1739c FW |
17133 | MOK will not be recompiled. |
17134 | ||
17135 | @item DIF (modified) | |
17136 | No version of the source found on the path corresponds to the source | |
17137 | used to build this object. | |
17138 | ||
17139 | @item ??? (file not found) | |
17140 | No source file was found for this unit. | |
17141 | ||
17142 | @item HID (hidden, unchanged version not first on PATH) | |
17143 | The version of the source that corresponds exactly to the source used | |
17144 | for compilation has been found on the path but it is hidden by another | |
17145 | version of the same source that has been modified. | |
17146 | ||
17147 | @end table | |
17148 | ||
17149 | @node Switches for gnatls | |
17150 | @section Switches for @code{gnatls} | |
17151 | ||
17152 | @noindent | |
17153 | @code{gnatls} recognizes the following switches: | |
17154 | ||
7cd4527e AC |
17155 | @table @option |
17156 | @c !sort! | |
54df6fd9 VC |
17157 | @cindex @option{--version} @command{gnatls} |
17158 | Display Copyright and version, then exit disregarding all other options. | |
17159 | ||
17160 | @item --help | |
17161 | @cindex @option{--help} @command{gnatls} | |
17162 | If @option{--version} was not used, display usage, then exit disregarding | |
17163 | all other options. | |
17164 | ||
88e1739c | 17165 | @item ^-a^/ALL_UNITS^ |
7cd4527e | 17166 | @cindex @option{^-a^/ALL_UNITS^} (@code{gnatls}) |
88e1739c | 17167 | Consider all units, including those of the predefined Ada library. |
7cd4527e | 17168 | Especially useful with @option{^-d^/DEPENDENCIES^}. |
88e1739c FW |
17169 | |
17170 | @item ^-d^/DEPENDENCIES^ | |
7cd4527e | 17171 | @cindex @option{^-d^/DEPENDENCIES^} (@code{gnatls}) |
88e1739c FW |
17172 | List sources from which specified units depend on. |
17173 | ||
17174 | @item ^-h^/OUTPUT=OPTIONS^ | |
7cd4527e | 17175 | @cindex @option{^-h^/OUTPUT=OPTIONS^} (@code{gnatls}) |
88e1739c FW |
17176 | Output the list of options. |
17177 | ||
17178 | @item ^-o^/OUTPUT=OBJECTS^ | |
7cd4527e | 17179 | @cindex @option{^-o^/OUTPUT=OBJECTS^} (@code{gnatls}) |
88e1739c FW |
17180 | Only output information about object files. |
17181 | ||
17182 | @item ^-s^/OUTPUT=SOURCES^ | |
7cd4527e | 17183 | @cindex @option{^-s^/OUTPUT=SOURCES^} (@code{gnatls}) |
88e1739c FW |
17184 | Only output information about source files. |
17185 | ||
17186 | @item ^-u^/OUTPUT=UNITS^ | |
7cd4527e | 17187 | @cindex @option{^-u^/OUTPUT=UNITS^} (@code{gnatls}) |
88e1739c FW |
17188 | Only output information about compilation units. |
17189 | ||
0da2c8ac AC |
17190 | @item ^-files^/FILES^=@var{file} |
17191 | @cindex @option{^-files^/FILES^} (@code{gnatls}) | |
17192 | Take as arguments the files listed in text file @var{file}. | |
17193 | Text file @var{file} may contain empty lines that are ignored. | |
4d0e4612 | 17194 | Each nonempty line should contain the name of an existing file. |
0da2c8ac AC |
17195 | Several such switches may be specified simultaneously. |
17196 | ||
88e1739c FW |
17197 | @item ^-aO^/OBJECT_SEARCH=^@var{dir} |
17198 | @itemx ^-aI^/SOURCE_SEARCH=^@var{dir} | |
17199 | @itemx ^-I^/SEARCH=^@var{dir} | |
17200 | @itemx ^-I-^/NOCURRENT_DIRECTORY^ | |
17201 | @itemx -nostdinc | |
7cd4527e AC |
17202 | @cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatls}) |
17203 | @cindex @option{^-aI^/SOURCE_SEARCH^} (@code{gnatls}) | |
17204 | @cindex @option{^-I^/SEARCH^} (@code{gnatls}) | |
17205 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatls}) | |
984a64bc AC |
17206 | Source path manipulation. Same meaning as the equivalent @command{gnatmake} |
17207 | flags (@pxref{Switches for gnatmake}). | |
88e1739c | 17208 | |
b5bdffcc AC |
17209 | @item ^-aP^/ADD_PROJECT_SEARCH_DIR=^@var{dir} |
17210 | @cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (@code{gnatls}) | |
17211 | Add @var{dir} at the beginning of the project search dir. | |
17212 | ||
88e1739c | 17213 | @item --RTS=@var{rts-path} |
7cd4527e | 17214 | @cindex @option{--RTS} (@code{gnatls}) |
88e1739c | 17215 | Specifies the default location of the runtime library. Same meaning as the |
984a64bc | 17216 | equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). |
88e1739c FW |
17217 | |
17218 | @item ^-v^/OUTPUT=VERBOSE^ | |
7cd4527e | 17219 | @cindex @option{^-v^/OUTPUT=VERBOSE^} (@code{gnatls}) |
a5b62485 | 17220 | Verbose mode. Output the complete source, object and project paths. Do not use |
88e1739c FW |
17221 | the default column layout but instead use long format giving as much as |
17222 | information possible on each requested units, including special | |
17223 | characteristics such as: | |
17224 | ||
17225 | @table @code | |
17226 | @item Preelaborable | |
e08b38f5 | 17227 | The unit is preelaborable in the Ada sense. |
88e1739c FW |
17228 | |
17229 | @item No_Elab_Code | |
17230 | No elaboration code has been produced by the compiler for this unit. | |
17231 | ||
17232 | @item Pure | |
e08b38f5 | 17233 | The unit is pure in the Ada sense. |
88e1739c FW |
17234 | |
17235 | @item Elaborate_Body | |
17236 | The unit contains a pragma Elaborate_Body. | |
17237 | ||
17238 | @item Remote_Types | |
17239 | The unit contains a pragma Remote_Types. | |
17240 | ||
17241 | @item Shared_Passive | |
17242 | The unit contains a pragma Shared_Passive. | |
17243 | ||
17244 | @item Predefined | |
17245 | This unit is part of the predefined environment and cannot be modified | |
17246 | by the user. | |
17247 | ||
17248 | @item Remote_Call_Interface | |
17249 | The unit contains a pragma Remote_Call_Interface. | |
17250 | ||
17251 | @end table | |
17252 | ||
17253 | @end table | |
17254 | ||
17255 | @node Examples of gnatls Usage | |
17256 | @section Example of @code{gnatls} Usage | |
17257 | @ifclear vms | |
17258 | ||
17259 | @noindent | |
17260 | Example of using the verbose switch. Note how the source and | |
f1093866 | 17261 | object paths are affected by the -I switch. |
88e1739c FW |
17262 | |
17263 | @smallexample | |
17264 | $ gnatls -v -I.. demo1.o | |
17265 | ||
a5b62485 AC |
17266 | GNATLS 5.03w (20041123-34) |
17267 | Copyright 1997-2004 Free Software Foundation, Inc. | |
88e1739c FW |
17268 | |
17269 | Source Search Path: | |
17270 | <Current_Directory> | |
17271 | ../ | |
17272 | /home/comar/local/adainclude/ | |
17273 | ||
17274 | Object Search Path: | |
17275 | <Current_Directory> | |
17276 | ../ | |
0f1b0456 | 17277 | /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ |
88e1739c | 17278 | |
a5b62485 AC |
17279 | Project Search Path: |
17280 | <Current_Directory> | |
17281 | /home/comar/local/lib/gnat/ | |
17282 | ||
88e1739c FW |
17283 | ./demo1.o |
17284 | Unit => | |
17285 | Name => demo1 | |
17286 | Kind => subprogram body | |
17287 | Flags => No_Elab_Code | |
17288 | Source => demo1.adb modified | |
17289 | @end smallexample | |
17290 | ||
17291 | @noindent | |
17292 | The following is an example of use of the dependency list. | |
17293 | Note the use of the -s switch | |
17294 | which gives a straight list of source files. This can be useful for | |
17295 | building specialized scripts. | |
17296 | ||
17297 | @smallexample | |
17298 | $ gnatls -d demo2.o | |
17299 | ./demo2.o demo2 OK demo2.adb | |
17300 | OK gen_list.ads | |
17301 | OK gen_list.adb | |
17302 | OK instr.ads | |
17303 | OK instr-child.ads | |
17304 | ||
17305 | $ gnatls -d -s -a demo1.o | |
17306 | demo1.adb | |
17307 | /home/comar/local/adainclude/ada.ads | |
17308 | /home/comar/local/adainclude/a-finali.ads | |
17309 | /home/comar/local/adainclude/a-filico.ads | |
17310 | /home/comar/local/adainclude/a-stream.ads | |
17311 | /home/comar/local/adainclude/a-tags.ads | |
17312 | gen_list.ads | |
17313 | gen_list.adb | |
17314 | /home/comar/local/adainclude/gnat.ads | |
17315 | /home/comar/local/adainclude/g-io.ads | |
17316 | instr.ads | |
17317 | /home/comar/local/adainclude/system.ads | |
17318 | /home/comar/local/adainclude/s-exctab.ads | |
17319 | /home/comar/local/adainclude/s-finimp.ads | |
17320 | /home/comar/local/adainclude/s-finroo.ads | |
17321 | /home/comar/local/adainclude/s-secsta.ads | |
17322 | /home/comar/local/adainclude/s-stalib.ads | |
17323 | /home/comar/local/adainclude/s-stoele.ads | |
17324 | /home/comar/local/adainclude/s-stratt.ads | |
17325 | /home/comar/local/adainclude/s-tasoli.ads | |
17326 | /home/comar/local/adainclude/s-unstyp.ads | |
17327 | /home/comar/local/adainclude/unchconv.ads | |
17328 | @end smallexample | |
17329 | @end ifclear | |
17330 | ||
17331 | @ifset vms | |
17332 | @smallexample | |
17333 | GNAT LIST /DEPENDENCIES /OUTPUT=SOURCES /ALL_UNITS DEMO1.ADB | |
17334 | ||
17335 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]ada.ads | |
17336 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-finali.ads | |
17337 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-filico.ads | |
17338 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-stream.ads | |
17339 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-tags.ads | |
17340 | demo1.adb | |
17341 | gen_list.ads | |
17342 | gen_list.adb | |
17343 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]gnat.ads | |
17344 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]g-io.ads | |
17345 | instr.ads | |
17346 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]system.ads | |
17347 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-exctab.ads | |
17348 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finimp.ads | |
17349 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finroo.ads | |
17350 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-secsta.ads | |
17351 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stalib.ads | |
17352 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stoele.ads | |
17353 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stratt.ads | |
17354 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-tasoli.ads | |
17355 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-unstyp.ads | |
17356 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]unchconv.ads | |
17357 | @end smallexample | |
17358 | @end ifset | |
17359 | ||
c2658843 AC |
17360 | @node Cleaning Up with gnatclean |
17361 | @chapter Cleaning Up with @code{gnatclean} | |
7cd4527e AC |
17362 | @findex gnatclean |
17363 | @cindex Cleaning tool | |
17364 | ||
17365 | @noindent | |
17366 | @code{gnatclean} is a tool that allows the deletion of files produced by the | |
17367 | compiler, binder and linker, including ALI files, object files, tree files, | |
17368 | expanded source files, library files, interface copy source files, binder | |
17369 | generated files and executable files. | |
17370 | ||
17371 | @menu | |
17372 | * Running gnatclean:: | |
17373 | * Switches for gnatclean:: | |
0453ca3d | 17374 | @c * Examples of gnatclean Usage:: |
7cd4527e AC |
17375 | @end menu |
17376 | ||
17377 | @node Running gnatclean | |
17378 | @section Running @code{gnatclean} | |
17379 | ||
17380 | @noindent | |
17381 | The @code{gnatclean} command has the form: | |
17382 | ||
17383 | @smallexample | |
17384 | $ gnatclean switches @var{names} | |
17385 | @end smallexample | |
17386 | ||
17387 | @noindent | |
17388 | @var{names} is a list of source file names. Suffixes @code{.^ads^ADS^} and | |
17389 | @code{^adb^ADB^} may be omitted. If a project file is specified using switch | |
17390 | @code{^-P^/PROJECT_FILE=^}, then @var{names} may be completely omitted. | |
17391 | ||
17392 | @noindent | |
17393 | In normal mode, @code{gnatclean} delete the files produced by the compiler and, | |
17394 | if switch @code{^-c^/COMPILER_FILES_ONLY^} is not specified, by the binder and | |
17395 | the linker. In informative-only mode, specified by switch | |
17396 | @code{^-n^/NODELETE^}, the list of files that would have been deleted in | |
17397 | normal mode is listed, but no file is actually deleted. | |
17398 | ||
17399 | @node Switches for gnatclean | |
17400 | @section Switches for @code{gnatclean} | |
17401 | ||
17402 | @noindent | |
17403 | @code{gnatclean} recognizes the following switches: | |
17404 | ||
17405 | @table @option | |
17406 | @c !sort! | |
54df6fd9 VC |
17407 | @cindex @option{--version} @command{gnatclean} |
17408 | Display Copyright and version, then exit disregarding all other options. | |
17409 | ||
17410 | @item --help | |
17411 | @cindex @option{--help} @command{gnatclean} | |
17412 | If @option{--version} was not used, display usage, then exit disregarding | |
17413 | all other options. | |
17414 | ||
eeb41f01 VC |
17415 | @item ^--subdirs^/SUBDIRS^=subdir |
17416 | Actual object directory of each project file is the subdirectory subdir of the | |
308e6f3a | 17417 | object directory specified or defaulted in the project file. |
eeb41f01 VC |
17418 | |
17419 | @item ^--unchecked-shared-lib-imports^/UNCHECKED_SHARED_LIB_IMPORTS^ | |
17420 | By default, shared library projects are not allowed to import static library | |
17421 | projects. When this switch is used on the command line, this restriction is | |
17422 | relaxed. | |
17423 | ||
7cd4527e AC |
17424 | @item ^-c^/COMPILER_FILES_ONLY^ |
17425 | @cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean}) | |
17426 | Only attempt to delete the files produced by the compiler, not those produced | |
17427 | by the binder or the linker. The files that are not to be deleted are library | |
17428 | files, interface copy files, binder generated files and executable files. | |
17429 | ||
17430 | @item ^-D ^/DIRECTORY_OBJECTS=^@var{dir} | |
17431 | @cindex @option{^-D^/DIRECTORY_OBJECTS^} (@code{gnatclean}) | |
17432 | Indicate that ALI and object files should normally be found in directory | |
17433 | @var{dir}. | |
17434 | ||
17435 | @item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^ | |
17436 | @cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@code{gnatclean}) | |
17437 | When using project files, if some errors or warnings are detected during | |
17438 | parsing and verbose mode is not in effect (no use of switch | |
17439 | ^-v^/VERBOSE^), then error lines start with the full path name of the project | |
17440 | file, rather than its simple file name. | |
17441 | ||
17442 | @item ^-h^/HELP^ | |
17443 | @cindex @option{^-h^/HELP^} (@code{gnatclean}) | |
17444 | Output a message explaining the usage of @code{^gnatclean^gnatclean^}. | |
17445 | ||
17446 | @item ^-n^/NODELETE^ | |
17447 | @cindex @option{^-n^/NODELETE^} (@code{gnatclean}) | |
17448 | Informative-only mode. Do not delete any files. Output the list of the files | |
17449 | that would have been deleted if this switch was not specified. | |
17450 | ||
17451 | @item ^-P^/PROJECT_FILE=^@var{project} | |
17452 | @cindex @option{^-P^/PROJECT_FILE^} (@code{gnatclean}) | |
17453 | Use project file @var{project}. Only one such switch can be used. | |
17454 | When cleaning a project file, the files produced by the compilation of the | |
17455 | immediate sources or inherited sources of the project files are to be | |
17456 | deleted. This is not depending on the presence or not of executable names | |
17457 | on the command line. | |
17458 | ||
17459 | @item ^-q^/QUIET^ | |
17460 | @cindex @option{^-q^/QUIET^} (@code{gnatclean}) | |
7e3d710b | 17461 | Quiet output. If there are no errors, do not output anything, except in |
7cd4527e AC |
17462 | verbose mode (switch ^-v^/VERBOSE^) or in informative-only mode |
17463 | (switch ^-n^/NODELETE^). | |
17464 | ||
17465 | @item ^-r^/RECURSIVE^ | |
17466 | @cindex @option{^-r^/RECURSIVE^} (@code{gnatclean}) | |
17467 | When a project file is specified (using switch ^-P^/PROJECT_FILE=^), | |
17468 | clean all imported and extended project files, recursively. If this switch | |
17469 | is not specified, only the files related to the main project file are to be | |
17470 | deleted. This switch has no effect if no project file is specified. | |
17471 | ||
17472 | @item ^-v^/VERBOSE^ | |
17473 | @cindex @option{^-v^/VERBOSE^} (@code{gnatclean}) | |
17474 | Verbose mode. | |
17475 | ||
17476 | @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} | |
17477 | @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (@code{gnatclean}) | |
17478 | Indicates the verbosity of the parsing of GNAT project files. | |
a3da92f9 | 17479 | @xref{Switches Related to Project Files}. |
7cd4527e AC |
17480 | |
17481 | @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} | |
17482 | @cindex @option{^-X^/EXTERNAL_REFERENCE^} (@code{gnatclean}) | |
17483 | Indicates that external variable @var{name} has the value @var{value}. | |
17484 | The Project Manager will use this value for occurrences of | |
17485 | @code{external(name)} when parsing the project file. | |
a3da92f9 | 17486 | @xref{Switches Related to Project Files}. |
7cd4527e AC |
17487 | |
17488 | @item ^-aO^/OBJECT_SEARCH=^@var{dir} | |
17489 | @cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatclean}) | |
17490 | When searching for ALI and object files, look in directory | |
17491 | @var{dir}. | |
17492 | ||
17493 | @item ^-I^/SEARCH=^@var{dir} | |
17494 | @cindex @option{^-I^/SEARCH^} (@code{gnatclean}) | |
17495 | Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir}}. | |
17496 | ||
17497 | @item ^-I-^/NOCURRENT_DIRECTORY^ | |
17498 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatclean}) | |
17499 | @cindex Source files, suppressing search | |
17500 | Do not look for ALI or object files in the directory | |
17501 | where @code{gnatclean} was invoked. | |
17502 | ||
17503 | @end table | |
17504 | ||
0453ca3d RD |
17505 | @c @node Examples of gnatclean Usage |
17506 | @c @section Examples of @code{gnatclean} Usage | |
7cd4527e | 17507 | |
88e1739c FW |
17508 | @ifclear vms |
17509 | @node GNAT and Libraries | |
17510 | @chapter GNAT and Libraries | |
9bc856dd | 17511 | @cindex Library, building, installing, using |
88e1739c FW |
17512 | |
17513 | @noindent | |
87b3f81f AC |
17514 | This chapter describes how to build and use libraries with GNAT, and also shows |
17515 | how to recompile the GNAT run-time library. You should be familiar with the | |
984a64bc | 17516 | Project Manager facility (@pxref{GNAT Project Manager}) before reading this |
0ab80019 | 17517 | chapter. |
88e1739c FW |
17518 | |
17519 | @menu | |
9bc856dd AC |
17520 | * Introduction to Libraries in GNAT:: |
17521 | * General Ada Libraries:: | |
17522 | * Stand-alone Ada Libraries:: | |
88e1739c FW |
17523 | * Rebuilding the GNAT Run-Time Library:: |
17524 | @end menu | |
17525 | ||
9bc856dd AC |
17526 | @node Introduction to Libraries in GNAT |
17527 | @section Introduction to Libraries in GNAT | |
88e1739c FW |
17528 | |
17529 | @noindent | |
9bc856dd AC |
17530 | A library is, conceptually, a collection of objects which does not have its |
17531 | own main thread of execution, but rather provides certain services to the | |
17532 | applications that use it. A library can be either statically linked with the | |
17533 | application, in which case its code is directly included in the application, | |
17534 | or, on platforms that support it, be dynamically linked, in which case | |
0ab80019 AC |
17535 | its code is shared by all applications making use of this library. |
17536 | ||
17537 | GNAT supports both types of libraries. | |
87b3f81f AC |
17538 | In the static case, the compiled code can be provided in different ways. The |
17539 | simplest approach is to provide directly the set of objects resulting from | |
17540 | compilation of the library source files. Alternatively, you can group the | |
17541 | objects into an archive using whatever commands are provided by the operating | |
17542 | system. For the latter case, the objects are grouped into a shared library. | |
17543 | ||
17544 | In the GNAT environment, a library has three types of components: | |
88e1739c FW |
17545 | @itemize @bullet |
17546 | @item | |
17547 | Source files. | |
17548 | @item | |
87b3f81f | 17549 | @file{ALI} files. |
984a64bc | 17550 | @xref{The Ada Library Information Files}. |
87b3f81f AC |
17551 | @item |
17552 | Object files, an archive or a shared library. | |
88e1739c FW |
17553 | @end itemize |
17554 | ||
17555 | @noindent | |
87b3f81f AC |
17556 | A GNAT library may expose all its source files, which is useful for |
17557 | documentation purposes. Alternatively, it may expose only the units needed by | |
17558 | an external user to make use of the library. That is to say, the specs | |
984a64bc | 17559 | reflecting the library services along with all the units needed to compile |
87b3f81f AC |
17560 | those specs, which can include generic bodies or any body implementing an |
17561 | inlined routine. In the case of @emph{stand-alone libraries} those exposed | |
984a64bc | 17562 | units are called @emph{interface units} (@pxref{Stand-alone Ada Libraries}). |
9bc856dd | 17563 | |
87b3f81f AC |
17564 | All compilation units comprising an application, including those in a library, |
17565 | need to be elaborated in an order partially defined by Ada's semantics. GNAT | |
17566 | computes the elaboration order from the @file{ALI} files and this is why they | |
03456e44 AC |
17567 | constitute a mandatory part of GNAT libraries. |
17568 | @emph{Stand-alone libraries} are the exception to this rule because a specific | |
17569 | library elaboration routine is produced independently of the application(s) | |
17570 | using the library. | |
9bc856dd AC |
17571 | |
17572 | @node General Ada Libraries | |
17573 | @section General Ada Libraries | |
17574 | ||
17575 | @menu | |
87b3f81f AC |
17576 | * Building a library:: |
17577 | * Installing a library:: | |
17578 | * Using a library:: | |
9bc856dd AC |
17579 | @end menu |
17580 | ||
87b3f81f AC |
17581 | @node Building a library |
17582 | @subsection Building a library | |
88e1739c FW |
17583 | |
17584 | @noindent | |
0ab80019 | 17585 | The easiest way to build a library is to use the Project Manager, |
984a64bc AC |
17586 | which supports a special type of project called a @emph{Library Project} |
17587 | (@pxref{Library Projects}). | |
9bc856dd AC |
17588 | |
17589 | A project is considered a library project, when two project-level attributes | |
17590 | are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to | |
17591 | control different aspects of library configuration, additional optional | |
17592 | project-level attributes can be specified: | |
0ab80019 AC |
17593 | @table @code |
17594 | @item Library_Kind | |
87b3f81f | 17595 | This attribute controls whether the library is to be static or dynamic |
0ab80019 AC |
17596 | |
17597 | @item Library_Version | |
984a64bc | 17598 | This attribute specifies the library version; this value is used |
9bc856dd AC |
17599 | during dynamic linking of shared libraries to determine if the currently |
17600 | installed versions of the binaries are compatible. | |
0ab80019 AC |
17601 | |
17602 | @item Library_Options | |
17603 | @item Library_GCC | |
9bc856dd AC |
17604 | These attributes specify additional low-level options to be used during |
17605 | library generation, and redefine the actual application used to generate | |
17606 | library. | |
0ab80019 | 17607 | @end table |
88e1739c FW |
17608 | |
17609 | @noindent | |
0ab80019 | 17610 | The GNAT Project Manager takes full care of the library maintenance task, |
9bc856dd AC |
17611 | including recompilation of the source files for which objects do not exist |
17612 | or are not up to date, assembly of the library archive, and installation of | |
984a64bc AC |
17613 | the library (i.e., copying associated source, object and @file{ALI} files |
17614 | to the specified location). | |
9bc856dd | 17615 | |
87b3f81f AC |
17616 | Here is a simple library project file: |
17617 | @smallexample @c ada | |
17618 | project My_Lib is | |
17619 | for Source_Dirs use ("src1", "src2"); | |
17620 | for Object_Dir use "obj"; | |
17621 | for Library_Name use "mylib"; | |
17622 | for Library_Dir use "lib"; | |
17623 | for Library_Kind use "dynamic"; | |
17624 | end My_lib; | |
17625 | @end smallexample | |
984a64bc AC |
17626 | |
17627 | @noindent | |
87b3f81f | 17628 | and the compilation command to build and install the library: |
984a64bc | 17629 | |
87b3f81f AC |
17630 | @smallexample @c ada |
17631 | $ gnatmake -Pmy_lib | |
17632 | @end smallexample | |
17633 | ||
984a64bc | 17634 | @noindent |
87b3f81f | 17635 | It is not entirely trivial to perform manually all the steps required to |
0ab80019 | 17636 | produce a library. We recommend that you use the GNAT Project Manager |
9bc856dd AC |
17637 | for this task. In special cases where this is not desired, the necessary |
17638 | steps are discussed below. | |
17639 | ||
88e1739c | 17640 | There are various possibilities for compiling the units that make up the |
984a64bc | 17641 | library: for example with a Makefile (@pxref{Using the GNU make Utility}) or |
87b3f81f | 17642 | with a conventional script. For simple libraries, it is also possible to create |
984a64bc | 17643 | a dummy main program which depends upon all the packages that comprise the |
88e1739c | 17644 | interface of the library. This dummy main program can then be given to |
0ab80019 | 17645 | @command{gnatmake}, which will ensure that all necessary objects are built. |
9bc856dd | 17646 | |
0ab80019 | 17647 | After this task is accomplished, you should follow the standard procedure |
9bc856dd AC |
17648 | of the underlying operating system to produce the static or shared library. |
17649 | ||
0ab80019 | 17650 | Here is an example of such a dummy program: |
7cd4527e | 17651 | @smallexample @c ada |
0ab80019 | 17652 | @group |
7cd4527e AC |
17653 | with My_Lib.Service1; |
17654 | with My_Lib.Service2; | |
17655 | with My_Lib.Service3; | |
17656 | procedure My_Lib_Dummy is | |
17657 | begin | |
17658 | null; | |
17659 | end; | |
0ab80019 | 17660 | @end group |
7cd4527e | 17661 | @end smallexample |
88e1739c | 17662 | |
0ab80019 AC |
17663 | @noindent |
17664 | Here are the generic commands that will build an archive or a shared library. | |
17665 | ||
7cd4527e | 17666 | @smallexample |
88e1739c FW |
17667 | # compiling the library |
17668 | $ gnatmake -c my_lib_dummy.adb | |
17669 | ||
17670 | # we don't need the dummy object itself | |
17671 | $ rm my_lib_dummy.o my_lib_dummy.ali | |
17672 | ||
17673 | # create an archive with the remaining objects | |
17674 | $ ar rc libmy_lib.a *.o | |
17675 | # some systems may require "ranlib" to be run as well | |
17676 | ||
17677 | # or create a shared library | |
17678 | $ gcc -shared -o libmy_lib.so *.o | |
17679 | # some systems may require the code to have been compiled with -fPIC | |
7cd4527e AC |
17680 | |
17681 | # remove the object files that are now in the library | |
17682 | $ rm *.o | |
17683 | ||
17684 | # Make the ALI files read-only so that gnatmake will not try to | |
17685 | # regenerate the objects that are in the library | |
17686 | $ chmod -w *.ali | |
88e1739c FW |
17687 | @end smallexample |
17688 | ||
7cd4527e | 17689 | @noindent |
79f34d07 RW |
17690 | Please note that the library must have a name of the form @file{lib@var{xxx}.a} |
17691 | or @file{lib@var{xxx}.so} (or @file{lib@var{xxx}.dll} on Windows) in order to | |
17692 | be accessed by the directive @option{-l@var{xxx}} at link time. | |
87b3f81f AC |
17693 | |
17694 | @node Installing a library | |
17695 | @subsection Installing a library | |
0453ca3d | 17696 | @cindex @code{ADA_PROJECT_PATH} |
7bccff24 | 17697 | @cindex @code{GPR_PROJECT_PATH} |
87b3f81f AC |
17698 | |
17699 | @noindent | |
984a64bc | 17700 | If you use project files, library installation is part of the library build |
b2cacbfe | 17701 | process (@pxref{Installing a library with project files}). |
87b3f81f AC |
17702 | |
17703 | When project files are not an option, it is also possible, but not recommended, | |
984a64bc | 17704 | to install the library so that the sources needed to use the library are on the |
87b3f81f | 17705 | Ada source path and the ALI files & libraries be on the Ada Object path (see |
984a64bc AC |
17706 | @ref{Search Paths and the Run-Time Library (RTL)}. Alternatively, the system |
17707 | administrator can place general-purpose libraries in the default compiler | |
87b3f81f AC |
17708 | paths, by specifying the libraries' location in the configuration files |
17709 | @file{ada_source_path} and @file{ada_object_path}. These configuration files | |
17710 | must be located in the GNAT installation tree at the same place as the gcc spec | |
17711 | file. The location of the gcc spec file can be determined as follows: | |
88e1739c FW |
17712 | @smallexample |
17713 | $ gcc -v | |
17714 | @end smallexample | |
17715 | ||
17716 | @noindent | |
0ab80019 AC |
17717 | The configuration files mentioned above have a simple format: each line |
17718 | must contain one unique directory name. | |
17719 | Those names are added to the corresponding path | |
88e1739c | 17720 | in their order of appearance in the file. The names can be either absolute |
0ab80019 | 17721 | or relative; in the latter case, they are relative to where theses files |
88e1739c FW |
17722 | are located. |
17723 | ||
0ab80019 | 17724 | The files @file{ada_source_path} and @file{ada_object_path} might not be |
7cd4527e | 17725 | present in a |
88e1739c | 17726 | GNAT installation, in which case, GNAT will look for its run-time library in |
0ab80019 AC |
17727 | the directories @file{adainclude} (for the sources) and @file{adalib} (for the |
17728 | objects and @file{ALI} files). When the files exist, the compiler does not | |
17729 | look in @file{adainclude} and @file{adalib}, and thus the | |
7cd4527e | 17730 | @file{ada_source_path} file |
88e1739c | 17731 | must contain the location for the GNAT run-time sources (which can simply |
7cd4527e AC |
17732 | be @file{adainclude}). In the same way, the @file{ada_object_path} file must |
17733 | contain the location for the GNAT run-time objects (which can simply | |
17734 | be @file{adalib}). | |
88e1739c | 17735 | |
0ab80019 AC |
17736 | You can also specify a new default path to the run-time library at compilation |
17737 | time with the switch @option{--RTS=rts-path}. You can thus choose / change | |
17738 | the run-time library you want your program to be compiled with. This switch is | |
17739 | recognized by @command{gcc}, @command{gnatmake}, @command{gnatbind}, | |
17740 | @command{gnatls}, @command{gnatfind} and @command{gnatxref}. | |
88e1739c | 17741 | |
88e1739c FW |
17742 | It is possible to install a library before or after the standard GNAT |
17743 | library, by reordering the lines in the configuration files. In general, a | |
7cd4527e AC |
17744 | library must be installed before the GNAT library if it redefines |
17745 | any part of it. | |
88e1739c | 17746 | |
87b3f81f AC |
17747 | @node Using a library |
17748 | @subsection Using a library | |
88e1739c | 17749 | |
87b3f81f AC |
17750 | @noindent Once again, the project facility greatly simplifies the use of |
17751 | libraries. In this context, using a library is just a matter of adding a | |
17752 | @code{with} clause in the user project. For instance, to make use of the | |
984a64bc AC |
17753 | library @code{My_Lib} shown in examples in earlier sections, you can |
17754 | write: | |
17755 | ||
17756 | @smallexample @c projectfile | |
87b3f81f AC |
17757 | with "my_lib"; |
17758 | project My_Proj is | |
d488f6ea | 17759 | @dots{} |
87b3f81f AC |
17760 | end My_Proj; |
17761 | @end smallexample | |
9bc856dd | 17762 | |
0ab80019 | 17763 | Even if you have a third-party, non-Ada library, you can still use GNAT's |
984a64bc AC |
17764 | Project Manager facility to provide a wrapper for it. For example, the |
17765 | following project, when @code{with}ed by your main project, will link with the | |
0ab80019 | 17766 | third-party library @file{liba.a}: |
9bc856dd AC |
17767 | |
17768 | @smallexample @c projectfile | |
17769 | @group | |
17770 | project Liba is | |
0f1b0456 | 17771 | for Externally_Built use "true"; |
e08b38f5 | 17772 | for Source_Files use (); |
9bc856dd AC |
17773 | for Library_Dir use "lib"; |
17774 | for Library_Name use "a"; | |
17775 | for Library_Kind use "static"; | |
17776 | end Liba; | |
17777 | @end group | |
17778 | @end smallexample | |
0f1b0456 | 17779 | This is an alternative to the use of @code{pragma Linker_Options}. It is |
7e3d710b | 17780 | especially interesting in the context of systems with several interdependent |
0f1b0456 | 17781 | static libraries where finding a proper linker order is not easy and best be |
7e3d710b | 17782 | left to the tools having visibility over project dependence information. |
9bc856dd AC |
17783 | |
17784 | @noindent | |
17785 | In order to use an Ada library manually, you need to make sure that this | |
88e1739c | 17786 | library is on both your source and object path |
984a64bc | 17787 | (see @ref{Search Paths and the Run-Time Library (RTL)} |
0ab80019 AC |
17788 | and @ref{Search Paths for gnatbind}). Furthermore, when the objects are grouped |
17789 | in an archive or a shared library, you need to specify the desired | |
9bc856dd AC |
17790 | library at link time. |
17791 | ||
0ab80019 | 17792 | For example, you can use the library @file{mylib} installed in |
7cd4527e | 17793 | @file{/dir/my_lib_src} and @file{/dir/my_lib_obj} with the following commands: |
88e1739c FW |
17794 | |
17795 | @smallexample | |
17796 | $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \ | |
17797 | -largs -lmy_lib | |
17798 | @end smallexample | |
17799 | ||
17800 | @noindent | |
0ab80019 | 17801 | This can be expressed more simply: |
88e1739c FW |
17802 | @smallexample |
17803 | $ gnatmake my_appl | |
17804 | @end smallexample | |
0ab80019 | 17805 | @noindent |
88e1739c FW |
17806 | when the following conditions are met: |
17807 | @itemize @bullet | |
17808 | @item | |
7cd4527e | 17809 | @file{/dir/my_lib_src} has been added by the user to the environment |
443b3472 | 17810 | variable @env{ADA_INCLUDE_PATH}, or by the administrator to the file |
7cd4527e | 17811 | @file{ada_source_path} |
88e1739c | 17812 | @item |
7cd4527e | 17813 | @file{/dir/my_lib_obj} has been added by the user to the environment |
443b3472 | 17814 | variable @env{ADA_OBJECTS_PATH}, or by the administrator to the file |
7cd4527e | 17815 | @file{ada_object_path} |
88e1739c | 17816 | @item |
0ab80019 | 17817 | a pragma @code{Linker_Options} has been added to one of the sources. |
9bc856dd AC |
17818 | For example: |
17819 | ||
17820 | @smallexample @c ada | |
17821 | pragma Linker_Options ("-lmy_lib"); | |
17822 | @end smallexample | |
88e1739c | 17823 | @end itemize |
88e1739c | 17824 | |
9bc856dd AC |
17825 | @node Stand-alone Ada Libraries |
17826 | @section Stand-alone Ada Libraries | |
17827 | @cindex Stand-alone library, building, using | |
88e1739c | 17828 | |
9bc856dd | 17829 | @menu |
0ab80019 AC |
17830 | * Introduction to Stand-alone Libraries:: |
17831 | * Building a Stand-alone Library:: | |
17832 | * Creating a Stand-alone Library to be used in a non-Ada context:: | |
17833 | * Restrictions in Stand-alone Libraries:: | |
9bc856dd | 17834 | @end menu |
88e1739c | 17835 | |
0ab80019 AC |
17836 | @node Introduction to Stand-alone Libraries |
17837 | @subsection Introduction to Stand-alone Libraries | |
88e1739c | 17838 | |
9bc856dd | 17839 | @noindent |
984a64bc AC |
17840 | A Stand-alone Library (abbreviated ``SAL'') is a library that contains the |
17841 | necessary code to | |
0ab80019 AC |
17842 | elaborate the Ada units that are included in the library. In contrast with |
17843 | an ordinary library, which consists of all sources, objects and @file{ALI} | |
17844 | files of the | |
17845 | library, a SAL may specify a restricted subset of compilation units | |
17846 | to serve as a library interface. In this case, the fully | |
17847 | self-sufficient set of files will normally consist of an objects | |
17848 | archive, the sources of interface units' specs, and the @file{ALI} | |
17849 | files of interface units. | |
17850 | If an interface spec contains a generic unit or an inlined subprogram, | |
17851 | the body's | |
9bc856dd | 17852 | source must also be provided; if the units that must be provided in the source |
0ab80019 AC |
17853 | form depend on other units, the source and @file{ALI} files of those must |
17854 | also be provided. | |
88e1739c | 17855 | |
0ab80019 AC |
17856 | The main purpose of a SAL is to minimize the recompilation overhead of client |
17857 | applications when a new version of the library is installed. Specifically, | |
9bc856dd | 17858 | if the interface sources have not changed, client applications do not need to |
0ab80019 AC |
17859 | be recompiled. If, furthermore, a SAL is provided in the shared form and its |
17860 | version, controlled by @code{Library_Version} attribute, is not changed, | |
17861 | then the clients do not need to be relinked. | |
88e1739c | 17862 | |
0ab80019 AC |
17863 | SALs also allow the library providers to minimize the amount of library source |
17864 | text exposed to the clients. Such ``information hiding'' might be useful or | |
17865 | necessary for various reasons. | |
88e1739c | 17866 | |
0ab80019 AC |
17867 | Stand-alone libraries are also well suited to be used in an executable whose |
17868 | main routine is not written in Ada. | |
88e1739c | 17869 | |
0ab80019 AC |
17870 | @node Building a Stand-alone Library |
17871 | @subsection Building a Stand-alone Library | |
88e1739c | 17872 | |
9bc856dd | 17873 | @noindent |
0ab80019 AC |
17874 | GNAT's Project facility provides a simple way of building and installing |
17875 | stand-alone libraries; see @ref{Stand-alone Library Projects}. | |
9bc856dd AC |
17876 | To be a Stand-alone Library Project, in addition to the two attributes |
17877 | that make a project a Library Project (@code{Library_Name} and | |
0ab80019 AC |
17878 | @code{Library_Dir}; see @ref{Library Projects}), the attribute |
17879 | @code{Library_Interface} must be defined. For example: | |
88e1739c | 17880 | |
9bc856dd AC |
17881 | @smallexample @c projectfile |
17882 | @group | |
17883 | for Library_Dir use "lib_dir"; | |
17884 | for Library_Name use "dummy"; | |
17885 | for Library_Interface use ("int1", "int1.child"); | |
17886 | @end group | |
17887 | @end smallexample | |
88e1739c | 17888 | |
0ab80019 | 17889 | @noindent |
984a64bc | 17890 | Attribute @code{Library_Interface} has a non-empty string list value, |
9bc856dd AC |
17891 | each string in the list designating a unit contained in an immediate source |
17892 | of the project file. | |
88e1739c | 17893 | |
9bc856dd AC |
17894 | When a Stand-alone Library is built, first the binder is invoked to build |
17895 | a package whose name depends on the library name | |
0ab80019 | 17896 | (@file{^b~dummy.ads/b^B$DUMMY.ADS/B^} in the example above). |
9bc856dd AC |
17897 | This binder-generated package includes initialization and |
17898 | finalization procedures whose | |
0ab80019 AC |
17899 | names depend on the library name (@code{dummyinit} and @code{dummyfinal} |
17900 | in the example | |
9bc856dd | 17901 | above). The object corresponding to this package is included in the library. |
88e1739c | 17902 | |
0ab80019 AC |
17903 | You must ensure timely (e.g., prior to any use of interfaces in the SAL) |
17904 | calling of these procedures if a static SAL is built, or if a shared SAL | |
17905 | is built | |
17906 | with the project-level attribute @code{Library_Auto_Init} set to | |
17907 | @code{"false"}. | |
88e1739c | 17908 | |
9bc856dd AC |
17909 | For a Stand-Alone Library, only the @file{ALI} files of the Interface Units |
17910 | (those that are listed in attribute @code{Library_Interface}) are copied to | |
17911 | the Library Directory. As a consequence, only the Interface Units may be | |
17912 | imported from Ada units outside of the library. If other units are imported, | |
17913 | the binding phase will fail. | |
88e1739c | 17914 | |
76f734d8 | 17915 | @noindent |
5e12215f | 17916 | It is also possible to build an encapsulated library where not only |
76f734d8 AC |
17917 | the code to elaborate and finalize the library is embedded but also |
17918 | ensuring that the library is linked only against static | |
5e12215f | 17919 | libraries. So an encapsulated library only depends on system |
76f734d8 | 17920 | libraries, all other code, including the GNAT runtime, is embedded. To |
5e12215f AC |
17921 | build an encapsulated library the attribute |
17922 | @code{Library_Standalone} must be set to @code{encapsulated}: | |
76f734d8 AC |
17923 | |
17924 | @smallexample @c projectfile | |
17925 | @group | |
17926 | for Library_Dir use "lib_dir"; | |
17927 | for Library_Name use "dummy"; | |
f6820c2d | 17928 | for Library_Kind use "dynamic"; |
76f734d8 | 17929 | for Library_Interface use ("int1", "int1.child"); |
5e12215f | 17930 | for Library_Standalone use "encapsulated"; |
76f734d8 AC |
17931 | @end group |
17932 | @end smallexample | |
17933 | ||
17934 | @noindent | |
17935 | The default value for this attribute is @code{standard} in which case | |
5e12215f | 17936 | a stand-alone library is built. |
76f734d8 | 17937 | |
0ab80019 | 17938 | The attribute @code{Library_Src_Dir} may be specified for a |
9bc856dd AC |
17939 | Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a |
17940 | single string value. Its value must be the path (absolute or relative to the | |
17941 | project directory) of an existing directory. This directory cannot be the | |
17942 | object directory or one of the source directories, but it can be the same as | |
17943 | the library directory. The sources of the Interface | |
0ab80019 AC |
17944 | Units of the library that are needed by an Ada client of the library will be |
17945 | copied to the designated directory, called the Interface Copy directory. | |
984a64bc | 17946 | These sources include the specs of the Interface Units, but they may also |
9bc856dd | 17947 | include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always} |
0ab80019 | 17948 | are used, or when there is a generic unit in the spec. Before the sources |
9bc856dd AC |
17949 | are copied to the Interface Copy directory, an attempt is made to delete all |
17950 | files in the Interface Copy directory. | |
88e1739c | 17951 | |
0ab80019 AC |
17952 | Building stand-alone libraries by hand is somewhat tedious, but for those |
17953 | occasions when it is necessary here are the steps that you need to perform: | |
9bc856dd AC |
17954 | @itemize @bullet |
17955 | @item | |
0ab80019 AC |
17956 | Compile all library sources. |
17957 | ||
9bc856dd | 17958 | @item |
0ab80019 AC |
17959 | Invoke the binder with the switch @option{-n} (No Ada main program), |
17960 | with all the @file{ALI} files of the interfaces, and | |
17961 | with the switch @option{-L} to give specific names to the @code{init} | |
17962 | and @code{final} procedures. For example: | |
9bc856dd AC |
17963 | @smallexample |
17964 | gnatbind -n int1.ali int2.ali -Lsal1 | |
17965 | @end smallexample | |
0ab80019 | 17966 | |
9bc856dd | 17967 | @item |
0ab80019 | 17968 | Compile the binder generated file: |
9bc856dd AC |
17969 | @smallexample |
17970 | gcc -c b~int2.adb | |
17971 | @end smallexample | |
0ab80019 | 17972 | |
9bc856dd | 17973 | @item |
0ab80019 AC |
17974 | Link the dynamic library with all the necessary object files, |
17975 | indicating to the linker the names of the @code{init} (and possibly | |
17976 | @code{final}) procedures for automatic initialization (and finalization). | |
17977 | The built library should be placed in a directory different from | |
9bc856dd | 17978 | the object directory. |
0ab80019 | 17979 | |
9bc856dd | 17980 | @item |
0ab80019 AC |
17981 | Copy the @code{ALI} files of the interface to the library directory, |
17982 | add in this copy an indication that it is an interface to a SAL | |
8dd07840 | 17983 | (i.e., add a word @option{SL} on the line in the @file{ALI} file that starts |
0ab80019 AC |
17984 | with letter ``P'') and make the modified copy of the @file{ALI} file |
17985 | read-only. | |
9bc856dd | 17986 | @end itemize |
88e1739c | 17987 | |
9bc856dd AC |
17988 | @noindent |
17989 | Using SALs is not different from using other libraries | |
87b3f81f | 17990 | (see @ref{Using a library}). |
88e1739c | 17991 | |
0ab80019 AC |
17992 | @node Creating a Stand-alone Library to be used in a non-Ada context |
17993 | @subsection Creating a Stand-alone Library to be used in a non-Ada context | |
88e1739c | 17994 | |
9bc856dd | 17995 | @noindent |
0ab80019 | 17996 | It is easy to adapt the SAL build procedure discussed above for use of a SAL in |
9bc856dd | 17997 | a non-Ada context. |
88e1739c | 17998 | |
9bc856dd AC |
17999 | The only extra step required is to ensure that library interface subprograms |
18000 | are compatible with the main program, by means of @code{pragma Export} | |
18001 | or @code{pragma Convention}. | |
88e1739c | 18002 | |
9bc856dd | 18003 | Here is an example of simple library interface for use with C main program: |
88e1739c | 18004 | |
9bc856dd | 18005 | @smallexample @c ada |
241bea26 | 18006 | package My_Package is |
88e1739c | 18007 | |
9bc856dd AC |
18008 | procedure Do_Something; |
18009 | pragma Export (C, Do_Something, "do_something"); | |
88e1739c | 18010 | |
9bc856dd AC |
18011 | procedure Do_Something_Else; |
18012 | pragma Export (C, Do_Something_Else, "do_something_else"); | |
88e1739c | 18013 | |
241bea26 | 18014 | end My_Package; |
88e1739c FW |
18015 | @end smallexample |
18016 | ||
9bc856dd AC |
18017 | @noindent |
18018 | On the foreign language side, you must provide a ``foreign'' view of the | |
0ab80019 AC |
18019 | library interface; remember that it should contain elaboration routines in |
18020 | addition to interface subprograms. | |
88e1739c FW |
18021 | |
18022 | The example below shows the content of @code{mylib_interface.h} (note | |
18023 | that there is no rule for the naming of this file, any name can be used) | |
18024 | @smallexample | |
18025 | /* the library elaboration procedure */ | |
18026 | extern void mylibinit (void); | |
18027 | ||
18028 | /* the library finalization procedure */ | |
18029 | extern void mylibfinal (void); | |
18030 | ||
18031 | /* the interface exported by the library */ | |
18032 | extern void do_something (void); | |
18033 | extern void do_something_else (void); | |
18034 | @end smallexample | |
88e1739c FW |
18035 | |
18036 | @noindent | |
18037 | Libraries built as explained above can be used from any program, provided | |
18038 | that the elaboration procedures (named @code{mylibinit} in the previous | |
18039 | example) are called before the library services are used. Any number of | |
18040 | libraries can be used simultaneously, as long as the elaboration | |
18041 | procedure of each library is called. | |
18042 | ||
984a64bc | 18043 | Below is an example of a C program that uses the @code{mylib} library. |
88e1739c FW |
18044 | |
18045 | @smallexample | |
18046 | #include "mylib_interface.h" | |
18047 | ||
18048 | int | |
18049 | main (void) | |
18050 | @{ | |
18051 | /* First, elaborate the library before using it */ | |
18052 | mylibinit (); | |
18053 | ||
18054 | /* Main program, using the library exported entities */ | |
18055 | do_something (); | |
18056 | do_something_else (); | |
18057 | ||
18058 | /* Library finalization at the end of the program */ | |
18059 | mylibfinal (); | |
18060 | return 0; | |
18061 | @} | |
18062 | @end smallexample | |
18063 | ||
18064 | @noindent | |
9bc856dd | 18065 | Note that invoking any library finalization procedure generated by |
0ab80019 AC |
18066 | @code{gnatbind} shuts down the Ada run-time environment. |
18067 | Consequently, the | |
9bc856dd | 18068 | finalization of all Ada libraries must be performed at the end of the program. |
984a64bc | 18069 | No call to these libraries or to the Ada run-time library should be made |
0ab80019 | 18070 | after the finalization phase. |
88e1739c | 18071 | |
0ab80019 AC |
18072 | @node Restrictions in Stand-alone Libraries |
18073 | @subsection Restrictions in Stand-alone Libraries | |
88e1739c FW |
18074 | |
18075 | @noindent | |
18076 | The pragmas listed below should be used with caution inside libraries, | |
18077 | as they can create incompatibilities with other Ada libraries: | |
18078 | @itemize @bullet | |
18079 | @item pragma @code{Locking_Policy} | |
3d918396 | 18080 | @item pragma @code{Partition_Elaboration_Policy} |
88e1739c FW |
18081 | @item pragma @code{Queuing_Policy} |
18082 | @item pragma @code{Task_Dispatching_Policy} | |
18083 | @item pragma @code{Unreserve_All_Interrupts} | |
18084 | @end itemize | |
0ab80019 AC |
18085 | |
18086 | @noindent | |
88e1739c FW |
18087 | When using a library that contains such pragmas, the user must make sure |
18088 | that all libraries use the same pragmas with the same values. Otherwise, | |
0ab80019 | 18089 | @code{Program_Error} will |
88e1739c FW |
18090 | be raised during the elaboration of the conflicting |
18091 | libraries. The usage of these pragmas and its consequences for the user | |
18092 | should therefore be well documented. | |
18093 | ||
0ab80019 | 18094 | Similarly, the traceback in the exception occurrence mechanism should be |
88e1739c | 18095 | enabled or disabled in a consistent manner across all libraries. |
0ab80019 | 18096 | Otherwise, Program_Error will be raised during the elaboration of the |
88e1739c FW |
18097 | conflicting libraries. |
18098 | ||
0ab80019 AC |
18099 | If the @code{Version} or @code{Body_Version} |
18100 | attributes are used inside a library, then you need to | |
18101 | perform a @code{gnatbind} step that specifies all @file{ALI} files in all | |
88e1739c FW |
18102 | libraries, so that version identifiers can be properly computed. |
18103 | In practice these attributes are rarely used, so this is unlikely | |
18104 | to be a consideration. | |
18105 | ||
18106 | @node Rebuilding the GNAT Run-Time Library | |
18107 | @section Rebuilding the GNAT Run-Time Library | |
9bc856dd | 18108 | @cindex GNAT Run-Time Library, rebuilding |
7e3d710b AC |
18109 | @cindex Building the GNAT Run-Time Library |
18110 | @cindex Rebuilding the GNAT Run-Time Library | |
18111 | @cindex Run-Time Library, rebuilding | |
88e1739c FW |
18112 | |
18113 | @noindent | |
18114 | It may be useful to recompile the GNAT library in various contexts, the | |
18115 | most important one being the use of partition-wide configuration pragmas | |
9bc856dd | 18116 | such as @code{Normalize_Scalars}. A special Makefile called |
88e1739c FW |
18117 | @code{Makefile.adalib} is provided to that effect and can be found in |
18118 | the directory containing the GNAT library. The location of this | |
18119 | directory depends on the way the GNAT environment has been installed and can | |
18120 | be determined by means of the command: | |
18121 | ||
18122 | @smallexample | |
18123 | $ gnatls -v | |
18124 | @end smallexample | |
18125 | ||
18126 | @noindent | |
18127 | The last entry in the object search path usually contains the | |
18128 | gnat library. This Makefile contains its own documentation and in | |
18129 | particular the set of instructions needed to rebuild a new library and | |
18130 | to use it. | |
18131 | ||
18132 | @node Using the GNU make Utility | |
18133 | @chapter Using the GNU @code{make} Utility | |
18134 | @findex make | |
18135 | ||
18136 | @noindent | |
18137 | This chapter offers some examples of makefiles that solve specific | |
b2e74434 RW |
18138 | problems. It does not explain how to write a makefile (@pxref{Top,, GNU |
18139 | make, make, GNU @code{make}}), nor does it try to replace the | |
18140 | @command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}). | |
88e1739c FW |
18141 | |
18142 | All the examples in this section are specific to the GNU version of | |
1992bbd9 | 18143 | make. Although @command{make} is a standard utility, and the basic language |
88e1739c FW |
18144 | is the same, these examples use some advanced features found only in |
18145 | @code{GNU make}. | |
18146 | ||
18147 | @menu | |
18148 | * Using gnatmake in a Makefile:: | |
18149 | * Automatically Creating a List of Directories:: | |
18150 | * Generating the Command Line Switches:: | |
18151 | * Overcoming Command Line Length Limits:: | |
18152 | @end menu | |
18153 | ||
18154 | @node Using gnatmake in a Makefile | |
18155 | @section Using gnatmake in a Makefile | |
18156 | @findex makefile | |
18157 | @cindex GNU make | |
18158 | ||
18159 | @noindent | |
18160 | Complex project organizations can be handled in a very powerful way by | |
18161 | using GNU make combined with gnatmake. For instance, here is a Makefile | |
18162 | which allows you to build each subsystem of a big project into a separate | |
18163 | shared library. Such a makefile allows you to significantly reduce the link | |
18164 | time of very big applications while maintaining full coherence at | |
18165 | each step of the build process. | |
18166 | ||
18167 | The list of dependencies are handled automatically by | |
984a64bc | 18168 | @command{gnatmake}. The Makefile is simply used to call gnatmake in each of |
88e1739c FW |
18169 | the appropriate directories. |
18170 | ||
18171 | Note that you should also read the example on how to automatically | |
7cd4527e AC |
18172 | create the list of directories |
18173 | (@pxref{Automatically Creating a List of Directories}) | |
18174 | which might help you in case your project has a lot of subdirectories. | |
88e1739c FW |
18175 | |
18176 | @smallexample | |
18177 | @iftex | |
18178 | @leftskip=0cm | |
18179 | @font@heightrm=cmr8 | |
18180 | @heightrm | |
18181 | @end iftex | |
18182 | ## This Makefile is intended to be used with the following directory | |
18183 | ## configuration: | |
18184 | ## - The sources are split into a series of csc (computer software components) | |
18185 | ## Each of these csc is put in its own directory. | |
18186 | ## Their name are referenced by the directory names. | |
18187 | ## They will be compiled into shared library (although this would also work | |
18188 | ## with static libraries | |
18189 | ## - The main program (and possibly other packages that do not belong to any | |
18190 | ## csc is put in the top level directory (where the Makefile is). | |
18191 | ## toplevel_dir __ first_csc (sources) __ lib (will contain the library) | |
18192 | ## \_ second_csc (sources) __ lib (will contain the library) | |
d488f6ea | 18193 | ## \_ @dots{} |
88e1739c FW |
18194 | ## Although this Makefile is build for shared library, it is easy to modify |
18195 | ## to build partial link objects instead (modify the lines with -shared and | |
18196 | ## gnatlink below) | |
18197 | ## | |
18198 | ## With this makefile, you can change any file in the system or add any new | |
18199 | ## file, and everything will be recompiled correctly (only the relevant shared | |
18200 | ## objects will be recompiled, and the main program will be re-linked). | |
18201 | ||
18202 | # The list of computer software component for your project. This might be | |
18203 | # generated automatically. | |
18204 | CSC_LIST=aa bb cc | |
18205 | ||
18206 | # Name of the main program (no extension) | |
18207 | MAIN=main | |
18208 | ||
18209 | # If we need to build objects with -fPIC, uncomment the following line | |
18210 | #NEED_FPIC=-fPIC | |
18211 | ||
18212 | # The following variable should give the directory containing libgnat.so | |
18213 | # You can get this directory through 'gnatls -v'. This is usually the last | |
18214 | # directory in the Object_Path. | |
d488f6ea | 18215 | GLIB=@dots{} |
88e1739c FW |
18216 | |
18217 | # The directories for the libraries | |
18218 | # (This macro expands the list of CSC to the list of shared libraries, you | |
e69044cb | 18219 | # could simply use the expanded form: |
88e1739c FW |
18220 | # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so |
18221 | LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@} | |
18222 | ||
18223 | $@{MAIN@}: objects $@{LIB_DIR@} | |
18224 | gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared | |
18225 | gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@} | |
18226 | ||
18227 | objects:: | |
18228 | # recompile the sources | |
18229 | gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@} | |
18230 | ||
18231 | # Note: In a future version of GNAT, the following commands will be simplified | |
18232 | # by a new tool, gnatmlib | |
18233 | $@{LIB_DIR@}: | |
18234 | mkdir -p $@{dir $@@ @} | |
9538dfb9 RW |
18235 | cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat |
18236 | cd $@{dir $@@ @} && cp -f ../*.ali . | |
88e1739c FW |
18237 | |
18238 | # The dependencies for the modules | |
7cd4527e AC |
18239 | # Note that we have to force the expansion of *.o, since in some cases |
18240 | # make won't be able to do it itself. | |
88e1739c FW |
18241 | aa/lib/libaa.so: $@{wildcard aa/*.o@} |
18242 | bb/lib/libbb.so: $@{wildcard bb/*.o@} | |
18243 | cc/lib/libcc.so: $@{wildcard cc/*.o@} | |
18244 | ||
18245 | # Make sure all of the shared libraries are in the path before starting the | |
18246 | # program | |
18247 | run:: | |
18248 | LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@} | |
18249 | ||
18250 | clean:: | |
18251 | $@{RM@} -rf $@{CSC_LIST:%=%/lib@} | |
18252 | $@{RM@} $@{CSC_LIST:%=%/*.ali@} | |
18253 | $@{RM@} $@{CSC_LIST:%=%/*.o@} | |
18254 | $@{RM@} *.o *.ali $@{MAIN@} | |
18255 | @end smallexample | |
18256 | ||
18257 | @node Automatically Creating a List of Directories | |
18258 | @section Automatically Creating a List of Directories | |
18259 | ||
18260 | @noindent | |
18261 | In most makefiles, you will have to specify a list of directories, and | |
18262 | store it in a variable. For small projects, it is often easier to | |
18263 | specify each of them by hand, since you then have full control over what | |
18264 | is the proper order for these directories, which ones should be | |
d488f6ea | 18265 | included. |
88e1739c FW |
18266 | |
18267 | However, in larger projects, which might involve hundreds of | |
18268 | subdirectories, it might be more convenient to generate this list | |
18269 | automatically. | |
18270 | ||
18271 | The example below presents two methods. The first one, although less | |
18272 | general, gives you more control over the list. It involves wildcard | |
1992bbd9 | 18273 | characters, that are automatically expanded by @command{make}. Its |
88e1739c FW |
18274 | shortcoming is that you need to explicitly specify some of the |
18275 | organization of your project, such as for instance the directory tree | |
d488f6ea | 18276 | depth, whether some directories are found in a separate tree, @enddots{} |
88e1739c FW |
18277 | |
18278 | The second method is the most general one. It requires an external | |
1992bbd9 | 18279 | program, called @command{find}, which is standard on all Unix systems. All |
88e1739c FW |
18280 | the directories found under a given root directory will be added to the |
18281 | list. | |
18282 | ||
18283 | @smallexample | |
18284 | @iftex | |
18285 | @leftskip=0cm | |
18286 | @font@heightrm=cmr8 | |
18287 | @heightrm | |
18288 | @end iftex | |
18289 | # The examples below are based on the following directory hierarchy: | |
18290 | # All the directories can contain any number of files | |
18291 | # ROOT_DIRECTORY -> a -> aa -> aaa | |
18292 | # -> ab | |
18293 | # -> ac | |
18294 | # -> b -> ba -> baa | |
18295 | # -> bb | |
18296 | # -> bc | |
18297 | # This Makefile creates a variable called DIRS, that can be reused any time | |
18298 | # you need this list (see the other examples in this section) | |
18299 | ||
18300 | # The root of your project's directory hierarchy | |
18301 | ROOT_DIRECTORY=. | |
18302 | ||
18303 | #### | |
18304 | # First method: specify explicitly the list of directories | |
18305 | # This allows you to specify any subset of all the directories you need. | |
18306 | #### | |
18307 | ||
18308 | DIRS := a/aa/ a/ab/ b/ba/ | |
18309 | ||
18310 | #### | |
18311 | # Second method: use wildcards | |
18312 | # Note that the argument(s) to wildcard below should end with a '/'. | |
18313 | # Since wildcards also return file names, we have to filter them out | |
18314 | # to avoid duplicate directory names. | |
18315 | # We thus use make's @code{dir} and @code{sort} functions. | |
18316 | # It sets DIRs to the following value (note that the directories aaa and baa | |
18317 | # are not given, unless you change the arguments to wildcard). | |
18318 | # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ | |
18319 | #### | |
18320 | ||
7cd4527e AC |
18321 | DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/ |
18322 | $@{ROOT_DIRECTORY@}/*/*/@}@}@} | |
88e1739c FW |
18323 | |
18324 | #### | |
18325 | # Third method: use an external program | |
18326 | # This command is much faster if run on local disks, avoiding NFS slowdowns. | |
18327 | # This is the most complete command: it sets DIRs to the following value: | |
18328 | # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc | |
18329 | #### | |
18330 | ||
18331 | DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@} | |
18332 | ||
18333 | @end smallexample | |
18334 | ||
18335 | @node Generating the Command Line Switches | |
18336 | @section Generating the Command Line Switches | |
18337 | ||
18338 | @noindent | |
18339 | Once you have created the list of directories as explained in the | |
18340 | previous section (@pxref{Automatically Creating a List of Directories}), | |
18341 | you can easily generate the command line arguments to pass to gnatmake. | |
18342 | ||
18343 | For the sake of completeness, this example assumes that the source path | |
18344 | is not the same as the object path, and that you have two separate lists | |
18345 | of directories. | |
18346 | ||
18347 | @smallexample | |
18348 | # see "Automatically creating a list of directories" to create | |
18349 | # these variables | |
18350 | SOURCE_DIRS= | |
18351 | OBJECT_DIRS= | |
18352 | ||
18353 | GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@} | |
18354 | GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@} | |
18355 | ||
18356 | all: | |
18357 | gnatmake $@{GNATMAKE_SWITCHES@} main_unit | |
18358 | @end smallexample | |
18359 | ||
18360 | @node Overcoming Command Line Length Limits | |
18361 | @section Overcoming Command Line Length Limits | |
18362 | ||
18363 | @noindent | |
18364 | One problem that might be encountered on big projects is that many | |
18365 | operating systems limit the length of the command line. It is thus hard to give | |
18366 | gnatmake the list of source and object directories. | |
18367 | ||
18368 | This example shows how you can set up environment variables, which will | |
984a64bc | 18369 | make @command{gnatmake} behave exactly as if the directories had been |
88e1739c FW |
18370 | specified on the command line, but have a much higher length limit (or |
18371 | even none on most systems). | |
18372 | ||
18373 | It assumes that you have created a list of directories in your Makefile, | |
18374 | using one of the methods presented in | |
18375 | @ref{Automatically Creating a List of Directories}. | |
18376 | For the sake of completeness, we assume that the object | |
18377 | path (where the ALI files are found) is different from the sources patch. | |
18378 | ||
18379 | Note a small trick in the Makefile below: for efficiency reasons, we | |
18380 | create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are | |
18381 | expanded immediately by @code{make}. This way we overcome the standard | |
18382 | make behavior which is to expand the variables only when they are | |
18383 | actually used. | |
18384 | ||
7cd4527e AC |
18385 | On Windows, if you are using the standard Windows command shell, you must |
18386 | replace colons with semicolons in the assignments to these variables. | |
18387 | ||
88e1739c FW |
18388 | @smallexample |
18389 | @iftex | |
18390 | @leftskip=0cm | |
18391 | @font@heightrm=cmr8 | |
18392 | @heightrm | |
18393 | @end iftex | |
b60a3f26 | 18394 | # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH. |
88e1739c FW |
18395 | # This is the same thing as putting the -I arguments on the command line. |
18396 | # (the equivalent of using -aI on the command line would be to define | |
b60a3f26 | 18397 | # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH). |
88e1739c FW |
18398 | # You can of course have different values for these variables. |
18399 | # | |
18400 | # Note also that we need to keep the previous values of these variables, since | |
18401 | # they might have been set before running 'make' to specify where the GNAT | |
18402 | # library is installed. | |
18403 | ||
18404 | # see "Automatically creating a list of directories" to create these | |
18405 | # variables | |
18406 | SOURCE_DIRS= | |
18407 | OBJECT_DIRS= | |
18408 | ||
18409 | empty:= | |
18410 | space:=$@{empty@} $@{empty@} | |
18411 | SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@} | |
18412 | OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@} | |
18413 | ADA_INCLUDE_PATH += $@{SOURCE_LIST@} | |
b60a3f26 | 18414 | ADA_OBJECTS_PATH += $@{OBJECT_LIST@} |
88e1739c | 18415 | export ADA_INCLUDE_PATH |
b60a3f26 | 18416 | export ADA_OBJECTS_PATH |
88e1739c FW |
18417 | |
18418 | all: | |
18419 | gnatmake main_unit | |
18420 | @end smallexample | |
7cd4527e | 18421 | @end ifclear |
88e1739c | 18422 | |
f142e9fa CC |
18423 | @node Memory Management Issues |
18424 | @chapter Memory Management Issues | |
7cd4527e AC |
18425 | |
18426 | @noindent | |
f142e9fa CC |
18427 | This chapter describes some useful memory pools provided in the GNAT library |
18428 | and in particular the GNAT Debug Pool facility, which can be used to detect | |
18429 | incorrect uses of access values (including ``dangling references''). | |
7cd4527e | 18430 | @ifclear vms |
1037b0f4 | 18431 | @ifclear FSFEDITION |
f142e9fa CC |
18432 | It also describes the @command{gnatmem} tool, which can be used to track down |
18433 | ``memory leaks''. | |
7cd4527e | 18434 | @end ifclear |
1037b0f4 | 18435 | @end ifclear |
7cd4527e AC |
18436 | |
18437 | @menu | |
f142e9fa CC |
18438 | * Some Useful Memory Pools:: |
18439 | * The GNAT Debug Pool Facility:: | |
7cd4527e | 18440 | @ifclear vms |
1037b0f4 | 18441 | @ifclear FSFEDITION |
7cd4527e AC |
18442 | * The gnatmem Tool:: |
18443 | @end ifclear | |
1037b0f4 | 18444 | @end ifclear |
7cd4527e AC |
18445 | @end menu |
18446 | ||
f142e9fa CC |
18447 | @node Some Useful Memory Pools |
18448 | @section Some Useful Memory Pools | |
18449 | @findex Memory Pool | |
18450 | @cindex storage, pool | |
18451 | ||
18452 | @noindent | |
18453 | The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool | |
18454 | storage pool. Allocations use the standard system call @code{malloc} while | |
18455 | deallocations use the standard system call @code{free}. No reclamation is | |
18456 | performed when the pool goes out of scope. For performance reasons, the | |
18457 | standard default Ada allocators/deallocators do not use any explicit storage | |
18458 | pools but if they did, they could use this storage pool without any change in | |
18459 | behavior. That is why this storage pool is used when the user | |
18460 | manages to make the default implicit allocator explicit as in this example: | |
18461 | @smallexample @c ada | |
18462 | type T1 is access Something; | |
18463 | -- no Storage pool is defined for T2 | |
18464 | type T2 is access Something_Else; | |
18465 | for T2'Storage_Pool use T1'Storage_Pool; | |
18466 | -- the above is equivalent to | |
18467 | for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object; | |
18468 | @end smallexample | |
18469 | ||
18470 | @noindent | |
18471 | The @code{System.Pool_Local} package offers the Unbounded_Reclaim_Pool storage | |
18472 | pool. The allocation strategy is similar to @code{Pool_Local}'s | |
18473 | except that the all | |
18474 | storage allocated with this pool is reclaimed when the pool object goes out of | |
18475 | scope. This pool provides a explicit mechanism similar to the implicit one | |
18476 | provided by several Ada 83 compilers for allocations performed through a local | |
18477 | access type and whose purpose was to reclaim memory when exiting the | |
18478 | scope of a given local access. As an example, the following program does not | |
18479 | leak memory even though it does not perform explicit deallocation: | |
18480 | ||
18481 | @smallexample @c ada | |
18482 | with System.Pool_Local; | |
18483 | procedure Pooloc1 is | |
18484 | procedure Internal is | |
18485 | type A is access Integer; | |
18486 | X : System.Pool_Local.Unbounded_Reclaim_Pool; | |
18487 | for A'Storage_Pool use X; | |
18488 | v : A; | |
18489 | begin | |
18490 | for I in 1 .. 50 loop | |
18491 | v := new Integer; | |
18492 | end loop; | |
18493 | end Internal; | |
18494 | begin | |
18495 | for I in 1 .. 100 loop | |
18496 | Internal; | |
18497 | end loop; | |
18498 | end Pooloc1; | |
18499 | @end smallexample | |
18500 | ||
18501 | @noindent | |
18502 | The @code{System.Pool_Size} package implements the Stack_Bounded_Pool used when | |
18503 | @code{Storage_Size} is specified for an access type. | |
18504 | The whole storage for the pool is | |
18505 | allocated at once, usually on the stack at the point where the access type is | |
18506 | elaborated. It is automatically reclaimed when exiting the scope where the | |
18507 | access type is defined. This package is not intended to be used directly by the | |
18508 | user and it is implicitly used for each such declaration: | |
18509 | ||
18510 | @smallexample @c ada | |
18511 | type T1 is access Something; | |
18512 | for T1'Storage_Size use 10_000; | |
18513 | @end smallexample | |
18514 | ||
f142e9fa CC |
18515 | @node The GNAT Debug Pool Facility |
18516 | @section The GNAT Debug Pool Facility | |
18517 | @findex Debug Pool | |
18518 | @cindex storage, pool, memory corruption | |
18519 | ||
18520 | @noindent | |
18521 | The use of unchecked deallocation and unchecked conversion can easily | |
18522 | lead to incorrect memory references. The problems generated by such | |
18523 | references are usually difficult to tackle because the symptoms can be | |
18524 | very remote from the origin of the problem. In such cases, it is | |
18525 | very helpful to detect the problem as early as possible. This is the | |
18526 | purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}. | |
18527 | ||
18528 | In order to use the GNAT specific debugging pool, the user must | |
18529 | associate a debug pool object with each of the access types that may be | |
18530 | related to suspected memory problems. See Ada Reference Manual 13.11. | |
18531 | @smallexample @c ada | |
18532 | type Ptr is access Some_Type; | |
18533 | Pool : GNAT.Debug_Pools.Debug_Pool; | |
18534 | for Ptr'Storage_Pool use Pool; | |
18535 | @end smallexample | |
18536 | ||
18537 | @noindent | |
18538 | @code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of | |
18539 | pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools, | |
18540 | allow the user to redefine allocation and deallocation strategies. They | |
18541 | also provide a checkpoint for each dereference, through the use of | |
18542 | the primitive operation @code{Dereference} which is implicitly called at | |
18543 | each dereference of an access value. | |
18544 | ||
18545 | Once an access type has been associated with a debug pool, operations on | |
18546 | values of the type may raise four distinct exceptions, | |
18547 | which correspond to four potential kinds of memory corruption: | |
18548 | @itemize @bullet | |
18549 | @item | |
18550 | @code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage} | |
18551 | @item | |
18552 | @code{GNAT.Debug_Pools.Accessing_Deallocated_Storage} | |
18553 | @item | |
18554 | @code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage} | |
18555 | @item | |
18556 | @code{GNAT.Debug_Pools.Freeing_Deallocated_Storage } | |
18557 | @end itemize | |
18558 | ||
18559 | @noindent | |
18560 | For types associated with a Debug_Pool, dynamic allocation is performed using | |
18561 | the standard GNAT allocation routine. References to all allocated chunks of | |
18562 | memory are kept in an internal dictionary. Several deallocation strategies are | |
18563 | provided, whereupon the user can choose to release the memory to the system, | |
18564 | keep it allocated for further invalid access checks, or fill it with an easily | |
18565 | recognizable pattern for debug sessions. The memory pattern is the old IBM | |
18566 | hexadecimal convention: @code{16#DEADBEEF#}. | |
18567 | ||
18568 | See the documentation in the file g-debpoo.ads for more information on the | |
18569 | various strategies. | |
18570 | ||
18571 | Upon each dereference, a check is made that the access value denotes a | |
18572 | properly allocated memory location. Here is a complete example of use of | |
18573 | @code{Debug_Pools}, that includes typical instances of memory corruption: | |
18574 | @smallexample @c ada | |
18575 | @iftex | |
18576 | @leftskip=0cm | |
18577 | @end iftex | |
18578 | with Gnat.Io; use Gnat.Io; | |
18579 | with Unchecked_Deallocation; | |
18580 | with Unchecked_Conversion; | |
18581 | with GNAT.Debug_Pools; | |
18582 | with System.Storage_Elements; | |
18583 | with Ada.Exceptions; use Ada.Exceptions; | |
18584 | procedure Debug_Pool_Test is | |
18585 | ||
18586 | type T is access Integer; | |
18587 | type U is access all T; | |
18588 | ||
18589 | P : GNAT.Debug_Pools.Debug_Pool; | |
18590 | for T'Storage_Pool use P; | |
18591 | ||
18592 | procedure Free is new Unchecked_Deallocation (Integer, T); | |
18593 | function UC is new Unchecked_Conversion (U, T); | |
18594 | A, B : aliased T; | |
18595 | ||
18596 | procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); | |
18597 | ||
18598 | begin | |
18599 | Info (P); | |
18600 | A := new Integer; | |
18601 | B := new Integer; | |
18602 | B := A; | |
18603 | Info (P); | |
18604 | Free (A); | |
18605 | begin | |
18606 | Put_Line (Integer'Image(B.all)); | |
18607 | exception | |
18608 | when E : others => Put_Line ("raised: " & Exception_Name (E)); | |
18609 | end; | |
18610 | begin | |
18611 | Free (B); | |
18612 | exception | |
18613 | when E : others => Put_Line ("raised: " & Exception_Name (E)); | |
18614 | end; | |
18615 | B := UC(A'Access); | |
18616 | begin | |
18617 | Put_Line (Integer'Image(B.all)); | |
18618 | exception | |
18619 | when E : others => Put_Line ("raised: " & Exception_Name (E)); | |
18620 | end; | |
18621 | begin | |
18622 | Free (B); | |
18623 | exception | |
18624 | when E : others => Put_Line ("raised: " & Exception_Name (E)); | |
18625 | end; | |
18626 | Info (P); | |
18627 | end Debug_Pool_Test; | |
18628 | @end smallexample | |
18629 | ||
18630 | @noindent | |
18631 | The debug pool mechanism provides the following precise diagnostics on the | |
18632 | execution of this erroneous program: | |
18633 | @smallexample | |
18634 | Debug Pool info: | |
18635 | Total allocated bytes : 0 | |
18636 | Total deallocated bytes : 0 | |
18637 | Current Water Mark: 0 | |
18638 | High Water Mark: 0 | |
18639 | ||
18640 | Debug Pool info: | |
18641 | Total allocated bytes : 8 | |
18642 | Total deallocated bytes : 0 | |
18643 | Current Water Mark: 8 | |
18644 | High Water Mark: 8 | |
18645 | ||
18646 | raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE | |
18647 | raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE | |
18648 | raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE | |
18649 | raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE | |
18650 | Debug Pool info: | |
18651 | Total allocated bytes : 8 | |
18652 | Total deallocated bytes : 4 | |
18653 | Current Water Mark: 4 | |
18654 | High Water Mark: 8 | |
18655 | @end smallexample | |
18656 | ||
7cd4527e | 18657 | @ifclear vms |
1037b0f4 | 18658 | @ifclear FSFEDITION |
7cd4527e AC |
18659 | @node The gnatmem Tool |
18660 | @section The @command{gnatmem} Tool | |
88e1739c FW |
18661 | @findex gnatmem |
18662 | ||
18663 | @noindent | |
7cd4527e | 18664 | The @code{gnatmem} utility monitors dynamic allocation and |
88e1739c | 18665 | deallocation activity in a program, and displays information about |
7cd4527e | 18666 | incorrect deallocations and possible sources of memory leaks. |
b2ed7a03 AC |
18667 | It is designed to work in association with a static runtime library |
18668 | only and in this context provides three types of information: | |
88e1739c FW |
18669 | @itemize @bullet |
18670 | @item | |
18671 | General information concerning memory management, such as the total | |
18672 | number of allocations and deallocations, the amount of allocated | |
8dd07840 | 18673 | memory and the high water mark, i.e.@: the largest amount of allocated |
88e1739c FW |
18674 | memory in the course of program execution. |
18675 | ||
18676 | @item | |
18677 | Backtraces for all incorrect deallocations, that is to say deallocations | |
18678 | which do not correspond to a valid allocation. | |
18679 | ||
18680 | @item | |
18681 | Information on each allocation that is potentially the origin of a memory | |
18682 | leak. | |
18683 | @end itemize | |
18684 | ||
88e1739c | 18685 | @menu |
7cd4527e | 18686 | * Running gnatmem:: |
88e1739c | 18687 | * Switches for gnatmem:: |
7cd4527e | 18688 | * Example of gnatmem Usage:: |
88e1739c FW |
18689 | @end menu |
18690 | ||
7cd4527e AC |
18691 | @node Running gnatmem |
18692 | @subsection Running @code{gnatmem} | |
18693 | ||
18694 | @noindent | |
18695 | @code{gnatmem} makes use of the output created by the special version of | |
18696 | allocation and deallocation routines that record call information. This | |
18697 | allows to obtain accurate dynamic memory usage history at a minimal cost to | |
18698 | the execution speed. Note however, that @code{gnatmem} is not supported on | |
e08b38f5 VC |
18699 | all platforms (currently, it is supported on AIX, HP-UX, GNU/Linux, |
18700 | Solaris and Windows NT/2000/XP (x86). | |
88e1739c FW |
18701 | |
18702 | @noindent | |
18703 | The @code{gnatmem} command has the form | |
18704 | ||
18705 | @smallexample | |
e074d476 AC |
18706 | @c $ gnatmem @ovar{switches} user_program |
18707 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
18708 | $ gnatmem @r{[}@var{switches}@r{]} @var{user_program} | |
88e1739c FW |
18709 | @end smallexample |
18710 | ||
18711 | @noindent | |
7cd4527e AC |
18712 | The program must have been linked with the instrumented version of the |
18713 | allocation and deallocation routines. This is done by linking with the | |
18714 | @file{libgmem.a} library. For correct symbolic backtrace information, | |
18715 | the user program should be compiled with debugging options | |
7e3d710b | 18716 | (see @ref{Switches for gcc}). For example to build @file{my_program}: |
7cd4527e | 18717 | |
88e1739c | 18718 | @smallexample |
7cd4527e | 18719 | $ gnatmake -g my_program -largs -lgmem |
88e1739c | 18720 | @end smallexample |
7cd4527e | 18721 | |
ba1cbfb9 RD |
18722 | @noindent |
18723 | As library @file{libgmem.a} contains an alternate body for package | |
18724 | @code{System.Memory}, @file{s-memory.adb} should not be compiled and linked | |
18725 | when an executable is linked with library @file{libgmem.a}. It is then not | |
18726 | recommended to use @command{gnatmake} with switch @option{^-a^/ALL_FILES^}. | |
18727 | ||
7cd4527e | 18728 | @noindent |
7e3d710b AC |
18729 | When @file{my_program} is executed, the file @file{gmem.out} is produced. |
18730 | This file contains information about all allocations and deallocations | |
18731 | performed by the program. It is produced by the instrumented allocations and | |
7cd4527e AC |
18732 | deallocations routines and will be used by @code{gnatmem}. |
18733 | ||
7e3d710b AC |
18734 | In order to produce symbolic backtrace information for allocations and |
18735 | deallocations performed by the GNAT run-time library, you need to use a | |
18736 | version of that library that has been compiled with the @option{-g} switch | |
18737 | (see @ref{Rebuilding the GNAT Run-Time Library}). | |
18738 | ||
7cd4527e AC |
18739 | Gnatmem must be supplied with the @file{gmem.out} file and the executable to |
18740 | examine. If the location of @file{gmem.out} file was not explicitly supplied by | |
1992bbd9 | 18741 | @option{-i} switch, gnatmem will assume that this file can be found in the |
7cd4527e AC |
18742 | current directory. For example, after you have executed @file{my_program}, |
18743 | @file{gmem.out} can be analyzed by @code{gnatmem} using the command: | |
18744 | ||
88e1739c | 18745 | @smallexample |
7cd4527e | 18746 | $ gnatmem my_program |
88e1739c FW |
18747 | @end smallexample |
18748 | ||
7cd4527e AC |
18749 | @noindent |
18750 | This will produce the output with the following format: | |
88e1739c FW |
18751 | |
18752 | *************** debut cc | |
18753 | @smallexample | |
7cd4527e | 18754 | $ gnatmem my_program |
88e1739c FW |
18755 | |
18756 | Global information | |
18757 | ------------------ | |
18758 | Total number of allocations : 45 | |
18759 | Total number of deallocations : 6 | |
18760 | Final Water Mark (non freed mem) : 11.29 Kilobytes | |
18761 | High Water Mark : 11.40 Kilobytes | |
18762 | ||
18763 | . | |
18764 | . | |
18765 | . | |
18766 | Allocation Root # 2 | |
18767 | ------------------- | |
18768 | Number of non freed allocations : 11 | |
18769 | Final Water Mark (non freed mem) : 1.16 Kilobytes | |
18770 | High Water Mark : 1.27 Kilobytes | |
18771 | Backtrace : | |
7cd4527e | 18772 | my_program.adb:23 my_program.alloc |
88e1739c FW |
18773 | . |
18774 | . | |
18775 | . | |
18776 | @end smallexample | |
18777 | ||
7cd4527e AC |
18778 | The first block of output gives general information. In this case, the |
18779 | Ada construct ``@code{@b{new}}'' was executed 45 times, and only 6 calls to an | |
18780 | Unchecked_Deallocation routine occurred. | |
88e1739c | 18781 | |
7cd4527e | 18782 | @noindent |
88e1739c FW |
18783 | Subsequent paragraphs display information on all allocation roots. |
18784 | An allocation root is a specific point in the execution of the program | |
7cd4527e AC |
18785 | that generates some dynamic allocation, such as a ``@code{@b{new}}'' |
18786 | construct. This root is represented by an execution backtrace (or subprogram | |
18787 | call stack). By default the backtrace depth for allocations roots is 1, so | |
88e1739c FW |
18788 | that a root corresponds exactly to a source location. The backtrace can |
18789 | be made deeper, to make the root more specific. | |
18790 | ||
88e1739c | 18791 | @node Switches for gnatmem |
7cd4527e | 18792 | @subsection Switches for @code{gnatmem} |
88e1739c FW |
18793 | |
18794 | @noindent | |
18795 | @code{gnatmem} recognizes the following switches: | |
18796 | ||
7cd4527e | 18797 | @table @option |
88e1739c | 18798 | |
7cd4527e AC |
18799 | @item -q |
18800 | @cindex @option{-q} (@code{gnatmem}) | |
88e1739c | 18801 | Quiet. Gives the minimum output needed to identify the origin of the |
7cd4527e | 18802 | memory leaks. Omits statistical information. |
88e1739c | 18803 | |
7cd4527e AC |
18804 | @item @var{N} |
18805 | @cindex @var{N} (@code{gnatmem}) | |
88e1739c FW |
18806 | N is an integer literal (usually between 1 and 10) which controls the |
18807 | depth of the backtraces defining allocation root. The default value for | |
18808 | N is 1. The deeper the backtrace, the more precise the localization of | |
18809 | the root. Note that the total number of roots can depend on this | |
7cd4527e AC |
18810 | parameter. This parameter must be specified @emph{before} the name of the |
18811 | executable to be analyzed, to avoid ambiguity. | |
18812 | ||
18813 | @item -b n | |
18814 | @cindex @option{-b} (@code{gnatmem}) | |
18815 | This switch has the same effect as just depth parameter. | |
18816 | ||
18817 | @item -i @var{file} | |
18818 | @cindex @option{-i} (@code{gnatmem}) | |
18819 | Do the @code{gnatmem} processing starting from @file{file}, rather than | |
18820 | @file{gmem.out} in the current directory. | |
18821 | ||
18822 | @item -m n | |
18823 | @cindex @option{-m} (@code{gnatmem}) | |
18824 | This switch causes @code{gnatmem} to mask the allocation roots that have less | |
18825 | than n leaks. The default value is 1. Specifying the value of 0 will allow to | |
18826 | examine even the roots that didn't result in leaks. | |
18827 | ||
18828 | @item -s order | |
18829 | @cindex @option{-s} (@code{gnatmem}) | |
18830 | This switch causes @code{gnatmem} to sort the allocation roots according to the | |
18831 | specified order of sort criteria, each identified by a single letter. The | |
18832 | currently supported criteria are @code{n, h, w} standing respectively for | |
18833 | number of unfreed allocations, high watermark, and final watermark | |
18834 | corresponding to a specific root. The default order is @code{nwh}. | |
88e1739c FW |
18835 | |
18836 | @end table | |
18837 | ||
7cd4527e AC |
18838 | @node Example of gnatmem Usage |
18839 | @subsection Example of @code{gnatmem} Usage | |
88e1739c FW |
18840 | |
18841 | @noindent | |
7cd4527e AC |
18842 | The following example shows the use of @code{gnatmem} |
18843 | on a simple memory-leaking program. | |
88e1739c FW |
18844 | Suppose that we have the following Ada program: |
18845 | ||
7cd4527e | 18846 | @smallexample @c ada |
88e1739c FW |
18847 | @group |
18848 | @cartouche | |
7cd4527e AC |
18849 | with Unchecked_Deallocation; |
18850 | procedure Test_Gm is | |
88e1739c | 18851 | |
7cd4527e AC |
18852 | type T is array (1..1000) of Integer; |
18853 | type Ptr is access T; | |
18854 | procedure Free is new Unchecked_Deallocation (T, Ptr); | |
88e1739c FW |
18855 | A : Ptr; |
18856 | ||
7cd4527e AC |
18857 | procedure My_Alloc is |
18858 | begin | |
18859 | A := new T; | |
18860 | end My_Alloc; | |
88e1739c | 18861 | |
7cd4527e | 18862 | procedure My_DeAlloc is |
88e1739c | 18863 | B : Ptr := A; |
7cd4527e | 18864 | begin |
88e1739c | 18865 | Free (B); |
7cd4527e | 18866 | end My_DeAlloc; |
88e1739c | 18867 | |
7cd4527e | 18868 | begin |
88e1739c | 18869 | My_Alloc; |
7cd4527e AC |
18870 | for I in 1 .. 5 loop |
18871 | for J in I .. 5 loop | |
88e1739c | 18872 | My_Alloc; |
7cd4527e | 18873 | end loop; |
88e1739c | 18874 | My_Dealloc; |
7cd4527e AC |
18875 | end loop; |
18876 | end; | |
88e1739c FW |
18877 | @end cartouche |
18878 | @end group | |
18879 | @end smallexample | |
18880 | ||
18881 | @noindent | |
7cd4527e AC |
18882 | The program needs to be compiled with debugging option and linked with |
18883 | @code{gmem} library: | |
18884 | ||
18885 | @smallexample | |
18886 | $ gnatmake -g test_gm -largs -lgmem | |
18887 | @end smallexample | |
18888 | ||
18889 | @noindent | |
18890 | Then we execute the program as usual: | |
88e1739c FW |
18891 | |
18892 | @smallexample | |
7cd4527e | 18893 | $ test_gm |
88e1739c FW |
18894 | @end smallexample |
18895 | ||
7cd4527e AC |
18896 | @noindent |
18897 | Then @code{gnatmem} is invoked simply with | |
88e1739c FW |
18898 | @smallexample |
18899 | $ gnatmem test_gm | |
18900 | @end smallexample | |
18901 | ||
18902 | @noindent | |
7cd4527e | 18903 | which produces the following output (result may vary on different platforms): |
88e1739c FW |
18904 | |
18905 | @smallexample | |
18906 | Global information | |
18907 | ------------------ | |
18908 | Total number of allocations : 18 | |
18909 | Total number of deallocations : 5 | |
18910 | Final Water Mark (non freed mem) : 53.00 Kilobytes | |
18911 | High Water Mark : 56.90 Kilobytes | |
18912 | ||
18913 | Allocation Root # 1 | |
18914 | ------------------- | |
18915 | Number of non freed allocations : 11 | |
18916 | Final Water Mark (non freed mem) : 42.97 Kilobytes | |
18917 | High Water Mark : 46.88 Kilobytes | |
18918 | Backtrace : | |
18919 | test_gm.adb:11 test_gm.my_alloc | |
18920 | ||
18921 | Allocation Root # 2 | |
18922 | ------------------- | |
18923 | Number of non freed allocations : 1 | |
18924 | Final Water Mark (non freed mem) : 10.02 Kilobytes | |
18925 | High Water Mark : 10.02 Kilobytes | |
18926 | Backtrace : | |
18927 | s-secsta.adb:81 system.secondary_stack.ss_init | |
18928 | ||
18929 | Allocation Root # 3 | |
18930 | ------------------- | |
18931 | Number of non freed allocations : 1 | |
18932 | Final Water Mark (non freed mem) : 12 Bytes | |
18933 | High Water Mark : 12 Bytes | |
18934 | Backtrace : | |
18935 | s-secsta.adb:181 system.secondary_stack.ss_init | |
18936 | @end smallexample | |
18937 | ||
18938 | @noindent | |
18939 | Note that the GNAT run time contains itself a certain number of | |
18940 | allocations that have no corresponding deallocation, | |
18941 | as shown here for root #2 and root | |
4d0e4612 | 18942 | #3. This is a normal behavior when the number of non-freed allocations |
7cd4527e | 18943 | is one, it allocates dynamic data structures that the run time needs for |
88e1739c FW |
18944 | the complete lifetime of the program. Note also that there is only one |
18945 | allocation root in the user program with a single line back trace: | |
18946 | test_gm.adb:11 test_gm.my_alloc, whereas a careful analysis of the | |
18947 | program shows that 'My_Alloc' is called at 2 different points in the | |
18948 | source (line 21 and line 24). If those two allocation roots need to be | |
18949 | distinguished, the backtrace depth parameter can be used: | |
18950 | ||
18951 | @smallexample | |
18952 | $ gnatmem 3 test_gm | |
18953 | @end smallexample | |
18954 | ||
18955 | @noindent | |
18956 | which will give the following output: | |
18957 | ||
18958 | @smallexample | |
18959 | Global information | |
18960 | ------------------ | |
18961 | Total number of allocations : 18 | |
18962 | Total number of deallocations : 5 | |
18963 | Final Water Mark (non freed mem) : 53.00 Kilobytes | |
18964 | High Water Mark : 56.90 Kilobytes | |
18965 | ||
18966 | Allocation Root # 1 | |
18967 | ------------------- | |
18968 | Number of non freed allocations : 10 | |
18969 | Final Water Mark (non freed mem) : 39.06 Kilobytes | |
18970 | High Water Mark : 42.97 Kilobytes | |
18971 | Backtrace : | |
18972 | test_gm.adb:11 test_gm.my_alloc | |
18973 | test_gm.adb:24 test_gm | |
18974 | b_test_gm.c:52 main | |
18975 | ||
18976 | Allocation Root # 2 | |
18977 | ------------------- | |
18978 | Number of non freed allocations : 1 | |
18979 | Final Water Mark (non freed mem) : 10.02 Kilobytes | |
18980 | High Water Mark : 10.02 Kilobytes | |
18981 | Backtrace : | |
18982 | s-secsta.adb:81 system.secondary_stack.ss_init | |
18983 | s-secsta.adb:283 <system__secondary_stack___elabb> | |
18984 | b_test_gm.c:33 adainit | |
18985 | ||
18986 | Allocation Root # 3 | |
18987 | ------------------- | |
18988 | Number of non freed allocations : 1 | |
18989 | Final Water Mark (non freed mem) : 3.91 Kilobytes | |
18990 | High Water Mark : 3.91 Kilobytes | |
18991 | Backtrace : | |
18992 | test_gm.adb:11 test_gm.my_alloc | |
18993 | test_gm.adb:21 test_gm | |
18994 | b_test_gm.c:52 main | |
18995 | ||
18996 | Allocation Root # 4 | |
18997 | ------------------- | |
18998 | Number of non freed allocations : 1 | |
18999 | Final Water Mark (non freed mem) : 12 Bytes | |
19000 | High Water Mark : 12 Bytes | |
19001 | Backtrace : | |
19002 | s-secsta.adb:181 system.secondary_stack.ss_init | |
19003 | s-secsta.adb:283 <system__secondary_stack___elabb> | |
19004 | b_test_gm.c:33 adainit | |
19005 | @end smallexample | |
19006 | ||
19007 | @noindent | |
19008 | The allocation root #1 of the first example has been split in 2 roots #1 | |
19009 | and #3 thanks to the more precise associated backtrace. | |
1037b0f4 | 19010 | @end ifclear |
88e1739c FW |
19011 | @end ifclear |
19012 | ||
7e3d710b AC |
19013 | @node Stack Related Facilities |
19014 | @chapter Stack Related Facilities | |
9c8457a7 QO |
19015 | |
19016 | @noindent | |
7e3d710b AC |
19017 | This chapter describes some useful tools associated with stack |
19018 | checking and analysis. In | |
19019 | particular, it deals with dynamic and static stack usage measurements. | |
9c8457a7 QO |
19020 | |
19021 | @menu | |
19022 | * Stack Overflow Checking:: | |
19023 | * Static Stack Usage Analysis:: | |
19024 | * Dynamic Stack Usage Analysis:: | |
19025 | @end menu | |
19026 | ||
19027 | @node Stack Overflow Checking | |
19028 | @section Stack Overflow Checking | |
19029 | @cindex Stack Overflow Checking | |
19030 | @cindex -fstack-check | |
19031 | ||
19032 | @noindent | |
19033 | For most operating systems, @command{gcc} does not perform stack overflow | |
19034 | checking by default. This means that if the main environment task or | |
19035 | some other task exceeds the available stack space, then unpredictable | |
7e3d710b AC |
19036 | behavior will occur. Most native systems offer some level of protection by |
19037 | adding a guard page at the end of each task stack. This mechanism is usually | |
19038 | not enough for dealing properly with stack overflow situations because | |
19039 | a large local variable could ``jump'' above the guard page. | |
19040 | Furthermore, when the | |
19041 | guard page is hit, there may not be any space left on the stack for executing | |
19042 | the exception propagation code. Enabling stack checking avoids | |
19043 | such situations. | |
9c8457a7 QO |
19044 | |
19045 | To activate stack checking, compile all units with the gcc option | |
19046 | @option{-fstack-check}. For example: | |
19047 | ||
19048 | @smallexample | |
19049 | gcc -c -fstack-check package1.adb | |
19050 | @end smallexample | |
19051 | ||
19052 | @noindent | |
19053 | Units compiled with this option will generate extra instructions to check | |
19054 | that any use of the stack (for procedure calls or for declaring local | |
7e3d710b | 19055 | variables in declare blocks) does not exceed the available stack space. |
9c8457a7 QO |
19056 | If the space is exceeded, then a @code{Storage_Error} exception is raised. |
19057 | ||
7e3d710b AC |
19058 | For declared tasks, the stack size is controlled by the size |
19059 | given in an applicable @code{Storage_Size} pragma or by the value specified | |
19060 | at bind time with @option{-d} (@pxref{Switches for gnatbind}) or is set to | |
19061 | the default size as defined in the GNAT runtime otherwise. | |
9c8457a7 QO |
19062 | |
19063 | For the environment task, the stack size depends on | |
7e3d710b AC |
19064 | system defaults and is unknown to the compiler. Stack checking |
19065 | may still work correctly if a fixed | |
9c8457a7 | 19066 | size stack is allocated, but this cannot be guaranteed. |
54df6fd9 | 19067 | @ifclear vms |
9c8457a7 QO |
19068 | To ensure that a clean exception is signalled for stack |
19069 | overflow, set the environment variable | |
443b3472 | 19070 | @env{GNAT_STACK_LIMIT} to indicate the maximum |
9c8457a7 QO |
19071 | stack area that can be used, as in: |
19072 | @cindex GNAT_STACK_LIMIT | |
19073 | ||
19074 | @smallexample | |
19075 | SET GNAT_STACK_LIMIT 1600 | |
19076 | @end smallexample | |
19077 | ||
19078 | @noindent | |
19079 | The limit is given in kilobytes, so the above declaration would | |
19080 | set the stack limit of the environment task to 1.6 megabytes. | |
19081 | Note that the only purpose of this usage is to limit the amount | |
19082 | of stack used by the environment task. If it is necessary to | |
19083 | increase the amount of stack for the environment task, then this | |
19084 | is an operating systems issue, and must be addressed with the | |
19085 | appropriate operating systems commands. | |
54df6fd9 VC |
19086 | @end ifclear |
19087 | @ifset vms | |
19088 | To have a fixed size stack in the environment task, the stack must be put | |
19089 | in the P0 address space and its size specified. Use these switches to | |
19090 | create a p0 image: | |
19091 | ||
19092 | @smallexample | |
19093 | gnatmake my_progs -largs "-Wl,--opt=STACK=4000,/p0image" | |
19094 | @end smallexample | |
19095 | ||
19096 | @noindent | |
19097 | The quotes are required to keep case. The number after @samp{STACK=} is the | |
19098 | size of the environmental task stack in pagelets (512 bytes). In this example | |
19099 | the stack size is about 2 megabytes. | |
19100 | ||
19101 | @noindent | |
19102 | A consequence of the @option{/p0image} qualifier is also to makes RMS buffers | |
19103 | be placed in P0 space. Refer to @cite{HP OpenVMS Linker Utility Manual} for | |
19104 | more details about the @option{/p0image} qualifier and the @option{stack} | |
19105 | option. | |
70c0422d AC |
19106 | |
19107 | @noindent | |
19108 | On Itanium platforms, you can instead assign the @samp{GNAT_STACK_SIZE} and | |
19109 | @samp{GNAT_RBS_SIZE} logicals to the size of the primary and register | |
19110 | stack in kilobytes. For example: | |
19111 | ||
19112 | @smallexample | |
19113 | $ define GNAT_RBS_SIZE 1024 ! Limit the RBS size to 1MB. | |
19114 | @end smallexample | |
54df6fd9 | 19115 | @end ifset |
9c8457a7 QO |
19116 | |
19117 | @node Static Stack Usage Analysis | |
19118 | @section Static Stack Usage Analysis | |
19119 | @cindex Static Stack Usage Analysis | |
19120 | @cindex -fstack-usage | |
19121 | ||
19122 | @noindent | |
7e3d710b AC |
19123 | A unit compiled with @option{-fstack-usage} will generate an extra file |
19124 | that specifies | |
19125 | the maximum amount of stack used, on a per-function basis. | |
19126 | The file has the same | |
19127 | basename as the target object file with a @file{.su} extension. | |
19128 | Each line of this file is made up of three fields: | |
9c8457a7 QO |
19129 | |
19130 | @itemize | |
19131 | @item | |
19132 | The name of the function. | |
19133 | @item | |
19134 | A number of bytes. | |
19135 | @item | |
19136 | One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}. | |
19137 | @end itemize | |
19138 | ||
7e3d710b AC |
19139 | The second field corresponds to the size of the known part of the function |
19140 | frame. | |
19141 | ||
19142 | The qualifier @code{static} means that the function frame size | |
19143 | is purely static. | |
19144 | It usually means that all local variables have a static size. | |
19145 | In this case, the second field is a reliable measure of the function stack | |
19146 | utilization. | |
19147 | ||
19148 | The qualifier @code{dynamic} means that the function frame size is not static. | |
19149 | It happens mainly when some local variables have a dynamic size. When this | |
19150 | qualifier appears alone, the second field is not a reliable measure | |
19151 | of the function stack analysis. When it is qualified with @code{bounded}, it | |
19152 | means that the second field is a reliable maximum of the function stack | |
19153 | utilization. | |
9c8457a7 | 19154 | |
56e94186 AC |
19155 | A unit compiled with @option{-Wstack-usage} will issue a warning for each |
19156 | subprogram whose stack usage might be larger than the specified amount of | |
19157 | bytes. The wording is in keeping with the qualifier documented above. | |
19158 | ||
9c8457a7 QO |
19159 | @node Dynamic Stack Usage Analysis |
19160 | @section Dynamic Stack Usage Analysis | |
19161 | ||
19162 | @noindent | |
19163 | It is possible to measure the maximum amount of stack used by a task, by | |
19164 | adding a switch to @command{gnatbind}, as: | |
19165 | ||
19166 | @smallexample | |
19167 | $ gnatbind -u0 file | |
19168 | @end smallexample | |
19169 | ||
19170 | @noindent | |
7e3d710b AC |
19171 | With this option, at each task termination, its stack usage is output on |
19172 | @file{stderr}. | |
19173 | It is not always convenient to output the stack usage when the program | |
19174 | is still running. Hence, it is possible to delay this output until program | |
19175 | termination. for a given number of tasks specified as the argument of the | |
1992bbd9 | 19176 | @option{-u} option. For instance: |
9c8457a7 QO |
19177 | |
19178 | @smallexample | |
19179 | $ gnatbind -u100 file | |
19180 | @end smallexample | |
19181 | ||
19182 | @noindent | |
7e3d710b AC |
19183 | will buffer the stack usage information of the first 100 tasks to terminate and |
19184 | output this info at program termination. Results are displayed in four | |
19185 | columns: | |
9c8457a7 QO |
19186 | |
19187 | @noindent | |
2ba7e31e | 19188 | Index | Task Name | Stack Size | Stack Usage |
9c8457a7 QO |
19189 | |
19190 | @noindent | |
19191 | where: | |
19192 | ||
19193 | @table @emph | |
7e3d710b AC |
19194 | @item Index |
19195 | is a number associated with each task. | |
9c8457a7 | 19196 | |
7e3d710b | 19197 | @item Task Name |
9c8457a7 QO |
19198 | is the name of the task analyzed. |
19199 | ||
7e3d710b | 19200 | @item Stack Size |
e08b38f5 | 19201 | is the maximum size for the stack. |
9c8457a7 | 19202 | |
91c2cbdb AC |
19203 | @item Stack Usage |
19204 | is the measure done by the stack analyzer. In order to prevent overflow, the stack | |
19205 | is not entirely analyzed, and it's not possible to know exactly how | |
2ba7e31e | 19206 | much has actually been used. |
9c8457a7 QO |
19207 | |
19208 | @end table | |
19209 | ||
19210 | @noindent | |
8dd07840 | 19211 | The environment task stack, e.g., the stack that contains the main unit, is |
9c8457a7 QO |
19212 | only processed when the environment variable GNAT_STACK_LIMIT is set. |
19213 | ||
24558db8 | 19214 | @noindent |
1f9939b5 AC |
19215 | The package @code{GNAT.Task_Stack_Usage} provides facilities to get |
19216 | stack usage reports at run-time. See its body for the details. | |
e08b38f5 | 19217 | |
1037b0f4 | 19218 | @ifclear FSFEDITION |
e08b38f5 VC |
19219 | @c ********************************* |
19220 | @c * GNATCHECK * | |
7e3d710b | 19221 | @c ********************************* |
c2658843 AC |
19222 | @node Verifying Properties with gnatcheck |
19223 | @chapter Verifying Properties with @command{gnatcheck} | |
7e3d710b | 19224 | @findex gnatcheck |
e08b38f5 | 19225 | @cindex @command{gnatcheck} |
7e3d710b AC |
19226 | |
19227 | @noindent | |
19228 | The @command{gnatcheck} tool is an ASIS-based utility that checks properties | |
19229 | of Ada source files according to a given set of semantic rules. | |
e08b38f5 | 19230 | @cindex ASIS |
7e3d710b AC |
19231 | |
19232 | In order to check compliance with a given rule, @command{gnatcheck} has to | |
19233 | semantically analyze the Ada sources. | |
19234 | Therefore, checks can only be performed on | |
19235 | legal Ada units. Moreover, when a unit depends semantically upon units located | |
19236 | outside the current directory, the source search path has to be provided when | |
19237 | calling @command{gnatcheck}, either through a specified project file or | |
229db351 | 19238 | through @command{gnatcheck} switches. |
7e3d710b | 19239 | |
229db351 | 19240 | For full details, refer to @cite{GNATcheck Reference Manual} document. |
1037b0f4 | 19241 | @end ifclear |
ee13bdc7 | 19242 | |
1037b0f4 | 19243 | @ifclear FSFEDITION |
e08b38f5 | 19244 | @c ********************************* |
c2658843 AC |
19245 | @node Creating Sample Bodies with gnatstub |
19246 | @chapter Creating Sample Bodies with @command{gnatstub} | |
e08b38f5 VC |
19247 | @findex gnatstub |
19248 | ||
19249 | @noindent | |
19250 | @command{gnatstub} creates body stubs, that is, empty but compilable bodies | |
19251 | for library unit declarations. | |
19252 | ||
19253 | Note: to invoke @code{gnatstub} with a project file, use the @code{gnat} | |
19254 | driver (see @ref{The GNAT Driver and Project Files}). | |
19255 | ||
19256 | To create a body stub, @command{gnatstub} has to compile the library | |
19257 | unit declaration. Therefore, bodies can be created only for legal | |
19258 | library units. Moreover, if a library unit depends semantically upon | |
19259 | units located outside the current directory, you have to provide | |
7cd4527e AC |
19260 | the source search path when calling @command{gnatstub}, see the description |
19261 | of @command{gnatstub} switches below. | |
88e1739c | 19262 | |
f559e62f AC |
19263 | By default, all the program unit body stubs generated by @code{gnatstub} |
19264 | raise the predefined @code{Program_Error} exception, which will catch | |
19265 | accidental calls of generated stubs. This behavior can be changed with | |
19266 | option @option{^--no-exception^/NO_EXCEPTION^} (see below). | |
19267 | ||
88e1739c FW |
19268 | @menu |
19269 | * Running gnatstub:: | |
19270 | * Switches for gnatstub:: | |
19271 | @end menu | |
19272 | ||
19273 | @node Running gnatstub | |
7cd4527e | 19274 | @section Running @command{gnatstub} |
88e1739c FW |
19275 | |
19276 | @noindent | |
5972791c | 19277 | @command{gnatstub} has a command-line interface of the form: |
88e1739c FW |
19278 | |
19279 | @smallexample | |
e074d476 AC |
19280 | @c $ gnatstub @ovar{switches} @var{filename} @ovar{directory} |
19281 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
5875f8d6 | 19282 | $ gnatstub @r{[}@var{switches}@r{]} @var{filename} @r{[}@var{directory}@r{]} @r{[}-cargs @var{gcc_switches}@r{]} |
88e1739c FW |
19283 | @end smallexample |
19284 | ||
19285 | @noindent | |
19286 | where | |
66bfd481 | 19287 | @table @var |
88e1739c FW |
19288 | @item filename |
19289 | is the name of the source file that contains a library unit declaration | |
7cd4527e AC |
19290 | for which a body must be created. The file name may contain the path |
19291 | information. | |
19292 | The file name does not have to follow the GNAT file name conventions. If the | |
19293 | name | |
19294 | does not follow GNAT file naming conventions, the name of the body file must | |
19295 | be provided | |
19296 | explicitly as the value of the @option{^-o^/BODY=^@var{body-name}} option. | |
19297 | If the file name follows the GNAT file naming | |
19298 | conventions and the name of the body file is not provided, | |
19299 | @command{gnatstub} | |
19300 | creates the name | |
19301 | of the body file from the argument file name by replacing the @file{.ads} | |
19302 | suffix | |
19303 | with the @file{.adb} suffix. | |
88e1739c FW |
19304 | |
19305 | @item directory | |
7cd4527e AC |
19306 | indicates the directory in which the body stub is to be placed (the default |
19307 | is the | |
88e1739c FW |
19308 | current directory) |
19309 | ||
5875f8d6 AC |
19310 | @item @samp{@var{gcc_switches}} is a list of switches for |
19311 | @command{gcc}. They will be passed on to all compiler invocations made by | |
4674dd21 | 19312 | @command{gnatstub} to generate the ASIS trees. Here you can provide |
5875f8d6 | 19313 | @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, |
4b6133ea AC |
19314 | use the @option{-gnatec} switch to set the configuration file, |
19315 | use the @option{-gnat05} switch if sources should be compiled in | |
19316 | Ada 2005 mode etc. | |
5875f8d6 | 19317 | |
88e1739c FW |
19318 | @item switches |
19319 | is an optional sequence of switches as described in the next section | |
19320 | @end table | |
19321 | ||
19322 | @node Switches for gnatstub | |
7cd4527e | 19323 | @section Switches for @command{gnatstub} |
88e1739c | 19324 | |
7cd4527e AC |
19325 | @table @option |
19326 | @c !sort! | |
88e1739c | 19327 | |
327b1ba4 AC |
19328 | @item --version |
19329 | @cindex @option{--version} @command{gnatstub} | |
19330 | Display Copyright and version, then exit disregarding all other options. | |
19331 | ||
19332 | @item --help | |
19333 | @cindex @option{--help} @command{gnatstub} | |
19334 | Display usage, then exit disregarding all other options. | |
19335 | ||
350b83cc AC |
19336 | @item -P @var{file} |
19337 | @cindex @option{-P} @command{gnatstub} | |
19338 | Indicates the name of the project file that describes the set of sources | |
19339 | to be processed. | |
19340 | ||
19341 | @item -X@var{name}=@var{value} | |
19342 | @cindex @option{-X} @command{gnatstub} | |
19343 | Indicates that external variable @var{name} in the argument project | |
f1a3590e | 19344 | has the value @var{value}. Has no effect if no project is specified as |
350b83cc AC |
19345 | tool argument. |
19346 | ||
88e1739c | 19347 | @item ^-f^/FULL^ |
7cd4527e AC |
19348 | @cindex @option{^-f^/FULL^} (@command{gnatstub}) |
19349 | If the destination directory already contains a file with the name of the | |
19350 | body file | |
88e1739c FW |
19351 | for the argument spec file, replace it with the generated body stub. |
19352 | ||
19353 | @item ^-hs^/HEADER=SPEC^ | |
7cd4527e AC |
19354 | @cindex @option{^-hs^/HEADER=SPEC^} (@command{gnatstub}) |
19355 | Put the comment header (i.e., all the comments preceding the | |
88e1739c FW |
19356 | compilation unit) from the source of the library unit declaration |
19357 | into the body stub. | |
19358 | ||
19359 | @item ^-hg^/HEADER=GENERAL^ | |
7cd4527e | 19360 | @cindex @option{^-hg^/HEADER=GENERAL^} (@command{gnatstub}) |
88e1739c FW |
19361 | Put a sample comment header into the body stub. |
19362 | ||
da508766 RD |
19363 | @item ^--header-file=@var{filename}^/FROM_HEADER_FILE=@var{filename}^ |
19364 | @cindex @option{^--header-file^/FROM_HEADER_FILE=^} (@command{gnatstub}) | |
19365 | Use the content of the file as the comment header for a generated body stub. | |
19366 | ||
7cd4527e | 19367 | @ifclear vms |
88e1739c | 19368 | @item -IDIR |
7cd4527e AC |
19369 | @cindex @option{-IDIR} (@command{gnatstub}) |
19370 | @itemx -I- | |
19371 | @cindex @option{-I-} (@command{gnatstub}) | |
19372 | @end ifclear | |
19373 | @ifset vms | |
19374 | @item /NOCURRENT_DIRECTORY | |
19375 | @cindex @option{/NOCURRENT_DIRECTORY} (@command{gnatstub}) | |
19376 | @end ifset | |
19377 | ^These switches have ^This switch has^ the same meaning as in calls to | |
19378 | @command{gcc}. | |
19379 | ^They define ^It defines ^ the source search path in the call to | |
19380 | @command{gcc} issued | |
19381 | by @command{gnatstub} to compile an argument source file. | |
19382 | ||
19383 | @item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE=^@var{PATH} | |
19384 | @cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@command{gnatstub}) | |
19385 | This switch has the same meaning as in calls to @command{gcc}. | |
19386 | It defines the additional configuration file to be passed to the call to | |
19387 | @command{gcc} issued | |
19388 | by @command{gnatstub} to compile an argument source file. | |
19389 | ||
19390 | @item ^-gnatyM^/MAX_LINE_LENGTH=^@var{n} | |
19391 | @cindex @option{^-gnatyM^/MAX_LINE_LENGTH^} (@command{gnatstub}) | |
08988ed9 AC |
19392 | (@var{n} is a non-negative integer). Set the maximum line length that is |
19393 | allowed in a source file. The default is 79. The maximum value that can be | |
5950a3ac AC |
19394 | specified is 32767. Note that in the special case of configuration |
19395 | pragma files, the maximum is always 32767 regardless of whether or | |
19396 | not this switch appears. | |
7cd4527e AC |
19397 | |
19398 | @item ^-gnaty^/STYLE_CHECKS=^@var{n} | |
19399 | @cindex @option{^-gnaty^/STYLE_CHECKS=^} (@command{gnatstub}) | |
19400 | (@var{n} is a non-negative integer from 1 to 9). Set the indentation level in | |
19401 | the generated body sample to @var{n}. | |
19402 | The default indentation is 3. | |
19403 | ||
19404 | @item ^-gnatyo^/ORDERED_SUBPROGRAMS^ | |
354c3840 | 19405 | @cindex @option{^-gnatyo^/ORDERED_SUBPROGRAMS^} (@command{gnatstub}) |
7cd4527e AC |
19406 | Order local bodies alphabetically. (By default local bodies are ordered |
19407 | in the same way as the corresponding local specs in the argument spec file.) | |
88e1739c FW |
19408 | |
19409 | @item ^-i^/INDENTATION=^@var{n} | |
7cd4527e AC |
19410 | @cindex @option{^-i^/INDENTATION^} (@command{gnatstub}) |
19411 | Same as @option{^-gnaty^/STYLE_CHECKS=^@var{n}} | |
88e1739c FW |
19412 | |
19413 | @item ^-k^/TREE_FILE=SAVE^ | |
7cd4527e AC |
19414 | @cindex @option{^-k^/TREE_FILE=SAVE^} (@command{gnatstub}) |
19415 | Do not remove the tree file (i.e., the snapshot of the compiler internal | |
19416 | structures used by @command{gnatstub}) after creating the body stub. | |
88e1739c FW |
19417 | |
19418 | @item ^-l^/LINE_LENGTH=^@var{n} | |
7cd4527e AC |
19419 | @cindex @option{^-l^/LINE_LENGTH^} (@command{gnatstub}) |
19420 | Same as @option{^-gnatyM^/MAX_LINE_LENGTH=^@var{n}} | |
19421 | ||
f559e62f AC |
19422 | @item ^--no-exception^/NO_EXCEPTION^ |
19423 | @cindex @option{^--no-exception^/NO_EXCEPTION^} (@command{gnatstub}) | |
a3068ca6 | 19424 | Avoid raising PROGRAM_ERROR in the generated bodies of program unit stubs. |
f559e62f AC |
19425 | This is not always possible for function stubs. |
19426 | ||
a36c1c3e RD |
19427 | @item ^--no-local-header^/NO_LOCAL_HEADER^ |
19428 | @cindex @option{^--no-local-header^/NO_LOCAL_HEADER^} (@command{gnatstub}) | |
19429 | Do not place local comment header with unit name before body stub for a | |
19430 | unit. | |
19431 | ||
f559e62f | 19432 | @item ^-o ^/BODY=^@var{body-name} |
7cd4527e AC |
19433 | @cindex @option{^-o^/BODY^} (@command{gnatstub}) |
19434 | Body file name. This should be set if the argument file name does not | |
19435 | follow | |
19436 | the GNAT file naming | |
19437 | conventions. If this switch is omitted the default name for the body will be | |
19438 | obtained | |
19439 | from the argument file name according to the GNAT file naming conventions. | |
88e1739c FW |
19440 | |
19441 | @item ^-q^/QUIET^ | |
7cd4527e | 19442 | @cindex @option{^-q^/QUIET^} (@command{gnatstub}) |
88e1739c | 19443 | Quiet mode: do not generate a confirmation when a body is |
7cd4527e AC |
19444 | successfully created, and do not generate a message when a body is not |
19445 | required for an | |
88e1739c FW |
19446 | argument unit. |
19447 | ||
19448 | @item ^-r^/TREE_FILE=REUSE^ | |
7cd4527e AC |
19449 | @cindex @option{^-r^/TREE_FILE=REUSE^} (@command{gnatstub}) |
19450 | Reuse the tree file (if it exists) instead of creating it. Instead of | |
19451 | creating the tree file for the library unit declaration, @command{gnatstub} | |
88e1739c | 19452 | tries to find it in the current directory and use it for creating |
7cd4527e AC |
19453 | a body. If the tree file is not found, no body is created. This option |
19454 | also implies @option{^-k^/SAVE^}, whether or not | |
19455 | the latter is set explicitly. | |
88e1739c FW |
19456 | |
19457 | @item ^-t^/TREE_FILE=OVERWRITE^ | |
7cd4527e AC |
19458 | @cindex @option{^-t^/TREE_FILE=OVERWRITE^} (@command{gnatstub}) |
19459 | Overwrite the existing tree file. If the current directory already | |
19460 | contains the file which, according to the GNAT file naming rules should | |
19461 | be considered as a tree file for the argument source file, | |
19462 | @command{gnatstub} | |
19463 | will refuse to create the tree file needed to create a sample body | |
19464 | unless this option is set. | |
88e1739c FW |
19465 | |
19466 | @item ^-v^/VERBOSE^ | |
7cd4527e | 19467 | @cindex @option{^-v^/VERBOSE^} (@command{gnatstub}) |
88e1739c FW |
19468 | Verbose mode: generate version information. |
19469 | ||
19470 | @end table | |
1037b0f4 | 19471 | @end ifclear |
88e1739c | 19472 | |
1037b0f4 | 19473 | @ifclear FSFEDITION |
8417f4b2 | 19474 | @c ********************************* |
c2658843 AC |
19475 | @node Creating Unit Tests with gnattest |
19476 | @chapter Creating Unit Tests with @command{gnattest} | |
8417f4b2 AC |
19477 | @findex gnattest |
19478 | ||
19479 | @noindent | |
fc7d1319 | 19480 | @command{gnattest} is an ASIS-based utility that creates unit-test skeletons |
1a36a0cd | 19481 | as well as a test driver infrastructure (harness). @command{gnattest} creates |
fc7d1319 | 19482 | a skeleton for each visible subprogram in the packages under consideration when |
1a36a0cd | 19483 | they do not exist already. |
8417f4b2 | 19484 | |
5972791c | 19485 | In order to process source files from a project, @command{gnattest} has to |
fc7d1319 | 19486 | semantically analyze the sources. Therefore, test skeletons can only be |
5972791c AC |
19487 | generated for legal Ada units. If a unit is dependent on other units, |
19488 | those units should be among the source files of the project or of other projects | |
8417f4b2 AC |
19489 | imported by this one. |
19490 | ||
fc7d1319 AC |
19491 | Generated skeletons and harnesses are based on the AUnit testing framework. |
19492 | AUnit is an Ada adaptation of the xxxUnit testing frameworks, similar to JUnit | |
19493 | for Java or CppUnit for C++. While it is advised that gnattest users read | |
19494 | the AUnit manual, deep knowledge of AUnit is not necessary for using gnattest. | |
19495 | For correct operation of @command{gnattest}, AUnit should be installed and | |
19496 | aunit.gpr must be on the project path. This happens automatically when Aunit | |
19497 | is installed at its default location. | |
8417f4b2 AC |
19498 | @menu |
19499 | * Running gnattest:: | |
19500 | * Switches for gnattest:: | |
19501 | * Project Attributes for gnattest:: | |
1a36a0cd | 19502 | * Simple Example:: |
5972791c | 19503 | * Setting Up and Tearing Down the Testing Environment:: |
1a36a0cd | 19504 | * Regenerating Tests:: |
8417f4b2 AC |
19505 | * Default Test Behavior:: |
19506 | * Testing Primitive Operations of Tagged Types:: | |
5972791c | 19507 | * Testing Inheritance:: |
1a36a0cd | 19508 | * Tagged Types Substitutability Testing:: |
8417f4b2 AC |
19509 | * Testing with Contracts:: |
19510 | * Additional Tests:: | |
473e20df | 19511 | @ifclear vms |
a1e16658 | 19512 | * Support for other platforms/run-times:: |
473e20df | 19513 | @end ifclear |
8417f4b2 AC |
19514 | * Current Limitations:: |
19515 | @end menu | |
19516 | ||
19517 | @node Running gnattest | |
19518 | @section Running @command{gnattest} | |
19519 | ||
19520 | @noindent | |
5972791c | 19521 | @command{gnattest} has a command-line interface of the form |
8417f4b2 AC |
19522 | |
19523 | @smallexample | |
1a36a0cd | 19524 | @c $ gnattest @var{-Pprojname} @ovar{switches} @ovar{filename} @ovar{directory} |
8417f4b2 | 19525 | @c Expanding @ovar macro inline (explanation in macro def comments) |
1a36a0cd | 19526 | $ gnattest @var{-Pprojname} @r{[}@var{--harness-dir=dirname}@r{]} @r{[}@var{switches}@r{]} @r{[}@var{filename}@r{]} @r{[}-cargs @var{gcc_switches}@r{]} |
8417f4b2 AC |
19527 | @end smallexample |
19528 | ||
19529 | @noindent | |
19530 | where | |
19531 | @table @var | |
19532 | ||
19533 | @item -Pprojname | |
5972791c AC |
19534 | specifies the project defining the location of source files. When no |
19535 | file names are provided on the command line, all sources in the project | |
19536 | are used as input. This switch is required. | |
8417f4b2 | 19537 | |
8417f4b2 | 19538 | @item filename |
5972791c | 19539 | is the name of the source file containing the library unit package declaration |
0df7e2d0 AC |
19540 | for which a test package will be created. The file name may be given with a |
19541 | path. | |
8417f4b2 | 19542 | |
0df7e2d0 AC |
19543 | @item @samp{@var{gcc_switches}} |
19544 | is a list of switches for | |
5972791c | 19545 | @command{gcc}. These switches will be passed on to all compiler invocations |
fc7d1319 | 19546 | made by @command{gnattest} to generate a set of ASIS trees. Here you can provide |
8417f4b2 AC |
19547 | @option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, |
19548 | use the @option{-gnatec} switch to set the configuration file, | |
19549 | use the @option{-gnat05} switch if sources should be compiled in | |
5972791c | 19550 | Ada 2005 mode, etc. |
8417f4b2 AC |
19551 | |
19552 | @item switches | |
5972791c | 19553 | is an optional sequence of switches as described in the next section. |
8417f4b2 AC |
19554 | |
19555 | @end table | |
19556 | ||
1a36a0cd AC |
19557 | @command{gnattest} results can be found in two different places. |
19558 | ||
19559 | @itemize @bullet | |
0df7e2d0 | 19560 | @item automatic harness: |
fc7d1319 AC |
19561 | the harness code, which is located by default in "gnattest/harness" directory |
19562 | that is created in the object directory of corresponding project file. All of | |
19563 | this code is generated completely automatically and can be destroyed and | |
19564 | regenerated at will. It is not recommended to modify this code manually, since | |
19565 | it could easily be overridden by mistake. The entry point in the harness code is | |
19566 | the project file named @command{test_driver.gpr}. Tests can be compiled and run | |
19567 | using a command such as: | |
1a36a0cd AC |
19568 | |
19569 | @smallexample | |
19570 | gnatmake -P<harness-dir>/test_driver | |
19571 | test_runner | |
19572 | @end smallexample | |
19573 | ||
bdf69d33 AC |
19574 | Note that you might need to specify the necessary values of scenario variables |
19575 | when you are not using the AUnit defaults. | |
19576 | ||
fc7d1319 AC |
19577 | @item actual unit test skeletons: |
19578 | a test skeleton for each visible subprogram is created in a separate file, if it | |
1a36a0cd | 19579 | doesn't exist already. By default, those separate test files are located in a |
fc7d1319 AC |
19580 | "gnattest/tests" directory that is created in the object directory of |
19581 | corresponding project file. For example, if a source file my_unit.ads in | |
19582 | directory src contains a visible subprogram Proc, then the corresponding unit | |
19583 | test will be found in file src/tests/my_unit-test_data-tests-proc_<code>.adb. | |
19584 | <code> is a signature encoding used to differentiate test names in case of | |
19585 | overloading. | |
19586 | ||
19587 | Note that if the project already has both my_unit.ads and my_unit-test_data.ads, | |
0df7e2d0 | 19588 | this will cause a name conflict with the generated test package. |
1a36a0cd AC |
19589 | @end itemize |
19590 | ||
8417f4b2 AC |
19591 | @node Switches for gnattest |
19592 | @section Switches for @command{gnattest} | |
19593 | ||
19594 | @table @option | |
19595 | @c !sort! | |
19596 | ||
19597 | @item --harness-only | |
19598 | @cindex @option{--harness-only} (@command{gnattest}) | |
19599 | When this option is given, @command{gnattest} creates a harness for all | |
5972791c | 19600 | sources, treating them as test packages. |
8417f4b2 AC |
19601 | |
19602 | @item --additional-tests=@var{projname} | |
19603 | @cindex @option{--additional-tests} (@command{gnattest}) | |
19604 | Sources described in @var{projname} are considered potential additional | |
19605 | manual tests to be added to the test suite. | |
19606 | ||
19607 | @item -r | |
19608 | @cindex @option{-r} (@command{gnattest}) | |
5972791c | 19609 | Recursively consider all sources from all projects. |
8417f4b2 | 19610 | |
bdf69d33 AC |
19611 | @item -X@var{name=value} |
19612 | @cindex @option{-X} (@command{gnattest}) | |
19613 | Indicate that external variable @var{name} has the value @var{value}. | |
19614 | ||
8417f4b2 AC |
19615 | @item -q |
19616 | @cindex @option{-q} (@command{gnattest}) | |
5972791c | 19617 | Suppresses noncritical output messages. |
8417f4b2 AC |
19618 | |
19619 | @item -v | |
19620 | @cindex @option{-v} (@command{gnattest}) | |
5972791c | 19621 | Verbose mode: generates version information. |
8417f4b2 | 19622 | |
fc7d1319 AC |
19623 | @item --validate-type-extensions |
19624 | @cindex @option{--validate-type-extensions} (@command{gnattest}) | |
19625 | Enables substitution check: run all tests from all parents in order | |
8417f4b2 AC |
19626 | to check substitutability. |
19627 | ||
fc7d1319 AC |
19628 | @item --skeleton-default=@var{val} |
19629 | @cindex @option{--skeleton-default} (@command{gnattest}) | |
19630 | Specifies the default behavior of generated skeletons. @var{val} can be either | |
8417f4b2 AC |
19631 | "fail" or "pass", "fail" being the default. |
19632 | ||
a1efcc17 AC |
19633 | @item --passed-tests=@var{val} |
19634 | @cindex @option{--skeleton-default} (@command{gnattest}) | |
19635 | Specifies whether or not passed tests should be shown. @var{val} can be either | |
19636 | "show" or "hide", "show" being the default. | |
19637 | ||
19638 | ||
fc7d1319 AC |
19639 | @item --tests-root=@var{dirname} |
19640 | @cindex @option{--tests-root} (@command{gnattest}) | |
5972791c AC |
19641 | The directory hierarchy of tested sources is recreated in the @var{dirname} |
19642 | directory, and test packages are placed in corresponding directories. | |
fc7d1319 AC |
19643 | If the @var{dirname} is a relative path, it is considered relative to the object |
19644 | directory of the project file. When all sources from all projects are taken | |
19645 | recursively from all projects, directory hierarchies of tested sources are | |
19646 | recreated for each project in their object directories and test packages are | |
19647 | placed accordingly. | |
8417f4b2 AC |
19648 | |
19649 | @item --subdir=@var{dirname} | |
19650 | @cindex @option{--subdir} (@command{gnattest}) | |
fc7d1319 AC |
19651 | Test packages are placed in subdirectories. |
19652 | ||
19653 | @item --tests-dir=@var{dirname} | |
19654 | @cindex @option{--tests-dir} (@command{gnattest}) | |
19655 | All test packages are placed in the @var{dirname} directory. | |
19656 | If the @var{dirname} is a relative path, it is considered relative to the object | |
19657 | directory of the project file. When all sources from all projects are taken | |
19658 | recursively from all projects, @var{dirname} directories are created for each | |
19659 | project in their object directories and test packages are placed accordingly. | |
19660 | ||
19661 | @item --harness-dir=@var{dirname} | |
19662 | @cindex @option{--harness-dir} (@command{gnattest}) | |
19663 | specifies the directory that will hold the harness packages and project file | |
19664 | for the test driver. If the @var{dirname} is a relative path, it is considered | |
19665 | relative to the object directory of the project file. | |
8417f4b2 | 19666 | |
2fe2920e AC |
19667 | @item --separates |
19668 | @cindex @option{--separates} (@command{gnattest}) | |
2a328c94 AC |
19669 | Bodies of all test routines are generated as separates. Note that this mode is |
19670 | kept for compatibility reasons only and it is not advised to use it due to | |
19671 | possible problems with hash in names of test skeletons when using an | |
19672 | inconsistent casing. Separate test skeletons can be incorporated to monolith | |
19673 | test package with improved hash being used by using @option{--transition} | |
19674 | switch. | |
2fe2920e AC |
19675 | |
19676 | ||
19677 | @item --transition | |
19678 | @cindex @option{--transition} (@command{gnattest}) | |
19679 | This allows transition from separate test routines to monolith test packages. | |
19680 | All matching test routines are overwritten with contents of corresponding | |
19681 | separates. Note that if separate test routines had any manually added with | |
19682 | clauses they will be moved to the test package body as is and have to be moved | |
19683 | by hand. | |
19684 | ||
8417f4b2 AC |
19685 | @end table |
19686 | ||
fc7d1319 AC |
19687 | @option{--tests_root}, @option{--subdir} and @option{--tests-dir} switches are |
19688 | mutually exclusive. | |
8417f4b2 AC |
19689 | |
19690 | @node Project Attributes for gnattest | |
19691 | @section Project Attributes for @command{gnattest} | |
19692 | ||
19693 | @noindent | |
19694 | ||
5972791c | 19695 | Most of the command-line options can also be passed to the tool by adding |
8417f4b2 | 19696 | special attributes to the project file. Those attributes should be put in |
5972791c | 19697 | package gnattest. Here is the list of attributes: |
8417f4b2 AC |
19698 | |
19699 | @itemize @bullet | |
19700 | ||
fc7d1319 AC |
19701 | @item Tests_Root |
19702 | is used to select the same output mode as with the --tests-root option. | |
19703 | This attribute cannot be used together with Subdir or Tests_Dir. | |
8417f4b2 | 19704 | |
fc7d1319 | 19705 | @item Subdir |
5972791c | 19706 | is used to select the same output mode as with the --subdir option. |
fc7d1319 AC |
19707 | This attribute cannot be used together with Tests_Root or Tests_Dir. |
19708 | ||
19709 | @item Tests_Dir | |
19710 | is used to select the same output mode as with the --tests-dir option. | |
19711 | This attribute cannot be used together with Subdir or Tests_Root. | |
8417f4b2 AC |
19712 | |
19713 | @item Harness_Dir | |
5972791c | 19714 | is used to specify the directory in which to place harness packages and project |
8417f4b2 AC |
19715 | file for the test driver, otherwise specified by --harness-dir. |
19716 | ||
19717 | @item Additional_Tests | |
5972791c | 19718 | is used to specify the project file, otherwise given by |
8417f4b2 AC |
19719 | --additional-tests switch. |
19720 | ||
fc7d1319 AC |
19721 | @item Skeletons_Default |
19722 | is used to specify the default behaviour of test skeletons, otherwise | |
19723 | specified by --skeleton-default option. The value of this attribute | |
5972791c | 19724 | should be either "pass" or "fail". |
8417f4b2 AC |
19725 | |
19726 | @end itemize | |
19727 | ||
5972791c | 19728 | Each of those attributes can be overridden from the command line if needed. |
8417f4b2 AC |
19729 | Other @command{gnattest} switches can also be passed via the project |
19730 | file as an attribute list called GNATtest_Switches. | |
19731 | ||
1a36a0cd AC |
19732 | @node Simple Example |
19733 | @section Simple Example | |
8417f4b2 AC |
19734 | |
19735 | @noindent | |
19736 | ||
1a36a0cd | 19737 | Let's take a very simple example using the first @command{gnattest} example |
5972791c | 19738 | located in: |
8417f4b2 AC |
19739 | |
19740 | @smallexample | |
ea10ca9c | 19741 | <install_prefix>/share/examples/gnattest/simple |
8417f4b2 AC |
19742 | @end smallexample |
19743 | ||
5972791c | 19744 | This project contains a simple package containing one subprogram. By running gnattest: |
8417f4b2 AC |
19745 | |
19746 | @smallexample | |
ea10ca9c | 19747 | $ gnattest --harness-dir=driver -Psimple.gpr |
8417f4b2 AC |
19748 | @end smallexample |
19749 | ||
5972791c | 19750 | a test driver is created in directory "driver". It can be compiled and run: |
8417f4b2 AC |
19751 | |
19752 | @smallexample | |
8b1011c0 AC |
19753 | $ cd obj/driver |
19754 | $ gnatmake -Ptest_driver | |
8417f4b2 AC |
19755 | $ test_runner |
19756 | @end smallexample | |
19757 | ||
19758 | One failed test with diagnosis "test not implemented" is reported. | |
5972791c AC |
19759 | Since no special output option was specified, the test package Simple.Tests |
19760 | is located in: | |
8417f4b2 AC |
19761 | |
19762 | @smallexample | |
fc7d1319 | 19763 | <install_prefix>/share/examples/gnattest/simple/obj/gnattest/tests |
8417f4b2 AC |
19764 | @end smallexample |
19765 | ||
1a36a0cd | 19766 | For each package containing visible subprograms, a child test package is |
8417f4b2 | 19767 | generated. It contains one test routine per tested subprogram. Each |
5972791c | 19768 | declaration of a test subprogram has a comment specifying which tested |
2fe2920e AC |
19769 | subprogram it corresponds to. Bodies of test routines are placed in test package |
19770 | bodies and are surrounded by special comment sections. Those comment sections | |
19771 | should not be removed or modified in order for gnattest to be able to regenerate | |
19772 | test packages and keep already written tests in place. | |
19773 | The test routine Test_Inc_5eaee3 located at simple-test_data-tests.adb contains | |
fc7d1319 AC |
19774 | a single statement: a call to procedure Assert. It has two arguments: |
19775 | the Boolean expression we want to check and the diagnosis message to display if | |
5972791c | 19776 | the condition is false. |
8417f4b2 AC |
19777 | |
19778 | That is where actual testing code should be written after a proper setup. | |
5972791c | 19779 | An actual check can be performed by replacing the Assert call with: |
8417f4b2 AC |
19780 | |
19781 | @smallexample @c ada | |
19782 | Assert (Inc (1) = 2, "wrong incrementation"); | |
19783 | @end smallexample | |
19784 | ||
5972791c | 19785 | After recompiling and running the test driver, one successfully passed test |
8417f4b2 AC |
19786 | is reported. |
19787 | ||
5972791c AC |
19788 | @node Setting Up and Tearing Down the Testing Environment |
19789 | @section Setting Up and Tearing Down the Testing Environment | |
8417f4b2 AC |
19790 | |
19791 | @noindent | |
19792 | ||
fc7d1319 AC |
19793 | Besides test routines themselves, each test package has a parent package |
19794 | Test_Data that has two procedures: Set_Up and Tear_Down. This package is never | |
19795 | overwritten by the tool. Set_Up is called before each test routine of the | |
19796 | package and Tear_Down is called after each test routine. Those two procedures | |
19797 | can be used to perform necessary initialization and finalization, | |
19798 | memory allocation, etc. Test type declared in Test_Data package is parent type | |
19799 | for the test type of test package and can have user-defined components whose | |
19800 | values can be set by Set_Up routine and used in test routines afterwards. | |
8417f4b2 | 19801 | |
1a36a0cd AC |
19802 | @node Regenerating Tests |
19803 | @section Regenerating Tests | |
8417f4b2 AC |
19804 | |
19805 | @noindent | |
19806 | ||
fc7d1319 | 19807 | Bodies of test routines and test_data packages are never overridden after they |
1a36a0cd | 19808 | have been created once. As long as the name of the subprogram, full expanded Ada |
2fe2920e AC |
19809 | names, and the order of its parameters is the same, and comment sections are |
19810 | intact the old test routine will fit in its place and no test skeleton will be | |
19811 | generated for the subprogram. | |
8417f4b2 | 19812 | |
1a36a0cd | 19813 | This can be demonstrated with the previous example. By uncommenting declaration |
ea10ca9c | 19814 | and body of function Dec in simple.ads and simple.adb, running |
5972791c | 19815 | @command{gnattest} on the project, and then running the test driver: |
8417f4b2 AC |
19816 | |
19817 | @smallexample | |
ea10ca9c | 19818 | gnattest --harness-dir=driver -Psimple.gpr |
8b1011c0 AC |
19819 | cd obj/driver |
19820 | gnatmake -Ptest_driver | |
8417f4b2 AC |
19821 | test_runner |
19822 | @end smallexample | |
19823 | ||
fc7d1319 AC |
19824 | the old test is not replaced with a stub, nor is it lost, but a new test |
19825 | skeleton is created for function Dec. | |
1a36a0cd | 19826 | |
fc7d1319 | 19827 | The only way of regenerating tests skeletons is to remove the previously created |
2fe2920e | 19828 | tests together with corresponding comment sections. |
8417f4b2 AC |
19829 | |
19830 | @node Default Test Behavior | |
19831 | @section Default Test Behavior | |
19832 | ||
19833 | @noindent | |
19834 | ||
5972791c AC |
19835 | The generated test driver can treat unimplemented tests in two ways: |
19836 | either count them all as failed (this is useful to see which tests are still | |
19837 | left to implement) or as passed (to sort out unimplemented ones from those | |
19838 | actually failing). | |
8417f4b2 | 19839 | |
fc7d1319 AC |
19840 | The test driver accepts a switch to specify this behavior: |
19841 | --skeleton-default=val, where val is either "pass" or "fail" (exactly as for | |
19842 | @command{gnattest}). | |
8417f4b2 AC |
19843 | |
19844 | The default behavior of the test driver is set with the same switch | |
5972791c | 19845 | as passed to gnattest when generating the test driver. |
8417f4b2 | 19846 | |
5972791c | 19847 | Passing it to the driver generated on the first example: |
8417f4b2 AC |
19848 | |
19849 | @smallexample | |
db914ff8 | 19850 | test_runner --skeleton-default=pass |
8417f4b2 AC |
19851 | @end smallexample |
19852 | ||
19853 | makes both tests pass, even the unimplemented one. | |
19854 | ||
19855 | @node Testing Primitive Operations of Tagged Types | |
19856 | @section Testing Primitive Operations of Tagged Types | |
19857 | ||
19858 | @noindent | |
19859 | ||
fc7d1319 AC |
19860 | Creation of test skeletons for primitive operations of tagged types entails |
19861 | a number of features. Test routines for all primitives of a given tagged type | |
19862 | are placed in a separate child package named according to the tagged type. For | |
5972791c | 19863 | example, if you have tagged type T in package P, all tests for primitives |
fc7d1319 | 19864 | of T will be in P.T_Test_Data.T_Tests. |
8417f4b2 | 19865 | |
5972791c AC |
19866 | Consider running gnattest on the second example (note: actual tests for this |
19867 | example already exist, so there's no need to worry if the tool reports that | |
19868 | no new stubs were generated): | |
8417f4b2 AC |
19869 | |
19870 | @smallexample | |
ea10ca9c AC |
19871 | cd <install_prefix>/share/examples/gnattest/tagged_rec |
19872 | gnattest --harness-dir=driver -Ptagged_rec.gpr | |
8417f4b2 AC |
19873 | @end smallexample |
19874 | ||
19875 | Taking a closer look at the test type declared in the test package | |
fc7d1319 | 19876 | Speed1.Controller_Test_Data is necessary. It is declared in: |
8417f4b2 AC |
19877 | |
19878 | @smallexample | |
fc7d1319 | 19879 | <install_prefix>/share/examples/gnattest/tagged_rec/obj/gnattest/tests |
8417f4b2 AC |
19880 | @end smallexample |
19881 | ||
19882 | Test types are direct or indirect descendants of | |
5972791c AC |
19883 | AUnit.Test_Fixtures.Test_Fixture type. In the case of nonprimitive tested |
19884 | subprograms, the user doesn't need to be concerned with them. However, | |
19885 | when generating test packages for primitive operations, there are some things | |
19886 | the user needs to know. | |
8417f4b2 | 19887 | |
5972791c | 19888 | Type Test_Controller has components that allow assignment of various |
8417f4b2 | 19889 | derivations of type Controller. And if you look at the specification of |
5972791c AC |
19890 | package Speed2.Auto_Controller, you will see that Test_Auto_Controller |
19891 | actually derives from Test_Controller rather than AUnit type Test_Fixture. | |
19892 | Thus, test types mirror the hierarchy of tested types. | |
8417f4b2 | 19893 | |
fc7d1319 | 19894 | The Set_Up procedure of Test_Data package corresponding to a test package |
5972791c AC |
19895 | of primitive operations of type T assigns to Fixture a reference to an |
19896 | object of that exact type T. Notice, however, that if the tagged type has | |
fc7d1319 | 19897 | discriminants, the Set_Up only has a commented template for setting |
5972791c | 19898 | up the fixture, since filling the discriminant with actual value is up |
8417f4b2 AC |
19899 | to the user. |
19900 | ||
5972791c | 19901 | The knowledge of the structure of test types allows additional testing |
8417f4b2 AC |
19902 | without additional effort. Those possibilities are described below. |
19903 | ||
5972791c AC |
19904 | @node Testing Inheritance |
19905 | @section Testing Inheritance | |
8417f4b2 AC |
19906 | |
19907 | @noindent | |
19908 | ||
5972791c AC |
19909 | Since the test type hierarchy mimics the hierarchy of tested types, the |
19910 | inheritance of tests takes place. An example of such inheritance can be | |
19911 | seen by running the test driver generated for the second example. As previously | |
8417f4b2 AC |
19912 | mentioned, actual tests are already written for this example. |
19913 | ||
19914 | @smallexample | |
8b1011c0 AC |
19915 | cd obj/driver |
19916 | gnatmake -Ptest_driver | |
8417f4b2 AC |
19917 | test_runner |
19918 | @end smallexample | |
19919 | ||
5972791c AC |
19920 | There are 6 passed tests while there are only 5 testable subprograms. The test |
19921 | routine for function Speed has been inherited and run against objects of the | |
8417f4b2 AC |
19922 | derived type. |
19923 | ||
1a36a0cd AC |
19924 | @node Tagged Types Substitutability Testing |
19925 | @section Tagged Types Substitutability Testing | |
8417f4b2 AC |
19926 | |
19927 | @noindent | |
19928 | ||
fc7d1319 AC |
19929 | Tagged Types Substitutability Testing is a way of verifying the global type |
19930 | consistency by testing. Global type consistency is a principle stating that if | |
1a36a0cd | 19931 | S is a subtype of T (in Ada, S is a derived type of tagged type T), |
5972791c AC |
19932 | then objects of type T may be replaced with objects of type S (that is, |
19933 | objects of type S may be substituted for objects of type T), without | |
19934 | altering any of the desirable properties of the program. When the properties | |
19935 | of the program are expressed in the form of subprogram preconditions and | |
fc7d1319 AC |
19936 | postconditions (let's call them pre and post), the principle is formulated as |
19937 | relations between the pre and post of primitive operations and the pre and post | |
19938 | of their derived operations. The pre of a derived operation should not be | |
19939 | stronger than the original pre, and the post of the derived operation should | |
19940 | not be weaker than the original post. Those relations ensure that verifying if | |
19941 | a dispatching call is safe can be done just by using the pre and post of the | |
19942 | root operation. | |
19943 | ||
19944 | Verifying global type consistency by testing consists of running all the unit | |
19945 | tests associated with the primitives of a given tagged type with objects of its | |
19946 | derived types. | |
1a36a0cd | 19947 | |
5972791c | 19948 | In the example used in the previous section, there was clearly a violation of |
fc7d1319 AC |
19949 | type consistency. The overriding primitive Adjust_Speed in package Speed2 |
19950 | removes the functionality of the overridden primitive and thus doesn't respect | |
19951 | the consistency principle. | |
5972791c AC |
19952 | Gnattest has a special option to run overridden parent tests against objects |
19953 | of the type which have overriding primitives: | |
8417f4b2 AC |
19954 | |
19955 | @smallexample | |
2fe2920e | 19956 | gnattest --harness-dir=driver --validate-type-extensions -Ptagged_rec.gpr |
8b1011c0 AC |
19957 | cd obj/driver |
19958 | gnatmake -Ptest_driver | |
8417f4b2 AC |
19959 | test_runner |
19960 | @end smallexample | |
19961 | ||
19962 | While all the tests pass by themselves, the parent test for Adjust_Speed fails | |
5972791c | 19963 | against objects of the derived type. |
8417f4b2 | 19964 | |
fc7d1319 AC |
19965 | Non-overridden tests are already inherited for derived test types, so the |
19966 | --validate-type-extensions enables the application of overriden tests to objects | |
19967 | of derived types. | |
19968 | ||
8417f4b2 AC |
19969 | @node Testing with Contracts |
19970 | @section Testing with Contracts | |
19971 | ||
19972 | @noindent | |
19973 | ||
fc7d1319 AC |
19974 | @command{gnattest} supports pragmas Precondition, Postcondition, and Test_Case, |
19975 | as well as corresponding aspects. | |
5972791c | 19976 | Test routines are generated, one per each Test_Case associated with a tested |
8417f4b2 | 19977 | subprogram. Those test routines have special wrappers for tested functions |
5972791c AC |
19978 | that have composition of pre- and postcondition of the subprogram with |
19979 | "requires" and "ensures" of the Test_Case (depending on the mode, pre and post | |
19980 | either count for Nominal mode or do not count for Robustness mode). | |
8417f4b2 | 19981 | |
5972791c | 19982 | The third example demonstrates how this works: |
8417f4b2 AC |
19983 | |
19984 | @smallexample | |
ea10ca9c AC |
19985 | cd <install_prefix>/share/examples/gnattest/contracts |
19986 | gnattest --harness-dir=driver -Pcontracts.gpr | |
8417f4b2 AC |
19987 | @end smallexample |
19988 | ||
19989 | Putting actual checks within the range of the contract does not cause any | |
19990 | error reports. For example, for the test routine which corresponds to | |
5972791c | 19991 | test case 1: |
8417f4b2 AC |
19992 | |
19993 | @smallexample @c ada | |
19994 | Assert (Sqrt (9.0) = 3.0, "wrong sqrt"); | |
19995 | @end smallexample | |
19996 | ||
5972791c | 19997 | and for the test routine corresponding to test case 2: |
8417f4b2 AC |
19998 | |
19999 | @smallexample @c ada | |
20000 | Assert (Sqrt (-5.0) = -1.0, "wrong error indication"); | |
20001 | @end smallexample | |
20002 | ||
20003 | are acceptable: | |
20004 | ||
20005 | @smallexample | |
8b1011c0 AC |
20006 | cd obj/driver |
20007 | gnatmake -Ptest_driver | |
8417f4b2 AC |
20008 | test_runner |
20009 | @end smallexample | |
20010 | ||
5972791c AC |
20011 | However, by changing 9.0 to 25.0 and 3.0 to 5.0, for example, you can get |
20012 | a precondition violation for test case one. Also, by using any otherwise | |
20013 | correct but positive pair of numbers in the second test routine, you can also | |
8417f4b2 AC |
20014 | get a precondition violation. Postconditions are checked and reported |
20015 | the same way. | |
20016 | ||
20017 | @node Additional Tests | |
20018 | @section Additional Tests | |
20019 | ||
20020 | @noindent | |
5972791c AC |
20021 | @command{gnattest} can add user-written tests to the main suite of the test |
20022 | driver. @command{gnattest} traverses the given packages and searches for test | |
ea10ca9c | 20023 | routines. All procedures with a single in out parameter of a type which is |
5972791c AC |
20024 | derived from AUnit.Test_Fixtures.Test_Fixture and that are declared in package |
20025 | specifications are added to the suites and are then executed by the test driver. | |
20026 | (Set_Up and Tear_Down are filtered out.) | |
ea10ca9c | 20027 | |
5972791c AC |
20028 | An example illustrates two ways of creating test harnesses for user-written |
20029 | tests. Directory additional_tests contains an AUnit-based test driver written | |
20030 | by hand. | |
ea10ca9c AC |
20031 | |
20032 | @smallexample | |
20033 | <install_prefix>/share/examples/gnattest/additional_tests/ | |
20034 | @end smallexample | |
20035 | ||
5972791c AC |
20036 | To create a test driver for already-written tests, use the --harness-only |
20037 | option: | |
ea10ca9c AC |
20038 | |
20039 | @smallexample | |
20040 | gnattest -Padditional/harness/harness.gpr --harness-dir=harness_only \ | |
20041 | --harness-only | |
20042 | gnatmake -Pharness_only/test_driver.gpr | |
20043 | harness_only/test_runner | |
20044 | @end smallexample | |
20045 | ||
5972791c | 20046 | Additional tests can also be executed together with generated tests: |
ea10ca9c AC |
20047 | |
20048 | @smallexample | |
20049 | gnattest -Psimple.gpr --additional-tests=additional/harness/harness.gpr \ | |
20050 | --harness-dir=mixing | |
20051 | gnatmake -Pmixing/test_driver.gpr | |
20052 | mixing/test_runner | |
20053 | @end smallexample | |
8417f4b2 | 20054 | |
473e20df | 20055 | @ifclear vms |
a1e16658 AC |
20056 | @node Support for other platforms/run-times |
20057 | @section Support for other platforms/run-times | |
20058 | ||
20059 | @noindent | |
20060 | @command{gnattest} can be used to generate the test harness for platforms | |
20061 | and run-time libraries others than the default native target with the | |
20062 | default full run-time. For example, when using a limited run-time library | |
20063 | such as Zero FootPrint (ZFP), a simplified harness is generated. | |
20064 | ||
20065 | Two variables are used to tell the underlying AUnit framework how to generate | |
20066 | the test harness: @code{PLATFORM}, which identifies the target, and | |
20067 | @code{RUNTIME}, used to determine the run-time library for which the harness | |
db914ff8 AC |
20068 | is generated. Corresponding prefix should also be used when calling |
20069 | @command{gnattest} for non-native targets. For example, the following options | |
20070 | are used to generate the AUnit test harness for a PowerPC ELF target using | |
20071 | the ZFP run-time library: | |
a1e16658 AC |
20072 | |
20073 | @smallexample | |
db914ff8 | 20074 | powerpc-elf-gnattest -Psimple.gpr -XPLATFORM=powerpc-elf -XRUNTIME=zfp |
a1e16658 | 20075 | @end smallexample |
473e20df | 20076 | @end ifclear |
a1e16658 | 20077 | |
8417f4b2 AC |
20078 | @node Current Limitations |
20079 | @section Current Limitations | |
20080 | ||
20081 | @noindent | |
20082 | ||
20083 | The tool currently does not support following features: | |
20084 | ||
20085 | @itemize @bullet | |
20086 | @item generic tests for generic packages and package instantiations | |
5972791c | 20087 | @item tests for protected subprograms and entries |
bdf69d33 | 20088 | |
8417f4b2 | 20089 | @end itemize |
1037b0f4 AC |
20090 | @end ifclear |
20091 | ||
8417f4b2 | 20092 | |
5f44f0d4 AC |
20093 | @c ********************************* |
20094 | @node Performing Dimensionality Analysis in GNAT | |
20095 | @chapter Performing Dimensionality Analysis in GNAT | |
20096 | @noindent | |
20097 | The GNAT compiler now supports dimensionality checking. The user can | |
20098 | specify physical units for objects, and the compiler will verify that uses | |
20099 | of these objects are compatible with their dimensions, in a fashion that is | |
20100 | familiar to engineering practice. The dimensions of algebraic expressions | |
20101 | (including powers with static exponents) are computed from their consistuents. | |
20102 | ||
20103 | This feature depends on Ada 2012 aspect specifications, and is available from | |
20104 | version 7.0.1 of GNAT onwards. The GNAT-specific aspect Dimension_System allows | |
7be8338d | 20105 | you to define a system of units; the aspect Dimension then allows the user |
5f44f0d4 AC |
20106 | to declare dimensioned quantities within a given system. |
20107 | ||
7a6de2e2 AC |
20108 | The major advantage of this model is that it does not require the declaration of |
20109 | multiple operators for all possible combinations of types: it is only necessary | |
20110 | to use the proper subtypes in object declarations. | |
20111 | ||
5f44f0d4 AC |
20112 | The simplest way to impose dimensionality checking on a computation is to make |
20113 | use of the package System.Dim.Mks, which is part of the GNAT library. This | |
20114 | package defines a floating-point type MKS_Type, for which a sequence of | |
20115 | dimension names are specified, together with their conventional abbreviations. | |
20116 | The following should be read together with the full specification of the | |
20117 | package, in file s-dimmks.ads. | |
20118 | ||
20119 | @smallexample @c ada | |
20120 | type Mks_Type is new Long_Long_Float | |
20121 | with | |
20122 | Dimension_System => ( | |
24cb156d AC |
20123 | (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), |
20124 | (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), | |
20125 | (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), | |
20126 | (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), | |
20127 | (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"), | |
20128 | (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), | |
20129 | (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); | |
5f44f0d4 AC |
20130 | @end smallexample |
20131 | ||
20132 | @noindent | |
20133 | The package then defines a series of subtypes that correspond to these | |
20134 | conventional units. For example: | |
20135 | @smallexample @c ada | |
20136 | subtype Length is Mks_Type | |
20137 | with | |
7be8338d | 20138 | Dimension => (Symbol => 'm', Meter => 1, others => 0); |
5f44f0d4 AC |
20139 | @end smallexample |
20140 | @noindent | |
20141 | and similarly for Mass, Time, Electric_Current, Thermodynamic_Temperature, | |
20142 | Amount_Of_Substance, and Luminous_Intensity (the standard set of units of | |
20143 | the SI system). | |
20144 | ||
20145 | The package also defines conventional names for values of each unit, for | |
20146 | example: | |
20147 | ||
20148 | @smallexample @c ada | |
24cb156d AC |
20149 | m : constant Length := 1.0; |
20150 | kg : constant Mass := 1.0; | |
20151 | s : constant Time := 1.0; | |
20152 | A : constant Electric_Current := 1.0; | |
5f44f0d4 AC |
20153 | @end smallexample |
20154 | ||
20155 | @noindent | |
20156 | as well as useful multiples of these units: | |
20157 | ||
20158 | @smallexample @c ada | |
20159 | cm : constant Length := 1.0E-02; | |
20160 | g : constant Mass := 1.0E-03; | |
20161 | min : constant Time := 60.0; | |
20162 | day : constant TIme := 60.0 * 24.0 * min; | |
20163 | ... | |
20164 | @end smallexample | |
20165 | ||
20166 | @noindent | |
7be8338d RD |
20167 | Using this package, you can then define a derived unit by |
20168 | providing the aspect that | |
7a6de2e2 AC |
20169 | specifies its dimensions within the MKS system, as well as the string to |
20170 | be used for output of a value of that unit: | |
5f44f0d4 AC |
20171 | |
20172 | @smallexample @c ada | |
20173 | subtype Acceleration is Mks_Type | |
7be8338d RD |
20174 | with Dimension => ("m/sec^^^2", |
20175 | Meter => 1, | |
20176 | Second => -2, | |
20177 | others => 0); | |
5f44f0d4 AC |
20178 | @end smallexample |
20179 | ||
20180 | @noindent | |
20181 | Here is a complete example of use: | |
20182 | ||
20183 | @smallexample @c ada | |
20184 | with System.Dim.MKS; use System.Dim.Mks; | |
20185 | with System.Dim.Mks_IO; use System.Dim.Mks_IO; | |
20186 | with Text_IO; use Text_IO; | |
20187 | procedure Free_Fall is | |
20188 | subtype Acceleration is Mks_Type | |
7a6de2e2 | 20189 | with Dimension => ("m/sec^^^2", 1, 0, -2, others => 0); |
5f44f0d4 AC |
20190 | G : constant acceleration := 9.81 * m / (s ** 2); |
20191 | T : Time := 10.0*s; | |
20192 | Distance : Length; | |
20193 | begin | |
7a6de2e2 AC |
20194 | Put ("Gravitational constant: "); |
20195 | Put (G, Aft => 2, Exp => 0); Put_Line (""); | |
5f44f0d4 AC |
20196 | Distance := 0.5 * G * T ** 2; |
20197 | Put ("distance travelled in 10 seconds of free fall "); | |
20198 | Put (Distance, Aft => 2, Exp => 0); | |
20199 | Put_Line (""); | |
20200 | end Free_Fall; | |
20201 | @end smallexample | |
20202 | ||
20203 | @noindent | |
20204 | Execution of this program yields: | |
20205 | @smallexample | |
7a6de2e2 | 20206 | Gravitational constant: 9.81 m/sec^^^2 |
5f44f0d4 AC |
20207 | distance travelled in 10 seconds of free fall 490.50 m |
20208 | @end smallexample | |
20209 | ||
20210 | @noindent | |
20211 | However, incorrect assignments such as: | |
20212 | ||
20213 | @smallexample @c ada | |
20214 | Distance := 5.0; | |
20215 | Distance := 5.0 * kg: | |
20216 | @end smallexample | |
20217 | ||
20218 | @noindent | |
20219 | are rejected with the following diagnoses: | |
20220 | ||
20221 | @smallexample | |
20222 | Distance := 5.0; | |
20223 | >>> dimensions mismatch in assignment | |
219d9cc7 | 20224 | >>> left-hand side has dimension [L] |
5f44f0d4 AC |
20225 | >>> right-hand side is dimensionless |
20226 | ||
20227 | Distance := 5.0 * kg: | |
20228 | >>> dimensions mismatch in assignment | |
219d9cc7 AC |
20229 | >>> left-hand side has dimension [L] |
20230 | >>> right-hand side has dimension [M] | |
5f44f0d4 AC |
20231 | @end smallexample |
20232 | ||
20233 | @noindent | |
7a6de2e2 AC |
20234 | The dimensions of an expression are properly displayed, even if there is |
20235 | no explicit subtype for it. If we add to the program: | |
5f44f0d4 AC |
20236 | |
20237 | @smallexample @c ada | |
20238 | Put ("Final velocity: "); | |
20239 | Put (G * T, Aft =>2, Exp =>0); | |
20240 | Put_Line (""); | |
20241 | @end smallexample | |
20242 | ||
20243 | @noindent | |
20244 | then the output includes: | |
20245 | @smallexample | |
20246 | Final velocity: 98.10 m.s**(-1) | |
20247 | @end smallexample | |
20248 | ||
c5d91669 AC |
20249 | @c ********************************* |
20250 | @node Generating Ada Bindings for C and C++ headers | |
20251 | @chapter Generating Ada Bindings for C and C++ headers | |
20252 | @findex binding | |
20253 | ||
20254 | @noindent | |
c4e09c3f AC |
20255 | GNAT now comes with a binding generator for C and C++ headers which is |
20256 | intended to do 95% of the tedious work of generating Ada specs from C | |
20257 | or C++ header files. | |
20258 | ||
20259 | Note that this capability is not intended to generate 100% correct Ada specs, | |
20260 | and will is some cases require manual adjustments, although it can often | |
20261 | be used out of the box in practice. | |
20262 | ||
20263 | Some of the known limitations include: | |
20264 | ||
20265 | @itemize @bullet | |
20266 | @item only very simple character constant macros are translated into Ada | |
20267 | constants. Function macros (macros with arguments) are partially translated | |
20268 | as comments, to be completed manually if needed. | |
20269 | @item some extensions (e.g. vector types) are not supported | |
20270 | @item pointers to pointers or complex structures are mapped to System.Address | |
ce417b8f AC |
20271 | @item identifiers with identical name (except casing) will generate compilation |
20272 | errors (e.g. @code{shm_get} vs @code{SHM_GET}). | |
c4e09c3f | 20273 | @end itemize |
c5d91669 | 20274 | |
9fcf2a0b AC |
20275 | The code generated is using the Ada 2005 syntax, which makes it |
20276 | easier to interface with other languages than previous versions of Ada. | |
c5d91669 AC |
20277 | |
20278 | @menu | |
20279 | * Running the binding generator:: | |
20280 | * Generating bindings for C++ headers:: | |
20281 | * Switches:: | |
20282 | @end menu | |
20283 | ||
20284 | @node Running the binding generator | |
20285 | @section Running the binding generator | |
20286 | ||
20287 | @noindent | |
20288 | The binding generator is part of the @command{gcc} compiler and can be | |
20289 | invoked via the @option{-fdump-ada-spec} switch, which will generate Ada | |
20290 | spec files for the header files specified on the command line, and all | |
308e6f3a | 20291 | header files needed by these files transitively. For example: |
c5d91669 AC |
20292 | |
20293 | @smallexample | |
20294 | $ g++ -c -fdump-ada-spec -C /usr/include/time.h | |
20295 | $ gcc -c -gnat05 *.ads | |
20296 | @end smallexample | |
20297 | ||
9fcf2a0b AC |
20298 | will generate, under GNU/Linux, the following files: @file{time_h.ads}, |
20299 | @file{bits_time_h.ads}, @file{stddef_h.ads}, @file{bits_types_h.ads} which | |
c5d91669 AC |
20300 | correspond to the files @file{/usr/include/time.h}, |
20301 | @file{/usr/include/bits/time.h}, etc@dots{}, and will then compile in Ada 2005 | |
20302 | mode these Ada specs. | |
20303 | ||
20304 | The @code{-C} switch tells @command{gcc} to extract comments from headers, | |
20305 | and will attempt to generate corresponding Ada comments. | |
20306 | ||
20307 | If you want to generate a single Ada file and not the transitive closure, you | |
20308 | can use instead the @option{-fdump-ada-spec-slim} switch. | |
20309 | ||
0929eaeb AC |
20310 | You can optionally specify a parent unit, of which all generated units will |
20311 | be children, using @code{-fada-spec-parent=}@var{unit}. | |
20312 | ||
c5d91669 AC |
20313 | Note that we recommend when possible to use the @command{g++} driver to |
20314 | generate bindings, even for most C headers, since this will in general | |
20315 | generate better Ada specs. For generating bindings for C++ headers, it is | |
20316 | mandatory to use the @command{g++} command, or @command{gcc -x c++} which | |
20317 | is equivalent in this case. If @command{g++} cannot work on your C headers | |
20318 | because of incompatibilities between C and C++, then you can fallback to | |
20319 | @command{gcc} instead. | |
20320 | ||
20321 | For an example of better bindings generated from the C++ front-end, | |
20322 | the name of the parameters (when available) are actually ignored by the C | |
20323 | front-end. Consider the following C header: | |
20324 | ||
20325 | @smallexample | |
20326 | extern void foo (int variable); | |
20327 | @end smallexample | |
20328 | ||
20329 | with the C front-end, @code{variable} is ignored, and the above is handled as: | |
20330 | ||
20331 | @smallexample | |
20332 | extern void foo (int); | |
20333 | @end smallexample | |
20334 | ||
20335 | generating a generic: | |
20336 | ||
20337 | @smallexample | |
20338 | procedure foo (param1 : int); | |
20339 | @end smallexample | |
20340 | ||
20341 | with the C++ front-end, the name is available, and we generate: | |
20342 | ||
20343 | @smallexample | |
20344 | procedure foo (variable : int); | |
20345 | @end smallexample | |
20346 | ||
20347 | In some cases, the generated bindings will be more complete or more meaningful | |
9fcf2a0b | 20348 | when defining some macros, which you can do via the @option{-D} switch. This |
c5d91669 AC |
20349 | is for example the case with @file{Xlib.h} under GNU/Linux: |
20350 | ||
20351 | @smallexample | |
20352 | g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h | |
20353 | @end smallexample | |
20354 | ||
20355 | The above will generate more complete bindings than a straight call without | |
20356 | the @option{-DXLIB_ILLEGAL_ACCESS} switch. | |
20357 | ||
6c57023b | 20358 | In other cases, it is not possible to parse a header file in a stand-alone |
c5d91669 AC |
20359 | manner, because other include files need to be included first. In this |
20360 | case, the solution is to create a small header file including the needed | |
20361 | @code{#include} and possible @code{#define} directives. For example, to | |
9fcf2a0b | 20362 | generate Ada bindings for @file{readline/readline.h}, you need to first |
c5d91669 AC |
20363 | include @file{stdio.h}, so you can create a file with the following two |
20364 | lines in e.g. @file{readline1.h}: | |
20365 | ||
20366 | @smallexample | |
20367 | #include <stdio.h> | |
20368 | #include <readline/readline.h> | |
20369 | @end smallexample | |
20370 | ||
20371 | and then generate Ada bindings from this file: | |
20372 | ||
20373 | @smallexample | |
20374 | $ g++ -c -fdump-ada-spec readline1.h | |
20375 | @end smallexample | |
20376 | ||
20377 | @node Generating bindings for C++ headers | |
20378 | @section Generating bindings for C++ headers | |
20379 | ||
20380 | @noindent | |
20381 | Generating bindings for C++ headers is done using the same options, always | |
20382 | with the @command{g++} compiler. | |
20383 | ||
20384 | In this mode, C++ classes will be mapped to Ada tagged types, constructors | |
20385 | will be mapped using the @code{CPP_Constructor} pragma, and when possible, | |
20386 | multiple inheritance of abstract classes will be mapped to Ada interfaces | |
20387 | (@xref{Interfacing to C++,,,gnat_rm, GNAT Reference Manual}, for additional | |
20388 | information on interfacing to C++). | |
20389 | ||
f8b86c2d AC |
20390 | For example, given the following C++ header file: |
20391 | ||
20392 | @smallexample | |
20393 | @group | |
20394 | @cartouche | |
20395 | class Carnivore @{ | |
20396 | public: | |
20397 | virtual int Number_Of_Teeth () = 0; | |
20398 | @}; | |
20399 | ||
20400 | class Domestic @{ | |
20401 | public: | |
20402 | virtual void Set_Owner (char* Name) = 0; | |
20403 | @}; | |
20404 | ||
20405 | class Animal @{ | |
20406 | public: | |
20407 | int Age_Count; | |
20408 | virtual void Set_Age (int New_Age); | |
20409 | @}; | |
20410 | ||
20411 | class Dog : Animal, Carnivore, Domestic @{ | |
20412 | public: | |
20413 | int Tooth_Count; | |
20414 | char *Owner; | |
20415 | ||
20416 | virtual int Number_Of_Teeth (); | |
20417 | virtual void Set_Owner (char* Name); | |
20418 | ||
20419 | Dog(); | |
20420 | @}; | |
20421 | @end cartouche | |
20422 | @end group | |
20423 | @end smallexample | |
20424 | ||
20425 | The corresponding Ada code is generated: | |
20426 | ||
20427 | @smallexample @c ada | |
20428 | @group | |
20429 | @cartouche | |
20430 | package Class_Carnivore is | |
20431 | type Carnivore is limited interface; | |
20432 | pragma Import (CPP, Carnivore); | |
20433 | ||
20434 | function Number_Of_Teeth (this : access Carnivore) return int is abstract; | |
20435 | end; | |
20436 | use Class_Carnivore; | |
20437 | ||
20438 | package Class_Domestic is | |
20439 | type Domestic is limited interface; | |
20440 | pragma Import (CPP, Domestic); | |
20441 | ||
20442 | procedure Set_Owner | |
20443 | (this : access Domestic; | |
20444 | Name : Interfaces.C.Strings.chars_ptr) is abstract; | |
20445 | end; | |
20446 | use Class_Domestic; | |
20447 | ||
20448 | package Class_Animal is | |
20449 | type Animal is tagged limited record | |
20450 | Age_Count : aliased int; | |
20451 | end record; | |
20452 | pragma Import (CPP, Animal); | |
20453 | ||
20454 | procedure Set_Age (this : access Animal; New_Age : int); | |
20455 | pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi"); | |
20456 | end; | |
20457 | use Class_Animal; | |
20458 | ||
20459 | package Class_Dog is | |
20460 | type Dog is new Animal and Carnivore and Domestic with record | |
20461 | Tooth_Count : aliased int; | |
20462 | Owner : Interfaces.C.Strings.chars_ptr; | |
20463 | end record; | |
20464 | pragma Import (CPP, Dog); | |
20465 | ||
20466 | function Number_Of_Teeth (this : access Dog) return int; | |
20467 | pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv"); | |
20468 | ||
20469 | procedure Set_Owner | |
20470 | (this : access Dog; Name : Interfaces.C.Strings.chars_ptr); | |
20471 | pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc"); | |
20472 | ||
7b4db06c | 20473 | function New_Dog return Dog; |
f8b86c2d AC |
20474 | pragma CPP_Constructor (New_Dog); |
20475 | pragma Import (CPP, New_Dog, "_ZN3DogC1Ev"); | |
20476 | end; | |
20477 | use Class_Dog; | |
20478 | @end cartouche | |
20479 | @end group | |
20480 | @end smallexample | |
20481 | ||
c5d91669 AC |
20482 | @node Switches |
20483 | @section Switches | |
20484 | ||
20485 | @table @option | |
20486 | @item -fdump-ada-spec | |
20487 | @cindex @option{-fdump-ada-spec} (@command{gcc}) | |
20488 | Generate Ada spec files for the given header files transitively (including | |
20489 | all header files that these headers depend upon). | |
20490 | ||
20491 | @item -fdump-ada-spec-slim | |
20492 | @cindex @option{-fdump-ada-spec-slim} (@command{gcc}) | |
20493 | Generate Ada spec files for the header files specified on the command line | |
20494 | only. | |
20495 | ||
0929eaeb AC |
20496 | @item -fada-spec-parent=@var{unit} |
20497 | @cindex -fada-spec-parent (@command{gcc}) | |
b9820f7b | 20498 | Specifies that all files generated by @option{-fdump-ada-spec*} are |
0929eaeb AC |
20499 | to be child units of the specified parent unit. |
20500 | ||
c5d91669 | 20501 | @item -C |
9fcf2a0b | 20502 | @cindex @option{-C} (@command{gcc}) |
c5d91669 AC |
20503 | Extract comments from headers and generate Ada comments in the Ada spec files. |
20504 | @end table | |
20505 | ||
7cd4527e AC |
20506 | @node Other Utility Programs |
20507 | @chapter Other Utility Programs | |
20508 | ||
20509 | @noindent | |
20510 | This chapter discusses some other utility programs available in the Ada | |
20511 | environment. | |
88e1739c FW |
20512 | |
20513 | @menu | |
7cd4527e AC |
20514 | * Using Other Utility Programs with GNAT:: |
20515 | * The External Symbol Naming Scheme of GNAT:: | |
7cd4527e AC |
20516 | * Converting Ada Files to html with gnathtml:: |
20517 | * Installing gnathtml:: | |
20518 | @ifset vms | |
20519 | * LSE:: | |
20520 | * Profiling:: | |
20521 | @end ifset | |
88e1739c FW |
20522 | @end menu |
20523 | ||
7cd4527e AC |
20524 | @node Using Other Utility Programs with GNAT |
20525 | @section Using Other Utility Programs with GNAT | |
88e1739c FW |
20526 | |
20527 | @noindent | |
7cd4527e AC |
20528 | The object files generated by GNAT are in standard system format and in |
20529 | particular the debugging information uses this format. This means | |
20530 | programs generated by GNAT can be used with existing utilities that | |
20531 | depend on these formats. | |
88e1739c | 20532 | |
7cd4527e AC |
20533 | @ifclear vms |
20534 | In general, any utility program that works with C will also often work with | |
20535 | Ada programs generated by GNAT. This includes software utilities such as | |
20536 | gprof (a profiling program), @code{gdb} (the FSF debugger), and utilities such | |
20537 | as Purify. | |
20538 | @end ifclear | |
88e1739c | 20539 | |
7cd4527e AC |
20540 | @node The External Symbol Naming Scheme of GNAT |
20541 | @section The External Symbol Naming Scheme of GNAT | |
88e1739c FW |
20542 | |
20543 | @noindent | |
7cd4527e AC |
20544 | In order to interpret the output from GNAT, when using tools that are |
20545 | originally intended for use with other languages, it is useful to | |
20546 | understand the conventions used to generate link names from the Ada | |
20547 | entity names. | |
88e1739c | 20548 | |
7cd4527e AC |
20549 | All link names are in all lowercase letters. With the exception of library |
20550 | procedure names, the mechanism used is simply to use the full expanded | |
20551 | Ada name with dots replaced by double underscores. For example, suppose | |
20552 | we have the following package spec: | |
20553 | ||
20554 | @smallexample @c ada | |
20555 | @group | |
88e1739c | 20556 | @cartouche |
7cd4527e AC |
20557 | package QRS is |
20558 | MN : Integer; | |
20559 | end QRS; | |
88e1739c | 20560 | @end cartouche |
7cd4527e | 20561 | @end group |
88e1739c FW |
20562 | @end smallexample |
20563 | ||
20564 | @noindent | |
7cd4527e AC |
20565 | The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so |
20566 | the corresponding link name is @code{qrs__mn}. | |
20567 | @findex Export | |
20568 | Of course if a @code{pragma Export} is used this may be overridden: | |
88e1739c | 20569 | |
7cd4527e | 20570 | @smallexample @c ada |
88e1739c FW |
20571 | @group |
20572 | @cartouche | |
7cd4527e | 20573 | package Exports is |
88e1739c | 20574 | Var1 : Integer; |
7cd4527e | 20575 | pragma Export (Var1, C, External_Name => "var1_name"); |
88e1739c | 20576 | Var2 : Integer; |
7cd4527e AC |
20577 | pragma Export (Var2, C, Link_Name => "var2_link_name"); |
20578 | end Exports; | |
88e1739c FW |
20579 | @end cartouche |
20580 | @end group | |
20581 | @end smallexample | |
20582 | ||
20583 | @noindent | |
20584 | In this case, the link name for @var{Var1} is whatever link name the | |
20585 | C compiler would assign for the C function @var{var1_name}. This typically | |
20586 | would be either @var{var1_name} or @var{_var1_name}, depending on operating | |
20587 | system conventions, but other possibilities exist. The link name for | |
20588 | @var{Var2} is @var{var2_link_name}, and this is not operating system | |
20589 | dependent. | |
20590 | ||
20591 | @findex _main | |
20592 | One exception occurs for library level procedures. A potential ambiguity | |
20593 | arises between the required name @code{_main} for the C main program, | |
20594 | and the name we would otherwise assign to an Ada library level procedure | |
20595 | called @code{Main} (which might well not be the main program). | |
20596 | ||
20597 | To avoid this ambiguity, we attach the prefix @code{_ada_} to such | |
20598 | names. So if we have a library level procedure such as | |
20599 | ||
7cd4527e | 20600 | @smallexample @c ada |
88e1739c FW |
20601 | @group |
20602 | @cartouche | |
7cd4527e | 20603 | procedure Hello (S : String); |
88e1739c FW |
20604 | @end cartouche |
20605 | @end group | |
20606 | @end smallexample | |
20607 | ||
20608 | @noindent | |
20609 | the external name of this procedure will be @var{_ada_hello}. | |
20610 | ||
7cd4527e | 20611 | |
88e1739c | 20612 | @node Converting Ada Files to html with gnathtml |
7cd4527e | 20613 | @section Converting Ada Files to HTML with @code{gnathtml} |
88e1739c FW |
20614 | |
20615 | @noindent | |
20616 | This @code{Perl} script allows Ada source files to be browsed using | |
20617 | standard Web browsers. For installation procedure, see the section | |
20618 | @xref{Installing gnathtml}. | |
20619 | ||
20620 | Ada reserved keywords are highlighted in a bold font and Ada comments in | |
20621 | a blue font. Unless your program was compiled with the gcc @option{-gnatx} | |
20622 | switch to suppress the generation of cross-referencing information, user | |
20623 | defined variables and types will appear in a different color; you will | |
20624 | be able to click on any identifier and go to its declaration. | |
20625 | ||
20626 | The command line is as follow: | |
20627 | @smallexample | |
e074d476 AC |
20628 | @c $ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files} |
20629 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
20630 | $ perl gnathtml.pl @r{[}@var{^switches^options^}@r{]} @var{ada-files} | |
88e1739c FW |
20631 | @end smallexample |
20632 | ||
7cd4527e | 20633 | @noindent |
88e1739c FW |
20634 | You can pass it as many Ada files as you want. @code{gnathtml} will generate |
20635 | an html file for every ada file, and a global file called @file{index.htm}. | |
20636 | This file is an index of every identifier defined in the files. | |
20637 | ||
e69044cb | 20638 | The available ^switches^options^ are the following ones: |
88e1739c | 20639 | |
7cd4527e | 20640 | @table @option |
88e1739c | 20641 | @item -83 |
7cd4527e | 20642 | @cindex @option{-83} (@code{gnathtml}) |
e08b38f5 | 20643 | Only the Ada 83 subset of keywords will be highlighted. |
88e1739c FW |
20644 | |
20645 | @item -cc @var{color} | |
7cd4527e | 20646 | @cindex @option{-cc} (@code{gnathtml}) |
88e1739c FW |
20647 | This option allows you to change the color used for comments. The default |
20648 | value is green. The color argument can be any name accepted by html. | |
20649 | ||
20650 | @item -d | |
7cd4527e | 20651 | @cindex @option{-d} (@code{gnathtml}) |
7e3d710b AC |
20652 | If the Ada files depend on some other files (for instance through |
20653 | @code{with} clauses, the latter files will also be converted to html. | |
88e1739c FW |
20654 | Only the files in the user project will be converted to html, not the files |
20655 | in the run-time library itself. | |
20656 | ||
20657 | @item -D | |
7cd4527e AC |
20658 | @cindex @option{-D} (@code{gnathtml}) |
20659 | This command is the same as @option{-d} above, but @command{gnathtml} will | |
20660 | also look for files in the run-time library, and generate html files for them. | |
20661 | ||
20662 | @item -ext @var{extension} | |
20663 | @cindex @option{-ext} (@code{gnathtml}) | |
20664 | This option allows you to change the extension of the generated HTML files. | |
20665 | If you do not specify an extension, it will default to @file{htm}. | |
88e1739c FW |
20666 | |
20667 | @item -f | |
7cd4527e | 20668 | @cindex @option{-f} (@code{gnathtml}) |
88e1739c | 20669 | By default, gnathtml will generate html links only for global entities |
d488f6ea | 20670 | ('with'ed units, global variables and types,@dots{}). If you specify |
7cd4527e | 20671 | @option{-f} on the command line, then links will be generated for local |
88e1739c FW |
20672 | entities too. |
20673 | ||
20674 | @item -l @var{number} | |
7cd4527e | 20675 | @cindex @option{-l} (@code{gnathtml}) |
7e3d710b AC |
20676 | If this ^switch^option^ is provided and @var{number} is not 0, then |
20677 | @code{gnathtml} will number the html files every @var{number} line. | |
88e1739c FW |
20678 | |
20679 | @item -I @var{dir} | |
7cd4527e AC |
20680 | @cindex @option{-I} (@code{gnathtml}) |
20681 | Specify a directory to search for library files (@file{.ALI} files) and | |
88e1739c FW |
20682 | source files. You can provide several -I switches on the command line, |
20683 | and the directories will be parsed in the order of the command line. | |
20684 | ||
20685 | @item -o @var{dir} | |
7cd4527e | 20686 | @cindex @option{-o} (@code{gnathtml}) |
88e1739c FW |
20687 | Specify the output directory for html files. By default, gnathtml will |
20688 | saved the generated html files in a subdirectory named @file{html/}. | |
20689 | ||
20690 | @item -p @var{file} | |
7cd4527e | 20691 | @cindex @option{-p} (@code{gnathtml}) |
88e1739c FW |
20692 | If you are using Emacs and the most recent Emacs Ada mode, which provides |
20693 | a full Integrated Development Environment for compiling, checking, | |
7cd4527e | 20694 | running and debugging applications, you may use @file{.gpr} files |
88e1739c FW |
20695 | to give the directories where Emacs can find sources and object files. |
20696 | ||
7e3d710b AC |
20697 | Using this ^switch^option^, you can tell gnathtml to use these files. |
20698 | This allows you to get an html version of your application, even if it | |
20699 | is spread over multiple directories. | |
88e1739c FW |
20700 | |
20701 | @item -sc @var{color} | |
7cd4527e | 20702 | @cindex @option{-sc} (@code{gnathtml}) |
7e3d710b AC |
20703 | This ^switch^option^ allows you to change the color used for symbol |
20704 | definitions. | |
88e1739c FW |
20705 | The default value is red. The color argument can be any name accepted by html. |
20706 | ||
20707 | @item -t @var{file} | |
7cd4527e | 20708 | @cindex @option{-t} (@code{gnathtml}) |
7e3d710b | 20709 | This ^switch^option^ provides the name of a file. This file contains a list of |
88e1739c FW |
20710 | file names to be converted, and the effect is exactly as though they had |
20711 | appeared explicitly on the command line. This | |
20712 | is the recommended way to work around the command line length limit on some | |
20713 | systems. | |
20714 | ||
20715 | @end table | |
20716 | ||
20717 | @node Installing gnathtml | |
20718 | @section Installing @code{gnathtml} | |
20719 | ||
20720 | @noindent | |
20721 | @code{Perl} needs to be installed on your machine to run this script. | |
20722 | @code{Perl} is freely available for almost every architecture and | |
20723 | Operating System via the Internet. | |
20724 | ||
20725 | On Unix systems, you may want to modify the first line of the script | |
20726 | @code{gnathtml}, to explicitly tell the Operating system where Perl | |
e69044cb | 20727 | is. The syntax of this line is: |
88e1739c FW |
20728 | @smallexample |
20729 | #!full_path_name_to_perl | |
20730 | @end smallexample | |
20731 | ||
20732 | @noindent | |
20733 | Alternatively, you may run the script using the following command line: | |
20734 | ||
20735 | @smallexample | |
e074d476 AC |
20736 | @c $ perl gnathtml.pl @ovar{switches} @var{files} |
20737 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
20738 | $ perl gnathtml.pl @r{[}@var{switches}@r{]} @var{files} | |
88e1739c FW |
20739 | @end smallexample |
20740 | ||
20741 | @ifset vms | |
20742 | @node LSE | |
20743 | @section LSE | |
20744 | @findex LSE | |
20745 | ||
20746 | @noindent | |
32e209e4 | 20747 | The GNAT distribution provides an Ada 95 template for the HP Language |
88e1739c FW |
20748 | Sensitive Editor (LSE), a component of DECset. In order to |
20749 | access it, invoke LSE with the qualifier /ENVIRONMENT=GNU:[LIB]ADA95.ENV. | |
20750 | ||
20751 | @node Profiling | |
20752 | @section Profiling | |
20753 | @findex PCA | |
20754 | ||
20755 | @noindent | |
32e209e4 | 20756 | GNAT supports The HP Performance Coverage Analyzer (PCA), a component |
7cd4527e | 20757 | of DECset. To use it proceed as outlined under ``HELP PCA'', except for running |
88e1739c FW |
20758 | the collection phase with the /DEBUG qualifier. |
20759 | ||
20760 | @smallexample | |
20761 | $ GNAT MAKE /DEBUG <PROGRAM_NAME> | |
20762 | $ DEFINE LIB$DEBUG PCA$COLLECTOR | |
20763 | $ RUN/DEBUG <PROGRAM_NAME> | |
20764 | @end smallexample | |
20765 | @noindent | |
20766 | @end ifset | |
20767 | ||
da508766 RD |
20768 | @ifclear vms |
20769 | @c ****************************** | |
20770 | @node Code Coverage and Profiling | |
20771 | @chapter Code Coverage and Profiling | |
20772 | @cindex Code Coverage | |
20773 | @cindex Profiling | |
20774 | ||
20775 | @noindent | |
20776 | This chapter describes how to use @code{gcov} - coverage testing tool - and | |
20777 | @code{gprof} - profiler tool - on your Ada programs. | |
20778 | ||
20779 | @menu | |
c2658843 AC |
20780 | * Code Coverage of Ada Programs with gcov:: |
20781 | * Profiling an Ada Program with gprof:: | |
da508766 RD |
20782 | @end menu |
20783 | ||
c2658843 AC |
20784 | @node Code Coverage of Ada Programs with gcov |
20785 | @section Code Coverage of Ada Programs with gcov | |
da508766 RD |
20786 | @cindex gcov |
20787 | @cindex -fprofile-arcs | |
20788 | @cindex -ftest-coverage | |
20789 | @cindex -coverage | |
20790 | @cindex Code Coverage | |
20791 | ||
20792 | @noindent | |
20793 | @code{gcov} is a test coverage program: it analyzes the execution of a given | |
20794 | program on selected tests, to help you determine the portions of the program | |
20795 | that are still untested. | |
20796 | ||
20797 | @code{gcov} is part of the GCC suite, and is described in detail in the GCC | |
20798 | User's Guide. You can refer to this documentation for a more complete | |
20799 | description. | |
20800 | ||
20801 | This chapter provides a quick startup guide, and | |
20802 | details some Gnat-specific features. | |
20803 | ||
20804 | @menu | |
20805 | * Quick startup guide:: | |
20806 | * Gnat specifics:: | |
20807 | @end menu | |
20808 | ||
20809 | @node Quick startup guide | |
20810 | @subsection Quick startup guide | |
20811 | ||
20812 | In order to perform coverage analysis of a program using @code{gcov}, 3 | |
20813 | steps are needed: | |
20814 | ||
20815 | @itemize @bullet | |
20816 | @item | |
20817 | Code instrumentation during the compilation process | |
20818 | @item | |
20819 | Execution of the instrumented program | |
20820 | @item | |
20821 | Execution of the @code{gcov} tool to generate the result. | |
20822 | @end itemize | |
20823 | ||
20824 | The code instrumentation needed by gcov is created at the object level: | |
20825 | The source code is not modified in any way, because the instrumentation code is | |
20826 | inserted by gcc during the compilation process. To compile your code with code | |
20827 | coverage activated, you need to recompile your whole project using the | |
20828 | switches | |
20829 | @code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using | |
20830 | @code{-fprofile-arcs}. | |
20831 | ||
20832 | @smallexample | |
20833 | $ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \ | |
20834 | -largs -fprofile-arcs | |
20835 | @end smallexample | |
20836 | ||
20837 | This compilation process will create @file{.gcno} files together with | |
20838 | the usual object files. | |
20839 | ||
20840 | Once the program is compiled with coverage instrumentation, you can | |
20841 | run it as many times as needed - on portions of a test suite for | |
20842 | example. The first execution will produce @file{.gcda} files at the | |
20843 | same location as the @file{.gcno} files. The following executions | |
20844 | will update those files, so that a cumulative result of the covered | |
20845 | portions of the program is generated. | |
20846 | ||
276e95ca | 20847 | Finally, you need to call the @code{gcov} tool. The different options of |
da508766 RD |
20848 | @code{gcov} are available in the GCC User's Guide, section 'Invoking gcov'. |
20849 | ||
276e95ca | 20850 | This will create annotated source files with a @file{.gcov} extension: |
da508766 RD |
20851 | @file{my_main.adb} file will be analysed in @file{my_main.adb.gcov}. |
20852 | ||
20853 | @node Gnat specifics | |
20854 | @subsection Gnat specifics | |
20855 | ||
20856 | Because Ada semantics, portions of the source code may be shared among | |
20857 | several object files. This is the case for example when generics are | |
20858 | involved, when inlining is active or when declarations generate initialisation | |
20859 | calls. In order to take | |
20860 | into account this shared code, you need to call @code{gcov} on all | |
20861 | source files of the tested program at once. | |
20862 | ||
20863 | The list of source files might exceed the system's maximum command line | |
20864 | length. In order to bypass this limitation, a new mechanism has been | |
20865 | implemented in @code{gcov}: you can now list all your project's files into a | |
20866 | text file, and provide this file to gcov as a parameter, preceded by a @@ | |
20867 | (e.g. @samp{gcov @@mysrclist.txt}). | |
20868 | ||
34afead0 TG |
20869 | Note that on AIX compiling a static library with @code{-fprofile-arcs} is |
20870 | not supported as there can be unresolved symbols during the final link. | |
20871 | ||
c2658843 AC |
20872 | @node Profiling an Ada Program with gprof |
20873 | @section Profiling an Ada Program with gprof | |
da508766 RD |
20874 | @cindex gprof |
20875 | @cindex -pg | |
20876 | @cindex Profiling | |
20877 | ||
20878 | @noindent | |
20879 | This section is not meant to be an exhaustive documentation of @code{gprof}. | |
20880 | Full documentation for it can be found in the GNU Profiler User's Guide | |
20881 | documentation that is part of this GNAT distribution. | |
20882 | ||
20883 | Profiling a program helps determine the parts of a program that are executed | |
20884 | most often, and are therefore the most time-consuming. | |
20885 | ||
20886 | @code{gprof} is the standard GNU profiling tool; it has been enhanced to | |
20887 | better handle Ada programs and multitasking. | |
276e95ca | 20888 | It is currently supported on the following platforms |
da508766 RD |
20889 | @itemize @bullet |
20890 | @item | |
20891 | linux x86/x86_64 | |
20892 | @item | |
20893 | solaris sparc/sparc64/x86 | |
20894 | @item | |
20895 | windows x86 | |
20896 | @end itemize | |
20897 | ||
20898 | @noindent | |
20899 | In order to profile a program using @code{gprof}, 3 steps are needed: | |
20900 | ||
20901 | @itemize @bullet | |
20902 | @item | |
20903 | Code instrumentation, requiring a full recompilation of the project with the | |
20904 | proper switches. | |
20905 | @item | |
20906 | Execution of the program under the analysis conditions, i.e. with the desired | |
20907 | input. | |
20908 | @item | |
20909 | Analysis of the results using the @code{gprof} tool. | |
20910 | @end itemize | |
20911 | ||
20912 | @noindent | |
20913 | The following sections detail the different steps, and indicate how | |
20914 | to interpret the results: | |
20915 | @menu | |
20916 | * Compilation for profiling:: | |
20917 | * Program execution:: | |
20918 | * Running gprof:: | |
20919 | * Interpretation of profiling results:: | |
20920 | @end menu | |
20921 | ||
20922 | @node Compilation for profiling | |
20923 | @subsection Compilation for profiling | |
20924 | @cindex -pg | |
20925 | @cindex Profiling | |
20926 | ||
20927 | In order to profile a program the first step is to tell the compiler | |
20928 | to generate the necessary profiling information. The compiler switch to be used | |
20929 | is @code{-pg}, which must be added to other compilation switches. This | |
20930 | switch needs to be specified both during compilation and link stages, and can | |
20931 | be specified once when using gnatmake: | |
20932 | ||
20933 | @smallexample | |
20934 | gnatmake -f -pg -P my_project | |
20935 | @end smallexample | |
20936 | ||
20937 | @noindent | |
aa0df10b VC |
20938 | Note that only the objects that were compiled with the @samp{-pg} switch will |
20939 | be profiled; if you need to profile your whole project, use the @samp{-f} | |
20940 | gnatmake switch to force full recompilation. | |
da508766 RD |
20941 | |
20942 | @node Program execution | |
20943 | @subsection Program execution | |
20944 | ||
20945 | @noindent | |
20946 | Once the program has been compiled for profiling, you can run it as usual. | |
20947 | ||
20948 | The only constraint imposed by profiling is that the program must terminate | |
20949 | normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be | |
20950 | properly analyzed. | |
20951 | ||
20952 | Once the program completes execution, a data file called @file{gmon.out} is | |
20953 | generated in the directory where the program was launched from. If this file | |
20954 | already exists, it will be overwritten. | |
20955 | ||
20956 | @node Running gprof | |
20957 | @subsection Running gprof | |
20958 | ||
20959 | @noindent | |
20960 | The @code{gprof} tool is called as follow: | |
20961 | ||
20962 | @smallexample | |
20963 | gprof my_prog gmon.out | |
20964 | @end smallexample | |
20965 | ||
20966 | @noindent | |
20967 | or simpler: | |
20968 | ||
20969 | @smallexample | |
20970 | gprof my_prog | |
20971 | @end smallexample | |
20972 | ||
20973 | @noindent | |
20974 | The complete form of the gprof command line is the following: | |
20975 | ||
20976 | @smallexample | |
20977 | gprof [^switches^options^] [executable [data-file]] | |
20978 | @end smallexample | |
20979 | ||
20980 | @noindent | |
20981 | @code{gprof} supports numerous ^switch^options^. The order of these | |
20982 | ^switch^options^ does not matter. The full list of options can be found in | |
20983 | the GNU Profiler User's Guide documentation that comes with this documentation. | |
20984 | ||
20985 | The following is the subset of those switches that is most relevant: | |
20986 | ||
20987 | @table @option | |
20988 | ||
20989 | @item --demangle[=@var{style}] | |
20990 | @itemx --no-demangle | |
20991 | @cindex @option{--demangle} (@code{gprof}) | |
20992 | These options control whether symbol names should be demangled when | |
20993 | printing output. The default is to demangle C++ symbols. The | |
20994 | @code{--no-demangle} option may be used to turn off demangling. Different | |
20995 | compilers have different mangling styles. The optional demangling style | |
20996 | argument can be used to choose an appropriate demangling style for your | |
20997 | compiler, in particular Ada symbols generated by GNAT can be demangled using | |
20998 | @code{--demangle=gnat}. | |
20999 | ||
21000 | @item -e @var{function_name} | |
21001 | @cindex @option{-e} (@code{gprof}) | |
21002 | The @samp{-e @var{function}} option tells @code{gprof} not to print | |
21003 | information about the function @var{function_name} (and its | |
21004 | children@dots{}) in the call graph. The function will still be listed | |
21005 | as a child of any functions that call it, but its index number will be | |
21006 | shown as @samp{[not printed]}. More than one @samp{-e} option may be | |
21007 | given; only one @var{function_name} may be indicated with each @samp{-e} | |
21008 | option. | |
21009 | ||
21010 | @item -E @var{function_name} | |
21011 | @cindex @option{-E} (@code{gprof}) | |
21012 | The @code{-E @var{function}} option works like the @code{-e} option, but | |
21013 | execution time spent in the function (and children who were not called from | |
21014 | anywhere else), will not be used to compute the percentages-of-time for | |
21015 | the call graph. More than one @samp{-E} option may be given; only one | |
21016 | @var{function_name} may be indicated with each @samp{-E} option. | |
21017 | ||
21018 | @item -f @var{function_name} | |
21019 | @cindex @option{-f} (@code{gprof}) | |
21020 | The @samp{-f @var{function}} option causes @code{gprof} to limit the | |
21021 | call graph to the function @var{function_name} and its children (and | |
21022 | their children@dots{}). More than one @samp{-f} option may be given; | |
21023 | only one @var{function_name} may be indicated with each @samp{-f} | |
21024 | option. | |
21025 | ||
21026 | @item -F @var{function_name} | |
21027 | @cindex @option{-F} (@code{gprof}) | |
21028 | The @samp{-F @var{function}} option works like the @code{-f} option, but | |
21029 | only time spent in the function and its children (and their | |
21030 | children@dots{}) will be used to determine total-time and | |
21031 | percentages-of-time for the call graph. More than one @samp{-F} option | |
21032 | may be given; only one @var{function_name} may be indicated with each | |
21033 | @samp{-F} option. The @samp{-F} option overrides the @samp{-E} option. | |
21034 | ||
21035 | @end table | |
21036 | ||
21037 | @node Interpretation of profiling results | |
21038 | @subsection Interpretation of profiling results | |
21039 | ||
21040 | @noindent | |
21041 | ||
21042 | The results of the profiling analysis are represented by two arrays: the | |
21043 | 'flat profile' and the 'call graph'. Full documentation of those outputs | |
21044 | can be found in the GNU Profiler User's Guide. | |
21045 | ||
21046 | The flat profile shows the time spent in each function of the program, and how | |
21047 | many time it has been called. This allows you to locate easily the most | |
21048 | time-consuming functions. | |
21049 | ||
21050 | The call graph shows, for each subprogram, the subprograms that call it, | |
21051 | and the subprograms that it calls. It also provides an estimate of the time | |
21052 | spent in each of those callers/called subprograms. | |
21053 | @end ifclear | |
21054 | ||
21055 | @c ****************************** | |
88e1739c FW |
21056 | @node Running and Debugging Ada Programs |
21057 | @chapter Running and Debugging Ada Programs | |
21058 | @cindex Debugging | |
21059 | ||
21060 | @noindent | |
87b3f81f AC |
21061 | This chapter discusses how to debug Ada programs. |
21062 | @ifset vms | |
e08b38f5 VC |
21063 | It applies to GNAT on the Alpha OpenVMS platform; |
21064 | for I64 OpenVMS please refer to the @cite{OpenVMS Debugger Manual}, | |
21065 | since HP has implemented Ada support in the OpenVMS debugger on I64. | |
87b3f81f AC |
21066 | @end ifset |
21067 | ||
21068 | An incorrect Ada program may be handled in three ways by the GNAT compiler: | |
88e1739c FW |
21069 | |
21070 | @enumerate | |
21071 | @item | |
21072 | The illegality may be a violation of the static semantics of Ada. In | |
21073 | that case GNAT diagnoses the constructs in the program that are illegal. | |
21074 | It is then a straightforward matter for the user to modify those parts of | |
21075 | the program. | |
21076 | ||
21077 | @item | |
21078 | The illegality may be a violation of the dynamic semantics of Ada. In | |
21079 | that case the program compiles and executes, but may generate incorrect | |
21080 | results, or may terminate abnormally with some exception. | |
21081 | ||
21082 | @item | |
21083 | When presented with a program that contains convoluted errors, GNAT | |
21084 | itself may terminate abnormally without providing full diagnostics on | |
21085 | the incorrect user program. | |
21086 | @end enumerate | |
21087 | ||
21088 | @menu | |
21089 | * The GNAT Debugger GDB:: | |
21090 | * Running GDB:: | |
21091 | * Introduction to GDB Commands:: | |
21092 | * Using Ada Expressions:: | |
21093 | * Calling User-Defined Subprograms:: | |
21094 | * Using the Next Command in a Function:: | |
21095 | * Ada Exceptions:: | |
21096 | * Ada Tasks:: | |
21097 | * Debugging Generic Units:: | |
c2658843 | 21098 | * Remote Debugging with gdbserver:: |
88e1739c FW |
21099 | * GNAT Abnormal Termination or Failure to Terminate:: |
21100 | * Naming Conventions for GNAT Source Files:: | |
21101 | * Getting Internal Debugging Information:: | |
21102 | * Stack Traceback:: | |
21103 | @end menu | |
21104 | ||
21105 | @cindex Debugger | |
21106 | @findex gdb | |
21107 | ||
21108 | @node The GNAT Debugger GDB | |
21109 | @section The GNAT Debugger GDB | |
21110 | ||
21111 | @noindent | |
21112 | @code{GDB} is a general purpose, platform-independent debugger that | |
984a64bc | 21113 | can be used to debug mixed-language programs compiled with @command{gcc}, |
88e1739c FW |
21114 | and in particular is capable of debugging Ada programs compiled with |
21115 | GNAT. The latest versions of @code{GDB} are Ada-aware and can handle | |
21116 | complex Ada data structures. | |
21117 | ||
b2e74434 | 21118 | @xref{Top,, Debugging with GDB, gdb, Debugging with GDB}, |
88e1739c | 21119 | @ifset vms |
b2e74434 | 21120 | located in the GNU:[DOCS] directory, |
88e1739c | 21121 | @end ifset |
b2e74434 | 21122 | for full details on the usage of @code{GDB}, including a section on |
88e1739c FW |
21123 | its usage on programs. This manual should be consulted for full |
21124 | details. The section that follows is a brief introduction to the | |
21125 | philosophy and use of @code{GDB}. | |
21126 | ||
21127 | When GNAT programs are compiled, the compiler optionally writes debugging | |
21128 | information into the generated object file, including information on | |
21129 | line numbers, and on declared types and variables. This information is | |
21130 | separate from the generated code. It makes the object files considerably | |
21131 | larger, but it does not add to the size of the actual executable that | |
21132 | will be loaded into memory, and has no impact on run-time performance. The | |
21133 | generation of debug information is triggered by the use of the | |
1992bbd9 RW |
21134 | ^-g^/DEBUG^ switch in the @command{gcc} or @command{gnatmake} command |
21135 | used to carry out the compilations. It is important to emphasize that | |
21136 | the use of these options does not change the generated code. | |
88e1739c FW |
21137 | |
21138 | The debugging information is written in standard system formats that | |
21139 | are used by many tools, including debuggers and profilers. The format | |
21140 | of the information is typically designed to describe C types and | |
21141 | semantics, but GNAT implements a translation scheme which allows full | |
21142 | details about Ada types and variables to be encoded into these | |
21143 | standard C formats. Details of this encoding scheme may be found in | |
21144 | the file exp_dbug.ads in the GNAT source distribution. However, the | |
21145 | details of this encoding are, in general, of no interest to a user, | |
21146 | since @code{GDB} automatically performs the necessary decoding. | |
21147 | ||
21148 | When a program is bound and linked, the debugging information is | |
21149 | collected from the object files, and stored in the executable image of | |
21150 | the program. Again, this process significantly increases the size of | |
21151 | the generated executable file, but it does not increase the size of | |
21152 | the executable program itself. Furthermore, if this program is run in | |
21153 | the normal manner, it runs exactly as if the debug information were | |
21154 | not present, and takes no more actual memory. | |
21155 | ||
21156 | However, if the program is run under control of @code{GDB}, the | |
21157 | debugger is activated. The image of the program is loaded, at which | |
21158 | point it is ready to run. If a run command is given, then the program | |
21159 | will run exactly as it would have if @code{GDB} were not present. This | |
21160 | is a crucial part of the @code{GDB} design philosophy. @code{GDB} is | |
21161 | entirely non-intrusive until a breakpoint is encountered. If no | |
21162 | breakpoint is ever hit, the program will run exactly as it would if no | |
21163 | debugger were present. When a breakpoint is hit, @code{GDB} accesses | |
21164 | the debugging information and can respond to user commands to inspect | |
21165 | variables, and more generally to report on the state of execution. | |
21166 | ||
7cd4527e | 21167 | @c ************** |
88e1739c FW |
21168 | @node Running GDB |
21169 | @section Running GDB | |
21170 | ||
88e1739c | 21171 | @noindent |
e08b38f5 VC |
21172 | This section describes how to initiate the debugger. |
21173 | @c The above sentence is really just filler, but it was otherwise | |
21174 | @c clumsy to get the first paragraph nonindented given the conditional | |
21175 | @c nature of the description | |
88e1739c FW |
21176 | |
21177 | @ifclear vms | |
e08b38f5 VC |
21178 | The debugger can be launched from a @code{GPS} menu or |
21179 | directly from the command line. The description below covers the latter use. | |
21180 | All the commands shown can be used in the @code{GPS} debug console window, | |
21181 | but there are usually more GUI-based ways to achieve the same effect. | |
88e1739c FW |
21182 | @end ifclear |
21183 | ||
e08b38f5 | 21184 | The command to run @code{GDB} is |
88e1739c FW |
21185 | |
21186 | @smallexample | |
e08b38f5 | 21187 | $ ^gdb program^GDB PROGRAM^ |
88e1739c FW |
21188 | @end smallexample |
21189 | ||
21190 | @noindent | |
21191 | where @code{^program^PROGRAM^} is the name of the executable file. This | |
21192 | activates the debugger and results in a prompt for debugger commands. | |
21193 | The simplest command is simply @code{run}, which causes the program to run | |
21194 | exactly as if the debugger were not present. The following section | |
21195 | describes some of the additional commands that can be given to @code{GDB}. | |
88e1739c | 21196 | |
7cd4527e | 21197 | @c ******************************* |
88e1739c FW |
21198 | @node Introduction to GDB Commands |
21199 | @section Introduction to GDB Commands | |
21200 | ||
21201 | @noindent | |
b2e74434 RW |
21202 | @code{GDB} contains a large repertoire of commands. @xref{Top,, |
21203 | Debugging with GDB, gdb, Debugging with GDB}, | |
88e1739c | 21204 | @ifset vms |
b2e74434 | 21205 | located in the GNU:[DOCS] directory, |
88e1739c | 21206 | @end ifset |
b2e74434 | 21207 | for extensive documentation on the use |
88e1739c | 21208 | of these commands, together with examples of their use. Furthermore, |
1992bbd9 | 21209 | the command @command{help} invoked from within GDB activates a simple help |
88e1739c FW |
21210 | facility which summarizes the available commands and their options. |
21211 | In this section we summarize a few of the most commonly | |
21212 | used commands to give an idea of what @code{GDB} is about. You should create | |
21213 | a simple program with debugging information and experiment with the use of | |
21214 | these @code{GDB} commands on the program as you read through the | |
21215 | following section. | |
21216 | ||
21217 | @table @code | |
21218 | @item set args @var{arguments} | |
21219 | The @var{arguments} list above is a list of arguments to be passed to | |
21220 | the program on a subsequent run command, just as though the arguments | |
21221 | had been entered on a normal invocation of the program. The @code{set args} | |
21222 | command is not needed if the program does not require arguments. | |
21223 | ||
21224 | @item run | |
21225 | The @code{run} command causes execution of the program to start from | |
21226 | the beginning. If the program is already running, that is to say if | |
21227 | you are currently positioned at a breakpoint, then a prompt will ask | |
21228 | for confirmation that you want to abandon the current execution and | |
21229 | restart. | |
21230 | ||
21231 | @item breakpoint @var{location} | |
21232 | The breakpoint command sets a breakpoint, that is to say a point at which | |
21233 | execution will halt and @code{GDB} will await further | |
21234 | commands. @var{location} is | |
21235 | either a line number within a file, given in the format @code{file:linenumber}, | |
21236 | or it is the name of a subprogram. If you request that a breakpoint be set on | |
21237 | a subprogram that is overloaded, a prompt will ask you to specify on which of | |
21238 | those subprograms you want to breakpoint. You can also | |
21239 | specify that all of them should be breakpointed. If the program is run | |
21240 | and execution encounters the breakpoint, then the program | |
21241 | stops and @code{GDB} signals that the breakpoint was encountered by | |
21242 | printing the line of code before which the program is halted. | |
21243 | ||
2383acbd AC |
21244 | @item catch exception @var{name} |
21245 | This command causes the program execution to stop whenever exception | |
21246 | @var{name} is raised. If @var{name} is omitted, then the execution is | |
21247 | suspended when any exception is raised. | |
88e1739c FW |
21248 | |
21249 | @item print @var{expression} | |
21250 | This will print the value of the given expression. Most simple | |
21251 | Ada expression formats are properly handled by @code{GDB}, so the expression | |
21252 | can contain function calls, variables, operators, and attribute references. | |
21253 | ||
21254 | @item continue | |
21255 | Continues execution following a breakpoint, until the next breakpoint or the | |
21256 | termination of the program. | |
21257 | ||
21258 | @item step | |
7cd4527e AC |
21259 | Executes a single line after a breakpoint. If the next statement |
21260 | is a subprogram call, execution continues into (the first statement of) | |
21261 | the called subprogram. | |
88e1739c FW |
21262 | |
21263 | @item next | |
21264 | Executes a single line. If this line is a subprogram call, executes and | |
21265 | returns from the call. | |
21266 | ||
21267 | @item list | |
21268 | Lists a few lines around the current source location. In practice, it | |
21269 | is usually more convenient to have a separate edit window open with the | |
21270 | relevant source file displayed. Successive applications of this command | |
21271 | print subsequent lines. The command can be given an argument which is a | |
21272 | line number, in which case it displays a few lines around the specified one. | |
21273 | ||
21274 | @item backtrace | |
21275 | Displays a backtrace of the call chain. This command is typically | |
21276 | used after a breakpoint has occurred, to examine the sequence of calls that | |
21277 | leads to the current breakpoint. The display includes one line for each | |
21278 | activation record (frame) corresponding to an active subprogram. | |
21279 | ||
21280 | @item up | |
21281 | At a breakpoint, @code{GDB} can display the values of variables local | |
21282 | to the current frame. The command @code{up} can be used to | |
21283 | examine the contents of other active frames, by moving the focus up | |
21284 | the stack, that is to say from callee to caller, one frame at a time. | |
21285 | ||
21286 | @item down | |
21287 | Moves the focus of @code{GDB} down from the frame currently being | |
21288 | examined to the frame of its callee (the reverse of the previous command), | |
21289 | ||
21290 | @item frame @var{n} | |
21291 | Inspect the frame with the given number. The value 0 denotes the frame | |
21292 | of the current breakpoint, that is to say the top of the call stack. | |
21293 | ||
21294 | @end table | |
21295 | ||
e08b38f5 | 21296 | @noindent |
88e1739c FW |
21297 | The above list is a very short introduction to the commands that |
21298 | @code{GDB} provides. Important additional capabilities, including conditional | |
21299 | breakpoints, the ability to execute command sequences on a breakpoint, | |
21300 | the ability to debug at the machine instruction level and many other | |
b2e74434 RW |
21301 | features are described in detail in @ref{Top,, Debugging with GDB, gdb, |
21302 | Debugging with GDB}. Note that most commands can be abbreviated | |
88e1739c FW |
21303 | (for example, c for continue, bt for backtrace). |
21304 | ||
21305 | @node Using Ada Expressions | |
21306 | @section Using Ada Expressions | |
21307 | @cindex Ada expressions | |
21308 | ||
21309 | @noindent | |
21310 | @code{GDB} supports a fairly large subset of Ada expression syntax, with some | |
21311 | extensions. The philosophy behind the design of this subset is | |
21312 | ||
21313 | @itemize @bullet | |
21314 | @item | |
21315 | That @code{GDB} should provide basic literals and access to operations for | |
21316 | arithmetic, dereferencing, field selection, indexing, and subprogram calls, | |
21317 | leaving more sophisticated computations to subprograms written into the | |
21318 | program (which therefore may be called from @code{GDB}). | |
21319 | ||
21320 | @item | |
21321 | That type safety and strict adherence to Ada language restrictions | |
21322 | are not particularly important to the @code{GDB} user. | |
21323 | ||
21324 | @item | |
21325 | That brevity is important to the @code{GDB} user. | |
21326 | @end itemize | |
21327 | ||
e08b38f5 | 21328 | @noindent |
88e1739c FW |
21329 | Thus, for brevity, the debugger acts as if there were |
21330 | implicit @code{with} and @code{use} clauses in effect for all user-written | |
21331 | packages, thus making it unnecessary to fully qualify most names with | |
21332 | their packages, regardless of context. Where this causes ambiguity, | |
21333 | @code{GDB} asks the user's intent. | |
21334 | ||
b2e74434 RW |
21335 | For details on the supported Ada syntax, see @ref{Top,, Debugging with |
21336 | GDB, gdb, Debugging with GDB}. | |
88e1739c FW |
21337 | |
21338 | @node Calling User-Defined Subprograms | |
21339 | @section Calling User-Defined Subprograms | |
21340 | ||
21341 | @noindent | |
21342 | An important capability of @code{GDB} is the ability to call user-defined | |
21343 | subprograms while debugging. This is achieved simply by entering | |
21344 | a subprogram call statement in the form: | |
21345 | ||
21346 | @smallexample | |
21347 | call subprogram-name (parameters) | |
21348 | @end smallexample | |
21349 | ||
21350 | @noindent | |
21351 | The keyword @code{call} can be omitted in the normal case where the | |
21352 | @code{subprogram-name} does not coincide with any of the predefined | |
21353 | @code{GDB} commands. | |
21354 | ||
21355 | The effect is to invoke the given subprogram, passing it the | |
21356 | list of parameters that is supplied. The parameters can be expressions and | |
21357 | can include variables from the program being debugged. The | |
21358 | subprogram must be defined | |
21359 | at the library level within your program, and @code{GDB} will call the | |
21360 | subprogram within the environment of your program execution (which | |
21361 | means that the subprogram is free to access or even modify variables | |
21362 | within your program). | |
21363 | ||
21364 | The most important use of this facility is in allowing the inclusion of | |
21365 | debugging routines that are tailored to particular data structures | |
21366 | in your program. Such debugging routines can be written to provide a suitably | |
21367 | high-level description of an abstract type, rather than a low-level dump | |
21368 | of its physical layout. After all, the standard | |
21369 | @code{GDB print} command only knows the physical layout of your | |
21370 | types, not their abstract meaning. Debugging routines can provide information | |
21371 | at the desired semantic level and are thus enormously useful. | |
21372 | ||
21373 | For example, when debugging GNAT itself, it is crucial to have access to | |
21374 | the contents of the tree nodes used to represent the program internally. | |
21375 | But tree nodes are represented simply by an integer value (which in turn | |
21376 | is an index into a table of nodes). | |
21377 | Using the @code{print} command on a tree node would simply print this integer | |
21378 | value, which is not very useful. But the PN routine (defined in file | |
21379 | treepr.adb in the GNAT sources) takes a tree node as input, and displays | |
21380 | a useful high level representation of the tree node, which includes the | |
21381 | syntactic category of the node, its position in the source, the integers | |
21382 | that denote descendant nodes and parent node, as well as varied | |
21383 | semantic information. To study this example in more detail, you might want to | |
21384 | look at the body of the PN procedure in the stated file. | |
21385 | ||
21386 | @node Using the Next Command in a Function | |
21387 | @section Using the Next Command in a Function | |
21388 | ||
21389 | @noindent | |
21390 | When you use the @code{next} command in a function, the current source | |
21391 | location will advance to the next statement as usual. A special case | |
21392 | arises in the case of a @code{return} statement. | |
21393 | ||
7cd4527e | 21394 | Part of the code for a return statement is the ``epilog'' of the function. |
88e1739c FW |
21395 | This is the code that returns to the caller. There is only one copy of |
21396 | this epilog code, and it is typically associated with the last return | |
21397 | statement in the function if there is more than one return. In some | |
21398 | implementations, this epilog is associated with the first statement | |
21399 | of the function. | |
21400 | ||
21401 | The result is that if you use the @code{next} command from a return | |
21402 | statement that is not the last return statement of the function you | |
21403 | may see a strange apparent jump to the last return statement or to | |
21404 | the start of the function. You should simply ignore this odd jump. | |
21405 | The value returned is always that from the first return statement | |
21406 | that was stepped through. | |
21407 | ||
21408 | @node Ada Exceptions | |
2383acbd | 21409 | @section Stopping when Ada Exceptions are Raised |
88e1739c FW |
21410 | @cindex Exceptions |
21411 | ||
21412 | @noindent | |
2383acbd AC |
21413 | You can set catchpoints that stop the program execution when your program |
21414 | raises selected exceptions. | |
88e1739c FW |
21415 | |
21416 | @table @code | |
2383acbd AC |
21417 | @item catch exception |
21418 | Set a catchpoint that stops execution whenever (any task in the) program | |
21419 | raises any exception. | |
88e1739c | 21420 | |
2383acbd AC |
21421 | @item catch exception @var{name} |
21422 | Set a catchpoint that stops execution whenever (any task in the) program | |
21423 | raises the exception @var{name}. | |
88e1739c | 21424 | |
2383acbd | 21425 | @item catch exception unhandled |
308e6f3a | 21426 | Set a catchpoint that stops executing whenever (any task in the) program |
2383acbd | 21427 | raises an exception for which there is no handler. |
88e1739c FW |
21428 | |
21429 | @item info exceptions | |
21430 | @itemx info exceptions @var{regexp} | |
21431 | The @code{info exceptions} command permits the user to examine all defined | |
21432 | exceptions within Ada programs. With a regular expression, @var{regexp}, as | |
21433 | argument, prints out only those exceptions whose name matches @var{regexp}. | |
21434 | @end table | |
21435 | ||
21436 | @node Ada Tasks | |
21437 | @section Ada Tasks | |
21438 | @cindex Tasks | |
21439 | ||
21440 | @noindent | |
21441 | @code{GDB} allows the following task-related commands: | |
21442 | ||
21443 | @table @code | |
21444 | @item info tasks | |
21445 | This command shows a list of current Ada tasks, as in the following example: | |
21446 | ||
21447 | @smallexample | |
21448 | @iftex | |
21449 | @leftskip=0cm | |
21450 | @end iftex | |
21451 | (gdb) info tasks | |
21452 | ID TID P-ID Thread Pri State Name | |
21453 | 1 8088000 0 807e000 15 Child Activation Wait main_task | |
21454 | 2 80a4000 1 80ae000 15 Accept/Select Wait b | |
21455 | 3 809a800 1 80a4800 15 Child Activation Wait a | |
21456 | * 4 80ae800 3 80b8000 15 Running c | |
21457 | @end smallexample | |
21458 | ||
21459 | @noindent | |
21460 | In this listing, the asterisk before the first task indicates it to be the | |
21461 | currently running task. The first column lists the task ID that is used | |
21462 | to refer to tasks in the following commands. | |
21463 | ||
21464 | @item break @var{linespec} task @var{taskid} | |
21465 | @itemx break @var{linespec} task @var{taskid} if @dots{} | |
21466 | @cindex Breakpoints and tasks | |
21467 | These commands are like the @code{break @dots{} thread @dots{}}. | |
21468 | @var{linespec} specifies source lines. | |
21469 | ||
21470 | Use the qualifier @samp{task @var{taskid}} with a breakpoint command | |
21471 | to specify that you only want @code{GDB} to stop the program when a | |
21472 | particular Ada task reaches this breakpoint. @var{taskid} is one of the | |
21473 | numeric task identifiers assigned by @code{GDB}, shown in the first | |
21474 | column of the @samp{info tasks} display. | |
21475 | ||
21476 | If you do not specify @samp{task @var{taskid}} when you set a | |
21477 | breakpoint, the breakpoint applies to @emph{all} tasks of your | |
21478 | program. | |
21479 | ||
21480 | You can use the @code{task} qualifier on conditional breakpoints as | |
21481 | well; in this case, place @samp{task @var{taskid}} before the | |
21482 | breakpoint condition (before the @code{if}). | |
21483 | ||
21484 | @item task @var{taskno} | |
21485 | @cindex Task switching | |
21486 | ||
21487 | This command allows to switch to the task referred by @var{taskno}. In | |
21488 | particular, This allows to browse the backtrace of the specified | |
21489 | task. It is advised to switch back to the original task before | |
21490 | continuing execution otherwise the scheduling of the program may be | |
ce2e12c2 | 21491 | perturbed. |
88e1739c FW |
21492 | @end table |
21493 | ||
21494 | @noindent | |
7cd4527e | 21495 | For more detailed information on the tasking support, |
b2e74434 | 21496 | see @ref{Top,, Debugging with GDB, gdb, Debugging with GDB}. |
88e1739c FW |
21497 | |
21498 | @node Debugging Generic Units | |
21499 | @section Debugging Generic Units | |
21500 | @cindex Debugging Generic Units | |
21501 | @cindex Generics | |
21502 | ||
21503 | @noindent | |
21504 | GNAT always uses code expansion for generic instantiation. This means that | |
21505 | each time an instantiation occurs, a complete copy of the original code is | |
21506 | made, with appropriate substitutions of formals by actuals. | |
21507 | ||
21508 | It is not possible to refer to the original generic entities in | |
21509 | @code{GDB}, but it is always possible to debug a particular instance of | |
21510 | a generic, by using the appropriate expanded names. For example, if we have | |
21511 | ||
7cd4527e | 21512 | @smallexample @c ada |
88e1739c FW |
21513 | @group |
21514 | @cartouche | |
7cd4527e | 21515 | procedure g is |
88e1739c | 21516 | |
7cd4527e AC |
21517 | generic package k is |
21518 | procedure kp (v1 : in out integer); | |
21519 | end k; | |
88e1739c | 21520 | |
7cd4527e AC |
21521 | package body k is |
21522 | procedure kp (v1 : in out integer) is | |
21523 | begin | |
88e1739c | 21524 | v1 := v1 + 1; |
7cd4527e AC |
21525 | end kp; |
21526 | end k; | |
88e1739c | 21527 | |
7cd4527e AC |
21528 | package k1 is new k; |
21529 | package k2 is new k; | |
88e1739c FW |
21530 | |
21531 | var : integer := 1; | |
21532 | ||
7cd4527e | 21533 | begin |
88e1739c FW |
21534 | k1.kp (var); |
21535 | k2.kp (var); | |
21536 | k1.kp (var); | |
21537 | k2.kp (var); | |
7cd4527e | 21538 | end; |
88e1739c FW |
21539 | @end cartouche |
21540 | @end group | |
21541 | @end smallexample | |
21542 | ||
21543 | @noindent | |
21544 | Then to break on a call to procedure kp in the k2 instance, simply | |
21545 | use the command: | |
21546 | ||
21547 | @smallexample | |
21548 | (gdb) break g.k2.kp | |
21549 | @end smallexample | |
21550 | ||
21551 | @noindent | |
21552 | When the breakpoint occurs, you can step through the code of the | |
21553 | instance in the normal manner and examine the values of local variables, as for | |
21554 | other units. | |
21555 | ||
c2658843 AC |
21556 | @node Remote Debugging with gdbserver |
21557 | @section Remote Debugging with gdbserver | |
21558 | @cindex Remote Debugging with gdbserver | |
4519314c AC |
21559 | |
21560 | @noindent | |
21561 | On platforms where gdbserver is supported, it is possible to use this tool | |
21562 | to debug your application remotely. This can be useful in situations | |
21563 | where the program needs to be run on a target host that is different | |
21564 | from the host used for development, particularly when the target has | |
21565 | a limited amount of resources (either CPU and/or memory). | |
21566 | ||
21567 | To do so, start your program using gdbserver on the target machine. | |
21568 | gdbserver then automatically suspends the execution of your program | |
21569 | at its entry point, waiting for a debugger to connect to it. The | |
21570 | following commands starts an application and tells gdbserver to | |
21571 | wait for a connection with the debugger on localhost port 4444. | |
21572 | ||
21573 | @smallexample | |
21574 | $ gdbserver localhost:4444 program | |
21575 | Process program created; pid = 5685 | |
21576 | Listening on port 4444 | |
21577 | @end smallexample | |
21578 | ||
21579 | Once gdbserver has started listening, we can tell the debugger to establish | |
21580 | a connection with this gdbserver, and then start the same debugging session | |
21581 | as if the program was being debugged on the same host, directly under | |
21582 | the control of GDB. | |
21583 | ||
21584 | @smallexample | |
21585 | $ gdb program | |
21586 | (gdb) target remote targethost:4444 | |
21587 | Remote debugging using targethost:4444 | |
21588 | 0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so. | |
21589 | (gdb) b foo.adb:3 | |
21590 | Breakpoint 1 at 0x401f0c: file foo.adb, line 3. | |
21591 | (gdb) continue | |
21592 | Continuing. | |
21593 | ||
21594 | Breakpoint 1, foo () at foo.adb:4 | |
21595 | 4 end foo; | |
21596 | @end smallexample | |
21597 | ||
21598 | It is also possible to use gdbserver to attach to an already running | |
21599 | program, in which case the execution of that program is simply suspended | |
21600 | until the connection between the debugger and gdbserver is established. | |
21601 | ||
21602 | For more information on how to use gdbserver, @ref{Top, Server, Using | |
164e06c6 | 21603 | the gdbserver Program, gdb, Debugging with GDB}. @value{EDITION} provides support |
4519314c AC |
21604 | for gdbserver on x86-linux, x86-windows and x86_64-linux. |
21605 | ||
88e1739c FW |
21606 | @node GNAT Abnormal Termination or Failure to Terminate |
21607 | @section GNAT Abnormal Termination or Failure to Terminate | |
21608 | @cindex GNAT Abnormal Termination or Failure to Terminate | |
21609 | ||
21610 | @noindent | |
21611 | When presented with programs that contain serious errors in syntax | |
21612 | or semantics, | |
21613 | GNAT may on rare occasions experience problems in operation, such | |
21614 | as aborting with a | |
21615 | segmentation fault or illegal memory access, raising an internal | |
21616 | exception, terminating abnormally, or failing to terminate at all. | |
21617 | In such cases, you can activate | |
21618 | various features of GNAT that can help you pinpoint the construct in your | |
21619 | program that is the likely source of the problem. | |
21620 | ||
21621 | The following strategies are presented in increasing order of | |
21622 | difficulty, corresponding to your experience in using GNAT and your | |
21623 | familiarity with compiler internals. | |
21624 | ||
21625 | @enumerate | |
21626 | @item | |
984a64bc | 21627 | Run @command{gcc} with the @option{-gnatf}. This first |
88e1739c FW |
21628 | switch causes all errors on a given line to be reported. In its absence, |
21629 | only the first error on a line is displayed. | |
21630 | ||
21631 | The @option{-gnatdO} switch causes errors to be displayed as soon as they | |
21632 | are encountered, rather than after compilation is terminated. If GNAT | |
21633 | terminates prematurely or goes into an infinite loop, the last error | |
21634 | message displayed may help to pinpoint the culprit. | |
21635 | ||
21636 | @item | |
984a64bc AC |
21637 | Run @command{gcc} with the @option{^-v (verbose)^/VERBOSE^} switch. In this |
21638 | mode, @command{gcc} produces ongoing information about the progress of the | |
88e1739c FW |
21639 | compilation and provides the name of each procedure as code is |
21640 | generated. This switch allows you to find which Ada procedure was being | |
21641 | compiled when it encountered a code generation problem. | |
21642 | ||
21643 | @item | |
21644 | @cindex @option{-gnatdc} switch | |
984a64bc | 21645 | Run @command{gcc} with the @option{-gnatdc} switch. This is a GNAT specific |
7cd4527e AC |
21646 | switch that does for the front-end what @option{^-v^VERBOSE^} does |
21647 | for the back end. The system prints the name of each unit, | |
21648 | either a compilation unit or nested unit, as it is being analyzed. | |
88e1739c FW |
21649 | @item |
21650 | Finally, you can start | |
21651 | @code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the | |
21652 | front-end of GNAT, and can be run independently (normally it is just | |
984a64bc | 21653 | called from @command{gcc}). You can use @code{gdb} on @code{gnat1} as you |
88e1739c FW |
21654 | would on a C program (but @pxref{The GNAT Debugger GDB} for caveats). The |
21655 | @code{where} command is the first line of attack; the variable | |
21656 | @code{lineno} (seen by @code{print lineno}), used by the second phase of | |
984a64bc | 21657 | @code{gnat1} and by the @command{gcc} backend, indicates the source line at |
88e1739c FW |
21658 | which the execution stopped, and @code{input_file name} indicates the name of |
21659 | the source file. | |
21660 | @end enumerate | |
21661 | ||
21662 | @node Naming Conventions for GNAT Source Files | |
21663 | @section Naming Conventions for GNAT Source Files | |
21664 | ||
21665 | @noindent | |
21666 | In order to examine the workings of the GNAT system, the following | |
21667 | brief description of its organization may be helpful: | |
21668 | ||
21669 | @itemize @bullet | |
21670 | @item | |
21671 | Files with prefix @file{^sc^SC^} contain the lexical scanner. | |
21672 | ||
21673 | @item | |
21674 | All files prefixed with @file{^par^PAR^} are components of the parser. The | |
e08b38f5 | 21675 | numbers correspond to chapters of the Ada Reference Manual. For example, |
88e1739c FW |
21676 | parsing of select statements can be found in @file{par-ch9.adb}. |
21677 | ||
21678 | @item | |
21679 | All files prefixed with @file{^sem^SEM^} perform semantic analysis. The | |
21680 | numbers correspond to chapters of the Ada standard. For example, all | |
21681 | issues involving context clauses can be found in @file{sem_ch10.adb}. In | |
21682 | addition, some features of the language require sufficient special processing | |
21683 | to justify their own semantic files: sem_aggr for aggregates, sem_disp for | |
21684 | dynamic dispatching, etc. | |
21685 | ||
21686 | @item | |
21687 | All files prefixed with @file{^exp^EXP^} perform normalization and | |
21688 | expansion of the intermediate representation (abstract syntax tree, or AST). | |
21689 | these files use the same numbering scheme as the parser and semantics files. | |
21690 | For example, the construction of record initialization procedures is done in | |
21691 | @file{exp_ch3.adb}. | |
21692 | ||
21693 | @item | |
21694 | The files prefixed with @file{^bind^BIND^} implement the binder, which | |
21695 | verifies the consistency of the compilation, determines an order of | |
21696 | elaboration, and generates the bind file. | |
21697 | ||
21698 | @item | |
21699 | The files @file{atree.ads} and @file{atree.adb} detail the low-level | |
21700 | data structures used by the front-end. | |
21701 | ||
21702 | @item | |
21703 | The files @file{sinfo.ads} and @file{sinfo.adb} detail the structure of | |
21704 | the abstract syntax tree as produced by the parser. | |
21705 | ||
21706 | @item | |
21707 | The files @file{einfo.ads} and @file{einfo.adb} detail the attributes of | |
21708 | all entities, computed during semantic analysis. | |
21709 | ||
21710 | @item | |
21711 | Library management issues are dealt with in files with prefix | |
21712 | @file{^lib^LIB^}. | |
21713 | ||
21714 | @item | |
21715 | @findex Ada | |
21716 | @cindex Annex A | |
21717 | Ada files with the prefix @file{^a-^A-^} are children of @code{Ada}, as | |
21718 | defined in Annex A. | |
21719 | ||
21720 | @item | |
21721 | @findex Interfaces | |
21722 | @cindex Annex B | |
21723 | Files with prefix @file{^i-^I-^} are children of @code{Interfaces}, as | |
21724 | defined in Annex B. | |
21725 | ||
21726 | @item | |
21727 | @findex System | |
21728 | Files with prefix @file{^s-^S-^} are children of @code{System}. This includes | |
21729 | both language-defined children and GNAT run-time routines. | |
21730 | ||
21731 | @item | |
21732 | @findex GNAT | |
21733 | Files with prefix @file{^g-^G-^} are children of @code{GNAT}. These are useful | |
1a5f40e1 | 21734 | general-purpose packages, fully documented in their specs. All |
984a64bc | 21735 | the other @file{.c} files are modifications of common @command{gcc} files. |
88e1739c FW |
21736 | @end itemize |
21737 | ||
21738 | @node Getting Internal Debugging Information | |
21739 | @section Getting Internal Debugging Information | |
21740 | ||
21741 | @noindent | |
21742 | Most compilers have internal debugging switches and modes. GNAT | |
21743 | does also, except GNAT internal debugging switches and modes are not | |
21744 | secret. A summary and full description of all the compiler and binder | |
21745 | debug flags are in the file @file{debug.adb}. You must obtain the | |
21746 | sources of the compiler to see the full detailed effects of these flags. | |
21747 | ||
21748 | The switches that print the source of the program (reconstructed from | |
21749 | the internal tree) are of general interest for user programs, as are the | |
21750 | options to print | |
21751 | the full internal tree, and the entity table (the symbol table | |
21752 | information). The reconstructed source provides a readable version of the | |
7cd4527e AC |
21753 | program after the front-end has completed analysis and expansion, |
21754 | and is useful when studying the performance of specific constructs. | |
21755 | For example, constraint checks are indicated, complex aggregates | |
21756 | are replaced with loops and assignments, and tasking primitives | |
21757 | are replaced with run-time calls. | |
88e1739c FW |
21758 | |
21759 | @node Stack Traceback | |
21760 | @section Stack Traceback | |
21761 | @cindex traceback | |
21762 | @cindex stack traceback | |
21763 | @cindex stack unwinding | |
21764 | ||
21765 | @noindent | |
21766 | Traceback is a mechanism to display the sequence of subprogram calls that | |
21767 | leads to a specified execution point in a program. Often (but not always) | |
21768 | the execution point is an instruction at which an exception has been raised. | |
21769 | This mechanism is also known as @i{stack unwinding} because it obtains | |
21770 | its information by scanning the run-time stack and recovering the activation | |
21771 | records of all active subprograms. Stack unwinding is one of the most | |
21772 | important tools for program debugging. | |
21773 | ||
88e1739c FW |
21774 | The first entry stored in traceback corresponds to the deepest calling level, |
21775 | that is to say the subprogram currently executing the instruction | |
21776 | from which we want to obtain the traceback. | |
21777 | ||
88e1739c | 21778 | Note that there is no runtime performance penalty when stack traceback |
7cd4527e | 21779 | is enabled, and no exception is raised during program execution. |
88e1739c FW |
21780 | |
21781 | @menu | |
21782 | * Non-Symbolic Traceback:: | |
21783 | * Symbolic Traceback:: | |
21784 | @end menu | |
21785 | ||
21786 | @node Non-Symbolic Traceback | |
21787 | @subsection Non-Symbolic Traceback | |
21788 | @cindex traceback, non-symbolic | |
21789 | ||
21790 | @noindent | |
21791 | Note: this feature is not supported on all platforms. See | |
21792 | @file{GNAT.Traceback spec in g-traceb.ads} for a complete list of supported | |
21793 | platforms. | |
21794 | ||
21795 | @menu | |
21796 | * Tracebacks From an Unhandled Exception:: | |
21797 | * Tracebacks From Exception Occurrences (non-symbolic):: | |
21798 | * Tracebacks From Anywhere in a Program (non-symbolic):: | |
21799 | @end menu | |
21800 | ||
21801 | @node Tracebacks From an Unhandled Exception | |
21802 | @subsubsection Tracebacks From an Unhandled Exception | |
21803 | ||
21804 | @noindent | |
21805 | A runtime non-symbolic traceback is a list of addresses of call instructions. | |
7cd4527e | 21806 | To enable this feature you must use the @option{-E} |
88e1739c | 21807 | @code{gnatbind}'s option. With this option a stack traceback is stored as part |
7cd4527e AC |
21808 | of exception information. You can retrieve this information using the |
21809 | @code{addr2line} tool. | |
88e1739c | 21810 | |
7cd4527e | 21811 | Here is a simple example: |
88e1739c | 21812 | |
7cd4527e | 21813 | @smallexample @c ada |
88e1739c | 21814 | @cartouche |
88e1739c FW |
21815 | procedure STB is |
21816 | ||
21817 | procedure P1 is | |
21818 | begin | |
21819 | raise Constraint_Error; | |
21820 | end P1; | |
21821 | ||
21822 | procedure P2 is | |
21823 | begin | |
21824 | P1; | |
21825 | end P2; | |
21826 | ||
21827 | begin | |
21828 | P2; | |
21829 | end STB; | |
88e1739c FW |
21830 | @end cartouche |
21831 | @end smallexample | |
21832 | ||
21833 | @smallexample | |
21834 | $ gnatmake stb -bargs -E | |
21835 | $ stb | |
21836 | ||
21837 | Execution terminated by unhandled exception | |
21838 | Exception name: CONSTRAINT_ERROR | |
21839 | Message: stb.adb:5 | |
21840 | Call stack traceback locations: | |
21841 | 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 | |
21842 | @end smallexample | |
21843 | ||
21844 | @noindent | |
21845 | As we see the traceback lists a sequence of addresses for the unhandled | |
7cd4527e | 21846 | exception @code{CONSTRAINT_ERROR} raised in procedure P1. It is easy to |
88e1739c FW |
21847 | guess that this exception come from procedure P1. To translate these |
21848 | addresses into the source lines where the calls appear, the | |
21849 | @code{addr2line} tool, described below, is invaluable. The use of this tool | |
21850 | requires the program to be compiled with debug information. | |
21851 | ||
21852 | @smallexample | |
21853 | $ gnatmake -g stb -bargs -E | |
21854 | $ stb | |
21855 | ||
21856 | Execution terminated by unhandled exception | |
21857 | Exception name: CONSTRAINT_ERROR | |
21858 | Message: stb.adb:5 | |
21859 | Call stack traceback locations: | |
21860 | 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 | |
21861 | ||
21862 | $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 | |
21863 | 0x4011f1 0x77e892a4 | |
21864 | ||
21865 | 00401373 at d:/stb/stb.adb:5 | |
21866 | 0040138B at d:/stb/stb.adb:10 | |
21867 | 0040139C at d:/stb/stb.adb:14 | |
21868 | 00401335 at d:/stb/b~stb.adb:104 | |
d488f6ea RW |
21869 | 004011C4 at /build/@dots{}/crt1.c:200 |
21870 | 004011F1 at /build/@dots{}/crt1.c:222 | |
88e1739c FW |
21871 | 77E892A4 in ?? at ??:0 |
21872 | @end smallexample | |
21873 | ||
21874 | @noindent | |
7cd4527e | 21875 | The @code{addr2line} tool has several other useful options: |
88e1739c FW |
21876 | |
21877 | @table @code | |
21878 | @item --functions | |
21879 | to get the function name corresponding to any location | |
21880 | ||
21881 | @item --demangle=gnat | |
7cd4527e AC |
21882 | to use the gnat decoding mode for the function names. Note that |
21883 | for binutils version 2.9.x the option is simply @option{--demangle}. | |
88e1739c FW |
21884 | @end table |
21885 | ||
21886 | @smallexample | |
21887 | $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b | |
21888 | 0x40139c 0x401335 0x4011c4 0x4011f1 | |
21889 | ||
21890 | 00401373 in stb.p1 at d:/stb/stb.adb:5 | |
21891 | 0040138B in stb.p2 at d:/stb/stb.adb:10 | |
21892 | 0040139C in stb at d:/stb/stb.adb:14 | |
21893 | 00401335 in main at d:/stb/b~stb.adb:104 | |
d488f6ea RW |
21894 | 004011C4 in <__mingw_CRTStartup> at /build/@dots{}/crt1.c:200 |
21895 | 004011F1 in <mainCRTStartup> at /build/@dots{}/crt1.c:222 | |
88e1739c FW |
21896 | @end smallexample |
21897 | ||
21898 | @noindent | |
21899 | From this traceback we can see that the exception was raised in | |
21900 | @file{stb.adb} at line 5, which was reached from a procedure call in | |
21901 | @file{stb.adb} at line 10, and so on. The @file{b~std.adb} is the binder file, | |
21902 | which contains the call to the main program. | |
984a64bc | 21903 | @xref{Running gnatbind}. The remaining entries are assorted runtime routines, |
88e1739c FW |
21904 | and the output will vary from platform to platform. |
21905 | ||
88e1739c FW |
21906 | It is also possible to use @code{GDB} with these traceback addresses to debug |
21907 | the program. For example, we can break at a given code location, as reported | |
21908 | in the stack traceback: | |
21909 | ||
21910 | @smallexample | |
21911 | $ gdb -nw stb | |
7cd4527e | 21912 | @ifclear vms |
88e1739c FW |
21913 | @noindent |
21914 | Furthermore, this feature is not implemented inside Windows DLL. Only | |
21915 | the non-symbolic traceback is reported in this case. | |
7cd4527e | 21916 | @end ifclear |
88e1739c FW |
21917 | |
21918 | (gdb) break *0x401373 | |
21919 | Breakpoint 1 at 0x401373: file stb.adb, line 5. | |
21920 | @end smallexample | |
21921 | ||
21922 | @noindent | |
21923 | It is important to note that the stack traceback addresses | |
21924 | do not change when debug information is included. This is particularly useful | |
21925 | because it makes it possible to release software without debug information (to | |
21926 | minimize object size), get a field report that includes a stack traceback | |
21927 | whenever an internal bug occurs, and then be able to retrieve the sequence | |
21928 | of calls with the same program compiled with debug information. | |
21929 | ||
21930 | @node Tracebacks From Exception Occurrences (non-symbolic) | |
21931 | @subsubsection Tracebacks From Exception Occurrences | |
21932 | ||
21933 | @noindent | |
7cd4527e | 21934 | Non-symbolic tracebacks are obtained by using the @option{-E} binder argument. |
88e1739c FW |
21935 | The stack traceback is attached to the exception information string, and can |
21936 | be retrieved in an exception handler within the Ada program, by means of the | |
e08b38f5 | 21937 | Ada facilities defined in @code{Ada.Exceptions}. Here is a simple example: |
88e1739c | 21938 | |
7cd4527e | 21939 | @smallexample @c ada |
88e1739c FW |
21940 | with Ada.Text_IO; |
21941 | with Ada.Exceptions; | |
21942 | ||
21943 | procedure STB is | |
21944 | ||
21945 | use Ada; | |
21946 | use Ada.Exceptions; | |
21947 | ||
21948 | procedure P1 is | |
21949 | K : Positive := 1; | |
21950 | begin | |
21951 | K := K - 1; | |
21952 | exception | |
21953 | when E : others => | |
21954 | Text_IO.Put_Line (Exception_Information (E)); | |
21955 | end P1; | |
21956 | ||
21957 | procedure P2 is | |
21958 | begin | |
21959 | P1; | |
21960 | end P2; | |
21961 | ||
21962 | begin | |
21963 | P2; | |
21964 | end STB; | |
88e1739c FW |
21965 | @end smallexample |
21966 | ||
21967 | @noindent | |
21968 | This program will output: | |
21969 | ||
21970 | @smallexample | |
21971 | $ stb | |
21972 | ||
21973 | Exception name: CONSTRAINT_ERROR | |
21974 | Message: stb.adb:12 | |
21975 | Call stack traceback locations: | |
21976 | 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 | |
21977 | @end smallexample | |
21978 | ||
21979 | @node Tracebacks From Anywhere in a Program (non-symbolic) | |
21980 | @subsubsection Tracebacks From Anywhere in a Program | |
21981 | ||
21982 | @noindent | |
21983 | It is also possible to retrieve a stack traceback from anywhere in a | |
21984 | program. For this you need to | |
21985 | use the @code{GNAT.Traceback} API. This package includes a procedure called | |
21986 | @code{Call_Chain} that computes a complete stack traceback, as well as useful | |
21987 | display procedures described below. It is not necessary to use the | |
7cd4527e | 21988 | @option{-E gnatbind} option in this case, because the stack traceback mechanism |
88e1739c FW |
21989 | is invoked explicitly. |
21990 | ||
21991 | @noindent | |
21992 | In the following example we compute a traceback at a specific location in | |
21993 | the program, and we display it using @code{GNAT.Debug_Utilities.Image} to | |
21994 | convert addresses to strings: | |
21995 | ||
7cd4527e | 21996 | @smallexample @c ada |
88e1739c FW |
21997 | with Ada.Text_IO; |
21998 | with GNAT.Traceback; | |
21999 | with GNAT.Debug_Utilities; | |
22000 | ||
22001 | procedure STB is | |
22002 | ||
22003 | use Ada; | |
22004 | use GNAT; | |
22005 | use GNAT.Traceback; | |
22006 | ||
22007 | procedure P1 is | |
22008 | TB : Tracebacks_Array (1 .. 10); | |
22009 | -- We are asking for a maximum of 10 stack frames. | |
22010 | Len : Natural; | |
22011 | -- Len will receive the actual number of stack frames returned. | |
22012 | begin | |
22013 | Call_Chain (TB, Len); | |
22014 | ||
22015 | Text_IO.Put ("In STB.P1 : "); | |
22016 | ||
22017 | for K in 1 .. Len loop | |
22018 | Text_IO.Put (Debug_Utilities.Image (TB (K))); | |
22019 | Text_IO.Put (' '); | |
22020 | end loop; | |
22021 | ||
22022 | Text_IO.New_Line; | |
22023 | end P1; | |
22024 | ||
22025 | procedure P2 is | |
22026 | begin | |
22027 | P1; | |
22028 | end P2; | |
22029 | ||
22030 | begin | |
22031 | P2; | |
22032 | end STB; | |
88e1739c FW |
22033 | @end smallexample |
22034 | ||
22035 | @smallexample | |
7cd4527e | 22036 | $ gnatmake -g stb |
88e1739c FW |
22037 | $ stb |
22038 | ||
22039 | In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# | |
22040 | 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# | |
22041 | @end smallexample | |
22042 | ||
7cd4527e AC |
22043 | @noindent |
22044 | You can then get further information by invoking the @code{addr2line} | |
22045 | tool as described earlier (note that the hexadecimal addresses | |
22046 | need to be specified in C format, with a leading ``0x''). | |
22047 | ||
88e1739c FW |
22048 | @node Symbolic Traceback |
22049 | @subsection Symbolic Traceback | |
22050 | @cindex traceback, symbolic | |
22051 | ||
22052 | @noindent | |
22053 | A symbolic traceback is a stack traceback in which procedure names are | |
22054 | associated with each code location. | |
22055 | ||
22056 | @noindent | |
22057 | Note that this feature is not supported on all platforms. See | |
22058 | @file{GNAT.Traceback.Symbolic spec in g-trasym.ads} for a complete | |
22059 | list of currently supported platforms. | |
22060 | ||
22061 | @noindent | |
22062 | Note that the symbolic traceback requires that the program be compiled | |
22063 | with debug information. If it is not compiled with debug information | |
22064 | only the non-symbolic information will be valid. | |
22065 | ||
22066 | @menu | |
22067 | * Tracebacks From Exception Occurrences (symbolic):: | |
22068 | * Tracebacks From Anywhere in a Program (symbolic):: | |
22069 | @end menu | |
22070 | ||
22071 | @node Tracebacks From Exception Occurrences (symbolic) | |
22072 | @subsubsection Tracebacks From Exception Occurrences | |
22073 | ||
7cd4527e | 22074 | @smallexample @c ada |
88e1739c FW |
22075 | with Ada.Text_IO; |
22076 | with GNAT.Traceback.Symbolic; | |
22077 | ||
22078 | procedure STB is | |
22079 | ||
22080 | procedure P1 is | |
22081 | begin | |
22082 | raise Constraint_Error; | |
22083 | end P1; | |
22084 | ||
22085 | procedure P2 is | |
22086 | begin | |
22087 | P1; | |
22088 | end P2; | |
22089 | ||
22090 | procedure P3 is | |
22091 | begin | |
22092 | P2; | |
22093 | end P3; | |
22094 | ||
22095 | begin | |
22096 | P3; | |
22097 | exception | |
22098 | when E : others => | |
22099 | Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); | |
22100 | end STB; | |
88e1739c FW |
22101 | @end smallexample |
22102 | ||
22103 | @smallexample | |
27a8f150 | 22104 | $ gnatmake -g .\stb -bargs -E |
88e1739c FW |
22105 | $ stb |
22106 | ||
22107 | 0040149F in stb.p1 at stb.adb:8 | |
22108 | 004014B7 in stb.p2 at stb.adb:13 | |
22109 | 004014CF in stb.p3 at stb.adb:18 | |
22110 | 004015DD in ada.stb at stb.adb:22 | |
22111 | 00401461 in main at b~stb.adb:168 | |
22112 | 004011C4 in __mingw_CRTStartup at crt1.c:200 | |
22113 | 004011F1 in mainCRTStartup at crt1.c:222 | |
22114 | 77E892A4 in ?? at ??:0 | |
22115 | @end smallexample | |
22116 | ||
22117 | @noindent | |
7cd4527e AC |
22118 | In the above example the ``.\'' syntax in the @command{gnatmake} command |
22119 | is currently required by @command{addr2line} for files that are in | |
22120 | the current working directory. | |
22121 | Moreover, the exact sequence of linker options may vary from platform | |
22122 | to platform. | |
22123 | The above @option{-largs} section is for Windows platforms. By contrast, | |
22124 | under Unix there is no need for the @option{-largs} section. | |
88e1739c FW |
22125 | Differences across platforms are due to details of linker implementation. |
22126 | ||
22127 | @node Tracebacks From Anywhere in a Program (symbolic) | |
22128 | @subsubsection Tracebacks From Anywhere in a Program | |
22129 | ||
22130 | @noindent | |
22131 | It is possible to get a symbolic stack traceback | |
22132 | from anywhere in a program, just as for non-symbolic tracebacks. | |
22133 | The first step is to obtain a non-symbolic | |
22134 | traceback, and then call @code{Symbolic_Traceback} to compute the symbolic | |
22135 | information. Here is an example: | |
22136 | ||
7cd4527e | 22137 | @smallexample @c ada |
88e1739c FW |
22138 | with Ada.Text_IO; |
22139 | with GNAT.Traceback; | |
22140 | with GNAT.Traceback.Symbolic; | |
22141 | ||
22142 | procedure STB is | |
22143 | ||
22144 | use Ada; | |
22145 | use GNAT.Traceback; | |
22146 | use GNAT.Traceback.Symbolic; | |
22147 | ||
22148 | procedure P1 is | |
22149 | TB : Tracebacks_Array (1 .. 10); | |
22150 | -- We are asking for a maximum of 10 stack frames. | |
22151 | Len : Natural; | |
22152 | -- Len will receive the actual number of stack frames returned. | |
22153 | begin | |
22154 | Call_Chain (TB, Len); | |
22155 | Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); | |
22156 | end P1; | |
22157 | ||
22158 | procedure P2 is | |
22159 | begin | |
22160 | P1; | |
22161 | end P2; | |
22162 | ||
22163 | begin | |
22164 | P2; | |
22165 | end STB; | |
88e1739c FW |
22166 | @end smallexample |
22167 | ||
7e3d710b | 22168 | @c ****************************** |
88e1739c | 22169 | @ifset vms |
32e209e4 CC |
22170 | @node Compatibility with HP Ada |
22171 | @chapter Compatibility with HP Ada | |
88e1739c FW |
22172 | @cindex Compatibility |
22173 | ||
22174 | @noindent | |
7e3d710b AC |
22175 | @cindex DEC Ada |
22176 | @cindex HP Ada | |
22177 | @cindex Compatibility between GNAT and HP Ada | |
22178 | This chapter compares HP Ada (formerly known as ``DEC Ada'') | |
22179 | for OpenVMS Alpha and GNAT for OpenVMS for Alpha and for I64. | |
22180 | GNAT is highly compatible | |
32e209e4 CC |
22181 | with HP Ada, and it should generally be straightforward to port code |
22182 | from the HP Ada environment to GNAT. However, there are a few language | |
88e1739c | 22183 | and implementation differences of which the user must be aware. These |
7e3d710b | 22184 | differences are discussed in this chapter. In |
88e1739c FW |
22185 | addition, the operating environment and command structure for the |
22186 | compiler are different, and these differences are also discussed. | |
22187 | ||
7e3d710b AC |
22188 | For further details on these and other compatibility issues, |
22189 | see Appendix E of the HP publication | |
22190 | @cite{HP Ada, Technical Overview and Comparison on HP Platforms}. | |
22191 | ||
22192 | Except where otherwise indicated, the description of GNAT for OpenVMS | |
22193 | applies to both the Alpha and I64 platforms. | |
22194 | ||
22195 | For information on porting Ada code from GNAT on Alpha OpenVMS to GNAT on | |
ba1cbfb9 | 22196 | I64 OpenVMS, see @ref{Transitioning to 64-Bit GNAT for OpenVMS}. |
7e3d710b AC |
22197 | |
22198 | The discussion in this chapter addresses specifically the implementation | |
32e209e4 CC |
22199 | of Ada 83 for HP OpenVMS Alpha Systems. In cases where the implementation |
22200 | of HP Ada differs between OpenVMS Alpha Systems and OpenVMS VAX Systems, | |
7cd4527e | 22201 | GNAT always follows the Alpha implementation. |
88e1739c | 22202 | |
7e3d710b AC |
22203 | For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and |
22204 | attributes are recognized, although only a subset of them can sensibly | |
b2e74434 | 22205 | be implemented. The description of pragmas in |
3f5bb1b8 | 22206 | @xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}, |
b2e74434 | 22207 | indicates whether or not they are applicable to non-VMS systems. |
7e3d710b | 22208 | |
88e1739c | 22209 | @menu |
e08b38f5 | 22210 | * Ada Language Compatibility:: |
88e1739c FW |
22211 | * Differences in the Definition of Package System:: |
22212 | * Language-Related Features:: | |
22213 | * The Package STANDARD:: | |
22214 | * The Package SYSTEM:: | |
22215 | * Tasking and Task-Related Features:: | |
88e1739c FW |
22216 | * Pragmas and Pragma-Related Features:: |
22217 | * Library of Predefined Units:: | |
22218 | * Bindings:: | |
22219 | * Main Program Definition:: | |
22220 | * Implementation-Defined Attributes:: | |
22221 | * Compiler and Run-Time Interfacing:: | |
22222 | * Program Compilation and Library Management:: | |
22223 | * Input-Output:: | |
22224 | * Implementation Limits:: | |
7e3d710b | 22225 | * Tools and Utilities:: |
88e1739c FW |
22226 | @end menu |
22227 | ||
e08b38f5 VC |
22228 | @node Ada Language Compatibility |
22229 | @section Ada Language Compatibility | |
88e1739c FW |
22230 | |
22231 | @noindent | |
e08b38f5 VC |
22232 | GNAT handles Ada 95 and Ada 2005 as well as Ada 83, whereas HP Ada is only |
22233 | for Ada 83. Ada 95 and Ada 2005 are almost completely upwards compatible | |
88e1739c FW |
22234 | with Ada 83, and therefore Ada 83 programs will compile |
22235 | and run under GNAT with | |
e08b38f5 VC |
22236 | no changes or only minor changes. The @cite{Annotated Ada Reference Manual} |
22237 | provides details on specific incompatibilities. | |
88e1739c | 22238 | |
7e3d710b AC |
22239 | GNAT provides the switch @option{/83} on the @command{GNAT COMPILE} command, |
22240 | as well as the pragma @code{ADA_83}, to force the compiler to | |
88e1739c FW |
22241 | operate in Ada 83 mode. This mode does not guarantee complete |
22242 | conformance to Ada 83, but in practice is sufficient to | |
22243 | eliminate most sources of incompatibilities. | |
22244 | In particular, it eliminates the recognition of the | |
e08b38f5 | 22245 | additional Ada 95 and Ada 2005 keywords, so that their use as identifiers |
7e3d710b | 22246 | in Ada 83 programs is legal, and handles the cases of packages |
88e1739c FW |
22247 | with optional bodies, and generics that instantiate unconstrained |
22248 | types without the use of @code{(<>)}. | |
22249 | ||
22250 | @node Differences in the Definition of Package System | |
7e3d710b | 22251 | @section Differences in the Definition of Package @code{System} |
88e1739c FW |
22252 | |
22253 | @noindent | |
e08b38f5 | 22254 | An Ada compiler is allowed to add |
7e3d710b AC |
22255 | implementation-dependent declarations to package @code{System}. |
22256 | In normal mode, | |
22257 | GNAT does not take advantage of this permission, and the version of | |
e08b38f5 VC |
22258 | @code{System} provided by GNAT exactly matches that defined in the Ada |
22259 | Reference Manual. | |
88e1739c | 22260 | |
7e3d710b AC |
22261 | However, HP Ada adds an extensive set of declarations to package |
22262 | @code{System}, | |
32e209e4 | 22263 | as fully documented in the HP Ada manuals. To minimize changes required |
88e1739c | 22264 | for programs that make use of these extensions, GNAT provides the pragma |
7e3d710b AC |
22265 | @code{Extend_System} for extending the definition of package System. By using: |
22266 | @cindex pragma @code{Extend_System} | |
22267 | @cindex @code{Extend_System} pragma | |
88e1739c | 22268 | |
7cd4527e | 22269 | @smallexample @c ada |
88e1739c FW |
22270 | @group |
22271 | @cartouche | |
7cd4527e | 22272 | pragma Extend_System (Aux_DEC); |
88e1739c FW |
22273 | @end cartouche |
22274 | @end group | |
22275 | @end smallexample | |
22276 | ||
22277 | @noindent | |
7e3d710b AC |
22278 | the set of definitions in @code{System} is extended to include those in |
22279 | package @code{System.Aux_DEC}. | |
22280 | @cindex @code{System.Aux_DEC} package | |
22281 | @cindex @code{Aux_DEC} package (child of @code{System}) | |
22282 | These definitions are incorporated directly into package @code{System}, | |
22283 | as though they had been declared there. For a | |
1a5f40e1 | 22284 | list of the declarations added, see the spec of this package, |
7e3d710b AC |
22285 | which can be found in the file @file{s-auxdec.ads} in the GNAT library. |
22286 | @cindex @file{s-auxdec.ads} file | |
22287 | The pragma @code{Extend_System} is a configuration pragma, which means that | |
88e1739c | 22288 | it can be placed in the file @file{gnat.adc}, so that it will automatically |
7e3d710b AC |
22289 | apply to all subsequent compilations. See @ref{Configuration Pragmas}, |
22290 | for further details. | |
88e1739c FW |
22291 | |
22292 | An alternative approach that avoids the use of the non-standard | |
7e3d710b | 22293 | @code{Extend_System} pragma is to add a context clause to the unit that |
88e1739c FW |
22294 | references these facilities: |
22295 | ||
7cd4527e | 22296 | @smallexample @c ada |
88e1739c | 22297 | @cartouche |
7cd4527e AC |
22298 | with System.Aux_DEC; |
22299 | use System.Aux_DEC; | |
88e1739c | 22300 | @end cartouche |
88e1739c FW |
22301 | @end smallexample |
22302 | ||
22303 | @noindent | |
7cd4527e AC |
22304 | The effect is not quite semantically identical to incorporating |
22305 | the declarations directly into package @code{System}, | |
88e1739c | 22306 | but most programs will not notice a difference |
8dd07840 | 22307 | unless they use prefix notation (e.g.@: @code{System.Integer_8}) |
7e3d710b | 22308 | to reference the entities directly in package @code{System}. |
88e1739c FW |
22309 | For units containing such references, |
22310 | the prefixes must either be removed, or the pragma @code{Extend_System} | |
22311 | must be used. | |
22312 | ||
22313 | @node Language-Related Features | |
22314 | @section Language-Related Features | |
22315 | ||
22316 | @noindent | |
22317 | The following sections highlight differences in types, | |
22318 | representations of types, operations, alignment, and | |
22319 | related topics. | |
22320 | ||
22321 | @menu | |
22322 | * Integer Types and Representations:: | |
22323 | * Floating-Point Types and Representations:: | |
22324 | * Pragmas Float_Representation and Long_Float:: | |
22325 | * Fixed-Point Types and Representations:: | |
22326 | * Record and Array Component Alignment:: | |
22327 | * Address Clauses:: | |
22328 | * Other Representation Clauses:: | |
22329 | @end menu | |
22330 | ||
22331 | @node Integer Types and Representations | |
22332 | @subsection Integer Types and Representations | |
22333 | ||
22334 | @noindent | |
32e209e4 | 22335 | The set of predefined integer types is identical in HP Ada and GNAT. |
88e1739c FW |
22336 | Furthermore the representation of these integer types is also identical, |
22337 | including the capability of size clauses forcing biased representation. | |
22338 | ||
22339 | In addition, | |
32e209e4 | 22340 | HP Ada for OpenVMS Alpha systems has defined the |
7e3d710b | 22341 | following additional integer types in package @code{System}: |
88e1739c FW |
22342 | |
22343 | @itemize @bullet | |
22344 | ||
22345 | @item | |
7e3d710b | 22346 | @code{INTEGER_8} |
88e1739c FW |
22347 | |
22348 | @item | |
7e3d710b | 22349 | @code{INTEGER_16} |
88e1739c FW |
22350 | |
22351 | @item | |
7e3d710b | 22352 | @code{INTEGER_32} |
88e1739c FW |
22353 | |
22354 | @item | |
7e3d710b | 22355 | @code{INTEGER_64} |
88e1739c FW |
22356 | |
22357 | @item | |
7e3d710b | 22358 | @code{LARGEST_INTEGER} |
88e1739c FW |
22359 | @end itemize |
22360 | ||
22361 | @noindent | |
7e3d710b | 22362 | In GNAT, the first four of these types may be obtained from the |
e08b38f5 | 22363 | standard Ada package @code{Interfaces}. |
7e3d710b | 22364 | Alternatively, by use of the pragma @code{Extend_System}, identical |
88e1739c | 22365 | declarations can be referenced directly in package @code{System}. |
32e209e4 | 22366 | On both GNAT and HP Ada, the maximum integer size is 64 bits. |
88e1739c FW |
22367 | |
22368 | @node Floating-Point Types and Representations | |
22369 | @subsection Floating-Point Types and Representations | |
22370 | @cindex Floating-Point types | |
22371 | ||
22372 | @noindent | |
32e209e4 | 22373 | The set of predefined floating-point types is identical in HP Ada and GNAT. |
88e1739c FW |
22374 | Furthermore the representation of these floating-point |
22375 | types is also identical. One important difference is that the default | |
7e3d710b | 22376 | representation for HP Ada is @code{VAX_Float}, but the default representation |
88e1739c FW |
22377 | for GNAT is IEEE. |
22378 | ||
7e3d710b AC |
22379 | Specific types may be declared to be @code{VAX_Float} or IEEE, using the |
22380 | pragma @code{Float_Representation} as described in the HP Ada | |
22381 | documentation. | |
88e1739c FW |
22382 | For example, the declarations: |
22383 | ||
7cd4527e | 22384 | @smallexample @c ada |
88e1739c | 22385 | @cartouche |
7cd4527e AC |
22386 | type F_Float is digits 6; |
22387 | pragma Float_Representation (VAX_Float, F_Float); | |
88e1739c | 22388 | @end cartouche |
88e1739c FW |
22389 | @end smallexample |
22390 | ||
22391 | @noindent | |
7e3d710b AC |
22392 | declares a type @code{F_Float} that will be represented in @code{VAX_Float} |
22393 | format. | |
22394 | This set of declarations actually appears in @code{System.Aux_DEC}, | |
22395 | which contains | |
88e1739c | 22396 | the full set of additional floating-point declarations provided in |
7e3d710b AC |
22397 | the HP Ada version of package @code{System}. |
22398 | This and similar declarations may be accessed in a user program | |
7cd4527e | 22399 | by using pragma @code{Extend_System}. The use of this |
88e1739c FW |
22400 | pragma, and the related pragma @code{Long_Float} is described in further |
22401 | detail in the following section. | |
22402 | ||
22403 | @node Pragmas Float_Representation and Long_Float | |
7e3d710b | 22404 | @subsection Pragmas @code{Float_Representation} and @code{Long_Float} |
88e1739c FW |
22405 | |
22406 | @noindent | |
32e209e4 | 22407 | HP Ada provides the pragma @code{Float_Representation}, which |
88e1739c FW |
22408 | acts as a program library switch to allow control over |
22409 | the internal representation chosen for the predefined | |
22410 | floating-point types declared in the package @code{Standard}. | |
22411 | The format of this pragma is as follows: | |
22412 | ||
7e3d710b | 22413 | @smallexample @c ada |
88e1739c | 22414 | @cartouche |
7e3d710b | 22415 | pragma Float_Representation(VAX_Float | IEEE_Float); |
88e1739c | 22416 | @end cartouche |
88e1739c FW |
22417 | @end smallexample |
22418 | ||
22419 | @noindent | |
22420 | This pragma controls the representation of floating-point | |
22421 | types as follows: | |
22422 | ||
22423 | @itemize @bullet | |
22424 | @item | |
22425 | @code{VAX_Float} specifies that floating-point | |
32e209e4 | 22426 | types are represented by default with the VAX system hardware types |
7e3d710b AC |
22427 | @code{F-floating}, @code{D-floating}, @code{G-floating}. |
22428 | Note that the @code{H-floating} | |
22429 | type was available only on VAX systems, and is not available | |
22430 | in either HP Ada or GNAT. | |
88e1739c FW |
22431 | |
22432 | @item | |
22433 | @code{IEEE_Float} specifies that floating-point | |
22434 | types are represented by default with the IEEE single and | |
22435 | double floating-point types. | |
22436 | @end itemize | |
22437 | ||
22438 | @noindent | |
22439 | GNAT provides an identical implementation of the pragma | |
22440 | @code{Float_Representation}, except that it functions as a | |
7e3d710b | 22441 | configuration pragma. Note that the |
88e1739c | 22442 | notion of configuration pragma corresponds closely to the |
32e209e4 | 22443 | HP Ada notion of a program library switch. |
88e1739c | 22444 | |
7e3d710b AC |
22445 | When no pragma is used in GNAT, the default is @code{IEEE_Float}, |
22446 | which is different | |
22447 | from HP Ada 83, where the default is @code{VAX_Float}. In addition, the | |
22448 | predefined libraries in GNAT are built using @code{IEEE_Float}, so it is not | |
88e1739c FW |
22449 | advisable to change the format of numbers passed to standard library |
22450 | routines, and if necessary explicit type conversions may be needed. | |
22451 | ||
7e3d710b AC |
22452 | The use of @code{IEEE_Float} is recommended in GNAT since it is more |
22453 | efficient, and (given that it conforms to an international standard) | |
22454 | potentially more portable. | |
22455 | The situation in which @code{VAX_Float} may be useful is in interfacing | |
22456 | to existing code and data that expect the use of @code{VAX_Float}. | |
22457 | In such a situation use the predefined @code{VAX_Float} | |
88e1739c FW |
22458 | types in package @code{System}, as extended by |
22459 | @code{Extend_System}. For example, use @code{System.F_Float} | |
22460 | to specify the 32-bit @code{F-Float} format. | |
22461 | ||
88e1739c | 22462 | @noindent |
32e209e4 | 22463 | On OpenVMS systems, HP Ada provides the pragma @code{Long_Float} |
88e1739c FW |
22464 | to allow control over the internal representation chosen |
22465 | for the predefined type @code{Long_Float} and for floating-point | |
22466 | type declarations with digits specified in the range 7 .. 15. | |
22467 | The format of this pragma is as follows: | |
22468 | ||
7cd4527e | 22469 | @smallexample @c ada |
88e1739c | 22470 | @cartouche |
7cd4527e | 22471 | pragma Long_Float (D_FLOAT | G_FLOAT); |
88e1739c FW |
22472 | @end cartouche |
22473 | @end smallexample | |
22474 | ||
22475 | @node Fixed-Point Types and Representations | |
22476 | @subsection Fixed-Point Types and Representations | |
22477 | ||
22478 | @noindent | |
32e209e4 | 22479 | On HP Ada for OpenVMS Alpha systems, rounding is |
88e1739c | 22480 | away from zero for both positive and negative numbers. |
7e3d710b AC |
22481 | Therefore, @code{+0.5} rounds to @code{1}, |
22482 | and @code{-0.5} rounds to @code{-1}. | |
88e1739c | 22483 | |
7e3d710b | 22484 | On GNAT the results of operations |
e08b38f5 | 22485 | on fixed-point types are in accordance with the Ada |
88e1739c FW |
22486 | rules. In particular, results of operations on decimal |
22487 | fixed-point types are truncated. | |
22488 | ||
22489 | @node Record and Array Component Alignment | |
22490 | @subsection Record and Array Component Alignment | |
22491 | ||
22492 | @noindent | |
4d0e4612 | 22493 | On HP Ada for OpenVMS Alpha, all non-composite components |
88e1739c FW |
22494 | are aligned on natural boundaries. For example, 1-byte |
22495 | components are aligned on byte boundaries, 2-byte | |
22496 | components on 2-byte boundaries, 4-byte components on 4-byte | |
22497 | byte boundaries, and so on. The OpenVMS Alpha hardware | |
22498 | runs more efficiently with naturally aligned data. | |
22499 | ||
7e3d710b | 22500 | On GNAT, alignment rules are compatible |
32e209e4 | 22501 | with HP Ada for OpenVMS Alpha. |
88e1739c FW |
22502 | |
22503 | @node Address Clauses | |
22504 | @subsection Address Clauses | |
22505 | ||
22506 | @noindent | |
32e209e4 | 22507 | In HP Ada and GNAT, address clauses are supported for |
88e1739c FW |
22508 | objects and imported subprograms. |
22509 | The predefined type @code{System.Address} is a private type | |
7e3d710b AC |
22510 | in both compilers on Alpha OpenVMS, with the same representation |
22511 | (it is simply a machine pointer). Addition, subtraction, and comparison | |
e08b38f5 | 22512 | operations are available in the standard Ada package |
88e1739c FW |
22513 | @code{System.Storage_Elements}, or in package @code{System} |
22514 | if it is extended to include @code{System.Aux_DEC} using a | |
22515 | pragma @code{Extend_System} as previously described. | |
22516 | ||
7e3d710b | 22517 | Note that code that @code{with}'s both this extended package @code{System} |
88e1739c FW |
22518 | and the package @code{System.Storage_Elements} should not @code{use} |
22519 | both packages, or ambiguities will result. In general it is better | |
e08b38f5 | 22520 | not to mix these two sets of facilities. The Ada package was |
32e209e4 | 22521 | designed specifically to provide the kind of features that HP Ada |
88e1739c FW |
22522 | adds directly to package @code{System}. |
22523 | ||
7e3d710b AC |
22524 | The type @code{System.Address} is a 64-bit integer type in GNAT for |
22525 | I64 OpenVMS. For more information, | |
ba1cbfb9 | 22526 | see @ref{Transitioning to 64-Bit GNAT for OpenVMS}. |
7e3d710b | 22527 | |
32e209e4 | 22528 | GNAT is compatible with HP Ada in its handling of address |
88e1739c FW |
22529 | clauses, except for some limitations in |
22530 | the form of address clauses for composite objects with | |
22531 | initialization. Such address clauses are easily replaced | |
22532 | by the use of an explicitly-defined constant as described | |
e08b38f5 | 22533 | in the Ada Reference Manual (13.1(22)). For example, the sequence |
88e1739c FW |
22534 | of declarations: |
22535 | ||
7cd4527e | 22536 | @smallexample @c ada |
88e1739c FW |
22537 | @cartouche |
22538 | X, Y : Integer := Init_Func; | |
22539 | Q : String (X .. Y) := "abc"; | |
d488f6ea | 22540 | @dots{} |
7cd4527e | 22541 | for Q'Address use Compute_Address; |
88e1739c | 22542 | @end cartouche |
88e1739c FW |
22543 | @end smallexample |
22544 | ||
22545 | @noindent | |
22546 | will be rejected by GNAT, since the address cannot be computed at the time | |
7e3d710b | 22547 | that @code{Q} is declared. To achieve the intended effect, write instead: |
88e1739c | 22548 | |
7cd4527e | 22549 | @smallexample @c ada |
88e1739c FW |
22550 | @group |
22551 | @cartouche | |
22552 | X, Y : Integer := Init_Func; | |
7cd4527e | 22553 | Q_Address : constant Address := Compute_Address; |
88e1739c | 22554 | Q : String (X .. Y) := "abc"; |
d488f6ea | 22555 | @dots{} |
7cd4527e | 22556 | for Q'Address use Q_Address; |
88e1739c FW |
22557 | @end cartouche |
22558 | @end group | |
22559 | @end smallexample | |
22560 | ||
22561 | @noindent | |
e08b38f5 | 22562 | which will be accepted by GNAT (and other Ada compilers), and is also |
7e3d710b | 22563 | compatible with Ada 83. A fuller description of the restrictions |
b2e74434 RW |
22564 | on address specifications is found in @ref{Top, GNAT Reference Manual, |
22565 | About This Guide, gnat_rm, GNAT Reference Manual}. | |
88e1739c FW |
22566 | |
22567 | @node Other Representation Clauses | |
22568 | @subsection Other Representation Clauses | |
22569 | ||
22570 | @noindent | |
7e3d710b AC |
22571 | GNAT implements in a compatible manner all the representation |
22572 | clauses supported by HP Ada. In addition, GNAT | |
22573 | implements the representation clause forms that were introduced in Ada 95, | |
22574 | including @code{COMPONENT_SIZE} and @code{SIZE} clauses for objects. | |
88e1739c FW |
22575 | |
22576 | @node The Package STANDARD | |
7e3d710b | 22577 | @section The Package @code{STANDARD} |
88e1739c FW |
22578 | |
22579 | @noindent | |
7e3d710b | 22580 | The package @code{STANDARD}, as implemented by HP Ada, is fully |
e08b38f5 VC |
22581 | described in the @cite{Ada Reference Manual} and in the |
22582 | @cite{HP Ada Language Reference Manual}. As implemented by GNAT, the | |
22583 | package @code{STANDARD} is described in the @cite{Ada Reference Manual}. | |
88e1739c | 22584 | |
32e209e4 | 22585 | In addition, HP Ada supports the Latin-1 character set in |
7e3d710b AC |
22586 | the type @code{CHARACTER}. GNAT supports the Latin-1 character set |
22587 | in the type @code{CHARACTER} and also Unicode (ISO 10646 BMP) in | |
22588 | the type @code{WIDE_CHARACTER}. | |
88e1739c FW |
22589 | |
22590 | The floating-point types supported by GNAT are those | |
7e3d710b AC |
22591 | supported by HP Ada, but the defaults are different, and are controlled by |
22592 | pragmas. See @ref{Floating-Point Types and Representations}, for details. | |
88e1739c FW |
22593 | |
22594 | @node The Package SYSTEM | |
7e3d710b | 22595 | @section The Package @code{SYSTEM} |
88e1739c FW |
22596 | |
22597 | @noindent | |
7e3d710b AC |
22598 | HP Ada provides a specific version of the package |
22599 | @code{SYSTEM} for each platform on which the language is implemented. | |
1a5f40e1 | 22600 | For the complete spec of the package @code{SYSTEM}, see |
7e3d710b | 22601 | Appendix F of the @cite{HP Ada Language Reference Manual}. |
88e1739c | 22602 | |
7e3d710b AC |
22603 | On HP Ada, the package @code{SYSTEM} includes the following conversion |
22604 | functions: | |
88e1739c | 22605 | @itemize @bullet |
7e3d710b | 22606 | @item @code{TO_ADDRESS(INTEGER)} |
88e1739c | 22607 | |
7e3d710b | 22608 | @item @code{TO_ADDRESS(UNSIGNED_LONGWORD)} |
88e1739c | 22609 | |
7e3d710b | 22610 | @item @code{TO_ADDRESS(}@i{universal_integer}@code{)} |
88e1739c | 22611 | |
7e3d710b | 22612 | @item @code{TO_INTEGER(ADDRESS)} |
88e1739c | 22613 | |
7e3d710b | 22614 | @item @code{TO_UNSIGNED_LONGWORD(ADDRESS)} |
88e1739c | 22615 | |
7e3d710b | 22616 | @item Function @code{IMPORT_VALUE return UNSIGNED_LONGWORD} and the |
6ccde948 | 22617 | functions @code{IMPORT_ADDRESS} and @code{IMPORT_LARGEST_VALUE} |
88e1739c FW |
22618 | @end itemize |
22619 | ||
22620 | @noindent | |
7e3d710b | 22621 | By default, GNAT supplies a version of @code{SYSTEM} that matches |
e08b38f5 | 22622 | the definition given in the @cite{Ada Reference Manual}. |
88e1739c | 22623 | This |
32e209e4 | 22624 | is a subset of the HP system definitions, which is as |
88e1739c | 22625 | close as possible to the original definitions. The only difference |
7e3d710b | 22626 | is that the definition of @code{SYSTEM_NAME} is different: |
88e1739c | 22627 | |
7cd4527e | 22628 | @smallexample @c ada |
88e1739c | 22629 | @cartouche |
7cd4527e AC |
22630 | type Name is (SYSTEM_NAME_GNAT); |
22631 | System_Name : constant Name := SYSTEM_NAME_GNAT; | |
88e1739c | 22632 | @end cartouche |
88e1739c FW |
22633 | @end smallexample |
22634 | ||
22635 | @noindent | |
e08b38f5 | 22636 | Also, GNAT adds the Ada declarations for |
7e3d710b | 22637 | @code{BIT_ORDER} and @code{DEFAULT_BIT_ORDER}. |
88e1739c FW |
22638 | |
22639 | However, the use of the following pragma causes GNAT | |
7e3d710b | 22640 | to extend the definition of package @code{SYSTEM} so that it |
32e209e4 | 22641 | encompasses the full set of HP-specific extensions, |
88e1739c FW |
22642 | including the functions listed above: |
22643 | ||
7cd4527e | 22644 | @smallexample @c ada |
88e1739c | 22645 | @cartouche |
7cd4527e | 22646 | pragma Extend_System (Aux_DEC); |
88e1739c FW |
22647 | @end cartouche |
22648 | @end smallexample | |
22649 | ||
22650 | @noindent | |
7e3d710b | 22651 | The pragma @code{Extend_System} is a configuration pragma that |
b2e74434 | 22652 | is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma |
3f5bb1b8 | 22653 | Extend_System,,, gnat_rm, GNAT Reference Manual}, for further details. |
88e1739c | 22654 | |
32e209e4 | 22655 | HP Ada does not allow the recompilation of the package |
7e3d710b AC |
22656 | @code{SYSTEM}. Instead HP Ada provides several pragmas |
22657 | (@code{SYSTEM_NAME}, @code{STORAGE_UNIT}, and @code{MEMORY_SIZE}) | |
22658 | to modify values in the package @code{SYSTEM}. | |
22659 | On OpenVMS Alpha systems, the pragma | |
22660 | @code{SYSTEM_NAME} takes the enumeration literal @code{OPENVMS_AXP} as | |
88e1739c FW |
22661 | its single argument. |
22662 | ||
7e3d710b AC |
22663 | GNAT does permit the recompilation of package @code{SYSTEM} using |
22664 | the special switch @option{-gnatg}, and this switch can be used if | |
22665 | it is necessary to modify the definitions in @code{SYSTEM}. GNAT does | |
22666 | not permit the specification of @code{SYSTEM_NAME}, @code{STORAGE_UNIT} | |
22667 | or @code{MEMORY_SIZE} by any other means. | |
88e1739c | 22668 | |
7e3d710b AC |
22669 | On GNAT systems, the pragma @code{SYSTEM_NAME} takes the |
22670 | enumeration literal @code{SYSTEM_NAME_GNAT}. | |
88e1739c FW |
22671 | |
22672 | The definitions provided by the use of | |
22673 | ||
7cd4527e | 22674 | @smallexample @c ada |
88e1739c FW |
22675 | pragma Extend_System (AUX_Dec); |
22676 | @end smallexample | |
22677 | ||
22678 | @noindent | |
32e209e4 | 22679 | are virtually identical to those provided by the HP Ada 83 package |
7e3d710b AC |
22680 | @code{SYSTEM}. One important difference is that the name of the |
22681 | @code{TO_ADDRESS} | |
22682 | function for type @code{UNSIGNED_LONGWORD} is changed to | |
22683 | @code{TO_ADDRESS_LONG}. | |
3f5bb1b8 | 22684 | @xref{Address Clauses,,, gnat_rm, GNAT Reference Manual}, for a |
b2e74434 | 22685 | discussion of why this change was necessary. |
88e1739c FW |
22686 | |
22687 | @noindent | |
7e3d710b AC |
22688 | The version of @code{TO_ADDRESS} taking a @i{universal_integer} argument |
22689 | is in fact | |
88e1739c | 22690 | an extension to Ada 83 not strictly compatible with the reference manual. |
7e3d710b AC |
22691 | GNAT, in order to be exactly compatible with the standard, |
22692 | does not provide this capability. In HP Ada 83, the | |
88e1739c FW |
22693 | point of this definition is to deal with a call like: |
22694 | ||
7cd4527e | 22695 | @smallexample @c ada |
88e1739c FW |
22696 | TO_ADDRESS (16#12777#); |
22697 | @end smallexample | |
22698 | ||
22699 | @noindent | |
7e3d710b AC |
22700 | Normally, according to Ada 83 semantics, one would expect this to be |
22701 | ambiguous, since it matches both the @code{INTEGER} and | |
22702 | @code{UNSIGNED_LONGWORD} forms of @code{TO_ADDRESS}. | |
22703 | However, in HP Ada 83, there is no ambiguity, since the | |
22704 | definition using @i{universal_integer} takes precedence. | |
88e1739c | 22705 | |
7e3d710b AC |
22706 | In GNAT, since the version with @i{universal_integer} cannot be supplied, |
22707 | it is | |
88e1739c | 22708 | not possible to be 100% compatible. Since there are many programs using |
7e3d710b AC |
22709 | numeric constants for the argument to @code{TO_ADDRESS}, the decision in |
22710 | GNAT was | |
22711 | to change the name of the function in the @code{UNSIGNED_LONGWORD} case, | |
22712 | so the declarations provided in the GNAT version of @code{AUX_Dec} are: | |
88e1739c | 22713 | |
7cd4527e | 22714 | @smallexample @c ada |
88e1739c FW |
22715 | function To_Address (X : Integer) return Address; |
22716 | pragma Pure_Function (To_Address); | |
22717 | ||
22718 | function To_Address_Long (X : Unsigned_Longword) return Address; | |
22719 | pragma Pure_Function (To_Address_Long); | |
22720 | @end smallexample | |
22721 | ||
22722 | @noindent | |
7e3d710b AC |
22723 | This means that programs using @code{TO_ADDRESS} for |
22724 | @code{UNSIGNED_LONGWORD} must change the name to @code{TO_ADDRESS_LONG}. | |
88e1739c FW |
22725 | |
22726 | @node Tasking and Task-Related Features | |
22727 | @section Tasking and Task-Related Features | |
22728 | ||
22729 | @noindent | |
7e3d710b AC |
22730 | This section compares the treatment of tasking in GNAT |
22731 | and in HP Ada for OpenVMS Alpha. | |
22732 | The GNAT description applies to both Alpha and I64 OpenVMS. | |
22733 | For detailed information on tasking in | |
22734 | HP Ada, see the @cite{HP Ada Language Reference Manual} and the | |
88e1739c FW |
22735 | relevant run-time reference manual. |
22736 | ||
7e3d710b AC |
22737 | @menu |
22738 | * Implementation of Tasks in HP Ada for OpenVMS Alpha Systems:: | |
22739 | * Assigning Task IDs:: | |
22740 | * Task IDs and Delays:: | |
22741 | * Task-Related Pragmas:: | |
22742 | * Scheduling and Task Priority:: | |
22743 | * The Task Stack:: | |
22744 | * External Interrupts:: | |
22745 | @end menu | |
22746 | ||
32e209e4 | 22747 | @node Implementation of Tasks in HP Ada for OpenVMS Alpha Systems |
7e3d710b | 22748 | @subsection Implementation of Tasks in HP Ada for OpenVMS Alpha Systems |
88e1739c FW |
22749 | |
22750 | @noindent | |
22751 | On OpenVMS Alpha systems, each Ada task (except a passive | |
22752 | task) is implemented as a single stream of execution | |
22753 | that is created and managed by the kernel. On these | |
32e209e4 | 22754 | systems, HP Ada tasking support is based on DECthreads, |
88e1739c FW |
22755 | an implementation of the POSIX standard for threads. |
22756 | ||
32e209e4 | 22757 | Also, on OpenVMS Alpha systems, HP Ada tasks and foreign |
88e1739c FW |
22758 | code that calls DECthreads routines can be used together. |
22759 | The interaction between Ada tasks and DECthreads routines | |
22760 | can have some benefits. For example when on OpenVMS Alpha, | |
32e209e4 | 22761 | HP Ada can call C code that is already threaded. |
7e3d710b AC |
22762 | |
22763 | GNAT uses the facilities of DECthreads, | |
88e1739c FW |
22764 | and Ada tasks are mapped to threads. |
22765 | ||
88e1739c FW |
22766 | @node Assigning Task IDs |
22767 | @subsection Assigning Task IDs | |
22768 | ||
22769 | @noindent | |
7e3d710b | 22770 | The HP Ada Run-Time Library always assigns @code{%TASK 1} to |
88e1739c | 22771 | the environment task that executes the main program. On |
7e3d710b | 22772 | OpenVMS Alpha systems, @code{%TASK 0} is often used for tasks |
88e1739c FW |
22773 | that have been created but are not yet activated. |
22774 | ||
22775 | On OpenVMS Alpha systems, task IDs are assigned at | |
22776 | activation. On GNAT systems, task IDs are also assigned at | |
22777 | task creation but do not have the same form or values as | |
32e209e4 | 22778 | task ID values in HP Ada. There is no null task, and the |
88e1739c FW |
22779 | environment task does not have a specific task ID value. |
22780 | ||
22781 | @node Task IDs and Delays | |
22782 | @subsection Task IDs and Delays | |
22783 | ||
22784 | @noindent | |
22785 | On OpenVMS Alpha systems, tasking delays are implemented | |
22786 | using Timer System Services. The Task ID is used for the | |
7e3d710b | 22787 | identification of the timer request (the @code{REQIDT} parameter). |
88e1739c | 22788 | If Timers are used in the application take care not to use |
7e3d710b | 22789 | @code{0} for the identification, because cancelling such a timer |
88e1739c FW |
22790 | will cancel all timers and may lead to unpredictable results. |
22791 | ||
22792 | @node Task-Related Pragmas | |
22793 | @subsection Task-Related Pragmas | |
22794 | ||
22795 | @noindent | |
7e3d710b | 22796 | Ada supplies the pragma @code{TASK_STORAGE}, which allows |
88e1739c FW |
22797 | specification of the size of the guard area for a task |
22798 | stack. (The guard area forms an area of memory that has no | |
22799 | read or write access and thus helps in the detection of | |
22800 | stack overflow.) On OpenVMS Alpha systems, if the pragma | |
7e3d710b AC |
22801 | @code{TASK_STORAGE} specifies a value of zero, a minimal guard |
22802 | area is created. In the absence of a pragma @code{TASK_STORAGE}, | |
22803 | a default guard area is created. | |
88e1739c FW |
22804 | |
22805 | GNAT supplies the following task-related pragmas: | |
22806 | ||
22807 | @itemize @bullet | |
7e3d710b | 22808 | @item @code{TASK_INFO} |
88e1739c | 22809 | |
6ccde948 RW |
22810 | This pragma appears within a task definition and |
22811 | applies to the task in which it appears. The argument | |
22812 | must be of type @code{SYSTEM.TASK_INFO.TASK_INFO_TYPE}. | |
88e1739c | 22813 | |
7e3d710b | 22814 | @item @code{TASK_STORAGE} |
88e1739c | 22815 | |
6ccde948 RW |
22816 | GNAT implements pragma @code{TASK_STORAGE} in the same way as HP Ada. |
22817 | Both HP Ada and GNAT supply the pragmas @code{PASSIVE}, | |
22818 | @code{SUPPRESS}, and @code{VOLATILE}. | |
88e1739c FW |
22819 | @end itemize |
22820 | @node Scheduling and Task Priority | |
22821 | @subsection Scheduling and Task Priority | |
22822 | ||
22823 | @noindent | |
32e209e4 | 22824 | HP Ada implements the Ada language requirement that |
88e1739c FW |
22825 | when two tasks are eligible for execution and they have |
22826 | different priorities, the lower priority task does not | |
32e209e4 | 22827 | execute while the higher priority task is waiting. The HP |
88e1739c FW |
22828 | Ada Run-Time Library keeps a task running until either the |
22829 | task is suspended or a higher priority task becomes ready. | |
22830 | ||
22831 | On OpenVMS Alpha systems, the default strategy is round- | |
22832 | robin with preemption. Tasks of equal priority take turns | |
22833 | at the processor. A task is run for a certain period of | |
7e3d710b | 22834 | time and then placed at the tail of the ready queue for |
88e1739c FW |
22835 | its priority level. |
22836 | ||
7e3d710b | 22837 | HP Ada provides the implementation-defined pragma @code{TIME_SLICE}, |
88e1739c FW |
22838 | which can be used to enable or disable round-robin |
22839 | scheduling of tasks with the same priority. | |
32e209e4 CC |
22840 | See the relevant HP Ada run-time reference manual for |
22841 | information on using the pragmas to control HP Ada task | |
88e1739c FW |
22842 | scheduling. |
22843 | ||
7e3d710b | 22844 | GNAT follows the scheduling rules of Annex D (Real-Time |
e08b38f5 | 22845 | Annex) of the @cite{Ada Reference Manual}. In general, this |
32e209e4 | 22846 | scheduling strategy is fully compatible with HP Ada |
88e1739c FW |
22847 | although it provides some additional constraints (as |
22848 | fully documented in Annex D). | |
22849 | GNAT implements time slicing control in a manner compatible with | |
7e3d710b AC |
22850 | HP Ada 83, by means of the pragma @code{Time_Slice}, whose semantics |
22851 | are identical to the HP Ada 83 pragma of the same name. | |
88e1739c | 22852 | Note that it is not possible to mix GNAT tasking and |
7e3d710b AC |
22853 | HP Ada 83 tasking in the same program, since the two run-time |
22854 | libraries are not compatible. | |
88e1739c FW |
22855 | |
22856 | @node The Task Stack | |
22857 | @subsection The Task Stack | |
22858 | ||
22859 | @noindent | |
32e209e4 | 22860 | In HP Ada, a task stack is allocated each time a |
7e3d710b | 22861 | non-passive task is activated. As soon as the task is |
88e1739c | 22862 | terminated, the storage for the task stack is deallocated. |
7e3d710b | 22863 | If you specify a size of zero (bytes) with @code{T'STORAGE_SIZE}, |
88e1739c FW |
22864 | a default stack size is used. Also, regardless of the size |
22865 | specified, some additional space is allocated for task | |
22866 | management purposes. On OpenVMS Alpha systems, at least | |
22867 | one page is allocated. | |
22868 | ||
7e3d710b | 22869 | GNAT handles task stacks in a similar manner. In accordance with |
e08b38f5 | 22870 | the Ada rules, it provides the pragma @code{STORAGE_SIZE} as |
88e1739c | 22871 | an alternative method for controlling the task stack size. |
7e3d710b | 22872 | The specification of the attribute @code{T'STORAGE_SIZE} is also |
32e209e4 | 22873 | supported in a manner compatible with HP Ada. |
88e1739c FW |
22874 | |
22875 | @node External Interrupts | |
22876 | @subsection External Interrupts | |
22877 | ||
22878 | @noindent | |
32e209e4 CC |
22879 | On HP Ada, external interrupts can be associated with task entries. |
22880 | GNAT is compatible with HP Ada in its handling of external interrupts. | |
88e1739c FW |
22881 | |
22882 | @node Pragmas and Pragma-Related Features | |
22883 | @section Pragmas and Pragma-Related Features | |
22884 | ||
22885 | @noindent | |
32e209e4 | 22886 | Both HP Ada and GNAT supply all language-defined pragmas |
88e1739c | 22887 | as specified by the Ada 83 standard. GNAT also supplies all |
e08b38f5 | 22888 | language-defined pragmas introduced by Ada 95 and Ada 2005. |
88e1739c | 22889 | In addition, GNAT implements the implementation-defined pragmas |
32e209e4 | 22890 | from HP Ada 83. |
88e1739c FW |
22891 | |
22892 | @itemize @bullet | |
7e3d710b | 22893 | @item @code{AST_ENTRY} |
88e1739c | 22894 | |
7e3d710b | 22895 | @item @code{COMMON_OBJECT} |
88e1739c | 22896 | |
7e3d710b | 22897 | @item @code{COMPONENT_ALIGNMENT} |
88e1739c | 22898 | |
7e3d710b | 22899 | @item @code{EXPORT_EXCEPTION} |
88e1739c | 22900 | |
7e3d710b | 22901 | @item @code{EXPORT_FUNCTION} |
88e1739c | 22902 | |
7e3d710b | 22903 | @item @code{EXPORT_OBJECT} |
88e1739c | 22904 | |
7e3d710b | 22905 | @item @code{EXPORT_PROCEDURE} |
88e1739c | 22906 | |
7e3d710b | 22907 | @item @code{EXPORT_VALUED_PROCEDURE} |
88e1739c | 22908 | |
7e3d710b | 22909 | @item @code{FLOAT_REPRESENTATION} |
88e1739c | 22910 | |
7e3d710b | 22911 | @item @code{IDENT} |
88e1739c | 22912 | |
7e3d710b | 22913 | @item @code{IMPORT_EXCEPTION} |
88e1739c | 22914 | |
7e3d710b | 22915 | @item @code{IMPORT_FUNCTION} |
88e1739c | 22916 | |
7e3d710b | 22917 | @item @code{IMPORT_OBJECT} |
88e1739c | 22918 | |
7e3d710b | 22919 | @item @code{IMPORT_PROCEDURE} |
88e1739c | 22920 | |
7e3d710b | 22921 | @item @code{IMPORT_VALUED_PROCEDURE} |
88e1739c | 22922 | |
7e3d710b | 22923 | @item @code{INLINE_GENERIC} |
88e1739c | 22924 | |
7e3d710b | 22925 | @item @code{INTERFACE_NAME} |
88e1739c | 22926 | |
7e3d710b | 22927 | @item @code{LONG_FLOAT} |
88e1739c | 22928 | |
7e3d710b | 22929 | @item @code{MAIN_STORAGE} |
88e1739c | 22930 | |
7e3d710b | 22931 | @item @code{PASSIVE} |
88e1739c | 22932 | |
c690a2ec | 22933 | @item @code{PSECT_OBJECT} |
88e1739c | 22934 | |
7e3d710b | 22935 | @item @code{SHARE_GENERIC} |
88e1739c | 22936 | |
7e3d710b | 22937 | @item @code{SUPPRESS_ALL} |
88e1739c | 22938 | |
7e3d710b | 22939 | @item @code{TASK_STORAGE} |
88e1739c | 22940 | |
7e3d710b | 22941 | @item @code{TIME_SLICE} |
88e1739c | 22942 | |
7e3d710b | 22943 | @item @code{TITLE} |
88e1739c FW |
22944 | @end itemize |
22945 | ||
22946 | @noindent | |
7e3d710b AC |
22947 | These pragmas are all fully implemented, with the exception of @code{TITLE}, |
22948 | @code{PASSIVE}, and @code{SHARE_GENERIC}, which are | |
88e1739c | 22949 | recognized, but which have no |
7e3d710b | 22950 | effect in GNAT. The effect of @code{PASSIVE} may be obtained by the |
e08b38f5 | 22951 | use of Ada protected objects. In GNAT, all generics are inlined. |
88e1739c | 22952 | |
7e3d710b | 22953 | Unlike HP Ada, the GNAT ``@code{EXPORT_}@i{subprogram}'' pragmas require |
88e1739c FW |
22954 | a separate subprogram specification which must appear before the |
22955 | subprogram body. | |
22956 | ||
0eed45bb AC |
22957 | GNAT also supplies a number of implementation-defined pragmas including the |
22958 | following: | |
22959 | ||
88e1739c | 22960 | @itemize @bullet |
7e3d710b | 22961 | @item @code{ABORT_DEFER} |
88e1739c | 22962 | |
7e3d710b | 22963 | @item @code{ADA_83} |
88e1739c | 22964 | |
7e3d710b | 22965 | @item @code{ADA_95} |
88e1739c | 22966 | |
7e3d710b | 22967 | @item @code{ADA_05} |
88e1739c | 22968 | |
0eed45bb AC |
22969 | @item @code{Ada_2005} |
22970 | ||
22971 | @item @code{Ada_12} | |
22972 | ||
22973 | @item @code{Ada_2012} | |
22974 | ||
818b578d AC |
22975 | @item @code{ALLOW_INTEGER_ADDRESS} |
22976 | ||
7e3d710b | 22977 | @item @code{ANNOTATE} |
88e1739c | 22978 | |
7e3d710b | 22979 | @item @code{ASSERT} |
88e1739c | 22980 | |
7e3d710b | 22981 | @item @code{C_PASS_BY_COPY} |
88e1739c | 22982 | |
7e3d710b | 22983 | @item @code{CPP_CLASS} |
88e1739c | 22984 | |
7e3d710b | 22985 | @item @code{CPP_CONSTRUCTOR} |
0f1b0456 | 22986 | |
7e3d710b | 22987 | @item @code{CPP_DESTRUCTOR} |
88e1739c | 22988 | |
7e3d710b | 22989 | @item @code{DEBUG} |
88e1739c | 22990 | |
7e3d710b | 22991 | @item @code{EXTEND_SYSTEM} |
88e1739c | 22992 | |
7e3d710b | 22993 | @item @code{LINKER_ALIAS} |
88e1739c | 22994 | |
7e3d710b | 22995 | @item @code{LINKER_SECTION} |
88e1739c | 22996 | |
7e3d710b | 22997 | @item @code{MACHINE_ATTRIBUTE} |
88e1739c | 22998 | |
7e3d710b | 22999 | @item @code{NO_RETURN} |
88e1739c | 23000 | |
7e3d710b | 23001 | @item @code{PURE_FUNCTION} |
88e1739c | 23002 | |
7e3d710b | 23003 | @item @code{SOURCE_FILE_NAME} |
88e1739c | 23004 | |
7e3d710b | 23005 | @item @code{SOURCE_REFERENCE} |
88e1739c | 23006 | |
7e3d710b | 23007 | @item @code{TASK_INFO} |
88e1739c | 23008 | |
7e3d710b | 23009 | @item @code{UNCHECKED_UNION} |
88e1739c | 23010 | |
7e3d710b | 23011 | @item @code{UNIMPLEMENTED_UNIT} |
88e1739c | 23012 | |
7e3d710b | 23013 | @item @code{UNIVERSAL_DATA} |
88e1739c | 23014 | |
7e3d710b | 23015 | @item @code{UNSUPPRESS} |
88e1739c | 23016 | |
7e3d710b | 23017 | @item @code{WARNINGS} |
7cd4527e | 23018 | |
7e3d710b | 23019 | @item @code{WEAK_EXTERNAL} |
88e1739c FW |
23020 | @end itemize |
23021 | ||
23022 | @noindent | |
0eed45bb | 23023 | For full details on these and other GNAT implementation-defined pragmas, |
b2e74434 RW |
23024 | see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference |
23025 | Manual}. | |
88e1739c FW |
23026 | |
23027 | @menu | |
23028 | * Restrictions on the Pragma INLINE:: | |
23029 | * Restrictions on the Pragma INTERFACE:: | |
23030 | * Restrictions on the Pragma SYSTEM_NAME:: | |
23031 | @end menu | |
23032 | ||
23033 | @node Restrictions on the Pragma INLINE | |
7e3d710b | 23034 | @subsection Restrictions on Pragma @code{INLINE} |
88e1739c FW |
23035 | |
23036 | @noindent | |
7e3d710b | 23037 | HP Ada enforces the following restrictions on the pragma @code{INLINE}: |
88e1739c | 23038 | @itemize @bullet |
7e3d710b | 23039 | @item Parameters cannot have a task type. |
88e1739c FW |
23040 | |
23041 | @item Function results cannot be task types, unconstrained | |
23042 | array types, or unconstrained types with discriminants. | |
23043 | ||
23044 | @item Bodies cannot declare the following: | |
23045 | @itemize @bullet | |
23046 | @item Subprogram body or stub (imported subprogram is allowed) | |
23047 | ||
23048 | @item Tasks | |
23049 | ||
23050 | @item Generic declarations | |
23051 | ||
23052 | @item Instantiations | |
23053 | ||
23054 | @item Exceptions | |
23055 | ||
23056 | @item Access types (types derived from access types allowed) | |
23057 | ||
23058 | @item Array or record types | |
23059 | ||
23060 | @item Dependent tasks | |
23061 | ||
23062 | @item Direct recursive calls of subprogram or containing | |
23063 | subprogram, directly or via a renaming | |
23064 | ||
23065 | @end itemize | |
23066 | @end itemize | |
23067 | ||
23068 | @noindent | |
7e3d710b | 23069 | In GNAT, the only restriction on pragma @code{INLINE} is that the |
88e1739c FW |
23070 | body must occur before the call if both are in the same |
23071 | unit, and the size must be appropriately small. There are | |
23072 | no other specific restrictions which cause subprograms to | |
23073 | be incapable of being inlined. | |
23074 | ||
23075 | @node Restrictions on the Pragma INTERFACE | |
7e3d710b | 23076 | @subsection Restrictions on Pragma @code{INTERFACE} |
88e1739c FW |
23077 | |
23078 | @noindent | |
7e3d710b AC |
23079 | The following restrictions on pragma @code{INTERFACE} |
23080 | are enforced by both HP Ada and GNAT: | |
88e1739c FW |
23081 | @itemize @bullet |
23082 | @item Languages accepted: Ada, Bliss, C, Fortran, Default. | |
23083 | Default is the default on OpenVMS Alpha systems. | |
23084 | ||
23085 | @item Parameter passing: Language specifies default | |
7e3d710b | 23086 | mechanisms but can be overridden with an @code{EXPORT} pragma. |
88e1739c FW |
23087 | |
23088 | @itemize @bullet | |
23089 | @item Ada: Use internal Ada rules. | |
23090 | ||
23091 | @item Bliss, C: Parameters must be mode @code{in}; cannot be | |
23092 | record or task type. Result cannot be a string, an | |
23093 | array, or a record. | |
23094 | ||
7e3d710b | 23095 | @item Fortran: Parameters cannot have a task type. Result cannot |
88e1739c FW |
23096 | be a string, an array, or a record. |
23097 | @end itemize | |
23098 | @end itemize | |
23099 | ||
23100 | @noindent | |
32e209e4 | 23101 | GNAT is entirely upwards compatible with HP Ada, and in addition allows |
88e1739c FW |
23102 | record parameters for all languages. |
23103 | ||
23104 | @node Restrictions on the Pragma SYSTEM_NAME | |
7e3d710b | 23105 | @subsection Restrictions on Pragma @code{SYSTEM_NAME} |
88e1739c FW |
23106 | |
23107 | @noindent | |
32e209e4 | 23108 | For HP Ada for OpenVMS Alpha, the enumeration literal |
7e3d710b AC |
23109 | for the type @code{NAME} is @code{OPENVMS_AXP}. |
23110 | In GNAT, the enumeration | |
23111 | literal for the type @code{NAME} is @code{SYSTEM_NAME_GNAT}. | |
88e1739c FW |
23112 | |
23113 | @node Library of Predefined Units | |
23114 | @section Library of Predefined Units | |
23115 | ||
23116 | @noindent | |
23117 | A library of predefined units is provided as part of the | |
32e209e4 | 23118 | HP Ada and GNAT implementations. HP Ada does not provide |
7e3d710b | 23119 | the package @code{MACHINE_CODE} but instead recommends importing |
88e1739c FW |
23120 | assembler code. |
23121 | ||
7e3d710b | 23122 | The GNAT versions of the HP Ada Run-Time Library (@code{ADA$PREDEFINED:}) |
88e1739c | 23123 | units are taken from the OpenVMS Alpha version, not the OpenVMS VAX |
7e3d710b | 23124 | version. |
e08b38f5 | 23125 | The HP Ada Predefined Library units are modified to remove post-Ada 83 |
7e3d710b AC |
23126 | incompatibilities and to make them interoperable with GNAT |
23127 | (@pxref{Changes to DECLIB}, for details). | |
23128 | The units are located in the @file{DECLIB} directory. | |
23129 | ||
88e1739c | 23130 | The GNAT RTL is contained in |
7e3d710b AC |
23131 | the @file{ADALIB} directory, and |
23132 | the default search path is set up to find @code{DECLIB} units in preference | |
23133 | to @code{ADALIB} units with the same name (@code{TEXT_IO}, | |
23134 | @code{SEQUENTIAL_IO}, and @code{DIRECT_IO}, for example). | |
88e1739c | 23135 | |
88e1739c FW |
23136 | @menu |
23137 | * Changes to DECLIB:: | |
23138 | @end menu | |
23139 | ||
23140 | @node Changes to DECLIB | |
7e3d710b | 23141 | @subsection Changes to @code{DECLIB} |
88e1739c FW |
23142 | |
23143 | @noindent | |
e08b38f5 | 23144 | The changes made to the HP Ada predefined library for GNAT and post-Ada 83 |
88e1739c FW |
23145 | compatibility are minor and include the following: |
23146 | ||
23147 | @itemize @bullet | |
23148 | @item Adjusting the location of pragmas and record representation | |
e08b38f5 | 23149 | clauses to obey Ada 95 (and thus Ada 2005) rules |
88e1739c FW |
23150 | |
23151 | @item Adding the proper notation to generic formal parameters | |
23152 | that take unconstrained types in instantiation | |
23153 | ||
1a5f40e1 | 23154 | @item Adding pragma @code{ELABORATE_BODY} to package specs |
88e1739c FW |
23155 | that have package bodies not otherwise allowed |
23156 | ||
7e3d710b AC |
23157 | @item Replacing occurrences of the identifier ``@code{PROTECTED}'' by |
23158 | ``@code{PROTECTD}''. | |
23159 | Currently these are found only in the @code{STARLET} package spec. | |
23160 | ||
23161 | @item Changing @code{SYSTEM.ADDRESS} to @code{SYSTEM.SHORT_ADDRESS} | |
23162 | where the address size is constrained to 32 bits. | |
88e1739c FW |
23163 | @end itemize |
23164 | ||
23165 | @noindent | |
23166 | None of the above changes is visible to users. | |
23167 | ||
23168 | @node Bindings | |
23169 | @section Bindings | |
23170 | ||
23171 | @noindent | |
32e209e4 | 23172 | On OpenVMS Alpha, HP Ada provides the following strongly-typed bindings: |
88e1739c FW |
23173 | @itemize @bullet |
23174 | ||
23175 | @item Command Language Interpreter (CLI interface) | |
23176 | ||
23177 | @item DECtalk Run-Time Library (DTK interface) | |
23178 | ||
23179 | @item Librarian utility routines (LBR interface) | |
23180 | ||
23181 | @item General Purpose Run-Time Library (LIB interface) | |
23182 | ||
23183 | @item Math Run-Time Library (MTH interface) | |
23184 | ||
23185 | @item National Character Set Run-Time Library (NCS interface) | |
23186 | ||
23187 | @item Compiled Code Support Run-Time Library (OTS interface) | |
23188 | ||
23189 | @item Parallel Processing Run-Time Library (PPL interface) | |
23190 | ||
23191 | @item Screen Management Run-Time Library (SMG interface) | |
23192 | ||
23193 | @item Sort Run-Time Library (SOR interface) | |
23194 | ||
23195 | @item String Run-Time Library (STR interface) | |
23196 | ||
23197 | @item STARLET System Library | |
23198 | @findex Starlet | |
23199 | ||
23200 | @item X Window System Version 11R4 and 11R5 (X, XLIB interface) | |
23201 | ||
23202 | @item X Windows Toolkit (XT interface) | |
23203 | ||
23204 | @item X/Motif Version 1.1.3 and 1.2 (XM interface) | |
23205 | @end itemize | |
23206 | ||
23207 | @noindent | |
7e3d710b | 23208 | GNAT provides implementations of these HP bindings in the @code{DECLIB} |
e08b38f5 | 23209 | directory, on both the Alpha and I64 OpenVMS platforms. |
88e1739c | 23210 | |
db4b3c49 AC |
23211 | The X components of DECLIB compatibility package are located in a separate |
23212 | library, called XDECGNAT, which is not linked with by default; this library | |
23213 | must be explicitly linked with any application that makes use of any X facilities, | |
23214 | with a command similar to | |
23215 | ||
23216 | @code{GNAT MAKE USE_X /LINK /LIBRARY=XDECGNAT} | |
23217 | ||
7e3d710b AC |
23218 | The X/Motif bindings used to build @code{DECLIB} are whatever versions are |
23219 | in the | |
32e209e4 | 23220 | HP Ada @file{ADA$PREDEFINED} directory with extension @file{.ADC}. |
7e3d710b AC |
23221 | A pragma @code{Linker_Options} has been added to packages @code{Xm}, |
23222 | @code{Xt}, and @code{X_Lib} | |
7cd4527e AC |
23223 | causing the default X/Motif sharable image libraries to be linked in. This |
23224 | is done via options files named @file{xm.opt}, @file{xt.opt}, and | |
23225 | @file{x_lib.opt} (also located in the @file{DECLIB} directory). | |
88e1739c FW |
23226 | |
23227 | It may be necessary to edit these options files to update or correct the | |
7cd4527e AC |
23228 | library names if, for example, the newer X/Motif bindings from |
23229 | @file{ADA$EXAMPLES} | |
23230 | had been (previous to installing GNAT) copied and renamed to supersede the | |
23231 | default @file{ADA$PREDEFINED} versions. | |
88e1739c FW |
23232 | |
23233 | @menu | |
23234 | * Shared Libraries and Options Files:: | |
23235 | * Interfaces to C:: | |
23236 | @end menu | |
23237 | ||
23238 | @node Shared Libraries and Options Files | |
23239 | @subsection Shared Libraries and Options Files | |
23240 | ||
23241 | @noindent | |
32e209e4 | 23242 | When using the HP Ada |
7cd4527e AC |
23243 | predefined X and Motif bindings, the linking with their sharable images is |
23244 | done automatically by @command{GNAT LINK}. | |
23245 | When using other X and Motif bindings, you need | |
23246 | to add the corresponding sharable images to the command line for | |
23247 | @code{GNAT LINK}. When linking with shared libraries, or with | |
23248 | @file{.OPT} files, you must | |
23249 | also add them to the command line for @command{GNAT LINK}. | |
88e1739c FW |
23250 | |
23251 | A shared library to be used with GNAT is built in the same way as other | |
23252 | libraries under VMS. The VMS Link command can be used in standard fashion. | |
23253 | ||
23254 | @node Interfaces to C | |
23255 | @subsection Interfaces to C | |
23256 | ||
23257 | @noindent | |
32e209e4 | 23258 | HP Ada |
88e1739c FW |
23259 | provides the following Ada types and operations: |
23260 | ||
23261 | @itemize @bullet | |
7e3d710b | 23262 | @item C types package (@code{C_TYPES}) |
88e1739c | 23263 | |
7e3d710b | 23264 | @item C strings (@code{C_TYPES.NULL_TERMINATED}) |
88e1739c | 23265 | |
7e3d710b | 23266 | @item Other_types (@code{SHORT_INT}) |
88e1739c FW |
23267 | @end itemize |
23268 | ||
23269 | @noindent | |
7e3d710b | 23270 | Interfacing to C with GNAT, you can use the above approach |
32e209e4 | 23271 | described for HP Ada or the facilities of Annex B of |
e08b38f5 | 23272 | the @cite{Ada Reference Manual} (packages @code{INTERFACES.C}, |
7e3d710b | 23273 | @code{INTERFACES.C.STRINGS} and @code{INTERFACES.C.POINTERS}). For more |
b2e74434 | 23274 | information, see @ref{Interfacing to C,,, gnat_rm, GNAT Reference Manual}. |
88e1739c FW |
23275 | |
23276 | The @option{-gnatF} qualifier forces default and explicit | |
7e3d710b | 23277 | @code{External_Name} parameters in pragmas @code{Import} and @code{Export} |
88e1739c | 23278 | to be uppercased for compatibility with the default behavior |
7e3d710b | 23279 | of HP C. The qualifier has no effect on @code{Link_Name} parameters. |
88e1739c FW |
23280 | |
23281 | @node Main Program Definition | |
23282 | @section Main Program Definition | |
23283 | ||
23284 | @noindent | |
23285 | The following section discusses differences in the | |
32e209e4 CC |
23286 | definition of main programs on HP Ada and GNAT. |
23287 | On HP Ada, main programs are defined to meet the | |
88e1739c FW |
23288 | following conditions: |
23289 | @itemize @bullet | |
7e3d710b | 23290 | @item Procedure with no formal parameters (returns @code{0} upon |
6ccde948 | 23291 | normal completion) |
88e1739c | 23292 | |
7e3d710b | 23293 | @item Procedure with no formal parameters (returns @code{42} when |
6ccde948 | 23294 | an unhandled exception is raised) |
88e1739c FW |
23295 | |
23296 | @item Function with no formal parameters whose returned value | |
6ccde948 | 23297 | is of a discrete type |
88e1739c | 23298 | |
7e3d710b | 23299 | @item Procedure with one @code{out} formal of a discrete type for |
6ccde948 | 23300 | which a specification of pragma @code{EXPORT_VALUED_PROCEDURE} is given. |
88e1739c FW |
23301 | |
23302 | @end itemize | |
23303 | ||
23304 | @noindent | |
7e3d710b | 23305 | When declared with the pragma @code{EXPORT_VALUED_PROCEDURE}, |
88e1739c FW |
23306 | a main function or main procedure returns a discrete |
23307 | value whose size is less than 64 bits (32 on VAX systems), | |
23308 | the value is zero- or sign-extended as appropriate. | |
23309 | On GNAT, main programs are defined as follows: | |
23310 | @itemize @bullet | |
7e3d710b | 23311 | @item Must be a non-generic, parameterless subprogram that |
88e1739c | 23312 | is either a procedure or function returning an Ada |
7e3d710b | 23313 | @code{STANDARD.INTEGER} (the predefined type) |
88e1739c FW |
23314 | |
23315 | @item Cannot be a generic subprogram or an instantiation of a | |
23316 | generic subprogram | |
23317 | @end itemize | |
23318 | ||
23319 | @node Implementation-Defined Attributes | |
23320 | @section Implementation-Defined Attributes | |
23321 | ||
23322 | @noindent | |
32e209e4 | 23323 | GNAT provides all HP Ada implementation-defined |
88e1739c FW |
23324 | attributes. |
23325 | ||
23326 | @node Compiler and Run-Time Interfacing | |
23327 | @section Compiler and Run-Time Interfacing | |
23328 | ||
23329 | @noindent | |
7e3d710b | 23330 | HP Ada provides the following qualifiers to pass options to the linker |
7cd4527e | 23331 | (ACS LINK): |
88e1739c | 23332 | @itemize @bullet |
7e3d710b | 23333 | @item @option{/WAIT} and @option{/SUBMIT} |
88e1739c | 23334 | |
7e3d710b | 23335 | @item @option{/COMMAND} |
88e1739c | 23336 | |
66bfd481 | 23337 | @item @option{/@r{[}NO@r{]}MAP} |
88e1739c | 23338 | |
66bfd481 | 23339 | @item @option{/OUTPUT=@var{file-spec}} |
88e1739c | 23340 | |
66bfd481 | 23341 | @item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK} |
88e1739c FW |
23342 | @end itemize |
23343 | ||
23344 | @noindent | |
23345 | To pass options to the linker, GNAT provides the following | |
23346 | switches: | |
23347 | ||
23348 | @itemize @bullet | |
66bfd481 | 23349 | @item @option{/EXECUTABLE=@var{exec-name}} |
88e1739c | 23350 | |
7e3d710b | 23351 | @item @option{/VERBOSE} |
88e1739c | 23352 | |
66bfd481 | 23353 | @item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK} |
88e1739c FW |
23354 | @end itemize |
23355 | ||
23356 | @noindent | |
7cd4527e AC |
23357 | For more information on these switches, see |
23358 | @ref{Switches for gnatlink}. | |
32e209e4 CC |
23359 | In HP Ada, the command-line switch @option{/OPTIMIZE} is available |
23360 | to control optimization. HP Ada also supplies the | |
88e1739c FW |
23361 | following pragmas: |
23362 | @itemize @bullet | |
7cd4527e | 23363 | @item @code{OPTIMIZE} |
88e1739c | 23364 | |
7cd4527e | 23365 | @item @code{INLINE} |
88e1739c | 23366 | |
7cd4527e | 23367 | @item @code{INLINE_GENERIC} |
88e1739c | 23368 | |
7cd4527e | 23369 | @item @code{SUPPRESS_ALL} |
88e1739c | 23370 | |
7cd4527e | 23371 | @item @code{PASSIVE} |
88e1739c FW |
23372 | @end itemize |
23373 | ||
23374 | @noindent | |
23375 | In GNAT, optimization is controlled strictly by command | |
23376 | line parameters, as described in the corresponding section of this guide. | |
32e209e4 | 23377 | The HP pragmas for control of optimization are |
88e1739c FW |
23378 | recognized but ignored. |
23379 | ||
7e3d710b | 23380 | Note that in GNAT, the default is optimization off, whereas in HP Ada |
88e1739c FW |
23381 | the default is that optimization is turned on. |
23382 | ||
23383 | @node Program Compilation and Library Management | |
23384 | @section Program Compilation and Library Management | |
23385 | ||
23386 | @noindent | |
32e209e4 CC |
23387 | HP Ada and GNAT provide a comparable set of commands to |
23388 | build programs. HP Ada also provides a program library, | |
88e1739c FW |
23389 | which is a concept that does not exist on GNAT. Instead, |
23390 | GNAT provides directories of sources that are compiled as | |
23391 | needed. | |
23392 | ||
23393 | The following table summarizes | |
32e209e4 | 23394 | the HP Ada commands and provides |
88e1739c FW |
23395 | equivalent GNAT commands. In this table, some GNAT |
23396 | equivalents reflect the fact that GNAT does not use the | |
23397 | concept of a program library. Instead, it uses a model | |
23398 | in which collections of source and object files are used | |
23399 | in a manner consistent with other languages like C and | |
23400 | Fortran. Therefore, standard system file commands are used | |
23401 | to manipulate these elements. Those GNAT commands are marked with | |
7cd4527e | 23402 | an asterisk. |
32e209e4 | 23403 | Note that, unlike HP Ada, none of the GNAT commands accepts wild cards. |
88e1739c FW |
23404 | |
23405 | @need 1500 | |
7cd4527e AC |
23406 | @multitable @columnfractions .35 .65 |
23407 | ||
32e209e4 | 23408 | @item @emph{HP Ada Command} |
7cd4527e AC |
23409 | @tab @emph{GNAT Equivalent / Description} |
23410 | ||
23411 | @item @command{ADA} | |
23412 | @tab @command{GNAT COMPILE}@* | |
23413 | Invokes the compiler to compile one or more Ada source files. | |
23414 | ||
23415 | @item @command{ACS ATTACH}@* | |
23416 | @tab [No equivalent]@* | |
23417 | Switches control of terminal from current process running the program | |
23418 | library manager. | |
23419 | ||
23420 | @item @command{ACS CHECK} | |
23421 | @tab @command{GNAT MAKE /DEPENDENCY_LIST}@* | |
23422 | Forms the execution closure of one | |
23423 | or more compiled units and checks completeness and currency. | |
23424 | ||
23425 | @item @command{ACS COMPILE} | |
23426 | @tab @command{GNAT MAKE /ACTIONS=COMPILE}@* | |
23427 | Forms the execution closure of one or | |
23428 | more specified units, checks completeness and currency, | |
23429 | identifies units that have revised source files, compiles same, | |
23430 | and recompiles units that are or will become obsolete. | |
23431 | Also completes incomplete generic instantiations. | |
23432 | ||
23433 | @item @command{ACS COPY FOREIGN} | |
23434 | @tab Copy (*)@* | |
23435 | Copies a foreign object file into the program library as a | |
23436 | library unit body. | |
23437 | ||
23438 | @item @command{ACS COPY UNIT} | |
23439 | @tab Copy (*)@* | |
23440 | Copies a compiled unit from one program library to another. | |
23441 | ||
23442 | @item @command{ACS CREATE LIBRARY} | |
23443 | @tab Create /directory (*)@* | |
23444 | Creates a program library. | |
23445 | ||
23446 | @item @command{ACS CREATE SUBLIBRARY} | |
23447 | @tab Create /directory (*)@* | |
23448 | Creates a program sublibrary. | |
23449 | ||
23450 | @item @command{ACS DELETE LIBRARY} | |
23451 | @tab @* | |
23452 | Deletes a program library and its contents. | |
23453 | ||
23454 | @item @command{ACS DELETE SUBLIBRARY} | |
23455 | @tab @* | |
23456 | Deletes a program sublibrary and its contents. | |
23457 | ||
23458 | @item @command{ACS DELETE UNIT} | |
23459 | @tab Delete file (*)@* | |
23460 | On OpenVMS systems, deletes one or more compiled units from | |
23461 | the current program library. | |
23462 | ||
23463 | @item @command{ACS DIRECTORY} | |
23464 | @tab Directory (*)@* | |
23465 | On OpenVMS systems, lists units contained in the current | |
23466 | program library. | |
23467 | ||
23468 | @item @command{ACS ENTER FOREIGN} | |
23469 | @tab Copy (*)@* | |
23470 | Allows the import of a foreign body as an Ada library | |
1a5f40e1 | 23471 | spec and enters a reference to a pointer. |
7cd4527e AC |
23472 | |
23473 | @item @command{ACS ENTER UNIT} | |
23474 | @tab Copy (*)@* | |
23475 | Enters a reference (pointer) from the current program library to | |
23476 | a unit compiled into another program library. | |
23477 | ||
23478 | @item @command{ACS EXIT} | |
23479 | @tab [No equivalent]@* | |
23480 | Exits from the program library manager. | |
23481 | ||
23482 | @item @command{ACS EXPORT} | |
23483 | @tab Copy (*)@* | |
23484 | Creates an object file that contains system-specific object code | |
23485 | for one or more units. With GNAT, object files can simply be copied | |
23486 | into the desired directory. | |
23487 | ||
23488 | @item @command{ACS EXTRACT SOURCE} | |
23489 | @tab Copy (*)@* | |
23490 | Allows access to the copied source file for each Ada compilation unit | |
23491 | ||
23492 | @item @command{ACS HELP} | |
23493 | @tab @command{HELP GNAT}@* | |
23494 | Provides online help. | |
23495 | ||
23496 | @item @command{ACS LINK} | |
23497 | @tab @command{GNAT LINK}@* | |
23498 | Links an object file containing Ada units into an executable file. | |
23499 | ||
23500 | @item @command{ACS LOAD} | |
23501 | @tab Copy (*)@* | |
23502 | Loads (partially compiles) Ada units into the program library. | |
23503 | Allows loading a program from a collection of files into a library | |
23504 | without knowing the relationship among units. | |
23505 | ||
23506 | @item @command{ACS MERGE} | |
23507 | @tab Copy (*)@* | |
23508 | Merges into the current program library, one or more units from | |
23509 | another library where they were modified. | |
23510 | ||
23511 | @item @command{ACS RECOMPILE} | |
23512 | @tab @command{GNAT MAKE /ACTIONS=COMPILE}@* | |
23513 | Recompiles from external or copied source files any obsolete | |
23514 | unit in the closure. Also, completes any incomplete generic | |
23515 | instantiations. | |
23516 | ||
23517 | @item @command{ACS REENTER} | |
23518 | @tab @command{GNAT MAKE}@* | |
23519 | Reenters current references to units compiled after last entered | |
23520 | with the @command{ACS ENTER UNIT} command. | |
23521 | ||
23522 | @item @command{ACS SET LIBRARY} | |
23523 | @tab Set default (*)@* | |
23524 | Defines a program library to be the compilation context as well | |
23525 | as the target library for compiler output and commands in general. | |
23526 | ||
23527 | @item @command{ACS SET PRAGMA} | |
23528 | @tab Edit @file{gnat.adc} (*)@* | |
23529 | Redefines specified values of the library characteristics | |
23530 | @code{LONG_ FLOAT}, @code{MEMORY_SIZE}, @code{SYSTEM_NAME}, | |
23531 | and @code{Float_Representation}. | |
23532 | ||
23533 | @item @command{ACS SET SOURCE} | |
23534 | @tab Define @code{ADA_INCLUDE_PATH} path (*)@* | |
23535 | Defines the source file search list for the @command{ACS COMPILE} command. | |
23536 | ||
23537 | @item @command{ACS SHOW LIBRARY} | |
23538 | @tab Directory (*)@* | |
23539 | Lists information about one or more program libraries. | |
23540 | ||
23541 | @item @command{ACS SHOW PROGRAM} | |
23542 | @tab [No equivalent]@* | |
23543 | Lists information about the execution closure of one or | |
23544 | more units in the program library. | |
23545 | ||
23546 | @item @command{ACS SHOW SOURCE} | |
23547 | @tab Show logical @code{ADA_INCLUDE_PATH}@* | |
23548 | Shows the source file search used when compiling units. | |
23549 | ||
23550 | @item @command{ACS SHOW VERSION} | |
23551 | @tab Compile with @option{VERBOSE} option | |
23552 | Displays the version number of the compiler and program library | |
23553 | manager used. | |
23554 | ||
23555 | @item @command{ACS SPAWN} | |
23556 | @tab [No equivalent]@* | |
23557 | Creates a subprocess of the current process (same as @command{DCL SPAWN} | |
23558 | command). | |
23559 | ||
23560 | @item @command{ACS VERIFY} | |
23561 | @tab [No equivalent]@* | |
23562 | Performs a series of consistency checks on a program library to | |
23563 | determine whether the library structure and library files are in | |
23564 | valid form. | |
88e1739c FW |
23565 | @end multitable |
23566 | ||
23567 | @noindent | |
23568 | ||
23569 | @node Input-Output | |
23570 | @section Input-Output | |
23571 | ||
23572 | @noindent | |
32e209e4 | 23573 | On OpenVMS Alpha systems, HP Ada uses OpenVMS Record |
88e1739c FW |
23574 | Management Services (RMS) to perform operations on |
23575 | external files. | |
23576 | ||
23577 | @noindent | |
32e209e4 | 23578 | HP Ada and GNAT predefine an identical set of input- |
88e1739c | 23579 | output packages. To make the use of the |
7e3d710b | 23580 | generic @code{TEXT_IO} operations more convenient, HP Ada |
88e1739c FW |
23581 | provides predefined library packages that instantiate the |
23582 | integer and floating-point operations for the predefined | |
23583 | integer and floating-point types as shown in the following table. | |
23584 | ||
7cd4527e AC |
23585 | @multitable @columnfractions .45 .55 |
23586 | @item @emph{Package Name} @tab Instantiation | |
88e1739c | 23587 | |
7cd4527e AC |
23588 | @item @code{INTEGER_TEXT_IO} |
23589 | @tab @code{INTEGER_IO(INTEGER)} | |
88e1739c | 23590 | |
7cd4527e AC |
23591 | @item @code{SHORT_INTEGER_TEXT_IO} |
23592 | @tab @code{INTEGER_IO(SHORT_INTEGER)} | |
88e1739c | 23593 | |
7cd4527e AC |
23594 | @item @code{SHORT_SHORT_INTEGER_TEXT_IO} |
23595 | @tab @code{INTEGER_IO(SHORT_SHORT_INTEGER)} | |
88e1739c | 23596 | |
7cd4527e AC |
23597 | @item @code{FLOAT_TEXT_IO} |
23598 | @tab @code{FLOAT_IO(FLOAT)} | |
88e1739c | 23599 | |
7cd4527e AC |
23600 | @item @code{LONG_FLOAT_TEXT_IO} |
23601 | @tab @code{FLOAT_IO(LONG_FLOAT)} | |
23602 | @end multitable | |
88e1739c FW |
23603 | |
23604 | @noindent | |
32e209e4 | 23605 | The HP Ada predefined packages and their operations |
7e3d710b AC |
23606 | are implemented using OpenVMS Alpha files and input-output |
23607 | facilities. HP Ada supports asynchronous input-output on OpenVMS Alpha. | |
23608 | Familiarity with the following is recommended: | |
88e1739c FW |
23609 | @itemize @bullet |
23610 | @item RMS file organizations and access methods | |
23611 | ||
23612 | @item OpenVMS file specifications and directories | |
23613 | ||
23614 | @item OpenVMS File Definition Language (FDL) | |
23615 | @end itemize | |
23616 | ||
23617 | @noindent | |
23618 | GNAT provides I/O facilities that are completely | |
32e209e4 CC |
23619 | compatible with HP Ada. The distribution includes the |
23620 | standard HP Ada versions of all I/O packages, operating | |
23621 | in a manner compatible with HP Ada. In particular, the | |
23622 | following packages are by default the HP Ada (Ada 83) | |
88e1739c | 23623 | versions of these packages rather than the renamings |
e08b38f5 | 23624 | suggested in Annex J of the Ada Reference Manual: |
88e1739c | 23625 | @itemize @bullet |
7cd4527e | 23626 | @item @code{TEXT_IO} |
88e1739c | 23627 | |
7cd4527e | 23628 | @item @code{SEQUENTIAL_IO} |
88e1739c | 23629 | |
7cd4527e | 23630 | @item @code{DIRECT_IO} |
88e1739c FW |
23631 | @end itemize |
23632 | ||
23633 | @noindent | |
e08b38f5 VC |
23634 | The use of the standard child package syntax (for |
23635 | example, @code{ADA.TEXT_IO}) retrieves the post-Ada 83 versions of these | |
23636 | packages. | |
32e209e4 | 23637 | GNAT provides HP-compatible predefined instantiations |
7cd4527e | 23638 | of the @code{TEXT_IO} packages, and also |
88e1739c | 23639 | provides the standard predefined instantiations required |
e08b38f5 | 23640 | by the @cite{Ada Reference Manual}. |
88e1739c FW |
23641 | |
23642 | For further information on how GNAT interfaces to the file | |
23643 | system or how I/O is implemented in programs written in | |
b2e74434 RW |
23644 | mixed languages, see @ref{Implementation of the Standard I/O,,, |
23645 | gnat_rm, GNAT Reference Manual}. | |
88e1739c FW |
23646 | This chapter covers the following: |
23647 | @itemize @bullet | |
23648 | @item Standard I/O packages | |
23649 | ||
7cd4527e | 23650 | @item @code{FORM} strings |
88e1739c | 23651 | |
7cd4527e | 23652 | @item @code{ADA.DIRECT_IO} |
88e1739c | 23653 | |
7cd4527e | 23654 | @item @code{ADA.SEQUENTIAL_IO} |
88e1739c | 23655 | |
7cd4527e | 23656 | @item @code{ADA.TEXT_IO} |
88e1739c FW |
23657 | |
23658 | @item Stream pointer positioning | |
23659 | ||
23660 | @item Reading and writing non-regular files | |
23661 | ||
7cd4527e | 23662 | @item @code{GET_IMMEDIATE} |
88e1739c | 23663 | |
7cd4527e | 23664 | @item Treating @code{TEXT_IO} files as streams |
88e1739c FW |
23665 | |
23666 | @item Shared files | |
23667 | ||
23668 | @item Open modes | |
23669 | @end itemize | |
23670 | ||
23671 | @node Implementation Limits | |
23672 | @section Implementation Limits | |
23673 | ||
23674 | @noindent | |
32e209e4 | 23675 | The following table lists implementation limits for HP Ada |
7cd4527e | 23676 | and GNAT systems. |
88e1739c | 23677 | @multitable @columnfractions .60 .20 .20 |
7cd4527e AC |
23678 | @sp 1 |
23679 | @item @emph{Compilation Parameter} | |
32e209e4 | 23680 | @tab @emph{HP Ada} |
7cd4527e AC |
23681 | @tab @emph{GNAT} |
23682 | @sp 1 | |
88e1739c FW |
23683 | |
23684 | @item In a subprogram or entry declaration, maximum number of | |
6ccde948 | 23685 | formal parameters that are of an unconstrained record type |
88e1739c FW |
23686 | @tab 32 |
23687 | @tab No set limit | |
7cd4527e | 23688 | @sp 1 |
88e1739c FW |
23689 | |
23690 | @item Maximum identifier length (number of characters) | |
23691 | @tab 255 | |
e08b38f5 | 23692 | @tab 32766 |
7cd4527e AC |
23693 | @sp 1 |
23694 | ||
23695 | @item Maximum number of characters in a source line | |
23696 | @tab 255 | |
e08b38f5 | 23697 | @tab 32766 |
7cd4527e AC |
23698 | @sp 1 |
23699 | ||
23700 | @item Maximum collection size (number of bytes) | |
23701 | @tab 2**31-1 | |
23702 | @tab 2**31-1 | |
23703 | @sp 1 | |
23704 | ||
23705 | @item Maximum number of discriminants for a record type | |
23706 | @tab 245 | |
23707 | @tab No set limit | |
23708 | @sp 1 | |
23709 | ||
23710 | @item Maximum number of formal parameters in an entry or | |
6ccde948 | 23711 | subprogram declaration |
7cd4527e AC |
23712 | @tab 246 |
23713 | @tab No set limit | |
23714 | @sp 1 | |
23715 | ||
23716 | @item Maximum number of dimensions in an array type | |
23717 | @tab 255 | |
23718 | @tab No set limit | |
23719 | @sp 1 | |
23720 | ||
23721 | @item Maximum number of library units and subunits in a compilation. | |
23722 | @tab 4095 | |
23723 | @tab No set limit | |
23724 | @sp 1 | |
23725 | ||
23726 | @item Maximum number of library units and subunits in an execution. | |
23727 | @tab 16383 | |
23728 | @tab No set limit | |
23729 | @sp 1 | |
23730 | ||
23731 | @item Maximum number of objects declared with the pragma @code{COMMON_OBJECT} | |
6ccde948 | 23732 | or @code{PSECT_OBJECT} |
7cd4527e AC |
23733 | @tab 32757 |
23734 | @tab No set limit | |
23735 | @sp 1 | |
23736 | ||
23737 | @item Maximum number of enumeration literals in an enumeration type | |
6ccde948 | 23738 | definition |
7cd4527e AC |
23739 | @tab 65535 |
23740 | @tab No set limit | |
23741 | @sp 1 | |
23742 | ||
23743 | @item Maximum number of lines in a source file | |
23744 | @tab 65534 | |
23745 | @tab No set limit | |
23746 | @sp 1 | |
23747 | ||
23748 | @item Maximum number of bits in any object | |
23749 | @tab 2**31-1 | |
23750 | @tab 2**31-1 | |
23751 | @sp 1 | |
23752 | ||
23753 | @item Maximum size of the static portion of a stack frame (approximate) | |
23754 | @tab 2**31-1 | |
23755 | @tab 2**31-1 | |
23756 | @end multitable | |
23757 | ||
7e3d710b AC |
23758 | @node Tools and Utilities |
23759 | @section Tools and Utilities | |
23760 | ||
23761 | @noindent | |
23762 | The following table lists some of the OpenVMS development tools | |
23763 | available for HP Ada, and the corresponding tools for | |
23764 | use with @value{EDITION} on Alpha and I64 platforms. | |
23765 | Aside from the debugger, all the OpenVMS tools identified are part | |
23766 | of the DECset package. | |
23767 | ||
7e3d710b AC |
23768 | @iftex |
23769 | @c Specify table in TeX since Texinfo does a poor job | |
23770 | @tex | |
23771 | \smallskip | |
23772 | \smallskip | |
23773 | \settabs\+Language-Sensitive Editor\quad | |
23774 | &Product with HP Ada\quad | |
23775 | &\cr | |
23776 | \+\it Tool | |
23777 | &\it Product with HP Ada | |
164e06c6 | 23778 | & \it Product with @value{EDITION}\cr |
7e3d710b AC |
23779 | \smallskip |
23780 | \+Code Management System | |
23781 | &HP CMS | |
23782 | & HP CMS\cr | |
23783 | \smallskip | |
23784 | \+Language-Sensitive Editor | |
23785 | &HP LSE | |
23786 | & emacs or HP LSE (Alpha)\cr | |
23787 | \+ | |
23788 | & | |
23789 | & HP LSE (I64)\cr | |
23790 | \smallskip | |
23791 | \+Debugger | |
23792 | &OpenVMS Debug | |
23793 | & gdb (Alpha),\cr | |
23794 | \+ | |
23795 | & | |
23796 | & OpenVMS Debug (I64)\cr | |
23797 | \smallskip | |
23798 | \+Source Code Analyzer / | |
23799 | &HP SCA | |
23800 | & GNAT XREF\cr | |
23801 | \+Cross Referencer | |
23802 | & | |
23803 | &\cr | |
23804 | \smallskip | |
23805 | \+Test Manager | |
23806 | &HP Digital Test | |
23807 | & HP DTM\cr | |
23808 | \+ | |
23809 | &Manager (DTM) | |
23810 | &\cr | |
23811 | \smallskip | |
23812 | \+Performance and | |
23813 | & HP PCA | |
23814 | & HP PCA\cr | |
23815 | \+Coverage Analyzer | |
23816 | & | |
23817 | &\cr | |
23818 | \smallskip | |
23819 | \+Module Management | |
23820 | & HP MMS | |
23821 | & Not applicable\cr | |
23822 | \+ System | |
23823 | & | |
23824 | &\cr | |
23825 | \smallskip | |
23826 | \smallskip | |
23827 | @end tex | |
23828 | @end iftex | |
23829 | ||
23830 | @ifnottex | |
23831 | @c This is the Texinfo version of the table. It renders poorly in pdf, hence | |
23832 | @c the TeX version above for the printed version | |
23833 | @flushleft | |
23834 | @c @multitable @columnfractions .3 .4 .4 | |
164e06c6 | 23835 | @multitable {Source Code Analyzer /}{Tool with HP Ada}{Tool with @value{EDITION}} |
7e3d710b | 23836 | @item @i{Tool} |
6ccde948 RW |
23837 | @tab @i{Tool with HP Ada} |
23838 | @tab @i{Tool with @value{EDITION}} | |
7e3d710b | 23839 | @item Code Management@*System |
6ccde948 RW |
23840 | @tab HP CMS |
23841 | @tab HP CMS | |
7e3d710b | 23842 | @item Language-Sensitive@*Editor |
6ccde948 RW |
23843 | @tab HP LSE |
23844 | @tab emacs or HP LSE (Alpha) | |
7e3d710b | 23845 | @item |
6ccde948 RW |
23846 | @tab |
23847 | @tab HP LSE (I64) | |
7e3d710b | 23848 | @item Debugger |
6ccde948 RW |
23849 | @tab OpenVMS Debug |
23850 | @tab gdb (Alpha), | |
7e3d710b | 23851 | @item |
6ccde948 RW |
23852 | @tab |
23853 | @tab OpenVMS Debug (I64) | |
7e3d710b | 23854 | @item Source Code Analyzer /@*Cross Referencer |
6ccde948 RW |
23855 | @tab HP SCA |
23856 | @tab GNAT XREF | |
7e3d710b | 23857 | @item Test Manager |
6ccde948 RW |
23858 | @tab HP Digital Test@*Manager (DTM) |
23859 | @tab HP DTM | |
7e3d710b | 23860 | @item Performance and@*Coverage Analyzer |
6ccde948 RW |
23861 | @tab HP PCA |
23862 | @tab HP PCA | |
7e3d710b | 23863 | @item Module Management@*System |
6ccde948 RW |
23864 | @tab HP MMS |
23865 | @tab Not applicable | |
7e3d710b AC |
23866 | @end multitable |
23867 | @end flushleft | |
23868 | @end ifnottex | |
23869 | ||
7cd4527e AC |
23870 | @end ifset |
23871 | ||
7cd4527e AC |
23872 | @c ************************************** |
23873 | @node Platform-Specific Information for the Run-Time Libraries | |
23874 | @appendix Platform-Specific Information for the Run-Time Libraries | |
23875 | @cindex Tasking and threads libraries | |
23876 | @cindex Threads libraries and tasking | |
23877 | @cindex Run-time libraries (platform-specific information) | |
23878 | ||
23879 | @noindent | |
984a64bc AC |
23880 | The GNAT run-time implementation may vary with respect to both the |
23881 | underlying threads library and the exception handling scheme. | |
7cd4527e AC |
23882 | For threads support, one or more of the following are supplied: |
23883 | @itemize @bullet | |
23884 | @item @b{native threads library}, a binding to the thread package from | |
23885 | the underlying operating system | |
23886 | ||
7cd4527e AC |
23887 | @item @b{pthreads library} (Sparc Solaris only), a binding to the Solaris |
23888 | POSIX thread package | |
23889 | @end itemize | |
23890 | ||
23891 | @noindent | |
23892 | For exception handling, either or both of two models are supplied: | |
23893 | @itemize @bullet | |
23894 | @item @b{Zero-Cost Exceptions} (``ZCX''),@footnote{ | |
23895 | Most programs should experience a substantial speed improvement by | |
23896 | being compiled with a ZCX run-time. | |
23897 | This is especially true for | |
23898 | tasking applications or applications with many exception handlers.} | |
23899 | @cindex Zero-Cost Exceptions | |
23900 | @cindex ZCX (Zero-Cost Exceptions) | |
23901 | which uses binder-generated tables that | |
23902 | are interrogated at run time to locate a handler | |
23903 | ||
23904 | @item @b{setjmp / longjmp} (``SJLJ''), | |
23905 | @cindex setjmp/longjmp Exception Model | |
23906 | @cindex SJLJ (setjmp/longjmp Exception Model) | |
23907 | which uses dynamically-set data to establish | |
23908 | the set of handlers | |
23909 | @end itemize | |
23910 | ||
23911 | @noindent | |
23912 | This appendix summarizes which combinations of threads and exception support | |
23913 | are supplied on various GNAT platforms. | |
23914 | It then shows how to select a particular library either | |
23915 | permanently or temporarily, | |
23916 | explains the properties of (and tradeoffs among) the various threads | |
23917 | libraries, and provides some additional | |
23918 | information about several specific platforms. | |
23919 | ||
23920 | @menu | |
23921 | * Summary of Run-Time Configurations:: | |
23922 | * Specifying a Run-Time Library:: | |
7cd4527e AC |
23923 | * Choosing the Scheduling Policy:: |
23924 | * Solaris-Specific Considerations:: | |
7cd4527e | 23925 | * Linux-Specific Considerations:: |
9bc856dd | 23926 | * AIX-Specific Considerations:: |
72734842 | 23927 | * RTX-Specific Considerations:: |
e074d476 | 23928 | * HP-UX-Specific Considerations:: |
7cd4527e AC |
23929 | @end menu |
23930 | ||
7cd4527e AC |
23931 | @node Summary of Run-Time Configurations |
23932 | @section Summary of Run-Time Configurations | |
23933 | ||
7cd4527e AC |
23934 | @multitable @columnfractions .30 .70 |
23935 | @item @b{alpha-openvms} | |
23936 | @item @code{@ @ }@i{rts-native (default)} | |
23937 | @item @code{@ @ @ @ }Tasking @tab native VMS threads | |
23938 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
23939 | @* | |
7e3d710b AC |
23940 | @item @code{@ @ }@i{rts-sjlj} |
23941 | @item @code{@ @ @ @ }Tasking @tab native TRU64 threads | |
23942 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
23943 | @* | |
23944 | @item @b{ia64-hp_linux} | |
23945 | @item @code{@ @ }@i{rts-native (default)} | |
23946 | @item @code{@ @ @ @ }Tasking @tab pthread library | |
23947 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
23948 | @* | |
23949 | @item @b{ia64-hpux} | |
23950 | @item @code{@ @ }@i{rts-native (default)} | |
23951 | @item @code{@ @ @ @ }Tasking @tab native HP-UX threads | |
23952 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
23953 | @* | |
23954 | @item @b{ia64-openvms} | |
23955 | @item @code{@ @ }@i{rts-native (default)} | |
23956 | @item @code{@ @ @ @ }Tasking @tab native VMS threads | |
23957 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
23958 | @* | |
23959 | @item @b{ia64-sgi_linux} | |
23960 | @item @code{@ @ }@i{rts-native (default)} | |
23961 | @item @code{@ @ @ @ }Tasking @tab pthread library | |
23962 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
23963 | @* | |
7cd4527e AC |
23964 | @item @b{pa-hpux} |
23965 | @item @code{@ @ }@i{rts-native (default)} | |
7e3d710b | 23966 | @item @code{@ @ @ @ }Tasking @tab native HP-UX threads |
7cd4527e AC |
23967 | @item @code{@ @ @ @ }Exceptions @tab ZCX |
23968 | @* | |
23969 | @item @code{@ @ }@i{rts-sjlj} | |
7e3d710b | 23970 | @item @code{@ @ @ @ }Tasking @tab native HP-UX threads |
7cd4527e AC |
23971 | @item @code{@ @ @ @ }Exceptions @tab SJLJ |
23972 | @* | |
7e3d710b AC |
23973 | @item @b{ppc-aix} |
23974 | @item @code{@ @ }@i{rts-native (default)} | |
23975 | @item @code{@ @ @ @ }Tasking @tab native AIX threads | |
b254da66 AC |
23976 | @item @code{@ @ @ @ }Exceptions @tab ZCX |
23977 | @* | |
23978 | @item @code{@ @ }@i{rts-sjlj} | |
23979 | @item @code{@ @ @ @ }Tasking @tab native AIX threads | |
7e3d710b AC |
23980 | @item @code{@ @ @ @ }Exceptions @tab SJLJ |
23981 | @* | |
23982 | @item @b{ppc-darwin} | |
23983 | @item @code{@ @ }@i{rts-native (default)} | |
23984 | @item @code{@ @ @ @ }Tasking @tab native MacOS threads | |
23985 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
23986 | @* | |
7cd4527e AC |
23987 | @item @b{sparc-solaris} @tab |
23988 | @item @code{@ @ }@i{rts-native (default)} | |
23989 | @item @code{@ @ @ @ }Tasking @tab native Solaris threads library | |
23990 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
23991 | @* | |
7cd4527e | 23992 | @item @code{@ @ }@i{rts-pthread} |
7e3d710b | 23993 | @item @code{@ @ @ @ }Tasking @tab pthread library |
7cd4527e AC |
23994 | @item @code{@ @ @ @ }Exceptions @tab ZCX |
23995 | @* | |
23996 | @item @code{@ @ }@i{rts-sjlj} | |
23997 | @item @code{@ @ @ @ }Tasking @tab native Solaris threads library | |
23998 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
23999 | @* | |
e08b38f5 VC |
24000 | @item @b{sparc64-solaris} @tab |
24001 | @item @code{@ @ }@i{rts-native (default)} | |
24002 | @item @code{@ @ @ @ }Tasking @tab native Solaris threads library | |
24003 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
24004 | @* | |
7cd4527e AC |
24005 | @item @b{x86-linux} |
24006 | @item @code{@ @ }@i{rts-native (default)} | |
984a64bc | 24007 | @item @code{@ @ @ @ }Tasking @tab pthread library |
7cd4527e AC |
24008 | @item @code{@ @ @ @ }Exceptions @tab ZCX |
24009 | @* | |
7cd4527e | 24010 | @item @code{@ @ }@i{rts-sjlj} |
984a64bc | 24011 | @item @code{@ @ @ @ }Tasking @tab pthread library |
7cd4527e AC |
24012 | @item @code{@ @ @ @ }Exceptions @tab SJLJ |
24013 | @* | |
7e3d710b AC |
24014 | @item @b{x86-lynx} |
24015 | @item @code{@ @ }@i{rts-native (default)} | |
24016 | @item @code{@ @ @ @ }Tasking @tab native LynxOS threads | |
24017 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
24018 | @* | |
e08b38f5 VC |
24019 | @item @b{x86-solaris} |
24020 | @item @code{@ @ }@i{rts-native (default)} | |
24021 | @item @code{@ @ @ @ }Tasking @tab native Solaris threads | |
b254da66 AC |
24022 | @item @code{@ @ @ @ }Exceptions @tab ZCX |
24023 | @* | |
24024 | @item @code{@ @ }@i{rts-sjlj} | |
24025 | @item @code{@ @ @ @ }Tasking @tab native Solaris threads library | |
e08b38f5 VC |
24026 | @item @code{@ @ @ @ }Exceptions @tab SJLJ |
24027 | @* | |
7cd4527e AC |
24028 | @item @b{x86-windows} |
24029 | @item @code{@ @ }@i{rts-native (default)} | |
24030 | @item @code{@ @ @ @ }Tasking @tab native Win32 threads | |
7e3d710b AC |
24031 | @item @code{@ @ @ @ }Exceptions @tab ZCX |
24032 | @* | |
60370fb1 | 24033 | @item @code{@ @ }@i{rts-sjlj} |
7e3d710b AC |
24034 | @item @code{@ @ @ @ }Tasking @tab native Win32 threads |
24035 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
24036 | @* | |
72734842 JR |
24037 | @item @b{x86-windows-rtx} |
24038 | @item @code{@ @ }@i{rts-rtx-rtss (default)} | |
24039 | @item @code{@ @ @ @ }Tasking @tab RTX real-time subsystem RTSS threads (kernel mode) | |
24040 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
24041 | @* | |
24042 | @item @code{@ @ }@i{rts-rtx-w32} | |
24043 | @item @code{@ @ @ @ }Tasking @tab RTX Win32 threads (user mode) | |
24044 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
24045 | @* | |
7e3d710b AC |
24046 | @item @b{x86_64-linux} |
24047 | @item @code{@ @ }@i{rts-native (default)} | |
24048 | @item @code{@ @ @ @ }Tasking @tab pthread library | |
24049 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
24050 | @* | |
24051 | @item @code{@ @ }@i{rts-sjlj} | |
24052 | @item @code{@ @ @ @ }Tasking @tab pthread library | |
7cd4527e AC |
24053 | @item @code{@ @ @ @ }Exceptions @tab SJLJ |
24054 | @* | |
24055 | @end multitable | |
24056 | ||
7cd4527e AC |
24057 | @node Specifying a Run-Time Library |
24058 | @section Specifying a Run-Time Library | |
24059 | ||
24060 | @noindent | |
24061 | The @file{adainclude} subdirectory containing the sources of the GNAT | |
24062 | run-time library, and the @file{adalib} subdirectory containing the | |
24063 | @file{ALI} files and the static and/or shared GNAT library, are located | |
24064 | in the gcc target-dependent area: | |
24065 | ||
24066 | @smallexample | |
e08b38f5 | 24067 | target=$prefix/lib/gcc/gcc-@i{dumpmachine}/gcc-@i{dumpversion}/ |
7cd4527e AC |
24068 | @end smallexample |
24069 | ||
24070 | @noindent | |
24071 | As indicated above, on some platforms several run-time libraries are supplied. | |
24072 | These libraries are installed in the target dependent area and | |
24073 | contain a complete source and binary subdirectory. The detailed description | |
24074 | below explains the differences between the different libraries in terms of | |
24075 | their thread support. | |
24076 | ||
24077 | The default run-time library (when GNAT is installed) is @emph{rts-native}. | |
24078 | This default run time is selected by the means of soft links. | |
24079 | For example on x86-linux: | |
24080 | ||
24081 | @smallexample | |
24082 | @group | |
24083 | $(target-dir) | |
24084 | | | |
24085 | +--- adainclude----------+ | |
24086 | | | | |
24087 | +--- adalib-----------+ | | |
24088 | | | | | |
24089 | +--- rts-native | | | |
24090 | | | | | | |
24091 | | +--- adainclude <---+ | |
24092 | | | | | |
24093 | | +--- adalib <----+ | |
24094 | | | |
7cd4527e AC |
24095 | +--- rts-sjlj |
24096 | | | |
24097 | +--- adainclude | |
24098 | | | |
24099 | +--- adalib | |
24100 | @end group | |
24101 | @end smallexample | |
24102 | ||
24103 | @noindent | |
984a64bc | 24104 | If the @i{rts-sjlj} library is to be selected on a permanent basis, |
7cd4527e AC |
24105 | these soft links can be modified with the following commands: |
24106 | ||
24107 | @smallexample | |
24108 | $ cd $target | |
24109 | $ rm -f adainclude adalib | |
984a64bc AC |
24110 | $ ln -s rts-sjlj/adainclude adainclude |
24111 | $ ln -s rts-sjlj/adalib adalib | |
7cd4527e AC |
24112 | @end smallexample |
24113 | ||
24114 | @noindent | |
984a64bc AC |
24115 | Alternatively, you can specify @file{rts-sjlj/adainclude} in the file |
24116 | @file{$target/ada_source_path} and @file{rts-sjlj/adalib} in | |
7cd4527e AC |
24117 | @file{$target/ada_object_path}. |
24118 | ||
24119 | Selecting another run-time library temporarily can be | |
e08b38f5 | 24120 | achieved by using the @option{--RTS} switch, e.g., @option{--RTS=sjlj} |
7cd4527e | 24121 | @cindex @option{--RTS} option |
7cd4527e | 24122 | |
7cd4527e AC |
24123 | @node Choosing the Scheduling Policy |
24124 | @section Choosing the Scheduling Policy | |
24125 | ||
24126 | @noindent | |
24127 | When using a POSIX threads implementation, you have a choice of several | |
24128 | scheduling policies: @code{SCHED_FIFO}, | |
24129 | @cindex @code{SCHED_FIFO} scheduling policy | |
24130 | @code{SCHED_RR} | |
24131 | @cindex @code{SCHED_RR} scheduling policy | |
24132 | and @code{SCHED_OTHER}. | |
24133 | @cindex @code{SCHED_OTHER} scheduling policy | |
24134 | Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO} | |
24135 | or @code{SCHED_RR} requires special (e.g., root) privileges. | |
24136 | ||
24137 | By default, GNAT uses the @code{SCHED_OTHER} policy. To specify | |
24138 | @code{SCHED_FIFO}, | |
24139 | @cindex @code{SCHED_FIFO} scheduling policy | |
24140 | you can use one of the following: | |
24141 | ||
24142 | @itemize @bullet | |
24143 | @item | |
24144 | @code{pragma Time_Slice (0.0)} | |
24145 | @cindex pragma Time_Slice | |
24146 | @item | |
24147 | the corresponding binder option @option{-T0} | |
24148 | @cindex @option{-T0} option | |
24149 | @item | |
24150 | @code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} | |
24151 | @cindex pragma Task_Dispatching_Policy | |
24152 | @end itemize | |
24153 | ||
24154 | @noindent | |
24155 | To specify @code{SCHED_RR}, | |
24156 | @cindex @code{SCHED_RR} scheduling policy | |
24157 | you should use @code{pragma Time_Slice} with a | |
24158 | value greater than @code{0.0}, or else use the corresponding @option{-T} | |
24159 | binder option. | |
24160 | ||
7cd4527e AC |
24161 | @node Solaris-Specific Considerations |
24162 | @section Solaris-Specific Considerations | |
24163 | @cindex Solaris Sparc threads libraries | |
24164 | ||
24165 | @noindent | |
24166 | This section addresses some topics related to the various threads libraries | |
e08b38f5 | 24167 | on Sparc Solaris. |
7cd4527e AC |
24168 | |
24169 | @menu | |
24170 | * Solaris Threads Issues:: | |
7cd4527e AC |
24171 | @end menu |
24172 | ||
7cd4527e AC |
24173 | @node Solaris Threads Issues |
24174 | @subsection Solaris Threads Issues | |
24175 | ||
24176 | @noindent | |
e08b38f5 VC |
24177 | GNAT under Solaris/Sparc 32 bits comes with an alternate tasking run-time |
24178 | library based on POSIX threads --- @emph{rts-pthread}. | |
7cd4527e AC |
24179 | @cindex rts-pthread threads library |
24180 | This run-time library has the advantage of being mostly shared across all | |
24181 | POSIX-compliant thread implementations, and it also provides under | |
24182 | @w{Solaris 8} the @code{PTHREAD_PRIO_INHERIT} | |
24183 | @cindex @code{PTHREAD_PRIO_INHERIT} policy (under rts-pthread) | |
24184 | and @code{PTHREAD_PRIO_PROTECT} | |
24185 | @cindex @code{PTHREAD_PRIO_PROTECT} policy (under rts-pthread) | |
24186 | semantics that can be selected using the predefined pragma | |
24187 | @code{Locking_Policy} | |
24188 | @cindex pragma Locking_Policy (under rts-pthread) | |
24189 | with respectively | |
24190 | @code{Inheritance_Locking} and @code{Ceiling_Locking} as the policy. | |
24191 | @cindex @code{Inheritance_Locking} (under rts-pthread) | |
24192 | @cindex @code{Ceiling_Locking} (under rts-pthread) | |
24193 | ||
24194 | As explained above, the native run-time library is based on the Solaris thread | |
24195 | library (@code{libthread}) and is the default library. | |
7cd4527e | 24196 | |
984a64bc | 24197 | When the Solaris threads library is used (this is the default), programs |
7cd4527e AC |
24198 | compiled with GNAT can automatically take advantage of |
24199 | and can thus execute on multiple processors. | |
24200 | The user can alternatively specify a processor on which the program should run | |
24201 | to emulate a single-processor system. The multiprocessor / uniprocessor choice | |
24202 | is made by | |
443b3472 RW |
24203 | setting the environment variable @env{GNAT_PROCESSOR} |
24204 | @cindex @env{GNAT_PROCESSOR} environment variable (on Sparc Solaris) | |
7cd4527e AC |
24205 | to one of the following: |
24206 | ||
24207 | @table @code | |
24208 | @item -2 | |
24209 | Use the default configuration (run the program on all | |
6ccde948 RW |
24210 | available processors) - this is the same as having @code{GNAT_PROCESSOR} |
24211 | unset | |
7cd4527e AC |
24212 | |
24213 | @item -1 | |
24214 | Let the run-time implementation choose one processor and run the program on | |
6ccde948 | 24215 | that processor |
7cd4527e AC |
24216 | |
24217 | @item 0 .. Last_Proc | |
24218 | Run the program on the specified processor. | |
6ccde948 | 24219 | @code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1} |
7cd4527e AC |
24220 | (where @code{_SC_NPROCESSORS_CONF} is a system variable). |
24221 | @end table | |
24222 | ||
7cd4527e AC |
24223 | @node Linux-Specific Considerations |
24224 | @section Linux-Specific Considerations | |
24225 | @cindex Linux threads libraries | |
24226 | ||
24227 | @noindent | |
7e3d710b AC |
24228 | On GNU/Linux without NPTL support (usually system with GNU C Library |
24229 | older than 2.3), the signal model is not POSIX compliant, which means | |
24230 | that to send a signal to the process, you need to send the signal to all | |
8dd07840 | 24231 | threads, e.g.@: by using @code{killpg()}. |
7cd4527e | 24232 | |
9bc856dd AC |
24233 | @node AIX-Specific Considerations |
24234 | @section AIX-Specific Considerations | |
24235 | @cindex AIX resolver library | |
24236 | ||
24237 | @noindent | |
24238 | On AIX, the resolver library initializes some internal structure on | |
24239 | the first call to @code{get*by*} functions, which are used to implement | |
0ab80019 | 24240 | @code{GNAT.Sockets.Get_Host_By_Name} and |
e08b38f5 | 24241 | @code{GNAT.Sockets.Get_Host_By_Address}. |
9bc856dd AC |
24242 | If such initialization occurs within an Ada task, and the stack size for |
24243 | the task is the default size, a stack overflow may occur. | |
7cd4527e | 24244 | |
9bc856dd | 24245 | To avoid this overflow, the user should either ensure that the first call |
0ab80019 AC |
24246 | to @code{GNAT.Sockets.Get_Host_By_Name} or |
24247 | @code{GNAT.Sockets.Get_Host_By_Addrss} | |
9bc856dd AC |
24248 | occurs in the environment task, or use @code{pragma Storage_Size} to |
24249 | specify a sufficiently large size for the stack of the task that contains | |
24250 | this call. | |
7cd4527e | 24251 | |
72734842 JR |
24252 | @node RTX-Specific Considerations |
24253 | @section RTX-Specific Considerations | |
24254 | @cindex RTX libraries | |
24255 | ||
24256 | @noindent | |
24257 | The Real-time Extension (RTX) to Windows is based on the Windows Win32 | |
24258 | API. Applications can be built to work in two different modes: | |
24259 | ||
24260 | @itemize @bullet | |
24261 | @item | |
24262 | Windows executables that run in Ring 3 to utilize memory protection | |
24263 | (@emph{rts-rtx-w32}). | |
24264 | ||
24265 | @item | |
24266 | Real-time subsystem (RTSS) executables that run in Ring 0, where | |
24267 | performance can be optimized with RTSS applications taking precedent | |
6a497607 AC |
24268 | over all Windows applications (@emph{rts-rtx-rtss}). This mode requires |
24269 | the Microsoft linker to handle RTSS libraries. | |
72734842 JR |
24270 | |
24271 | @end itemize | |
24272 | ||
e074d476 AC |
24273 | @node HP-UX-Specific Considerations |
24274 | @section HP-UX-Specific Considerations | |
24275 | @cindex HP-UX Scheduling | |
24276 | ||
24277 | @noindent | |
24278 | On HP-UX, appropriate privileges are required to change the scheduling | |
24279 | parameters of a task. The calling process must have appropriate | |
24280 | privileges or be a member of a group having @code{PRIV_RTSCHED} access to | |
24281 | successfully change the scheduling parameters. | |
24282 | ||
24283 | By default, GNAT uses the @code{SCHED_HPUX} policy. To have access to the | |
24284 | priority range 0-31 either the @code{FIFO_Within_Priorities} or the | |
24285 | @code{Round_Robin_Within_Priorities} scheduling policies need to be set. | |
24286 | ||
24287 | To specify the @code{FIFO_Within_Priorities} scheduling policy you can use | |
24288 | one of the following: | |
24289 | ||
24290 | @itemize @bullet | |
24291 | @item | |
24292 | @code{pragma Time_Slice (0.0)} | |
24293 | @cindex pragma Time_Slice | |
24294 | @item | |
24295 | the corresponding binder option @option{-T0} | |
24296 | @cindex @option{-T0} option | |
24297 | @item | |
24298 | @code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} | |
24299 | @cindex pragma Task_Dispatching_Policy | |
24300 | @end itemize | |
24301 | ||
24302 | @noindent | |
24303 | To specify the @code{Round_Robin_Within_Priorities}, scheduling policy | |
24304 | you should use @code{pragma Time_Slice} with a | |
24305 | value greater than @code{0.0}, or use the corresponding @option{-T} | |
24306 | binder option, or set the @code{pragma Task_Dispatching_Policy | |
24307 | (Round_Robin_Within_Priorities)}. | |
24308 | ||
7cd4527e AC |
24309 | @c ******************************* |
24310 | @node Example of Binder Output File | |
24311 | @appendix Example of Binder Output File | |
24312 | ||
24313 | @noindent | |
24314 | This Appendix displays the source code for @command{gnatbind}'s output | |
24315 | file generated for a simple ``Hello World'' program. | |
24316 | Comments have been added for clarification purposes. | |
24317 | ||
7cd4527e AC |
24318 | @smallexample @c adanocomment |
24319 | @iftex | |
24320 | @leftskip=0cm | |
24321 | @end iftex | |
24322 | -- The package is called Ada_Main unless this name is actually used | |
24323 | -- as a unit name in the partition, in which case some other unique | |
24324 | -- name is used. | |
24325 | ||
24326 | with System; | |
24327 | package ada_main is | |
24328 | ||
24329 | Elab_Final_Code : Integer; | |
24330 | pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code"); | |
24331 | ||
24332 | -- The main program saves the parameters (argument count, | |
24333 | -- argument values, environment pointer) in global variables | |
24334 | -- for later access by other units including | |
24335 | -- Ada.Command_Line. | |
24336 | ||
24337 | gnat_argc : Integer; | |
24338 | gnat_argv : System.Address; | |
24339 | gnat_envp : System.Address; | |
24340 | ||
24341 | -- The actual variables are stored in a library routine. This | |
24342 | -- is useful for some shared library situations, where there | |
24343 | -- are problems if variables are not in the library. | |
24344 | ||
24345 | pragma Import (C, gnat_argc); | |
24346 | pragma Import (C, gnat_argv); | |
24347 | pragma Import (C, gnat_envp); | |
24348 | ||
24349 | -- The exit status is similarly an external location | |
24350 | ||
24351 | gnat_exit_status : Integer; | |
24352 | pragma Import (C, gnat_exit_status); | |
24353 | ||
24354 | GNAT_Version : constant String := | |
e08b38f5 | 24355 | "GNAT Version: 6.0.0w (20061115)"; |
7cd4527e AC |
24356 | pragma Export (C, GNAT_Version, "__gnat_version"); |
24357 | ||
24358 | -- This is the generated adafinal routine that performs | |
24359 | -- finalization at the end of execution. In the case where | |
24360 | -- Ada is the main program, this main program makes a call | |
24361 | -- to adafinal at program termination. | |
24362 | ||
24363 | procedure adafinal; | |
24364 | pragma Export (C, adafinal, "adafinal"); | |
24365 | ||
24366 | -- This is the generated adainit routine that performs | |
24367 | -- initialization at the start of execution. In the case | |
24368 | -- where Ada is the main program, this main program makes | |
24369 | -- a call to adainit at program startup. | |
24370 | ||
24371 | procedure adainit; | |
24372 | pragma Export (C, adainit, "adainit"); | |
24373 | ||
24374 | -- This routine is called at the start of execution. It is | |
24375 | -- a dummy routine that is used by the debugger to breakpoint | |
24376 | -- at the start of execution. | |
24377 | ||
24378 | procedure Break_Start; | |
24379 | pragma Import (C, Break_Start, "__gnat_break_start"); | |
24380 | ||
24381 | -- This is the actual generated main program (it would be | |
24382 | -- suppressed if the no main program switch were used). As | |
24383 | -- required by standard system conventions, this program has | |
24384 | -- the external name main. | |
24385 | ||
24386 | function main | |
24387 | (argc : Integer; | |
24388 | argv : System.Address; | |
24389 | envp : System.Address) | |
24390 | return Integer; | |
24391 | pragma Export (C, main, "main"); | |
24392 | ||
24393 | -- The following set of constants give the version | |
24394 | -- identification values for every unit in the bound | |
24395 | -- partition. This identification is computed from all | |
24396 | -- dependent semantic units, and corresponds to the | |
24397 | -- string that would be returned by use of the | |
24398 | -- Body_Version or Version attributes. | |
24399 | ||
24400 | type Version_32 is mod 2 ** 32; | |
24401 | u00001 : constant Version_32 := 16#7880BEB3#; | |
24402 | u00002 : constant Version_32 := 16#0D24CBD0#; | |
24403 | u00003 : constant Version_32 := 16#3283DBEB#; | |
24404 | u00004 : constant Version_32 := 16#2359F9ED#; | |
24405 | u00005 : constant Version_32 := 16#664FB847#; | |
24406 | u00006 : constant Version_32 := 16#68E803DF#; | |
24407 | u00007 : constant Version_32 := 16#5572E604#; | |
24408 | u00008 : constant Version_32 := 16#46B173D8#; | |
24409 | u00009 : constant Version_32 := 16#156A40CF#; | |
24410 | u00010 : constant Version_32 := 16#033DABE0#; | |
24411 | u00011 : constant Version_32 := 16#6AB38FEA#; | |
24412 | u00012 : constant Version_32 := 16#22B6217D#; | |
24413 | u00013 : constant Version_32 := 16#68A22947#; | |
24414 | u00014 : constant Version_32 := 16#18CC4A56#; | |
24415 | u00015 : constant Version_32 := 16#08258E1B#; | |
24416 | u00016 : constant Version_32 := 16#367D5222#; | |
24417 | u00017 : constant Version_32 := 16#20C9ECA4#; | |
24418 | u00018 : constant Version_32 := 16#50D32CB6#; | |
24419 | u00019 : constant Version_32 := 16#39A8BB77#; | |
24420 | u00020 : constant Version_32 := 16#5CF8FA2B#; | |
24421 | u00021 : constant Version_32 := 16#2F1EB794#; | |
24422 | u00022 : constant Version_32 := 16#31AB6444#; | |
24423 | u00023 : constant Version_32 := 16#1574B6E9#; | |
24424 | u00024 : constant Version_32 := 16#5109C189#; | |
24425 | u00025 : constant Version_32 := 16#56D770CD#; | |
24426 | u00026 : constant Version_32 := 16#02F9DE3D#; | |
24427 | u00027 : constant Version_32 := 16#08AB6B2C#; | |
24428 | u00028 : constant Version_32 := 16#3FA37670#; | |
24429 | u00029 : constant Version_32 := 16#476457A0#; | |
24430 | u00030 : constant Version_32 := 16#731E1B6E#; | |
24431 | u00031 : constant Version_32 := 16#23C2E789#; | |
24432 | u00032 : constant Version_32 := 16#0F1BD6A1#; | |
24433 | u00033 : constant Version_32 := 16#7C25DE96#; | |
24434 | u00034 : constant Version_32 := 16#39ADFFA2#; | |
24435 | u00035 : constant Version_32 := 16#571DE3E7#; | |
24436 | u00036 : constant Version_32 := 16#5EB646AB#; | |
24437 | u00037 : constant Version_32 := 16#4249379B#; | |
24438 | u00038 : constant Version_32 := 16#0357E00A#; | |
24439 | u00039 : constant Version_32 := 16#3784FB72#; | |
24440 | u00040 : constant Version_32 := 16#2E723019#; | |
24441 | u00041 : constant Version_32 := 16#623358EA#; | |
24442 | u00042 : constant Version_32 := 16#107F9465#; | |
24443 | u00043 : constant Version_32 := 16#6843F68A#; | |
24444 | u00044 : constant Version_32 := 16#63305874#; | |
24445 | u00045 : constant Version_32 := 16#31E56CE1#; | |
24446 | u00046 : constant Version_32 := 16#02917970#; | |
24447 | u00047 : constant Version_32 := 16#6CCBA70E#; | |
24448 | u00048 : constant Version_32 := 16#41CD4204#; | |
24449 | u00049 : constant Version_32 := 16#572E3F58#; | |
24450 | u00050 : constant Version_32 := 16#20729FF5#; | |
24451 | u00051 : constant Version_32 := 16#1D4F93E8#; | |
24452 | u00052 : constant Version_32 := 16#30B2EC3D#; | |
24453 | u00053 : constant Version_32 := 16#34054F96#; | |
24454 | u00054 : constant Version_32 := 16#5A199860#; | |
24455 | u00055 : constant Version_32 := 16#0E7F912B#; | |
24456 | u00056 : constant Version_32 := 16#5760634A#; | |
24457 | u00057 : constant Version_32 := 16#5D851835#; | |
24458 | ||
24459 | -- The following Export pragmas export the version numbers | |
24460 | -- with symbolic names ending in B (for body) or S | |
24461 | -- (for spec) so that they can be located in a link. The | |
24462 | -- information provided here is sufficient to track down | |
24463 | -- the exact versions of units used in a given build. | |
24464 | ||
24465 | pragma Export (C, u00001, "helloB"); | |
24466 | pragma Export (C, u00002, "system__standard_libraryB"); | |
24467 | pragma Export (C, u00003, "system__standard_libraryS"); | |
24468 | pragma Export (C, u00004, "adaS"); | |
24469 | pragma Export (C, u00005, "ada__text_ioB"); | |
24470 | pragma Export (C, u00006, "ada__text_ioS"); | |
24471 | pragma Export (C, u00007, "ada__exceptionsB"); | |
24472 | pragma Export (C, u00008, "ada__exceptionsS"); | |
24473 | pragma Export (C, u00009, "gnatS"); | |
24474 | pragma Export (C, u00010, "gnat__heap_sort_aB"); | |
24475 | pragma Export (C, u00011, "gnat__heap_sort_aS"); | |
24476 | pragma Export (C, u00012, "systemS"); | |
24477 | pragma Export (C, u00013, "system__exception_tableB"); | |
24478 | pragma Export (C, u00014, "system__exception_tableS"); | |
24479 | pragma Export (C, u00015, "gnat__htableB"); | |
24480 | pragma Export (C, u00016, "gnat__htableS"); | |
24481 | pragma Export (C, u00017, "system__exceptionsS"); | |
24482 | pragma Export (C, u00018, "system__machine_state_operationsB"); | |
24483 | pragma Export (C, u00019, "system__machine_state_operationsS"); | |
24484 | pragma Export (C, u00020, "system__machine_codeS"); | |
24485 | pragma Export (C, u00021, "system__storage_elementsB"); | |
24486 | pragma Export (C, u00022, "system__storage_elementsS"); | |
24487 | pragma Export (C, u00023, "system__secondary_stackB"); | |
24488 | pragma Export (C, u00024, "system__secondary_stackS"); | |
24489 | pragma Export (C, u00025, "system__parametersB"); | |
24490 | pragma Export (C, u00026, "system__parametersS"); | |
24491 | pragma Export (C, u00027, "system__soft_linksB"); | |
24492 | pragma Export (C, u00028, "system__soft_linksS"); | |
24493 | pragma Export (C, u00029, "system__stack_checkingB"); | |
24494 | pragma Export (C, u00030, "system__stack_checkingS"); | |
24495 | pragma Export (C, u00031, "system__tracebackB"); | |
24496 | pragma Export (C, u00032, "system__tracebackS"); | |
24497 | pragma Export (C, u00033, "ada__streamsS"); | |
24498 | pragma Export (C, u00034, "ada__tagsB"); | |
24499 | pragma Export (C, u00035, "ada__tagsS"); | |
24500 | pragma Export (C, u00036, "system__string_opsB"); | |
24501 | pragma Export (C, u00037, "system__string_opsS"); | |
24502 | pragma Export (C, u00038, "interfacesS"); | |
24503 | pragma Export (C, u00039, "interfaces__c_streamsB"); | |
24504 | pragma Export (C, u00040, "interfaces__c_streamsS"); | |
24505 | pragma Export (C, u00041, "system__file_ioB"); | |
24506 | pragma Export (C, u00042, "system__file_ioS"); | |
24507 | pragma Export (C, u00043, "ada__finalizationB"); | |
24508 | pragma Export (C, u00044, "ada__finalizationS"); | |
24509 | pragma Export (C, u00045, "system__finalization_rootB"); | |
24510 | pragma Export (C, u00046, "system__finalization_rootS"); | |
24511 | pragma Export (C, u00047, "system__finalization_implementationB"); | |
24512 | pragma Export (C, u00048, "system__finalization_implementationS"); | |
24513 | pragma Export (C, u00049, "system__string_ops_concat_3B"); | |
24514 | pragma Export (C, u00050, "system__string_ops_concat_3S"); | |
24515 | pragma Export (C, u00051, "system__stream_attributesB"); | |
24516 | pragma Export (C, u00052, "system__stream_attributesS"); | |
24517 | pragma Export (C, u00053, "ada__io_exceptionsS"); | |
24518 | pragma Export (C, u00054, "system__unsigned_typesS"); | |
24519 | pragma Export (C, u00055, "system__file_control_blockS"); | |
24520 | pragma Export (C, u00056, "ada__finalization__list_controllerB"); | |
24521 | pragma Export (C, u00057, "ada__finalization__list_controllerS"); | |
24522 | ||
24523 | -- BEGIN ELABORATION ORDER | |
24524 | -- ada (spec) | |
24525 | -- gnat (spec) | |
24526 | -- gnat.heap_sort_a (spec) | |
24527 | -- gnat.heap_sort_a (body) | |
24528 | -- gnat.htable (spec) | |
24529 | -- gnat.htable (body) | |
24530 | -- interfaces (spec) | |
24531 | -- system (spec) | |
24532 | -- system.machine_code (spec) | |
24533 | -- system.parameters (spec) | |
24534 | -- system.parameters (body) | |
24535 | -- interfaces.c_streams (spec) | |
24536 | -- interfaces.c_streams (body) | |
24537 | -- system.standard_library (spec) | |
24538 | -- ada.exceptions (spec) | |
24539 | -- system.exception_table (spec) | |
24540 | -- system.exception_table (body) | |
24541 | -- ada.io_exceptions (spec) | |
24542 | -- system.exceptions (spec) | |
24543 | -- system.storage_elements (spec) | |
24544 | -- system.storage_elements (body) | |
24545 | -- system.machine_state_operations (spec) | |
24546 | -- system.machine_state_operations (body) | |
24547 | -- system.secondary_stack (spec) | |
24548 | -- system.stack_checking (spec) | |
24549 | -- system.soft_links (spec) | |
24550 | -- system.soft_links (body) | |
24551 | -- system.stack_checking (body) | |
24552 | -- system.secondary_stack (body) | |
24553 | -- system.standard_library (body) | |
24554 | -- system.string_ops (spec) | |
24555 | -- system.string_ops (body) | |
24556 | -- ada.tags (spec) | |
24557 | -- ada.tags (body) | |
24558 | -- ada.streams (spec) | |
24559 | -- system.finalization_root (spec) | |
24560 | -- system.finalization_root (body) | |
24561 | -- system.string_ops_concat_3 (spec) | |
24562 | -- system.string_ops_concat_3 (body) | |
24563 | -- system.traceback (spec) | |
24564 | -- system.traceback (body) | |
24565 | -- ada.exceptions (body) | |
24566 | -- system.unsigned_types (spec) | |
24567 | -- system.stream_attributes (spec) | |
24568 | -- system.stream_attributes (body) | |
24569 | -- system.finalization_implementation (spec) | |
24570 | -- system.finalization_implementation (body) | |
24571 | -- ada.finalization (spec) | |
24572 | -- ada.finalization (body) | |
24573 | -- ada.finalization.list_controller (spec) | |
24574 | -- ada.finalization.list_controller (body) | |
24575 | -- system.file_control_block (spec) | |
24576 | -- system.file_io (spec) | |
24577 | -- system.file_io (body) | |
24578 | -- ada.text_io (spec) | |
24579 | -- ada.text_io (body) | |
24580 | -- hello (body) | |
24581 | -- END ELABORATION ORDER | |
24582 | ||
24583 | end ada_main; | |
24584 | ||
24585 | -- The following source file name pragmas allow the generated file | |
24586 | -- names to be unique for different main programs. They are needed | |
24587 | -- since the package name will always be Ada_Main. | |
24588 | ||
24589 | pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads"); | |
24590 | pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb"); | |
24591 | ||
24592 | -- Generated package body for Ada_Main starts here | |
24593 | ||
24594 | package body ada_main is | |
24595 | ||
24596 | -- The actual finalization is performed by calling the | |
24597 | -- library routine in System.Standard_Library.Adafinal | |
24598 | ||
24599 | procedure Do_Finalize; | |
24600 | pragma Import (C, Do_Finalize, "system__standard_library__adafinal"); | |
24601 | ||
24602 | ------------- | |
24603 | -- adainit -- | |
24604 | ------------- | |
24605 | ||
24606 | @findex adainit | |
24607 | procedure adainit is | |
24608 | ||
24609 | -- These booleans are set to True once the associated unit has | |
24610 | -- been elaborated. It is also used to avoid elaborating the | |
24611 | -- same unit twice. | |
88e1739c | 24612 | |
7cd4527e AC |
24613 | E040 : Boolean; |
24614 | pragma Import (Ada, E040, "interfaces__c_streams_E"); | |
88e1739c | 24615 | |
7cd4527e AC |
24616 | E008 : Boolean; |
24617 | pragma Import (Ada, E008, "ada__exceptions_E"); | |
88e1739c | 24618 | |
7cd4527e AC |
24619 | E014 : Boolean; |
24620 | pragma Import (Ada, E014, "system__exception_table_E"); | |
88e1739c | 24621 | |
7cd4527e AC |
24622 | E053 : Boolean; |
24623 | pragma Import (Ada, E053, "ada__io_exceptions_E"); | |
88e1739c | 24624 | |
7cd4527e AC |
24625 | E017 : Boolean; |
24626 | pragma Import (Ada, E017, "system__exceptions_E"); | |
88e1739c | 24627 | |
7cd4527e AC |
24628 | E024 : Boolean; |
24629 | pragma Import (Ada, E024, "system__secondary_stack_E"); | |
88e1739c | 24630 | |
7cd4527e AC |
24631 | E030 : Boolean; |
24632 | pragma Import (Ada, E030, "system__stack_checking_E"); | |
88e1739c | 24633 | |
7cd4527e AC |
24634 | E028 : Boolean; |
24635 | pragma Import (Ada, E028, "system__soft_links_E"); | |
88e1739c | 24636 | |
7cd4527e AC |
24637 | E035 : Boolean; |
24638 | pragma Import (Ada, E035, "ada__tags_E"); | |
88e1739c | 24639 | |
7cd4527e AC |
24640 | E033 : Boolean; |
24641 | pragma Import (Ada, E033, "ada__streams_E"); | |
88e1739c | 24642 | |
7cd4527e AC |
24643 | E046 : Boolean; |
24644 | pragma Import (Ada, E046, "system__finalization_root_E"); | |
88e1739c | 24645 | |
7cd4527e AC |
24646 | E048 : Boolean; |
24647 | pragma Import (Ada, E048, "system__finalization_implementation_E"); | |
88e1739c | 24648 | |
7cd4527e AC |
24649 | E044 : Boolean; |
24650 | pragma Import (Ada, E044, "ada__finalization_E"); | |
88e1739c | 24651 | |
7cd4527e AC |
24652 | E057 : Boolean; |
24653 | pragma Import (Ada, E057, "ada__finalization__list_controller_E"); | |
88e1739c | 24654 | |
7cd4527e AC |
24655 | E055 : Boolean; |
24656 | pragma Import (Ada, E055, "system__file_control_block_E"); | |
88e1739c | 24657 | |
7cd4527e AC |
24658 | E042 : Boolean; |
24659 | pragma Import (Ada, E042, "system__file_io_E"); | |
88e1739c | 24660 | |
7cd4527e AC |
24661 | E006 : Boolean; |
24662 | pragma Import (Ada, E006, "ada__text_io_E"); | |
88e1739c | 24663 | |
7cd4527e AC |
24664 | -- Set_Globals is a library routine that stores away the |
24665 | -- value of the indicated set of global values in global | |
24666 | -- variables within the library. | |
88e1739c | 24667 | |
7cd4527e AC |
24668 | procedure Set_Globals |
24669 | (Main_Priority : Integer; | |
24670 | Time_Slice_Value : Integer; | |
24671 | WC_Encoding : Character; | |
24672 | Locking_Policy : Character; | |
24673 | Queuing_Policy : Character; | |
24674 | Task_Dispatching_Policy : Character; | |
24675 | Adafinal : System.Address; | |
24676 | Unreserve_All_Interrupts : Integer; | |
24677 | Exception_Tracebacks : Integer); | |
24678 | @findex __gnat_set_globals | |
24679 | pragma Import (C, Set_Globals, "__gnat_set_globals"); | |
88e1739c | 24680 | |
7cd4527e AC |
24681 | -- SDP_Table_Build is a library routine used to build the |
24682 | -- exception tables. See unit Ada.Exceptions in files | |
24683 | -- a-except.ads/adb for full details of how zero cost | |
24684 | -- exception handling works. This procedure, the call to | |
24685 | -- it, and the two following tables are all omitted if the | |
30783513 | 24686 | -- build is in longjmp/setjmp exception mode. |
88e1739c | 24687 | |
7cd4527e AC |
24688 | @findex SDP_Table_Build |
24689 | @findex Zero Cost Exceptions | |
24690 | procedure SDP_Table_Build | |
24691 | (SDP_Addresses : System.Address; | |
24692 | SDP_Count : Natural; | |
24693 | Elab_Addresses : System.Address; | |
24694 | Elab_Addr_Count : Natural); | |
24695 | pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build"); | |
88e1739c | 24696 | |
7cd4527e AC |
24697 | -- Table of Unit_Exception_Table addresses. Used for zero |
24698 | -- cost exception handling to build the top level table. | |
88e1739c | 24699 | |
7cd4527e AC |
24700 | ST : aliased constant array (1 .. 23) of System.Address := ( |
24701 | Hello'UET_Address, | |
24702 | Ada.Text_Io'UET_Address, | |
24703 | Ada.Exceptions'UET_Address, | |
24704 | Gnat.Heap_Sort_A'UET_Address, | |
24705 | System.Exception_Table'UET_Address, | |
24706 | System.Machine_State_Operations'UET_Address, | |
24707 | System.Secondary_Stack'UET_Address, | |
24708 | System.Parameters'UET_Address, | |
24709 | System.Soft_Links'UET_Address, | |
24710 | System.Stack_Checking'UET_Address, | |
24711 | System.Traceback'UET_Address, | |
24712 | Ada.Streams'UET_Address, | |
24713 | Ada.Tags'UET_Address, | |
24714 | System.String_Ops'UET_Address, | |
24715 | Interfaces.C_Streams'UET_Address, | |
24716 | System.File_Io'UET_Address, | |
24717 | Ada.Finalization'UET_Address, | |
24718 | System.Finalization_Root'UET_Address, | |
24719 | System.Finalization_Implementation'UET_Address, | |
24720 | System.String_Ops_Concat_3'UET_Address, | |
24721 | System.Stream_Attributes'UET_Address, | |
24722 | System.File_Control_Block'UET_Address, | |
24723 | Ada.Finalization.List_Controller'UET_Address); | |
88e1739c | 24724 | |
7cd4527e AC |
24725 | -- Table of addresses of elaboration routines. Used for |
24726 | -- zero cost exception handling to make sure these | |
24727 | -- addresses are included in the top level procedure | |
24728 | -- address table. | |
88e1739c | 24729 | |
7cd4527e AC |
24730 | EA : aliased constant array (1 .. 23) of System.Address := ( |
24731 | adainit'Code_Address, | |
24732 | Do_Finalize'Code_Address, | |
24733 | Ada.Exceptions'Elab_Spec'Address, | |
24734 | System.Exceptions'Elab_Spec'Address, | |
24735 | Interfaces.C_Streams'Elab_Spec'Address, | |
24736 | System.Exception_Table'Elab_Body'Address, | |
24737 | Ada.Io_Exceptions'Elab_Spec'Address, | |
24738 | System.Stack_Checking'Elab_Spec'Address, | |
24739 | System.Soft_Links'Elab_Body'Address, | |
24740 | System.Secondary_Stack'Elab_Body'Address, | |
24741 | Ada.Tags'Elab_Spec'Address, | |
24742 | Ada.Tags'Elab_Body'Address, | |
24743 | Ada.Streams'Elab_Spec'Address, | |
24744 | System.Finalization_Root'Elab_Spec'Address, | |
24745 | Ada.Exceptions'Elab_Body'Address, | |
24746 | System.Finalization_Implementation'Elab_Spec'Address, | |
24747 | System.Finalization_Implementation'Elab_Body'Address, | |
24748 | Ada.Finalization'Elab_Spec'Address, | |
24749 | Ada.Finalization.List_Controller'Elab_Spec'Address, | |
24750 | System.File_Control_Block'Elab_Spec'Address, | |
24751 | System.File_Io'Elab_Body'Address, | |
24752 | Ada.Text_Io'Elab_Spec'Address, | |
24753 | Ada.Text_Io'Elab_Body'Address); | |
88e1739c | 24754 | |
7cd4527e | 24755 | -- Start of processing for adainit |
88e1739c | 24756 | |
7cd4527e | 24757 | begin |
88e1739c | 24758 | |
7cd4527e AC |
24759 | -- Call SDP_Table_Build to build the top level procedure |
24760 | -- table for zero cost exception handling (omitted in | |
30783513 | 24761 | -- longjmp/setjmp mode). |
88e1739c | 24762 | |
7cd4527e | 24763 | SDP_Table_Build (ST'Address, 23, EA'Address, 23); |
88e1739c | 24764 | |
7cd4527e AC |
24765 | -- Call Set_Globals to record various information for |
24766 | -- this partition. The values are derived by the binder | |
24767 | -- from information stored in the ali files by the compiler. | |
88e1739c | 24768 | |
7cd4527e AC |
24769 | @findex __gnat_set_globals |
24770 | Set_Globals | |
24771 | (Main_Priority => -1, | |
24772 | -- Priority of main program, -1 if no pragma Priority used | |
88e1739c | 24773 | |
7cd4527e AC |
24774 | Time_Slice_Value => -1, |
24775 | -- Time slice from Time_Slice pragma, -1 if none used | |
88e1739c | 24776 | |
7cd4527e AC |
24777 | WC_Encoding => 'b', |
24778 | -- Wide_Character encoding used, default is brackets | |
24779 | ||
24780 | Locking_Policy => ' ', | |
24781 | -- Locking_Policy used, default of space means not | |
24782 | -- specified, otherwise it is the first character of | |
24783 | -- the policy name. | |
88e1739c | 24784 | |
7cd4527e AC |
24785 | Queuing_Policy => ' ', |
24786 | -- Queuing_Policy used, default of space means not | |
24787 | -- specified, otherwise it is the first character of | |
24788 | -- the policy name. | |
88e1739c | 24789 | |
7cd4527e AC |
24790 | Task_Dispatching_Policy => ' ', |
24791 | -- Task_Dispatching_Policy used, default of space means | |
24792 | -- not specified, otherwise first character of the | |
24793 | -- policy name. | |
88e1739c | 24794 | |
7cd4527e AC |
24795 | Adafinal => System.Null_Address, |
24796 | -- Address of Adafinal routine, not used anymore | |
88e1739c | 24797 | |
7cd4527e AC |
24798 | Unreserve_All_Interrupts => 0, |
24799 | -- Set true if pragma Unreserve_All_Interrupts was used | |
88e1739c | 24800 | |
7cd4527e AC |
24801 | Exception_Tracebacks => 0); |
24802 | -- Indicates if exception tracebacks are enabled | |
88e1739c | 24803 | |
7cd4527e | 24804 | Elab_Final_Code := 1; |
88e1739c | 24805 | |
7cd4527e AC |
24806 | -- Now we have the elaboration calls for all units in the partition. |
24807 | -- The Elab_Spec and Elab_Body attributes generate references to the | |
24808 | -- implicit elaboration procedures generated by the compiler for | |
24809 | -- each unit that requires elaboration. | |
88e1739c | 24810 | |
7cd4527e AC |
24811 | if not E040 then |
24812 | Interfaces.C_Streams'Elab_Spec; | |
24813 | end if; | |
24814 | E040 := True; | |
24815 | if not E008 then | |
24816 | Ada.Exceptions'Elab_Spec; | |
24817 | end if; | |
24818 | if not E014 then | |
24819 | System.Exception_Table'Elab_Body; | |
24820 | E014 := True; | |
24821 | end if; | |
24822 | if not E053 then | |
24823 | Ada.Io_Exceptions'Elab_Spec; | |
24824 | E053 := True; | |
24825 | end if; | |
24826 | if not E017 then | |
24827 | System.Exceptions'Elab_Spec; | |
24828 | E017 := True; | |
24829 | end if; | |
24830 | if not E030 then | |
24831 | System.Stack_Checking'Elab_Spec; | |
24832 | end if; | |
24833 | if not E028 then | |
24834 | System.Soft_Links'Elab_Body; | |
24835 | E028 := True; | |
24836 | end if; | |
24837 | E030 := True; | |
24838 | if not E024 then | |
24839 | System.Secondary_Stack'Elab_Body; | |
24840 | E024 := True; | |
24841 | end if; | |
24842 | if not E035 then | |
24843 | Ada.Tags'Elab_Spec; | |
24844 | end if; | |
24845 | if not E035 then | |
24846 | Ada.Tags'Elab_Body; | |
24847 | E035 := True; | |
24848 | end if; | |
24849 | if not E033 then | |
24850 | Ada.Streams'Elab_Spec; | |
24851 | E033 := True; | |
24852 | end if; | |
24853 | if not E046 then | |
24854 | System.Finalization_Root'Elab_Spec; | |
24855 | end if; | |
24856 | E046 := True; | |
24857 | if not E008 then | |
24858 | Ada.Exceptions'Elab_Body; | |
24859 | E008 := True; | |
24860 | end if; | |
24861 | if not E048 then | |
24862 | System.Finalization_Implementation'Elab_Spec; | |
24863 | end if; | |
24864 | if not E048 then | |
24865 | System.Finalization_Implementation'Elab_Body; | |
24866 | E048 := True; | |
24867 | end if; | |
24868 | if not E044 then | |
24869 | Ada.Finalization'Elab_Spec; | |
24870 | end if; | |
24871 | E044 := True; | |
24872 | if not E057 then | |
24873 | Ada.Finalization.List_Controller'Elab_Spec; | |
24874 | end if; | |
24875 | E057 := True; | |
24876 | if not E055 then | |
24877 | System.File_Control_Block'Elab_Spec; | |
24878 | E055 := True; | |
24879 | end if; | |
24880 | if not E042 then | |
24881 | System.File_Io'Elab_Body; | |
24882 | E042 := True; | |
24883 | end if; | |
24884 | if not E006 then | |
24885 | Ada.Text_Io'Elab_Spec; | |
24886 | end if; | |
24887 | if not E006 then | |
24888 | Ada.Text_Io'Elab_Body; | |
24889 | E006 := True; | |
24890 | end if; | |
88e1739c | 24891 | |
7cd4527e AC |
24892 | Elab_Final_Code := 0; |
24893 | end adainit; | |
88e1739c | 24894 | |
7cd4527e AC |
24895 | -------------- |
24896 | -- adafinal -- | |
24897 | -------------- | |
88e1739c | 24898 | |
7cd4527e AC |
24899 | @findex adafinal |
24900 | procedure adafinal is | |
24901 | begin | |
24902 | Do_Finalize; | |
24903 | end adafinal; | |
88e1739c | 24904 | |
7cd4527e AC |
24905 | ---------- |
24906 | -- main -- | |
24907 | ---------- | |
88e1739c | 24908 | |
7cd4527e AC |
24909 | -- main is actually a function, as in the ANSI C standard, |
24910 | -- defined to return the exit status. The three parameters | |
24911 | -- are the argument count, argument values and environment | |
24912 | -- pointer. | |
88e1739c | 24913 | |
7cd4527e AC |
24914 | @findex Main Program |
24915 | function main | |
24916 | (argc : Integer; | |
24917 | argv : System.Address; | |
24918 | envp : System.Address) | |
24919 | return Integer | |
24920 | is | |
24921 | -- The initialize routine performs low level system | |
24922 | -- initialization using a standard library routine which | |
24923 | -- sets up signal handling and performs any other | |
24924 | -- required setup. The routine can be found in file | |
24925 | -- a-init.c. | |
88e1739c | 24926 | |
7cd4527e AC |
24927 | @findex __gnat_initialize |
24928 | procedure initialize; | |
24929 | pragma Import (C, initialize, "__gnat_initialize"); | |
88e1739c | 24930 | |
7cd4527e AC |
24931 | -- The finalize routine performs low level system |
24932 | -- finalization using a standard library routine. The | |
24933 | -- routine is found in file a-final.c and in the standard | |
24934 | -- distribution is a dummy routine that does nothing, so | |
24935 | -- really this is a hook for special user finalization. | |
88e1739c | 24936 | |
7cd4527e AC |
24937 | @findex __gnat_finalize |
24938 | procedure finalize; | |
24939 | pragma Import (C, finalize, "__gnat_finalize"); | |
88e1739c | 24940 | |
7cd4527e AC |
24941 | -- We get to the main program of the partition by using |
24942 | -- pragma Import because if we try to with the unit and | |
24943 | -- call it Ada style, then not only do we waste time | |
24944 | -- recompiling it, but also, we don't really know the right | |
8dd07840 | 24945 | -- switches (e.g.@: identifier character set) to be used |
7cd4527e | 24946 | -- to compile it. |
88e1739c | 24947 | |
7cd4527e AC |
24948 | procedure Ada_Main_Program; |
24949 | pragma Import (Ada, Ada_Main_Program, "_ada_hello"); | |
88e1739c | 24950 | |
7cd4527e | 24951 | -- Start of processing for main |
88e1739c | 24952 | |
7cd4527e AC |
24953 | begin |
24954 | -- Save global variables | |
88e1739c | 24955 | |
7cd4527e AC |
24956 | gnat_argc := argc; |
24957 | gnat_argv := argv; | |
24958 | gnat_envp := envp; | |
88e1739c | 24959 | |
7cd4527e | 24960 | -- Call low level system initialization |
88e1739c | 24961 | |
7cd4527e | 24962 | Initialize; |
88e1739c | 24963 | |
7cd4527e | 24964 | -- Call our generated Ada initialization routine |
88e1739c | 24965 | |
7cd4527e AC |
24966 | adainit; |
24967 | ||
24968 | -- This is the point at which we want the debugger to get | |
24969 | -- control | |
24970 | ||
24971 | Break_Start; | |
24972 | ||
24973 | -- Now we call the main program of the partition | |
88e1739c | 24974 | |
7cd4527e | 24975 | Ada_Main_Program; |
88e1739c | 24976 | |
7cd4527e | 24977 | -- Perform Ada finalization |
88e1739c | 24978 | |
7cd4527e | 24979 | adafinal; |
88e1739c | 24980 | |
7cd4527e | 24981 | -- Perform low level system finalization |
88e1739c | 24982 | |
7cd4527e | 24983 | Finalize; |
88e1739c | 24984 | |
7cd4527e AC |
24985 | -- Return the proper exit status |
24986 | return (gnat_exit_status); | |
24987 | end; | |
88e1739c | 24988 | |
7cd4527e AC |
24989 | -- This section is entirely comments, so it has no effect on the |
24990 | -- compilation of the Ada_Main package. It provides the list of | |
24991 | -- object files and linker options, as well as some standard | |
24992 | -- libraries needed for the link. The gnatlink utility parses | |
24993 | -- this b~hello.adb file to read these comment lines to generate | |
24994 | -- the appropriate command line arguments for the call to the | |
24995 | -- system linker. The BEGIN/END lines are used for sentinels for | |
24996 | -- this parsing operation. | |
88e1739c | 24997 | |
7cd4527e AC |
24998 | -- The exact file names will of course depend on the environment, |
24999 | -- host/target and location of files on the host system. | |
25000 | ||
25001 | @findex Object file list | |
25002 | -- BEGIN Object file/option list | |
25003 | -- ./hello.o | |
25004 | -- -L./ | |
25005 | -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/ | |
25006 | -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a | |
25007 | -- END Object file/option list | |
25008 | ||
25009 | end ada_main; | |
88e1739c | 25010 | @end smallexample |
7cd4527e | 25011 | |
88e1739c | 25012 | @noindent |
7cd4527e AC |
25013 | The Ada code in the above example is exactly what is generated by the |
25014 | binder. We have added comments to more clearly indicate the function | |
25015 | of each part of the generated @code{Ada_Main} package. | |
88e1739c | 25016 | |
7cd4527e AC |
25017 | The code is standard Ada in all respects, and can be processed by any |
25018 | tools that handle Ada. In particular, it is possible to use the debugger | |
25019 | in Ada mode to debug the generated @code{Ada_Main} package. For example, | |
25020 | suppose that for reasons that you do not understand, your program is crashing | |
25021 | during elaboration of the body of @code{Ada.Text_IO}. To locate this bug, | |
25022 | you can place a breakpoint on the call: | |
88e1739c | 25023 | |
7cd4527e AC |
25024 | @smallexample @c ada |
25025 | Ada.Text_Io'Elab_Body; | |
88e1739c FW |
25026 | @end smallexample |
25027 | ||
25028 | @noindent | |
7cd4527e AC |
25029 | and trace the elaboration routine for this package to find out where |
25030 | the problem might be (more usually of course you would be debugging | |
25031 | elaboration code in your own application). | |
88e1739c | 25032 | |
7cd4527e AC |
25033 | @node Elaboration Order Handling in GNAT |
25034 | @appendix Elaboration Order Handling in GNAT | |
25035 | @cindex Order of elaboration | |
25036 | @cindex Elaboration control | |
25037 | ||
25038 | @menu | |
e08b38f5 VC |
25039 | * Elaboration Code:: |
25040 | * Checking the Elaboration Order:: | |
25041 | * Controlling the Elaboration Order:: | |
7cd4527e AC |
25042 | * Controlling Elaboration in GNAT - Internal Calls:: |
25043 | * Controlling Elaboration in GNAT - External Calls:: | |
25044 | * Default Behavior in GNAT - Ensuring Safety:: | |
25045 | * Treatment of Pragma Elaborate:: | |
25046 | * Elaboration Issues for Library Tasks:: | |
25047 | * Mixing Elaboration Models:: | |
25048 | * What to Do If the Default Elaboration Behavior Fails:: | |
78c0f016 | 25049 | * Elaboration for Dispatching Calls:: |
7cd4527e AC |
25050 | * Summary of Procedures for Elaboration Control:: |
25051 | * Other Elaboration Order Considerations:: | |
4c51ff88 | 25052 | * Determining the Chosen Elaboration Order:: |
7cd4527e | 25053 | @end menu |
88e1739c FW |
25054 | |
25055 | @noindent | |
e08b38f5 | 25056 | This chapter describes the handling of elaboration code in Ada and |
7cd4527e AC |
25057 | in GNAT, and discusses how the order of elaboration of program units can |
25058 | be controlled in GNAT, either automatically or with explicit programming | |
25059 | features. | |
88e1739c | 25060 | |
e08b38f5 VC |
25061 | @node Elaboration Code |
25062 | @section Elaboration Code | |
88e1739c | 25063 | |
7cd4527e | 25064 | @noindent |
e08b38f5 | 25065 | Ada provides rather general mechanisms for executing code at elaboration |
7cd4527e AC |
25066 | time, that is to say before the main program starts executing. Such code arises |
25067 | in three contexts: | |
25068 | ||
25069 | @table @asis | |
25070 | @item Initializers for variables. | |
25071 | Variables declared at the library level, in package specs or bodies, can | |
25072 | require initialization that is performed at elaboration time, as in: | |
25073 | @smallexample @c ada | |
25074 | @cartouche | |
25075 | Sqrt_Half : Float := Sqrt (0.5); | |
25076 | @end cartouche | |
88e1739c FW |
25077 | @end smallexample |
25078 | ||
7cd4527e AC |
25079 | @item Package initialization code |
25080 | Code in a @code{BEGIN-END} section at the outer level of a package body is | |
25081 | executed as part of the package body elaboration code. | |
88e1739c | 25082 | |
7cd4527e AC |
25083 | @item Library level task allocators |
25084 | Tasks that are declared using task allocators at the library level | |
25085 | start executing immediately and hence can execute at elaboration time. | |
25086 | @end table | |
88e1739c | 25087 | |
7cd4527e AC |
25088 | @noindent |
25089 | Subprogram calls are possible in any of these contexts, which means that | |
25090 | any arbitrary part of the program may be executed as part of the elaboration | |
25091 | code. It is even possible to write a program which does all its work at | |
25092 | elaboration time, with a null main program, although stylistically this | |
25093 | would usually be considered an inappropriate way to structure | |
25094 | a program. | |
88e1739c | 25095 | |
7cd4527e AC |
25096 | An important concern arises in the context of elaboration code: |
25097 | we have to be sure that it is executed in an appropriate order. What we | |
25098 | have is a series of elaboration code sections, potentially one section | |
25099 | for each unit in the program. It is important that these execute | |
25100 | in the correct order. Correctness here means that, taking the above | |
25101 | example of the declaration of @code{Sqrt_Half}, | |
25102 | if some other piece of | |
25103 | elaboration code references @code{Sqrt_Half}, | |
25104 | then it must run after the | |
25105 | section of elaboration code that contains the declaration of | |
25106 | @code{Sqrt_Half}. | |
88e1739c | 25107 | |
7cd4527e AC |
25108 | There would never be any order of elaboration problem if we made a rule |
25109 | that whenever you @code{with} a unit, you must elaborate both the spec and body | |
25110 | of that unit before elaborating the unit doing the @code{with}'ing: | |
88e1739c | 25111 | |
7cd4527e AC |
25112 | @smallexample @c ada |
25113 | @group | |
25114 | @cartouche | |
25115 | with Unit_1; | |
d488f6ea | 25116 | package Unit_2 is @dots{} |
7cd4527e | 25117 | @end cartouche |
88e1739c FW |
25118 | @end group |
25119 | @end smallexample | |
25120 | ||
7cd4527e AC |
25121 | @noindent |
25122 | would require that both the body and spec of @code{Unit_1} be elaborated | |
25123 | before the spec of @code{Unit_2}. However, a rule like that would be far too | |
25124 | restrictive. In particular, it would make it impossible to have routines | |
25125 | in separate packages that were mutually recursive. | |
88e1739c | 25126 | |
7cd4527e AC |
25127 | You might think that a clever enough compiler could look at the actual |
25128 | elaboration code and determine an appropriate correct order of elaboration, | |
25129 | but in the general case, this is not possible. Consider the following | |
25130 | example. | |
88e1739c | 25131 | |
7cd4527e AC |
25132 | In the body of @code{Unit_1}, we have a procedure @code{Func_1} |
25133 | that references | |
25134 | the variable @code{Sqrt_1}, which is declared in the elaboration code | |
25135 | of the body of @code{Unit_1}: | |
88e1739c | 25136 | |
7cd4527e AC |
25137 | @smallexample @c ada |
25138 | @cartouche | |
25139 | Sqrt_1 : Float := Sqrt (0.1); | |
25140 | @end cartouche | |
25141 | @end smallexample | |
88e1739c | 25142 | |
7cd4527e AC |
25143 | @noindent |
25144 | The elaboration code of the body of @code{Unit_1} also contains: | |
88e1739c | 25145 | |
7cd4527e | 25146 | @smallexample @c ada |
88e1739c | 25147 | @group |
7cd4527e AC |
25148 | @cartouche |
25149 | if expression_1 = 1 then | |
25150 | Q := Unit_2.Func_2; | |
25151 | end if; | |
25152 | @end cartouche | |
88e1739c FW |
25153 | @end group |
25154 | @end smallexample | |
25155 | ||
88e1739c | 25156 | @noindent |
7cd4527e AC |
25157 | @code{Unit_2} is exactly parallel, |
25158 | it has a procedure @code{Func_2} that references | |
25159 | the variable @code{Sqrt_2}, which is declared in the elaboration code of | |
25160 | the body @code{Unit_2}: | |
88e1739c | 25161 | |
7cd4527e AC |
25162 | @smallexample @c ada |
25163 | @cartouche | |
25164 | Sqrt_2 : Float := Sqrt (0.1); | |
25165 | @end cartouche | |
25166 | @end smallexample | |
88e1739c | 25167 | |
7cd4527e AC |
25168 | @noindent |
25169 | The elaboration code of the body of @code{Unit_2} also contains: | |
88e1739c | 25170 | |
7cd4527e AC |
25171 | @smallexample @c ada |
25172 | @group | |
25173 | @cartouche | |
25174 | if expression_2 = 2 then | |
25175 | Q := Unit_1.Func_1; | |
25176 | end if; | |
25177 | @end cartouche | |
88e1739c FW |
25178 | @end group |
25179 | @end smallexample | |
25180 | ||
7cd4527e AC |
25181 | @noindent |
25182 | Now the question is, which of the following orders of elaboration is | |
25183 | acceptable: | |
88e1739c FW |
25184 | |
25185 | @smallexample | |
25186 | @group | |
7cd4527e AC |
25187 | Spec of Unit_1 |
25188 | Spec of Unit_2 | |
25189 | Body of Unit_1 | |
25190 | Body of Unit_2 | |
88e1739c FW |
25191 | @end group |
25192 | @end smallexample | |
25193 | ||
25194 | @noindent | |
7cd4527e | 25195 | or |
88e1739c FW |
25196 | |
25197 | @smallexample | |
25198 | @group | |
7cd4527e AC |
25199 | Spec of Unit_2 |
25200 | Spec of Unit_1 | |
25201 | Body of Unit_2 | |
25202 | Body of Unit_1 | |
88e1739c FW |
25203 | @end group |
25204 | @end smallexample | |
25205 | ||
25206 | @noindent | |
7cd4527e AC |
25207 | If you carefully analyze the flow here, you will see that you cannot tell |
25208 | at compile time the answer to this question. | |
25209 | If @code{expression_1} is not equal to 1, | |
25210 | and @code{expression_2} is not equal to 2, | |
25211 | then either order is acceptable, because neither of the function calls is | |
25212 | executed. If both tests evaluate to true, then neither order is acceptable | |
25213 | and in fact there is no correct order. | |
88e1739c | 25214 | |
7cd4527e AC |
25215 | If one of the two expressions is true, and the other is false, then one |
25216 | of the above orders is correct, and the other is incorrect. For example, | |
c690a2ec RD |
25217 | if @code{expression_1} /= 1 and @code{expression_2} = 2, |
25218 | then the call to @code{Func_1} | |
25219 | will occur, but not the call to @code{Func_2.} | |
7cd4527e AC |
25220 | This means that it is essential |
25221 | to elaborate the body of @code{Unit_1} before | |
25222 | the body of @code{Unit_2}, so the first | |
25223 | order of elaboration is correct and the second is wrong. | |
25224 | ||
25225 | By making @code{expression_1} and @code{expression_2} | |
25226 | depend on input data, or perhaps | |
25227 | the time of day, we can make it impossible for the compiler or binder | |
25228 | to figure out which of these expressions will be true, and hence it | |
25229 | is impossible to guarantee a safe order of elaboration at run time. | |
25230 | ||
e08b38f5 VC |
25231 | @node Checking the Elaboration Order |
25232 | @section Checking the Elaboration Order | |
88e1739c FW |
25233 | |
25234 | @noindent | |
7cd4527e | 25235 | In some languages that involve the same kind of elaboration problems, |
8dd07840 | 25236 | e.g.@: Java and C++, the programmer is expected to worry about these |
7cd4527e AC |
25237 | ordering problems himself, and it is common to |
25238 | write a program in which an incorrect elaboration order gives | |
25239 | surprising results, because it references variables before they | |
25240 | are initialized. | |
e08b38f5 | 25241 | Ada is designed to be a safe language, and a programmer-beware approach is |
7cd4527e AC |
25242 | clearly not sufficient. Consequently, the language provides three lines |
25243 | of defense: | |
88e1739c | 25244 | |
7cd4527e AC |
25245 | @table @asis |
25246 | @item Standard rules | |
25247 | Some standard rules restrict the possible choice of elaboration | |
25248 | order. In particular, if you @code{with} a unit, then its spec is always | |
25249 | elaborated before the unit doing the @code{with}. Similarly, a parent | |
25250 | spec is always elaborated before the child spec, and finally | |
25251 | a spec is always elaborated before its corresponding body. | |
88e1739c | 25252 | |
7cd4527e AC |
25253 | @item Dynamic elaboration checks |
25254 | @cindex Elaboration checks | |
25255 | @cindex Checks, elaboration | |
25256 | Dynamic checks are made at run time, so that if some entity is accessed | |
25257 | before it is elaborated (typically by means of a subprogram call) | |
25258 | then the exception (@code{Program_Error}) is raised. | |
25259 | ||
25260 | @item Elaboration control | |
25261 | Facilities are provided for the programmer to specify the desired order | |
25262 | of elaboration. | |
25263 | @end table | |
25264 | ||
25265 | Let's look at these facilities in more detail. First, the rules for | |
25266 | dynamic checking. One possible rule would be simply to say that the | |
25267 | exception is raised if you access a variable which has not yet been | |
25268 | elaborated. The trouble with this approach is that it could require | |
e08b38f5 | 25269 | expensive checks on every variable reference. Instead Ada has two |
7cd4527e AC |
25270 | rules which are a little more restrictive, but easier to check, and |
25271 | easier to state: | |
25272 | ||
25273 | @table @asis | |
25274 | @item Restrictions on calls | |
25275 | A subprogram can only be called at elaboration time if its body | |
25276 | has been elaborated. The rules for elaboration given above guarantee | |
25277 | that the spec of the subprogram has been elaborated before the | |
25278 | call, but not the body. If this rule is violated, then the | |
25279 | exception @code{Program_Error} is raised. | |
25280 | ||
25281 | @item Restrictions on instantiations | |
25282 | A generic unit can only be instantiated if the body of the generic | |
25283 | unit has been elaborated. Again, the rules for elaboration given above | |
25284 | guarantee that the spec of the generic unit has been elaborated | |
25285 | before the instantiation, but not the body. If this rule is | |
25286 | violated, then the exception @code{Program_Error} is raised. | |
25287 | @end table | |
88e1739c FW |
25288 | |
25289 | @noindent | |
7cd4527e AC |
25290 | The idea is that if the body has been elaborated, then any variables |
25291 | it references must have been elaborated; by checking for the body being | |
25292 | elaborated we guarantee that none of its references causes any | |
25293 | trouble. As we noted above, this is a little too restrictive, because a | |
25294 | subprogram that has no non-local references in its body may in fact be safe | |
25295 | to call. However, it really would be unsafe to rely on this, because | |
25296 | it would mean that the caller was aware of details of the implementation | |
25297 | in the body. This goes against the basic tenets of Ada. | |
25298 | ||
25299 | A plausible implementation can be described as follows. | |
25300 | A Boolean variable is associated with each subprogram | |
25301 | and each generic unit. This variable is initialized to False, and is set to | |
25302 | True at the point body is elaborated. Every call or instantiation checks the | |
25303 | variable, and raises @code{Program_Error} if the variable is False. | |
25304 | ||
25305 | Note that one might think that it would be good enough to have one Boolean | |
25306 | variable for each package, but that would not deal with cases of trying | |
25307 | to call a body in the same package as the call | |
25308 | that has not been elaborated yet. | |
25309 | Of course a compiler may be able to do enough analysis to optimize away | |
25310 | some of the Boolean variables as unnecessary, and @code{GNAT} indeed | |
25311 | does such optimizations, but still the easiest conceptual model is to | |
25312 | think of there being one variable per subprogram. | |
25313 | ||
e08b38f5 VC |
25314 | @node Controlling the Elaboration Order |
25315 | @section Controlling the Elaboration Order | |
88e1739c | 25316 | |
88e1739c | 25317 | @noindent |
e08b38f5 | 25318 | In the previous section we discussed the rules in Ada which ensure |
7cd4527e AC |
25319 | that @code{Program_Error} is raised if an incorrect elaboration order is |
25320 | chosen. This prevents erroneous executions, but we need mechanisms to | |
25321 | specify a correct execution and avoid the exception altogether. | |
e08b38f5 | 25322 | To achieve this, Ada provides a number of features for controlling |
7cd4527e | 25323 | the order of elaboration. We discuss these features in this section. |
88e1739c | 25324 | |
7cd4527e AC |
25325 | First, there are several ways of indicating to the compiler that a given |
25326 | unit has no elaboration problems: | |
88e1739c | 25327 | |
7cd4527e AC |
25328 | @table @asis |
25329 | @item packages that do not require a body | |
e08b38f5 VC |
25330 | A library package that does not require a body does not permit |
25331 | a body (this rule was introduced in Ada 95). | |
25332 | Thus if we have a such a package, as in: | |
7cd4527e AC |
25333 | |
25334 | @smallexample @c ada | |
88e1739c | 25335 | @group |
7cd4527e AC |
25336 | @cartouche |
25337 | package Definitions is | |
25338 | generic | |
25339 | type m is new integer; | |
25340 | package Subp is | |
25341 | type a is array (1 .. 10) of m; | |
25342 | type b is array (1 .. 20) of m; | |
25343 | end Subp; | |
25344 | end Definitions; | |
25345 | @end cartouche | |
88e1739c FW |
25346 | @end group |
25347 | @end smallexample | |
25348 | ||
7cd4527e AC |
25349 | @noindent |
25350 | A package that @code{with}'s @code{Definitions} may safely instantiate | |
25351 | @code{Definitions.Subp} because the compiler can determine that there | |
25352 | definitely is no package body to worry about in this case | |
88e1739c | 25353 | |
7cd4527e AC |
25354 | @item pragma Pure |
25355 | @cindex pragma Pure | |
25356 | @findex Pure | |
25357 | Places sufficient restrictions on a unit to guarantee that | |
25358 | no call to any subprogram in the unit can result in an | |
25359 | elaboration problem. This means that the compiler does not need | |
25360 | to worry about the point of elaboration of such units, and in | |
25361 | particular, does not need to check any calls to any subprograms | |
25362 | in this unit. | |
88e1739c | 25363 | |
7cd4527e AC |
25364 | @item pragma Preelaborate |
25365 | @findex Preelaborate | |
25366 | @cindex pragma Preelaborate | |
25367 | This pragma places slightly less stringent restrictions on a unit than | |
25368 | does pragma Pure, | |
25369 | but these restrictions are still sufficient to ensure that there | |
25370 | are no elaboration problems with any calls to the unit. | |
88e1739c | 25371 | |
7cd4527e AC |
25372 | @item pragma Elaborate_Body |
25373 | @findex Elaborate_Body | |
25374 | @cindex pragma Elaborate_Body | |
25375 | This pragma requires that the body of a unit be elaborated immediately | |
25376 | after its spec. Suppose a unit @code{A} has such a pragma, | |
25377 | and unit @code{B} does | |
25378 | a @code{with} of unit @code{A}. Recall that the standard rules require | |
25379 | the spec of unit @code{A} | |
25380 | to be elaborated before the @code{with}'ing unit; given the pragma in | |
25381 | @code{A}, we also know that the body of @code{A} | |
25382 | will be elaborated before @code{B}, so | |
25383 | that calls to @code{A} are safe and do not need a check. | |
25384 | @end table | |
88e1739c | 25385 | |
7cd4527e AC |
25386 | @noindent |
25387 | Note that, | |
25388 | unlike pragma @code{Pure} and pragma @code{Preelaborate}, | |
25389 | the use of | |
25390 | @code{Elaborate_Body} does not guarantee that the program is | |
25391 | free of elaboration problems, because it may not be possible | |
25392 | to satisfy the requested elaboration order. | |
25393 | Let's go back to the example with @code{Unit_1} and @code{Unit_2}. | |
25394 | If a programmer | |
25395 | marks @code{Unit_1} as @code{Elaborate_Body}, | |
25396 | and not @code{Unit_2,} then the order of | |
25397 | elaboration will be: | |
88e1739c FW |
25398 | |
25399 | @smallexample | |
25400 | @group | |
7cd4527e AC |
25401 | Spec of Unit_2 |
25402 | Spec of Unit_1 | |
25403 | Body of Unit_1 | |
25404 | Body of Unit_2 | |
88e1739c FW |
25405 | @end group |
25406 | @end smallexample | |
25407 | ||
88e1739c | 25408 | @noindent |
7cd4527e AC |
25409 | Now that means that the call to @code{Func_1} in @code{Unit_2} |
25410 | need not be checked, | |
25411 | it must be safe. But the call to @code{Func_2} in | |
25412 | @code{Unit_1} may still fail if | |
25413 | @code{Expression_1} is equal to 1, | |
25414 | and the programmer must still take | |
25415 | responsibility for this not being the case. | |
88e1739c | 25416 | |
7cd4527e AC |
25417 | If all units carry a pragma @code{Elaborate_Body}, then all problems are |
25418 | eliminated, except for calls entirely within a body, which are | |
25419 | in any case fully under programmer control. However, using the pragma | |
25420 | everywhere is not always possible. | |
25421 | In particular, for our @code{Unit_1}/@code{Unit_2} example, if | |
25422 | we marked both of them as having pragma @code{Elaborate_Body}, then | |
25423 | clearly there would be no possible elaboration order. | |
88e1739c | 25424 | |
7cd4527e | 25425 | The above pragmas allow a server to guarantee safe use by clients, and |
e08b38f5 VC |
25426 | clearly this is the preferable approach. Consequently a good rule |
25427 | is to mark units as @code{Pure} or @code{Preelaborate} if possible, | |
7cd4527e AC |
25428 | and if this is not possible, |
25429 | mark them as @code{Elaborate_Body} if possible. | |
25430 | As we have seen, there are situations where neither of these | |
25431 | three pragmas can be used. | |
25432 | So we also provide methods for clients to control the | |
25433 | order of elaboration of the servers on which they depend: | |
88e1739c | 25434 | |
7cd4527e AC |
25435 | @table @asis |
25436 | @item pragma Elaborate (unit) | |
25437 | @findex Elaborate | |
25438 | @cindex pragma Elaborate | |
25439 | This pragma is placed in the context clause, after a @code{with} clause, | |
25440 | and it requires that the body of the named unit be elaborated before | |
25441 | the unit in which the pragma occurs. The idea is to use this pragma | |
25442 | if the current unit calls at elaboration time, directly or indirectly, | |
25443 | some subprogram in the named unit. | |
88e1739c | 25444 | |
7cd4527e AC |
25445 | @item pragma Elaborate_All (unit) |
25446 | @findex Elaborate_All | |
25447 | @cindex pragma Elaborate_All | |
25448 | This is a stronger version of the Elaborate pragma. Consider the | |
25449 | following example: | |
88e1739c FW |
25450 | |
25451 | @smallexample | |
7cd4527e AC |
25452 | Unit A @code{with}'s unit B and calls B.Func in elab code |
25453 | Unit B @code{with}'s unit C, and B.Func calls C.Func | |
25454 | @end smallexample | |
88e1739c | 25455 | |
7cd4527e AC |
25456 | @noindent |
25457 | Now if we put a pragma @code{Elaborate (B)} | |
25458 | in unit @code{A}, this ensures that the | |
25459 | body of @code{B} is elaborated before the call, but not the | |
25460 | body of @code{C}, so | |
25461 | the call to @code{C.Func} could still cause @code{Program_Error} to | |
25462 | be raised. | |
88e1739c | 25463 | |
7cd4527e AC |
25464 | The effect of a pragma @code{Elaborate_All} is stronger, it requires |
25465 | not only that the body of the named unit be elaborated before the | |
25466 | unit doing the @code{with}, but also the bodies of all units that the | |
25467 | named unit uses, following @code{with} links transitively. For example, | |
25468 | if we put a pragma @code{Elaborate_All (B)} in unit @code{A}, | |
25469 | then it requires | |
25470 | not only that the body of @code{B} be elaborated before @code{A}, | |
25471 | but also the | |
25472 | body of @code{C}, because @code{B} @code{with}'s @code{C}. | |
25473 | @end table | |
88e1739c | 25474 | |
7cd4527e | 25475 | @noindent |
e08b38f5 | 25476 | We are now in a position to give a usage rule in Ada for avoiding |
7cd4527e AC |
25477 | elaboration problems, at least if dynamic dispatching and access to |
25478 | subprogram values are not used. We will handle these cases separately | |
25479 | later. | |
88e1739c | 25480 | |
7cd4527e AC |
25481 | The rule is simple. If a unit has elaboration code that can directly or |
25482 | indirectly make a call to a subprogram in a @code{with}'ed unit, or instantiate | |
32e209e4 | 25483 | a generic package in a @code{with}'ed unit, |
7cd4527e AC |
25484 | then if the @code{with}'ed unit does not have |
25485 | pragma @code{Pure} or @code{Preelaborate}, then the client should have | |
25486 | a pragma @code{Elaborate_All} | |
25487 | for the @code{with}'ed unit. By following this rule a client is | |
25488 | assured that calls can be made without risk of an exception. | |
32e209e4 CC |
25489 | |
25490 | For generic subprogram instantiations, the rule can be relaxed to | |
25491 | require only a pragma @code{Elaborate} since elaborating the body | |
25492 | of a subprogram cannot cause any transitive elaboration (we are | |
25493 | not calling the subprogram in this case, just elaborating its | |
25494 | declaration). | |
25495 | ||
7cd4527e AC |
25496 | If this rule is not followed, then a program may be in one of four |
25497 | states: | |
88e1739c | 25498 | |
7cd4527e AC |
25499 | @table @asis |
25500 | @item No order exists | |
25501 | No order of elaboration exists which follows the rules, taking into | |
25502 | account any @code{Elaborate}, @code{Elaborate_All}, | |
25503 | or @code{Elaborate_Body} pragmas. In | |
e08b38f5 | 25504 | this case, an Ada compiler must diagnose the situation at bind |
7cd4527e | 25505 | time, and refuse to build an executable program. |
88e1739c | 25506 | |
7cd4527e | 25507 | @item One or more orders exist, all incorrect |
c690a2ec | 25508 | One or more acceptable elaboration orders exist, and all of them |
7cd4527e AC |
25509 | generate an elaboration order problem. In this case, the binder |
25510 | can build an executable program, but @code{Program_Error} will be raised | |
25511 | when the program is run. | |
88e1739c | 25512 | |
7cd4527e AC |
25513 | @item Several orders exist, some right, some incorrect |
25514 | One or more acceptable elaboration orders exists, and some of them | |
25515 | work, and some do not. The programmer has not controlled | |
25516 | the order of elaboration, so the binder may or may not pick one of | |
25517 | the correct orders, and the program may or may not raise an | |
25518 | exception when it is run. This is the worst case, because it means | |
25519 | that the program may fail when moved to another compiler, or even | |
25520 | another version of the same compiler. | |
88e1739c | 25521 | |
7cd4527e AC |
25522 | @item One or more orders exists, all correct |
25523 | One ore more acceptable elaboration orders exist, and all of them | |
25524 | work. In this case the program runs successfully. This state of | |
25525 | affairs can be guaranteed by following the rule we gave above, but | |
25526 | may be true even if the rule is not followed. | |
25527 | @end table | |
88e1739c | 25528 | |
7cd4527e | 25529 | @noindent |
32e209e4 CC |
25530 | Note that one additional advantage of following our rules on the use |
25531 | of @code{Elaborate} and @code{Elaborate_All} | |
7cd4527e AC |
25532 | is that the program continues to stay in the ideal (all orders OK) state |
25533 | even if maintenance | |
32e209e4 | 25534 | changes some bodies of some units. Conversely, if a program that does |
7cd4527e AC |
25535 | not follow this rule happens to be safe at some point, this state of affairs |
25536 | may deteriorate silently as a result of maintenance changes. | |
88e1739c | 25537 | |
7cd4527e AC |
25538 | You may have noticed that the above discussion did not mention |
25539 | the use of @code{Elaborate_Body}. This was a deliberate omission. If you | |
25540 | @code{with} an @code{Elaborate_Body} unit, it still may be the case that | |
25541 | code in the body makes calls to some other unit, so it is still necessary | |
25542 | to use @code{Elaborate_All} on such units. | |
88e1739c | 25543 | |
7cd4527e AC |
25544 | @node Controlling Elaboration in GNAT - Internal Calls |
25545 | @section Controlling Elaboration in GNAT - Internal Calls | |
88e1739c | 25546 | |
7cd4527e | 25547 | @noindent |
8dd07840 | 25548 | In the case of internal calls, i.e., calls within a single package, the |
7cd4527e AC |
25549 | programmer has full control over the order of elaboration, and it is up |
25550 | to the programmer to elaborate declarations in an appropriate order. For | |
25551 | example writing: | |
88e1739c | 25552 | |
7cd4527e AC |
25553 | @smallexample @c ada |
25554 | @group | |
25555 | @cartouche | |
25556 | function One return Float; | |
88e1739c | 25557 | |
7cd4527e | 25558 | Q : Float := One; |
88e1739c | 25559 | |
7cd4527e AC |
25560 | function One return Float is |
25561 | begin | |
25562 | return 1.0; | |
25563 | end One; | |
25564 | @end cartouche | |
25565 | @end group | |
25566 | @end smallexample | |
88e1739c | 25567 | |
7cd4527e AC |
25568 | @noindent |
25569 | will obviously raise @code{Program_Error} at run time, because function | |
25570 | One will be called before its body is elaborated. In this case GNAT will | |
25571 | generate a warning that the call will raise @code{Program_Error}: | |
25572 | ||
25573 | @smallexample | |
25574 | @group | |
25575 | @cartouche | |
25576 | 1. procedure y is | |
25577 | 2. function One return Float; | |
25578 | 3. | |
25579 | 4. Q : Float := One; | |
25580 | | | |
25581 | >>> warning: cannot call "One" before body is elaborated | |
25582 | >>> warning: Program_Error will be raised at run time | |
88e1739c | 25583 | |
7cd4527e AC |
25584 | 5. |
25585 | 6. function One return Float is | |
25586 | 7. begin | |
25587 | 8. return 1.0; | |
25588 | 9. end One; | |
25589 | 10. | |
25590 | 11. begin | |
25591 | 12. null; | |
25592 | 13. end; | |
25593 | @end cartouche | |
25594 | @end group | |
25595 | @end smallexample | |
88e1739c | 25596 | |
7cd4527e AC |
25597 | @noindent |
25598 | Note that in this particular case, it is likely that the call is safe, because | |
25599 | the function @code{One} does not access any global variables. | |
e08b38f5 | 25600 | Nevertheless in Ada, we do not want the validity of the check to depend on |
7cd4527e AC |
25601 | the contents of the body (think about the separate compilation case), so this |
25602 | is still wrong, as we discussed in the previous sections. | |
88e1739c | 25603 | |
7cd4527e | 25604 | The error is easily corrected by rearranging the declarations so that the |
e08b38f5 VC |
25605 | body of @code{One} appears before the declaration containing the call |
25606 | (note that in Ada 95 and Ada 2005, | |
7cd4527e AC |
25607 | declarations can appear in any order, so there is no restriction that |
25608 | would prevent this reordering, and if we write: | |
88e1739c | 25609 | |
7cd4527e AC |
25610 | @smallexample @c ada |
25611 | @group | |
25612 | @cartouche | |
25613 | function One return Float; | |
88e1739c | 25614 | |
7cd4527e AC |
25615 | function One return Float is |
25616 | begin | |
25617 | return 1.0; | |
25618 | end One; | |
88e1739c | 25619 | |
7cd4527e AC |
25620 | Q : Float := One; |
25621 | @end cartouche | |
25622 | @end group | |
25623 | @end smallexample | |
88e1739c | 25624 | |
7cd4527e AC |
25625 | @noindent |
25626 | then all is well, no warning is generated, and no | |
25627 | @code{Program_Error} exception | |
25628 | will be raised. | |
25629 | Things are more complicated when a chain of subprograms is executed: | |
88e1739c | 25630 | |
7cd4527e AC |
25631 | @smallexample @c ada |
25632 | @group | |
25633 | @cartouche | |
25634 | function A return Integer; | |
25635 | function B return Integer; | |
25636 | function C return Integer; | |
88e1739c | 25637 | |
7cd4527e AC |
25638 | function B return Integer is begin return A; end; |
25639 | function C return Integer is begin return B; end; | |
88e1739c | 25640 | |
7cd4527e | 25641 | X : Integer := C; |
88e1739c | 25642 | |
7cd4527e AC |
25643 | function A return Integer is begin return 1; end; |
25644 | @end cartouche | |
25645 | @end group | |
25646 | @end smallexample | |
88e1739c | 25647 | |
7cd4527e AC |
25648 | @noindent |
25649 | Now the call to @code{C} | |
25650 | at elaboration time in the declaration of @code{X} is correct, because | |
25651 | the body of @code{C} is already elaborated, | |
25652 | and the call to @code{B} within the body of | |
25653 | @code{C} is correct, but the call | |
25654 | to @code{A} within the body of @code{B} is incorrect, because the body | |
25655 | of @code{A} has not been elaborated, so @code{Program_Error} | |
25656 | will be raised on the call to @code{A}. | |
25657 | In this case GNAT will generate a | |
25658 | warning that @code{Program_Error} may be | |
25659 | raised at the point of the call. Let's look at the warning: | |
88e1739c | 25660 | |
7cd4527e AC |
25661 | @smallexample |
25662 | @group | |
25663 | @cartouche | |
25664 | 1. procedure x is | |
25665 | 2. function A return Integer; | |
25666 | 3. function B return Integer; | |
25667 | 4. function C return Integer; | |
25668 | 5. | |
25669 | 6. function B return Integer is begin return A; end; | |
25670 | | | |
25671 | >>> warning: call to "A" before body is elaborated may | |
25672 | raise Program_Error | |
25673 | >>> warning: "B" called at line 7 | |
25674 | >>> warning: "C" called at line 9 | |
88e1739c | 25675 | |
7cd4527e AC |
25676 | 7. function C return Integer is begin return B; end; |
25677 | 8. | |
25678 | 9. X : Integer := C; | |
25679 | 10. | |
25680 | 11. function A return Integer is begin return 1; end; | |
25681 | 12. | |
25682 | 13. begin | |
25683 | 14. null; | |
25684 | 15. end; | |
25685 | @end cartouche | |
25686 | @end group | |
25687 | @end smallexample | |
88e1739c | 25688 | |
7cd4527e AC |
25689 | @noindent |
25690 | Note that the message here says ``may raise'', instead of the direct case, | |
25691 | where the message says ``will be raised''. That's because whether | |
25692 | @code{A} is | |
25693 | actually called depends in general on run-time flow of control. | |
25694 | For example, if the body of @code{B} said | |
88e1739c | 25695 | |
7cd4527e AC |
25696 | @smallexample @c ada |
25697 | @group | |
25698 | @cartouche | |
25699 | function B return Integer is | |
25700 | begin | |
25701 | if some-condition-depending-on-input-data then | |
25702 | return A; | |
25703 | else | |
25704 | return 1; | |
88e1739c | 25705 | end if; |
7cd4527e AC |
25706 | end B; |
25707 | @end cartouche | |
25708 | @end group | |
25709 | @end smallexample | |
88e1739c | 25710 | |
7cd4527e AC |
25711 | @noindent |
25712 | then we could not know until run time whether the incorrect call to A would | |
25713 | actually occur, so @code{Program_Error} might | |
25714 | or might not be raised. It is possible for a compiler to | |
25715 | do a better job of analyzing bodies, to | |
25716 | determine whether or not @code{Program_Error} | |
25717 | might be raised, but it certainly | |
25718 | couldn't do a perfect job (that would require solving the halting problem | |
25719 | and is provably impossible), and because this is a warning anyway, it does | |
25720 | not seem worth the effort to do the analysis. Cases in which it | |
25721 | would be relevant are rare. | |
88e1739c | 25722 | |
7cd4527e AC |
25723 | In practice, warnings of either of the forms given |
25724 | above will usually correspond to | |
25725 | real errors, and should be examined carefully and eliminated. | |
25726 | In the rare case where a warning is bogus, it can be suppressed by any of | |
25727 | the following methods: | |
88e1739c | 25728 | |
7cd4527e AC |
25729 | @itemize @bullet |
25730 | @item | |
25731 | Compile with the @option{-gnatws} switch set | |
88e1739c | 25732 | |
7cd4527e AC |
25733 | @item |
25734 | Suppress @code{Elaboration_Check} for the called subprogram | |
88e1739c | 25735 | |
7cd4527e AC |
25736 | @item |
25737 | Use pragma @code{Warnings_Off} to turn warnings off for the call | |
25738 | @end itemize | |
88e1739c | 25739 | |
7cd4527e AC |
25740 | @noindent |
25741 | For the internal elaboration check case, | |
25742 | GNAT by default generates the | |
25743 | necessary run-time checks to ensure | |
25744 | that @code{Program_Error} is raised if any | |
25745 | call fails an elaboration check. Of course this can only happen if a | |
25746 | warning has been issued as described above. The use of pragma | |
25747 | @code{Suppress (Elaboration_Check)} may (but is not guaranteed to) suppress | |
25748 | some of these checks, meaning that it may be possible (but is not | |
25749 | guaranteed) for a program to be able to call a subprogram whose body | |
25750 | is not yet elaborated, without raising a @code{Program_Error} exception. | |
88e1739c | 25751 | |
7cd4527e AC |
25752 | @node Controlling Elaboration in GNAT - External Calls |
25753 | @section Controlling Elaboration in GNAT - External Calls | |
88e1739c | 25754 | |
7cd4527e AC |
25755 | @noindent |
25756 | The previous section discussed the case in which the execution of a | |
25757 | particular thread of elaboration code occurred entirely within a | |
25758 | single unit. This is the easy case to handle, because a programmer | |
25759 | has direct and total control over the order of elaboration, and | |
25760 | furthermore, checks need only be generated in cases which are rare | |
25761 | and which the compiler can easily detect. | |
25762 | The situation is more complex when separate compilation is taken into account. | |
25763 | Consider the following: | |
88e1739c | 25764 | |
7cd4527e AC |
25765 | @smallexample @c ada |
25766 | @cartouche | |
25767 | @group | |
25768 | package Math is | |
25769 | function Sqrt (Arg : Float) return Float; | |
25770 | end Math; | |
88e1739c | 25771 | |
7cd4527e AC |
25772 | package body Math is |
25773 | function Sqrt (Arg : Float) return Float is | |
25774 | begin | |
d488f6ea | 25775 | @dots{} |
7cd4527e AC |
25776 | end Sqrt; |
25777 | end Math; | |
25778 | @end group | |
25779 | @group | |
25780 | with Math; | |
25781 | package Stuff is | |
25782 | X : Float := Math.Sqrt (0.5); | |
25783 | end Stuff; | |
88e1739c | 25784 | |
7cd4527e AC |
25785 | with Stuff; |
25786 | procedure Main is | |
25787 | begin | |
d488f6ea | 25788 | @dots{} |
7cd4527e AC |
25789 | end Main; |
25790 | @end group | |
25791 | @end cartouche | |
25792 | @end smallexample | |
88e1739c | 25793 | |
7cd4527e AC |
25794 | @noindent |
25795 | where @code{Main} is the main program. When this program is executed, the | |
25796 | elaboration code must first be executed, and one of the jobs of the | |
25797 | binder is to determine the order in which the units of a program are | |
25798 | to be elaborated. In this case we have four units: the spec and body | |
25799 | of @code{Math}, | |
25800 | the spec of @code{Stuff} and the body of @code{Main}). | |
25801 | In what order should the four separate sections of elaboration code | |
25802 | be executed? | |
88e1739c | 25803 | |
7cd4527e AC |
25804 | There are some restrictions in the order of elaboration that the binder |
25805 | can choose. In particular, if unit U has a @code{with} | |
25806 | for a package @code{X}, then you | |
25807 | are assured that the spec of @code{X} | |
25808 | is elaborated before U , but you are | |
25809 | not assured that the body of @code{X} | |
25810 | is elaborated before U. | |
25811 | This means that in the above case, the binder is allowed to choose the | |
25812 | order: | |
88e1739c | 25813 | |
7cd4527e AC |
25814 | @smallexample |
25815 | spec of Math | |
25816 | spec of Stuff | |
25817 | body of Math | |
25818 | body of Main | |
25819 | @end smallexample | |
88e1739c | 25820 | |
7cd4527e AC |
25821 | @noindent |
25822 | but that's not good, because now the call to @code{Math.Sqrt} | |
25823 | that happens during | |
25824 | the elaboration of the @code{Stuff} | |
25825 | spec happens before the body of @code{Math.Sqrt} is | |
25826 | elaborated, and hence causes @code{Program_Error} exception to be raised. | |
25827 | At first glance, one might say that the binder is misbehaving, because | |
25828 | obviously you want to elaborate the body of something you @code{with} | |
25829 | first, but | |
25830 | that is not a general rule that can be followed in all cases. Consider | |
88e1739c | 25831 | |
7cd4527e AC |
25832 | @smallexample @c ada |
25833 | @group | |
25834 | @cartouche | |
d488f6ea | 25835 | package X is @dots{} |
88e1739c | 25836 | |
d488f6ea | 25837 | package Y is @dots{} |
88e1739c | 25838 | |
7cd4527e | 25839 | with X; |
d488f6ea | 25840 | package body Y is @dots{} |
88e1739c | 25841 | |
7cd4527e | 25842 | with Y; |
d488f6ea | 25843 | package body X is @dots{} |
7cd4527e AC |
25844 | @end cartouche |
25845 | @end group | |
25846 | @end smallexample | |
88e1739c | 25847 | |
7cd4527e AC |
25848 | @noindent |
25849 | This is a common arrangement, and, apart from the order of elaboration | |
25850 | problems that might arise in connection with elaboration code, this works fine. | |
25851 | A rule that says that you must first elaborate the body of anything you | |
25852 | @code{with} cannot work in this case: | |
25853 | the body of @code{X} @code{with}'s @code{Y}, | |
25854 | which means you would have to | |
25855 | elaborate the body of @code{Y} first, but that @code{with}'s @code{X}, | |
25856 | which means | |
d488f6ea | 25857 | you have to elaborate the body of @code{X} first, but @dots{} and we have a |
7cd4527e | 25858 | loop that cannot be broken. |
88e1739c | 25859 | |
7cd4527e AC |
25860 | It is true that the binder can in many cases guess an order of elaboration |
25861 | that is unlikely to cause a @code{Program_Error} | |
25862 | exception to be raised, and it tries to do so (in the | |
25863 | above example of @code{Math/Stuff/Spec}, the GNAT binder will | |
25864 | by default | |
25865 | elaborate the body of @code{Math} right after its spec, so all will be well). | |
88e1739c | 25866 | |
7cd4527e AC |
25867 | However, a program that blindly relies on the binder to be helpful can |
25868 | get into trouble, as we discussed in the previous sections, so | |
25869 | GNAT | |
25870 | provides a number of facilities for assisting the programmer in | |
25871 | developing programs that are robust with respect to elaboration order. | |
88e1739c | 25872 | |
7cd4527e AC |
25873 | @node Default Behavior in GNAT - Ensuring Safety |
25874 | @section Default Behavior in GNAT - Ensuring Safety | |
88e1739c | 25875 | |
7cd4527e AC |
25876 | @noindent |
25877 | The default behavior in GNAT ensures elaboration safety. In its | |
25878 | default mode GNAT implements the | |
25879 | rule we previously described as the right approach. Let's restate it: | |
88e1739c | 25880 | |
7cd4527e AC |
25881 | @itemize |
25882 | @item | |
25883 | @emph{If a unit has elaboration code that can directly or indirectly make a | |
32e209e4 CC |
25884 | call to a subprogram in a @code{with}'ed unit, or instantiate a generic |
25885 | package in a @code{with}'ed unit, then if the @code{with}'ed unit | |
7cd4527e AC |
25886 | does not have pragma @code{Pure} or |
25887 | @code{Preelaborate}, then the client should have an | |
32e209e4 CC |
25888 | @code{Elaborate_All} pragma for the @code{with}'ed unit.} |
25889 | ||
25890 | @emph{In the case of instantiating a generic subprogram, it is always | |
25891 | sufficient to have only an @code{Elaborate} pragma for the | |
25892 | @code{with}'ed unit.} | |
7cd4527e | 25893 | @end itemize |
88e1739c | 25894 | |
7cd4527e AC |
25895 | @noindent |
25896 | By following this rule a client is assured that calls and instantiations | |
25897 | can be made without risk of an exception. | |
88e1739c | 25898 | |
7cd4527e | 25899 | In this mode GNAT traces all calls that are potentially made from |
32e209e4 CC |
25900 | elaboration code, and puts in any missing implicit @code{Elaborate} |
25901 | and @code{Elaborate_All} pragmas. | |
7cd4527e AC |
25902 | The advantage of this approach is that no elaboration problems |
25903 | are possible if the binder can find an elaboration order that is | |
32e209e4 CC |
25904 | consistent with these implicit @code{Elaborate} and |
25905 | @code{Elaborate_All} pragmas. The | |
7cd4527e | 25906 | disadvantage of this approach is that no such order may exist. |
88e1739c | 25907 | |
32e209e4 CC |
25908 | If the binder does not generate any diagnostics, then it means that it has |
25909 | found an elaboration order that is guaranteed to be safe. However, the binder | |
25910 | may still be relying on implicitly generated @code{Elaborate} and | |
25911 | @code{Elaborate_All} pragmas so portability to other compilers than GNAT is not | |
25912 | guaranteed. | |
88e1739c | 25913 | |
7cd4527e AC |
25914 | If it is important to guarantee portability, then the compilations should |
25915 | use the | |
25916 | @option{-gnatwl} | |
25917 | (warn on elaboration problems) switch. This will cause warning messages | |
32e209e4 CC |
25918 | to be generated indicating the missing @code{Elaborate} and |
25919 | @code{Elaborate_All} pragmas. | |
7cd4527e | 25920 | Consider the following source program: |
88e1739c | 25921 | |
7cd4527e AC |
25922 | @smallexample @c ada |
25923 | @group | |
25924 | @cartouche | |
25925 | with k; | |
25926 | package j is | |
25927 | m : integer := k.r; | |
25928 | end; | |
25929 | @end cartouche | |
25930 | @end group | |
25931 | @end smallexample | |
88e1739c | 25932 | |
7cd4527e AC |
25933 | @noindent |
25934 | where it is clear that there | |
25935 | should be a pragma @code{Elaborate_All} | |
25936 | for unit @code{k}. An implicit pragma will be generated, and it is | |
25937 | likely that the binder will be able to honor it. However, if you want | |
25938 | to port this program to some other Ada compiler than GNAT. | |
25939 | it is safer to include the pragma explicitly in the source. If this | |
25940 | unit is compiled with the | |
25941 | @option{-gnatwl} | |
25942 | switch, then the compiler outputs a warning: | |
88e1739c | 25943 | |
7cd4527e AC |
25944 | @smallexample |
25945 | @group | |
25946 | @cartouche | |
25947 | 1. with k; | |
25948 | 2. package j is | |
25949 | 3. m : integer := k.r; | |
25950 | | | |
25951 | >>> warning: call to "r" may raise Program_Error | |
25952 | >>> warning: missing pragma Elaborate_All for "k" | |
88e1739c | 25953 | |
7cd4527e AC |
25954 | 4. end; |
25955 | @end cartouche | |
25956 | @end group | |
25957 | @end smallexample | |
88e1739c | 25958 | |
7cd4527e AC |
25959 | @noindent |
25960 | and these warnings can be used as a guide for supplying manually | |
25961 | the missing pragmas. It is usually a bad idea to use this warning | |
25962 | option during development. That's because it will warn you when | |
25963 | you need to put in a pragma, but cannot warn you when it is time | |
32e209e4 | 25964 | to take it out. So the use of pragma @code{Elaborate_All} may lead to |
7cd4527e | 25965 | unnecessary dependencies and even false circularities. |
88e1739c | 25966 | |
7cd4527e AC |
25967 | This default mode is more restrictive than the Ada Reference |
25968 | Manual, and it is possible to construct programs which will compile | |
25969 | using the dynamic model described there, but will run into a | |
25970 | circularity using the safer static model we have described. | |
88e1739c | 25971 | |
7cd4527e AC |
25972 | Of course any Ada compiler must be able to operate in a mode |
25973 | consistent with the requirements of the Ada Reference Manual, | |
25974 | and in particular must have the capability of implementing the | |
25975 | standard dynamic model of elaboration with run-time checks. | |
88e1739c | 25976 | |
7cd4527e | 25977 | In GNAT, this standard mode can be achieved either by the use of |
984a64bc AC |
25978 | the @option{-gnatE} switch on the compiler (@command{gcc} or |
25979 | @command{gnatmake}) command, or by the use of the configuration pragma: | |
88e1739c | 25980 | |
7cd4527e | 25981 | @smallexample @c ada |
4cd029c7 | 25982 | pragma Elaboration_Checks (DYNAMIC); |
7cd4527e | 25983 | @end smallexample |
88e1739c | 25984 | |
7cd4527e AC |
25985 | @noindent |
25986 | Either approach will cause the unit affected to be compiled using the | |
25987 | standard dynamic run-time elaboration checks described in the Ada | |
25988 | Reference Manual. The static model is generally preferable, since it | |
25989 | is clearly safer to rely on compile and link time checks rather than | |
25990 | run-time checks. However, in the case of legacy code, it may be | |
25991 | difficult to meet the requirements of the static model. This | |
25992 | issue is further discussed in | |
25993 | @ref{What to Do If the Default Elaboration Behavior Fails}. | |
88e1739c | 25994 | |
7cd4527e AC |
25995 | Note that the static model provides a strict subset of the allowed |
25996 | behavior and programs of the Ada Reference Manual, so if you do | |
25997 | adhere to the static model and no circularities exist, | |
25998 | then you are assured that your program will | |
25999 | work using the dynamic model, providing that you remove any | |
26000 | pragma Elaborate statements from the source. | |
26001 | ||
26002 | @node Treatment of Pragma Elaborate | |
26003 | @section Treatment of Pragma Elaborate | |
26004 | @cindex Pragma Elaborate | |
26005 | ||
26006 | @noindent | |
26007 | The use of @code{pragma Elaborate} | |
e08b38f5 VC |
26008 | should generally be avoided in Ada 95 and Ada 2005 programs, |
26009 | since there is no guarantee that transitive calls | |
7cd4527e AC |
26010 | will be properly handled. Indeed at one point, this pragma was placed |
26011 | in Annex J (Obsolescent Features), on the grounds that it is never useful. | |
26012 | ||
26013 | Now that's a bit restrictive. In practice, the case in which | |
26014 | @code{pragma Elaborate} is useful is when the caller knows that there | |
26015 | are no transitive calls, or that the called unit contains all necessary | |
26016 | transitive @code{pragma Elaborate} statements, and legacy code often | |
26017 | contains such uses. | |
26018 | ||
26019 | Strictly speaking the static mode in GNAT should ignore such pragmas, | |
26020 | since there is no assurance at compile time that the necessary safety | |
26021 | conditions are met. In practice, this would cause GNAT to be incompatible | |
26022 | with correctly written Ada 83 code that had all necessary | |
26023 | @code{pragma Elaborate} statements in place. Consequently, we made the | |
26024 | decision that GNAT in its default mode will believe that if it encounters | |
26025 | a @code{pragma Elaborate} then the programmer knows what they are doing, | |
26026 | and it will trust that no elaboration errors can occur. | |
26027 | ||
26028 | The result of this decision is two-fold. First to be safe using the | |
26029 | static mode, you should remove all @code{pragma Elaborate} statements. | |
26030 | Second, when fixing circularities in existing code, you can selectively | |
26031 | use @code{pragma Elaborate} statements to convince the static mode of | |
26032 | GNAT that it need not generate an implicit @code{pragma Elaborate_All} | |
26033 | statement. | |
26034 | ||
26035 | When using the static mode with @option{-gnatwl}, any use of | |
26036 | @code{pragma Elaborate} will generate a warning about possible | |
26037 | problems. | |
88e1739c | 26038 | |
7cd4527e AC |
26039 | @node Elaboration Issues for Library Tasks |
26040 | @section Elaboration Issues for Library Tasks | |
26041 | @cindex Library tasks, elaboration issues | |
26042 | @cindex Elaboration of library tasks | |
88e1739c | 26043 | |
7cd4527e AC |
26044 | @noindent |
26045 | In this section we examine special elaboration issues that arise for | |
26046 | programs that declare library level tasks. | |
88e1739c | 26047 | |
7cd4527e AC |
26048 | Generally the model of execution of an Ada program is that all units are |
26049 | elaborated, and then execution of the program starts. However, the | |
26050 | declaration of library tasks definitely does not fit this model. The | |
26051 | reason for this is that library tasks start as soon as they are declared | |
26052 | (more precisely, as soon as the statement part of the enclosing package | |
26053 | body is reached), that is to say before elaboration | |
26054 | of the program is complete. This means that if such a task calls a | |
26055 | subprogram, or an entry in another task, the callee may or may not be | |
26056 | elaborated yet, and in the standard | |
26057 | Reference Manual model of dynamic elaboration checks, you can even | |
26058 | get timing dependent Program_Error exceptions, since there can be | |
26059 | a race between the elaboration code and the task code. | |
88e1739c | 26060 | |
7cd4527e AC |
26061 | The static model of elaboration in GNAT seeks to avoid all such |
26062 | dynamic behavior, by being conservative, and the conservative | |
26063 | approach in this particular case is to assume that all the code | |
26064 | in a task body is potentially executed at elaboration time if | |
26065 | a task is declared at the library level. | |
88e1739c | 26066 | |
7cd4527e AC |
26067 | This can definitely result in unexpected circularities. Consider |
26068 | the following example | |
88e1739c | 26069 | |
7cd4527e AC |
26070 | @smallexample @c ada |
26071 | package Decls is | |
26072 | task Lib_Task is | |
26073 | entry Start; | |
26074 | end Lib_Task; | |
88e1739c | 26075 | |
7cd4527e | 26076 | type My_Int is new Integer; |
88e1739c | 26077 | |
7cd4527e AC |
26078 | function Ident (M : My_Int) return My_Int; |
26079 | end Decls; | |
88e1739c | 26080 | |
7cd4527e AC |
26081 | with Utils; |
26082 | package body Decls is | |
26083 | task body Lib_Task is | |
26084 | begin | |
26085 | accept Start; | |
26086 | Utils.Put_Val (2); | |
26087 | end Lib_Task; | |
88e1739c | 26088 | |
7cd4527e AC |
26089 | function Ident (M : My_Int) return My_Int is |
26090 | begin | |
26091 | return M; | |
26092 | end Ident; | |
26093 | end Decls; | |
88e1739c | 26094 | |
7cd4527e AC |
26095 | with Decls; |
26096 | package Utils is | |
26097 | procedure Put_Val (Arg : Decls.My_Int); | |
26098 | end Utils; | |
88e1739c | 26099 | |
7cd4527e AC |
26100 | with Text_IO; |
26101 | package body Utils is | |
26102 | procedure Put_Val (Arg : Decls.My_Int) is | |
26103 | begin | |
26104 | Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); | |
26105 | end Put_Val; | |
26106 | end Utils; | |
88e1739c | 26107 | |
7cd4527e AC |
26108 | with Decls; |
26109 | procedure Main is | |
26110 | begin | |
26111 | Decls.Lib_Task.Start; | |
26112 | end; | |
26113 | @end smallexample | |
88e1739c | 26114 | |
7cd4527e AC |
26115 | @noindent |
26116 | If the above example is compiled in the default static elaboration | |
26117 | mode, then a circularity occurs. The circularity comes from the call | |
26118 | @code{Utils.Put_Val} in the task body of @code{Decls.Lib_Task}. Since | |
26119 | this call occurs in elaboration code, we need an implicit pragma | |
26120 | @code{Elaborate_All} for @code{Utils}. This means that not only must | |
26121 | the spec and body of @code{Utils} be elaborated before the body | |
26122 | of @code{Decls}, but also the spec and body of any unit that is | |
26123 | @code{with'ed} by the body of @code{Utils} must also be elaborated before | |
26124 | the body of @code{Decls}. This is the transitive implication of | |
26125 | pragma @code{Elaborate_All} and it makes sense, because in general | |
26126 | the body of @code{Put_Val} might have a call to something in a | |
26127 | @code{with'ed} unit. | |
88e1739c | 26128 | |
7cd4527e AC |
26129 | In this case, the body of Utils (actually its spec) @code{with's} |
26130 | @code{Decls}. Unfortunately this means that the body of @code{Decls} | |
26131 | must be elaborated before itself, in case there is a call from the | |
26132 | body of @code{Utils}. | |
88e1739c | 26133 | |
7cd4527e | 26134 | Here is the exact chain of events we are worrying about: |
88e1739c | 26135 | |
7cd4527e AC |
26136 | @enumerate |
26137 | @item | |
26138 | In the body of @code{Decls} a call is made from within the body of a library | |
26139 | task to a subprogram in the package @code{Utils}. Since this call may | |
26140 | occur at elaboration time (given that the task is activated at elaboration | |
8dd07840 | 26141 | time), we have to assume the worst, i.e., that the |
7cd4527e | 26142 | call does happen at elaboration time. |
88e1739c | 26143 | |
7cd4527e AC |
26144 | @item |
26145 | This means that the body and spec of @code{Util} must be elaborated before | |
26146 | the body of @code{Decls} so that this call does not cause an access before | |
26147 | elaboration. | |
88e1739c | 26148 | |
7cd4527e AC |
26149 | @item |
26150 | Within the body of @code{Util}, specifically within the body of | |
26151 | @code{Util.Put_Val} there may be calls to any unit @code{with}'ed | |
26152 | by this package. | |
88e1739c | 26153 | |
7cd4527e AC |
26154 | @item |
26155 | One such @code{with}'ed package is package @code{Decls}, so there | |
26156 | might be a call to a subprogram in @code{Decls} in @code{Put_Val}. | |
26157 | In fact there is such a call in this example, but we would have to | |
26158 | assume that there was such a call even if it were not there, since | |
26159 | we are not supposed to write the body of @code{Decls} knowing what | |
26160 | is in the body of @code{Utils}; certainly in the case of the | |
26161 | static elaboration model, the compiler does not know what is in | |
26162 | other bodies and must assume the worst. | |
88e1739c | 26163 | |
7cd4527e AC |
26164 | @item |
26165 | This means that the spec and body of @code{Decls} must also be | |
26166 | elaborated before we elaborate the unit containing the call, but | |
26167 | that unit is @code{Decls}! This means that the body of @code{Decls} | |
26168 | must be elaborated before itself, and that's a circularity. | |
26169 | @end enumerate | |
88e1739c | 26170 | |
7cd4527e | 26171 | @noindent |
32e209e4 | 26172 | Indeed, if you add an explicit pragma @code{Elaborate_All} for @code{Utils} in |
7cd4527e AC |
26173 | the body of @code{Decls} you will get a true Ada Reference Manual |
26174 | circularity that makes the program illegal. | |
88e1739c | 26175 | |
7cd4527e AC |
26176 | In practice, we have found that problems with the static model of |
26177 | elaboration in existing code often arise from library tasks, so | |
26178 | we must address this particular situation. | |
88e1739c | 26179 | |
7cd4527e AC |
26180 | Note that if we compile and run the program above, using the dynamic model of |
26181 | elaboration (that is to say use the @option{-gnatE} switch), | |
26182 | then it compiles, binds, | |
26183 | links, and runs, printing the expected result of 2. Therefore in some sense | |
26184 | the circularity here is only apparent, and we need to capture | |
26185 | the properties of this program that distinguish it from other library-level | |
26186 | tasks that have real elaboration problems. | |
88e1739c | 26187 | |
7cd4527e | 26188 | We have four possible answers to this question: |
88e1739c | 26189 | |
7cd4527e | 26190 | @itemize @bullet |
88e1739c | 26191 | |
7cd4527e AC |
26192 | @item |
26193 | Use the dynamic model of elaboration. | |
88e1739c | 26194 | |
7cd4527e AC |
26195 | If we use the @option{-gnatE} switch, then as noted above, the program works. |
26196 | Why is this? If we examine the task body, it is apparent that the task cannot | |
26197 | proceed past the | |
26198 | @code{accept} statement until after elaboration has been completed, because | |
26199 | the corresponding entry call comes from the main program, not earlier. | |
26200 | This is why the dynamic model works here. But that's really giving | |
26201 | up on a precise analysis, and we prefer to take this approach only if we cannot | |
26202 | solve the | |
26203 | problem in any other manner. So let us examine two ways to reorganize | |
26204 | the program to avoid the potential elaboration problem. | |
88e1739c | 26205 | |
7cd4527e AC |
26206 | @item |
26207 | Split library tasks into separate packages. | |
88e1739c | 26208 | |
7cd4527e AC |
26209 | Write separate packages, so that library tasks are isolated from |
26210 | other declarations as much as possible. Let us look at a variation on | |
26211 | the above program. | |
88e1739c | 26212 | |
7cd4527e AC |
26213 | @smallexample @c ada |
26214 | package Decls1 is | |
26215 | task Lib_Task is | |
26216 | entry Start; | |
26217 | end Lib_Task; | |
26218 | end Decls1; | |
88e1739c | 26219 | |
7cd4527e AC |
26220 | with Utils; |
26221 | package body Decls1 is | |
26222 | task body Lib_Task is | |
26223 | begin | |
26224 | accept Start; | |
26225 | Utils.Put_Val (2); | |
26226 | end Lib_Task; | |
26227 | end Decls1; | |
88e1739c | 26228 | |
7cd4527e AC |
26229 | package Decls2 is |
26230 | type My_Int is new Integer; | |
26231 | function Ident (M : My_Int) return My_Int; | |
26232 | end Decls2; | |
88e1739c | 26233 | |
7cd4527e AC |
26234 | with Utils; |
26235 | package body Decls2 is | |
26236 | function Ident (M : My_Int) return My_Int is | |
26237 | begin | |
26238 | return M; | |
26239 | end Ident; | |
26240 | end Decls2; | |
88e1739c | 26241 | |
7cd4527e AC |
26242 | with Decls2; |
26243 | package Utils is | |
26244 | procedure Put_Val (Arg : Decls2.My_Int); | |
26245 | end Utils; | |
88e1739c | 26246 | |
7cd4527e AC |
26247 | with Text_IO; |
26248 | package body Utils is | |
26249 | procedure Put_Val (Arg : Decls2.My_Int) is | |
26250 | begin | |
26251 | Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg))); | |
26252 | end Put_Val; | |
26253 | end Utils; | |
88e1739c | 26254 | |
7cd4527e AC |
26255 | with Decls1; |
26256 | procedure Main is | |
26257 | begin | |
26258 | Decls1.Lib_Task.Start; | |
26259 | end; | |
26260 | @end smallexample | |
88e1739c | 26261 | |
7cd4527e AC |
26262 | @noindent |
26263 | All we have done is to split @code{Decls} into two packages, one | |
26264 | containing the library task, and one containing everything else. Now | |
26265 | there is no cycle, and the program compiles, binds, links and executes | |
26266 | using the default static model of elaboration. | |
88e1739c | 26267 | |
7cd4527e AC |
26268 | @item |
26269 | Declare separate task types. | |
88e1739c | 26270 | |
7cd4527e AC |
26271 | A significant part of the problem arises because of the use of the |
26272 | single task declaration form. This means that the elaboration of | |
8dd07840 | 26273 | the task type, and the elaboration of the task itself (i.e.@: the |
7cd4527e | 26274 | creation of the task) happen at the same time. A good rule |
e08b38f5 | 26275 | of style in Ada is to always create explicit task types. By |
7cd4527e AC |
26276 | following the additional step of placing task objects in separate |
26277 | packages from the task type declaration, many elaboration problems | |
26278 | are avoided. Here is another modified example of the example program: | |
88e1739c | 26279 | |
7cd4527e AC |
26280 | @smallexample @c ada |
26281 | package Decls is | |
26282 | task type Lib_Task_Type is | |
26283 | entry Start; | |
26284 | end Lib_Task_Type; | |
88e1739c | 26285 | |
7cd4527e | 26286 | type My_Int is new Integer; |
88e1739c | 26287 | |
7cd4527e AC |
26288 | function Ident (M : My_Int) return My_Int; |
26289 | end Decls; | |
88e1739c | 26290 | |
7cd4527e AC |
26291 | with Utils; |
26292 | package body Decls is | |
26293 | task body Lib_Task_Type is | |
26294 | begin | |
26295 | accept Start; | |
26296 | Utils.Put_Val (2); | |
26297 | end Lib_Task_Type; | |
88e1739c | 26298 | |
7cd4527e AC |
26299 | function Ident (M : My_Int) return My_Int is |
26300 | begin | |
26301 | return M; | |
26302 | end Ident; | |
26303 | end Decls; | |
88e1739c | 26304 | |
7cd4527e AC |
26305 | with Decls; |
26306 | package Utils is | |
26307 | procedure Put_Val (Arg : Decls.My_Int); | |
26308 | end Utils; | |
88e1739c | 26309 | |
7cd4527e AC |
26310 | with Text_IO; |
26311 | package body Utils is | |
26312 | procedure Put_Val (Arg : Decls.My_Int) is | |
26313 | begin | |
26314 | Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); | |
26315 | end Put_Val; | |
26316 | end Utils; | |
88e1739c | 26317 | |
7cd4527e AC |
26318 | with Decls; |
26319 | package Declst is | |
26320 | Lib_Task : Decls.Lib_Task_Type; | |
26321 | end Declst; | |
88e1739c | 26322 | |
7cd4527e AC |
26323 | with Declst; |
26324 | procedure Main is | |
26325 | begin | |
26326 | Declst.Lib_Task.Start; | |
26327 | end; | |
26328 | @end smallexample | |
88e1739c | 26329 | |
7cd4527e AC |
26330 | @noindent |
26331 | What we have done here is to replace the @code{task} declaration in | |
26332 | package @code{Decls} with a @code{task type} declaration. Then we | |
26333 | introduce a separate package @code{Declst} to contain the actual | |
26334 | task object. This separates the elaboration issues for | |
26335 | the @code{task type} | |
26336 | declaration, which causes no trouble, from the elaboration issues | |
26337 | of the task object, which is also unproblematic, since it is now independent | |
26338 | of the elaboration of @code{Utils}. | |
26339 | This separation of concerns also corresponds to | |
26340 | a generally sound engineering principle of separating declarations | |
26341 | from instances. This version of the program also compiles, binds, links, | |
26342 | and executes, generating the expected output. | |
88e1739c | 26343 | |
7cd4527e AC |
26344 | @item |
26345 | Use No_Entry_Calls_In_Elaboration_Code restriction. | |
26346 | @cindex No_Entry_Calls_In_Elaboration_Code | |
26347 | ||
26348 | The previous two approaches described how a program can be restructured | |
26349 | to avoid the special problems caused by library task bodies. in practice, | |
26350 | however, such restructuring may be difficult to apply to existing legacy code, | |
26351 | so we must consider solutions that do not require massive rewriting. | |
88e1739c | 26352 | |
7cd4527e AC |
26353 | Let us consider more carefully why our original sample program works |
26354 | under the dynamic model of elaboration. The reason is that the code | |
26355 | in the task body blocks immediately on the @code{accept} | |
26356 | statement. Now of course there is nothing to prohibit elaboration | |
26357 | code from making entry calls (for example from another library level task), | |
26358 | so we cannot tell in isolation that | |
26359 | the task will not execute the accept statement during elaboration. | |
88e1739c | 26360 | |
7cd4527e AC |
26361 | However, in practice it is very unusual to see elaboration code |
26362 | make any entry calls, and the pattern of tasks starting | |
26363 | at elaboration time and then immediately blocking on @code{accept} or | |
26364 | @code{select} statements is very common. What this means is that | |
26365 | the compiler is being too pessimistic when it analyzes the | |
26366 | whole package body as though it might be executed at elaboration | |
26367 | time. | |
88e1739c | 26368 | |
7cd4527e AC |
26369 | If we know that the elaboration code contains no entry calls, (a very safe |
26370 | assumption most of the time, that could almost be made the default | |
26371 | behavior), then we can compile all units of the program under control | |
26372 | of the following configuration pragma: | |
88e1739c | 26373 | |
7cd4527e AC |
26374 | @smallexample |
26375 | pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); | |
26376 | @end smallexample | |
88e1739c | 26377 | |
7cd4527e AC |
26378 | @noindent |
26379 | This pragma can be placed in the @file{gnat.adc} file in the usual | |
26380 | manner. If we take our original unmodified program and compile it | |
26381 | in the presence of a @file{gnat.adc} containing the above pragma, | |
26382 | then once again, we can compile, bind, link, and execute, obtaining | |
26383 | the expected result. In the presence of this pragma, the compiler does | |
26384 | not trace calls in a task body, that appear after the first @code{accept} | |
26385 | or @code{select} statement, and therefore does not report a potential | |
26386 | circularity in the original program. | |
88e1739c | 26387 | |
7cd4527e AC |
26388 | The compiler will check to the extent it can that the above |
26389 | restriction is not violated, but it is not always possible to do a | |
26390 | complete check at compile time, so it is important to use this | |
26391 | pragma only if the stated restriction is in fact met, that is to say | |
26392 | no task receives an entry call before elaboration of all units is completed. | |
88e1739c | 26393 | |
7cd4527e | 26394 | @end itemize |
88e1739c | 26395 | |
7cd4527e AC |
26396 | @node Mixing Elaboration Models |
26397 | @section Mixing Elaboration Models | |
26398 | @noindent | |
26399 | So far, we have assumed that the entire program is either compiled | |
26400 | using the dynamic model or static model, ensuring consistency. It | |
26401 | is possible to mix the two models, but rules have to be followed | |
26402 | if this mixing is done to ensure that elaboration checks are not | |
26403 | omitted. | |
88e1739c | 26404 | |
7cd4527e AC |
26405 | The basic rule is that @emph{a unit compiled with the static model cannot |
26406 | be @code{with'ed} by a unit compiled with the dynamic model}. The | |
26407 | reason for this is that in the static model, a unit assumes that | |
26408 | its clients guarantee to use (the equivalent of) pragma | |
26409 | @code{Elaborate_All} so that no elaboration checks are required | |
26410 | in inner subprograms, and this assumption is violated if the | |
26411 | client is compiled with dynamic checks. | |
88e1739c | 26412 | |
7cd4527e AC |
26413 | The precise rule is as follows. A unit that is compiled with dynamic |
26414 | checks can only @code{with} a unit that meets at least one of the | |
26415 | following criteria: | |
88e1739c | 26416 | |
7cd4527e | 26417 | @itemize @bullet |
88e1739c | 26418 | |
7cd4527e AC |
26419 | @item |
26420 | The @code{with'ed} unit is itself compiled with dynamic elaboration | |
26421 | checks (that is with the @option{-gnatE} switch. | |
88e1739c | 26422 | |
7cd4527e AC |
26423 | @item |
26424 | The @code{with'ed} unit is an internal GNAT implementation unit from | |
26425 | the System, Interfaces, Ada, or GNAT hierarchies. | |
88e1739c | 26426 | |
7cd4527e AC |
26427 | @item |
26428 | The @code{with'ed} unit has pragma Preelaborate or pragma Pure. | |
88e1739c | 26429 | |
7cd4527e AC |
26430 | @item |
26431 | The @code{with'ing} unit (that is the client) has an explicit pragma | |
26432 | @code{Elaborate_All} for the @code{with'ed} unit. | |
88e1739c | 26433 | |
7cd4527e | 26434 | @end itemize |
88e1739c | 26435 | |
7cd4527e AC |
26436 | @noindent |
26437 | If this rule is violated, that is if a unit with dynamic elaboration | |
26438 | checks @code{with's} a unit that does not meet one of the above four | |
26439 | criteria, then the binder (@code{gnatbind}) will issue a warning | |
26440 | similar to that in the following example: | |
88e1739c | 26441 | |
7cd4527e AC |
26442 | @smallexample |
26443 | warning: "x.ads" has dynamic elaboration checks and with's | |
26444 | warning: "y.ads" which has static elaboration checks | |
26445 | @end smallexample | |
88e1739c | 26446 | |
7cd4527e AC |
26447 | @noindent |
26448 | These warnings indicate that the rule has been violated, and that as a result | |
26449 | elaboration checks may be missed in the resulting executable file. | |
26450 | This warning may be suppressed using the @option{-ws} binder switch | |
26451 | in the usual manner. | |
88e1739c | 26452 | |
7cd4527e AC |
26453 | One useful application of this mixing rule is in the case of a subsystem |
26454 | which does not itself @code{with} units from the remainder of the | |
26455 | application. In this case, the entire subsystem can be compiled with | |
26456 | dynamic checks to resolve a circularity in the subsystem, while | |
26457 | allowing the main application that uses this subsystem to be compiled | |
26458 | using the more reliable default static model. | |
88e1739c | 26459 | |
7cd4527e AC |
26460 | @node What to Do If the Default Elaboration Behavior Fails |
26461 | @section What to Do If the Default Elaboration Behavior Fails | |
88e1739c | 26462 | |
7cd4527e AC |
26463 | @noindent |
26464 | If the binder cannot find an acceptable order, it outputs detailed | |
26465 | diagnostics. For example: | |
26466 | @smallexample | |
26467 | @group | |
26468 | @iftex | |
26469 | @leftskip=0cm | |
26470 | @end iftex | |
26471 | error: elaboration circularity detected | |
26472 | info: "proc (body)" must be elaborated before "pack (body)" | |
26473 | info: reason: Elaborate_All probably needed in unit "pack (body)" | |
26474 | info: recompile "pack (body)" with -gnatwl | |
26475 | info: for full details | |
26476 | info: "proc (body)" | |
26477 | info: is needed by its spec: | |
26478 | info: "proc (spec)" | |
26479 | info: which is withed by: | |
26480 | info: "pack (body)" | |
26481 | info: "pack (body)" must be elaborated before "proc (body)" | |
26482 | info: reason: pragma Elaborate in unit "proc (body)" | |
26483 | @end group | |
88e1739c | 26484 | |
7cd4527e | 26485 | @end smallexample |
88e1739c | 26486 | |
7cd4527e AC |
26487 | @noindent |
26488 | In this case we have a cycle that the binder cannot break. On the one | |
26489 | hand, there is an explicit pragma Elaborate in @code{proc} for | |
26490 | @code{pack}. This means that the body of @code{pack} must be elaborated | |
26491 | before the body of @code{proc}. On the other hand, there is elaboration | |
26492 | code in @code{pack} that calls a subprogram in @code{proc}. This means | |
26493 | that for maximum safety, there should really be a pragma | |
26494 | Elaborate_All in @code{pack} for @code{proc} which would require that | |
26495 | the body of @code{proc} be elaborated before the body of | |
26496 | @code{pack}. Clearly both requirements cannot be satisfied. | |
26497 | Faced with a circularity of this kind, you have three different options. | |
88e1739c | 26498 | |
7cd4527e AC |
26499 | @table @asis |
26500 | @item Fix the program | |
26501 | The most desirable option from the point of view of long-term maintenance | |
26502 | is to rearrange the program so that the elaboration problems are avoided. | |
26503 | One useful technique is to place the elaboration code into separate | |
26504 | child packages. Another is to move some of the initialization code to | |
26505 | explicitly called subprograms, where the program controls the order | |
26506 | of initialization explicitly. Although this is the most desirable option, | |
26507 | it may be impractical and involve too much modification, especially in | |
26508 | the case of complex legacy code. | |
88e1739c | 26509 | |
7cd4527e AC |
26510 | @item Perform dynamic checks |
26511 | If the compilations are done using the | |
26512 | @option{-gnatE} | |
32e209e4 CC |
26513 | (dynamic elaboration check) switch, then GNAT behaves in a quite different |
26514 | manner. Dynamic checks are generated for all calls that could possibly result | |
26515 | in raising an exception. With this switch, the compiler does not generate | |
26516 | implicit @code{Elaborate} or @code{Elaborate_All} pragmas. The behavior then is | |
e08b38f5 VC |
26517 | exactly as specified in the @cite{Ada Reference Manual}. |
26518 | The binder will generate | |
32e209e4 CC |
26519 | an executable program that may or may not raise @code{Program_Error}, and then |
26520 | it is the programmer's job to ensure that it does not raise an exception. Note | |
26521 | that it is important to compile all units with the switch, it cannot be used | |
26522 | selectively. | |
88e1739c | 26523 | |
7cd4527e AC |
26524 | @item Suppress checks |
26525 | The drawback of dynamic checks is that they generate a | |
26526 | significant overhead at run time, both in space and time. If you | |
26527 | are absolutely sure that your program cannot raise any elaboration | |
26528 | exceptions, and you still want to use the dynamic elaboration model, | |
26529 | then you can use the configuration pragma | |
26530 | @code{Suppress (Elaboration_Check)} to suppress all such checks. For | |
26531 | example this pragma could be placed in the @file{gnat.adc} file. | |
88e1739c | 26532 | |
7cd4527e | 26533 | @item Suppress checks selectively |
32e209e4 CC |
26534 | When you know that certain calls or instantiations in elaboration code cannot |
26535 | possibly lead to an elaboration error, and the binder nevertheless complains | |
26536 | about implicit @code{Elaborate} and @code{Elaborate_All} pragmas that lead to | |
26537 | elaboration circularities, it is possible to remove those warnings locally and | |
26538 | obtain a program that will bind. Clearly this can be unsafe, and it is the | |
26539 | responsibility of the programmer to make sure that the resulting program has no | |
26540 | elaboration anomalies. The pragma @code{Suppress (Elaboration_Check)} can be | |
26541 | used with different granularity to suppress warnings and break elaboration | |
26542 | circularities: | |
88e1739c | 26543 | |
7cd4527e AC |
26544 | @itemize @bullet |
26545 | @item | |
26546 | Place the pragma that names the called subprogram in the declarative part | |
26547 | that contains the call. | |
88e1739c | 26548 | |
7cd4527e AC |
26549 | @item |
26550 | Place the pragma in the declarative part, without naming an entity. This | |
26551 | disables warnings on all calls in the corresponding declarative region. | |
88e1739c | 26552 | |
7cd4527e AC |
26553 | @item |
26554 | Place the pragma in the package spec that declares the called subprogram, | |
26555 | and name the subprogram. This disables warnings on all elaboration calls to | |
26556 | that subprogram. | |
88e1739c | 26557 | |
7cd4527e AC |
26558 | @item |
26559 | Place the pragma in the package spec that declares the called subprogram, | |
26560 | without naming any entity. This disables warnings on all elaboration calls to | |
26561 | all subprograms declared in this spec. | |
88e1739c | 26562 | |
7cd4527e AC |
26563 | @item Use Pragma Elaborate |
26564 | As previously described in section @xref{Treatment of Pragma Elaborate}, | |
26565 | GNAT in static mode assumes that a @code{pragma} Elaborate indicates correctly | |
26566 | that no elaboration checks are required on calls to the designated unit. | |
26567 | There may be cases in which the caller knows that no transitive calls | |
26568 | can occur, so that a @code{pragma Elaborate} will be sufficient in a | |
26569 | case where @code{pragma Elaborate_All} would cause a circularity. | |
26570 | @end itemize | |
88e1739c | 26571 | |
7cd4527e AC |
26572 | @noindent |
26573 | These five cases are listed in order of decreasing safety, and therefore | |
26574 | require increasing programmer care in their application. Consider the | |
26575 | following program: | |
88e1739c | 26576 | |
7cd4527e AC |
26577 | @smallexample @c adanocomment |
26578 | package Pack1 is | |
26579 | function F1 return Integer; | |
26580 | X1 : Integer; | |
26581 | end Pack1; | |
88e1739c | 26582 | |
7cd4527e AC |
26583 | package Pack2 is |
26584 | function F2 return Integer; | |
26585 | function Pure (x : integer) return integer; | |
26586 | -- pragma Suppress (Elaboration_Check, On => Pure); -- (3) | |
26587 | -- pragma Suppress (Elaboration_Check); -- (4) | |
26588 | end Pack2; | |
88e1739c | 26589 | |
7cd4527e AC |
26590 | with Pack2; |
26591 | package body Pack1 is | |
26592 | function F1 return Integer is | |
26593 | begin | |
26594 | return 100; | |
26595 | end F1; | |
26596 | Val : integer := Pack2.Pure (11); -- Elab. call (1) | |
26597 | begin | |
26598 | declare | |
26599 | -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1) | |
26600 | -- pragma Suppress(Elaboration_Check); -- (2) | |
26601 | begin | |
26602 | X1 := Pack2.F2 + 1; -- Elab. call (2) | |
26603 | end; | |
26604 | end Pack1; | |
88e1739c | 26605 | |
7cd4527e AC |
26606 | with Pack1; |
26607 | package body Pack2 is | |
26608 | function F2 return Integer is | |
26609 | begin | |
26610 | return Pack1.F1; | |
26611 | end F2; | |
26612 | function Pure (x : integer) return integer is | |
26613 | begin | |
26614 | return x ** 3 - 3 * x; | |
26615 | end; | |
26616 | end Pack2; | |
88e1739c | 26617 | |
7cd4527e AC |
26618 | with Pack1, Ada.Text_IO; |
26619 | procedure Proc3 is | |
26620 | begin | |
26621 | Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 | |
26622 | end Proc3; | |
26623 | @end smallexample | |
26624 | In the absence of any pragmas, an attempt to bind this program produces | |
26625 | the following diagnostics: | |
26626 | @smallexample | |
26627 | @group | |
26628 | @iftex | |
26629 | @leftskip=.5cm | |
26630 | @end iftex | |
26631 | error: elaboration circularity detected | |
26632 | info: "pack1 (body)" must be elaborated before "pack1 (body)" | |
26633 | info: reason: Elaborate_All probably needed in unit "pack1 (body)" | |
26634 | info: recompile "pack1 (body)" with -gnatwl for full details | |
26635 | info: "pack1 (body)" | |
26636 | info: must be elaborated along with its spec: | |
26637 | info: "pack1 (spec)" | |
26638 | info: which is withed by: | |
26639 | info: "pack2 (body)" | |
26640 | info: which must be elaborated along with its spec: | |
26641 | info: "pack2 (spec)" | |
26642 | info: which is withed by: | |
26643 | info: "pack1 (body)" | |
26644 | @end group | |
26645 | @end smallexample | |
26646 | The sources of the circularity are the two calls to @code{Pack2.Pure} and | |
26647 | @code{Pack2.F2} in the body of @code{Pack1}. We can see that the call to | |
26648 | F2 is safe, even though F2 calls F1, because the call appears after the | |
26649 | elaboration of the body of F1. Therefore the pragma (1) is safe, and will | |
26650 | remove the warning on the call. It is also possible to use pragma (2) | |
26651 | because there are no other potentially unsafe calls in the block. | |
88e1739c | 26652 | |
7cd4527e AC |
26653 | @noindent |
26654 | The call to @code{Pure} is safe because this function does not depend on the | |
26655 | state of @code{Pack2}. Therefore any call to this function is safe, and it | |
26656 | is correct to place pragma (3) in the corresponding package spec. | |
88e1739c | 26657 | |
7cd4527e AC |
26658 | @noindent |
26659 | Finally, we could place pragma (4) in the spec of @code{Pack2} to disable | |
26660 | warnings on all calls to functions declared therein. Note that this is not | |
26661 | necessarily safe, and requires more detailed examination of the subprogram | |
26662 | bodies involved. In particular, a call to @code{F2} requires that @code{F1} | |
26663 | be already elaborated. | |
26664 | @end table | |
88e1739c | 26665 | |
7cd4527e AC |
26666 | @noindent |
26667 | It is hard to generalize on which of these four approaches should be | |
26668 | taken. Obviously if it is possible to fix the program so that the default | |
26669 | treatment works, this is preferable, but this may not always be practical. | |
26670 | It is certainly simple enough to use | |
26671 | @option{-gnatE} | |
26672 | but the danger in this case is that, even if the GNAT binder | |
26673 | finds a correct elaboration order, it may not always do so, | |
26674 | and certainly a binder from another Ada compiler might not. A | |
26675 | combination of testing and analysis (for which the warnings generated | |
26676 | with the | |
26677 | @option{-gnatwl} | |
26678 | switch can be useful) must be used to ensure that the program is free | |
26679 | of errors. One switch that is useful in this testing is the | |
26680 | @option{^-p (pessimistic elaboration order)^/PESSIMISTIC_ELABORATION_ORDER^} | |
26681 | switch for | |
26682 | @code{gnatbind}. | |
c690a2ec RD |
26683 | Normally the binder tries to find an order that has the best chance |
26684 | of avoiding elaboration problems. However, if this switch is used, the binder | |
7cd4527e AC |
26685 | plays a devil's advocate role, and tries to choose the order that |
26686 | has the best chance of failing. If your program works even with this | |
26687 | switch, then it has a better chance of being error free, but this is still | |
26688 | not a guarantee. | |
88e1739c | 26689 | |
7cd4527e AC |
26690 | For an example of this approach in action, consider the C-tests (executable |
26691 | tests) from the ACVC suite. If these are compiled and run with the default | |
26692 | treatment, then all but one of them succeed without generating any error | |
26693 | diagnostics from the binder. However, there is one test that fails, and | |
26694 | this is not surprising, because the whole point of this test is to ensure | |
26695 | that the compiler can handle cases where it is impossible to determine | |
26696 | a correct order statically, and it checks that an exception is indeed | |
26697 | raised at run time. | |
88e1739c | 26698 | |
7cd4527e AC |
26699 | This one test must be compiled and run using the |
26700 | @option{-gnatE} | |
26701 | switch, and then it passes. Alternatively, the entire suite can | |
26702 | be run using this switch. It is never wrong to run with the dynamic | |
26703 | elaboration switch if your code is correct, and we assume that the | |
26704 | C-tests are indeed correct (it is less efficient, but efficiency is | |
26705 | not a factor in running the ACVC tests.) | |
88e1739c | 26706 | |
78c0f016 AC |
26707 | @node Elaboration for Dispatching Calls |
26708 | @section Elaboration for Dispatching Calls | |
26709 | @cindex Dispatching calls | |
88e1739c | 26710 | |
78c0f016 AC |
26711 | @noindent |
26712 | In rare cases, the static elaboration model fails to prevent | |
26713 | dispatching calls to not-yet-elaborated subprograms. In such cases, we | |
26714 | fall back to run-time checks; premature calls to any primitive | |
7cd4527e | 26715 | operation of a tagged type before the body of the operation has been |
78c0f016 AC |
26716 | elaborated will raise @code{Program_Error}. |
26717 | ||
26718 | Access-to-subprogram types, however, are handled conservatively, and | |
26719 | do not require run-time checks. This was not true in earlier versions | |
26720 | of the compiler; you can use the @option{-gnatd.U} debug switch to | |
26721 | revert to the old behavior if the new conservative behavior causes | |
26722 | elaboration cycles. | |
88e1739c | 26723 | |
7cd4527e AC |
26724 | @node Summary of Procedures for Elaboration Control |
26725 | @section Summary of Procedures for Elaboration Control | |
26726 | @cindex Elaboration control | |
88e1739c | 26727 | |
7cd4527e AC |
26728 | @noindent |
26729 | First, compile your program with the default options, using none of | |
26730 | the special elaboration control switches. If the binder successfully | |
26731 | binds your program, then you can be confident that, apart from issues | |
26732 | raised by the use of access-to-subprogram types and dynamic dispatching, | |
26733 | the program is free of elaboration errors. If it is important that the | |
26734 | program be portable, then use the | |
26735 | @option{-gnatwl} | |
32e209e4 CC |
26736 | switch to generate warnings about missing @code{Elaborate} or |
26737 | @code{Elaborate_All} pragmas, and supply the missing pragmas. | |
88e1739c | 26738 | |
7cd4527e AC |
26739 | If the program fails to bind using the default static elaboration |
26740 | handling, then you can fix the program to eliminate the binder | |
26741 | message, or recompile the entire program with the | |
26742 | @option{-gnatE} switch to generate dynamic elaboration checks, | |
26743 | and, if you are sure there really are no elaboration problems, | |
26744 | use a global pragma @code{Suppress (Elaboration_Check)}. | |
88e1739c | 26745 | |
7cd4527e AC |
26746 | @node Other Elaboration Order Considerations |
26747 | @section Other Elaboration Order Considerations | |
26748 | @noindent | |
26749 | This section has been entirely concerned with the issue of finding a valid | |
26750 | elaboration order, as defined by the Ada Reference Manual. In a case | |
26751 | where several elaboration orders are valid, the task is to find one | |
26752 | of the possible valid elaboration orders (and the static model in GNAT | |
26753 | will ensure that this is achieved). | |
88e1739c | 26754 | |
7cd4527e AC |
26755 | The purpose of the elaboration rules in the Ada Reference Manual is to |
26756 | make sure that no entity is accessed before it has been elaborated. For | |
26757 | a subprogram, this means that the spec and body must have been elaborated | |
26758 | before the subprogram is called. For an object, this means that the object | |
26759 | must have been elaborated before its value is read or written. A violation | |
26760 | of either of these two requirements is an access before elaboration order, | |
26761 | and this section has been all about avoiding such errors. | |
88e1739c | 26762 | |
7cd4527e AC |
26763 | In the case where more than one order of elaboration is possible, in the |
26764 | sense that access before elaboration errors are avoided, then any one of | |
26765 | the orders is ``correct'' in the sense that it meets the requirements of | |
26766 | the Ada Reference Manual, and no such error occurs. | |
88e1739c | 26767 | |
7cd4527e AC |
26768 | However, it may be the case for a given program, that there are |
26769 | constraints on the order of elaboration that come not from consideration | |
26770 | of avoiding elaboration errors, but rather from extra-lingual logic | |
26771 | requirements. Consider this example: | |
88e1739c | 26772 | |
7cd4527e AC |
26773 | @smallexample @c ada |
26774 | with Init_Constants; | |
26775 | package Constants is | |
26776 | X : Integer := 0; | |
26777 | Y : Integer := 0; | |
26778 | end Constants; | |
88e1739c | 26779 | |
7cd4527e AC |
26780 | package Init_Constants is |
26781 | procedure P; -- require a body | |
26782 | end Init_Constants; | |
88e1739c | 26783 | |
7cd4527e AC |
26784 | with Constants; |
26785 | package body Init_Constants is | |
26786 | procedure P is begin null; end; | |
26787 | begin | |
26788 | Constants.X := 3; | |
26789 | Constants.Y := 4; | |
26790 | end Init_Constants; | |
88e1739c | 26791 | |
7cd4527e AC |
26792 | with Constants; |
26793 | package Calc is | |
26794 | Z : Integer := Constants.X + Constants.Y; | |
26795 | end Calc; | |
88e1739c | 26796 | |
7cd4527e AC |
26797 | with Calc; |
26798 | with Text_IO; use Text_IO; | |
26799 | procedure Main is | |
26800 | begin | |
26801 | Put_Line (Calc.Z'Img); | |
26802 | end Main; | |
26803 | @end smallexample | |
88e1739c | 26804 | |
7cd4527e AC |
26805 | @noindent |
26806 | In this example, there is more than one valid order of elaboration. For | |
26807 | example both the following are correct orders: | |
88e1739c | 26808 | |
7cd4527e AC |
26809 | @smallexample |
26810 | Init_Constants spec | |
26811 | Constants spec | |
26812 | Calc spec | |
26813 | Init_Constants body | |
26814 | Main body | |
88e1739c | 26815 | |
7cd4527e | 26816 | and |
88e1739c | 26817 | |
7cd4527e AC |
26818 | Init_Constants spec |
26819 | Init_Constants body | |
26820 | Constants spec | |
26821 | Calc spec | |
26822 | Main body | |
88e1739c | 26823 | @end smallexample |
88e1739c FW |
26824 | |
26825 | @noindent | |
7cd4527e AC |
26826 | There is no language rule to prefer one or the other, both are correct |
26827 | from an order of elaboration point of view. But the programmatic effects | |
26828 | of the two orders are very different. In the first, the elaboration routine | |
26829 | of @code{Calc} initializes @code{Z} to zero, and then the main program | |
26830 | runs with this value of zero. But in the second order, the elaboration | |
26831 | routine of @code{Calc} runs after the body of Init_Constants has set | |
26832 | @code{X} and @code{Y} and thus @code{Z} is set to 7 before @code{Main} | |
26833 | runs. | |
88e1739c | 26834 | |
7cd4527e AC |
26835 | One could perhaps by applying pretty clever non-artificial intelligence |
26836 | to the situation guess that it is more likely that the second order of | |
26837 | elaboration is the one desired, but there is no formal linguistic reason | |
26838 | to prefer one over the other. In fact in this particular case, GNAT will | |
26839 | prefer the second order, because of the rule that bodies are elaborated | |
26840 | as soon as possible, but it's just luck that this is what was wanted | |
26841 | (if indeed the second order was preferred). | |
88e1739c | 26842 | |
7cd4527e AC |
26843 | If the program cares about the order of elaboration routines in a case like |
26844 | this, it is important to specify the order required. In this particular | |
26845 | case, that could have been achieved by adding to the spec of Calc: | |
88e1739c | 26846 | |
7cd4527e AC |
26847 | @smallexample @c ada |
26848 | pragma Elaborate_All (Constants); | |
26849 | @end smallexample | |
88e1739c | 26850 | |
7cd4527e AC |
26851 | @noindent |
26852 | which requires that the body (if any) and spec of @code{Constants}, | |
26853 | as well as the body and spec of any unit @code{with}'ed by | |
26854 | @code{Constants} be elaborated before @code{Calc} is elaborated. | |
88e1739c | 26855 | |
7cd4527e AC |
26856 | Clearly no automatic method can always guess which alternative you require, |
26857 | and if you are working with legacy code that had constraints of this kind | |
26858 | which were not properly specified by adding @code{Elaborate} or | |
26859 | @code{Elaborate_All} pragmas, then indeed it is possible that two different | |
26860 | compilers can choose different orders. | |
88e1739c | 26861 | |
ba1cbfb9 RD |
26862 | However, GNAT does attempt to diagnose the common situation where there |
26863 | are uninitialized variables in the visible part of a package spec, and the | |
26864 | corresponding package body has an elaboration block that directly or | |
26865 | indirectly initialized one or more of these variables. This is the situation | |
26866 | in which a pragma Elaborate_Body is usually desirable, and GNAT will generate | |
26867 | a warning that suggests this addition if it detects this situation. | |
26868 | ||
7cd4527e AC |
26869 | The @code{gnatbind} |
26870 | @option{^-p^/PESSIMISTIC_ELABORATION^} switch may be useful in smoking | |
26871 | out problems. This switch causes bodies to be elaborated as late as possible | |
26872 | instead of as early as possible. In the example above, it would have forced | |
26873 | the choice of the first elaboration order. If you get different results | |
26874 | when using this switch, and particularly if one set of results is right, | |
26875 | and one is wrong as far as you are concerned, it shows that you have some | |
26876 | missing @code{Elaborate} pragmas. For the example above, we have the | |
26877 | following output: | |
88e1739c | 26878 | |
7cd4527e AC |
26879 | @smallexample |
26880 | gnatmake -f -q main | |
26881 | main | |
26882 | 7 | |
26883 | gnatmake -f -q main -bargs -p | |
26884 | main | |
26885 | 0 | |
26886 | @end smallexample | |
88e1739c | 26887 | |
7cd4527e AC |
26888 | @noindent |
26889 | It is of course quite unlikely that both these results are correct, so | |
26890 | it is up to you in a case like this to investigate the source of the | |
26891 | difference, by looking at the two elaboration orders that are chosen, | |
26892 | and figuring out which is correct, and then adding the necessary | |
32e209e4 | 26893 | @code{Elaborate} or @code{Elaborate_All} pragmas to ensure the desired order. |
88e1739c | 26894 | |
4c51ff88 AC |
26895 | @node Determining the Chosen Elaboration Order |
26896 | @section Determining the Chosen Elaboration Order | |
26897 | @noindent | |
26898 | ||
26899 | To see the elaboration order that the binder chooses, you can look at | |
26900 | the last part of the b~xxx.adb binder output file. Here is an example: | |
26901 | ||
26902 | @smallexample @c ada | |
26903 | System.Soft_Links'Elab_Body; | |
26904 | E14 := True; | |
26905 | System.Secondary_Stack'Elab_Body; | |
26906 | E18 := True; | |
26907 | System.Exception_Table'Elab_Body; | |
26908 | E24 := True; | |
26909 | Ada.Io_Exceptions'Elab_Spec; | |
26910 | E67 := True; | |
26911 | Ada.Tags'Elab_Spec; | |
26912 | Ada.Streams'Elab_Spec; | |
26913 | E43 := True; | |
26914 | Interfaces.C'Elab_Spec; | |
26915 | E69 := True; | |
26916 | System.Finalization_Root'Elab_Spec; | |
26917 | E60 := True; | |
26918 | System.Os_Lib'Elab_Body; | |
26919 | E71 := True; | |
26920 | System.Finalization_Implementation'Elab_Spec; | |
26921 | System.Finalization_Implementation'Elab_Body; | |
26922 | E62 := True; | |
26923 | Ada.Finalization'Elab_Spec; | |
26924 | E58 := True; | |
26925 | Ada.Finalization.List_Controller'Elab_Spec; | |
26926 | E76 := True; | |
26927 | System.File_Control_Block'Elab_Spec; | |
26928 | E74 := True; | |
26929 | System.File_Io'Elab_Body; | |
26930 | E56 := True; | |
26931 | Ada.Tags'Elab_Body; | |
26932 | E45 := True; | |
26933 | Ada.Text_Io'Elab_Spec; | |
26934 | Ada.Text_Io'Elab_Body; | |
26935 | E07 := True; | |
26936 | @end smallexample | |
26937 | ||
26938 | @noindent | |
26939 | Here Elab_Spec elaborates the spec | |
26940 | and Elab_Body elaborates the body. The assignments to the Exx flags | |
26941 | flag that the corresponding body is now elaborated. | |
26942 | ||
26943 | You can also ask the binder to generate a more | |
26944 | readable list of the elaboration order using the | |
26945 | @code{-l} switch when invoking the binder. Here is | |
26946 | an example of the output generated by this switch: | |
26947 | ||
26948 | @smallexample | |
26949 | ada (spec) | |
26950 | interfaces (spec) | |
26951 | system (spec) | |
26952 | system.case_util (spec) | |
26953 | system.case_util (body) | |
26954 | system.concat_2 (spec) | |
26955 | system.concat_2 (body) | |
26956 | system.concat_3 (spec) | |
26957 | system.concat_3 (body) | |
26958 | system.htable (spec) | |
26959 | system.parameters (spec) | |
26960 | system.parameters (body) | |
26961 | system.crtl (spec) | |
26962 | interfaces.c_streams (spec) | |
26963 | interfaces.c_streams (body) | |
26964 | system.restrictions (spec) | |
26965 | system.restrictions (body) | |
26966 | system.standard_library (spec) | |
26967 | system.exceptions (spec) | |
26968 | system.exceptions (body) | |
26969 | system.storage_elements (spec) | |
26970 | system.storage_elements (body) | |
26971 | system.secondary_stack (spec) | |
26972 | system.stack_checking (spec) | |
26973 | system.stack_checking (body) | |
26974 | system.string_hash (spec) | |
26975 | system.string_hash (body) | |
26976 | system.htable (body) | |
26977 | system.strings (spec) | |
26978 | system.strings (body) | |
26979 | system.traceback (spec) | |
26980 | system.traceback (body) | |
26981 | system.traceback_entries (spec) | |
26982 | system.traceback_entries (body) | |
26983 | ada.exceptions (spec) | |
26984 | ada.exceptions.last_chance_handler (spec) | |
26985 | system.soft_links (spec) | |
26986 | system.soft_links (body) | |
26987 | ada.exceptions.last_chance_handler (body) | |
26988 | system.secondary_stack (body) | |
26989 | system.exception_table (spec) | |
26990 | system.exception_table (body) | |
26991 | ada.io_exceptions (spec) | |
26992 | ada.tags (spec) | |
26993 | ada.streams (spec) | |
26994 | interfaces.c (spec) | |
26995 | interfaces.c (body) | |
26996 | system.finalization_root (spec) | |
26997 | system.finalization_root (body) | |
26998 | system.memory (spec) | |
26999 | system.memory (body) | |
27000 | system.standard_library (body) | |
27001 | system.os_lib (spec) | |
27002 | system.os_lib (body) | |
27003 | system.unsigned_types (spec) | |
27004 | system.stream_attributes (spec) | |
27005 | system.stream_attributes (body) | |
27006 | system.finalization_implementation (spec) | |
27007 | system.finalization_implementation (body) | |
27008 | ada.finalization (spec) | |
27009 | ada.finalization (body) | |
27010 | ada.finalization.list_controller (spec) | |
27011 | ada.finalization.list_controller (body) | |
27012 | system.file_control_block (spec) | |
27013 | system.file_io (spec) | |
27014 | system.file_io (body) | |
27015 | system.val_uns (spec) | |
27016 | system.val_util (spec) | |
27017 | system.val_util (body) | |
27018 | system.val_uns (body) | |
27019 | system.wch_con (spec) | |
27020 | system.wch_con (body) | |
27021 | system.wch_cnv (spec) | |
27022 | system.wch_jis (spec) | |
27023 | system.wch_jis (body) | |
27024 | system.wch_cnv (body) | |
27025 | system.wch_stw (spec) | |
27026 | system.wch_stw (body) | |
27027 | ada.tags (body) | |
27028 | ada.exceptions (body) | |
27029 | ada.text_io (spec) | |
27030 | ada.text_io (body) | |
27031 | text_io (spec) | |
27032 | gdbstr (body) | |
27033 | @end smallexample | |
c690a2ec | 27034 | |
6e6636ec RD |
27035 | @c ********************************** |
27036 | @node Overflow Check Handling in GNAT | |
27037 | @appendix Overflow Check Handling in GNAT | |
27038 | @cindex Overflow checks | |
27039 | @cindex Checks (overflow) | |
27040 | @c ********************************** | |
27041 | ||
27042 | @menu | |
27043 | * Background:: | |
27044 | * Overflow Checking Modes in GNAT:: | |
27045 | * Specifying the Desired Mode:: | |
27046 | * Default Settings:: | |
27047 | * Implementation Notes:: | |
27048 | @end menu | |
27049 | ||
27050 | ||
27051 | @node Background | |
27052 | @section Background | |
27053 | ||
27054 | @noindent | |
27055 | Overflow checks are checks that the compiler may make to ensure | |
27056 | that intermediate results are not out of range. For example: | |
27057 | ||
27058 | @smallexample @c ada | |
27059 | A : Integer; | |
27060 | ... | |
27061 | A := A + 1; | |
27062 | @end smallexample | |
27063 | ||
27064 | @noindent | |
27065 | if @code{A} has the value @code{Integer'Last}, then the addition may cause | |
27066 | overflow since the result is out of range of the type @code{Integer}. | |
27067 | In this case @code{Constraint_Error} will be raised if checks are | |
27068 | enabled. | |
27069 | ||
27070 | A trickier situation arises in examples like the following: | |
27071 | ||
27072 | @smallexample @c ada | |
27073 | A, C : Integer; | |
27074 | ... | |
27075 | A := (A + 1) + C; | |
27076 | @end smallexample | |
27077 | ||
27078 | @noindent | |
27079 | where @code{A} is @code{Integer'Last} and @code{C} is @code{-1}. | |
27080 | Now the final result of the expression on the right hand side is | |
27081 | @code{Integer'Last} which is in range, but the question arises whether the | |
27082 | intermediate addition of @code{(A + 1)} raises an overflow error. | |
27083 | ||
27084 | The (perhaps surprising) answer is that the Ada language | |
27085 | definition does not answer this question. Instead it leaves | |
d8192289 AC |
27086 | it up to the implementation to do one of two things if overflow |
27087 | checks are enabled. | |
6e6636ec RD |
27088 | |
27089 | @itemize @bullet | |
27090 | @item | |
27091 | raise an exception (@code{Constraint_Error}), or | |
27092 | ||
27093 | @item | |
27094 | yield the correct mathematical result which is then used in | |
27095 | subsequent operations. | |
27096 | @end itemize | |
27097 | ||
27098 | @noindent | |
27099 | If the compiler chooses the first approach, then the assignment of this | |
d8192289 AC |
27100 | example will indeed raise @code{Constraint_Error} if overflow checking is |
27101 | enabled, or result in erroneous execution if overflow checks are suppressed. | |
27102 | ||
27103 | But if the compiler | |
6e6636ec RD |
27104 | chooses the second approach, then it can perform both additions yielding |
27105 | the correct mathematical result, which is in range, so no exception | |
d8192289 AC |
27106 | will be raised, and the right result is obtained, regardless of whether |
27107 | overflow checks are suppressed. | |
6e6636ec RD |
27108 | |
27109 | Note that in the first example an | |
27110 | exception will be raised in either case, since if the compiler | |
27111 | gives the correct mathematical result for the addition, it will | |
27112 | be out of range of the target type of the assignment, and thus | |
27113 | fails the range check. | |
27114 | ||
27115 | This lack of specified behavior in the handling of overflow for | |
27116 | intermediate results is a source of non-portability, and can thus | |
27117 | be problematic when programs are ported. Most typically this arises | |
27118 | in a situation where the original compiler did not raise an exception, | |
27119 | and then the application is moved to a compiler where the check is | |
27120 | performed on the intermediate result and an unexpected exception is | |
27121 | raised. | |
27122 | ||
27123 | Furthermore, when using Ada 2012's preconditions and other | |
27124 | assertion forms, another issue arises. Consider: | |
27125 | ||
27126 | @smallexample @c ada | |
27127 | procedure P (A, B : Integer) with | |
27128 | Pre => A + B <= Integer'Last; | |
27129 | @end smallexample | |
27130 | ||
27131 | @noindent | |
27132 | One often wants to regard arithmetic in a context like this from | |
27133 | a mathematical point of view. So for example, if the two actual parameters | |
27134 | for a call to @code{P} are both @code{Integer'Last}, then | |
27135 | the precondition should be regarded as False. If we are executing | |
27136 | in a mode with run-time checks enabled for preconditions, then we would | |
27137 | like this precondition to fail, rather than raising an exception | |
27138 | because of the intermediate overflow. | |
27139 | ||
27140 | However, the language definition leaves the specification of | |
27141 | whether the above condition fails (raising @code{Assert_Error}) or | |
27142 | causes an intermediate overflow (raising @code{Constraint_Error}) | |
27143 | up to the implementation. | |
27144 | ||
27145 | The situation is worse in a case such as the following: | |
27146 | ||
27147 | @smallexample @c ada | |
27148 | procedure Q (A, B, C : Integer) with | |
27149 | Pre => A + B + C <= Integer'Last; | |
27150 | @end smallexample | |
27151 | ||
27152 | @noindent | |
27153 | Consider the call | |
27154 | ||
27155 | @smallexample @c ada | |
27156 | Q (A => Integer'Last, B => 1, C => -1); | |
27157 | @end smallexample | |
27158 | ||
27159 | @noindent | |
27160 | From a mathematical point of view the precondition | |
27161 | is True, but at run time we may (but are not guaranteed to) get an | |
27162 | exception raised because of the intermediate overflow (and we really | |
27163 | would prefer this precondition to be considered True at run time). | |
27164 | ||
27165 | @node Overflow Checking Modes in GNAT | |
27166 | @section Overflow Checking Modes in GNAT | |
27167 | ||
27168 | @noindent | |
27169 | To deal with the portability issue, and with the problem of | |
d4aef883 | 27170 | mathematical versus run-time interpretation of the expressions in |
6e6636ec | 27171 | assertions, GNAT provides comprehensive control over the handling |
d8192289 | 27172 | of intermediate overflow. GNAT can operate in three modes, and |
6e6636ec RD |
27173 | furthemore, permits separate selection of operating modes for |
27174 | the expressions within assertions (here the term ``assertions'' | |
27175 | is used in the technical sense, which includes preconditions and so forth) | |
27176 | and for expressions appearing outside assertions. | |
27177 | ||
d8192289 | 27178 | The three modes are: |
6e6636ec RD |
27179 | |
27180 | @itemize @bullet | |
ceee0bde | 27181 | @item @i{Use base type for intermediate operations} (@code{STRICT}) |
6e6636ec RD |
27182 | |
27183 | In this mode, all intermediate results for predefined arithmetic | |
ceee0bde AC |
27184 | operators are computed using the base type, and the result must |
27185 | be in range of the base type. If this is not the | |
d8192289 AC |
27186 | case then either an exception is raised (if overflow checks are |
27187 | enabled) or the execution is erroneous (if overflow checks are suppressed). | |
27188 | This is the normal default mode. | |
6e6636ec RD |
27189 | |
27190 | @item @i{Most intermediate overflows avoided} (@code{MINIMIZED}) | |
27191 | ||
27192 | In this mode, the compiler attempts to avoid intermediate overflows by | |
ceee0bde AC |
27193 | using a larger integer type, typically @code{Long_Long_Integer}, |
27194 | as the type in which arithmetic is | |
27195 | performed for predefined arithmetic operators. This may be slightly more | |
6e6636ec RD |
27196 | expensive at |
27197 | run time (compared to suppressing intermediate overflow checks), though | |
d8192289 | 27198 | the cost is negligible on modern 64-bit machines. For the examples given |
6e6636ec RD |
27199 | earlier, no intermediate overflows would have resulted in exceptions, |
27200 | since the intermediate results are all in the range of | |
27201 | @code{Long_Long_Integer} (typically 64-bits on nearly all implementations | |
ceee0bde AC |
27202 | of GNAT). In addition, if checks are enabled, this reduces the number of |
27203 | checks that must be made, so this choice may actually result in an | |
27204 | improvement in space and time behavior. | |
6e6636ec RD |
27205 | |
27206 | However, there are cases where @code{Long_Long_Integer} is not large | |
27207 | enough, consider the following example: | |
27208 | ||
27209 | @smallexample @c ada | |
27210 | procedure R (A, B, C, D : Integer) with | |
27211 | Pre => (A**2 * B**2) / (C**2 * D**2) <= 10; | |
27212 | @end smallexample | |
27213 | ||
27214 | where @code{A} = @code{B} = @code{C} = @code{D} = @code{Integer'Last}. | |
27215 | Now the intermediate results are | |
27216 | out of the range of @code{Long_Long_Integer} even though the final result | |
27217 | is in range and the precondition is True (from a mathematical point | |
d8192289 AC |
27218 | of view). In such a case, operating in this mode, an overflow occurs |
27219 | for the intermediate computation (which is why this mode | |
27220 | says @i{most} intermediate overflows are avoided). In this case, | |
27221 | an exception is raised if overflow checks are enabled, and the | |
27222 | execution is erroneous if overflow checks are suppressed. | |
6e6636ec RD |
27223 | |
27224 | @item @i{All intermediate overflows avoided} (@code{ELIMINATED}) | |
27225 | ||
27226 | In this mode, the compiler avoids all intermediate overflows | |
27227 | by using arbitrary precision arithmetic as required. In this | |
27228 | mode, the above example with @code{A**2 * B**2} would | |
27229 | not cause intermediate overflow, because the intermediate result | |
27230 | would be evaluated using sufficient precision, and the result | |
27231 | of evaluating the precondition would be True. | |
27232 | ||
27233 | This mode has the advantage of avoiding any intermediate | |
27234 | overflows, but at the expense of significant run-time overhead, | |
27235 | including the use of a library (included automatically in this | |
27236 | mode) for multiple-precision arithmetic. | |
27237 | ||
27238 | This mode provides cleaner semantics for assertions, since now | |
27239 | the run-time behavior emulates true arithmetic behavior for the | |
27240 | predefined arithmetic operators, meaning that there is never a | |
27241 | conflict between the mathematical view of the assertion, and its | |
27242 | run-time behavior. | |
d8192289 AC |
27243 | |
27244 | Note that in this mode, the behavior is unaffected by whether or | |
27245 | not overflow checks are suppressed, since overflow does not occur. | |
27246 | It is possible for gigantic intermediate expressions to raise | |
27247 | @code{Storage_Error} as a result of attempting to compute the | |
27248 | results of such expressions (e.g. @code{Integer'Last ** Integer'Last}) | |
27249 | but overflow is impossible. | |
27250 | ||
27251 | ||
6e6636ec RD |
27252 | @end itemize |
27253 | ||
27254 | @noindent | |
27255 | Note that these modes apply only to the evaluation of predefined | |
27256 | arithmetic, membership, and comparison operators for signed integer | |
27257 | aritmetic. | |
27258 | ||
27259 | For fixed-point arithmetic, checks can be suppressed. But if checks | |
d8192289 | 27260 | are enabled |
6e6636ec | 27261 | then fixed-point values are always checked for overflow against the |
d8192289 AC |
27262 | base type for intermediate expressions (that is such checks always |
27263 | operate in the equivalent of @code{STRICT} mode). | |
6e6636ec RD |
27264 | |
27265 | For floating-point, on nearly all architectures, @code{Machine_Overflows} | |
27266 | is False, and IEEE infinities are generated, so overflow exceptions | |
27267 | are never raised. If you want to avoid infinities, and check that | |
27268 | final results of expressions are in range, then you can declare a | |
27269 | constrained floating-point type, and range checks will be carried | |
27270 | out in the normal manner (with infinite values always failing all | |
27271 | range checks). | |
27272 | ||
27273 | ||
27274 | @c ------------------------- | |
27275 | @node Specifying the Desired Mode | |
27276 | @section Specifying the Desired Mode | |
27277 | ||
27278 | @noindent | |
d8192289 | 27279 | The desired mode of for handling intermediate overflow can be specified using |
ceee0bde | 27280 | either the @code{Overflow_Mode} pragma or an equivalent compiler switch. |
6e6636ec | 27281 | The pragma has the form |
ceee0bde | 27282 | @cindex pragma @code{Overflow_Mode} |
6e6636ec RD |
27283 | |
27284 | @smallexample @c ada | |
ceee0bde | 27285 | pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]); |
6e6636ec RD |
27286 | @end smallexample |
27287 | ||
27288 | @noindent | |
27289 | where @code{MODE} is one of | |
27290 | ||
27291 | @itemize @bullet | |
d8192289 | 27292 | @item @code{STRICT}: intermediate overflows checked (using base type) |
6e6636ec RD |
27293 | @item @code{MINIMIZED}: minimize intermediate overflows |
27294 | @item @code{ELIMINATED}: eliminate intermediate overflows | |
27295 | @end itemize | |
27296 | ||
27297 | @noindent | |
27298 | The case is ignored, so @code{MINIMIZED}, @code{Minimized} and | |
27299 | @code{minimized} all have the same effect. | |
27300 | ||
27301 | If only the @code{General} parameter is present, then the given @code{MODE} | |
27302 | applies | |
27303 | to expressions both within and outside assertions. If both arguments | |
27304 | are present, then @code{General} applies to expressions outside assertions, | |
27305 | and @code{Assertions} applies to expressions within assertions. For example: | |
27306 | ||
27307 | @smallexample @c ada | |
ceee0bde | 27308 | pragma Overflow_Mode |
6e6636ec RD |
27309 | (General => Minimized, Assertions => Eliminated); |
27310 | @end smallexample | |
27311 | ||
27312 | @noindent | |
27313 | specifies that general expressions outside assertions be evaluated | |
27314 | in ``minimize intermediate overflows'' mode, and expressions within | |
27315 | assertions be evaluated in ``eliminate intermediate overflows'' mode. | |
27316 | This is often a reasonable choice, avoiding excessive overhead | |
27317 | outside assertions, but assuring a high degree of portability | |
27318 | when importing code from another compiler, while incurring | |
27319 | the extra overhead for assertion expressions to ensure that | |
27320 | the behavior at run time matches the expected mathematical | |
27321 | behavior. | |
27322 | ||
ceee0bde | 27323 | The @code{Overflow_Mode} pragma has the same scoping and placement |
6e6636ec RD |
27324 | rules as pragma @code{Suppress}, so it can occur either as a |
27325 | configuration pragma, specifying a default for the whole | |
27326 | program, or in a declarative scope, where it applies to the | |
27327 | remaining declarations and statements in that scope. | |
27328 | ||
ceee0bde | 27329 | Note that pragma @code{Overflow_Mode} does not affect whether |
d8192289 AC |
27330 | overflow checks are enabled or suppressed. It only controls the |
27331 | method used to compute intermediate values. To control whether | |
27332 | overflow checking is enabled or suppressed, use pragma @code{Suppress} | |
27333 | or @code{Unsuppress} in the usual manner | |
27334 | ||
6e6636ec RD |
27335 | Additionally, a compiler switch @option{-gnato?} or @option{-gnato??} |
27336 | can be used to control the checking mode default (which can be subsequently | |
d8192289 | 27337 | overridden using pragmas). |
6e6636ec RD |
27338 | @cindex @option{-gnato?} (gcc) |
27339 | @cindex @option{-gnato??} (gcc) | |
27340 | ||
d8192289 | 27341 | Here `@code{?}' is one of the digits `@code{1}' through `@code{3}': |
6e6636ec RD |
27342 | |
27343 | @itemize @bullet | |
6e6636ec | 27344 | @item @code{1}: |
ceee0bde | 27345 | use base type for intermediate operations (@code{STRICT}) |
6e6636ec RD |
27346 | @item @code{2}: |
27347 | minimize intermediate overflows (@code{MINIMIZED}) | |
27348 | @item @code{3}: | |
27349 | eliminate intermediate overflows (@code{ELIMINATED}) | |
27350 | @end itemize | |
27351 | ||
27352 | @noindent | |
27353 | As with the pragma, if only one digit appears then it applies to all | |
27354 | cases; if two digits are given, then the first applies outside | |
27355 | assertions, and the second within assertions. Thus the equivalent | |
354c3840 AC |
27356 | of the example pragma above would be |
27357 | @option{^-gnato23^/OVERFLOW_CHECKS=23^}. | |
6e6636ec RD |
27358 | |
27359 | If no digits follow the @option{-gnato}, then it is equivalent to | |
354c3840 | 27360 | @option{^-gnato11^/OVERFLOW_CHECKS=11^}, |
ceee0bde AC |
27361 | causing all intermediate operations to be computed using the base |
27362 | type (@code{STRICT} mode). | |
6e6636ec | 27363 | |
d8192289 AC |
27364 | In addition to setting the mode used for computation of intermediate |
27365 | results, the @code{-gnato} switch also enables overflow checking (which | |
27366 | is suppressed by default). It thus combines the effect of using | |
ceee0bde | 27367 | a pragma @code{Overflow_Mode} and pragma @code{Unsuppress}. |
d8192289 | 27368 | |
6e6636ec RD |
27369 | |
27370 | @c ------------------------- | |
27371 | @node Default Settings | |
27372 | @section Default Settings | |
27373 | ||
27374 | The default mode for overflow checks is | |
27375 | ||
27376 | @smallexample | |
d8192289 | 27377 | General => Strict |
6e6636ec RD |
27378 | @end smallexample |
27379 | ||
27380 | @noindent | |
d8192289 AC |
27381 | which causes all computations both inside and outside assertions to use |
27382 | the base type. In addition overflow checks are suppressed. | |
27383 | ||
6e6636ec | 27384 | This retains compatibility with previous versions of |
d8192289 AC |
27385 | GNAT which suppressed overflow checks by default and always |
27386 | used the base type for computation of intermediate results. | |
6e6636ec RD |
27387 | |
27388 | The switch @option{-gnato} (with no digits following) is equivalent to | |
27389 | @cindex @option{-gnato} (gcc) | |
27390 | ||
27391 | @smallexample | |
d8192289 | 27392 | General => Strict |
6e6636ec RD |
27393 | @end smallexample |
27394 | ||
27395 | @noindent | |
27396 | which causes overflow checking of all intermediate overflows | |
d8192289 AC |
27397 | both inside and outside assertions against the base type. |
27398 | This provides compatibility | |
6e6636ec RD |
27399 | with this switch as implemented in previous versions of GNAT. |
27400 | ||
d8192289 AC |
27401 | The pragma @code{Suppress (Overflow_Check)} disables overflow |
27402 | checking, but it has no effect on the method used for computing | |
27403 | intermediate results. | |
6e6636ec | 27404 | |
3565684a | 27405 | The pragma @code{Unsuppress (Overflow_Check)} enables overflow |
d8192289 AC |
27406 | checking, but it has no effect on the method used for computing |
27407 | intermediate results. | |
6e6636ec RD |
27408 | |
27409 | @c ------------------------- | |
27410 | @node Implementation Notes | |
27411 | @section Implementation Notes | |
27412 | ||
27413 | In practice on typical 64-bit machines, the @code{MINIMIZED} mode is | |
27414 | reasonably efficient, and can be generally used. It also helps | |
27415 | to ensure compatibility with code imported from some other | |
27416 | compiler to GNAT. | |
27417 | ||
27418 | Setting all intermediate overflows checking (@code{CHECKED} mode) | |
27419 | makes sense if you want to | |
27420 | make sure that your code is compatible with any other possible | |
27421 | Ada implementation. This may be useful in ensuring portability | |
27422 | for code that is to be exported to some other compiler than GNAT. | |
d8192289 | 27423 | |
6e6636ec RD |
27424 | |
27425 | The Ada standard allows the reassociation of expressions at | |
27426 | the same precedence level if no parentheses are present. For | |
27427 | example, @w{@code{A+B+C}} parses as though it were @w{@code{(A+B)+C}}, but | |
27428 | the compiler can reintepret this as @w{@code{A+(B+C)}}, possibly | |
27429 | introducing or eliminating an overflow exception. The GNAT | |
27430 | compiler never takes advantage of this freedom, and the | |
27431 | expression @w{@code{A+B+C}} will be evaluated as @w{@code{(A+B)+C}}. | |
27432 | If you need the other order, you can write the parentheses | |
27433 | explicitly @w{@code{A+(B+C)}} and GNAT will respect this order. | |
27434 | ||
27435 | The use of @code{ELIMINATED} mode will cause the compiler to | |
27436 | automatically include an appropriate arbitrary precision | |
27437 | integer arithmetic package. The compiler will make calls | |
27438 | to this package, though only in cases where it cannot be | |
27439 | sure that @code{Long_Long_Integer} is sufficient to guard against | |
27440 | intermediate overflows. This package does not use dynamic | |
27441 | alllocation, but it does use the secondary stack, so an | |
27442 | appropriate secondary stack package must be present (this | |
27443 | is always true for standard full Ada, but may require | |
27444 | specific steps for restricted run times such as ZFP). | |
27445 | ||
27446 | Although @code{ELIMINATED} mode causes expressions to use arbitrary | |
27447 | precision arithmetic, avoiding overflow, the final result | |
27448 | must be in an appropriate range. This is true even if the | |
27449 | final result is of type @code{[Long_[Long_]]Integer'Base}, which | |
27450 | still has the same bounds as its associated constrained | |
27451 | type at run-time. | |
27452 | ||
27453 | Currently, the @code{ELIMINATED} mode is only available on target | |
27454 | platforms for which @code{Long_Long_Integer} is 64-bits (nearly all GNAT | |
27455 | platforms). | |
c690a2ec RD |
27456 | |
27457 | @c ******************************* | |
27458 | @node Conditional Compilation | |
27459 | @appendix Conditional Compilation | |
27460 | @c ******************************* | |
27461 | @cindex Conditional compilation | |
27462 | ||
27463 | @noindent | |
27464 | It is often necessary to arrange for a single source program | |
27465 | to serve multiple purposes, where it is compiled in different | |
27466 | ways to achieve these different goals. Some examples of the | |
27467 | need for this feature are | |
27468 | ||
27469 | @itemize @bullet | |
27470 | @item Adapting a program to a different hardware environment | |
27471 | @item Adapting a program to a different target architecture | |
27472 | @item Turning debugging features on and off | |
27473 | @item Arranging for a program to compile with different compilers | |
27474 | @end itemize | |
27475 | ||
27476 | @noindent | |
27477 | In C, or C++, the typical approach would be to use the preprocessor | |
27478 | that is defined as part of the language. The Ada language does not | |
27479 | contain such a feature. This is not an oversight, but rather a very | |
27480 | deliberate design decision, based on the experience that overuse of | |
27481 | the preprocessing features in C and C++ can result in programs that | |
27482 | are extremely difficult to maintain. For example, if we have ten | |
27483 | switches that can be on or off, this means that there are a thousand | |
27484 | separate programs, any one of which might not even be syntactically | |
27485 | correct, and even if syntactically correct, the resulting program | |
27486 | might not work correctly. Testing all combinations can quickly become | |
27487 | impossible. | |
27488 | ||
27489 | Nevertheless, the need to tailor programs certainly exists, and in | |
27490 | this Appendix we will discuss how this can | |
27491 | be achieved using Ada in general, and GNAT in particular. | |
27492 | ||
27493 | @menu | |
27494 | * Use of Boolean Constants:: | |
27495 | * Debugging - A Special Case:: | |
27496 | * Conditionalizing Declarations:: | |
27497 | * Use of Alternative Implementations:: | |
27498 | * Preprocessing:: | |
27499 | @end menu | |
27500 | ||
27501 | @node Use of Boolean Constants | |
27502 | @section Use of Boolean Constants | |
27503 | ||
27504 | @noindent | |
27505 | In the case where the difference is simply which code | |
27506 | sequence is executed, the cleanest solution is to use Boolean | |
27507 | constants to control which code is executed. | |
27508 | ||
27509 | @smallexample @c ada | |
27510 | @group | |
27511 | FP_Initialize_Required : constant Boolean := True; | |
d488f6ea | 27512 | @dots{} |
c690a2ec | 27513 | if FP_Initialize_Required then |
d488f6ea | 27514 | @dots{} |
c690a2ec RD |
27515 | end if; |
27516 | @end group | |
27517 | @end smallexample | |
27518 | ||
27519 | @noindent | |
27520 | Not only will the code inside the @code{if} statement not be executed if | |
27521 | the constant Boolean is @code{False}, but it will also be completely | |
27522 | deleted from the program. | |
27523 | However, the code is only deleted after the @code{if} statement | |
27524 | has been checked for syntactic and semantic correctness. | |
27525 | (In contrast, with preprocessors the code is deleted before the | |
27526 | compiler ever gets to see it, so it is not checked until the switch | |
27527 | is turned on.) | |
27528 | @cindex Preprocessors (contrasted with conditional compilation) | |
27529 | ||
27530 | Typically the Boolean constants will be in a separate package, | |
27531 | something like: | |
27532 | ||
27533 | @smallexample @c ada | |
27534 | @group | |
27535 | package Config is | |
27536 | FP_Initialize_Required : constant Boolean := True; | |
27537 | Reset_Available : constant Boolean := False; | |
d488f6ea | 27538 | @dots{} |
c690a2ec RD |
27539 | end Config; |
27540 | @end group | |
27541 | @end smallexample | |
27542 | ||
27543 | @noindent | |
27544 | The @code{Config} package exists in multiple forms for the various targets, | |
27545 | with an appropriate script selecting the version of @code{Config} needed. | |
27546 | Then any other unit requiring conditional compilation can do a @code{with} | |
27547 | of @code{Config} to make the constants visible. | |
27548 | ||
27549 | ||
27550 | @node Debugging - A Special Case | |
27551 | @section Debugging - A Special Case | |
27552 | ||
27553 | @noindent | |
27554 | A common use of conditional code is to execute statements (for example | |
27555 | dynamic checks, or output of intermediate results) under control of a | |
27556 | debug switch, so that the debugging behavior can be turned on and off. | |
27557 | This can be done using a Boolean constant to control whether the code | |
27558 | is active: | |
27559 | ||
27560 | @smallexample @c ada | |
27561 | @group | |
27562 | if Debugging then | |
27563 | Put_Line ("got to the first stage!"); | |
27564 | end if; | |
27565 | @end group | |
27566 | @end smallexample | |
27567 | ||
27568 | @noindent | |
27569 | or | |
27570 | ||
27571 | @smallexample @c ada | |
27572 | @group | |
27573 | if Debugging and then Temperature > 999.0 then | |
27574 | raise Temperature_Crazy; | |
27575 | end if; | |
27576 | @end group | |
27577 | @end smallexample | |
27578 | ||
27579 | @noindent | |
27580 | Since this is a common case, there are special features to deal with | |
27581 | this in a convenient manner. For the case of tests, Ada 2005 has added | |
27582 | a pragma @code{Assert} that can be used for such tests. This pragma is modeled | |
27583 | @cindex pragma @code{Assert} | |
27584 | on the @code{Assert} pragma that has always been available in GNAT, so this | |
27585 | feature may be used with GNAT even if you are not using Ada 2005 features. | |
b2e74434 RW |
27586 | The use of pragma @code{Assert} is described in |
27587 | @ref{Pragma Assert,,, gnat_rm, GNAT Reference Manual}, but as an | |
27588 | example, the last test could be written: | |
c690a2ec RD |
27589 | |
27590 | @smallexample @c ada | |
27591 | pragma Assert (Temperature <= 999.0, "Temperature Crazy"); | |
27592 | @end smallexample | |
27593 | ||
27594 | @noindent | |
27595 | or simply | |
27596 | ||
27597 | @smallexample @c ada | |
27598 | pragma Assert (Temperature <= 999.0); | |
27599 | @end smallexample | |
27600 | ||
27601 | @noindent | |
27602 | In both cases, if assertions are active and the temperature is excessive, | |
27603 | the exception @code{Assert_Failure} will be raised, with the given string in | |
27604 | the first case or a string indicating the location of the pragma in the second | |
27605 | case used as the exception message. | |
27606 | ||
27607 | You can turn assertions on and off by using the @code{Assertion_Policy} | |
27608 | pragma. | |
27609 | @cindex pragma @code{Assertion_Policy} | |
27610 | This is an Ada 2005 pragma which is implemented in all modes by | |
27611 | GNAT, but only in the latest versions of GNAT which include Ada 2005 | |
27612 | capability. Alternatively, you can use the @option{-gnata} switch | |
27613 | @cindex @option{-gnata} switch | |
27614 | to enable assertions from the command line (this is recognized by all versions | |
27615 | of GNAT). | |
27616 | ||
27617 | For the example above with the @code{Put_Line}, the GNAT-specific pragma | |
27618 | @code{Debug} can be used: | |
27619 | @cindex pragma @code{Debug} | |
27620 | ||
27621 | @smallexample @c ada | |
27622 | pragma Debug (Put_Line ("got to the first stage!")); | |
27623 | @end smallexample | |
27624 | ||
27625 | @noindent | |
27626 | If debug pragmas are enabled, the argument, which must be of the form of | |
27627 | a procedure call, is executed (in this case, @code{Put_Line} will be called). | |
27628 | Only one call can be present, but of course a special debugging procedure | |
27629 | containing any code you like can be included in the program and then | |
27630 | called in a pragma @code{Debug} argument as needed. | |
27631 | ||
27632 | One advantage of pragma @code{Debug} over the @code{if Debugging then} | |
27633 | construct is that pragma @code{Debug} can appear in declarative contexts, | |
27634 | such as at the very beginning of a procedure, before local declarations have | |
27635 | been elaborated. | |
27636 | ||
27637 | Debug pragmas are enabled using either the @option{-gnata} switch that also | |
27638 | controls assertions, or with a separate Debug_Policy pragma. | |
27639 | @cindex pragma @code{Debug_Policy} | |
27640 | The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used | |
27641 | in Ada 95 and Ada 83 programs as well), and is analogous to | |
27642 | pragma @code{Assertion_Policy} to control assertions. | |
27643 | ||
27644 | @code{Assertion_Policy} and @code{Debug_Policy} are configuration pragmas, | |
27645 | and thus they can appear in @file{gnat.adc} if you are not using a | |
27646 | project file, or in the file designated to contain configuration pragmas | |
27647 | in a project file. | |
27648 | They then apply to all subsequent compilations. In practice the use of | |
27649 | the @option{-gnata} switch is often the most convenient method of controlling | |
27650 | the status of these pragmas. | |
27651 | ||
27652 | Note that a pragma is not a statement, so in contexts where a statement | |
27653 | sequence is required, you can't just write a pragma on its own. You have | |
27654 | to add a @code{null} statement. | |
27655 | ||
27656 | @smallexample @c ada | |
27657 | @group | |
d488f6ea RW |
27658 | if @dots{} then |
27659 | @dots{} -- some statements | |
c690a2ec RD |
27660 | else |
27661 | pragma Assert (Num_Cases < 10); | |
27662 | null; | |
27663 | end if; | |
27664 | @end group | |
27665 | @end smallexample | |
27666 | ||
27667 | ||
27668 | @node Conditionalizing Declarations | |
27669 | @section Conditionalizing Declarations | |
27670 | ||
27671 | @noindent | |
27672 | In some cases, it may be necessary to conditionalize declarations to meet | |
27673 | different requirements. For example we might want a bit string whose length | |
27674 | is set to meet some hardware message requirement. | |
27675 | ||
27676 | In some cases, it may be possible to do this using declare blocks controlled | |
27677 | by conditional constants: | |
27678 | ||
27679 | @smallexample @c ada | |
27680 | @group | |
27681 | if Small_Machine then | |
27682 | declare | |
27683 | X : Bit_String (1 .. 10); | |
27684 | begin | |
d488f6ea | 27685 | @dots{} |
c690a2ec RD |
27686 | end; |
27687 | else | |
27688 | declare | |
27689 | X : Large_Bit_String (1 .. 1000); | |
27690 | begin | |
d488f6ea | 27691 | @dots{} |
c690a2ec RD |
27692 | end; |
27693 | end if; | |
27694 | @end group | |
27695 | @end smallexample | |
27696 | ||
27697 | @noindent | |
27698 | Note that in this approach, both declarations are analyzed by the | |
27699 | compiler so this can only be used where both declarations are legal, | |
27700 | even though one of them will not be used. | |
27701 | ||
aa0df10b VC |
27702 | Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word}, |
27703 | or Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations | |
c690a2ec RD |
27704 | that are parameterized by these constants. For example |
27705 | ||
27706 | @smallexample @c ada | |
27707 | @group | |
27708 | for Rec use | |
27709 | Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word; | |
27710 | end record; | |
27711 | @end group | |
27712 | @end smallexample | |
27713 | ||
27714 | @noindent | |
27715 | If @code{Bits_Per_Word} is set to 32, this generates either | |
27716 | ||
27717 | @smallexample @c ada | |
27718 | @group | |
27719 | for Rec use | |
27720 | Field1 at 0 range 0 .. 32; | |
27721 | end record; | |
27722 | @end group | |
27723 | @end smallexample | |
27724 | ||
27725 | @noindent | |
27726 | for the big endian case, or | |
27727 | ||
27728 | @smallexample @c ada | |
27729 | @group | |
27730 | for Rec use record | |
27731 | Field1 at 0 range 10 .. 32; | |
27732 | end record; | |
27733 | @end group | |
27734 | @end smallexample | |
27735 | ||
27736 | @noindent | |
27737 | for the little endian case. Since a powerful subset of Ada expression | |
27738 | notation is usable for creating static constants, clever use of this | |
27739 | feature can often solve quite difficult problems in conditionalizing | |
27740 | compilation (note incidentally that in Ada 95, the little endian | |
27741 | constant was introduced as @code{System.Default_Bit_Order}, so you do not | |
27742 | need to define this one yourself). | |
27743 | ||
27744 | ||
27745 | @node Use of Alternative Implementations | |
27746 | @section Use of Alternative Implementations | |
27747 | ||
27748 | @noindent | |
27749 | In some cases, none of the approaches described above are adequate. This | |
27750 | can occur for example if the set of declarations required is radically | |
27751 | different for two different configurations. | |
27752 | ||
27753 | In this situation, the official Ada way of dealing with conditionalizing | |
27754 | such code is to write separate units for the different cases. As long as | |
27755 | this does not result in excessive duplication of code, this can be done | |
27756 | without creating maintenance problems. The approach is to share common | |
27757 | code as far as possible, and then isolate the code and declarations | |
27758 | that are different. Subunits are often a convenient method for breaking | |
27759 | out a piece of a unit that is to be conditionalized, with separate files | |
27760 | for different versions of the subunit for different targets, where the | |
27761 | build script selects the right one to give to the compiler. | |
27762 | @cindex Subunits (and conditional compilation) | |
27763 | ||
27764 | As an example, consider a situation where a new feature in Ada 2005 | |
27765 | allows something to be done in a really nice way. But your code must be able | |
27766 | to compile with an Ada 95 compiler. Conceptually you want to say: | |
27767 | ||
27768 | @smallexample @c ada | |
27769 | @group | |
27770 | if Ada_2005 then | |
d488f6ea | 27771 | @dots{} neat Ada 2005 code |
c690a2ec | 27772 | else |
d488f6ea | 27773 | @dots{} not quite as neat Ada 95 code |
c690a2ec RD |
27774 | end if; |
27775 | @end group | |
27776 | @end smallexample | |
27777 | ||
27778 | @noindent | |
27779 | where @code{Ada_2005} is a Boolean constant. | |
27780 | ||
27781 | But this won't work when @code{Ada_2005} is set to @code{False}, | |
27782 | since the @code{then} clause will be illegal for an Ada 95 compiler. | |
27783 | (Recall that although such unreachable code would eventually be deleted | |
27784 | by the compiler, it still needs to be legal. If it uses features | |
27785 | introduced in Ada 2005, it will be illegal in Ada 95.) | |
27786 | ||
27787 | So instead we write | |
27788 | ||
27789 | @smallexample @c ada | |
27790 | procedure Insert is separate; | |
27791 | @end smallexample | |
27792 | ||
27793 | @noindent | |
27794 | Then we have two files for the subunit @code{Insert}, with the two sets of | |
27795 | code. | |
27796 | If the package containing this is called @code{File_Queries}, then we might | |
27797 | have two files | |
27798 | ||
27799 | @itemize @bullet | |
27800 | @item @file{file_queries-insert-2005.adb} | |
27801 | @item @file{file_queries-insert-95.adb} | |
27802 | @end itemize | |
27803 | ||
27804 | @noindent | |
27805 | and the build script renames the appropriate file to | |
27806 | ||
27807 | @smallexample | |
27808 | file_queries-insert.adb | |
27809 | @end smallexample | |
27810 | ||
27811 | @noindent | |
27812 | and then carries out the compilation. | |
27813 | ||
27814 | This can also be done with project files' naming schemes. For example: | |
27815 | ||
27816 | @smallexample @c project | |
27817 | For Body ("File_Queries.Insert") use "file_queries-insert-2005.ada"; | |
27818 | @end smallexample | |
27819 | ||
27820 | @noindent | |
27821 | Note also that with project files it is desirable to use a different extension | |
e69044cb | 27822 | than @file{ads} / @file{adb} for alternative versions. Otherwise a naming |
c690a2ec RD |
27823 | conflict may arise through another commonly used feature: to declare as part |
27824 | of the project a set of directories containing all the sources obeying the | |
27825 | default naming scheme. | |
27826 | ||
27827 | The use of alternative units is certainly feasible in all situations, | |
27828 | and for example the Ada part of the GNAT run-time is conditionalized | |
27829 | based on the target architecture using this approach. As a specific example, | |
27830 | consider the implementation of the AST feature in VMS. There is one | |
27831 | spec: | |
27832 | ||
27833 | @smallexample | |
27834 | s-asthan.ads | |
27835 | @end smallexample | |
27836 | ||
27837 | @noindent | |
27838 | which is the same for all architectures, and three bodies: | |
27839 | ||
27840 | @table @file | |
27841 | @item s-asthan.adb | |
27842 | used for all non-VMS operating systems | |
27843 | @item s-asthan-vms-alpha.adb | |
27844 | used for VMS on the Alpha | |
27845 | @item s-asthan-vms-ia64.adb | |
27846 | used for VMS on the ia64 | |
27847 | @end table | |
27848 | ||
27849 | @noindent | |
27850 | The dummy version @file{s-asthan.adb} simply raises exceptions noting that | |
27851 | this operating system feature is not available, and the two remaining | |
27852 | versions interface with the corresponding versions of VMS to provide | |
27853 | VMS-compatible AST handling. The GNAT build script knows the architecture | |
27854 | and operating system, and automatically selects the right version, | |
27855 | renaming it if necessary to @file{s-asthan.adb} before the run-time build. | |
27856 | ||
27857 | Another style for arranging alternative implementations is through Ada's | |
27858 | access-to-subprogram facility. | |
27859 | In case some functionality is to be conditionally included, | |
27860 | you can declare an access-to-procedure variable @code{Ref} that is initialized | |
27861 | to designate a ``do nothing'' procedure, and then invoke @code{Ref.all} | |
27862 | when appropriate. | |
27863 | In some library package, set @code{Ref} to @code{Proc'Access} for some | |
27864 | procedure @code{Proc} that performs the relevant processing. | |
27865 | The initialization only occurs if the library package is included in the | |
27866 | program. | |
27867 | The same idea can also be implemented using tagged types and dispatching | |
27868 | calls. | |
27869 | ||
27870 | ||
27871 | @node Preprocessing | |
27872 | @section Preprocessing | |
27873 | @cindex Preprocessing | |
27874 | ||
27875 | @noindent | |
27876 | Although it is quite possible to conditionalize code without the use of | |
27877 | C-style preprocessing, as described earlier in this section, it is | |
27878 | nevertheless convenient in some cases to use the C approach. Moreover, | |
27879 | older Ada compilers have often provided some preprocessing capability, | |
27880 | so legacy code may depend on this approach, even though it is not | |
27881 | standard. | |
27882 | ||
27883 | To accommodate such use, GNAT provides a preprocessor (modeled to a large | |
27884 | extent on the various preprocessors that have been used | |
27885 | with legacy code on other compilers, to enable easier transition). | |
27886 | ||
27887 | The preprocessor may be used in two separate modes. It can be used quite | |
27888 | separately from the compiler, to generate a separate output source file | |
27889 | that is then fed to the compiler as a separate step. This is the | |
27890 | @code{gnatprep} utility, whose use is fully described in | |
c2658843 | 27891 | @ref{Preprocessing with gnatprep}. |
c690a2ec RD |
27892 | @cindex @code{gnatprep} |
27893 | ||
27894 | The preprocessing language allows such constructs as | |
27895 | ||
27896 | @smallexample | |
27897 | @group | |
5c211bfd | 27898 | #if DEBUG or else (PRIORITY > 4) then |
c690a2ec RD |
27899 | bunch of declarations |
27900 | #else | |
27901 | completely different bunch of declarations | |
27902 | #end if; | |
27903 | @end group | |
27904 | @end smallexample | |
27905 | ||
27906 | @noindent | |
27907 | The values of the symbols @code{DEBUG} and @code{PRIORITY} can be | |
27908 | defined either on the command line or in a separate file. | |
27909 | ||
27910 | The other way of running the preprocessor is even closer to the C style and | |
27911 | often more convenient. In this approach the preprocessing is integrated into | |
27912 | the compilation process. The compiler is fed the preprocessor input which | |
27913 | includes @code{#if} lines etc, and then the compiler carries out the | |
27914 | preprocessing internally and processes the resulting output. | |
27915 | For more details on this approach, see @ref{Integrated Preprocessing}. | |
27916 | ||
27917 | ||
27918 | @c ******************************* | |
7cd4527e AC |
27919 | @node Inline Assembler |
27920 | @appendix Inline Assembler | |
c690a2ec | 27921 | @c ******************************* |
88e1739c FW |
27922 | |
27923 | @noindent | |
7cd4527e AC |
27924 | If you need to write low-level software that interacts directly |
27925 | with the hardware, Ada provides two ways to incorporate assembly | |
27926 | language code into your program. First, you can import and invoke | |
27927 | external routines written in assembly language, an Ada feature fully | |
e08b38f5 | 27928 | supported by GNAT@. However, for small sections of code it may be simpler |
7cd4527e AC |
27929 | or more efficient to include assembly language statements directly |
27930 | in your Ada source program, using the facilities of the implementation-defined | |
27931 | package @code{System.Machine_Code}, which incorporates the gcc | |
27932 | Inline Assembler. The Inline Assembler approach offers a number of advantages, | |
27933 | including the following: | |
88e1739c FW |
27934 | |
27935 | @itemize @bullet | |
7cd4527e AC |
27936 | @item No need to use non-Ada tools |
27937 | @item Consistent interface over different targets | |
27938 | @item Automatic usage of the proper calling conventions | |
27939 | @item Access to Ada constants and variables | |
27940 | @item Definition of intrinsic routines | |
27941 | @item Possibility of inlining a subprogram comprising assembler code | |
27942 | @item Code optimizer can take Inline Assembler code into account | |
88e1739c FW |
27943 | @end itemize |
27944 | ||
7cd4527e AC |
27945 | This chapter presents a series of examples to show you how to use |
27946 | the Inline Assembler. Although it focuses on the Intel x86, | |
27947 | the general approach applies also to other processors. | |
27948 | It is assumed that you are familiar with Ada | |
27949 | and with assembly language programming. | |
88e1739c FW |
27950 | |
27951 | @menu | |
7cd4527e AC |
27952 | * Basic Assembler Syntax:: |
27953 | * A Simple Example of Inline Assembler:: | |
27954 | * Output Variables in Inline Assembler:: | |
27955 | * Input Variables in Inline Assembler:: | |
27956 | * Inlining Inline Assembler Code:: | |
27957 | * Other Asm Functionality:: | |
88e1739c FW |
27958 | @end menu |
27959 | ||
7cd4527e AC |
27960 | @c --------------------------------------------------------------------------- |
27961 | @node Basic Assembler Syntax | |
27962 | @section Basic Assembler Syntax | |
27963 | ||
88e1739c | 27964 | @noindent |
7cd4527e AC |
27965 | The assembler used by GNAT and gcc is based not on the Intel assembly |
27966 | language, but rather on a language that descends from the AT&T Unix | |
27967 | assembler @emph{as} (and which is often referred to as ``AT&T syntax''). | |
27968 | The following table summarizes the main features of @emph{as} syntax | |
27969 | and points out the differences from the Intel conventions. | |
27970 | See the gcc @emph{as} and @emph{gas} (an @emph{as} macro | |
27971 | pre-processor) documentation for further information. | |
88e1739c | 27972 | |
7cd4527e AC |
27973 | @table @asis |
27974 | @item Register names | |
27975 | gcc / @emph{as}: Prefix with ``%''; for example @code{%eax} | |
27976 | @* | |
27977 | Intel: No extra punctuation; for example @code{eax} | |
88e1739c | 27978 | |
7cd4527e AC |
27979 | @item Immediate operand |
27980 | gcc / @emph{as}: Prefix with ``$''; for example @code{$4} | |
27981 | @* | |
27982 | Intel: No extra punctuation; for example @code{4} | |
88e1739c | 27983 | |
7cd4527e AC |
27984 | @item Address |
27985 | gcc / @emph{as}: Prefix with ``$''; for example @code{$loc} | |
27986 | @* | |
27987 | Intel: No extra punctuation; for example @code{loc} | |
88e1739c | 27988 | |
7cd4527e AC |
27989 | @item Memory contents |
27990 | gcc / @emph{as}: No extra punctuation; for example @code{loc} | |
27991 | @* | |
27992 | Intel: Square brackets; for example @code{[loc]} | |
27993 | ||
27994 | @item Register contents | |
27995 | gcc / @emph{as}: Parentheses; for example @code{(%eax)} | |
27996 | @* | |
27997 | Intel: Square brackets; for example @code{[eax]} | |
27998 | ||
27999 | @item Hexadecimal numbers | |
28000 | gcc / @emph{as}: Leading ``0x'' (C language syntax); for example @code{0xA0} | |
28001 | @* | |
28002 | Intel: Trailing ``h''; for example @code{A0h} | |
28003 | ||
28004 | @item Operand size | |
28005 | gcc / @emph{as}: Explicit in op code; for example @code{movw} to move | |
28006 | a 16-bit word | |
28007 | @* | |
28008 | Intel: Implicit, deduced by assembler; for example @code{mov} | |
28009 | ||
28010 | @item Instruction repetition | |
28011 | gcc / @emph{as}: Split into two lines; for example | |
28012 | @* | |
28013 | @code{rep} | |
28014 | @* | |
28015 | @code{stosl} | |
28016 | @* | |
28017 | Intel: Keep on one line; for example @code{rep stosl} | |
28018 | ||
28019 | @item Order of operands | |
28020 | gcc / @emph{as}: Source first; for example @code{movw $4, %eax} | |
28021 | @* | |
28022 | Intel: Destination first; for example @code{mov eax, 4} | |
88e1739c FW |
28023 | @end table |
28024 | ||
7cd4527e AC |
28025 | @c --------------------------------------------------------------------------- |
28026 | @node A Simple Example of Inline Assembler | |
28027 | @section A Simple Example of Inline Assembler | |
88e1739c FW |
28028 | |
28029 | @noindent | |
7cd4527e AC |
28030 | The following example will generate a single assembly language statement, |
28031 | @code{nop}, which does nothing. Despite its lack of run-time effect, | |
28032 | the example will be useful in illustrating the basics of | |
28033 | the Inline Assembler facility. | |
28034 | ||
28035 | @smallexample @c ada | |
28036 | @group | |
28037 | with System.Machine_Code; use System.Machine_Code; | |
28038 | procedure Nothing is | |
28039 | begin | |
28040 | Asm ("nop"); | |
28041 | end Nothing; | |
28042 | @end group | |
28043 | @end smallexample | |
88e1739c | 28044 | |
7cd4527e AC |
28045 | @code{Asm} is a procedure declared in package @code{System.Machine_Code}; |
28046 | here it takes one parameter, a @emph{template string} that must be a static | |
28047 | expression and that will form the generated instruction. | |
28048 | @code{Asm} may be regarded as a compile-time procedure that parses | |
28049 | the template string and additional parameters (none here), | |
28050 | from which it generates a sequence of assembly language instructions. | |
88e1739c | 28051 | |
7cd4527e AC |
28052 | The examples in this chapter will illustrate several of the forms |
28053 | for invoking @code{Asm}; a complete specification of the syntax | |
b2e74434 RW |
28054 | is found in @ref{Machine Code Insertions,,, gnat_rm, GNAT Reference |
28055 | Manual}. | |
7cd4527e AC |
28056 | |
28057 | Under the standard GNAT conventions, the @code{Nothing} procedure | |
28058 | should be in a file named @file{nothing.adb}. | |
28059 | You can build the executable in the usual way: | |
28060 | @smallexample | |
28061 | gnatmake nothing | |
28062 | @end smallexample | |
28063 | However, the interesting aspect of this example is not its run-time behavior | |
28064 | but rather the generated assembly code. | |
28065 | To see this output, invoke the compiler as follows: | |
28066 | @smallexample | |
28067 | gcc -c -S -fomit-frame-pointer -gnatp @file{nothing.adb} | |
28068 | @end smallexample | |
28069 | where the options are: | |
88e1739c | 28070 | |
7cd4527e AC |
28071 | @table @code |
28072 | @item -c | |
28073 | compile only (no bind or link) | |
28074 | @item -S | |
28075 | generate assembler listing | |
28076 | @item -fomit-frame-pointer | |
28077 | do not set up separate stack frames | |
28078 | @item -gnatp | |
28079 | do not add runtime checks | |
28080 | @end table | |
88e1739c | 28081 | |
7cd4527e AC |
28082 | This gives a human-readable assembler version of the code. The resulting |
28083 | file will have the same name as the Ada source file, but with a @code{.s} | |
28084 | extension. In our example, the file @file{nothing.s} has the following | |
28085 | contents: | |
88e1739c | 28086 | |
7cd4527e AC |
28087 | @smallexample |
28088 | @group | |
28089 | .file "nothing.adb" | |
28090 | gcc2_compiled.: | |
28091 | ___gnu_compiled_ada: | |
28092 | .text | |
28093 | .align 4 | |
28094 | .globl __ada_nothing | |
28095 | __ada_nothing: | |
28096 | #APP | |
28097 | nop | |
28098 | #NO_APP | |
28099 | jmp L1 | |
28100 | .align 2,0x90 | |
28101 | L1: | |
28102 | ret | |
28103 | @end group | |
28104 | @end smallexample | |
88e1739c | 28105 | |
7cd4527e AC |
28106 | The assembly code you included is clearly indicated by |
28107 | the compiler, between the @code{#APP} and @code{#NO_APP} | |
28108 | delimiters. The character before the 'APP' and 'NOAPP' | |
28109 | can differ on different targets. For example, GNU/Linux uses '#APP' while | |
28110 | on NT you will see '/APP'. | |
88e1739c | 28111 | |
7cd4527e AC |
28112 | If you make a mistake in your assembler code (such as using the |
28113 | wrong size modifier, or using a wrong operand for the instruction) GNAT | |
28114 | will report this error in a temporary file, which will be deleted when | |
28115 | the compilation is finished. Generating an assembler file will help | |
28116 | in such cases, since you can assemble this file separately using the | |
28117 | @emph{as} assembler that comes with gcc. | |
88e1739c | 28118 | |
7cd4527e | 28119 | Assembling the file using the command |
88e1739c | 28120 | |
7cd4527e AC |
28121 | @smallexample |
28122 | as @file{nothing.s} | |
28123 | @end smallexample | |
88e1739c | 28124 | @noindent |
7cd4527e AC |
28125 | will give you error messages whose lines correspond to the assembler |
28126 | input file, so you can easily find and correct any mistakes you made. | |
28127 | If there are no errors, @emph{as} will generate an object file | |
28128 | @file{nothing.out}. | |
88e1739c | 28129 | |
7cd4527e AC |
28130 | @c --------------------------------------------------------------------------- |
28131 | @node Output Variables in Inline Assembler | |
28132 | @section Output Variables in Inline Assembler | |
88e1739c | 28133 | |
7cd4527e AC |
28134 | @noindent |
28135 | The examples in this section, showing how to access the processor flags, | |
28136 | illustrate how to specify the destination operands for assembly language | |
28137 | statements. | |
88e1739c | 28138 | |
7cd4527e AC |
28139 | @smallexample @c ada |
28140 | @group | |
28141 | with Interfaces; use Interfaces; | |
28142 | with Ada.Text_IO; use Ada.Text_IO; | |
28143 | with System.Machine_Code; use System.Machine_Code; | |
28144 | procedure Get_Flags is | |
28145 | Flags : Unsigned_32; | |
28146 | use ASCII; | |
28147 | begin | |
28148 | Asm ("pushfl" & LF & HT & -- push flags on stack | |
28149 | "popl %%eax" & LF & HT & -- load eax with flags | |
28150 | "movl %%eax, %0", -- store flags in variable | |
28151 | Outputs => Unsigned_32'Asm_Output ("=g", Flags)); | |
28152 | Put_Line ("Flags register:" & Flags'Img); | |
28153 | end Get_Flags; | |
28154 | @end group | |
28155 | @end smallexample | |
88e1739c | 28156 | |
7cd4527e AC |
28157 | In order to have a nicely aligned assembly listing, we have separated |
28158 | multiple assembler statements in the Asm template string with linefeed | |
28159 | (ASCII.LF) and horizontal tab (ASCII.HT) characters. | |
28160 | The resulting section of the assembly output file is: | |
88e1739c FW |
28161 | |
28162 | @smallexample | |
7cd4527e AC |
28163 | @group |
28164 | #APP | |
28165 | pushfl | |
28166 | popl %eax | |
28167 | movl %eax, -40(%ebp) | |
28168 | #NO_APP | |
28169 | @end group | |
88e1739c FW |
28170 | @end smallexample |
28171 | ||
7cd4527e | 28172 | It would have been legal to write the Asm invocation as: |
88e1739c | 28173 | |
7cd4527e AC |
28174 | @smallexample |
28175 | Asm ("pushfl popl %%eax movl %%eax, %0") | |
28176 | @end smallexample | |
88e1739c | 28177 | |
7cd4527e | 28178 | but in the generated assembler file, this would come out as: |
88e1739c | 28179 | |
7cd4527e AC |
28180 | @smallexample |
28181 | #APP | |
28182 | pushfl popl %eax movl %eax, -40(%ebp) | |
28183 | #NO_APP | |
28184 | @end smallexample | |
88e1739c | 28185 | |
7cd4527e | 28186 | which is not so convenient for the human reader. |
88e1739c | 28187 | |
7cd4527e AC |
28188 | We use Ada comments |
28189 | at the end of each line to explain what the assembler instructions | |
28190 | actually do. This is a useful convention. | |
88e1739c | 28191 | |
7cd4527e AC |
28192 | When writing Inline Assembler instructions, you need to precede each register |
28193 | and variable name with a percent sign. Since the assembler already requires | |
28194 | a percent sign at the beginning of a register name, you need two consecutive | |
28195 | percent signs for such names in the Asm template string, thus @code{%%eax}. | |
28196 | In the generated assembly code, one of the percent signs will be stripped off. | |
88e1739c | 28197 | |
7cd4527e AC |
28198 | Names such as @code{%0}, @code{%1}, @code{%2}, etc., denote input or output |
28199 | variables: operands you later define using @code{Input} or @code{Output} | |
28200 | parameters to @code{Asm}. | |
28201 | An output variable is illustrated in | |
28202 | the third statement in the Asm template string: | |
28203 | @smallexample | |
28204 | movl %%eax, %0 | |
28205 | @end smallexample | |
28206 | The intent is to store the contents of the eax register in a variable that can | |
28207 | be accessed in Ada. Simply writing @code{movl %%eax, Flags} would not | |
28208 | necessarily work, since the compiler might optimize by using a register | |
28209 | to hold Flags, and the expansion of the @code{movl} instruction would not be | |
28210 | aware of this optimization. The solution is not to store the result directly | |
28211 | but rather to advise the compiler to choose the correct operand form; | |
28212 | that is the purpose of the @code{%0} output variable. | |
88e1739c | 28213 | |
7cd4527e AC |
28214 | Information about the output variable is supplied in the @code{Outputs} |
28215 | parameter to @code{Asm}: | |
28216 | @smallexample | |
28217 | Outputs => Unsigned_32'Asm_Output ("=g", Flags)); | |
28218 | @end smallexample | |
88e1739c | 28219 | |
7cd4527e AC |
28220 | The output is defined by the @code{Asm_Output} attribute of the target type; |
28221 | the general format is | |
28222 | @smallexample | |
28223 | Type'Asm_Output (constraint_string, variable_name) | |
28224 | @end smallexample | |
88e1739c | 28225 | |
7cd4527e AC |
28226 | The constraint string directs the compiler how |
28227 | to store/access the associated variable. In the example | |
28228 | @smallexample | |
28229 | Unsigned_32'Asm_Output ("=m", Flags); | |
28230 | @end smallexample | |
28231 | the @code{"m"} (memory) constraint tells the compiler that the variable | |
28232 | @code{Flags} should be stored in a memory variable, thus preventing | |
28233 | the optimizer from keeping it in a register. In contrast, | |
28234 | @smallexample | |
28235 | Unsigned_32'Asm_Output ("=r", Flags); | |
28236 | @end smallexample | |
28237 | uses the @code{"r"} (register) constraint, telling the compiler to | |
28238 | store the variable in a register. | |
88e1739c | 28239 | |
7cd4527e AC |
28240 | If the constraint is preceded by the equal character (@strong{=}), it tells |
28241 | the compiler that the variable will be used to store data into it. | |
88e1739c | 28242 | |
7cd4527e AC |
28243 | In the @code{Get_Flags} example, we used the @code{"g"} (global) constraint, |
28244 | allowing the optimizer to choose whatever it deems best. | |
88e1739c | 28245 | |
7cd4527e AC |
28246 | There are a fairly large number of constraints, but the ones that are |
28247 | most useful (for the Intel x86 processor) are the following: | |
88e1739c | 28248 | |
7cd4527e AC |
28249 | @table @code |
28250 | @item = | |
28251 | output constraint | |
28252 | @item g | |
8dd07840 | 28253 | global (i.e.@: can be stored anywhere) |
7cd4527e AC |
28254 | @item m |
28255 | in memory | |
28256 | @item I | |
28257 | a constant | |
28258 | @item a | |
28259 | use eax | |
28260 | @item b | |
28261 | use ebx | |
28262 | @item c | |
28263 | use ecx | |
28264 | @item d | |
28265 | use edx | |
28266 | @item S | |
28267 | use esi | |
28268 | @item D | |
28269 | use edi | |
28270 | @item r | |
28271 | use one of eax, ebx, ecx or edx | |
28272 | @item q | |
28273 | use one of eax, ebx, ecx, edx, esi or edi | |
28274 | @end table | |
88e1739c | 28275 | |
7cd4527e AC |
28276 | The full set of constraints is described in the gcc and @emph{as} |
28277 | documentation; note that it is possible to combine certain constraints | |
28278 | in one constraint string. | |
88e1739c | 28279 | |
7cd4527e AC |
28280 | You specify the association of an output variable with an assembler operand |
28281 | through the @code{%}@emph{n} notation, where @emph{n} is a non-negative | |
28282 | integer. Thus in | |
28283 | @smallexample @c ada | |
28284 | @group | |
28285 | Asm ("pushfl" & LF & HT & -- push flags on stack | |
28286 | "popl %%eax" & LF & HT & -- load eax with flags | |
28287 | "movl %%eax, %0", -- store flags in variable | |
28288 | Outputs => Unsigned_32'Asm_Output ("=g", Flags)); | |
28289 | @end group | |
28290 | @end smallexample | |
88e1739c | 28291 | @noindent |
7cd4527e AC |
28292 | @code{%0} will be replaced in the expanded code by the appropriate operand, |
28293 | whatever | |
28294 | the compiler decided for the @code{Flags} variable. | |
88e1739c | 28295 | |
7cd4527e | 28296 | In general, you may have any number of output variables: |
88e1739c FW |
28297 | @itemize @bullet |
28298 | @item | |
7cd4527e | 28299 | Count the operands starting at 0; thus @code{%0}, @code{%1}, etc. |
88e1739c | 28300 | @item |
7cd4527e AC |
28301 | Specify the @code{Outputs} parameter as a parenthesized comma-separated list |
28302 | of @code{Asm_Output} attributes | |
88e1739c FW |
28303 | @end itemize |
28304 | ||
7cd4527e AC |
28305 | For example: |
28306 | @smallexample @c ada | |
28307 | @group | |
28308 | Asm ("movl %%eax, %0" & LF & HT & | |
28309 | "movl %%ebx, %1" & LF & HT & | |
28310 | "movl %%ecx, %2", | |
28311 | Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A | |
28312 | Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B | |
28313 | Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C | |
28314 | @end group | |
28315 | @end smallexample | |
88e1739c | 28316 | @noindent |
7cd4527e AC |
28317 | where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables |
28318 | in the Ada program. | |
88e1739c | 28319 | |
7cd4527e AC |
28320 | As a variation on the @code{Get_Flags} example, we can use the constraints |
28321 | string to direct the compiler to store the eax register into the @code{Flags} | |
28322 | variable, instead of including the store instruction explicitly in the | |
28323 | @code{Asm} template string: | |
88e1739c | 28324 | |
7cd4527e AC |
28325 | @smallexample @c ada |
28326 | @group | |
28327 | with Interfaces; use Interfaces; | |
28328 | with Ada.Text_IO; use Ada.Text_IO; | |
28329 | with System.Machine_Code; use System.Machine_Code; | |
28330 | procedure Get_Flags_2 is | |
28331 | Flags : Unsigned_32; | |
28332 | use ASCII; | |
28333 | begin | |
28334 | Asm ("pushfl" & LF & HT & -- push flags on stack | |
28335 | "popl %%eax", -- save flags in eax | |
28336 | Outputs => Unsigned_32'Asm_Output ("=a", Flags)); | |
28337 | Put_Line ("Flags register:" & Flags'Img); | |
28338 | end Get_Flags_2; | |
28339 | @end group | |
88e1739c FW |
28340 | @end smallexample |
28341 | ||
28342 | @noindent | |
7cd4527e AC |
28343 | The @code{"a"} constraint tells the compiler that the @code{Flags} |
28344 | variable will come from the eax register. Here is the resulting code: | |
88e1739c FW |
28345 | |
28346 | @smallexample | |
28347 | @group | |
7cd4527e AC |
28348 | #APP |
28349 | pushfl | |
28350 | popl %eax | |
28351 | #NO_APP | |
28352 | movl %eax,-40(%ebp) | |
88e1739c FW |
28353 | @end group |
28354 | @end smallexample | |
28355 | ||
28356 | @noindent | |
7cd4527e AC |
28357 | The compiler generated the store of eax into Flags after |
28358 | expanding the assembler code. | |
88e1739c | 28359 | |
7cd4527e AC |
28360 | Actually, there was no need to pop the flags into the eax register; |
28361 | more simply, we could just pop the flags directly into the program variable: | |
88e1739c | 28362 | |
7cd4527e AC |
28363 | @smallexample @c ada |
28364 | @group | |
28365 | with Interfaces; use Interfaces; | |
28366 | with Ada.Text_IO; use Ada.Text_IO; | |
28367 | with System.Machine_Code; use System.Machine_Code; | |
28368 | procedure Get_Flags_3 is | |
28369 | Flags : Unsigned_32; | |
28370 | use ASCII; | |
28371 | begin | |
28372 | Asm ("pushfl" & LF & HT & -- push flags on stack | |
28373 | "pop %0", -- save flags in Flags | |
28374 | Outputs => Unsigned_32'Asm_Output ("=g", Flags)); | |
28375 | Put_Line ("Flags register:" & Flags'Img); | |
28376 | end Get_Flags_3; | |
28377 | @end group | |
28378 | @end smallexample | |
28379 | ||
28380 | @c --------------------------------------------------------------------------- | |
28381 | @node Input Variables in Inline Assembler | |
28382 | @section Input Variables in Inline Assembler | |
88e1739c FW |
28383 | |
28384 | @noindent | |
7cd4527e AC |
28385 | The example in this section illustrates how to specify the source operands |
28386 | for assembly language statements. | |
28387 | The program simply increments its input value by 1: | |
88e1739c | 28388 | |
7cd4527e AC |
28389 | @smallexample @c ada |
28390 | @group | |
28391 | with Interfaces; use Interfaces; | |
28392 | with Ada.Text_IO; use Ada.Text_IO; | |
28393 | with System.Machine_Code; use System.Machine_Code; | |
28394 | procedure Increment is | |
88e1739c | 28395 | |
7cd4527e AC |
28396 | function Incr (Value : Unsigned_32) return Unsigned_32 is |
28397 | Result : Unsigned_32; | |
28398 | begin | |
28399 | Asm ("incl %0", | |
3777b2c0 AC |
28400 | Outputs => Unsigned_32'Asm_Output ("=a", Result), |
28401 | Inputs => Unsigned_32'Asm_Input ("a", Value)); | |
7cd4527e AC |
28402 | return Result; |
28403 | end Incr; | |
88e1739c | 28404 | |
7cd4527e AC |
28405 | Value : Unsigned_32; |
28406 | ||
28407 | begin | |
28408 | Value := 5; | |
28409 | Put_Line ("Value before is" & Value'Img); | |
28410 | Value := Incr (Value); | |
28411 | Put_Line ("Value after is" & Value'Img); | |
28412 | end Increment; | |
28413 | @end group | |
88e1739c FW |
28414 | @end smallexample |
28415 | ||
7cd4527e AC |
28416 | The @code{Outputs} parameter to @code{Asm} specifies |
28417 | that the result will be in the eax register and that it is to be stored | |
28418 | in the @code{Result} variable. | |
28419 | ||
28420 | The @code{Inputs} parameter looks much like the @code{Outputs} parameter, | |
28421 | but with an @code{Asm_Input} attribute. | |
28422 | The @code{"="} constraint, indicating an output value, is not present. | |
28423 | ||
28424 | You can have multiple input variables, in the same way that you can have more | |
28425 | than one output variable. | |
28426 | ||
3777b2c0 AC |
28427 | The parameter count (%0, %1) etc, still starts at the first output statement, |
28428 | and continues with the input statements. | |
7cd4527e AC |
28429 | |
28430 | Just as the @code{Outputs} parameter causes the register to be stored into the | |
28431 | target variable after execution of the assembler statements, so does the | |
28432 | @code{Inputs} parameter cause its variable to be loaded into the register | |
28433 | before execution of the assembler statements. | |
28434 | ||
28435 | Thus the effect of the @code{Asm} invocation is: | |
28436 | @enumerate | |
28437 | @item load the 32-bit value of @code{Value} into eax | |
28438 | @item execute the @code{incl %eax} instruction | |
28439 | @item store the contents of eax into the @code{Result} variable | |
28440 | @end enumerate | |
88e1739c | 28441 | |
7cd4527e | 28442 | The resulting assembler file (with @option{-O2} optimization) contains: |
88e1739c FW |
28443 | @smallexample |
28444 | @group | |
7cd4527e AC |
28445 | _increment__incr.1: |
28446 | subl $4,%esp | |
28447 | movl 8(%esp),%eax | |
28448 | #APP | |
28449 | incl %eax | |
28450 | #NO_APP | |
28451 | movl %eax,%edx | |
28452 | movl %ecx,(%esp) | |
28453 | addl $4,%esp | |
28454 | ret | |
88e1739c FW |
28455 | @end group |
28456 | @end smallexample | |
28457 | ||
7cd4527e AC |
28458 | @c --------------------------------------------------------------------------- |
28459 | @node Inlining Inline Assembler Code | |
28460 | @section Inlining Inline Assembler Code | |
28461 | ||
88e1739c | 28462 | @noindent |
7cd4527e AC |
28463 | For a short subprogram such as the @code{Incr} function in the previous |
28464 | section, the overhead of the call and return (creating / deleting the stack | |
28465 | frame) can be significant, compared to the amount of code in the subprogram | |
28466 | body. A solution is to apply Ada's @code{Inline} pragma to the subprogram, | |
28467 | which directs the compiler to expand invocations of the subprogram at the | |
28468 | point(s) of call, instead of setting up a stack frame for out-of-line calls. | |
28469 | Here is the resulting program: | |
88e1739c | 28470 | |
7cd4527e | 28471 | @smallexample @c ada |
88e1739c | 28472 | @group |
7cd4527e AC |
28473 | with Interfaces; use Interfaces; |
28474 | with Ada.Text_IO; use Ada.Text_IO; | |
28475 | with System.Machine_Code; use System.Machine_Code; | |
28476 | procedure Increment_2 is | |
28477 | ||
28478 | function Incr (Value : Unsigned_32) return Unsigned_32 is | |
28479 | Result : Unsigned_32; | |
28480 | begin | |
28481 | Asm ("incl %0", | |
3777b2c0 AC |
28482 | Outputs => Unsigned_32'Asm_Output ("=a", Result), |
28483 | Inputs => Unsigned_32'Asm_Input ("a", Value)); | |
7cd4527e AC |
28484 | return Result; |
28485 | end Incr; | |
28486 | pragma Inline (Increment); | |
28487 | ||
28488 | Value : Unsigned_32; | |
28489 | ||
28490 | begin | |
28491 | Value := 5; | |
28492 | Put_Line ("Value before is" & Value'Img); | |
28493 | Value := Increment (Value); | |
28494 | Put_Line ("Value after is" & Value'Img); | |
28495 | end Increment_2; | |
88e1739c FW |
28496 | @end group |
28497 | @end smallexample | |
28498 | ||
7cd4527e | 28499 | Compile the program with both optimization (@option{-O2}) and inlining |
1a5f40e1 | 28500 | (@option{-gnatn}) enabled. |
7cd4527e AC |
28501 | |
28502 | The @code{Incr} function is still compiled as usual, but at the | |
28503 | point in @code{Increment} where our function used to be called: | |
88e1739c FW |
28504 | |
28505 | @smallexample | |
28506 | @group | |
7cd4527e AC |
28507 | pushl %edi |
28508 | call _increment__incr.1 | |
88e1739c FW |
28509 | @end group |
28510 | @end smallexample | |
28511 | ||
28512 | @noindent | |
7cd4527e AC |
28513 | the code for the function body directly appears: |
28514 | ||
28515 | @smallexample | |
28516 | @group | |
28517 | movl %esi,%eax | |
28518 | #APP | |
28519 | incl %eax | |
28520 | #NO_APP | |
28521 | movl %eax,%edx | |
28522 | @end group | |
28523 | @end smallexample | |
88e1739c FW |
28524 | |
28525 | @noindent | |
7cd4527e | 28526 | thus saving the overhead of stack frame setup and an out-of-line call. |
88e1739c | 28527 | |
7cd4527e AC |
28528 | @c --------------------------------------------------------------------------- |
28529 | @node Other Asm Functionality | |
28530 | @section Other @code{Asm} Functionality | |
88e1739c FW |
28531 | |
28532 | @noindent | |
7cd4527e AC |
28533 | This section describes two important parameters to the @code{Asm} |
28534 | procedure: @code{Clobber}, which identifies register usage; | |
28535 | and @code{Volatile}, which inhibits unwanted optimizations. | |
88e1739c | 28536 | |
7cd4527e AC |
28537 | @menu |
28538 | * The Clobber Parameter:: | |
28539 | * The Volatile Parameter:: | |
28540 | @end menu | |
28541 | ||
28542 | @c --------------------------------------------------------------------------- | |
28543 | @node The Clobber Parameter | |
28544 | @subsection The @code{Clobber} Parameter | |
88e1739c FW |
28545 | |
28546 | @noindent | |
7cd4527e AC |
28547 | One of the dangers of intermixing assembly language and a compiled language |
28548 | such as Ada is that the compiler needs to be aware of which registers are | |
28549 | being used by the assembly code. In some cases, such as the earlier examples, | |
28550 | the constraint string is sufficient to indicate register usage (e.g., | |
28551 | @code{"a"} for | |
28552 | the eax register). But more generally, the compiler needs an explicit | |
28553 | identification of the registers that are used by the Inline Assembly | |
28554 | statements. | |
88e1739c | 28555 | |
7cd4527e AC |
28556 | Using a register that the compiler doesn't know about |
28557 | could be a side effect of an instruction (like @code{mull} | |
28558 | storing its result in both eax and edx). | |
28559 | It can also arise from explicit register usage in your | |
28560 | assembly code; for example: | |
88e1739c FW |
28561 | @smallexample |
28562 | @group | |
7cd4527e AC |
28563 | Asm ("movl %0, %%ebx" & LF & HT & |
28564 | "movl %%ebx, %1", | |
3777b2c0 AC |
28565 | Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), |
28566 | Inputs => Unsigned_32'Asm_Input ("g", Var_In)); | |
88e1739c FW |
28567 | @end group |
28568 | @end smallexample | |
88e1739c | 28569 | @noindent |
7cd4527e AC |
28570 | where the compiler (since it does not analyze the @code{Asm} template string) |
28571 | does not know you are using the ebx register. | |
88e1739c | 28572 | |
7cd4527e AC |
28573 | In such cases you need to supply the @code{Clobber} parameter to @code{Asm}, |
28574 | to identify the registers that will be used by your assembly code: | |
28575 | ||
28576 | @smallexample | |
28577 | @group | |
28578 | Asm ("movl %0, %%ebx" & LF & HT & | |
28579 | "movl %%ebx, %1", | |
7cd4527e | 28580 | Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), |
3777b2c0 | 28581 | Inputs => Unsigned_32'Asm_Input ("g", Var_In), |
7cd4527e AC |
28582 | Clobber => "ebx"); |
28583 | @end group | |
28584 | @end smallexample | |
88e1739c | 28585 | |
7cd4527e AC |
28586 | The Clobber parameter is a static string expression specifying the |
28587 | register(s) you are using. Note that register names are @emph{not} prefixed | |
28588 | by a percent sign. Also, if more than one register is used then their names | |
28589 | are separated by commas; e.g., @code{"eax, ebx"} | |
28590 | ||
28591 | The @code{Clobber} parameter has several additional uses: | |
88e1739c | 28592 | @enumerate |
7cd4527e AC |
28593 | @item Use ``register'' name @code{cc} to indicate that flags might have changed |
28594 | @item Use ``register'' name @code{memory} if you changed a memory location | |
28595 | @end enumerate | |
88e1739c | 28596 | |
7cd4527e AC |
28597 | @c --------------------------------------------------------------------------- |
28598 | @node The Volatile Parameter | |
28599 | @subsection The @code{Volatile} Parameter | |
28600 | @cindex Volatile parameter | |
88e1739c | 28601 | |
7cd4527e AC |
28602 | @noindent |
28603 | Compiler optimizations in the presence of Inline Assembler may sometimes have | |
28604 | unwanted effects. For example, when an @code{Asm} invocation with an input | |
28605 | variable is inside a loop, the compiler might move the loading of the input | |
28606 | variable outside the loop, regarding it as a one-time initialization. | |
88e1739c | 28607 | |
7cd4527e AC |
28608 | If this effect is not desired, you can disable such optimizations by setting |
28609 | the @code{Volatile} parameter to @code{True}; for example: | |
88e1739c | 28610 | |
7cd4527e AC |
28611 | @smallexample @c ada |
28612 | @group | |
28613 | Asm ("movl %0, %%ebx" & LF & HT & | |
28614 | "movl %%ebx, %1", | |
7cd4527e | 28615 | Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), |
3777b2c0 | 28616 | Inputs => Unsigned_32'Asm_Input ("g", Var_In), |
7cd4527e AC |
28617 | Clobber => "ebx", |
28618 | Volatile => True); | |
28619 | @end group | |
28620 | @end smallexample | |
88e1739c | 28621 | |
7cd4527e AC |
28622 | By default, @code{Volatile} is set to @code{False} unless there is no |
28623 | @code{Outputs} parameter. | |
88e1739c | 28624 | |
7cd4527e AC |
28625 | Although setting @code{Volatile} to @code{True} prevents unwanted |
28626 | optimizations, it will also disable other optimizations that might be | |
28627 | important for efficiency. In general, you should set @code{Volatile} | |
28628 | to @code{True} only if the compiler's optimizations have created | |
28629 | problems. | |
7cd4527e AC |
28630 | @c END OF INLINE ASSEMBLER CHAPTER |
28631 | @c =============================== | |
88e1739c | 28632 | |
7cd4527e AC |
28633 | @c *********************************** |
28634 | @c * Compatibility and Porting Guide * | |
28635 | @c *********************************** | |
28636 | @node Compatibility and Porting Guide | |
28637 | @appendix Compatibility and Porting Guide | |
88e1739c | 28638 | |
7cd4527e AC |
28639 | @noindent |
28640 | This chapter describes the compatibility issues that may arise between | |
e08b38f5 VC |
28641 | GNAT and other Ada compilation systems (including those for Ada 83), |
28642 | and shows how GNAT can expedite porting | |
7cd4527e | 28643 | applications developed in other Ada environments. |
88e1739c | 28644 | |
7cd4527e AC |
28645 | @menu |
28646 | * Compatibility with Ada 83:: | |
e08b38f5 | 28647 | * Compatibility between Ada 95 and Ada 2005:: |
7cd4527e | 28648 | * Implementation-dependent characteristics:: |
e08b38f5 | 28649 | * Compatibility with Other Ada Systems:: |
7cd4527e | 28650 | * Representation Clauses:: |
7e3d710b AC |
28651 | @ifclear vms |
28652 | @c Brief section is only in non-VMS version | |
28653 | @c Full chapter is in VMS version | |
32e209e4 | 28654 | * Compatibility with HP Ada 83:: |
7e3d710b | 28655 | @end ifclear |
87b3f81f | 28656 | @ifset vms |
ba1cbfb9 | 28657 | * Transitioning to 64-Bit GNAT for OpenVMS:: |
87b3f81f | 28658 | @end ifset |
7cd4527e | 28659 | @end menu |
88e1739c | 28660 | |
7cd4527e AC |
28661 | @node Compatibility with Ada 83 |
28662 | @section Compatibility with Ada 83 | |
e08b38f5 | 28663 | @cindex Compatibility (between Ada 83 and Ada 95 / Ada 2005) |
88e1739c FW |
28664 | |
28665 | @noindent | |
e08b38f5 VC |
28666 | Ada 95 and Ada 2005 are highly upwards compatible with Ada 83. In |
28667 | particular, the design intention was that the difficulties associated | |
28668 | with moving from Ada 83 to Ada 95 or Ada 2005 should be no greater than those | |
7cd4527e | 28669 | that occur when moving from one Ada 83 system to another. |
88e1739c | 28670 | |
7cd4527e AC |
28671 | However, there are a number of points at which there are minor |
28672 | incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains | |
28673 | full details of these issues, | |
28674 | and should be consulted for a complete treatment. | |
28675 | In practice the | |
28676 | following subsections treat the most likely issues to be encountered. | |
88e1739c FW |
28677 | |
28678 | @menu | |
7cd4527e AC |
28679 | * Legal Ada 83 programs that are illegal in Ada 95:: |
28680 | * More deterministic semantics:: | |
28681 | * Changed semantics:: | |
28682 | * Other language compatibility issues:: | |
88e1739c FW |
28683 | @end menu |
28684 | ||
7cd4527e AC |
28685 | @node Legal Ada 83 programs that are illegal in Ada 95 |
28686 | @subsection Legal Ada 83 programs that are illegal in Ada 95 | |
88e1739c | 28687 | |
8dd07840 | 28688 | Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in |
e08b38f5 VC |
28689 | Ada 95 and thus also in Ada 2005: |
28690 | ||
28691 | @table @emph | |
7cd4527e AC |
28692 | @item Character literals |
28693 | Some uses of character literals are ambiguous. Since Ada 95 has introduced | |
28694 | @code{Wide_Character} as a new predefined character type, some uses of | |
28695 | character literals that were legal in Ada 83 are illegal in Ada 95. | |
28696 | For example: | |
28697 | @smallexample @c ada | |
d488f6ea | 28698 | for Char in 'A' .. 'Z' loop @dots{} end loop; |
7cd4527e | 28699 | @end smallexample |
e08b38f5 | 28700 | |
88e1739c | 28701 | @noindent |
7cd4527e AC |
28702 | The problem is that @code{'A'} and @code{'Z'} could be from either |
28703 | @code{Character} or @code{Wide_Character}. The simplest correction | |
28704 | is to make the type explicit; e.g.: | |
28705 | @smallexample @c ada | |
d488f6ea | 28706 | for Char in Character range 'A' .. 'Z' loop @dots{} end loop; |
7cd4527e AC |
28707 | @end smallexample |
28708 | ||
28709 | @item New reserved words | |
28710 | The identifiers @code{abstract}, @code{aliased}, @code{protected}, | |
28711 | @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. | |
28712 | Existing Ada 83 code using any of these identifiers must be edited to | |
28713 | use some alternative name. | |
28714 | ||
28715 | @item Freezing rules | |
28716 | The rules in Ada 95 are slightly different with regard to the point at | |
28717 | which entities are frozen, and representation pragmas and clauses are | |
28718 | not permitted past the freeze point. This shows up most typically in | |
28719 | the form of an error message complaining that a representation item | |
28720 | appears too late, and the appropriate corrective action is to move | |
28721 | the item nearer to the declaration of the entity to which it refers. | |
28722 | ||
28723 | A particular case is that representation pragmas | |
28724 | @ifset vms | |
28725 | (including the | |
32e209e4 | 28726 | extended HP Ada 83 compatibility pragmas such as @code{Export_Procedure}) |
7cd4527e AC |
28727 | @end ifset |
28728 | cannot be applied to a subprogram body. If necessary, a separate subprogram | |
28729 | declaration must be introduced to which the pragma can be applied. | |
28730 | ||
28731 | @item Optional bodies for library packages | |
28732 | In Ada 83, a package that did not require a package body was nevertheless | |
28733 | allowed to have one. This lead to certain surprises in compiling large | |
28734 | systems (situations in which the body could be unexpectedly ignored by the | |
28735 | binder). In Ada 95, if a package does not require a body then it is not | |
28736 | permitted to have a body. To fix this problem, simply remove a redundant | |
28737 | body if it is empty, or, if it is non-empty, introduce a dummy declaration | |
28738 | into the spec that makes the body required. One approach is to add a private | |
28739 | part to the package declaration (if necessary), and define a parameterless | |
28740 | procedure called @code{Requires_Body}, which must then be given a dummy | |
28741 | procedure body in the package body, which then becomes required. | |
28742 | Another approach (assuming that this does not introduce elaboration | |
28743 | circularities) is to add an @code{Elaborate_Body} pragma to the package spec, | |
28744 | since one effect of this pragma is to require the presence of a package body. | |
28745 | ||
28746 | @item @code{Numeric_Error} is now the same as @code{Constraint_Error} | |
28747 | In Ada 95, the exception @code{Numeric_Error} is a renaming of | |
28748 | @code{Constraint_Error}. | |
28749 | This means that it is illegal to have separate exception handlers for | |
28750 | the two exceptions. The fix is simply to remove the handler for the | |
28751 | @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise | |
28752 | @code{Constraint_Error} in place of @code{Numeric_Error} in all cases). | |
28753 | ||
28754 | @item Indefinite subtypes in generics | |
28755 | In Ada 83, it was permissible to pass an indefinite type (e.g.@: @code{String}) | |
28756 | as the actual for a generic formal private type, but then the instantiation | |
28757 | would be illegal if there were any instances of declarations of variables | |
28758 | of this type in the generic body. In Ada 95, to avoid this clear violation | |
28759 | of the methodological principle known as the ``contract model'', | |
28760 | the generic declaration explicitly indicates whether | |
28761 | or not such instantiations are permitted. If a generic formal parameter | |
28762 | has explicit unknown discriminants, indicated by using @code{(<>)} after the | |
7a6c40a6 | 28763 | subtype name, then it can be instantiated with indefinite types, but no |
7cd4527e AC |
28764 | stand-alone variables can be declared of this type. Any attempt to declare |
28765 | such a variable will result in an illegality at the time the generic is | |
28766 | declared. If the @code{(<>)} notation is not used, then it is illegal | |
28767 | to instantiate the generic with an indefinite type. | |
28768 | This is the potential incompatibility issue when porting Ada 83 code to Ada 95. | |
28769 | It will show up as a compile time error, and | |
28770 | the fix is usually simply to add the @code{(<>)} to the generic declaration. | |
28771 | @end table | |
28772 | ||
28773 | @node More deterministic semantics | |
28774 | @subsection More deterministic semantics | |
28775 | ||
e08b38f5 | 28776 | @table @emph |
7cd4527e AC |
28777 | @item Conversions |
28778 | Conversions from real types to integer types round away from 0. In Ada 83 | |
28779 | the conversion Integer(2.5) could deliver either 2 or 3 as its value. This | |
28780 | implementation freedom was intended to support unbiased rounding in | |
28781 | statistical applications, but in practice it interfered with portability. | |
28782 | In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 | |
28783 | is required. Numeric code may be affected by this change in semantics. | |
28784 | Note, though, that this issue is no worse than already existed in Ada 83 | |
28785 | when porting code from one vendor to another. | |
28786 | ||
28787 | @item Tasking | |
28788 | The Real-Time Annex introduces a set of policies that define the behavior of | |
28789 | features that were implementation dependent in Ada 83, such as the order in | |
28790 | which open select branches are executed. | |
28791 | @end table | |
28792 | ||
28793 | @node Changed semantics | |
28794 | @subsection Changed semantics | |
88e1739c FW |
28795 | |
28796 | @noindent | |
7cd4527e AC |
28797 | The worst kind of incompatibility is one where a program that is legal in |
28798 | Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not | |
28799 | possible in Ada 83. Fortunately this is extremely rare, but the one | |
28800 | situation that you should be alert to is the change in the predefined type | |
28801 | @code{Character} from 7-bit ASCII to 8-bit Latin-1. | |
88e1739c | 28802 | |
e08b38f5 VC |
28803 | @table @emph |
28804 | @item Range of type @code{Character} | |
7cd4527e AC |
28805 | The range of @code{Standard.Character} is now the full 256 characters |
28806 | of Latin-1, whereas in most Ada 83 implementations it was restricted | |
28807 | to 128 characters. Although some of the effects of | |
28808 | this change will be manifest in compile-time rejection of legal | |
28809 | Ada 83 programs it is possible for a working Ada 83 program to have | |
28810 | a different effect in Ada 95, one that was not permitted in Ada 83. | |
28811 | As an example, the expression | |
28812 | @code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now | |
28813 | delivers @code{255} as its value. | |
28814 | In general, you should look at the logic of any | |
28815 | character-processing Ada 83 program and see whether it needs to be adapted | |
28816 | to work correctly with Latin-1. Note that the predefined Ada 95 API has a | |
28817 | character handling package that may be relevant if code needs to be adapted | |
28818 | to account for the additional Latin-1 elements. | |
28819 | The desirable fix is to | |
28820 | modify the program to accommodate the full character set, but in some cases | |
28821 | it may be convenient to define a subtype or derived type of Character that | |
28822 | covers only the restricted range. | |
28823 | @cindex Latin-1 | |
28824 | @end table | |
88e1739c | 28825 | |
7cd4527e AC |
28826 | @node Other language compatibility issues |
28827 | @subsection Other language compatibility issues | |
e08b38f5 VC |
28828 | |
28829 | @table @emph | |
28830 | @item @option{-gnat83} switch | |
7cd4527e AC |
28831 | All implementations of GNAT provide a switch that causes GNAT to operate |
28832 | in Ada 83 mode. In this mode, some but not all compatibility problems | |
28833 | of the type described above are handled automatically. For example, the | |
e08b38f5 VC |
28834 | new reserved words introduced in Ada 95 and Ada 2005 are treated simply |
28835 | as identifiers as in Ada 83. | |
7cd4527e AC |
28836 | However, |
28837 | in practice, it is usually advisable to make the necessary modifications | |
28838 | to the program to remove the need for using this switch. | |
0f1b0456 | 28839 | See @ref{Compiling Different Versions of Ada}. |
7cd4527e AC |
28840 | |
28841 | @item Support for removed Ada 83 pragmas and attributes | |
e08b38f5 VC |
28842 | A number of pragmas and attributes from Ada 83 were removed from Ada 95, |
28843 | generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 | |
7cd4527e | 28844 | compilers are allowed, but not required, to implement these missing |
e08b38f5 | 28845 | elements. In contrast with some other compilers, GNAT implements all |
7cd4527e AC |
28846 | such pragmas and attributes, eliminating this compatibility concern. These |
28847 | include @code{pragma Interface} and the floating point type attributes | |
28848 | (@code{Emax}, @code{Mantissa}, etc.), among other items. | |
28849 | @end table | |
88e1739c | 28850 | |
e08b38f5 VC |
28851 | |
28852 | @node Compatibility between Ada 95 and Ada 2005 | |
28853 | @section Compatibility between Ada 95 and Ada 2005 | |
28854 | @cindex Compatibility between Ada 95 and Ada 2005 | |
28855 | ||
28856 | @noindent | |
28857 | Although Ada 2005 was designed to be upwards compatible with Ada 95, there are | |
28858 | a number of incompatibilities. Several are enumerated below; | |
28859 | for a complete description please see the | |
28860 | Annotated Ada 2005 Reference Manual, or section 9.1.1 in | |
28861 | @cite{Rationale for Ada 2005}. | |
28862 | ||
28863 | @table @emph | |
28864 | @item New reserved words. | |
28865 | The words @code{interface}, @code{overriding} and @code{synchronized} are | |
28866 | reserved in Ada 2005. | |
28867 | A pre-Ada 2005 program that uses any of these as an identifier will be | |
28868 | illegal. | |
28869 | ||
28870 | @item New declarations in predefined packages. | |
28871 | A number of packages in the predefined environment contain new declarations: | |
28872 | @code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, | |
28873 | @code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, | |
28874 | @code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, | |
28875 | @code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, | |
28876 | @code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. | |
28877 | If an Ada 95 program does a @code{with} and @code{use} of any of these | |
28878 | packages, the new declarations may cause name clashes. | |
28879 | ||
28880 | @item Access parameters. | |
28881 | A nondispatching subprogram with an access parameter cannot be renamed | |
28882 | as a dispatching operation. This was permitted in Ada 95. | |
28883 | ||
28884 | @item Access types, discriminants, and constraints. | |
28885 | Rule changes in this area have led to some incompatibilities; for example, | |
28886 | constrained subtypes of some access types are not permitted in Ada 2005. | |
28887 | ||
28888 | @item Aggregates for limited types. | |
28889 | The allowance of aggregates for limited types in Ada 2005 raises the | |
28890 | possibility of ambiguities in legal Ada 95 programs, since additional types | |
28891 | now need to be considered in expression resolution. | |
28892 | ||
28893 | @item Fixed-point multiplication and division. | |
28894 | Certain expressions involving ``*'' or ``/'' for a fixed-point type, which | |
28895 | were legal in Ada 95 and invoked the predefined versions of these operations, | |
28896 | are now ambiguous. | |
28897 | The ambiguity may be resolved either by applying a type conversion to the | |
28898 | expression, or by explicitly invoking the operation from package | |
28899 | @code{Standard}. | |
28900 | ||
28901 | @item Return-by-reference types. | |
28902 | The Ada 95 return-by-reference mechanism has been removed. Instead, the user | |
28903 | can declare a function returning a value from an anonymous access type. | |
28904 | @end table | |
28905 | ||
28906 | ||
7cd4527e AC |
28907 | @node Implementation-dependent characteristics |
28908 | @section Implementation-dependent characteristics | |
28909 | @noindent | |
28910 | Although the Ada language defines the semantics of each construct as | |
28911 | precisely as practical, in some situations (for example for reasons of | |
28912 | efficiency, or where the effect is heavily dependent on the host or target | |
28913 | platform) the implementation is allowed some freedom. In porting Ada 83 | |
28914 | code to GNAT, you need to be aware of whether / how the existing code | |
28915 | exercised such implementation dependencies. Such characteristics fall into | |
28916 | several categories, and GNAT offers specific support in assisting the | |
28917 | transition from certain Ada 83 compilers. | |
88e1739c | 28918 | |
7cd4527e AC |
28919 | @menu |
28920 | * Implementation-defined pragmas:: | |
28921 | * Implementation-defined attributes:: | |
28922 | * Libraries:: | |
28923 | * Elaboration order:: | |
28924 | * Target-specific aspects:: | |
28925 | @end menu | |
88e1739c | 28926 | |
7cd4527e AC |
28927 | @node Implementation-defined pragmas |
28928 | @subsection Implementation-defined pragmas | |
28929 | ||
28930 | @noindent | |
28931 | Ada compilers are allowed to supplement the language-defined pragmas, and | |
28932 | these are a potential source of non-portability. All GNAT-defined pragmas | |
b2e74434 RW |
28933 | are described in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT |
28934 | Reference Manual}, and these include several that are specifically | |
28935 | intended to correspond to other vendors' Ada 83 pragmas. | |
7cd4527e | 28936 | For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. |
b2e74434 | 28937 | For compatibility with HP Ada 83, GNAT supplies the pragmas |
7cd4527e AC |
28938 | @code{Extend_System}, @code{Ident}, @code{Inline_Generic}, |
28939 | @code{Interface_Name}, @code{Passive}, @code{Suppress_All}, | |
28940 | and @code{Volatile}. | |
28941 | Other relevant pragmas include @code{External} and @code{Link_With}. | |
28942 | Some vendor-specific | |
28943 | Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are | |
28944 | recognized, thus | |
28945 | avoiding compiler rejection of units that contain such pragmas; they are not | |
28946 | relevant in a GNAT context and hence are not otherwise implemented. | |
28947 | ||
28948 | @node Implementation-defined attributes | |
28949 | @subsection Implementation-defined attributes | |
28950 | ||
28951 | Analogous to pragmas, the set of attributes may be extended by an | |
b2e74434 RW |
28952 | implementation. All GNAT-defined attributes are described in |
28953 | @ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference | |
28954 | Manual}, and these include several that are specifically intended | |
7cd4527e | 28955 | to correspond to other vendors' Ada 83 attributes. For migrating from VADS, |
32e209e4 | 28956 | the attribute @code{VADS_Size} may be useful. For compatibility with HP |
7cd4527e AC |
28957 | Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and |
28958 | @code{Type_Class}. | |
28959 | ||
28960 | @node Libraries | |
28961 | @subsection Libraries | |
28962 | @noindent | |
28963 | Vendors may supply libraries to supplement the standard Ada API. If Ada 83 | |
28964 | code uses vendor-specific libraries then there are several ways to manage | |
e08b38f5 | 28965 | this in Ada 95 or Ada 2005: |
7cd4527e | 28966 | @enumerate |
88e1739c | 28967 | @item |
1a5f40e1 | 28968 | If the source code for the libraries (specs and bodies) are |
7cd4527e AC |
28969 | available, then the libraries can be migrated in the same way as the |
28970 | application. | |
28971 | @item | |
1a5f40e1 | 28972 | If the source code for the specs but not the bodies are |
7cd4527e AC |
28973 | available, then you can reimplement the bodies. |
28974 | @item | |
e08b38f5 | 28975 | Some features introduced by Ada 95 obviate the need for library support. For |
7cd4527e AC |
28976 | example most Ada 83 vendors supplied a package for unsigned integers. The |
28977 | Ada 95 modular type feature is the preferred way to handle this need, so | |
28978 | instead of migrating or reimplementing the unsigned integer package it may | |
28979 | be preferable to retrofit the application using modular types. | |
28980 | @end enumerate | |
88e1739c | 28981 | |
7cd4527e AC |
28982 | @node Elaboration order |
28983 | @subsection Elaboration order | |
28984 | @noindent | |
28985 | The implementation can choose any elaboration order consistent with the unit | |
28986 | dependency relationship. This freedom means that some orders can result in | |
28987 | Program_Error being raised due to an ``Access Before Elaboration'': an attempt | |
28988 | to invoke a subprogram its body has been elaborated, or to instantiate a | |
28989 | generic before the generic body has been elaborated. By default GNAT | |
28990 | attempts to choose a safe order (one that will not encounter access before | |
32e209e4 CC |
28991 | elaboration problems) by implicitly inserting @code{Elaborate} or |
28992 | @code{Elaborate_All} pragmas where | |
7cd4527e AC |
28993 | needed. However, this can lead to the creation of elaboration circularities |
28994 | and a resulting rejection of the program by gnatbind. This issue is | |
28995 | thoroughly described in @ref{Elaboration Order Handling in GNAT}. | |
28996 | In brief, there are several | |
28997 | ways to deal with this situation: | |
88e1739c | 28998 | |
7cd4527e | 28999 | @itemize @bullet |
88e1739c | 29000 | @item |
8dd07840 | 29001 | Modify the program to eliminate the circularities, e.g.@: by moving |
7cd4527e AC |
29002 | elaboration-time code into explicitly-invoked procedures |
29003 | @item | |
29004 | Constrain the elaboration order by including explicit @code{Elaborate_Body} or | |
29005 | @code{Elaborate} pragmas, and then inhibit the generation of implicit | |
29006 | @code{Elaborate_All} | |
29007 | pragmas either globally (as an effect of the @option{-gnatE} switch) or locally | |
29008 | (by selectively suppressing elaboration checks via pragma | |
29009 | @code{Suppress(Elaboration_Check)} when it is safe to do so). | |
29010 | @end itemize | |
88e1739c | 29011 | |
7cd4527e AC |
29012 | @node Target-specific aspects |
29013 | @subsection Target-specific aspects | |
88e1739c | 29014 | @noindent |
7cd4527e AC |
29015 | Low-level applications need to deal with machine addresses, data |
29016 | representations, interfacing with assembler code, and similar issues. If | |
29017 | such an Ada 83 application is being ported to different target hardware (for | |
29018 | example where the byte endianness has changed) then you will need to | |
29019 | carefully examine the program logic; the porting effort will heavily depend | |
e08b38f5 VC |
29020 | on the robustness of the original design. Moreover, Ada 95 (and thus |
29021 | Ada 2005) are sometimes | |
7cd4527e AC |
29022 | incompatible with typical Ada 83 compiler practices regarding implicit |
29023 | packing, the meaning of the Size attribute, and the size of access values. | |
29024 | GNAT's approach to these issues is described in @ref{Representation Clauses}. | |
88e1739c | 29025 | |
e08b38f5 VC |
29026 | @node Compatibility with Other Ada Systems |
29027 | @section Compatibility with Other Ada Systems | |
88e1739c FW |
29028 | |
29029 | @noindent | |
e08b38f5 VC |
29030 | If programs avoid the use of implementation dependent and |
29031 | implementation defined features, as documented in the @cite{Ada | |
29032 | Reference Manual}, there should be a high degree of portability between | |
29033 | GNAT and other Ada systems. The following are specific items which | |
29034 | have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 | |
7cd4527e | 29035 | compilers, but do not affect porting code to GNAT@. |
e08b38f5 VC |
29036 | (As of @value{NOW}, GNAT is the only compiler available for Ada 2005; |
29037 | the following issues may or may not arise for Ada 2005 programs | |
29038 | when other compilers appear.) | |
88e1739c | 29039 | |
e08b38f5 | 29040 | @table @emph |
7cd4527e AC |
29041 | @item Ada 83 Pragmas and Attributes |
29042 | Ada 95 compilers are allowed, but not required, to implement the missing | |
29043 | Ada 83 pragmas and attributes that are no longer defined in Ada 95. | |
29044 | GNAT implements all such pragmas and attributes, eliminating this as | |
29045 | a compatibility concern, but some other Ada 95 compilers reject these | |
29046 | pragmas and attributes. | |
29047 | ||
e08b38f5 | 29048 | @item Specialized Needs Annexes |
7cd4527e AC |
29049 | GNAT implements the full set of special needs annexes. At the |
29050 | current time, it is the only Ada 95 compiler to do so. This means that | |
29051 | programs making use of these features may not be portable to other Ada | |
29052 | 95 compilation systems. | |
29053 | ||
29054 | @item Representation Clauses | |
29055 | Some other Ada 95 compilers implement only the minimal set of | |
29056 | representation clauses required by the Ada 95 reference manual. GNAT goes | |
29057 | far beyond this minimal set, as described in the next section. | |
29058 | @end table | |
29059 | ||
29060 | @node Representation Clauses | |
29061 | @section Representation Clauses | |
88e1739c FW |
29062 | |
29063 | @noindent | |
7cd4527e AC |
29064 | The Ada 83 reference manual was quite vague in describing both the minimal |
29065 | required implementation of representation clauses, and also their precise | |
e08b38f5 VC |
29066 | effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the |
29067 | minimal set of capabilities required is still quite limited. | |
88e1739c | 29068 | |
e08b38f5 VC |
29069 | GNAT implements the full required set of capabilities in |
29070 | Ada 95 and Ada 2005, but also goes much further, and in particular | |
7cd4527e AC |
29071 | an effort has been made to be compatible with existing Ada 83 usage to the |
29072 | greatest extent possible. | |
88e1739c | 29073 | |
7cd4527e | 29074 | A few cases exist in which Ada 83 compiler behavior is incompatible with |
e08b38f5 | 29075 | the requirements in Ada 95 (and thus also Ada 2005). These are instances of |
7cd4527e AC |
29076 | intentional or accidental dependence on specific implementation dependent |
29077 | characteristics of these Ada 83 compilers. The following is a list of | |
e08b38f5 | 29078 | the cases most likely to arise in existing Ada 83 code. |
88e1739c | 29079 | |
e08b38f5 | 29080 | @table @emph |
7cd4527e AC |
29081 | @item Implicit Packing |
29082 | Some Ada 83 compilers allowed a Size specification to cause implicit | |
29083 | packing of an array or record. This could cause expensive implicit | |
29084 | conversions for change of representation in the presence of derived | |
29085 | types, and the Ada design intends to avoid this possibility. | |
29086 | Subsequent AI's were issued to make it clear that such implicit | |
29087 | change of representation in response to a Size clause is inadvisable, | |
e08b38f5 VC |
29088 | and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) |
29089 | Reference Manuals as implementation advice that is followed by GNAT@. | |
7cd4527e AC |
29090 | The problem will show up as an error |
29091 | message rejecting the size clause. The fix is simply to provide | |
29092 | the explicit pragma @code{Pack}, or for more fine tuned control, provide | |
29093 | a Component_Size clause. | |
29094 | ||
29095 | @item Meaning of Size Attribute | |
e08b38f5 VC |
29096 | The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as |
29097 | the minimal number of bits required to hold values of the type. For example, | |
29098 | on a 32-bit machine, the size of @code{Natural} will typically be 31 and not | |
7cd4527e AC |
29099 | 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and |
29100 | some 32 in this situation. This problem will usually show up as a compile | |
29101 | time error, but not always. It is a good idea to check all uses of the | |
29102 | 'Size attribute when porting Ada 83 code. The GNAT specific attribute | |
29103 | Object_Size can provide a useful way of duplicating the behavior of | |
29104 | some Ada 83 compiler systems. | |
29105 | ||
29106 | @item Size of Access Types | |
29107 | A common assumption in Ada 83 code is that an access type is in fact a pointer, | |
29108 | and that therefore it will be the same size as a System.Address value. This | |
29109 | assumption is true for GNAT in most cases with one exception. For the case of | |
29110 | a pointer to an unconstrained array type (where the bounds may vary from one | |
29111 | value of the access type to another), the default is to use a ``fat pointer'', | |
29112 | which is represented as two separate pointers, one to the bounds, and one to | |
29113 | the array. This representation has a number of advantages, including improved | |
29114 | efficiency. However, it may cause some difficulties in porting existing Ada 83 | |
29115 | code which makes the assumption that, for example, pointers fit in 32 bits on | |
29116 | a machine with 32-bit addressing. | |
29117 | ||
29118 | To get around this problem, GNAT also permits the use of ``thin pointers'' for | |
29119 | access types in this case (where the designated type is an unconstrained array | |
29120 | type). These thin pointers are indeed the same size as a System.Address value. | |
29121 | To specify a thin pointer, use a size clause for the type, for example: | |
29122 | ||
29123 | @smallexample @c ada | |
29124 | type X is access all String; | |
29125 | for X'Size use Standard'Address_Size; | |
29126 | @end smallexample | |
29127 | ||
29128 | @noindent | |
29129 | which will cause the type X to be represented using a single pointer. | |
29130 | When using this representation, the bounds are right behind the array. | |
29131 | This representation is slightly less efficient, and does not allow quite | |
29132 | such flexibility in the use of foreign pointers or in using the | |
29133 | Unrestricted_Access attribute to create pointers to non-aliased objects. | |
29134 | But for any standard portable use of the access type it will work in | |
29135 | a functionally correct manner and allow porting of existing code. | |
29136 | Note that another way of forcing a thin pointer representation | |
29137 | is to use a component size clause for the element size in an array, | |
29138 | or a record representation clause for an access field in a record. | |
29139 | @end table | |
88e1739c | 29140 | |
7e3d710b AC |
29141 | @ifclear vms |
29142 | @c This brief section is only in the non-VMS version | |
29143 | @c The complete chapter on HP Ada is in the VMS version | |
32e209e4 CC |
29144 | @node Compatibility with HP Ada 83 |
29145 | @section Compatibility with HP Ada 83 | |
88e1739c | 29146 | |
7cd4527e AC |
29147 | @noindent |
29148 | The VMS version of GNAT fully implements all the pragmas and attributes | |
32e209e4 | 29149 | provided by HP Ada 83, as well as providing the standard HP Ada 83 |
7cd4527e AC |
29150 | libraries, including Starlet. In addition, data layouts and parameter |
29151 | passing conventions are highly compatible. This means that porting | |
32e209e4 | 29152 | existing HP Ada 83 code to GNAT in VMS systems should be easier than |
7cd4527e | 29153 | most other porting efforts. The following are some of the most |
32e209e4 | 29154 | significant differences between GNAT and HP Ada 83. |
88e1739c | 29155 | |
e08b38f5 | 29156 | @table @emph |
7cd4527e | 29157 | @item Default floating-point representation |
32e209e4 | 29158 | In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, |
7cd4527e AC |
29159 | it is VMS format. GNAT does implement the necessary pragmas |
29160 | (Long_Float, Float_Representation) for changing this default. | |
88e1739c | 29161 | |
7cd4527e AC |
29162 | @item System |
29163 | The package System in GNAT exactly corresponds to the definition in the | |
29164 | Ada 95 reference manual, which means that it excludes many of the | |
32e209e4 | 29165 | HP Ada 83 extensions. However, a separate package Aux_DEC is provided |
7cd4527e AC |
29166 | that contains the additional definitions, and a special pragma, |
29167 | Extend_System allows this package to be treated transparently as an | |
29168 | extension of package System. | |
88e1739c | 29169 | |
7cd4527e AC |
29170 | @item To_Address |
29171 | The definitions provided by Aux_DEC are exactly compatible with those | |
32e209e4 CC |
29172 | in the HP Ada 83 version of System, with one exception. |
29173 | HP Ada provides the following declarations: | |
7cd4527e AC |
29174 | |
29175 | @smallexample @c ada | |
29176 | TO_ADDRESS (INTEGER) | |
29177 | TO_ADDRESS (UNSIGNED_LONGWORD) | |
e08b38f5 | 29178 | TO_ADDRESS (@i{universal_integer}) |
88e1739c FW |
29179 | @end smallexample |
29180 | ||
7cd4527e | 29181 | @noindent |
e08b38f5 | 29182 | The version of TO_ADDRESS taking a @i{universal integer} argument is in fact |
7cd4527e AC |
29183 | an extension to Ada 83 not strictly compatible with the reference manual. |
29184 | In GNAT, we are constrained to be exactly compatible with the standard, | |
32e209e4 | 29185 | and this means we cannot provide this capability. In HP Ada 83, the |
7cd4527e | 29186 | point of this definition is to deal with a call like: |
88e1739c | 29187 | |
7cd4527e AC |
29188 | @smallexample @c ada |
29189 | TO_ADDRESS (16#12777#); | |
88e1739c FW |
29190 | @end smallexample |
29191 | ||
7cd4527e AC |
29192 | @noindent |
29193 | Normally, according to the Ada 83 standard, one would expect this to be | |
29194 | ambiguous, since it matches both the INTEGER and UNSIGNED_LONGWORD forms | |
32e209e4 | 29195 | of TO_ADDRESS@. However, in HP Ada 83, there is no ambiguity, since the |
e08b38f5 | 29196 | definition using @i{universal_integer} takes precedence. |
88e1739c | 29197 | |
e08b38f5 VC |
29198 | In GNAT, since the version with @i{universal_integer} cannot be supplied, it |
29199 | is not possible to be 100% compatible. Since there are many programs using | |
7cd4527e AC |
29200 | numeric constants for the argument to TO_ADDRESS, the decision in GNAT was |
29201 | to change the name of the function in the UNSIGNED_LONGWORD case, so the | |
29202 | declarations provided in the GNAT version of AUX_Dec are: | |
88e1739c | 29203 | |
7cd4527e AC |
29204 | @smallexample @c ada |
29205 | function To_Address (X : Integer) return Address; | |
29206 | pragma Pure_Function (To_Address); | |
88e1739c | 29207 | |
7cd4527e AC |
29208 | function To_Address_Long (X : Unsigned_Longword) |
29209 | return Address; | |
29210 | pragma Pure_Function (To_Address_Long); | |
88e1739c FW |
29211 | @end smallexample |
29212 | ||
88e1739c | 29213 | @noindent |
7cd4527e AC |
29214 | This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must |
29215 | change the name to TO_ADDRESS_LONG@. | |
88e1739c | 29216 | |
7cd4527e AC |
29217 | @item Task_Id values |
29218 | The Task_Id values assigned will be different in the two systems, and GNAT | |
29219 | does not provide a specified value for the Task_Id of the environment task, | |
29220 | which in GNAT is treated like any other declared task. | |
29221 | @end table | |
88e1739c | 29222 | |
e08b38f5 | 29223 | @noindent |
7cd4527e | 29224 | For full details on these and other less significant compatibility issues, |
32e209e4 CC |
29225 | see appendix E of the HP publication entitled @cite{HP Ada, Technical |
29226 | Overview and Comparison on HP Platforms}. | |
88e1739c | 29227 | |
32e209e4 | 29228 | For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and |
7cd4527e | 29229 | attributes are recognized, although only a subset of them can sensibly |
b2e74434 RW |
29230 | be implemented. The description of pragmas in @ref{Implementation |
29231 | Defined Pragmas,,, gnat_rm, GNAT Reference Manual} | |
7cd4527e | 29232 | indicates whether or not they are applicable to non-VMS systems. |
7e3d710b | 29233 | @end ifclear |
87b3f81f AC |
29234 | |
29235 | @ifset vms | |
ba1cbfb9 RD |
29236 | @node Transitioning to 64-Bit GNAT for OpenVMS |
29237 | @section Transitioning to 64-Bit @value{EDITION} for OpenVMS | |
29238 | ||
29239 | @noindent | |
29240 | This section is meant to assist users of pre-2006 @value{EDITION} | |
29241 | for Alpha OpenVMS who are transitioning to 64-bit @value{EDITION}, | |
29242 | the version of the GNAT technology supplied in 2006 and later for | |
29243 | OpenVMS on both Alpha and I64. | |
87b3f81f AC |
29244 | |
29245 | @menu | |
29246 | * Introduction to transitioning:: | |
29247 | * Migration of 32 bit code:: | |
29248 | * Taking advantage of 64 bit addressing:: | |
29249 | * Technical details:: | |
29250 | @end menu | |
29251 | ||
29252 | @node Introduction to transitioning | |
ba1cbfb9 | 29253 | @subsection Introduction |
87b3f81f AC |
29254 | |
29255 | @noindent | |
ba1cbfb9 | 29256 | 64-bit @value{EDITION} for Open VMS has been designed to meet |
87b3f81f AC |
29257 | three main goals: |
29258 | ||
29259 | @enumerate | |
29260 | @item | |
e08b38f5 | 29261 | Providing a full conforming implementation of Ada 95 and Ada 2005 |
87b3f81f AC |
29262 | |
29263 | @item | |
29264 | Allowing maximum backward compatibility, thus easing migration of existing | |
29265 | Ada source code | |
29266 | ||
29267 | @item | |
ba1cbfb9 | 29268 | Supplying a path for exploiting the full 64-bit address range |
87b3f81f AC |
29269 | @end enumerate |
29270 | ||
29271 | @noindent | |
29272 | Ada's strong typing semantics has made it | |
29273 | impractical to have different 32-bit and 64-bit modes. As soon as | |
29274 | one object could possibly be outside the 32-bit address space, this | |
29275 | would make it necessary for the @code{System.Address} type to be 64 bits. | |
29276 | In particular, this would cause inconsistencies if 32-bit code is | |
29277 | called from 64-bit code that raises an exception. | |
29278 | ||
29279 | This issue has been resolved by always using 64-bit addressing | |
29280 | at the system level, but allowing for automatic conversions between | |
29281 | 32-bit and 64-bit addresses where required. Thus users who | |
29282 | do not currently require 64-bit addressing capabilities, can | |
29283 | recompile their code with only minimal changes (and indeed | |
29284 | if the code is written in portable Ada, with no assumptions about | |
29285 | the size of the @code{Address} type, then no changes at all are necessary). | |
29286 | At the same time, | |
29287 | this approach provides a simple, gradual upgrade path to future | |
29288 | use of larger memories than available for 32-bit systems. | |
29289 | Also, newly written applications or libraries will by default | |
29290 | be fully compatible with future systems exploiting 64-bit | |
ba1cbfb9 | 29291 | addressing capabilities. |
87b3f81f AC |
29292 | |
29293 | @ref{Migration of 32 bit code}, will focus on porting applications | |
29294 | that do not require more than 2 GB of | |
29295 | addressable memory. This code will be referred to as | |
29296 | @emph{32-bit code}. | |
ba1cbfb9 | 29297 | For applications intending to exploit the full 64-bit address space, |
87b3f81f AC |
29298 | @ref{Taking advantage of 64 bit addressing}, |
29299 | will consider further changes that may be required. | |
ba1cbfb9 | 29300 | Such code will be referred to below as @emph{64-bit code}. |
87b3f81f AC |
29301 | |
29302 | @node Migration of 32 bit code | |
29303 | @subsection Migration of 32-bit code | |
29304 | ||
29305 | @menu | |
29306 | * Address types:: | |
08564036 | 29307 | * Access types and 32/64-bit allocation:: |
87b3f81f AC |
29308 | * Unchecked conversions:: |
29309 | * Predefined constants:: | |
ba1cbfb9 | 29310 | * Interfacing with C:: |
08564036 | 29311 | * 32/64-bit descriptors:: |
87b3f81f AC |
29312 | * Experience with source compatibility:: |
29313 | @end menu | |
29314 | ||
29315 | @node Address types | |
29316 | @subsubsection Address types | |
29317 | ||
29318 | @noindent | |
29319 | To solve the problem of mixing 64-bit and 32-bit addressing, | |
29320 | while maintaining maximum backward compatibility, the following | |
29321 | approach has been taken: | |
29322 | ||
29323 | @itemize @bullet | |
29324 | @item | |
29325 | @code{System.Address} always has a size of 64 bits | |
08564036 AC |
29326 | @cindex @code{System.Address} size |
29327 | @cindex @code{Address} size | |
87b3f81f AC |
29328 | |
29329 | @item | |
29330 | @code{System.Short_Address} is a 32-bit subtype of @code{System.Address} | |
08564036 AC |
29331 | @cindex @code{System.Short_Address} size |
29332 | @cindex @code{Short_Address} size | |
87b3f81f AC |
29333 | @end itemize |
29334 | ||
87b3f81f AC |
29335 | @noindent |
29336 | Since @code{System.Short_Address} is a subtype of @code{System.Address}, | |
29337 | a @code{Short_Address} | |
29338 | may be used where an @code{Address} is required, and vice versa, without | |
29339 | needing explicit type conversions. | |
ba1cbfb9 | 29340 | By virtue of the Open VMS parameter passing conventions, |
87b3f81f AC |
29341 | even imported |
29342 | and exported subprograms that have 32-bit address parameters are | |
29343 | compatible with those that have 64-bit address parameters. | |
984a64bc | 29344 | (See @ref{Making code 64 bit clean} for details.) |
87b3f81f AC |
29345 | |
29346 | The areas that may need attention are those where record types have | |
29347 | been defined that contain components of the type @code{System.Address}, and | |
29348 | where objects of this type are passed to code expecting a record layout with | |
29349 | 32-bit addresses. | |
29350 | ||
29351 | Different compilers on different platforms cannot be | |
29352 | expected to represent the same type in the same way, | |
29353 | since alignment constraints | |
29354 | and other system-dependent properties affect the compiler's decision. | |
29355 | For that reason, Ada code | |
29356 | generally uses representation clauses to specify the expected | |
29357 | layout where required. | |
29358 | ||
29359 | If such a representation clause uses 32 bits for a component having | |
ba1cbfb9 RD |
29360 | the type @code{System.Address}, 64-bit @value{EDITION} for OpenVMS |
29361 | will detect that error and produce a specific diagnostic message. | |
87b3f81f AC |
29362 | The developer should then determine whether the representation |
29363 | should be 64 bits or not and make either of two changes: | |
29364 | change the size to 64 bits and leave the type as @code{System.Address}, or | |
29365 | leave the size as 32 bits and change the type to @code{System.Short_Address}. | |
29366 | Since @code{Short_Address} is a subtype of @code{Address}, no changes are | |
29367 | required in any code setting or accessing the field; the compiler will | |
29368 | automatically perform any needed conversions between address | |
29369 | formats. | |
29370 | ||
08564036 AC |
29371 | @node Access types and 32/64-bit allocation |
29372 | @subsubsection Access types and 32/64-bit allocation | |
29373 | @cindex 32-bit allocation | |
29374 | @cindex 64-bit allocation | |
87b3f81f AC |
29375 | |
29376 | @noindent | |
08564036 AC |
29377 | By default, objects designated by access values are always allocated in |
29378 | the 64-bit address space, and access values themselves are represented | |
29379 | in 64 bits. If these defaults are not appropriate, and 32-bit allocation | |
29380 | is required (for example if the address of an allocated object is assigned | |
29381 | to a @code{Short_Address} variable), then several alternatives are available: | |
87b3f81f | 29382 | |
08564036 AC |
29383 | @itemize @bullet |
29384 | @item | |
29385 | A pool-specific access type (ie, an @w{Ada 83} access type, whose | |
29386 | definition is @code{access T} versus @code{access all T} or | |
29387 | @code{access constant T}), may be declared with a @code{'Size} representation | |
29388 | clause that establishes the size as 32 bits. | |
29389 | In such circumstances allocations for that type will | |
29390 | be from the 32-bit heap. Such a clause is not permitted | |
29391 | for a general access type (declared with @code{access all} or | |
29392 | @code{access constant}) as values of such types must be able to refer | |
29393 | to any object of the designated type, including objects residing outside | |
29394 | the 32-bit address range. Existing @w{Ada 83} code will not contain such | |
29395 | type definitions, however, since general access types were introduced | |
29396 | in @w{Ada 95}. | |
29397 | ||
29398 | @item | |
29399 | Switches for @command{GNAT BIND} control whether the internal GNAT | |
29400 | allocation routine @code{__gnat_malloc} uses 64-bit or 32-bit allocations. | |
29401 | @cindex @code{__gnat_malloc} | |
29402 | The switches are respectively @option{-H64} (the default) and | |
29403 | @option{-H32}. | |
29404 | @cindex @option{-H32} (@command{gnatbind}) | |
29405 | @cindex @option{-H64} (@command{gnatbind}) | |
29406 | ||
29407 | @item | |
29408 | The environment variable (logical name) @code{GNAT$NO_MALLOC_64} | |
29409 | @cindex @code{GNAT$NO_MALLOC_64} environment variable | |
29410 | may be used to force @code{__gnat_malloc} to use 32-bit allocation. | |
29411 | If this variable is left | |
29412 | undefined, or defined as @code{"DISABLE"}, @code{"FALSE"}, or @code{"0"}, | |
29413 | then the default (64-bit) allocation is used. | |
29414 | If defined as @code{"ENABLE"}, @code{"TRUE"}, or @code{"1"}, | |
29415 | then 32-bit allocation is used. The gnatbind qualifiers described above | |
29416 | override this logical name. | |
29417 | ||
29418 | @item | |
29419 | A ^gcc switch^gcc switch^ for OpenVMS, @option{-mno-malloc64}, operates | |
29420 | @cindex @option{-mno-malloc64} (^gcc^gcc^) | |
29421 | at a low level to convert explicit calls to @code{malloc} and related | |
29422 | functions from the C run-time library so that they perform allocations | |
29423 | in the 32-bit heap. | |
29424 | Since all internal allocations from GNAT use @code{__gnat_malloc}, | |
29425 | this switch is not required unless the program makes explicit calls on | |
29426 | @code{malloc} (or related functions) from interfaced C code. | |
29427 | @end itemize | |
87b3f81f | 29428 | |
87b3f81f AC |
29429 | |
29430 | @node Unchecked conversions | |
29431 | @subsubsection Unchecked conversions | |
29432 | ||
29433 | @noindent | |
29434 | In the case of an @code{Unchecked_Conversion} where the source type is a | |
29435 | 64-bit access type or the type @code{System.Address}, and the target | |
29436 | type is a 32-bit type, the compiler will generate a warning. | |
29437 | Even though the generated code will still perform the required | |
29438 | conversions, it is highly recommended in these cases to use | |
29439 | respectively a 32-bit access type or @code{System.Short_Address} | |
29440 | as the source type. | |
29441 | ||
29442 | @node Predefined constants | |
29443 | @subsubsection Predefined constants | |
29444 | ||
29445 | @noindent | |
ba1cbfb9 RD |
29446 | The following table shows the correspondence between pre-2006 versions of |
29447 | @value{EDITION} on Alpha OpenVMS (``Old'') and 64-bit @value{EDITION} | |
29448 | (``New''): | |
87b3f81f | 29449 | |
ba1cbfb9 RD |
29450 | @multitable {@code{System.Short_Memory_Size}} {2**32} {2**64} |
29451 | @item @b{Constant} @tab @b{Old} @tab @b{New} | |
29452 | @item @code{System.Word_Size} @tab 32 @tab 64 | |
29453 | @item @code{System.Memory_Size} @tab 2**32 @tab 2**64 | |
29454 | @item @code{System.Short_Memory_Size} @tab 2**32 @tab 2**32 | |
29455 | @item @code{System.Address_Size} @tab 32 @tab 64 | |
87b3f81f AC |
29456 | @end multitable |
29457 | ||
29458 | @noindent | |
29459 | If you need to refer to the specific | |
29460 | memory size of a 32-bit implementation, instead of the | |
29461 | actual memory size, use @code{System.Short_Memory_Size} | |
29462 | rather than @code{System.Memory_Size}. | |
29463 | Similarly, references to @code{System.Address_Size} may need | |
29464 | to be replaced by @code{System.Short_Address'Size}. | |
29465 | The program @command{gnatfind} may be useful for locating | |
29466 | references to the above constants, so that you can verify that they | |
29467 | are still correct. | |
29468 | ||
ba1cbfb9 RD |
29469 | @node Interfacing with C |
29470 | @subsubsection Interfacing with C | |
29471 | ||
29472 | @noindent | |
29473 | In order to minimize the impact of the transition to 64-bit addresses on | |
29474 | legacy programs, some fundamental types in the @code{Interfaces.C} | |
29475 | package hierarchy continue to be represented in 32 bits. | |
29476 | These types are: @code{ptrdiff_t}, @code{size_t}, and @code{chars_ptr}. | |
29477 | This eases integration with the default HP C layout choices, for example | |
29478 | as found in the system routines in @code{DECC$SHR.EXE}. | |
29479 | Because of this implementation choice, the type fully compatible with | |
29480 | @code{chars_ptr} is now @code{Short_Address} and not @code{Address}. | |
29481 | Depending on the context the compiler will issue a | |
29482 | warning or an error when type @code{Address} is used, alerting the user to a | |
29483 | potential problem. Otherwise 32-bit programs that use | |
29484 | @code{Interfaces.C} should normally not require code modifications | |
29485 | ||
29486 | The other issue arising with C interfacing concerns pragma @code{Convention}. | |
29487 | For VMS 64-bit systems, there is an issue of the appropriate default size | |
29488 | of C convention pointers in the absence of an explicit size clause. The HP | |
29489 | C compiler can choose either 32 or 64 bits depending on compiler options. | |
29490 | GNAT chooses 32-bits rather than 64-bits in the default case where no size | |
29491 | clause is given. This proves a better choice for porting 32-bit legacy | |
29492 | applications. In order to have a 64-bit representation, it is necessary to | |
29493 | specify a size representation clause. For example: | |
87b3f81f | 29494 | |
ba1cbfb9 RD |
29495 | @smallexample @c ada |
29496 | type int_star is access Interfaces.C.int; | |
29497 | pragma Convention(C, int_star); | |
29498 | for int_star'Size use 64; -- Necessary to get 64 and not 32 bits | |
29499 | @end smallexample | |
87b3f81f | 29500 | |
08564036 AC |
29501 | @node 32/64-bit descriptors |
29502 | @subsubsection 32/64-bit descriptors | |
29503 | ||
29504 | @noindent | |
29505 | By default, GNAT uses a 64-bit descriptor mechanism. For an imported | |
29506 | subprogram (i.e., a subprogram identified by pragma @code{Import_Function}, | |
29507 | @code{Import_Procedure}, or @code{Import_Valued_Procedure}) that specifies | |
29508 | @code{Short_Descriptor} as its mechanism, a 32-bit descriptor is used. | |
29509 | @cindex @code{Short_Descriptor} mechanism for imported subprograms | |
29510 | ||
29511 | If the configuration pragma @code{Short_Descriptors} is supplied, then | |
29512 | all descriptors will be 32 bits. | |
29513 | @cindex pragma @code{Short_Descriptors} | |
29514 | ||
87b3f81f AC |
29515 | @node Experience with source compatibility |
29516 | @subsubsection Experience with source compatibility | |
29517 | ||
29518 | @noindent | |
ba1cbfb9 | 29519 | The Security Server and STARLET on I64 provide an interesting ``test case'' |
87b3f81f AC |
29520 | for source compatibility issues, since it is in such system code |
29521 | where assumptions about @code{Address} size might be expected to occur. | |
29522 | Indeed, there were a small number of occasions in the Security Server | |
29523 | file @file{jibdef.ads} | |
29524 | where a representation clause for a record type specified | |
29525 | 32 bits for a component of type @code{Address}. | |
29526 | All of these errors were detected by the compiler. | |
29527 | The repair was obvious and immediate; to simply replace @code{Address} by | |
29528 | @code{Short_Address}. | |
29529 | ||
29530 | In the case of STARLET, there were several record types that should | |
29531 | have had representation clauses but did not. In these record types | |
29532 | there was an implicit assumption that an @code{Address} value occupied | |
29533 | 32 bits. | |
29534 | These compiled without error, but their usage resulted in run-time error | |
29535 | returns from STARLET system calls. | |
ba1cbfb9 RD |
29536 | Future GNAT technology enhancements may include a tool that detects and flags |
29537 | these sorts of potential source code porting problems. | |
87b3f81f AC |
29538 | |
29539 | @c **************************************** | |
29540 | @node Taking advantage of 64 bit addressing | |
29541 | @subsection Taking advantage of 64-bit addressing | |
29542 | ||
29543 | @menu | |
29544 | * Making code 64 bit clean:: | |
29545 | * Allocating memory from the 64 bit storage pool:: | |
29546 | * Restrictions on use of 64 bit objects:: | |
87b3f81f AC |
29547 | * STARLET and other predefined libraries:: |
29548 | @end menu | |
29549 | ||
29550 | @node Making code 64 bit clean | |
29551 | @subsubsection Making code 64-bit clean | |
29552 | ||
29553 | @noindent | |
29554 | In order to prevent problems that may occur when (parts of) a | |
29555 | system start using memory outside the 32-bit address range, | |
29556 | we recommend some additional guidelines: | |
29557 | ||
29558 | @itemize @bullet | |
29559 | @item | |
29560 | For imported subprograms that take parameters of the | |
29561 | type @code{System.Address}, ensure that these subprograms can | |
29562 | indeed handle 64-bit addresses. If not, or when in doubt, | |
29563 | change the subprogram declaration to specify | |
29564 | @code{System.Short_Address} instead. | |
29565 | ||
29566 | @item | |
29567 | Resolve all warnings related to size mismatches in | |
29568 | unchecked conversions. Failing to do so causes | |
29569 | erroneous execution if the source object is outside | |
29570 | the 32-bit address space. | |
29571 | ||
29572 | @item | |
29573 | (optional) Explicitly use the 32-bit storage pool | |
29574 | for access types used in a 32-bit context, or use | |
29575 | generic access types where possible | |
984a64bc | 29576 | (@pxref{Restrictions on use of 64 bit objects}). |
87b3f81f AC |
29577 | @end itemize |
29578 | ||
29579 | @noindent | |
29580 | If these rules are followed, the compiler will automatically insert | |
29581 | any necessary checks to ensure that no addresses or access values | |
29582 | passed to 32-bit code ever refer to objects outside the 32-bit | |
29583 | address range. | |
29584 | Any attempt to do this will raise @code{Constraint_Error}. | |
29585 | ||
29586 | @node Allocating memory from the 64 bit storage pool | |
29587 | @subsubsection Allocating memory from the 64-bit storage pool | |
29588 | ||
29589 | @noindent | |
08564036 AC |
29590 | By default, all allocations -- for both pool-specific and general |
29591 | access types -- use the 64-bit storage pool. To override | |
29592 | this default, for an individual access type or globally, see | |
29593 | @ref{Access types and 32/64-bit allocation}. | |
87b3f81f | 29594 | |
87b3f81f AC |
29595 | @node Restrictions on use of 64 bit objects |
29596 | @subsubsection Restrictions on use of 64-bit objects | |
29597 | ||
29598 | @noindent | |
29599 | Taking the address of an object allocated from a 64-bit storage pool, | |
29600 | and then passing this address to a subprogram expecting | |
29601 | @code{System.Short_Address}, | |
29602 | or assigning it to a variable of type @code{Short_Address}, will cause | |
29603 | @code{Constraint_Error} to be raised. In case the code is not 64-bit clean | |
984a64bc | 29604 | (@pxref{Making code 64 bit clean}), or checks are suppressed, |
87b3f81f AC |
29605 | no exception is raised and execution |
29606 | will become erroneous. | |
29607 | ||
87b3f81f AC |
29608 | @node STARLET and other predefined libraries |
29609 | @subsubsection STARLET and other predefined libraries | |
29610 | ||
29611 | @noindent | |
29612 | All code that comes as part of GNAT is 64-bit clean, but the | |
29613 | restrictions given in @ref{Restrictions on use of 64 bit objects}, | |
29614 | still apply. Look at the package | |
1a5f40e1 | 29615 | specs to see in which contexts objects allocated |
87b3f81f AC |
29616 | in 64-bit address space are acceptable. |
29617 | ||
29618 | @node Technical details | |
29619 | @subsection Technical details | |
29620 | ||
29621 | @noindent | |
ba1cbfb9 RD |
29622 | 64-bit @value{EDITION} for Open VMS takes advantage of the freedom given in the |
29623 | Ada standard with respect to the type of @code{System.Address}. Previous | |
164e06c6 | 29624 | versions of @value{EDITION} have defined this type as private and implemented it as a |
ba1cbfb9 | 29625 | modular type. |
87b3f81f AC |
29626 | |
29627 | In order to allow defining @code{System.Short_Address} as a proper subtype, | |
29628 | and to match the implicit sign extension in parameter passing, | |
ba1cbfb9 | 29629 | in 64-bit @value{EDITION} for Open VMS, @code{System.Address} is defined as a |
87b3f81f AC |
29630 | visible (i.e., non-private) integer type. |
29631 | Standard operations on the type, such as the binary operators ``+'', ``-'', | |
29632 | etc., that take @code{Address} operands and return an @code{Address} result, | |
29633 | have been hidden by declaring these | |
e08b38f5 VC |
29634 | @code{abstract}, a feature introduced in Ada 95 that helps avoid the potential |
29635 | ambiguities that would otherwise result from overloading. | |
87b3f81f AC |
29636 | (Note that, although @code{Address} is a visible integer type, |
29637 | good programming practice dictates against exploiting the type's | |
29638 | integer properties such as literals, since this will compromise | |
29639 | code portability.) | |
29640 | ||
29641 | Defining @code{Address} as a visible integer type helps achieve | |
29642 | maximum compatibility for existing Ada code, | |
ba1cbfb9 | 29643 | without sacrificing the capabilities of the 64-bit architecture. |
87b3f81f AC |
29644 | @end ifset |
29645 | ||
87b3f81f | 29646 | @c ************************************************ |
7cd4527e AC |
29647 | @node Microsoft Windows Topics |
29648 | @appendix Microsoft Windows Topics | |
29649 | @cindex Windows NT | |
29650 | @cindex Windows 95 | |
29651 | @cindex Windows 98 | |
88e1739c FW |
29652 | |
29653 | @noindent | |
7cd4527e AC |
29654 | This chapter describes topics that are specific to the Microsoft Windows |
29655 | platforms (NT, 2000, and XP Professional). | |
88e1739c | 29656 | |
7cd4527e | 29657 | @menu |
03eb6036 AC |
29658 | @ifclear FSFEDITION |
29659 | * Installing from the Command Line:: | |
29660 | @end ifclear | |
7cd4527e AC |
29661 | * Using GNAT on Windows:: |
29662 | * Using a network installation of GNAT:: | |
29663 | * CONSOLE and WINDOWS subsystems:: | |
29664 | * Temporary Files:: | |
29665 | * Mixed-Language Programming on Windows:: | |
29666 | * Windows Calling Conventions:: | |
29667 | * Introduction to Dynamic Link Libraries (DLLs):: | |
29668 | * Using DLLs with GNAT:: | |
5d09245e | 29669 | * Building DLLs with GNAT Project files:: |
3a207e62 | 29670 | * Building DLLs with GNAT:: |
5d09245e | 29671 | * Building DLLs with gnatdll:: |
7cd4527e AC |
29672 | * GNAT and Windows Resources:: |
29673 | * Debugging a DLL:: | |
7e3d710b AC |
29674 | * Setting Stack Size from gnatlink:: |
29675 | * Setting Heap Size from gnatlink:: | |
7cd4527e | 29676 | @end menu |
88e1739c | 29677 | |
03eb6036 AC |
29678 | @ifclear FSFEDITION |
29679 | @node Installing from the Command Line | |
29680 | @section Installing from the Command Line | |
29681 | @cindex Batch installation | |
29682 | @cindex Silent installation | |
29683 | @cindex Unassisted installation | |
29684 | ||
29685 | @noindent | |
29686 | By default the @value{EDITION} installers display a GUI that prompts the user | |
29687 | to enter installation path and similar information, and guide him through the | |
29688 | installation process. It is also possible to perform silent installations | |
29689 | using the command-line interface. | |
29690 | ||
29691 | In order to install one of the @value{EDITION} installers from the command | |
29692 | line you should pass parameter @code{/S} (and, optionally, | |
29693 | @code{/D=<directory>}) as command-line arguments. | |
29694 | ||
29695 | @ifset PROEDITION | |
29696 | For example, for an unattended installation of | |
29697 | @value{EDITION} 7.0.2 into the default directory | |
29698 | @code{C:\GNATPRO\7.0.2} you would run: | |
29699 | ||
29700 | @smallexample | |
29701 | gnatpro-7.0.2-i686-pc-mingw32-bin.exe /S | |
29702 | @end smallexample | |
29703 | ||
29704 | To install into a custom directory, say, @code{C:\TOOLS\GNATPRO\7.0.2}: | |
29705 | ||
29706 | @smallexample | |
29707 | gnatpro-7.0.2-i686-pc-mingw32-bin /S /D=C:\TOOLS\GNATPRO\7.0.2 | |
29708 | @end smallexample | |
29709 | @end ifset | |
29710 | ||
29711 | @ifset GPLEDITION | |
29712 | For example, for an unattended installation of | |
29713 | @value{EDITION} 2012 into @code{C:\GNAT\2012}: | |
29714 | ||
29715 | @smallexample | |
29716 | gnat-gpl-2012-i686-pc-mingw32-bin /S /D=C:\GNAT\2012 | |
29717 | @end smallexample | |
29718 | @end ifset | |
29719 | ||
29720 | You can use the same syntax for all installers. | |
29721 | ||
29722 | Note that unattended installations don't modify system path, nor create file | |
29723 | associations, so such activities need to be done by hand. | |
29724 | @end ifclear | |
29725 | ||
7cd4527e AC |
29726 | @node Using GNAT on Windows |
29727 | @section Using GNAT on Windows | |
88e1739c FW |
29728 | |
29729 | @noindent | |
7cd4527e | 29730 | One of the strengths of the GNAT technology is that its tool set |
984a64bc | 29731 | (@command{gcc}, @command{gnatbind}, @command{gnatlink}, @command{gnatmake}, the |
7cd4527e AC |
29732 | @code{gdb} debugger, etc.) is used in the same way regardless of the |
29733 | platform. | |
88e1739c | 29734 | |
7cd4527e AC |
29735 | On Windows this tool set is complemented by a number of Microsoft-specific |
29736 | tools that have been provided to facilitate interoperability with Windows | |
29737 | when this is required. With these tools: | |
88e1739c | 29738 | |
7cd4527e | 29739 | @itemize @bullet |
88e1739c | 29740 | |
7cd4527e AC |
29741 | @item |
29742 | You can build applications using the @code{CONSOLE} or @code{WINDOWS} | |
29743 | subsystems. | |
88e1739c | 29744 | |
7cd4527e AC |
29745 | @item |
29746 | You can use any Dynamically Linked Library (DLL) in your Ada code (both | |
29747 | relocatable and non-relocatable DLLs are supported). | |
88e1739c | 29748 | |
7cd4527e AC |
29749 | @item |
29750 | You can build Ada DLLs for use in other applications. These applications | |
29751 | can be written in a language other than Ada (e.g., C, C++, etc). Again both | |
29752 | relocatable and non-relocatable Ada DLLs are supported. | |
88e1739c | 29753 | |
7cd4527e AC |
29754 | @item |
29755 | You can include Windows resources in your Ada application. | |
88e1739c | 29756 | |
7cd4527e AC |
29757 | @item |
29758 | You can use or create COM/DCOM objects. | |
29759 | @end itemize | |
88e1739c FW |
29760 | |
29761 | @noindent | |
7cd4527e AC |
29762 | Immediately below are listed all known general GNAT-for-Windows restrictions. |
29763 | Other restrictions about specific features like Windows Resources and DLLs | |
29764 | are listed in separate sections below. | |
88e1739c | 29765 | |
7cd4527e | 29766 | @itemize @bullet |
88e1739c | 29767 | |
7cd4527e AC |
29768 | @item |
29769 | It is not possible to use @code{GetLastError} and @code{SetLastError} | |
29770 | when tasking, protected records, or exceptions are used. In these | |
29771 | cases, in order to implement Ada semantics, the GNAT run-time system | |
29772 | calls certain Win32 routines that set the last error variable to 0 upon | |
29773 | success. It should be possible to use @code{GetLastError} and | |
29774 | @code{SetLastError} when tasking, protected record, and exception | |
29775 | features are not used, but it is not guaranteed to work. | |
88e1739c | 29776 | |
7cd4527e | 29777 | @item |
95081e99 | 29778 | It is not possible to link against Microsoft C++ libraries except for |
3a207e62 | 29779 | import libraries. Interfacing must be done by the mean of DLLs. |
88e1739c | 29780 | |
95081e99 AC |
29781 | @item |
29782 | It is possible to link against Microsoft C libraries. Yet the preferred | |
29783 | solution is to use C/C++ compiler that comes with @value{EDITION}, since it | |
29784 | doesn't require having two different development environments and makes the | |
29785 | inter-language debugging experience smoother. | |
29786 | ||
7cd4527e AC |
29787 | @item |
29788 | When the compilation environment is located on FAT32 drives, users may | |
29789 | experience recompilations of the source files that have not changed if | |
29790 | Daylight Saving Time (DST) state has changed since the last time files | |
29791 | were compiled. NTFS drives do not have this problem. | |
88e1739c | 29792 | |
7cd4527e AC |
29793 | @item |
29794 | No components of the GNAT toolset use any entries in the Windows | |
29795 | registry. The only entries that can be created are file associations and | |
29796 | PATH settings, provided the user has chosen to create them at installation | |
29797 | time, as well as some minimal book-keeping information needed to correctly | |
29798 | uninstall or integrate different GNAT products. | |
29799 | @end itemize | |
88e1739c | 29800 | |
7cd4527e AC |
29801 | @node Using a network installation of GNAT |
29802 | @section Using a network installation of GNAT | |
88e1739c FW |
29803 | |
29804 | @noindent | |
7cd4527e | 29805 | Make sure the system on which GNAT is installed is accessible from the |
8dd07840 | 29806 | current machine, i.e., the install location is shared over the network. |
7cd4527e AC |
29807 | Shared resources are accessed on Windows by means of UNC paths, which |
29808 | have the format @code{\\server\sharename\path} | |
29809 | ||
29810 | In order to use such a network installation, simply add the UNC path of the | |
29811 | @file{bin} directory of your GNAT installation in front of your PATH. For | |
29812 | example, if GNAT is installed in @file{\GNAT} directory of a share location | |
29813 | called @file{c-drive} on a machine @file{LOKI}, the following command will | |
29814 | make it available: | |
29815 | ||
29816 | @code{@ @ @ path \\loki\c-drive\gnat\bin;%path%} | |
29817 | ||
29818 | Be aware that every compilation using the network installation results in the | |
29819 | transfer of large amounts of data across the network and will likely cause | |
29820 | serious performance penalty. | |
29821 | ||
29822 | @node CONSOLE and WINDOWS subsystems | |
29823 | @section CONSOLE and WINDOWS subsystems | |
29824 | @cindex CONSOLE Subsystem | |
29825 | @cindex WINDOWS Subsystem | |
29826 | @cindex -mwindows | |
88e1739c | 29827 | |
7cd4527e AC |
29828 | @noindent |
29829 | There are two main subsystems under Windows. The @code{CONSOLE} subsystem | |
29830 | (which is the default subsystem) will always create a console when | |
29831 | launching the application. This is not something desirable when the | |
29832 | application has a Windows GUI. To get rid of this console the | |
29833 | application must be using the @code{WINDOWS} subsystem. To do so | |
29834 | the @option{-mwindows} linker option must be specified. | |
88e1739c FW |
29835 | |
29836 | @smallexample | |
7cd4527e | 29837 | $ gnatmake winprog -largs -mwindows |
88e1739c FW |
29838 | @end smallexample |
29839 | ||
7cd4527e AC |
29840 | @node Temporary Files |
29841 | @section Temporary Files | |
29842 | @cindex Temporary files | |
88e1739c FW |
29843 | |
29844 | @noindent | |
7cd4527e | 29845 | It is possible to control where temporary files gets created by setting |
443b3472 | 29846 | the @env{TMP} environment variable. The file will be created: |
88e1739c | 29847 | |
7cd4527e | 29848 | @itemize |
443b3472 | 29849 | @item Under the directory pointed to by the @env{TMP} environment variable if |
7cd4527e | 29850 | this directory exists. |
88e1739c | 29851 | |
443b3472 RW |
29852 | @item Under @file{c:\temp}, if the @env{TMP} environment variable is not |
29853 | set (or not pointing to a directory) and if this directory exists. | |
88e1739c | 29854 | |
7cd4527e AC |
29855 | @item Under the current working directory otherwise. |
29856 | @end itemize | |
88e1739c FW |
29857 | |
29858 | @noindent | |
7cd4527e AC |
29859 | This allows you to determine exactly where the temporary |
29860 | file will be created. This is particularly useful in networked | |
29861 | environments where you may not have write access to some | |
29862 | directories. | |
88e1739c | 29863 | |
7cd4527e AC |
29864 | @node Mixed-Language Programming on Windows |
29865 | @section Mixed-Language Programming on Windows | |
88e1739c FW |
29866 | |
29867 | @noindent | |
7cd4527e AC |
29868 | Developing pure Ada applications on Windows is no different than on |
29869 | other GNAT-supported platforms. However, when developing or porting an | |
29870 | application that contains a mix of Ada and C/C++, the choice of your | |
29871 | Windows C/C++ development environment conditions your overall | |
29872 | interoperability strategy. | |
29873 | ||
95081e99 AC |
29874 | If you use @command{gcc} or Microsoft C to compile the non-Ada part of |
29875 | your application, there are no Windows-specific restrictions that | |
29876 | affect the overall interoperability with your Ada code. If you do want | |
29877 | to use the Microsoft tools for your C++ code, you have two choices: | |
88e1739c | 29878 | |
7cd4527e AC |
29879 | @enumerate |
29880 | @item | |
95081e99 | 29881 | Encapsulate your C++ code in a DLL to be linked with your Ada |
7cd4527e AC |
29882 | application. In this case, use the Microsoft or whatever environment to |
29883 | build the DLL and use GNAT to build your executable | |
29884 | (@pxref{Using DLLs with GNAT}). | |
88e1739c | 29885 | |
7cd4527e AC |
29886 | @item |
29887 | Or you can encapsulate your Ada code in a DLL to be linked with the | |
29888 | other part of your application. In this case, use GNAT to build the DLL | |
3a207e62 AC |
29889 | (@pxref{Building DLLs with GNAT Project files}) and use the Microsoft |
29890 | or whatever environment to build your executable. | |
7cd4527e | 29891 | @end enumerate |
88e1739c | 29892 | |
7af1cf83 AC |
29893 | In addition to the description about C main in |
29894 | @pxref{Mixed Language Programming} section, if the C main uses a | |
29895 | stand-alone library it is required on x86-windows to | |
29896 | setup the SEH context. For this the C main must looks like this: | |
29897 | ||
29898 | @smallexample | |
29899 | /* main.c */ | |
29900 | extern void adainit (void); | |
29901 | extern void adafinal (void); | |
29902 | extern void __gnat_initialize(void*); | |
29903 | extern void call_to_ada (void); | |
29904 | ||
29905 | int main (int argc, char *argv[]) | |
29906 | @{ | |
29907 | int SEH [2]; | |
29908 | ||
29909 | /* Initialize the SEH context */ | |
29910 | __gnat_initialize (&SEH); | |
29911 | ||
29912 | adainit(); | |
29913 | ||
29914 | /* Then call Ada services in the stand-alone library */ | |
29915 | ||
29916 | call_to_ada(); | |
29917 | ||
29918 | adafinal(); | |
29919 | @} | |
29920 | @end smallexample | |
29921 | ||
29922 | Note that this is not needed on x86_64-windows where the Windows | |
29923 | native SEH support is used. | |
29924 | ||
7cd4527e AC |
29925 | @node Windows Calling Conventions |
29926 | @section Windows Calling Conventions | |
29927 | @findex Stdcall | |
29928 | @findex APIENTRY | |
88e1739c | 29929 | |
3a207e62 AC |
29930 | This section pertain only to Win32. On Win64 there is a single native |
29931 | calling convention. All convention specifiers are ignored on this | |
29932 | platform. | |
29933 | ||
7cd4527e AC |
29934 | @menu |
29935 | * C Calling Convention:: | |
29936 | * Stdcall Calling Convention:: | |
32e209e4 | 29937 | * Win32 Calling Convention:: |
7cd4527e AC |
29938 | * DLL Calling Convention:: |
29939 | @end menu | |
88e1739c FW |
29940 | |
29941 | @noindent | |
7cd4527e AC |
29942 | When a subprogram @code{F} (caller) calls a subprogram @code{G} |
29943 | (callee), there are several ways to push @code{G}'s parameters on the | |
29944 | stack and there are several possible scenarios to clean up the stack | |
29945 | upon @code{G}'s return. A calling convention is an agreed upon software | |
29946 | protocol whereby the responsibilities between the caller (@code{F}) and | |
29947 | the callee (@code{G}) are clearly defined. Several calling conventions | |
29948 | are available for Windows: | |
88e1739c FW |
29949 | |
29950 | @itemize @bullet | |
29951 | @item | |
7cd4527e | 29952 | @code{C} (Microsoft defined) |
88e1739c FW |
29953 | |
29954 | @item | |
7cd4527e | 29955 | @code{Stdcall} (Microsoft defined) |
88e1739c | 29956 | |
32e209e4 CC |
29957 | @item |
29958 | @code{Win32} (GNAT specific) | |
29959 | ||
88e1739c | 29960 | @item |
7cd4527e | 29961 | @code{DLL} (GNAT specific) |
88e1739c FW |
29962 | @end itemize |
29963 | ||
7cd4527e AC |
29964 | @node C Calling Convention |
29965 | @subsection @code{C} Calling Convention | |
88e1739c FW |
29966 | |
29967 | @noindent | |
7cd4527e | 29968 | This is the default calling convention used when interfacing to C/C++ |
984a64bc | 29969 | routines compiled with either @command{gcc} or Microsoft Visual C++. |
88e1739c | 29970 | |
7cd4527e AC |
29971 | In the @code{C} calling convention subprogram parameters are pushed on the |
29972 | stack by the caller from right to left. The caller itself is in charge of | |
29973 | cleaning up the stack after the call. In addition, the name of a routine | |
29974 | with @code{C} calling convention is mangled by adding a leading underscore. | |
88e1739c | 29975 | |
7cd4527e AC |
29976 | The name to use on the Ada side when importing (or exporting) a routine |
29977 | with @code{C} calling convention is the name of the routine. For | |
29978 | instance the C function: | |
88e1739c FW |
29979 | |
29980 | @smallexample | |
7cd4527e AC |
29981 | int get_val (long); |
29982 | @end smallexample | |
88e1739c | 29983 | |
7cd4527e AC |
29984 | @noindent |
29985 | should be imported from Ada as follows: | |
88e1739c | 29986 | |
7cd4527e AC |
29987 | @smallexample @c ada |
29988 | @group | |
29989 | function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; | |
29990 | pragma Import (C, Get_Val, External_Name => "get_val"); | |
29991 | @end group | |
29992 | @end smallexample | |
88e1739c | 29993 | |
7cd4527e AC |
29994 | @noindent |
29995 | Note that in this particular case the @code{External_Name} parameter could | |
29996 | have been omitted since, when missing, this parameter is taken to be the | |
29997 | name of the Ada entity in lower case. When the @code{Link_Name} parameter | |
29998 | is missing, as in the above example, this parameter is set to be the | |
29999 | @code{External_Name} with a leading underscore. | |
88e1739c | 30000 | |
7cd4527e AC |
30001 | When importing a variable defined in C, you should always use the @code{C} |
30002 | calling convention unless the object containing the variable is part of a | |
32e209e4 CC |
30003 | DLL (in which case you should use the @code{Stdcall} calling |
30004 | convention, @pxref{Stdcall Calling Convention}). | |
88e1739c | 30005 | |
7cd4527e AC |
30006 | @node Stdcall Calling Convention |
30007 | @subsection @code{Stdcall} Calling Convention | |
88e1739c | 30008 | |
7cd4527e AC |
30009 | @noindent |
30010 | This convention, which was the calling convention used for Pascal | |
30011 | programs, is used by Microsoft for all the routines in the Win32 API for | |
30012 | efficiency reasons. It must be used to import any routine for which this | |
30013 | convention was specified. | |
88e1739c | 30014 | |
7cd4527e AC |
30015 | In the @code{Stdcall} calling convention subprogram parameters are pushed |
30016 | on the stack by the caller from right to left. The callee (and not the | |
30017 | caller) is in charge of cleaning the stack on routine exit. In addition, | |
30018 | the name of a routine with @code{Stdcall} calling convention is mangled by | |
30019 | adding a leading underscore (as for the @code{C} calling convention) and a | |
66bfd481 | 30020 | trailing @code{@@}@code{@var{nn}}, where @var{nn} is the overall size (in |
7cd4527e | 30021 | bytes) of the parameters passed to the routine. |
88e1739c | 30022 | |
7cd4527e AC |
30023 | The name to use on the Ada side when importing a C routine with a |
30024 | @code{Stdcall} calling convention is the name of the C routine. The leading | |
66bfd481 | 30025 | underscore and trailing @code{@@}@code{@var{nn}} are added automatically by |
7cd4527e | 30026 | the compiler. For instance the Win32 function: |
88e1739c | 30027 | |
7cd4527e AC |
30028 | @smallexample |
30029 | @b{APIENTRY} int get_val (long); | |
30030 | @end smallexample | |
88e1739c | 30031 | |
7cd4527e AC |
30032 | @noindent |
30033 | should be imported from Ada as follows: | |
88e1739c | 30034 | |
7cd4527e AC |
30035 | @smallexample @c ada |
30036 | @group | |
30037 | function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; | |
30038 | pragma Import (Stdcall, Get_Val); | |
30039 | -- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4" | |
30040 | @end group | |
30041 | @end smallexample | |
88e1739c | 30042 | |
7cd4527e AC |
30043 | @noindent |
30044 | As for the @code{C} calling convention, when the @code{External_Name} | |
30045 | parameter is missing, it is taken to be the name of the Ada entity in lower | |
30046 | case. If instead of writing the above import pragma you write: | |
88e1739c | 30047 | |
7cd4527e AC |
30048 | @smallexample @c ada |
30049 | @group | |
30050 | function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; | |
30051 | pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val"); | |
30052 | @end group | |
30053 | @end smallexample | |
88e1739c | 30054 | |
7cd4527e AC |
30055 | @noindent |
30056 | then the imported routine is @code{_retrieve_val@@4}. However, if instead | |
30057 | of specifying the @code{External_Name} parameter you specify the | |
30058 | @code{Link_Name} as in the following example: | |
88e1739c | 30059 | |
7cd4527e AC |
30060 | @smallexample @c ada |
30061 | @group | |
30062 | function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; | |
30063 | pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val"); | |
30064 | @end group | |
88e1739c FW |
30065 | @end smallexample |
30066 | ||
88e1739c | 30067 | @noindent |
0916df6a RD |
30068 | then the imported routine is @code{retrieve_val}, that is, there is no |
30069 | decoration at all. No leading underscore and no Stdcall suffix | |
66bfd481 | 30070 | @code{@@}@code{@var{nn}}. |
88e1739c | 30071 | |
7cd4527e | 30072 | @noindent |
0916df6a | 30073 | This is especially important as in some special cases a DLL's entry |
66bfd481 | 30074 | point name lacks a trailing @code{@@}@code{@var{nn}} while the exported |
0916df6a | 30075 | name generated for a call has it. |
88e1739c | 30076 | |
7cd4527e | 30077 | @noindent |
32e209e4 CC |
30078 | It is also possible to import variables defined in a DLL by using an |
30079 | import pragma for a variable. As an example, if a DLL contains a | |
30080 | variable defined as: | |
88e1739c FW |
30081 | |
30082 | @smallexample | |
7cd4527e AC |
30083 | int my_var; |
30084 | @end smallexample | |
88e1739c | 30085 | |
7cd4527e AC |
30086 | @noindent |
30087 | then, to access this variable from Ada you should write: | |
88e1739c | 30088 | |
7cd4527e AC |
30089 | @smallexample @c ada |
30090 | @group | |
30091 | My_Var : Interfaces.C.int; | |
32e209e4 | 30092 | pragma Import (Stdcall, My_Var); |
7cd4527e AC |
30093 | @end group |
30094 | @end smallexample | |
88e1739c | 30095 | |
32e209e4 CC |
30096 | @noindent |
30097 | Note that to ease building cross-platform bindings this convention | |
4d0e4612 | 30098 | will be handled as a @code{C} calling convention on non-Windows platforms. |
32e209e4 CC |
30099 | |
30100 | @node Win32 Calling Convention | |
30101 | @subsection @code{Win32} Calling Convention | |
30102 | ||
30103 | @noindent | |
30104 | This convention, which is GNAT-specific is fully equivalent to the | |
30105 | @code{Stdcall} calling convention described above. | |
30106 | ||
30107 | @node DLL Calling Convention | |
30108 | @subsection @code{DLL} Calling Convention | |
30109 | ||
30110 | @noindent | |
30111 | This convention, which is GNAT-specific is fully equivalent to the | |
30112 | @code{Stdcall} calling convention described above. | |
88e1739c | 30113 | |
7cd4527e AC |
30114 | @node Introduction to Dynamic Link Libraries (DLLs) |
30115 | @section Introduction to Dynamic Link Libraries (DLLs) | |
30116 | @findex DLL | |
88e1739c | 30117 | |
7cd4527e AC |
30118 | @noindent |
30119 | A Dynamically Linked Library (DLL) is a library that can be shared by | |
30120 | several applications running under Windows. A DLL can contain any number of | |
30121 | routines and variables. | |
88e1739c | 30122 | |
7cd4527e AC |
30123 | One advantage of DLLs is that you can change and enhance them without |
30124 | forcing all the applications that depend on them to be relinked or | |
30125 | recompiled. However, you should be aware than all calls to DLL routines are | |
30126 | slower since, as you will understand below, such calls are indirect. | |
88e1739c | 30127 | |
7cd4527e AC |
30128 | To illustrate the remainder of this section, suppose that an application |
30129 | wants to use the services of a DLL @file{API.dll}. To use the services | |
5d09245e AC |
30130 | provided by @file{API.dll} you must statically link against the DLL or |
30131 | an import library which contains a jump table with an entry for each | |
30132 | routine and variable exported by the DLL. In the Microsoft world this | |
30133 | import library is called @file{API.lib}. When using GNAT this import | |
c690a2ec RD |
30134 | library is called either @file{libAPI.dll.a}, @file{libapi.dll.a}, |
30135 | @file{libAPI.a} or @file{libapi.a} (names are case insensitive). | |
5d09245e AC |
30136 | |
30137 | After you have linked your application with the DLL or the import library | |
7cd4527e | 30138 | and you run your application, here is what happens: |
88e1739c | 30139 | |
7cd4527e AC |
30140 | @enumerate |
30141 | @item | |
30142 | Your application is loaded into memory. | |
88e1739c | 30143 | |
7cd4527e AC |
30144 | @item |
30145 | The DLL @file{API.dll} is mapped into the address space of your | |
30146 | application. This means that: | |
88e1739c | 30147 | |
7cd4527e AC |
30148 | @itemize @bullet |
30149 | @item | |
30150 | The DLL will use the stack of the calling thread. | |
88e1739c | 30151 | |
7cd4527e AC |
30152 | @item |
30153 | The DLL will use the virtual address space of the calling process. | |
88e1739c | 30154 | |
7cd4527e AC |
30155 | @item |
30156 | The DLL will allocate memory from the virtual address space of the calling | |
30157 | process. | |
88e1739c | 30158 | |
7cd4527e AC |
30159 | @item |
30160 | Handles (pointers) can be safely exchanged between routines in the DLL | |
30161 | routines and routines in the application using the DLL. | |
30162 | @end itemize | |
88e1739c | 30163 | |
7cd4527e | 30164 | @item |
c690a2ec | 30165 | The entries in the jump table (from the import library @file{libAPI.dll.a} |
5d09245e AC |
30166 | or @file{API.lib} or automatically created when linking against a DLL) |
30167 | which is part of your application are initialized with the addresses | |
30168 | of the routines and variables in @file{API.dll}. | |
88e1739c | 30169 | |
7cd4527e AC |
30170 | @item |
30171 | If present in @file{API.dll}, routines @code{DllMain} or | |
30172 | @code{DllMainCRTStartup} are invoked. These routines typically contain | |
30173 | the initialization code needed for the well-being of the routines and | |
30174 | variables exported by the DLL. | |
30175 | @end enumerate | |
88e1739c FW |
30176 | |
30177 | @noindent | |
7cd4527e AC |
30178 | There is an additional point which is worth mentioning. In the Windows |
30179 | world there are two kind of DLLs: relocatable and non-relocatable | |
30180 | DLLs. Non-relocatable DLLs can only be loaded at a very specific address | |
30181 | in the target application address space. If the addresses of two | |
30182 | non-relocatable DLLs overlap and these happen to be used by the same | |
30183 | application, a conflict will occur and the application will run | |
30184 | incorrectly. Hence, when possible, it is always preferable to use and | |
30185 | build relocatable DLLs. Both relocatable and non-relocatable DLLs are | |
30186 | supported by GNAT. Note that the @option{-s} linker option (see GNU Linker | |
30187 | User's Guide) removes the debugging symbols from the DLL but the DLL can | |
30188 | still be relocated. | |
88e1739c | 30189 | |
7cd4527e AC |
30190 | As a side note, an interesting difference between Microsoft DLLs and |
30191 | Unix shared libraries, is the fact that on most Unix systems all public | |
30192 | routines are exported by default in a Unix shared library, while under | |
5d09245e AC |
30193 | Windows it is possible (but not required) to list exported routines in |
30194 | a definition file (@pxref{The Definition File}). | |
88e1739c | 30195 | |
7cd4527e AC |
30196 | @node Using DLLs with GNAT |
30197 | @section Using DLLs with GNAT | |
88e1739c | 30198 | |
7cd4527e AC |
30199 | @menu |
30200 | * Creating an Ada Spec for the DLL Services:: | |
30201 | * Creating an Import Library:: | |
30202 | @end menu | |
88e1739c | 30203 | |
7cd4527e AC |
30204 | @noindent |
30205 | To use the services of a DLL, say @file{API.dll}, in your Ada application | |
30206 | you must have: | |
88e1739c | 30207 | |
7cd4527e AC |
30208 | @enumerate |
30209 | @item | |
30210 | The Ada spec for the routines and/or variables you want to access in | |
30211 | @file{API.dll}. If not available this Ada spec must be built from the C/C++ | |
30212 | header files provided with the DLL. | |
88e1739c | 30213 | |
7cd4527e | 30214 | @item |
c690a2ec | 30215 | The import library (@file{libAPI.dll.a} or @file{API.lib}). As previously |
7cd4527e AC |
30216 | mentioned an import library is a statically linked library containing the |
30217 | import table which will be filled at load time to point to the actual | |
30218 | @file{API.dll} routines. Sometimes you don't have an import library for the | |
5d09245e AC |
30219 | DLL you want to use. The following sections will explain how to build |
30220 | one. Note that this is optional. | |
88e1739c | 30221 | |
7cd4527e AC |
30222 | @item |
30223 | The actual DLL, @file{API.dll}. | |
30224 | @end enumerate | |
88e1739c | 30225 | |
7cd4527e AC |
30226 | @noindent |
30227 | Once you have all the above, to compile an Ada application that uses the | |
30228 | services of @file{API.dll} and whose main subprogram is @code{My_Ada_App}, | |
30229 | you simply issue the command | |
88e1739c | 30230 | |
7cd4527e AC |
30231 | @smallexample |
30232 | $ gnatmake my_ada_app -largs -lAPI | |
30233 | @end smallexample | |
88e1739c | 30234 | |
7cd4527e | 30235 | @noindent |
984a64bc | 30236 | The argument @option{-largs -lAPI} at the end of the @command{gnatmake} command |
3a207e62 AC |
30237 | tells the GNAT linker to look for an import library. The linker will |
30238 | look for a library name in this specific order: | |
30239 | ||
30240 | @enumerate | |
30241 | @item @file{libAPI.dll.a} | |
30242 | @item @file{API.dll.a} | |
30243 | @item @file{libAPI.a} | |
30244 | @item @file{API.lib} | |
30245 | @item @file{libAPI.dll} | |
30246 | @item @file{API.dll} | |
30247 | @end enumerate | |
30248 | ||
30249 | The first three are the GNU style import libraries. The third is the | |
308e6f3a | 30250 | Microsoft style import libraries. The last two are the actual DLL names. |
3a207e62 AC |
30251 | |
30252 | Note that if the Ada package spec for @file{API.dll} contains the | |
30253 | following pragma | |
88e1739c | 30254 | |
7cd4527e AC |
30255 | @smallexample @c ada |
30256 | pragma Linker_Options ("-lAPI"); | |
30257 | @end smallexample | |
88e1739c | 30258 | |
7cd4527e | 30259 | @noindent |
984a64bc AC |
30260 | you do not have to add @option{-largs -lAPI} at the end of the |
30261 | @command{gnatmake} command. | |
88e1739c | 30262 | |
7cd4527e AC |
30263 | If any one of the items above is missing you will have to create it |
30264 | yourself. The following sections explain how to do so using as an | |
30265 | example a fictitious DLL called @file{API.dll}. | |
88e1739c | 30266 | |
7cd4527e AC |
30267 | @node Creating an Ada Spec for the DLL Services |
30268 | @subsection Creating an Ada Spec for the DLL Services | |
88e1739c | 30269 | |
7cd4527e AC |
30270 | @noindent |
30271 | A DLL typically comes with a C/C++ header file which provides the | |
30272 | definitions of the routines and variables exported by the DLL. The Ada | |
30273 | equivalent of this header file is a package spec that contains definitions | |
30274 | for the imported entities. If the DLL you intend to use does not come with | |
30275 | an Ada spec you have to generate one such spec yourself. For example if | |
30276 | the header file of @file{API.dll} is a file @file{api.h} containing the | |
30277 | following two definitions: | |
88e1739c | 30278 | |
7cd4527e AC |
30279 | @smallexample |
30280 | @group | |
30281 | @cartouche | |
30282 | int some_var; | |
30283 | int get (char *); | |
30284 | @end cartouche | |
30285 | @end group | |
30286 | @end smallexample | |
88e1739c | 30287 | |
7cd4527e AC |
30288 | @noindent |
30289 | then the equivalent Ada spec could be: | |
88e1739c | 30290 | |
7cd4527e AC |
30291 | @smallexample @c ada |
30292 | @group | |
30293 | @cartouche | |
30294 | with Interfaces.C.Strings; | |
30295 | package API is | |
30296 | use Interfaces; | |
88e1739c | 30297 | |
7cd4527e AC |
30298 | Some_Var : C.int; |
30299 | function Get (Str : C.Strings.Chars_Ptr) return C.int; | |
88e1739c | 30300 | |
7cd4527e AC |
30301 | private |
30302 | pragma Import (C, Get); | |
30303 | pragma Import (DLL, Some_Var); | |
30304 | end API; | |
30305 | @end cartouche | |
30306 | @end group | |
30307 | @end smallexample | |
88e1739c | 30308 | |
7cd4527e AC |
30309 | @node Creating an Import Library |
30310 | @subsection Creating an Import Library | |
30311 | @cindex Import library | |
88e1739c | 30312 | |
7cd4527e AC |
30313 | @menu |
30314 | * The Definition File:: | |
30315 | * GNAT-Style Import Library:: | |
30316 | * Microsoft-Style Import Library:: | |
30317 | @end menu | |
88e1739c | 30318 | |
7cd4527e AC |
30319 | @noindent |
30320 | If a Microsoft-style import library @file{API.lib} or a GNAT-style | |
c690a2ec RD |
30321 | import library @file{libAPI.dll.a} or @file{libAPI.a} is available |
30322 | with @file{API.dll} you can skip this section. You can also skip this | |
30323 | section if @file{API.dll} or @file{libAPI.dll} is built with GNU tools | |
30324 | as in this case it is possible to link directly against the | |
30325 | DLL. Otherwise read on. | |
88e1739c | 30326 | |
7cd4527e AC |
30327 | @node The Definition File |
30328 | @subsubsection The Definition File | |
30329 | @cindex Definition file | |
30330 | @findex .def | |
88e1739c | 30331 | |
7cd4527e AC |
30332 | @noindent |
30333 | As previously mentioned, and unlike Unix systems, the list of symbols | |
30334 | that are exported from a DLL must be provided explicitly in Windows. | |
30335 | The main goal of a definition file is precisely that: list the symbols | |
30336 | exported by a DLL. A definition file (usually a file with a @code{.def} | |
30337 | suffix) has the following structure: | |
88e1739c | 30338 | |
7cd4527e AC |
30339 | @smallexample |
30340 | @group | |
30341 | @cartouche | |
66bfd481 RW |
30342 | @r{[}LIBRARY @var{name}@r{]} |
30343 | @r{[}DESCRIPTION @var{string}@r{]} | |
7cd4527e | 30344 | EXPORTS |
66bfd481 RW |
30345 | @var{symbol1} |
30346 | @var{symbol2} | |
d488f6ea | 30347 | @dots{} |
7cd4527e AC |
30348 | @end cartouche |
30349 | @end group | |
88e1739c FW |
30350 | @end smallexample |
30351 | ||
7cd4527e | 30352 | @table @code |
66bfd481 | 30353 | @item LIBRARY @var{name} |
7cd4527e | 30354 | This section, which is optional, gives the name of the DLL. |
88e1739c | 30355 | |
66bfd481 | 30356 | @item DESCRIPTION @var{string} |
7cd4527e AC |
30357 | This section, which is optional, gives a description string that will be |
30358 | embedded in the import library. | |
88e1739c | 30359 | |
7cd4527e AC |
30360 | @item EXPORTS |
30361 | This section gives the list of exported symbols (procedures, functions or | |
30362 | variables). For instance in the case of @file{API.dll} the @code{EXPORTS} | |
30363 | section of @file{API.def} looks like: | |
88e1739c FW |
30364 | |
30365 | @smallexample | |
7cd4527e AC |
30366 | @group |
30367 | @cartouche | |
30368 | EXPORTS | |
30369 | some_var | |
30370 | get | |
30371 | @end cartouche | |
30372 | @end group | |
88e1739c | 30373 | @end smallexample |
7cd4527e | 30374 | @end table |
88e1739c FW |
30375 | |
30376 | @noindent | |
66bfd481 | 30377 | Note that you must specify the correct suffix (@code{@@}@code{@var{nn}}) |
7cd4527e AC |
30378 | (@pxref{Windows Calling Conventions}) for a Stdcall |
30379 | calling convention function in the exported symbols list. | |
88e1739c | 30380 | |
7cd4527e AC |
30381 | @noindent |
30382 | There can actually be other sections in a definition file, but these | |
30383 | sections are not relevant to the discussion at hand. | |
88e1739c | 30384 | |
7cd4527e AC |
30385 | @node GNAT-Style Import Library |
30386 | @subsubsection GNAT-Style Import Library | |
88e1739c | 30387 | |
7cd4527e AC |
30388 | @noindent |
30389 | To create a static import library from @file{API.dll} with the GNAT tools | |
30390 | you should proceed as follows: | |
88e1739c | 30391 | |
7cd4527e AC |
30392 | @enumerate |
30393 | @item | |
30394 | Create the definition file @file{API.def} (@pxref{The Definition File}). | |
30395 | For that use the @code{dll2def} tool as follows: | |
88e1739c | 30396 | |
7cd4527e AC |
30397 | @smallexample |
30398 | $ dll2def API.dll > API.def | |
30399 | @end smallexample | |
88e1739c | 30400 | |
7cd4527e AC |
30401 | @noindent |
30402 | @code{dll2def} is a very simple tool: it takes as input a DLL and prints | |
30403 | to standard output the list of entry points in the DLL. Note that if | |
30404 | some routines in the DLL have the @code{Stdcall} convention | |
66bfd481 | 30405 | (@pxref{Windows Calling Conventions}) with stripped @code{@@}@var{nn} |
0ab80019 | 30406 | suffix then you'll have to edit @file{api.def} to add it, and specify |
1992bbd9 | 30407 | @option{-k} to @command{gnatdll} when creating the import library. |
88e1739c | 30408 | |
7cd4527e | 30409 | @noindent |
66bfd481 | 30410 | Here are some hints to find the right @code{@@}@var{nn} suffix. |
88e1739c | 30411 | |
7cd4527e AC |
30412 | @enumerate |
30413 | @item | |
30414 | If you have the Microsoft import library (.lib), it is possible to get | |
30415 | the right symbols by using Microsoft @code{dumpbin} tool (see the | |
30416 | corresponding Microsoft documentation for further details). | |
88e1739c | 30417 | |
7cd4527e AC |
30418 | @smallexample |
30419 | $ dumpbin /exports api.lib | |
30420 | @end smallexample | |
88e1739c | 30421 | |
7cd4527e AC |
30422 | @item |
30423 | If you have a message about a missing symbol at link time the compiler | |
30424 | tells you what symbol is expected. You just have to go back to the | |
30425 | definition file and add the right suffix. | |
30426 | @end enumerate | |
88e1739c | 30427 | |
7cd4527e | 30428 | @item |
c690a2ec | 30429 | Build the import library @code{libAPI.dll.a}, using @code{gnatdll} |
7cd4527e | 30430 | (@pxref{Using gnatdll}) as follows: |
88e1739c | 30431 | |
7cd4527e AC |
30432 | @smallexample |
30433 | $ gnatdll -e API.def -d API.dll | |
30434 | @end smallexample | |
88e1739c | 30435 | |
7cd4527e AC |
30436 | @noindent |
30437 | @code{gnatdll} takes as input a definition file @file{API.def} and the | |
30438 | name of the DLL containing the services listed in the definition file | |
30439 | @file{API.dll}. The name of the static import library generated is | |
30440 | computed from the name of the definition file as follows: if the | |
66bfd481 RW |
30441 | definition file name is @var{xyz}@code{.def}, the import library name will |
30442 | be @code{lib}@var{xyz}@code{.a}. Note that in the previous example option | |
7cd4527e AC |
30443 | @option{-e} could have been removed because the name of the definition |
30444 | file (before the ``@code{.def}'' suffix) is the same as the name of the | |
30445 | DLL (@pxref{Using gnatdll} for more information about @code{gnatdll}). | |
30446 | @end enumerate | |
88e1739c | 30447 | |
7cd4527e AC |
30448 | @node Microsoft-Style Import Library |
30449 | @subsubsection Microsoft-Style Import Library | |
88e1739c | 30450 | |
7cd4527e AC |
30451 | @noindent |
30452 | With GNAT you can either use a GNAT-style or Microsoft-style import | |
30453 | library. A Microsoft import library is needed only if you plan to make an | |
30454 | Ada DLL available to applications developed with Microsoft | |
30455 | tools (@pxref{Mixed-Language Programming on Windows}). | |
88e1739c | 30456 | |
7cd4527e AC |
30457 | To create a Microsoft-style import library for @file{API.dll} you |
30458 | should proceed as follows: | |
88e1739c | 30459 | |
7cd4527e AC |
30460 | @enumerate |
30461 | @item | |
30462 | Create the definition file @file{API.def} from the DLL. For this use either | |
30463 | the @code{dll2def} tool as described above or the Microsoft @code{dumpbin} | |
30464 | tool (see the corresponding Microsoft documentation for further details). | |
88e1739c | 30465 | |
7cd4527e AC |
30466 | @item |
30467 | Build the actual import library using Microsoft's @code{lib} utility: | |
88e1739c FW |
30468 | |
30469 | @smallexample | |
7cd4527e | 30470 | $ lib -machine:IX86 -def:API.def -out:API.lib |
88e1739c FW |
30471 | @end smallexample |
30472 | ||
30473 | @noindent | |
7cd4527e AC |
30474 | If you use the above command the definition file @file{API.def} must |
30475 | contain a line giving the name of the DLL: | |
88e1739c FW |
30476 | |
30477 | @smallexample | |
7cd4527e | 30478 | LIBRARY "API" |
88e1739c FW |
30479 | @end smallexample |
30480 | ||
30481 | @noindent | |
7cd4527e AC |
30482 | See the Microsoft documentation for further details about the usage of |
30483 | @code{lib}. | |
30484 | @end enumerate | |
88e1739c | 30485 | |
3a207e62 AC |
30486 | @node Building DLLs with GNAT Project files |
30487 | @section Building DLLs with GNAT Project files | |
30488 | @cindex DLLs, building | |
30489 | ||
30490 | @noindent | |
30491 | There is nothing specific to Windows in the build process. | |
30492 | @pxref{Library Projects}. | |
30493 | ||
30494 | @noindent | |
30495 | Due to a system limitation, it is not possible under Windows to create threads | |
30496 | when inside the @code{DllMain} routine which is used for auto-initialization | |
30497 | of shared libraries, so it is not possible to have library level tasks in SALs. | |
30498 | ||
7cd4527e AC |
30499 | @node Building DLLs with GNAT |
30500 | @section Building DLLs with GNAT | |
30501 | @cindex DLLs, building | |
88e1739c | 30502 | |
5d09245e AC |
30503 | @noindent |
30504 | This section explain how to build DLLs using the GNAT built-in DLL | |
30505 | support. With the following procedure it is straight forward to build | |
30506 | and use DLLs with GNAT. | |
30507 | ||
30508 | @enumerate | |
30509 | ||
30510 | @item building object files | |
30511 | ||
30512 | The first step is to build all objects files that are to be included | |
984a64bc | 30513 | into the DLL. This is done by using the standard @command{gnatmake} tool. |
5d09245e AC |
30514 | |
30515 | @item building the DLL | |
30516 | ||
1c218ac3 AC |
30517 | To build the DLL you must use @command{gcc}'s @option{-shared} and |
30518 | @option{-shared-libgcc} options. It is quite simple to use this method: | |
5d09245e AC |
30519 | |
30520 | @smallexample | |
1c218ac3 | 30521 | $ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o @dots{} |
5d09245e AC |
30522 | @end smallexample |
30523 | ||
30524 | It is important to note that in this case all symbols found in the | |
30525 | object files are automatically exported. It is possible to restrict | |
984a64bc | 30526 | the set of symbols to export by passing to @command{gcc} a definition |
5d09245e AC |
30527 | file, @pxref{The Definition File}. For example: |
30528 | ||
30529 | @smallexample | |
1c218ac3 | 30530 | $ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o @dots{} |
5d09245e AC |
30531 | @end smallexample |
30532 | ||
30533 | If you use a definition file you must export the elaboration procedures | |
30534 | for every package that required one. Elaboration procedures are named | |
30535 | using the package name followed by "_E". | |
30536 | ||
30537 | @item preparing DLL to be used | |
30538 | ||
30539 | For the DLL to be used by client programs the bodies must be hidden | |
30540 | from it and the .ali set with read-only attribute. This is very important | |
30541 | otherwise GNAT will recompile all packages and will not actually use | |
30542 | the code in the DLL. For example: | |
30543 | ||
30544 | @smallexample | |
30545 | $ mkdir apilib | |
30546 | $ copy *.ads *.ali api.dll apilib | |
30547 | $ attrib +R apilib\*.ali | |
30548 | @end smallexample | |
30549 | ||
30550 | @end enumerate | |
30551 | ||
30552 | At this point it is possible to use the DLL by directly linking | |
30553 | against it. Note that you must use the GNAT shared runtime when using | |
1992bbd9 | 30554 | GNAT shared libraries. This is achieved by using @option{-shared} binder's |
5d09245e AC |
30555 | option. |
30556 | ||
30557 | @smallexample | |
30558 | $ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI | |
30559 | @end smallexample | |
30560 | ||
5d09245e AC |
30561 | @node Building DLLs with gnatdll |
30562 | @section Building DLLs with gnatdll | |
30563 | @cindex DLLs, building | |
30564 | ||
7cd4527e AC |
30565 | @menu |
30566 | * Limitations When Using Ada DLLs from Ada:: | |
30567 | * Exporting Ada Entities:: | |
30568 | * Ada DLLs and Elaboration:: | |
30569 | * Ada DLLs and Finalization:: | |
30570 | * Creating a Spec for Ada DLLs:: | |
30571 | * Creating the Definition File:: | |
30572 | * Using gnatdll:: | |
30573 | @end menu | |
88e1739c FW |
30574 | |
30575 | @noindent | |
3a207e62 AC |
30576 | Note that it is preferred to use GNAT Project files |
30577 | (@pxref{Building DLLs with GNAT Project files}) or the built-in GNAT | |
30578 | DLL support (@pxref{Building DLLs with GNAT}) or to build DLLs. | |
5d09245e AC |
30579 | |
30580 | This section explains how to build DLLs containing Ada code using | |
30581 | @code{gnatdll}. These DLLs will be referred to as Ada DLLs in the | |
30582 | remainder of this section. | |
88e1739c | 30583 | |
7cd4527e AC |
30584 | The steps required to build an Ada DLL that is to be used by Ada as well as |
30585 | non-Ada applications are as follows: | |
88e1739c | 30586 | |
7cd4527e AC |
30587 | @enumerate |
30588 | @item | |
30589 | You need to mark each Ada @i{entity} exported by the DLL with a @code{C} or | |
30590 | @code{Stdcall} calling convention to avoid any Ada name mangling for the | |
30591 | entities exported by the DLL (@pxref{Exporting Ada Entities}). You can | |
30592 | skip this step if you plan to use the Ada DLL only from Ada applications. | |
88e1739c | 30593 | |
7cd4527e AC |
30594 | @item |
30595 | Your Ada code must export an initialization routine which calls the routine | |
984a64bc | 30596 | @code{adainit} generated by @command{gnatbind} to perform the elaboration of |
7cd4527e AC |
30597 | the Ada code in the DLL (@pxref{Ada DLLs and Elaboration}). The initialization |
30598 | routine exported by the Ada DLL must be invoked by the clients of the DLL | |
30599 | to initialize the DLL. | |
88e1739c | 30600 | |
7cd4527e AC |
30601 | @item |
30602 | When useful, the DLL should also export a finalization routine which calls | |
984a64bc | 30603 | routine @code{adafinal} generated by @command{gnatbind} to perform the |
7cd4527e AC |
30604 | finalization of the Ada code in the DLL (@pxref{Ada DLLs and Finalization}). |
30605 | The finalization routine exported by the Ada DLL must be invoked by the | |
30606 | clients of the DLL when the DLL services are no further needed. | |
30607 | ||
30608 | @item | |
30609 | You must provide a spec for the services exported by the Ada DLL in each | |
30610 | of the programming languages to which you plan to make the DLL available. | |
88e1739c | 30611 | |
7cd4527e AC |
30612 | @item |
30613 | You must provide a definition file listing the exported entities | |
30614 | (@pxref{The Definition File}). | |
88e1739c | 30615 | |
7cd4527e AC |
30616 | @item |
30617 | Finally you must use @code{gnatdll} to produce the DLL and the import | |
30618 | library (@pxref{Using gnatdll}). | |
30619 | @end enumerate | |
88e1739c FW |
30620 | |
30621 | @noindent | |
c279327b | 30622 | Note that a relocatable DLL stripped using the @code{strip} |
32e209e4 CC |
30623 | binutils tool will not be relocatable anymore. To build a DLL without |
30624 | debug information pass @code{-largs -s} to @code{gnatdll}. This | |
30625 | restriction does not apply to a DLL built using a Library Project. | |
30626 | @pxref{Library Projects}. | |
88e1739c | 30627 | |
7cd4527e AC |
30628 | @node Limitations When Using Ada DLLs from Ada |
30629 | @subsection Limitations When Using Ada DLLs from Ada | |
88e1739c FW |
30630 | |
30631 | @noindent | |
7cd4527e AC |
30632 | When using Ada DLLs from Ada applications there is a limitation users |
30633 | should be aware of. Because on Windows the GNAT run time is not in a DLL of | |
30634 | its own, each Ada DLL includes a part of the GNAT run time. Specifically, | |
30635 | each Ada DLL includes the services of the GNAT run time that are necessary | |
30636 | to the Ada code inside the DLL. As a result, when an Ada program uses an | |
30637 | Ada DLL there are two independent GNAT run times: one in the Ada DLL and | |
30638 | one in the main program. | |
88e1739c | 30639 | |
7cd4527e AC |
30640 | It is therefore not possible to exchange GNAT run-time objects between the |
30641 | Ada DLL and the main Ada program. Example of GNAT run-time objects are file | |
8dd07840 | 30642 | handles (e.g.@: @code{Text_IO.File_Type}), tasks types, protected objects |
7cd4527e | 30643 | types, etc. |
88e1739c | 30644 | |
7cd4527e AC |
30645 | It is completely safe to exchange plain elementary, array or record types, |
30646 | Windows object handles, etc. | |
88e1739c | 30647 | |
7cd4527e AC |
30648 | @node Exporting Ada Entities |
30649 | @subsection Exporting Ada Entities | |
30650 | @cindex Export table | |
88e1739c | 30651 | |
88e1739c | 30652 | @noindent |
7cd4527e AC |
30653 | Building a DLL is a way to encapsulate a set of services usable from any |
30654 | application. As a result, the Ada entities exported by a DLL should be | |
30655 | exported with the @code{C} or @code{Stdcall} calling conventions to avoid | |
32e209e4 CC |
30656 | any Ada name mangling. As an example here is an Ada package |
30657 | @code{API}, spec and body, exporting two procedures, a function, and a | |
30658 | variable: | |
88e1739c | 30659 | |
7cd4527e AC |
30660 | @smallexample @c ada |
30661 | @group | |
30662 | @cartouche | |
30663 | with Interfaces.C; use Interfaces; | |
30664 | package API is | |
30665 | Count : C.int := 0; | |
30666 | function Factorial (Val : C.int) return C.int; | |
88e1739c | 30667 | |
7cd4527e AC |
30668 | procedure Initialize_API; |
30669 | procedure Finalize_API; | |
30670 | -- Initialization & Finalization routines. More in the next section. | |
30671 | private | |
30672 | pragma Export (C, Initialize_API); | |
30673 | pragma Export (C, Finalize_API); | |
30674 | pragma Export (C, Count); | |
30675 | pragma Export (C, Factorial); | |
30676 | end API; | |
30677 | @end cartouche | |
30678 | @end group | |
88e1739c FW |
30679 | @end smallexample |
30680 | ||
7cd4527e AC |
30681 | @smallexample @c ada |
30682 | @group | |
30683 | @cartouche | |
30684 | package body API is | |
30685 | function Factorial (Val : C.int) return C.int is | |
30686 | Fact : C.int := 1; | |
30687 | begin | |
30688 | Count := Count + 1; | |
30689 | for K in 1 .. Val loop | |
30690 | Fact := Fact * K; | |
30691 | end loop; | |
30692 | return Fact; | |
30693 | end Factorial; | |
88e1739c | 30694 | |
7cd4527e AC |
30695 | procedure Initialize_API is |
30696 | procedure Adainit; | |
30697 | pragma Import (C, Adainit); | |
30698 | begin | |
30699 | Adainit; | |
30700 | end Initialize_API; | |
88e1739c | 30701 | |
7cd4527e AC |
30702 | procedure Finalize_API is |
30703 | procedure Adafinal; | |
30704 | pragma Import (C, Adafinal); | |
30705 | begin | |
30706 | Adafinal; | |
30707 | end Finalize_API; | |
30708 | end API; | |
30709 | @end cartouche | |
30710 | @end group | |
88e1739c FW |
30711 | @end smallexample |
30712 | ||
7cd4527e AC |
30713 | @noindent |
30714 | If the Ada DLL you are building will only be used by Ada applications | |
30715 | you do not have to export Ada entities with a @code{C} or @code{Stdcall} | |
30716 | convention. As an example, the previous package could be written as | |
30717 | follows: | |
30718 | ||
30719 | @smallexample @c ada | |
30720 | @group | |
30721 | @cartouche | |
30722 | package API is | |
30723 | Count : Integer := 0; | |
30724 | function Factorial (Val : Integer) return Integer; | |
30725 | ||
30726 | procedure Initialize_API; | |
30727 | procedure Finalize_API; | |
30728 | -- Initialization and Finalization routines. | |
30729 | end API; | |
30730 | @end cartouche | |
30731 | @end group | |
88e1739c | 30732 | @end smallexample |
88e1739c | 30733 | |
7cd4527e AC |
30734 | @smallexample @c ada |
30735 | @group | |
30736 | @cartouche | |
30737 | package body API is | |
30738 | function Factorial (Val : Integer) return Integer is | |
30739 | Fact : Integer := 1; | |
30740 | begin | |
30741 | Count := Count + 1; | |
30742 | for K in 1 .. Val loop | |
30743 | Fact := Fact * K; | |
30744 | end loop; | |
30745 | return Fact; | |
30746 | end Factorial; | |
88e1739c | 30747 | |
d488f6ea | 30748 | @dots{} |
7cd4527e AC |
30749 | -- The remainder of this package body is unchanged. |
30750 | end API; | |
30751 | @end cartouche | |
30752 | @end group | |
88e1739c FW |
30753 | @end smallexample |
30754 | ||
30755 | @noindent | |
7cd4527e AC |
30756 | Note that if you do not export the Ada entities with a @code{C} or |
30757 | @code{Stdcall} convention you will have to provide the mangled Ada names | |
30758 | in the definition file of the Ada DLL | |
30759 | (@pxref{Creating the Definition File}). | |
88e1739c | 30760 | |
7cd4527e AC |
30761 | @node Ada DLLs and Elaboration |
30762 | @subsection Ada DLLs and Elaboration | |
30763 | @cindex DLLs and elaboration | |
88e1739c FW |
30764 | |
30765 | @noindent | |
7cd4527e AC |
30766 | The DLL that you are building contains your Ada code as well as all the |
30767 | routines in the Ada library that are needed by it. The first thing a | |
30768 | user of your DLL must do is elaborate the Ada code | |
30769 | (@pxref{Elaboration Order Handling in GNAT}). | |
30770 | ||
30771 | To achieve this you must export an initialization routine | |
30772 | (@code{Initialize_API} in the previous example), which must be invoked | |
30773 | before using any of the DLL services. This elaboration routine must call | |
30774 | the Ada elaboration routine @code{adainit} generated by the GNAT binder | |
30775 | (@pxref{Binding with Non-Ada Main Programs}). See the body of | |
30776 | @code{Initialize_Api} for an example. Note that the GNAT binder is | |
30777 | automatically invoked during the DLL build process by the @code{gnatdll} | |
30778 | tool (@pxref{Using gnatdll}). | |
30779 | ||
30780 | When a DLL is loaded, Windows systematically invokes a routine called | |
30781 | @code{DllMain}. It would therefore be possible to call @code{adainit} | |
30782 | directly from @code{DllMain} without having to provide an explicit | |
30783 | initialization routine. Unfortunately, it is not possible to call | |
30784 | @code{adainit} from the @code{DllMain} if your program has library level | |
30785 | tasks because access to the @code{DllMain} entry point is serialized by | |
30786 | the system (that is, only a single thread can execute ``through'' it at a | |
30787 | time), which means that the GNAT run time will deadlock waiting for the | |
30788 | newly created task to complete its initialization. | |
30789 | ||
30790 | @node Ada DLLs and Finalization | |
30791 | @subsection Ada DLLs and Finalization | |
30792 | @cindex DLLs and finalization | |
88e1739c FW |
30793 | |
30794 | @noindent | |
7cd4527e AC |
30795 | When the services of an Ada DLL are no longer needed, the client code should |
30796 | invoke the DLL finalization routine, if available. The DLL finalization | |
30797 | routine is in charge of releasing all resources acquired by the DLL. In the | |
30798 | case of the Ada code contained in the DLL, this is achieved by calling | |
30799 | routine @code{adafinal} generated by the GNAT binder | |
30800 | (@pxref{Binding with Non-Ada Main Programs}). | |
30801 | See the body of @code{Finalize_Api} for an | |
30802 | example. As already pointed out the GNAT binder is automatically invoked | |
30803 | during the DLL build process by the @code{gnatdll} tool | |
30804 | (@pxref{Using gnatdll}). | |
30805 | ||
30806 | @node Creating a Spec for Ada DLLs | |
30807 | @subsection Creating a Spec for Ada DLLs | |
88e1739c FW |
30808 | |
30809 | @noindent | |
7cd4527e | 30810 | To use the services exported by the Ada DLL from another programming |
8dd07840 | 30811 | language (e.g.@: C), you have to translate the specs of the exported Ada |
7cd4527e AC |
30812 | entities in that language. For instance in the case of @code{API.dll}, |
30813 | the corresponding C header file could look like: | |
88e1739c | 30814 | |
88e1739c | 30815 | @smallexample |
7cd4527e AC |
30816 | @group |
30817 | @cartouche | |
30818 | extern int *_imp__count; | |
30819 | #define count (*_imp__count) | |
30820 | int factorial (int); | |
30821 | @end cartouche | |
30822 | @end group | |
88e1739c | 30823 | @end smallexample |
88e1739c FW |
30824 | |
30825 | @noindent | |
7cd4527e AC |
30826 | It is important to understand that when building an Ada DLL to be used by |
30827 | other Ada applications, you need two different specs for the packages | |
30828 | contained in the DLL: one for building the DLL and the other for using | |
30829 | the DLL. This is because the @code{DLL} calling convention is needed to | |
30830 | use a variable defined in a DLL, but when building the DLL, the variable | |
30831 | must have either the @code{Ada} or @code{C} calling convention. As an | |
30832 | example consider a DLL comprising the following package @code{API}: | |
88e1739c | 30833 | |
7cd4527e AC |
30834 | @smallexample @c ada |
30835 | @group | |
30836 | @cartouche | |
30837 | package API is | |
30838 | Count : Integer := 0; | |
d488f6ea | 30839 | @dots{} |
7cd4527e AC |
30840 | -- Remainder of the package omitted. |
30841 | end API; | |
30842 | @end cartouche | |
30843 | @end group | |
30844 | @end smallexample | |
88e1739c FW |
30845 | |
30846 | @noindent | |
7cd4527e AC |
30847 | After producing a DLL containing package @code{API}, the spec that |
30848 | must be used to import @code{API.Count} from Ada code outside of the | |
30849 | DLL is: | |
88e1739c | 30850 | |
7cd4527e AC |
30851 | @smallexample @c ada |
30852 | @group | |
30853 | @cartouche | |
30854 | package API is | |
30855 | Count : Integer; | |
30856 | pragma Import (DLL, Count); | |
30857 | end API; | |
30858 | @end cartouche | |
30859 | @end group | |
88e1739c | 30860 | @end smallexample |
88e1739c | 30861 | |
7cd4527e AC |
30862 | @node Creating the Definition File |
30863 | @subsection Creating the Definition File | |
88e1739c FW |
30864 | |
30865 | @noindent | |
7cd4527e AC |
30866 | The definition file is the last file needed to build the DLL. It lists |
30867 | the exported symbols. As an example, the definition file for a DLL | |
30868 | containing only package @code{API} (where all the entities are exported | |
30869 | with a @code{C} calling convention) is: | |
88e1739c | 30870 | |
88e1739c | 30871 | @smallexample |
7cd4527e AC |
30872 | @group |
30873 | @cartouche | |
30874 | EXPORTS | |
30875 | count | |
30876 | factorial | |
30877 | finalize_api | |
30878 | initialize_api | |
30879 | @end cartouche | |
30880 | @end group | |
88e1739c FW |
30881 | @end smallexample |
30882 | ||
88e1739c | 30883 | @noindent |
7cd4527e AC |
30884 | If the @code{C} calling convention is missing from package @code{API}, |
30885 | then the definition file contains the mangled Ada names of the above | |
30886 | entities, which in this case are: | |
88e1739c | 30887 | |
88e1739c | 30888 | @smallexample |
7cd4527e AC |
30889 | @group |
30890 | @cartouche | |
30891 | EXPORTS | |
30892 | api__count | |
30893 | api__factorial | |
30894 | api__finalize_api | |
30895 | api__initialize_api | |
30896 | @end cartouche | |
30897 | @end group | |
88e1739c FW |
30898 | @end smallexample |
30899 | ||
7cd4527e AC |
30900 | @node Using gnatdll |
30901 | @subsection Using @code{gnatdll} | |
30902 | @findex gnatdll | |
88e1739c FW |
30903 | |
30904 | @menu | |
7cd4527e AC |
30905 | * gnatdll Example:: |
30906 | * gnatdll behind the Scenes:: | |
30907 | * Using dlltool:: | |
88e1739c FW |
30908 | @end menu |
30909 | ||
30910 | @noindent | |
7cd4527e AC |
30911 | @code{gnatdll} is a tool to automate the DLL build process once all the Ada |
30912 | and non-Ada sources that make up your DLL have been compiled. | |
30913 | @code{gnatdll} is actually in charge of two distinct tasks: build the | |
30914 | static import library for the DLL and the actual DLL. The form of the | |
30915 | @code{gnatdll} command is | |
88e1739c | 30916 | |
7cd4527e AC |
30917 | @smallexample |
30918 | @cartouche | |
e074d476 AC |
30919 | @c $ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]} |
30920 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
30921 | $ gnatdll @r{[}@var{switches}@r{]} @var{list-of-files} @r{[}-largs @var{opts}@r{]} | |
7cd4527e AC |
30922 | @end cartouche |
30923 | @end smallexample | |
88e1739c FW |
30924 | |
30925 | @noindent | |
66bfd481 | 30926 | where @var{list-of-files} is a list of ALI and object files. The object |
7cd4527e AC |
30927 | file list must be the exact list of objects corresponding to the non-Ada |
30928 | sources whose services are to be included in the DLL. The ALI file list | |
30929 | must be the exact list of ALI files for the corresponding Ada sources | |
66bfd481 | 30930 | whose services are to be included in the DLL. If @var{list-of-files} is |
7cd4527e | 30931 | missing, only the static import library is generated. |
88e1739c | 30932 | |
7cd4527e AC |
30933 | @noindent |
30934 | You may specify any of the following switches to @code{gnatdll}: | |
88e1739c | 30935 | |
7cd4527e | 30936 | @table @code |
e074d476 AC |
30937 | @c @item -a@ovar{address} |
30938 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
30939 | @item -a@r{[}@var{address}@r{]} | |
7cd4527e AC |
30940 | @cindex @option{-a} (@code{gnatdll}) |
30941 | Build a non-relocatable DLL at @var{address}. If @var{address} is not | |
30942 | specified the default address @var{0x11000000} will be used. By default, | |
30943 | when this switch is missing, @code{gnatdll} builds relocatable DLL. We | |
30944 | advise the reader to build relocatable DLL. | |
88e1739c | 30945 | |
7cd4527e AC |
30946 | @item -b @var{address} |
30947 | @cindex @option{-b} (@code{gnatdll}) | |
30948 | Set the relocatable DLL base address. By default the address is | |
1992bbd9 | 30949 | @code{0x11000000}. |
88e1739c | 30950 | |
7cd4527e AC |
30951 | @item -bargs @var{opts} |
30952 | @cindex @option{-bargs} (@code{gnatdll}) | |
30953 | Binder options. Pass @var{opts} to the binder. | |
88e1739c | 30954 | |
7cd4527e AC |
30955 | @item -d @var{dllfile} |
30956 | @cindex @option{-d} (@code{gnatdll}) | |
30957 | @var{dllfile} is the name of the DLL. This switch must be present for | |
30958 | @code{gnatdll} to do anything. The name of the generated import library is | |
30959 | obtained algorithmically from @var{dllfile} as shown in the following | |
30960 | example: if @var{dllfile} is @code{xyz.dll}, the import library name is | |
c690a2ec | 30961 | @code{libxyz.dll.a}. The name of the definition file to use (if not specified |
7cd4527e AC |
30962 | by option @option{-e}) is obtained algorithmically from @var{dllfile} |
30963 | as shown in the following example: | |
30964 | if @var{dllfile} is @code{xyz.dll}, the definition | |
30965 | file used is @code{xyz.def}. | |
88e1739c | 30966 | |
7cd4527e AC |
30967 | @item -e @var{deffile} |
30968 | @cindex @option{-e} (@code{gnatdll}) | |
30969 | @var{deffile} is the name of the definition file. | |
88e1739c | 30970 | |
7cd4527e AC |
30971 | @item -g |
30972 | @cindex @option{-g} (@code{gnatdll}) | |
30973 | Generate debugging information. This information is stored in the object | |
30974 | file and copied from there to the final DLL file by the linker, | |
30975 | where it can be read by the debugger. You must use the | |
30976 | @option{-g} switch if you plan on using the debugger or the symbolic | |
30977 | stack traceback. | |
88e1739c | 30978 | |
7cd4527e AC |
30979 | @item -h |
30980 | @cindex @option{-h} (@code{gnatdll}) | |
30981 | Help mode. Displays @code{gnatdll} switch usage information. | |
88e1739c | 30982 | |
7cd4527e AC |
30983 | @item -Idir |
30984 | @cindex @option{-I} (@code{gnatdll}) | |
30985 | Direct @code{gnatdll} to search the @var{dir} directory for source and | |
30986 | object files needed to build the DLL. | |
30987 | (@pxref{Search Paths and the Run-Time Library (RTL)}). | |
88e1739c | 30988 | |
7cd4527e AC |
30989 | @item -k |
30990 | @cindex @option{-k} (@code{gnatdll}) | |
66bfd481 | 30991 | Removes the @code{@@}@var{nn} suffix from the import library's exported |
0ab80019 AC |
30992 | names, but keeps them for the link names. You must specify this |
30993 | option if you want to use a @code{Stdcall} function in a DLL for which | |
66bfd481 | 30994 | the @code{@@}@var{nn} suffix has been removed. This is the case for most |
0ab80019 AC |
30995 | of the Windows NT DLL for example. This option has no effect when |
30996 | @option{-n} option is specified. | |
88e1739c | 30997 | |
7cd4527e AC |
30998 | @item -l @var{file} |
30999 | @cindex @option{-l} (@code{gnatdll}) | |
31000 | The list of ALI and object files used to build the DLL are listed in | |
31001 | @var{file}, instead of being given in the command line. Each line in | |
31002 | @var{file} contains the name of an ALI or object file. | |
88e1739c | 31003 | |
7cd4527e AC |
31004 | @item -n |
31005 | @cindex @option{-n} (@code{gnatdll}) | |
31006 | No Import. Do not create the import library. | |
88e1739c | 31007 | |
7cd4527e AC |
31008 | @item -q |
31009 | @cindex @option{-q} (@code{gnatdll}) | |
31010 | Quiet mode. Do not display unnecessary messages. | |
88e1739c | 31011 | |
7cd4527e AC |
31012 | @item -v |
31013 | @cindex @option{-v} (@code{gnatdll}) | |
31014 | Verbose mode. Display extra information. | |
88e1739c | 31015 | |
7cd4527e AC |
31016 | @item -largs @var{opts} |
31017 | @cindex @option{-largs} (@code{gnatdll}) | |
31018 | Linker options. Pass @var{opts} to the linker. | |
31019 | @end table | |
88e1739c | 31020 | |
7cd4527e AC |
31021 | @node gnatdll Example |
31022 | @subsubsection @code{gnatdll} Example | |
88e1739c FW |
31023 | |
31024 | @noindent | |
7cd4527e AC |
31025 | As an example the command to build a relocatable DLL from @file{api.adb} |
31026 | once @file{api.adb} has been compiled and @file{api.def} created is | |
88e1739c | 31027 | |
88e1739c | 31028 | @smallexample |
7cd4527e | 31029 | $ gnatdll -d api.dll api.ali |
88e1739c FW |
31030 | @end smallexample |
31031 | ||
31032 | @noindent | |
c690a2ec | 31033 | The above command creates two files: @file{libapi.dll.a} (the import |
7cd4527e AC |
31034 | library) and @file{api.dll} (the actual DLL). If you want to create |
31035 | only the DLL, just type: | |
88e1739c | 31036 | |
88e1739c | 31037 | @smallexample |
7cd4527e | 31038 | $ gnatdll -d api.dll -n api.ali |
88e1739c FW |
31039 | @end smallexample |
31040 | ||
31041 | @noindent | |
7cd4527e | 31042 | Alternatively if you want to create just the import library, type: |
88e1739c | 31043 | |
88e1739c | 31044 | @smallexample |
7cd4527e | 31045 | $ gnatdll -d api.dll |
88e1739c FW |
31046 | @end smallexample |
31047 | ||
7cd4527e AC |
31048 | @node gnatdll behind the Scenes |
31049 | @subsubsection @code{gnatdll} behind the Scenes | |
88e1739c | 31050 | |
7cd4527e AC |
31051 | @noindent |
31052 | This section details the steps involved in creating a DLL. @code{gnatdll} | |
31053 | does these steps for you. Unless you are interested in understanding what | |
31054 | goes on behind the scenes, you should skip this section. | |
88e1739c | 31055 | |
7cd4527e AC |
31056 | We use the previous example of a DLL containing the Ada package @code{API}, |
31057 | to illustrate the steps necessary to build a DLL. The starting point is a | |
31058 | set of objects that will make up the DLL and the corresponding ALI | |
31059 | files. In the case of this example this means that @file{api.o} and | |
31060 | @file{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does | |
31061 | the following: | |
88e1739c | 31062 | |
7cd4527e | 31063 | @enumerate |
88e1739c | 31064 | @item |
7cd4527e AC |
31065 | @code{gnatdll} builds the base file (@file{api.base}). A base file gives |
31066 | the information necessary to generate relocation information for the | |
31067 | DLL. | |
88e1739c | 31068 | |
7cd4527e AC |
31069 | @smallexample |
31070 | @group | |
31071 | $ gnatbind -n api | |
31072 | $ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base | |
31073 | @end group | |
31074 | @end smallexample | |
88e1739c FW |
31075 | |
31076 | @noindent | |
984a64bc | 31077 | In addition to the base file, the @command{gnatlink} command generates an |
7cd4527e | 31078 | output file @file{api.jnk} which can be discarded. The @option{-mdll} switch |
984a64bc | 31079 | asks @command{gnatlink} to generate the routines @code{DllMain} and |
7cd4527e AC |
31080 | @code{DllMainCRTStartup} that are called by the Windows loader when the DLL |
31081 | is loaded into memory. | |
88e1739c FW |
31082 | |
31083 | @item | |
7cd4527e AC |
31084 | @code{gnatdll} uses @code{dlltool} (@pxref{Using dlltool}) to build the |
31085 | export table (@file{api.exp}). The export table contains the relocation | |
31086 | information in a form which can be used during the final link to ensure | |
31087 | that the Windows loader is able to place the DLL anywhere in memory. | |
88e1739c | 31088 | |
88e1739c | 31089 | @smallexample |
7cd4527e AC |
31090 | @group |
31091 | $ dlltool --dllname api.dll --def api.def --base-file api.base \ | |
31092 | --output-exp api.exp | |
31093 | @end group | |
88e1739c FW |
31094 | @end smallexample |
31095 | ||
31096 | @item | |
7cd4527e | 31097 | @code{gnatdll} builds the base file using the new export table. Note that |
984a64bc AC |
31098 | @command{gnatbind} must be called once again since the binder generated file |
31099 | has been deleted during the previous call to @command{gnatlink}. | |
88e1739c | 31100 | |
7cd4527e AC |
31101 | @smallexample |
31102 | @group | |
31103 | $ gnatbind -n api | |
31104 | $ gnatlink api -o api.jnk api.exp -mdll | |
31105 | -Wl,--base-file,api.base | |
31106 | @end group | |
31107 | @end smallexample | |
88e1739c FW |
31108 | |
31109 | @item | |
7cd4527e | 31110 | @code{gnatdll} builds the new export table using the new base file and |
c690a2ec | 31111 | generates the DLL import library @file{libAPI.dll.a}. |
88e1739c | 31112 | |
88e1739c | 31113 | @smallexample |
7cd4527e AC |
31114 | @group |
31115 | $ dlltool --dllname api.dll --def api.def --base-file api.base \ | |
31116 | --output-exp api.exp --output-lib libAPI.a | |
31117 | @end group | |
88e1739c | 31118 | @end smallexample |
88e1739c | 31119 | |
7cd4527e AC |
31120 | @item |
31121 | Finally @code{gnatdll} builds the relocatable DLL using the final export | |
31122 | table. | |
88e1739c FW |
31123 | |
31124 | @smallexample | |
7cd4527e AC |
31125 | @group |
31126 | $ gnatbind -n api | |
31127 | $ gnatlink api api.exp -o api.dll -mdll | |
31128 | @end group | |
88e1739c | 31129 | @end smallexample |
7cd4527e | 31130 | @end enumerate |
88e1739c | 31131 | |
7cd4527e AC |
31132 | @node Using dlltool |
31133 | @subsubsection Using @code{dlltool} | |
88e1739c FW |
31134 | |
31135 | @noindent | |
7cd4527e AC |
31136 | @code{dlltool} is the low-level tool used by @code{gnatdll} to build |
31137 | DLLs and static import libraries. This section summarizes the most | |
31138 | common @code{dlltool} switches. The form of the @code{dlltool} command | |
31139 | is | |
88e1739c | 31140 | |
7cd4527e | 31141 | @smallexample |
e074d476 AC |
31142 | @c $ dlltool @ovar{switches} |
31143 | @c Expanding @ovar macro inline (explanation in macro def comments) | |
31144 | $ dlltool @r{[}@var{switches}@r{]} | |
7cd4527e | 31145 | @end smallexample |
88e1739c FW |
31146 | |
31147 | @noindent | |
7cd4527e | 31148 | @code{dlltool} switches include: |
88e1739c | 31149 | |
7cd4527e AC |
31150 | @table @option |
31151 | @item --base-file @var{basefile} | |
31152 | @cindex @option{--base-file} (@command{dlltool}) | |
31153 | Read the base file @var{basefile} generated by the linker. This switch | |
31154 | is used to create a relocatable DLL. | |
88e1739c | 31155 | |
7cd4527e AC |
31156 | @item --def @var{deffile} |
31157 | @cindex @option{--def} (@command{dlltool}) | |
31158 | Read the definition file. | |
88e1739c | 31159 | |
7cd4527e AC |
31160 | @item --dllname @var{name} |
31161 | @cindex @option{--dllname} (@command{dlltool}) | |
31162 | Gives the name of the DLL. This switch is used to embed the name of the | |
31163 | DLL in the static import library generated by @code{dlltool} with switch | |
31164 | @option{--output-lib}. | |
88e1739c | 31165 | |
7cd4527e AC |
31166 | @item -k |
31167 | @cindex @option{-k} (@command{dlltool}) | |
66bfd481 | 31168 | Kill @code{@@}@var{nn} from exported names |
7cd4527e AC |
31169 | (@pxref{Windows Calling Conventions} |
31170 | for a discussion about @code{Stdcall}-style symbols. | |
88e1739c | 31171 | |
7cd4527e AC |
31172 | @item --help |
31173 | @cindex @option{--help} (@command{dlltool}) | |
31174 | Prints the @code{dlltool} switches with a concise description. | |
88e1739c | 31175 | |
7cd4527e AC |
31176 | @item --output-exp @var{exportfile} |
31177 | @cindex @option{--output-exp} (@command{dlltool}) | |
31178 | Generate an export file @var{exportfile}. The export file contains the | |
31179 | export table (list of symbols in the DLL) and is used to create the DLL. | |
88e1739c | 31180 | |
66bfd481 | 31181 | @item --output-lib @var{libfile} |
7cd4527e AC |
31182 | @cindex @option{--output-lib} (@command{dlltool}) |
31183 | Generate a static import library @var{libfile}. | |
88e1739c | 31184 | |
7cd4527e AC |
31185 | @item -v |
31186 | @cindex @option{-v} (@command{dlltool}) | |
31187 | Verbose mode. | |
88e1739c | 31188 | |
66bfd481 | 31189 | @item --as @var{assembler-name} |
7cd4527e | 31190 | @cindex @option{--as} (@command{dlltool}) |
66bfd481 | 31191 | Use @var{assembler-name} as the assembler. The default is @code{as}. |
7cd4527e | 31192 | @end table |
88e1739c | 31193 | |
7cd4527e AC |
31194 | @node GNAT and Windows Resources |
31195 | @section GNAT and Windows Resources | |
31196 | @cindex Resources, windows | |
88e1739c | 31197 | |
7cd4527e AC |
31198 | @menu |
31199 | * Building Resources:: | |
31200 | * Compiling Resources:: | |
31201 | * Using Resources:: | |
31202 | @end menu | |
88e1739c FW |
31203 | |
31204 | @noindent | |
7cd4527e AC |
31205 | Resources are an easy way to add Windows specific objects to your |
31206 | application. The objects that can be added as resources include: | |
88e1739c | 31207 | |
7cd4527e | 31208 | @itemize @bullet |
af9e051f | 31209 | @item menus |
88e1739c | 31210 | |
af9e051f | 31211 | @item accelerators |
88e1739c | 31212 | |
af9e051f | 31213 | @item dialog boxes |
88e1739c | 31214 | |
af9e051f | 31215 | @item string tables |
88e1739c | 31216 | |
af9e051f | 31217 | @item bitmaps |
88e1739c | 31218 | |
af9e051f | 31219 | @item cursors |
88e1739c | 31220 | |
af9e051f | 31221 | @item icons |
88e1739c | 31222 | |
af9e051f PO |
31223 | @item fonts |
31224 | ||
31225 | @item version information | |
7cd4527e | 31226 | @end itemize |
88e1739c | 31227 | |
af9e051f PO |
31228 | For example, a version information resource can be defined as follow and |
31229 | embedded into an executable or DLL: | |
31230 | ||
31231 | A version information resource can be used to embed information into an | |
31232 | executable or a DLL. These information can be viewed using the file properties | |
31233 | from the Windows Explorer. Here is an example of a version information | |
31234 | resource: | |
31235 | ||
31236 | @smallexample | |
31237 | @group | |
31238 | 1 VERSIONINFO | |
31239 | FILEVERSION 1,0,0,0 | |
31240 | PRODUCTVERSION 1,0,0,0 | |
31241 | BEGIN | |
31242 | BLOCK "StringFileInfo" | |
31243 | BEGIN | |
31244 | BLOCK "080904E4" | |
31245 | BEGIN | |
31246 | VALUE "CompanyName", "My Company Name" | |
31247 | VALUE "FileDescription", "My application" | |
31248 | VALUE "FileVersion", "1.0" | |
31249 | VALUE "InternalName", "my_app" | |
31250 | VALUE "LegalCopyright", "My Name" | |
31251 | VALUE "OriginalFilename", "my_app.exe" | |
31252 | VALUE "ProductName", "My App" | |
31253 | VALUE "ProductVersion", "1.0" | |
31254 | END | |
31255 | END | |
31256 | ||
31257 | BLOCK "VarFileInfo" | |
31258 | BEGIN | |
31259 | VALUE "Translation", 0x809, 1252 | |
31260 | END | |
31261 | END | |
31262 | @end group | |
31263 | @end smallexample | |
31264 | ||
31265 | The value @code{0809} (langID) is for the U.K English language and | |
31266 | @code{04E4} (charsetID), which is equal to @code{1252} decimal, for | |
31267 | multilingual. | |
31268 | ||
88e1739c | 31269 | @noindent |
af9e051f PO |
31270 | This section explains how to build, compile and use resources. Note that this |
31271 | section does not cover all resource objects, for a complete description see | |
31272 | the corresponding Microsoft documentation. | |
88e1739c | 31273 | |
7cd4527e AC |
31274 | @node Building Resources |
31275 | @subsection Building Resources | |
31276 | @cindex Resources, building | |
88e1739c FW |
31277 | |
31278 | @noindent | |
7cd4527e AC |
31279 | A resource file is an ASCII file. By convention resource files have an |
31280 | @file{.rc} extension. | |
31281 | The easiest way to build a resource file is to use Microsoft tools | |
31282 | such as @code{imagedit.exe} to build bitmaps, icons and cursors and | |
31283 | @code{dlgedit.exe} to build dialogs. | |
31284 | It is always possible to build an @file{.rc} file yourself by writing a | |
31285 | resource script. | |
88e1739c | 31286 | |
7cd4527e AC |
31287 | It is not our objective to explain how to write a resource file. A |
31288 | complete description of the resource script language can be found in the | |
31289 | Microsoft documentation. | |
88e1739c | 31290 | |
7cd4527e AC |
31291 | @node Compiling Resources |
31292 | @subsection Compiling Resources | |
31293 | @findex rc | |
31294 | @findex windres | |
31295 | @cindex Resources, compiling | |
88e1739c FW |
31296 | |
31297 | @noindent | |
7cd4527e AC |
31298 | This section describes how to build a GNAT-compatible (COFF) object file |
31299 | containing the resources. This is done using the Resource Compiler | |
31300 | @code{windres} as follows: | |
88e1739c FW |
31301 | |
31302 | @smallexample | |
7cd4527e | 31303 | $ windres -i myres.rc -o myres.o |
88e1739c FW |
31304 | @end smallexample |
31305 | ||
31306 | @noindent | |
984a64bc | 31307 | By default @code{windres} will run @command{gcc} to preprocess the @file{.rc} |
7cd4527e AC |
31308 | file. You can specify an alternate preprocessor (usually named |
31309 | @file{cpp.exe}) using the @code{windres} @option{--preprocessor} | |
31310 | parameter. A list of all possible options may be obtained by entering | |
31311 | the command @code{windres} @option{--help}. | |
31312 | ||
31313 | It is also possible to use the Microsoft resource compiler @code{rc.exe} | |
31314 | to produce a @file{.res} file (binary resource file). See the | |
31315 | corresponding Microsoft documentation for further details. In this case | |
31316 | you need to use @code{windres} to translate the @file{.res} file to a | |
31317 | GNAT-compatible object file as follows: | |
88e1739c FW |
31318 | |
31319 | @smallexample | |
7cd4527e | 31320 | $ windres -i myres.res -o myres.o |
88e1739c FW |
31321 | @end smallexample |
31322 | ||
7cd4527e AC |
31323 | @node Using Resources |
31324 | @subsection Using Resources | |
31325 | @cindex Resources, using | |
31326 | ||
88e1739c | 31327 | @noindent |
7cd4527e AC |
31328 | To include the resource file in your program just add the |
31329 | GNAT-compatible object file for the resource(s) to the linker | |
984a64bc | 31330 | arguments. With @command{gnatmake} this is done by using the @option{-largs} |
7cd4527e | 31331 | option: |
88e1739c FW |
31332 | |
31333 | @smallexample | |
7cd4527e | 31334 | $ gnatmake myprog -largs myres.o |
88e1739c | 31335 | @end smallexample |
88e1739c | 31336 | |
7cd4527e AC |
31337 | @node Debugging a DLL |
31338 | @section Debugging a DLL | |
31339 | @cindex DLL debugging | |
88e1739c | 31340 | |
7cd4527e AC |
31341 | @menu |
31342 | * Program and DLL Both Built with GCC/GNAT:: | |
31343 | * Program Built with Foreign Tools and DLL Built with GCC/GNAT:: | |
31344 | @end menu | |
88e1739c FW |
31345 | |
31346 | @noindent | |
7cd4527e AC |
31347 | Debugging a DLL is similar to debugging a standard program. But |
31348 | we have to deal with two different executable parts: the DLL and the | |
31349 | program that uses it. We have the following four possibilities: | |
88e1739c | 31350 | |
7cd4527e | 31351 | @enumerate 1 |
88e1739c | 31352 | @item |
7cd4527e | 31353 | The program and the DLL are built with @code{GCC/GNAT}. |
88e1739c | 31354 | @item |
7cd4527e AC |
31355 | The program is built with foreign tools and the DLL is built with |
31356 | @code{GCC/GNAT}. | |
88e1739c | 31357 | @item |
7cd4527e AC |
31358 | The program is built with @code{GCC/GNAT} and the DLL is built with |
31359 | foreign tools. | |
7cd4527e | 31360 | @end enumerate |
88e1739c FW |
31361 | |
31362 | @noindent | |
7cd4527e AC |
31363 | In this section we address only cases one and two above. |
31364 | There is no point in trying to debug | |
31365 | a DLL with @code{GNU/GDB}, if there is no GDB-compatible debugging | |
31366 | information in it. To do so you must use a debugger compatible with the | |
31367 | tools suite used to build the DLL. | |
88e1739c | 31368 | |
7cd4527e AC |
31369 | @node Program and DLL Both Built with GCC/GNAT |
31370 | @subsection Program and DLL Both Built with GCC/GNAT | |
88e1739c FW |
31371 | |
31372 | @noindent | |
7cd4527e AC |
31373 | This is the simplest case. Both the DLL and the program have @code{GDB} |
31374 | compatible debugging information. It is then possible to break anywhere in | |
31375 | the process. Let's suppose here that the main procedure is named | |
31376 | @code{ada_main} and that in the DLL there is an entry point named | |
31377 | @code{ada_dll}. | |
88e1739c FW |
31378 | |
31379 | @noindent | |
7cd4527e AC |
31380 | The DLL (@pxref{Introduction to Dynamic Link Libraries (DLLs)}) and |
31381 | program must have been built with the debugging information (see GNAT -g | |
31382 | switch). Here are the step-by-step instructions for debugging it: | |
88e1739c | 31383 | |
7cd4527e AC |
31384 | @enumerate 1 |
31385 | @item Launch @code{GDB} on the main program. | |
88e1739c | 31386 | |
7cd4527e AC |
31387 | @smallexample |
31388 | $ gdb -nw ada_main | |
31389 | @end smallexample | |
88e1739c | 31390 | |
32e209e4 | 31391 | @item Start the program and stop at the beginning of the main procedure |
88e1739c | 31392 | |
7cd4527e | 31393 | @smallexample |
32e209e4 | 31394 | (gdb) start |
7cd4527e | 31395 | @end smallexample |
88e1739c FW |
31396 | |
31397 | @noindent | |
7cd4527e AC |
31398 | This step is required to be able to set a breakpoint inside the DLL. As long |
31399 | as the program is not run, the DLL is not loaded. This has the | |
31400 | consequence that the DLL debugging information is also not loaded, so it is not | |
31401 | possible to set a breakpoint in the DLL. | |
88e1739c | 31402 | |
7cd4527e | 31403 | @item Set a breakpoint inside the DLL |
88e1739c | 31404 | |
7cd4527e AC |
31405 | @smallexample |
31406 | (gdb) break ada_dll | |
32e209e4 | 31407 | (gdb) cont |
7cd4527e | 31408 | @end smallexample |
88e1739c | 31409 | |
7cd4527e | 31410 | @end enumerate |
88e1739c | 31411 | |
7cd4527e AC |
31412 | @noindent |
31413 | At this stage a breakpoint is set inside the DLL. From there on | |
31414 | you can use the standard approach to debug the whole program | |
31415 | (@pxref{Running and Debugging Ada Programs}). | |
88e1739c | 31416 | |
32e209e4 CC |
31417 | @ignore |
31418 | @c This used to work, probably because the DLLs were non-relocatable | |
31419 | @c keep this section around until the problem is sorted out. | |
31420 | ||
984a64bc AC |
31421 | To break on the @code{DllMain} routine it is not possible to follow |
31422 | the procedure above. At the time the program stop on @code{ada_main} | |
31423 | the @code{DllMain} routine as already been called. Either you can use | |
31424 | the procedure below @pxref{Debugging the DLL Directly} or this procedure: | |
31425 | ||
31426 | @enumerate 1 | |
31427 | @item Launch @code{GDB} on the main program. | |
31428 | ||
31429 | @smallexample | |
32e209e4 | 31430 | $ gdb ada_main |
984a64bc AC |
31431 | @end smallexample |
31432 | ||
31433 | @item Load DLL symbols | |
31434 | ||
31435 | @smallexample | |
31436 | (gdb) add-sym api.dll | |
31437 | @end smallexample | |
31438 | ||
31439 | @item Set a breakpoint inside the DLL | |
31440 | ||
31441 | @smallexample | |
31442 | (gdb) break ada_dll.adb:45 | |
31443 | @end smallexample | |
31444 | ||
31445 | Note that at this point it is not possible to break using the routine symbol | |
31446 | directly as the program is not yet running. The solution is to break | |
31447 | on the proper line (break in @file{ada_dll.adb} line 45). | |
31448 | ||
31449 | @item Start the program | |
31450 | ||
31451 | @smallexample | |
31452 | (gdb) run | |
31453 | @end smallexample | |
31454 | ||
31455 | @end enumerate | |
32e209e4 | 31456 | @end ignore |
984a64bc | 31457 | |
7cd4527e AC |
31458 | @node Program Built with Foreign Tools and DLL Built with GCC/GNAT |
31459 | @subsection Program Built with Foreign Tools and DLL Built with GCC/GNAT | |
88e1739c | 31460 | |
7cd4527e AC |
31461 | @menu |
31462 | * Debugging the DLL Directly:: | |
31463 | * Attaching to a Running Process:: | |
31464 | @end menu | |
88e1739c | 31465 | |
7cd4527e AC |
31466 | @noindent |
31467 | In this case things are slightly more complex because it is not possible to | |
31468 | start the main program and then break at the beginning to load the DLL and the | |
31469 | associated DLL debugging information. It is not possible to break at the | |
31470 | beginning of the program because there is no @code{GDB} debugging information, | |
31471 | and therefore there is no direct way of getting initial control. This | |
31472 | section addresses this issue by describing some methods that can be used | |
31473 | to break somewhere in the DLL to debug it. | |
88e1739c FW |
31474 | |
31475 | @noindent | |
7cd4527e AC |
31476 | First suppose that the main procedure is named @code{main} (this is for |
31477 | example some C code built with Microsoft Visual C) and that there is a | |
31478 | DLL named @code{test.dll} containing an Ada entry point named | |
31479 | @code{ada_dll}. | |
88e1739c | 31480 | |
7cd4527e AC |
31481 | @noindent |
31482 | The DLL (@pxref{Introduction to Dynamic Link Libraries (DLLs)}) must have | |
31483 | been built with debugging information (see GNAT -g option). | |
88e1739c | 31484 | |
7cd4527e AC |
31485 | @node Debugging the DLL Directly |
31486 | @subsubsection Debugging the DLL Directly | |
88e1739c | 31487 | |
7cd4527e | 31488 | @enumerate 1 |
88e1739c | 31489 | @item |
32e209e4 | 31490 | Find out the executable starting address |
88e1739c | 31491 | |
7cd4527e | 31492 | @smallexample |
32e209e4 | 31493 | $ objdump --file-header main.exe |
7cd4527e | 31494 | @end smallexample |
88e1739c | 31495 | |
32e209e4 | 31496 | The starting address is reported on the last line. For example: |
88e1739c | 31497 | |
7cd4527e | 31498 | @smallexample |
32e209e4 CC |
31499 | main.exe: file format pei-i386 |
31500 | architecture: i386, flags 0x0000010a: | |
31501 | EXEC_P, HAS_DEBUG, D_PAGED | |
31502 | start address 0x00401010 | |
7cd4527e | 31503 | @end smallexample |
88e1739c | 31504 | |
32e209e4 CC |
31505 | @item |
31506 | Launch the debugger on the executable. | |
31507 | ||
31508 | @smallexample | |
31509 | $ gdb main.exe | |
31510 | @end smallexample | |
984a64bc | 31511 | |
88e1739c | 31512 | @item |
32e209e4 | 31513 | Set a breakpoint at the starting address, and launch the program. |
88e1739c | 31514 | |
7cd4527e | 31515 | @smallexample |
32e209e4 CC |
31516 | $ (gdb) break *0x00401010 |
31517 | $ (gdb) run | |
7cd4527e | 31518 | @end smallexample |
88e1739c | 31519 | |
32e209e4 CC |
31520 | The program will stop at the given address. |
31521 | ||
88e1739c | 31522 | @item |
32e209e4 | 31523 | Set a breakpoint on a DLL subroutine. |
88e1739c | 31524 | |
7cd4527e | 31525 | @smallexample |
32e209e4 CC |
31526 | (gdb) break ada_dll.adb:45 |
31527 | @end smallexample | |
31528 | ||
31529 | Or if you want to break using a symbol on the DLL, you need first to | |
31530 | select the Ada language (language used by the DLL). | |
31531 | ||
31532 | @smallexample | |
31533 | (gdb) set language ada | |
31534 | (gdb) break ada_dll | |
31535 | @end smallexample | |
31536 | ||
31537 | @item | |
31538 | Continue the program. | |
31539 | ||
31540 | @smallexample | |
31541 | (gdb) cont | |
7cd4527e | 31542 | @end smallexample |
88e1739c FW |
31543 | |
31544 | @noindent | |
7cd4527e AC |
31545 | This will run the program until it reaches the breakpoint that has been |
31546 | set. From that point you can use the standard way to debug a program | |
31547 | as described in (@pxref{Running and Debugging Ada Programs}). | |
88e1739c | 31548 | |
7cd4527e | 31549 | @end enumerate |
88e1739c FW |
31550 | |
31551 | @noindent | |
7cd4527e | 31552 | It is also possible to debug the DLL by attaching to a running process. |
88e1739c | 31553 | |
7cd4527e AC |
31554 | @node Attaching to a Running Process |
31555 | @subsubsection Attaching to a Running Process | |
31556 | @cindex DLL debugging, attach to process | |
88e1739c | 31557 | |
7cd4527e AC |
31558 | @noindent |
31559 | With @code{GDB} it is always possible to debug a running process by | |
31560 | attaching to it. It is possible to debug a DLL this way. The limitation | |
31561 | of this approach is that the DLL must run long enough to perform the | |
31562 | attach operation. It may be useful for instance to insert a time wasting | |
31563 | loop in the code of the DLL to meet this criterion. | |
88e1739c | 31564 | |
7cd4527e | 31565 | @enumerate 1 |
88e1739c | 31566 | |
7cd4527e | 31567 | @item Launch the main program @file{main.exe}. |
88e1739c | 31568 | |
7cd4527e AC |
31569 | @smallexample |
31570 | $ main | |
31571 | @end smallexample | |
88e1739c | 31572 | |
7cd4527e AC |
31573 | @item Use the Windows @i{Task Manager} to find the process ID. Let's say |
31574 | that the process PID for @file{main.exe} is 208. | |
88e1739c | 31575 | |
7cd4527e | 31576 | @item Launch gdb. |
88e1739c | 31577 | |
7cd4527e | 31578 | @smallexample |
32e209e4 | 31579 | $ gdb |
7cd4527e | 31580 | @end smallexample |
88e1739c | 31581 | |
7cd4527e | 31582 | @item Attach to the running process to be debugged. |
88e1739c | 31583 | |
7cd4527e AC |
31584 | @smallexample |
31585 | (gdb) attach 208 | |
31586 | @end smallexample | |
88e1739c | 31587 | |
7cd4527e | 31588 | @item Load the process debugging information. |
88e1739c FW |
31589 | |
31590 | @smallexample | |
7cd4527e | 31591 | (gdb) symbol-file main.exe |
88e1739c FW |
31592 | @end smallexample |
31593 | ||
7cd4527e | 31594 | @item Break somewhere in the DLL. |
88e1739c | 31595 | |
7cd4527e AC |
31596 | @smallexample |
31597 | (gdb) break ada_dll | |
31598 | @end smallexample | |
88e1739c | 31599 | |
7cd4527e | 31600 | @item Continue process execution. |
88e1739c | 31601 | |
7cd4527e | 31602 | @smallexample |
32e209e4 | 31603 | (gdb) cont |
7cd4527e | 31604 | @end smallexample |
88e1739c | 31605 | |
7cd4527e | 31606 | @end enumerate |
88e1739c | 31607 | |
7cd4527e AC |
31608 | @noindent |
31609 | This last step will resume the process execution, and stop at | |
31610 | the breakpoint we have set. From there you can use the standard | |
31611 | approach to debug a program as described in | |
31612 | (@pxref{Running and Debugging Ada Programs}). | |
31613 | ||
7e3d710b AC |
31614 | @node Setting Stack Size from gnatlink |
31615 | @section Setting Stack Size from @command{gnatlink} | |
88e1739c FW |
31616 | |
31617 | @noindent | |
7e3d710b AC |
31618 | It is possible to specify the program stack size at link time. On modern |
31619 | versions of Windows, starting with XP, this is mostly useful to set the size of | |
31620 | the main stack (environment task). The other task stacks are set with pragma | |
e08b38f5 | 31621 | Storage_Size or with the @command{gnatbind -d} command. |
ba1cbfb9 | 31622 | |
e08b38f5 VC |
31623 | Since older versions of Windows (2000, NT4, etc.) do not allow setting the |
31624 | reserve size of individual tasks, the link-time stack size applies to all | |
31625 | tasks, and pragma Storage_Size has no effect. | |
31626 | In particular, Stack Overflow checks are made against this | |
ba1cbfb9 | 31627 | link-time specified size. |
7e3d710b AC |
31628 | |
31629 | This setting can be done with | |
31630 | @command{gnatlink} using either: | |
31631 | ||
31632 | @itemize @bullet | |
31633 | ||
31634 | @item using @option{-Xlinker} linker option | |
31635 | ||
31636 | @smallexample | |
31637 | $ gnatlink hello -Xlinker --stack=0x10000,0x1000 | |
31638 | @end smallexample | |
31639 | ||
31640 | This sets the stack reserve size to 0x10000 bytes and the stack commit | |
31641 | size to 0x1000 bytes. | |
31642 | ||
31643 | @item using @option{-Wl} linker option | |
31644 | ||
31645 | @smallexample | |
31646 | $ gnatlink hello -Wl,--stack=0x1000000 | |
31647 | @end smallexample | |
31648 | ||
31649 | This sets the stack reserve size to 0x1000000 bytes. Note that with | |
31650 | @option{-Wl} option it is not possible to set the stack commit size | |
31651 | because the coma is a separator for this option. | |
31652 | ||
31653 | @end itemize | |
31654 | ||
31655 | @node Setting Heap Size from gnatlink | |
31656 | @section Setting Heap Size from @command{gnatlink} | |
31657 | ||
31658 | @noindent | |
31659 | Under Windows systems, it is possible to specify the program heap size from | |
31660 | @command{gnatlink} using either: | |
31661 | ||
31662 | @itemize @bullet | |
31663 | ||
31664 | @item using @option{-Xlinker} linker option | |
31665 | ||
31666 | @smallexample | |
31667 | $ gnatlink hello -Xlinker --heap=0x10000,0x1000 | |
31668 | @end smallexample | |
31669 | ||
31670 | This sets the heap reserve size to 0x10000 bytes and the heap commit | |
31671 | size to 0x1000 bytes. | |
31672 | ||
31673 | @item using @option{-Wl} linker option | |
31674 | ||
31675 | @smallexample | |
31676 | $ gnatlink hello -Wl,--heap=0x1000000 | |
31677 | @end smallexample | |
31678 | ||
31679 | This sets the heap reserve size to 0x1000000 bytes. Note that with | |
31680 | @option{-Wl} option it is not possible to set the heap commit size | |
31681 | because the coma is a separator for this option. | |
31682 | ||
31683 | @end itemize | |
31684 | ||
2a328c94 AC |
31685 | @node Mac OS Topics |
31686 | @appendix Mac OS Topics | |
31687 | @cindex OS X | |
31688 | ||
31689 | @noindent | |
31690 | This chapter describes topics that are specific to Apple's OS X | |
31691 | platform. | |
31692 | ||
31693 | @menu | |
31694 | * Codesigning the Debugger:: | |
31695 | @end menu | |
31696 | ||
31697 | @node Codesigning the Debugger | |
31698 | @section Codesigning the Debugger | |
31699 | ||
31700 | @noindent | |
31701 | The Darwin Kernel requires the debugger to have special permissions | |
31702 | before it is allowed to control other processes. These permissions | |
31703 | are granted by codesigning the GDB executable. Without these | |
31704 | permissions, the debugger will report error messages such as: | |
31705 | ||
31706 | @smallexample | |
31707 | Starting program: /x/y/foo | |
31708 | Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5). | |
31709 | (please check gdb is codesigned - see taskgated(8)) | |
31710 | @end smallexample | |
31711 | ||
31712 | Codesigning requires a certificate. The following procedure explains | |
31713 | how to create one: | |
31714 | ||
31715 | @itemize @bullet | |
31716 | @item Start the Keychain Access application (in | |
31717 | /Applications/Utilities/Keychain Access.app) | |
31718 | ||
31719 | @item Select the Keychain Access -> Certificate Assistant -> | |
31720 | Create a Certificate... menu | |
31721 | ||
31722 | @item Then: | |
31723 | ||
31724 | @itemize @bullet | |
31725 | @item Choose a name for the new certificate (this procedure will use | |
31726 | "gdb-cert" as an example) | |
31727 | ||
31728 | @item Set "Identity Type" to "Self Signed Root" | |
31729 | ||
31730 | @item Set "Certificate Type" to "Code Signing" | |
31731 | ||
31732 | @item Activate the "Let me override defaults" option | |
31733 | ||
31734 | @end itemize | |
31735 | ||
31736 | @item Click several times on "Continue" until the "Specify a Location | |
31737 | For The Certificate" screen appears, then set "Keychain" to "System" | |
31738 | ||
31739 | @item Click on "Continue" until the certificate is created | |
31740 | ||
31741 | @item Finally, in the view, double-click on the new certificate, | |
31742 | and set "When using this certificate" to "Always Trust" | |
31743 | ||
31744 | @item Exit the Keychain Access application and restart the computer | |
31745 | (this is unfortunately required) | |
31746 | ||
31747 | @end itemize | |
31748 | ||
31749 | Once a certificate has been created, the debugger can be codesigned | |
31750 | as follow. In a Terminal, run the following command... | |
31751 | ||
31752 | @smallexample | |
31753 | codesign -f -s "gdb-cert" <gnat_install_prefix>/bin/gdb | |
31754 | @end smallexample | |
31755 | ||
31756 | ... where "gdb-cert" should be replaced by the actual certificate | |
31757 | name chosen above, and <gnat_install_prefix> should be replaced by | |
31758 | the location where you installed GNAT. | |
31759 | ||
7cd4527e AC |
31760 | @c ********************************** |
31761 | @c * GNU Free Documentation License * | |
31762 | @c ********************************** | |
88e1739c FW |
31763 | @include fdl.texi |
31764 | @c GNU Free Documentation License | |
31765 | ||
0c68c613 | 31766 | @node Index |
88e1739c FW |
31767 | @unnumbered Index |
31768 | ||
31769 | @printindex cp | |
31770 | ||
31771 | @contents | |
7cd4527e AC |
31772 | @c Put table of contents at end, otherwise it precedes the "title page" in |
31773 | @c the .txt version | |
31774 | @c Edit the pdf file to move the contents to the beginning, after the title | |
31775 | @c page | |
88e1739c FW |
31776 | |
31777 | @bye |