]>
Commit | Line | Data |
---|---|---|
88e1739c FW |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | ||
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 |
7cd4527e | 10 | @c Copyright (C) 1992-2004 Ada Core Technologies, Inc. o |
88e1739c FW |
11 | @c o |
12 | @c GNAT is free software; you can redistribute it and/or modify it under o | |
13 | @c terms of the GNU General Public License as published by the Free Soft- o | |
14 | @c ware Foundation; either version 2, or (at your option) any later ver- o | |
15 | @c sion. GNAT is distributed in the hope that it will be useful, but WITH- o | |
16 | @c OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY o | |
17 | @c or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License o | |
18 | @c for more details. You should have received a copy of the GNU General o | |
19 | @c Public License distributed with GNAT; see file COPYING. If not, write o | |
20 | @c to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, o | |
21 | @c MA 02111-1307, USA. o | |
22 | @c o | |
88e1739c FW |
23 | @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo |
24 | ||
25 | @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo | |
26 | @c | |
7cd4527e | 27 | @c GNAT_UGN Style Guide |
88e1739c FW |
28 | @c |
29 | @c 1. Always put a @noindent on the line before the first paragraph | |
30 | @c after any of these commands: | |
31 | @c | |
32 | @c @chapter | |
33 | @c @section | |
34 | @c @subsection | |
35 | @c @subsubsection | |
36 | @c @subsubsubsection | |
37 | @c | |
38 | @c @end smallexample | |
39 | @c @end itemize | |
40 | @c @end enumerate | |
41 | @c | |
42 | @c 2. DO NOT use @example. Use @smallexample instead. | |
7cd4527e AC |
43 | @c a) DO NOT use highlighting commands (@b{}, @i{}) inside an @smallexample |
44 | @c context. These can interfere with the readability of the texi | |
45 | @c source file. Instead, use one of the following annotated | |
46 | @c @smallexample commands, and preprocess the texi file with the | |
47 | @c ada2texi tool (which generates appropriate highlighting): | |
48 | @c @smallexample @c ada | |
49 | @c @smallexample @c adanocomment | |
50 | @c @smallexample @c projectfile | |
51 | @c b) The "@c ada" markup will result in boldface for reserved words | |
52 | @c and italics for comments | |
53 | @c c) The "@c adanocomment" markup will result only in boldface for | |
54 | @c reserved words (comments are left alone) | |
55 | @c d) The "@c projectfile" markup is like "@c ada" except that the set | |
56 | @c of reserved words include the new reserved words for project files | |
88e1739c FW |
57 | @c |
58 | @c 3. Each @chapter, @section, @subsection, @subsubsection, etc. | |
59 | @c command must be preceded by two empty lines | |
60 | @c | |
7cd4527e | 61 | @c 4. The @item command should be on a line of its own if it is in an |
88e1739c FW |
62 | @c @itemize or @enumerate command. |
63 | @c | |
64 | @c 5. When talking about ALI files use "ALI" (all uppercase), not "Ali" | |
65 | @c or "ali". | |
66 | @c | |
7cd4527e AC |
67 | @c 6. DO NOT put trailing spaces at the end of a line. Such spaces will |
68 | @c cause the document build to fail. | |
69 | @c | |
70 | @c 7. DO NOT use @cartouche for examples that are longer than around 10 lines. | |
71 | @c This command inhibits page breaks, so long examples in a @cartouche can | |
72 | @c lead to large, ugly patches of empty space on a page. | |
73 | @c | |
74 | @c NOTE: This file should be submitted to xgnatugn with either the vms flag | |
75 | @c or the unw flag set. The unw flag covers topics for both Unix and | |
76 | @c Windows. | |
77 | @c | |
88e1739c FW |
78 | @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo |
79 | ||
7cd4527e | 80 | @setfilename gnat_ugn.info |
88e1739c | 81 | |
7cd4527e AC |
82 | @ifset vms |
83 | @settitle GNAT User's Guide for Native Platforms / OpenVMS Alpha | |
6da7d579 AC |
84 | @dircategory GNU Ada tools |
85 | @direntry | |
86 | * GNAT User's Guide (gnat_ugn_vms) for Native Platforms / OpenVMS Alpha | |
87 | @end direntry | |
88e1739c FW |
88 | @end ifset |
89 | ||
7cd4527e AC |
90 | @ifset unw |
91 | @settitle GNAT User's Guide for Native Platforms / Unix and Windows | |
6da7d579 AC |
92 | @direntry |
93 | * GNAT User's Guide (gnat_ugn_unw) for Native Platforms / Unix and Windows | |
94 | @end direntry | |
88e1739c FW |
95 | @end ifset |
96 | ||
5321fb3e FW |
97 | @include gcc-common.texi |
98 | ||
88e1739c FW |
99 | @setchapternewpage odd |
100 | @syncodeindex fn cp | |
101 | @c %**end of header | |
102 | ||
bdefb2ab | 103 | @copying |
7cd4527e | 104 | Copyright @copyright{} 1995-2004, Free Software Foundation |
bdefb2ab JM |
105 | |
106 | Permission is granted to copy, distribute and/or modify this document | |
b3a8389d | 107 | under the terms of the GNU Free Documentation License, Version 1.2 |
bdefb2ab JM |
108 | or any later version published by the Free Software Foundation; |
109 | with the Invariant Sections being ``GNU Free Documentation License'', with the | |
110 | Front-Cover Texts being | |
111 | @ifset vms | |
7cd4527e | 112 | ``GNAT User's Guide for Native Platforms / OpenVMS Alpha'', |
bdefb2ab | 113 | @end ifset |
7cd4527e AC |
114 | @ifset unw |
115 | ``GNAT User's Guide for Native Platforms / Unix and Windows'', | |
bdefb2ab JM |
116 | @end ifset |
117 | and with no Back-Cover Texts. | |
7cd4527e AC |
118 | A copy of the license is included in the section entitled |
119 | ``GNU Free Documentation License''. | |
bdefb2ab JM |
120 | @end copying |
121 | ||
88e1739c FW |
122 | @titlepage |
123 | ||
88e1739c | 124 | @title GNAT User's Guide |
7cd4527e AC |
125 | @center @titlefont{for Native Platforms} |
126 | @sp 1 | |
88e1739c | 127 | |
7cd4527e AC |
128 | @flushright |
129 | @ifset unw | |
130 | @titlefont{@i{Unix and Windows}} | |
88e1739c | 131 | @end ifset |
7cd4527e AC |
132 | @ifset vms |
133 | @titlefont{@i{OpenVMS Alpha}} | |
88e1739c | 134 | @end ifset |
7cd4527e AC |
135 | @end flushright |
136 | @sp 2 | |
88e1739c FW |
137 | |
138 | @subtitle GNAT, The GNU Ada 95 Compiler | |
7cd4527e | 139 | @subtitle GCC version @value{version-GCC} |
88e1739c FW |
140 | |
141 | @author Ada Core Technologies, Inc. | |
142 | ||
143 | @page | |
144 | @vskip 0pt plus 1filll | |
145 | ||
bdefb2ab | 146 | @insertcopying |
88e1739c FW |
147 | |
148 | @end titlepage | |
149 | ||
7cd4527e | 150 | |
6da7d579 | 151 | @ifnottex |
88e1739c FW |
152 | @node Top, About This Guide, (dir), (dir) |
153 | @top GNAT User's Guide | |
154 | ||
155 | @ifset vms | |
7cd4527e AC |
156 | @noindent |
157 | GNAT User's Guide for Native Platforms / OpenVMS Alpha | |
88e1739c FW |
158 | @end ifset |
159 | ||
7cd4527e AC |
160 | @ifset unw |
161 | @noindent | |
162 | GNAT User's Guide for Native Platforms / Unix and Windows | |
88e1739c FW |
163 | @end ifset |
164 | ||
7cd4527e AC |
165 | @noindent |
166 | GNAT, The GNU Ada 95 Compiler@* | |
167 | GCC version @value{version-GCC}@* | |
88e1739c | 168 | |
7cd4527e AC |
169 | @noindent |
170 | Ada Core Technologies, Inc.@* | |
88e1739c FW |
171 | |
172 | @menu | |
173 | * About This Guide:: | |
88e1739c FW |
174 | * Getting Started with GNAT:: |
175 | * The GNAT Compilation Model:: | |
176 | * Compiling Using gcc:: | |
177 | * Binding Using gnatbind:: | |
178 | * Linking Using gnatlink:: | |
179 | * The GNAT Make Program gnatmake:: | |
7cd4527e | 180 | * Improving Performance:: |
88e1739c FW |
181 | * Renaming Files Using gnatchop:: |
182 | * Configuration Pragmas:: | |
183 | * Handling Arbitrary File Naming Conventions Using gnatname:: | |
184 | * GNAT Project Manager:: | |
88e1739c | 185 | * The Cross-Referencing Tools gnatxref and gnatfind:: |
7cd4527e | 186 | * The GNAT Pretty-Printer gnatpp:: |
88e1739c FW |
187 | * File Name Krunching Using gnatkr:: |
188 | * Preprocessing Using gnatprep:: | |
189 | @ifset vms | |
190 | * The GNAT Run-Time Library Builder gnatlbr:: | |
191 | @end ifset | |
192 | * The GNAT Library Browser gnatls:: | |
7cd4527e | 193 | * Cleaning Up Using gnatclean:: |
88e1739c FW |
194 | @ifclear vms |
195 | * GNAT and Libraries:: | |
196 | * Using the GNU make Utility:: | |
88e1739c | 197 | @end ifclear |
7cd4527e | 198 | * Finding Memory Problems:: |
88e1739c | 199 | * Creating Sample Bodies Using gnatstub:: |
88e1739c | 200 | * Other Utility Programs:: |
7cd4527e | 201 | * Running and Debugging Ada Programs:: |
88e1739c FW |
202 | @ifset vms |
203 | * Compatibility with DEC Ada:: | |
204 | @end ifset | |
7cd4527e AC |
205 | * Platform-Specific Information for the Run-Time Libraries:: |
206 | * Example of Binder Output File:: | |
207 | * Elaboration Order Handling in GNAT:: | |
88e1739c | 208 | * Inline Assembler:: |
7cd4527e AC |
209 | * Compatibility and Porting Guide:: |
210 | @ifset unw | |
88e1739c FW |
211 | * Microsoft Windows Topics:: |
212 | @end ifset | |
88e1739c FW |
213 | * GNU Free Documentation License:: |
214 | * Index:: | |
215 | ||
216 | --- The Detailed Node Listing --- | |
217 | ||
218 | About This Guide | |
219 | ||
220 | * What This Guide Contains:: | |
221 | * What You Should Know before Reading This Guide:: | |
222 | * Related Information:: | |
223 | * Conventions:: | |
224 | ||
88e1739c FW |
225 | Getting Started with GNAT |
226 | ||
227 | * Running GNAT:: | |
88e1739c | 228 | * Running a Simple Ada Program:: |
88e1739c FW |
229 | * Running a Program with Multiple Units:: |
230 | * Using the gnatmake Utility:: | |
231 | @ifset vms | |
232 | * Editing with Emacs:: | |
233 | @end ifset | |
7cd4527e AC |
234 | @ifclear vms |
235 | * Introduction to GPS:: | |
236 | * Introduction to Glide and GVD:: | |
237 | @end ifclear | |
88e1739c FW |
238 | |
239 | The GNAT Compilation Model | |
240 | ||
241 | * Source Representation:: | |
242 | * Foreign Language Representation:: | |
243 | * File Naming Rules:: | |
244 | * Using Other File Names:: | |
245 | * Alternative File Naming Schemes:: | |
246 | * Generating Object Files:: | |
247 | * Source Dependencies:: | |
248 | * The Ada Library Information Files:: | |
249 | * Binding an Ada Program:: | |
250 | * Mixed Language Programming:: | |
251 | * Building Mixed Ada & C++ Programs:: | |
252 | * Comparison between GNAT and C/C++ Compilation Models:: | |
253 | * Comparison between GNAT and Conventional Ada Library Models:: | |
7cd4527e AC |
254 | @ifset vms |
255 | * Placement of temporary files:: | |
256 | @end ifset | |
88e1739c FW |
257 | |
258 | Foreign Language Representation | |
259 | ||
260 | * Latin-1:: | |
261 | * Other 8-Bit Codes:: | |
262 | * Wide Character Encodings:: | |
263 | ||
264 | Compiling Ada Programs With gcc | |
265 | ||
266 | * Compiling Programs:: | |
267 | * Switches for gcc:: | |
268 | * Search Paths and the Run-Time Library (RTL):: | |
269 | * Order of Compilation Issues:: | |
270 | * Examples:: | |
271 | ||
272 | Switches for gcc | |
273 | ||
274 | * Output and Error Message Control:: | |
7cd4527e | 275 | * Warning Message Control:: |
88e1739c FW |
276 | * Debugging and Assertion Control:: |
277 | * Run-Time Checks:: | |
278 | * Stack Overflow Checking:: | |
88e1739c FW |
279 | * Validity Checking:: |
280 | * Style Checking:: | |
281 | * Using gcc for Syntax Checking:: | |
282 | * Using gcc for Semantic Checking:: | |
283 | * Compiling Ada 83 Programs:: | |
284 | * Character Set Control:: | |
285 | * File Naming Control:: | |
286 | * Subprogram Inlining Control:: | |
287 | * Auxiliary Output Control:: | |
288 | * Debugging Control:: | |
7cd4527e | 289 | * Exception Handling Control:: |
88e1739c | 290 | * Units to Sources Mapping Files:: |
7cd4527e AC |
291 | * Integrated Preprocessing:: |
292 | @ifset vms | |
293 | * Return Codes:: | |
294 | @end ifset | |
88e1739c FW |
295 | |
296 | Binding Ada Programs With gnatbind | |
297 | ||
298 | * Running gnatbind:: | |
7cd4527e AC |
299 | * Switches for gnatbind:: |
300 | * Command-Line Access:: | |
301 | * Search Paths for gnatbind:: | |
302 | * Examples of gnatbind Usage:: | |
303 | ||
304 | Switches for gnatbind | |
305 | ||
88e1739c FW |
306 | * Consistency-Checking Modes:: |
307 | * Binder Error Message Control:: | |
308 | * Elaboration Control:: | |
309 | * Output Control:: | |
310 | * Binding with Non-Ada Main Programs:: | |
311 | * Binding Programs with No Main Subprogram:: | |
88e1739c FW |
312 | |
313 | Linking Using gnatlink | |
314 | ||
315 | * Running gnatlink:: | |
316 | * Switches for gnatlink:: | |
317 | * Setting Stack Size from gnatlink:: | |
318 | * Setting Heap Size from gnatlink:: | |
319 | ||
320 | The GNAT Make Program gnatmake | |
321 | ||
322 | * Running gnatmake:: | |
323 | * Switches for gnatmake:: | |
324 | * Mode Switches for gnatmake:: | |
325 | * Notes on the Command Line:: | |
326 | * How gnatmake Works:: | |
327 | * Examples of gnatmake Usage:: | |
328 | ||
7cd4527e AC |
329 | |
330 | Improving Performance | |
331 | * Performance Considerations:: | |
332 | * Reducing the Size of Ada Executables with gnatelim:: | |
333 | ||
334 | Performance Considerations | |
335 | * Controlling Run-Time Checks:: | |
336 | * Use of Restrictions:: | |
337 | * Optimization Levels:: | |
338 | * Debugging Optimized Code:: | |
339 | * Inlining of Subprograms:: | |
340 | * Optimization and Strict Aliasing:: | |
341 | @ifset vms | |
342 | * Coverage Analysis:: | |
343 | @end ifset | |
344 | ||
345 | Reducing the Size of Ada Executables with gnatelim | |
346 | * About gnatelim:: | |
347 | * Running gnatelim:: | |
348 | * Correcting the List of Eliminate Pragmas:: | |
349 | * Making Your Executables Smaller:: | |
350 | * Summary of the gnatelim Usage Cycle:: | |
351 | ||
88e1739c FW |
352 | Renaming Files Using gnatchop |
353 | ||
354 | * Handling Files with Multiple Units:: | |
355 | * Operating gnatchop in Compilation Mode:: | |
356 | * Command Line for gnatchop:: | |
357 | * Switches for gnatchop:: | |
358 | * Examples of gnatchop Usage:: | |
359 | ||
360 | Configuration Pragmas | |
361 | ||
362 | * Handling of Configuration Pragmas:: | |
363 | * The Configuration Pragmas Files:: | |
364 | ||
365 | Handling Arbitrary File Naming Conventions Using gnatname | |
366 | ||
367 | * Arbitrary File Naming Conventions:: | |
368 | * Running gnatname:: | |
369 | * Switches for gnatname:: | |
370 | * Examples of gnatname Usage:: | |
371 | ||
372 | GNAT Project Manager | |
373 | ||
374 | * Introduction:: | |
375 | * Examples of Project Files:: | |
376 | * Project File Syntax:: | |
377 | * Objects and Sources in Project Files:: | |
378 | * Importing Projects:: | |
379 | * Project Extension:: | |
380 | * External References in Project Files:: | |
381 | * Packages in Project Files:: | |
382 | * Variables from Imported Projects:: | |
383 | * Naming Schemes:: | |
384 | * Library Projects:: | |
7cd4527e AC |
385 | * Using Third-Party Libraries through Projects:: |
386 | * Stand-alone Library Projects:: | |
88e1739c FW |
387 | * Switches Related to Project Files:: |
388 | * Tools Supporting Project Files:: | |
389 | * An Extended Example:: | |
390 | * Project File Complete Syntax:: | |
391 | ||
88e1739c FW |
392 | |
393 | The Cross-Referencing Tools gnatxref and gnatfind | |
394 | ||
395 | * gnatxref Switches:: | |
396 | * gnatfind Switches:: | |
397 | * Project Files for gnatxref and gnatfind:: | |
398 | * Regular Expressions in gnatfind and gnatxref:: | |
399 | * Examples of gnatxref Usage:: | |
400 | * Examples of gnatfind Usage:: | |
401 | ||
7cd4527e AC |
402 | |
403 | The GNAT Pretty-Printer gnatpp | |
404 | ||
405 | * Switches for gnatpp:: | |
406 | * Formatting Rules:: | |
407 | ||
408 | ||
88e1739c FW |
409 | File Name Krunching Using gnatkr |
410 | ||
411 | * About gnatkr:: | |
412 | * Using gnatkr:: | |
413 | * Krunching Method:: | |
414 | * Examples of gnatkr Usage:: | |
415 | ||
416 | Preprocessing Using gnatprep | |
417 | ||
418 | * Using gnatprep:: | |
419 | * Switches for gnatprep:: | |
420 | * Form of Definitions File:: | |
421 | * Form of Input Text for gnatprep:: | |
422 | ||
423 | @ifset vms | |
424 | The GNAT Run-Time Library Builder gnatlbr | |
425 | ||
426 | * Running gnatlbr:: | |
427 | * Switches for gnatlbr:: | |
428 | * Examples of gnatlbr Usage:: | |
429 | @end ifset | |
430 | ||
431 | The GNAT Library Browser gnatls | |
432 | ||
433 | * Running gnatls:: | |
434 | * Switches for gnatls:: | |
435 | * Examples of gnatls Usage:: | |
436 | ||
7cd4527e AC |
437 | Cleaning Up Using gnatclean |
438 | ||
439 | * Running gnatclean:: | |
440 | * Switches for gnatclean:: | |
441 | * Examples of gnatclean Usage:: | |
442 | ||
88e1739c FW |
443 | @ifclear vms |
444 | ||
445 | GNAT and Libraries | |
446 | ||
447 | * Creating an Ada Library:: | |
448 | * Installing an Ada Library:: | |
449 | * Using an Ada Library:: | |
450 | * Creating an Ada Library to be Used in a Non-Ada Context:: | |
451 | * Rebuilding the GNAT Run-Time Library:: | |
452 | ||
453 | Using the GNU make Utility | |
454 | ||
455 | * Using gnatmake in a Makefile:: | |
456 | * Automatically Creating a List of Directories:: | |
457 | * Generating the Command Line Switches:: | |
458 | * Overcoming Command Line Length Limits:: | |
7cd4527e | 459 | @end ifclear |
88e1739c | 460 | |
7cd4527e | 461 | Finding Memory Problems |
88e1739c | 462 | |
7cd4527e AC |
463 | @ifclear vms |
464 | * The gnatmem Tool:: | |
88e1739c | 465 | @end ifclear |
7cd4527e AC |
466 | * The GNAT Debug Pool Facility:: |
467 | ||
468 | @ifclear vms | |
469 | The gnatmem Tool | |
470 | ||
471 | * Running gnatmem:: | |
472 | * Switches for gnatmem:: | |
473 | * Example of gnatmem Usage:: | |
88e1739c FW |
474 | @end ifclear |
475 | ||
7cd4527e | 476 | The GNAT Debug Pool Facility |
88e1739c FW |
477 | |
478 | Creating Sample Bodies Using gnatstub | |
479 | ||
480 | * Running gnatstub:: | |
481 | * Switches for gnatstub:: | |
482 | ||
88e1739c FW |
483 | Other Utility Programs |
484 | ||
485 | * Using Other Utility Programs with GNAT:: | |
88e1739c | 486 | * The External Symbol Naming Scheme of GNAT:: |
7cd4527e | 487 | @ifclear vms |
88e1739c | 488 | * Ada Mode for Glide:: |
7cd4527e | 489 | @end ifclear |
88e1739c | 490 | * Converting Ada Files to html with gnathtml:: |
7cd4527e AC |
491 | |
492 | Running and Debugging Ada Programs | |
493 | ||
494 | * The GNAT Debugger GDB:: | |
495 | * Running GDB:: | |
496 | * Introduction to GDB Commands:: | |
497 | * Using Ada Expressions:: | |
498 | * Calling User-Defined Subprograms:: | |
499 | * Using the Next Command in a Function:: | |
500 | * Ada Exceptions:: | |
501 | * Ada Tasks:: | |
502 | * Debugging Generic Units:: | |
503 | * GNAT Abnormal Termination or Failure to Terminate:: | |
504 | * Naming Conventions for GNAT Source Files:: | |
505 | * Getting Internal Debugging Information:: | |
506 | * Stack Traceback:: | |
507 | ||
88e1739c FW |
508 | @ifset vms |
509 | * LSE:: | |
510 | @end ifset | |
511 | ||
512 | @ifset vms | |
513 | Compatibility with DEC Ada | |
514 | ||
515 | * Ada 95 Compatibility:: | |
516 | * Differences in the Definition of Package System:: | |
517 | * Language-Related Features:: | |
518 | * The Package STANDARD:: | |
519 | * The Package SYSTEM:: | |
520 | * Tasking and Task-Related Features:: | |
521 | * Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems:: | |
522 | * Pragmas and Pragma-Related Features:: | |
523 | * Library of Predefined Units:: | |
524 | * Bindings:: | |
525 | * Main Program Definition:: | |
526 | * Implementation-Defined Attributes:: | |
527 | * Compiler and Run-Time Interfacing:: | |
528 | * Program Compilation and Library Management:: | |
529 | * Input-Output:: | |
530 | * Implementation Limits:: | |
531 | * Tools:: | |
532 | ||
533 | Language-Related Features | |
534 | ||
535 | * Integer Types and Representations:: | |
536 | * Floating-Point Types and Representations:: | |
537 | * Pragmas Float_Representation and Long_Float:: | |
538 | * Fixed-Point Types and Representations:: | |
539 | * Record and Array Component Alignment:: | |
540 | * Address Clauses:: | |
541 | * Other Representation Clauses:: | |
542 | ||
543 | Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems | |
544 | ||
545 | * Assigning Task IDs:: | |
546 | * Task IDs and Delays:: | |
547 | * Task-Related Pragmas:: | |
548 | * Scheduling and Task Priority:: | |
549 | * The Task Stack:: | |
550 | * External Interrupts:: | |
551 | ||
552 | Pragmas and Pragma-Related Features | |
553 | ||
554 | * Restrictions on the Pragma INLINE:: | |
555 | * Restrictions on the Pragma INTERFACE:: | |
556 | * Restrictions on the Pragma SYSTEM_NAME:: | |
557 | ||
558 | Library of Predefined Units | |
559 | ||
560 | * Changes to DECLIB:: | |
561 | ||
562 | Bindings | |
563 | ||
564 | * Shared Libraries and Options Files:: | |
565 | * Interfaces to C:: | |
566 | @end ifset | |
567 | ||
7cd4527e | 568 | Platform-Specific Information for the Run-Time Libraries |
88e1739c | 569 | |
7cd4527e AC |
570 | * Summary of Run-Time Configurations:: |
571 | * Specifying a Run-Time Library:: | |
572 | * Choosing between Native and FSU Threads Libraries:: | |
573 | * Choosing the Scheduling Policy:: | |
574 | * Solaris-Specific Considerations:: | |
575 | * IRIX-Specific Considerations:: | |
576 | * Linux-Specific Considerations:: | |
577 | ||
578 | Example of Binder Output File | |
579 | ||
580 | Elaboration Order Handling in GNAT | |
581 | ||
582 | * Elaboration Code in Ada 95:: | |
583 | * Checking the Elaboration Order in Ada 95:: | |
584 | * Controlling the Elaboration Order in Ada 95:: | |
585 | * Controlling Elaboration in GNAT - Internal Calls:: | |
586 | * Controlling Elaboration in GNAT - External Calls:: | |
587 | * Default Behavior in GNAT - Ensuring Safety:: | |
588 | * Treatment of Pragma Elaborate:: | |
589 | * Elaboration Issues for Library Tasks:: | |
590 | * Mixing Elaboration Models:: | |
591 | * What to Do If the Default Elaboration Behavior Fails:: | |
592 | * Elaboration for Access-to-Subprogram Values:: | |
593 | * Summary of Procedures for Elaboration Control:: | |
594 | * Other Elaboration Order Considerations:: | |
88e1739c FW |
595 | |
596 | Inline Assembler | |
597 | ||
598 | * Basic Assembler Syntax:: | |
599 | * A Simple Example of Inline Assembler:: | |
600 | * Output Variables in Inline Assembler:: | |
601 | * Input Variables in Inline Assembler:: | |
602 | * Inlining Inline Assembler Code:: | |
603 | * Other Asm Functionality:: | |
604 | * A Complete Example:: | |
605 | ||
7cd4527e AC |
606 | Compatibility and Porting Guide |
607 | ||
608 | * Compatibility with Ada 83:: | |
609 | * Implementation-dependent characteristics:: | |
610 | * Compatibility with DEC Ada 83:: | |
611 | * Compatibility with Other Ada 95 Systems:: | |
612 | * Representation Clauses:: | |
613 | ||
614 | @ifset unw | |
88e1739c FW |
615 | Microsoft Windows Topics |
616 | ||
617 | * Using GNAT on Windows:: | |
88e1739c FW |
618 | * CONSOLE and WINDOWS subsystems:: |
619 | * Temporary Files:: | |
620 | * Mixed-Language Programming on Windows:: | |
621 | * Windows Calling Conventions:: | |
622 | * Introduction to Dynamic Link Libraries (DLLs):: | |
623 | * Using DLLs with GNAT:: | |
624 | * Building DLLs with GNAT:: | |
625 | * GNAT and Windows Resources:: | |
7cd4527e | 626 | * Debugging a DLL:: |
88e1739c FW |
627 | * GNAT and COM/DCOM Objects:: |
628 | @end ifset | |
629 | ||
88e1739c FW |
630 | |
631 | * Index:: | |
632 | @end menu | |
6da7d579 | 633 | @end ifnottex |
88e1739c FW |
634 | |
635 | @node About This Guide | |
636 | @unnumbered About This Guide | |
637 | ||
638 | @noindent | |
639 | @ifset vms | |
640 | This guide describes the use of of GNAT, a full language compiler for the Ada | |
7cd4527e | 641 | 95 programming language, implemented on HP OpenVMS Alpha platforms. |
88e1739c FW |
642 | @end ifset |
643 | @ifclear vms | |
644 | This guide describes the use of GNAT, a compiler and software development | |
645 | toolset for the full Ada 95 programming language. | |
646 | @end ifclear | |
647 | It describes the features of the compiler and tools, and details | |
648 | how to use them to build Ada 95 applications. | |
649 | ||
650 | @menu | |
651 | * What This Guide Contains:: | |
652 | * What You Should Know before Reading This Guide:: | |
653 | * Related Information:: | |
654 | * Conventions:: | |
655 | @end menu | |
656 | ||
657 | @node What This Guide Contains | |
658 | @unnumberedsec What This Guide Contains | |
659 | ||
660 | @noindent | |
661 | This guide contains the following chapters: | |
662 | @itemize @bullet | |
7cd4527e | 663 | |
88e1739c FW |
664 | @item |
665 | @ref{Getting Started with GNAT}, describes how to get started compiling | |
666 | and running Ada programs with the GNAT Ada programming environment. | |
667 | @item | |
668 | @ref{The GNAT Compilation Model}, describes the compilation model used | |
669 | by GNAT. | |
7cd4527e | 670 | |
88e1739c FW |
671 | @item |
672 | @ref{Compiling Using gcc}, describes how to compile | |
673 | Ada programs with @code{gcc}, the Ada compiler. | |
7cd4527e | 674 | |
88e1739c FW |
675 | @item |
676 | @ref{Binding Using gnatbind}, describes how to | |
677 | perform binding of Ada programs with @code{gnatbind}, the GNAT binding | |
678 | utility. | |
7cd4527e | 679 | |
88e1739c FW |
680 | @item |
681 | @ref{Linking Using gnatlink}, | |
682 | describes @code{gnatlink}, a | |
683 | program that provides for linking using the GNAT run-time library to | |
684 | construct a program. @code{gnatlink} can also incorporate foreign language | |
685 | object units into the executable. | |
7cd4527e | 686 | |
88e1739c FW |
687 | @item |
688 | @ref{The GNAT Make Program gnatmake}, describes @code{gnatmake}, a | |
689 | utility that automatically determines the set of sources | |
690 | needed by an Ada compilation unit, and executes the necessary compilations | |
691 | binding and link. | |
7cd4527e AC |
692 | |
693 | @item | |
694 | @ref{Improving Performance}, shows various techniques for making your | |
695 | Ada program run faster or take less space. | |
696 | It discusses the effect of the compiler's optimization switch and | |
697 | also describes the @command{gnatelim} tool. | |
698 | ||
88e1739c FW |
699 | @item |
700 | @ref{Renaming Files Using gnatchop}, describes | |
701 | @code{gnatchop}, a utility that allows you to preprocess a file that | |
702 | contains Ada source code, and split it into one or more new files, one | |
703 | for each compilation unit. | |
7cd4527e | 704 | |
88e1739c | 705 | @item |
7cd4527e AC |
706 | @ref{Configuration Pragmas}, describes the configuration pragmas |
707 | handled by GNAT. | |
708 | ||
88e1739c | 709 | @item |
7cd4527e AC |
710 | @ref{Handling Arbitrary File Naming Conventions Using gnatname}, |
711 | shows how to override the default GNAT file naming conventions, | |
712 | either for an individual unit or globally. | |
713 | ||
88e1739c | 714 | @item |
7cd4527e AC |
715 | @ref{GNAT Project Manager}, describes how to use project files |
716 | to organize large projects. | |
717 | ||
88e1739c FW |
718 | @item |
719 | @ref{The Cross-Referencing Tools gnatxref and gnatfind}, discusses | |
720 | @code{gnatxref} and @code{gnatfind}, two tools that provide an easy | |
721 | way to navigate through sources. | |
7cd4527e AC |
722 | |
723 | @item | |
724 | @ref{The GNAT Pretty-Printer gnatpp}, shows how to produce a reformatted | |
725 | version of an Ada source file with control over casing, indentation, | |
726 | comment placement, and other elements of program presentation style. | |
727 | ||
728 | ||
88e1739c FW |
729 | @item |
730 | @ref{File Name Krunching Using gnatkr}, describes the @code{gnatkr} | |
731 | file name krunching utility, used to handle shortened | |
732 | file names on operating systems with a limit on the length of names. | |
7cd4527e | 733 | |
88e1739c FW |
734 | @item |
735 | @ref{Preprocessing Using gnatprep}, describes @code{gnatprep}, a | |
736 | preprocessor utility that allows a single source file to be used to | |
737 | generate multiple or parameterized source files, by means of macro | |
738 | substitution. | |
7cd4527e AC |
739 | |
740 | @ifset vms | |
741 | @item | |
742 | @ref{The GNAT Run-Time Library Builder gnatlbr}, describes @command{gnatlbr}, | |
743 | a tool for rebuilding the GNAT run time with user-supplied | |
744 | configuration pragmas. | |
745 | @end ifset | |
746 | ||
88e1739c FW |
747 | @item |
748 | @ref{The GNAT Library Browser gnatls}, describes @code{gnatls}, a | |
749 | utility that displays information about compiled units, including dependences | |
750 | on the corresponding sources files, and consistency of compilations. | |
7cd4527e AC |
751 | |
752 | @item | |
753 | @ref{Cleaning Up Using gnatclean}, describes @code{gnatclean}, a utility | |
754 | to delete files that are produced by the compiler, binder and linker. | |
755 | ||
88e1739c FW |
756 | @ifclear vms |
757 | @item | |
758 | @ref{GNAT and Libraries}, describes the process of creating and using | |
759 | Libraries with GNAT. It also describes how to recompile the GNAT run-time | |
760 | library. | |
761 | ||
762 | @item | |
763 | @ref{Using the GNU make Utility}, describes some techniques for using | |
764 | the GNAT toolset in Makefiles. | |
7cd4527e | 765 | @end ifclear |
88e1739c | 766 | |
88e1739c | 767 | @item |
7cd4527e AC |
768 | @ref{Finding Memory Problems}, describes |
769 | @ifclear vms | |
770 | @command{gnatmem}, a utility that monitors dynamic allocation and deallocation | |
771 | and helps detect ``memory leaks'', and | |
88e1739c | 772 | @end ifclear |
7cd4527e | 773 | the GNAT Debug Pool facility, which helps detect incorrect memory references. |
88e1739c FW |
774 | |
775 | @item | |
776 | @ref{Creating Sample Bodies Using gnatstub}, discusses @code{gnatstub}, | |
777 | a utility that generates empty but compilable bodies for library units. | |
778 | ||
88e1739c FW |
779 | @item |
780 | @ref{Other Utility Programs}, discusses several other GNAT utilities, | |
7cd4527e | 781 | including @code{gnathtml}. |
88e1739c FW |
782 | |
783 | @item | |
784 | @ref{Running and Debugging Ada Programs}, describes how to run and debug | |
785 | Ada programs. | |
786 | ||
7cd4527e | 787 | @ifset vms |
88e1739c | 788 | @item |
7cd4527e AC |
789 | @ref{Compatibility with DEC Ada}, details the compatibility of GNAT with |
790 | DEC Ada 83 @footnote{``DEC Ada'' refers to the legacy product originally | |
791 | developed by Digital Equipment Corporation and currently supported by HP.} | |
792 | for OpenVMS Alpha. | |
793 | @end ifset | |
88e1739c | 794 | |
88e1739c | 795 | @item |
7cd4527e AC |
796 | @ref{Platform-Specific Information for the Run-Time Libraries}, |
797 | describes the various run-time | |
798 | libraries supported by GNAT on various platforms and explains how to | |
799 | choose a particular library. | |
88e1739c FW |
800 | |
801 | @item | |
7cd4527e AC |
802 | @ref{Example of Binder Output File}, shows the source code for the binder |
803 | output file for a sample program. | |
88e1739c FW |
804 | |
805 | @item | |
7cd4527e AC |
806 | @ref{Elaboration Order Handling in GNAT}, describes how GNAT helps |
807 | you deal with elaboration order issues. | |
808 | ||
88e1739c | 809 | @item |
7cd4527e AC |
810 | @ref{Inline Assembler}, shows how to use the inline assembly facility |
811 | in an Ada program. | |
812 | ||
813 | @item | |
814 | @ref{Compatibility and Porting Guide}, includes sections on compatibility | |
815 | of GNAT with other Ada 83 and Ada 95 compilation systems, to assist | |
816 | in porting code from other environments. | |
817 | ||
818 | @ifset unw | |
819 | @item | |
820 | @ref{Microsoft Windows Topics}, presents information relevant to the | |
821 | Microsoft Windows platform. | |
88e1739c FW |
822 | @end ifset |
823 | @end itemize | |
824 | ||
7cd4527e AC |
825 | |
826 | @c ************************************************* | |
88e1739c | 827 | @node What You Should Know before Reading This Guide |
7cd4527e | 828 | @c ************************************************* |
88e1739c FW |
829 | @unnumberedsec What You Should Know before Reading This Guide |
830 | ||
831 | @cindex Ada 95 Language Reference Manual | |
832 | @noindent | |
833 | This user's guide assumes that you are familiar with Ada 95 language, as | |
7cd4527e | 834 | described in the International Standard ANSI/ISO/IEC-8652:1995, January |
88e1739c FW |
835 | 1995. |
836 | ||
837 | @node Related Information | |
838 | @unnumberedsec Related Information | |
839 | ||
840 | @noindent | |
841 | For further information about related tools, refer to the following | |
842 | documents: | |
843 | ||
844 | @itemize @bullet | |
845 | @item | |
846 | @cite{GNAT Reference Manual}, which contains all reference | |
847 | material for the GNAT implementation of Ada 95. | |
848 | ||
7cd4527e AC |
849 | @ifset unw |
850 | @item | |
851 | @cite{Using the GNAT Programming System}, which describes the GPS | |
852 | integrated development environment. | |
853 | ||
854 | @item | |
855 | @cite{GNAT Programming System Tutorial}, which introduces the | |
856 | main GPS features through examples. | |
857 | @end ifset | |
858 | ||
88e1739c FW |
859 | @item |
860 | @cite{Ada 95 Language Reference Manual}, which contains all reference | |
861 | material for the Ada 95 programming language. | |
862 | ||
863 | @item | |
864 | @cite{Debugging with GDB} | |
865 | @ifset vms | |
866 | , located in the GNU:[DOCS] directory, | |
867 | @end ifset | |
868 | contains all details on the use of the GNU source-level debugger. | |
869 | ||
870 | @item | |
871 | @cite{GNU Emacs Manual} | |
872 | @ifset vms | |
873 | , located in the GNU:[DOCS] directory if the EMACS kit is installed, | |
874 | @end ifset | |
875 | contains full information on the extensible editor and programming | |
876 | environment Emacs. | |
877 | ||
878 | @end itemize | |
879 | ||
7cd4527e | 880 | @c ************** |
88e1739c FW |
881 | @node Conventions |
882 | @unnumberedsec Conventions | |
883 | @cindex Conventions | |
884 | @cindex Typographical conventions | |
885 | ||
886 | @noindent | |
887 | Following are examples of the typographical and graphic conventions used | |
888 | in this guide: | |
889 | ||
890 | @itemize @bullet | |
891 | @item | |
892 | @code{Functions}, @code{utility program names}, @code{standard names}, | |
893 | and @code{classes}. | |
894 | ||
895 | @item | |
896 | @samp{Option flags} | |
897 | ||
898 | @item | |
899 | @file{File Names}, @file{button names}, and @file{field names}. | |
900 | ||
901 | @item | |
902 | @var{Variables}. | |
903 | ||
904 | @item | |
905 | @emph{Emphasis}. | |
906 | ||
907 | @item | |
908 | [optional information or parameters] | |
909 | ||
910 | @item | |
911 | Examples are described by text | |
912 | @smallexample | |
913 | and then shown this way. | |
914 | @end smallexample | |
915 | @end itemize | |
916 | ||
917 | @noindent | |
918 | Commands that are entered by the user are preceded in this manual by the | |
7cd4527e | 919 | characters @w{``@code{$ }''} (dollar sign followed by space). If your system |
88e1739c FW |
920 | uses this sequence as a prompt, then the commands will appear exactly as |
921 | you see them in the manual. If your system uses some other prompt, then | |
922 | the command will appear with the @code{$} replaced by whatever prompt | |
923 | character you are using. | |
924 | ||
7cd4527e AC |
925 | @ifset unw |
926 | Full file names are shown with the ``@code{/}'' character | |
927 | as the directory separator; e.g., @file{parent-dir/subdir/myfile.adb}. | |
928 | If you are using GNAT on a Windows platform, please note that | |
929 | the ``@code{\}'' character should be used instead. | |
88e1739c FW |
930 | @end ifset |
931 | ||
7cd4527e AC |
932 | |
933 | ||
934 | @c **************************** | |
88e1739c FW |
935 | @node Getting Started with GNAT |
936 | @chapter Getting Started with GNAT | |
937 | ||
88e1739c FW |
938 | @noindent |
939 | This chapter describes some simple ways of using GNAT to build | |
940 | executable Ada programs. | |
7cd4527e AC |
941 | @ifset unw |
942 | @ref{Running GNAT}, through @ref{Using the gnatmake Utility}, | |
943 | show how to use the command line environment. | |
944 | @ref{Introduction to Glide and GVD}, provides a brief | |
945 | introduction to the visually-oriented IDE for GNAT. | |
946 | Supplementing Glide on some platforms is GPS, the | |
947 | GNAT Programming System, which offers a richer graphical | |
948 | ``look and feel'', enhanced configurability, support for | |
949 | development in other programming language, comprehensive | |
950 | browsing features, and many other capabilities. | |
951 | For information on GPS please refer to | |
952 | @cite{Using the GNAT Programming System}. | |
88e1739c FW |
953 | @end ifset |
954 | ||
955 | @menu | |
956 | * Running GNAT:: | |
88e1739c | 957 | * Running a Simple Ada Program:: |
88e1739c | 958 | * Running a Program with Multiple Units:: |
88e1739c FW |
959 | * Using the gnatmake Utility:: |
960 | @ifset vms | |
961 | * Editing with Emacs:: | |
962 | @end ifset | |
963 | @ifclear vms | |
7cd4527e | 964 | * Introduction to GPS:: |
88e1739c FW |
965 | * Introduction to Glide and GVD:: |
966 | @end ifclear | |
967 | @end menu | |
968 | ||
969 | @node Running GNAT | |
970 | @section Running GNAT | |
971 | ||
972 | @noindent | |
973 | Three steps are needed to create an executable file from an Ada source | |
974 | file: | |
975 | ||
976 | @enumerate | |
977 | @item | |
978 | The source file(s) must be compiled. | |
979 | @item | |
980 | The file(s) must be bound using the GNAT binder. | |
981 | @item | |
88e1739c | 982 | All appropriate object files must be linked to produce an executable. |
88e1739c FW |
983 | @end enumerate |
984 | ||
985 | @noindent | |
986 | All three steps are most commonly handled by using the @code{gnatmake} | |
987 | utility program that, given the name of the main program, automatically | |
988 | performs the necessary compilation, binding and linking steps. | |
989 | ||
7cd4527e | 990 | |
88e1739c FW |
991 | @node Running a Simple Ada Program |
992 | @section Running a Simple Ada Program | |
88e1739c FW |
993 | |
994 | @noindent | |
7cd4527e AC |
995 | Any text editor may be used to prepare an Ada program. |
996 | @ifclear vms | |
997 | If @code{Glide} is | |
998 | used, the optional Ada mode may be helpful in laying out the program. | |
999 | @end ifclear | |
1000 | The | |
88e1739c FW |
1001 | program text is a normal text file. We will suppose in our initial |
1002 | example that you have used your editor to prepare the following | |
1003 | standard format text file: | |
1004 | ||
7cd4527e | 1005 | @smallexample @c ada |
88e1739c | 1006 | @cartouche |
7cd4527e AC |
1007 | with Ada.Text_IO; use Ada.Text_IO; |
1008 | procedure Hello is | |
1009 | begin | |
88e1739c | 1010 | Put_Line ("Hello WORLD!"); |
7cd4527e | 1011 | end Hello; |
88e1739c | 1012 | @end cartouche |
88e1739c FW |
1013 | @end smallexample |
1014 | ||
1015 | @noindent | |
1016 | This file should be named @file{hello.adb}. | |
1017 | With the normal default file naming conventions, GNAT requires | |
1018 | that each file | |
1019 | contain a single compilation unit whose file name is the | |
1020 | unit name, | |
1021 | with periods replaced by hyphens; the | |
1022 | extension is @file{ads} for a | |
1023 | spec and @file{adb} for a body. | |
1024 | You can override this default file naming convention by use of the | |
1025 | special pragma @code{Source_File_Name} (@pxref{Using Other File Names}). | |
1026 | Alternatively, if you want to rename your files according to this default | |
1027 | convention, which is probably more convenient if you will be using GNAT | |
1028 | for all your compilations, then the @code{gnatchop} utility | |
1029 | can be used to generate correctly-named source files | |
1030 | (@pxref{Renaming Files Using gnatchop}). | |
1031 | ||
1032 | You can compile the program using the following command (@code{$} is used | |
1033 | as the command prompt in the examples in this document): | |
1034 | ||
88e1739c FW |
1035 | @smallexample |
1036 | $ gcc -c hello.adb | |
1037 | @end smallexample | |
88e1739c FW |
1038 | |
1039 | @noindent | |
1040 | @code{gcc} is the command used to run the compiler. This compiler is | |
1041 | capable of compiling programs in several languages, including Ada 95 and | |
1042 | C. It assumes that you have given it an Ada program if the file extension is | |
7cd4527e AC |
1043 | either @file{.ads} or @file{.adb}, and it will then call |
1044 | the GNAT compiler to compile the specified file. | |
88e1739c FW |
1045 | |
1046 | @ifclear vms | |
1047 | The @option{-c} switch is required. It tells @command{gcc} to only do a | |
1048 | compilation. (For C programs, @command{gcc} can also do linking, but this | |
1049 | capability is not used directly for Ada programs, so the @option{-c} | |
1050 | switch must always be present.) | |
1051 | @end ifclear | |
1052 | ||
1053 | This compile command generates a file | |
1054 | @file{hello.o}, which is the object | |
7cd4527e AC |
1055 | file corresponding to your Ada program. It also generates |
1056 | an ``Ada Library Information'' file @file{hello.ali}, | |
88e1739c FW |
1057 | which contains additional information used to check |
1058 | that an Ada program is consistent. | |
88e1739c | 1059 | To build an executable file, |
88e1739c FW |
1060 | use @code{gnatbind} to bind the program |
1061 | and @code{gnatlink} to link it. The | |
1062 | argument to both @code{gnatbind} and @code{gnatlink} is the name of the | |
7cd4527e | 1063 | @file{ALI} file, but the default extension of @file{.ali} can |
88e1739c FW |
1064 | be omitted. This means that in the most common case, the argument |
1065 | is simply the name of the main program: | |
1066 | ||
88e1739c FW |
1067 | @smallexample |
1068 | $ gnatbind hello | |
1069 | $ gnatlink hello | |
1070 | @end smallexample | |
88e1739c FW |
1071 | |
1072 | @noindent | |
1073 | A simpler method of carrying out these steps is to use | |
1074 | @command{gnatmake}, | |
1075 | a master program that invokes all the required | |
1076 | compilation, binding and linking tools in the correct order. In particular, | |
7cd4527e AC |
1077 | @command{gnatmake} automatically recompiles any sources that have been |
1078 | modified since they were last compiled, or sources that depend | |
1079 | on such modified sources, so that ``version skew'' is avoided. | |
88e1739c FW |
1080 | @cindex Version skew (avoided by @command{gnatmake}) |
1081 | ||
88e1739c FW |
1082 | @smallexample |
1083 | $ gnatmake hello.adb | |
1084 | @end smallexample | |
88e1739c | 1085 | |
88e1739c FW |
1086 | @noindent |
1087 | The result is an executable program called @file{hello}, which can be | |
1088 | run by entering: | |
1089 | ||
1090 | @c The following should be removed (BMB 2001-01-23) | |
1091 | @c @smallexample | |
1092 | @c $ ^./hello^$ RUN HELLO^ | |
1093 | @c @end smallexample | |
1094 | ||
1095 | @smallexample | |
1096 | $ hello | |
1097 | @end smallexample | |
1098 | ||
1099 | @noindent | |
7cd4527e AC |
1100 | assuming that the current directory is on the search path |
1101 | for executable programs. | |
88e1739c FW |
1102 | |
1103 | @noindent | |
1104 | and, if all has gone well, you will see | |
1105 | ||
1106 | @smallexample | |
1107 | Hello WORLD! | |
1108 | @end smallexample | |
1109 | ||
1110 | @noindent | |
1111 | appear in response to this command. | |
1112 | ||
88e1739c | 1113 | |
7cd4527e | 1114 | @c **************************************** |
88e1739c FW |
1115 | @node Running a Program with Multiple Units |
1116 | @section Running a Program with Multiple Units | |
1117 | ||
1118 | @noindent | |
1119 | Consider a slightly more complicated example that has three files: a | |
1120 | main program, and the spec and body of a package: | |
1121 | ||
7cd4527e | 1122 | @smallexample @c ada |
88e1739c FW |
1123 | @cartouche |
1124 | @group | |
7cd4527e AC |
1125 | package Greetings is |
1126 | procedure Hello; | |
1127 | procedure Goodbye; | |
1128 | end Greetings; | |
1129 | ||
1130 | with Ada.Text_IO; use Ada.Text_IO; | |
1131 | package body Greetings is | |
1132 | procedure Hello is | |
1133 | begin | |
88e1739c | 1134 | Put_Line ("Hello WORLD!"); |
7cd4527e | 1135 | end Hello; |
88e1739c | 1136 | |
7cd4527e AC |
1137 | procedure Goodbye is |
1138 | begin | |
88e1739c | 1139 | Put_Line ("Goodbye WORLD!"); |
7cd4527e AC |
1140 | end Goodbye; |
1141 | end Greetings; | |
88e1739c FW |
1142 | @end group |
1143 | ||
1144 | @group | |
7cd4527e AC |
1145 | with Greetings; |
1146 | procedure Gmain is | |
1147 | begin | |
88e1739c FW |
1148 | Greetings.Hello; |
1149 | Greetings.Goodbye; | |
7cd4527e | 1150 | end Gmain; |
88e1739c FW |
1151 | @end group |
1152 | @end cartouche | |
1153 | @end smallexample | |
1154 | ||
1155 | @noindent | |
1156 | Following the one-unit-per-file rule, place this program in the | |
1157 | following three separate files: | |
1158 | ||
1159 | @table @file | |
1160 | @item greetings.ads | |
1161 | spec of package @code{Greetings} | |
1162 | ||
1163 | @item greetings.adb | |
1164 | body of package @code{Greetings} | |
1165 | ||
1166 | @item gmain.adb | |
1167 | body of main program | |
1168 | @end table | |
1169 | ||
1170 | @noindent | |
1171 | To build an executable version of | |
1172 | this program, we could use four separate steps to compile, bind, and link | |
1173 | the program, as follows: | |
1174 | ||
88e1739c FW |
1175 | @smallexample |
1176 | $ gcc -c gmain.adb | |
1177 | $ gcc -c greetings.adb | |
1178 | $ gnatbind gmain | |
1179 | $ gnatlink gmain | |
1180 | @end smallexample | |
88e1739c FW |
1181 | |
1182 | @noindent | |
1183 | Note that there is no required order of compilation when using GNAT. | |
1184 | In particular it is perfectly fine to compile the main program first. | |
1185 | Also, it is not necessary to compile package specs in the case where | |
1186 | there is an accompanying body; you only need to compile the body. If you want | |
7cd4527e AC |
1187 | to submit these files to the compiler for semantic checking and not code |
1188 | generation, then use the | |
88e1739c FW |
1189 | @option{-gnatc} switch: |
1190 | ||
88e1739c | 1191 | @smallexample |
7cd4527e | 1192 | $ gcc -c greetings.ads -gnatc |
88e1739c | 1193 | @end smallexample |
88e1739c FW |
1194 | |
1195 | @noindent | |
1196 | Although the compilation can be done in separate steps as in the | |
1197 | above example, in practice it is almost always more convenient | |
1198 | to use the @code{gnatmake} tool. All you need to know in this case | |
1199 | is the name of the main program's source file. The effect of the above four | |
1200 | commands can be achieved with a single one: | |
1201 | ||
88e1739c FW |
1202 | @smallexample |
1203 | $ gnatmake gmain.adb | |
1204 | @end smallexample | |
88e1739c FW |
1205 | |
1206 | @noindent | |
1207 | In the next section we discuss the advantages of using @code{gnatmake} in | |
1208 | more detail. | |
1209 | ||
7cd4527e | 1210 | @c ***************************** |
88e1739c FW |
1211 | @node Using the gnatmake Utility |
1212 | @section Using the @command{gnatmake} Utility | |
1213 | ||
1214 | @noindent | |
1215 | If you work on a program by compiling single components at a time using | |
1216 | @code{gcc}, you typically keep track of the units you modify. In order to | |
1217 | build a consistent system, you compile not only these units, but also any | |
1218 | units that depend on the units you have modified. | |
1219 | For example, in the preceding case, | |
1220 | if you edit @file{gmain.adb}, you only need to recompile that file. But if | |
1221 | you edit @file{greetings.ads}, you must recompile both | |
1222 | @file{greetings.adb} and @file{gmain.adb}, because both files contain | |
1223 | units that depend on @file{greetings.ads}. | |
1224 | ||
1225 | @code{gnatbind} will warn you if you forget one of these compilation | |
1226 | steps, so that it is impossible to generate an inconsistent program as a | |
1227 | result of forgetting to do a compilation. Nevertheless it is tedious and | |
1228 | error-prone to keep track of dependencies among units. | |
1229 | One approach to handle the dependency-bookkeeping is to use a | |
1230 | makefile. However, makefiles present maintenance problems of their own: | |
1231 | if the dependencies change as you change the program, you must make | |
1232 | sure that the makefile is kept up-to-date manually, which is also an | |
1233 | error-prone process. | |
1234 | ||
1235 | The @code{gnatmake} utility takes care of these details automatically. | |
1236 | Invoke it using either one of the following forms: | |
1237 | ||
88e1739c FW |
1238 | @smallexample |
1239 | $ gnatmake gmain.adb | |
1240 | $ gnatmake ^gmain^GMAIN^ | |
1241 | @end smallexample | |
88e1739c FW |
1242 | |
1243 | @noindent | |
1244 | The argument is the name of the file containing the main program; | |
1245 | you may omit the extension. @code{gnatmake} | |
1246 | examines the environment, automatically recompiles any files that need | |
1247 | recompiling, and binds and links the resulting set of object files, | |
1248 | generating the executable file, @file{^gmain^GMAIN.EXE^}. | |
1249 | In a large program, it | |
1250 | can be extremely helpful to use @code{gnatmake}, because working out by hand | |
1251 | what needs to be recompiled can be difficult. | |
1252 | ||
1253 | Note that @code{gnatmake} | |
1254 | takes into account all the Ada 95 rules that | |
1255 | establish dependencies among units. These include dependencies that result | |
1256 | from inlining subprogram bodies, and from | |
1257 | generic instantiation. Unlike some other | |
1258 | Ada make tools, @code{gnatmake} does not rely on the dependencies that were | |
1259 | found by the compiler on a previous compilation, which may possibly | |
1260 | be wrong when sources change. @code{gnatmake} determines the exact set of | |
1261 | dependencies from scratch each time it is run. | |
1262 | ||
1263 | @ifset vms | |
1264 | @node Editing with Emacs | |
1265 | @section Editing with Emacs | |
1266 | @cindex Emacs | |
1267 | ||
1268 | @noindent | |
1269 | Emacs is an extensible self-documenting text editor that is available in a | |
1270 | separate VMSINSTAL kit. | |
1271 | ||
7cd4527e | 1272 | Invoke Emacs by typing @kbd{Emacs} at the command prompt. To get started, |
88e1739c | 1273 | click on the Emacs Help menu and run the Emacs Tutorial. |
7cd4527e AC |
1274 | In a character cell terminal, Emacs help is invoked with @kbd{Ctrl-h} (also |
1275 | written as @kbd{C-h}), and the tutorial by @kbd{C-h t}. | |
88e1739c FW |
1276 | |
1277 | Documentation on Emacs and other tools is available in Emacs under the | |
7cd4527e AC |
1278 | pull-down menu button: @code{Help - Info}. After selecting @code{Info}, |
1279 | use the middle mouse button to select a topic (e.g. Emacs). | |
88e1739c | 1280 | |
7cd4527e AC |
1281 | In a character cell terminal, do @kbd{C-h i} to invoke info, and then @kbd{m} |
1282 | (stands for menu) followed by the menu item desired, as in @kbd{m Emacs}, to | |
1283 | get to the Emacs manual. | |
1284 | Help on Emacs is also available by typing @kbd{HELP EMACS} at the DCL command | |
88e1739c FW |
1285 | prompt. |
1286 | ||
1287 | The tutorial is highly recommended in order to learn the intricacies of Emacs, | |
1288 | which is sufficiently extensible to provide for a complete programming | |
1289 | environment and shell for the sophisticated user. | |
1290 | @end ifset | |
1291 | ||
1292 | @ifclear vms | |
7cd4527e AC |
1293 | @node Introduction to GPS |
1294 | @section Introduction to GPS | |
1295 | @cindex GPS (GNAT Programming System) | |
1296 | @cindex GNAT Programming System (GPS) | |
1297 | @noindent | |
1298 | Although the command line interface (@command{gnatmake}, etc.) alone | |
1299 | is sufficient, a graphical Interactive Development | |
1300 | Environment can make it easier for you to compose, navigate, and debug | |
1301 | programs. This section describes the main features of GPS | |
1302 | (``GNAT Programming System''), the GNAT graphical IDE. | |
1303 | You will see how to use GPS to build and debug an executable, and | |
1304 | you will also learn some of the basics of the GNAT ``project'' facility. | |
1305 | ||
1306 | GPS enables you to do much more than is presented here; | |
1307 | e.g., you can produce a call graph, interface to a third-party | |
1308 | Version Control System, and inspect the generated assembly language | |
1309 | for a program. | |
1310 | Indeed, GPS also supports languages other than Ada. | |
1311 | Such additional information, and an explanation of all of the GPS menu | |
1312 | items. may be found in the on-line help, which includes | |
1313 | a user's guide and a tutorial (these are also accessible from the GNAT | |
1314 | startup menu). | |
1315 | ||
1316 | @menu | |
1317 | * Building a New Program with GPS:: | |
1318 | * Simple Debugging with GPS:: | |
1319 | @end menu | |
1320 | ||
1321 | ||
1322 | @node Building a New Program with GPS | |
1323 | @subsection Building a New Program with GPS | |
1324 | @noindent | |
1325 | GPS invokes the GNAT compilation tools using information | |
1326 | contained in a @emph{project} (also known as a @emph{project file}): | |
1327 | a collection of properties such | |
1328 | as source directories, identities of main subprograms, tool switches, etc., | |
1329 | and their associated values. | |
1330 | (See @ref{GNAT Project Manager}, for details.) | |
1331 | In order to run GPS, you will need to either create a new project | |
1332 | or else open an existing one. | |
1333 | ||
1334 | This section will explain how you can use GPS to create a project, | |
1335 | to associate Ada source files with a project, and to build and run | |
1336 | programs. | |
1337 | ||
1338 | @enumerate | |
1339 | @item @emph{Creating a project} | |
1340 | ||
1341 | Invoke GPS, either from the command line or the platform's IDE. | |
1342 | After it starts, GPS will display a ``Welcome'' screen with three | |
1343 | radio buttons: | |
1344 | ||
1345 | @itemize @bullet | |
1346 | @item | |
1347 | @code{Start with default project in directory} | |
1348 | ||
1349 | @item | |
1350 | @code{Create new project with wizard} | |
1351 | ||
1352 | @item | |
1353 | @code{Open existing project} | |
1354 | @end itemize | |
1355 | ||
1356 | @noindent | |
1357 | Select @code{Create new project with wizard} and press @code{OK}. | |
1358 | A new window will appear. In the text box labeled with | |
1359 | @code{Enter the name of the project to create}, type @file{sample} | |
1360 | as the project name. | |
1361 | In the next box, browse to choose the directory in which you | |
1362 | would like to create the project file. | |
1363 | After selecting an appropriate directory, press @code{Forward}. | |
1364 | ||
1365 | A window will appear with the title | |
1366 | @code{Version Control System Configuration}. | |
1367 | Simply press @code{Forward}. | |
1368 | ||
1369 | A window will appear with the title | |
1370 | @code{Please select the source directories for this project}. | |
1371 | The directory that you specified for the project file will be selected | |
1372 | by default as the one to use for sources; simply press @code{Forward}. | |
1373 | ||
1374 | A window will appear with the title | |
1375 | @code{Please select the build directory for this project}. | |
1376 | The directory that you specified for the project file will be selected | |
1377 | by default for object files and executables; | |
1378 | simply press @code{Forward}. | |
1379 | ||
1380 | A window will appear with the title | |
1381 | @code{Please select the main units for this project}. | |
1382 | You will supply this information later, after creating the source file. | |
1383 | Simply press @code{Forward} for now. | |
1384 | ||
1385 | A window will appear with the title | |
1386 | @code{Please select the switches to build the project}. | |
1387 | Press @code{Apply}. This will create a project file named | |
1388 | @file{sample.prj} in the directory that you had specified. | |
1389 | ||
1390 | @item @emph{Creating and saving the source file} | |
1391 | ||
1392 | After you create the new project, a GPS window will appear, which is | |
1393 | partitioned into two main sections: | |
1394 | ||
1395 | @itemize @bullet | |
1396 | @item | |
1397 | A @emph{Workspace area}, initially greyed out, which you will use for | |
1398 | creating and editing source files | |
1399 | ||
1400 | @item | |
1401 | Directly below, a @emph{Messages area}, which initially displays a | |
1402 | ``Welcome'' message. | |
1403 | (If the Messages area is not visible, drag its border upward to expand it.) | |
1404 | @end itemize | |
1405 | ||
1406 | @noindent | |
1407 | Select @code{File} on the menu bar, and then the @code{New} command. | |
1408 | The Workspace area will become white, and you can now | |
1409 | enter the source program explicitly. | |
1410 | Type the following text | |
1411 | ||
1412 | @smallexample @c ada | |
1413 | @group | |
1414 | with Ada.Text_IO; use Ada.Text_IO; | |
1415 | procedure Hello is | |
1416 | begin | |
1417 | Put_Line("Hello from GPS!"); | |
1418 | end Hello; | |
1419 | @end group | |
1420 | @end smallexample | |
1421 | ||
1422 | @noindent | |
1423 | Select @code{File}, then @code{Save As}, and enter the source file name | |
1424 | @file{hello.adb}. | |
1425 | The file will be saved in the same directory you specified as the | |
1426 | location of the default project file. | |
1427 | ||
1428 | ||
1429 | @item @emph{Updating the project file} | |
1430 | ||
1431 | You need to add the new source file to the project. | |
1432 | To do this, select | |
1433 | the @code{Project} menu and then @code{Edit project properties}. | |
1434 | Click the @code{Main files} tab on the left, and then the | |
1435 | @code{Add} button. | |
1436 | Choose @file{hello.adb} from the list, and press @code{Open}. | |
1437 | The project settings window will reflect this action. | |
1438 | Click @code{OK}. | |
1439 | ||
1440 | @item @emph{Building and running the program} | |
1441 | ||
1442 | In the main GPS window, now choose the @code{Build} menu, then @code{Make}, | |
1443 | and select @file{hello.adb}. | |
1444 | The Messages window will display the resulting invocations of @command{gcc}, | |
1445 | @command{gnatbind}, and @command{gnatlink} | |
1446 | (reflecting the default switch settings from the | |
1447 | project file that you created) and then a ``successful compilation/build'' | |
1448 | message. | |
1449 | ||
1450 | To run the program, choose the @code{Build} menu, then @code{Run}, and | |
1451 | select @command{hello}. | |
1452 | An @emph{Arguments Selection} window will appear. | |
1453 | There are no command line arguments, so just click @code{OK}. | |
1454 | ||
1455 | The Messages window will now display the program's output (the string | |
1456 | @code{Hello from GPS}), and at the bottom of the GPS window a status | |
1457 | update is displayed (@code{Run: hello}). | |
1458 | Close the GPS window (or select @code{File}, then @code{Exit}) to | |
1459 | terminate this GPS session. | |
1460 | @end enumerate | |
1461 | ||
1462 | ||
1463 | ||
1464 | @node Simple Debugging with GPS | |
1465 | @subsection Simple Debugging with GPS | |
1466 | @noindent | |
1467 | This section illustrates basic debugging techniques (setting breakpoints, | |
1468 | examining/modifying variables, single stepping). | |
1469 | ||
1470 | @enumerate | |
1471 | @item @emph{Opening a project} | |
1472 | ||
1473 | Start GPS and select @code{Open existing project}; browse to | |
1474 | specify the project file @file{sample.prj} that you had created in the | |
1475 | earlier example. | |
1476 | ||
1477 | @item @emph{Creating a source file} | |
1478 | ||
1479 | Select @code{File}, then @code{New}, and type in the following program: | |
1480 | ||
1481 | @smallexample @c ada | |
1482 | @group | |
1483 | with Ada.Text_IO; use Ada.Text_IO; | |
1484 | procedure Example is | |
1485 | Line : String (1..80); | |
1486 | N : Natural; | |
1487 | begin | |
1488 | Put_Line("Type a line of text at each prompt; an empty line to exit"); | |
1489 | loop | |
1490 | Put(": "); | |
1491 | Get_Line (Line, N); | |
1492 | Put_Line (Line (1..N) ); | |
1493 | exit when N=0; | |
1494 | end loop; | |
1495 | end Example; | |
1496 | @end group | |
1497 | @end smallexample | |
1498 | ||
1499 | @noindent | |
1500 | Select @code{File}, then @code{Save as}, and enter the file name | |
1501 | @file{example.adb}. | |
1502 | ||
1503 | @item @emph{Updating the project file} | |
1504 | ||
1505 | Add @code{Example} as a new main unit for the project: | |
1506 | @enumerate a | |
1507 | @item | |
1508 | Select @code{Project}, then @code{Edit Project Properties}. | |
1509 | ||
1510 | @item | |
1511 | Select the @code{Main files} tab, click @code{Add}, then | |
1512 | select the file @file{example.adb} from the list, and | |
1513 | click @code{Open}. | |
1514 | You will see the file name appear in the list of main units | |
1515 | ||
1516 | @item | |
1517 | Click @code{OK} | |
1518 | @end enumerate | |
1519 | ||
1520 | @item @emph{Building/running the executable} | |
1521 | ||
1522 | To build the executable | |
1523 | select @code{Build}, then @code{Make}, and then choose @file{example.adb}. | |
1524 | ||
1525 | Run the program to see its effect (in the Messages area). | |
1526 | Each line that you enter is displayed; an empty line will | |
1527 | cause the loop to exit and the program to terminate. | |
1528 | ||
1529 | @item @emph{Debugging the program} | |
1530 | ||
1531 | Note that the @option{-g} switches to @command{gcc} and @command{gnatlink}, | |
1532 | which are required for debugging, are on by default when you create | |
1533 | a new project. | |
1534 | Thus unless you intentionally remove these settings, you will be able | |
1535 | to debug any program that you develop using GPS. | |
1536 | ||
1537 | @enumerate a | |
1538 | @item @emph{Initializing} | |
1539 | ||
1540 | Select @code{Debug}, then @code{Initialize}, then @file{example} | |
1541 | ||
1542 | @item @emph{Setting a breakpoint} | |
1543 | ||
1544 | After performing the initialization step, you will observe a small | |
1545 | icon to the right of each line number. | |
1546 | This serves as a toggle for breakpoints; clicking the icon will | |
1547 | set a breakpoint at the corresponding line (the icon will change to | |
1548 | a red circle with an ``x''), and clicking it again | |
1549 | will remove the breakpoint / reset the icon. | |
1550 | ||
1551 | For purposes of this example, set a breakpoint at line 10 (the | |
1552 | statement @code{Put_Line@ (Line@ (1..N));} | |
1553 | ||
1554 | @item @emph{Starting program execution} | |
1555 | ||
1556 | Select @code{Debug}, then @code{Run}. When the | |
1557 | @code{Program Arguments} window appears, click @code{OK}. | |
1558 | A console window will appear; enter some line of text, | |
1559 | e.g. @code{abcde}, at the prompt. | |
1560 | The program will pause execution when it gets to the | |
1561 | breakpoint, and the corresponding line is highlighted. | |
1562 | ||
1563 | @item @emph{Examining a variable} | |
1564 | ||
1565 | Move the mouse over one of the occurrences of the variable @code{N}. | |
1566 | You will see the value (5) displayed, in ``tool tip'' fashion. | |
1567 | Right click on @code{N}, select @code{Debug}, then select @code{Display N}. | |
1568 | You will see information about @code{N} appear in the @code{Debugger Data} | |
1569 | pane, showing the value as 5. | |
1570 | ||
1571 | ||
1572 | @item @emph{Assigning a new value to a variable} | |
1573 | ||
1574 | Right click on the @code{N} in the @code{Debugger Data} pane, and | |
1575 | select @code{Set value of N}. | |
1576 | When the input window appears, enter the value @code{4} and click | |
1577 | @code{OK}. | |
1578 | This value does not automatically appear in the @code{Debugger Data} | |
1579 | pane; to see it, right click again on the @code{N} in the | |
1580 | @code{Debugger Data} pane and select @code{Update value}. | |
1581 | The new value, 4, will appear in red. | |
1582 | ||
1583 | @item @emph{Single stepping} | |
1584 | ||
1585 | Select @code{Debug}, then @code{Next}. | |
1586 | This will cause the next statement to be executed, in this case the | |
1587 | call of @code{Put_Line} with the string slice. | |
1588 | Notice in the console window that the displayed string is simply | |
1589 | @code{abcd} and not @code{abcde} which you had entered. | |
1590 | This is because the upper bound of the slice is now 4 rather than 5. | |
1591 | ||
1592 | @item @emph{Removing a breakpoint} | |
1593 | ||
1594 | Toggle the breakpoint icon at line 10. | |
1595 | ||
1596 | @item @emph{Resuming execution from a breakpoint} | |
1597 | ||
1598 | Select @code{Debug}, then @code{Continue}. | |
1599 | The program will reach the next iteration of the loop, and | |
1600 | wait for input after displaying the prompt. | |
1601 | This time, just hit the @kbd{Enter} key. | |
1602 | The value of @code{N} will be 0, and the program will terminate. | |
1603 | The console window will disappear. | |
1604 | @end enumerate | |
1605 | @end enumerate | |
1606 | ||
1607 | ||
88e1739c FW |
1608 | @node Introduction to Glide and GVD |
1609 | @section Introduction to Glide and GVD | |
1610 | @cindex Glide | |
1611 | @cindex GVD | |
1612 | @noindent | |
7cd4527e AC |
1613 | This section describes the main features of Glide, |
1614 | a GNAT graphical IDE, and also shows how to use the basic commands in GVD, | |
1615 | the GNU Visual Debugger. | |
1616 | These tools may be present in addition to, or in place of, GPS on some | |
1617 | platforms. | |
1618 | Additional information on Glide and GVD may be found | |
1619 | in the on-line help for these tools. | |
88e1739c FW |
1620 | |
1621 | @menu | |
1622 | * Building a New Program with Glide:: | |
1623 | * Simple Debugging with GVD:: | |
1624 | * Other Glide Features:: | |
1625 | @end menu | |
1626 | ||
1627 | @node Building a New Program with Glide | |
1628 | @subsection Building a New Program with Glide | |
1629 | @noindent | |
7cd4527e AC |
1630 | The simplest way to invoke Glide is to enter @command{glide} |
1631 | at the command prompt. It will generally be useful to issue this | |
1632 | as a background command, thus allowing you to continue using | |
1633 | your command window for other purposes while Glide is running: | |
88e1739c FW |
1634 | |
1635 | @smallexample | |
1636 | $ glide& | |
1637 | @end smallexample | |
1638 | ||
1639 | @noindent | |
7cd4527e AC |
1640 | Glide will start up with an initial screen displaying the top-level menu items |
1641 | as well as some other information. The menu selections are as follows | |
88e1739c FW |
1642 | @itemize @bullet |
1643 | @item @code{Buffers} | |
1644 | @item @code{Files} | |
1645 | @item @code{Tools} | |
1646 | @item @code{Edit} | |
1647 | @item @code{Search} | |
1648 | @item @code{Mule} | |
1649 | @item @code{Glide} | |
1650 | @item @code{Help} | |
1651 | @end itemize | |
1652 | ||
1653 | @noindent | |
7cd4527e AC |
1654 | For this introductory example, you will need to create a new Ada source file. |
1655 | First, select the @code{Files} menu. This will pop open a menu with around | |
1656 | a dozen or so items. To create a file, select the @code{Open file...} choice. | |
1657 | Depending on the platform, you may see a pop-up window where you can browse | |
1658 | to an appropriate directory and then enter the file name, or else simply | |
1659 | see a line at the bottom of the Glide window where you can likewise enter | |
1660 | the file name. Note that in Glide, when you attempt to open a non-existent | |
1661 | file, the effect is to create a file with that name. For this example enter | |
1662 | @file{hello.adb} as the name of the file. | |
88e1739c | 1663 | |
7cd4527e AC |
1664 | A new buffer will now appear, occupying the entire Glide window, |
1665 | with the file name at the top. The menu selections are slightly different | |
1666 | from the ones you saw on the opening screen; there is an @code{Entities} item, | |
1667 | and in place of @code{Glide} there is now an @code{Ada} item. Glide uses | |
1668 | the file extension to identify the source language, so @file{adb} indicates | |
1669 | an Ada source file. | |
88e1739c | 1670 | |
7cd4527e AC |
1671 | You will enter some of the source program lines explicitly, |
1672 | and use the syntax-oriented template mechanism to enter other lines. | |
1673 | First, type the following text: | |
88e1739c FW |
1674 | @smallexample |
1675 | with Ada.Text_IO; use Ada.Text_IO; | |
1676 | procedure Hello is | |
1677 | begin | |
1678 | @end smallexample | |
1679 | ||
1680 | @noindent | |
7cd4527e AC |
1681 | Observe that Glide uses different colors to distinguish reserved words from |
1682 | identifiers. Also, after the @code{procedure Hello is} line, the cursor is | |
1683 | automatically indented in anticipation of declarations. When you enter | |
1684 | @code{begin}, Glide recognizes that there are no declarations and thus places | |
1685 | @code{begin} flush left. But after the @code{begin} line the cursor is again | |
1686 | indented, where the statement(s) will be placed. | |
1687 | ||
1688 | The main part of the program will be a @code{for} loop. Instead of entering | |
1689 | the text explicitly, however, use a statement template. Select the @code{Ada} | |
1690 | item on the top menu bar, move the mouse to the @code{Statements} item, | |
1691 | and you will see a large selection of alternatives. Choose @code{for loop}. | |
1692 | You will be prompted (at the bottom of the buffer) for a loop name; | |
1693 | simply press the @key{Enter} key since a loop name is not needed. | |
1694 | You should see the beginning of a @code{for} loop appear in the source | |
1695 | program window. You will now be prompted for the name of the loop variable; | |
1696 | enter a line with the identifier @code{ind} (lower case). Note that, | |
1697 | by default, Glide capitalizes the name (you can override such behavior | |
1698 | if you wish, although this is outside the scope of this introduction). | |
1699 | Next, Glide prompts you for the loop range; enter a line containing | |
1700 | @code{1..5} and you will see this also appear in the source program, | |
1701 | together with the remaining elements of the @code{for} loop syntax. | |
1702 | ||
1703 | Next enter the statement (with an intentional error, a missing semicolon) | |
1704 | that will form the body of the loop: | |
88e1739c FW |
1705 | @smallexample |
1706 | Put_Line("Hello, World" & Integer'Image(I)) | |
1707 | @end smallexample | |
1708 | ||
1709 | @noindent | |
7cd4527e AC |
1710 | Finally, type @code{end Hello;} as the last line in the program. |
1711 | Now save the file: choose the @code{File} menu item, and then the | |
1712 | @code{Save buffer} selection. You will see a message at the bottom | |
1713 | of the buffer confirming that the file has been saved. | |
88e1739c | 1714 | |
7cd4527e AC |
1715 | You are now ready to attempt to build the program. Select the @code{Ada} |
1716 | item from the top menu bar. Although we could choose simply to compile | |
1717 | the file, we will instead attempt to do a build (which invokes | |
1718 | @command{gnatmake}) since, if the compile is successful, we want to build | |
1719 | an executable. Thus select @code{Ada build}. This will fail because of the | |
1720 | compilation error, and you will notice that the Glide window has been split: | |
1721 | the top window contains the source file, and the bottom window contains the | |
1722 | output from the GNAT tools. Glide allows you to navigate from a compilation | |
1723 | error to the source file position corresponding to the error: click the | |
1724 | middle mouse button (or simultaneously press the left and right buttons, | |
1725 | on a two-button mouse) on the diagnostic line in the tool window. The | |
1726 | focus will shift to the source window, and the cursor will be positioned | |
1727 | on the character at which the error was detected. | |
88e1739c | 1728 | |
7cd4527e AC |
1729 | Correct the error: type in a semicolon to terminate the statement. |
1730 | Although you can again save the file explicitly, you can also simply invoke | |
1731 | @code{Ada} @result{} @code{Build} and you will be prompted to save the file. | |
1732 | This time the build will succeed; the tool output window shows you the | |
1733 | options that are supplied by default. The GNAT tools' output (e.g. | |
1734 | object and ALI files, executable) will go in the directory from which | |
1735 | Glide was launched. | |
88e1739c | 1736 | |
7cd4527e AC |
1737 | To execute the program, choose @code{Ada} and then @code{Run}. |
1738 | You should see the program's output displayed in the bottom window: | |
88e1739c FW |
1739 | |
1740 | @smallexample | |
1741 | Hello, world 1 | |
1742 | Hello, world 2 | |
1743 | Hello, world 3 | |
1744 | Hello, world 4 | |
1745 | Hello, world 5 | |
1746 | @end smallexample | |
1747 | ||
1748 | @node Simple Debugging with GVD | |
1749 | @subsection Simple Debugging with GVD | |
1750 | ||
1751 | @noindent | |
7cd4527e AC |
1752 | This section describes how to set breakpoints, examine/modify variables, |
1753 | and step through execution. | |
88e1739c | 1754 | |
7cd4527e AC |
1755 | In order to enable debugging, you need to pass the @option{-g} switch |
1756 | to both the compiler and to @command{gnatlink}. If you are using | |
1757 | the command line, passing @option{-g} to @command{gnatmake} will have | |
1758 | this effect. You can then launch GVD, e.g. on the @code{hello} program, | |
1759 | by issuing the command: | |
88e1739c FW |
1760 | |
1761 | @smallexample | |
1762 | $ gvd hello | |
1763 | @end smallexample | |
1764 | ||
1765 | @noindent | |
7cd4527e AC |
1766 | If you are using Glide, then @option{-g} is passed to the relevant tools |
1767 | by default when you do a build. Start the debugger by selecting the | |
1768 | @code{Ada} menu item, and then @code{Debug}. | |
1769 | ||
1770 | GVD comes up in a multi-part window. One pane shows the names of files | |
1771 | comprising your executable; another pane shows the source code of the current | |
1772 | unit (initially your main subprogram), another pane shows the debugger output | |
1773 | and user interactions, and the fourth pane (the data canvas at the top | |
1774 | of the window) displays data objects that you have selected. | |
1775 | ||
1776 | To the left of the source file pane, you will notice green dots adjacent | |
1777 | to some lines. These are lines for which object code exists and where | |
1778 | breakpoints can thus be set. You set/reset a breakpoint by clicking | |
1779 | the green dot. When a breakpoint is set, the dot is replaced by an @code{X} | |
1780 | in a red circle. Clicking the circle toggles the breakpoint off, | |
1781 | and the red circle is replaced by the green dot. | |
1782 | ||
1783 | For this example, set a breakpoint at the statement where @code{Put_Line} | |
1784 | is invoked. | |
1785 | ||
1786 | Start program execution by selecting the @code{Run} button on the top menu bar. | |
1787 | (The @code{Start} button will also start your program, but it will | |
1788 | cause program execution to break at the entry to your main subprogram.) | |
1789 | Evidence of reaching the breakpoint will appear: the source file line will be | |
1790 | highlighted, and the debugger interactions pane will display | |
1791 | a relevant message. | |
1792 | ||
1793 | You can examine the values of variables in several ways. Move the mouse | |
1794 | over an occurrence of @code{Ind} in the @code{for} loop, and you will see | |
1795 | the value (now @code{1}) displayed. Alternatively, right-click on @code{Ind} | |
1796 | and select @code{Display Ind}; a box showing the variable's name and value | |
1797 | will appear in the data canvas. | |
1798 | ||
1799 | Although a loop index is a constant with respect to Ada semantics, | |
1800 | you can change its value in the debugger. Right-click in the box | |
1801 | for @code{Ind}, and select the @code{Set Value of Ind} item. | |
1802 | Enter @code{2} as the new value, and press @command{OK}. | |
1803 | The box for @code{Ind} shows the update. | |
1804 | ||
1805 | Press the @code{Step} button on the top menu bar; this will step through | |
1806 | one line of program text (the invocation of @code{Put_Line}), and you can | |
1807 | observe the effect of having modified @code{Ind} since the value displayed | |
1808 | is @code{2}. | |
1809 | ||
1810 | Remove the breakpoint, and resume execution by selecting the @code{Cont} | |
1811 | button. You will see the remaining output lines displayed in the debugger | |
1812 | interaction window, along with a message confirming normal program | |
1813 | termination. | |
88e1739c FW |
1814 | |
1815 | @node Other Glide Features | |
1816 | @subsection Other Glide Features | |
1817 | ||
1818 | @noindent | |
7cd4527e AC |
1819 | You may have observed that some of the menu selections contain abbreviations; |
1820 | e.g., @code{(C-x C-f)} for @code{Open file...} in the @code{Files} menu. | |
1821 | These are @emph{shortcut keys} that you can use instead of selecting | |
1822 | menu items. The @key{C} stands for @key{Ctrl}; thus @code{(C-x C-f)} means | |
1823 | @key{Ctrl-x} followed by @key{Ctrl-f}, and this sequence can be used instead | |
1824 | of selecting @code{Files} and then @code{Open file...}. | |
88e1739c FW |
1825 | |
1826 | To abort a Glide command, type @key{Ctrl-g}. | |
1827 | ||
7cd4527e AC |
1828 | If you want Glide to start with an existing source file, you can either |
1829 | launch Glide as above and then open the file via @code{Files} @result{} | |
1830 | @code{Open file...}, or else simply pass the name of the source file | |
1831 | on the command line: | |
88e1739c FW |
1832 | |
1833 | @smallexample | |
1834 | $ glide hello.adb& | |
1835 | @end smallexample | |
1836 | ||
1837 | @noindent | |
7cd4527e AC |
1838 | While you are using Glide, a number of @emph{buffers} exist. |
1839 | You create some explicitly; e.g., when you open/create a file. | |
1840 | Others arise as an effect of the commands that you issue; e.g., the buffer | |
1841 | containing the output of the tools invoked during a build. If a buffer | |
1842 | is hidden, you can bring it into a visible window by first opening | |
1843 | the @code{Buffers} menu and then selecting the desired entry. | |
88e1739c | 1844 | |
7cd4527e AC |
1845 | If a buffer occupies only part of the Glide screen and you want to expand it |
1846 | to fill the entire screen, then click in the buffer and then select | |
1847 | @code{Files} @result{} @code{One Window}. | |
88e1739c | 1848 | |
7cd4527e AC |
1849 | If a window is occupied by one buffer and you want to split the window |
1850 | to bring up a second buffer, perform the following steps: | |
88e1739c | 1851 | @itemize @bullet |
7cd4527e AC |
1852 | @item Select @code{Files} @result{} @code{Split Window}; |
1853 | this will produce two windows each of which holds the original buffer | |
1854 | (these are not copies, but rather different views of the same buffer contents) | |
1855 | ||
1856 | @item With the focus in one of the windows, | |
1857 | select the desired buffer from the @code{Buffers} menu | |
88e1739c FW |
1858 | @end itemize |
1859 | ||
1860 | @noindent | |
1861 | To exit from Glide, choose @code{Files} @result{} @code{Exit}. | |
1862 | @end ifclear | |
1863 | ||
1864 | @node The GNAT Compilation Model | |
1865 | @chapter The GNAT Compilation Model | |
1866 | @cindex GNAT compilation model | |
1867 | @cindex Compilation model | |
1868 | ||
1869 | @menu | |
1870 | * Source Representation:: | |
1871 | * Foreign Language Representation:: | |
1872 | * File Naming Rules:: | |
1873 | * Using Other File Names:: | |
1874 | * Alternative File Naming Schemes:: | |
1875 | * Generating Object Files:: | |
1876 | * Source Dependencies:: | |
1877 | * The Ada Library Information Files:: | |
1878 | * Binding an Ada Program:: | |
1879 | * Mixed Language Programming:: | |
1880 | * Building Mixed Ada & C++ Programs:: | |
1881 | * Comparison between GNAT and C/C++ Compilation Models:: | |
1882 | * Comparison between GNAT and Conventional Ada Library Models:: | |
7cd4527e AC |
1883 | @ifset vms |
1884 | * Placement of temporary files:: | |
1885 | @end ifset | |
88e1739c FW |
1886 | @end menu |
1887 | ||
1888 | @noindent | |
1889 | This chapter describes the compilation model used by GNAT. Although | |
1890 | similar to that used by other languages, such as C and C++, this model | |
1891 | is substantially different from the traditional Ada compilation models, | |
1892 | which are based on a library. The model is initially described without | |
1893 | reference to the library-based model. If you have not previously used an | |
1894 | Ada compiler, you need only read the first part of this chapter. The | |
1895 | last section describes and discusses the differences between the GNAT | |
1896 | model and the traditional Ada compiler models. If you have used other | |
1897 | Ada compilers, this section will help you to understand those | |
1898 | differences, and the advantages of the GNAT model. | |
1899 | ||
1900 | @node Source Representation | |
1901 | @section Source Representation | |
1902 | @cindex Latin-1 | |
1903 | ||
1904 | @noindent | |
1905 | Ada source programs are represented in standard text files, using | |
1906 | Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar | |
1907 | 7-bit ASCII set, plus additional characters used for | |
1908 | representing foreign languages (@pxref{Foreign Language Representation} | |
1909 | for support of non-USA character sets). The format effector characters | |
1910 | are represented using their standard ASCII encodings, as follows: | |
1911 | ||
1912 | @table @code | |
1913 | @item VT | |
1914 | @findex VT | |
1915 | Vertical tab, @code{16#0B#} | |
1916 | ||
1917 | @item HT | |
1918 | @findex HT | |
1919 | Horizontal tab, @code{16#09#} | |
1920 | ||
1921 | @item CR | |
1922 | @findex CR | |
1923 | Carriage return, @code{16#0D#} | |
1924 | ||
1925 | @item LF | |
1926 | @findex LF | |
1927 | Line feed, @code{16#0A#} | |
1928 | ||
1929 | @item FF | |
1930 | @findex FF | |
1931 | Form feed, @code{16#0C#} | |
1932 | @end table | |
1933 | ||
1934 | @noindent | |
1935 | Source files are in standard text file format. In addition, GNAT will | |
1936 | recognize a wide variety of stream formats, in which the end of physical | |
1937 | physical lines is marked by any of the following sequences: | |
1938 | @code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful | |
1939 | in accommodating files that are imported from other operating systems. | |
1940 | ||
1941 | @cindex End of source file | |
1942 | @cindex Source file, end | |
1943 | @findex SUB | |
1944 | The end of a source file is normally represented by the physical end of | |
1945 | file. However, the control character @code{16#1A#} (@code{SUB}) is also | |
1946 | recognized as signalling the end of the source file. Again, this is | |
1947 | provided for compatibility with other operating systems where this | |
1948 | code is used to represent the end of file. | |
1949 | ||
1950 | Each file contains a single Ada compilation unit, including any pragmas | |
1951 | associated with the unit. For example, this means you must place a | |
1952 | package declaration (a package @dfn{spec}) and the corresponding body in | |
1953 | separate files. An Ada @dfn{compilation} (which is a sequence of | |
1954 | compilation units) is represented using a sequence of files. Similarly, | |
1955 | you will place each subunit or child unit in a separate file. | |
1956 | ||
1957 | @node Foreign Language Representation | |
1958 | @section Foreign Language Representation | |
1959 | ||
1960 | @noindent | |
1961 | GNAT supports the standard character sets defined in Ada 95 as well as | |
1962 | several other non-standard character sets for use in localized versions | |
1963 | of the compiler (@pxref{Character Set Control}). | |
1964 | @menu | |
1965 | * Latin-1:: | |
1966 | * Other 8-Bit Codes:: | |
1967 | * Wide Character Encodings:: | |
1968 | @end menu | |
1969 | ||
1970 | @node Latin-1 | |
1971 | @subsection Latin-1 | |
1972 | @cindex Latin-1 | |
1973 | ||
1974 | @noindent | |
1975 | The basic character set is Latin-1. This character set is defined by ISO | |
1976 | standard 8859, part 1. The lower half (character codes @code{16#00#} | |
7cd4527e AC |
1977 | ... @code{16#7F#)} is identical to standard ASCII coding, but the upper half |
1978 | is used to represent additional characters. These include extended letters | |
88e1739c FW |
1979 | used by European languages, such as French accents, the vowels with umlauts |
1980 | used in German, and the extra letter A-ring used in Swedish. | |
1981 | ||
1982 | @findex Ada.Characters.Latin_1 | |
1983 | For a complete list of Latin-1 codes and their encodings, see the source | |
1984 | file of library unit @code{Ada.Characters.Latin_1} in file | |
1985 | @file{a-chlat1.ads}. | |
1986 | You may use any of these extended characters freely in character or | |
1987 | string literals. In addition, the extended characters that represent | |
1988 | letters can be used in identifiers. | |
1989 | ||
1990 | @node Other 8-Bit Codes | |
1991 | @subsection Other 8-Bit Codes | |
1992 | ||
1993 | @noindent | |
1994 | GNAT also supports several other 8-bit coding schemes: | |
1995 | ||
1996 | @table @asis | |
7cd4527e | 1997 | @item ISO 8859-2 (Latin-2) |
88e1739c | 1998 | @cindex Latin-2 |
7cd4527e | 1999 | @cindex ISO 8859-2 |
88e1739c FW |
2000 | Latin-2 letters allowed in identifiers, with uppercase and lowercase |
2001 | equivalence. | |
2002 | ||
7cd4527e | 2003 | @item ISO 8859-3 (Latin-3) |
88e1739c | 2004 | @cindex Latin-3 |
7cd4527e | 2005 | @cindex ISO 8859-3 |
88e1739c FW |
2006 | Latin-3 letters allowed in identifiers, with uppercase and lowercase |
2007 | equivalence. | |
2008 | ||
7cd4527e | 2009 | @item ISO 8859-4 (Latin-4) |
88e1739c | 2010 | @cindex Latin-4 |
7cd4527e | 2011 | @cindex ISO 8859-4 |
88e1739c FW |
2012 | Latin-4 letters allowed in identifiers, with uppercase and lowercase |
2013 | equivalence. | |
2014 | ||
7cd4527e AC |
2015 | @item ISO 8859-5 (Cyrillic) |
2016 | @cindex ISO 8859-5 | |
88e1739c | 2017 | @cindex Cyrillic |
7cd4527e AC |
2018 | ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and |
2019 | lowercase equivalence. | |
2020 | ||
2021 | @item ISO 8859-15 (Latin-9) | |
2022 | @cindex ISO 8859-15 | |
2023 | @cindex Latin-9 | |
2024 | ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and | |
2025 | lowercase equivalence | |
88e1739c FW |
2026 | |
2027 | @item IBM PC (code page 437) | |
2028 | @cindex code page 437 | |
2029 | This code page is the normal default for PCs in the U.S. It corresponds | |
2030 | to the original IBM PC character set. This set has some, but not all, of | |
2031 | the extended Latin-1 letters, but these letters do not have the same | |
2032 | encoding as Latin-1. In this mode, these letters are allowed in | |
2033 | identifiers with uppercase and lowercase equivalence. | |
2034 | ||
2035 | @item IBM PC (code page 850) | |
2036 | @cindex code page 850 | |
2037 | This code page is a modification of 437 extended to include all the | |
2038 | Latin-1 letters, but still not with the usual Latin-1 encoding. In this | |
2039 | mode, all these letters are allowed in identifiers with uppercase and | |
2040 | lowercase equivalence. | |
2041 | ||
2042 | @item Full Upper 8-bit | |
2043 | Any character in the range 80-FF allowed in identifiers, and all are | |
2044 | considered distinct. In other words, there are no uppercase and lowercase | |
2045 | equivalences in this range. This is useful in conjunction with | |
2046 | certain encoding schemes used for some foreign character sets (e.g. | |
2047 | the typical method of representing Chinese characters on the PC). | |
2048 | ||
2049 | @item No Upper-Half | |
2050 | No upper-half characters in the range 80-FF are allowed in identifiers. | |
2051 | This gives Ada 83 compatibility for identifier names. | |
2052 | @end table | |
2053 | ||
2054 | @noindent | |
2055 | For precise data on the encodings permitted, and the uppercase and lowercase | |
2056 | equivalences that are recognized, see the file @file{csets.adb} in | |
2057 | the GNAT compiler sources. You will need to obtain a full source release | |
2058 | of GNAT to obtain this file. | |
2059 | ||
2060 | @node Wide Character Encodings | |
2061 | @subsection Wide Character Encodings | |
2062 | ||
2063 | @noindent | |
2064 | GNAT allows wide character codes to appear in character and string | |
2065 | literals, and also optionally in identifiers, by means of the following | |
2066 | possible encoding schemes: | |
2067 | ||
2068 | @table @asis | |
2069 | ||
2070 | @item Hex Coding | |
2071 | In this encoding, a wide character is represented by the following five | |
2072 | character sequence: | |
2073 | ||
2074 | @smallexample | |
2075 | ESC a b c d | |
2076 | @end smallexample | |
2077 | ||
2078 | @noindent | |
2079 | Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
2080 | characters (using uppercase letters) of the wide character code. For | |
2081 | example, ESC A345 is used to represent the wide character with code | |
2082 | @code{16#A345#}. | |
2083 | This scheme is compatible with use of the full Wide_Character set. | |
2084 | ||
2085 | @item Upper-Half Coding | |
2086 | @cindex Upper-Half Coding | |
7cd4527e AC |
2087 | The wide character with encoding @code{16#abcd#} where the upper bit is on |
2088 | (in other words, ``a'' is in the range 8-F) is represented as two bytes, | |
88e1739c FW |
2089 | @code{16#ab#} and @code{16#cd#}. The second byte cannot be a format control |
2090 | character, but is not required to be in the upper half. This method can | |
2091 | be also used for shift-JIS or EUC, where the internal coding matches the | |
2092 | external coding. | |
2093 | ||
2094 | @item Shift JIS Coding | |
2095 | @cindex Shift JIS Coding | |
2096 | A wide character is represented by a two-character sequence, | |
2097 | @code{16#ab#} and | |
2098 | @code{16#cd#}, with the restrictions described for upper-half encoding as | |
2099 | described above. The internal character code is the corresponding JIS | |
2100 | character according to the standard algorithm for Shift-JIS | |
2101 | conversion. Only characters defined in the JIS code set table can be | |
2102 | used with this encoding method. | |
2103 | ||
2104 | @item EUC Coding | |
2105 | @cindex EUC Coding | |
2106 | A wide character is represented by a two-character sequence | |
2107 | @code{16#ab#} and | |
2108 | @code{16#cd#}, with both characters being in the upper half. The internal | |
2109 | character code is the corresponding JIS character according to the EUC | |
2110 | encoding algorithm. Only characters defined in the JIS code set table | |
2111 | can be used with this encoding method. | |
2112 | ||
2113 | @item UTF-8 Coding | |
2114 | A wide character is represented using | |
2115 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
2116 | 10646-1/Am.2. Depending on the character value, the representation | |
2117 | is a one, two, or three byte sequence: | |
2118 | @smallexample | |
2119 | @iftex | |
2120 | @leftskip=.7cm | |
2121 | @end iftex | |
2122 | 16#0000#-16#007f#: 2#0xxxxxxx# | |
2123 | 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# | |
2124 | 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# | |
2125 | ||
2126 | @end smallexample | |
2127 | ||
2128 | @noindent | |
2129 | where the xxx bits correspond to the left-padded bits of the | |
2130 | 16-bit character value. Note that all lower half ASCII characters | |
2131 | are represented as ASCII bytes and all upper half characters and | |
2132 | other wide characters are represented as sequences of upper-half | |
2133 | (The full UTF-8 scheme allows for encoding 31-bit characters as | |
2134 | 6-byte sequences, but in this implementation, all UTF-8 sequences | |
2135 | of four or more bytes length will be treated as illegal). | |
2136 | @item Brackets Coding | |
2137 | In this encoding, a wide character is represented by the following eight | |
2138 | character sequence: | |
2139 | ||
2140 | @smallexample | |
2141 | [ " a b c d " ] | |
2142 | @end smallexample | |
2143 | ||
2144 | @noindent | |
2145 | Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
2146 | characters (using uppercase letters) of the wide character code. For | |
7cd4527e | 2147 | example, [``A345''] is used to represent the wide character with code |
88e1739c FW |
2148 | @code{16#A345#}. It is also possible (though not required) to use the |
2149 | Brackets coding for upper half characters. For example, the code | |
7cd4527e | 2150 | @code{16#A3#} can be represented as @code{[``A3'']}. |
88e1739c FW |
2151 | |
2152 | This scheme is compatible with use of the full Wide_Character set, | |
2153 | and is also the method used for wide character encoding in the standard | |
2154 | ACVC (Ada Compiler Validation Capability) test suite distributions. | |
2155 | ||
2156 | @end table | |
2157 | ||
2158 | @noindent | |
2159 | Note: Some of these coding schemes do not permit the full use of the | |
2160 | Ada 95 character set. For example, neither Shift JIS, nor EUC allow the | |
2161 | use of the upper half of the Latin-1 set. | |
2162 | ||
2163 | @node File Naming Rules | |
2164 | @section File Naming Rules | |
2165 | ||
2166 | @noindent | |
2167 | The default file name is determined by the name of the unit that the | |
2168 | file contains. The name is formed by taking the full expanded name of | |
2169 | the unit and replacing the separating dots with hyphens and using | |
2170 | ^lowercase^uppercase^ for all letters. | |
2171 | ||
2172 | An exception arises if the file name generated by the above rules starts | |
2173 | with one of the characters | |
2174 | @ifset vms | |
2175 | A,G,I, or S, | |
2176 | @end ifset | |
2177 | @ifclear vms | |
2178 | a,g,i, or s, | |
2179 | @end ifclear | |
2180 | and the second character is a | |
2181 | minus. In this case, the character ^tilde^dollar sign^ is used in place | |
2182 | of the minus. The reason for this special rule is to avoid clashes with | |
2183 | the standard names for child units of the packages System, Ada, | |
2184 | Interfaces, and GNAT, which use the prefixes | |
2185 | @ifset vms | |
2186 | S- A- I- and G- | |
2187 | @end ifset | |
2188 | @ifclear vms | |
2189 | s- a- i- and g- | |
2190 | @end ifclear | |
2191 | respectively. | |
2192 | ||
2193 | The file extension is @file{.ads} for a spec and | |
2194 | @file{.adb} for a body. The following list shows some | |
2195 | examples of these rules. | |
2196 | ||
2197 | @table @file | |
2198 | @item main.ads | |
2199 | Main (spec) | |
2200 | @item main.adb | |
2201 | Main (body) | |
2202 | @item arith_functions.ads | |
2203 | Arith_Functions (package spec) | |
2204 | @item arith_functions.adb | |
2205 | Arith_Functions (package body) | |
2206 | @item func-spec.ads | |
2207 | Func.Spec (child package spec) | |
2208 | @item func-spec.adb | |
2209 | Func.Spec (child package body) | |
2210 | @item main-sub.adb | |
2211 | Sub (subunit of Main) | |
2212 | @item ^a~bad.adb^A$BAD.ADB^ | |
2213 | A.Bad (child package body) | |
2214 | @end table | |
2215 | ||
2216 | @noindent | |
2217 | Following these rules can result in excessively long | |
2218 | file names if corresponding | |
2219 | unit names are long (for example, if child units or subunits are | |
2220 | heavily nested). An option is available to shorten such long file names | |
7cd4527e | 2221 | (called file name ``krunching''). This may be particularly useful when |
88e1739c FW |
2222 | programs being developed with GNAT are to be used on operating systems |
2223 | with limited file name lengths. @xref{Using gnatkr}. | |
2224 | ||
2225 | Of course, no file shortening algorithm can guarantee uniqueness over | |
2226 | all possible unit names; if file name krunching is used, it is your | |
2227 | responsibility to ensure no name clashes occur. Alternatively you | |
2228 | can specify the exact file names that you want used, as described | |
2229 | in the next section. Finally, if your Ada programs are migrating from a | |
2230 | compiler with a different naming convention, you can use the gnatchop | |
2231 | utility to produce source files that follow the GNAT naming conventions. | |
2232 | (For details @pxref{Renaming Files Using gnatchop}.) | |
2233 | ||
7cd4527e AC |
2234 | Note: in the case of @code{Windows NT/XP} or @code{OpenVMS} operating |
2235 | systems, case is not significant. So for example on @code{Windows XP} | |
2236 | if the canonical name is @code{main-sub.adb}, you can use the file name | |
2237 | @code{Main-Sub.adb} instead. However, case is significant for other | |
2238 | operating systems, so for example, if you want to use other than | |
2239 | canonically cased file names on a Unix system, you need to follow | |
2240 | the procedures described in the next section. | |
2241 | ||
88e1739c FW |
2242 | @node Using Other File Names |
2243 | @section Using Other File Names | |
2244 | @cindex File names | |
2245 | ||
2246 | @noindent | |
2247 | In the previous section, we have described the default rules used by | |
2248 | GNAT to determine the file name in which a given unit resides. It is | |
2249 | often convenient to follow these default rules, and if you follow them, | |
2250 | the compiler knows without being explicitly told where to find all | |
2251 | the files it needs. | |
2252 | ||
2253 | However, in some cases, particularly when a program is imported from | |
2254 | another Ada compiler environment, it may be more convenient for the | |
2255 | programmer to specify which file names contain which units. GNAT allows | |
2256 | arbitrary file names to be used by means of the Source_File_Name pragma. | |
2257 | The form of this pragma is as shown in the following examples: | |
2258 | @cindex Source_File_Name pragma | |
2259 | ||
7cd4527e | 2260 | @smallexample @c ada |
88e1739c | 2261 | @cartouche |
7cd4527e | 2262 | pragma Source_File_Name (My_Utilities.Stacks, |
88e1739c | 2263 | Spec_File_Name => "myutilst_a.ada"); |
7cd4527e | 2264 | pragma Source_File_name (My_Utilities.Stacks, |
88e1739c FW |
2265 | Body_File_Name => "myutilst.ada"); |
2266 | @end cartouche | |
88e1739c FW |
2267 | @end smallexample |
2268 | ||
2269 | @noindent | |
2270 | As shown in this example, the first argument for the pragma is the unit | |
2271 | name (in this example a child unit). The second argument has the form | |
2272 | of a named association. The identifier | |
2273 | indicates whether the file name is for a spec or a body; | |
2274 | the file name itself is given by a string literal. | |
2275 | ||
2276 | The source file name pragma is a configuration pragma, which means that | |
2277 | normally it will be placed in the @file{gnat.adc} | |
2278 | file used to hold configuration | |
2279 | pragmas that apply to a complete compilation environment. | |
2280 | For more details on how the @file{gnat.adc} file is created and used | |
2281 | @pxref{Handling of Configuration Pragmas} | |
2282 | @cindex @file{gnat.adc} | |
2283 | ||
2284 | @ifclear vms | |
2285 | GNAT allows completely arbitrary file names to be specified using the | |
2286 | source file name pragma. However, if the file name specified has an | |
7cd4527e AC |
2287 | extension other than @file{.ads} or @file{.adb} it is necessary to use |
2288 | a special syntax when compiling the file. The name in this case must be | |
2289 | preceded by the special sequence @code{-x} followed by a space and the name | |
2290 | of the language, here @code{ada}, as in: | |
88e1739c FW |
2291 | |
2292 | @smallexample | |
2293 | $ gcc -c -x ada peculiar_file_name.sim | |
2294 | @end smallexample | |
2295 | @end ifclear | |
2296 | ||
2297 | @noindent | |
2298 | @code{gnatmake} handles non-standard file names in the usual manner (the | |
2299 | non-standard file name for the main program is simply used as the | |
2300 | argument to gnatmake). Note that if the extension is also non-standard, | |
2301 | then it must be included in the gnatmake command, it may not be omitted. | |
2302 | ||
2303 | @node Alternative File Naming Schemes | |
2304 | @section Alternative File Naming Schemes | |
2305 | @cindex File naming schemes, alternative | |
2306 | @cindex File names | |
2307 | ||
2308 | In the previous section, we described the use of the @code{Source_File_Name} | |
2309 | pragma to allow arbitrary names to be assigned to individual source files. | |
2310 | However, this approach requires one pragma for each file, and especially in | |
2311 | large systems can result in very long @file{gnat.adc} files, and also create | |
2312 | a maintenance problem. | |
2313 | ||
2314 | GNAT also provides a facility for specifying systematic file naming schemes | |
2315 | other than the standard default naming scheme previously described. An | |
2316 | alternative scheme for naming is specified by the use of | |
2317 | @code{Source_File_Name} pragmas having the following format: | |
2318 | @cindex Source_File_Name pragma | |
2319 | ||
7cd4527e | 2320 | @smallexample @c ada |
88e1739c FW |
2321 | pragma Source_File_Name ( |
2322 | Spec_File_Name => FILE_NAME_PATTERN | |
2323 | [,Casing => CASING_SPEC] | |
2324 | [,Dot_Replacement => STRING_LITERAL]); | |
2325 | ||
2326 | pragma Source_File_Name ( | |
2327 | Body_File_Name => FILE_NAME_PATTERN | |
2328 | [,Casing => CASING_SPEC] | |
2329 | [,Dot_Replacement => STRING_LITERAL]); | |
2330 | ||
2331 | pragma Source_File_Name ( | |
2332 | Subunit_File_Name => FILE_NAME_PATTERN | |
2333 | [,Casing => CASING_SPEC] | |
2334 | [,Dot_Replacement => STRING_LITERAL]); | |
2335 | ||
2336 | FILE_NAME_PATTERN ::= STRING_LITERAL | |
2337 | CASING_SPEC ::= Lowercase | Uppercase | Mixedcase | |
88e1739c FW |
2338 | @end smallexample |
2339 | ||
2340 | @noindent | |
2341 | The @code{FILE_NAME_PATTERN} string shows how the file name is constructed. | |
2342 | It contains a single asterisk character, and the unit name is substituted | |
2343 | systematically for this asterisk. The optional parameter | |
2344 | @code{Casing} indicates | |
2345 | whether the unit name is to be all upper-case letters, all lower-case letters, | |
2346 | or mixed-case. If no | |
2347 | @code{Casing} parameter is used, then the default is all | |
2348 | ^lower-case^upper-case^. | |
2349 | ||
2350 | The optional @code{Dot_Replacement} string is used to replace any periods | |
2351 | that occur in subunit or child unit names. If no @code{Dot_Replacement} | |
2352 | argument is used then separating dots appear unchanged in the resulting | |
2353 | file name. | |
2354 | Although the above syntax indicates that the | |
2355 | @code{Casing} argument must appear | |
2356 | before the @code{Dot_Replacement} argument, but it | |
2357 | is also permissible to write these arguments in the opposite order. | |
2358 | ||
2359 | As indicated, it is possible to specify different naming schemes for | |
2360 | bodies, specs, and subunits. Quite often the rule for subunits is the | |
2361 | same as the rule for bodies, in which case, there is no need to give | |
2362 | a separate @code{Subunit_File_Name} rule, and in this case the | |
2363 | @code{Body_File_name} rule is used for subunits as well. | |
2364 | ||
2365 | The separate rule for subunits can also be used to implement the rather | |
2366 | unusual case of a compilation environment (e.g. a single directory) which | |
2367 | contains a subunit and a child unit with the same unit name. Although | |
2368 | both units cannot appear in the same partition, the Ada Reference Manual | |
2369 | allows (but does not require) the possibility of the two units coexisting | |
2370 | in the same environment. | |
2371 | ||
2372 | The file name translation works in the following steps: | |
2373 | ||
2374 | @itemize @bullet | |
2375 | ||
2376 | @item | |
2377 | If there is a specific @code{Source_File_Name} pragma for the given unit, | |
2378 | then this is always used, and any general pattern rules are ignored. | |
2379 | ||
2380 | @item | |
2381 | If there is a pattern type @code{Source_File_Name} pragma that applies to | |
2382 | the unit, then the resulting file name will be used if the file exists. If | |
2383 | more than one pattern matches, the latest one will be tried first, and the | |
2384 | first attempt resulting in a reference to a file that exists will be used. | |
2385 | ||
2386 | @item | |
2387 | If no pattern type @code{Source_File_Name} pragma that applies to the unit | |
2388 | for which the corresponding file exists, then the standard GNAT default | |
2389 | naming rules are used. | |
2390 | ||
2391 | @end itemize | |
2392 | ||
2393 | @noindent | |
2394 | As an example of the use of this mechanism, consider a commonly used scheme | |
2395 | in which file names are all lower case, with separating periods copied | |
7cd4527e AC |
2396 | unchanged to the resulting file name, and specs end with @file{.1.ada}, and |
2397 | bodies end with @file{.2.ada}. GNAT will follow this scheme if the following | |
88e1739c FW |
2398 | two pragmas appear: |
2399 | ||
7cd4527e | 2400 | @smallexample @c ada |
88e1739c FW |
2401 | pragma Source_File_Name |
2402 | (Spec_File_Name => "*.1.ada"); | |
2403 | pragma Source_File_Name | |
2404 | (Body_File_Name => "*.2.ada"); | |
2405 | @end smallexample | |
2406 | ||
2407 | @noindent | |
2408 | The default GNAT scheme is actually implemented by providing the following | |
2409 | default pragmas internally: | |
2410 | ||
7cd4527e | 2411 | @smallexample @c ada |
88e1739c FW |
2412 | pragma Source_File_Name |
2413 | (Spec_File_Name => "*.ads", Dot_Replacement => "-"); | |
2414 | pragma Source_File_Name | |
2415 | (Body_File_Name => "*.adb", Dot_Replacement => "-"); | |
2416 | @end smallexample | |
2417 | ||
2418 | @noindent | |
2419 | Our final example implements a scheme typically used with one of the | |
7cd4527e | 2420 | Ada 83 compilers, where the separator character for subunits was ``__'' |
88e1739c FW |
2421 | (two underscores), specs were identified by adding @file{_.ADA}, bodies |
2422 | by adding @file{.ADA}, and subunits by | |
2423 | adding @file{.SEP}. All file names were | |
2424 | upper case. Child units were not present of course since this was an | |
2425 | Ada 83 compiler, but it seems reasonable to extend this scheme to use | |
2426 | the same double underscore separator for child units. | |
2427 | ||
7cd4527e | 2428 | @smallexample @c ada |
88e1739c FW |
2429 | pragma Source_File_Name |
2430 | (Spec_File_Name => "*_.ADA", | |
2431 | Dot_Replacement => "__", | |
2432 | Casing = Uppercase); | |
2433 | pragma Source_File_Name | |
2434 | (Body_File_Name => "*.ADA", | |
2435 | Dot_Replacement => "__", | |
2436 | Casing = Uppercase); | |
2437 | pragma Source_File_Name | |
2438 | (Subunit_File_Name => "*.SEP", | |
2439 | Dot_Replacement => "__", | |
2440 | Casing = Uppercase); | |
2441 | @end smallexample | |
2442 | ||
2443 | @node Generating Object Files | |
2444 | @section Generating Object Files | |
2445 | ||
2446 | @noindent | |
2447 | An Ada program consists of a set of source files, and the first step in | |
2448 | compiling the program is to generate the corresponding object files. | |
2449 | These are generated by compiling a subset of these source files. | |
2450 | The files you need to compile are the following: | |
2451 | ||
2452 | @itemize @bullet | |
2453 | @item | |
2454 | If a package spec has no body, compile the package spec to produce the | |
2455 | object file for the package. | |
2456 | ||
2457 | @item | |
2458 | If a package has both a spec and a body, compile the body to produce the | |
2459 | object file for the package. The source file for the package spec need | |
2460 | not be compiled in this case because there is only one object file, which | |
2461 | contains the code for both the spec and body of the package. | |
2462 | ||
2463 | @item | |
2464 | For a subprogram, compile the subprogram body to produce the object file | |
2465 | for the subprogram. The spec, if one is present, is as usual in a | |
2466 | separate file, and need not be compiled. | |
2467 | ||
2468 | @item | |
2469 | @cindex Subunits | |
2470 | In the case of subunits, only compile the parent unit. A single object | |
2471 | file is generated for the entire subunit tree, which includes all the | |
2472 | subunits. | |
2473 | ||
2474 | @item | |
2475 | Compile child units independently of their parent units | |
2476 | (though, of course, the spec of all the ancestor unit must be present in order | |
2477 | to compile a child unit). | |
2478 | ||
2479 | @item | |
2480 | @cindex Generics | |
2481 | Compile generic units in the same manner as any other units. The object | |
2482 | files in this case are small dummy files that contain at most the | |
2483 | flag used for elaboration checking. This is because GNAT always handles generic | |
2484 | instantiation by means of macro expansion. However, it is still necessary to | |
2485 | compile generic units, for dependency checking and elaboration purposes. | |
2486 | @end itemize | |
2487 | ||
2488 | @noindent | |
2489 | The preceding rules describe the set of files that must be compiled to | |
2490 | generate the object files for a program. Each object file has the same | |
2491 | name as the corresponding source file, except that the extension is | |
2492 | @file{.o} as usual. | |
2493 | ||
2494 | You may wish to compile other files for the purpose of checking their | |
2495 | syntactic and semantic correctness. For example, in the case where a | |
2496 | package has a separate spec and body, you would not normally compile the | |
2497 | spec. However, it is convenient in practice to compile the spec to make | |
2498 | sure it is error-free before compiling clients of this spec, because such | |
2499 | compilations will fail if there is an error in the spec. | |
2500 | ||
2501 | GNAT provides an option for compiling such files purely for the | |
2502 | purposes of checking correctness; such compilations are not required as | |
2503 | part of the process of building a program. To compile a file in this | |
2504 | checking mode, use the @option{-gnatc} switch. | |
2505 | ||
2506 | @node Source Dependencies | |
2507 | @section Source Dependencies | |
2508 | ||
2509 | @noindent | |
2510 | A given object file clearly depends on the source file which is compiled | |
2511 | to produce it. Here we are using @dfn{depends} in the sense of a typical | |
2512 | @code{make} utility; in other words, an object file depends on a source | |
2513 | file if changes to the source file require the object file to be | |
2514 | recompiled. | |
2515 | In addition to this basic dependency, a given object may depend on | |
2516 | additional source files as follows: | |
2517 | ||
2518 | @itemize @bullet | |
2519 | @item | |
2520 | If a file being compiled @code{with}'s a unit @var{X}, the object file | |
2521 | depends on the file containing the spec of unit @var{X}. This includes | |
2522 | files that are @code{with}'ed implicitly either because they are parents | |
2523 | of @code{with}'ed child units or they are run-time units required by the | |
2524 | language constructs used in a particular unit. | |
2525 | ||
2526 | @item | |
2527 | If a file being compiled instantiates a library level generic unit, the | |
2528 | object file depends on both the spec and body files for this generic | |
2529 | unit. | |
2530 | ||
2531 | @item | |
2532 | If a file being compiled instantiates a generic unit defined within a | |
2533 | package, the object file depends on the body file for the package as | |
2534 | well as the spec file. | |
2535 | ||
2536 | @item | |
2537 | @findex Inline | |
2538 | @cindex @option{-gnatn} switch | |
2539 | If a file being compiled contains a call to a subprogram for which | |
2540 | pragma @code{Inline} applies and inlining is activated with the | |
2541 | @option{-gnatn} switch, the object file depends on the file containing the | |
2542 | body of this subprogram as well as on the file containing the spec. Note | |
2543 | that for inlining to actually occur as a result of the use of this switch, | |
2544 | it is necessary to compile in optimizing mode. | |
2545 | ||
2546 | @cindex @option{-gnatN} switch | |
2547 | The use of @option{-gnatN} activates a more extensive inlining optimization | |
2548 | that is performed by the front end of the compiler. This inlining does | |
2549 | not require that the code generation be optimized. Like @option{-gnatn}, | |
2550 | the use of this switch generates additional dependencies. | |
7cd4527e AC |
2551 | Note that |
2552 | @option{-gnatN} automatically implies @option{-gnatn} so it is not necessary | |
2553 | to specify both options. | |
88e1739c FW |
2554 | |
2555 | @item | |
2556 | If an object file O depends on the proper body of a subunit through inlining | |
2557 | or instantiation, it depends on the parent unit of the subunit. This means that | |
2558 | any modification of the parent unit or one of its subunits affects the | |
2559 | compilation of O. | |
2560 | ||
2561 | @item | |
2562 | The object file for a parent unit depends on all its subunit body files. | |
2563 | ||
2564 | @item | |
2565 | The previous two rules meant that for purposes of computing dependencies and | |
2566 | recompilation, a body and all its subunits are treated as an indivisible whole. | |
2567 | ||
2568 | @noindent | |
2569 | These rules are applied transitively: if unit @code{A} @code{with}'s | |
2570 | unit @code{B}, whose elaboration calls an inlined procedure in package | |
2571 | @code{C}, the object file for unit @code{A} will depend on the body of | |
2572 | @code{C}, in file @file{c.adb}. | |
2573 | ||
2574 | The set of dependent files described by these rules includes all the | |
2575 | files on which the unit is semantically dependent, as described in the | |
2576 | Ada 95 Language Reference Manual. However, it is a superset of what the | |
2577 | ARM describes, because it includes generic, inline, and subunit dependencies. | |
2578 | ||
2579 | An object file must be recreated by recompiling the corresponding source | |
2580 | file if any of the source files on which it depends are modified. For | |
2581 | example, if the @code{make} utility is used to control compilation, | |
2582 | the rule for an Ada object file must mention all the source files on | |
2583 | which the object file depends, according to the above definition. | |
2584 | The determination of the necessary | |
2585 | recompilations is done automatically when one uses @code{gnatmake}. | |
2586 | @end itemize | |
2587 | ||
2588 | @node The Ada Library Information Files | |
2589 | @section The Ada Library Information Files | |
2590 | @cindex Ada Library Information files | |
7cd4527e | 2591 | @cindex @file{ALI} files |
88e1739c FW |
2592 | |
2593 | @noindent | |
2594 | Each compilation actually generates two output files. The first of these | |
2595 | is the normal object file that has a @file{.o} extension. The second is a | |
2596 | text file containing full dependency information. It has the same | |
2597 | name as the source file, but an @file{.ali} extension. | |
7cd4527e AC |
2598 | This file is known as the Ada Library Information (@file{ALI}) file. |
2599 | The following information is contained in the @file{ALI} file. | |
88e1739c FW |
2600 | |
2601 | @itemize @bullet | |
2602 | @item | |
2603 | Version information (indicates which version of GNAT was used to compile | |
2604 | the unit(s) in question) | |
2605 | ||
2606 | @item | |
2607 | Main program information (including priority and time slice settings, | |
2608 | as well as the wide character encoding used during compilation). | |
2609 | ||
2610 | @item | |
2611 | List of arguments used in the @code{gcc} command for the compilation | |
2612 | ||
2613 | @item | |
2614 | Attributes of the unit, including configuration pragmas used, an indication | |
2615 | of whether the compilation was successful, exception model used etc. | |
2616 | ||
2617 | @item | |
2618 | A list of relevant restrictions applying to the unit (used for consistency) | |
2619 | checking. | |
2620 | ||
2621 | @item | |
2622 | Categorization information (e.g. use of pragma @code{Pure}). | |
2623 | ||
2624 | @item | |
2625 | Information on all @code{with}'ed units, including presence of | |
2626 | @code{Elaborate} or @code{Elaborate_All} pragmas. | |
2627 | ||
2628 | @item | |
2629 | Information from any @code{Linker_Options} pragmas used in the unit | |
2630 | ||
2631 | @item | |
2632 | Information on the use of @code{Body_Version} or @code{Version} | |
2633 | attributes in the unit. | |
2634 | ||
2635 | @item | |
2636 | Dependency information. This is a list of files, together with | |
2637 | time stamp and checksum information. These are files on which | |
2638 | the unit depends in the sense that recompilation is required | |
2639 | if any of these units are modified. | |
2640 | ||
2641 | @item | |
2642 | Cross-reference data. Contains information on all entities referenced | |
2643 | in the unit. Used by tools like @code{gnatxref} and @code{gnatfind} to | |
2644 | provide cross-reference information. | |
2645 | ||
2646 | @end itemize | |
2647 | ||
2648 | @noindent | |
7cd4527e | 2649 | For a full detailed description of the format of the @file{ALI} file, |
88e1739c FW |
2650 | see the source of the body of unit @code{Lib.Writ}, contained in file |
2651 | @file{lib-writ.adb} in the GNAT compiler sources. | |
2652 | ||
2653 | @node Binding an Ada Program | |
2654 | @section Binding an Ada Program | |
2655 | ||
2656 | @noindent | |
2657 | When using languages such as C and C++, once the source files have been | |
2658 | compiled the only remaining step in building an executable program | |
2659 | is linking the object modules together. This means that it is possible to | |
2660 | link an inconsistent version of a program, in which two units have | |
2661 | included different versions of the same header. | |
2662 | ||
2663 | The rules of Ada do not permit such an inconsistent program to be built. | |
2664 | For example, if two clients have different versions of the same package, | |
2665 | it is illegal to build a program containing these two clients. | |
2666 | These rules are enforced by the GNAT binder, which also determines an | |
2667 | elaboration order consistent with the Ada rules. | |
2668 | ||
2669 | The GNAT binder is run after all the object files for a program have | |
2670 | been created. It is given the name of the main program unit, and from | |
2671 | this it determines the set of units required by the program, by reading the | |
2672 | corresponding ALI files. It generates error messages if the program is | |
2673 | inconsistent or if no valid order of elaboration exists. | |
2674 | ||
2675 | If no errors are detected, the binder produces a main program, in Ada by | |
2676 | default, that contains calls to the elaboration procedures of those | |
2677 | compilation unit that require them, followed by | |
2678 | a call to the main program. This Ada program is compiled to generate the | |
2679 | object file for the main program. The name of | |
2680 | the Ada file is @file{b~@var{xxx}.adb} (with the corresponding spec | |
2681 | @file{b~@var{xxx}.ads}) where @var{xxx} is the name of the | |
2682 | main program unit. | |
2683 | ||
2684 | Finally, the linker is used to build the resulting executable program, | |
2685 | using the object from the main program from the bind step as well as the | |
2686 | object files for the Ada units of the program. | |
2687 | ||
2688 | @node Mixed Language Programming | |
2689 | @section Mixed Language Programming | |
2690 | @cindex Mixed Language Programming | |
2691 | ||
7cd4527e AC |
2692 | @noindent |
2693 | This section describes how to develop a mixed-language program, | |
2694 | specifically one that comprises units in both Ada and C. | |
2695 | ||
88e1739c FW |
2696 | @menu |
2697 | * Interfacing to C:: | |
2698 | * Calling Conventions:: | |
2699 | @end menu | |
2700 | ||
2701 | @node Interfacing to C | |
2702 | @subsection Interfacing to C | |
2703 | @noindent | |
7cd4527e AC |
2704 | Interfacing Ada with a foreign language such as C involves using |
2705 | compiler directives to import and/or export entity definitions in each | |
2706 | language---using @code{extern} statements in C, for instance, and the | |
2707 | @code{Import}, @code{Export}, and @code{Convention} pragmas in Ada. For | |
2708 | a full treatment of these topics, read Appendix B, section 1 of the Ada | |
2709 | 95 Language Reference Manual. | |
2710 | ||
2711 | There are two ways to build a program using GNAT that contains some Ada | |
2712 | sources and some foreign language sources, depending on whether or not | |
2713 | the main subprogram is written in Ada. Here is a source example with | |
2714 | the main subprogram in Ada: | |
2715 | ||
2716 | @smallexample | |
2717 | /* file1.c */ | |
2718 | #include <stdio.h> | |
2719 | ||
2720 | void print_num (int num) | |
2721 | @{ | |
2722 | printf ("num is %d.\n", num); | |
2723 | return; | |
2724 | @} | |
2725 | ||
2726 | /* file2.c */ | |
2727 | ||
2728 | /* num_from_Ada is declared in my_main.adb */ | |
2729 | extern int num_from_Ada; | |
2730 | ||
2731 | int get_num (void) | |
2732 | @{ | |
2733 | return num_from_Ada; | |
2734 | @} | |
2735 | @end smallexample | |
2736 | ||
2737 | @smallexample @c ada | |
2738 | -- my_main.adb | |
2739 | procedure My_Main is | |
2740 | ||
2741 | -- Declare then export an Integer entity called num_from_Ada | |
2742 | My_Num : Integer := 10; | |
2743 | pragma Export (C, My_Num, "num_from_Ada"); | |
2744 | ||
2745 | -- Declare an Ada function spec for Get_Num, then use | |
2746 | -- C function get_num for the implementation. | |
2747 | function Get_Num return Integer; | |
2748 | pragma Import (C, Get_Num, "get_num"); | |
2749 | ||
2750 | -- Declare an Ada procedure spec for Print_Num, then use | |
2751 | -- C function print_num for the implementation. | |
2752 | procedure Print_Num (Num : Integer); | |
2753 | pragma Import (C, Print_Num, "print_num"); | |
2754 | ||
2755 | begin | |
2756 | Print_Num (Get_Num); | |
2757 | end My_Main; | |
2758 | @end smallexample | |
88e1739c FW |
2759 | |
2760 | @enumerate | |
2761 | @item | |
7cd4527e AC |
2762 | To build this example, first compile the foreign language files to |
2763 | generate object files: | |
88e1739c FW |
2764 | @smallexample |
2765 | gcc -c file1.c | |
2766 | gcc -c file2.c | |
2767 | @end smallexample | |
2768 | ||
2769 | @item | |
7cd4527e AC |
2770 | Then, compile the Ada units to produce a set of object files and ALI |
2771 | files: | |
88e1739c FW |
2772 | @smallexample |
2773 | gnatmake ^-c^/ACTIONS=COMPILE^ my_main.adb | |
2774 | @end smallexample | |
2775 | ||
2776 | @item | |
7cd4527e | 2777 | Run the Ada binder on the Ada main program: |
88e1739c FW |
2778 | @smallexample |
2779 | gnatbind my_main.ali | |
2780 | @end smallexample | |
2781 | ||
2782 | @item | |
2783 | Link the Ada main program, the Ada objects and the other language | |
7cd4527e | 2784 | objects: |
88e1739c FW |
2785 | @smallexample |
2786 | gnatlink my_main.ali file1.o file2.o | |
2787 | @end smallexample | |
2788 | @end enumerate | |
2789 | ||
7cd4527e | 2790 | The last three steps can be grouped in a single command: |
88e1739c FW |
2791 | @smallexample |
2792 | gnatmake my_main.adb -largs file1.o file2.o | |
2793 | @end smallexample | |
2794 | ||
2795 | @cindex Binder output file | |
2796 | @noindent | |
7cd4527e AC |
2797 | If the main program is in a language other than Ada, then you may have |
2798 | more than one entry point into the Ada subsystem. You must use a special | |
2799 | binder option to generate callable routines that initialize and | |
2800 | finalize the Ada units (@pxref{Binding with Non-Ada Main Programs}). | |
2801 | Calls to the initialization and finalization routines must be inserted | |
2802 | in the main program, or some other appropriate point in the code. The | |
2803 | call to initialize the Ada units must occur before the first Ada | |
2804 | subprogram is called, and the call to finalize the Ada units must occur | |
2805 | after the last Ada subprogram returns. The binder will place the | |
2806 | initialization and finalization subprograms into the | |
2807 | @file{b~@var{xxx}.adb} file where they can be accessed by your C | |
2808 | sources. To illustrate, we have the following example: | |
2809 | ||
2810 | @smallexample | |
2811 | /* main.c */ | |
2812 | extern void adainit (void); | |
2813 | extern void adafinal (void); | |
2814 | extern int add (int, int); | |
2815 | extern int sub (int, int); | |
2816 | ||
2817 | int main (int argc, char *argv[]) | |
2818 | @{ | |
2819 | int a = 21, b = 7; | |
2820 | ||
2821 | adainit(); | |
2822 | ||
2823 | /* Should print "21 + 7 = 28" */ | |
2824 | printf ("%d + %d = %d\n", a, b, add (a, b)); | |
2825 | /* Should print "21 - 7 = 14" */ | |
2826 | printf ("%d - %d = %d\n", a, b, sub (a, b)); | |
2827 | ||
2828 | adafinal(); | |
2829 | @} | |
2830 | @end smallexample | |
2831 | ||
2832 | @smallexample @c ada | |
2833 | -- unit1.ads | |
2834 | package Unit1 is | |
2835 | function Add (A, B : Integer) return Integer; | |
2836 | pragma Export (C, Add, "add"); | |
2837 | end Unit1; | |
2838 | ||
2839 | -- unit1.adb | |
2840 | package body Unit1 is | |
2841 | function Add (A, B : Integer) return Integer is | |
2842 | begin | |
2843 | return A + B; | |
2844 | end Add; | |
2845 | end Unit1; | |
2846 | ||
2847 | -- unit2.ads | |
2848 | package Unit2 is | |
2849 | function Sub (A, B : Integer) return Integer; | |
2850 | pragma Export (C, Sub, "sub"); | |
2851 | end Unit2; | |
2852 | ||
2853 | -- unit2.adb | |
2854 | package body Unit2 is | |
2855 | function Sub (A, B : Integer) return Integer is | |
2856 | begin | |
2857 | return A - B; | |
2858 | end Sub; | |
2859 | end Unit2; | |
2860 | @end smallexample | |
88e1739c FW |
2861 | |
2862 | @enumerate | |
2863 | @item | |
7cd4527e AC |
2864 | The build procedure for this application is similar to the last |
2865 | example's. First, compile the foreign language files to generate object | |
2866 | files: | |
88e1739c | 2867 | @smallexample |
7cd4527e | 2868 | gcc -c main.c |
88e1739c FW |
2869 | @end smallexample |
2870 | ||
2871 | @item | |
7cd4527e AC |
2872 | Next, compile the Ada units to produce a set of object files and ALI |
2873 | files: | |
88e1739c | 2874 | @smallexample |
7cd4527e AC |
2875 | gnatmake ^-c^/ACTIONS=COMPILE^ unit1.adb |
2876 | gnatmake ^-c^/ACTIONS=COMPILE^ unit2.adb | |
88e1739c FW |
2877 | @end smallexample |
2878 | ||
2879 | @item | |
7cd4527e AC |
2880 | Run the Ada binder on every generated ALI file. Make sure to use the |
2881 | @option{-n} option to specify a foreign main program: | |
88e1739c | 2882 | @smallexample |
7cd4527e | 2883 | gnatbind ^-n^/NOMAIN^ unit1.ali unit2.ali |
88e1739c FW |
2884 | @end smallexample |
2885 | ||
2886 | @item | |
7cd4527e AC |
2887 | Link the Ada main program, the Ada objects and the foreign language |
2888 | objects. You need only list the last ALI file here: | |
88e1739c | 2889 | @smallexample |
7cd4527e | 2890 | gnatlink unit2.ali main.o -o exec_file |
88e1739c | 2891 | @end smallexample |
7cd4527e AC |
2892 | |
2893 | This procedure yields a binary executable called @file{exec_file}. | |
88e1739c FW |
2894 | @end enumerate |
2895 | ||
2896 | @node Calling Conventions | |
2897 | @subsection Calling Conventions | |
2898 | @cindex Foreign Languages | |
2899 | @cindex Calling Conventions | |
2900 | GNAT follows standard calling sequence conventions and will thus interface | |
2901 | to any other language that also follows these conventions. The following | |
2902 | Convention identifiers are recognized by GNAT: | |
2903 | ||
7cd4527e | 2904 | @table @code |
88e1739c FW |
2905 | @cindex Interfacing to Ada |
2906 | @cindex Other Ada compilers | |
2907 | @cindex Convention Ada | |
7cd4527e AC |
2908 | @item Ada |
2909 | This indicates that the standard Ada calling sequence will be | |
88e1739c FW |
2910 | used and all Ada data items may be passed without any limitations in the |
2911 | case where GNAT is used to generate both the caller and callee. It is also | |
2912 | possible to mix GNAT generated code and code generated by another Ada | |
2913 | compiler. In this case, the data types should be restricted to simple | |
2914 | cases, including primitive types. Whether complex data types can be passed | |
2915 | depends on the situation. Probably it is safe to pass simple arrays, such | |
2916 | as arrays of integers or floats. Records may or may not work, depending | |
2917 | on whether both compilers lay them out identically. Complex structures | |
2918 | involving variant records, access parameters, tasks, or protected types, | |
2919 | are unlikely to be able to be passed. | |
2920 | ||
2921 | Note that in the case of GNAT running | |
2922 | on a platform that supports DEC Ada 83, a higher degree of compatibility | |
2923 | can be guaranteed, and in particular records are layed out in an identical | |
2924 | manner in the two compilers. Note also that if output from two different | |
2925 | compilers is mixed, the program is responsible for dealing with elaboration | |
2926 | issues. Probably the safest approach is to write the main program in the | |
2927 | version of Ada other than GNAT, so that it takes care of its own elaboration | |
2928 | requirements, and then call the GNAT-generated adainit procedure to ensure | |
2929 | elaboration of the GNAT components. Consult the documentation of the other | |
2930 | Ada compiler for further details on elaboration. | |
2931 | ||
2932 | However, it is not possible to mix the tasking run time of GNAT and | |
2933 | DEC Ada 83, All the tasking operations must either be entirely within | |
2934 | GNAT compiled sections of the program, or entirely within DEC Ada 83 | |
2935 | compiled sections of the program. | |
2936 | ||
2937 | @cindex Interfacing to Assembly | |
2938 | @cindex Convention Assembler | |
7cd4527e AC |
2939 | @item Assembler |
2940 | Specifies assembler as the convention. In practice this has the | |
88e1739c FW |
2941 | same effect as convention Ada (but is not equivalent in the sense of being |
2942 | considered the same convention). | |
2943 | ||
2944 | @cindex Convention Asm | |
2945 | @findex Asm | |
7cd4527e AC |
2946 | @item Asm |
2947 | Equivalent to Assembler. | |
88e1739c FW |
2948 | |
2949 | @cindex Interfacing to COBOL | |
2950 | @cindex Convention COBOL | |
2951 | @findex COBOL | |
7cd4527e AC |
2952 | @item COBOL |
2953 | Data will be passed according to the conventions described | |
88e1739c FW |
2954 | in section B.4 of the Ada 95 Reference Manual. |
2955 | ||
2956 | @findex C | |
2957 | @cindex Interfacing to C | |
2958 | @cindex Convention C | |
7cd4527e AC |
2959 | @item C |
2960 | Data will be passed according to the conventions described | |
88e1739c FW |
2961 | in section B.3 of the Ada 95 Reference Manual. |
2962 | ||
7cd4527e AC |
2963 | @findex C varargs function |
2964 | @cindex Intefacing to C varargs function | |
2965 | @cindex varargs function intefacs | |
2966 | @item C varargs function | |
2967 | In C, @code{varargs} allows a function to take a variable number of | |
2968 | arguments. There is no direct equivalent in this to Ada. One | |
2969 | approach that can be used is to create a C wrapper for each | |
2970 | different profile and then interface to this C wrapper. For | |
2971 | example, to print an @code{int} value using @code{printf}, | |
2972 | create a C function @code{printfi} that takes two arguments, a | |
2973 | pointer to a string and an int, and calls @code{printf}. | |
2974 | Then in the Ada program, use pragma @code{Import} to | |
2975 | interface to printfi. | |
2976 | ||
2977 | It may work on some platforms to directly interface to | |
2978 | a @code{varargs} function by providing a specific Ada profile | |
2979 | for a a particular call. However, this does not work on | |
2980 | all platforms, since there is no guarantee that the | |
2981 | calling sequence for a two argument normal C function | |
2982 | is the same as for calling a @code{varargs} C function with | |
2983 | the same two arguments. | |
2984 | ||
88e1739c FW |
2985 | @cindex Convention Default |
2986 | @findex Default | |
7cd4527e AC |
2987 | @item Default |
2988 | Equivalent to C. | |
88e1739c FW |
2989 | |
2990 | @cindex Convention External | |
2991 | @findex External | |
7cd4527e AC |
2992 | @item External |
2993 | Equivalent to C. | |
88e1739c FW |
2994 | |
2995 | @findex C++ | |
2996 | @cindex Interfacing to C++ | |
2997 | @cindex Convention C++ | |
7cd4527e AC |
2998 | @item CPP |
2999 | This stands for C++. For most purposes this is identical to C. | |
88e1739c FW |
3000 | See the separate description of the specialized GNAT pragmas relating to |
3001 | C++ interfacing for further details. | |
3002 | ||
3003 | @findex Fortran | |
3004 | @cindex Interfacing to Fortran | |
3005 | @cindex Convention Fortran | |
7cd4527e AC |
3006 | @item Fortran |
3007 | Data will be passed according to the conventions described | |
88e1739c FW |
3008 | in section B.5 of the Ada 95 Reference Manual. |
3009 | ||
7cd4527e AC |
3010 | @item Intrinsic |
3011 | This applies to an intrinsic operation, as defined in the Ada 95 | |
88e1739c FW |
3012 | Reference Manual. If a a pragma Import (Intrinsic) applies to a subprogram, |
3013 | this means that the body of the subprogram is provided by the compiler itself, | |
3014 | usually by means of an efficient code sequence, and that the user does not | |
7cd4527e AC |
3015 | supply an explicit body for it. In an application program, the pragma can |
3016 | only be applied to the following two sets of names, which the GNAT compiler | |
88e1739c | 3017 | recognizes. |
7cd4527e | 3018 | |
88e1739c FW |
3019 | @itemize @bullet |
3020 | @item | |
3021 | Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, Shift_Right_- | |
3022 | Arithmetic. The corresponding subprogram declaration must have | |
3023 | two formal parameters. The | |
3024 | first one must be a signed integer type or a modular type with a binary | |
3025 | modulus, and the second parameter must be of type Natural. | |
3026 | The return type must be the same as the type of the first argument. The size | |
3027 | of this type can only be 8, 16, 32, or 64. | |
7cd4527e | 3028 | @item binary arithmetic operators: ``+'', ``-'', ``*'', ``/'' |
88e1739c FW |
3029 | The corresponding operator declaration must have parameters and result type |
3030 | that have the same root numeric type (for example, all three are long_float | |
3031 | types). This simplifies the definition of operations that use type checking | |
3032 | to perform dimensional checks: | |
7cd4527e AC |
3033 | |
3034 | @smallexample @c ada | |
88e1739c FW |
3035 | type Distance is new Long_Float; |
3036 | type Time is new Long_Float; | |
3037 | type Velocity is new Long_Float; | |
3038 | function "/" (D : Distance; T : Time) | |
3039 | return Velocity; | |
3040 | pragma Import (Intrinsic, "/"); | |
3041 | @end smallexample | |
7cd4527e | 3042 | |
88e1739c | 3043 | @noindent |
7cd4527e AC |
3044 | This common idiom is often programmed with a generic definition and an |
3045 | explicit body. The pragma makes it simpler to introduce such declarations. | |
3046 | It incurs no overhead in compilation time or code size, because it is | |
3047 | implemented as a single machine instruction. | |
88e1739c FW |
3048 | @end itemize |
3049 | @noindent | |
3050 | ||
7cd4527e | 3051 | @ifset unw |
88e1739c FW |
3052 | @findex Stdcall |
3053 | @cindex Convention Stdcall | |
7cd4527e AC |
3054 | @item Stdcall |
3055 | This is relevant only to NT/Win95 implementations of GNAT, | |
88e1739c FW |
3056 | and specifies that the Stdcall calling sequence will be used, as defined |
3057 | by the NT API. | |
3058 | ||
3059 | @findex DLL | |
3060 | @cindex Convention DLL | |
7cd4527e AC |
3061 | @item DLL |
3062 | This is equivalent to Stdcall. | |
88e1739c FW |
3063 | |
3064 | @findex Win32 | |
3065 | @cindex Convention Win32 | |
7cd4527e AC |
3066 | @item Win32 |
3067 | This is equivalent to Stdcall. | |
3068 | @end ifset | |
88e1739c FW |
3069 | |
3070 | @findex Stubbed | |
3071 | @cindex Convention Stubbed | |
7cd4527e AC |
3072 | @item Stubbed |
3073 | This is a special convention that indicates that the compiler | |
88e1739c | 3074 | should provide a stub body that raises @code{Program_Error}. |
7cd4527e | 3075 | @end table |
88e1739c FW |
3076 | |
3077 | @noindent | |
3078 | GNAT additionally provides a useful pragma @code{Convention_Identifier} | |
3079 | that can be used to parametrize conventions and allow additional synonyms | |
3080 | to be specified. For example if you have legacy code in which the convention | |
3081 | identifier Fortran77 was used for Fortran, you can use the configuration | |
3082 | pragma: | |
3083 | ||
7cd4527e AC |
3084 | @smallexample @c ada |
3085 | pragma Convention_Identifier (Fortran77, Fortran); | |
88e1739c FW |
3086 | @end smallexample |
3087 | ||
3088 | @noindent | |
3089 | And from now on the identifier Fortran77 may be used as a convention | |
3090 | identifier (for example in an @code{Import} pragma) with the same | |
3091 | meaning as Fortran. | |
3092 | ||
3093 | @node Building Mixed Ada & C++ Programs | |
3094 | @section Building Mixed Ada & C++ Programs | |
3095 | ||
3096 | @noindent | |
7cd4527e AC |
3097 | A programmer inexperienced with mixed-language development may find that |
3098 | building an application containing both Ada and C++ code can be a | |
3099 | challenge. As a matter of fact, interfacing with C++ has not been | |
3100 | standardized in the Ada 95 Reference Manual due to the immaturity of -- | |
3101 | and lack of standards for -- C++ at the time. This section gives a few | |
3102 | hints that should make this task easier. The first section addresses | |
3103 | the differences regarding interfacing with C. The second section | |
3104 | looks into the delicate problem of linking the complete application from | |
3105 | its Ada and C++ parts. The last section gives some hints on how the GNAT | |
3106 | run time can be adapted in order to allow inter-language dispatching | |
3107 | with a new C++ compiler. | |
88e1739c FW |
3108 | |
3109 | @menu | |
3110 | * Interfacing to C++:: | |
3111 | * Linking a Mixed C++ & Ada Program:: | |
3112 | * A Simple Example:: | |
3113 | * Adapting the Run Time to a New C++ Compiler:: | |
3114 | @end menu | |
3115 | ||
3116 | @node Interfacing to C++ | |
3117 | @subsection Interfacing to C++ | |
3118 | ||
3119 | @noindent | |
3120 | GNAT supports interfacing with C++ compilers generating code that is | |
3121 | compatible with the standard Application Binary Interface of the given | |
3122 | platform. | |
3123 | ||
3124 | @noindent | |
7cd4527e AC |
3125 | Interfacing can be done at 3 levels: simple data, subprograms, and |
3126 | classes. In the first two cases, GNAT offers a specific @var{Convention | |
3127 | CPP} that behaves exactly like @var{Convention C}. Usually, C++ mangles | |
3128 | the names of subprograms, and currently, GNAT does not provide any help | |
3129 | to solve the demangling problem. This problem can be addressed in two | |
3130 | ways: | |
88e1739c FW |
3131 | @itemize @bullet |
3132 | @item | |
3133 | by modifying the C++ code in order to force a C convention using | |
7cd4527e | 3134 | the @code{extern "C"} syntax. |
88e1739c FW |
3135 | |
3136 | @item | |
3137 | by figuring out the mangled name and use it as the Link_Name argument of | |
3138 | the pragma import. | |
3139 | @end itemize | |
3140 | ||
3141 | @noindent | |
3142 | Interfacing at the class level can be achieved by using the GNAT specific | |
3143 | pragmas such as @code{CPP_Class} and @code{CPP_Virtual}. See the GNAT | |
3144 | Reference Manual for additional information. | |
3145 | ||
3146 | @node Linking a Mixed C++ & Ada Program | |
3147 | @subsection Linking a Mixed C++ & Ada Program | |
3148 | ||
3149 | @noindent | |
3150 | Usually the linker of the C++ development system must be used to link | |
3151 | mixed applications because most C++ systems will resolve elaboration | |
3152 | issues (such as calling constructors on global class instances) | |
3153 | transparently during the link phase. GNAT has been adapted to ease the | |
3154 | use of a foreign linker for the last phase. Three cases can be | |
3155 | considered: | |
3156 | @enumerate | |
3157 | ||
3158 | @item | |
7cd4527e AC |
3159 | Using GNAT and G++ (GNU C++ compiler) from the same GCC installation: |
3160 | The C++ linker can simply be called by using the C++ specific driver | |
3161 | called @code{c++}. Note that this setup is not very common because it | |
3162 | may involve recompiling the whole GCC tree from sources, which makes it | |
3163 | harder to upgrade the compilation system for one language without | |
3164 | destabilizing the other. | |
88e1739c FW |
3165 | |
3166 | @smallexample | |
3167 | $ c++ -c file1.C | |
3168 | $ c++ -c file2.C | |
3169 | $ gnatmake ada_unit -largs file1.o file2.o --LINK=c++ | |
3170 | @end smallexample | |
3171 | ||
3172 | @item | |
7cd4527e AC |
3173 | Using GNAT and G++ from two different GCC installations: If both |
3174 | compilers are on the PATH, the previous method may be used. It is | |
3175 | important to note that environment variables such as C_INCLUDE_PATH, | |
3176 | GCC_EXEC_PREFIX, BINUTILS_ROOT, and GCC_ROOT will affect both compilers | |
3177 | at the same time and may make one of the two compilers operate | |
3178 | improperly if set during invocation of the wrong compiler. It is also | |
3179 | very important that the linker uses the proper @file{libgcc.a} GCC | |
3180 | library -- that is, the one from the C++ compiler installation. The | |
3181 | implicit link command as suggested in the gnatmake command from the | |
3182 | former example can be replaced by an explicit link command with the | |
3183 | full-verbosity option in order to verify which library is used: | |
88e1739c FW |
3184 | @smallexample |
3185 | $ gnatbind ada_unit | |
3186 | $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ | |
3187 | @end smallexample | |
3188 | If there is a problem due to interfering environment variables, it can | |
7cd4527e | 3189 | be worked around by using an intermediate script. The following example |
88e1739c FW |
3190 | shows the proper script to use when GNAT has not been installed at its |
3191 | default location and g++ has been installed at its default location: | |
3192 | ||
3193 | @smallexample | |
88e1739c FW |
3194 | $ cat ./my_script |
3195 | #!/bin/sh | |
3196 | unset BINUTILS_ROOT | |
3197 | unset GCC_ROOT | |
3198 | c++ $* | |
7cd4527e | 3199 | $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script |
88e1739c FW |
3200 | @end smallexample |
3201 | ||
3202 | @item | |
7cd4527e AC |
3203 | Using a non-GNU C++ compiler: The commands previously described can be |
3204 | used to insure that the C++ linker is used. Nonetheless, you need to add | |
3205 | the path to libgcc explicitly, since some libraries needed by GNAT are | |
3206 | located in this directory: | |
88e1739c FW |
3207 | |
3208 | @smallexample | |
88e1739c FW |
3209 | $ cat ./my_script |
3210 | #!/bin/sh | |
3211 | CC $* `gcc -print-libgcc-file-name` | |
7cd4527e | 3212 | $ gnatlink ada_unit file1.o file2.o --LINK=./my_script |
88e1739c FW |
3213 | @end smallexample |
3214 | ||
7cd4527e | 3215 | Where CC is the name of the non-GNU C++ compiler. |
88e1739c FW |
3216 | |
3217 | @end enumerate | |
3218 | ||
3219 | @node A Simple Example | |
3220 | @subsection A Simple Example | |
3221 | @noindent | |
7cd4527e | 3222 | The following example, provided as part of the GNAT examples, shows how |
88e1739c | 3223 | to achieve procedural interfacing between Ada and C++ in both |
7cd4527e | 3224 | directions. The C++ class A has two methods. The first method is exported |
88e1739c | 3225 | to Ada by the means of an extern C wrapper function. The second method |
7cd4527e | 3226 | calls an Ada subprogram. On the Ada side, The C++ calls are modelled by |
88e1739c | 3227 | a limited record with a layout comparable to the C++ class. The Ada |
7cd4527e AC |
3228 | subprogram, in turn, calls the C++ method. So, starting from the C++ |
3229 | main program, the process passes back and forth between the two | |
3230 | languages. | |
88e1739c FW |
3231 | |
3232 | @noindent | |
7cd4527e | 3233 | Here are the compilation commands: |
88e1739c FW |
3234 | @smallexample |
3235 | $ gnatmake -c simple_cpp_interface | |
3236 | $ c++ -c cpp_main.C | |
3237 | $ c++ -c ex7.C | |
3238 | $ gnatbind -n simple_cpp_interface | |
3239 | $ gnatlink simple_cpp_interface -o cpp_main --LINK=$(CPLUSPLUS) | |
3240 | -lstdc++ ex7.o cpp_main.o | |
3241 | @end smallexample | |
7cd4527e | 3242 | |
88e1739c FW |
3243 | @noindent |
3244 | Here are the corresponding sources: | |
3245 | @smallexample | |
3246 | ||
3247 | //cpp_main.C | |
3248 | ||
3249 | #include "ex7.h" | |
3250 | ||
3251 | extern "C" @{ | |
3252 | void adainit (void); | |
3253 | void adafinal (void); | |
3254 | void method1 (A *t); | |
3255 | @} | |
3256 | ||
3257 | void method1 (A *t) | |
3258 | @{ | |
3259 | t->method1 (); | |
3260 | @} | |
3261 | ||
3262 | int main () | |
3263 | @{ | |
3264 | A obj; | |
3265 | adainit (); | |
3266 | obj.method2 (3030); | |
3267 | adafinal (); | |
3268 | @} | |
3269 | ||
3270 | //ex7.h | |
3271 | ||
3272 | class Origin @{ | |
3273 | public: | |
3274 | int o_value; | |
3275 | @}; | |
3276 | class A : public Origin @{ | |
3277 | public: | |
3278 | void method1 (void); | |
3279 | virtual void method2 (int v); | |
3280 | A(); | |
3281 | int a_value; | |
3282 | @}; | |
3283 | ||
3284 | //ex7.C | |
3285 | ||
3286 | #include "ex7.h" | |
3287 | #include <stdio.h> | |
3288 | ||
3289 | extern "C" @{ void ada_method2 (A *t, int v);@} | |
3290 | ||
3291 | void A::method1 (void) | |
3292 | @{ | |
3293 | a_value = 2020; | |
3294 | printf ("in A::method1, a_value = %d \n",a_value); | |
3295 | ||
3296 | @} | |
3297 | ||
3298 | void A::method2 (int v) | |
3299 | @{ | |
3300 | ada_method2 (this, v); | |
3301 | printf ("in A::method2, a_value = %d \n",a_value); | |
3302 | ||
3303 | @} | |
3304 | ||
3305 | A::A(void) | |
3306 | @{ | |
3307 | a_value = 1010; | |
3308 | printf ("in A::A, a_value = %d \n",a_value); | |
3309 | @} | |
3310 | ||
3311 | -- Ada sources | |
3312 | @b{package} @b{body} Simple_Cpp_Interface @b{is} | |
3313 | ||
3314 | @b{procedure} Ada_Method2 (This : @b{in} @b{out} A; V : Integer) @b{is} | |
3315 | @b{begin} | |
3316 | Method1 (This); | |
3317 | This.A_Value := V; | |
3318 | @b{end} Ada_Method2; | |
3319 | ||
3320 | @b{end} Simple_Cpp_Interface; | |
3321 | ||
3322 | @b{package} Simple_Cpp_Interface @b{is} | |
3323 | @b{type} A @b{is} @b{limited} | |
3324 | @b{record} | |
3325 | O_Value : Integer; | |
3326 | A_Value : Integer; | |
3327 | @b{end} @b{record}; | |
3328 | @b{pragma} Convention (C, A); | |
3329 | ||
3330 | @b{procedure} Method1 (This : @b{in} @b{out} A); | |
3331 | @b{pragma} Import (C, Method1); | |
3332 | ||
3333 | @b{procedure} Ada_Method2 (This : @b{in} @b{out} A; V : Integer); | |
3334 | @b{pragma} Export (C, Ada_Method2); | |
3335 | ||
3336 | @b{end} Simple_Cpp_Interface; | |
3337 | @end smallexample | |
3338 | ||
3339 | @node Adapting the Run Time to a New C++ Compiler | |
3340 | @subsection Adapting the Run Time to a New C++ Compiler | |
3341 | @noindent | |
3342 | GNAT offers the capability to derive Ada 95 tagged types directly from | |
7cd4527e AC |
3343 | preexisting C++ classes and . See ``Interfacing with C++'' in the |
3344 | @cite{GNAT Reference Manual}. The mechanism used by GNAT for achieving | |
3345 | such a goal | |
88e1739c FW |
3346 | has been made user configurable through a GNAT library unit |
3347 | @code{Interfaces.CPP}. The default version of this file is adapted to | |
7cd4527e | 3348 | the GNU C++ compiler. Internal knowledge of the virtual |
88e1739c FW |
3349 | table layout used by the new C++ compiler is needed to configure |
3350 | properly this unit. The Interface of this unit is known by the compiler | |
3351 | and cannot be changed except for the value of the constants defining the | |
3352 | characteristics of the virtual table: CPP_DT_Prologue_Size, CPP_DT_Entry_Size, | |
3353 | CPP_TSD_Prologue_Size, CPP_TSD_Entry_Size. Read comments in the source | |
3354 | of this unit for more details. | |
3355 | ||
3356 | @node Comparison between GNAT and C/C++ Compilation Models | |
3357 | @section Comparison between GNAT and C/C++ Compilation Models | |
3358 | ||
3359 | @noindent | |
3360 | The GNAT model of compilation is close to the C and C++ models. You can | |
3361 | think of Ada specs as corresponding to header files in C. As in C, you | |
3362 | don't need to compile specs; they are compiled when they are used. The | |
3363 | Ada @code{with} is similar in effect to the @code{#include} of a C | |
3364 | header. | |
3365 | ||
3366 | One notable difference is that, in Ada, you may compile specs separately | |
3367 | to check them for semantic and syntactic accuracy. This is not always | |
3368 | possible with C headers because they are fragments of programs that have | |
3369 | less specific syntactic or semantic rules. | |
3370 | ||
3371 | The other major difference is the requirement for running the binder, | |
3372 | which performs two important functions. First, it checks for | |
3373 | consistency. In C or C++, the only defense against assembling | |
3374 | inconsistent programs lies outside the compiler, in a makefile, for | |
3375 | example. The binder satisfies the Ada requirement that it be impossible | |
3376 | to construct an inconsistent program when the compiler is used in normal | |
3377 | mode. | |
3378 | ||
3379 | @cindex Elaboration order control | |
3380 | The other important function of the binder is to deal with elaboration | |
3381 | issues. There are also elaboration issues in C++ that are handled | |
3382 | automatically. This automatic handling has the advantage of being | |
3383 | simpler to use, but the C++ programmer has no control over elaboration. | |
3384 | Where @code{gnatbind} might complain there was no valid order of | |
3385 | elaboration, a C++ compiler would simply construct a program that | |
3386 | malfunctioned at run time. | |
3387 | ||
3388 | @node Comparison between GNAT and Conventional Ada Library Models | |
3389 | @section Comparison between GNAT and Conventional Ada Library Models | |
3390 | ||
3391 | @noindent | |
3392 | This section is intended to be useful to Ada programmers who have | |
3393 | previously used an Ada compiler implementing the traditional Ada library | |
3394 | model, as described in the Ada 95 Language Reference Manual. If you | |
3395 | have not used such a system, please go on to the next section. | |
3396 | ||
3397 | @cindex GNAT library | |
3398 | In GNAT, there is no @dfn{library} in the normal sense. Instead, the set of | |
3399 | source files themselves acts as the library. Compiling Ada programs does | |
3400 | not generate any centralized information, but rather an object file and | |
3401 | a ALI file, which are of interest only to the binder and linker. | |
3402 | In a traditional system, the compiler reads information not only from | |
3403 | the source file being compiled, but also from the centralized library. | |
3404 | This means that the effect of a compilation depends on what has been | |
3405 | previously compiled. In particular: | |
3406 | ||
3407 | @itemize @bullet | |
3408 | @item | |
3409 | When a unit is @code{with}'ed, the unit seen by the compiler corresponds | |
3410 | to the version of the unit most recently compiled into the library. | |
3411 | ||
3412 | @item | |
3413 | Inlining is effective only if the necessary body has already been | |
3414 | compiled into the library. | |
3415 | ||
3416 | @item | |
3417 | Compiling a unit may obsolete other units in the library. | |
3418 | @end itemize | |
3419 | ||
3420 | @noindent | |
3421 | In GNAT, compiling one unit never affects the compilation of any other | |
3422 | units because the compiler reads only source files. Only changes to source | |
3423 | files can affect the results of a compilation. In particular: | |
3424 | ||
3425 | @itemize @bullet | |
3426 | @item | |
3427 | When a unit is @code{with}'ed, the unit seen by the compiler corresponds | |
3428 | to the source version of the unit that is currently accessible to the | |
3429 | compiler. | |
3430 | ||
3431 | @item | |
3432 | @cindex Inlining | |
3433 | Inlining requires the appropriate source files for the package or | |
3434 | subprogram bodies to be available to the compiler. Inlining is always | |
3435 | effective, independent of the order in which units are complied. | |
3436 | ||
3437 | @item | |
3438 | Compiling a unit never affects any other compilations. The editing of | |
3439 | sources may cause previous compilations to be out of date if they | |
3440 | depended on the source file being modified. | |
3441 | @end itemize | |
3442 | ||
3443 | @noindent | |
3444 | The most important result of these differences is that order of compilation | |
3445 | is never significant in GNAT. There is no situation in which one is | |
3446 | required to do one compilation before another. What shows up as order of | |
3447 | compilation requirements in the traditional Ada library becomes, in | |
3448 | GNAT, simple source dependencies; in other words, there is only a set | |
3449 | of rules saying what source files must be present when a file is | |
3450 | compiled. | |
3451 | ||
7cd4527e AC |
3452 | @ifset vms |
3453 | @node Placement of temporary files | |
3454 | @section Placement of temporary files | |
3455 | @cindex Temporary files (user control over placement) | |
3456 | ||
3457 | @noindent | |
3458 | GNAT creates temporary files in the directory designated by the environment | |
3459 | variable @env{TMPDIR}. | |
3460 | (See the HP @emph{C RTL Reference Manual} on the function @code{getenv()} | |
3461 | for detailed information on how environment variables are resolved. | |
3462 | For most users the easiest way to make use of this feature is to simply | |
3463 | define @env{TMPDIR} as a job level logical name). | |
3464 | For example, if you wish to use a Ramdisk (assuming DECRAM is installed) | |
3465 | for compiler temporary files, then you can include something like the | |
3466 | following command in your @file{LOGIN.COM} file: | |
3467 | ||
3468 | @smallexample | |
3469 | $ define/job TMPDIR "/disk$scratchram/000000/temp/" | |
3470 | @end smallexample | |
3471 | ||
3472 | @noindent | |
3473 | If @env{TMPDIR} is not defined, then GNAT uses the directory designated by | |
3474 | @env{TMP}; if @env{TMP} is not defined, then GNAT uses the directory | |
3475 | designated by @env{TEMP}. | |
3476 | If none of these environment variables are defined then GNAT uses the | |
3477 | directory designated by the logical name @code{SYS$SCRATCH:} | |
3478 | (by default the user's home directory). If all else fails | |
3479 | GNAT uses the current directory for temporary files. | |
3480 | @end ifset | |
3481 | ||
3482 | ||
3483 | @c ************************* | |
88e1739c FW |
3484 | @node Compiling Using gcc |
3485 | @chapter Compiling Using @code{gcc} | |
3486 | ||
3487 | @noindent | |
3488 | This chapter discusses how to compile Ada programs using the @code{gcc} | |
3489 | command. It also describes the set of switches | |
3490 | that can be used to control the behavior of the compiler. | |
3491 | @menu | |
3492 | * Compiling Programs:: | |
3493 | * Switches for gcc:: | |
3494 | * Search Paths and the Run-Time Library (RTL):: | |
3495 | * Order of Compilation Issues:: | |
3496 | * Examples:: | |
3497 | @end menu | |
3498 | ||
3499 | @node Compiling Programs | |
3500 | @section Compiling Programs | |
3501 | ||
3502 | @noindent | |
3503 | The first step in creating an executable program is to compile the units | |
3504 | of the program using the @code{gcc} command. You must compile the | |
3505 | following files: | |
3506 | ||
3507 | @itemize @bullet | |
3508 | @item | |
3509 | the body file (@file{.adb}) for a library level subprogram or generic | |
3510 | subprogram | |
3511 | ||
3512 | @item | |
3513 | the spec file (@file{.ads}) for a library level package or generic | |
3514 | package that has no body | |
3515 | ||
3516 | @item | |
3517 | the body file (@file{.adb}) for a library level package | |
3518 | or generic package that has a body | |
3519 | ||
3520 | @end itemize | |
3521 | ||
3522 | @noindent | |
3523 | You need @emph{not} compile the following files | |
3524 | ||
3525 | @itemize @bullet | |
3526 | ||
3527 | @item | |
3528 | the spec of a library unit which has a body | |
3529 | ||
3530 | @item | |
3531 | subunits | |
3532 | @end itemize | |
3533 | ||
3534 | @noindent | |
3535 | because they are compiled as part of compiling related units. GNAT | |
3536 | package specs | |
3537 | when the corresponding body is compiled, and subunits when the parent is | |
3538 | compiled. | |
7cd4527e AC |
3539 | |
3540 | @cindex cannot generate code | |
88e1739c FW |
3541 | If you attempt to compile any of these files, you will get one of the |
3542 | following error messages (where fff is the name of the file you compiled): | |
3543 | ||
3544 | @smallexample | |
7cd4527e AC |
3545 | cannot generate code for file @var{fff} (package spec) |
3546 | to check package spec, use -gnatc | |
3547 | ||
3548 | cannot generate code for file @var{fff} (missing subunits) | |
3549 | to check parent unit, use -gnatc | |
3550 | ||
3551 | cannot generate code for file @var{fff} (subprogram spec) | |
3552 | to check subprogram spec, use -gnatc | |
3553 | ||
3554 | cannot generate code for file @var{fff} (subunit) | |
3555 | to check subunit, use -gnatc | |
88e1739c FW |
3556 | @end smallexample |
3557 | ||
3558 | @noindent | |
7cd4527e AC |
3559 | As indicated by the above error messages, if you want to submit |
3560 | one of these files to the compiler to check for correct semantics | |
3561 | without generating code, then use the @option{-gnatc} switch. | |
3562 | ||
88e1739c FW |
3563 | The basic command for compiling a file containing an Ada unit is |
3564 | ||
3565 | @smallexample | |
3566 | $ gcc -c [@var{switches}] @file{file name} | |
3567 | @end smallexample | |
3568 | ||
3569 | @noindent | |
3570 | where @var{file name} is the name of the Ada file (usually | |
3571 | having an extension | |
3572 | @file{.ads} for a spec or @file{.adb} for a body). | |
3573 | @ifclear vms | |
3574 | You specify the | |
7cd4527e | 3575 | @option{-c} switch to tell @code{gcc} to compile, but not link, the file. |
88e1739c FW |
3576 | @end ifclear |
3577 | The result of a successful compilation is an object file, which has the | |
3578 | same name as the source file but an extension of @file{.o} and an Ada | |
3579 | Library Information (ALI) file, which also has the same name as the | |
3580 | source file, but with @file{.ali} as the extension. GNAT creates these | |
3581 | two output files in the current directory, but you may specify a source | |
3582 | file in any directory using an absolute or relative path specification | |
3583 | containing the directory information. | |
3584 | ||
3585 | @findex gnat1 | |
3586 | @code{gcc} is actually a driver program that looks at the extensions of | |
3587 | the file arguments and loads the appropriate compiler. For example, the | |
3588 | GNU C compiler is @file{cc1}, and the Ada compiler is @file{gnat1}. | |
3589 | These programs are in directories known to the driver program (in some | |
3590 | configurations via environment variables you set), but need not be in | |
3591 | your path. The @code{gcc} driver also calls the assembler and any other | |
3592 | utilities needed to complete the generation of the required object | |
3593 | files. | |
3594 | ||
3595 | It is possible to supply several file names on the same @code{gcc} | |
3596 | command. This causes @code{gcc} to call the appropriate compiler for | |
3597 | each file. For example, the following command lists three separate | |
3598 | files to be compiled: | |
3599 | ||
3600 | @smallexample | |
3601 | $ gcc -c x.adb y.adb z.c | |
3602 | @end smallexample | |
3603 | ||
3604 | @noindent | |
3605 | calls @code{gnat1} (the Ada compiler) twice to compile @file{x.adb} and | |
3606 | @file{y.adb}, and @code{cc1} (the C compiler) once to compile @file{z.c}. | |
3607 | The compiler generates three object files @file{x.o}, @file{y.o} and | |
3608 | @file{z.o} and the two ALI files @file{x.ali} and @file{y.ali} from the | |
3609 | Ada compilations. Any switches apply to all the files ^listed,^listed.^ | |
3610 | @ifclear vms | |
3611 | except for | |
3612 | @option{-gnat@var{x}} switches, which apply only to Ada compilations. | |
3613 | @end ifclear | |
3614 | ||
3615 | @node Switches for gcc | |
3616 | @section Switches for @code{gcc} | |
3617 | ||
3618 | @noindent | |
3619 | The @code{gcc} command accepts switches that control the | |
3620 | compilation process. These switches are fully described in this section. | |
3621 | First we briefly list all the switches, in alphabetical order, then we | |
3622 | describe the switches in more detail in functionally grouped sections. | |
3623 | ||
3624 | @menu | |
3625 | * Output and Error Message Control:: | |
7cd4527e | 3626 | * Warning Message Control:: |
88e1739c FW |
3627 | * Debugging and Assertion Control:: |
3628 | * Run-Time Checks:: | |
3629 | * Stack Overflow Checking:: | |
88e1739c FW |
3630 | * Validity Checking:: |
3631 | * Style Checking:: | |
3632 | * Using gcc for Syntax Checking:: | |
3633 | * Using gcc for Semantic Checking:: | |
3634 | * Compiling Ada 83 Programs:: | |
3635 | * Character Set Control:: | |
3636 | * File Naming Control:: | |
3637 | * Subprogram Inlining Control:: | |
3638 | * Auxiliary Output Control:: | |
3639 | * Debugging Control:: | |
7cd4527e | 3640 | * Exception Handling Control:: |
88e1739c | 3641 | * Units to Sources Mapping Files:: |
7cd4527e AC |
3642 | * Integrated Preprocessing:: |
3643 | @ifset vms | |
3644 | * Return Codes:: | |
3645 | @end ifset | |
88e1739c FW |
3646 | @end menu |
3647 | ||
7cd4527e AC |
3648 | @table @option |
3649 | @c !sort! | |
88e1739c | 3650 | @ifclear vms |
7cd4527e | 3651 | @cindex @option{-b} (@code{gcc}) |
88e1739c FW |
3652 | @item -b @var{target} |
3653 | Compile your program to run on @var{target}, which is the name of a | |
3654 | system configuration. You must have a GNAT cross-compiler built if | |
3655 | @var{target} is not the same as your host system. | |
3656 | ||
3657 | @item -B@var{dir} | |
7cd4527e | 3658 | @cindex @option{-B} (@code{gcc}) |
88e1739c FW |
3659 | Load compiler executables (for example, @code{gnat1}, the Ada compiler) |
3660 | from @var{dir} instead of the default location. Only use this switch | |
3661 | when multiple versions of the GNAT compiler are available. See the | |
3662 | @code{gcc} manual page for further details. You would normally use the | |
7cd4527e | 3663 | @option{-b} or @option{-V} switch instead. |
88e1739c FW |
3664 | |
3665 | @item -c | |
7cd4527e | 3666 | @cindex @option{-c} (@code{gcc}) |
88e1739c FW |
3667 | Compile. Always use this switch when compiling Ada programs. |
3668 | ||
3669 | Note: for some other languages when using @code{gcc}, notably in | |
3670 | the case of C and C++, it is possible to use | |
7cd4527e | 3671 | use @code{gcc} without a @option{-c} switch to |
88e1739c FW |
3672 | compile and link in one step. In the case of GNAT, you |
3673 | cannot use this approach, because the binder must be run | |
3674 | and @code{gcc} cannot be used to run the GNAT binder. | |
3675 | @end ifclear | |
3676 | ||
7cd4527e AC |
3677 | @item -fno-inline |
3678 | @cindex @option{-fno-inline} (@code{gcc}) | |
3679 | Suppresses all back-end inlining, even if other optimization or inlining | |
3680 | switches are set. | |
3681 | This includes suppression of inlining that results | |
3682 | from the use of the pragma @code{Inline_Always}. | |
3683 | See also @option{-gnatn} and @option{-gnatN}. | |
3684 | ||
3685 | @item -fno-strict-aliasing | |
3686 | @cindex @option{-fno-strict-aliasing} (@code{gcc}) | |
3687 | Causes the compiler to avoid assumptions regarding non-aliasing | |
3688 | of objects of different types. See section | |
3689 | @pxref{Optimization and Strict Aliasing} for details. | |
3690 | ||
3691 | @item -fstack-check | |
3692 | @cindex @option{-fstack-check} (@code{gcc}) | |
3693 | Activates stack checking. | |
3694 | See @ref{Stack Overflow Checking} for details of the use of this option. | |
3695 | ||
88e1739c | 3696 | @item ^-g^/DEBUG^ |
7cd4527e | 3697 | @cindex @option{^-g^/DEBUG^} (@code{gcc}) |
88e1739c FW |
3698 | Generate debugging information. This information is stored in the object |
3699 | file and copied from there to the final executable file by the linker, | |
3700 | where it can be read by the debugger. You must use the | |
7cd4527e | 3701 | @option{^-g^/DEBUG^} switch if you plan on using the debugger. |
88e1739c | 3702 | |
7cd4527e AC |
3703 | @item -gnat83 |
3704 | @cindex @option{-gnat83} (@code{gcc}) | |
3705 | Enforce Ada 83 restrictions. | |
88e1739c FW |
3706 | |
3707 | @item -gnata | |
7cd4527e | 3708 | @cindex @option{-gnata} (@code{gcc}) |
88e1739c FW |
3709 | Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be |
3710 | activated. | |
3711 | ||
3712 | @item -gnatA | |
7cd4527e AC |
3713 | @cindex @option{-gnatA} (@code{gcc}) |
3714 | Avoid processing @file{gnat.adc}. If a gnat.adc file is present, | |
3715 | it will be ignored. | |
88e1739c FW |
3716 | |
3717 | @item -gnatb | |
7cd4527e | 3718 | @cindex @option{-gnatb} (@code{gcc}) |
88e1739c FW |
3719 | Generate brief messages to @file{stderr} even if verbose mode set. |
3720 | ||
3721 | @item -gnatc | |
7cd4527e | 3722 | @cindex @option{-gnatc} (@code{gcc}) |
88e1739c FW |
3723 | Check syntax and semantics only (no code generation attempted). |
3724 | ||
7cd4527e AC |
3725 | @item -gnatd |
3726 | @cindex @option{-gnatd} (@code{gcc}) | |
3727 | Specify debug options for the compiler. The string of characters after | |
3728 | the @option{-gnatd} specify the specific debug options. The possible | |
3729 | characters are 0-9, a-z, A-Z, optionally preceded by a dot. See | |
3730 | compiler source file @file{debug.adb} for details of the implemented | |
3731 | debug options. Certain debug options are relevant to applications | |
3732 | programmers, and these are documented at appropriate points in this | |
3733 | users guide. | |
88e1739c FW |
3734 | |
3735 | @item -gnatD | |
7cd4527e AC |
3736 | @cindex @option{-gnatD} (@code{gcc}) |
3737 | Create expanded source files for source level debugging. This switch | |
3738 | also suppress generation of cross-reference information | |
3739 | (see @option{-gnatx}). | |
3740 | ||
3741 | @item -gnatec=@var{path} | |
3742 | @cindex @option{-gnatec} (@code{gcc}) | |
3743 | Specify a configuration pragma file | |
3744 | @ifclear vms | |
3745 | (the equal sign is optional) | |
3746 | @end ifclear | |
3747 | (see @ref{The Configuration Pragmas Files}). | |
3748 | ||
3749 | @item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value] | |
3750 | @cindex @option{-gnateD} (@code{gcc}) | |
3751 | Defines a symbol, associated with value, for preprocessing. | |
3752 | (see @ref{Integrated Preprocessing}) | |
3753 | ||
3754 | @item -gnatef | |
3755 | @cindex @option{-gnatef} (@code{gcc}) | |
3756 | Display full source path name in brief error messages. | |
88e1739c | 3757 | |
7cd4527e AC |
3758 | @item -gnatem=@var{path} |
3759 | @cindex @option{-gnatem} (@code{gcc}) | |
3760 | Specify a mapping file | |
3761 | @ifclear vms | |
3762 | (the equal sign is optional) | |
3763 | @end ifclear | |
3764 | (see @ref{Units to Sources Mapping Files}). | |
88e1739c | 3765 | |
7cd4527e AC |
3766 | @item -gnatep=@var{file} |
3767 | @cindex @option{-gnatep} (@code{gcc}) | |
3768 | Specify a preprocessing data file | |
3769 | @ifclear vms | |
3770 | (the equal sign is optional) | |
3771 | @end ifclear | |
3772 | (see @ref{Integrated Preprocessing}). | |
88e1739c FW |
3773 | |
3774 | @item -gnatE | |
7cd4527e | 3775 | @cindex @option{-gnatE} (@code{gcc}) |
88e1739c FW |
3776 | Full dynamic elaboration checks. |
3777 | ||
3778 | @item -gnatf | |
7cd4527e AC |
3779 | @cindex @option{-gnatf} (@code{gcc}) |
3780 | Full errors. Multiple errors per line, all undefined references, do not | |
3781 | attempt to suppress cascaded errors. | |
88e1739c FW |
3782 | |
3783 | @item -gnatF | |
7cd4527e | 3784 | @cindex @option{-gnatF} (@code{gcc}) |
88e1739c FW |
3785 | Externals names are folded to all uppercase. |
3786 | ||
3787 | @item -gnatg | |
7cd4527e | 3788 | @cindex @option{-gnatg} (@code{gcc}) |
88e1739c FW |
3789 | Internal GNAT implementation mode. This should not be used for |
3790 | applications programs, it is intended only for use by the compiler | |
3791 | and its run-time library. For documentation, see the GNAT sources. | |
7cd4527e AC |
3792 | Note that @option{-gnatg} implies @option{-gnatwu} so that warnings |
3793 | are generated on unreferenced entities, and all warnings are treated | |
3794 | as errors. | |
88e1739c FW |
3795 | |
3796 | @item -gnatG | |
7cd4527e | 3797 | @cindex @option{-gnatG} (@code{gcc}) |
88e1739c FW |
3798 | List generated expanded code in source form. |
3799 | ||
7cd4527e AC |
3800 | @item ^-gnath^/HELP^ |
3801 | @cindex @option{^-gnath^/HELP^} (@code{gcc}) | |
3802 | Output usage information. The output is written to @file{stdout}. | |
3803 | ||
88e1739c | 3804 | @item ^-gnati^/IDENTIFIER_CHARACTER_SET=^@var{c} |
7cd4527e | 3805 | @cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@code{gcc}) |
88e1739c FW |
3806 | Identifier character set |
3807 | @ifclear vms | |
3808 | (@var{c}=1/2/3/4/8/9/p/f/n/w). | |
3809 | @end ifclear | |
3810 | @ifset vms | |
3811 | For details of the possible selections for @var{c}, | |
3812 | see @xref{Character Set Control}. | |
3813 | @end ifset | |
3814 | ||
7cd4527e AC |
3815 | @item -gnatk=@var{n} |
3816 | @cindex @option{-gnatk} (@code{gcc}) | |
88e1739c FW |
3817 | Limit file names to @var{n} (1-999) characters ^(@code{k} = krunch)^^. |
3818 | ||
3819 | @item -gnatl | |
7cd4527e | 3820 | @cindex @option{-gnatl} (@code{gcc}) |
88e1739c FW |
3821 | Output full source listing with embedded error messages. |
3822 | ||
7cd4527e AC |
3823 | @item -gnatL |
3824 | @cindex @option{-gnatL} (@code{gcc}) | |
3825 | Use the longjmp/setjmp method for exception handling | |
3826 | ||
3827 | @item -gnatm=@var{n} | |
3828 | @cindex @option{-gnatm} (@code{gcc}) | |
3829 | Limit number of detected error or warning messages to @var{n} | |
3830 | where @var{n} is in the range 1..999_999. The default setting if | |
3831 | no switch is given is 9999. Compilation is terminated if this | |
3832 | limit is exceeded. | |
88e1739c FW |
3833 | |
3834 | @item -gnatn | |
7cd4527e AC |
3835 | @cindex @option{-gnatn} (@code{gcc}) |
3836 | Activate inlining for subprograms for which | |
3837 | pragma @code{inline} is specified. This inlining is performed | |
3838 | by the GCC back-end. | |
88e1739c FW |
3839 | |
3840 | @item -gnatN | |
7cd4527e AC |
3841 | @cindex @option{-gnatN} (@code{gcc}) |
3842 | Activate front end inlining for subprograms for which | |
3843 | pragma @code{Inline} is specified. This inlining is performed | |
3844 | by the front end and will be visible in the | |
3845 | @option{-gnatG} output. | |
3846 | In some cases, this has proved more effective than the back end | |
3847 | inlining resulting from the use of | |
3848 | @option{-gnatn}. | |
3849 | Note that | |
3850 | @option{-gnatN} automatically implies | |
3851 | @option{-gnatn} so it is not necessary | |
3852 | to specify both options. There are a few cases that the back-end inlining | |
3853 | catches that cannot be dealt with in the front-end. | |
88e1739c FW |
3854 | |
3855 | @item -gnato | |
7cd4527e | 3856 | @cindex @option{-gnato} (@code{gcc}) |
88e1739c FW |
3857 | Enable numeric overflow checking (which is not normally enabled by |
3858 | default). Not that division by zero is a separate check that is not | |
3859 | controlled by this switch (division by zero checking is on by default). | |
3860 | ||
3861 | @item -gnatp | |
7cd4527e | 3862 | @cindex @option{-gnatp} (@code{gcc}) |
88e1739c FW |
3863 | Suppress all checks. |
3864 | ||
88e1739c | 3865 | @item -gnatP |
7cd4527e | 3866 | @cindex @option{-gnatP} (@code{gcc}) |
88e1739c FW |
3867 | Enable polling. This is required on some systems (notably Windows NT) to |
3868 | obtain asynchronous abort and asynchronous transfer of control capability. | |
3869 | See the description of pragma Polling in the GNAT Reference Manual for | |
3870 | full details. | |
3871 | ||
7cd4527e AC |
3872 | @item -gnatq |
3873 | @cindex @option{-gnatq} (@code{gcc}) | |
3874 | Don't quit; try semantics, even if parse errors. | |
3875 | ||
3876 | @item -gnatQ | |
3877 | @cindex @option{-gnatQ} (@code{gcc}) | |
3878 | Don't quit; generate @file{ALI} and tree files even if illegalities. | |
3879 | ||
3880 | @item ^-gnatR[0/1/2/3[s]]^/REPRESENTATION_INFO^ | |
3881 | @cindex @option{-gnatR} (@code{gcc}) | |
88e1739c FW |
3882 | Output representation information for declared types and objects. |
3883 | ||
3884 | @item -gnats | |
7cd4527e | 3885 | @cindex @option{-gnats} (@code{gcc}) |
88e1739c FW |
3886 | Syntax check only. |
3887 | ||
7cd4527e AC |
3888 | @item -gnatS |
3889 | @cindex @option{-gnatS} (@code{gcc}) | |
3890 | Print package Standard. | |
3891 | ||
88e1739c | 3892 | @item -gnatt |
7cd4527e AC |
3893 | @cindex @option{-gnatt} (@code{gcc}) |
3894 | Generate tree output file. | |
88e1739c | 3895 | |
7cd4527e AC |
3896 | @item ^-gnatT^/TABLE_MULTIPLIER=^@var{nnn} |
3897 | @cindex @option{^-gnatT^/TABLE_MULTIPLIER^} (@code{gcc}) | |
3898 | All compiler tables start at @var{nnn} times usual starting size. | |
88e1739c FW |
3899 | |
3900 | @item -gnatu | |
7cd4527e | 3901 | @cindex @option{-gnatu} (@code{gcc}) |
88e1739c FW |
3902 | List units for this compilation. |
3903 | ||
3904 | @item -gnatU | |
7cd4527e AC |
3905 | @cindex @option{-gnatU} (@code{gcc}) |
3906 | Tag all error messages with the unique string ``error:'' | |
88e1739c FW |
3907 | |
3908 | @item -gnatv | |
7cd4527e | 3909 | @cindex @option{-gnatv} (@code{gcc}) |
88e1739c FW |
3910 | Verbose mode. Full error output with source lines to @file{stdout}. |
3911 | ||
3912 | @item -gnatV | |
7cd4527e | 3913 | @cindex @option{-gnatV} (@code{gcc}) |
88e1739c FW |
3914 | Control level of validity checking. See separate section describing |
3915 | this feature. | |
3916 | ||
7cd4527e AC |
3917 | @item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}[,...])^ |
3918 | @cindex @option{^-gnatw^/WARNINGS^} (@code{gcc}) | |
88e1739c | 3919 | Warning mode where |
7cd4527e AC |
3920 | ^@var{xxx} is a string of option letters that^the list of options^ denotes |
3921 | the exact warnings that | |
3922 | are enabled or disabled. (see @ref{Warning Message Control}) | |
88e1739c FW |
3923 | |
3924 | @item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e} | |
7cd4527e | 3925 | @cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@code{gcc}) |
88e1739c FW |
3926 | Wide character encoding method |
3927 | @ifclear vms | |
3928 | (@var{e}=n/h/u/s/e/8). | |
3929 | @end ifclear | |
3930 | @ifset vms | |
3931 | (@var{e}=@code{BRACKETS, NONE, HEX, UPPER, SHIFT_JIS, EUC, UTF8}) | |
3932 | @end ifset | |
3933 | ||
3934 | @item -gnatx | |
7cd4527e | 3935 | @cindex @option{-gnatx} (@code{gcc}) |
88e1739c FW |
3936 | Suppress generation of cross-reference information. |
3937 | ||
3938 | @item ^-gnaty^/STYLE_CHECKS=(option,option..)^ | |
7cd4527e AC |
3939 | @cindex @option{^-gnaty^/STYLE_CHECKS^} (@code{gcc}) |
3940 | Enable built-in style checks. (see @ref{Style Checking}) | |
88e1739c FW |
3941 | |
3942 | @item ^-gnatz^/DISTRIBUTION_STUBS=^@var{m} | |
7cd4527e | 3943 | @cindex @option{^-gnatz^/DISTRIBUTION_STUBS^} (@code{gcc}) |
88e1739c FW |
3944 | Distribution stub generation and compilation |
3945 | @ifclear vms | |
3946 | (@var{m}=r/c for receiver/caller stubs). | |
3947 | @end ifclear | |
3948 | @ifset vms | |
3949 | (@var{m}=@code{RECEIVER} or @code{CALLER} to specify the type of stubs | |
3950 | to be generated and compiled). | |
3951 | @end ifset | |
3952 | ||
7cd4527e AC |
3953 | @item -gnatZ |
3954 | Use the zero cost method for exception handling | |
3955 | ||
3956 | @item ^-I^/SEARCH=^@var{dir} | |
3957 | @cindex @option{^-I^/SEARCH^} (@code{gcc}) | |
3958 | @cindex RTL | |
3959 | Direct GNAT to search the @var{dir} directory for source files needed by | |
3960 | the current compilation | |
3961 | (@pxref{Search Paths and the Run-Time Library (RTL)}). | |
3962 | ||
3963 | @item ^-I-^/NOCURRENT_DIRECTORY^ | |
3964 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gcc}) | |
3965 | @cindex RTL | |
3966 | Except for the source file named in the command line, do not look for source | |
3967 | files in the directory containing the source file named in the command line | |
3968 | (@pxref{Search Paths and the Run-Time Library (RTL)}). | |
88e1739c FW |
3969 | |
3970 | @ifclear vms | |
7cd4527e AC |
3971 | @item -mbig-switch |
3972 | @cindex @option{-mbig-switch} (@command{gcc}) | |
3973 | @cindex @code{case} statement (effect of @option{-mbig-switch} option) | |
3974 | This standard gcc switch causes the compiler to use larger offsets in its | |
3975 | jump table representation for @code{case} statements. | |
3976 | This may result in less efficient code, but is sometimes necessary | |
3977 | (for example on HP-UX targets) | |
3978 | @cindex HP-UX and @option{-mbig-switch} option | |
3979 | in order to compile large and/or nested @code{case} statements. | |
3980 | ||
3981 | @item -o @var{file} | |
3982 | @cindex @option{-o} (@code{gcc}) | |
3983 | This switch is used in @code{gcc} to redirect the generated object file | |
3984 | and its associated ALI file. Beware of this switch with GNAT, because it may | |
3985 | cause the object file and ALI file to have different names which in turn | |
3986 | may confuse the binder and the linker. | |
88e1739c | 3987 | @end ifclear |
7cd4527e AC |
3988 | |
3989 | @item -nostdinc | |
3990 | @cindex @option{-nostdinc} (@command{gcc}) | |
3991 | Inhibit the search of the default location for the GNAT Run Time | |
3992 | Library (RTL) source files. | |
3993 | ||
3994 | @item -nostdlib | |
3995 | @cindex @option{-nostdlib} (@command{gcc}) | |
3996 | Inhibit the search of the default location for the GNAT Run Time | |
3997 | Library (RTL) ALI files. | |
88e1739c FW |
3998 | |
3999 | @ifclear vms | |
7cd4527e AC |
4000 | @item -O[@var{n}] |
4001 | @cindex @option{-O} (@code{gcc}) | |
4002 | @var{n} controls the optimization level. | |
88e1739c | 4003 | |
7cd4527e AC |
4004 | @table @asis |
4005 | @item n = 0 | |
4006 | No optimization, the default setting if no @option{-O} appears | |
88e1739c | 4007 | |
7cd4527e AC |
4008 | @item n = 1 |
4009 | Normal optimization, the default if you specify @option{-O} without | |
4010 | an operand. | |
88e1739c | 4011 | |
7cd4527e AC |
4012 | @item n = 2 |
4013 | Extensive optimization | |
88e1739c | 4014 | |
7cd4527e AC |
4015 | @item n = 3 |
4016 | Extensive optimization with automatic inlining of subprograms not | |
4017 | specified by pragma @code{Inline}. This applies only to | |
4018 | inlining within a unit. For details on control of inlining | |
4019 | see @xref{Subprogram Inlining Control}. | |
4020 | @end table | |
4021 | @end ifclear | |
88e1739c | 4022 | |
7cd4527e AC |
4023 | @ifset vms |
4024 | @item /NOOPTIMIZE | |
4025 | @cindex @option{/NOOPTIMIZE} (@code{GNAT COMPILE}) | |
4026 | Equivalent to @option{/OPTIMIZE=NONE}. | |
4027 | This is the default behavior in the absence of an @option{/OPTMIZE} | |
4028 | qualifier. | |
4029 | ||
4030 | @item /OPTIMIZE[=(keyword[,...])] | |
4031 | @cindex @option{/OPTIMIZE} (@code{GNAT COMPILE}) | |
4032 | Selects the level of optimization for your program. The supported | |
4033 | keywords are as follows: | |
4034 | @table @code | |
4035 | @item ALL | |
4036 | Perform most optimizations, including those that | |
4037 | are expensive. | |
4038 | This is the default if the @option{/OPTMIZE} qualifier is supplied | |
4039 | without keyword options. | |
88e1739c | 4040 | |
7cd4527e AC |
4041 | @item NONE |
4042 | Do not do any optimizations. Same as @code{/NOOPTIMIZE}. | |
88e1739c | 4043 | |
7cd4527e AC |
4044 | @item SOME |
4045 | Perform some optimizations, but omit ones that are costly. | |
88e1739c | 4046 | |
7cd4527e AC |
4047 | @item DEVELOPMENT |
4048 | Same as @code{SOME}. | |
4049 | ||
4050 | @item INLINING | |
4051 | Full optimization, and also attempt automatic inlining of small | |
4052 | subprograms within a unit even when pragma @code{Inline} | |
4053 | is not specified (@pxref{Inlining of Subprograms}). | |
4054 | ||
4055 | @item UNROLL_LOOPS | |
4056 | Try to unroll loops. This keyword may be specified together with | |
4057 | any keyword above other than @code{NONE}. Loop unrolling | |
4058 | usually, but not always, improves the performance of programs. | |
4059 | @end table | |
4060 | @end ifset | |
4061 | ||
4062 | @ifclear vms | |
4063 | @item -pass-exit-codes | |
4064 | @cindex @option{-pass-exit-codes} (@code{gcc}) | |
4065 | Catch exit codes from the compiler and use the most meaningful as | |
4066 | exit status. | |
4067 | @end ifclear | |
4068 | ||
4069 | @item --RTS=@var{rts-path} | |
4070 | @cindex @option{--RTS} (@code{gcc}) | |
4071 | Specifies the default location of the runtime library. Same meaning as the | |
4072 | equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}). | |
4073 | ||
4074 | @item ^-S^/ASM^ | |
4075 | @cindex @option{^-S^/ASM^} (@code{gcc}) | |
4076 | ^Used in place of @option{-c} to^Used to^ | |
4077 | cause the assembler source file to be | |
4078 | generated, using @file{^.s^.S^} as the extension, | |
4079 | instead of the object file. | |
4080 | This may be useful if you need to examine the generated assembly code. | |
4081 | ||
4082 | @item ^-v^/VERBOSE^ | |
4083 | @cindex @option{^-v^/VERBOSE^} (@code{gcc}) | |
4084 | Show commands generated by the @code{gcc} driver. Normally used only for | |
4085 | debugging purposes or if you need to be sure what version of the | |
4086 | compiler you are executing. | |
4087 | ||
4088 | @ifclear vms | |
4089 | @item -V @var{ver} | |
4090 | @cindex @option{-V} (@code{gcc}) | |
4091 | Execute @var{ver} version of the compiler. This is the @code{gcc} | |
4092 | version, not the GNAT version. | |
4093 | @end ifclear | |
4094 | ||
4095 | @end table | |
4096 | ||
4097 | @ifclear vms | |
4098 | You may combine a sequence of GNAT switches into a single switch. For | |
4099 | example, the combined switch | |
4100 | ||
4101 | @cindex Combining GNAT switches | |
4102 | @smallexample | |
4103 | -gnatofi3 | |
4104 | @end smallexample | |
4105 | ||
4106 | @noindent | |
4107 | is equivalent to specifying the following sequence of switches: | |
4108 | ||
4109 | @smallexample | |
4110 | -gnato -gnatf -gnati3 | |
4111 | @end smallexample | |
4112 | @end ifclear | |
4113 | ||
4114 | ||
4115 | @c NEED TO CHECK THIS FOR VMS | |
4116 | ||
4117 | @noindent | |
4118 | The following restrictions apply to the combination of switches | |
4119 | in this manner: | |
4120 | ||
4121 | @itemize @bullet | |
4122 | @item | |
4123 | The switch @option{-gnatc} if combined with other switches must come | |
4124 | first in the string. | |
4125 | ||
4126 | @item | |
4127 | The switch @option{-gnats} if combined with other switches must come | |
4128 | first in the string. | |
4129 | ||
4130 | @item | |
4131 | The switches | |
4132 | @option{^-gnatz^/DISTRIBUTION_STUBS^}, @option{-gnatzc}, and @option{-gnatzr} | |
4133 | may not be combined with any other switches. | |
4134 | ||
4135 | @ifclear vms | |
4136 | @item | |
4137 | Once a ``y'' appears in the string (that is a use of the @option{-gnaty} | |
4138 | switch), then all further characters in the switch are interpreted | |
4139 | as style modifiers (see description of @option{-gnaty}). | |
4140 | ||
4141 | @item | |
4142 | Once a ``d'' appears in the string (that is a use of the @option{-gnatd} | |
4143 | switch), then all further characters in the switch are interpreted | |
4144 | as debug flags (see description of @option{-gnatd}). | |
88e1739c FW |
4145 | |
4146 | @item | |
7cd4527e | 4147 | Once a ``w'' appears in the string (that is a use of the @option{-gnatw} |
88e1739c FW |
4148 | switch), then all further characters in the switch are interpreted |
4149 | as warning mode modifiers (see description of @option{-gnatw}). | |
4150 | ||
4151 | @item | |
7cd4527e | 4152 | Once a ``V'' appears in the string (that is a use of the @option{-gnatV} |
88e1739c FW |
4153 | switch), then all further characters in the switch are interpreted |
4154 | as validity checking options (see description of @option{-gnatV}). | |
7cd4527e | 4155 | @end ifclear |
88e1739c FW |
4156 | @end itemize |
4157 | ||
7cd4527e | 4158 | |
88e1739c FW |
4159 | @node Output and Error Message Control |
4160 | @subsection Output and Error Message Control | |
4161 | @findex stderr | |
4162 | ||
4163 | @noindent | |
7cd4527e | 4164 | The standard default format for error messages is called ``brief format''. |
88e1739c FW |
4165 | Brief format messages are written to @file{stderr} (the standard error |
4166 | file) and have the following form: | |
4167 | ||
4168 | @smallexample | |
88e1739c FW |
4169 | e.adb:3:04: Incorrect spelling of keyword "function" |
4170 | e.adb:4:20: ";" should be "is" | |
4171 | @end smallexample | |
4172 | ||
4173 | @noindent | |
4174 | The first integer after the file name is the line number in the file, | |
4175 | and the second integer is the column number within the line. | |
4176 | @code{glide} can parse the error messages | |
4177 | and point to the referenced character. | |
4178 | The following switches provide control over the error message | |
4179 | format: | |
4180 | ||
7cd4527e AC |
4181 | @table @option |
4182 | @c !sort! | |
88e1739c FW |
4183 | @item -gnatv |
4184 | @cindex @option{-gnatv} (@code{gcc}) | |
4185 | @findex stdout | |
4186 | @ifclear vms | |
4187 | The v stands for verbose. | |
4188 | @end ifclear | |
4189 | The effect of this setting is to write long-format error | |
4190 | messages to @file{stdout} (the standard output file. | |
4191 | The same program compiled with the | |
4192 | @option{-gnatv} switch would generate: | |
4193 | ||
4194 | @smallexample | |
88e1739c FW |
4195 | @cartouche |
4196 | 3. funcion X (Q : Integer) | |
4197 | | | |
4198 | >>> Incorrect spelling of keyword "function" | |
4199 | 4. return Integer; | |
4200 | | | |
4201 | >>> ";" should be "is" | |
4202 | @end cartouche | |
88e1739c FW |
4203 | @end smallexample |
4204 | ||
4205 | @noindent | |
4206 | The vertical bar indicates the location of the error, and the @samp{>>>} | |
4207 | prefix can be used to search for error messages. When this switch is | |
4208 | used the only source lines output are those with errors. | |
4209 | ||
4210 | @item -gnatl | |
4211 | @cindex @option{-gnatl} (@code{gcc}) | |
4212 | @ifclear vms | |
4213 | The @code{l} stands for list. | |
4214 | @end ifclear | |
4215 | This switch causes a full listing of | |
4216 | the file to be generated. The output might look as follows: | |
4217 | ||
4218 | @smallexample | |
88e1739c FW |
4219 | @cartouche |
4220 | 1. procedure E is | |
4221 | 2. V : Integer; | |
4222 | 3. funcion X (Q : Integer) | |
4223 | | | |
4224 | >>> Incorrect spelling of keyword "function" | |
4225 | 4. return Integer; | |
4226 | | | |
4227 | >>> ";" should be "is" | |
4228 | 5. begin | |
4229 | 6. return Q + Q; | |
4230 | 7. end; | |
4231 | 8. begin | |
4232 | 9. V := X + X; | |
4233 | 10.end E; | |
4234 | @end cartouche | |
88e1739c FW |
4235 | @end smallexample |
4236 | ||
4237 | @noindent | |
4238 | @findex stderr | |
4239 | When you specify the @option{-gnatv} or @option{-gnatl} switches and | |
4240 | standard output is redirected, a brief summary is written to | |
4241 | @file{stderr} (standard error) giving the number of error messages and | |
4242 | warning messages generated. | |
4243 | ||
4244 | @item -gnatU | |
4245 | @cindex @option{-gnatU} (@code{gcc}) | |
4246 | This switch forces all error messages to be preceded by the unique | |
7cd4527e | 4247 | string ``error:''. This means that error messages take a few more |
88e1739c FW |
4248 | characters in space, but allows easy searching for and identification |
4249 | of error messages. | |
4250 | ||
4251 | @item -gnatb | |
4252 | @cindex @option{-gnatb} (@code{gcc}) | |
4253 | @ifclear vms | |
4254 | The @code{b} stands for brief. | |
4255 | @end ifclear | |
4256 | This switch causes GNAT to generate the | |
4257 | brief format error messages to @file{stderr} (the standard error | |
4258 | file) as well as the verbose | |
4259 | format message or full listing (which as usual is written to | |
4260 | @file{stdout} (the standard output file). | |
4261 | ||
4262 | @item -gnatm^^=^@var{n} | |
4263 | @cindex @option{-gnatm} (@code{gcc}) | |
4264 | @ifclear vms | |
4265 | The @code{m} stands for maximum. | |
4266 | @end ifclear | |
4267 | @var{n} is a decimal integer in the | |
4268 | range of 1 to 999 and limits the number of error messages to be | |
4269 | generated. For example, using @option{-gnatm2} might yield | |
4270 | ||
4271 | @smallexample | |
88e1739c FW |
4272 | e.adb:3:04: Incorrect spelling of keyword "function" |
4273 | e.adb:5:35: missing ".." | |
4274 | fatal error: maximum errors reached | |
4275 | compilation abandoned | |
4276 | @end smallexample | |
4277 | ||
4278 | @item -gnatf | |
4279 | @cindex @option{-gnatf} (@code{gcc}) | |
4280 | @cindex Error messages, suppressing | |
4281 | @ifclear vms | |
4282 | The @code{f} stands for full. | |
4283 | @end ifclear | |
4284 | Normally, the compiler suppresses error messages that are likely to be | |
4285 | redundant. This switch causes all error | |
4286 | messages to be generated. In particular, in the case of | |
4287 | references to undefined variables. If a given variable is referenced | |
4288 | several times, the normal format of messages is | |
4289 | @smallexample | |
88e1739c FW |
4290 | e.adb:7:07: "V" is undefined (more references follow) |
4291 | @end smallexample | |
4292 | ||
4293 | @noindent | |
4294 | where the parenthetical comment warns that there are additional | |
4295 | references to the variable @code{V}. Compiling the same program with the | |
4296 | @option{-gnatf} switch yields | |
4297 | ||
4298 | @smallexample | |
4299 | e.adb:7:07: "V" is undefined | |
4300 | e.adb:8:07: "V" is undefined | |
4301 | e.adb:8:12: "V" is undefined | |
4302 | e.adb:8:16: "V" is undefined | |
4303 | e.adb:9:07: "V" is undefined | |
4304 | e.adb:9:12: "V" is undefined | |
4305 | @end smallexample | |
4306 | ||
7cd4527e AC |
4307 | @noindent |
4308 | The @option{-gnatf} switch also generates additional information for | |
4309 | some error messages. Some examples are: | |
4310 | ||
4311 | @itemize @bullet | |
4312 | @item | |
4313 | Full details on entities not available in high integrity mode | |
4314 | @item | |
4315 | Details on possibly non-portable unchecked conversion | |
4316 | @item | |
4317 | List possible interpretations for ambiguous calls | |
4318 | @item | |
4319 | Additional details on incorrect parameters | |
4320 | @end itemize | |
4321 | ||
4322 | ||
88e1739c FW |
4323 | @item -gnatq |
4324 | @cindex @option{-gnatq} (@code{gcc}) | |
4325 | @ifclear vms | |
7cd4527e | 4326 | The @code{q} stands for quit (really ``don't quit''). |
88e1739c FW |
4327 | @end ifclear |
4328 | In normal operation mode, the compiler first parses the program and | |
4329 | determines if there are any syntax errors. If there are, appropriate | |
4330 | error messages are generated and compilation is immediately terminated. | |
4331 | This switch tells | |
4332 | GNAT to continue with semantic analysis even if syntax errors have been | |
4333 | found. This may enable the detection of more errors in a single run. On | |
4334 | the other hand, the semantic analyzer is more likely to encounter some | |
4335 | internal fatal error when given a syntactically invalid tree. | |
4336 | ||
4337 | @item -gnatQ | |
7cd4527e AC |
4338 | @cindex @option{-gnatQ} (@code{gcc}) |
4339 | In normal operation mode, the @file{ALI} file is not generated if any | |
88e1739c | 4340 | illegalities are detected in the program. The use of @option{-gnatQ} forces |
7cd4527e | 4341 | generation of the @file{ALI} file. This file is marked as being in |
88e1739c FW |
4342 | error, so it cannot be used for binding purposes, but it does contain |
4343 | reasonably complete cross-reference information, and thus may be useful | |
4344 | for use by tools (e.g. semantic browsing tools or integrated development | |
7cd4527e AC |
4345 | environments) that are driven from the @file{ALI} file. This switch |
4346 | implies @option{-gnatq}, since the semantic phase must be run to get a | |
4347 | meaningful ALI file. | |
88e1739c FW |
4348 | |
4349 | In addition, if @option{-gnatt} is also specified, then the tree file is | |
4350 | generated even if there are illegalities. It may be useful in this case | |
4351 | to also specify @option{-gnatq} to ensure that full semantic processing | |
4352 | occurs. The resulting tree file can be processed by ASIS, for the purpose | |
4353 | of providing partial information about illegal units, but if the error | |
4354 | causes the tree to be badly malformed, then ASIS may crash during the | |
4355 | analysis. | |
4356 | ||
7cd4527e AC |
4357 | When @option{-gnatQ} is used and the generated @file{ALI} file is marked as |
4358 | being in error, @code{gnatmake} will attempt to recompile the source when it | |
4359 | finds such an @file{ALI} file, including with switch @option{-gnatc}. | |
4360 | ||
4361 | Note that @option{-gnatQ} has no effect if @option{-gnats} is specified, | |
4362 | since ALI files are never generated if @option{-gnats} is set. | |
4363 | ||
88e1739c FW |
4364 | @end table |
4365 | ||
7cd4527e AC |
4366 | |
4367 | @node Warning Message Control | |
4368 | @subsection Warning Message Control | |
4369 | @cindex Warning messages | |
88e1739c FW |
4370 | @noindent |
4371 | In addition to error messages, which correspond to illegalities as defined | |
4372 | in the Ada 95 Reference Manual, the compiler detects two kinds of warning | |
4373 | situations. | |
4374 | ||
88e1739c FW |
4375 | First, the compiler considers some constructs suspicious and generates a |
4376 | warning message to alert you to a possible error. Second, if the | |
4377 | compiler detects a situation that is sure to raise an exception at | |
4378 | run time, it generates a warning message. The following shows an example | |
4379 | of warning messages: | |
4380 | @smallexample | |
88e1739c FW |
4381 | e.adb:4:24: warning: creation of object may raise Storage_Error |
4382 | e.adb:10:17: warning: static value out of range | |
4383 | e.adb:10:17: warning: "Constraint_Error" will be raised at run time | |
88e1739c FW |
4384 | @end smallexample |
4385 | ||
4386 | @noindent | |
4387 | GNAT considers a large number of situations as appropriate | |
4388 | for the generation of warning messages. As always, warnings are not | |
4389 | definite indications of errors. For example, if you do an out-of-range | |
4390 | assignment with the deliberate intention of raising a | |
4391 | @code{Constraint_Error} exception, then the warning that may be | |
4392 | issued does not indicate an error. Some of the situations for which GNAT | |
4393 | issues warnings (at least some of the time) are given in the following | |
7cd4527e AC |
4394 | list. This list is not complete, and new warnings are often added to |
4395 | subsequent versions of GNAT. The list is intended to give a general idea | |
4396 | of the kinds of warnings that are generated. | |
88e1739c FW |
4397 | |
4398 | @itemize @bullet | |
4399 | @item | |
4400 | Possible infinitely recursive calls | |
4401 | ||
4402 | @item | |
4403 | Out-of-range values being assigned | |
4404 | ||
4405 | @item | |
4406 | Possible order of elaboration problems | |
4407 | ||
4408 | @item | |
4409 | Unreachable code | |
4410 | ||
4411 | @item | |
4412 | Fixed-point type declarations with a null range | |
4413 | ||
4414 | @item | |
4415 | Variables that are never assigned a value | |
4416 | ||
4417 | @item | |
4418 | Variables that are referenced before being initialized | |
4419 | ||
4420 | @item | |
7cd4527e | 4421 | Task entries with no corresponding @code{accept} statement |
88e1739c FW |
4422 | |
4423 | @item | |
7cd4527e | 4424 | Duplicate accepts for the same task entry in a @code{select} |
88e1739c FW |
4425 | |
4426 | @item | |
4427 | Objects that take too much storage | |
4428 | ||
4429 | @item | |
4430 | Unchecked conversion between types of differing sizes | |
4431 | ||
4432 | @item | |
7cd4527e | 4433 | Missing @code{return} statement along some execution path in a function |
88e1739c FW |
4434 | |
4435 | @item | |
4436 | Incorrect (unrecognized) pragmas | |
4437 | ||
4438 | @item | |
4439 | Incorrect external names | |
4440 | ||
4441 | @item | |
4442 | Allocation from empty storage pool | |
4443 | ||
4444 | @item | |
7cd4527e | 4445 | Potentially blocking operation in protected type |
88e1739c FW |
4446 | |
4447 | @item | |
4448 | Suspicious parenthesization of expressions | |
4449 | ||
4450 | @item | |
4451 | Mismatching bounds in an aggregate | |
4452 | ||
4453 | @item | |
4454 | Attempt to return local value by reference | |
4455 | ||
88e1739c FW |
4456 | |
4457 | @item | |
4458 | Premature instantiation of a generic body | |
4459 | ||
4460 | @item | |
4461 | Attempt to pack aliased components | |
4462 | ||
4463 | @item | |
4464 | Out of bounds array subscripts | |
4465 | ||
4466 | @item | |
4467 | Wrong length on string assignment | |
4468 | ||
4469 | @item | |
4470 | Violations of style rules if style checking is enabled | |
4471 | ||
4472 | @item | |
7cd4527e | 4473 | Unused @code{with} clauses |
88e1739c FW |
4474 | |
4475 | @item | |
7cd4527e | 4476 | @code{Bit_Order} usage that does not have any effect |
88e1739c FW |
4477 | |
4478 | @item | |
7cd4527e | 4479 | @code{Standard.Duration} used to resolve universal fixed expression |
88e1739c FW |
4480 | |
4481 | @item | |
4482 | Dereference of possibly null value | |
4483 | ||
4484 | @item | |
4485 | Declaration that is likely to cause storage error | |
4486 | ||
4487 | @item | |
7cd4527e | 4488 | Internal GNAT unit @code{with}'ed by application unit |
88e1739c FW |
4489 | |
4490 | @item | |
4491 | Values known to be out of range at compile time | |
4492 | ||
4493 | @item | |
4494 | Unreferenced labels and variables | |
4495 | ||
4496 | @item | |
4497 | Address overlays that could clobber memory | |
4498 | ||
4499 | @item | |
4500 | Unexpected initialization when address clause present | |
4501 | ||
4502 | @item | |
4503 | Bad alignment for address clause | |
4504 | ||
4505 | @item | |
4506 | Useless type conversions | |
4507 | ||
4508 | @item | |
7cd4527e | 4509 | Redundant assignment statements and other redundant constructs |
88e1739c FW |
4510 | |
4511 | @item | |
7cd4527e | 4512 | Useless exception handlers |
88e1739c FW |
4513 | |
4514 | @item | |
7cd4527e AC |
4515 | Accidental hiding of name by child unit |
4516 | ||
88e1739c FW |
4517 | |
4518 | @item | |
4519 | Access before elaboration detected at compile time | |
4520 | ||
4521 | @item | |
4522 | A range in a @code{for} loop that is known to be null or might be null | |
4523 | ||
4524 | @end itemize | |
4525 | ||
4526 | @noindent | |
4527 | The following switches are available to control the handling of | |
4528 | warning messages: | |
4529 | ||
7cd4527e AC |
4530 | @table @option |
4531 | @c !sort! | |
4532 | @item -gnatwa | |
4533 | @emph{Activate all optional errors.} | |
88e1739c FW |
4534 | @cindex @option{-gnatwa} (@code{gcc}) |
4535 | This switch activates most optional warning messages, see remaining list | |
4536 | in this section for details on optional warning messages that can be | |
7cd4527e AC |
4537 | individually controlled. The warnings that are not turned on by this |
4538 | switch are | |
88e1739c | 4539 | @option{-gnatwd} (implicit dereferencing), |
7cd4527e AC |
4540 | @option{-gnatwh} (hiding), |
4541 | and @option{-gnatwl} (elaboration warnings). | |
4542 | All other optional warnings are turned on. | |
88e1739c | 4543 | |
7cd4527e AC |
4544 | @item -gnatwA |
4545 | @emph{Suppress all optional errors.} | |
88e1739c FW |
4546 | @cindex @option{-gnatwA} (@code{gcc}) |
4547 | This switch suppresses all optional warning messages, see remaining list | |
4548 | in this section for details on optional warning messages that can be | |
4549 | individually controlled. | |
4550 | ||
7cd4527e AC |
4551 | @item -gnatwc |
4552 | @emph{Activate warnings on conditionals.} | |
88e1739c FW |
4553 | @cindex @option{-gnatwc} (@code{gcc}) |
4554 | @cindex Conditionals, constant | |
4555 | This switch activates warnings for conditional expressions used in | |
4556 | tests that are known to be True or False at compile time. The default | |
4557 | is that such warnings are not generated. | |
7cd4527e AC |
4558 | Note that this warning does |
4559 | not get issued for the use of boolean variables or constants whose | |
4560 | values are known at compile time, since this is a standard technique | |
4561 | for conditional compilation in Ada, and this would generate too many | |
4562 | ``false positive'' warnings. | |
88e1739c FW |
4563 | This warning can also be turned on using @option{-gnatwa}. |
4564 | ||
7cd4527e AC |
4565 | @item -gnatwC |
4566 | @emph{Suppress warnings on conditionals.} | |
88e1739c FW |
4567 | @cindex @option{-gnatwC} (@code{gcc}) |
4568 | This switch suppresses warnings for conditional expressions used in | |
4569 | tests that are known to be True or False at compile time. | |
4570 | ||
7cd4527e AC |
4571 | @item -gnatwd |
4572 | @emph{Activate warnings on implicit dereferencing.} | |
88e1739c FW |
4573 | @cindex @option{-gnatwd} (@code{gcc}) |
4574 | If this switch is set, then the use of a prefix of an access type | |
4575 | in an indexed component, slice, or selected component without an | |
4576 | explicit @code{.all} will generate a warning. With this warning | |
4577 | enabled, access checks occur only at points where an explicit | |
4578 | @code{.all} appears in the source code (assuming no warnings are | |
4579 | generated as a result of this switch). The default is that such | |
4580 | warnings are not generated. | |
4581 | Note that @option{-gnatwa} does not affect the setting of | |
4582 | this warning option. | |
4583 | ||
7cd4527e AC |
4584 | @item -gnatwD |
4585 | @emph{Suppress warnings on implicit dereferencing.} | |
88e1739c FW |
4586 | @cindex @option{-gnatwD} (@code{gcc}) |
4587 | @cindex Implicit dereferencing | |
4588 | @cindex Dereferencing, implicit | |
7cd4527e | 4589 | This switch suppresses warnings for implicit dereferences in |
88e1739c FW |
4590 | indexed components, slices, and selected components. |
4591 | ||
7cd4527e AC |
4592 | @item -gnatwe |
4593 | @emph{Treat warnings as errors.} | |
88e1739c FW |
4594 | @cindex @option{-gnatwe} (@code{gcc}) |
4595 | @cindex Warnings, treat as error | |
4596 | This switch causes warning messages to be treated as errors. | |
4597 | The warning string still appears, but the warning messages are counted | |
4598 | as errors, and prevent the generation of an object file. | |
4599 | ||
7cd4527e AC |
4600 | @item -gnatwf |
4601 | @emph{Activate warnings on unreferenced formals.} | |
88e1739c FW |
4602 | @cindex @option{-gnatwf} (@code{gcc}) |
4603 | @cindex Formals, unreferenced | |
4604 | This switch causes a warning to be generated if a formal parameter | |
4605 | is not referenced in the body of the subprogram. This warning can | |
4606 | also be turned on using @option{-gnatwa} or @option{-gnatwu}. | |
4607 | ||
7cd4527e AC |
4608 | @item -gnatwF |
4609 | @emph{Suppress warnings on unreferenced formals.} | |
88e1739c FW |
4610 | @cindex @option{-gnatwF} (@code{gcc}) |
4611 | This switch suppresses warnings for unreferenced formal | |
4612 | parameters. Note that the | |
4613 | combination @option{-gnatwu} followed by @option{-gnatwF} has the | |
4614 | effect of warning on unreferenced entities other than subprogram | |
4615 | formals. | |
4616 | ||
7cd4527e AC |
4617 | @item -gnatwg |
4618 | @emph{Activate warnings on unrecognized pragmas.} | |
4619 | @cindex @option{-gnatwg} (@code{gcc}) | |
4620 | @cindex Pragmas, unrecognized | |
4621 | This switch causes a warning to be generated if an unrecognized | |
4622 | pragma is encountered. Apart from issuing this warning, the | |
4623 | pragma is ignored and has no effect. This warning can | |
4624 | also be turned on using @option{-gnatwa}. The default | |
4625 | is that such warnings are issued (satisfying the Ada Reference | |
4626 | Manual requirement that such warnings appear). | |
4627 | ||
4628 | @item -gnatwG | |
4629 | @emph{Suppress warnings on unrecognized pragmas.} | |
4630 | @cindex @option{-gnatwG} (@code{gcc}) | |
4631 | This switch suppresses warnings for unrecognized pragmas. | |
4632 | ||
4633 | @item -gnatwh | |
4634 | @emph{Activate warnings on hiding.} | |
88e1739c FW |
4635 | @cindex @option{-gnatwh} (@code{gcc}) |
4636 | @cindex Hiding of Declarations | |
4637 | This switch activates warnings on hiding declarations. | |
4638 | A declaration is considered hiding | |
4639 | if it is for a non-overloadable entity, and it declares an entity with the | |
4640 | same name as some other entity that is directly or use-visible. The default | |
4641 | is that such warnings are not generated. | |
4642 | Note that @option{-gnatwa} does not affect the setting of this warning option. | |
4643 | ||
7cd4527e AC |
4644 | @item -gnatwH |
4645 | @emph{Suppress warnings on hiding.} | |
88e1739c FW |
4646 | @cindex @option{-gnatwH} (@code{gcc}) |
4647 | This switch suppresses warnings on hiding declarations. | |
4648 | ||
7cd4527e AC |
4649 | @item -gnatwi |
4650 | @emph{Activate warnings on implementation units.} | |
88e1739c FW |
4651 | @cindex @option{-gnatwi} (@code{gcc}) |
4652 | This switch activates warnings for a @code{with} of an internal GNAT | |
4653 | implementation unit, defined as any unit from the @code{Ada}, | |
4654 | @code{Interfaces}, @code{GNAT}, | |
4655 | ^^@code{DEC},^ or @code{System} | |
4656 | hierarchies that is not | |
4657 | documented in either the Ada Reference Manual or the GNAT | |
4658 | Programmer's Reference Manual. Such units are intended only | |
4659 | for internal implementation purposes and should not be @code{with}'ed | |
4660 | by user programs. The default is that such warnings are generated | |
4661 | This warning can also be turned on using @option{-gnatwa}. | |
4662 | ||
7cd4527e AC |
4663 | @item -gnatwI |
4664 | @emph{Disable warnings on implementation units.} | |
88e1739c FW |
4665 | @cindex @option{-gnatwI} (@code{gcc}) |
4666 | This switch disables warnings for a @code{with} of an internal GNAT | |
4667 | implementation unit. | |
4668 | ||
7cd4527e AC |
4669 | @item -gnatwj |
4670 | @emph{Activate warnings on obsolescent features (Annex J).} | |
4671 | @cindex @option{-gnatwj} (@code{gcc}) | |
4672 | @cindex Features, obsolescent | |
4673 | @cindex Obsolescent features | |
4674 | If this warning option is activated, then warnings are generated for | |
4675 | calls to subprograms marked with @code{pragma Obsolescent} and | |
4676 | for use of features in Annex J of the Ada Reference Manual. In the | |
4677 | case of Annex J, not all features are flagged. In particular use | |
4678 | of the renamed packages (like @code{Text_IO}) and use of package | |
4679 | @code{ASCII} are not flagged, since these are very common and | |
4680 | would generate many annoying positive warnings. The default is that | |
4681 | such warnings are not generated. | |
4682 | ||
4683 | @item -gnatwJ | |
4684 | @emph{Suppress warnings on obsolescent features (Annex J).} | |
4685 | @cindex @option{-gnatwJ} (@code{gcc}) | |
4686 | This switch disables warnings on use of obsolescent features. | |
4687 | ||
4688 | @item -gnatwk | |
4689 | @emph{Activate warnings on variables that could be constants.} | |
4690 | @cindex @option{-gnatwk} (@code{gcc}) | |
4691 | This switch activates warnings for variables that are initialized but | |
4692 | never modified, and then could be declared constants. | |
4693 | ||
4694 | @item -gnatwK | |
4695 | @emph{Suppress warnings on variables that could be constants.} | |
4696 | @cindex @option{-gnatwK} (@code{gcc}) | |
4697 | This switch disables warnings on variables that could be declared constants. | |
4698 | ||
4699 | @item -gnatwl | |
4700 | @emph{Activate warnings for missing elaboration pragmas.} | |
88e1739c FW |
4701 | @cindex @option{-gnatwl} (@code{gcc}) |
4702 | @cindex Elaboration, warnings | |
7cd4527e AC |
4703 | This switch activates warnings on missing |
4704 | @code{pragma Elaborate_All} statements. | |
88e1739c | 4705 | See the section in this guide on elaboration checking for details on |
7cd4527e AC |
4706 | when such pragma should be used. Warnings are also generated if you |
4707 | are using the static mode of elaboration, and a @code{pragma Elaborate} | |
4708 | is encountered. The default is that such warnings | |
88e1739c | 4709 | are not generated. |
7cd4527e | 4710 | This warning is not automatically turned on by the use of @option{-gnatwa}. |
88e1739c | 4711 | |
7cd4527e AC |
4712 | @item -gnatwL |
4713 | @emph{Suppress warnings for missing elaboration pragmas.} | |
88e1739c FW |
4714 | @cindex @option{-gnatwL} (@code{gcc}) |
4715 | This switch suppresses warnings on missing pragma Elaborate_All statements. | |
4716 | See the section in this guide on elaboration checking for details on | |
4717 | when such pragma should be used. | |
4718 | ||
7cd4527e AC |
4719 | @item -gnatwm |
4720 | @emph{Activate warnings on modified but unreferenced variables.} | |
4721 | @cindex @option{-gnatwm} (@code{gcc}) | |
4722 | This switch activates warnings for variables that are assigned (using | |
4723 | an initialization value or with one or more assignment statements) but | |
4724 | whose value is never read. The warning is suppressed for volatile | |
4725 | variables and also for variables that are renamings of other variables | |
4726 | or for which an address clause is given. | |
4727 | This warning can also be turned on using @option{-gnatwa}. | |
4728 | ||
4729 | @item -gnatwM | |
4730 | @emph{Disable warnings on modified but unreferenced variables.} | |
4731 | @cindex @option{-gnatwM} (@code{gcc}) | |
4732 | This switch disables warnings for variables that are assigned or | |
4733 | initialized, but never read. | |
4734 | ||
4735 | @item -gnatwn | |
4736 | @emph{Set normal warnings mode.} | |
4737 | @cindex @option{-gnatwn} (@code{gcc}) | |
4738 | This switch sets normal warning mode, in which enabled warnings are | |
4739 | issued and treated as warnings rather than errors. This is the default | |
4740 | mode. the switch @option{-gnatwn} can be used to cancel the effect of | |
4741 | an explicit @option{-gnatws} or | |
4742 | @option{-gnatwe}. It also cancels the effect of the | |
4743 | implicit @option{-gnatwe} that is activated by the | |
4744 | use of @option{-gnatg}. | |
4745 | ||
4746 | @item -gnatwo | |
4747 | @emph{Activate warnings on address clause overlays.} | |
88e1739c FW |
4748 | @cindex @option{-gnatwo} (@code{gcc}) |
4749 | @cindex Address Clauses, warnings | |
4750 | This switch activates warnings for possibly unintended initialization | |
4751 | effects of defining address clauses that cause one variable to overlap | |
4752 | another. The default is that such warnings are generated. | |
4753 | This warning can also be turned on using @option{-gnatwa}. | |
4754 | ||
7cd4527e AC |
4755 | @item -gnatwO |
4756 | @emph{Suppress warnings on address clause overlays.} | |
88e1739c FW |
4757 | @cindex @option{-gnatwO} (@code{gcc}) |
4758 | This switch suppresses warnings on possibly unintended initialization | |
4759 | effects of defining address clauses that cause one variable to overlap | |
4760 | another. | |
4761 | ||
7cd4527e AC |
4762 | @item -gnatwp |
4763 | @emph{Activate warnings on ineffective pragma Inlines.} | |
88e1739c FW |
4764 | @cindex @option{-gnatwp} (@code{gcc}) |
4765 | @cindex Inlining, warnings | |
4766 | This switch activates warnings for failure of front end inlining | |
4767 | (activated by @option{-gnatN}) to inline a particular call. There are | |
4768 | many reasons for not being able to inline a call, including most | |
4769 | commonly that the call is too complex to inline. | |
4770 | This warning can also be turned on using @option{-gnatwa}. | |
4771 | ||
7cd4527e AC |
4772 | @item -gnatwP |
4773 | @emph{Suppress warnings on ineffective pragma Inlines.} | |
88e1739c FW |
4774 | @cindex @option{-gnatwP} (@code{gcc}) |
4775 | This switch suppresses warnings on ineffective pragma Inlines. If the | |
4776 | inlining mechanism cannot inline a call, it will simply ignore the | |
4777 | request silently. | |
4778 | ||
7cd4527e AC |
4779 | @item -gnatwr |
4780 | @emph{Activate warnings on redundant constructs.} | |
88e1739c FW |
4781 | @cindex @option{-gnatwr} (@code{gcc}) |
4782 | This switch activates warnings for redundant constructs. The following | |
4783 | is the current list of constructs regarded as redundant: | |
4784 | This warning can also be turned on using @option{-gnatwa}. | |
4785 | ||
4786 | @itemize @bullet | |
4787 | @item | |
4788 | Assignment of an item to itself. | |
4789 | @item | |
4790 | Type conversion that converts an expression to its own type. | |
4791 | @item | |
4792 | Use of the attribute @code{Base} where @code{typ'Base} is the same | |
4793 | as @code{typ}. | |
4794 | @item | |
4795 | Use of pragma @code{Pack} when all components are placed by a record | |
4796 | representation clause. | |
7cd4527e AC |
4797 | @item |
4798 | Exception handler containing only a reraise statement (raise with no | |
4799 | operand) which has no effect. | |
4800 | @item | |
4801 | Use of the operator abs on an operand that is known at compile time | |
4802 | to be non-negative | |
4803 | @item | |
4804 | Use of an unnecessary extra level of parentheses (C-style) around conditions | |
4805 | in @code{if} statements, @code{while} statements and @code{exit} statements. | |
4806 | @item | |
4807 | Comparison of boolean expressions to an explicit True value. | |
88e1739c FW |
4808 | @end itemize |
4809 | ||
7cd4527e AC |
4810 | @item -gnatwR |
4811 | @emph{Suppress warnings on redundant constructs.} | |
88e1739c FW |
4812 | @cindex @option{-gnatwR} (@code{gcc}) |
4813 | This switch suppresses warnings for redundant constructs. | |
4814 | ||
7cd4527e AC |
4815 | @item -gnatws |
4816 | @emph{Suppress all warnings.} | |
88e1739c FW |
4817 | @cindex @option{-gnatws} (@code{gcc}) |
4818 | This switch completely suppresses the | |
4819 | output of all warning messages from the GNAT front end. | |
4820 | Note that it does not suppress warnings from the @code{gcc} back end. | |
7cd4527e | 4821 | To suppress these back end warnings as well, use the switch @option{-w} |
88e1739c FW |
4822 | in addition to @option{-gnatws}. |
4823 | ||
7cd4527e AC |
4824 | @item -gnatwu |
4825 | @emph{Activate warnings on unused entities.} | |
88e1739c FW |
4826 | @cindex @option{-gnatwu} (@code{gcc}) |
4827 | This switch activates warnings to be generated for entities that | |
7cd4527e | 4828 | are declared but not referenced, and for units that are @code{with}'ed |
88e1739c FW |
4829 | and not |
4830 | referenced. In the case of packages, a warning is also generated if | |
4831 | no entities in the package are referenced. This means that if the package | |
4832 | is referenced but the only references are in @code{use} | |
4833 | clauses or @code{renames} | |
4834 | declarations, a warning is still generated. A warning is also generated | |
4835 | for a generic package that is @code{with}'ed but never instantiated. | |
4836 | In the case where a package or subprogram body is compiled, and there | |
4837 | is a @code{with} on the corresponding spec | |
4838 | that is only referenced in the body, | |
4839 | a warning is also generated, noting that the | |
4840 | @code{with} can be moved to the body. The default is that | |
4841 | such warnings are not generated. | |
4842 | This switch also activates warnings on unreferenced formals | |
4843 | (it is includes the effect of @option{-gnatwf}). | |
4844 | This warning can also be turned on using @option{-gnatwa}. | |
4845 | ||
7cd4527e AC |
4846 | @item -gnatwU |
4847 | @emph{Suppress warnings on unused entities.} | |
88e1739c FW |
4848 | @cindex @option{-gnatwU} (@code{gcc}) |
4849 | This switch suppresses warnings for unused entities and packages. | |
4850 | It also turns off warnings on unreferenced formals (and thus includes | |
4851 | the effect of @option{-gnatwF}). | |
4852 | ||
7cd4527e AC |
4853 | @item -gnatwv |
4854 | @emph{Activate warnings on unassigned variables.} | |
4855 | @cindex @option{-gnatwv} (@code{gcc}) | |
4856 | @cindex Unassigned variable warnings | |
4857 | This switch activates warnings for access to variables which | |
4858 | may not be properly initialized. The default is that | |
4859 | such warnings are generated. | |
4860 | ||
4861 | @item -gnatwV | |
4862 | @emph{Suppress warnings on unassigned variables.} | |
4863 | @cindex @option{-gnatwV} (@code{gcc}) | |
4864 | This switch suppresses warnings for access to variables which | |
4865 | may not be properly initialized. | |
4866 | ||
4867 | @item -gnatwx | |
4868 | @emph{Activate warnings on Export/Import pragmas.} | |
4869 | @cindex @option{-gnatwx} (@code{gcc}) | |
4870 | @cindex Export/Import pragma warnings | |
4871 | This switch activates warnings on Export/Import pragmas when | |
4872 | the compiler detects a possible conflict between the Ada and | |
4873 | foreign language calling sequences. For example, the use of | |
4874 | default parameters in a convention C procedure is dubious | |
4875 | because the C compiler cannot supply the proper default, so | |
4876 | a warning is issued. The default is that such warnings are | |
4877 | generated. | |
4878 | ||
4879 | @item -gnatwX | |
4880 | @emph{Suppress warnings on Export/Import pragmas.} | |
4881 | @cindex @option{-gnatwX} (@code{gcc}) | |
4882 | This switch suppresses warnings on Export/Import pragmas. | |
4883 | The sense of this is that you are telling the compiler that | |
4884 | you know what you are doing in writing the pragma, and it | |
4885 | should not complain at you. | |
4886 | ||
4887 | @item -gnatwz | |
4888 | @emph{Activate warnings on unchecked conversions.} | |
4889 | @cindex @option{-gnatwz} (@code{gcc}) | |
4890 | @cindex Unchecked_Conversion warnings | |
4891 | This switch activates warnings for unchecked conversions | |
4892 | where the types are known at compile time to have different | |
4893 | sizes. The default | |
4894 | is that such warnings are generated. | |
4895 | ||
4896 | @item -gnatwZ | |
4897 | @emph{Suppress warnings on unchecked conversions.} | |
4898 | @cindex @option{-gnatwZ} (@code{gcc}) | |
4899 | This switch suppresses warnings for unchecked conversions | |
4900 | where the types are known at compile time to have different | |
4901 | sizes. | |
4902 | ||
4903 | @item ^-Wuninitialized^WARNINGS=UNINITIALIZED^ | |
4904 | @cindex @option{-Wuninitialized} | |
4905 | The warnings controlled by the @option{-gnatw} switch are generated by the | |
4906 | front end of the compiler. In some cases, the @option{^gcc^GCC^} back end | |
4907 | can provide additional warnings. One such useful warning is provided by | |
4908 | @option{^-Wuninitialized^WARNINGS=UNINITIALIZED^}. This must be used in | |
4909 | conjunction with tunrning on optimization mode. This causes the flow | |
4910 | analysis circuits of the back end optimizer to output additional | |
4911 | warnings about uninitialized variables. | |
4912 | ||
4913 | @item ^-w^/NO_BACK_END_WARNINGS^ | |
4914 | @cindex @option{-w} | |
4915 | This switch suppresses warnings from the @option{^gcc^GCC^} back end. It may | |
4916 | be used in conjunction with @option{-gnatws} to ensure that all warnings | |
4917 | are suppressed during the entire compilation process. | |
4918 | ||
4919 | @end table | |
4920 | ||
88e1739c | 4921 | @noindent |
7cd4527e | 4922 | @ifclear vms |
88e1739c FW |
4923 | A string of warning parameters can be used in the same parameter. For example: |
4924 | ||
4925 | @smallexample | |
4926 | -gnatwaLe | |
4927 | @end smallexample | |
4928 | ||
4929 | @noindent | |
7cd4527e | 4930 | will turn on all optional warnings except for elaboration pragma warnings, |
88e1739c | 4931 | and also specify that warnings should be treated as errors. |
7cd4527e AC |
4932 | @end ifclear |
4933 | When no switch @option{^-gnatw^/WARNINGS^} is used, this is equivalent to: | |
4934 | ||
4935 | @table @option | |
4936 | @c !sort! | |
4937 | @item -gnatwC | |
4938 | @item -gnatwD | |
4939 | @item -gnatwF | |
4940 | @item -gnatwg | |
4941 | @item -gnatwH | |
4942 | @item -gnatwi | |
4943 | @item -gnatwJ | |
4944 | @item -gnatwK | |
4945 | @item -gnatwL | |
4946 | @item -gnatwM | |
4947 | @item -gnatwn | |
4948 | @item -gnatwo | |
4949 | @item -gnatwP | |
4950 | @item -gnatwR | |
4951 | @item -gnatwU | |
4952 | @item -gnatwv | |
4953 | @item -gnatwz | |
4954 | @item -gnatwx | |
88e1739c FW |
4955 | |
4956 | @end table | |
4957 | ||
7cd4527e | 4958 | |
88e1739c FW |
4959 | @node Debugging and Assertion Control |
4960 | @subsection Debugging and Assertion Control | |
4961 | ||
7cd4527e | 4962 | @table @option |
88e1739c FW |
4963 | @item -gnata |
4964 | @cindex @option{-gnata} (@code{gcc}) | |
4965 | @findex Assert | |
4966 | @findex Debug | |
4967 | @cindex Assertions | |
4968 | ||
4969 | @noindent | |
4970 | The pragmas @code{Assert} and @code{Debug} normally have no effect and | |
4971 | are ignored. This switch, where @samp{a} stands for assert, causes | |
4972 | @code{Assert} and @code{Debug} pragmas to be activated. | |
4973 | ||
4974 | The pragmas have the form: | |
4975 | ||
4976 | @smallexample | |
88e1739c FW |
4977 | @cartouche |
4978 | @b{pragma} Assert (@var{Boolean-expression} [, | |
4979 | @var{static-string-expression}]) | |
4980 | @b{pragma} Debug (@var{procedure call}) | |
4981 | @end cartouche | |
88e1739c FW |
4982 | @end smallexample |
4983 | ||
4984 | @noindent | |
4985 | The @code{Assert} pragma causes @var{Boolean-expression} to be tested. | |
4986 | If the result is @code{True}, the pragma has no effect (other than | |
4987 | possible side effects from evaluating the expression). If the result is | |
4988 | @code{False}, the exception @code{Assert_Failure} declared in the package | |
4989 | @code{System.Assertions} is | |
4990 | raised (passing @var{static-string-expression}, if present, as the | |
4991 | message associated with the exception). If no string expression is | |
4992 | given the default is a string giving the file name and line number | |
4993 | of the pragma. | |
4994 | ||
4995 | The @code{Debug} pragma causes @var{procedure} to be called. Note that | |
4996 | @code{pragma Debug} may appear within a declaration sequence, allowing | |
4997 | debugging procedures to be called between declarations. | |
4998 | ||
4999 | @ifset vms | |
5000 | @item /DEBUG[=debug-level] | |
5001 | @itemx /NODEBUG | |
5002 | Specifies how much debugging information is to be included in | |
5003 | the resulting object file where 'debug-level' is one of the following: | |
5004 | @table @code | |
7cd4527e | 5005 | @item TRACEBACK |
88e1739c FW |
5006 | Include both debugger symbol records and traceback |
5007 | the object file. | |
7cd4527e | 5008 | This is the default setting. |
88e1739c FW |
5009 | @item ALL |
5010 | Include both debugger symbol records and traceback in | |
5011 | object file. | |
5012 | @item NONE | |
5013 | Excludes both debugger symbol records and traceback | |
5014 | the object file. Same as /NODEBUG. | |
5015 | @item SYMBOLS | |
5016 | Includes only debugger symbol records in the object | |
5017 | file. Note that this doesn't include traceback information. | |
5018 | @end table | |
5019 | @end ifset | |
5020 | @end table | |
5021 | ||
5022 | @node Validity Checking | |
5023 | @subsection Validity Checking | |
5024 | @findex Validity Checking | |
5025 | ||
5026 | @noindent | |
5027 | The Ada 95 Reference Manual has specific requirements for checking | |
5028 | for invalid values. In particular, RM 13.9.1 requires that the | |
5029 | evaluation of invalid values (for example from unchecked conversions), | |
5030 | not result in erroneous execution. In GNAT, the result of such an | |
5031 | evaluation in normal default mode is to either use the value | |
5032 | unmodified, or to raise Constraint_Error in those cases where use | |
5033 | of the unmodified value would cause erroneous execution. The cases | |
5034 | where unmodified values might lead to erroneous execution are case | |
5035 | statements (where a wild jump might result from an invalid value), | |
5036 | and subscripts on the left hand side (where memory corruption could | |
5037 | occur as a result of an invalid value). | |
5038 | ||
7cd4527e AC |
5039 | The @option{-gnatV^@var{x}^^} switch allows more control over the validity |
5040 | checking mode. | |
5041 | @ifclear vms | |
5042 | The @code{x} argument is a string of letters that | |
5043 | indicate validity checks that are performed or not performed in addition | |
5044 | to the default checks described above. | |
5045 | @end ifclear | |
5046 | @ifset vms | |
5047 | The options allowed for this qualifier | |
5048 | indicate validity checks that are performed or not performed in addition | |
5049 | to the default checks described above. | |
5050 | @end ifset | |
5051 | ||
88e1739c | 5052 | |
7cd4527e AC |
5053 | @table @option |
5054 | @c !sort! | |
5055 | @item -gnatVa | |
5056 | @emph{All validity checks.} | |
5057 | @cindex @option{-gnatVa} (@code{gcc}) | |
5058 | All validity checks are turned on. | |
5059 | @ifclear vms | |
5060 | That is, @option{-gnatVa} is | |
5061 | equivalent to @option{gnatVcdfimorst}. | |
5062 | @end ifclear | |
88e1739c | 5063 | |
7cd4527e AC |
5064 | @item -gnatVc |
5065 | @emph{Validity checks for copies.} | |
5066 | @cindex @option{-gnatVc} (@code{gcc}) | |
88e1739c FW |
5067 | The right hand side of assignments, and the initializing values of |
5068 | object declarations are validity checked. | |
5069 | ||
7cd4527e AC |
5070 | @item -gnatVd |
5071 | @emph{Default (RM) validity checks.} | |
5072 | @cindex @option{-gnatVd} (@code{gcc}) | |
88e1739c FW |
5073 | Some validity checks are done by default following normal Ada semantics |
5074 | (RM 13.9.1 (9-11)). | |
5075 | A check is done in case statements that the expression is within the range | |
5076 | of the subtype. If it is not, Constraint_Error is raised. | |
5077 | For assignments to array components, a check is done that the expression used | |
5078 | as index is within the range. If it is not, Constraint_Error is raised. | |
5079 | Both these validity checks may be turned off using switch @option{-gnatVD}. | |
5080 | They are turned on by default. If @option{-gnatVD} is specified, a subsequent | |
5081 | switch @option{-gnatVd} will leave the checks turned on. | |
5082 | Switch @option{-gnatVD} should be used only if you are sure that all such | |
5083 | expressions have valid values. If you use this switch and invalid values | |
5084 | are present, then the program is erroneous, and wild jumps or memory | |
5085 | overwriting may occur. | |
5086 | ||
7cd4527e AC |
5087 | @item -gnatVf |
5088 | @emph{Validity checks for floating-point values.} | |
5089 | @cindex @option{-gnatVf} (@code{gcc}) | |
5090 | In the absence of this switch, validity checking occurs only for discrete | |
5091 | values. If @option{-gnatVf} is specified, then validity checking also applies | |
5092 | for floating-point values, and NaN's and infinities are considered invalid, | |
5093 | as well as out of range values for constrained types. Note that this means | |
5094 | that standard @code{IEEE} infinity mode is not allowed. The exact contexts | |
5095 | in which floating-point values are checked depends on the setting of other | |
5096 | options. For example, | |
5097 | @option{^-gnatVif^VALIDITY_CHECKING=(IN_PARAMS,FLOATS)^} or | |
5098 | @option{^-gnatVfi^VALIDITY_CHECKING=(FLOATS,IN_PARAMS)^} | |
5099 | (the order does not matter) specifies that floating-point parameters of mode | |
5100 | @code{in} should be validity checked. | |
5101 | ||
5102 | @item -gnatVi | |
5103 | @emph{Validity checks for @code{in} mode parameters} | |
5104 | @cindex @option{-gnatVi} (@code{gcc}) | |
88e1739c FW |
5105 | Arguments for parameters of mode @code{in} are validity checked in function |
5106 | and procedure calls at the point of call. | |
5107 | ||
7cd4527e AC |
5108 | @item -gnatVm |
5109 | @emph{Validity checks for @code{in out} mode parameters.} | |
5110 | @cindex @option{-gnatVm} (@code{gcc}) | |
88e1739c FW |
5111 | Arguments for parameters of mode @code{in out} are validity checked in |
5112 | procedure calls at the point of call. The @code{'m'} here stands for | |
5113 | modify, since this concerns parameters that can be modified by the call. | |
5114 | Note that there is no specific option to test @code{out} parameters, | |
5115 | but any reference within the subprogram will be tested in the usual | |
5116 | manner, and if an invalid value is copied back, any reference to it | |
5117 | will be subject to validity checking. | |
5118 | ||
7cd4527e AC |
5119 | @item -gnatVn |
5120 | @emph{No validity checks.} | |
5121 | @cindex @option{-gnatVn} (@code{gcc}) | |
5122 | This switch turns off all validity checking, including the default checking | |
5123 | for case statements and left hand side subscripts. Note that the use of | |
5124 | the switch @option{-gnatp} suppresses all run-time checks, including | |
5125 | validity checks, and thus implies @option{-gnatVn}. When this switch | |
5126 | is used, it cancels any other @option{-gnatV} previously issued. | |
88e1739c | 5127 | |
7cd4527e AC |
5128 | @item -gnatVo |
5129 | @emph{Validity checks for operator and attribute operands.} | |
5130 | @cindex @option{-gnatVo} (@code{gcc}) | |
88e1739c FW |
5131 | Arguments for predefined operators and attributes are validity checked. |
5132 | This includes all operators in package @code{Standard}, | |
5133 | the shift operators defined as intrinsic in package @code{Interfaces} | |
7cd4527e AC |
5134 | and operands for attributes such as @code{Pos}. Checks are also made |
5135 | on individual component values for composite comparisons. | |
5136 | ||
5137 | @item -gnatVp | |
5138 | @emph{Validity checks for parameters.} | |
5139 | @cindex @option{-gnatVp} (@code{gcc}) | |
5140 | This controls the treatment of parameters within a subprogram (as opposed | |
5141 | to @option{-gnatVi} and @option{-gnatVm} which control validity testing | |
5142 | of parameters on a call. If either of these call options is used, then | |
5143 | normally an assumption is made within a subprogram that the input arguments | |
5144 | have been validity checking at the point of call, and do not need checking | |
5145 | again within a subprogram). If @option{-gnatVp} is set, then this assumption | |
5146 | is not made, and parameters are not assumed to be valid, so their validity | |
5147 | will be checked (or rechecked) within the subprogram. | |
5148 | ||
5149 | @item -gnatVr | |
5150 | @emph{Validity checks for function returns.} | |
5151 | @cindex @option{-gnatVr} (@code{gcc}) | |
88e1739c FW |
5152 | The expression in @code{return} statements in functions is validity |
5153 | checked. | |
5154 | ||
7cd4527e AC |
5155 | @item -gnatVs |
5156 | @emph{Validity checks for subscripts.} | |
5157 | @cindex @option{-gnatVs} (@code{gcc}) | |
88e1739c FW |
5158 | All subscripts expressions are checked for validity, whether they appear |
5159 | on the right side or left side (in default mode only left side subscripts | |
5160 | are validity checked). | |
5161 | ||
7cd4527e AC |
5162 | @item -gnatVt |
5163 | @emph{Validity checks for tests.} | |
5164 | @cindex @option{-gnatVt} (@code{gcc}) | |
88e1739c FW |
5165 | Expressions used as conditions in @code{if}, @code{while} or @code{exit} |
5166 | statements are checked, as well as guard expressions in entry calls. | |
5167 | ||
7cd4527e | 5168 | @end table |
88e1739c | 5169 | |
7cd4527e AC |
5170 | @noindent |
5171 | The @option{-gnatV} switch may be followed by | |
5172 | ^a string of letters^a list of options^ | |
5173 | to turn on a series of validity checking options. | |
5174 | For example, | |
5175 | @option{^-gnatVcr^/VALIDITY_CHECKING=(COPIES, RETURNS)^} | |
5176 | specifies that in addition to the default validity checking, copies and | |
5177 | function return expressions are to be validity checked. | |
5178 | In order to make it easier | |
5179 | to specify the desired combination of effects, | |
5180 | @ifclear vms | |
5181 | the upper case letters @code{CDFIMORST} may | |
5182 | be used to turn off the corresponding lower case option. | |
5183 | @end ifclear | |
5184 | @ifset vms | |
5185 | the prefix @code{NO} on an option turns off the corresponding validity | |
5186 | checking: | |
5187 | @itemize @bullet | |
5188 | @item @code{NOCOPIES} | |
5189 | @item @code{NODEFAULT} | |
5190 | @item @code{NOFLOATS} | |
5191 | @item @code{NOIN_PARAMS} | |
5192 | @item @code{NOMOD_PARAMS} | |
5193 | @item @code{NOOPERANDS} | |
5194 | @item @code{NORETURNS} | |
5195 | @item @code{NOSUBSCRIPTS} | |
5196 | @item @code{NOTESTS} | |
88e1739c | 5197 | @end itemize |
7cd4527e AC |
5198 | @end ifset |
5199 | Thus | |
5200 | @option{^-gnatVaM^/VALIDITY_CHECKING=(ALL, NOMOD_PARAMS)^} | |
5201 | turns on all validity checking options except for | |
5202 | checking of @code{@b{in out}} procedure arguments. | |
88e1739c FW |
5203 | |
5204 | The specification of additional validity checking generates extra code (and | |
7cd4527e AC |
5205 | in the case of @option{-gnatVa} the code expansion can be substantial. |
5206 | However, these additional checks can be very useful in detecting | |
88e1739c FW |
5207 | uninitialized variables, incorrect use of unchecked conversion, and other |
5208 | errors leading to invalid values. The use of pragma @code{Initialize_Scalars} | |
5209 | is useful in conjunction with the extra validity checking, since this | |
5210 | ensures that wherever possible uninitialized variables have invalid values. | |
5211 | ||
5212 | See also the pragma @code{Validity_Checks} which allows modification of | |
5213 | the validity checking mode at the program source level, and also allows for | |
5214 | temporary disabling of validity checks. | |
5215 | ||
7cd4527e | 5216 | |
88e1739c FW |
5217 | @node Style Checking |
5218 | @subsection Style Checking | |
5219 | @findex Style checking | |
5220 | ||
5221 | @noindent | |
7cd4527e AC |
5222 | The @option{-gnaty^x^(option,option,...)^} switch |
5223 | @cindex @option{-gnaty} (@code{gcc}) | |
5224 | causes the compiler to | |
88e1739c FW |
5225 | enforce specified style rules. A limited set of style rules has been used |
5226 | in writing the GNAT sources themselves. This switch allows user programs | |
5227 | to activate all or some of these checks. If the source program fails a | |
5228 | specified style check, an appropriate warning message is given, preceded by | |
7cd4527e | 5229 | the character sequence ``(style)''. |
88e1739c | 5230 | @ifset vms |
7cd4527e | 5231 | @code{(option,option,...)} is a sequence of keywords |
88e1739c FW |
5232 | @end ifset |
5233 | @ifclear vms | |
5234 | The string @var{x} is a sequence of letters or digits | |
5235 | @end ifclear | |
5236 | indicating the particular style | |
5237 | checks to be performed. The following checks are defined: | |
5238 | ||
7cd4527e AC |
5239 | @table @option |
5240 | @c !sort! | |
5241 | @item 1-9 | |
5242 | @emph{Specify indentation level.} | |
5243 | If a digit from 1-9 appears | |
5244 | ^in the string after @option{-gnaty}^as an option for /STYLE_CHECKS^ | |
5245 | then proper indentation is checked, with the digit indicating the | |
5246 | indentation level required. | |
5247 | The general style of required indentation is as specified by | |
88e1739c FW |
5248 | the examples in the Ada Reference Manual. Full line comments must be |
5249 | aligned with the @code{--} starting on a column that is a multiple of | |
5250 | the alignment level. | |
5251 | ||
7cd4527e AC |
5252 | @item ^a^ATTRIBUTE^ |
5253 | @emph{Check attribute casing.} | |
5254 | If the ^letter a^word ATTRIBUTE^ appears in the string after @option{-gnaty} | |
5255 | then attribute names, including the case of keywords such as @code{digits} | |
88e1739c FW |
5256 | used as attributes names, must be written in mixed case, that is, the |
5257 | initial letter and any letter following an underscore must be uppercase. | |
5258 | All other letters must be lowercase. | |
5259 | ||
7cd4527e AC |
5260 | @item ^b^BLANKS^ |
5261 | @emph{Blanks not allowed at statement end.} | |
88e1739c FW |
5262 | If the ^letter b^word BLANKS^ appears in the string after @option{-gnaty} then |
5263 | trailing blanks are not allowed at the end of statements. The purpose of this | |
5264 | rule, together with h (no horizontal tabs), is to enforce a canonical format | |
5265 | for the use of blanks to separate source tokens. | |
5266 | ||
7cd4527e AC |
5267 | @item ^c^COMMENTS^ |
5268 | @emph{Check comments.} | |
5269 | If the ^letter c^word COMMENTS^ appears in the string after @option{-gnaty} | |
5270 | then comments must meet the following set of rules: | |
88e1739c FW |
5271 | |
5272 | @itemize @bullet | |
5273 | ||
5274 | @item | |
7cd4527e AC |
5275 | The ``@code{--}'' that starts the column must either start in column one, |
5276 | or else at least one blank must precede this sequence. | |
88e1739c FW |
5277 | |
5278 | @item | |
5279 | Comments that follow other tokens on a line must have at least one blank | |
7cd4527e | 5280 | following the ``@code{--}'' at the start of the comment. |
88e1739c FW |
5281 | |
5282 | @item | |
7cd4527e AC |
5283 | Full line comments must have two blanks following the ``@code{--}'' that |
5284 | starts the comment, with the following exceptions. | |
88e1739c FW |
5285 | |
5286 | @item | |
7cd4527e AC |
5287 | A line consisting only of the ``@code{--}'' characters, possibly preceded |
5288 | by blanks is permitted. | |
88e1739c FW |
5289 | |
5290 | @item | |
7cd4527e AC |
5291 | A comment starting with ``@code{--x}'' where @code{x} is a special character |
5292 | is permitted. | |
5293 | This allows proper processing of the output generated by specialized tools | |
5294 | including @command{gnatprep} (where ``@code{--!}'' is used) and the SPARK | |
5295 | annotation | |
5296 | language (where ``@code{--#}'' is used). For the purposes of this rule, a | |
5297 | special character is defined as being in one of the ASCII ranges | |
5298 | @code{16#21#..16#2F#} or @code{16#3A#..16#3F#}. | |
5299 | Note that this usage is not permitted | |
5300 | in GNAT implementation units (i.e. when @option{-gnatg} is used). | |
88e1739c FW |
5301 | |
5302 | @item | |
5303 | A line consisting entirely of minus signs, possibly preceded by blanks, is | |
5304 | permitted. This allows the construction of box comments where lines of minus | |
5305 | signs are used to form the top and bottom of the box. | |
5306 | ||
5307 | @item | |
7cd4527e AC |
5308 | If a comment starts and ends with ``@code{--}'' is permitted as long as at |
5309 | least one blank follows the initial ``@code{--}''. Together with the preceding | |
5310 | rule, this allows the construction of box comments, as shown in the following | |
88e1739c FW |
5311 | example: |
5312 | @smallexample | |
5313 | --------------------------- | |
5314 | -- This is a box comment -- | |
5315 | -- with two text lines. -- | |
5316 | --------------------------- | |
5317 | @end smallexample | |
5318 | @end itemize | |
5319 | ||
7cd4527e AC |
5320 | @item ^e^END^ |
5321 | @emph{Check end/exit labels.} | |
88e1739c FW |
5322 | If the ^letter e^word END^ appears in the string after @option{-gnaty} then |
5323 | optional labels on @code{end} statements ending subprograms and on | |
5324 | @code{exit} statements exiting named loops, are required to be present. | |
5325 | ||
7cd4527e AC |
5326 | @item ^f^VTABS^ |
5327 | @emph{No form feeds or vertical tabs.} | |
88e1739c FW |
5328 | If the ^letter f^word VTABS^ appears in the string after @option{-gnaty} then |
5329 | neither form feeds nor vertical tab characters are not permitted | |
5330 | in the source text. | |
5331 | ||
7cd4527e AC |
5332 | @item ^h^HTABS^ |
5333 | @emph{No horizontal tabs.} | |
88e1739c FW |
5334 | If the ^letter h^word HTABS^ appears in the string after @option{-gnaty} then |
5335 | horizontal tab characters are not permitted in the source text. | |
5336 | Together with the b (no blanks at end of line) check, this | |
5337 | enforces a canonical form for the use of blanks to separate | |
5338 | source tokens. | |
5339 | ||
7cd4527e AC |
5340 | @item ^i^IF_THEN^ |
5341 | @emph{Check if-then layout.} | |
88e1739c FW |
5342 | If the ^letter i^word IF_THEN^ appears in the string after @option{-gnaty}, |
5343 | then the keyword @code{then} must appear either on the same | |
5344 | line as corresponding @code{if}, or on a line on its own, lined | |
5345 | up under the @code{if} with at least one non-blank line in between | |
5346 | containing all or part of the condition to be tested. | |
5347 | ||
7cd4527e AC |
5348 | @item ^k^KEYWORD^ |
5349 | @emph{Check keyword casing.} | |
88e1739c FW |
5350 | If the ^letter k^word KEYWORD^ appears in the string after @option{-gnaty} then |
5351 | all keywords must be in lower case (with the exception of keywords | |
5352 | such as @code{digits} used as attribute names to which this check | |
5353 | does not apply). | |
5354 | ||
7cd4527e AC |
5355 | @item ^l^LAYOUT^ |
5356 | @emph{Check layout.} | |
88e1739c FW |
5357 | If the ^letter l^word LAYOUT^ appears in the string after @option{-gnaty} then |
5358 | layout of statement and declaration constructs must follow the | |
5359 | recommendations in the Ada Reference Manual, as indicated by the | |
5360 | form of the syntax rules. For example an @code{else} keyword must | |
5361 | be lined up with the corresponding @code{if} keyword. | |
5362 | ||
5363 | There are two respects in which the style rule enforced by this check | |
5364 | option are more liberal than those in the Ada Reference Manual. First | |
5365 | in the case of record declarations, it is permissible to put the | |
5366 | @code{record} keyword on the same line as the @code{type} keyword, and | |
5367 | then the @code{end} in @code{end record} must line up under @code{type}. | |
5368 | For example, either of the following two layouts is acceptable: | |
5369 | ||
7cd4527e | 5370 | @smallexample @c ada |
88e1739c | 5371 | @cartouche |
7cd4527e | 5372 | type q is record |
88e1739c FW |
5373 | a : integer; |
5374 | b : integer; | |
7cd4527e | 5375 | end record; |
88e1739c | 5376 | |
7cd4527e AC |
5377 | type q is |
5378 | record | |
88e1739c FW |
5379 | a : integer; |
5380 | b : integer; | |
7cd4527e | 5381 | end record; |
88e1739c | 5382 | @end cartouche |
88e1739c FW |
5383 | @end smallexample |
5384 | ||
5385 | @noindent | |
5386 | Second, in the case of a block statement, a permitted alternative | |
5387 | is to put the block label on the same line as the @code{declare} or | |
5388 | @code{begin} keyword, and then line the @code{end} keyword up under | |
5389 | the block label. For example both the following are permitted: | |
5390 | ||
7cd4527e | 5391 | @smallexample @c ada |
88e1739c | 5392 | @cartouche |
7cd4527e | 5393 | Block : declare |
88e1739c | 5394 | A : Integer := 3; |
7cd4527e | 5395 | begin |
88e1739c | 5396 | Proc (A, A); |
7cd4527e | 5397 | end Block; |
88e1739c FW |
5398 | |
5399 | Block : | |
7cd4527e | 5400 | declare |
88e1739c | 5401 | A : Integer := 3; |
7cd4527e | 5402 | begin |
88e1739c | 5403 | Proc (A, A); |
7cd4527e | 5404 | end Block; |
88e1739c | 5405 | @end cartouche |
88e1739c FW |
5406 | @end smallexample |
5407 | ||
5408 | @noindent | |
5409 | The same alternative format is allowed for loops. For example, both of | |
5410 | the following are permitted: | |
5411 | ||
7cd4527e | 5412 | @smallexample @c ada |
88e1739c | 5413 | @cartouche |
7cd4527e | 5414 | Clear : while J < 10 loop |
88e1739c | 5415 | A (J) := 0; |
7cd4527e | 5416 | end loop Clear; |
88e1739c FW |
5417 | |
5418 | Clear : | |
7cd4527e | 5419 | while J < 10 loop |
88e1739c | 5420 | A (J) := 0; |
7cd4527e | 5421 | end loop Clear; |
88e1739c | 5422 | @end cartouche |
88e1739c FW |
5423 | @end smallexample |
5424 | ||
7cd4527e AC |
5425 | @item ^m^LINE_LENGTH^ |
5426 | @emph{Check maximum line length.} | |
88e1739c FW |
5427 | If the ^letter m^word LINE_LENGTH^ appears in the string after @option{-gnaty} |
5428 | then the length of source lines must not exceed 79 characters, including | |
5429 | any trailing blanks. The value of 79 allows convenient display on an | |
5430 | 80 character wide device or window, allowing for possible special | |
7cd4527e AC |
5431 | treatment of 80 character lines. Note that this count is of raw |
5432 | characters in the source text. This means that a tab character counts | |
5433 | as one character in this count and a wide character sequence counts as | |
5434 | several characters (however many are needed in the encoding). | |
88e1739c | 5435 | |
7cd4527e AC |
5436 | @item ^Mnnn^MAX_LENGTH=nnn^ |
5437 | @emph{Set maximum line length.} | |
88e1739c FW |
5438 | If the sequence ^M^MAX_LENGTH=^nnn, where nnn is a decimal number, appears in |
5439 | the string after @option{-gnaty} then the length of lines must not exceed the | |
5440 | given value. | |
5441 | ||
7cd4527e AC |
5442 | @item ^n^STANDARD_CASING^ |
5443 | @emph{Check casing of entities in Standard.} | |
88e1739c FW |
5444 | If the ^letter n^word STANDARD_CASING^ appears in the string |
5445 | after @option{-gnaty} then any identifier from Standard must be cased | |
5446 | to match the presentation in the Ada Reference Manual (for example, | |
5447 | @code{Integer} and @code{ASCII.NUL}). | |
5448 | ||
7cd4527e AC |
5449 | @item ^o^ORDERED_SUBPROGRAMS^ |
5450 | @emph{Check order of subprogram bodies.} | |
88e1739c FW |
5451 | If the ^letter o^word ORDERED_SUBPROGRAMS^ appears in the string |
5452 | after @option{-gnaty} then all subprogram bodies in a given scope | |
5453 | (e.g. a package body) must be in alphabetical order. The ordering | |
5454 | rule uses normal Ada rules for comparing strings, ignoring casing | |
5455 | of letters, except that if there is a trailing numeric suffix, then | |
5456 | the value of this suffix is used in the ordering (e.g. Junk2 comes | |
5457 | before Junk10). | |
5458 | ||
7cd4527e AC |
5459 | @item ^p^PRAGMA^ |
5460 | @emph{Check pragma casing.} | |
88e1739c FW |
5461 | If the ^letter p^word PRAGMA^ appears in the string after @option{-gnaty} then |
5462 | pragma names must be written in mixed case, that is, the | |
5463 | initial letter and any letter following an underscore must be uppercase. | |
5464 | All other letters must be lowercase. | |
5465 | ||
7cd4527e AC |
5466 | @item ^r^REFERENCES^ |
5467 | @emph{Check references.} | |
88e1739c FW |
5468 | If the ^letter r^word REFERENCES^ appears in the string after @option{-gnaty} |
5469 | then all identifier references must be cased in the same way as the | |
5470 | corresponding declaration. No specific casing style is imposed on | |
5471 | identifiers. The only requirement is for consistency of references | |
5472 | with declarations. | |
5473 | ||
7cd4527e AC |
5474 | @item ^s^SPECS^ |
5475 | @emph{Check separate specs.} | |
88e1739c | 5476 | If the ^letter s^word SPECS^ appears in the string after @option{-gnaty} then |
7cd4527e | 5477 | separate declarations (``specs'') are required for subprograms (a |
88e1739c FW |
5478 | body is not allowed to serve as its own declaration). The only |
5479 | exception is that parameterless library level procedures are | |
5480 | not required to have a separate declaration. This exception covers | |
5481 | the most frequent form of main program procedures. | |
5482 | ||
7cd4527e AC |
5483 | @item ^t^TOKEN^ |
5484 | @emph{Check token spacing.} | |
88e1739c FW |
5485 | If the ^letter t^word TOKEN^ appears in the string after @option{-gnaty} then |
5486 | the following token spacing rules are enforced: | |
5487 | ||
5488 | @itemize @bullet | |
5489 | ||
5490 | @item | |
7cd4527e | 5491 | The keywords @code{@b{abs}} and @code{@b{not}} must be followed by a space. |
88e1739c FW |
5492 | |
5493 | @item | |
5494 | The token @code{=>} must be surrounded by spaces. | |
5495 | ||
5496 | @item | |
5497 | The token @code{<>} must be preceded by a space or a left parenthesis. | |
5498 | ||
5499 | @item | |
5500 | Binary operators other than @code{**} must be surrounded by spaces. | |
5501 | There is no restriction on the layout of the @code{**} binary operator. | |
5502 | ||
5503 | @item | |
5504 | Colon must be surrounded by spaces. | |
5505 | ||
5506 | @item | |
7cd4527e | 5507 | Colon-equal (assignment, initialization) must be surrounded by spaces. |
88e1739c FW |
5508 | |
5509 | @item | |
5510 | Comma must be the first non-blank character on the line, or be | |
5511 | immediately preceded by a non-blank character, and must be followed | |
5512 | by a space. | |
5513 | ||
5514 | @item | |
7cd4527e | 5515 | If the token preceding a left parenthesis ends with a letter or digit, then |
88e1739c FW |
5516 | a space must separate the two tokens. |
5517 | ||
5518 | @item | |
5519 | A right parenthesis must either be the first non-blank character on | |
5520 | a line, or it must be preceded by a non-blank character. | |
5521 | ||
5522 | @item | |
5523 | A semicolon must not be preceded by a space, and must not be followed by | |
5524 | a non-blank character. | |
5525 | ||
5526 | @item | |
5527 | A unary plus or minus may not be followed by a space. | |
5528 | ||
5529 | @item | |
5530 | A vertical bar must be surrounded by spaces. | |
5531 | @end itemize | |
5532 | ||
5533 | @noindent | |
5534 | In the above rules, appearing in column one is always permitted, that is, | |
5535 | counts as meeting either a requirement for a required preceding space, | |
5536 | or as meeting a requirement for no preceding space. | |
5537 | ||
5538 | Appearing at the end of a line is also always permitted, that is, counts | |
5539 | as meeting either a requirement for a following space, or as meeting | |
5540 | a requirement for no following space. | |
5541 | ||
5542 | @end table | |
5543 | ||
5544 | @noindent | |
5545 | If any of these style rules is violated, a message is generated giving | |
5546 | details on the violation. The initial characters of such messages are | |
7cd4527e | 5547 | always ``@code{(style)}''. Note that these messages are treated as warning |
88e1739c FW |
5548 | messages, so they normally do not prevent the generation of an object |
5549 | file. The @option{-gnatwe} switch can be used to treat warning messages, | |
5550 | including style messages, as fatal errors. | |
5551 | ||
88e1739c | 5552 | The switch |
7cd4527e AC |
5553 | @ifclear vms |
5554 | @option{-gnaty} on its own (that is not | |
5555 | followed by any letters or digits), | |
5556 | is equivalent to @code{gnaty3abcefhiklmprst}, that is all checking | |
5557 | options enabled with the exception of -gnatyo, | |
5558 | @end ifclear | |
5559 | @ifset vms | |
5560 | /STYLE_CHECKS=ALL_BUILTIN enables all checking options with | |
5561 | the exception of ORDERED_SUBPROGRAMS, | |
5562 | @end ifset | |
88e1739c FW |
5563 | with an indentation level of 3. This is the standard |
5564 | checking option that is used for the GNAT sources. | |
5565 | ||
7cd4527e AC |
5566 | The switch |
5567 | @ifclear vms | |
5568 | @option{-gnatyN} | |
5569 | @end ifclear | |
5570 | @ifset vms | |
5571 | /STYLE_CHECKS=NONE | |
5572 | @end ifset | |
5573 | clears any previously set style checks. | |
5574 | ||
88e1739c FW |
5575 | @node Run-Time Checks |
5576 | @subsection Run-Time Checks | |
5577 | @cindex Division by zero | |
5578 | @cindex Access before elaboration | |
5579 | @cindex Checks, division by zero | |
5580 | @cindex Checks, access before elaboration | |
5581 | ||
5582 | @noindent | |
5583 | If you compile with the default options, GNAT will insert many run-time | |
5584 | checks into the compiled code, including code that performs range | |
5585 | checking against constraints, but not arithmetic overflow checking for | |
5586 | integer operations (including division by zero) or checks for access | |
5587 | before elaboration on subprogram calls. All other run-time checks, as | |
5588 | required by the Ada 95 Reference Manual, are generated by default. | |
5589 | The following @code{gcc} switches refine this default behavior: | |
5590 | ||
7cd4527e AC |
5591 | @table @option |
5592 | @c !sort! | |
88e1739c FW |
5593 | @item -gnatp |
5594 | @cindex @option{-gnatp} (@code{gcc}) | |
5595 | @cindex Suppressing checks | |
5596 | @cindex Checks, suppressing | |
5597 | @findex Suppress | |
5598 | Suppress all run-time checks as though @code{pragma Suppress (all_checks}) | |
5599 | had been present in the source. Validity checks are also suppressed (in | |
5600 | other words @option{-gnatp} also implies @option{-gnatVn}. | |
5601 | Use this switch to improve the performance | |
5602 | of the code at the expense of safety in the presence of invalid data or | |
5603 | program bugs. | |
5604 | ||
5605 | @item -gnato | |
5606 | @cindex @option{-gnato} (@code{gcc}) | |
5607 | @cindex Overflow checks | |
5608 | @cindex Check, overflow | |
5609 | Enables overflow checking for integer operations. | |
5610 | This causes GNAT to generate slower and larger executable | |
5611 | programs by adding code to check for overflow (resulting in raising | |
5612 | @code{Constraint_Error} as required by standard Ada | |
5613 | semantics). These overflow checks correspond to situations in which | |
5614 | the true value of the result of an operation may be outside the base | |
5615 | range of the result type. The following example shows the distinction: | |
5616 | ||
7cd4527e | 5617 | @smallexample @c ada |
88e1739c FW |
5618 | X1 : Integer := Integer'Last; |
5619 | X2 : Integer range 1 .. 5 := 5; | |
7cd4527e AC |
5620 | X3 : Integer := Integer'Last; |
5621 | X4 : Integer range 1 .. 5 := 5; | |
5622 | F : Float := 2.0E+20; | |
88e1739c | 5623 | ... |
7cd4527e AC |
5624 | X1 := X1 + 1; |
5625 | X2 := X2 + 1; | |
5626 | X3 := Integer (F); | |
5627 | X4 := Integer (F); | |
88e1739c FW |
5628 | @end smallexample |
5629 | ||
5630 | @noindent | |
5631 | Here the first addition results in a value that is outside the base range | |
5632 | of Integer, and hence requires an overflow check for detection of the | |
7cd4527e AC |
5633 | constraint error. Thus the first assignment to @code{X1} raises a |
5634 | @code{Constraint_Error} exception only if @option{-gnato} is set. | |
5635 | ||
5636 | The second increment operation results in a violation | |
88e1739c | 5637 | of the explicit range constraint, and such range checks are always |
7cd4527e AC |
5638 | performed (unless specifically suppressed with a pragma @code{suppress} |
5639 | or the use of @option{-gnatp}). | |
5640 | ||
5641 | The two conversions of @code{F} both result in values that are outside | |
5642 | the base range of type @code{Integer} and thus will raise | |
5643 | @code{Constraint_Error} exceptions only if @option{-gnato} is used. | |
5644 | The fact that the result of the second conversion is assigned to | |
5645 | variable @code{X4} with a restricted range is irrelevant, since the problem | |
5646 | is in the conversion, not the assignment. | |
5647 | ||
5648 | Basically the rule is that in the default mode (@option{-gnato} not | |
5649 | used), the generated code assures that all integer variables stay | |
5650 | within their declared ranges, or within the base range if there is | |
5651 | no declared range. This prevents any serious problems like indexes | |
5652 | out of range for array operations. | |
5653 | ||
5654 | What is not checked in default mode is an overflow that results in | |
5655 | an in-range, but incorrect value. In the above example, the assignments | |
5656 | to @code{X1}, @code{X2}, @code{X3} all give results that are within the | |
5657 | range of the target variable, but the result is wrong in the sense that | |
5658 | it is too large to be represented correctly. Typically the assignment | |
5659 | to @code{X1} will result in wrap around to the largest negative number. | |
5660 | The conversions of @code{F} will result in some @code{Integer} value | |
5661 | and if that integer value is out of the @code{X4} range then the | |
5662 | subsequent assignment would generate an exception. | |
88e1739c FW |
5663 | |
5664 | @findex Machine_Overflows | |
5665 | Note that the @option{-gnato} switch does not affect the code generated | |
5666 | for any floating-point operations; it applies only to integer | |
5667 | semantics). | |
5668 | For floating-point, GNAT has the @code{Machine_Overflows} | |
5669 | attribute set to @code{False} and the normal mode of operation is to | |
5670 | generate IEEE NaN and infinite values on overflow or invalid operations | |
5671 | (such as dividing 0.0 by 0.0). | |
5672 | ||
5673 | The reason that we distinguish overflow checking from other kinds of | |
5674 | range constraint checking is that a failure of an overflow check can | |
5675 | generate an incorrect value, but cannot cause erroneous behavior. This | |
5676 | is unlike the situation with a constraint check on an array subscript, | |
5677 | where failure to perform the check can result in random memory description, | |
5678 | or the range check on a case statement, where failure to perform the check | |
5679 | can cause a wild jump. | |
5680 | ||
5681 | Note again that @option{-gnato} is off by default, so overflow checking is | |
5682 | not performed in default mode. This means that out of the box, with the | |
5683 | default settings, GNAT does not do all the checks expected from the | |
5684 | language description in the Ada Reference Manual. If you want all constraint | |
5685 | checks to be performed, as described in this Manual, then you must | |
5686 | explicitly use the -gnato switch either on the @code{gnatmake} or | |
5687 | @code{gcc} command. | |
5688 | ||
5689 | @item -gnatE | |
5690 | @cindex @option{-gnatE} (@code{gcc}) | |
5691 | @cindex Elaboration checks | |
5692 | @cindex Check, elaboration | |
5693 | Enables dynamic checks for access-before-elaboration | |
5694 | on subprogram calls and generic instantiations. | |
5695 | For full details of the effect and use of this switch, | |
5696 | @xref{Compiling Using gcc}. | |
5697 | @end table | |
5698 | ||
5699 | @findex Unsuppress | |
5700 | @noindent | |
5701 | The setting of these switches only controls the default setting of the | |
5702 | checks. You may modify them using either @code{Suppress} (to remove | |
5703 | checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in | |
5704 | the program source. | |
5705 | ||
5706 | @node Stack Overflow Checking | |
5707 | @subsection Stack Overflow Checking | |
5708 | @cindex Stack Overflow Checking | |
5709 | @cindex -fstack-check | |
5710 | ||
5711 | @noindent | |
5712 | For most operating systems, @code{gcc} does not perform stack overflow | |
5713 | checking by default. This means that if the main environment task or | |
5714 | some other task exceeds the available stack space, then unpredictable | |
5715 | behavior will occur. | |
5716 | ||
5717 | To activate stack checking, compile all units with the gcc option | |
7cd4527e | 5718 | @option{-fstack-check}. For example: |
88e1739c FW |
5719 | |
5720 | @smallexample | |
5721 | gcc -c -fstack-check package1.adb | |
5722 | @end smallexample | |
5723 | ||
5724 | @noindent | |
5725 | Units compiled with this option will generate extra instructions to check | |
5726 | that any use of the stack (for procedure calls or for declaring local | |
5727 | variables in declare blocks) do not exceed the available stack space. | |
5728 | If the space is exceeded, then a @code{Storage_Error} exception is raised. | |
5729 | ||
5730 | For declared tasks, the stack size is always controlled by the size | |
5731 | given in an applicable @code{Storage_Size} pragma (or is set to | |
5732 | the default size if no pragma is used. | |
5733 | ||
5734 | For the environment task, the stack size depends on | |
5735 | system defaults and is unknown to the compiler. The stack | |
5736 | may even dynamically grow on some systems, precluding the | |
5737 | normal Ada semantics for stack overflow. In the worst case, | |
5738 | unbounded stack usage, causes unbounded stack expansion | |
5739 | resulting in the system running out of virtual memory. | |
5740 | ||
5741 | The stack checking may still work correctly if a fixed | |
5742 | size stack is allocated, but this cannot be guaranteed. | |
5743 | To ensure that a clean exception is signalled for stack | |
5744 | overflow, set the environment variable | |
5745 | @code{GNAT_STACK_LIMIT} to indicate the maximum | |
5746 | stack area that can be used, as in: | |
5747 | @cindex GNAT_STACK_LIMIT | |
5748 | ||
5749 | @smallexample | |
5750 | SET GNAT_STACK_LIMIT 1600 | |
5751 | @end smallexample | |
5752 | ||
5753 | @noindent | |
5754 | The limit is given in kilobytes, so the above declaration would | |
5755 | set the stack limit of the environment task to 1.6 megabytes. | |
5756 | Note that the only purpose of this usage is to limit the amount | |
5757 | of stack used by the environment task. If it is necessary to | |
5758 | increase the amount of stack for the environment task, then this | |
5759 | is an operating systems issue, and must be addressed with the | |
5760 | appropriate operating systems commands. | |
5761 | ||
88e1739c FW |
5762 | |
5763 | @node Using gcc for Syntax Checking | |
5764 | @subsection Using @code{gcc} for Syntax Checking | |
7cd4527e | 5765 | @table @option |
88e1739c FW |
5766 | @item -gnats |
5767 | @cindex @option{-gnats} (@code{gcc}) | |
5768 | @ifclear vms | |
5769 | ||
5770 | @noindent | |
7cd4527e | 5771 | The @code{s} stands for ``syntax''. |
88e1739c FW |
5772 | @end ifclear |
5773 | ||
5774 | Run GNAT in syntax checking only mode. For | |
5775 | example, the command | |
5776 | ||
5777 | @smallexample | |
5778 | $ gcc -c -gnats x.adb | |
5779 | @end smallexample | |
5780 | ||
5781 | @noindent | |
5782 | compiles file @file{x.adb} in syntax-check-only mode. You can check a | |
5783 | series of files in a single command | |
5784 | @ifclear vms | |
5785 | , and can use wild cards to specify such a group of files. | |
7cd4527e | 5786 | Note that you must specify the @option{-c} (compile |
88e1739c FW |
5787 | only) flag in addition to the @option{-gnats} flag. |
5788 | @end ifclear | |
5789 | . | |
88e1739c FW |
5790 | You may use other switches in conjunction with @option{-gnats}. In |
5791 | particular, @option{-gnatl} and @option{-gnatv} are useful to control the | |
5792 | format of any generated error messages. | |
5793 | ||
7cd4527e AC |
5794 | When the source file is empty or contains only empty lines and/or comments, |
5795 | the output is a warning: | |
5796 | ||
5797 | @smallexample | |
5798 | $ gcc -c -gnats -x ada toto.txt | |
5799 | toto.txt:1:01: warning: empty file, contains no compilation units | |
5800 | $ | |
5801 | @end smallexample | |
5802 | ||
5803 | Otherwise, the output is simply the error messages, if any. No object file or | |
5804 | ALI file is generated by a syntax-only compilation. Also, no units other | |
88e1739c FW |
5805 | than the one specified are accessed. For example, if a unit @code{X} |
5806 | @code{with}'s a unit @code{Y}, compiling unit @code{X} in syntax | |
5807 | check only mode does not access the source file containing unit | |
5808 | @code{Y}. | |
5809 | ||
5810 | @cindex Multiple units, syntax checking | |
5811 | Normally, GNAT allows only a single unit in a source file. However, this | |
5812 | restriction does not apply in syntax-check-only mode, and it is possible | |
5813 | to check a file containing multiple compilation units concatenated | |
5814 | together. This is primarily used by the @code{gnatchop} utility | |
5815 | (@pxref{Renaming Files Using gnatchop}). | |
5816 | @end table | |
5817 | ||
7cd4527e | 5818 | |
88e1739c FW |
5819 | @node Using gcc for Semantic Checking |
5820 | @subsection Using @code{gcc} for Semantic Checking | |
7cd4527e | 5821 | @table @option |
88e1739c FW |
5822 | @item -gnatc |
5823 | @cindex @option{-gnatc} (@code{gcc}) | |
5824 | ||
5825 | @ifclear vms | |
5826 | @noindent | |
7cd4527e | 5827 | The @code{c} stands for ``check''. |
88e1739c FW |
5828 | @end ifclear |
5829 | Causes the compiler to operate in semantic check mode, | |
5830 | with full checking for all illegalities specified in the | |
5831 | Ada 95 Reference Manual, but without generation of any object code | |
5832 | (no object file is generated). | |
5833 | ||
5834 | Because dependent files must be accessed, you must follow the GNAT | |
5835 | semantic restrictions on file structuring to operate in this mode: | |
5836 | ||
5837 | @itemize @bullet | |
5838 | @item | |
5839 | The needed source files must be accessible | |
5840 | (@pxref{Search Paths and the Run-Time Library (RTL)}). | |
5841 | ||
5842 | @item | |
5843 | Each file must contain only one compilation unit. | |
5844 | ||
5845 | @item | |
5846 | The file name and unit name must match (@pxref{File Naming Rules}). | |
5847 | @end itemize | |
5848 | ||
5849 | The output consists of error messages as appropriate. No object file is | |
5850 | generated. An @file{ALI} file is generated for use in the context of | |
5851 | cross-reference tools, but this file is marked as not being suitable | |
5852 | for binding (since no object file is generated). | |
5853 | The checking corresponds exactly to the notion of | |
5854 | legality in the Ada 95 Reference Manual. | |
5855 | ||
5856 | Any unit can be compiled in semantics-checking-only mode, including | |
5857 | units that would not normally be compiled (subunits, | |
5858 | and specifications where a separate body is present). | |
5859 | @end table | |
5860 | ||
5861 | @node Compiling Ada 83 Programs | |
5862 | @subsection Compiling Ada 83 Programs | |
7cd4527e | 5863 | @table @option |
88e1739c FW |
5864 | @cindex Ada 83 compatibility |
5865 | @item -gnat83 | |
5866 | @cindex @option{-gnat83} (@code{gcc}) | |
5867 | @cindex ACVC, Ada 83 tests | |
5868 | ||
5869 | @noindent | |
5870 | Although GNAT is primarily an Ada 95 compiler, it accepts this switch to | |
7cd4527e | 5871 | specify that an Ada 83 program is to be compiled in Ada 83 mode. If you specify |
88e1739c FW |
5872 | this switch, GNAT rejects most Ada 95 extensions and applies Ada 83 semantics |
5873 | where this can be done easily. | |
5874 | It is not possible to guarantee this switch does a perfect | |
5875 | job; for example, some subtle tests, such as are | |
7cd4527e AC |
5876 | found in earlier ACVC tests (and that have been removed from the ACATS suite |
5877 | for Ada 95), might not compile correctly. | |
5878 | Nevertheless, this switch may be useful in some circumstances, for example | |
5879 | where, due to contractual reasons, legacy code needs to be maintained | |
5880 | using only Ada 83 features. | |
88e1739c FW |
5881 | |
5882 | With few exceptions (most notably the need to use @code{<>} on | |
5883 | @cindex Generic formal parameters | |
5884 | unconstrained generic formal parameters, the use of the new Ada 95 | |
7cd4527e | 5885 | reserved words, and the use of packages |
88e1739c FW |
5886 | with optional bodies), it is not necessary to use the |
5887 | @option{-gnat83} switch when compiling Ada 83 programs, because, with rare | |
5888 | exceptions, Ada 95 is upwardly compatible with Ada 83. This | |
5889 | means that a correct Ada 83 program is usually also a correct Ada 95 | |
5890 | program. | |
7cd4527e | 5891 | For further information, please refer to @ref{Compatibility and Porting Guide}. |
88e1739c FW |
5892 | |
5893 | @end table | |
5894 | ||
5895 | @node Character Set Control | |
5896 | @subsection Character Set Control | |
7cd4527e | 5897 | @table @option |
88e1739c | 5898 | @item ^-gnati^/IDENTIFIER_CHARACTER_SET=^@var{c} |
7cd4527e | 5899 | @cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@code{gcc}) |
88e1739c FW |
5900 | |
5901 | @noindent | |
5902 | Normally GNAT recognizes the Latin-1 character set in source program | |
5903 | identifiers, as described in the Ada 95 Reference Manual. | |
5904 | This switch causes | |
5905 | GNAT to recognize alternate character sets in identifiers. @var{c} is a | |
5906 | single character ^^or word^ indicating the character set, as follows: | |
5907 | ||
5908 | @table @code | |
5909 | @item 1 | |
7cd4527e | 5910 | ISO 8859-1 (Latin-1) identifiers |
88e1739c FW |
5911 | |
5912 | @item 2 | |
7cd4527e | 5913 | ISO 8859-2 (Latin-2) letters allowed in identifiers |
88e1739c FW |
5914 | |
5915 | @item 3 | |
7cd4527e | 5916 | ISO 8859-3 (Latin-3) letters allowed in identifiers |
88e1739c FW |
5917 | |
5918 | @item 4 | |
7cd4527e | 5919 | ISO 8859-4 (Latin-4) letters allowed in identifiers |
88e1739c FW |
5920 | |
5921 | @item 5 | |
7cd4527e | 5922 | ISO 8859-5 (Cyrillic) letters allowed in identifiers |
88e1739c FW |
5923 | |
5924 | @item 9 | |
7cd4527e | 5925 | ISO 8859-15 (Latin-9) letters allowed in identifiers |
88e1739c FW |
5926 | |
5927 | @item ^p^PC^ | |
5928 | IBM PC letters (code page 437) allowed in identifiers | |
5929 | ||
5930 | @item ^8^PC850^ | |
5931 | IBM PC letters (code page 850) allowed in identifiers | |
5932 | ||
5933 | @item ^f^FULL_UPPER^ | |
5934 | Full upper-half codes allowed in identifiers | |
5935 | ||
5936 | @item ^n^NO_UPPER^ | |
5937 | No upper-half codes allowed in identifiers | |
5938 | ||
5939 | @item ^w^WIDE^ | |
5940 | Wide-character codes (that is, codes greater than 255) | |
5941 | allowed in identifiers | |
5942 | @end table | |
5943 | ||
5944 | @xref{Foreign Language Representation}, for full details on the | |
5945 | implementation of these character sets. | |
5946 | ||
5947 | @item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e} | |
7cd4527e | 5948 | @cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@code{gcc}) |
88e1739c FW |
5949 | Specify the method of encoding for wide characters. |
5950 | @var{e} is one of the following: | |
5951 | ||
5952 | @table @code | |
5953 | ||
5954 | @item ^h^HEX^ | |
5955 | Hex encoding (brackets coding also recognized) | |
5956 | ||
5957 | @item ^u^UPPER^ | |
5958 | Upper half encoding (brackets encoding also recognized) | |
5959 | ||
5960 | @item ^s^SHIFT_JIS^ | |
5961 | Shift/JIS encoding (brackets encoding also recognized) | |
5962 | ||
5963 | @item ^e^EUC^ | |
5964 | EUC encoding (brackets encoding also recognized) | |
5965 | ||
5966 | @item ^8^UTF8^ | |
5967 | UTF-8 encoding (brackets encoding also recognized) | |
5968 | ||
5969 | @item ^b^BRACKETS^ | |
5970 | Brackets encoding only (default value) | |
5971 | @end table | |
5972 | For full details on the these encoding | |
5973 | methods see @xref{Wide Character Encodings}. | |
5974 | Note that brackets coding is always accepted, even if one of the other | |
5975 | options is specified, so for example @option{-gnatW8} specifies that both | |
5976 | brackets and @code{UTF-8} encodings will be recognized. The units that are | |
5977 | with'ed directly or indirectly will be scanned using the specified | |
5978 | representation scheme, and so if one of the non-brackets scheme is | |
5979 | used, it must be used consistently throughout the program. However, | |
5980 | since brackets encoding is always recognized, it may be conveniently | |
5981 | used in standard libraries, allowing these libraries to be used with | |
5982 | any of the available coding schemes. | |
5983 | scheme. If no @option{-gnatW?} parameter is present, then the default | |
5984 | representation is Brackets encoding only. | |
5985 | ||
5986 | Note that the wide character representation that is specified (explicitly | |
5987 | or by default) for the main program also acts as the default encoding used | |
5988 | for Wide_Text_IO files if not specifically overridden by a WCEM form | |
5989 | parameter. | |
5990 | ||
5991 | @end table | |
5992 | @node File Naming Control | |
5993 | @subsection File Naming Control | |
5994 | ||
7cd4527e | 5995 | @table @option |
88e1739c FW |
5996 | @item ^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{n} |
5997 | @cindex @option{-gnatk} (@code{gcc}) | |
7cd4527e | 5998 | Activates file name ``krunching''. @var{n}, a decimal integer in the range |
88e1739c FW |
5999 | 1-999, indicates the maximum allowable length of a file name (not |
6000 | including the @file{.ads} or @file{.adb} extension). The default is not | |
6001 | to enable file name krunching. | |
6002 | ||
6003 | For the source file naming rules, @xref{File Naming Rules}. | |
6004 | @end table | |
6005 | ||
7cd4527e | 6006 | |
88e1739c FW |
6007 | @node Subprogram Inlining Control |
6008 | @subsection Subprogram Inlining Control | |
6009 | ||
7cd4527e AC |
6010 | @table @option |
6011 | @c !sort! | |
88e1739c FW |
6012 | @item -gnatn |
6013 | @cindex @option{-gnatn} (@code{gcc}) | |
6014 | @ifclear vms | |
6015 | The @code{n} here is intended to suggest the first syllable of the | |
7cd4527e | 6016 | word ``inline''. |
88e1739c FW |
6017 | @end ifclear |
6018 | GNAT recognizes and processes @code{Inline} pragmas. However, for the | |
6019 | inlining to actually occur, optimization must be enabled. To enable | |
7cd4527e AC |
6020 | inlining of subprograms specified by pragma @code{Inline}, |
6021 | you must also specify this switch. | |
88e1739c | 6022 | In the absence of this switch, GNAT does not attempt |
7cd4527e | 6023 | inlining and does not need to access the bodies of |
88e1739c FW |
6024 | subprograms for which @code{pragma Inline} is specified if they are not |
6025 | in the current unit. | |
6026 | ||
6027 | If you specify this switch the compiler will access these bodies, | |
6028 | creating an extra source dependency for the resulting object file, and | |
6029 | where possible, the call will be inlined. | |
6030 | For further details on when inlining is possible | |
6031 | see @xref{Inlining of Subprograms}. | |
6032 | ||
6033 | @item -gnatN | |
6034 | @cindex @option{-gnatN} (@code{gcc}) | |
6035 | The front end inlining activated by this switch is generally more extensive, | |
6036 | and quite often more effective than the standard @option{-gnatn} inlining mode. | |
6037 | It will also generate additional dependencies. | |
7cd4527e AC |
6038 | Note that |
6039 | @option{-gnatN} automatically implies @option{-gnatn} so it is not necessary | |
6040 | to specify both options. | |
88e1739c FW |
6041 | @end table |
6042 | ||
6043 | @node Auxiliary Output Control | |
6044 | @subsection Auxiliary Output Control | |
6045 | ||
7cd4527e | 6046 | @table @option |
88e1739c FW |
6047 | @item -gnatt |
6048 | @cindex @option{-gnatt} (@code{gcc}) | |
6049 | @cindex Writing internal trees | |
6050 | @cindex Internal trees, writing to file | |
6051 | Causes GNAT to write the internal tree for a unit to a file (with the | |
6052 | extension @file{.adt}. | |
6053 | This not normally required, but is used by separate analysis tools. | |
6054 | Typically | |
6055 | these tools do the necessary compilations automatically, so you should | |
6056 | not have to specify this switch in normal operation. | |
6057 | ||
6058 | @item -gnatu | |
6059 | @cindex @option{-gnatu} (@code{gcc}) | |
6060 | Print a list of units required by this compilation on @file{stdout}. | |
6061 | The listing includes all units on which the unit being compiled depends | |
6062 | either directly or indirectly. | |
6063 | ||
6064 | @ifclear vms | |
6065 | @item -pass-exit-codes | |
7cd4527e | 6066 | @cindex @option{-pass-exit-codes} (@code{gcc}) |
88e1739c FW |
6067 | If this switch is not used, the exit code returned by @code{gcc} when |
6068 | compiling multiple files indicates whether all source files have | |
6069 | been successfully used to generate object files or not. | |
6070 | ||
7cd4527e | 6071 | When @option{-pass-exit-codes} is used, @code{gcc} exits with an extended |
88e1739c FW |
6072 | exit status and allows an integrated development environment to better |
6073 | react to a compilation failure. Those exit status are: | |
6074 | ||
6075 | @table @asis | |
6076 | @item 5 | |
6077 | There was an error in at least one source file. | |
6078 | @item 3 | |
6079 | At least one source file did not generate an object file. | |
6080 | @item 2 | |
6081 | The compiler died unexpectedly (internal error for example). | |
6082 | @item 0 | |
6083 | An object file has been generated for every source file. | |
6084 | @end table | |
6085 | @end ifclear | |
6086 | @end table | |
6087 | ||
6088 | @node Debugging Control | |
6089 | @subsection Debugging Control | |
6090 | ||
7cd4527e AC |
6091 | @table @option |
6092 | @c !sort! | |
88e1739c FW |
6093 | @cindex Debugging options |
6094 | @ifclear vms | |
6095 | @item -gnatd@var{x} | |
7cd4527e | 6096 | @cindex @option{-gnatd} (@code{gcc}) |
88e1739c FW |
6097 | Activate internal debugging switches. @var{x} is a letter or digit, or |
6098 | string of letters or digits, which specifies the type of debugging | |
6099 | outputs desired. Normally these are used only for internal development | |
6100 | or system debugging purposes. You can find full documentation for these | |
6101 | switches in the body of the @code{Debug} unit in the compiler source | |
6102 | file @file{debug.adb}. | |
6103 | @end ifclear | |
6104 | ||
6105 | @item -gnatG | |
6106 | @cindex @option{-gnatG} (@code{gcc}) | |
6107 | This switch causes the compiler to generate auxiliary output containing | |
6108 | a pseudo-source listing of the generated expanded code. Like most Ada | |
6109 | compilers, GNAT works by first transforming the high level Ada code into | |
6110 | lower level constructs. For example, tasking operations are transformed | |
6111 | into calls to the tasking run-time routines. A unique capability of GNAT | |
6112 | is to list this expanded code in a form very close to normal Ada source. | |
6113 | This is very useful in understanding the implications of various Ada | |
6114 | usage on the efficiency of the generated code. There are many cases in | |
6115 | Ada (e.g. the use of controlled types), where simple Ada statements can | |
6116 | generate a lot of run-time code. By using @option{-gnatG} you can identify | |
6117 | these cases, and consider whether it may be desirable to modify the coding | |
6118 | approach to improve efficiency. | |
6119 | ||
6120 | The format of the output is very similar to standard Ada source, and is | |
6121 | easily understood by an Ada programmer. The following special syntactic | |
6122 | additions correspond to low level features used in the generated code that | |
6123 | do not have any exact analogies in pure Ada source form. The following | |
6124 | is a partial list of these special constructions. See the specification | |
6125 | of package @code{Sprint} in file @file{sprint.ads} for a full list. | |
6126 | ||
6127 | @table @code | |
6128 | @item new @var{xxx} [storage_pool = @var{yyy}] | |
6129 | Shows the storage pool being used for an allocator. | |
6130 | ||
6131 | @item at end @var{procedure-name}; | |
6132 | Shows the finalization (cleanup) procedure for a scope. | |
6133 | ||
6134 | @item (if @var{expr} then @var{expr} else @var{expr}) | |
6135 | Conditional expression equivalent to the @code{x?y:z} construction in C. | |
6136 | ||
6137 | @item @var{target}^^^(@var{source}) | |
6138 | A conversion with floating-point truncation instead of rounding. | |
6139 | ||
6140 | @item @var{target}?(@var{source}) | |
6141 | A conversion that bypasses normal Ada semantic checking. In particular | |
6142 | enumeration types and fixed-point types are treated simply as integers. | |
6143 | ||
6144 | @item @var{target}?^^^(@var{source}) | |
6145 | Combines the above two cases. | |
6146 | ||
6147 | @item @var{x} #/ @var{y} | |
6148 | @itemx @var{x} #mod @var{y} | |
6149 | @itemx @var{x} #* @var{y} | |
6150 | @itemx @var{x} #rem @var{y} | |
6151 | A division or multiplication of fixed-point values which are treated as | |
6152 | integers without any kind of scaling. | |
6153 | ||
6154 | @item free @var{expr} [storage_pool = @var{xxx}] | |
6155 | Shows the storage pool associated with a @code{free} statement. | |
6156 | ||
6157 | @item freeze @var{typename} [@var{actions}] | |
6158 | Shows the point at which @var{typename} is frozen, with possible | |
6159 | associated actions to be performed at the freeze point. | |
6160 | ||
6161 | @item reference @var{itype} | |
6162 | Reference (and hence definition) to internal type @var{itype}. | |
6163 | ||
6164 | @item @var{function-name}! (@var{arg}, @var{arg}, @var{arg}) | |
6165 | Intrinsic function call. | |
6166 | ||
6167 | @item @var{labelname} : label | |
6168 | Declaration of label @var{labelname}. | |
6169 | ||
6170 | @item @var{expr} && @var{expr} && @var{expr} ... && @var{expr} | |
6171 | A multiple concatenation (same effect as @var{expr} & @var{expr} & | |
6172 | @var{expr}, but handled more efficiently). | |
6173 | ||
6174 | @item [constraint_error] | |
6175 | Raise the @code{Constraint_Error} exception. | |
6176 | ||
6177 | @item @var{expression}'reference | |
6178 | A pointer to the result of evaluating @var{expression}. | |
6179 | ||
6180 | @item @var{target-type}!(@var{source-expression}) | |
6181 | An unchecked conversion of @var{source-expression} to @var{target-type}. | |
6182 | ||
6183 | @item [@var{numerator}/@var{denominator}] | |
6184 | Used to represent internal real literals (that) have no exact | |
6185 | representation in base 2-16 (for example, the result of compile time | |
6186 | evaluation of the expression 1.0/27.0). | |
7cd4527e | 6187 | @end table |
88e1739c FW |
6188 | |
6189 | @item -gnatD | |
6190 | @cindex @option{-gnatD} (@code{gcc}) | |
7cd4527e AC |
6191 | When used in conjunction with @option{-gnatG}, this switch causes |
6192 | the expanded source, as described above for | |
6193 | @option{-gnatG} to be written to files with names | |
88e1739c | 6194 | @file{^xxx.dg^XXX_DG^}, where @file{xxx} is the normal file name, |
7cd4527e AC |
6195 | instead of to the standard ooutput file. For |
6196 | example, if the source file name is @file{hello.adb}, then a file | |
6197 | @file{^hello.adb.dg^HELLO.ADB_DG^} will be written. The debugging | |
6198 | information generated by the @code{gcc} @option{^-g^/DEBUG^} switch | |
6199 | will refer to the generated @file{^xxx.dg^XXX_DG^} file. This allows | |
6200 | you to do source level debugging using the generated code which is | |
6201 | sometimes useful for complex code, for example to find out exactly | |
6202 | which part of a complex construction raised an exception. This switch | |
6203 | also suppress generation of cross-reference information (see | |
6204 | @option{-gnatx}) since otherwise the cross-reference information | |
6205 | would refer to the @file{^.dg^.DG^} file, which would cause | |
6206 | confusion since this is not the original source file. | |
6207 | ||
6208 | Note that @option{-gnatD} actually implies @option{-gnatG} | |
6209 | automatically, so it is not necessary to give both options. | |
6210 | In other words @option{-gnatD} is equivalent to @option{-gnatDG}). | |
88e1739c | 6211 | |
7cd4527e AC |
6212 | @ifclear vms |
6213 | @item -gnatR[0|1|2|3[s]] | |
88e1739c FW |
6214 | @cindex @option{-gnatR} (@code{gcc}) |
6215 | This switch controls output from the compiler of a listing showing | |
6216 | representation information for declared types and objects. For | |
6217 | @option{-gnatR0}, no information is output (equivalent to omitting | |
6218 | the @option{-gnatR} switch). For @option{-gnatR1} (which is the default, | |
6219 | so @option{-gnatR} with no parameter has the same effect), size and alignment | |
6220 | information is listed for declared array and record types. For | |
6221 | @option{-gnatR2}, size and alignment information is listed for all | |
6222 | expression information for values that are computed at run time for | |
6223 | variant records. These symbolic expressions have a mostly obvious | |
6224 | format with #n being used to represent the value of the n'th | |
6225 | discriminant. See source files @file{repinfo.ads/adb} in the | |
7cd4527e | 6226 | @code{GNAT} sources for full details on the format of @option{-gnatR3} |
88e1739c FW |
6227 | output. If the switch is followed by an s (e.g. @option{-gnatR2s}), then |
6228 | the output is to a file with the name @file{^file.rep^file_REP^} where | |
6229 | file is the name of the corresponding source file. | |
7cd4527e AC |
6230 | @end ifclear |
6231 | @ifset vms | |
6232 | @item /REPRESENTATION_INFO | |
6233 | @cindex @option{/REPRESENTATION_INFO} (@code{gcc}) | |
6234 | This qualifier controls output from the compiler of a listing showing | |
6235 | representation information for declared types and objects. For | |
6236 | @option{/REPRESENTATION_INFO=NONE}, no information is output | |
6237 | (equivalent to omitting the @option{/REPRESENTATION_INFO} qualifier). | |
6238 | @option{/REPRESENTATION_INFO} without option is equivalent to | |
6239 | @option{/REPRESENTATION_INFO=ARRAYS}. | |
6240 | For @option{/REPRESENTATION_INFO=ARRAYS}, size and alignment | |
6241 | information is listed for declared array and record types. For | |
6242 | @option{/REPRESENTATION_INFO=OBJECTS}, size and alignment information | |
6243 | is listed for all expression information for values that are computed | |
6244 | at run time for variant records. These symbolic expressions have a mostly | |
6245 | obvious format with #n being used to represent the value of the n'th | |
6246 | discriminant. See source files @file{REPINFO.ADS/ADB} in the | |
6247 | @code{GNAT} sources for full details on the format of | |
6248 | @option{/REPRESENTATION_INFO=SYMBOLIC} output. | |
6249 | If _FILE is added at the end of an option | |
6250 | (e.g. @option{/REPRESENTATION_INFO=ARRAYS_FILE}), | |
6251 | then the output is to a file with the name @file{file_REP} where | |
6252 | file is the name of the corresponding source file. | |
6253 | @end ifset | |
6254 | ||
6255 | @item -gnatS | |
6256 | @cindex @option{-gnatS} (@code{gcc}) | |
6257 | The use of the switch @option{-gnatS} for an | |
6258 | Ada compilation will cause the compiler to output a | |
6259 | representation of package Standard in a form very | |
6260 | close to standard Ada. It is not quite possible to | |
6261 | do this and remain entirely Standard (since new | |
6262 | numeric base types cannot be created in standard | |
6263 | Ada), but the output is easily | |
6264 | readable to any Ada programmer, and is useful to | |
6265 | determine the characteristics of target dependent | |
6266 | types in package Standard. | |
88e1739c FW |
6267 | |
6268 | @item -gnatx | |
6269 | @cindex @option{-gnatx} (@code{gcc}) | |
6270 | Normally the compiler generates full cross-referencing information in | |
6271 | the @file{ALI} file. This information is used by a number of tools, | |
7cd4527e | 6272 | including @code{gnatfind} and @code{gnatxref}. The @option{-gnatx} switch |
88e1739c FW |
6273 | suppresses this information. This saves some space and may slightly |
6274 | speed up compilation, but means that these tools cannot be used. | |
6275 | @end table | |
6276 | ||
7cd4527e AC |
6277 | @node Exception Handling Control |
6278 | @subsection Exception Handling Control | |
6279 | ||
6280 | @noindent | |
6281 | GNAT uses two methods for handling exceptions at run-time. The | |
6282 | @code{longjmp/setjmp} method saves the context when entering | |
6283 | a frame with an exception handler. Then when an exception is | |
6284 | raised, the context can be restored immediately, without the | |
6285 | need for tracing stack frames. This method provides very fast | |
6286 | exception propagation, but introduces significant overhead for | |
6287 | the use of exception handlers, even if no exception is raised. | |
6288 | ||
6289 | The other approach is called ``zero cost'' exception handling. | |
6290 | With this method, the compiler builds static tables to describe | |
6291 | the exception ranges. No dynamic code is required when entering | |
6292 | a frame containing an exception handler. When an exception is | |
6293 | raised, the tables are used to control a back trace of the | |
6294 | subprogram invocation stack to locate the required exception | |
6295 | handler. This method has considerably poorer performance for | |
6296 | the propagation of exceptions, but there is no overhead for | |
6297 | exception handlers if no exception is raised. | |
6298 | ||
6299 | The following switches can be used to control which of the | |
6300 | two exception handling methods is used. | |
6301 | ||
6302 | @table @option | |
6303 | @c !sort! | |
6304 | ||
6305 | @item -gnatL | |
6306 | @cindex @option{-gnatL} (@code{gcc}) | |
6307 | This switch causes the longjmp/setjmp approach to be used | |
6308 | for exception handling. If this is the default mechanism for the | |
6309 | target (see below), then this has no effect. If the default | |
6310 | mechanism for the target is zero cost exceptions, then | |
6311 | this switch can be used to modify this default, but it must be | |
6312 | used for all units in the partition, including all run-time | |
6313 | library units. One way to achieve this is to use the | |
6314 | @option{-a} and @option{-f} switches for @code{gnatmake}. | |
6315 | This option is rarely used. One case in which it may be | |
6316 | advantageous is if you have an application where exception | |
6317 | raising is common and the overall performance of the | |
6318 | application is improved by favoring exception propagation. | |
6319 | ||
6320 | @item -gnatZ | |
6321 | @cindex @option{-gnatZ} (@code{gcc}) | |
6322 | @cindex Zero Cost Exceptions | |
6323 | This switch causes the zero cost approach to be sed | |
6324 | for exception handling. If this is the default mechanism for the | |
6325 | target (see below), then this has no effect. If the default | |
6326 | mechanism for the target is longjmp/setjmp exceptions, then | |
6327 | this switch can be used to modify this default, but it must be | |
6328 | used for all units in the partition, including all run-time | |
6329 | library units. One way to achieve this is to use the | |
6330 | @option{-a} and @option{-f} switches for @code{gnatmake}. | |
6331 | This option can only be used if the zero cost approach | |
6332 | is available for the target in use (see below). | |
6333 | @end table | |
6334 | ||
6335 | @noindent | |
6336 | The @code{longjmp/setjmp} approach is available on all targets, but | |
6337 | the @code{zero cost} approach is only available on selected targets. | |
6338 | To determine whether zero cost exceptions can be used for a | |
6339 | particular target, look at the private part of the file system.ads. | |
6340 | Either @code{GCC_ZCX_Support} or @code{Front_End_ZCX_Support} must | |
6341 | be True to use the zero cost approach. If both of these switches | |
6342 | are set to False, this means that zero cost exception handling | |
6343 | is not yet available for that target. The switch | |
6344 | @code{ZCX_By_Default} indicates the default approach. If this | |
6345 | switch is set to True, then the @code{zero cost} approach is | |
6346 | used by default. | |
6347 | ||
88e1739c FW |
6348 | @node Units to Sources Mapping Files |
6349 | @subsection Units to Sources Mapping Files | |
6350 | ||
7cd4527e | 6351 | @table @option |
88e1739c | 6352 | |
7cd4527e | 6353 | @item -gnatem^^=^@var{path} |
88e1739c FW |
6354 | @cindex @option{-gnatem} (@code{gcc}) |
6355 | A mapping file is a way to communicate to the compiler two mappings: | |
6356 | from unit names to file names (without any directory information) and from | |
6357 | file names to path names (with full directory information). These mappings | |
6358 | are used by the compiler to short-circuit the path search. | |
6359 | ||
7cd4527e AC |
6360 | The use of mapping files is not required for correct operation of the |
6361 | compiler, but mapping files can improve efficiency, particularly when | |
6362 | sources are read over a slow network connection. In normal operation, | |
6363 | you need not be concerned with the format or use of mapping files, | |
6364 | and the @option{-gnatem} switch is not a switch that you would use | |
6365 | explicitly. it is intended only for use by automatic tools such as | |
6366 | @code{gnatmake} running under the project file facility. The | |
6367 | description here of the format of mapping files is provided | |
6368 | for completeness and for possible use by other tools. | |
6369 | ||
88e1739c | 6370 | A mapping file is a sequence of sets of three lines. In each set, |
7cd4527e AC |
6371 | the first line is the unit name, in lower case, with ``@code{%s}'' |
6372 | appended for | |
6373 | specifications and ``@code{%b}'' appended for bodies; the second line is the | |
6374 | file name; and the third line is the path name. | |
88e1739c FW |
6375 | |
6376 | Example: | |
6377 | @smallexample | |
6378 | main%b | |
6379 | main.2.ada | |
6380 | /gnat/project1/sources/main.2.ada | |
6381 | @end smallexample | |
6382 | ||
6383 | When the switch @option{-gnatem} is specified, the compiler will create | |
6384 | in memory the two mappings from the specified file. If there is any problem | |
6385 | (non existent file, truncated file or duplicate entries), no mapping | |
6386 | will be created. | |
6387 | ||
6388 | Several @option{-gnatem} switches may be specified; however, only the last | |
6389 | one on the command line will be taken into account. | |
6390 | ||
6391 | When using a project file, @code{gnatmake} create a temporary mapping file | |
6392 | and communicates it to the compiler using this switch. | |
6393 | ||
6394 | @end table | |
6395 | ||
7cd4527e AC |
6396 | |
6397 | @node Integrated Preprocessing | |
6398 | @subsection Integrated Preprocessing | |
6399 | ||
6400 | @noindent | |
6401 | GNAT sources may be preprocessed immediately before compilation; the actual | |
6402 | text of the source is not the text of the source file, but is derived from it | |
6403 | through a process called preprocessing. Integrated preprocessing is specified | |
6404 | through switches @option{-gnatep} and/or @option{-gnateD}. @option{-gnatep} | |
6405 | indicates, through a text file, the preprocessing data to be used. | |
6406 | @option{-gnateD} specifies or modifies the values of preprocessing symbol. | |
6407 | ||
6408 | @noindent | |
6409 | It is recommended that @code{gnatmake} switch ^-s^/SWITCH_CHECK^ should be | |
6410 | used when Integrated Preprocessing is used. The reason is that preprocessing | |
6411 | with another Preprocessing Data file without changing the sources will | |
6412 | not trigger recompilation without this switch. | |
6413 | ||
6414 | @noindent | |
6415 | Note that @code{gnatmake} switch ^-m^/MINIMAL_RECOMPILATION^ will almost | |
6416 | always trigger recompilation for sources that are preprocessed, | |
6417 | because @code{gnatmake} cannot compute the checksum of the source after | |
6418 | preprocessing. | |
6419 | ||
6420 | @noindent | |
6421 | The actual preprocessing function is described in details in section | |
6422 | @ref{Preprocessing Using gnatprep}. This section only describes how integrated | |
6423 | preprocessing is triggered and parameterized. | |
6424 | ||
6425 | @table @code | |
6426 | ||
6427 | @item -gnatep=@var{file} | |
6428 | @cindex @option{-gnatep} (@code{gcc}) | |
6429 | This switch indicates to the compiler the file name (without directory | |
6430 | information) of the preprocessor data file to use. The preprocessor data file | |
6431 | should be found in the source directories. | |
6432 | ||
6433 | @noindent | |
6434 | A preprocessing data file is a text file with significant lines indicating | |
6435 | how should be preprocessed either a specific source or all sources not | |
6436 | mentioned in other lines. A significant line is a non empty, non comment line. | |
6437 | Comments are similar to Ada comments. | |
6438 | ||
6439 | @noindent | |
6440 | Each significant line starts with either a literal string or the character '*'. | |
6441 | A literal string is the file name (without directory information) of the source | |
6442 | to preprocess. A character '*' indicates the preprocessing for all the sources | |
6443 | that are not specified explicitly on other lines (order of the lines is not | |
6444 | significant). It is an error to have two lines with the same file name or two | |
6445 | lines starting with the character '*'. | |
6446 | ||
6447 | @noindent | |
6448 | After the file name or the character '*', another optional literal string | |
6449 | indicating the file name of the definition file to be used for preprocessing. | |
6450 | (see @ref{Form of Definitions File}. The definition files are found by the | |
6451 | compiler in one of the source directories. In some cases, when compiling | |
6452 | a source in a directory other than the current directory, if the definition | |
6453 | file is in the current directory, it may be necessary to add the current | |
6454 | directory as a source directory through switch ^-I.^/SEARCH=[]^, otherwise | |
6455 | the compiler would not find the definition file. | |
6456 | ||
6457 | @noindent | |
6458 | Then, optionally, ^switches^switches^ similar to those of @code{gnatprep} may | |
6459 | be found. Those ^switches^switches^ are: | |
6460 | ||
6461 | @table @code | |
6462 | ||
6463 | @item -b | |
6464 | Causes both preprocessor lines and the lines deleted by | |
6465 | preprocessing to be replaced by blank lines, preserving the line number. | |
6466 | This ^switch^switch^ is always implied; however, if specified after @option{-c} | |
6467 | it cancels the effect of @option{-c}. | |
6468 | ||
6469 | @item -c | |
6470 | Causes both preprocessor lines and the lines deleted | |
6471 | by preprocessing to be retained as comments marked | |
6472 | with the special string ``@code{--! }''. | |
6473 | ||
6474 | @item -Dsymbol=value | |
6475 | Define or redefine a symbol, associated with value. A symbol is an Ada | |
6476 | identifier, or an Ada reserved word, with the exception of @code{if}, | |
6477 | @code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. | |
6478 | @code{value} is either a literal string, an Ada identifier or any Ada reserved | |
6479 | word. A symbol declared with this ^switch^switch^ replaces a symbol with the | |
6480 | same name defined in a definition file. | |
6481 | ||
6482 | @item -s | |
6483 | Causes a sorted list of symbol names and values to be | |
6484 | listed on the standard output file. | |
6485 | ||
6486 | @item -u | |
6487 | Causes undefined symbols to be treated as having the value @code{FALSE} | |
6488 | in the context | |
6489 | of a preprocessor test. In the absence of this option, an undefined symbol in | |
6490 | a @code{#if} or @code{#elsif} test will be treated as an error. | |
6491 | ||
6492 | @end table | |
6493 | ||
6494 | @noindent | |
6495 | Examples of valid lines in a preprocessor data file: | |
6496 | ||
6497 | @smallexample | |
6498 | "toto.adb" "prep.def" -u | |
6499 | -- preprocess "toto.adb", using definition file "prep.def", | |
6500 | -- undefined symbol are False. | |
6501 | ||
6502 | * -c -DVERSION=V101 | |
6503 | -- preprocess all other sources without a definition file; | |
6504 | -- suppressed lined are commented; symbol VERSION has the value V101. | |
6505 | ||
6506 | "titi.adb" "prep2.def" -s | |
6507 | -- preprocess "titi.adb", using definition file "prep2.def"; | |
6508 | -- list all symbols with their values. | |
6509 | @end smallexample | |
6510 | ||
6511 | @item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value] | |
6512 | @cindex @option{-gnateD} (@code{gcc}) | |
6513 | Define or redefine a preprocessing symbol, associated with value. If no value | |
6514 | is given on the command line, then the value of the symbol is @code{True}. | |
6515 | A symbol is an identifier, following normal Ada (case-insensitive) | |
6516 | rules for its syntax, and value is any sequence (including an empty sequence) | |
6517 | of characters from the set (letters, digits, period, underline). | |
6518 | Ada reserved words may be used as symbols, with the exceptions of @code{if}, | |
6519 | @code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. | |
6520 | ||
6521 | @noindent | |
6522 | A symbol declared with this ^switch^switch^ on the command line replaces a | |
6523 | symbol with the same name either in a definition file or specified with a | |
6524 | ^switch^switch^ -D in the preprocessor data file. | |
6525 | ||
6526 | @noindent | |
6527 | This switch is similar to switch @option{^-D^/ASSOCIATE^} of @code{gnatprep}. | |
6528 | ||
6529 | @end table | |
6530 | ||
6531 | @ifset vms | |
6532 | @node Return Codes | |
6533 | @subsection Return Codes | |
6534 | @cindex Return Codes | |
6535 | @cindex @option{/RETURN_CODES=VMS} | |
6536 | ||
6537 | @noindent | |
6538 | On VMS, GNAT compiled programs return POSIX-style codes by default, | |
6539 | e.g. @option{/RETURN_CODES=POSIX}. | |
6540 | ||
6541 | To enable VMS style return codes, GNAT LINK with the option | |
6542 | @option{/RETURN_CODES=VMS}. For example: | |
6543 | ||
6544 | @smallexample | |
6545 | GNAT LINK MYMAIN.ALI /RETURN_CODES=VMS | |
6546 | @end smallexample | |
6547 | ||
6548 | @noindent | |
6549 | Programs built with /RETURN_CODES=VMS are suitable to be called in | |
6550 | VMS DCL scripts. Programs compiled with the default /RETURN_CODES=POSIX | |
6551 | are suitable for spawning with appropriate GNAT RTL routines. | |
6552 | ||
6553 | @end ifset | |
6554 | ||
6555 | ||
88e1739c FW |
6556 | @node Search Paths and the Run-Time Library (RTL) |
6557 | @section Search Paths and the Run-Time Library (RTL) | |
6558 | ||
6559 | @noindent | |
6560 | With the GNAT source-based library system, the compiler must be able to | |
6561 | find source files for units that are needed by the unit being compiled. | |
6562 | Search paths are used to guide this process. | |
6563 | ||
6564 | The compiler compiles one source file whose name must be given | |
6565 | explicitly on the command line. In other words, no searching is done | |
6566 | for this file. To find all other source files that are needed (the most | |
6567 | common being the specs of units), the compiler examines the following | |
6568 | directories, in the following order: | |
6569 | ||
6570 | @enumerate | |
6571 | @item | |
6572 | The directory containing the source file of the main unit being compiled | |
6573 | (the file name on the command line). | |
6574 | ||
6575 | @item | |
7cd4527e AC |
6576 | Each directory named by an @option{^-I^/SOURCE_SEARCH^} switch given on the |
6577 | @code{gcc} command line, in the order given. | |
88e1739c FW |
6578 | |
6579 | @item | |
6580 | @findex ADA_INCLUDE_PATH | |
6581 | Each of the directories listed in the value of the | |
6582 | @code{ADA_INCLUDE_PATH} ^environment variable^logical name^. | |
6583 | @ifclear vms | |
6584 | Construct this value | |
6585 | exactly as the @code{PATH} environment variable: a list of directory | |
6586 | names separated by colons (semicolons when working with the NT version). | |
6587 | @end ifclear | |
6588 | @ifset vms | |
6589 | Normally, define this value as a logical name containing a comma separated | |
6590 | list of directory names. | |
6591 | ||
6592 | This variable can also be defined by means of an environment string | |
6593 | (an argument to the DEC C exec* set of functions). | |
6594 | ||
6595 | Logical Name: | |
6596 | @smallexample | |
6597 | DEFINE ANOTHER_PATH FOO:[BAG] | |
6598 | DEFINE ADA_INCLUDE_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR] | |
6599 | @end smallexample | |
6600 | ||
6601 | By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] | |
6602 | first, followed by the standard Ada 95 | |
6603 | libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADAINCLUDE]. | |
7cd4527e | 6604 | If this is not redefined, the user will obtain the DEC Ada 83 IO packages |
88e1739c FW |
6605 | (Text_IO, Sequential_IO, etc) |
6606 | instead of the Ada95 packages. Thus, in order to get the Ada 95 | |
6607 | packages by default, ADA_INCLUDE_PATH must be redefined. | |
6608 | @end ifset | |
7cd4527e AC |
6609 | |
6610 | @item | |
6611 | @findex ADA_PRJ_INCLUDE_FILE | |
6612 | Each of the directories listed in the text file whose name is given | |
6613 | by the @code{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^. | |
6614 | ||
6615 | @noindent | |
6616 | @code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^ | |
6617 | driver when project files are used. It should not normally be set | |
6618 | by other means. | |
6619 | ||
88e1739c | 6620 | @item |
7cd4527e | 6621 | The content of the @file{ada_source_path} file which is part of the GNAT |
88e1739c FW |
6622 | installation tree and is used to store standard libraries such as the |
6623 | GNAT Run Time Library (RTL) source files. | |
6624 | @ifclear vms | |
6625 | @ref{Installing an Ada Library} | |
6626 | @end ifclear | |
6627 | @end enumerate | |
6628 | ||
6629 | @noindent | |
7cd4527e | 6630 | Specifying the switch @option{^-I-^/NOCURRENT_DIRECTORY^} |
88e1739c FW |
6631 | inhibits the use of the directory |
6632 | containing the source file named in the command line. You can still | |
6633 | have this directory on your search path, but in this case it must be | |
7cd4527e | 6634 | explicitly requested with a @option{^-I^/SOURCE_SEARCH^} switch. |
88e1739c | 6635 | |
7cd4527e | 6636 | Specifying the switch @option{-nostdinc} |
88e1739c FW |
6637 | inhibits the search of the default location for the GNAT Run Time |
6638 | Library (RTL) source files. | |
6639 | ||
6640 | The compiler outputs its object files and ALI files in the current | |
6641 | working directory. | |
6642 | @ifclear vms | |
7cd4527e | 6643 | Caution: The object file can be redirected with the @option{-o} switch; |
88e1739c | 6644 | however, @code{gcc} and @code{gnat1} have not been coordinated on this |
7cd4527e AC |
6645 | so the @file{ALI} file will not go to the right place. Therefore, you should |
6646 | avoid using the @option{-o} switch. | |
88e1739c FW |
6647 | @end ifclear |
6648 | ||
6649 | @findex System.IO | |
6650 | The packages @code{Ada}, @code{System}, and @code{Interfaces} and their | |
6651 | children make up the GNAT RTL, together with the simple @code{System.IO} | |
7cd4527e | 6652 | package used in the @code{"Hello World"} example. The sources for these units |
88e1739c FW |
6653 | are needed by the compiler and are kept together in one directory. Not |
6654 | all of the bodies are needed, but all of the sources are kept together | |
6655 | anyway. In a normal installation, you need not specify these directory | |
6656 | names when compiling or binding. Either the environment variables or | |
6657 | the built-in defaults cause these files to be found. | |
6658 | ||
7cd4527e AC |
6659 | In addition to the language-defined hierarchies (@code{System}, @code{Ada} and |
6660 | @code{Interfaces}), the GNAT distribution provides a fourth hierarchy, | |
6661 | consisting of child units of @code{GNAT}. This is a collection of generally | |
6662 | useful types, subprograms, etc. See the @cite{GNAT Reference Manual} for | |
6663 | further details. | |
88e1739c FW |
6664 | |
6665 | Besides simplifying access to the RTL, a major use of search paths is | |
6666 | in compiling sources from multiple directories. This can make | |
6667 | development environments much more flexible. | |
6668 | ||
7cd4527e | 6669 | |
88e1739c FW |
6670 | @node Order of Compilation Issues |
6671 | @section Order of Compilation Issues | |
6672 | ||
6673 | @noindent | |
6674 | If, in our earlier example, there was a spec for the @code{hello} | |
6675 | procedure, it would be contained in the file @file{hello.ads}; yet this | |
6676 | file would not have to be explicitly compiled. This is the result of the | |
6677 | model we chose to implement library management. Some of the consequences | |
6678 | of this model are as follows: | |
6679 | ||
6680 | @itemize @bullet | |
6681 | @item | |
6682 | There is no point in compiling specs (except for package | |
6683 | specs with no bodies) because these are compiled as needed by clients. If | |
6684 | you attempt a useless compilation, you will receive an error message. | |
6685 | It is also useless to compile subunits because they are compiled as needed | |
6686 | by the parent. | |
6687 | ||
6688 | @item | |
6689 | There are no order of compilation requirements: performing a | |
6690 | compilation never obsoletes anything. The only way you can obsolete | |
6691 | something and require recompilations is to modify one of the | |
6692 | source files on which it depends. | |
6693 | ||
6694 | @item | |
6695 | There is no library as such, apart from the ALI files | |
7cd4527e AC |
6696 | (@pxref{The Ada Library Information Files}, for information on the format |
6697 | of these files). For now we find it convenient to create separate ALI files, | |
6698 | but eventually the information therein may be incorporated into the object | |
88e1739c FW |
6699 | file directly. |
6700 | ||
6701 | @item | |
6702 | When you compile a unit, the source files for the specs of all units | |
6703 | that it @code{with}'s, all its subunits, and the bodies of any generics it | |
6704 | instantiates must be available (reachable by the search-paths mechanism | |
6705 | described above), or you will receive a fatal error message. | |
6706 | @end itemize | |
6707 | ||
6708 | @node Examples | |
6709 | @section Examples | |
6710 | ||
6711 | @noindent | |
6712 | The following are some typical Ada compilation command line examples: | |
6713 | ||
6714 | @table @code | |
6715 | @item $ gcc -c xyz.adb | |
6716 | Compile body in file @file{xyz.adb} with all default options. | |
6717 | ||
6718 | @ifclear vms | |
6719 | @item $ gcc -c -O2 -gnata xyz-def.adb | |
6720 | @end ifclear | |
6721 | @ifset vms | |
6722 | @item $ GNAT COMPILE /OPTIMIZE=ALL -gnata xyz-def.adb | |
6723 | @end ifset | |
6724 | ||
6725 | Compile the child unit package in file @file{xyz-def.adb} with extensive | |
6726 | optimizations, and pragma @code{Assert}/@code{Debug} statements | |
6727 | enabled. | |
6728 | ||
6729 | @item $ gcc -c -gnatc abc-def.adb | |
6730 | Compile the subunit in file @file{abc-def.adb} in semantic-checking-only | |
6731 | mode. | |
6732 | @end table | |
6733 | ||
6734 | @node Binding Using gnatbind | |
6735 | @chapter Binding Using @code{gnatbind} | |
6736 | @findex gnatbind | |
6737 | ||
6738 | @menu | |
6739 | * Running gnatbind:: | |
7cd4527e | 6740 | * Switches for gnatbind:: |
88e1739c FW |
6741 | * Command-Line Access:: |
6742 | * Search Paths for gnatbind:: | |
6743 | * Examples of gnatbind Usage:: | |
6744 | @end menu | |
6745 | ||
6746 | @noindent | |
6747 | This chapter describes the GNAT binder, @code{gnatbind}, which is used | |
6748 | to bind compiled GNAT objects. The @code{gnatbind} program performs | |
6749 | four separate functions: | |
6750 | ||
6751 | @enumerate | |
6752 | @item | |
6753 | Checks that a program is consistent, in accordance with the rules in | |
6754 | Chapter 10 of the Ada 95 Reference Manual. In particular, error | |
6755 | messages are generated if a program uses inconsistent versions of a | |
6756 | given unit. | |
6757 | ||
6758 | @item | |
6759 | Checks that an acceptable order of elaboration exists for the program | |
6760 | and issues an error message if it cannot find an order of elaboration | |
6761 | that satisfies the rules in Chapter 10 of the Ada 95 Language Manual. | |
6762 | ||
6763 | @item | |
6764 | Generates a main program incorporating the given elaboration order. | |
6765 | This program is a small Ada package (body and spec) that | |
6766 | must be subsequently compiled | |
6767 | using the GNAT compiler. The necessary compilation step is usually | |
6768 | performed automatically by @code{gnatlink}. The two most important | |
6769 | functions of this program | |
6770 | are to call the elaboration routines of units in an appropriate order | |
6771 | and to call the main program. | |
6772 | ||
6773 | @item | |
6774 | Determines the set of object files required by the given main program. | |
6775 | This information is output in the forms of comments in the generated program, | |
6776 | to be read by the @code{gnatlink} utility used to link the Ada application. | |
6777 | @end enumerate | |
6778 | ||
7cd4527e | 6779 | |
88e1739c FW |
6780 | @node Running gnatbind |
6781 | @section Running @code{gnatbind} | |
6782 | ||
6783 | @noindent | |
6784 | The form of the @code{gnatbind} command is | |
6785 | ||
6786 | @smallexample | |
7cd4527e | 6787 | $ gnatbind [@i{switches}] @i{mainprog}[.ali] [@i{switches}] |
88e1739c FW |
6788 | @end smallexample |
6789 | ||
6790 | @noindent | |
7cd4527e | 6791 | where @file{@i{mainprog}.adb} is the Ada file containing the main program |
88e1739c | 6792 | unit body. If no switches are specified, @code{gnatbind} constructs an Ada |
7cd4527e AC |
6793 | package in two files whose names are |
6794 | @file{b~@i{mainprog}.ads}, and @file{b~@i{mainprog}.adb}. | |
88e1739c | 6795 | For example, if given the |
7cd4527e | 6796 | parameter @file{hello.ali}, for a main program contained in file |
88e1739c FW |
6797 | @file{hello.adb}, the binder output files would be @file{b~hello.ads} |
6798 | and @file{b~hello.adb}. | |
6799 | ||
6800 | When doing consistency checking, the binder takes into consideration | |
6801 | any source files it can locate. For example, if the binder determines | |
6802 | that the given main program requires the package @code{Pack}, whose | |
7cd4527e | 6803 | @file{.ALI} |
88e1739c FW |
6804 | file is @file{pack.ali} and whose corresponding source spec file is |
6805 | @file{pack.ads}, it attempts to locate the source file @file{pack.ads} | |
6806 | (using the same search path conventions as previously described for the | |
6807 | @code{gcc} command). If it can locate this source file, it checks that | |
6808 | the time stamps | |
7cd4527e AC |
6809 | or source checksums of the source and its references to in @file{ALI} files |
6810 | match. In other words, any @file{ALI} files that mentions this spec must have | |
88e1739c FW |
6811 | resulted from compiling this version of the source file (or in the case |
6812 | where the source checksums match, a version close enough that the | |
6813 | difference does not matter). | |
6814 | ||
6815 | @cindex Source files, use by binder | |
6816 | The effect of this consistency checking, which includes source files, is | |
6817 | that the binder ensures that the program is consistent with the latest | |
6818 | version of the source files that can be located at bind time. Editing a | |
6819 | source file without compiling files that depend on the source file cause | |
6820 | error messages to be generated by the binder. | |
6821 | ||
6822 | For example, suppose you have a main program @file{hello.adb} and a | |
6823 | package @code{P}, from file @file{p.ads} and you perform the following | |
6824 | steps: | |
6825 | ||
6826 | @enumerate | |
6827 | @item | |
6828 | Enter @code{gcc -c hello.adb} to compile the main program. | |
6829 | ||
6830 | @item | |
6831 | Enter @code{gcc -c p.ads} to compile package @code{P}. | |
6832 | ||
6833 | @item | |
6834 | Edit file @file{p.ads}. | |
6835 | ||
6836 | @item | |
6837 | Enter @code{gnatbind hello}. | |
6838 | @end enumerate | |
6839 | ||
7cd4527e | 6840 | @noindent |
88e1739c FW |
6841 | At this point, the file @file{p.ali} contains an out-of-date time stamp |
6842 | because the file @file{p.ads} has been edited. The attempt at binding | |
6843 | fails, and the binder generates the following error messages: | |
6844 | ||
6845 | @smallexample | |
6846 | error: "hello.adb" must be recompiled ("p.ads" has been modified) | |
6847 | error: "p.ads" has been modified and must be recompiled | |
6848 | @end smallexample | |
6849 | ||
6850 | @noindent | |
6851 | Now both files must be recompiled as indicated, and then the bind can | |
6852 | succeed, generating a main program. You need not normally be concerned | |
7cd4527e AC |
6853 | with the contents of this file, but for reference purposes a sample |
6854 | binder output file is given in @ref{Example of Binder Output File}. | |
88e1739c | 6855 | |
7cd4527e AC |
6856 | In most normal usage, the default mode of @command{gnatbind} which is to |
6857 | generate the main package in Ada, as described in the previous section. | |
6858 | In particular, this means that any Ada programmer can read and understand | |
6859 | the generated main program. It can also be debugged just like any other | |
6860 | Ada code provided the @option{^-g^/DEBUG^} switch is used for | |
6861 | @command{gnatbind} and @command{gnatlink}. | |
88e1739c | 6862 | |
7cd4527e AC |
6863 | However for some purposes it may be convenient to generate the main |
6864 | program in C rather than Ada. This may for example be helpful when you | |
6865 | are generating a mixed language program with the main program in C. The | |
6866 | GNAT compiler itself is an example. | |
6867 | The use of the @option{^-C^/BIND_FILE=C^} switch | |
6868 | for both @code{gnatbind} and @code{gnatlink} will cause the program to | |
6869 | be generated in C (and compiled using the gnu C compiler). | |
88e1739c | 6870 | |
88e1739c | 6871 | |
7cd4527e AC |
6872 | @node Switches for gnatbind |
6873 | @section Switches for @command{gnatbind} | |
88e1739c | 6874 | |
7cd4527e AC |
6875 | @noindent |
6876 | The following switches are available with @code{gnatbind}; details will | |
6877 | be presented in subsequent sections. | |
88e1739c | 6878 | |
7cd4527e AC |
6879 | @menu |
6880 | * Consistency-Checking Modes:: | |
6881 | * Binder Error Message Control:: | |
6882 | * Elaboration Control:: | |
6883 | * Output Control:: | |
6884 | * Binding with Non-Ada Main Programs:: | |
6885 | * Binding Programs with No Main Subprogram:: | |
6886 | @end menu | |
88e1739c | 6887 | |
7cd4527e AC |
6888 | @table @option |
6889 | @c !sort! | |
6890 | @item ^-aO^/OBJECT_SEARCH^ | |
6891 | @cindex @option{^-aO^/OBJECT_SEARCH^} (@command{gnatbind}) | |
6892 | Specify directory to be searched for ALI files. | |
88e1739c | 6893 | |
7cd4527e AC |
6894 | @item ^-aI^/SOURCE_SEARCH^ |
6895 | @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind}) | |
6896 | Specify directory to be searched for source file. | |
88e1739c | 6897 | |
7cd4527e AC |
6898 | @item ^-A^/BIND_FILE=ADA^ |
6899 | @cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatbind}) | |
6900 | Generate binder program in Ada (default) | |
88e1739c | 6901 | |
7cd4527e AC |
6902 | @item ^-b^/REPORT_ERRORS=BRIEF^ |
6903 | @cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@command{gnatbind}) | |
6904 | Generate brief messages to @file{stderr} even if verbose mode set. | |
88e1739c | 6905 | |
7cd4527e AC |
6906 | @item ^-c^/NOOUTPUT^ |
6907 | @cindex @option{^-c^/NOOUTPUT^} (@command{gnatbind}) | |
6908 | Check only, no generation of binder output file. | |
88e1739c | 6909 | |
7cd4527e AC |
6910 | @item ^-C^/BIND_FILE=C^ |
6911 | @cindex @option{^-C^/BIND_FILE=C^} (@command{gnatbind}) | |
6912 | Generate binder program in C | |
88e1739c | 6913 | |
7cd4527e AC |
6914 | @item ^-e^/ELABORATION_DEPENDENCIES^ |
6915 | @cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@command{gnatbind}) | |
6916 | Output complete list of elaboration-order dependencies. | |
88e1739c | 6917 | |
7cd4527e AC |
6918 | @item ^-E^/STORE_TRACEBACKS^ |
6919 | @cindex @option{^-E^/STORE_TRACEBACKS^} (@command{gnatbind}) | |
6920 | Store tracebacks in exception occurrences when the target supports it. | |
6921 | This is the default with the zero cost exception mechanism. | |
6922 | @ignore | |
6923 | @c The following may get moved to an appendix | |
6924 | This option is currently supported on the following targets: | |
6925 | all x86 ports, Solaris, Windows, HP-UX, AIX, PowerPC VxWorks and Alpha VxWorks. | |
6926 | @end ignore | |
6927 | See also the packages @code{GNAT.Traceback} and | |
6928 | @code{GNAT.Traceback.Symbolic} for more information. | |
6929 | @ifclear vms | |
6930 | Note that on x86 ports, you must not use @option{-fomit-frame-pointer} | |
6931 | @code{gcc} option. | |
6932 | @end ifclear vms | |
6933 | ||
6934 | @item ^-F^/FORCE_ELABS_FLAGS^ | |
6935 | @cindex @option{^-F^/FORCE_ELABS_FLAGS^} (@command{gnatbind}) | |
6936 | Force the checks of elaboration flags. @command{gnatbind} does not normally | |
6937 | generate checks of elaboration flags for the main executable, except when | |
6938 | a Stand-Alone Library is used. However, there are cases when this cannot be | |
6939 | detected by gnatbind. An example is importing an interface of a Stand-Alone | |
6940 | Library through a pragma Import and only specifying through a linker switch | |
6941 | this Stand-Alone Library. This switch is used to guarantee that elaboration | |
6942 | flag checks are generated. | |
88e1739c | 6943 | |
7cd4527e AC |
6944 | @item ^-h^/HELP^ |
6945 | @cindex @option{^-h^/HELP^} (@command{gnatbind}) | |
6946 | Output usage (help) information | |
88e1739c | 6947 | |
7cd4527e AC |
6948 | @item ^-I^/SEARCH^ |
6949 | @cindex @option{^-I^/SEARCH^} (@command{gnatbind}) | |
6950 | Specify directory to be searched for source and ALI files. | |
88e1739c | 6951 | |
7cd4527e AC |
6952 | @item ^-I-^/NOCURRENT_DIRECTORY^ |
6953 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatbind}) | |
6954 | Do not look for sources in the current directory where @code{gnatbind} was | |
6955 | invoked, and do not look for ALI files in the directory containing the | |
6956 | ALI file named in the @code{gnatbind} command line. | |
88e1739c | 6957 | |
7cd4527e AC |
6958 | @item ^-l^/ORDER_OF_ELABORATION^ |
6959 | @cindex @option{^-l^/ORDER_OF_ELABORATION^} (@command{gnatbind}) | |
6960 | Output chosen elaboration order. | |
88e1739c | 6961 | |
7cd4527e AC |
6962 | @item ^-Lxxx^/BUILD_LIBRARY=xxx^ |
6963 | @cindex @option{^-L^/BUILD_LIBRARY^} (@command{gnatbind}) | |
6964 | Binds the units for library building. In this case the adainit and | |
6965 | adafinal procedures (See @pxref{Binding with Non-Ada Main Programs}) | |
6966 | are renamed to ^xxxinit^XXXINIT^ and | |
6967 | ^xxxfinal^XXXFINAL^. | |
6968 | Implies ^-n^/NOCOMPILE^. | |
6969 | @ifclear vms | |
6970 | (@pxref{GNAT and Libraries}, for more details.) | |
6971 | @end ifclear | |
6972 | @ifset vms | |
6973 | On OpenVMS, these init and final procedures are exported in uppercase | |
6974 | letters. For example if /BUILD_LIBRARY=toto is used, the exported name of | |
6975 | the init procedure will be "TOTOINIT" and the exported name of the final | |
6976 | procedure will be "TOTOFINAL". | |
6977 | @end ifset | |
88e1739c | 6978 | |
7cd4527e AC |
6979 | @item ^-Mxyz^/RENAME_MAIN=xyz^ |
6980 | @cindex @option{^-M^/RENAME_MAIN^} (@command{gnatbind}) | |
6981 | Rename generated main program from main to xyz | |
88e1739c | 6982 | |
7cd4527e AC |
6983 | @item ^-m^/ERROR_LIMIT=^@var{n} |
6984 | @cindex @option{^-m^/ERROR_LIMIT^} (@command{gnatbind}) | |
6985 | Limit number of detected errors to @var{n}, where @var{n} is | |
6986 | in the range 1..999_999. The default value if no switch is | |
6987 | given is 9999. Binding is terminated if the limit is exceeded. | |
6988 | @ifset unw | |
6989 | Furthermore, under Windows, the sources pointed to by the libraries path | |
6990 | set in the registry are not searched for. | |
6991 | @end ifset | |
88e1739c | 6992 | |
7cd4527e AC |
6993 | @item ^-n^/NOMAIN^ |
6994 | @cindex @option{^-n^/NOMAIN^} (@command{gnatbind}) | |
6995 | No main program. | |
88e1739c | 6996 | |
7cd4527e AC |
6997 | @item -nostdinc |
6998 | @cindex @option{-nostdinc} (@command{gnatbind}) | |
6999 | Do not look for sources in the system default directory. | |
88e1739c | 7000 | |
7cd4527e AC |
7001 | @item -nostdlib |
7002 | @cindex @option{-nostdlib} (@command{gnatbind}) | |
7003 | Do not look for library files in the system default directory. | |
88e1739c | 7004 | |
7cd4527e AC |
7005 | @item --RTS=@var{rts-path} |
7006 | @cindex @option{--RTS} (@code{gnatbind}) | |
7007 | Specifies the default location of the runtime library. Same meaning as the | |
7008 | equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}). | |
88e1739c | 7009 | |
7cd4527e AC |
7010 | @item ^-o ^/OUTPUT=^@var{file} |
7011 | @cindex @option{^-o ^/OUTPUT^} (@command{gnatbind}) | |
7012 | Name the output file @var{file} (default is @file{b~@var{xxx}.adb}). | |
7013 | Note that if this option is used, then linking must be done manually, | |
7014 | gnatlink cannot be used. | |
88e1739c | 7015 | |
7cd4527e AC |
7016 | @item ^-O^/OBJECT_LIST^ |
7017 | @cindex @option{^-O^/OBJECT_LIST^} (@command{gnatbind}) | |
7018 | Output object list. | |
88e1739c | 7019 | |
7cd4527e AC |
7020 | @item ^-p^/PESSIMISTIC_ELABORATION^ |
7021 | @cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@command{gnatbind}) | |
7022 | Pessimistic (worst-case) elaboration order | |
88e1739c | 7023 | |
7cd4527e AC |
7024 | @item ^-s^/READ_SOURCES=ALL^ |
7025 | @cindex @option{^-s^/READ_SOURCES=ALL^} (@command{gnatbind}) | |
7026 | Require all source files to be present. | |
88e1739c | 7027 | |
7cd4527e AC |
7028 | @item ^-S@var{xxx}^/INITIALIZE_SCALARS=@var{xxx}^ |
7029 | @cindex @option{^-S^/INITIALIZE_SCALARS^} (@command{gnatbind}) | |
7030 | Specifies the value to be used when detecting uninitialized scalar | |
7031 | objects with pragma Initialize_Scalars. | |
7032 | The @var{xxx} ^string specified with the switch^option^ may be either | |
7033 | @itemize @bullet | |
7034 | @item ``@option{^in^INVALID^}'' requesting an invalid value where possible | |
7035 | @item ``@option{^lo^LOW^}'' for the lowest possible value | |
7036 | possible, and the low | |
7037 | @item ``@option{^hi^HIGH^}'' for the highest possible value | |
7038 | @item ``@option{xx}'' for a value consisting of repeated bytes with the | |
7039 | value 16#xx# (i.e. xx is a string of two hexadecimal digits). | |
7040 | @end itemize | |
88e1739c | 7041 | |
7cd4527e AC |
7042 | In addition, you can specify @option{-Sev} to indicate that the value is |
7043 | to be set at run time. In this case, the program will look for an environment | |
7044 | @cindex GNAT_INIT_SCALARS | |
7045 | variable of the form @code{GNAT_INIT_SCALARS=xx}, where xx is one | |
7046 | of @option{in/lo/hi/xx} with the same meanings as above. | |
7047 | If no environment variable is found, or if it does not have a valid value, | |
7048 | then the default is @option{in} (invalid values). | |
88e1739c | 7049 | |
7cd4527e AC |
7050 | @ifclear vms |
7051 | @item -static | |
7052 | @cindex @option{-static} (@code{gnatbind}) | |
7053 | Link against a static GNAT run time. | |
88e1739c | 7054 | |
7cd4527e AC |
7055 | @item -shared |
7056 | @cindex @option{-shared} (@code{gnatbind}) | |
7057 | Link against a shared GNAT run time when available. | |
7058 | @end ifclear | |
88e1739c | 7059 | |
7cd4527e AC |
7060 | @item ^-t^/NOTIME_STAMP_CHECK^ |
7061 | @cindex @option{^-t^/NOTIME_STAMP_CHECK^} (@code{gnatbind}) | |
7062 | Tolerate time stamp and other consistency errors | |
88e1739c | 7063 | |
7cd4527e AC |
7064 | @item ^-T@var{n}^/TIME_SLICE=@var{n}^ |
7065 | @cindex @option{^-T^/TIME_SLICE^} (@code{gnatbind}) | |
7066 | Set the time slice value to @var{n} milliseconds. If the system supports | |
7067 | the specification of a specific time slice value, then the indicated value | |
7068 | is used. If the system does not support specific time slice values, but | |
7069 | does support some general notion of round-robin scheduling, then any | |
7070 | non-zero value will activate round-robin scheduling. | |
88e1739c | 7071 | |
7cd4527e AC |
7072 | A value of zero is treated specially. It turns off time |
7073 | slicing, and in addition, indicates to the tasking run time that the | |
7074 | semantics should match as closely as possible the Annex D | |
7075 | requirements of the Ada RM, and in particular sets the default | |
7076 | scheduling policy to @code{FIFO_Within_Priorities}. | |
88e1739c | 7077 | |
7cd4527e AC |
7078 | @item ^-v^/REPORT_ERRORS=VERBOSE^ |
7079 | @cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind}) | |
7080 | Verbose mode. Write error messages, header, summary output to | |
7081 | @file{stdout}. | |
88e1739c | 7082 | |
7cd4527e AC |
7083 | @ifclear vms |
7084 | @item -w@var{x} | |
7085 | @cindex @option{-w} (@code{gnatbind}) | |
7086 | Warning mode (@var{x}=s/e for suppress/treat as error) | |
7087 | @end ifclear | |
88e1739c | 7088 | |
7cd4527e AC |
7089 | @ifset vms |
7090 | @item /WARNINGS=NORMAL | |
7091 | @cindex @option{/WARNINGS} (@code{gnatbind}) | |
7092 | Normal warnings mode. Warnings are issued but ignored | |
88e1739c | 7093 | |
7cd4527e AC |
7094 | @item /WARNINGS=SUPPRESS |
7095 | @cindex @option{/WARNINGS} (@code{gnatbind}) | |
7096 | All warning messages are suppressed | |
88e1739c | 7097 | |
7cd4527e AC |
7098 | @item /WARNINGS=ERROR |
7099 | @cindex @option{/WARNINGS} (@code{gnatbind}) | |
7100 | Warning messages are treated as fatal errors | |
7101 | @end ifset | |
88e1739c | 7102 | |
7cd4527e AC |
7103 | @item ^-x^/READ_SOURCES=NONE^ |
7104 | @cindex @option{^-x^/READ_SOURCES^} (@code{gnatbind}) | |
7105 | Exclude source files (check object consistency only). | |
88e1739c | 7106 | |
7cd4527e AC |
7107 | @ifset vms |
7108 | @item /READ_SOURCES=AVAILABLE | |
7109 | @cindex @option{/READ_SOURCES} (@code{gnatbind}) | |
7110 | Default mode, in which sources are checked for consistency only if | |
7111 | they are available. | |
7112 | @end ifset | |
88e1739c | 7113 | |
7cd4527e AC |
7114 | @item ^-z^/ZERO_MAIN^ |
7115 | @cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind}) | |
7116 | No main subprogram. | |
7117 | @end table | |
88e1739c | 7118 | |
7cd4527e AC |
7119 | @ifclear vms |
7120 | @noindent | |
7121 | You may obtain this listing of switches by running @code{gnatbind} with | |
7122 | no arguments. | |
7123 | @end ifclear | |
88e1739c | 7124 | |
88e1739c | 7125 | |
7cd4527e AC |
7126 | @node Consistency-Checking Modes |
7127 | @subsection Consistency-Checking Modes | |
88e1739c | 7128 | |
7cd4527e AC |
7129 | @noindent |
7130 | As described earlier, by default @code{gnatbind} checks | |
7131 | that object files are consistent with one another and are consistent | |
7132 | with any source files it can locate. The following switches control binder | |
7133 | access to sources. | |
88e1739c | 7134 | |
7cd4527e AC |
7135 | @table @option |
7136 | @c !sort! | |
7137 | @item ^-s^/READ_SOURCES=ALL^ | |
7138 | @cindex @option{^-s^/READ_SOURCES=ALL^} (@code{gnatbind}) | |
7139 | Require source files to be present. In this mode, the binder must be | |
7140 | able to locate all source files that are referenced, in order to check | |
7141 | their consistency. In normal mode, if a source file cannot be located it | |
7142 | is simply ignored. If you specify this switch, a missing source | |
7143 | file is an error. | |
88e1739c | 7144 | |
7cd4527e AC |
7145 | @item ^-x^/READ_SOURCES=NONE^ |
7146 | @cindex @option{^-x^/READ_SOURCES=NONE^} (@code{gnatbind}) | |
7147 | Exclude source files. In this mode, the binder only checks that ALI | |
7148 | files are consistent with one another. Source files are not accessed. | |
7149 | The binder runs faster in this mode, and there is still a guarantee that | |
7150 | the resulting program is self-consistent. | |
7151 | If a source file has been edited since it was last compiled, and you | |
7152 | specify this switch, the binder will not detect that the object | |
7153 | file is out of date with respect to the source file. Note that this is the | |
7154 | mode that is automatically used by @code{gnatmake} because in this | |
7155 | case the checking against sources has already been performed by | |
7156 | @code{gnatmake} in the course of compilation (i.e. before binding). | |
88e1739c | 7157 | |
7cd4527e AC |
7158 | @ifset vms |
7159 | @item /READ_SOURCES=AVAILABLE | |
7160 | @cindex @code{/READ_SOURCES=AVAILABLE} (@code{gnatbind}) | |
7161 | This is the default mode in which source files are checked if they are | |
7162 | available, and ignored if they are not available. | |
7163 | @end ifset | |
7164 | @end table | |
88e1739c | 7165 | |
7cd4527e AC |
7166 | @node Binder Error Message Control |
7167 | @subsection Binder Error Message Control | |
88e1739c | 7168 | |
7cd4527e AC |
7169 | @noindent |
7170 | The following switches provide control over the generation of error | |
7171 | messages from the binder: | |
88e1739c | 7172 | |
7cd4527e AC |
7173 | @table @option |
7174 | @c !sort! | |
7175 | @item ^-v^/REPORT_ERRORS=VERBOSE^ | |
7176 | @cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind}) | |
7177 | Verbose mode. In the normal mode, brief error messages are generated to | |
7178 | @file{stderr}. If this switch is present, a header is written | |
7179 | to @file{stdout} and any error messages are directed to @file{stdout}. | |
7180 | All that is written to @file{stderr} is a brief summary message. | |
88e1739c | 7181 | |
7cd4527e AC |
7182 | @item ^-b^/REPORT_ERRORS=BRIEF^ |
7183 | @cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@code{gnatbind}) | |
7184 | Generate brief error messages to @file{stderr} even if verbose mode is | |
7185 | specified. This is relevant only when used with the | |
7186 | @option{^-v^/REPORT_ERRORS=VERBOSE^} switch. | |
88e1739c | 7187 | |
7cd4527e AC |
7188 | @ifclear vms |
7189 | @item -m@var{n} | |
7190 | @cindex @option{-m} (@code{gnatbind}) | |
7191 | Limits the number of error messages to @var{n}, a decimal integer in the | |
7192 | range 1-999. The binder terminates immediately if this limit is reached. | |
88e1739c | 7193 | |
7cd4527e AC |
7194 | @item -M@var{xxx} |
7195 | @cindex @option{-M} (@code{gnatbind}) | |
7196 | Renames the generated main program from @code{main} to @code{xxx}. | |
7197 | This is useful in the case of some cross-building environments, where | |
7198 | the actual main program is separate from the one generated | |
7199 | by @code{gnatbind}. | |
7200 | @end ifclear | |
88e1739c | 7201 | |
7cd4527e AC |
7202 | @item ^-ws^/WARNINGS=SUPPRESS^ |
7203 | @cindex @option{^-ws^/WARNINGS=SUPPRESS^} (@code{gnatbind}) | |
7204 | @cindex Warnings | |
7205 | Suppress all warning messages. | |
88e1739c | 7206 | |
7cd4527e AC |
7207 | @item ^-we^/WARNINGS=ERROR^ |
7208 | @cindex @option{^-we^/WARNINGS=ERROR^} (@code{gnatbind}) | |
7209 | Treat any warning messages as fatal errors. | |
88e1739c | 7210 | |
7cd4527e AC |
7211 | @ifset vms |
7212 | @item /WARNINGS=NORMAL | |
7213 | Standard mode with warnings generated, but warnings do not get treated | |
7214 | as errors. | |
7215 | @end ifset | |
88e1739c | 7216 | |
7cd4527e AC |
7217 | @item ^-t^/NOTIME_STAMP_CHECK^ |
7218 | @cindex @option{^-t^/NOTIME_STAMP_CHECK^} (@code{gnatbind}) | |
7219 | @cindex Time stamp checks, in binder | |
7220 | @cindex Binder consistency checks | |
7221 | @cindex Consistency checks, in binder | |
7222 | The binder performs a number of consistency checks including: | |
88e1739c FW |
7223 | |
7224 | @itemize @bullet | |
7225 | @item | |
7226 | Check that time stamps of a given source unit are consistent | |
7227 | @item | |
7228 | Check that checksums of a given source unit are consistent | |
7229 | @item | |
7230 | Check that consistent versions of @code{GNAT} were used for compilation | |
7231 | @item | |
7232 | Check consistency of configuration pragmas as required | |
7233 | @end itemize | |
7234 | ||
7235 | @noindent | |
7236 | Normally failure of such checks, in accordance with the consistency | |
7237 | requirements of the Ada Reference Manual, causes error messages to be | |
7238 | generated which abort the binder and prevent the output of a binder | |
7239 | file and subsequent link to obtain an executable. | |
7240 | ||
7cd4527e | 7241 | The @option{^-t^/NOTIME_STAMP_CHECK^} switch converts these error messages |
88e1739c FW |
7242 | into warnings, so that |
7243 | binding and linking can continue to completion even in the presence of such | |
7244 | errors. The result may be a failed link (due to missing symbols), or a | |
7245 | non-functional executable which has undefined semantics. | |
7246 | @emph{This means that | |
7cd4527e | 7247 | @option{^-t^/NOTIME_STAMP_CHECK^} should be used only in unusual situations, |
88e1739c FW |
7248 | with extreme care.} |
7249 | @end table | |
7250 | ||
7251 | @node Elaboration Control | |
7cd4527e | 7252 | @subsection Elaboration Control |
88e1739c FW |
7253 | |
7254 | @noindent | |
7255 | The following switches provide additional control over the elaboration | |
7256 | order. For full details see @xref{Elaboration Order Handling in GNAT}. | |
7257 | ||
7cd4527e | 7258 | @table @option |
88e1739c | 7259 | @item ^-p^/PESSIMISTIC_ELABORATION^ |
7cd4527e | 7260 | @cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@code{gnatbind}) |
88e1739c FW |
7261 | Normally the binder attempts to choose an elaboration order that is |
7262 | likely to minimize the likelihood of an elaboration order error resulting | |
7263 | in raising a @code{Program_Error} exception. This switch reverses the | |
7264 | action of the binder, and requests that it deliberately choose an order | |
7265 | that is likely to maximize the likelihood of an elaboration error. | |
7266 | This is useful in ensuring portability and avoiding dependence on | |
7267 | accidental fortuitous elaboration ordering. | |
7268 | ||
7cd4527e AC |
7269 | Normally it only makes sense to use the @option{^-p^/PESSIMISTIC_ELABORATION^} |
7270 | switch if dynamic | |
88e1739c FW |
7271 | elaboration checking is used (@option{-gnatE} switch used for compilation). |
7272 | This is because in the default static elaboration mode, all necessary | |
7cd4527e AC |
7273 | @code{Elaborate_All} pragmas are implicitly inserted. |
7274 | These implicit pragmas are still respected by the binder in | |
7275 | @option{^-p^/PESSIMISTIC_ELABORATION^} mode, so a | |
88e1739c FW |
7276 | safe elaboration order is assured. |
7277 | @end table | |
7278 | ||
7279 | @node Output Control | |
7cd4527e | 7280 | @subsection Output Control |
88e1739c FW |
7281 | |
7282 | @noindent | |
7283 | The following switches allow additional control over the output | |
7284 | generated by the binder. | |
7285 | ||
7cd4527e AC |
7286 | @table @option |
7287 | @c !sort! | |
88e1739c FW |
7288 | |
7289 | @item ^-A^/BIND_FILE=ADA^ | |
7cd4527e | 7290 | @cindex @option{^-A^/BIND_FILE=ADA^} (@code{gnatbind}) |
88e1739c FW |
7291 | Generate binder program in Ada (default). The binder program is named |
7292 | @file{b~@var{mainprog}.adb} by default. This can be changed with | |
7cd4527e | 7293 | @option{^-o^/OUTPUT^} @code{gnatbind} option. |
88e1739c FW |
7294 | |
7295 | @item ^-c^/NOOUTPUT^ | |
7cd4527e | 7296 | @cindex @option{^-c^/NOOUTPUT^} (@code{gnatbind}) |
88e1739c FW |
7297 | Check only. Do not generate the binder output file. In this mode the |
7298 | binder performs all error checks but does not generate an output file. | |
7299 | ||
7300 | @item ^-C^/BIND_FILE=C^ | |
7cd4527e | 7301 | @cindex @option{^-C^/BIND_FILE=C^} (@code{gnatbind}) |
88e1739c | 7302 | Generate binder program in C. The binder program is named |
7cd4527e AC |
7303 | @file{b_@var{mainprog}.c}. |
7304 | This can be changed with @option{^-o^/OUTPUT^} @code{gnatbind} | |
88e1739c FW |
7305 | option. |
7306 | ||
7307 | @item ^-e^/ELABORATION_DEPENDENCIES^ | |
7cd4527e | 7308 | @cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@code{gnatbind}) |
88e1739c FW |
7309 | Output complete list of elaboration-order dependencies, showing the |
7310 | reason for each dependency. This output can be rather extensive but may | |
7311 | be useful in diagnosing problems with elaboration order. The output is | |
7312 | written to @file{stdout}. | |
7313 | ||
7314 | @item ^-h^/HELP^ | |
7cd4527e | 7315 | @cindex @option{^-h^/HELP^} (@code{gnatbind}) |
88e1739c FW |
7316 | Output usage information. The output is written to @file{stdout}. |
7317 | ||
7318 | @item ^-K^/LINKER_OPTION_LIST^ | |
7cd4527e | 7319 | @cindex @option{^-K^/LINKER_OPTION_LIST^} (@code{gnatbind}) |
88e1739c FW |
7320 | Output linker options to @file{stdout}. Includes library search paths, |
7321 | contents of pragmas Ident and Linker_Options, and libraries added | |
7322 | by @code{gnatbind}. | |
7323 | ||
7324 | @item ^-l^/ORDER_OF_ELABORATION^ | |
7cd4527e | 7325 | @cindex @option{^-l^/ORDER_OF_ELABORATION^} (@code{gnatbind}) |
88e1739c FW |
7326 | Output chosen elaboration order. The output is written to @file{stdout}. |
7327 | ||
7328 | @item ^-O^/OBJECT_LIST^ | |
7cd4527e | 7329 | @cindex @option{^-O^/OBJECT_LIST^} (@code{gnatbind}) |
88e1739c FW |
7330 | Output full names of all the object files that must be linked to provide |
7331 | the Ada component of the program. The output is written to @file{stdout}. | |
7332 | This list includes the files explicitly supplied and referenced by the user | |
7333 | as well as implicitly referenced run-time unit files. The latter are | |
7334 | omitted if the corresponding units reside in shared libraries. The | |
7335 | directory names for the run-time units depend on the system configuration. | |
7336 | ||
7337 | @item ^-o ^/OUTPUT=^@var{file} | |
7cd4527e | 7338 | @cindex @option{^-o^/OUTPUT^} (@code{gnatbind}) |
88e1739c FW |
7339 | Set name of output file to @var{file} instead of the normal |
7340 | @file{b~@var{mainprog}.adb} default. Note that @var{file} denote the Ada | |
7341 | binder generated body filename. In C mode you would normally give | |
7342 | @var{file} an extension of @file{.c} because it will be a C source program. | |
7343 | Note that if this option is used, then linking must be done manually. | |
7344 | It is not possible to use gnatlink in this case, since it cannot locate | |
7345 | the binder file. | |
7346 | ||
7347 | @item ^-r^/RESTRICTION_LIST^ | |
7cd4527e AC |
7348 | @cindex @option{^-r^/RESTRICTION_LIST^} (@code{gnatbind}) |
7349 | Generate list of @code{pragma Restrictions} that could be applied to | |
88e1739c FW |
7350 | the current unit. This is useful for code audit purposes, and also may |
7351 | be used to improve code generation in some cases. | |
7352 | ||
7353 | @end table | |
7354 | ||
7355 | @node Binding with Non-Ada Main Programs | |
7cd4527e | 7356 | @subsection Binding with Non-Ada Main Programs |
88e1739c FW |
7357 | |
7358 | @noindent | |
7359 | In our description so far we have assumed that the main | |
7360 | program is in Ada, and that the task of the binder is to generate a | |
7361 | corresponding function @code{main} that invokes this Ada main | |
7362 | program. GNAT also supports the building of executable programs where | |
7363 | the main program is not in Ada, but some of the called routines are | |
7364 | written in Ada and compiled using GNAT (@pxref{Mixed Language Programming}). | |
7365 | The following switch is used in this situation: | |
7366 | ||
7cd4527e | 7367 | @table @option |
88e1739c | 7368 | @item ^-n^/NOMAIN^ |
7cd4527e | 7369 | @cindex @option{^-n^/NOMAIN^} (@code{gnatbind}) |
88e1739c FW |
7370 | No main program. The main program is not in Ada. |
7371 | @end table | |
7372 | ||
7373 | @noindent | |
7374 | In this case, most of the functions of the binder are still required, | |
7375 | but instead of generating a main program, the binder generates a file | |
7376 | containing the following callable routines: | |
7377 | ||
7378 | @table @code | |
7379 | @item adainit | |
7380 | @findex adainit | |
7381 | You must call this routine to initialize the Ada part of the program by | |
7382 | calling the necessary elaboration routines. A call to @code{adainit} is | |
7383 | required before the first call to an Ada subprogram. | |
7384 | ||
7385 | Note that it is assumed that the basic execution environment must be setup | |
7386 | to be appropriate for Ada execution at the point where the first Ada | |
7387 | subprogram is called. In particular, if the Ada code will do any | |
7388 | floating-point operations, then the FPU must be setup in an appropriate | |
7389 | manner. For the case of the x86, for example, full precision mode is | |
7390 | required. The procedure GNAT.Float_Control.Reset may be used to ensure | |
7391 | that the FPU is in the right state. | |
7392 | ||
7393 | @item adafinal | |
7394 | @findex adafinal | |
7395 | You must call this routine to perform any library-level finalization | |
7396 | required by the Ada subprograms. A call to @code{adafinal} is required | |
7397 | after the last call to an Ada subprogram, and before the program | |
7398 | terminates. | |
7399 | @end table | |
7400 | ||
7401 | @noindent | |
7cd4527e AC |
7402 | If the @option{^-n^/NOMAIN^} switch |
7403 | @cindex @option{^-n^/NOMAIN^} (@command{gnatbind}) | |
88e1739c FW |
7404 | @cindex Binder, multiple input files |
7405 | is given, more than one ALI file may appear on | |
7406 | the command line for @code{gnatbind}. The normal @dfn{closure} | |
7407 | calculation is performed for each of the specified units. Calculating | |
7408 | the closure means finding out the set of units involved by tracing | |
7409 | @code{with} references. The reason it is necessary to be able to | |
7410 | specify more than one ALI file is that a given program may invoke two or | |
7411 | more quite separate groups of Ada units. | |
7412 | ||
7413 | The binder takes the name of its output file from the last specified ALI | |
7cd4527e AC |
7414 | file, unless overridden by the use of the @option{^-o file^/OUTPUT=file^}. |
7415 | @cindex @option{^-o^/OUTPUT^} (@command{gnatbind}) | |
88e1739c FW |
7416 | The output is an Ada unit in source form that can |
7417 | be compiled with GNAT unless the -C switch is used in which case the | |
7418 | output is a C source file, which must be compiled using the C compiler. | |
7419 | This compilation occurs automatically as part of the @code{gnatlink} | |
7420 | processing. | |
7421 | ||
7422 | Currently the GNAT run time requires a FPU using 80 bits mode | |
7423 | precision. Under targets where this is not the default it is required to | |
7424 | call GNAT.Float_Control.Reset before using floating point numbers (this | |
7425 | include float computation, float input and output) in the Ada code. A | |
7426 | side effect is that this could be the wrong mode for the foreign code | |
7427 | where floating point computation could be broken after this call. | |
7428 | ||
7429 | @node Binding Programs with No Main Subprogram | |
7cd4527e | 7430 | @subsection Binding Programs with No Main Subprogram |
88e1739c FW |
7431 | |
7432 | @noindent | |
7433 | It is possible to have an Ada program which does not have a main | |
7434 | subprogram. This program will call the elaboration routines of all the | |
7435 | packages, then the finalization routines. | |
7436 | ||
7437 | The following switch is used to bind programs organized in this manner: | |
7438 | ||
7cd4527e | 7439 | @table @option |
88e1739c | 7440 | @item ^-z^/ZERO_MAIN^ |
7cd4527e | 7441 | @cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind}) |
88e1739c FW |
7442 | Normally the binder checks that the unit name given on the command line |
7443 | corresponds to a suitable main subprogram. When this switch is used, | |
7444 | a list of ALI files can be given, and the execution of the program | |
7445 | consists of elaboration of these units in an appropriate order. | |
7446 | @end table | |
7447 | ||
7cd4527e AC |
7448 | |
7449 | @node Command-Line Access | |
7450 | @section Command-Line Access | |
88e1739c FW |
7451 | |
7452 | @noindent | |
7cd4527e AC |
7453 | The package @code{Ada.Command_Line} provides access to the command-line |
7454 | arguments and program name. In order for this interface to operate | |
7455 | correctly, the two variables | |
88e1739c | 7456 | |
7cd4527e AC |
7457 | @smallexample |
7458 | @group | |
7459 | int gnat_argc; | |
7460 | char **gnat_argv; | |
7461 | @end group | |
7462 | @end smallexample | |
88e1739c FW |
7463 | |
7464 | @noindent | |
7465 | @findex gnat_argv | |
7466 | @findex gnat_argc | |
7467 | are declared in one of the GNAT library routines. These variables must | |
7468 | be set from the actual @code{argc} and @code{argv} values passed to the | |
7cd4527e | 7469 | main program. With no @option{^n^/NOMAIN^} present, @code{gnatbind} |
88e1739c | 7470 | generates the C main program to automatically set these variables. |
7cd4527e | 7471 | If the @option{^n^/NOMAIN^} switch is used, there is no automatic way to |
88e1739c FW |
7472 | set these variables. If they are not set, the procedures in |
7473 | @code{Ada.Command_Line} will not be available, and any attempt to use | |
7474 | them will raise @code{Constraint_Error}. If command line access is | |
7475 | required, your main program must set @code{gnat_argc} and | |
7476 | @code{gnat_argv} from the @code{argc} and @code{argv} values passed to | |
7477 | it. | |
7478 | ||
7cd4527e | 7479 | |
88e1739c FW |
7480 | @node Search Paths for gnatbind |
7481 | @section Search Paths for @code{gnatbind} | |
7482 | ||
7483 | @noindent | |
7484 | The binder takes the name of an ALI file as its argument and needs to | |
7485 | locate source files as well as other ALI files to verify object consistency. | |
7486 | ||
7487 | For source files, it follows exactly the same search rules as @code{gcc} | |
7488 | (@pxref{Search Paths and the Run-Time Library (RTL)}). For ALI files the | |
7489 | directories searched are: | |
7490 | ||
7491 | @enumerate | |
7492 | @item | |
7493 | The directory containing the ALI file named in the command line, unless | |
7cd4527e | 7494 | the switch @option{^-I-^/NOCURRENT_DIRECTORY^} is specified. |
88e1739c FW |
7495 | |
7496 | @item | |
7cd4527e | 7497 | All directories specified by @option{^-I^/SEARCH^} |
88e1739c FW |
7498 | switches on the @code{gnatbind} |
7499 | command line, in the order given. | |
7500 | ||
7501 | @item | |
7502 | @findex ADA_OBJECTS_PATH | |
7503 | Each of the directories listed in the value of the | |
7504 | @code{ADA_OBJECTS_PATH} ^environment variable^logical name^. | |
7cd4527e | 7505 | @ifset unw |
88e1739c FW |
7506 | Construct this value |
7507 | exactly as the @code{PATH} environment variable: a list of directory | |
7508 | names separated by colons (semicolons when working with the NT version | |
7509 | of GNAT). | |
7cd4527e | 7510 | @end ifset |
88e1739c FW |
7511 | @ifset vms |
7512 | Normally, define this value as a logical name containing a comma separated | |
7513 | list of directory names. | |
7514 | ||
7515 | This variable can also be defined by means of an environment string | |
7516 | (an argument to the DEC C exec* set of functions). | |
7517 | ||
7518 | Logical Name: | |
7519 | @smallexample | |
7520 | DEFINE ANOTHER_PATH FOO:[BAG] | |
7521 | DEFINE ADA_OBJECTS_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR] | |
7522 | @end smallexample | |
7523 | ||
7524 | By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] | |
7525 | first, followed by the standard Ada 95 | |
7526 | libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB]. | |
7cd4527e | 7527 | If this is not redefined, the user will obtain the DEC Ada 83 IO packages |
88e1739c FW |
7528 | (Text_IO, Sequential_IO, etc) |
7529 | instead of the Ada95 packages. Thus, in order to get the Ada 95 | |
7530 | packages by default, ADA_OBJECTS_PATH must be redefined. | |
7531 | @end ifset | |
7532 | ||
7533 | @item | |
7cd4527e AC |
7534 | @findex ADA_PRJ_OBJECTS_FILE |
7535 | Each of the directories listed in the text file whose name is given | |
7536 | by the @code{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^. | |
7537 | ||
7538 | @noindent | |
7539 | @code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^ | |
7540 | driver when project files are used. It should not normally be set | |
7541 | by other means. | |
7542 | ||
7543 | @item | |
7544 | The content of the @file{ada_object_path} file which is part of the GNAT | |
88e1739c | 7545 | installation tree and is used to store standard libraries such as the |
7cd4527e | 7546 | GNAT Run Time Library (RTL) unless the switch @option{-nostdlib} is |
88e1739c FW |
7547 | specified. |
7548 | @ifclear vms | |
7549 | @ref{Installing an Ada Library} | |
7550 | @end ifclear | |
7551 | @end enumerate | |
7552 | ||
7553 | @noindent | |
7cd4527e AC |
7554 | In the binder the switch @option{^-I^/SEARCH^} |
7555 | @cindex @option{^-I^/SEARCH^} (@command{gnatbind}) | |
88e1739c | 7556 | is used to specify both source and |
7cd4527e AC |
7557 | library file paths. Use @option{^-aI^/SOURCE_SEARCH^} |
7558 | @cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind}) | |
88e1739c | 7559 | instead if you want to specify |
7cd4527e AC |
7560 | source paths only, and @option{^-aO^/LIBRARY_SEARCH^} |
7561 | @cindex @option{^-aO^/LIBRARY_SEARCH^} (@command{gnatbind}) | |
88e1739c FW |
7562 | if you want to specify library paths |
7563 | only. This means that for the binder | |
7cd4527e AC |
7564 | @option{^-I^/SEARCH=^}@var{dir} is equivalent to |
7565 | @option{^-aI^/SOURCE_SEARCH=^}@var{dir} | |
7566 | @option{^-aO^/OBJECT_SEARCH=^}@var{dir}. | |
88e1739c FW |
7567 | The binder generates the bind file (a C language source file) in the |
7568 | current working directory. | |
7569 | ||
7570 | @findex Ada | |
7571 | @findex System | |
7572 | @findex Interfaces | |
7573 | @findex GNAT | |
7574 | The packages @code{Ada}, @code{System}, and @code{Interfaces} and their | |
7575 | children make up the GNAT Run-Time Library, together with the package | |
7576 | GNAT and its children, which contain a set of useful additional | |
7577 | library functions provided by GNAT. The sources for these units are | |
7578 | needed by the compiler and are kept together in one directory. The ALI | |
7579 | files and object files generated by compiling the RTL are needed by the | |
7580 | binder and the linker and are kept together in one directory, typically | |
7581 | different from the directory containing the sources. In a normal | |
7582 | installation, you need not specify these directory names when compiling | |
7583 | or binding. Either the environment variables or the built-in defaults | |
7584 | cause these files to be found. | |
7585 | ||
7586 | Besides simplifying access to the RTL, a major use of search paths is | |
7587 | in compiling sources from multiple directories. This can make | |
7588 | development environments much more flexible. | |
7589 | ||
7590 | @node Examples of gnatbind Usage | |
7591 | @section Examples of @code{gnatbind} Usage | |
7592 | ||
7593 | @noindent | |
7594 | This section contains a number of examples of using the GNAT binding | |
7595 | utility @code{gnatbind}. | |
7596 | ||
7597 | @table @code | |
7598 | @item gnatbind hello | |
7599 | The main program @code{Hello} (source program in @file{hello.adb}) is | |
7600 | bound using the standard switch settings. The generated main program is | |
7601 | @file{b~hello.adb}. This is the normal, default use of the binder. | |
7602 | ||
7603 | @ifclear vms | |
7604 | @item gnatbind hello -o mainprog.adb | |
7605 | @end ifclear | |
7606 | @ifset vms | |
7607 | @item gnatbind HELLO.ALI /OUTPUT=Mainprog.ADB | |
7608 | @end ifset | |
7609 | The main program @code{Hello} (source program in @file{hello.adb}) is | |
7610 | bound using the standard switch settings. The generated main program is | |
7611 | @file{mainprog.adb} with the associated spec in | |
7612 | @file{mainprog.ads}. Note that you must specify the body here not the | |
7613 | spec, in the case where the output is in Ada. Note that if this option | |
7614 | is used, then linking must be done manually, since gnatlink will not | |
7615 | be able to find the generated file. | |
7616 | ||
7617 | @ifclear vms | |
7618 | @item gnatbind main -C -o mainprog.c -x | |
7619 | @end ifclear | |
7620 | @ifset vms | |
7621 | @item gnatbind MAIN.ALI /BIND_FILE=C /OUTPUT=Mainprog.C /READ_SOURCES=NONE | |
7622 | @end ifset | |
7623 | The main program @code{Main} (source program in | |
7624 | @file{main.adb}) is bound, excluding source files from the | |
7625 | consistency checking, generating | |
7626 | the file @file{mainprog.c}. | |
7627 | ||
7628 | @ifclear vms | |
7629 | @item gnatbind -x main_program -C -o mainprog.c | |
7630 | This command is exactly the same as the previous example. Switches may | |
7631 | appear anywhere in the command line, and single letter switches may be | |
7632 | combined into a single switch. | |
7633 | @end ifclear | |
7634 | ||
7635 | @ifclear vms | |
7636 | @item gnatbind -n math dbase -C -o ada-control.c | |
7637 | @end ifclear | |
7638 | @ifset vms | |
7639 | @item gnatbind /NOMAIN math dbase /BIND_FILE=C /OUTPUT=ada-control.c | |
7640 | @end ifset | |
7641 | The main program is in a language other than Ada, but calls to | |
7642 | subprograms in packages @code{Math} and @code{Dbase} appear. This call | |
7643 | to @code{gnatbind} generates the file @file{ada-control.c} containing | |
7644 | the @code{adainit} and @code{adafinal} routines to be called before and | |
7645 | after accessing the Ada units. | |
7646 | @end table | |
7647 | ||
7cd4527e AC |
7648 | |
7649 | @c ------------------------------------ | |
88e1739c FW |
7650 | @node Linking Using gnatlink |
7651 | @chapter Linking Using @code{gnatlink} | |
7cd4527e | 7652 | @c ------------------------------------ |
88e1739c FW |
7653 | @findex gnatlink |
7654 | ||
7655 | @noindent | |
7cd4527e AC |
7656 | This chapter discusses @code{gnatlink}, a tool that links |
7657 | an Ada program and builds an executable file. This utility | |
7658 | invokes the system linker ^(via the @code{gcc} command)^^ | |
7659 | with a correct list of object files and library references. | |
88e1739c FW |
7660 | @code{gnatlink} automatically determines the list of files and |
7661 | references for the Ada part of a program. It uses the binder file | |
7cd4527e | 7662 | generated by the @command{gnatbind} to determine this list. |
88e1739c FW |
7663 | |
7664 | @menu | |
7665 | * Running gnatlink:: | |
7666 | * Switches for gnatlink:: | |
7667 | * Setting Stack Size from gnatlink:: | |
7668 | * Setting Heap Size from gnatlink:: | |
7669 | @end menu | |
7670 | ||
7671 | @node Running gnatlink | |
7672 | @section Running @code{gnatlink} | |
7673 | ||
7674 | @noindent | |
7675 | The form of the @code{gnatlink} command is | |
7676 | ||
7677 | @smallexample | |
7cd4527e AC |
7678 | $ gnatlink [@var{switches}] @var{mainprog}[.ali] |
7679 | [@var{non-Ada objects}] [@var{linker options}] | |
88e1739c FW |
7680 | @end smallexample |
7681 | ||
7cd4527e AC |
7682 | @noindent |
7683 | The arguments of @code{gnatlink} (switches, main @file{ALI} file, | |
7684 | non-Ada objects | |
7685 | or linker options) may be in any order, provided that no non-Ada object may | |
7686 | be mistaken for a main @file{ALI} file. | |
7687 | Any file name @file{F} without the @file{.ali} | |
7688 | extension will be taken as the main @file{ALI} file if a file exists | |
7689 | whose name is the concatenation of @file{F} and @file{.ali}. | |
7690 | ||
88e1739c FW |
7691 | @noindent |
7692 | @file{@var{mainprog}.ali} references the ALI file of the main program. | |
7693 | The @file{.ali} extension of this file can be omitted. From this | |
7694 | reference, @code{gnatlink} locates the corresponding binder file | |
7695 | @file{b~@var{mainprog}.adb} and, using the information in this file along | |
7cd4527e | 7696 | with the list of non-Ada objects and linker options, constructs a |
88e1739c FW |
7697 | linker command file to create the executable. |
7698 | ||
7cd4527e AC |
7699 | The arguments other than the @code{gnatlink} switches and the main @file{ALI} |
7700 | file are passed to the linker uninterpreted. | |
7701 | They typically include the names of | |
7702 | object files for units written in other languages than Ada and any library | |
7703 | references required to resolve references in any of these foreign language | |
7704 | units, or in @code{Import} pragmas in any Ada units. | |
88e1739c FW |
7705 | |
7706 | @var{linker options} is an optional list of linker specific | |
7cd4527e AC |
7707 | switches. |
7708 | The default linker called by gnatlink is @var{gcc} which in | |
7709 | turn calls the appropriate system linker. | |
7710 | Standard options for the linker such as @option{-lmy_lib} or | |
7711 | @option{-Ldir} can be added as is. | |
7712 | For options that are not recognized by | |
7713 | @var{gcc} as linker options, use the @var{gcc} switches @option{-Xlinker} or | |
7714 | @option{-Wl,}. | |
7715 | Refer to the GCC documentation for | |
7716 | details. Here is an example showing how to generate a linker map: | |
88e1739c | 7717 | |
7cd4527e | 7718 | @ifclear vms |
88e1739c FW |
7719 | @smallexample |
7720 | $ gnatlink my_prog -Wl,-Map,MAPFILE | |
7721 | @end smallexample | |
7cd4527e AC |
7722 | @end ifclear |
7723 | ||
7724 | @ifset vms | |
7725 | <<Need example for VMS>> | |
7726 | @end ifset | |
88e1739c FW |
7727 | |
7728 | Using @var{linker options} it is possible to set the program stack and | |
7cd4527e AC |
7729 | heap size. See @ref{Setting Stack Size from gnatlink}, and |
7730 | @ref{Setting Heap Size from gnatlink}. | |
88e1739c FW |
7731 | |
7732 | @code{gnatlink} determines the list of objects required by the Ada | |
7733 | program and prepends them to the list of objects passed to the linker. | |
7734 | @code{gnatlink} also gathers any arguments set by the use of | |
7735 | @code{pragma Linker_Options} and adds them to the list of arguments | |
7736 | presented to the linker. | |
7737 | ||
7738 | @ifset vms | |
7739 | @code{gnatlink} accepts the following types of extra files on the command | |
7cd4527e | 7740 | line: objects (.OBJ), libraries (.OLB), sharable images (.EXE), and |
88e1739c FW |
7741 | options files (.OPT). These are recognized and handled according to their |
7742 | extension. | |
7743 | @end ifset | |
7744 | ||
7745 | @node Switches for gnatlink | |
7746 | @section Switches for @code{gnatlink} | |
7747 | ||
7748 | @noindent | |
7749 | The following switches are available with the @code{gnatlink} utility: | |
7750 | ||
7cd4527e AC |
7751 | @table @option |
7752 | @c !sort! | |
88e1739c FW |
7753 | |
7754 | @item ^-A^/BIND_FILE=ADA^ | |
7cd4527e | 7755 | @cindex @option{^-A^/BIND_FILE=ADA^} (@code{gnatlink}) |
88e1739c FW |
7756 | The binder has generated code in Ada. This is the default. |
7757 | ||
7758 | @item ^-C^/BIND_FILE=C^ | |
7cd4527e | 7759 | @cindex @option{^-C^/BIND_FILE=C^} (@code{gnatlink}) |
88e1739c FW |
7760 | If instead of generating a file in Ada, the binder has generated one in |
7761 | C, then the linker needs to know about it. Use this switch to signal | |
7762 | to @code{gnatlink} that the binder has generated C code rather than | |
7763 | Ada code. | |
7764 | ||
7cd4527e | 7765 | @item ^-f^/FORCE_OBJECT_FILE_LIST^ |
88e1739c | 7766 | @cindex Command line length |
7cd4527e | 7767 | @cindex @option{^-f^/FORCE_OBJECT_FILE_LIST^} (@code{gnatlink}) |
88e1739c FW |
7768 | On some targets, the command line length is limited, and @code{gnatlink} |
7769 | will generate a separate file for the linker if the list of object files | |
7cd4527e AC |
7770 | is too long. |
7771 | The @option{^-f^/FORCE_OBJECT_FILE_LIST^} switch forces this file | |
7772 | to be generated even if | |
88e1739c FW |
7773 | the limit is not exceeded. This is useful in some cases to deal with |
7774 | special situations where the command line length is exceeded. | |
7775 | ||
7776 | @item ^-g^/DEBUG^ | |
7777 | @cindex Debugging information, including | |
7cd4527e | 7778 | @cindex @option{^-g^/DEBUG^} (@code{gnatlink}) |
88e1739c FW |
7779 | The option to include debugging information causes the Ada bind file (in |
7780 | other words, @file{b~@var{mainprog}.adb}) to be compiled with | |
7cd4527e | 7781 | @option{^-g^/DEBUG^}. |
88e1739c FW |
7782 | In addition, the binder does not delete the @file{b~@var{mainprog}.adb}, |
7783 | @file{b~@var{mainprog}.o} and @file{b~@var{mainprog}.ali} files. | |
7cd4527e | 7784 | Without @option{^-g^/DEBUG^}, the binder removes these files by |
88e1739c | 7785 | default. The same procedure apply if a C bind file was generated using |
7cd4527e AC |
7786 | @option{^-C^/BIND_FILE=C^} @code{gnatbind} option, in this case the filenames |
7787 | are @file{b_@var{mainprog}.c} and @file{b_@var{mainprog}.o}. | |
88e1739c | 7788 | |
7cd4527e AC |
7789 | @item ^-n^/NOCOMPILE^ |
7790 | @cindex @option{^-n^/NOCOMPILE^} (@code{gnatlink}) | |
88e1739c FW |
7791 | Do not compile the file generated by the binder. This may be used when |
7792 | a link is rerun with different options, but there is no need to recompile | |
7793 | the binder file. | |
88e1739c FW |
7794 | |
7795 | @item ^-v^/VERBOSE^ | |
7cd4527e | 7796 | @cindex @option{^-v^/VERBOSE^} (@code{gnatlink}) |
88e1739c FW |
7797 | Causes additional information to be output, including a full list of the |
7798 | included object files. This switch option is most useful when you want | |
7799 | to see what set of object files are being used in the link step. | |
7800 | ||
7cd4527e AC |
7801 | @item ^-v -v^/VERBOSE/VERBOSE^ |
7802 | @cindex @option{^-v -v^/VERBOSE/VERBOSE^} (@code{gnatlink}) | |
88e1739c FW |
7803 | Very verbose mode. Requests that the compiler operate in verbose mode when |
7804 | it compiles the binder file, and that the system linker run in verbose mode. | |
88e1739c FW |
7805 | |
7806 | @item ^-o ^/EXECUTABLE=^@var{exec-name} | |
7cd4527e | 7807 | @cindex @option{^-o^/EXECUTABLE^} (@code{gnatlink}) |
88e1739c FW |
7808 | @var{exec-name} specifies an alternate name for the generated |
7809 | executable program. If this switch is omitted, the executable has the same | |
7810 | name as the main unit. For example, @code{gnatlink try.ali} creates | |
7811 | an executable called @file{^try^TRY.EXE^}. | |
7812 | ||
7813 | @ifclear vms | |
7814 | @item -b @var{target} | |
7cd4527e | 7815 | @cindex @option{-b} (@code{gnatlink}) |
88e1739c FW |
7816 | Compile your program to run on @var{target}, which is the name of a |
7817 | system configuration. You must have a GNAT cross-compiler built if | |
7818 | @var{target} is not the same as your host system. | |
7819 | ||
7820 | @item -B@var{dir} | |
7cd4527e | 7821 | @cindex @option{-B} (@code{gnatlink}) |
88e1739c FW |
7822 | Load compiler executables (for example, @code{gnat1}, the Ada compiler) |
7823 | from @var{dir} instead of the default location. Only use this switch | |
7824 | when multiple versions of the GNAT compiler are available. See the | |
7825 | @code{gcc} manual page for further details. You would normally use the | |
7cd4527e | 7826 | @option{-b} or @option{-V} switch instead. |
88e1739c FW |
7827 | |
7828 | @item --GCC=@var{compiler_name} | |
7cd4527e | 7829 | @cindex @option{--GCC=compiler_name} (@code{gnatlink}) |
88e1739c FW |
7830 | Program used for compiling the binder file. The default is |
7831 | `@code{gcc}'. You need to use quotes around @var{compiler_name} if | |
7832 | @code{compiler_name} contains spaces or other separator characters. As | |
7cd4527e AC |
7833 | an example @option{--GCC="foo -x -y"} will instruct @code{gnatlink} to use |
7834 | @code{foo -x -y} as your compiler. Note that switch @option{-c} is always | |
88e1739c FW |
7835 | inserted after your command name. Thus in the above example the compiler |
7836 | command that will be used by @code{gnatlink} will be @code{foo -c -x -y}. | |
7cd4527e | 7837 | If several @option{--GCC=compiler_name} are used, only the last |
88e1739c FW |
7838 | @var{compiler_name} is taken into account. However, all the additional |
7839 | switches are also taken into account. Thus, | |
7cd4527e AC |
7840 | @option{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to |
7841 | @option{--GCC="bar -x -y -z -t"}. | |
88e1739c FW |
7842 | |
7843 | @item --LINK=@var{name} | |
7cd4527e | 7844 | @cindex @option{--LINK=} (@code{gnatlink}) |
88e1739c | 7845 | @var{name} is the name of the linker to be invoked. This is especially |
7cd4527e | 7846 | useful in mixed language programs since languages such as C++ require |
88e1739c FW |
7847 | their own linker to be used. When this switch is omitted, the default |
7848 | name for the linker is (@file{gcc}). When this switch is used, the | |
7849 | specified linker is called instead of (@file{gcc}) with exactly the same | |
7850 | parameters that would have been passed to (@file{gcc}) so if the desired | |
7851 | linker requires different parameters it is necessary to use a wrapper | |
7852 | script that massages the parameters before invoking the real linker. It | |
7853 | may be useful to control the exact invocation by using the verbose | |
7854 | switch. | |
7855 | ||
7856 | @end ifclear | |
7857 | ||
7858 | @ifset vms | |
7859 | @item /DEBUG=TRACEBACK | |
7860 | @cindex @code{/DEBUG=TRACEBACK} (@code{gnatlink}) | |
7861 | This qualifier causes sufficient information to be included in the | |
7862 | executable file to allow a traceback, but does not include the full | |
7863 | symbol information needed by the debugger. | |
7864 | ||
7865 | @item /IDENTIFICATION="<string>" | |
7cd4527e AC |
7866 | @code{"<string>"} specifies the string to be stored in the image file |
7867 | identification field in the image header. | |
7868 | It overrides any pragma @code{Ident} specified string. | |
88e1739c FW |
7869 | |
7870 | @item /NOINHIBIT-EXEC | |
7871 | Generate the executable file even if there are linker warnings. | |
7872 | ||
7873 | @item /NOSTART_FILES | |
7cd4527e | 7874 | Don't link in the object file containing the ``main'' transfer address. |
88e1739c FW |
7875 | Used when linking with a foreign language main program compiled with a |
7876 | Digital compiler. | |
7877 | ||
7878 | @item /STATIC | |
7cd4527e | 7879 | Prefer linking with object libraries over sharable images, even without |
88e1739c FW |
7880 | /DEBUG. |
7881 | @end ifset | |
7882 | ||
7883 | @end table | |
7884 | ||
7885 | @node Setting Stack Size from gnatlink | |
7886 | @section Setting Stack Size from @code{gnatlink} | |
7887 | ||
7888 | @noindent | |
7cd4527e AC |
7889 | Under Windows systems, it is possible to specify the program stack size from |
7890 | @code{gnatlink} using either: | |
88e1739c FW |
7891 | |
7892 | @itemize @bullet | |
7893 | ||
7cd4527e | 7894 | @item using @option{-Xlinker} linker option |
88e1739c FW |
7895 | |
7896 | @smallexample | |
7897 | $ gnatlink hello -Xlinker --stack=0x10000,0x1000 | |
7898 | @end smallexample | |
7899 | ||
7cd4527e | 7900 | This sets the stack reserve size to 0x10000 bytes and the stack commit |
88e1739c FW |
7901 | size to 0x1000 bytes. |
7902 | ||
7cd4527e | 7903 | @item using @option{-Wl} linker option |
88e1739c FW |
7904 | |
7905 | @smallexample | |
7906 | $ gnatlink hello -Wl,--stack=0x1000000 | |
7907 | @end smallexample | |
7908 | ||
7cd4527e AC |
7909 | This sets the stack reserve size to 0x1000000 bytes. Note that with |
7910 | @option{-Wl} option it is not possible to set the stack commit size | |
88e1739c FW |
7911 | because the coma is a separator for this option. |
7912 | ||
7913 | @end itemize | |
7914 | ||
7915 | @node Setting Heap Size from gnatlink | |
7916 | @section Setting Heap Size from @code{gnatlink} | |
7917 | ||
7918 | @noindent | |
7cd4527e AC |
7919 | Under Windows systems, it is possible to specify the program heap size from |
7920 | @code{gnatlink} using either: | |
88e1739c FW |
7921 | |
7922 | @itemize @bullet | |
7923 | ||
7cd4527e | 7924 | @item using @option{-Xlinker} linker option |
88e1739c FW |
7925 | |
7926 | @smallexample | |
7927 | $ gnatlink hello -Xlinker --heap=0x10000,0x1000 | |
7928 | @end smallexample | |
7929 | ||
7cd4527e | 7930 | This sets the heap reserve size to 0x10000 bytes and the heap commit |
88e1739c FW |
7931 | size to 0x1000 bytes. |
7932 | ||
7cd4527e | 7933 | @item using @option{-Wl} linker option |
88e1739c FW |
7934 | |
7935 | @smallexample | |
7936 | $ gnatlink hello -Wl,--heap=0x1000000 | |
7937 | @end smallexample | |
7938 | ||
7cd4527e AC |
7939 | This sets the heap reserve size to 0x1000000 bytes. Note that with |
7940 | @option{-Wl} option it is not possible to set the heap commit size | |
88e1739c FW |
7941 | because the coma is a separator for this option. |
7942 | ||
7943 | @end itemize | |
7944 | ||
7945 | @node The GNAT Make Program gnatmake | |
7946 | @chapter The GNAT Make Program @code{gnatmake} | |
7947 | @findex gnatmake | |
7948 | ||
7949 | @menu | |
7950 | * Running gnatmake:: | |
7951 | * Switches for gnatmake:: | |
7952 | * Mode Switches for gnatmake:: | |
7953 | * Notes on the Command Line:: | |
7954 | * How gnatmake Works:: | |
7955 | * Examples of gnatmake Usage:: | |
7956 | @end menu | |
7957 | @noindent | |
7958 | A typical development cycle when working on an Ada program consists of | |
7959 | the following steps: | |
7960 | ||
7961 | @enumerate | |
7962 | @item | |
7963 | Edit some sources to fix bugs. | |
7964 | ||
7965 | @item | |
7966 | Add enhancements. | |
7967 | ||
7968 | @item | |
7969 | Compile all sources affected. | |
7970 | ||
7971 | @item | |
7972 | Rebind and relink. | |
7973 | ||
7974 | @item | |
7975 | Test. | |
7976 | @end enumerate | |
7977 | ||
7978 | @noindent | |
7979 | The third step can be tricky, because not only do the modified files | |
7980 | @cindex Dependency rules | |
7981 | have to be compiled, but any files depending on these files must also be | |
7982 | recompiled. The dependency rules in Ada can be quite complex, especially | |
7983 | in the presence of overloading, @code{use} clauses, generics and inlined | |
7984 | subprograms. | |
7985 | ||
7986 | @code{gnatmake} automatically takes care of the third and fourth steps | |
7987 | of this process. It determines which sources need to be compiled, | |
7988 | compiles them, and binds and links the resulting object files. | |
7989 | ||
7990 | Unlike some other Ada make programs, the dependencies are always | |
7991 | accurately recomputed from the new sources. The source based approach of | |
7992 | the GNAT compilation model makes this possible. This means that if | |
7993 | changes to the source program cause corresponding changes in | |
7994 | dependencies, they will always be tracked exactly correctly by | |
7995 | @code{gnatmake}. | |
7996 | ||
7997 | @node Running gnatmake | |
7998 | @section Running @code{gnatmake} | |
7999 | ||
8000 | @noindent | |
8001 | The usual form of the @code{gnatmake} command is | |
8002 | ||
8003 | @smallexample | |
7cd4527e AC |
8004 | $ gnatmake [@var{switches}] @var{file_name} |
8005 | [@var{file_names}] [@var{mode_switches}] | |
88e1739c FW |
8006 | @end smallexample |
8007 | ||
8008 | @noindent | |
8009 | The only required argument is one @var{file_name}, which specifies | |
8010 | a compilation unit that is a main program. Several @var{file_names} can be | |
8011 | specified: this will result in several executables being built. | |
8012 | If @code{switches} are present, they can be placed before the first | |
8013 | @var{file_name}, between @var{file_names} or after the last @var{file_name}. | |
8014 | If @var{mode_switches} are present, they must always be placed after | |
8015 | the last @var{file_name} and all @code{switches}. | |
8016 | ||
8017 | If you are using standard file extensions (.adb and .ads), then the | |
8018 | extension may be omitted from the @var{file_name} arguments. However, if | |
8019 | you are using non-standard extensions, then it is required that the | |
8020 | extension be given. A relative or absolute directory path can be | |
8021 | specified in a @var{file_name}, in which case, the input source file will | |
8022 | be searched for in the specified directory only. Otherwise, the input | |
8023 | source file will first be searched in the directory where | |
8024 | @code{gnatmake} was invoked and if it is not found, it will be search on | |
8025 | the source path of the compiler as described in | |
8026 | @ref{Search Paths and the Run-Time Library (RTL)}. | |
8027 | ||
88e1739c | 8028 | All @code{gnatmake} output (except when you specify |
7cd4527e | 8029 | @option{^-M^/DEPENDENCIES_LIST^}) is to |
88e1739c | 8030 | @file{stderr}. The output produced by the |
7cd4527e | 8031 | @option{^-M^/DEPENDENCIES_LIST^} switch is send to |
88e1739c FW |
8032 | @file{stdout}. |
8033 | ||
8034 | @node Switches for gnatmake | |
8035 | @section Switches for @code{gnatmake} | |
8036 | ||
8037 | @noindent | |
8038 | You may specify any of the following switches to @code{gnatmake}: | |
8039 | ||
7cd4527e AC |
8040 | @table @option |
8041 | @c !sort! | |
88e1739c FW |
8042 | @ifclear vms |
8043 | @item --GCC=@var{compiler_name} | |
7cd4527e | 8044 | @cindex @option{--GCC=compiler_name} (@code{gnatmake}) |
88e1739c FW |
8045 | Program used for compiling. The default is `@code{gcc}'. You need to use |
8046 | quotes around @var{compiler_name} if @code{compiler_name} contains | |
7cd4527e | 8047 | spaces or other separator characters. As an example @option{--GCC="foo -x |
88e1739c | 8048 | -y"} will instruct @code{gnatmake} to use @code{foo -x -y} as your |
7cd4527e | 8049 | compiler. Note that switch @option{-c} is always inserted after your |
88e1739c FW |
8050 | command name. Thus in the above example the compiler command that will |
8051 | be used by @code{gnatmake} will be @code{foo -c -x -y}. | |
7cd4527e | 8052 | If several @option{--GCC=compiler_name} are used, only the last |
88e1739c FW |
8053 | @var{compiler_name} is taken into account. However, all the additional |
8054 | switches are also taken into account. Thus, | |
7cd4527e AC |
8055 | @option{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to |
8056 | @option{--GCC="bar -x -y -z -t"}. | |
88e1739c FW |
8057 | |
8058 | @item --GNATBIND=@var{binder_name} | |
7cd4527e | 8059 | @cindex @option{--GNATBIND=binder_name} (@code{gnatmake}) |
88e1739c FW |
8060 | Program used for binding. The default is `@code{gnatbind}'. You need to |
8061 | use quotes around @var{binder_name} if @var{binder_name} contains spaces | |
7cd4527e | 8062 | or other separator characters. As an example @option{--GNATBIND="bar -x |
88e1739c FW |
8063 | -y"} will instruct @code{gnatmake} to use @code{bar -x -y} as your |
8064 | binder. Binder switches that are normally appended by @code{gnatmake} to | |
8065 | `@code{gnatbind}' are now appended to the end of @code{bar -x -y}. | |
8066 | ||
8067 | @item --GNATLINK=@var{linker_name} | |
7cd4527e | 8068 | @cindex @option{--GNATLINK=linker_name} (@code{gnatmake}) |
88e1739c FW |
8069 | Program used for linking. The default is `@code{gnatlink}'. You need to |
8070 | use quotes around @var{linker_name} if @var{linker_name} contains spaces | |
7cd4527e | 8071 | or other separator characters. As an example @option{--GNATLINK="lan -x |
88e1739c FW |
8072 | -y"} will instruct @code{gnatmake} to use @code{lan -x -y} as your |
8073 | linker. Linker switches that are normally appended by @code{gnatmake} to | |
8074 | `@code{gnatlink}' are now appended to the end of @code{lan -x -y}. | |
8075 | ||
8076 | @end ifclear | |
8077 | ||
8078 | @item ^-a^/ALL_FILES^ | |
7cd4527e | 8079 | @cindex @option{^-a^/ALL_FILES^} (@code{gnatmake}) |
88e1739c FW |
8080 | Consider all files in the make process, even the GNAT internal system |
8081 | files (for example, the predefined Ada library files), as well as any | |
8082 | locked files. Locked files are files whose ALI file is write-protected. | |
8083 | By default, | |
8084 | @code{gnatmake} does not check these files, | |
8085 | because the assumption is that the GNAT internal files are properly up | |
8086 | to date, and also that any write protected ALI files have been properly | |
8087 | installed. Note that if there is an installation problem, such that one | |
8088 | of these files is not up to date, it will be properly caught by the | |
8089 | binder. | |
8090 | You may have to specify this switch if you are working on GNAT | |
7cd4527e AC |
8091 | itself. The switch @option{^-a^/ALL_FILES^} is also useful |
8092 | in conjunction with @option{^-f^/FORCE_COMPILE^} | |
88e1739c | 8093 | if you need to recompile an entire application, |
7cd4527e AC |
8094 | including run-time files, using special configuration pragmas, |
8095 | such as a @code{Normalize_Scalars} pragma. | |
8096 | ||
88e1739c FW |
8097 | By default |
8098 | @code{gnatmake ^-a^/ALL_FILES^} compiles all GNAT | |
8099 | internal files with | |
8100 | @ifclear vms | |
8101 | @code{gcc -c -gnatpg} rather than @code{gcc -c}. | |
8102 | @end ifclear | |
8103 | @ifset vms | |
8104 | the @code{/CHECKS=SUPPRESS_ALL /STYLE_CHECKS=GNAT} switch. | |
8105 | @end ifset | |
8106 | ||
8107 | @item ^-b^/ACTIONS=BIND^ | |
7cd4527e AC |
8108 | @cindex @option{^-b^/ACTIONS=BIND^} (@code{gnatmake}) |
8109 | Bind only. Can be combined with @option{^-c^/ACTIONS=COMPILE^} to do | |
8110 | compilation and binding, but no link. | |
8111 | Can be combined with @option{^-l^/ACTIONS=LINK^} | |
8112 | to do binding and linking. When not combined with | |
8113 | @option{^-c^/ACTIONS=COMPILE^} | |
88e1739c FW |
8114 | all the units in the closure of the main program must have been previously |
8115 | compiled and must be up to date. The root unit specified by @var{file_name} | |
8116 | may be given without extension, with the source extension or, if no GNAT | |
8117 | Project File is specified, with the ALI file extension. | |
8118 | ||
8119 | @item ^-c^/ACTIONS=COMPILE^ | |
7cd4527e AC |
8120 | @cindex @option{^-c^/ACTIONS=COMPILE^} (@code{gnatmake}) |
8121 | Compile only. Do not perform binding, except when @option{^-b^/ACTIONS=BIND^} | |
88e1739c | 8122 | is also specified. Do not perform linking, except if both |
7cd4527e AC |
8123 | @option{^-b^/ACTIONS=BIND^} and |
8124 | @option{^-l^/ACTIONS=LINK^} are also specified. | |
88e1739c FW |
8125 | If the root unit specified by @var{file_name} is not a main unit, this is the |
8126 | default. Otherwise @code{gnatmake} will attempt binding and linking | |
8127 | unless all objects are up to date and the executable is more recent than | |
8128 | the objects. | |
8129 | ||
8130 | @item ^-C^/MAPPING^ | |
7cd4527e AC |
8131 | @cindex @option{^-C^/MAPPING^} (@code{gnatmake}) |
8132 | Use a temporary mapping file. A mapping file is a way to communicate to the | |
8133 | compiler two mappings: from unit names to file names (without any directory | |
8134 | information) and from file names to path names (with full directory | |
8135 | information). These mappings are used by the compiler to short-circuit the path | |
8136 | search. When @code{gnatmake} is invoked with this switch, it will create | |
8137 | a temporary mapping file, initially populated by the project manager, | |
8138 | if @option{^-P^/PROJECT_FILE^} is used, otherwise initially empty. | |
8139 | Each invocation of the compiler will add the newly accessed sources to the | |
8140 | mapping file. This will improve the source search during the next invocation | |
8141 | of the compiler. | |
8142 | ||
8143 | @item ^-C=^/USE_MAPPING_FILE=^@var{file} | |
8144 | @cindex @option{^-C=^/USE_MAPPING^} (@code{gnatmake}) | |
8145 | Use a specific mapping file. The file, specified as a path name (absolute or | |
8146 | relative) by this switch, should already exist, otherwise the switch is | |
8147 | ineffective. The specified mapping file will be communicated to the compiler. | |
8148 | This switch is not compatible with a project file | |
8149 | (^-P^/PROJECT_FILE=^@var{file}) or with multiple compiling processes | |
8150 | (^-j^/PROCESSES=^nnn, when nnn is greater than 1). | |
8151 | ||
8152 | @item ^-D ^/DIRECTORY_OBJECTS=^@var{dir} | |
8153 | @cindex @option{^-D^/DIRECTORY_OBJECTS^} (@code{gnatmake}) | |
8154 | Put all object files and ALI file in directory @var{dir}. | |
8155 | If the @option{^-D^/DIRECTORY_OBJECTS^} switch is not used, all object files | |
8156 | and ALI files go in the current working directory. | |
8157 | ||
8158 | This switch cannot be used when using a project file. | |
88e1739c | 8159 | |
cc4f0de1 AC |
8160 | @ifclear vms |
8161 | @item -eL | |
8162 | @cindex @option{-eL} (@code{gnatmake}) | |
8163 | Follow all symbolic links when processing project files. | |
8164 | @end ifclear | |
8165 | ||
88e1739c | 8166 | @item ^-f^/FORCE_COMPILE^ |
7cd4527e | 8167 | @cindex @option{^-f^/FORCE_COMPILE^} (@code{gnatmake}) |
88e1739c FW |
8168 | Force recompilations. Recompile all sources, even though some object |
8169 | files may be up to date, but don't recompile predefined or GNAT internal | |
8170 | files or locked files (files with a write-protected ALI file), | |
7cd4527e AC |
8171 | unless the @option{^-a^/ALL_FILES^} switch is also specified. |
8172 | ||
8173 | @item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^ | |
8174 | @cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@code{gnatmake}) | |
8175 | When using project files, if some errors or warnings are detected during | |
8176 | parsing and verbose mode is not in effect (no use of switch | |
8177 | ^-v^/VERBOSE^), then error lines start with the full path name of the project | |
8178 | file, rather than its simple file name. | |
88e1739c | 8179 | |
88e1739c | 8180 | @item ^-i^/IN_PLACE^ |
7cd4527e | 8181 | @cindex @option{^-i^/IN_PLACE^} (@code{gnatmake}) |
88e1739c | 8182 | In normal mode, @code{gnatmake} compiles all object files and ALI files |
7cd4527e | 8183 | into the current directory. If the @option{^-i^/IN_PLACE^} switch is used, |
88e1739c FW |
8184 | then instead object files and ALI files that already exist are overwritten |
8185 | in place. This means that once a large project is organized into separate | |
8186 | directories in the desired manner, then @code{gnatmake} will automatically | |
8187 | maintain and update this organization. If no ALI files are found on the | |
8188 | Ada object path (@ref{Search Paths and the Run-Time Library (RTL)}), | |
8189 | the new object and ALI files are created in the | |
8190 | directory containing the source being compiled. If another organization | |
8191 | is desired, where objects and sources are kept in different directories, | |
8192 | a useful technique is to create dummy ALI files in the desired directories. | |
8193 | When detecting such a dummy file, @code{gnatmake} will be forced to recompile | |
8194 | the corresponding source file, and it will be put the resulting object | |
8195 | and ALI files in the directory where it found the dummy file. | |
8196 | ||
8197 | @item ^-j^/PROCESSES=^@var{n} | |
7cd4527e | 8198 | @cindex @option{^-j^/PROCESSES^} (@code{gnatmake}) |
88e1739c FW |
8199 | @cindex Parallel make |
8200 | Use @var{n} processes to carry out the (re)compilations. On a | |
8201 | multiprocessor machine compilations will occur in parallel. In the | |
8202 | event of compilation errors, messages from various compilations might | |
8203 | get interspersed (but @code{gnatmake} will give you the full ordered | |
8204 | list of failing compiles at the end). If this is problematic, rerun | |
8205 | the make process with n set to 1 to get a clean list of messages. | |
8206 | ||
8207 | @item ^-k^/CONTINUE_ON_ERROR^ | |
7cd4527e | 8208 | @cindex @option{^-k^/CONTINUE_ON_ERROR^} (@code{gnatmake}) |
88e1739c FW |
8209 | Keep going. Continue as much as possible after a compilation error. To |
8210 | ease the programmer's task in case of compilation errors, the list of | |
8211 | sources for which the compile fails is given when @code{gnatmake} | |
8212 | terminates. | |
8213 | ||
8214 | If @code{gnatmake} is invoked with several @file{file_names} and with this | |
8215 | switch, if there are compilation errors when building an executable, | |
8216 | @code{gnatmake} will not attempt to build the following executables. | |
8217 | ||
8218 | @item ^-l^/ACTIONS=LINK^ | |
7cd4527e AC |
8219 | @cindex @option{^-l^/ACTIONS=LINK^} (@code{gnatmake}) |
8220 | Link only. Can be combined with @option{^-b^/ACTIONS=BIND^} to binding | |
88e1739c | 8221 | and linking. Linking will not be performed if combined with |
7cd4527e AC |
8222 | @option{^-c^/ACTIONS=COMPILE^} |
8223 | but not with @option{^-b^/ACTIONS=BIND^}. | |
8224 | When not combined with @option{^-b^/ACTIONS=BIND^} | |
88e1739c FW |
8225 | all the units in the closure of the main program must have been previously |
8226 | compiled and must be up to date, and the main program need to have been bound. | |
8227 | The root unit specified by @var{file_name} | |
8228 | may be given without extension, with the source extension or, if no GNAT | |
8229 | Project File is specified, with the ALI file extension. | |
8230 | ||
8231 | @item ^-m^/MINIMAL_RECOMPILATION^ | |
7cd4527e | 8232 | @cindex @option{^-m^/MINIMAL_RECOMPILATION^} (@code{gnatmake}) |
88e1739c FW |
8233 | Specifies that the minimum necessary amount of recompilations |
8234 | be performed. In this mode @code{gnatmake} ignores time | |
8235 | stamp differences when the only | |
8236 | modifications to a source file consist in adding/removing comments, | |
8237 | empty lines, spaces or tabs. This means that if you have changed the | |
8238 | comments in a source file or have simply reformatted it, using this | |
8239 | switch will tell gnatmake not to recompile files that depend on it | |
8240 | (provided other sources on which these files depend have undergone no | |
8241 | semantic modifications). Note that the debugging information may be | |
7cd4527e | 8242 | out of date with respect to the sources if the @option{-m} switch causes |
88e1739c FW |
8243 | a compilation to be switched, so the use of this switch represents a |
8244 | trade-off between compilation time and accurate debugging information. | |
8245 | ||
8246 | @item ^-M^/DEPENDENCIES_LIST^ | |
8247 | @cindex Dependencies, producing list | |
7cd4527e | 8248 | @cindex @option{^-M^/DEPENDENCIES_LIST^} (@code{gnatmake}) |
88e1739c FW |
8249 | Check if all objects are up to date. If they are, output the object |
8250 | dependences to @file{stdout} in a form that can be directly exploited in | |
8251 | a @file{Makefile}. By default, each source file is prefixed with its | |
8252 | (relative or absolute) directory name. This name is whatever you | |
7cd4527e AC |
8253 | specified in the various @option{^-aI^/SOURCE_SEARCH^} |
8254 | and @option{^-I^/SEARCH^} switches. If you use | |
88e1739c | 8255 | @code{gnatmake ^-M^/DEPENDENCIES_LIST^} |
7cd4527e | 8256 | @option{^-q^/QUIET^} |
88e1739c FW |
8257 | (see below), only the source file names, |
8258 | without relative paths, are output. If you just specify the | |
7cd4527e | 8259 | @option{^-M^/DEPENDENCIES_LIST^} |
88e1739c FW |
8260 | switch, dependencies of the GNAT internal system files are omitted. This |
8261 | is typically what you want. If you also specify | |
7cd4527e | 8262 | the @option{^-a^/ALL_FILES^} switch, |
88e1739c FW |
8263 | dependencies of the GNAT internal files are also listed. Note that |
8264 | dependencies of the objects in external Ada libraries (see switch | |
7cd4527e AC |
8265 | @option{^-aL^/SKIP_MISSING=^}@var{dir} in the following list) |
8266 | are never reported. | |
88e1739c FW |
8267 | |
8268 | @item ^-n^/DO_OBJECT_CHECK^ | |
7cd4527e | 8269 | @cindex @option{^-n^/DO_OBJECT_CHECK^} (@code{gnatmake}) |
88e1739c FW |
8270 | Don't compile, bind, or link. Checks if all objects are up to date. |
8271 | If they are not, the full name of the first file that needs to be | |
8272 | recompiled is printed. | |
8273 | Repeated use of this option, followed by compiling the indicated source | |
8274 | file, will eventually result in recompiling all required units. | |
8275 | ||
8276 | @item ^-o ^/EXECUTABLE=^@var{exec_name} | |
7cd4527e | 8277 | @cindex @option{^-o^/EXECUTABLE^} (@code{gnatmake}) |
88e1739c | 8278 | Output executable name. The name of the final executable program will be |
7cd4527e | 8279 | @var{exec_name}. If the @option{^-o^/EXECUTABLE^} switch is omitted the default |
88e1739c FW |
8280 | name for the executable will be the name of the input file in appropriate form |
8281 | for an executable file on the host system. | |
8282 | ||
8283 | This switch cannot be used when invoking @code{gnatmake} with several | |
8284 | @file{file_names}. | |
8285 | ||
7cd4527e AC |
8286 | @item ^-P^/PROJECT_FILE=^@var{project} |
8287 | @cindex @option{^-P^/PROJECT_FILE^} (@code{gnatmake}) | |
8288 | Use project file @var{project}. Only one such switch can be used. | |
8289 | See @ref{gnatmake and Project Files}. | |
8290 | ||
88e1739c | 8291 | @item ^-q^/QUIET^ |
7cd4527e | 8292 | @cindex @option{^-q^/QUIET^} (@code{gnatmake}) |
88e1739c FW |
8293 | Quiet. When this flag is not set, the commands carried out by |
8294 | @code{gnatmake} are displayed. | |
8295 | ||
8296 | @item ^-s^/SWITCH_CHECK/^ | |
7cd4527e | 8297 | @cindex @option{^-s^/SWITCH_CHECK^} (@code{gnatmake}) |
88e1739c FW |
8298 | Recompile if compiler switches have changed since last compilation. |
8299 | All compiler switches but -I and -o are taken into account in the | |
8300 | following way: | |
8301 | orders between different ``first letter'' switches are ignored, but | |
8302 | orders between same switches are taken into account. For example, | |
7cd4527e AC |
8303 | @option{-O -O2} is different than @option{-O2 -O}, but @option{-g -O} |
8304 | is equivalent to @option{-O -g}. | |
8305 | ||
8306 | This switch is recommended when Integrated Preprocessing is used. | |
88e1739c FW |
8307 | |
8308 | @item ^-u^/UNIQUE^ | |
7cd4527e AC |
8309 | @cindex @option{^-u^/UNIQUE^} (@code{gnatmake}) |
8310 | Unique. Recompile at most the main files. It implies -c. Combined with | |
8311 | -f, it is equivalent to calling the compiler directly. Note that using | |
8312 | ^-u^/UNIQUE^ with a project file and no main has a special meaning | |
8313 | (see @ref{Project Files and Main Subprograms}). | |
8314 | ||
8315 | @item ^-U^/ALL_PROJECTS^ | |
8316 | @cindex @option{^-U^/ALL_PROJECTS^} (@code{gnatmake}) | |
8317 | When used without a project file or with one or several mains on the command | |
8318 | line, is equivalent to ^-u^/UNIQUE^. When used with a project file and no main | |
8319 | on the command line, all sources of all project files are checked and compiled | |
8320 | if not up to date, and libraries are rebuilt, if necessary. | |
88e1739c FW |
8321 | |
8322 | @item ^-v^/REASONS^ | |
7cd4527e | 8323 | @cindex @option{^-v^/REASONS^} (@code{gnatmake}) |
88e1739c FW |
8324 | Verbose. Displays the reason for all recompilations @code{gnatmake} |
8325 | decides are necessary. | |
8326 | ||
7cd4527e AC |
8327 | @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} |
8328 | Indicates the verbosity of the parsing of GNAT project files. | |
8329 | See @ref{Switches Related to Project Files}. | |
8330 | ||
8331 | @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} | |
8332 | Indicates that external variable @var{name} has the value @var{value}. | |
8333 | The Project Manager will use this value for occurrences of | |
8334 | @code{external(name)} when parsing the project file. | |
8335 | See @ref{Switches Related to Project Files}. | |
8336 | ||
88e1739c | 8337 | @item ^-z^/NOMAIN^ |
7cd4527e | 8338 | @cindex @option{^-z^/NOMAIN^} (@code{gnatmake}) |
88e1739c FW |
8339 | No main subprogram. Bind and link the program even if the unit name |
8340 | given on the command line is a package name. The resulting executable | |
8341 | will execute the elaboration routines of the package and its closure, | |
8342 | then the finalization routines. | |
8343 | ||
7cd4527e AC |
8344 | @item ^-g^/DEBUG^ |
8345 | @cindex @option{^-g^/DEBUG^} (@code{gnatmake}) | |
8346 | Enable debugging. This switch is simply passed to the compiler and to the | |
8347 | linker. | |
8348 | ||
8349 | @end table | |
8350 | ||
8351 | @table @asis | |
88e1739c FW |
8352 | @item @code{gcc} @asis{switches} |
8353 | @ifclear vms | |
cc4f0de1 AC |
8354 | Any uppercase or multi-character switch that is not a @code{gnatmake} switch |
8355 | is passed to @code{gcc} (e.g. @option{-O}, @option{-gnato,} etc.) | |
88e1739c FW |
8356 | @end ifclear |
8357 | @ifset vms | |
8358 | Any qualifier that cannot be recognized as a qualifier for @code{GNAT MAKE} | |
8359 | but is recognizable as a valid qualifier for @code{GNAT COMPILE} is | |
8360 | automatically treated as a compiler switch, and passed on to all | |
8361 | compilations that are carried out. | |
8362 | @end ifset | |
8363 | @end table | |
8364 | ||
8365 | @noindent | |
8366 | Source and library search path switches: | |
8367 | ||
7cd4527e AC |
8368 | @table @option |
8369 | @c !sort! | |
88e1739c | 8370 | @item ^-aI^/SOURCE_SEARCH=^@var{dir} |
7cd4527e | 8371 | @cindex @option{^-aI^/SOURCE_SEARCH^} (@code{gnatmake}) |
88e1739c FW |
8372 | When looking for source files also look in directory @var{dir}. |
8373 | The order in which source files search is undertaken is | |
8374 | described in @ref{Search Paths and the Run-Time Library (RTL)}. | |
8375 | ||
8376 | @item ^-aL^/SKIP_MISSING=^@var{dir} | |
7cd4527e | 8377 | @cindex @option{^-aL^/SKIP_MISSING^} (@code{gnatmake}) |
88e1739c | 8378 | Consider @var{dir} as being an externally provided Ada library. |
7cd4527e | 8379 | Instructs @code{gnatmake} to skip compilation units whose @file{.ALI} |
88e1739c FW |
8380 | files have been located in directory @var{dir}. This allows you to have |
8381 | missing bodies for the units in @var{dir} and to ignore out of date bodies | |
8382 | for the same units. You still need to specify | |
8383 | the location of the specs for these units by using the switches | |
7cd4527e AC |
8384 | @option{^-aI^/SOURCE_SEARCH=^@var{dir}} |
8385 | or @option{^-I^/SEARCH=^@var{dir}}. | |
88e1739c FW |
8386 | Note: this switch is provided for compatibility with previous versions |
8387 | of @code{gnatmake}. The easier method of causing standard libraries | |
8388 | to be excluded from consideration is to write-protect the corresponding | |
8389 | ALI files. | |
8390 | ||
8391 | @item ^-aO^/OBJECT_SEARCH=^@var{dir} | |
7cd4527e | 8392 | @cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatmake}) |
88e1739c FW |
8393 | When searching for library and object files, look in directory |
8394 | @var{dir}. The order in which library files are searched is described in | |
8395 | @ref{Search Paths for gnatbind}. | |
8396 | ||
8397 | @item ^-A^/CONDITIONAL_SOURCE_SEARCH=^@var{dir} | |
8398 | @cindex Search paths, for @code{gnatmake} | |
7cd4527e AC |
8399 | @cindex @option{^-A^/CONDITIONAL_SOURCE_SEARCH^} (@code{gnatmake}) |
8400 | Equivalent to @option{^-aL^/SKIP_MISSING=^@var{dir} | |
88e1739c FW |
8401 | ^-aI^/SOURCE_SEARCH=^@var{dir}}. |
8402 | ||
8403 | @item ^-I^/SEARCH=^@var{dir} | |
7cd4527e AC |
8404 | @cindex @option{^-I^/SEARCH^} (@code{gnatmake}) |
8405 | Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir} | |
88e1739c FW |
8406 | ^-aI^/SOURCE_SEARCH=^@var{dir}}. |
8407 | ||
8408 | @item ^-I-^/NOCURRENT_DIRECTORY^ | |
7cd4527e | 8409 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatmake}) |
88e1739c FW |
8410 | @cindex Source files, suppressing search |
8411 | Do not look for source files in the directory containing the source | |
8412 | file named in the command line. | |
8413 | Do not look for ALI or object files in the directory | |
8414 | where @code{gnatmake} was invoked. | |
8415 | ||
8416 | @item ^-L^/LIBRARY_SEARCH=^@var{dir} | |
7cd4527e | 8417 | @cindex @option{^-L^/LIBRARY_SEARCH^} (@code{gnatmake}) |
88e1739c FW |
8418 | @cindex Linker libraries |
8419 | Add directory @var{dir} to the list of directories in which the linker | |
7cd4527e AC |
8420 | will search for libraries. This is equivalent to |
8421 | @option{-largs ^-L^/LIBRARY_SEARCH=^}@var{dir}. | |
8422 | @ifclear vms | |
88e1739c FW |
8423 | Furthermore, under Windows, the sources pointed to by the libraries path |
8424 | set in the registry are not searched for. | |
7cd4527e | 8425 | @end ifclear |
88e1739c FW |
8426 | |
8427 | @item -nostdinc | |
7cd4527e | 8428 | @cindex @option{-nostdinc} (@code{gnatmake}) |
88e1739c FW |
8429 | Do not look for source files in the system default directory. |
8430 | ||
8431 | @item -nostdlib | |
7cd4527e | 8432 | @cindex @option{-nostdlib} (@code{gnatmake}) |
88e1739c FW |
8433 | Do not look for library files in the system default directory. |
8434 | ||
8435 | @item --RTS=@var{rts-path} | |
7cd4527e AC |
8436 | @cindex @option{--RTS} (@code{gnatmake}) |
8437 | Specifies the default location of the runtime library. GNAT looks for the | |
8438 | runtime | |
8439 | in the following directories, and stops as soon as a valid runtime is found | |
8440 | (@file{adainclude} or @file{ada_source_path}, and @file{adalib} or | |
8441 | @file{ada_object_path} present): | |
88e1739c FW |
8442 | |
8443 | @itemize @bullet | |
8444 | @item <current directory>/$rts_path | |
8445 | ||
8446 | @item <default-search-dir>/$rts_path | |
8447 | ||
8448 | @item <default-search-dir>/rts-$rts_path | |
8449 | @end itemize | |
8450 | ||
8451 | @noindent | |
8452 | The selected path is handled like a normal RTS path. | |
8453 | ||
8454 | @end table | |
8455 | ||
8456 | @node Mode Switches for gnatmake | |
8457 | @section Mode Switches for @code{gnatmake} | |
8458 | ||
8459 | @noindent | |
8460 | The mode switches (referred to as @code{mode_switches}) allow the | |
8461 | inclusion of switches that are to be passed to the compiler itself, the | |
8462 | binder or the linker. The effect of a mode switch is to cause all | |
8463 | subsequent switches up to the end of the switch list, or up to the next | |
8464 | mode switch, to be interpreted as switches to be passed on to the | |
8465 | designated component of GNAT. | |
8466 | ||
7cd4527e AC |
8467 | @table @option |
8468 | @c !sort! | |
88e1739c | 8469 | @item -cargs @var{switches} |
7cd4527e | 8470 | @cindex @option{-cargs} (@code{gnatmake}) |
88e1739c FW |
8471 | Compiler switches. Here @var{switches} is a list of switches |
8472 | that are valid switches for @code{gcc}. They will be passed on to | |
8473 | all compile steps performed by @code{gnatmake}. | |
8474 | ||
8475 | @item -bargs @var{switches} | |
7cd4527e | 8476 | @cindex @option{-bargs} (@code{gnatmake}) |
88e1739c | 8477 | Binder switches. Here @var{switches} is a list of switches |
7cd4527e | 8478 | that are valid switches for @code{gnatbind}. They will be passed on to |
88e1739c FW |
8479 | all bind steps performed by @code{gnatmake}. |
8480 | ||
8481 | @item -largs @var{switches} | |
7cd4527e | 8482 | @cindex @option{-largs} (@code{gnatmake}) |
88e1739c | 8483 | Linker switches. Here @var{switches} is a list of switches |
7cd4527e | 8484 | that are valid switches for @code{gnatlink}. They will be passed on to |
88e1739c | 8485 | all link steps performed by @code{gnatmake}. |
7cd4527e AC |
8486 | |
8487 | @item -margs @var{switches} | |
8488 | @cindex @option{-margs} (@code{gnatmake}) | |
8489 | Make switches. The switches are directly interpreted by @code{gnatmake}, | |
8490 | regardless of any previous occurrence of @option{-cargs}, @option{-bargs} | |
8491 | or @option{-largs}. | |
88e1739c FW |
8492 | @end table |
8493 | ||
8494 | @node Notes on the Command Line | |
8495 | @section Notes on the Command Line | |
8496 | ||
8497 | @noindent | |
8498 | This section contains some additional useful notes on the operation | |
8499 | of the @code{gnatmake} command. | |
8500 | ||
8501 | @itemize @bullet | |
8502 | @item | |
8503 | @cindex Recompilation, by @code{gnatmake} | |
8504 | If @code{gnatmake} finds no ALI files, it recompiles the main program | |
8505 | and all other units required by the main program. | |
8506 | This means that @code{gnatmake} | |
8507 | can be used for the initial compile, as well as during subsequent steps of | |
8508 | the development cycle. | |
8509 | ||
8510 | @item | |
8511 | If you enter @code{gnatmake @var{file}.adb}, where @file{@var{file}.adb} | |
8512 | is a subunit or body of a generic unit, @code{gnatmake} recompiles | |
8513 | @file{@var{file}.adb} (because it finds no ALI) and stops, issuing a | |
8514 | warning. | |
8515 | ||
8516 | @item | |
7cd4527e | 8517 | In @code{gnatmake} the switch @option{^-I^/SEARCH^} |
88e1739c | 8518 | is used to specify both source and |
7cd4527e | 8519 | library file paths. Use @option{^-aI^/SOURCE_SEARCH^} |
88e1739c | 8520 | instead if you just want to specify |
7cd4527e | 8521 | source paths only and @option{^-aO^/OBJECT_SEARCH^} |
88e1739c FW |
8522 | if you want to specify library paths |
8523 | only. | |
8524 | ||
8525 | @item | |
8526 | @code{gnatmake} examines both an ALI file and its corresponding object file | |
8527 | for consistency. If an ALI is more recent than its corresponding object, | |
8528 | or if the object file is missing, the corresponding source will be recompiled. | |
8529 | Note that @code{gnatmake} expects an ALI and the corresponding object file | |
8530 | to be in the same directory. | |
8531 | ||
8532 | @item | |
8533 | @code{gnatmake} will ignore any files whose ALI file is write-protected. | |
8534 | This may conveniently be used to exclude standard libraries from | |
8535 | consideration and in particular it means that the use of the | |
7cd4527e AC |
8536 | @option{^-f^/FORCE_COMPILE^} switch will not recompile these files |
8537 | unless @option{^-a^/ALL_FILES^} is also specified. | |
88e1739c FW |
8538 | |
8539 | @item | |
8540 | @code{gnatmake} has been designed to make the use of Ada libraries | |
8541 | particularly convenient. Assume you have an Ada library organized | |
7cd4527e | 8542 | as follows: @i{^obj-dir^[OBJ_DIR]^} contains the objects and ALI files for |
88e1739c | 8543 | of your Ada compilation units, |
7cd4527e | 8544 | whereas @i{^include-dir^[INCLUDE_DIR]^} contains the |
88e1739c FW |
8545 | specs of these units, but no bodies. Then to compile a unit |
8546 | stored in @code{main.adb}, which uses this Ada library you would just type | |
8547 | ||
8548 | @smallexample | |
8549 | @ifclear vms | |
8550 | $ gnatmake -aI@var{include-dir} -aL@var{obj-dir} main | |
8551 | @end ifclear | |
8552 | @ifset vms | |
7cd4527e AC |
8553 | $ gnatmake /SOURCE_SEARCH=@i{[INCLUDE_DIR]} |
8554 | /SKIP_MISSING=@i{[OBJ_DIR]} main | |
88e1739c FW |
8555 | @end ifset |
8556 | @end smallexample | |
8557 | ||
8558 | @item | |
8559 | Using @code{gnatmake} along with the | |
7cd4527e | 8560 | @option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^} |
88e1739c FW |
8561 | switch provides a mechanism for avoiding unnecessary rcompilations. Using |
8562 | this switch, | |
8563 | you can update the comments/format of your | |
8564 | source files without having to recompile everything. Note, however, that | |
8565 | adding or deleting lines in a source files may render its debugging | |
8566 | info obsolete. If the file in question is a spec, the impact is rather | |
8567 | limited, as that debugging info will only be useful during the | |
8568 | elaboration phase of your program. For bodies the impact can be more | |
8569 | significant. In all events, your debugger will warn you if a source file | |
8570 | is more recent than the corresponding object, and alert you to the fact | |
8571 | that the debugging information may be out of date. | |
8572 | @end itemize | |
8573 | ||
8574 | @node How gnatmake Works | |
8575 | @section How @code{gnatmake} Works | |
8576 | ||
8577 | @noindent | |
8578 | Generally @code{gnatmake} automatically performs all necessary | |
8579 | recompilations and you don't need to worry about how it works. However, | |
8580 | it may be useful to have some basic understanding of the @code{gnatmake} | |
8581 | approach and in particular to understand how it uses the results of | |
8582 | previous compilations without incorrectly depending on them. | |
8583 | ||
8584 | First a definition: an object file is considered @dfn{up to date} if the | |
8585 | corresponding ALI file exists and its time stamp predates that of the | |
8586 | object file and if all the source files listed in the | |
8587 | dependency section of this ALI file have time stamps matching those in | |
8588 | the ALI file. This means that neither the source file itself nor any | |
8589 | files that it depends on have been modified, and hence there is no need | |
8590 | to recompile this file. | |
8591 | ||
8592 | @code{gnatmake} works by first checking if the specified main unit is up | |
8593 | to date. If so, no compilations are required for the main unit. If not, | |
8594 | @code{gnatmake} compiles the main program to build a new ALI file that | |
8595 | reflects the latest sources. Then the ALI file of the main unit is | |
8596 | examined to find all the source files on which the main program depends, | |
8597 | and @code{gnatmake} recursively applies the above procedure on all these files. | |
8598 | ||
8599 | This process ensures that @code{gnatmake} only trusts the dependencies | |
8600 | in an existing ALI file if they are known to be correct. Otherwise it | |
8601 | always recompiles to determine a new, guaranteed accurate set of | |
7cd4527e | 8602 | dependencies. As a result the program is compiled ``upside down'' from what may |
88e1739c FW |
8603 | be more familiar as the required order of compilation in some other Ada |
8604 | systems. In particular, clients are compiled before the units on which | |
8605 | they depend. The ability of GNAT to compile in any order is critical in | |
8606 | allowing an order of compilation to be chosen that guarantees that | |
8607 | @code{gnatmake} will recompute a correct set of new dependencies if | |
8608 | necessary. | |
8609 | ||
8610 | When invoking @code{gnatmake} with several @var{file_names}, if a unit is | |
8611 | imported by several of the executables, it will be recompiled at most once. | |
8612 | ||
7cd4527e AC |
8613 | Note: when using non-standard naming conventions |
8614 | (See @ref{Using Other File Names}), changing through a configuration pragmas | |
8615 | file the version of a source and invoking @code{gnatmake} to recompile may | |
8616 | have no effect, if the previous version of the source is still accessible | |
8617 | by @code{gnatmake}. It may be necessary to use the switch ^-f^/FORCE_COMPILE^. | |
8618 | ||
88e1739c FW |
8619 | @node Examples of gnatmake Usage |
8620 | @section Examples of @code{gnatmake} Usage | |
8621 | ||
8622 | @table @code | |
8623 | @item gnatmake hello.adb | |
8624 | Compile all files necessary to bind and link the main program | |
8625 | @file{hello.adb} (containing unit @code{Hello}) and bind and link the | |
8626 | resulting object files to generate an executable file @file{^hello^HELLO.EXE^}. | |
8627 | ||
8628 | @item gnatmake main1 main2 main3 | |
8629 | Compile all files necessary to bind and link the main programs | |
8630 | @file{main1.adb} (containing unit @code{Main1}), @file{main2.adb} | |
8631 | (containing unit @code{Main2}) and @file{main3.adb} | |
8632 | (containing unit @code{Main3}) and bind and link the resulting object files | |
8633 | to generate three executable files @file{^main1^MAIN1.EXE^}, | |
8634 | @file{^main2^MAIN2.EXE^} | |
8635 | and @file{^main3^MAIN3.EXE^}. | |
8636 | ||
8637 | @ifclear vms | |
8638 | @item gnatmake -q Main_Unit -cargs -O2 -bargs -l | |
8639 | @end ifclear | |
8640 | ||
8641 | @ifset vms | |
7cd4527e AC |
8642 | @item gnatmake Main_Unit /QUIET |
8643 | /COMPILER_QUALIFIERS /OPTIMIZE=ALL | |
8644 | /BINDER_QUALIFIERS /ORDER_OF_ELABORATION | |
88e1739c FW |
8645 | @end ifset |
8646 | Compile all files necessary to bind and link the main program unit | |
8647 | @code{Main_Unit} (from file @file{main_unit.adb}). All compilations will | |
8648 | be done with optimization level 2 and the order of elaboration will be | |
8649 | listed by the binder. @code{gnatmake} will operate in quiet mode, not | |
8650 | displaying commands it is executing. | |
8651 | @end table | |
8652 | ||
7cd4527e AC |
8653 | |
8654 | @c ************************* | |
8655 | @node Improving Performance | |
8656 | @chapter Improving Performance | |
8657 | @cindex Improving performance | |
88e1739c FW |
8658 | |
8659 | @noindent | |
7cd4527e AC |
8660 | This chapter presents several topics related to program performance. |
8661 | It first describes some of the tradeoffs that need to be considered | |
8662 | and some of the techniques for making your program run faster. | |
8663 | It then documents the @command{gnatelim} tool, which can reduce | |
8664 | the size of program executables. | |
88e1739c | 8665 | |
6da7d579 | 8666 | @ifnottex |
88e1739c | 8667 | @menu |
7cd4527e AC |
8668 | * Performance Considerations:: |
8669 | * Reducing the Size of Ada Executables with gnatelim:: | |
88e1739c | 8670 | @end menu |
6da7d579 | 8671 | @end ifnottex |
88e1739c | 8672 | |
7cd4527e AC |
8673 | |
8674 | @c ***************************** | |
8675 | @node Performance Considerations | |
8676 | @section Performance Considerations | |
88e1739c FW |
8677 | |
8678 | @noindent | |
7cd4527e AC |
8679 | The GNAT system provides a number of options that allow a trade-off |
8680 | between | |
88e1739c | 8681 | |
7cd4527e AC |
8682 | @itemize @bullet |
8683 | @item | |
8684 | performance of the generated code | |
88e1739c | 8685 | |
7cd4527e AC |
8686 | @item |
8687 | speed of compilation | |
88e1739c | 8688 | |
7cd4527e AC |
8689 | @item |
8690 | minimization of dependences and recompilation | |
88e1739c | 8691 | |
7cd4527e AC |
8692 | @item |
8693 | the degree of run-time checking. | |
8694 | @end itemize | |
88e1739c FW |
8695 | |
8696 | @noindent | |
7cd4527e AC |
8697 | The defaults (if no options are selected) aim at improving the speed |
8698 | of compilation and minimizing dependences, at the expense of performance | |
8699 | of the generated code: | |
88e1739c | 8700 | |
7cd4527e AC |
8701 | @itemize @bullet |
8702 | @item | |
8703 | no optimization | |
88e1739c | 8704 | |
7cd4527e AC |
8705 | @item |
8706 | no inlining of subprogram calls | |
88e1739c | 8707 | |
7cd4527e AC |
8708 | @item |
8709 | all run-time checks enabled except overflow and elaboration checks | |
8710 | @end itemize | |
88e1739c | 8711 | |
7cd4527e AC |
8712 | @noindent |
8713 | These options are suitable for most program development purposes. This | |
8714 | chapter describes how you can modify these choices, and also provides | |
8715 | some guidelines on debugging optimized code. | |
88e1739c | 8716 | |
7cd4527e AC |
8717 | @menu |
8718 | * Controlling Run-Time Checks:: | |
8719 | * Use of Restrictions:: | |
8720 | * Optimization Levels:: | |
8721 | * Debugging Optimized Code:: | |
8722 | * Inlining of Subprograms:: | |
8723 | * Optimization and Strict Aliasing:: | |
8724 | @ifset vms | |
8725 | * Coverage Analysis:: | |
8726 | @end ifset | |
8727 | @end menu | |
88e1739c | 8728 | |
7cd4527e AC |
8729 | @node Controlling Run-Time Checks |
8730 | @subsection Controlling Run-Time Checks | |
88e1739c FW |
8731 | |
8732 | @noindent | |
7cd4527e AC |
8733 | By default, GNAT generates all run-time checks, except arithmetic overflow |
8734 | checking for integer operations and checks for access before elaboration on | |
8735 | subprogram calls. The latter are not required in default mode, because all | |
8736 | necessary checking is done at compile time. | |
8737 | @cindex @option{-gnatp} (@code{gcc}) | |
8738 | @cindex @option{-gnato} (@code{gcc}) | |
8739 | Two gnat switches, @option{-gnatp} and @option{-gnato} allow this default to | |
8740 | be modified. @xref{Run-Time Checks}. | |
88e1739c | 8741 | |
7cd4527e AC |
8742 | Our experience is that the default is suitable for most development |
8743 | purposes. | |
88e1739c | 8744 | |
7cd4527e AC |
8745 | We treat integer overflow specially because these |
8746 | are quite expensive and in our experience are not as important as other | |
8747 | run-time checks in the development process. Note that division by zero | |
8748 | is not considered an overflow check, and divide by zero checks are | |
8749 | generated where required by default. | |
88e1739c | 8750 | |
7cd4527e AC |
8751 | Elaboration checks are off by default, and also not needed by default, since |
8752 | GNAT uses a static elaboration analysis approach that avoids the need for | |
8753 | run-time checking. This manual contains a full chapter discussing the issue | |
8754 | of elaboration checks, and if the default is not satisfactory for your use, | |
8755 | you should read this chapter. | |
88e1739c | 8756 | |
7cd4527e AC |
8757 | For validity checks, the minimal checks required by the Ada Reference |
8758 | Manual (for case statements and assignments to array elements) are on | |
8759 | by default. These can be suppressed by use of the @option{-gnatVn} switch. | |
8760 | Note that in Ada 83, there were no validity checks, so if the Ada 83 mode | |
8761 | is acceptable (or when comparing GNAT performance with an Ada 83 compiler), | |
8762 | it may be reasonable to routinely use @option{-gnatVn}. Validity checks | |
8763 | are also suppressed entirely if @option{-gnatp} is used. | |
88e1739c | 8764 | |
7cd4527e AC |
8765 | @cindex Overflow checks |
8766 | @cindex Checks, overflow | |
8767 | @findex Suppress | |
8768 | @findex Unsuppress | |
8769 | @cindex pragma Suppress | |
8770 | @cindex pragma Unsuppress | |
8771 | Note that the setting of the switches controls the default setting of | |
8772 | the checks. They may be modified using either @code{pragma Suppress} (to | |
8773 | remove checks) or @code{pragma Unsuppress} (to add back suppressed | |
8774 | checks) in the program source. | |
88e1739c | 8775 | |
7cd4527e AC |
8776 | @node Use of Restrictions |
8777 | @subsection Use of Restrictions | |
88e1739c FW |
8778 | |
8779 | @noindent | |
7cd4527e AC |
8780 | The use of pragma Restrictions allows you to control which features are |
8781 | permitted in your program. Apart from the obvious point that if you avoid | |
8782 | relatively expensive features like finalization (enforceable by the use | |
8783 | of pragma Restrictions (No_Finalization), the use of this pragma does not | |
8784 | affect the generated code in most cases. | |
8785 | ||
8786 | One notable exception to this rule is that the possibility of task abort | |
8787 | results in some distributed overhead, particularly if finalization or | |
8788 | exception handlers are used. The reason is that certain sections of code | |
8789 | have to be marked as non-abortable. | |
8790 | ||
8791 | If you use neither the @code{abort} statement, nor asynchronous transfer | |
8792 | of control (@code{select .. then abort}), then this distributed overhead | |
8793 | is removed, which may have a general positive effect in improving | |
8794 | overall performance. Especially code involving frequent use of tasking | |
8795 | constructs and controlled types will show much improved performance. | |
8796 | The relevant restrictions pragmas are | |
88e1739c FW |
8797 | |
8798 | @smallexample | |
7cd4527e AC |
8799 | pragma Restrictions (No_Abort_Statements); |
8800 | pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); | |
88e1739c FW |
8801 | @end smallexample |
8802 | ||
8803 | @noindent | |
7cd4527e AC |
8804 | It is recommended that these restriction pragmas be used if possible. Note |
8805 | that this also means that you can write code without worrying about the | |
8806 | possibility of an immediate abort at any point. | |
88e1739c | 8807 | |
7cd4527e AC |
8808 | @node Optimization Levels |
8809 | @subsection Optimization Levels | |
8810 | @cindex @option{^-O^/OPTIMIZE^} (@code{gcc}) | |
88e1739c FW |
8811 | |
8812 | @noindent | |
7cd4527e AC |
8813 | The default is optimization off. This results in the fastest compile |
8814 | times, but GNAT makes absolutely no attempt to optimize, and the | |
8815 | generated programs are considerably larger and slower than when | |
8816 | optimization is enabled. You can use the | |
88e1739c | 8817 | @ifclear vms |
7cd4527e | 8818 | @option{-O@var{n}} switch, where @var{n} is an integer from 0 to 3, |
88e1739c | 8819 | @end ifclear |
7cd4527e AC |
8820 | @ifset vms |
8821 | @code{OPTIMIZE} qualifier | |
8822 | @end ifset | |
8823 | to @code{gcc} to control the optimization level: | |
88e1739c | 8824 | |
7cd4527e AC |
8825 | @table @option |
8826 | @item ^-O0^/OPTIMIZE=NONE^ | |
8827 | No optimization (the default); | |
8828 | generates unoptimized code but has | |
8829 | the fastest compilation time. | |
88e1739c | 8830 | |
7cd4527e AC |
8831 | @item ^-O1^/OPTIMIZE=SOME^ |
8832 | Medium level optimization; | |
8833 | optimizes reasonably well but does not | |
8834 | degrade compilation time significantly. | |
8835 | ||
8836 | @item ^-O2^/OPTIMIZE=ALL^ | |
88e1739c | 8837 | @ifset vms |
7cd4527e | 8838 | @itemx /OPTIMIZE=DEVELOPMENT |
88e1739c | 8839 | @end ifset |
7cd4527e AC |
8840 | Full optimization; |
8841 | generates highly optimized code and has | |
8842 | the slowest compilation time. | |
88e1739c | 8843 | |
7cd4527e AC |
8844 | @item ^-O3^/OPTIMIZE=INLINING^ |
8845 | Full optimization as in @option{-O2}, | |
8846 | and also attempts automatic inlining of small | |
8847 | subprograms within a unit (@pxref{Inlining of Subprograms}). | |
8848 | @end table | |
88e1739c | 8849 | |
7cd4527e AC |
8850 | @noindent |
8851 | Higher optimization levels perform more global transformations on the | |
8852 | program and apply more expensive analysis algorithms in order to generate | |
8853 | faster and more compact code. The price in compilation time, and the | |
8854 | resulting improvement in execution time, | |
8855 | both depend on the particular application and the hardware environment. | |
8856 | You should experiment to find the best level for your application. | |
88e1739c | 8857 | |
7cd4527e AC |
8858 | Since the precise set of optimizations done at each level will vary from |
8859 | release to release (and sometime from target to target), it is best to think | |
8860 | of the optimization settings in general terms. | |
8861 | The @cite{Using GNU GCC} manual contains details about | |
8862 | ^the @option{-O} settings and a number of @option{-f} options that^how to^ | |
8863 | individually enable or disable specific optimizations. | |
88e1739c | 8864 | |
7cd4527e AC |
8865 | Unlike some other compilation systems, ^@command{gcc}^GNAT^ has |
8866 | been tested extensively at all optimization levels. There are some bugs | |
8867 | which appear only with optimization turned on, but there have also been | |
8868 | bugs which show up only in @emph{unoptimized} code. Selecting a lower | |
8869 | level of optimization does not improve the reliability of the code | |
8870 | generator, which in practice is highly reliable at all optimization | |
8871 | levels. | |
88e1739c | 8872 | |
7cd4527e AC |
8873 | Note regarding the use of @option{-O3}: The use of this optimization level |
8874 | is generally discouraged with GNAT, since it often results in larger | |
8875 | executables which run more slowly. See further discussion of this point | |
8876 | in @pxref{Inlining of Subprograms}. | |
88e1739c | 8877 | |
88e1739c | 8878 | |
7cd4527e AC |
8879 | @node Debugging Optimized Code |
8880 | @subsection Debugging Optimized Code | |
8881 | @cindex Debugging optimized code | |
8882 | @cindex Optimization and debugging | |
8883 | ||
8884 | @noindent | |
8885 | Although it is possible to do a reasonable amount of debugging at | |
88e1739c | 8886 | @ifclear vms |
7cd4527e AC |
8887 | non-zero optimization levels, |
8888 | the higher the level the more likely that | |
88e1739c | 8889 | @end ifclear |
88e1739c | 8890 | @ifset vms |
7cd4527e AC |
8891 | @option{/OPTIMIZE} settings other than @code{NONE}, |
8892 | such settings will make it more likely that | |
88e1739c | 8893 | @end ifset |
7cd4527e AC |
8894 | source-level constructs will have been eliminated by optimization. |
8895 | For example, if a loop is strength-reduced, the loop | |
8896 | control variable may be completely eliminated and thus cannot be | |
8897 | displayed in the debugger. | |
8898 | This can only happen at @option{-O2} or @option{-O3}. | |
8899 | Explicit temporary variables that you code might be eliminated at | |
8900 | ^level^setting^ @option{-O1} or higher. | |
8901 | ||
8902 | The use of the @option{^-g^/DEBUG^} switch, | |
8903 | @cindex @option{^-g^/DEBUG^} (@code{gcc}) | |
8904 | which is needed for source-level debugging, | |
8905 | affects the size of the program executable on disk, | |
8906 | and indeed the debugging information can be quite large. | |
8907 | However, it has no effect on the generated code (and thus does not | |
8908 | degrade performance) | |
88e1739c | 8909 | |
7cd4527e AC |
8910 | Since the compiler generates debugging tables for a compilation unit before |
8911 | it performs optimizations, the optimizing transformations may invalidate some | |
8912 | of the debugging data. You therefore need to anticipate certain | |
8913 | anomalous situations that may arise while debugging optimized code. | |
8914 | These are the most common cases: | |
88e1739c | 8915 | |
7cd4527e AC |
8916 | @enumerate |
8917 | @item | |
8918 | @i{The ``hopping Program Counter'':} Repeated @code{step} or @code{next} | |
8919 | commands show | |
8920 | the PC bouncing back and forth in the code. This may result from any of | |
8921 | the following optimizations: | |
88e1739c | 8922 | |
7cd4527e AC |
8923 | @itemize @bullet |
8924 | @item | |
8925 | @i{Common subexpression elimination:} using a single instance of code for a | |
8926 | quantity that the source computes several times. As a result you | |
8927 | may not be able to stop on what looks like a statement. | |
88e1739c | 8928 | |
7cd4527e AC |
8929 | @item |
8930 | @i{Invariant code motion:} moving an expression that does not change within a | |
8931 | loop, to the beginning of the loop. | |
88e1739c | 8932 | |
7cd4527e AC |
8933 | @item |
8934 | @i{Instruction scheduling:} moving instructions so as to | |
8935 | overlap loads and stores (typically) with other code, or in | |
8936 | general to move computations of values closer to their uses. Often | |
8937 | this causes you to pass an assignment statement without the assignment | |
8938 | happening and then later bounce back to the statement when the | |
8939 | value is actually needed. Placing a breakpoint on a line of code | |
8940 | and then stepping over it may, therefore, not always cause all the | |
8941 | expected side-effects. | |
8942 | @end itemize | |
88e1739c | 8943 | |
7cd4527e AC |
8944 | @item |
8945 | @i{The ``big leap'':} More commonly known as @emph{cross-jumping}, in which | |
8946 | two identical pieces of code are merged and the program counter suddenly | |
8947 | jumps to a statement that is not supposed to be executed, simply because | |
8948 | it (and the code following) translates to the same thing as the code | |
8949 | that @emph{was} supposed to be executed. This effect is typically seen in | |
8950 | sequences that end in a jump, such as a @code{goto}, a @code{return}, or | |
8951 | a @code{break} in a C @code{^switch^switch^} statement. | |
88e1739c | 8952 | |
7cd4527e AC |
8953 | @item |
8954 | @i{The ``roving variable'':} The symptom is an unexpected value in a variable. | |
8955 | There are various reasons for this effect: | |
88e1739c | 8956 | |
7cd4527e AC |
8957 | @itemize @bullet |
8958 | @item | |
8959 | In a subprogram prologue, a parameter may not yet have been moved to its | |
8960 | ``home''. | |
88e1739c | 8961 | |
7cd4527e AC |
8962 | @item |
8963 | A variable may be dead, and its register re-used. This is | |
8964 | probably the most common cause. | |
88e1739c | 8965 | |
7cd4527e AC |
8966 | @item |
8967 | As mentioned above, the assignment of a value to a variable may | |
8968 | have been moved. | |
88e1739c | 8969 | |
7cd4527e AC |
8970 | @item |
8971 | A variable may be eliminated entirely by value propagation or | |
8972 | other means. In this case, GCC may incorrectly generate debugging | |
8973 | information for the variable | |
8974 | @end itemize | |
88e1739c FW |
8975 | |
8976 | @noindent | |
7cd4527e AC |
8977 | In general, when an unexpected value appears for a local variable or parameter |
8978 | you should first ascertain if that value was actually computed by | |
8979 | your program, as opposed to being incorrectly reported by the debugger. | |
8980 | Record fields or | |
8981 | array elements in an object designated by an access value | |
8982 | are generally less of a problem, once you have ascertained that the access | |
8983 | value is sensible. | |
8984 | Typically, this means checking variables in the preceding code and in the | |
8985 | calling subprogram to verify that the value observed is explainable from other | |
8986 | values (one must apply the procedure recursively to those | |
8987 | other values); or re-running the code and stopping a little earlier | |
8988 | (perhaps before the call) and stepping to better see how the variable obtained | |
8989 | the value in question; or continuing to step @emph{from} the point of the | |
8990 | strange value to see if code motion had simply moved the variable's | |
8991 | assignments later. | |
8992 | @end enumerate | |
88e1739c | 8993 | |
7cd4527e AC |
8994 | @noindent |
8995 | In light of such anomalies, a recommended technique is to use @option{-O0} | |
8996 | early in the software development cycle, when extensive debugging capabilities | |
8997 | are most needed, and then move to @option{-O1} and later @option{-O2} as | |
8998 | the debugger becomes less critical. | |
8999 | Whether to use the @option{^-g^/DEBUG^} switch in the release version is | |
9000 | a release management issue. | |
9001 | @ifclear vms | |
9002 | Note that if you use @option{-g} you can then use the @command{strip} program | |
9003 | on the resulting executable, | |
9004 | which removes both debugging information and global symbols. | |
9005 | @end ifclear | |
88e1739c | 9006 | |
88e1739c | 9007 | |
7cd4527e AC |
9008 | @node Inlining of Subprograms |
9009 | @subsection Inlining of Subprograms | |
88e1739c FW |
9010 | |
9011 | @noindent | |
7cd4527e AC |
9012 | A call to a subprogram in the current unit is inlined if all the |
9013 | following conditions are met: | |
88e1739c | 9014 | |
7cd4527e AC |
9015 | @itemize @bullet |
9016 | @item | |
9017 | The optimization level is at least @option{-O1}. | |
88e1739c | 9018 | |
7cd4527e AC |
9019 | @item |
9020 | The called subprogram is suitable for inlining: It must be small enough | |
9021 | and not contain nested subprograms or anything else that @code{gcc} | |
9022 | cannot support in inlined subprograms. | |
88e1739c | 9023 | |
7cd4527e AC |
9024 | @item |
9025 | The call occurs after the definition of the body of the subprogram. | |
88e1739c | 9026 | |
7cd4527e AC |
9027 | @item |
9028 | @cindex pragma Inline | |
9029 | @findex Inline | |
9030 | Either @code{pragma Inline} applies to the subprogram or it is | |
9031 | small and automatic inlining (optimization level @option{-O3}) is | |
9032 | specified. | |
9033 | @end itemize | |
88e1739c FW |
9034 | |
9035 | @noindent | |
7cd4527e AC |
9036 | Calls to subprograms in @code{with}'ed units are normally not inlined. |
9037 | To achieve this level of inlining, the following conditions must all be | |
9038 | true: | |
88e1739c | 9039 | |
7cd4527e AC |
9040 | @itemize @bullet |
9041 | @item | |
9042 | The optimization level is at least @option{-O1}. | |
88e1739c | 9043 | |
7cd4527e AC |
9044 | @item |
9045 | The called subprogram is suitable for inlining: It must be small enough | |
9046 | and not contain nested subprograms or anything else @code{gcc} cannot | |
9047 | support in inlined subprograms. | |
88e1739c | 9048 | |
7cd4527e AC |
9049 | @item |
9050 | The call appears in a body (not in a package spec). | |
88e1739c | 9051 | |
7cd4527e AC |
9052 | @item |
9053 | There is a @code{pragma Inline} for the subprogram. | |
88e1739c | 9054 | |
7cd4527e AC |
9055 | @item |
9056 | @cindex @option{-gnatn} (@code{gcc}) | |
9057 | The @option{^-gnatn^/INLINE^} switch | |
9058 | is used in the @code{gcc} command line | |
9059 | @end itemize | |
88e1739c | 9060 | |
7cd4527e AC |
9061 | Note that specifying the @option{-gnatn} switch causes additional |
9062 | compilation dependencies. Consider the following: | |
88e1739c | 9063 | |
7cd4527e AC |
9064 | @smallexample @c ada |
9065 | @cartouche | |
9066 | package R is | |
9067 | procedure Q; | |
9068 | pragma Inline (Q); | |
9069 | end R; | |
9070 | package body R is | |
9071 | ... | |
9072 | end R; | |
88e1739c | 9073 | |
7cd4527e AC |
9074 | with R; |
9075 | procedure Main is | |
9076 | begin | |
9077 | ... | |
9078 | R.Q; | |
9079 | end Main; | |
9080 | @end cartouche | |
9081 | @end smallexample | |
88e1739c FW |
9082 | |
9083 | @noindent | |
7cd4527e AC |
9084 | With the default behavior (no @option{-gnatn} switch specified), the |
9085 | compilation of the @code{Main} procedure depends only on its own source, | |
9086 | @file{main.adb}, and the spec of the package in file @file{r.ads}. This | |
9087 | means that editing the body of @code{R} does not require recompiling | |
9088 | @code{Main}. | |
88e1739c | 9089 | |
7cd4527e AC |
9090 | On the other hand, the call @code{R.Q} is not inlined under these |
9091 | circumstances. If the @option{-gnatn} switch is present when @code{Main} | |
9092 | is compiled, the call will be inlined if the body of @code{Q} is small | |
9093 | enough, but now @code{Main} depends on the body of @code{R} in | |
9094 | @file{r.adb} as well as on the spec. This means that if this body is edited, | |
9095 | the main program must be recompiled. Note that this extra dependency | |
9096 | occurs whether or not the call is in fact inlined by @code{gcc}. | |
88e1739c | 9097 | |
7cd4527e AC |
9098 | The use of front end inlining with @option{-gnatN} generates similar |
9099 | additional dependencies. | |
88e1739c | 9100 | |
7cd4527e AC |
9101 | @cindex @option{^-fno-inline^/INLINE=SUPPRESS^} (@code{gcc}) |
9102 | Note: The @option{^-fno-inline^/INLINE=SUPPRESS^} switch | |
9103 | can be used to prevent | |
9104 | all inlining. This switch overrides all other conditions and ensures | |
9105 | that no inlining occurs. The extra dependences resulting from | |
9106 | @option{-gnatn} will still be active, even if | |
9107 | this switch is used to suppress the resulting inlining actions. | |
88e1739c | 9108 | |
7cd4527e AC |
9109 | Note regarding the use of @option{-O3}: There is no difference in inlining |
9110 | behavior between @option{-O2} and @option{-O3} for subprograms with an explicit | |
9111 | pragma @code{Inline} assuming the use of @option{-gnatn} | |
9112 | or @option{-gnatN} (the switches that activate inlining). If you have used | |
9113 | pragma @code{Inline} in appropriate cases, then it is usually much better | |
9114 | to use @option{-O2} and @option{-gnatn} and avoid the use of @option{-O3} which | |
9115 | in this case only has the effect of inlining subprograms you did not | |
9116 | think should be inlined. We often find that the use of @option{-O3} slows | |
9117 | down code by performing excessive inlining, leading to increased instruction | |
9118 | cache pressure from the increased code size. So the bottom line here is | |
9119 | that you should not automatically assume that @option{-O3} is better than | |
9120 | @option{-O2}, and indeed you should use @option{-O3} only if tests show that | |
9121 | it actually improves performance. | |
88e1739c | 9122 | |
7cd4527e AC |
9123 | @node Optimization and Strict Aliasing |
9124 | @subsection Optimization and Strict Aliasing | |
9125 | @cindex Aliasing | |
9126 | @cindex Strict Aliasing | |
9127 | @cindex No_Strict_Aliasing | |
88e1739c | 9128 | |
7cd4527e AC |
9129 | @noindent |
9130 | The strong typing capabilities of Ada allow an optimizer to generate | |
9131 | efficient code in situations where other languages would be forced to | |
9132 | make worst case assumptions preventing such optimizations. Consider | |
9133 | the following example: | |
88e1739c | 9134 | |
7cd4527e AC |
9135 | @smallexample @c ada |
9136 | @cartouche | |
9137 | procedure R is | |
9138 | type Int1 is new Integer; | |
9139 | type Int2 is new Integer; | |
9140 | type Int1A is access Int1; | |
9141 | type Int2A is access Int2; | |
9142 | Int1V : Int1A; | |
9143 | Int2V : Int2A; | |
9144 | ... | |
88e1739c | 9145 | |
7cd4527e AC |
9146 | begin |
9147 | ... | |
9148 | for J in Data'Range loop | |
9149 | if Data (J) = Int1V.all then | |
9150 | Int2V.all := Int2V.all + 1; | |
9151 | end if; | |
9152 | end loop; | |
9153 | ... | |
9154 | end R; | |
9155 | @end cartouche | |
88e1739c FW |
9156 | @end smallexample |
9157 | ||
7cd4527e AC |
9158 | @noindent |
9159 | In this example, since the variable @code{Int1V} can only access objects | |
9160 | of type @code{Int1}, and @code{Int2V} can only access objects of type | |
9161 | @code{Int2}, there is no possibility that the assignment to | |
9162 | @code{Int2V.all} affects the value of @code{Int1V.all}. This means that | |
9163 | the compiler optimizer can "know" that the value @code{Int1V.all} is constant | |
9164 | for all iterations of the loop and avoid the extra memory reference | |
9165 | required to dereference it each time through the loop. | |
88e1739c | 9166 | |
7cd4527e AC |
9167 | This kind of optimziation, called strict aliasing analysis, is |
9168 | triggered by specifying an optimization level of @option{-O2} or | |
9169 | higher and allows @code{GNAT} to generate more efficient code | |
9170 | when access values are involved. | |
88e1739c | 9171 | |
7cd4527e AC |
9172 | However, although this optimization is always correct in terms of |
9173 | the formal semantics of the Ada Reference Manual, difficulties can | |
9174 | arise if features like @code{Unchecked_Conversion} are used to break | |
9175 | the typing system. Consider the following complete program example: | |
88e1739c | 9176 | |
7cd4527e AC |
9177 | @smallexample @c ada |
9178 | @cartouche | |
9179 | package p1 is | |
9180 | type int1 is new integer; | |
9181 | type int2 is new integer; | |
9182 | type a1 is access int1; | |
9183 | type a2 is access int2; | |
9184 | end p1; | |
9185 | ||
9186 | with p1; use p1; | |
9187 | package p2 is | |
9188 | function to_a2 (Input : a1) return a2; | |
9189 | end p2; | |
9190 | ||
9191 | with Unchecked_Conversion; | |
9192 | package body p2 is | |
9193 | function to_a2 (Input : a1) return a2 is | |
9194 | function to_a2u is | |
9195 | new Unchecked_Conversion (a1, a2); | |
9196 | begin | |
9197 | return to_a2u (Input); | |
9198 | end to_a2; | |
9199 | end p2; | |
88e1739c | 9200 | |
7cd4527e AC |
9201 | with p2; use p2; |
9202 | with p1; use p1; | |
9203 | with Text_IO; use Text_IO; | |
9204 | procedure m is | |
9205 | v1 : a1 := new int1; | |
9206 | v2 : a2 := to_a2 (v1); | |
9207 | begin | |
9208 | v1.all := 1; | |
9209 | v2.all := 0; | |
9210 | put_line (int1'image (v1.all)); | |
9211 | end; | |
9212 | @end cartouche | |
9213 | @end smallexample | |
88e1739c | 9214 | |
7cd4527e AC |
9215 | @noindent |
9216 | This program prints out 0 in @code{-O0} or @code{-O1} | |
9217 | mode, but it prints out 1 in @code{-O2} mode. That's | |
9218 | because in strict aliasing mode, the compiler can and | |
9219 | does assume that the assignment to @code{v2.all} could not | |
9220 | affect the value of @code{v1.all}, since different types | |
9221 | are involved. | |
88e1739c | 9222 | |
7cd4527e AC |
9223 | This behavior is not a case of non-conformance with the standard, since |
9224 | the Ada RM specifies that an unchecked conversion where the resulting | |
9225 | bit pattern is not a correct value of the target type can result in an | |
9226 | abnormal value and attempting to reference an abnormal value makes the | |
9227 | execution of a program erroneous. That's the case here since the result | |
9228 | does not point to an object of type @code{int2}. This means that the | |
9229 | effect is entirely unpredictable. | |
9230 | ||
9231 | However, although that explanation may satisfy a language | |
9232 | lawyer, in practice an applications programmer expects an | |
9233 | unchecked conversion involving pointers to create true | |
9234 | aliases and the behavior of printing 1 seems plain wrong. | |
9235 | In this case, the strict aliasing optimization is unwelcome. | |
9236 | ||
9237 | Indeed the compiler recognizes this possibility, and the | |
9238 | unchecked conversion generates a warning: | |
9239 | ||
9240 | @smallexample | |
9241 | p2.adb:5:07: warning: possible aliasing problem with type "a2" | |
9242 | p2.adb:5:07: warning: use -fno-strict-aliasing switch for references | |
9243 | p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);" | |
9244 | @end smallexample | |
9245 | ||
9246 | @noindent | |
9247 | Unfortunately the problem is recognized when compiling the body of | |
9248 | package @code{p2}, but the actual "bad" code is generated while | |
9249 | compiling the body of @code{m} and this latter compilation does not see | |
9250 | the suspicious @code{Unchecked_Conversion}. | |
9251 | ||
9252 | As implied by the warning message, there are approaches you can use to | |
9253 | avoid the unwanted strict aliasing optimization in a case like this. | |
9254 | ||
9255 | One possibility is to simply avoid the use of @code{-O2}, but | |
9256 | that is a bit drastic, since it throws away a number of useful | |
9257 | optimizations that do not involve strict aliasing assumptions. | |
9258 | ||
9259 | A less drastic approach is to compile the program using the | |
9260 | option @code{-fno-strict-aliasing}. Actually it is only the | |
9261 | unit containing the dereferencing of the suspicious pointer | |
9262 | that needs to be compiled. So in this case, if we compile | |
9263 | unit @code{m} with this switch, then we get the expected | |
9264 | value of zero printed. Analyzing which units might need | |
9265 | the switch can be painful, so a more reasonable approach | |
9266 | is to compile the entire program with options @code{-O2} | |
9267 | and @code{-fno-strict-aliasing}. If the performance is | |
9268 | satisfactory with this combination of options, then the | |
9269 | advantage is that the entire issue of possible "wrong" | |
9270 | optimization due to strict aliasing is avoided. | |
9271 | ||
9272 | To avoid the use of compiler switches, the configuration | |
9273 | pragma @code{No_Strict_Aliasing} with no parameters may be | |
9274 | used to specify that for all access types, the strict | |
9275 | aliasing optimization should be suppressed. | |
9276 | ||
9277 | However, these approaches are still overkill, in that they causes | |
9278 | all manipulations of all access values to be deoptimized. A more | |
9279 | refined approach is to concentrate attention on the specific | |
9280 | access type identified as problematic. | |
9281 | ||
9282 | First, if a careful analysis of uses of the pointer shows | |
9283 | that there are no possible problematic references, then | |
9284 | the warning can be suppressed by bracketing the | |
9285 | instantiation of @code{Unchecked_Conversion} to turn | |
9286 | the warning off: | |
9287 | ||
9288 | @smallexample @c ada | |
9289 | pragma Warnings (Off); | |
9290 | function to_a2u is | |
9291 | new Unchecked_Conversion (a1, a2); | |
9292 | pragma Warnings (On); | |
9293 | @end smallexample | |
9294 | ||
9295 | @noindent | |
9296 | Of course that approach is not appropriate for this particular | |
9297 | example, since indeed there is a problematic reference. In this | |
9298 | case we can take one of two other approaches. | |
9299 | ||
9300 | The first possibility is to move the instantiation of unchecked | |
9301 | conversion to the unit in which the type is declared. In | |
9302 | this example, we would move the instantiation of | |
9303 | @code{Unchecked_Conversion} from the body of package | |
9304 | @code{p2} to the spec of package @code{p1}. Now the | |
9305 | warning disappears. That's because any use of the | |
9306 | access type knows there is a suspicious unchecked | |
9307 | conversion, and the strict aliasing optimization | |
9308 | is automatically suppressed for the type. | |
9309 | ||
9310 | If it is not practical to move the unchecked conversion to the same unit | |
9311 | in which the destination access type is declared (perhaps because the | |
9312 | source type is not visible in that unit), you may use pragma | |
9313 | @code{No_Strict_Aliasing} for the type. This pragma must occur in the | |
9314 | same declarative sequence as the declaration of the access type: | |
9315 | ||
9316 | @smallexample @c ada | |
9317 | type a2 is access int2; | |
9318 | pragma No_Strict_Aliasing (a2); | |
9319 | @end smallexample | |
9320 | ||
9321 | @noindent | |
9322 | Here again, the compiler now knows that the strict aliasing optimization | |
9323 | should be suppressed for any reference to type @code{a2} and the | |
9324 | expected behavior is obtained. | |
9325 | ||
9326 | Finally, note that although the compiler can generate warnings for | |
9327 | simple cases of unchecked conversions, there are tricker and more | |
9328 | indirect ways of creating type incorrect aliases which the compiler | |
9329 | cannot detect. Examples are the use of address overlays and unchecked | |
9330 | conversions involving composite types containing access types as | |
9331 | components. In such cases, no warnings are generated, but there can | |
9332 | still be aliasing problems. One safe coding practice is to forbid the | |
9333 | use of address clauses for type overlaying, and to allow unchecked | |
9334 | conversion only for primitive types. This is not really a significant | |
9335 | restriction since any possible desired effect can be achieved by | |
9336 | unchecked conversion of access values. | |
88e1739c | 9337 | |
7cd4527e AC |
9338 | @ifset vms |
9339 | @node Coverage Analysis | |
9340 | @subsection Coverage Analysis | |
88e1739c | 9341 | |
7cd4527e AC |
9342 | @noindent |
9343 | GNAT supports the Digital Performance Coverage Analyzer (PCA), which allows | |
9344 | the user to determine the distribution of execution time across a program, | |
9345 | @pxref{Profiling} for details of usage. | |
9346 | @end ifset | |
9347 | ||
9348 | @node Reducing the Size of Ada Executables with gnatelim | |
9349 | @section Reducing the Size of Ada Executables with @code{gnatelim} | |
9350 | @findex gnatelim | |
88e1739c FW |
9351 | |
9352 | @noindent | |
7cd4527e AC |
9353 | This section describes @command{gnatelim}, a tool which detects unused |
9354 | subprograms and helps the compiler to create a smaller executable for your | |
9355 | program. | |
88e1739c FW |
9356 | |
9357 | @menu | |
7cd4527e AC |
9358 | * About gnatelim:: |
9359 | * Running gnatelim:: | |
9360 | * Correcting the List of Eliminate Pragmas:: | |
9361 | * Making Your Executables Smaller:: | |
9362 | * Summary of the gnatelim Usage Cycle:: | |
88e1739c FW |
9363 | @end menu |
9364 | ||
7cd4527e AC |
9365 | @node About gnatelim |
9366 | @subsection About @code{gnatelim} | |
88e1739c FW |
9367 | |
9368 | @noindent | |
7cd4527e AC |
9369 | When a program shares a set of Ada |
9370 | packages with other programs, it may happen that this program uses | |
9371 | only a fraction of the subprograms defined in these packages. The code | |
9372 | created for these unused subprograms increases the size of the executable. | |
88e1739c | 9373 | |
7cd4527e AC |
9374 | @code{gnatelim} tracks unused subprograms in an Ada program and |
9375 | outputs a list of GNAT-specific pragmas @code{Eliminate} marking all the | |
9376 | subprograms that are declared but never called. By placing the list of | |
9377 | @code{Eliminate} pragmas in the GNAT configuration file @file{gnat.adc} and | |
9378 | recompiling your program, you may decrease the size of its executable, | |
9379 | because the compiler will not generate the code for 'eliminated' subprograms. | |
9380 | See GNAT Reference Manual for more information about this pragma. | |
88e1739c | 9381 | |
7cd4527e AC |
9382 | @code{gnatelim} needs as its input data the name of the main subprogram |
9383 | and a bind file for a main subprogram. | |
88e1739c | 9384 | |
7cd4527e AC |
9385 | To create a bind file for @code{gnatelim}, run @code{gnatbind} for |
9386 | the main subprogram. @code{gnatelim} can work with both Ada and C | |
9387 | bind files; when both are present, it uses the Ada bind file. | |
9388 | The following commands will build the program and create the bind file: | |
88e1739c | 9389 | |
7cd4527e AC |
9390 | @smallexample |
9391 | $ gnatmake ^-c Main_Prog^/ACTIONS=COMPILE MAIN_PROG^ | |
9392 | $ gnatbind main_prog | |
9393 | @end smallexample | |
9394 | ||
9395 | Note that @code{gnatelim} needs neither object nor ALI files. | |
9396 | ||
9397 | @node Running gnatelim | |
9398 | @subsection Running @code{gnatelim} | |
88e1739c FW |
9399 | |
9400 | @noindent | |
7cd4527e | 9401 | @code{gnatelim} has the following command-line interface: |
88e1739c | 9402 | |
7cd4527e AC |
9403 | @smallexample |
9404 | $ gnatelim [options] name | |
9405 | @end smallexample | |
88e1739c | 9406 | |
7cd4527e AC |
9407 | @noindent |
9408 | @code{name} should be a name of a source file that contains the main subprogram | |
9409 | of a program (partition). | |
88e1739c | 9410 | |
7cd4527e | 9411 | @code{gnatelim} has the following switches: |
88e1739c | 9412 | |
7cd4527e AC |
9413 | @table @option |
9414 | @c !sort! | |
9415 | @item ^-q^/QUIET^ | |
9416 | @cindex @option{^-q^/QUIET^} (@command{gnatelim}) | |
9417 | Quiet mode: by default @code{gnatelim} outputs to the standard error | |
9418 | stream the number of program units left to be processed. This option turns | |
9419 | this trace off. | |
88e1739c | 9420 | |
7cd4527e AC |
9421 | @item ^-v^/VERBOSE^ |
9422 | @cindex @option{^-v^/VERBOSE^} (@command{gnatelim}) | |
9423 | Verbose mode: @code{gnatelim} version information is printed as Ada | |
9424 | comments to the standard output stream. Also, in addition to the number of | |
9425 | program units left @code{gnatelim} will output the name of the current unit | |
9426 | being processed. | |
88e1739c | 9427 | |
7cd4527e AC |
9428 | @item ^-a^/ALL^ |
9429 | @cindex @option{^-a^/ALL^} (@command{gnatelim}) | |
9430 | Also look for subprograms from the GNAT run time that can be eliminated. Note | |
9431 | that when @file{gnat.adc} is produced using this switch, the entire program | |
9432 | must be recompiled with switch @option{^-a^/ALL_FILES^} to @code{gnatmake}. | |
88e1739c | 9433 | |
7cd4527e AC |
9434 | @item ^-I^/INCLUDE_DIRS=^@var{dir} |
9435 | @cindex @option{^-I^/INCLUDE_DIRS^} (@command{gnatelim}) | |
9436 | When looking for source files also look in directory @var{dir}. Specifying | |
9437 | @option{^-I-^/INCLUDE_DIRS=-^} instructs @code{gnatelim} not to look for | |
9438 | sources in the current directory. | |
88e1739c | 9439 | |
7cd4527e AC |
9440 | @item ^-b^/BIND_FILE=^@var{bind_file} |
9441 | @cindex @option{^-b^/BIND_FILE^} (@command{gnatelim}) | |
9442 | Specifies @var{bind_file} as the bind file to process. If not set, the name | |
9443 | of the bind file is computed from the full expanded Ada name | |
9444 | of a main subprogram. | |
88e1739c | 9445 | |
7cd4527e AC |
9446 | @item ^-C^/CONFIG_FILE=^@var{config_file} |
9447 | @cindex @option{^-C^/CONFIG_FILE^} (@command{gnatelim}) | |
9448 | Specifies a file @var{config_file} that contains configuration pragmas. The | |
9449 | file must be specified with full path. | |
9450 | ||
9451 | @item ^--GCC^/COMPILER^=@var{compiler_name} | |
9452 | @cindex @option{^-GCC^/COMPILER^} (@command{gnatelim}) | |
9453 | Instructs @code{gnatelim} to use specific @code{gcc} compiler instead of one | |
9454 | available on the path. | |
9455 | ||
9456 | @item ^--GNATMAKE^/GNATMAKE^=@var{gnatmake_name} | |
9457 | @cindex @option{^--GNATMAKE^/GNATMAKE^} (@command{gnatelim}) | |
9458 | Instructs @code{gnatelim} to use specific @code{gnatmake} instead of one | |
9459 | available on the path. | |
9460 | ||
9461 | @item -d@var{x} | |
9462 | @cindex @option{-d@var{x}} (@command{gnatelim}) | |
9463 | Activate internal debugging switches. @var{x} is a letter or digit, or | |
9464 | string of letters or digits, which specifies the type of debugging | |
9465 | mode desired. Normally these are used only for internal development | |
9466 | or system debugging purposes. You can find full documentation for these | |
9467 | switches in the spec of the @code{Gnatelim} unit in the compiler | |
9468 | source file @file{gnatelim.ads}. | |
9469 | @end table | |
88e1739c FW |
9470 | |
9471 | @noindent | |
7cd4527e AC |
9472 | @code{gnatelim} sends its output to the standard output stream, and all the |
9473 | tracing and debug information is sent to the standard error stream. | |
9474 | In order to produce a proper GNAT configuration file | |
9475 | @file{gnat.adc}, redirection must be used: | |
88e1739c | 9476 | |
88e1739c | 9477 | @smallexample |
7cd4527e AC |
9478 | @ifset vms |
9479 | $ PIPE GNAT ELIM MAIN_PROG.ADB > GNAT.ADC | |
9480 | @end ifset | |
9481 | @ifclear vms | |
9482 | $ gnatelim main_prog.adb > gnat.adc | |
9483 | @end ifclear | |
88e1739c | 9484 | @end smallexample |
88e1739c | 9485 | |
7cd4527e AC |
9486 | @ifclear vms |
9487 | @noindent | |
9488 | or | |
88e1739c FW |
9489 | |
9490 | @smallexample | |
7cd4527e | 9491 | $ gnatelim main_prog.adb >> gnat.adc |
88e1739c FW |
9492 | @end smallexample |
9493 | ||
9494 | @noindent | |
7cd4527e AC |
9495 | in order to append the @code{gnatelim} output to the existing contents of |
9496 | @file{gnat.adc}. | |
9497 | @end ifclear | |
88e1739c | 9498 | |
7cd4527e AC |
9499 | @node Correcting the List of Eliminate Pragmas |
9500 | @subsection Correcting the List of Eliminate Pragmas | |
88e1739c FW |
9501 | |
9502 | @noindent | |
7cd4527e AC |
9503 | In some rare cases @code{gnatelim} may try to eliminate |
9504 | subprograms that are actually called in the program. In this case, the | |
9505 | compiler will generate an error message of the form: | |
88e1739c | 9506 | |
88e1739c | 9507 | @smallexample |
7cd4527e | 9508 | file.adb:106:07: cannot call eliminated subprogram "My_Prog" |
88e1739c FW |
9509 | @end smallexample |
9510 | ||
9511 | @noindent | |
7cd4527e AC |
9512 | You will need to manually remove the wrong @code{Eliminate} pragmas from |
9513 | the @file{gnat.adc} file. You should recompile your program | |
9514 | from scratch after that, because you need a consistent @file{gnat.adc} file | |
9515 | during the entire compilation. | |
88e1739c | 9516 | |
88e1739c | 9517 | |
7cd4527e AC |
9518 | @node Making Your Executables Smaller |
9519 | @subsection Making Your Executables Smaller | |
88e1739c FW |
9520 | |
9521 | @noindent | |
7cd4527e AC |
9522 | In order to get a smaller executable for your program you now have to |
9523 | recompile the program completely with the new @file{gnat.adc} file | |
9524 | created by @code{gnatelim} in your current directory: | |
88e1739c | 9525 | |
7cd4527e AC |
9526 | @smallexample |
9527 | $ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^ | |
9528 | @end smallexample | |
88e1739c FW |
9529 | |
9530 | @noindent | |
7cd4527e AC |
9531 | (Use the @option{^-f^/FORCE_COMPILE^} option for @command{gnatmake} to |
9532 | recompile everything | |
9533 | with the set of pragmas @code{Eliminate} that you have obtained with | |
9534 | @command{gnatelim}). | |
88e1739c | 9535 | |
7cd4527e AC |
9536 | Be aware that the set of @code{Eliminate} pragmas is specific to each |
9537 | program. It is not recommended to merge sets of @code{Eliminate} | |
9538 | pragmas created for different programs in one @file{gnat.adc} file. | |
9539 | ||
9540 | @node Summary of the gnatelim Usage Cycle | |
9541 | @subsection Summary of the gnatelim Usage Cycle | |
88e1739c FW |
9542 | |
9543 | @noindent | |
7cd4527e AC |
9544 | Here is a quick summary of the steps to be taken in order to reduce |
9545 | the size of your executables with @code{gnatelim}. You may use | |
9546 | other GNAT options to control the optimization level, | |
9547 | to produce the debugging information, to set search path, etc. | |
88e1739c | 9548 | |
7cd4527e AC |
9549 | @enumerate |
9550 | @item | |
9551 | Produce a bind file | |
88e1739c | 9552 | |
7cd4527e AC |
9553 | @smallexample |
9554 | $ gnatmake ^-c main_prog^/ACTIONS=COMPILE MAIN_PROG^ | |
9555 | $ gnatbind main_prog | |
9556 | @end smallexample | |
88e1739c | 9557 | |
7cd4527e AC |
9558 | @item |
9559 | Generate a list of @code{Eliminate} pragmas | |
9560 | @smallexample | |
9561 | @ifset vms | |
9562 | $ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC | |
9563 | @end ifset | |
9564 | @ifclear vms | |
9565 | $ gnatelim main_prog >[>] gnat.adc | |
9566 | @end ifclear | |
9567 | @end smallexample | |
88e1739c | 9568 | |
7cd4527e AC |
9569 | @item |
9570 | Recompile the application | |
88e1739c | 9571 | |
7cd4527e AC |
9572 | @smallexample |
9573 | $ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^ | |
9574 | @end smallexample | |
88e1739c | 9575 | |
7cd4527e | 9576 | @end enumerate |
88e1739c | 9577 | |
88e1739c | 9578 | |
88e1739c | 9579 | |
88e1739c | 9580 | |
7cd4527e AC |
9581 | @c ******************************** |
9582 | @node Renaming Files Using gnatchop | |
9583 | @chapter Renaming Files Using @code{gnatchop} | |
9584 | @findex gnatchop | |
88e1739c FW |
9585 | |
9586 | @noindent | |
7cd4527e AC |
9587 | This chapter discusses how to handle files with multiple units by using |
9588 | the @code{gnatchop} utility. This utility is also useful in renaming | |
9589 | files to meet the standard GNAT default file naming conventions. | |
88e1739c | 9590 | |
7cd4527e AC |
9591 | @menu |
9592 | * Handling Files with Multiple Units:: | |
9593 | * Operating gnatchop in Compilation Mode:: | |
9594 | * Command Line for gnatchop:: | |
9595 | * Switches for gnatchop:: | |
9596 | * Examples of gnatchop Usage:: | |
9597 | @end menu | |
88e1739c | 9598 | |
7cd4527e AC |
9599 | @node Handling Files with Multiple Units |
9600 | @section Handling Files with Multiple Units | |
88e1739c FW |
9601 | |
9602 | @noindent | |
7cd4527e AC |
9603 | The basic compilation model of GNAT requires that a file submitted to the |
9604 | compiler have only one unit and there be a strict correspondence | |
9605 | between the file name and the unit name. | |
88e1739c | 9606 | |
7cd4527e AC |
9607 | The @code{gnatchop} utility allows both of these rules to be relaxed, |
9608 | allowing GNAT to process files which contain multiple compilation units | |
9609 | and files with arbitrary file names. @code{gnatchop} | |
9610 | reads the specified file and generates one or more output files, | |
9611 | containing one unit per file. The unit and the file name correspond, | |
9612 | as required by GNAT. | |
88e1739c | 9613 | |
7cd4527e AC |
9614 | If you want to permanently restructure a set of ``foreign'' files so that |
9615 | they match the GNAT rules, and do the remaining development using the | |
9616 | GNAT structure, you can simply use @command{gnatchop} once, generate the | |
9617 | new set of files and work with them from that point on. | |
88e1739c | 9618 | |
7cd4527e AC |
9619 | Alternatively, if you want to keep your files in the ``foreign'' format, |
9620 | perhaps to maintain compatibility with some other Ada compilation | |
9621 | system, you can set up a procedure where you use @command{gnatchop} each | |
9622 | time you compile, regarding the source files that it writes as temporary | |
9623 | files that you throw away. | |
88e1739c | 9624 | |
88e1739c | 9625 | |
7cd4527e AC |
9626 | @node Operating gnatchop in Compilation Mode |
9627 | @section Operating gnatchop in Compilation Mode | |
88e1739c | 9628 | |
7cd4527e AC |
9629 | @noindent |
9630 | The basic function of @code{gnatchop} is to take a file with multiple units | |
9631 | and split it into separate files. The boundary between files is reasonably | |
9632 | clear, except for the issue of comments and pragmas. In default mode, the | |
9633 | rule is that any pragmas between units belong to the previous unit, except | |
9634 | that configuration pragmas always belong to the following unit. Any comments | |
9635 | belong to the following unit. These rules | |
9636 | almost always result in the right choice of | |
9637 | the split point without needing to mark it explicitly and most users will | |
9638 | find this default to be what they want. In this default mode it is incorrect to | |
9639 | submit a file containing only configuration pragmas, or one that ends in | |
9640 | configuration pragmas, to @code{gnatchop}. | |
88e1739c | 9641 | |
7cd4527e AC |
9642 | However, using a special option to activate ``compilation mode'', |
9643 | @code{gnatchop} | |
9644 | can perform another function, which is to provide exactly the semantics | |
9645 | required by the RM for handling of configuration pragmas in a compilation. | |
9646 | In the absence of configuration pragmas (at the main file level), this | |
9647 | option has no effect, but it causes such configuration pragmas to be handled | |
9648 | in a quite different manner. | |
88e1739c | 9649 | |
7cd4527e AC |
9650 | First, in compilation mode, if @code{gnatchop} is given a file that consists of |
9651 | only configuration pragmas, then this file is appended to the | |
9652 | @file{gnat.adc} file in the current directory. This behavior provides | |
9653 | the required behavior described in the RM for the actions to be taken | |
9654 | on submitting such a file to the compiler, namely that these pragmas | |
9655 | should apply to all subsequent compilations in the same compilation | |
9656 | environment. Using GNAT, the current directory, possibly containing a | |
9657 | @file{gnat.adc} file is the representation | |
9658 | of a compilation environment. For more information on the | |
9659 | @file{gnat.adc} file, see the section on handling of configuration | |
9660 | pragmas @pxref{Handling of Configuration Pragmas}. | |
88e1739c | 9661 | |
7cd4527e AC |
9662 | Second, in compilation mode, if @code{gnatchop} |
9663 | is given a file that starts with | |
9664 | configuration pragmas, and contains one or more units, then these | |
9665 | configuration pragmas are prepended to each of the chopped files. This | |
9666 | behavior provides the required behavior described in the RM for the | |
9667 | actions to be taken on compiling such a file, namely that the pragmas | |
9668 | apply to all units in the compilation, but not to subsequently compiled | |
9669 | units. | |
88e1739c | 9670 | |
7cd4527e AC |
9671 | Finally, if configuration pragmas appear between units, they are appended |
9672 | to the previous unit. This results in the previous unit being illegal, | |
9673 | since the compiler does not accept configuration pragmas that follow | |
9674 | a unit. This provides the required RM behavior that forbids configuration | |
9675 | pragmas other than those preceding the first compilation unit of a | |
9676 | compilation. | |
88e1739c | 9677 | |
7cd4527e AC |
9678 | For most purposes, @code{gnatchop} will be used in default mode. The |
9679 | compilation mode described above is used only if you need exactly | |
9680 | accurate behavior with respect to compilations, and you have files | |
9681 | that contain multiple units and configuration pragmas. In this | |
9682 | circumstance the use of @code{gnatchop} with the compilation mode | |
9683 | switch provides the required behavior, and is for example the mode | |
9684 | in which GNAT processes the ACVC tests. | |
88e1739c | 9685 | |
7cd4527e AC |
9686 | @node Command Line for gnatchop |
9687 | @section Command Line for @code{gnatchop} | |
88e1739c FW |
9688 | |
9689 | @noindent | |
7cd4527e | 9690 | The @code{gnatchop} command has the form: |
88e1739c | 9691 | |
88e1739c | 9692 | @smallexample |
7cd4527e AC |
9693 | $ gnatchop switches @var{file name} [@var{file name} @var{file name} ...] |
9694 | [@var{directory}] | |
88e1739c FW |
9695 | @end smallexample |
9696 | ||
9697 | @noindent | |
7cd4527e AC |
9698 | The only required argument is the file name of the file to be chopped. |
9699 | There are no restrictions on the form of this file name. The file itself | |
9700 | contains one or more Ada units, in normal GNAT format, concatenated | |
9701 | together. As shown, more than one file may be presented to be chopped. | |
88e1739c | 9702 | |
7cd4527e AC |
9703 | When run in default mode, @code{gnatchop} generates one output file in |
9704 | the current directory for each unit in each of the files. | |
88e1739c | 9705 | |
7cd4527e AC |
9706 | @var{directory}, if specified, gives the name of the directory to which |
9707 | the output files will be written. If it is not specified, all files are | |
9708 | written to the current directory. | |
88e1739c | 9709 | |
7cd4527e AC |
9710 | For example, given a |
9711 | file called @file{hellofiles} containing | |
88e1739c | 9712 | |
7cd4527e | 9713 | @smallexample @c ada |
88e1739c | 9714 | @group |
7cd4527e AC |
9715 | @cartouche |
9716 | procedure hello; | |
88e1739c | 9717 | |
7cd4527e AC |
9718 | with Text_IO; use Text_IO; |
9719 | procedure hello is | |
88e1739c | 9720 | begin |
7cd4527e AC |
9721 | Put_Line ("Hello"); |
9722 | end hello; | |
9723 | @end cartouche | |
88e1739c FW |
9724 | @end group |
9725 | @end smallexample | |
9726 | ||
9727 | @noindent | |
7cd4527e | 9728 | the command |
88e1739c FW |
9729 | |
9730 | @smallexample | |
7cd4527e | 9731 | $ gnatchop ^hellofiles^HELLOFILES.^ |
88e1739c FW |
9732 | @end smallexample |
9733 | ||
9734 | @noindent | |
7cd4527e AC |
9735 | generates two files in the current directory, one called |
9736 | @file{hello.ads} containing the single line that is the procedure spec, | |
9737 | and the other called @file{hello.adb} containing the remaining text. The | |
9738 | original file is not affected. The generated files can be compiled in | |
9739 | the normal manner. | |
88e1739c FW |
9740 | |
9741 | @noindent | |
7cd4527e AC |
9742 | When gnatchop is invoked on a file that is empty or that contains only empty |
9743 | lines and/or comments, gnatchop will not fail, but will not produce any | |
9744 | new sources. | |
88e1739c | 9745 | |
7cd4527e AC |
9746 | For example, given a |
9747 | file called @file{toto.txt} containing | |
88e1739c | 9748 | |
7cd4527e | 9749 | @smallexample @c ada |
88e1739c | 9750 | @group |
7cd4527e AC |
9751 | @cartouche |
9752 | -- Just a comment | |
9753 | @end cartouche | |
88e1739c FW |
9754 | @end group |
9755 | @end smallexample | |
9756 | ||
9757 | @noindent | |
7cd4527e | 9758 | the command |
88e1739c FW |
9759 | |
9760 | @smallexample | |
7cd4527e | 9761 | $ gnatchop ^toto.txt^TOT.TXT^ |
88e1739c FW |
9762 | @end smallexample |
9763 | ||
9764 | @noindent | |
7cd4527e | 9765 | will not produce any new file and will result in the following warnings: |
88e1739c FW |
9766 | |
9767 | @smallexample | |
7cd4527e AC |
9768 | toto.txt:1:01: warning: empty file, contains no compilation units |
9769 | no compilation units found | |
9770 | no source files written | |
88e1739c FW |
9771 | @end smallexample |
9772 | ||
7cd4527e AC |
9773 | @node Switches for gnatchop |
9774 | @section Switches for @code{gnatchop} | |
88e1739c | 9775 | |
7cd4527e AC |
9776 | @noindent |
9777 | @command{gnatchop} recognizes the following switches: | |
88e1739c | 9778 | |
7cd4527e AC |
9779 | @table @option |
9780 | @c !sort! | |
88e1739c | 9781 | |
7cd4527e AC |
9782 | @item ^-c^/COMPILATION^ |
9783 | @cindex @option{^-c^/COMPILATION^} (@code{gnatchop}) | |
9784 | Causes @code{gnatchop} to operate in compilation mode, in which | |
9785 | configuration pragmas are handled according to strict RM rules. See | |
9786 | previous section for a full description of this mode. | |
88e1739c | 9787 | |
7cd4527e AC |
9788 | @ifclear vms |
9789 | @item -gnatxxx | |
9790 | This passes the given @option{-gnatxxx} switch to @code{gnat} which is | |
9791 | used to parse the given file. Not all @code{xxx} options make sense, | |
9792 | but for example, the use of @option{-gnati2} allows @code{gnatchop} to | |
9793 | process a source file that uses Latin-2 coding for identifiers. | |
9794 | @end ifclear | |
88e1739c | 9795 | |
7cd4527e AC |
9796 | @item ^-h^/HELP^ |
9797 | Causes @code{gnatchop} to generate a brief help summary to the standard | |
9798 | output file showing usage information. | |
88e1739c | 9799 | |
7cd4527e AC |
9800 | @item ^-k@var{mm}^/FILE_NAME_MAX_LENGTH=@var{mm}^ |
9801 | @cindex @option{^-k^/FILE_NAME_MAX_LENGTH^} (@code{gnatchop}) | |
9802 | Limit generated file names to the specified number @code{mm} | |
9803 | of characters. | |
9804 | This is useful if the | |
9805 | resulting set of files is required to be interoperable with systems | |
9806 | which limit the length of file names. | |
9807 | @ifset vms | |
9808 | If no value is given, or | |
9809 | if no @code{/FILE_NAME_MAX_LENGTH} qualifier is given, | |
9810 | a default of 39, suitable for OpenVMS Alpha | |
9811 | Systems, is assumed | |
9812 | @end ifset | |
9813 | @ifclear vms | |
9814 | No space is allowed between the @option{-k} and the numeric value. The numeric | |
9815 | value may be omitted in which case a default of @option{-k8}, | |
9816 | suitable for use | |
9817 | with DOS-like file systems, is used. If no @option{-k} switch | |
9818 | is present then | |
9819 | there is no limit on the length of file names. | |
9820 | @end ifclear | |
88e1739c | 9821 | |
7cd4527e AC |
9822 | @item ^-p^/PRESERVE^ |
9823 | @cindex @option{^-p^/PRESERVE^} (@code{gnatchop}) | |
9824 | Causes the file ^modification^creation^ time stamp of the input file to be | |
9825 | preserved and used for the time stamp of the output file(s). This may be | |
9826 | useful for preserving coherency of time stamps in an environment where | |
9827 | @code{gnatchop} is used as part of a standard build process. | |
88e1739c | 9828 | |
7cd4527e AC |
9829 | @item ^-q^/QUIET^ |
9830 | @cindex @option{^-q^/QUIET^} (@code{gnatchop}) | |
9831 | Causes output of informational messages indicating the set of generated | |
9832 | files to be suppressed. Warnings and error messages are unaffected. | |
88e1739c | 9833 | |
7cd4527e AC |
9834 | @item ^-r^/REFERENCE^ |
9835 | @cindex @option{^-r^/REFERENCE^} (@code{gnatchop}) | |
9836 | @findex Source_Reference | |
9837 | Generate @code{Source_Reference} pragmas. Use this switch if the output | |
9838 | files are regarded as temporary and development is to be done in terms | |
9839 | of the original unchopped file. This switch causes | |
9840 | @code{Source_Reference} pragmas to be inserted into each of the | |
9841 | generated files to refers back to the original file name and line number. | |
9842 | The result is that all error messages refer back to the original | |
9843 | unchopped file. | |
9844 | In addition, the debugging information placed into the object file (when | |
9845 | the @option{^-g^/DEBUG^} switch of @code{gcc} or @code{gnatmake} is specified) | |
9846 | also refers back to this original file so that tools like profilers and | |
9847 | debuggers will give information in terms of the original unchopped file. | |
88e1739c | 9848 | |
7cd4527e AC |
9849 | If the original file to be chopped itself contains |
9850 | a @code{Source_Reference} | |
9851 | pragma referencing a third file, then gnatchop respects | |
9852 | this pragma, and the generated @code{Source_Reference} pragmas | |
9853 | in the chopped file refer to the original file, with appropriate | |
9854 | line numbers. This is particularly useful when @code{gnatchop} | |
9855 | is used in conjunction with @code{gnatprep} to compile files that | |
9856 | contain preprocessing statements and multiple units. | |
88e1739c | 9857 | |
7cd4527e AC |
9858 | @item ^-v^/VERBOSE^ |
9859 | @cindex @option{^-v^/VERBOSE^} (@code{gnatchop}) | |
9860 | Causes @code{gnatchop} to operate in verbose mode. The version | |
9861 | number and copyright notice are output, as well as exact copies of | |
9862 | the gnat1 commands spawned to obtain the chop control information. | |
88e1739c | 9863 | |
7cd4527e AC |
9864 | @item ^-w^/OVERWRITE^ |
9865 | @cindex @option{^-w^/OVERWRITE^} (@code{gnatchop}) | |
9866 | Overwrite existing file names. Normally @code{gnatchop} regards it as a | |
9867 | fatal error if there is already a file with the same name as a | |
9868 | file it would otherwise output, in other words if the files to be | |
9869 | chopped contain duplicated units. This switch bypasses this | |
9870 | check, and causes all but the last instance of such duplicated | |
9871 | units to be skipped. | |
88e1739c | 9872 | |
7cd4527e AC |
9873 | @ifclear vms |
9874 | @item --GCC=xxxx | |
9875 | @cindex @option{--GCC=} (@code{gnatchop}) | |
9876 | Specify the path of the GNAT parser to be used. When this switch is used, | |
9877 | no attempt is made to add the prefix to the GNAT parser executable. | |
9878 | @end ifclear | |
9879 | @end table | |
88e1739c | 9880 | |
7cd4527e AC |
9881 | @node Examples of gnatchop Usage |
9882 | @section Examples of @code{gnatchop} Usage | |
88e1739c | 9883 | |
7cd4527e AC |
9884 | @table @code |
9885 | @ifset vms | |
9886 | @item gnatchop /OVERWRITE HELLO_S.ADA [PRERELEASE.FILES] | |
9887 | @end ifset | |
9888 | @ifclear vms | |
9889 | @item gnatchop -w hello_s.ada prerelease/files | |
9890 | @end ifclear | |
88e1739c | 9891 | |
7cd4527e AC |
9892 | Chops the source file @file{hello_s.ada}. The output files will be |
9893 | placed in the directory @file{^prerelease/files^[PRERELEASE.FILES]^}, | |
9894 | overwriting any | |
9895 | files with matching names in that directory (no files in the current | |
9896 | directory are modified). | |
88e1739c | 9897 | |
7cd4527e AC |
9898 | @item gnatchop ^archive^ARCHIVE.^ |
9899 | Chops the source file @file{^archive^ARCHIVE.^} | |
9900 | into the current directory. One | |
9901 | useful application of @code{gnatchop} is in sending sets of sources | |
9902 | around, for example in email messages. The required sources are simply | |
9903 | concatenated (for example, using a ^Unix @code{cat}^VMS @code{APPEND/NEW}^ | |
9904 | command), and then | |
9905 | @code{gnatchop} is used at the other end to reconstitute the original | |
9906 | file names. | |
88e1739c | 9907 | |
7cd4527e AC |
9908 | @item gnatchop file1 file2 file3 direc |
9909 | Chops all units in files @file{file1}, @file{file2}, @file{file3}, placing | |
9910 | the resulting files in the directory @file{direc}. Note that if any units | |
9911 | occur more than once anywhere within this set of files, an error message | |
9912 | is generated, and no files are written. To override this check, use the | |
9913 | @option{^-w^/OVERWRITE^} switch, | |
9914 | in which case the last occurrence in the last file will | |
9915 | be the one that is output, and earlier duplicate occurrences for a given | |
9916 | unit will be skipped. | |
9917 | @end table | |
88e1739c | 9918 | |
7cd4527e AC |
9919 | @node Configuration Pragmas |
9920 | @chapter Configuration Pragmas | |
9921 | @cindex Configuration pragmas | |
9922 | @cindex Pragmas, configuration | |
88e1739c FW |
9923 | |
9924 | @noindent | |
7cd4527e AC |
9925 | In Ada 95, configuration pragmas include those pragmas described as |
9926 | such in the Ada 95 Reference Manual, as well as | |
9927 | implementation-dependent pragmas that are configuration pragmas. See the | |
9928 | individual descriptions of pragmas in the GNAT Reference Manual for | |
9929 | details on these additional GNAT-specific configuration pragmas. Most | |
9930 | notably, the pragma @code{Source_File_Name}, which allows | |
9931 | specifying non-default names for source files, is a configuration | |
9932 | pragma. The following is a complete list of configuration pragmas | |
9933 | recognized by @code{GNAT}: | |
88e1739c FW |
9934 | |
9935 | @smallexample | |
7cd4527e AC |
9936 | Ada_83 |
9937 | Ada_95 | |
9938 | C_Pass_By_Copy | |
9939 | Component_Alignment | |
9940 | Discard_Names | |
9941 | Elaboration_Checks | |
9942 | Eliminate | |
9943 | Extend_System | |
9944 | Extensions_Allowed | |
9945 | External_Name_Casing | |
9946 | Float_Representation | |
9947 | Initialize_Scalars | |
9948 | License | |
9949 | Locking_Policy | |
9950 | Long_Float | |
9951 | Normalize_Scalars | |
9952 | Polling | |
9953 | Propagate_Exceptions | |
9954 | Queuing_Policy | |
9955 | Ravenscar | |
9956 | Restricted_Run_Time | |
9957 | Restrictions | |
9958 | Reviewable | |
9959 | Source_File_Name | |
9960 | Style_Checks | |
9961 | Suppress | |
9962 | Task_Dispatching_Policy | |
9963 | Universal_Data | |
9964 | Unsuppress | |
9965 | Use_VADS_Size | |
9966 | Warnings | |
9967 | Validity_Checks | |
88e1739c FW |
9968 | @end smallexample |
9969 | ||
7cd4527e AC |
9970 | @menu |
9971 | * Handling of Configuration Pragmas:: | |
9972 | * The Configuration Pragmas Files:: | |
9973 | @end menu | |
88e1739c | 9974 | |
7cd4527e AC |
9975 | @node Handling of Configuration Pragmas |
9976 | @section Handling of Configuration Pragmas | |
88e1739c | 9977 | |
7cd4527e AC |
9978 | Configuration pragmas may either appear at the start of a compilation |
9979 | unit, in which case they apply only to that unit, or they may apply to | |
9980 | all compilations performed in a given compilation environment. | |
88e1739c | 9981 | |
7cd4527e AC |
9982 | GNAT also provides the @code{gnatchop} utility to provide an automatic |
9983 | way to handle configuration pragmas following the semantics for | |
9984 | compilations (that is, files with multiple units), described in the RM. | |
9985 | See section @pxref{Operating gnatchop in Compilation Mode} for details. | |
9986 | However, for most purposes, it will be more convenient to edit the | |
9987 | @file{gnat.adc} file that contains configuration pragmas directly, | |
9988 | as described in the following section. | |
88e1739c | 9989 | |
7cd4527e AC |
9990 | @node The Configuration Pragmas Files |
9991 | @section The Configuration Pragmas Files | |
9992 | @cindex @file{gnat.adc} | |
88e1739c FW |
9993 | |
9994 | @noindent | |
7cd4527e AC |
9995 | In GNAT a compilation environment is defined by the current |
9996 | directory at the time that a compile command is given. This current | |
9997 | directory is searched for a file whose name is @file{gnat.adc}. If | |
9998 | this file is present, it is expected to contain one or more | |
9999 | configuration pragmas that will be applied to the current compilation. | |
10000 | However, if the switch @option{-gnatA} is used, @file{gnat.adc} is not | |
10001 | considered. | |
88e1739c | 10002 | |
7cd4527e AC |
10003 | Configuration pragmas may be entered into the @file{gnat.adc} file |
10004 | either by running @code{gnatchop} on a source file that consists only of | |
10005 | configuration pragmas, or more conveniently by | |
10006 | direct editing of the @file{gnat.adc} file, which is a standard format | |
10007 | source file. | |
88e1739c | 10008 | |
7cd4527e AC |
10009 | In addition to @file{gnat.adc}, one additional file containing configuration |
10010 | pragmas may be applied to the current compilation using the switch | |
10011 | @option{-gnatec}@var{path}. @var{path} must designate an existing file that | |
10012 | contains only configuration pragmas. These configuration pragmas are | |
10013 | in addition to those found in @file{gnat.adc} (provided @file{gnat.adc} | |
10014 | is present and switch @option{-gnatA} is not used). | |
10015 | ||
10016 | It is allowed to specify several switches @option{-gnatec}, however only | |
10017 | the last one on the command line will be taken into account. | |
10018 | ||
10019 | If you are using project file, a separate mechanism is provided using | |
10020 | project attributes, see @ref{Specifying Configuration Pragmas} for more | |
10021 | details. | |
10022 | ||
10023 | @ifset vms | |
10024 | Of special interest to GNAT OpenVMS Alpha is the following | |
10025 | configuration pragma: | |
10026 | ||
10027 | @smallexample @c ada | |
10028 | @cartouche | |
10029 | pragma Extend_System (Aux_DEC); | |
10030 | @end cartouche | |
88e1739c | 10031 | @end smallexample |
88e1739c FW |
10032 | |
10033 | @noindent | |
7cd4527e AC |
10034 | In the presence of this pragma, GNAT adds to the definition of the |
10035 | predefined package SYSTEM all the additional types and subprograms that are | |
10036 | defined in DEC Ada. See @pxref{Compatibility with DEC Ada} for details. | |
10037 | @end ifset | |
10038 | ||
10039 | @node Handling Arbitrary File Naming Conventions Using gnatname | |
10040 | @chapter Handling Arbitrary File Naming Conventions Using @code{gnatname} | |
10041 | @cindex Arbitrary File Naming Conventions | |
10042 | ||
10043 | @menu | |
10044 | * Arbitrary File Naming Conventions:: | |
10045 | * Running gnatname:: | |
10046 | * Switches for gnatname:: | |
10047 | * Examples of gnatname Usage:: | |
10048 | @end menu | |
10049 | ||
10050 | @node Arbitrary File Naming Conventions | |
10051 | @section Arbitrary File Naming Conventions | |
10052 | ||
10053 | @noindent | |
10054 | The GNAT compiler must be able to know the source file name of a compilation | |
10055 | unit. When using the standard GNAT default file naming conventions | |
10056 | (@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler | |
10057 | does not need additional information. | |
10058 | ||
10059 | @noindent | |
10060 | When the source file names do not follow the standard GNAT default file naming | |
10061 | conventions, the GNAT compiler must be given additional information through | |
10062 | a configuration pragmas file (see @ref{Configuration Pragmas}) | |
10063 | or a project file. | |
10064 | When the non standard file naming conventions are well-defined, | |
10065 | a small number of pragmas @code{Source_File_Name} specifying a naming pattern | |
10066 | (see @ref{Alternative File Naming Schemes}) may be sufficient. However, | |
10067 | if the file naming conventions are irregular or arbitrary, a number | |
10068 | of pragma @code{Source_File_Name} for individual compilation units | |
10069 | must be defined. | |
10070 | To help maintain the correspondence between compilation unit names and | |
10071 | source file names within the compiler, | |
10072 | GNAT provides a tool @code{gnatname} to generate the required pragmas for a | |
10073 | set of files. | |
10074 | ||
10075 | @node Running gnatname | |
10076 | @section Running @code{gnatname} | |
10077 | ||
10078 | @noindent | |
10079 | The usual form of the @code{gnatname} command is | |
88e1739c FW |
10080 | |
10081 | @smallexample | |
7cd4527e | 10082 | $ gnatname [@var{switches}] @var{naming_pattern} [@var{naming_patterns}] |
88e1739c FW |
10083 | @end smallexample |
10084 | ||
7cd4527e AC |
10085 | @noindent |
10086 | All of the arguments are optional. If invoked without any argument, | |
10087 | @code{gnatname} will display its usage. | |
88e1739c | 10088 | |
7cd4527e AC |
10089 | @noindent |
10090 | When used with at least one naming pattern, @code{gnatname} will attempt to | |
10091 | find all the compilation units in files that follow at least one of the | |
10092 | naming patterns. To find these compilation units, | |
10093 | @code{gnatname} will use the GNAT compiler in syntax-check-only mode on all | |
10094 | regular files. | |
88e1739c FW |
10095 | |
10096 | @noindent | |
7cd4527e AC |
10097 | One or several Naming Patterns may be given as arguments to @code{gnatname}. |
10098 | Each Naming Pattern is enclosed between double quotes. | |
10099 | A Naming Pattern is a regular expression similar to the wildcard patterns | |
10100 | used in file names by the Unix shells or the DOS prompt. | |
88e1739c | 10101 | |
7cd4527e AC |
10102 | @noindent |
10103 | Examples of Naming Patterns are | |
88e1739c FW |
10104 | |
10105 | @smallexample | |
7cd4527e AC |
10106 | "*.[12].ada" |
10107 | "*.ad[sb]*" | |
10108 | "body_*" "spec_*" | |
88e1739c FW |
10109 | @end smallexample |
10110 | ||
10111 | @noindent | |
7cd4527e AC |
10112 | For a more complete description of the syntax of Naming Patterns, |
10113 | see the second kind of regular expressions described in @file{g-regexp.ads} | |
10114 | (the ``Glob'' regular expressions). | |
88e1739c | 10115 | |
7cd4527e AC |
10116 | @noindent |
10117 | When invoked with no switches, @code{gnatname} will create a configuration | |
10118 | pragmas file @file{gnat.adc} in the current working directory, with pragmas | |
10119 | @code{Source_File_Name} for each file that contains a valid Ada unit. | |
88e1739c | 10120 | |
7cd4527e AC |
10121 | @node Switches for gnatname |
10122 | @section Switches for @code{gnatname} | |
88e1739c | 10123 | |
7cd4527e AC |
10124 | @noindent |
10125 | Switches for @code{gnatname} must precede any specified Naming Pattern. | |
88e1739c | 10126 | |
7cd4527e AC |
10127 | @noindent |
10128 | You may specify any of the following switches to @code{gnatname}: | |
88e1739c | 10129 | |
7cd4527e AC |
10130 | @table @option |
10131 | @c !sort! | |
88e1739c | 10132 | |
7cd4527e AC |
10133 | @item ^-c^/CONFIG_FILE=^@file{file} |
10134 | @cindex @option{^-c^/CONFIG_FILE^} (@code{gnatname}) | |
10135 | Create a configuration pragmas file @file{file} (instead of the default | |
10136 | @file{gnat.adc}). | |
10137 | @ifclear vms | |
10138 | There may be zero, one or more space between @option{-c} and | |
10139 | @file{file}. | |
10140 | @end ifclear | |
10141 | @file{file} may include directory information. @file{file} must be | |
10142 | writable. There may be only one switch @option{^-c^/CONFIG_FILE^}. | |
10143 | When a switch @option{^-c^/CONFIG_FILE^} is | |
10144 | specified, no switch @option{^-P^/PROJECT_FILE^} may be specified (see below). | |
10145 | ||
10146 | @item ^-d^/SOURCE_DIRS=^@file{dir} | |
10147 | @cindex @option{^-d^/SOURCE_DIRS^} (@code{gnatname}) | |
10148 | Look for source files in directory @file{dir}. There may be zero, one or more | |
10149 | spaces between @option{^-d^/SOURCE_DIRS=^} and @file{dir}. | |
10150 | When a switch @option{^-d^/SOURCE_DIRS^} | |
10151 | is specified, the current working directory will not be searched for source | |
10152 | files, unless it is explicitly specified with a @option{^-d^/SOURCE_DIRS^} | |
10153 | or @option{^-D^/DIR_FILES^} switch. | |
10154 | Several switches @option{^-d^/SOURCE_DIRS^} may be specified. | |
10155 | If @file{dir} is a relative path, it is relative to the directory of | |
10156 | the configuration pragmas file specified with switch | |
10157 | @option{^-c^/CONFIG_FILE^}, | |
10158 | or to the directory of the project file specified with switch | |
10159 | @option{^-P^/PROJECT_FILE^} or, | |
10160 | if neither switch @option{^-c^/CONFIG_FILE^} | |
10161 | nor switch @option{^-P^/PROJECT_FILE^} are specified, it is relative to the | |
10162 | current working directory. The directory | |
10163 | specified with switch @option{^-d^/SOURCE_DIRS^} must exist and be readable. | |
10164 | ||
10165 | @item ^-D^/DIRS_FILE=^@file{file} | |
10166 | @cindex @option{^-D^/DIRS_FILE^} (@code{gnatname}) | |
10167 | Look for source files in all directories listed in text file @file{file}. | |
10168 | There may be zero, one or more spaces between @option{^-D^/DIRS_FILE=^} | |
10169 | and @file{file}. | |
10170 | @file{file} must be an existing, readable text file. | |
10171 | Each non empty line in @file{file} must be a directory. | |
10172 | Specifying switch @option{^-D^/DIRS_FILE^} is equivalent to specifying as many | |
10173 | switches @option{^-d^/SOURCE_DIRS^} as there are non empty lines in | |
10174 | @file{file}. | |
10175 | ||
10176 | @item ^-f^/FOREIGN_PATTERN=^@file{pattern} | |
10177 | @cindex @option{^-f^/FOREIGN_PATTERN^} (@code{gnatname}) | |
10178 | Foreign patterns. Using this switch, it is possible to add sources of languages | |
10179 | other than Ada to the list of sources of a project file. | |
10180 | It is only useful if a ^-P^/PROJECT_FILE^ switch is used. | |
10181 | For example, | |
10182 | @smallexample | |
10183 | gnatname ^-Pprj -f"*.c"^/PROJECT_FILE=PRJ /FOREIGN_PATTERN=*.C^ "*.ada" | |
10184 | @end smallexample | |
10185 | @noindent | |
10186 | will look for Ada units in all files with the @file{.ada} extension, | |
10187 | and will add to the list of file for project @file{prj.gpr} the C files | |
10188 | with extension ".^c^C^". | |
88e1739c | 10189 | |
7cd4527e AC |
10190 | @item ^-h^/HELP^ |
10191 | @cindex @option{^-h^/HELP^} (@code{gnatname}) | |
10192 | Output usage (help) information. The output is written to @file{stdout}. | |
10193 | ||
10194 | @item ^-P^/PROJECT_FILE=^@file{proj} | |
10195 | @cindex @option{^-P^/PROJECT_FILE^} (@code{gnatname}) | |
10196 | Create or update project file @file{proj}. There may be zero, one or more space | |
10197 | between @option{-P} and @file{proj}. @file{proj} may include directory | |
10198 | information. @file{proj} must be writable. | |
10199 | There may be only one switch @option{^-P^/PROJECT_FILE^}. | |
10200 | When a switch @option{^-P^/PROJECT_FILE^} is specified, | |
10201 | no switch @option{^-c^/CONFIG_FILE^} may be specified. | |
88e1739c | 10202 | |
7cd4527e AC |
10203 | @item ^-v^/VERBOSE^ |
10204 | @cindex @option{^-v^/VERBOSE^} (@code{gnatname}) | |
10205 | Verbose mode. Output detailed explanation of behavior to @file{stdout}. | |
10206 | This includes name of the file written, the name of the directories to search | |
10207 | and, for each file in those directories whose name matches at least one of | |
10208 | the Naming Patterns, an indication of whether the file contains a unit, | |
10209 | and if so the name of the unit. | |
10210 | ||
10211 | @item ^-v -v^/VERBOSE /VERBOSE^ | |
10212 | @cindex @option{^-v -v^/VERBOSE /VERBOSE^} (@code{gnatname}) | |
10213 | Very Verbose mode. In addition to the output produced in verbose mode, | |
10214 | for each file in the searched directories whose name matches none of | |
10215 | the Naming Patterns, an indication is given that there is no match. | |
10216 | ||
10217 | @item ^-x^/EXCLUDED_PATTERN=^@file{pattern} | |
10218 | @cindex @option{^-x^/EXCLUDED_PATTERN^} (@code{gnatname}) | |
10219 | Excluded patterns. Using this switch, it is possible to exclude some files | |
10220 | that would match the name patterns. For example, | |
88e1739c | 10221 | @smallexample |
7cd4527e | 10222 | gnatname ^-x "*_nt.ada"^/EXCLUDED_PATTERN=*_nt.ada^ "*.ada" |
88e1739c | 10223 | @end smallexample |
88e1739c | 10224 | @noindent |
7cd4527e AC |
10225 | will look for Ada units in all files with the @file{.ada} extension, |
10226 | except those whose names end with @file{_nt.ada}. | |
88e1739c | 10227 | |
7cd4527e | 10228 | @end table |
88e1739c | 10229 | |
7cd4527e AC |
10230 | @node Examples of gnatname Usage |
10231 | @section Examples of @code{gnatname} Usage | |
10232 | ||
10233 | @ifset vms | |
88e1739c | 10234 | @smallexample |
7cd4527e AC |
10235 | $ gnatname /CONFIG_FILE=[HOME.ME]NAMES.ADC /SOURCE_DIRS=SOURCES "[a-z]*.ada*" |
10236 | @end smallexample | |
10237 | @end ifset | |
10238 | ||
10239 | @ifclear vms | |
10240 | @smallexample | |
10241 | $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" | |
88e1739c | 10242 | @end smallexample |
7cd4527e | 10243 | @end ifclear |
88e1739c FW |
10244 | |
10245 | @noindent | |
7cd4527e AC |
10246 | In this example, the directory @file{^/home/me^[HOME.ME]^} must already exist |
10247 | and be writable. In addition, the directory | |
10248 | @file{^/home/me/sources^[HOME.ME.SOURCES]^} (specified by | |
10249 | @option{^-d sources^/SOURCE_DIRS=SOURCES^}) must exist and be readable. | |
10250 | ||
10251 | @ifclear vms | |
10252 | Note the optional spaces after @option{-c} and @option{-d}. | |
10253 | @end ifclear | |
88e1739c FW |
10254 | |
10255 | @smallexample | |
7cd4527e AC |
10256 | @ifclear vms |
10257 | $ gnatname -P/home/me/proj -x "*_nt_body.ada" | |
10258 | -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" | |
10259 | @end ifclear | |
10260 | @ifset vms | |
10261 | $ gnatname /PROJECT_FILE=[HOME.ME]PROJ | |
10262 | /EXCLUDED_PATTERN=*_nt_body.ada | |
10263 | /SOURCE_DIRS=(SOURCES,[SOURCES.PLUS]) | |
10264 | /DIRS_FILE=COMMON_DIRS.TXT "body_*" "spec_*" | |
10265 | @end ifset | |
88e1739c FW |
10266 | @end smallexample |
10267 | ||
7cd4527e AC |
10268 | Note that several switches @option{^-d^/SOURCE_DIRS^} may be used, |
10269 | even in conjunction with one or several switches | |
10270 | @option{^-D^/DIRS_FILE^}. Several Naming Patterns and one excluded pattern | |
10271 | are used in this example. | |
88e1739c | 10272 | |
88e1739c | 10273 | |
7cd4527e AC |
10274 | @c ***************************************** |
10275 | @c * G N A T P r o j e c t M a n a g e r * | |
10276 | @c ***************************************** | |
10277 | @node GNAT Project Manager | |
10278 | @chapter GNAT Project Manager | |
10279 | ||
10280 | @menu | |
10281 | * Introduction:: | |
10282 | * Examples of Project Files:: | |
10283 | * Project File Syntax:: | |
10284 | * Objects and Sources in Project Files:: | |
10285 | * Importing Projects:: | |
10286 | * Project Extension:: | |
10287 | * External References in Project Files:: | |
10288 | * Packages in Project Files:: | |
10289 | * Variables from Imported Projects:: | |
10290 | * Naming Schemes:: | |
10291 | * Library Projects:: | |
10292 | * Using Third-Party Libraries through Projects:: | |
10293 | * Stand-alone Library Projects:: | |
10294 | * Switches Related to Project Files:: | |
10295 | * Tools Supporting Project Files:: | |
10296 | * An Extended Example:: | |
10297 | * Project File Complete Syntax:: | |
10298 | @end menu | |
10299 | ||
10300 | @c **************** | |
10301 | @c * Introduction * | |
10302 | @c **************** | |
10303 | ||
10304 | @node Introduction | |
10305 | @section Introduction | |
88e1739c | 10306 | |
7cd4527e AC |
10307 | @noindent |
10308 | This chapter describes GNAT's @emph{Project Manager}, a facility that allows | |
10309 | you to manage complex builds involving a number of source files, directories, | |
10310 | and compilation options for different system configurations. In particular, | |
10311 | project files allow you to specify: | |
88e1739c | 10312 | @itemize @bullet |
7cd4527e AC |
10313 | @item |
10314 | The directory or set of directories containing the source files, and/or the | |
10315 | names of the specific source files themselves | |
10316 | @item | |
10317 | The directory in which the compiler's output | |
10318 | (@file{ALI} files, object files, tree files) is to be placed | |
10319 | @item | |
10320 | The directory in which the executable programs is to be placed | |
10321 | @item | |
10322 | ^Switch^Switch^ settings for any of the project-enabled tools | |
10323 | (@command{gnatmake}, compiler, binder, linker, @code{gnatls}, @code{gnatxref}, | |
10324 | @code{gnatfind}); you can apply these settings either globally or to individual | |
10325 | compilation units. | |
10326 | @item | |
10327 | The source files containing the main subprogram(s) to be built | |
10328 | @item | |
10329 | The source programming language(s) (currently Ada and/or C) | |
10330 | @item | |
10331 | Source file naming conventions; you can specify these either globally or for | |
10332 | individual compilation units | |
88e1739c FW |
10333 | @end itemize |
10334 | ||
7cd4527e AC |
10335 | @menu |
10336 | * Project Files:: | |
10337 | @end menu | |
10338 | ||
10339 | @node Project Files | |
10340 | @subsection Project Files | |
10341 | ||
88e1739c | 10342 | @noindent |
7cd4527e AC |
10343 | Project files are written in a syntax close to that of Ada, using familiar |
10344 | notions such as packages, context clauses, declarations, default values, | |
10345 | assignments, and inheritance. Finally, project files can be built | |
10346 | hierarchically from other project files, simplifying complex system | |
10347 | integration and project reuse. | |
10348 | ||
10349 | A @dfn{project} is a specific set of values for various compilation properties. | |
10350 | The settings for a given project are described by means of | |
10351 | a @dfn{project file}, which is a text file written in an Ada-like syntax. | |
10352 | Property values in project files are either strings or lists of strings. | |
10353 | Properties that are not explicitly set receive default values. A project | |
10354 | file may interrogate the values of @dfn{external variables} (user-defined | |
10355 | command-line switches or environment variables), and it may specify property | |
10356 | settings conditionally, based on the value of such variables. | |
88e1739c | 10357 | |
7cd4527e AC |
10358 | In simple cases, a project's source files depend only on other source files |
10359 | in the same project, or on the predefined libraries. (@emph{Dependence} is | |
10360 | used in | |
10361 | the Ada technical sense; as in one Ada unit @code{with}ing another.) However, | |
10362 | the Project Manager also allows more sophisticated arrangements, | |
10363 | where the source files in one project depend on source files in other | |
10364 | projects: | |
88e1739c | 10365 | @itemize @bullet |
7cd4527e AC |
10366 | @item |
10367 | One project can @emph{import} other projects containing needed source files. | |
10368 | @item | |
10369 | You can organize GNAT projects in a hierarchy: a @emph{child} project | |
10370 | can extend a @emph{parent} project, inheriting the parent's source files and | |
10371 | optionally overriding any of them with alternative versions | |
88e1739c FW |
10372 | @end itemize |
10373 | ||
10374 | @noindent | |
7cd4527e AC |
10375 | More generally, the Project Manager lets you structure large development |
10376 | efforts into hierarchical subsystems, where build decisions are delegated | |
10377 | to the subsystem level, and thus different compilation environments | |
10378 | (^switch^switch^ settings) used for different subsystems. | |
88e1739c | 10379 | |
7cd4527e AC |
10380 | The Project Manager is invoked through the |
10381 | @option{^-P^/PROJECT_FILE=^@emph{projectfile}} | |
10382 | switch to @command{gnatmake} or to the @command{^gnat^GNAT^} front driver. | |
10383 | @ifclear vms | |
10384 | There may be zero, one or more spaces between @option{-P} and | |
10385 | @option{@emph{projectfile}}. | |
10386 | @end ifclear | |
10387 | If you want to define (on the command line) an external variable that is | |
10388 | queried by the project file, you must use the | |
10389 | @option{^-X^/EXTERNAT_REFERENCE=^@emph{vbl}=@emph{value}} switch. | |
10390 | The Project Manager parses and interprets the project file, and drives the | |
10391 | invoked tool based on the project settings. | |
88e1739c | 10392 | |
7cd4527e AC |
10393 | The Project Manager supports a wide range of development strategies, |
10394 | for systems of all sizes. Here are some typical practices that are | |
10395 | easily handled: | |
10396 | @itemize @bullet | |
10397 | @item | |
10398 | Using a common set of source files, but generating object files in different | |
10399 | directories via different ^switch^switch^ settings | |
10400 | @item | |
10401 | Using a mostly-shared set of source files, but with different versions of | |
10402 | some unit or units | |
10403 | @end itemize | |
88e1739c FW |
10404 | |
10405 | @noindent | |
7cd4527e AC |
10406 | The destination of an executable can be controlled inside a project file |
10407 | using the @option{^-o^-o^} | |
10408 | ^switch^switch^. | |
10409 | In the absence of such a ^switch^switch^ either inside | |
10410 | the project file or on the command line, any executable files generated by | |
10411 | @command{gnatmake} are placed in the directory @code{Exec_Dir} specified | |
10412 | in the project file. If no @code{Exec_Dir} is specified, they will be placed | |
10413 | in the object directory of the project. | |
88e1739c | 10414 | |
7cd4527e AC |
10415 | You can use project files to achieve some of the effects of a source |
10416 | versioning system (for example, defining separate projects for | |
10417 | the different sets of sources that comprise different releases) but the | |
10418 | Project Manager is independent of any source configuration management tools | |
10419 | that might be used by the developers. | |
88e1739c | 10420 | |
7cd4527e AC |
10421 | The next section introduces the main features of GNAT's project facility |
10422 | through a sequence of examples; subsequent sections will present the syntax | |
10423 | and semantics in more detail. A more formal description of the project | |
10424 | facility appears in the GNAT Reference Manual. | |
88e1739c | 10425 | |
7cd4527e AC |
10426 | @c ***************************** |
10427 | @c * Examples of Project Files * | |
10428 | @c ***************************** | |
88e1739c | 10429 | |
7cd4527e AC |
10430 | @node Examples of Project Files |
10431 | @section Examples of Project Files | |
88e1739c | 10432 | @noindent |
7cd4527e AC |
10433 | This section illustrates some of the typical uses of project files and |
10434 | explains their basic structure and behavior. | |
88e1739c | 10435 | |
7cd4527e AC |
10436 | @menu |
10437 | * Common Sources with Different ^Switches^Switches^ and Directories:: | |
10438 | * Using External Variables:: | |
10439 | * Importing Other Projects:: | |
10440 | * Extending a Project:: | |
10441 | @end menu | |
88e1739c | 10442 | |
7cd4527e AC |
10443 | @node Common Sources with Different ^Switches^Switches^ and Directories |
10444 | @subsection Common Sources with Different ^Switches^Switches^ and Directories | |
88e1739c | 10445 | |
7cd4527e AC |
10446 | @menu |
10447 | * Source Files:: | |
10448 | * Specifying the Object Directory:: | |
10449 | * Specifying the Exec Directory:: | |
10450 | * Project File Packages:: | |
10451 | * Specifying ^Switch^Switch^ Settings:: | |
10452 | * Main Subprograms:: | |
10453 | * Executable File Names:: | |
10454 | * Source File Naming Conventions:: | |
10455 | * Source Language(s):: | |
10456 | @end menu | |
88e1739c FW |
10457 | |
10458 | @noindent | |
7cd4527e AC |
10459 | Suppose that the Ada source files @file{pack.ads}, @file{pack.adb}, and |
10460 | @file{proc.adb} are in the @file{/common} directory. The file | |
10461 | @file{proc.adb} contains an Ada main subprogram @code{Proc} that @code{with}s | |
10462 | package @code{Pack}. We want to compile these source files under two sets | |
10463 | of ^switches^switches^: | |
10464 | @itemize @bullet | |
10465 | @item | |
10466 | When debugging, we want to pass the @option{-g} switch to @command{gnatmake}, | |
10467 | and the @option{^-gnata^-gnata^}, | |
10468 | @option{^-gnato^-gnato^}, | |
10469 | and @option{^-gnatE^-gnatE^} switches to the | |
10470 | compiler; the compiler's output is to appear in @file{/common/debug} | |
10471 | @item | |
10472 | When preparing a release version, we want to pass the @option{^-O2^O2^} switch | |
10473 | to the compiler; the compiler's output is to appear in @file{/common/release} | |
10474 | @end itemize | |
88e1739c FW |
10475 | |
10476 | @noindent | |
7cd4527e AC |
10477 | The GNAT project files shown below, respectively @file{debug.gpr} and |
10478 | @file{release.gpr} in the @file{/common} directory, achieve these effects. | |
88e1739c | 10479 | |
7cd4527e AC |
10480 | Schematically: |
10481 | @smallexample | |
10482 | @group | |
10483 | ^/common^[COMMON]^ | |
10484 | debug.gpr | |
10485 | release.gpr | |
10486 | pack.ads | |
10487 | pack.adb | |
10488 | proc.adb | |
10489 | @end group | |
10490 | @group | |
10491 | ^/common/debug^[COMMON.DEBUG]^ | |
10492 | proc.ali, proc.o | |
10493 | pack.ali, pack.o | |
10494 | @end group | |
10495 | @group | |
10496 | ^/common/release^[COMMON.RELEASE]^ | |
10497 | proc.ali, proc.o | |
10498 | pack.ali, pack.o | |
10499 | @end group | |
10500 | @end smallexample | |
10501 | Here are the corresponding project files: | |
88e1739c | 10502 | |
7cd4527e AC |
10503 | @smallexample @c projectfile |
10504 | @group | |
10505 | project Debug is | |
10506 | for Object_Dir use "debug"; | |
10507 | for Main use ("proc"); | |
88e1739c | 10508 | |
7cd4527e AC |
10509 | package Builder is |
10510 | for ^Default_Switches^Default_Switches^ ("Ada") | |
10511 | use ("^-g^-g^"); | |
10512 | for Executable ("proc.adb") use "proc1"; | |
10513 | end Builder; | |
10514 | @end group | |
88e1739c | 10515 | |
7cd4527e AC |
10516 | @group |
10517 | package Compiler is | |
10518 | for ^Default_Switches^Default_Switches^ ("Ada") | |
10519 | use ("-fstack-check", | |
10520 | "^-gnata^-gnata^", | |
10521 | "^-gnato^-gnato^", | |
10522 | "^-gnatE^-gnatE^"); | |
10523 | end Compiler; | |
10524 | end Debug; | |
10525 | @end group | |
88e1739c FW |
10526 | @end smallexample |
10527 | ||
7cd4527e AC |
10528 | @smallexample @c projectfile |
10529 | @group | |
10530 | project Release is | |
10531 | for Object_Dir use "release"; | |
10532 | for Exec_Dir use "."; | |
10533 | for Main use ("proc"); | |
88e1739c | 10534 | |
7cd4527e AC |
10535 | package Compiler is |
10536 | for ^Default_Switches^Default_Switches^ ("Ada") | |
10537 | use ("^-O2^-O2^"); | |
10538 | end Compiler; | |
10539 | end Release; | |
10540 | @end group | |
10541 | @end smallexample | |
88e1739c | 10542 | |
7cd4527e AC |
10543 | @noindent |
10544 | The name of the project defined by @file{debug.gpr} is @code{"Debug"} (case | |
10545 | insensitive), and analogously the project defined by @file{release.gpr} is | |
10546 | @code{"Release"}. For consistency the file should have the same name as the | |
10547 | project, and the project file's extension should be @code{"gpr"}. These | |
10548 | conventions are not required, but a warning is issued if they are not followed. | |
88e1739c | 10549 | |
7cd4527e | 10550 | If the current directory is @file{^/temp^[TEMP]^}, then the command |
88e1739c | 10551 | @smallexample |
7cd4527e | 10552 | gnatmake ^-P/common/debug.gpr^/PROJECT_FILE=[COMMON]DEBUG^ |
88e1739c FW |
10553 | @end smallexample |
10554 | ||
10555 | @noindent | |
7cd4527e AC |
10556 | generates object and ALI files in @file{^/common/debug^[COMMON.DEBUG]^}, |
10557 | as well as the @code{^proc1^PROC1.EXE^} executable, | |
10558 | using the ^switch^switch^ settings defined in the project file. | |
88e1739c | 10559 | |
7cd4527e | 10560 | Likewise, the command |
88e1739c | 10561 | @smallexample |
7cd4527e | 10562 | gnatmake ^-P/common/release.gpr^/PROJECT_FILE=[COMMON]RELEASE^ |
88e1739c FW |
10563 | @end smallexample |
10564 | ||
10565 | @noindent | |
7cd4527e AC |
10566 | generates object and ALI files in @file{^/common/release^[COMMON.RELEASE]^}, |
10567 | and the @code{^proc^PROC.EXE^} | |
10568 | executable in @file{^/common^[COMMON]^}, | |
10569 | using the ^switch^switch^ settings from the project file. | |
88e1739c | 10570 | |
7cd4527e AC |
10571 | @node Source Files |
10572 | @unnumberedsubsubsec Source Files | |
88e1739c | 10573 | |
7cd4527e AC |
10574 | @noindent |
10575 | If a project file does not explicitly specify a set of source directories or | |
10576 | a set of source files, then by default the project's source files are the | |
10577 | Ada source files in the project file directory. Thus @file{pack.ads}, | |
10578 | @file{pack.adb}, and @file{proc.adb} are the source files for both projects. | |
88e1739c | 10579 | |
7cd4527e AC |
10580 | @node Specifying the Object Directory |
10581 | @unnumberedsubsubsec Specifying the Object Directory | |
88e1739c FW |
10582 | |
10583 | @noindent | |
7cd4527e AC |
10584 | Several project properties are modeled by Ada-style @emph{attributes}; |
10585 | a property is defined by supplying the equivalent of an Ada attribute | |
10586 | definition clause in the project file. | |
10587 | A project's object directory is another such a property; the corresponding | |
10588 | attribute is @code{Object_Dir}, and its value is also a string expression, | |
10589 | specified either as absolute or relative. In the later case, | |
10590 | it is relative to the project file directory. Thus the compiler's | |
10591 | output is directed to @file{^/common/debug^[COMMON.DEBUG]^} | |
10592 | (for the @code{Debug} project) | |
10593 | and to @file{^/common/release^[COMMON.RELEASE]^} | |
10594 | (for the @code{Release} project). | |
10595 | If @code{Object_Dir} is not specified, then the default is the project file | |
10596 | directory itself. | |
88e1739c | 10597 | |
7cd4527e AC |
10598 | @node Specifying the Exec Directory |
10599 | @unnumberedsubsubsec Specifying the Exec Directory | |
88e1739c | 10600 | |
7cd4527e AC |
10601 | @noindent |
10602 | A project's exec directory is another property; the corresponding | |
10603 | attribute is @code{Exec_Dir}, and its value is also a string expression, | |
10604 | either specified as relative or absolute. If @code{Exec_Dir} is not specified, | |
10605 | then the default is the object directory (which may also be the project file | |
10606 | directory if attribute @code{Object_Dir} is not specified). Thus the executable | |
10607 | is placed in @file{^/common/debug^[COMMON.DEBUG]^} | |
10608 | for the @code{Debug} project (attribute @code{Exec_Dir} not specified) | |
10609 | and in @file{^/common^[COMMON]^} for the @code{Release} project. | |
10610 | ||
10611 | @node Project File Packages | |
10612 | @unnumberedsubsubsec Project File Packages | |
88e1739c FW |
10613 | |
10614 | @noindent | |
7cd4527e AC |
10615 | A GNAT tool that is integrated with the Project Manager is modeled by a |
10616 | corresponding package in the project file. In the example above, | |
10617 | The @code{Debug} project defines the packages @code{Builder} | |
10618 | (for @command{gnatmake}) and @code{Compiler}; | |
10619 | the @code{Release} project defines only the @code{Compiler} package. | |
88e1739c | 10620 | |
7cd4527e AC |
10621 | The Ada-like package syntax is not to be taken literally. Although packages in |
10622 | project files bear a surface resemblance to packages in Ada source code, the | |
10623 | notation is simply a way to convey a grouping of properties for a named | |
10624 | entity. Indeed, the package names permitted in project files are restricted | |
10625 | to a predefined set, corresponding to the project-aware tools, and the contents | |
10626 | of packages are limited to a small set of constructs. | |
10627 | The packages in the example above contain attribute definitions. | |
88e1739c | 10628 | |
7cd4527e AC |
10629 | @node Specifying ^Switch^Switch^ Settings |
10630 | @unnumberedsubsubsec Specifying ^Switch^Switch^ Settings | |
88e1739c FW |
10631 | |
10632 | @noindent | |
7cd4527e AC |
10633 | ^Switch^Switch^ settings for a project-aware tool can be specified through |
10634 | attributes in the package that corresponds to the tool. | |
10635 | The example above illustrates one of the relevant attributes, | |
10636 | @code{^Default_Switches^Default_Switches^}, which is defined in packages | |
10637 | in both project files. | |
10638 | Unlike simple attributes like @code{Source_Dirs}, | |
10639 | @code{^Default_Switches^Default_Switches^} is | |
10640 | known as an @emph{associative array}. When you define this attribute, you must | |
10641 | supply an ``index'' (a literal string), and the effect of the attribute | |
10642 | definition is to set the value of the array at the specified index. | |
10643 | For the @code{^Default_Switches^Default_Switches^} attribute, | |
10644 | the index is a programming language (in our case, Ada), | |
10645 | and the value specified (after @code{use}) must be a list | |
10646 | of string expressions. | |
88e1739c | 10647 | |
7cd4527e AC |
10648 | The attributes permitted in project files are restricted to a predefined set. |
10649 | Some may appear at project level, others in packages. | |
10650 | For any attribute that is an associative array, the index must always be a | |
10651 | literal string, but the restrictions on this string (e.g., a file name or a | |
10652 | language name) depend on the individual attribute. | |
10653 | Also depending on the attribute, its specified value will need to be either a | |
10654 | string or a string list. | |
88e1739c | 10655 | |
7cd4527e AC |
10656 | In the @code{Debug} project, we set the switches for two tools, |
10657 | @command{gnatmake} and the compiler, and thus we include the two corresponding | |
10658 | packages; each package defines the @code{^Default_Switches^Default_Switches^} | |
10659 | attribute with index @code{"Ada"}. | |
10660 | Note that the package corresponding to | |
10661 | @command{gnatmake} is named @code{Builder}. The @code{Release} project is | |
10662 | similar, but only includes the @code{Compiler} package. | |
88e1739c | 10663 | |
7cd4527e AC |
10664 | In project @code{Debug} above, the ^switches^switches^ starting with |
10665 | @option{-gnat} that are specified in package @code{Compiler} | |
10666 | could have been placed in package @code{Builder}, since @command{gnatmake} | |
10667 | transmits all such ^switches^switches^ to the compiler. | |
88e1739c | 10668 | |
7cd4527e AC |
10669 | @node Main Subprograms |
10670 | @unnumberedsubsubsec Main Subprograms | |
88e1739c | 10671 | |
7cd4527e AC |
10672 | @noindent |
10673 | One of the specifiable properties of a project is a list of files that contain | |
10674 | main subprograms. This property is captured in the @code{Main} attribute, | |
10675 | whose value is a list of strings. If a project defines the @code{Main} | |
10676 | attribute, it is not necessary to identify the main subprogram(s) when | |
10677 | invoking @command{gnatmake} (see @ref{gnatmake and Project Files}). | |
88e1739c | 10678 | |
7cd4527e AC |
10679 | @node Executable File Names |
10680 | @unnumberedsubsubsec Executable File Names | |
88e1739c | 10681 | |
7cd4527e AC |
10682 | @noindent |
10683 | By default, the executable file name corresponding to a main source is | |
10684 | deducted from the main source file name. Through the attributes | |
10685 | @code{Executable} and @code{Executable_Suffix} of package @code{Builder}, | |
10686 | it is possible to change this default. | |
10687 | In project @code{Debug} above, the executable file name | |
10688 | for main source @file{^proc.adb^PROC.ADB^} is | |
10689 | @file{^proc1^PROC1.EXE^}. | |
10690 | Attribute @code{Executable_Suffix}, when specified, may change the suffix | |
10691 | of the the executable files, when no attribute @code{Executable} applies: | |
10692 | its value replace the platform-specific executable suffix. | |
10693 | Attributes @code{Executable} and @code{Executable_Suffix} are the only ways to | |
10694 | specify a non default executable file name when several mains are built at once | |
10695 | in a single @command{gnatmake} command. | |
88e1739c | 10696 | |
7cd4527e AC |
10697 | @node Source File Naming Conventions |
10698 | @unnumberedsubsubsec Source File Naming Conventions | |
88e1739c | 10699 | |
7cd4527e AC |
10700 | @noindent |
10701 | Since the project files above do not specify any source file naming | |
10702 | conventions, the GNAT defaults are used. The mechanism for defining source | |
10703 | file naming conventions -- a package named @code{Naming} -- | |
10704 | is described below (@pxref{Naming Schemes}). | |
88e1739c | 10705 | |
7cd4527e AC |
10706 | @node Source Language(s) |
10707 | @unnumberedsubsubsec Source Language(s) | |
88e1739c FW |
10708 | |
10709 | @noindent | |
7cd4527e AC |
10710 | Since the project files do not specify a @code{Languages} attribute, by |
10711 | default the GNAT tools assume that the language of the project file is Ada. | |
10712 | More generally, a project can comprise source files | |
10713 | in Ada, C, and/or other languages. | |
88e1739c | 10714 | |
7cd4527e AC |
10715 | @node Using External Variables |
10716 | @subsection Using External Variables | |
88e1739c FW |
10717 | |
10718 | @noindent | |
7cd4527e AC |
10719 | Instead of supplying different project files for debug and release, we can |
10720 | define a single project file that queries an external variable (set either | |
10721 | on the command line or via an ^environment variable^logical name^) in order to | |
10722 | conditionally define the appropriate settings. Again, assume that the | |
10723 | source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are | |
10724 | located in directory @file{^/common^[COMMON]^}. The following project file, | |
10725 | @file{build.gpr}, queries the external variable named @code{STYLE} and | |
10726 | defines an object directory and ^switch^switch^ settings based on whether | |
10727 | the value is @code{"deb"} (debug) or @code{"rel"} (release), and where | |
10728 | the default is @code{"deb"}. | |
88e1739c | 10729 | |
7cd4527e AC |
10730 | @smallexample @c projectfile |
10731 | @group | |
10732 | project Build is | |
10733 | for Main use ("proc"); | |
88e1739c | 10734 | |
7cd4527e AC |
10735 | type Style_Type is ("deb", "rel"); |
10736 | Style : Style_Type := external ("STYLE", "deb"); | |
88e1739c | 10737 | |
7cd4527e AC |
10738 | case Style is |
10739 | when "deb" => | |
10740 | for Object_Dir use "debug"; | |
88e1739c | 10741 | |
7cd4527e AC |
10742 | when "rel" => |
10743 | for Object_Dir use "release"; | |
10744 | for Exec_Dir use "."; | |
10745 | end case; | |
10746 | @end group | |
88e1739c | 10747 | |
7cd4527e AC |
10748 | @group |
10749 | package Builder is | |
88e1739c | 10750 | |
7cd4527e AC |
10751 | case Style is |
10752 | when "deb" => | |
10753 | for ^Default_Switches^Default_Switches^ ("Ada") | |
10754 | use ("^-g^-g^"); | |
10755 | for Executable ("proc") use "proc1"; | |
10756 | end case; | |
88e1739c | 10757 | |
7cd4527e AC |
10758 | end Builder; |
10759 | @end group | |
88e1739c | 10760 | |
7cd4527e AC |
10761 | @group |
10762 | package Compiler is | |
88e1739c | 10763 | |
7cd4527e AC |
10764 | case Style is |
10765 | when "deb" => | |
10766 | for ^Default_Switches^Default_Switches^ ("Ada") | |
10767 | use ("^-gnata^-gnata^", | |
10768 | "^-gnato^-gnato^", | |
10769 | "^-gnatE^-gnatE^"); | |
88e1739c | 10770 | |
7cd4527e AC |
10771 | when "rel" => |
10772 | for ^Default_Switches^Default_Switches^ ("Ada") | |
10773 | use ("^-O2^-O2^"); | |
10774 | end case; | |
88e1739c | 10775 | |
7cd4527e | 10776 | end Compiler; |
88e1739c | 10777 | |
7cd4527e AC |
10778 | end Build; |
10779 | @end group | |
10780 | @end smallexample | |
88e1739c FW |
10781 | |
10782 | @noindent | |
7cd4527e AC |
10783 | @code{Style_Type} is an example of a @emph{string type}, which is the project |
10784 | file analog of an Ada enumeration type but whose components are string literals | |
10785 | rather than identifiers. @code{Style} is declared as a variable of this type. | |
88e1739c | 10786 | |
7cd4527e AC |
10787 | The form @code{external("STYLE", "deb")} is known as an |
10788 | @emph{external reference}; its first argument is the name of an | |
10789 | @emph{external variable}, and the second argument is a default value to be | |
10790 | used if the external variable doesn't exist. You can define an external | |
10791 | variable on the command line via the @option{^-X^/EXTERNAL_REFERENCE^} switch, | |
10792 | or you can use ^an environment variable^a logical name^ | |
10793 | as an external variable. | |
88e1739c | 10794 | |
7cd4527e AC |
10795 | Each @code{case} construct is expanded by the Project Manager based on the |
10796 | value of @code{Style}. Thus the command | |
10797 | @ifclear vms | |
10798 | @smallexample | |
10799 | gnatmake -P/common/build.gpr -XSTYLE=deb | |
10800 | @end smallexample | |
10801 | @end ifclear | |
88e1739c | 10802 | |
7cd4527e | 10803 | @ifset vms |
88e1739c | 10804 | @smallexample |
7cd4527e | 10805 | gnatmake /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=deb |
88e1739c | 10806 | @end smallexample |
7cd4527e | 10807 | @end ifset |
88e1739c FW |
10808 | |
10809 | @noindent | |
7cd4527e AC |
10810 | is equivalent to the @command{gnatmake} invocation using the project file |
10811 | @file{debug.gpr} in the earlier example. So is the command | |
88e1739c | 10812 | @smallexample |
7cd4527e | 10813 | gnatmake ^-P/common/build.gpr^/PROJECT_FILE=[COMMON]BUILD.GPR^ |
88e1739c FW |
10814 | @end smallexample |
10815 | ||
10816 | @noindent | |
7cd4527e AC |
10817 | since @code{"deb"} is the default for @code{STYLE}. |
10818 | ||
10819 | Analogously, | |
88e1739c | 10820 | |
7cd4527e | 10821 | @ifclear vms |
88e1739c | 10822 | @smallexample |
7cd4527e | 10823 | gnatmake -P/common/build.gpr -XSTYLE=rel |
88e1739c | 10824 | @end smallexample |
7cd4527e | 10825 | @end ifclear |
88e1739c | 10826 | |
7cd4527e | 10827 | @ifset vms |
88e1739c | 10828 | @smallexample |
7cd4527e | 10829 | GNAT MAKE /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=rel |
88e1739c | 10830 | @end smallexample |
7cd4527e | 10831 | @end ifset |
88e1739c FW |
10832 | |
10833 | @noindent | |
7cd4527e AC |
10834 | is equivalent to the @command{gnatmake} invocation using the project file |
10835 | @file{release.gpr} in the earlier example. | |
88e1739c | 10836 | |
7cd4527e AC |
10837 | @node Importing Other Projects |
10838 | @subsection Importing Other Projects | |
88e1739c FW |
10839 | |
10840 | @noindent | |
7cd4527e AC |
10841 | A compilation unit in a source file in one project may depend on compilation |
10842 | units in source files in other projects. To compile this unit under | |
10843 | control of a project file, the | |
10844 | dependent project must @emph{import} the projects containing the needed source | |
10845 | files. | |
10846 | This effect is obtained using syntax similar to an Ada @code{with} clause, | |
10847 | but where @code{with}ed entities are strings that denote project files. | |
88e1739c | 10848 | |
7cd4527e AC |
10849 | As an example, suppose that the two projects @code{GUI_Proj} and |
10850 | @code{Comm_Proj} are defined in the project files @file{gui_proj.gpr} and | |
10851 | @file{comm_proj.gpr} in directories @file{^/gui^[GUI]^} | |
10852 | and @file{^/comm^[COMM]^}, respectively. | |
10853 | Suppose that the source files for @code{GUI_Proj} are | |
10854 | @file{gui.ads} and @file{gui.adb}, and that the source files for | |
10855 | @code{Comm_Proj} are @file{comm.ads} and @file{comm.adb}, where each set of | |
10856 | files is located in its respective project file directory. Schematically: | |
88e1739c FW |
10857 | |
10858 | @smallexample | |
7cd4527e AC |
10859 | @group |
10860 | ^/gui^[GUI]^ | |
10861 | gui_proj.gpr | |
10862 | gui.ads | |
10863 | gui.adb | |
10864 | @end group | |
10865 | ||
10866 | @group | |
10867 | ^/comm^[COMM]^ | |
10868 | comm_proj.gpr | |
10869 | comm.ads | |
10870 | comm.adb | |
10871 | @end group | |
88e1739c FW |
10872 | @end smallexample |
10873 | ||
10874 | @noindent | |
7cd4527e AC |
10875 | We want to develop an application in directory @file{^/app^[APP]^} that |
10876 | @code{with} the packages @code{GUI} and @code{Comm}, using the properties of | |
10877 | the corresponding project files (e.g. the ^switch^switch^ settings | |
10878 | and object directory). | |
10879 | Skeletal code for a main procedure might be something like the following: | |
88e1739c | 10880 | |
7cd4527e AC |
10881 | @smallexample @c ada |
10882 | @group | |
10883 | with GUI, Comm; | |
10884 | procedure App_Main is | |
10885 | ... | |
10886 | begin | |
10887 | ... | |
10888 | end App_Main; | |
10889 | @end group | |
88e1739c FW |
10890 | @end smallexample |
10891 | ||
10892 | @noindent | |
7cd4527e AC |
10893 | Here is a project file, @file{app_proj.gpr}, that achieves the desired |
10894 | effect: | |
88e1739c | 10895 | |
7cd4527e AC |
10896 | @smallexample @c projectfile |
10897 | @group | |
10898 | with "/gui/gui_proj", "/comm/comm_proj"; | |
10899 | project App_Proj is | |
10900 | for Main use ("app_main"); | |
10901 | end App_Proj; | |
10902 | @end group | |
10903 | @end smallexample | |
88e1739c | 10904 | |
7cd4527e AC |
10905 | @noindent |
10906 | Building an executable is achieved through the command: | |
88e1739c | 10907 | @smallexample |
7cd4527e | 10908 | gnatmake ^-P/app/app_proj^/PROJECT_FILE=[APP]APP_PROJ^ |
88e1739c | 10909 | @end smallexample |
88e1739c | 10910 | @noindent |
7cd4527e AC |
10911 | which will generate the @code{^app_main^APP_MAIN.EXE^} executable |
10912 | in the directory where @file{app_proj.gpr} resides. | |
88e1739c | 10913 | |
7cd4527e AC |
10914 | If an imported project file uses the standard extension (@code{^gpr^GPR^}) then |
10915 | (as illustrated above) the @code{with} clause can omit the extension. | |
88e1739c | 10916 | |
7cd4527e AC |
10917 | Our example specified an absolute path for each imported project file. |
10918 | Alternatively, the directory name of an imported object can be omitted | |
10919 | if either | |
10920 | @itemize @bullet | |
10921 | @item | |
10922 | The imported project file is in the same directory as the importing project | |
10923 | file, or | |
10924 | @item | |
10925 | You have defined ^an environment variable^a logical name^ | |
10926 | that includes the directory containing | |
10927 | the needed project file. The syntax of @code{ADA_PROJECT_PATH} is the same as | |
10928 | the syntax of @code{ADA_INCLUDE_PATH} and @code{ADA_OBJECTS_PATH}: a list of | |
10929 | directory names separated by colons (semicolons on Windows). | |
10930 | @end itemize | |
88e1739c FW |
10931 | |
10932 | @noindent | |
7cd4527e AC |
10933 | Thus, if we define @code{ADA_PROJECT_PATH} to include @file{^/gui^[GUI]^} and |
10934 | @file{^/comm^[COMM]^}, then our project file @file{app_proj.gpr} can be written | |
10935 | as follows: | |
88e1739c | 10936 | |
7cd4527e | 10937 | @smallexample @c projectfile |
88e1739c | 10938 | @group |
7cd4527e AC |
10939 | with "gui_proj", "comm_proj"; |
10940 | project App_Proj is | |
10941 | for Main use ("app_main"); | |
10942 | end App_Proj; | |
88e1739c FW |
10943 | @end group |
10944 | @end smallexample | |
10945 | ||
10946 | @noindent | |
7cd4527e AC |
10947 | Importing other projects can create ambiguities. |
10948 | For example, the same unit might be present in different imported projects, or | |
10949 | it might be present in both the importing project and in an imported project. | |
10950 | Both of these conditions are errors. Note that in the current version of | |
10951 | the Project Manager, it is illegal to have an ambiguous unit even if the | |
10952 | unit is never referenced by the importing project. This restriction may be | |
10953 | relaxed in a future release. | |
88e1739c | 10954 | |
7cd4527e AC |
10955 | @node Extending a Project |
10956 | @subsection Extending a Project | |
88e1739c FW |
10957 | |
10958 | @noindent | |
7cd4527e AC |
10959 | In large software systems it is common to have multiple |
10960 | implementations of a common interface; in Ada terms, multiple versions of a | |
10961 | package body for the same specification. For example, one implementation | |
10962 | might be safe for use in tasking programs, while another might only be used | |
10963 | in sequential applications. This can be modeled in GNAT using the concept | |
10964 | of @emph{project extension}. If one project (the ``child'') @emph{extends} | |
10965 | another project (the ``parent'') then by default all source files of the | |
10966 | parent project are inherited by the child, but the child project can | |
10967 | override any of the parent's source files with new versions, and can also | |
10968 | add new files. This facility is the project analog of a type extension in | |
10969 | Object-Oriented Programming. Project hierarchies are permitted (a child | |
10970 | project may be the parent of yet another project), and a project that | |
10971 | inherits one project can also import other projects. | |
10972 | ||
10973 | As an example, suppose that directory @file{^/seq^[SEQ]^} contains the project | |
10974 | file @file{seq_proj.gpr} as well as the source files @file{pack.ads}, | |
10975 | @file{pack.adb}, and @file{proc.adb}: | |
88e1739c FW |
10976 | |
10977 | @smallexample | |
7cd4527e AC |
10978 | @group |
10979 | ^/seq^[SEQ]^ | |
10980 | pack.ads | |
10981 | pack.adb | |
10982 | proc.adb | |
10983 | seq_proj.gpr | |
10984 | @end group | |
88e1739c FW |
10985 | @end smallexample |
10986 | ||
10987 | @noindent | |
7cd4527e AC |
10988 | Note that the project file can simply be empty (that is, no attribute or |
10989 | package is defined): | |
88e1739c | 10990 | |
7cd4527e AC |
10991 | @smallexample @c projectfile |
10992 | @group | |
10993 | project Seq_Proj is | |
10994 | end Seq_Proj; | |
10995 | @end group | |
10996 | @end smallexample | |
88e1739c FW |
10997 | |
10998 | @noindent | |
7cd4527e AC |
10999 | implying that its source files are all the Ada source files in the project |
11000 | directory. | |
11001 | ||
11002 | Suppose we want to supply an alternate version of @file{pack.adb}, in | |
11003 | directory @file{^/tasking^[TASKING]^}, but use the existing versions of | |
11004 | @file{pack.ads} and @file{proc.adb}. We can define a project | |
11005 | @code{Tasking_Proj} that inherits @code{Seq_Proj}: | |
88e1739c FW |
11006 | |
11007 | @smallexample | |
7cd4527e AC |
11008 | @group |
11009 | ^/tasking^[TASKING]^ | |
11010 | pack.adb | |
11011 | tasking_proj.gpr | |
11012 | @end group | |
11013 | ||
11014 | @group | |
11015 | project Tasking_Proj extends "/seq/seq_proj" is | |
11016 | end Tasking_Proj; | |
11017 | @end group | |
88e1739c FW |
11018 | @end smallexample |
11019 | ||
11020 | @noindent | |
7cd4527e AC |
11021 | The version of @file{pack.adb} used in a build depends on which project file |
11022 | is specified. | |
88e1739c | 11023 | |
7cd4527e AC |
11024 | Note that we could have obtained the desired behavior using project import |
11025 | rather than project inheritance; a @code{base} project would contain the | |
11026 | sources for @file{pack.ads} and @file{proc.adb}, a sequential project would | |
11027 | import @code{base} and add @file{pack.adb}, and likewise a tasking project | |
11028 | would import @code{base} and add a different version of @file{pack.adb}. The | |
11029 | choice depends on whether other sources in the original project need to be | |
11030 | overridden. If they do, then project extension is necessary, otherwise, | |
11031 | importing is sufficient. | |
88e1739c | 11032 | |
7cd4527e AC |
11033 | @noindent |
11034 | In a project file that extends another project file, it is possible to | |
11035 | indicate that an inherited source is not part of the sources of the extending | |
11036 | project. This is necessary sometimes when a package spec has been overloaded | |
11037 | and no longer requires a body: in this case, it is necessary to indicate that | |
11038 | the inherited body is not part of the sources of the project, otherwise there | |
11039 | will be a compilation error when compiling the spec. | |
88e1739c | 11040 | |
7cd4527e AC |
11041 | For that purpose, the attribute @code{Locally_Removed_Files} is used. |
11042 | Its value is a string list: a list of file names. | |
88e1739c | 11043 | |
7cd4527e AC |
11044 | @smallexample @c @projectfile |
11045 | project B extends "a" is | |
11046 | for Source_Files use ("pkg.ads"); | |
11047 | -- New spec of Pkg does not need a completion | |
11048 | for Locally_Removed_Files use ("pkg.adb"); | |
11049 | end B; | |
11050 | @end smallexample | |
88e1739c | 11051 | |
7cd4527e AC |
11052 | Attribute @code{Locally_Removed_Files} may also be used to check if a source |
11053 | is still needed: if it is possible to build using @code{gnatmake} when such | |
11054 | a source is put in attribute @code{Locally_Removed_Files} of a project P, then | |
11055 | it is possible to remove the source completely from a system that includes | |
11056 | project P. | |
88e1739c | 11057 | |
7cd4527e AC |
11058 | @c *********************** |
11059 | @c * Project File Syntax * | |
11060 | @c *********************** | |
88e1739c | 11061 | |
7cd4527e AC |
11062 | @node Project File Syntax |
11063 | @section Project File Syntax | |
88e1739c | 11064 | |
7cd4527e AC |
11065 | @menu |
11066 | * Basic Syntax:: | |
11067 | * Packages:: | |
11068 | * Expressions:: | |
11069 | * String Types:: | |
11070 | * Variables:: | |
11071 | * Attributes:: | |
11072 | * Associative Array Attributes:: | |
11073 | * case Constructions:: | |
11074 | @end menu | |
88e1739c FW |
11075 | |
11076 | @noindent | |
7cd4527e | 11077 | This section describes the structure of project files. |
88e1739c | 11078 | |
7cd4527e AC |
11079 | A project may be an @emph{independent project}, entirely defined by a single |
11080 | project file. Any Ada source file in an independent project depends only | |
11081 | on the predefined library and other Ada source files in the same project. | |
88e1739c | 11082 | |
7cd4527e AC |
11083 | @noindent |
11084 | A project may also @dfn{depend on} other projects, in either or both of | |
11085 | the following ways: | |
88e1739c | 11086 | @itemize @bullet |
7cd4527e AC |
11087 | @item It may import any number of projects |
11088 | @item It may extend at most one other project | |
88e1739c FW |
11089 | @end itemize |
11090 | ||
11091 | @noindent | |
7cd4527e AC |
11092 | The dependence relation is a directed acyclic graph (the subgraph reflecting |
11093 | the ``extends'' relation is a tree). | |
88e1739c | 11094 | |
7cd4527e AC |
11095 | A project's @dfn{immediate sources} are the source files directly defined by |
11096 | that project, either implicitly by residing in the project file's directory, | |
11097 | or explicitly through any of the source-related attributes described below. | |
11098 | More generally, a project @var{proj}'s @dfn{sources} are the immediate sources | |
11099 | of @var{proj} together with the immediate sources (unless overridden) of any | |
11100 | project on which @var{proj} depends (either directly or indirectly). | |
88e1739c | 11101 | |
7cd4527e AC |
11102 | @node Basic Syntax |
11103 | @subsection Basic Syntax | |
88e1739c | 11104 | |
7cd4527e AC |
11105 | @noindent |
11106 | As seen in the earlier examples, project files have an Ada-like syntax. | |
11107 | The minimal project file is: | |
11108 | @smallexample @c projectfile | |
88e1739c | 11109 | @group |
7cd4527e AC |
11110 | project Empty is |
11111 | ||
11112 | end Empty; | |
88e1739c FW |
11113 | @end group |
11114 | @end smallexample | |
11115 | ||
7cd4527e AC |
11116 | @noindent |
11117 | The identifier @code{Empty} is the name of the project. | |
11118 | This project name must be present after the reserved | |
11119 | word @code{end} at the end of the project file, followed by a semi-colon. | |
88e1739c | 11120 | |
7cd4527e AC |
11121 | Any name in a project file, such as the project name or a variable name, |
11122 | has the same syntax as an Ada identifier. | |
88e1739c | 11123 | |
7cd4527e AC |
11124 | The reserved words of project files are the Ada reserved words plus |
11125 | @code{extends}, @code{external}, and @code{project}. Note that the only Ada | |
11126 | reserved words currently used in project file syntax are: | |
88e1739c | 11127 | |
7cd4527e AC |
11128 | @itemize @bullet |
11129 | @item | |
11130 | @code{case} | |
11131 | @item | |
11132 | @code{end} | |
11133 | @item | |
11134 | @code{for} | |
11135 | @item | |
11136 | @code{is} | |
11137 | @item | |
11138 | @code{others} | |
11139 | @item | |
11140 | @code{package} | |
11141 | @item | |
11142 | @code{renames} | |
11143 | @item | |
11144 | @code{type} | |
11145 | @item | |
11146 | @code{use} | |
11147 | @item | |
11148 | @code{when} | |
11149 | @item | |
11150 | @code{with} | |
11151 | @end itemize | |
88e1739c FW |
11152 | |
11153 | @noindent | |
7cd4527e AC |
11154 | Comments in project files have the same syntax as in Ada, two consecutives |
11155 | hyphens through the end of the line. | |
88e1739c | 11156 | |
7cd4527e AC |
11157 | @node Packages |
11158 | @subsection Packages | |
88e1739c | 11159 | |
7cd4527e AC |
11160 | @noindent |
11161 | A project file may contain @emph{packages}. The name of a package must be one | |
11162 | of the identifiers from the following list. A package | |
11163 | with a given name may only appear once in a project file. Package names are | |
11164 | case insensitive. The following package names are legal: | |
88e1739c | 11165 | |
7cd4527e AC |
11166 | @itemize @bullet |
11167 | @item | |
11168 | @code{Naming} | |
11169 | @item | |
11170 | @code{Builder} | |
11171 | @item | |
11172 | @code{Compiler} | |
11173 | @item | |
11174 | @code{Binder} | |
11175 | @item | |
11176 | @code{Linker} | |
11177 | @item | |
11178 | @code{Finder} | |
11179 | @item | |
11180 | @code{Cross_Reference} | |
11181 | @item | |
11182 | @code{Eliminate} | |
11183 | @item | |
11184 | @code{gnatls} | |
11185 | @item | |
11186 | @code{gnatstub} | |
11187 | @item | |
11188 | @code{IDE} | |
11189 | @end itemize | |
88e1739c | 11190 | |
7cd4527e AC |
11191 | @noindent |
11192 | In its simplest form, a package may be empty: | |
11193 | ||
11194 | @smallexample @c projectfile | |
88e1739c | 11195 | @group |
7cd4527e AC |
11196 | project Simple is |
11197 | package Builder is | |
11198 | end Builder; | |
11199 | end Simple; | |
88e1739c FW |
11200 | @end group |
11201 | @end smallexample | |
11202 | ||
11203 | @noindent | |
7cd4527e AC |
11204 | A package may contain @emph{attribute declarations}, |
11205 | @emph{variable declarations} and @emph{case constructions}, as will be | |
11206 | described below. | |
88e1739c | 11207 | |
7cd4527e AC |
11208 | When there is ambiguity between a project name and a package name, |
11209 | the name always designates the project. To avoid possible confusion, it is | |
11210 | always a good idea to avoid naming a project with one of the | |
11211 | names allowed for packages or any name that starts with @code{gnat}. | |
88e1739c | 11212 | |
7cd4527e AC |
11213 | @node Expressions |
11214 | @subsection Expressions | |
88e1739c FW |
11215 | |
11216 | @noindent | |
7cd4527e AC |
11217 | An @emph{expression} is either a @emph{string expression} or a |
11218 | @emph{string list expression}. | |
88e1739c | 11219 | |
7cd4527e AC |
11220 | A @emph{string expression} is either a @emph{simple string expression} or a |
11221 | @emph{compound string expression}. | |
88e1739c | 11222 | |
7cd4527e AC |
11223 | A @emph{simple string expression} is one of the following: |
11224 | @itemize @bullet | |
11225 | @item A literal string; e.g.@code{"comm/my_proj.gpr"} | |
11226 | @item A string-valued variable reference (see @ref{Variables}) | |
11227 | @item A string-valued attribute reference (see @ref{Attributes}) | |
11228 | @item An external reference (see @ref{External References in Project Files}) | |
11229 | @end itemize | |
88e1739c | 11230 | |
7cd4527e AC |
11231 | @noindent |
11232 | A @emph{compound string expression} is a concatenation of string expressions, | |
11233 | using the operator @code{"&"} | |
11234 | @smallexample | |
11235 | Path & "/" & File_Name & ".ads" | |
88e1739c FW |
11236 | @end smallexample |
11237 | ||
11238 | @noindent | |
7cd4527e AC |
11239 | A @emph{string list expression} is either a |
11240 | @emph{simple string list expression} or a | |
11241 | @emph{compound string list expression}. | |
88e1739c | 11242 | |
7cd4527e | 11243 | A @emph{simple string list expression} is one of the following: |
88e1739c | 11244 | @itemize @bullet |
7cd4527e AC |
11245 | @item A parenthesized list of zero or more string expressions, |
11246 | separated by commas | |
11247 | @smallexample | |
11248 | File_Names := (File_Name, "gnat.adc", File_Name & ".orig"); | |
11249 | Empty_List := (); | |
11250 | @end smallexample | |
11251 | @item A string list-valued variable reference | |
11252 | @item A string list-valued attribute reference | |
88e1739c FW |
11253 | @end itemize |
11254 | ||
88e1739c | 11255 | @noindent |
7cd4527e AC |
11256 | A @emph{compound string list expression} is the concatenation (using |
11257 | @code{"&"}) of a simple string list expression and an expression. Note that | |
11258 | each term in a compound string list expression, except the first, may be | |
11259 | either a string expression or a string list expression. | |
88e1739c | 11260 | |
7cd4527e | 11261 | @smallexample @c projectfile |
88e1739c | 11262 | @group |
7cd4527e AC |
11263 | File_Name_List := () & File_Name; -- One string in this list |
11264 | Extended_File_Name_List := File_Name_List & (File_Name & ".orig"); | |
11265 | -- Two strings | |
11266 | Big_List := File_Name_List & Extended_File_Name_List; | |
11267 | -- Concatenation of two string lists: three strings | |
11268 | Illegal_List := "gnat.adc" & Extended_File_Name_List; | |
11269 | -- Illegal: must start with a string list | |
88e1739c FW |
11270 | @end group |
11271 | @end smallexample | |
11272 | ||
7cd4527e AC |
11273 | @node String Types |
11274 | @subsection String Types | |
11275 | ||
88e1739c | 11276 | @noindent |
7cd4527e AC |
11277 | A @emph{string type declaration} introduces a discrete set of string literals. |
11278 | If a string variable is declared to have this type, its value | |
11279 | is restricted to the given set of literals. | |
88e1739c | 11280 | |
7cd4527e | 11281 | Here is an example of a string type declaration: |
88e1739c | 11282 | |
7cd4527e AC |
11283 | @smallexample @c projectfile |
11284 | type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS"); | |
11285 | @end smallexample | |
88e1739c FW |
11286 | |
11287 | @noindent | |
7cd4527e AC |
11288 | Variables of a string type are called @emph{typed variables}; all other |
11289 | variables are called @emph{untyped variables}. Typed variables are | |
11290 | particularly useful in @code{case} constructions, to support conditional | |
11291 | attribute declarations. | |
11292 | (see @ref{case Constructions}). | |
88e1739c | 11293 | |
7cd4527e AC |
11294 | The string literals in the list are case sensitive and must all be different. |
11295 | They may include any graphic characters allowed in Ada, including spaces. | |
88e1739c | 11296 | |
7cd4527e | 11297 | A string type may only be declared at the project level, not inside a package. |
88e1739c | 11298 | |
7cd4527e AC |
11299 | A string type may be referenced by its name if it has been declared in the same |
11300 | project file, or by an expanded name whose prefix is the name of the project | |
11301 | in which it is declared. | |
88e1739c | 11302 | |
7cd4527e AC |
11303 | @node Variables |
11304 | @subsection Variables | |
88e1739c | 11305 | |
88e1739c | 11306 | @noindent |
7cd4527e AC |
11307 | A variable may be declared at the project file level, or within a package. |
11308 | Here are some examples of variable declarations: | |
88e1739c | 11309 | |
7cd4527e AC |
11310 | @smallexample @c projectfile |
11311 | @group | |
11312 | This_OS : OS := external ("OS"); -- a typed variable declaration | |
11313 | That_OS := "GNU/Linux"; -- an untyped variable declaration | |
11314 | @end group | |
11315 | @end smallexample | |
88e1739c | 11316 | |
88e1739c | 11317 | @noindent |
7cd4527e AC |
11318 | The syntax of a @emph{typed variable declaration} is identical to the Ada |
11319 | syntax for an object declaration. By contrast, the syntax of an untyped | |
11320 | variable declaration is identical to an Ada assignment statement. In fact, | |
11321 | variable declarations in project files have some of the characteristics of | |
11322 | an assignment, in that successive declarations for the same variable are | |
11323 | allowed. Untyped variable declarations do establish the expected kind of the | |
11324 | variable (string or string list), and successive declarations for it must | |
11325 | respect the initial kind. | |
88e1739c FW |
11326 | |
11327 | @noindent | |
7cd4527e AC |
11328 | A string variable declaration (typed or untyped) declares a variable |
11329 | whose value is a string. This variable may be used as a string expression. | |
11330 | @smallexample @c projectfile | |
11331 | File_Name := "readme.txt"; | |
11332 | Saved_File_Name := File_Name & ".saved"; | |
11333 | @end smallexample | |
88e1739c | 11334 | |
88e1739c | 11335 | @noindent |
7cd4527e AC |
11336 | A string list variable declaration declares a variable whose value is a list |
11337 | of strings. The list may contain any number (zero or more) of strings. | |
88e1739c | 11338 | |
7cd4527e AC |
11339 | @smallexample @c projectfile |
11340 | Empty_List := (); | |
11341 | List_With_One_Element := ("^-gnaty^-gnaty^"); | |
11342 | List_With_Two_Elements := List_With_One_Element & "^-gnatg^-gnatg^"; | |
11343 | Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada" | |
11344 | "pack2.ada", "util_.ada", "util.ada"); | |
88e1739c FW |
11345 | @end smallexample |
11346 | ||
7cd4527e AC |
11347 | @noindent |
11348 | The same typed variable may not be declared more than once at project level, | |
11349 | and it may not be declared more than once in any package; it is in effect | |
11350 | a constant. | |
88e1739c | 11351 | |
7cd4527e AC |
11352 | The same untyped variable may be declared several times. Declarations are |
11353 | elaborated in the order in which they appear, so the new value replaces | |
11354 | the old one, and any subsequent reference to the variable uses the new value. | |
11355 | However, as noted above, if a variable has been declared as a string, all | |
11356 | subsequent | |
11357 | declarations must give it a string value. Similarly, if a variable has | |
11358 | been declared as a string list, all subsequent declarations | |
11359 | must give it a string list value. | |
88e1739c | 11360 | |
7cd4527e | 11361 | A @emph{variable reference} may take several forms: |
88e1739c | 11362 | |
7cd4527e AC |
11363 | @itemize @bullet |
11364 | @item The simple variable name, for a variable in the current package (if any) | |
11365 | or in the current project | |
11366 | @item An expanded name, whose prefix is a context name. | |
11367 | @end itemize | |
88e1739c FW |
11368 | |
11369 | @noindent | |
7cd4527e | 11370 | A @emph{context} may be one of the following: |
88e1739c | 11371 | |
7cd4527e AC |
11372 | @itemize @bullet |
11373 | @item The name of an existing package in the current project | |
11374 | @item The name of an imported project of the current project | |
11375 | @item The name of an ancestor project (i.e., a project extended by the current | |
11376 | project, either directly or indirectly) | |
11377 | @item An expanded name whose prefix is an imported/parent project name, and | |
11378 | whose selector is a package name in that project. | |
11379 | @end itemize | |
88e1739c | 11380 | |
7cd4527e AC |
11381 | @noindent |
11382 | A variable reference may be used in an expression. | |
88e1739c | 11383 | |
7cd4527e AC |
11384 | @node Attributes |
11385 | @subsection Attributes | |
88e1739c | 11386 | |
7cd4527e AC |
11387 | @noindent |
11388 | A project (and its packages) may have @emph{attributes} that define | |
11389 | the project's properties. Some attributes have values that are strings; | |
11390 | others have values that are string lists. | |
88e1739c | 11391 | |
7cd4527e AC |
11392 | There are two categories of attributes: @emph{simple attributes} |
11393 | and @emph{associative arrays} (see @ref{Associative Array Attributes}). | |
88e1739c | 11394 | |
7cd4527e AC |
11395 | Legal project attribute names, and attribute names for each legal package are |
11396 | listed below. Attributes names are case-insensitive. | |
88e1739c | 11397 | |
7cd4527e | 11398 | The following attributes are defined on projects (all are simple attributes): |
88e1739c | 11399 | |
7cd4527e AC |
11400 | @multitable @columnfractions .4 .3 |
11401 | @item @emph{Attribute Name} | |
11402 | @tab @emph{Value} | |
11403 | @item @code{Source_Files} | |
11404 | @tab string list | |
11405 | @item @code{Source_Dirs} | |
11406 | @tab string list | |
11407 | @item @code{Source_List_File} | |
11408 | @tab string | |
11409 | @item @code{Object_Dir} | |
11410 | @tab string | |
11411 | @item @code{Exec_Dir} | |
11412 | @tab string | |
11413 | @item @code{Locally_Removed_Files} | |
11414 | @tab string list | |
11415 | @item @code{Main} | |
11416 | @tab string list | |
11417 | @item @code{Languages} | |
11418 | @tab string list | |
11419 | @item @code{Main_Language} | |
11420 | @tab string | |
11421 | @item @code{Library_Dir} | |
11422 | @tab string | |
11423 | @item @code{Library_Name} | |
11424 | @tab string | |
11425 | @item @code{Library_Kind} | |
11426 | @tab string | |
11427 | @item @code{Library_Version} | |
11428 | @tab string | |
11429 | @item @code{Library_Interface} | |
11430 | @tab string | |
11431 | @item @code{Library_Auto_Init} | |
11432 | @tab string | |
11433 | @item @code{Library_Options} | |
11434 | @tab string list | |
11435 | @item @code{Library_GCC} | |
11436 | @tab string | |
11437 | @end multitable | |
88e1739c FW |
11438 | |
11439 | @noindent | |
7cd4527e AC |
11440 | The following attributes are defined for package @code{Naming} |
11441 | (see @ref{Naming Schemes}): | |
88e1739c | 11442 | |
7cd4527e AC |
11443 | @multitable @columnfractions .4 .2 .2 .2 |
11444 | @item Attribute Name @tab Category @tab Index @tab Value | |
11445 | @item @code{Spec_Suffix} | |
11446 | @tab associative array | |
11447 | @tab language name | |
11448 | @tab string | |
11449 | @item @code{Body_Suffix} | |
11450 | @tab associative array | |
11451 | @tab language name | |
11452 | @tab string | |
11453 | @item @code{Separate_Suffix} | |
11454 | @tab simple attribute | |
11455 | @tab n/a | |
11456 | @tab string | |
11457 | @item @code{Casing} | |
11458 | @tab simple attribute | |
11459 | @tab n/a | |
11460 | @tab string | |
11461 | @item @code{Dot_Replacement} | |
11462 | @tab simple attribute | |
11463 | @tab n/a | |
11464 | @tab string | |
11465 | @item @code{Spec} | |
11466 | @tab associative array | |
11467 | @tab Ada unit name | |
11468 | @tab string | |
11469 | @item @code{Body} | |
11470 | @tab associative array | |
11471 | @tab Ada unit name | |
11472 | @tab string | |
11473 | @item @code{Specification_Exceptions} | |
11474 | @tab associative array | |
11475 | @tab language name | |
11476 | @tab string list | |
11477 | @item @code{Implementation_Exceptions} | |
11478 | @tab associative array | |
11479 | @tab language name | |
11480 | @tab string list | |
11481 | @end multitable | |
88e1739c FW |
11482 | |
11483 | @noindent | |
7cd4527e AC |
11484 | The following attributes are defined for packages @code{Builder}, |
11485 | @code{Compiler}, @code{Binder}, | |
11486 | @code{Linker}, @code{Cross_Reference}, and @code{Finder} | |
11487 | (see @ref{^Switches^Switches^ and Project Files}). | |
88e1739c | 11488 | |
7cd4527e AC |
11489 | @multitable @columnfractions .4 .2 .2 .2 |
11490 | @item Attribute Name @tab Category @tab Index @tab Value | |
11491 | @item @code{^Default_Switches^Default_Switches^} | |
11492 | @tab associative array | |
11493 | @tab language name | |
11494 | @tab string list | |
11495 | @item @code{^Switches^Switches^} | |
11496 | @tab associative array | |
11497 | @tab file name | |
11498 | @tab string list | |
11499 | @end multitable | |
88e1739c FW |
11500 | |
11501 | @noindent | |
7cd4527e AC |
11502 | In addition, package @code{Compiler} has a single string attribute |
11503 | @code{Local_Configuration_Pragmas} and package @code{Builder} has a single | |
11504 | string attribute @code{Global_Configuration_Pragmas}. | |
88e1739c FW |
11505 | |
11506 | @noindent | |
7cd4527e AC |
11507 | Each simple attribute has a default value: the empty string (for string-valued |
11508 | attributes) and the empty list (for string list-valued attributes). | |
88e1739c | 11509 | |
7cd4527e | 11510 | An attribute declaration defines a new value for an attribute. |
88e1739c | 11511 | |
7cd4527e | 11512 | Examples of simple attribute declarations: |
88e1739c | 11513 | |
7cd4527e AC |
11514 | @smallexample @c projectfile |
11515 | for Object_Dir use "objects"; | |
11516 | for Source_Dirs use ("units", "test/drivers"); | |
11517 | @end smallexample | |
88e1739c | 11518 | |
88e1739c | 11519 | @noindent |
7cd4527e AC |
11520 | The syntax of a @dfn{simple attribute declaration} is similar to that of an |
11521 | attribute definition clause in Ada. | |
88e1739c | 11522 | |
7cd4527e AC |
11523 | Attributes references may be appear in expressions. |
11524 | The general form for such a reference is @code{<entity>'<attribute>}: | |
11525 | Associative array attributes are functions. Associative | |
11526 | array attribute references must have an argument that is a string literal. | |
88e1739c | 11527 | |
7cd4527e | 11528 | Examples are: |
88e1739c | 11529 | |
7cd4527e AC |
11530 | @smallexample @c projectfile |
11531 | project'Object_Dir | |
11532 | Naming'Dot_Replacement | |
11533 | Imported_Project'Source_Dirs | |
11534 | Imported_Project.Naming'Casing | |
11535 | Builder'^Default_Switches^Default_Switches^("Ada") | |
11536 | @end smallexample | |
88e1739c FW |
11537 | |
11538 | @noindent | |
7cd4527e AC |
11539 | The prefix of an attribute may be: |
11540 | @itemize @bullet | |
11541 | @item @code{project} for an attribute of the current project | |
11542 | @item The name of an existing package of the current project | |
11543 | @item The name of an imported project | |
11544 | @item The name of a parent project that is extended by the current project | |
11545 | @item An expanded name whose prefix is imported/parent project name, | |
11546 | and whose selector is a package name | |
11547 | @end itemize | |
88e1739c FW |
11548 | |
11549 | @noindent | |
7cd4527e AC |
11550 | Example: |
11551 | @smallexample @c projectfile | |
88e1739c | 11552 | @group |
7cd4527e AC |
11553 | project Prj is |
11554 | for Source_Dirs use project'Source_Dirs & "units"; | |
11555 | for Source_Dirs use project'Source_Dirs & "test/drivers" | |
11556 | end Prj; | |
88e1739c FW |
11557 | @end group |
11558 | @end smallexample | |
11559 | ||
11560 | @noindent | |
7cd4527e AC |
11561 | In the first attribute declaration, initially the attribute @code{Source_Dirs} |
11562 | has the default value: an empty string list. After this declaration, | |
11563 | @code{Source_Dirs} is a string list of one element: @code{"units"}. | |
11564 | After the second attribute declaration @code{Source_Dirs} is a string list of | |
11565 | two elements: @code{"units"} and @code{"test/drivers"}. | |
88e1739c | 11566 | |
7cd4527e AC |
11567 | Note: this example is for illustration only. In practice, |
11568 | the project file would contain only one attribute declaration: | |
11569 | ||
11570 | @smallexample @c projectfile | |
11571 | for Source_Dirs use ("units", "test/drivers"); | |
88e1739c FW |
11572 | @end smallexample |
11573 | ||
7cd4527e AC |
11574 | @node Associative Array Attributes |
11575 | @subsection Associative Array Attributes | |
11576 | ||
88e1739c | 11577 | @noindent |
7cd4527e AC |
11578 | Some attributes are defined as @emph{associative arrays}. An associative |
11579 | array may be regarded as a function that takes a string as a parameter | |
11580 | and delivers a string or string list value as its result. | |
88e1739c | 11581 | |
7cd4527e | 11582 | Here are some examples of single associative array attribute associations: |
88e1739c | 11583 | |
7cd4527e AC |
11584 | @smallexample @c projectfile |
11585 | for Body ("main") use "Main.ada"; | |
11586 | for ^Switches^Switches^ ("main.ada") | |
11587 | use ("^-v^-v^", | |
11588 | "^-gnatv^-gnatv^"); | |
11589 | for ^Switches^Switches^ ("main.ada") | |
11590 | use Builder'^Switches^Switches^ ("main.ada") | |
11591 | & "^-g^-g^"; | |
11592 | @end smallexample | |
88e1739c FW |
11593 | |
11594 | @noindent | |
7cd4527e AC |
11595 | Like untyped variables and simple attributes, associative array attributes |
11596 | may be declared several times. Each declaration supplies a new value for the | |
11597 | attribute, and replaces the previous setting. | |
88e1739c | 11598 | |
7cd4527e AC |
11599 | @noindent |
11600 | An associative array attribute may be declared as a full associative array | |
11601 | declaration, with the value of the same attribute in an imported or extended | |
11602 | project. | |
88e1739c | 11603 | |
7cd4527e AC |
11604 | @smallexample @c projectfile |
11605 | package Builder is | |
11606 | for Default_Switches use Default.Builder'Default_Switches; | |
11607 | end Builder; | |
11608 | @end smallexample | |
88e1739c | 11609 | |
7cd4527e AC |
11610 | @noindent |
11611 | In this example, @code{Default} must be either an project imported by the | |
11612 | current project, or the project that the current project extends. If the | |
11613 | attribute is in a package (in this case, in package @code{Builder}), the same | |
11614 | package needs to be specified. | |
88e1739c | 11615 | |
7cd4527e AC |
11616 | @noindent |
11617 | A full associative array declaration replaces any other declaration for the | |
11618 | attribute, including other full associative array declaration. Single | |
11619 | associative array associations may be declare after a full associative | |
11620 | declaration, modifying the value for a single association of the attribute. | |
88e1739c | 11621 | |
7cd4527e AC |
11622 | @node case Constructions |
11623 | @subsection @code{case} Constructions | |
88e1739c FW |
11624 | |
11625 | @noindent | |
7cd4527e AC |
11626 | A @code{case} construction is used in a project file to effect conditional |
11627 | behavior. | |
11628 | Here is a typical example: | |
88e1739c | 11629 | |
7cd4527e AC |
11630 | @smallexample @c projectfile |
11631 | @group | |
11632 | project MyProj is | |
11633 | type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS"); | |
88e1739c | 11634 | |
7cd4527e AC |
11635 | OS : OS_Type := external ("OS", "GNU/Linux"); |
11636 | @end group | |
88e1739c | 11637 | |
88e1739c | 11638 | @group |
88e1739c | 11639 | package Compiler is |
7cd4527e AC |
11640 | case OS is |
11641 | when "GNU/Linux" | "Unix" => | |
11642 | for ^Default_Switches^Default_Switches^ ("Ada") | |
11643 | use ("^-gnath^-gnath^"); | |
11644 | when "NT" => | |
11645 | for ^Default_Switches^Default_Switches^ ("Ada") | |
11646 | use ("^-gnatP^-gnatP^"); | |
11647 | when others => | |
11648 | end case; | |
88e1739c | 11649 | end Compiler; |
7cd4527e | 11650 | end MyProj; |
88e1739c FW |
11651 | @end group |
11652 | @end smallexample | |
11653 | ||
11654 | @noindent | |
7cd4527e AC |
11655 | The syntax of a @code{case} construction is based on the Ada case statement |
11656 | (although there is no @code{null} construction for empty alternatives). | |
88e1739c | 11657 | |
7cd4527e AC |
11658 | The case expression must a typed string variable. |
11659 | Each alternative comprises the reserved word @code{when}, either a list of | |
11660 | literal strings separated by the @code{"|"} character or the reserved word | |
11661 | @code{others}, and the @code{"=>"} token. | |
11662 | Each literal string must belong to the string type that is the type of the | |
11663 | case variable. | |
11664 | An @code{others} alternative, if present, must occur last. | |
88e1739c | 11665 | |
7cd4527e AC |
11666 | After each @code{=>}, there are zero or more constructions. The only |
11667 | constructions allowed in a case construction are other case constructions and | |
11668 | attribute declarations. String type declarations, variable declarations and | |
11669 | package declarations are not allowed. | |
88e1739c | 11670 | |
7cd4527e AC |
11671 | The value of the case variable is often given by an external reference |
11672 | (see @ref{External References in Project Files}). | |
88e1739c | 11673 | |
7cd4527e AC |
11674 | @c **************************************** |
11675 | @c * Objects and Sources in Project Files * | |
11676 | @c **************************************** | |
88e1739c | 11677 | |
7cd4527e AC |
11678 | @node Objects and Sources in Project Files |
11679 | @section Objects and Sources in Project Files | |
11680 | ||
11681 | @menu | |
11682 | * Object Directory:: | |
11683 | * Exec Directory:: | |
11684 | * Source Directories:: | |
11685 | * Source File Names:: | |
11686 | @end menu | |
88e1739c FW |
11687 | |
11688 | @noindent | |
7cd4527e AC |
11689 | Each project has exactly one object directory and one or more source |
11690 | directories. The source directories must contain at least one source file, | |
11691 | unless the project file explicitly specifies that no source files are present | |
11692 | (see @ref{Source File Names}). | |
88e1739c | 11693 | |
7cd4527e AC |
11694 | @node Object Directory |
11695 | @subsection Object Directory | |
88e1739c | 11696 | |
7cd4527e AC |
11697 | @noindent |
11698 | The object directory for a project is the directory containing the compiler's | |
11699 | output (such as @file{ALI} files and object files) for the project's immediate | |
11700 | sources. | |
88e1739c | 11701 | |
7cd4527e AC |
11702 | The object directory is given by the value of the attribute @code{Object_Dir} |
11703 | in the project file. | |
88e1739c | 11704 | |
7cd4527e AC |
11705 | @smallexample @c projectfile |
11706 | for Object_Dir use "objects"; | |
11707 | @end smallexample | |
88e1739c | 11708 | |
7cd4527e AC |
11709 | @noindent |
11710 | The attribute @var{Object_Dir} has a string value, the path name of the object | |
11711 | directory. The path name may be absolute or relative to the directory of the | |
11712 | project file. This directory must already exist, and be readable and writable. | |
88e1739c | 11713 | |
7cd4527e AC |
11714 | By default, when the attribute @code{Object_Dir} is not given an explicit value |
11715 | or when its value is the empty string, the object directory is the same as the | |
11716 | directory containing the project file. | |
88e1739c | 11717 | |
7cd4527e AC |
11718 | @node Exec Directory |
11719 | @subsection Exec Directory | |
88e1739c | 11720 | |
7cd4527e AC |
11721 | @noindent |
11722 | The exec directory for a project is the directory containing the executables | |
11723 | for the project's main subprograms. | |
88e1739c | 11724 | |
7cd4527e AC |
11725 | The exec directory is given by the value of the attribute @code{Exec_Dir} |
11726 | in the project file. | |
11727 | ||
11728 | @smallexample @c projectfile | |
11729 | for Exec_Dir use "executables"; | |
88e1739c FW |
11730 | @end smallexample |
11731 | ||
11732 | @noindent | |
7cd4527e AC |
11733 | The attribute @var{Exec_Dir} has a string value, the path name of the exec |
11734 | directory. The path name may be absolute or relative to the directory of the | |
11735 | project file. This directory must already exist, and be writable. | |
88e1739c | 11736 | |
7cd4527e AC |
11737 | By default, when the attribute @code{Exec_Dir} is not given an explicit value |
11738 | or when its value is the empty string, the exec directory is the same as the | |
11739 | object directory of the project file. | |
88e1739c | 11740 | |
7cd4527e AC |
11741 | @node Source Directories |
11742 | @subsection Source Directories | |
88e1739c FW |
11743 | |
11744 | @noindent | |
7cd4527e AC |
11745 | The source directories of a project are specified by the project file |
11746 | attribute @code{Source_Dirs}. | |
88e1739c | 11747 | |
7cd4527e AC |
11748 | This attribute's value is a string list. If the attribute is not given an |
11749 | explicit value, then there is only one source directory, the one where the | |
11750 | project file resides. | |
11751 | ||
11752 | A @code{Source_Dirs} attribute that is explicitly defined to be the empty list, | |
11753 | as in | |
11754 | ||
11755 | @smallexample @c projectfile | |
11756 | for Source_Dirs use (); | |
88e1739c FW |
11757 | @end smallexample |
11758 | ||
11759 | @noindent | |
7cd4527e | 11760 | indicates that the project contains no source files. |
88e1739c | 11761 | |
7cd4527e AC |
11762 | Otherwise, each string in the string list designates one or more |
11763 | source directories. | |
88e1739c | 11764 | |
7cd4527e AC |
11765 | @smallexample @c projectfile |
11766 | for Source_Dirs use ("sources", "test/drivers"); | |
88e1739c FW |
11767 | @end smallexample |
11768 | ||
11769 | @noindent | |
7cd4527e AC |
11770 | If a string in the list ends with @code{"/**"}, then the directory whose path |
11771 | name precedes the two asterisks, as well as all its subdirectories | |
11772 | (recursively), are source directories. | |
88e1739c | 11773 | |
7cd4527e AC |
11774 | @smallexample @c projectfile |
11775 | for Source_Dirs use ("/system/sources/**"); | |
11776 | @end smallexample | |
88e1739c | 11777 | |
7cd4527e AC |
11778 | @noindent |
11779 | Here the directory @code{/system/sources} and all of its subdirectories | |
11780 | (recursively) are source directories. | |
88e1739c | 11781 | |
7cd4527e AC |
11782 | To specify that the source directories are the directory of the project file |
11783 | and all of its subdirectories, you can declare @code{Source_Dirs} as follows: | |
11784 | @smallexample @c projectfile | |
11785 | for Source_Dirs use ("./**"); | |
11786 | @end smallexample | |
88e1739c FW |
11787 | |
11788 | @noindent | |
7cd4527e | 11789 | Each of the source directories must exist and be readable. |
88e1739c | 11790 | |
7cd4527e AC |
11791 | @node Source File Names |
11792 | @subsection Source File Names | |
88e1739c | 11793 | |
7cd4527e AC |
11794 | @noindent |
11795 | In a project that contains source files, their names may be specified by the | |
11796 | attributes @code{Source_Files} (a string list) or @code{Source_List_File} | |
11797 | (a string). Source file names never include any directory information. | |
88e1739c | 11798 | |
7cd4527e AC |
11799 | If the attribute @code{Source_Files} is given an explicit value, then each |
11800 | element of the list is a source file name. | |
88e1739c | 11801 | |
7cd4527e AC |
11802 | @smallexample @c projectfile |
11803 | for Source_Files use ("main.adb"); | |
11804 | for Source_Files use ("main.adb", "pack1.ads", "pack2.adb"); | |
11805 | @end smallexample | |
88e1739c FW |
11806 | |
11807 | @noindent | |
7cd4527e AC |
11808 | If the attribute @code{Source_Files} is not given an explicit value, |
11809 | but the attribute @code{Source_List_File} is given a string value, | |
11810 | then the source file names are contained in the text file whose path name | |
11811 | (absolute or relative to the directory of the project file) is the | |
11812 | value of the attribute @code{Source_List_File}. | |
88e1739c | 11813 | |
7cd4527e AC |
11814 | Each line in the file that is not empty or is not a comment |
11815 | contains a source file name. | |
11816 | ||
11817 | @smallexample @c projectfile | |
11818 | for Source_List_File use "source_list.txt"; | |
88e1739c FW |
11819 | @end smallexample |
11820 | ||
11821 | @noindent | |
7cd4527e AC |
11822 | By default, if neither the attribute @code{Source_Files} nor the attribute |
11823 | @code{Source_List_File} is given an explicit value, then each file in the | |
11824 | source directories that conforms to the project's naming scheme | |
11825 | (see @ref{Naming Schemes}) is an immediate source of the project. | |
88e1739c | 11826 | |
7cd4527e AC |
11827 | A warning is issued if both attributes @code{Source_Files} and |
11828 | @code{Source_List_File} are given explicit values. In this case, the attribute | |
11829 | @code{Source_Files} prevails. | |
88e1739c | 11830 | |
7cd4527e AC |
11831 | Each source file name must be the name of one existing source file |
11832 | in one of the source directories. | |
88e1739c | 11833 | |
7cd4527e AC |
11834 | A @code{Source_Files} attribute whose value is an empty list |
11835 | indicates that there are no source files in the project. | |
88e1739c | 11836 | |
7cd4527e AC |
11837 | If the order of the source directories is known statically, that is if |
11838 | @code{"/**"} is not used in the string list @code{Source_Dirs}, then there may | |
11839 | be several files with the same source file name. In this case, only the file | |
11840 | in the first directory is considered as an immediate source of the project | |
11841 | file. If the order of the source directories is not known statically, it is | |
11842 | an error to have several files with the same source file name. | |
88e1739c | 11843 | |
7cd4527e AC |
11844 | Projects can be specified to have no Ada source |
11845 | files: the value of (@code{Source_Dirs} or @code{Source_Files} may be an empty | |
11846 | list, or the @code{"Ada"} may be absent from @code{Languages}: | |
88e1739c | 11847 | |
7cd4527e AC |
11848 | @smallexample @c projectfile |
11849 | for Source_Dirs use (); | |
11850 | for Source_Files use (); | |
11851 | for Languages use ("C", "C++"); | |
11852 | @end smallexample | |
88e1739c | 11853 | |
7cd4527e AC |
11854 | @noindent |
11855 | Otherwise, a project must contain at least one immediate source. | |
11856 | ||
11857 | Projects with no source files are useful as template packages | |
11858 | (see @ref{Packages in Project Files}) for other projects; in particular to | |
11859 | define a package @code{Naming} (see @ref{Naming Schemes}). | |
11860 | ||
11861 | @c **************************** | |
11862 | @c * Importing Projects * | |
11863 | @c **************************** | |
11864 | ||
11865 | @node Importing Projects | |
11866 | @section Importing Projects | |
88e1739c FW |
11867 | |
11868 | @noindent | |
7cd4527e AC |
11869 | An immediate source of a project P may depend on source files that |
11870 | are neither immediate sources of P nor in the predefined library. | |
11871 | To get this effect, P must @emph{import} the projects that contain the needed | |
11872 | source files. | |
88e1739c | 11873 | |
7cd4527e | 11874 | @smallexample @c projectfile |
88e1739c | 11875 | @group |
7cd4527e AC |
11876 | with "project1", "utilities.gpr"; |
11877 | with "/namings/apex.gpr"; | |
11878 | project Main is | |
11879 | ... | |
88e1739c FW |
11880 | @end group |
11881 | @end smallexample | |
11882 | ||
11883 | @noindent | |
7cd4527e AC |
11884 | As can be seen in this example, the syntax for importing projects is similar |
11885 | to the syntax for importing compilation units in Ada. However, project files | |
11886 | use literal strings instead of names, and the @code{with} clause identifies | |
11887 | project files rather than packages. | |
88e1739c | 11888 | |
7cd4527e AC |
11889 | Each literal string is the file name or path name (absolute or relative) of a |
11890 | project file. If a string is simply a file name, with no path, then its | |
11891 | location is determined by the @emph{project path}: | |
88e1739c | 11892 | |
7cd4527e AC |
11893 | @itemize @bullet |
11894 | @item | |
11895 | If the ^environment variable^logical name^ @env{ADA_PROJECT_PATH} exists, | |
11896 | then the project path includes all the directories in this | |
11897 | ^environment variable^logical name^, plus the directory of the project file. | |
88e1739c | 11898 | |
7cd4527e AC |
11899 | @item |
11900 | If the ^environment variable^logical name^ @env{ADA_PROJECT_PATH} does not | |
11901 | exist, then the project path contains only one directory, namely the one where | |
11902 | the project file is located. | |
11903 | @end itemize | |
88e1739c FW |
11904 | |
11905 | @noindent | |
7cd4527e | 11906 | If a relative pathname is used, as in |
88e1739c | 11907 | |
7cd4527e AC |
11908 | @smallexample @c projectfile |
11909 | with "tests/proj"; | |
88e1739c FW |
11910 | @end smallexample |
11911 | ||
11912 | @noindent | |
7cd4527e AC |
11913 | then the path is relative to the directory where the importing project file is |
11914 | located. Any symbolic link will be fully resolved in the directory | |
11915 | of the importing project file before the imported project file is examined. | |
88e1739c | 11916 | |
7cd4527e AC |
11917 | If the @code{with}'ed project file name does not have an extension, |
11918 | the default is @file{^.gpr^.GPR^}. If a file with this extension is not found, | |
11919 | then the file name as specified in the @code{with} clause (no extension) will | |
11920 | be used. In the above example, if a file @code{project1.gpr} is found, then it | |
11921 | will be used; otherwise, if a file @code{^project1^PROJECT1^} exists | |
11922 | then it will be used; if neither file exists, this is an error. | |
88e1739c | 11923 | |
7cd4527e AC |
11924 | A warning is issued if the name of the project file does not match the |
11925 | name of the project; this check is case insensitive. | |
88e1739c | 11926 | |
7cd4527e AC |
11927 | Any source file that is an immediate source of the imported project can be |
11928 | used by the immediate sources of the importing project, transitively. Thus | |
11929 | if @code{A} imports @code{B}, and @code{B} imports @code{C}, the immediate | |
11930 | sources of @code{A} may depend on the immediate sources of @code{C}, even if | |
11931 | @code{A} does not import @code{C} explicitly. However, this is not recommended, | |
11932 | because if and when @code{B} ceases to import @code{C}, some sources in | |
11933 | @code{A} will no longer compile. | |
88e1739c | 11934 | |
7cd4527e AC |
11935 | A side effect of this capability is that normally cyclic dependencies are not |
11936 | permitted: if @code{A} imports @code{B} (directly or indirectly) then @code{B} | |
11937 | is not allowed to import @code{A}. However, there are cases when cyclic | |
11938 | dependencies would be beneficial. For these cases, another form of import | |
11939 | between projects exists, the @code{limited with}: a project @code{A} that | |
11940 | imports a project @code{B} with a straigh @code{with} may also be imported, | |
11941 | directly or indirectly, by @code{B} on the condition that imports from @code{B} | |
11942 | to @code{A} include at least one @code{limited with}. | |
88e1739c | 11943 | |
7cd4527e AC |
11944 | @smallexample @c 0projectfile |
11945 | with "../b/b.gpr"; | |
11946 | with "../c/c.gpr"; | |
11947 | project A is | |
11948 | end A; | |
88e1739c | 11949 | |
7cd4527e AC |
11950 | limited with "../a/a.gpr"; |
11951 | project B is | |
11952 | end B; | |
88e1739c | 11953 | |
7cd4527e AC |
11954 | with "../d/d.gpr"; |
11955 | project C is | |
11956 | end C; | |
88e1739c | 11957 | |
7cd4527e AC |
11958 | limited with "../a/a.gpr"; |
11959 | project D is | |
11960 | end D; | |
88e1739c FW |
11961 | @end smallexample |
11962 | ||
11963 | @noindent | |
7cd4527e AC |
11964 | In the above legal example, there are two project cycles: |
11965 | @itemize @bullet | |
11966 | @item A-> B-> A | |
11967 | @item A -> C -> D -> A | |
11968 | @end itemize | |
88e1739c | 11969 | |
7cd4527e AC |
11970 | @noindent |
11971 | In each of these cycle there is one @code{limited with}: import of @code{A} | |
11972 | from @code{B} and import of @code{A} from @code{D}. | |
88e1739c | 11973 | |
7cd4527e AC |
11974 | The difference between straight @code{with} and @code{limited with} is that |
11975 | the name of a project imported with a @code{limited with} cannot be used in the | |
11976 | project that imports it. In particular, its packages cannot be renamed and | |
11977 | its variables cannot be referred to. | |
88e1739c | 11978 | |
7cd4527e AC |
11979 | An exception to the above rules for @code{limited with} is that for the main |
11980 | project specified to @command{gnatmake} or to the @command{GNAT} driver a | |
11981 | @code{limited with} is equivalent to a straight @code{with}. For example, | |
11982 | in the example above, projects @code{B} and @code{D} could not be main | |
11983 | projects for @command{gnatmake} or to the @command{GNAT} driver, because they | |
11984 | each have a @code{limited with} that is the only one in a cycle of importing | |
11985 | projects. | |
88e1739c | 11986 | |
7cd4527e AC |
11987 | @c ********************* |
11988 | @c * Project Extension * | |
11989 | @c ********************* | |
88e1739c | 11990 | |
7cd4527e AC |
11991 | @node Project Extension |
11992 | @section Project Extension | |
88e1739c | 11993 | |
7cd4527e AC |
11994 | @noindent |
11995 | During development of a large system, it is sometimes necessary to use | |
11996 | modified versions of some of the source files, without changing the original | |
11997 | sources. This can be achieved through the @emph{project extension} facility. | |
11998 | ||
11999 | @smallexample @c projectfile | |
12000 | project Modified_Utilities extends "/baseline/utilities.gpr" is ... | |
88e1739c FW |
12001 | @end smallexample |
12002 | ||
7cd4527e AC |
12003 | @noindent |
12004 | A project extension declaration introduces an extending project | |
12005 | (the @emph{child}) and a project being extended (the @emph{parent}). | |
88e1739c | 12006 | |
7cd4527e AC |
12007 | By default, a child project inherits all the sources of its parent. |
12008 | However, inherited sources can be overridden: a unit in a parent is hidden | |
12009 | by a unit of the same name in the child. | |
88e1739c | 12010 | |
7cd4527e AC |
12011 | Inherited sources are considered to be sources (but not immediate sources) |
12012 | of the child project; see @ref{Project File Syntax}. | |
88e1739c | 12013 | |
7cd4527e | 12014 | An inherited source file retains any switches specified in the parent project. |
88e1739c | 12015 | |
7cd4527e AC |
12016 | For example if the project @code{Utilities} contains the specification and the |
12017 | body of an Ada package @code{Util_IO}, then the project | |
12018 | @code{Modified_Utilities} can contain a new body for package @code{Util_IO}. | |
12019 | The original body of @code{Util_IO} will not be considered in program builds. | |
12020 | However, the package specification will still be found in the project | |
12021 | @code{Utilities}. | |
88e1739c | 12022 | |
7cd4527e AC |
12023 | A child project can have only one parent but it may import any number of other |
12024 | projects. | |
88e1739c | 12025 | |
7cd4527e AC |
12026 | A project is not allowed to import directly or indirectly at the same time a |
12027 | child project and any of its ancestors. | |
88e1739c | 12028 | |
7cd4527e AC |
12029 | @c **************************************** |
12030 | @c * External References in Project Files * | |
12031 | @c **************************************** | |
88e1739c | 12032 | |
7cd4527e AC |
12033 | @node External References in Project Files |
12034 | @section External References in Project Files | |
88e1739c | 12035 | |
7cd4527e AC |
12036 | @noindent |
12037 | A project file may contain references to external variables; such references | |
12038 | are called @emph{external references}. | |
88e1739c | 12039 | |
7cd4527e AC |
12040 | An external variable is either defined as part of the environment (an |
12041 | environment variable in Unix, for example) or else specified on the command | |
12042 | line via the @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. | |
12043 | If both, then the command line value is used. | |
88e1739c | 12044 | |
7cd4527e AC |
12045 | The value of an external reference is obtained by means of the built-in |
12046 | function @code{external}, which returns a string value. | |
12047 | This function has two forms: | |
12048 | @itemize @bullet | |
12049 | @item @code{external (external_variable_name)} | |
12050 | @item @code{external (external_variable_name, default_value)} | |
12051 | @end itemize | |
88e1739c | 12052 | |
7cd4527e AC |
12053 | @noindent |
12054 | Each parameter must be a string literal. For example: | |
88e1739c | 12055 | |
7cd4527e AC |
12056 | @smallexample @c projectfile |
12057 | external ("USER") | |
12058 | external ("OS", "GNU/Linux") | |
12059 | @end smallexample | |
88e1739c | 12060 | |
7cd4527e AC |
12061 | @noindent |
12062 | In the form with one parameter, the function returns the value of | |
12063 | the external variable given as parameter. If this name is not present in the | |
12064 | environment, the function returns an empty string. | |
88e1739c | 12065 | |
7cd4527e AC |
12066 | In the form with two string parameters, the second argument is |
12067 | the value returned when the variable given as the first argument is not | |
12068 | present in the environment. In the example above, if @code{"OS"} is not | |
12069 | the name of ^an environment variable^a logical name^ and is not passed on | |
12070 | the command line, then the returned value is @code{"GNU/Linux"}. | |
12071 | ||
12072 | An external reference may be part of a string expression or of a string | |
12073 | list expression, and can therefore appear in a variable declaration or | |
12074 | an attribute declaration. | |
12075 | ||
12076 | @smallexample @c projectfile | |
12077 | @group | |
12078 | type Mode_Type is ("Debug", "Release"); | |
12079 | Mode : Mode_Type := external ("MODE"); | |
12080 | case Mode is | |
12081 | when "Debug" => | |
12082 | ... | |
88e1739c FW |
12083 | @end group |
12084 | @end smallexample | |
12085 | ||
7cd4527e AC |
12086 | @c ***************************** |
12087 | @c * Packages in Project Files * | |
12088 | @c ***************************** | |
88e1739c | 12089 | |
7cd4527e AC |
12090 | @node Packages in Project Files |
12091 | @section Packages in Project Files | |
88e1739c FW |
12092 | |
12093 | @noindent | |
7cd4527e AC |
12094 | A @emph{package} defines the settings for project-aware tools within a |
12095 | project. | |
12096 | For each such tool one can declare a package; the names for these | |
12097 | packages are preset (see @ref{Packages}). | |
12098 | A package may contain variable declarations, attribute declarations, and case | |
12099 | constructions. | |
88e1739c | 12100 | |
7cd4527e AC |
12101 | @smallexample @c projectfile |
12102 | @group | |
12103 | project Proj is | |
12104 | package Builder is -- used by gnatmake | |
12105 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12106 | use ("^-v^-v^", | |
12107 | "^-g^-g^"); | |
12108 | end Builder; | |
12109 | end Proj; | |
12110 | @end group | |
88e1739c FW |
12111 | @end smallexample |
12112 | ||
12113 | @noindent | |
7cd4527e | 12114 | The syntax of package declarations mimics that of package in Ada. |
88e1739c | 12115 | |
7cd4527e AC |
12116 | Most of the packages have an attribute |
12117 | @code{^Default_Switches^Default_Switches^}. | |
12118 | This attribute is an associative array, and its value is a string list. | |
12119 | The index of the associative array is the name of a programming language (case | |
12120 | insensitive). This attribute indicates the ^switch^switch^ | |
12121 | or ^switches^switches^ to be used | |
12122 | with the corresponding tool. | |
88e1739c | 12123 | |
7cd4527e AC |
12124 | Some packages also have another attribute, @code{^Switches^Switches^}, |
12125 | an associative array whose value is a string list. | |
12126 | The index is the name of a source file. | |
12127 | This attribute indicates the ^switch^switch^ | |
12128 | or ^switches^switches^ to be used by the corresponding | |
12129 | tool when dealing with this specific file. | |
88e1739c | 12130 | |
7cd4527e AC |
12131 | Further information on these ^switch^switch^-related attributes is found in |
12132 | @ref{^Switches^Switches^ and Project Files}. | |
88e1739c | 12133 | |
7cd4527e AC |
12134 | A package may be declared as a @emph{renaming} of another package; e.g., from |
12135 | the project file for an imported project. | |
88e1739c | 12136 | |
7cd4527e AC |
12137 | @smallexample @c projectfile |
12138 | @group | |
12139 | with "/global/apex.gpr"; | |
12140 | project Example is | |
12141 | package Naming renames Apex.Naming; | |
12142 | ... | |
12143 | end Example; | |
12144 | @end group | |
12145 | @end smallexample | |
88e1739c | 12146 | |
7cd4527e AC |
12147 | @noindent |
12148 | Packages that are renamed in other project files often come from project files | |
12149 | that have no sources: they are just used as templates. Any modification in the | |
12150 | template will be reflected automatically in all the project files that rename | |
12151 | a package from the template. | |
88e1739c | 12152 | |
7cd4527e AC |
12153 | In addition to the tool-oriented packages, you can also declare a package |
12154 | named @code{Naming} to establish specialized source file naming conventions | |
12155 | (see @ref{Naming Schemes}). | |
88e1739c | 12156 | |
7cd4527e AC |
12157 | @c ************************************ |
12158 | @c * Variables from Imported Projects * | |
12159 | @c ************************************ | |
88e1739c | 12160 | |
7cd4527e AC |
12161 | @node Variables from Imported Projects |
12162 | @section Variables from Imported Projects | |
88e1739c | 12163 | |
7cd4527e AC |
12164 | @noindent |
12165 | An attribute or variable defined in an imported or parent project can | |
12166 | be used in expressions in the importing / extending project. | |
12167 | Such an attribute or variable is denoted by an expanded name whose prefix | |
12168 | is either the name of the project or the expanded name of a package within | |
12169 | a project. | |
88e1739c | 12170 | |
7cd4527e AC |
12171 | @smallexample @c projectfile |
12172 | @group | |
12173 | with "imported"; | |
12174 | project Main extends "base" is | |
12175 | Var1 := Imported.Var; | |
12176 | Var2 := Base.Var & ".new"; | |
12177 | @end group | |
88e1739c | 12178 | |
7cd4527e AC |
12179 | @group |
12180 | package Builder is | |
12181 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12182 | use Imported.Builder.Ada_^Switches^Switches^ & | |
12183 | "^-gnatg^-gnatg^" & | |
12184 | "^-v^-v^"; | |
12185 | end Builder; | |
12186 | @end group | |
88e1739c | 12187 | |
7cd4527e AC |
12188 | @group |
12189 | package Compiler is | |
12190 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12191 | use Base.Compiler.Ada_^Switches^Switches^; | |
12192 | end Compiler; | |
12193 | end Main; | |
12194 | @end group | |
12195 | @end smallexample | |
88e1739c | 12196 | |
7cd4527e AC |
12197 | @noindent |
12198 | In this example: | |
88e1739c | 12199 | |
7cd4527e AC |
12200 | @itemize @bullet |
12201 | @item | |
12202 | The value of @code{Var1} is a copy of the variable @code{Var} defined | |
12203 | in the project file @file{"imported.gpr"} | |
12204 | @item | |
12205 | the value of @code{Var2} is a copy of the value of variable @code{Var} | |
12206 | defined in the project file @file{base.gpr}, concatenated with @code{".new"} | |
12207 | @item | |
12208 | attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package | |
12209 | @code{Builder} is a string list that includes in its value a copy of the value | |
12210 | of @code{Ada_^Switches^Switches^} defined in the @code{Builder} package | |
12211 | in project file @file{imported.gpr} plus two new elements: | |
12212 | @option{"^-gnatg^-gnatg^"} | |
12213 | and @option{"^-v^-v^"}; | |
12214 | @item | |
12215 | attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package | |
12216 | @code{Compiler} is a copy of the variable @code{Ada_^Switches^Switches^} | |
12217 | defined in the @code{Compiler} package in project file @file{base.gpr}, | |
12218 | the project being extended. | |
12219 | @end itemize | |
88e1739c | 12220 | |
7cd4527e AC |
12221 | @c ****************** |
12222 | @c * Naming Schemes * | |
12223 | @c ****************** | |
88e1739c | 12224 | |
7cd4527e AC |
12225 | @node Naming Schemes |
12226 | @section Naming Schemes | |
88e1739c | 12227 | |
7cd4527e AC |
12228 | @noindent |
12229 | Sometimes an Ada software system is ported from a foreign compilation | |
12230 | environment to GNAT, and the file names do not use the default GNAT | |
12231 | conventions. Instead of changing all the file names (which for a variety | |
12232 | of reasons might not be possible), you can define the relevant file | |
12233 | naming scheme in the @code{Naming} package in your project file. | |
88e1739c | 12234 | |
7cd4527e AC |
12235 | @noindent |
12236 | Note that the use of pragmas described in @ref{Alternative | |
12237 | File Naming Schemes} by mean of a configuration pragmas file is not | |
12238 | supported when using project files. You must use the features described | |
12239 | in this paragraph. You can however use specify other configuration | |
12240 | pragmas (see @ref{Specifying Configuration Pragmas}). | |
88e1739c | 12241 | |
7cd4527e AC |
12242 | @ifclear vms |
12243 | For example, the following | |
12244 | package models the Apex file naming rules: | |
88e1739c | 12245 | |
7cd4527e AC |
12246 | @smallexample @c projectfile |
12247 | @group | |
12248 | package Naming is | |
12249 | for Casing use "lowercase"; | |
12250 | for Dot_Replacement use "."; | |
12251 | for Spec_Suffix ("Ada") use ".1.ada"; | |
12252 | for Body_Suffix ("Ada") use ".2.ada"; | |
12253 | end Naming; | |
12254 | @end group | |
12255 | @end smallexample | |
12256 | @end ifclear | |
88e1739c | 12257 | |
7cd4527e AC |
12258 | @ifset vms |
12259 | For example, the following package models the DEC Ada file naming rules: | |
88e1739c | 12260 | |
7cd4527e AC |
12261 | @smallexample @c projectfile |
12262 | @group | |
12263 | package Naming is | |
12264 | for Casing use "lowercase"; | |
12265 | for Dot_Replacement use "__"; | |
12266 | for Spec_Suffix ("Ada") use "_.^ada^ada^"; | |
12267 | for Body_Suffix ("Ada") use ".^ada^ada^"; | |
12268 | end Naming; | |
12269 | @end group | |
12270 | @end smallexample | |
88e1739c | 12271 | |
7cd4527e AC |
12272 | @noindent |
12273 | (Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file | |
12274 | names in lower case) | |
12275 | @end ifset | |
88e1739c | 12276 | |
7cd4527e AC |
12277 | @noindent |
12278 | You can define the following attributes in package @code{Naming}: | |
88e1739c | 12279 | |
7cd4527e | 12280 | @table @code |
88e1739c | 12281 | |
7cd4527e AC |
12282 | @item @var{Casing} |
12283 | This must be a string with one of the three values @code{"lowercase"}, | |
12284 | @code{"uppercase"} or @code{"mixedcase"}; these strings are case insensitive. | |
88e1739c | 12285 | |
7cd4527e AC |
12286 | @noindent |
12287 | If @var{Casing} is not specified, then the default is @code{"lowercase"}. | |
88e1739c | 12288 | |
7cd4527e AC |
12289 | @item @var{Dot_Replacement} |
12290 | This must be a string whose value satisfies the following conditions: | |
88e1739c | 12291 | |
7cd4527e AC |
12292 | @itemize @bullet |
12293 | @item It must not be empty | |
12294 | @item It cannot start or end with an alphanumeric character | |
12295 | @item It cannot be a single underscore | |
12296 | @item It cannot start with an underscore followed by an alphanumeric | |
12297 | @item It cannot contain a dot @code{'.'} except if the entire string | |
12298 | is @code{"."} | |
12299 | @end itemize | |
88e1739c | 12300 | |
7cd4527e AC |
12301 | @noindent |
12302 | If @code{Dot_Replacement} is not specified, then the default is @code{"-"}. | |
88e1739c | 12303 | |
7cd4527e AC |
12304 | @item @var{Spec_Suffix} |
12305 | This is an associative array (indexed by the programming language name, case | |
12306 | insensitive) whose value is a string that must satisfy the following | |
12307 | conditions: | |
88e1739c | 12308 | |
7cd4527e AC |
12309 | @itemize @bullet |
12310 | @item It must not be empty | |
12311 | @item It must include at least one dot | |
12312 | @end itemize | |
12313 | @noindent | |
12314 | If @code{Spec_Suffix ("Ada")} is not specified, then the default is | |
12315 | @code{"^.ads^.ADS^"}. | |
88e1739c | 12316 | |
7cd4527e AC |
12317 | @item @var{Body_Suffix} |
12318 | This is an associative array (indexed by the programming language name, case | |
12319 | insensitive) whose value is a string that must satisfy the following | |
12320 | conditions: | |
88e1739c | 12321 | |
7cd4527e AC |
12322 | @itemize @bullet |
12323 | @item It must not be empty | |
12324 | @item It must include at least one dot | |
12325 | @item It cannot end with the same string as @code{Spec_Suffix ("Ada")} | |
12326 | @end itemize | |
88e1739c | 12327 | @noindent |
7cd4527e AC |
12328 | If @code{Body_Suffix ("Ada")} is not specified, then the default is |
12329 | @code{"^.adb^.ADB^"}. | |
88e1739c | 12330 | |
7cd4527e AC |
12331 | @item @var{Separate_Suffix} |
12332 | This must be a string whose value satisfies the same conditions as | |
12333 | @code{Body_Suffix}. | |
88e1739c FW |
12334 | |
12335 | @noindent | |
7cd4527e AC |
12336 | If @code{Separate_Suffix ("Ada")} is not specified, then it defaults to same |
12337 | value as @code{Body_Suffix ("Ada")}. | |
88e1739c | 12338 | |
7cd4527e AC |
12339 | @item @var{Spec} |
12340 | @noindent | |
12341 | You can use the associative array attribute @code{Spec} to define | |
12342 | the source file name for an individual Ada compilation unit's spec. The array | |
12343 | index must be a string literal that identifies the Ada unit (case insensitive). | |
12344 | The value of this attribute must be a string that identifies the file that | |
12345 | contains this unit's spec (case sensitive or insensitive depending on the | |
12346 | operating system). | |
12347 | ||
12348 | @smallexample @c projectfile | |
12349 | for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; | |
88e1739c FW |
12350 | @end smallexample |
12351 | ||
7cd4527e | 12352 | @item @var{Body} |
88e1739c | 12353 | |
7cd4527e AC |
12354 | You can use the associative array attribute @code{Body} to |
12355 | define the source file name for an individual Ada compilation unit's body | |
12356 | (possibly a subunit). The array index must be a string literal that identifies | |
12357 | the Ada unit (case insensitive). The value of this attribute must be a string | |
12358 | that identifies the file that contains this unit's body or subunit (case | |
12359 | sensitive or insensitive depending on the operating system). | |
12360 | ||
12361 | @smallexample @c projectfile | |
12362 | for Body ("MyPack.MyChild") use "mypack.mychild.body"; | |
12363 | @end smallexample | |
88e1739c FW |
12364 | @end table |
12365 | ||
7cd4527e AC |
12366 | @c ******************** |
12367 | @c * Library Projects * | |
12368 | @c ******************** | |
12369 | ||
12370 | @node Library Projects | |
12371 | @section Library Projects | |
12372 | ||
88e1739c | 12373 | @noindent |
7cd4527e AC |
12374 | @emph{Library projects} are projects whose object code is placed in a library. |
12375 | (Note that this facility is not yet supported on all platforms) | |
88e1739c | 12376 | |
7cd4527e AC |
12377 | To create a library project, you need to define in its project file |
12378 | two project-level attributes: @code{Library_Name} and @code{Library_Dir}. | |
12379 | Additionally, you may define the library-related attributes | |
12380 | @code{Library_Kind}, @code{Library_Version}, @code{Library_Interface}, | |
12381 | @code{Library_Auto_Init}, @code{Library_Options} and @code{Library_GCC}. | |
88e1739c | 12382 | |
7cd4527e AC |
12383 | The @code{Library_Name} attribute has a string value. There is no restriction |
12384 | on the name of a library. It is the responsability of the developer to | |
12385 | choose a name that will be accepted by the platform. It is recommanded to | |
12386 | choose names that could be Ada identifiers; such names are almost guaranteed | |
12387 | to be acceptable on all platforms. | |
88e1739c | 12388 | |
7cd4527e AC |
12389 | The @code{Library_Dir} attribute has a string value that designates the path |
12390 | (absolute or relative) of the directory where the library will reside. | |
12391 | It must designate an existing directory, and this directory must be | |
12392 | different from the project's object directory. It also needs to be writable. | |
88e1739c | 12393 | |
7cd4527e AC |
12394 | If both @code{Library_Name} and @code{Library_Dir} are specified and |
12395 | are legal, then the project file defines a library project. The optional | |
12396 | library-related attributes are checked only for such project files. | |
88e1739c | 12397 | |
7cd4527e AC |
12398 | The @code{Library_Kind} attribute has a string value that must be one of the |
12399 | following (case insensitive): @code{"static"}, @code{"dynamic"} or | |
12400 | @code{"relocatable"}. If this attribute is not specified, the library is a | |
12401 | static library, that is an archive of object files that can be potentially | |
12402 | linked into an static executable. Otherwise, the library may be dynamic or | |
12403 | relocatable, that is a library that is loaded only at the start of execution. | |
12404 | Depending on the operating system, there may or may not be a distinction | |
12405 | between dynamic and relocatable libraries. For Unix and VMS Unix there is no | |
12406 | such distinction. | |
88e1739c | 12407 | |
7cd4527e AC |
12408 | If you need to build both a static and a dynamic library, you should use two |
12409 | different object directories, since in some cases some extra code needs to | |
12410 | be generated for the latter. For such cases, it is recommended to either use | |
12411 | two different project files, or a single one which uses external variables | |
12412 | to indicate what kind of library should be build. | |
88e1739c | 12413 | |
7cd4527e AC |
12414 | The @code{Library_Version} attribute has a string value whose interpretation |
12415 | is platform dependent. It has no effect on VMS and Windows. On Unix, it is | |
12416 | used only for dynamic/relocatable libraries as the internal name of the | |
12417 | library (the @code{"soname"}). If the library file name (built from the | |
12418 | @code{Library_Name}) is different from the @code{Library_Version}, then the | |
12419 | library file will be a symbolic link to the actual file whose name will be | |
12420 | @code{Library_Version}. | |
88e1739c | 12421 | |
7cd4527e | 12422 | Example (on Unix): |
88e1739c | 12423 | |
7cd4527e | 12424 | @smallexample @c projectfile |
88e1739c | 12425 | @group |
7cd4527e | 12426 | project Plib is |
88e1739c | 12427 | |
7cd4527e | 12428 | Version := "1"; |
88e1739c | 12429 | |
7cd4527e AC |
12430 | for Library_Dir use "lib_dir"; |
12431 | for Library_Name use "dummy"; | |
12432 | for Library_Kind use "relocatable"; | |
12433 | for Library_Version use "libdummy.so." & Version; | |
12434 | ||
12435 | end Plib; | |
12436 | @end group | |
88e1739c FW |
12437 | @end smallexample |
12438 | ||
12439 | @noindent | |
7cd4527e AC |
12440 | Directory @file{lib_dir} will contain the internal library file whose name |
12441 | will be @file{libdummy.so.1}, and @file{libdummy.so} will be a symbolic link to | |
12442 | @file{libdummy.so.1}. | |
88e1739c | 12443 | |
7cd4527e AC |
12444 | When @command{gnatmake} detects that a project file |
12445 | is a library project file, it will check all immediate sources of the project | |
12446 | and rebuild the library if any of the sources have been recompiled. | |
12447 | ||
af4b9434 AC |
12448 | Standard project files can import library project files. In such cases, |
12449 | the libraries will only be rebuild if some of its sources are recompiled | |
12450 | because they are in the closure of some other source in an importing project. | |
12451 | Sources of the library project files that are not in such a closure will | |
12452 | not be checked, unless the full library is checked, because one of its sources | |
12453 | needs to be recompiled. | |
12454 | ||
12455 | For instance, assume the project file @code{A} imports the library project file | |
12456 | @code{L}. The immediate sources of A are @file{a1.adb}, @file{a2.ads} and | |
12457 | @file{a2.adb}. The immediate sources of L are @file{l1.ads}, @file{l1.adb}, | |
12458 | @file{l2.ads}, @file{l2.adb}. | |
12459 | ||
12460 | If @file{l1.adb} has been modified, then the library associated with @code{L} | |
12461 | will be rebuild when compiling all the immediate sources of @code{A} only | |
12462 | if @file{a1.ads}, @file{a2.ads} or @file{a2.adb} includes a statement | |
12463 | @code{"with L1;"}. | |
12464 | ||
12465 | To be sure that all the sources in the library associated with @code{L} are | |
12466 | up to date, and that all the sources of parject @code{A} are also up to date, | |
12467 | the following two commands needs to be used: | |
12468 | ||
12469 | @smallexample | |
12470 | gnatmake -Pl.gpr | |
12471 | gnatmake -Pa.gpr | |
12472 | @end smallexample | |
12473 | ||
12474 | When a library is built or rebuilt, an attempt is made first to delete all | |
7cd4527e AC |
12475 | files in the library directory. |
12476 | All @file{ALI} files will also be copied from the object directory to the | |
12477 | library directory. To build executables, @command{gnatmake} will use the | |
af4b9434 | 12478 | library rather than the individual object files. |
7cd4527e AC |
12479 | |
12480 | ||
12481 | @c ********************************************** | |
12482 | @c * Using Third-Party Libraries through Projects | |
12483 | @c ********************************************** | |
12484 | @node Using Third-Party Libraries through Projects | |
12485 | @section Using Third-Party Libraries through Projects | |
12486 | ||
12487 | Whether you are exporting your own library to make it available to | |
12488 | clients, or you are using a library provided by a third party, it is | |
12489 | convenient to have project files that automatically set the correct | |
12490 | command line switches for the compiler and linker. | |
12491 | ||
12492 | Such project files are very similar to the library project files; | |
12493 | @xref{Library Projects}. The only difference is that you set the | |
12494 | @code{Source_Dirs} and @code{Object_Dir} attribute so that they point to the | |
12495 | directories where, respectively, the sources and the read-only ALI files have | |
12496 | been installed. | |
12497 | ||
12498 | If you need to interface with a set of libraries, as opposed to a | |
12499 | single one, you need to create one library project for each of the | |
12500 | libraries. In addition, a top-level project that imports all these | |
12501 | library projects should be provided, so that the user of your library | |
12502 | has a single @code{with} clause to add to his own projects. | |
12503 | ||
12504 | For instance, let's assume you are providing two static libraries | |
12505 | @file{liba.a} and @file{libb.a}. The user needs to link with | |
12506 | both of these libraries. Each of these is associated with its | |
12507 | own set of header files. Let's assume furthermore that all the | |
12508 | header files for the two libraries have been installed in the same | |
12509 | directory @file{headers}. The @file{ALI} files are found in the same | |
12510 | @file{headers} directory. | |
12511 | ||
12512 | In this case, you should provide the following three projects: | |
12513 | ||
12514 | @smallexample @c projectfile | |
88e1739c | 12515 | @group |
7cd4527e AC |
12516 | with "liba", "libb"; |
12517 | project My_Library is | |
12518 | for Source_Dirs use ("headers"); | |
12519 | for Object_Dir use "headers"; | |
12520 | end My_Library; | |
88e1739c | 12521 | @end group |
88e1739c | 12522 | |
7cd4527e AC |
12523 | @group |
12524 | project Liba is | |
12525 | for Source_Dirs use (); | |
12526 | for Library_Dir use "lib"; | |
12527 | for Library_Name use "a"; | |
12528 | for Library_Kind use "static"; | |
12529 | end Liba; | |
12530 | @end group | |
88e1739c | 12531 | |
88e1739c | 12532 | @group |
7cd4527e AC |
12533 | project Libb is |
12534 | for Source_Dirs use (); | |
12535 | for Library_Dir use "lib"; | |
12536 | for Library_Name use "b"; | |
12537 | for Library_Kind use "static"; | |
12538 | end Libb; | |
88e1739c FW |
12539 | @end group |
12540 | @end smallexample | |
12541 | ||
7cd4527e AC |
12542 | @c ******************************* |
12543 | @c * Stand-alone Library Projects * | |
12544 | @c ******************************* | |
12545 | ||
12546 | @node Stand-alone Library Projects | |
12547 | @section Stand-alone Library Projects | |
12548 | ||
88e1739c | 12549 | @noindent |
7cd4527e AC |
12550 | A Stand-alone Library is a library that contains the necessary code to |
12551 | elaborate the Ada units that are included in the library. A Stand-alone | |
12552 | Library is suitable to be used in an executable when the main is not | |
12553 | in Ada. However, Stand-alone Libraries may also be used with an Ada main | |
12554 | subprogram. | |
88e1739c | 12555 | |
7cd4527e AC |
12556 | A Stand-alone Library Project is a Library Project where the library is |
12557 | a Stand-alone Library. | |
12558 | ||
12559 | To be a Stand-alone Library Project, in addition to the two attributes | |
12560 | that make a project a Library Project (@code{Library_Name} and | |
12561 | @code{Library_Dir}, see @ref{Library Projects}), the attribute | |
12562 | @code{Library_Interface} must be defined. | |
12563 | ||
12564 | @smallexample @c projectfile | |
88e1739c | 12565 | @group |
7cd4527e AC |
12566 | for Library_Dir use "lib_dir"; |
12567 | for Library_Name use "dummy"; | |
12568 | for Library_Interface use ("int1", "int1.child"); | |
88e1739c FW |
12569 | @end group |
12570 | @end smallexample | |
12571 | ||
7cd4527e AC |
12572 | Attribute @code{Library_Interface} has a non empty string list value, |
12573 | each string in the list designating a unit contained in an immediate source | |
12574 | of the project file. | |
12575 | ||
12576 | When a Stand-alone Library is built, first the binder is invoked to build | |
12577 | a package whose name depends on the library name | |
12578 | (^b~dummy.ads/b^B$DUMMY.ADS/B^ in the example above). | |
12579 | This binder-generated package includes initialization and | |
12580 | finalization procedures whose | |
12581 | names depend on the library name (dummyinit and dummyfinal in the example | |
12582 | above). The object corresponding to this package is included in the library. | |
12583 | ||
12584 | A dynamic or relocatable Stand-alone Library is automatically initialized | |
12585 | if automatic initialization of Stand-alone Libraries is supported on the | |
12586 | platform and if attribute @code{Library_Auto_Init} is not specified or | |
12587 | is specified with the value "true". A static Stand-alone Library is never | |
12588 | automatically initialized. | |
12589 | ||
12590 | Single string attribute @code{Library_Auto_Init} may be specified with only | |
12591 | two possible values: "false" or "true" (case-insensitive). Specifying | |
12592 | "false" for attribute @code{Library_Auto_Init} will prevent automatic | |
12593 | initialization of dynamic or relocatable libraries. | |
12594 | ||
12595 | When a non automatically initialized Stand-alone Library is used | |
12596 | in an executable, its initialization procedure must be called before | |
12597 | any service of the library is used. | |
12598 | When the main subprogram is in Ada, it may mean that the initialization | |
12599 | procedure has to be called during elaboration of another package. | |
12600 | ||
12601 | For a Stand-Alone Library, only the @file{ALI} files of the Interface Units | |
12602 | (those that are listed in attribute @code{Library_Interface}) are copied to | |
12603 | the Library Directory. As a consequence, only the Interface Units may be | |
12604 | imported from Ada units outside of the library. If other units are imported, | |
12605 | the binding phase will fail. | |
12606 | ||
12607 | When a Stand-Alone Library is bound, the switches that are specified in | |
12608 | the attribute @code{Default_Switches ("Ada")} in package @code{Binder} are | |
12609 | used in the call to @command{gnatbind}. | |
12610 | ||
12611 | The string list attribute @code{Library_Options} may be used to specified | |
12612 | additional switches to the call to @command{gcc} to link the library. | |
12613 | ||
12614 | The attribute @code{Library_Src_Dir}, may be specified for a | |
12615 | Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a | |
12616 | single string value. Its value must be the path (absolute or relative to the | |
12617 | project directory) of an existing directory. This directory cannot be the | |
12618 | object directory or one of the source directories, but it can be the same as | |
12619 | the library directory. The sources of the Interface | |
12620 | Units of the library, necessary to an Ada client of the library, will be | |
12621 | copied to the designated directory, called Interface Copy directory. | |
12622 | These sources includes the specs of the Interface Units, but they may also | |
12623 | include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always} | |
12624 | are used, or when there is a generic units in the spec. Before the sources | |
12625 | are copied to the Interface Copy directory, an attempt is made to delete all | |
12626 | files in the Interface Copy directory. | |
12627 | ||
12628 | @c ************************************* | |
12629 | @c * Switches Related to Project Files * | |
12630 | @c ************************************* | |
12631 | @node Switches Related to Project Files | |
12632 | @section Switches Related to Project Files | |
12633 | ||
88e1739c | 12634 | @noindent |
7cd4527e | 12635 | The following switches are used by GNAT tools that support project files: |
88e1739c | 12636 | |
7cd4527e | 12637 | @table @option |
88e1739c | 12638 | |
7cd4527e AC |
12639 | @item ^-P^/PROJECT_FILE=^@var{project} |
12640 | @cindex @option{^-P^/PROJECT_FILE^} (any tool supporting project files) | |
12641 | Indicates the name of a project file. This project file will be parsed with | |
12642 | the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}}, | |
12643 | if any, and using the external references indicated | |
12644 | by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any. | |
12645 | @ifclear vms | |
12646 | There may zero, one or more spaces between @option{-P} and @var{project}. | |
12647 | @end ifclear | |
88e1739c | 12648 | |
7cd4527e AC |
12649 | @noindent |
12650 | There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line. | |
88e1739c FW |
12651 | |
12652 | @noindent | |
7cd4527e AC |
12653 | Since the Project Manager parses the project file only after all the switches |
12654 | on the command line are checked, the order of the switches | |
12655 | @option{^-P^/PROJECT_FILE^}, | |
12656 | @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} | |
12657 | or @option{^-X^/EXTERNAL_REFERENCE^} is not significant. | |
88e1739c | 12658 | |
7cd4527e AC |
12659 | @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} |
12660 | @cindex @option{^-X^/EXTERNAL_REFERENCE^} (any tool supporting project files) | |
12661 | Indicates that external variable @var{name} has the value @var{value}. | |
12662 | The Project Manager will use this value for occurrences of | |
12663 | @code{external(name)} when parsing the project file. | |
88e1739c | 12664 | |
7cd4527e AC |
12665 | @ifclear vms |
12666 | @noindent | |
12667 | If @var{name} or @var{value} includes a space, then @var{name=value} should be | |
12668 | put between quotes. | |
12669 | @smallexample | |
12670 | -XOS=NT | |
12671 | -X"user=John Doe" | |
12672 | @end smallexample | |
12673 | @end ifclear | |
88e1739c | 12674 | |
7cd4527e AC |
12675 | @noindent |
12676 | Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously. | |
12677 | If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same | |
12678 | @var{name}, only the last one is used. | |
88e1739c | 12679 | |
7cd4527e AC |
12680 | @noindent |
12681 | An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch | |
12682 | takes precedence over the value of the same name in the environment. | |
88e1739c | 12683 | |
7cd4527e AC |
12684 | @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} |
12685 | @cindex @code{^-vP^/MESSAGES_PROJECT_FILE^} (any tool supporting project files) | |
12686 | @c Previous line uses code vs option command, to stay less than 80 chars | |
12687 | Indicates the verbosity of the parsing of GNAT project files. | |
12688 | ||
12689 | @ifclear vms | |
12690 | @option{-vP0} means Default; | |
12691 | @option{-vP1} means Medium; | |
12692 | @option{-vP2} means High. | |
12693 | @end ifclear | |
12694 | ||
12695 | @ifset vms | |
12696 | There are three possible options for this qualifier: DEFAULT, MEDIUM and | |
12697 | HIGH. | |
12698 | @end ifset | |
12699 | ||
12700 | @noindent | |
12701 | The default is ^Default^DEFAULT^: no output for syntactically correct | |
12702 | project files. | |
12703 | @noindent | |
12704 | If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present, | |
12705 | only the last one is used. | |
88e1739c | 12706 | |
88e1739c FW |
12707 | @end table |
12708 | ||
7cd4527e AC |
12709 | @c ********************************** |
12710 | @c * Tools Supporting Project Files * | |
12711 | @c ********************************** | |
12712 | ||
12713 | @node Tools Supporting Project Files | |
12714 | @section Tools Supporting Project Files | |
12715 | ||
12716 | @menu | |
12717 | * gnatmake and Project Files:: | |
12718 | * The GNAT Driver and Project Files:: | |
12719 | @ifclear vms | |
12720 | * Glide and Project Files:: | |
12721 | @end ifclear | |
12722 | @end menu | |
12723 | ||
12724 | @node gnatmake and Project Files | |
12725 | @subsection gnatmake and Project Files | |
12726 | ||
88e1739c | 12727 | @noindent |
7cd4527e AC |
12728 | This section covers several topics related to @command{gnatmake} and |
12729 | project files: defining ^switches^switches^ for @command{gnatmake} | |
12730 | and for the tools that it invokes; specifying configuration pragmas; | |
12731 | the use of the @code{Main} attribute; building and rebuilding library project | |
12732 | files. | |
88e1739c | 12733 | |
7cd4527e AC |
12734 | @menu |
12735 | * ^Switches^Switches^ and Project Files:: | |
12736 | * Specifying Configuration Pragmas:: | |
12737 | * Project Files and Main Subprograms:: | |
12738 | * Library Project Files:: | |
12739 | @end menu | |
88e1739c | 12740 | |
7cd4527e AC |
12741 | @node ^Switches^Switches^ and Project Files |
12742 | @subsubsection ^Switches^Switches^ and Project Files | |
88e1739c | 12743 | |
7cd4527e AC |
12744 | @ifset vms |
12745 | It is not currently possible to specify VMS style qualifiers in the project | |
12746 | files; only Unix style ^switches^switches^ may be specified. | |
12747 | @end ifset | |
88e1739c FW |
12748 | |
12749 | @noindent | |
7cd4527e AC |
12750 | For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and |
12751 | @code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^} | |
12752 | attribute, a @code{^Switches^Switches^} attribute, or both; | |
12753 | as their names imply, these ^switch^switch^-related | |
12754 | attributes affect the ^switches^switches^ that are used for each of these GNAT | |
12755 | components when | |
12756 | @command{gnatmake} is invoked. As will be explained below, these | |
12757 | component-specific ^switches^switches^ precede | |
12758 | the ^switches^switches^ provided on the @command{gnatmake} command line. | |
88e1739c | 12759 | |
7cd4527e AC |
12760 | The @code{^Default_Switches^Default_Switches^} attribute is an associative |
12761 | array indexed by language name (case insensitive) whose value is a string list. | |
12762 | For example: | |
88e1739c | 12763 | |
7cd4527e AC |
12764 | @smallexample @c projectfile |
12765 | @group | |
12766 | package Compiler is | |
12767 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12768 | use ("^-gnaty^-gnaty^", | |
12769 | "^-v^-v^"); | |
12770 | end Compiler; | |
12771 | @end group | |
12772 | @end smallexample | |
88e1739c | 12773 | |
7cd4527e AC |
12774 | @noindent |
12775 | The @code{^Switches^Switches^} attribute is also an associative array, | |
12776 | indexed by a file name (which may or may not be case sensitive, depending | |
12777 | on the operating system) whose value is a string list. For example: | |
12778 | ||
12779 | @smallexample @c projectfile | |
88e1739c | 12780 | @group |
7cd4527e AC |
12781 | package Builder is |
12782 | for ^Switches^Switches^ ("main1.adb") | |
12783 | use ("^-O2^-O2^"); | |
12784 | for ^Switches^Switches^ ("main2.adb") | |
12785 | use ("^-g^-g^"); | |
12786 | end Builder; | |
88e1739c FW |
12787 | @end group |
12788 | @end smallexample | |
12789 | ||
12790 | @noindent | |
7cd4527e AC |
12791 | For the @code{Builder} package, the file names must designate source files |
12792 | for main subprograms. For the @code{Binder} and @code{Linker} packages, the | |
12793 | file names must designate @file{ALI} or source files for main subprograms. | |
12794 | In each case just the file name without an explicit extension is acceptable. | |
88e1739c | 12795 | |
7cd4527e AC |
12796 | For each tool used in a program build (@command{gnatmake}, the compiler, the |
12797 | binder, and the linker), the corresponding package @dfn{contributes} a set of | |
12798 | ^switches^switches^ for each file on which the tool is invoked, based on the | |
12799 | ^switch^switch^-related attributes defined in the package. | |
12800 | In particular, the ^switches^switches^ | |
12801 | that each of these packages contributes for a given file @var{f} comprise: | |
88e1739c | 12802 | |
7cd4527e AC |
12803 | @itemize @bullet |
12804 | @item | |
12805 | the value of attribute @code{^Switches^Switches^ (@var{f})}, | |
12806 | if it is specified in the package for the given file, | |
12807 | @item | |
12808 | otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")}, | |
12809 | if it is specified in the package. | |
12810 | @end itemize | |
88e1739c | 12811 | |
7cd4527e AC |
12812 | @noindent |
12813 | If neither of these attributes is defined in the package, then the package does | |
12814 | not contribute any ^switches^switches^ for the given file. | |
12815 | ||
12816 | When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise | |
12817 | two sets, in the following order: those contributed for the file | |
12818 | by the @code{Builder} package; | |
12819 | and the switches passed on the command line. | |
12820 | ||
12821 | When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file, | |
12822 | the ^switches^switches^ passed to the tool comprise three sets, | |
12823 | in the following order: | |
12824 | ||
12825 | @enumerate | |
12826 | @item | |
12827 | the applicable ^switches^switches^ contributed for the file | |
12828 | by the @code{Builder} package in the project file supplied on the command line; | |
12829 | ||
12830 | @item | |
12831 | those contributed for the file by the package (in the relevant project file -- | |
12832 | see below) corresponding to the tool; and | |
12833 | ||
12834 | @item | |
12835 | the applicable switches passed on the command line. | |
12836 | @end enumerate | |
88e1739c FW |
12837 | |
12838 | @noindent | |
7cd4527e AC |
12839 | The term @emph{applicable ^switches^switches^} reflects the fact that |
12840 | @command{gnatmake} ^switches^switches^ may or may not be passed to individual | |
12841 | tools, depending on the individual ^switch^switch^. | |
88e1739c | 12842 | |
7cd4527e AC |
12843 | @command{gnatmake} may invoke the compiler on source files from different |
12844 | projects. The Project Manager will use the appropriate project file to | |
12845 | determine the @code{Compiler} package for each source file being compiled. | |
12846 | Likewise for the @code{Binder} and @code{Linker} packages. | |
12847 | ||
12848 | As an example, consider the following package in a project file: | |
12849 | ||
12850 | @smallexample @c projectfile | |
88e1739c | 12851 | @group |
7cd4527e AC |
12852 | project Proj1 is |
12853 | package Compiler is | |
12854 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12855 | use ("^-g^-g^"); | |
12856 | for ^Switches^Switches^ ("a.adb") | |
12857 | use ("^-O1^-O1^"); | |
12858 | for ^Switches^Switches^ ("b.adb") | |
12859 | use ("^-O2^-O2^", | |
12860 | "^-gnaty^-gnaty^"); | |
12861 | end Compiler; | |
12862 | end Proj1; | |
88e1739c FW |
12863 | @end group |
12864 | @end smallexample | |
12865 | ||
12866 | @noindent | |
7cd4527e AC |
12867 | If @command{gnatmake} is invoked with this project file, and it needs to |
12868 | compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then | |
12869 | @file{a.adb} will be compiled with the ^switch^switch^ | |
12870 | @option{^-O1^-O1^}, | |
12871 | @file{b.adb} with ^switches^switches^ | |
12872 | @option{^-O2^-O2^} | |
12873 | and @option{^-gnaty^-gnaty^}, | |
12874 | and @file{c.adb} with @option{^-g^-g^}. | |
88e1739c | 12875 | |
7cd4527e AC |
12876 | The following example illustrates the ordering of the ^switches^switches^ |
12877 | contributed by different packages: | |
88e1739c | 12878 | |
7cd4527e AC |
12879 | @smallexample @c projectfile |
12880 | @group | |
12881 | project Proj2 is | |
12882 | package Builder is | |
12883 | for ^Switches^Switches^ ("main.adb") | |
12884 | use ("^-g^-g^", | |
12885 | "^-O1^-)1^", | |
12886 | "^-f^-f^"); | |
12887 | end Builder; | |
12888 | @end group | |
88e1739c | 12889 | |
7cd4527e AC |
12890 | @group |
12891 | package Compiler is | |
12892 | for ^Switches^Switches^ ("main.adb") | |
12893 | use ("^-O2^-O2^"); | |
12894 | end Compiler; | |
12895 | end Proj2; | |
12896 | @end group | |
12897 | @end smallexample | |
88e1739c | 12898 | |
7cd4527e AC |
12899 | @noindent |
12900 | If you issue the command: | |
88e1739c FW |
12901 | |
12902 | @smallexample | |
7cd4527e | 12903 | gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main |
88e1739c FW |
12904 | @end smallexample |
12905 | ||
12906 | @noindent | |
7cd4527e AC |
12907 | then the compiler will be invoked on @file{main.adb} with the following |
12908 | sequence of ^switches^switches^ | |
88e1739c | 12909 | |
7cd4527e AC |
12910 | @smallexample |
12911 | ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^ | |
12912 | @end smallexample | |
88e1739c | 12913 | |
7cd4527e AC |
12914 | with the last @option{^-O^-O^} |
12915 | ^switch^switch^ having precedence over the earlier ones; | |
12916 | several other ^switches^switches^ | |
12917 | (such as @option{^-c^-c^}) are added implicitly. | |
88e1739c | 12918 | |
7cd4527e AC |
12919 | The ^switches^switches^ |
12920 | @option{^-g^-g^} | |
12921 | and @option{^-O1^-O1^} are contributed by package | |
12922 | @code{Builder}, @option{^-O2^-O2^} is contributed | |
12923 | by the package @code{Compiler} | |
12924 | and @option{^-O0^-O0^} comes from the command line. | |
88e1739c | 12925 | |
7cd4527e AC |
12926 | The @option{^-g^-g^} |
12927 | ^switch^switch^ will also be passed in the invocation of | |
12928 | @command{Gnatlink.} | |
88e1739c | 12929 | |
7cd4527e AC |
12930 | A final example illustrates switch contributions from packages in different |
12931 | project files: | |
88e1739c | 12932 | |
7cd4527e AC |
12933 | @smallexample @c projectfile |
12934 | @group | |
12935 | project Proj3 is | |
12936 | for Source_Files use ("pack.ads", "pack.adb"); | |
12937 | package Compiler is | |
12938 | for ^Default_Switches^Default_Switches^ ("Ada") | |
12939 | use ("^-gnata^-gnata^"); | |
12940 | end Compiler; | |
12941 | end Proj3; | |
12942 | @end group | |
88e1739c | 12943 | |
7cd4527e AC |
12944 | @group |
12945 | with "Proj3"; | |
12946 | project Proj4 is | |
12947 | for Source_Files use ("foo_main.adb", "bar_main.adb"); | |
12948 | package Builder is | |
12949 | for ^Switches^Switches^ ("foo_main.adb") | |
12950 | use ("^-s^-s^", | |
12951 | "^-g^-g^"); | |
12952 | end Builder; | |
12953 | end Proj4; | |
12954 | @end group | |
88e1739c | 12955 | |
7cd4527e AC |
12956 | @group |
12957 | -- Ada source file: | |
12958 | with Pack; | |
12959 | procedure Foo_Main is | |
12960 | ... | |
12961 | end Foo_Main; | |
12962 | @end group | |
12963 | @end smallexample | |
88e1739c | 12964 | |
7cd4527e AC |
12965 | If the command is |
12966 | @smallexample | |
12967 | gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato | |
12968 | @end smallexample | |
12969 | ||
12970 | @noindent | |
12971 | then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are | |
12972 | @option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and | |
12973 | @option{^-gnato^-gnato^} (passed on the command line). | |
12974 | When the imported package @code{Pack} is compiled, the ^switches^switches^ used | |
12975 | are @option{^-g^-g^} from @code{Proj4.Builder}, | |
12976 | @option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler}, | |
12977 | and @option{^-gnato^-gnato^} from the command line. | |
12978 | ||
12979 | @noindent | |
12980 | When using @command{gnatmake} with project files, some ^switches^switches^ or | |
12981 | arguments may be expressed as relative paths. As the working directory where | |
12982 | compilation occurs may change, these relative paths are converted to absolute | |
12983 | paths. For the ^switches^switches^ found in a project file, the relative paths | |
12984 | are relative to the project file directory, for the switches on the command | |
12985 | line, they are relative to the directory where @command{gnatmake} is invoked. | |
12986 | The ^switches^switches^ for which this occurs are: | |
12987 | ^-I^-I^, | |
12988 | ^-A^-A^, | |
12989 | ^-L^-L^, | |
12990 | ^-aO^-aO^, | |
12991 | ^-aL^-aL^, | |
12992 | ^-aI^-aI^, as well as all arguments that are not switches (arguments to | |
12993 | ^switch^switch^ | |
12994 | ^-o^-o^, object files specified in package @code{Linker} or after | |
12995 | -largs on the command line). The exception to this rule is the ^switch^switch^ | |
12996 | ^--RTS=^--RTS=^ for which a relative path argument is never converted. | |
12997 | ||
12998 | @node Specifying Configuration Pragmas | |
12999 | @subsubsection Specifying Configuration Pragmas | |
13000 | ||
13001 | When using @command{gnatmake} with project files, if there exists a file | |
13002 | @file{gnat.adc} that contains configuration pragmas, this file will be | |
13003 | ignored. | |
13004 | ||
13005 | Configuration pragmas can be defined by means of the following attributes in | |
13006 | project files: @code{Global_Configuration_Pragmas} in package @code{Builder} | |
13007 | and @code{Local_Configuration_Pragmas} in package @code{Compiler}. | |
13008 | ||
13009 | Both these attributes are single string attributes. Their values is the path | |
13010 | name of a file containing configuration pragmas. If a path name is relative, | |
13011 | then it is relative to the project directory of the project file where the | |
13012 | attribute is defined. | |
13013 | ||
13014 | When compiling a source, the configuration pragmas used are, in order, | |
13015 | those listed in the file designated by attribute | |
13016 | @code{Global_Configuration_Pragmas} in package @code{Builder} of the main | |
13017 | project file, if it is specified, and those listed in the file designated by | |
13018 | attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of | |
13019 | the project file of the source, if it exists. | |
88e1739c | 13020 | |
7cd4527e AC |
13021 | @node Project Files and Main Subprograms |
13022 | @subsubsection Project Files and Main Subprograms | |
88e1739c FW |
13023 | |
13024 | @noindent | |
7cd4527e AC |
13025 | When using a project file, you can invoke @command{gnatmake} |
13026 | with one or several main subprograms, by specifying their source files on the | |
13027 | command line. | |
88e1739c FW |
13028 | |
13029 | @smallexample | |
7cd4527e AC |
13030 | gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3 |
13031 | @end smallexample | |
88e1739c | 13032 | |
7cd4527e AC |
13033 | @noindent |
13034 | Each of these needs to be a source file of the same project, except | |
13035 | when the switch ^-u^/UNIQUE^ is used. | |
88e1739c | 13036 | |
7cd4527e AC |
13037 | @noindent |
13038 | When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the | |
13039 | same project, one of the project in the tree rooted at the project specified | |
13040 | on the command line. The package @code{Builder} of this common project, the | |
13041 | "main project" is the one that is considered by @command{gnatmake}. | |
13042 | ||
13043 | @noindent | |
13044 | When ^-u^/UNIQUE^ is used, the specified source files may be in projects | |
13045 | imported directly or indirectly by the project specified on the command line. | |
13046 | Note that if such a source file is not part of the project specified on the | |
13047 | command line, the ^switches^switches^ found in package @code{Builder} of the | |
13048 | project specified on the command line, if any, that are transmitted | |
13049 | to the compiler will still be used, not those found in the project file of | |
13050 | the source file. | |
13051 | ||
13052 | @noindent | |
13053 | When using a project file, you can also invoke @command{gnatmake} without | |
13054 | explicitly specifying any main, and the effect depends on whether you have | |
13055 | defined the @code{Main} attribute. This attribute has a string list value, | |
13056 | where each element in the list is the name of a source file (the file | |
13057 | extension is optional) that contains a unit that can be a main subprogram. | |
13058 | ||
13059 | If the @code{Main} attribute is defined in a project file as a non-empty | |
13060 | string list and the switch @option{^-u^/UNIQUE^} is not used on the command | |
13061 | line, then invoking @command{gnatmake} with this project file but without any | |
13062 | main on the command line is equivalent to invoking @command{gnatmake} with all | |
13063 | the file names in the @code{Main} attribute on the command line. | |
13064 | ||
13065 | Example: | |
13066 | @smallexample @c projectfile | |
13067 | @group | |
13068 | project Prj is | |
13069 | for Main use ("main1", "main2", "main3"); | |
13070 | end Prj; | |
88e1739c FW |
13071 | @end group |
13072 | @end smallexample | |
13073 | ||
13074 | @noindent | |
7cd4527e AC |
13075 | With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"} |
13076 | is equivalent to | |
13077 | @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}. | |
88e1739c | 13078 | |
7cd4527e AC |
13079 | When the project attribute @code{Main} is not specified, or is specified |
13080 | as an empty string list, or when the switch @option{-u} is used on the command | |
13081 | line, then invoking @command{gnatmake} with no main on the command line will | |
13082 | result in all immediate sources of the project file being checked, and | |
13083 | potentially recompiled. Depending on the presence of the switch @option{-u}, | |
13084 | sources from other project files on which the immediate sources of the main | |
13085 | project file depend are also checked and potentially recompiled. In other | |
13086 | words, the @option{-u} switch is applied to all of the immediate sources of the | |
13087 | main project file. | |
88e1739c | 13088 | |
7cd4527e AC |
13089 | When no main is specified on the command line and attribute @code{Main} exists |
13090 | and includes several mains, or when several mains are specified on the | |
13091 | command line, the default ^switches^switches^ in package @code{Builder} will | |
13092 | be used for all mains, even if there are specific ^switches^switches^ | |
13093 | specified for one or several mains. | |
13094 | ||
13095 | But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be | |
13096 | the specific ^switches^switches^ for each main, if they are specified. | |
13097 | ||
13098 | @node Library Project Files | |
13099 | @subsubsection Library Project Files | |
88e1739c FW |
13100 | |
13101 | @noindent | |
7cd4527e AC |
13102 | When @command{gnatmake} is invoked with a main project file that is a library |
13103 | project file, it is not allowed to specify one or more mains on the command | |
13104 | line. | |
88e1739c | 13105 | |
7cd4527e AC |
13106 | @noindent |
13107 | When a library project file is specified, switches ^-b^/ACTION=BIND^ and | |
13108 | ^-l^/ACTION=LINK^ have special meanings. | |
88e1739c | 13109 | |
7cd4527e AC |
13110 | @itemize @bullet |
13111 | @item ^-b^/ACTION=BIND^ is only allwed for stand-alone libraries. It indicates | |
13112 | to @command{gnatmake} that @command{gnatbind} should be invoked for the | |
13113 | library. | |
88e1739c | 13114 | |
7cd4527e AC |
13115 | @item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates |
13116 | to @command{gnatmake} that the binder generated file should be compiled | |
13117 | (in the case of a stand-alone library) and that the library should be built. | |
88e1739c | 13118 | |
7cd4527e AC |
13119 | @end itemize |
13120 | ||
13121 | @node The GNAT Driver and Project Files | |
13122 | @subsection The GNAT Driver and Project Files | |
88e1739c FW |
13123 | |
13124 | @noindent | |
7cd4527e AC |
13125 | A number of GNAT tools, other than @command{^gnatmake^gnatmake^} |
13126 | are project-aware: | |
13127 | @command{^gnatbind^gnatbind^}, | |
13128 | @command{^gnatfind^gnatfind^}, | |
13129 | @command{^gnatlink^gnatlink^}, | |
13130 | @command{^gnatls^gnatls^}, | |
13131 | @command{^gnatelim^gnatelim^}, | |
13132 | @command{^gnatpp^gnatpp^}, | |
13133 | and @command{^gnatxref^gnatxref^}. However, none of these tools can be invoked | |
13134 | directly with a project file switch (@option{^-P^/PROJECT_FILE=^}). | |
13135 | They must be invoked through the @command{gnat} driver. | |
88e1739c | 13136 | |
7cd4527e AC |
13137 | The @command{gnat} driver is a front-end that accepts a number of commands and |
13138 | call the corresponding tool. It has been designed initially for VMS to convert | |
13139 | VMS style qualifiers to Unix style switches, but it is now available to all | |
13140 | the GNAT supported platforms. | |
88e1739c | 13141 | |
7cd4527e AC |
13142 | On non VMS platforms, the @command{gnat} driver accepts the following commands |
13143 | (case insensitive): | |
88e1739c | 13144 | |
7cd4527e AC |
13145 | @itemize @bullet |
13146 | @item | |
13147 | BIND to invoke @command{^gnatbind^gnatbind^} | |
13148 | @item | |
13149 | CHOP to invoke @command{^gnatchop^gnatchop^} | |
13150 | @item | |
13151 | CLEAN to invoke @command{^gnatclean^gnatclean^} | |
13152 | @item | |
13153 | COMP or COMPILE to invoke the compiler | |
13154 | @item | |
13155 | ELIM to invoke @command{^gnatelim^gnatelim^} | |
13156 | @item | |
13157 | FIND to invoke @command{^gnatfind^gnatfind^} | |
13158 | @item | |
13159 | KR or KRUNCH to invoke @command{^gnatkr^gnatkr^} | |
13160 | @item | |
13161 | LINK to invoke @command{^gnatlink^gnatlink^} | |
13162 | @item | |
13163 | LS or LIST to invoke @command{^gnatls^gnatls^} | |
13164 | @item | |
13165 | MAKE to invoke @command{^gnatmake^gnatmake^} | |
13166 | @item | |
13167 | NAME to invoke @command{^gnatname^gnatname^} | |
13168 | @item | |
13169 | PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^} | |
13170 | @item | |
13171 | PP or PRETTY to invoke @command{^gnatpp^gnatpp^} | |
13172 | @item | |
13173 | STUB to invoke @command{^gnatstub^gnatstub^} | |
13174 | @item | |
13175 | XREF to invoke @command{^gnatxref^gnatxref^} | |
13176 | @end itemize | |
88e1739c | 13177 | |
7cd4527e AC |
13178 | @noindent |
13179 | Note that the compiler is invoked using the command | |
13180 | @command{^gnatmake -f -u -c^gnatmake -f -u -c^}. | |
88e1739c FW |
13181 | |
13182 | @noindent | |
7cd4527e AC |
13183 | The command may be followed by switches and arguments for the invoked |
13184 | tool. | |
88e1739c FW |
13185 | |
13186 | @smallexample | |
7cd4527e AC |
13187 | gnat bind -C main.ali |
13188 | gnat ls -a main | |
13189 | gnat chop foo.txt | |
88e1739c FW |
13190 | @end smallexample |
13191 | ||
13192 | @noindent | |
7cd4527e AC |
13193 | Switches may also be put in text files, one switch per line, and the text |
13194 | files may be specified with their path name preceded by '@@'. | |
88e1739c FW |
13195 | |
13196 | @smallexample | |
7cd4527e | 13197 | gnat bind @@args.txt main.ali |
88e1739c FW |
13198 | @end smallexample |
13199 | ||
13200 | @noindent | |
7cd4527e AC |
13201 | In addition, for command BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK, |
13202 | PP or PRETTY and XREF, the project file related switches | |
13203 | (@option{^-P^/PROJECT_FILE^}, | |
13204 | @option{^-X^/EXTERNAL_REFERENCE^} and | |
13205 | @option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to | |
13206 | the switches of the invoking tool. | |
88e1739c | 13207 | |
7cd4527e AC |
13208 | @noindent |
13209 | When GNAT PP or GNAT PRETTY is used with a project file, but with no source | |
13210 | specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all | |
13211 | the immediate sources of the specified project file. | |
13212 | ||
13213 | @noindent | |
13214 | For each of these commands, there is optionally a corresponding package | |
13215 | in the main project. | |
88e1739c FW |
13216 | |
13217 | @itemize @bullet | |
13218 | @item | |
7cd4527e | 13219 | package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^}) |
88e1739c FW |
13220 | |
13221 | @item | |
7cd4527e | 13222 | package @code{Compiler} for command COMP or COMPILE (invoking the compiler) |
88e1739c FW |
13223 | |
13224 | @item | |
7cd4527e | 13225 | package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^}) |
88e1739c | 13226 | |
7cd4527e AC |
13227 | @item |
13228 | package @code{Eliminate} for command ELIM (invoking | |
13229 | @code{^gnatelim^gnatelim^}) | |
88e1739c | 13230 | |
7cd4527e AC |
13231 | @item |
13232 | package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^}) | |
88e1739c | 13233 | |
7cd4527e AC |
13234 | @item |
13235 | package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^}) | |
88e1739c | 13236 | |
7cd4527e AC |
13237 | @item |
13238 | package @code{Pretty_Printer} for command PP or PRETTY | |
13239 | (invoking @code{^gnatpp^gnatpp^}) | |
88e1739c | 13240 | |
7cd4527e AC |
13241 | @item |
13242 | package @code{Cross_Reference} for command XREF (invoking | |
13243 | @code{^gnatxref^gnatxref^}) | |
88e1739c | 13244 | |
7cd4527e AC |
13245 | @end itemize |
13246 | ||
13247 | @noindent | |
13248 | Package @code{Gnatls} has a unique attribute @code{^Switches^Switches^}, | |
13249 | a simple variable with a string list value. It contains ^switches^switches^ | |
13250 | for the invocation of @code{^gnatls^gnatls^}. | |
13251 | ||
13252 | @smallexample @c projectfile | |
13253 | @group | |
13254 | project Proj1 is | |
13255 | package gnatls is | |
13256 | for ^Switches^Switches^ | |
13257 | use ("^-a^-a^", | |
13258 | "^-v^-v^"); | |
13259 | end gnatls; | |
13260 | end Proj1; | |
88e1739c | 13261 | @end group |
88e1739c FW |
13262 | @end smallexample |
13263 | ||
13264 | @noindent | |
7cd4527e AC |
13265 | All other packages have two attribute @code{^Switches^Switches^} and |
13266 | @code{^Default_Switches^Default_Switches^}. | |
88e1739c | 13267 | |
7cd4527e AC |
13268 | @noindent |
13269 | @code{^Switches^Switches^} is an associated array attribute, indexed by the | |
13270 | source file name, that has a string list value: the ^switches^switches^ to be | |
13271 | used when the tool corresponding to the package is invoked for the specific | |
13272 | source file. | |
88e1739c FW |
13273 | |
13274 | @noindent | |
7cd4527e AC |
13275 | @code{^Default_Switches^Default_Switches^} is an associative array attribute, |
13276 | indexed by the programming language that has a string list value. | |
13277 | @code{^Default_Switches^Default_Switches^ ("Ada")} contains the | |
13278 | ^switches^switches^ for the invocation of the tool corresponding | |
13279 | to the package, except if a specific @code{^Switches^Switches^} attribute | |
13280 | is specified for the source file. | |
88e1739c | 13281 | |
7cd4527e | 13282 | @smallexample @c projectfile |
88e1739c | 13283 | @group |
7cd4527e | 13284 | project Proj is |
88e1739c | 13285 | |
7cd4527e | 13286 | for Source_Dirs use ("./**"); |
88e1739c | 13287 | |
7cd4527e AC |
13288 | package gnatls is |
13289 | for ^Switches^Switches^ use | |
13290 | ("^-a^-a^", | |
13291 | "^-v^-v^"); | |
13292 | end gnatls; | |
13293 | @end group | |
13294 | @group | |
88e1739c | 13295 | |
7cd4527e AC |
13296 | package Compiler is |
13297 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13298 | use ("^-gnatv^-gnatv^", | |
13299 | "^-gnatwa^-gnatwa^"); | |
13300 | end Binder; | |
88e1739c | 13301 | @end group |
7cd4527e | 13302 | @group |
88e1739c | 13303 | |
7cd4527e AC |
13304 | package Binder is |
13305 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13306 | use ("^-C^-C^", | |
13307 | "^-e^-e^"); | |
13308 | end Binder; | |
13309 | @end group | |
13310 | @group | |
88e1739c | 13311 | |
7cd4527e AC |
13312 | package Linker is |
13313 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13314 | use ("^-C^-C^"); | |
13315 | for ^Switches^Switches^ ("main.adb") | |
13316 | use ("^-C^-C^", | |
13317 | "^-v^-v^", | |
13318 | "^-v^-v^"); | |
13319 | end Linker; | |
13320 | @end group | |
13321 | @group | |
88e1739c | 13322 | |
7cd4527e AC |
13323 | package Finder is |
13324 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13325 | use ("^-a^-a^", | |
13326 | "^-f^-f^"); | |
13327 | end Finder; | |
13328 | @end group | |
13329 | @group | |
88e1739c | 13330 | |
7cd4527e AC |
13331 | package Cross_Reference is |
13332 | for ^Default_Switches^Default_Switches^ ("Ada") | |
13333 | use ("^-a^-a^", | |
13334 | "^-f^-f^", | |
13335 | "^-d^-d^", | |
13336 | "^-u^-u^"); | |
13337 | end Cross_Reference; | |
13338 | end Proj; | |
13339 | @end group | |
13340 | @end smallexample | |
88e1739c FW |
13341 | |
13342 | @noindent | |
7cd4527e | 13343 | With the above project file, commands such as |
88e1739c | 13344 | |
7cd4527e AC |
13345 | @smallexample |
13346 | ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^ | |
13347 | ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^ | |
13348 | ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^ | |
13349 | ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^ | |
13350 | ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^ | |
13351 | @end smallexample | |
88e1739c FW |
13352 | |
13353 | @noindent | |
7cd4527e AC |
13354 | will set up the environment properly and invoke the tool with the switches |
13355 | found in the package corresponding to the tool: | |
13356 | @code{^Default_Switches^Default_Switches^ ("Ada")} for all tools, | |
13357 | except @code{^Switches^Switches^ ("main.adb")} | |
13358 | for @code{^gnatlink^gnatlink^}. | |
88e1739c | 13359 | |
7cd4527e AC |
13360 | @ifclear vms |
13361 | @node Glide and Project Files | |
13362 | @subsection Glide and Project Files | |
88e1739c | 13363 | |
7cd4527e AC |
13364 | @noindent |
13365 | Glide will automatically recognize the @file{.gpr} extension for | |
13366 | project files, and will | |
13367 | convert them to its own internal format automatically. However, it | |
13368 | doesn't provide a syntax-oriented editor for modifying these | |
13369 | files. | |
13370 | The project file will be loaded as text when you select the menu item | |
13371 | @code{Ada} @result{} @code{Project} @result{} @code{Edit}. | |
13372 | You can edit this text and save the @file{gpr} file; | |
13373 | when you next select this project file in Glide it | |
13374 | will be automatically reloaded. | |
13375 | @end ifclear | |
88e1739c | 13376 | |
7cd4527e AC |
13377 | @c ********************** |
13378 | @node An Extended Example | |
13379 | @section An Extended Example | |
13380 | ||
13381 | @noindent | |
13382 | Suppose that we have two programs, @var{prog1} and @var{prog2}, | |
13383 | whose sources are in corresponding directories. We would like | |
13384 | to build them with a single @command{gnatmake} command, and we want to place | |
13385 | their object files into @file{build} subdirectories of the source directories. | |
13386 | Furthermore, we want to have to have two separate subdirectories | |
13387 | in @file{build} -- @file{release} and @file{debug} -- which will contain | |
13388 | the object files compiled with different set of compilation flags. | |
13389 | ||
13390 | In other words, we have the following structure: | |
88e1739c FW |
13391 | |
13392 | @smallexample | |
13393 | @group | |
7cd4527e AC |
13394 | main |
13395 | |- prog1 | |
13396 | | |- build | |
13397 | | | debug | |
13398 | | | release | |
13399 | |- prog2 | |
13400 | |- build | |
13401 | | debug | |
13402 | | release | |
88e1739c FW |
13403 | @end group |
13404 | @end smallexample | |
13405 | ||
13406 | @noindent | |
7cd4527e AC |
13407 | Here are the project files that we must place in a directory @file{main} |
13408 | to maintain this structure: | |
13409 | ||
13410 | @enumerate | |
13411 | ||
13412 | @item We create a @code{Common} project with a package @code{Compiler} that | |
13413 | specifies the compilation ^switches^switches^: | |
88e1739c FW |
13414 | |
13415 | @smallexample | |
7cd4527e | 13416 | File "common.gpr": |
88e1739c | 13417 | @group |
7cd4527e | 13418 | @b{project} Common @b{is} |
88e1739c | 13419 | |
7cd4527e AC |
13420 | @b{for} Source_Dirs @b{use} (); -- No source files |
13421 | @end group | |
13422 | ||
13423 | @group | |
13424 | @b{type} Build_Type @b{is} ("release", "debug"); | |
13425 | Build : Build_Type := External ("BUILD", "debug"); | |
13426 | @end group | |
13427 | @group | |
13428 | @b{package} Compiler @b{is} | |
13429 | @b{case} Build @b{is} | |
13430 | @b{when} "release" => | |
13431 | @b{for} ^Default_Switches^Default_Switches^ ("Ada") | |
13432 | @b{use} ("^-O2^-O2^"); | |
13433 | @b{when} "debug" => | |
13434 | @b{for} ^Default_Switches^Default_Switches^ ("Ada") | |
13435 | @b{use} ("^-g^-g^"); | |
13436 | @b{end case}; | |
13437 | @b{end} Compiler; | |
13438 | ||
13439 | @b{end} Common; | |
88e1739c FW |
13440 | @end group |
13441 | @end smallexample | |
13442 | ||
7cd4527e | 13443 | @item We create separate projects for the two programs: |
88e1739c | 13444 | |
7cd4527e AC |
13445 | @smallexample |
13446 | @group | |
13447 | File "prog1.gpr": | |
88e1739c | 13448 | |
7cd4527e AC |
13449 | @b{with} "common"; |
13450 | @b{project} Prog1 @b{is} | |
88e1739c | 13451 | |
7cd4527e AC |
13452 | @b{for} Source_Dirs @b{use} ("prog1"); |
13453 | @b{for} Object_Dir @b{use} "prog1/build/" & Common.Build; | |
88e1739c | 13454 | |
7cd4527e | 13455 | @b{package} Compiler @b{renames} Common.Compiler; |
88e1739c | 13456 | |
7cd4527e AC |
13457 | @b{end} Prog1; |
13458 | @end group | |
13459 | @end smallexample | |
88e1739c | 13460 | |
7cd4527e AC |
13461 | @smallexample |
13462 | @group | |
13463 | File "prog2.gpr": | |
88e1739c | 13464 | |
7cd4527e AC |
13465 | @b{with} "common"; |
13466 | @b{project} Prog2 @b{is} | |
88e1739c | 13467 | |
7cd4527e AC |
13468 | @b{for} Source_Dirs @b{use} ("prog2"); |
13469 | @b{for} Object_Dir @b{use} "prog2/build/" & Common.Build; | |
88e1739c | 13470 | |
7cd4527e | 13471 | @b{package} Compiler @b{renames} Common.Compiler; |
88e1739c | 13472 | |
7cd4527e AC |
13473 | @end group |
13474 | @b{end} Prog2; | |
13475 | @end smallexample | |
88e1739c | 13476 | |
7cd4527e | 13477 | @item We create a wrapping project @code{Main}: |
88e1739c FW |
13478 | |
13479 | @smallexample | |
7cd4527e AC |
13480 | @group |
13481 | File "main.gpr": | |
88e1739c | 13482 | |
7cd4527e AC |
13483 | @b{with} "common"; |
13484 | @b{with} "prog1"; | |
13485 | @b{with} "prog2"; | |
13486 | @b{project} Main @b{is} | |
88e1739c | 13487 | |
7cd4527e | 13488 | @b{package} Compiler @b{renames} Common.Compiler; |
88e1739c | 13489 | |
7cd4527e AC |
13490 | @b{end} Main; |
13491 | @end group | |
13492 | @end smallexample | |
88e1739c | 13493 | |
7cd4527e AC |
13494 | @item Finally we need to create a dummy procedure that @code{with}s (either |
13495 | explicitly or implicitly) all the sources of our two programs. | |
88e1739c | 13496 | |
7cd4527e | 13497 | @end enumerate |
88e1739c | 13498 | |
7cd4527e AC |
13499 | @noindent |
13500 | Now we can build the programs using the command | |
88e1739c | 13501 | |
7cd4527e AC |
13502 | @smallexample |
13503 | gnatmake ^-P^/PROJECT_FILE=^main dummy | |
88e1739c FW |
13504 | @end smallexample |
13505 | ||
13506 | @noindent | |
7cd4527e | 13507 | for the Debug mode, or |
88e1739c | 13508 | |
7cd4527e AC |
13509 | @ifclear vms |
13510 | @smallexample | |
13511 | gnatmake -Pmain -XBUILD=release | |
13512 | @end smallexample | |
13513 | @end ifclear | |
88e1739c | 13514 | |
7cd4527e AC |
13515 | @ifset vms |
13516 | @smallexample | |
13517 | GNAT MAKE /PROJECT_FILE=main /EXTERNAL_REFERENCE=BUILD=release | |
13518 | @end smallexample | |
13519 | @end ifset | |
88e1739c | 13520 | |
7cd4527e AC |
13521 | @noindent |
13522 | for the Release mode. | |
88e1739c | 13523 | |
7cd4527e AC |
13524 | @c ******************************** |
13525 | @c * Project File Complete Syntax * | |
13526 | @c ******************************** | |
88e1739c | 13527 | |
7cd4527e AC |
13528 | @node Project File Complete Syntax |
13529 | @section Project File Complete Syntax | |
88e1739c | 13530 | |
7cd4527e AC |
13531 | @smallexample |
13532 | project ::= | |
13533 | context_clause project_declaration | |
88e1739c | 13534 | |
7cd4527e AC |
13535 | context_clause ::= |
13536 | @{with_clause@} | |
88e1739c | 13537 | |
7cd4527e AC |
13538 | with_clause ::= |
13539 | @b{with} path_name @{ , path_name @} ; | |
88e1739c | 13540 | |
7cd4527e AC |
13541 | path_name ::= |
13542 | string_literal | |
88e1739c | 13543 | |
7cd4527e AC |
13544 | project_declaration ::= |
13545 | simple_project_declaration | project_extension | |
88e1739c | 13546 | |
7cd4527e AC |
13547 | simple_project_declaration ::= |
13548 | @b{project} <project_>simple_name @b{is} | |
13549 | @{declarative_item@} | |
13550 | @b{end} <project_>simple_name; | |
88e1739c | 13551 | |
7cd4527e AC |
13552 | project_extension ::= |
13553 | @b{project} <project_>simple_name @b{extends} path_name @b{is} | |
13554 | @{declarative_item@} | |
13555 | @b{end} <project_>simple_name; | |
88e1739c | 13556 | |
7cd4527e AC |
13557 | declarative_item ::= |
13558 | package_declaration | | |
13559 | typed_string_declaration | | |
13560 | other_declarative_item | |
88e1739c | 13561 | |
7cd4527e AC |
13562 | package_declaration ::= |
13563 | package_specification | package_renaming | |
88e1739c | 13564 | |
7cd4527e AC |
13565 | package_specification ::= |
13566 | @b{package} package_identifier @b{is} | |
13567 | @{simple_declarative_item@} | |
13568 | @b{end} package_identifier ; | |
88e1739c | 13569 | |
7cd4527e AC |
13570 | package_identifier ::= |
13571 | @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} | | |
13572 | @code{Linker} | @code{Finder} | @code{Cross_Reference} | | |
13573 | @code{^gnatls^gnatls^} | @code{IDE} | @code{Pretty_Printer} | |
88e1739c | 13574 | |
7cd4527e AC |
13575 | package_renaming ::== |
13576 | @b{package} package_identifier @b{renames} | |
13577 | <project_>simple_name.package_identifier ; | |
88e1739c | 13578 | |
7cd4527e AC |
13579 | typed_string_declaration ::= |
13580 | @b{type} <typed_string_>_simple_name @b{is} | |
13581 | ( string_literal @{, string_literal@} ); | |
88e1739c | 13582 | |
7cd4527e AC |
13583 | other_declarative_item ::= |
13584 | attribute_declaration | | |
13585 | typed_variable_declaration | | |
13586 | variable_declaration | | |
13587 | case_construction | |
88e1739c | 13588 | |
7cd4527e AC |
13589 | attribute_declaration ::= |
13590 | full_associative_array_declaration | | |
13591 | @b{for} attribute_designator @b{use} expression ; | |
88e1739c | 13592 | |
7cd4527e AC |
13593 | full_associative_array_declaration ::= |
13594 | @b{for} <associative_array_attribute_>simple_name @b{use} | |
13595 | <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ; | |
88e1739c | 13596 | |
7cd4527e AC |
13597 | attribute_designator ::= |
13598 | <simple_attribute_>simple_name | | |
13599 | <associative_array_attribute_>simple_name ( string_literal ) | |
88e1739c | 13600 | |
7cd4527e AC |
13601 | typed_variable_declaration ::= |
13602 | <typed_variable_>simple_name : <typed_string_>name := string_expression ; | |
88e1739c | 13603 | |
7cd4527e AC |
13604 | variable_declaration ::= |
13605 | <variable_>simple_name := expression; | |
88e1739c | 13606 | |
7cd4527e AC |
13607 | expression ::= |
13608 | term @{& term@} | |
88e1739c | 13609 | |
7cd4527e AC |
13610 | term ::= |
13611 | literal_string | | |
13612 | string_list | | |
13613 | <variable_>name | | |
13614 | external_value | | |
13615 | attribute_reference | |
88e1739c | 13616 | |
7cd4527e AC |
13617 | string_literal ::= |
13618 | (same as Ada) | |
88e1739c | 13619 | |
7cd4527e AC |
13620 | string_list ::= |
13621 | ( <string_>expression @{ , <string_>expression @} ) | |
88e1739c | 13622 | |
7cd4527e AC |
13623 | external_value ::= |
13624 | @b{external} ( string_literal [, string_literal] ) | |
88e1739c | 13625 | |
7cd4527e AC |
13626 | attribute_reference ::= |
13627 | attribute_prefix ' <simple_attribute_>simple_name [ ( literal_string ) ] | |
88e1739c | 13628 | |
7cd4527e AC |
13629 | attribute_prefix ::= |
13630 | @b{project} | | |
13631 | <project_>simple_name | package_identifier | | |
13632 | <project_>simple_name . package_identifier | |
88e1739c | 13633 | |
7cd4527e AC |
13634 | case_construction ::= |
13635 | @b{case} <typed_variable_>name @b{is} | |
13636 | @{case_item@} | |
13637 | @b{end case} ; | |
88e1739c | 13638 | |
7cd4527e AC |
13639 | case_item ::= |
13640 | @b{when} discrete_choice_list => | |
13641 | @{case_construction | attribute_declaration@} | |
88e1739c | 13642 | |
7cd4527e AC |
13643 | discrete_choice_list ::= |
13644 | string_literal @{| string_literal@} | | |
13645 | @b{others} | |
13646 | ||
13647 | name ::= | |
13648 | simple_name @{. simple_name@} | |
13649 | ||
13650 | simple_name ::= | |
13651 | identifier (same as Ada) | |
88e1739c | 13652 | |
88e1739c FW |
13653 | @end smallexample |
13654 | ||
7cd4527e AC |
13655 | |
13656 | @node The Cross-Referencing Tools gnatxref and gnatfind | |
13657 | @chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind} | |
13658 | @findex gnatxref | |
13659 | @findex gnatfind | |
13660 | ||
88e1739c | 13661 | @noindent |
7cd4527e AC |
13662 | The compiler generates cross-referencing information (unless |
13663 | you set the @samp{-gnatx} switch), which are saved in the @file{.ali} files. | |
13664 | This information indicates where in the source each entity is declared and | |
13665 | referenced. Note that entities in package Standard are not included, but | |
13666 | entities in all other predefined units are included in the output. | |
88e1739c | 13667 | |
7cd4527e AC |
13668 | Before using any of these two tools, you need to compile successfully your |
13669 | application, so that GNAT gets a chance to generate the cross-referencing | |
13670 | information. | |
88e1739c | 13671 | |
7cd4527e AC |
13672 | The two tools @code{gnatxref} and @code{gnatfind} take advantage of this |
13673 | information to provide the user with the capability to easily locate the | |
13674 | declaration and references to an entity. These tools are quite similar, | |
13675 | the difference being that @code{gnatfind} is intended for locating | |
13676 | definitions and/or references to a specified entity or entities, whereas | |
13677 | @code{gnatxref} is oriented to generating a full report of all | |
13678 | cross-references. | |
88e1739c | 13679 | |
7cd4527e AC |
13680 | To use these tools, you must not compile your application using the |
13681 | @option{-gnatx} switch on the @file{gnatmake} command line | |
13682 | (see @ref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing | |
13683 | information will not be generated. | |
88e1739c | 13684 | |
7cd4527e AC |
13685 | @menu |
13686 | * gnatxref Switches:: | |
13687 | * gnatfind Switches:: | |
13688 | * Project Files for gnatxref and gnatfind:: | |
13689 | * Regular Expressions in gnatfind and gnatxref:: | |
13690 | * Examples of gnatxref Usage:: | |
13691 | * Examples of gnatfind Usage:: | |
13692 | @end menu | |
88e1739c | 13693 | |
7cd4527e AC |
13694 | @node gnatxref Switches |
13695 | @section @code{gnatxref} Switches | |
88e1739c | 13696 | |
7cd4527e AC |
13697 | @noindent |
13698 | The command invocation for @code{gnatxref} is: | |
88e1739c | 13699 | @smallexample |
7cd4527e | 13700 | $ gnatxref [switches] sourcefile1 [sourcefile2 ...] |
88e1739c FW |
13701 | @end smallexample |
13702 | ||
13703 | @noindent | |
7cd4527e | 13704 | where |
88e1739c | 13705 | |
7cd4527e AC |
13706 | @table @code |
13707 | @item sourcefile1, sourcefile2 | |
13708 | identifies the source files for which a report is to be generated. The | |
13709 | ``with''ed units will be processed too. You must provide at least one file. | |
88e1739c | 13710 | |
7cd4527e AC |
13711 | These file names are considered to be regular expressions, so for instance |
13712 | specifying @file{source*.adb} is the same as giving every file in the current | |
13713 | directory whose name starts with @file{source} and whose extension is | |
13714 | @file{adb}. | |
13715 | ||
13716 | @end table | |
88e1739c | 13717 | |
88e1739c | 13718 | @noindent |
7cd4527e AC |
13719 | The switches can be : |
13720 | @table @option | |
13721 | @c !sort! | |
13722 | @item ^-a^/ALL_FILES^ | |
13723 | @cindex @option{^-a^/ALL_FILES^} (@command{gnatxref}) | |
13724 | If this switch is present, @code{gnatfind} and @code{gnatxref} will parse | |
13725 | the read-only files found in the library search path. Otherwise, these files | |
13726 | will be ignored. This option can be used to protect Gnat sources or your own | |
13727 | libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref} | |
13728 | much faster, and their output much smaller. Read-only here refers to access | |
13729 | or permissions status in the file system for the current user. | |
88e1739c | 13730 | |
7cd4527e AC |
13731 | @item -aIDIR |
13732 | @cindex @option{-aIDIR} (@command{gnatxref}) | |
13733 | When looking for source files also look in directory DIR. The order in which | |
13734 | source file search is undertaken is the same as for @file{gnatmake}. | |
88e1739c | 13735 | |
7cd4527e AC |
13736 | @item -aODIR |
13737 | @cindex @option{-aODIR} (@command{gnatxref}) | |
13738 | When searching for library and object files, look in directory | |
13739 | DIR. The order in which library files are searched is the same as for | |
13740 | @file{gnatmake}. | |
88e1739c | 13741 | |
7cd4527e AC |
13742 | @item -nostdinc |
13743 | @cindex @option{-nostdinc} (@command{gnatxref}) | |
13744 | Do not look for sources in the system default directory. | |
88e1739c | 13745 | |
7cd4527e AC |
13746 | @item -nostdlib |
13747 | @cindex @option{-nostdlib} (@command{gnatxref}) | |
13748 | Do not look for library files in the system default directory. | |
88e1739c | 13749 | |
7cd4527e AC |
13750 | @item --RTS=@var{rts-path} |
13751 | @cindex @option{--RTS} (@command{gnatxref}) | |
13752 | Specifies the default location of the runtime library. Same meaning as the | |
13753 | equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}). | |
88e1739c | 13754 | |
7cd4527e AC |
13755 | @item ^-d^/DERIVED_TYPES^ |
13756 | @cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref}) | |
13757 | If this switch is set @code{gnatxref} will output the parent type | |
13758 | reference for each matching derived types. | |
88e1739c | 13759 | |
7cd4527e AC |
13760 | @item ^-f^/FULL_PATHNAME^ |
13761 | @cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatxref}) | |
13762 | If this switch is set, the output file names will be preceded by their | |
13763 | directory (if the file was found in the search path). If this switch is | |
13764 | not set, the directory will not be printed. | |
88e1739c | 13765 | |
7cd4527e AC |
13766 | @item ^-g^/IGNORE_LOCALS^ |
13767 | @cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatxref}) | |
13768 | If this switch is set, information is output only for library-level | |
13769 | entities, ignoring local entities. The use of this switch may accelerate | |
13770 | @code{gnatfind} and @code{gnatxref}. | |
88e1739c | 13771 | |
7cd4527e AC |
13772 | @item -IDIR |
13773 | @cindex @option{-IDIR} (@command{gnatxref}) | |
13774 | Equivalent to @samp{-aODIR -aIDIR}. | |
88e1739c | 13775 | |
7cd4527e AC |
13776 | @item -pFILE |
13777 | @cindex @option{-pFILE} (@command{gnatxref}) | |
13778 | Specify a project file to use @xref{Project Files}. These project files are | |
13779 | the @file{.adp} files used by Glide. If you need to use the @file{.gpr} | |
13780 | project files, you should use gnatxref through the GNAT driver | |
13781 | (@command{gnat xref -Pproject}). | |
88e1739c | 13782 | |
7cd4527e AC |
13783 | By default, @code{gnatxref} and @code{gnatfind} will try to locate a |
13784 | project file in the current directory. | |
88e1739c | 13785 | |
7cd4527e AC |
13786 | If a project file is either specified or found by the tools, then the content |
13787 | of the source directory and object directory lines are added as if they | |
13788 | had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} | |
13789 | and @samp{^-aO^OBJECT_SEARCH^}. | |
13790 | @item ^-u^/UNUSED^ | |
13791 | Output only unused symbols. This may be really useful if you give your | |
13792 | main compilation unit on the command line, as @code{gnatxref} will then | |
13793 | display every unused entity and 'with'ed package. | |
88e1739c | 13794 | |
7cd4527e AC |
13795 | @ifclear vms |
13796 | @item -v | |
13797 | Instead of producing the default output, @code{gnatxref} will generate a | |
13798 | @file{tags} file that can be used by vi. For examples how to use this | |
13799 | feature, see @xref{Examples of gnatxref Usage}. The tags file is output | |
13800 | to the standard output, thus you will have to redirect it to a file. | |
13801 | @end ifclear | |
13802 | ||
13803 | @end table | |
88e1739c FW |
13804 | |
13805 | @noindent | |
7cd4527e AC |
13806 | All these switches may be in any order on the command line, and may even |
13807 | appear after the file names. They need not be separated by spaces, thus | |
13808 | you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of | |
13809 | @samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}. | |
88e1739c | 13810 | |
7cd4527e AC |
13811 | @node gnatfind Switches |
13812 | @section @code{gnatfind} Switches | |
88e1739c FW |
13813 | |
13814 | @noindent | |
7cd4527e | 13815 | The command line for @code{gnatfind} is: |
88e1739c | 13816 | |
7cd4527e AC |
13817 | @smallexample |
13818 | $ gnatfind [switches] pattern[:sourcefile[:line[:column]]] | |
13819 | [file1 file2 ...] | |
13820 | @end smallexample | |
88e1739c | 13821 | |
7cd4527e AC |
13822 | @noindent |
13823 | where | |
88e1739c | 13824 | |
7cd4527e AC |
13825 | @table @code |
13826 | @item pattern | |
13827 | An entity will be output only if it matches the regular expression found | |
13828 | in @samp{pattern}, see @xref{Regular Expressions in gnatfind and gnatxref}. | |
88e1739c | 13829 | |
7cd4527e AC |
13830 | Omitting the pattern is equivalent to specifying @samp{*}, which |
13831 | will match any entity. Note that if you do not provide a pattern, you | |
13832 | have to provide both a sourcefile and a line. | |
88e1739c | 13833 | |
7cd4527e AC |
13834 | Entity names are given in Latin-1, with uppercase/lowercase equivalence |
13835 | for matching purposes. At the current time there is no support for | |
13836 | 8-bit codes other than Latin-1, or for wide characters in identifiers. | |
88e1739c | 13837 | |
7cd4527e AC |
13838 | @item sourcefile |
13839 | @code{gnatfind} will look for references, bodies or declarations | |
13840 | of symbols referenced in @file{sourcefile}, at line @samp{line} | |
13841 | and column @samp{column}. See @pxref{Examples of gnatfind Usage} | |
13842 | for syntax examples. | |
88e1739c | 13843 | |
7cd4527e AC |
13844 | @item line |
13845 | is a decimal integer identifying the line number containing | |
13846 | the reference to the entity (or entities) to be located. | |
88e1739c | 13847 | |
7cd4527e AC |
13848 | @item column |
13849 | is a decimal integer identifying the exact location on the | |
13850 | line of the first character of the identifier for the | |
13851 | entity reference. Columns are numbered from 1. | |
88e1739c | 13852 | |
7cd4527e AC |
13853 | @item file1 file2 ... |
13854 | The search will be restricted to these source files. If none are given, then | |
13855 | the search will be done for every library file in the search path. | |
13856 | These file must appear only after the pattern or sourcefile. | |
88e1739c | 13857 | |
7cd4527e AC |
13858 | These file names are considered to be regular expressions, so for instance |
13859 | specifying 'source*.adb' is the same as giving every file in the current | |
13860 | directory whose name starts with 'source' and whose extension is 'adb'. | |
88e1739c | 13861 | |
7cd4527e AC |
13862 | The location of the spec of the entity will always be displayed, even if it |
13863 | isn't in one of file1, file2,... The occurrences of the entity in the | |
13864 | separate units of the ones given on the command line will also be displayed. | |
88e1739c | 13865 | |
7cd4527e AC |
13866 | Note that if you specify at least one file in this part, @code{gnatfind} may |
13867 | sometimes not be able to find the body of the subprograms... | |
88e1739c | 13868 | |
88e1739c FW |
13869 | @end table |
13870 | ||
13871 | @noindent | |
7cd4527e AC |
13872 | At least one of 'sourcefile' or 'pattern' has to be present on |
13873 | the command line. | |
88e1739c | 13874 | |
7cd4527e AC |
13875 | The following switches are available: |
13876 | @table @option | |
13877 | @c !sort! | |
88e1739c | 13878 | |
7cd4527e AC |
13879 | @item ^-a^/ALL_FILES^ |
13880 | @cindex @option{^-a^/ALL_FILES^} (@command{gnatfind}) | |
13881 | If this switch is present, @code{gnatfind} and @code{gnatxref} will parse | |
13882 | the read-only files found in the library search path. Otherwise, these files | |
13883 | will be ignored. This option can be used to protect Gnat sources or your own | |
13884 | libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref} | |
13885 | much faster, and their output much smaller. Read-only here refers to access | |
13886 | or permission status in the file system for the current user. | |
88e1739c | 13887 | |
7cd4527e AC |
13888 | @item -aIDIR |
13889 | @cindex @option{-aIDIR} (@command{gnatfind}) | |
13890 | When looking for source files also look in directory DIR. The order in which | |
13891 | source file search is undertaken is the same as for @file{gnatmake}. | |
88e1739c | 13892 | |
7cd4527e AC |
13893 | @item -aODIR |
13894 | @cindex @option{-aODIR} (@command{gnatfind}) | |
13895 | When searching for library and object files, look in directory | |
13896 | DIR. The order in which library files are searched is the same as for | |
13897 | @file{gnatmake}. | |
88e1739c | 13898 | |
7cd4527e AC |
13899 | @item -nostdinc |
13900 | @cindex @option{-nostdinc} (@command{gnatfind}) | |
13901 | Do not look for sources in the system default directory. | |
88e1739c | 13902 | |
7cd4527e AC |
13903 | @item -nostdlib |
13904 | @cindex @option{-nostdlib} (@command{gnatfind}) | |
13905 | Do not look for library files in the system default directory. | |
88e1739c | 13906 | |
7cd4527e AC |
13907 | @item --RTS=@var{rts-path} |
13908 | @cindex @option{--RTS} (@command{gnatfind}) | |
13909 | Specifies the default location of the runtime library. Same meaning as the | |
13910 | equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}). | |
88e1739c | 13911 | |
7cd4527e AC |
13912 | @item ^-d^/DERIVED_TYPE_INFORMATION^ |
13913 | @cindex @option{^-d^/DERIVED_TYPE_INFORMATION^} (@code{gnatfind}) | |
13914 | If this switch is set, then @code{gnatfind} will output the parent type | |
13915 | reference for each matching derived types. | |
88e1739c | 13916 | |
7cd4527e AC |
13917 | @item ^-e^/EXPRESSIONS^ |
13918 | @cindex @option{^-e^/EXPRESSIONS^} (@command{gnatfind}) | |
13919 | By default, @code{gnatfind} accept the simple regular expression set for | |
13920 | @samp{pattern}. If this switch is set, then the pattern will be | |
13921 | considered as full Unix-style regular expression. | |
88e1739c | 13922 | |
7cd4527e AC |
13923 | @item ^-f^/FULL_PATHNAME^ |
13924 | @cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatfind}) | |
13925 | If this switch is set, the output file names will be preceded by their | |
13926 | directory (if the file was found in the search path). If this switch is | |
13927 | not set, the directory will not be printed. | |
88e1739c | 13928 | |
7cd4527e AC |
13929 | @item ^-g^/IGNORE_LOCALS^ |
13930 | @cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatfind}) | |
13931 | If this switch is set, information is output only for library-level | |
13932 | entities, ignoring local entities. The use of this switch may accelerate | |
13933 | @code{gnatfind} and @code{gnatxref}. | |
88e1739c | 13934 | |
7cd4527e AC |
13935 | @item -IDIR |
13936 | @cindex @option{-IDIR} (@command{gnatfind}) | |
13937 | Equivalent to @samp{-aODIR -aIDIR}. | |
88e1739c | 13938 | |
7cd4527e AC |
13939 | @item -pFILE |
13940 | @cindex @option{-pFILE} (@command{gnatfind}) | |
13941 | Specify a project file (@pxref{Project Files}) to use. | |
13942 | By default, @code{gnatxref} and @code{gnatfind} will try to locate a | |
13943 | project file in the current directory. | |
88e1739c | 13944 | |
7cd4527e AC |
13945 | If a project file is either specified or found by the tools, then the content |
13946 | of the source directory and object directory lines are added as if they | |
13947 | had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} and | |
13948 | @samp{^-aO^/OBJECT_SEARCH^}. | |
88e1739c | 13949 | |
7cd4527e AC |
13950 | @item ^-r^/REFERENCES^ |
13951 | @cindex @option{^-r^/REFERENCES^} (@command{gnatfind}) | |
13952 | By default, @code{gnatfind} will output only the information about the | |
13953 | declaration, body or type completion of the entities. If this switch is | |
13954 | set, the @code{gnatfind} will locate every reference to the entities in | |
13955 | the files specified on the command line (or in every file in the search | |
13956 | path if no file is given on the command line). | |
88e1739c | 13957 | |
7cd4527e AC |
13958 | @item ^-s^/PRINT_LINES^ |
13959 | @cindex @option{^-s^/PRINT_LINES^} (@command{gnatfind}) | |
13960 | If this switch is set, then @code{gnatfind} will output the content | |
13961 | of the Ada source file lines were the entity was found. | |
88e1739c | 13962 | |
7cd4527e AC |
13963 | @item ^-t^/TYPE_HIERARCHY^ |
13964 | @cindex @option{^-t^/TYPE_HIERARCHY^} (@command{gnatfind}) | |
13965 | If this switch is set, then @code{gnatfind} will output the type hierarchy for | |
13966 | the specified type. It act like -d option but recursively from parent | |
13967 | type to parent type. When this switch is set it is not possible to | |
13968 | specify more than one file. | |
88e1739c | 13969 | |
7cd4527e | 13970 | @end table |
88e1739c FW |
13971 | |
13972 | @noindent | |
7cd4527e AC |
13973 | All these switches may be in any order on the command line, and may even |
13974 | appear after the file names. They need not be separated by spaces, thus | |
13975 | you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of | |
13976 | @samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}. | |
88e1739c | 13977 | |
7cd4527e AC |
13978 | As stated previously, gnatfind will search in every directory in the |
13979 | search path. You can force it to look only in the current directory if | |
13980 | you specify @code{*} at the end of the command line. | |
88e1739c | 13981 | |
7cd4527e AC |
13982 | @node Project Files for gnatxref and gnatfind |
13983 | @section Project Files for @command{gnatxref} and @command{gnatfind} | |
88e1739c FW |
13984 | |
13985 | @noindent | |
7cd4527e AC |
13986 | Project files allow a programmer to specify how to compile its |
13987 | application, where to find sources, etc. These files are used | |
13988 | @ifclear vms | |
13989 | primarily by the Glide Ada mode, but they can also be used | |
13990 | @end ifclear | |
13991 | by the two tools | |
13992 | @code{gnatxref} and @code{gnatfind}. | |
88e1739c | 13993 | |
7cd4527e AC |
13994 | A project file name must end with @file{.gpr}. If a single one is |
13995 | present in the current directory, then @code{gnatxref} and @code{gnatfind} will | |
13996 | extract the information from it. If multiple project files are found, none of | |
13997 | them is read, and you have to use the @samp{-p} switch to specify the one | |
13998 | you want to use. | |
88e1739c | 13999 | |
7cd4527e AC |
14000 | The following lines can be included, even though most of them have default |
14001 | values which can be used in most cases. | |
14002 | The lines can be entered in any order in the file. | |
14003 | Except for @file{src_dir} and @file{obj_dir}, you can only have one instance of | |
14004 | each line. If you have multiple instances, only the last one is taken into | |
14005 | account. | |
88e1739c | 14006 | |
7cd4527e AC |
14007 | @table @code |
14008 | @item src_dir=DIR | |
14009 | [default: @code{"^./^[]^"}] | |
14010 | specifies a directory where to look for source files. Multiple @code{src_dir} | |
14011 | lines can be specified and they will be searched in the order they | |
14012 | are specified. | |
88e1739c | 14013 | |
7cd4527e AC |
14014 | @item obj_dir=DIR |
14015 | [default: @code{"^./^[]^"}] | |
14016 | specifies a directory where to look for object and library files. Multiple | |
14017 | @code{obj_dir} lines can be specified, and they will be searched in the order | |
14018 | they are specified | |
88e1739c | 14019 | |
7cd4527e AC |
14020 | @item comp_opt=SWITCHES |
14021 | [default: @code{""}] | |
14022 | creates a variable which can be referred to subsequently by using | |
14023 | the @code{$@{comp_opt@}} notation. This is intended to store the default | |
14024 | switches given to @command{gnatmake} and @command{gcc}. | |
88e1739c | 14025 | |
7cd4527e AC |
14026 | @item bind_opt=SWITCHES |
14027 | [default: @code{""}] | |
14028 | creates a variable which can be referred to subsequently by using | |
14029 | the @samp{$@{bind_opt@}} notation. This is intended to store the default | |
14030 | switches given to @command{gnatbind}. | |
88e1739c | 14031 | |
7cd4527e AC |
14032 | @item link_opt=SWITCHES |
14033 | [default: @code{""}] | |
14034 | creates a variable which can be referred to subsequently by using | |
14035 | the @samp{$@{link_opt@}} notation. This is intended to store the default | |
14036 | switches given to @command{gnatlink}. | |
88e1739c | 14037 | |
7cd4527e AC |
14038 | @item main=EXECUTABLE |
14039 | [default: @code{""}] | |
14040 | specifies the name of the executable for the application. This variable can | |
14041 | be referred to in the following lines by using the @samp{$@{main@}} notation. | |
88e1739c | 14042 | |
7cd4527e AC |
14043 | @ifset vms |
14044 | @item comp_cmd=COMMAND | |
14045 | [default: @code{"GNAT COMPILE /SEARCH=$@{src_dir@} /DEBUG /TRY_SEMANTICS"}] | |
14046 | @end ifset | |
14047 | @ifclear vms | |
14048 | @item comp_cmd=COMMAND | |
14049 | [default: @code{"gcc -c -I$@{src_dir@} -g -gnatq"}] | |
14050 | @end ifclear | |
14051 | specifies the command used to compile a single file in the application. | |
88e1739c | 14052 | |
7cd4527e AC |
14053 | @ifset vms |
14054 | @item make_cmd=COMMAND | |
14055 | [default: @code{"GNAT MAKE $@{main@} | |
14056 | /SOURCE_SEARCH=$@{src_dir@} /OBJECT_SEARCH=$@{obj_dir@} | |
14057 | /DEBUG /TRY_SEMANTICS /COMPILER_QUALIFIERS $@{comp_opt@} | |
14058 | /BINDER_QUALIFIERS $@{bind_opt@} /LINKER_QUALIFIERS $@{link_opt@}"}] | |
14059 | @end ifset | |
14060 | @ifclear vms | |
14061 | @item make_cmd=COMMAND | |
14062 | [default: @code{"gnatmake $@{main@} -aI$@{src_dir@} | |
14063 | -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@} | |
14064 | -bargs $@{bind_opt@} -largs $@{link_opt@}"}] | |
14065 | @end ifclear | |
14066 | specifies the command used to recompile the whole application. | |
88e1739c | 14067 | |
7cd4527e AC |
14068 | @item run_cmd=COMMAND |
14069 | [default: @code{"$@{main@}"}] | |
14070 | specifies the command used to run the application. | |
88e1739c | 14071 | |
7cd4527e AC |
14072 | @item debug_cmd=COMMAND |
14073 | [default: @code{"gdb $@{main@}"}] | |
14074 | specifies the command used to debug the application | |
88e1739c | 14075 | |
7cd4527e | 14076 | @end table |
88e1739c FW |
14077 | |
14078 | @noindent | |
7cd4527e AC |
14079 | @command{gnatxref} and @command{gnatfind} only take into account the |
14080 | @code{src_dir} and @code{obj_dir} lines, and ignore the others. | |
14081 | ||
14082 | @node Regular Expressions in gnatfind and gnatxref | |
14083 | @section Regular Expressions in @code{gnatfind} and @code{gnatxref} | |
88e1739c FW |
14084 | |
14085 | @noindent | |
7cd4527e AC |
14086 | As specified in the section about @command{gnatfind}, the pattern can be a |
14087 | regular expression. Actually, there are to set of regular expressions | |
14088 | which are recognized by the program : | |
88e1739c FW |
14089 | |
14090 | @table @code | |
7cd4527e AC |
14091 | @item globbing patterns |
14092 | These are the most usual regular expression. They are the same that you | |
14093 | generally used in a Unix shell command line, or in a DOS session. | |
88e1739c | 14094 | |
7cd4527e AC |
14095 | Here is a more formal grammar : |
14096 | @smallexample | |
14097 | @group | |
14098 | @iftex | |
14099 | @leftskip=.5cm | |
14100 | @end iftex | |
14101 | regexp ::= term | |
14102 | term ::= elmt -- matches elmt | |
14103 | term ::= elmt elmt -- concatenation (elmt then elmt) | |
14104 | term ::= * -- any string of 0 or more characters | |
14105 | term ::= ? -- matches any character | |
14106 | term ::= [char @{char@}] -- matches any character listed | |
14107 | term ::= [char - char] -- matches any character in range | |
14108 | @end group | |
14109 | @end smallexample | |
88e1739c | 14110 | |
7cd4527e AC |
14111 | @item full regular expression |
14112 | The second set of regular expressions is much more powerful. This is the | |
14113 | type of regular expressions recognized by utilities such a @file{grep}. | |
88e1739c | 14114 | |
7cd4527e AC |
14115 | The following is the form of a regular expression, expressed in Ada |
14116 | reference manual style BNF is as follows | |
88e1739c | 14117 | |
7cd4527e AC |
14118 | @smallexample |
14119 | @iftex | |
14120 | @leftskip=.5cm | |
14121 | @end iftex | |
14122 | @group | |
14123 | regexp ::= term @{| term@} -- alternation (term or term ...) | |
88e1739c | 14124 | |
7cd4527e | 14125 | term ::= item @{item@} -- concatenation (item then item) |
88e1739c | 14126 | |
7cd4527e AC |
14127 | item ::= elmt -- match elmt |
14128 | item ::= elmt * -- zero or more elmt's | |
14129 | item ::= elmt + -- one or more elmt's | |
14130 | item ::= elmt ? -- matches elmt or nothing | |
14131 | @end group | |
14132 | @group | |
14133 | elmt ::= nschar -- matches given character | |
14134 | elmt ::= [nschar @{nschar@}] -- matches any character listed | |
14135 | elmt ::= [^^^ nschar @{nschar@}] -- matches any character not listed | |
14136 | elmt ::= [char - char] -- matches chars in given range | |
14137 | elmt ::= \ char -- matches given character | |
14138 | elmt ::= . -- matches any single character | |
14139 | elmt ::= ( regexp ) -- parens used for grouping | |
88e1739c | 14140 | |
7cd4527e AC |
14141 | char ::= any character, including special characters |
14142 | nschar ::= any character except ()[].*+?^^^ | |
14143 | @end group | |
14144 | @end smallexample | |
88e1739c | 14145 | |
7cd4527e | 14146 | Following are a few examples : |
88e1739c | 14147 | |
7cd4527e AC |
14148 | @table @samp |
14149 | @item abcde|fghi | |
14150 | will match any of the two strings 'abcde' and 'fghi'. | |
88e1739c | 14151 | |
7cd4527e AC |
14152 | @item abc*d |
14153 | will match any string like 'abd', 'abcd', 'abccd', 'abcccd', and so on | |
88e1739c | 14154 | |
7cd4527e AC |
14155 | @item [a-z]+ |
14156 | will match any string which has only lowercase characters in it (and at | |
14157 | least one character | |
88e1739c | 14158 | |
7cd4527e AC |
14159 | @end table |
14160 | @end table | |
88e1739c | 14161 | |
7cd4527e AC |
14162 | @node Examples of gnatxref Usage |
14163 | @section Examples of @code{gnatxref} Usage | |
88e1739c | 14164 | |
7cd4527e | 14165 | @subsection General Usage |
88e1739c | 14166 | |
7cd4527e AC |
14167 | @noindent |
14168 | For the following examples, we will consider the following units : | |
88e1739c | 14169 | |
7cd4527e AC |
14170 | @smallexample @c ada |
14171 | @group | |
14172 | @cartouche | |
14173 | main.ads: | |
14174 | 1: with Bar; | |
14175 | 2: package Main is | |
14176 | 3: procedure Foo (B : in Integer); | |
14177 | 4: C : Integer; | |
14178 | 5: private | |
14179 | 6: D : Integer; | |
14180 | 7: end Main; | |
88e1739c | 14181 | |
7cd4527e AC |
14182 | main.adb: |
14183 | 1: package body Main is | |
14184 | 2: procedure Foo (B : in Integer) is | |
14185 | 3: begin | |
14186 | 4: C := B; | |
14187 | 5: D := B; | |
14188 | 6: Bar.Print (B); | |
14189 | 7: Bar.Print (C); | |
14190 | 8: end Foo; | |
14191 | 9: end Main; | |
14192 | ||
14193 | bar.ads: | |
14194 | 1: package Bar is | |
14195 | 2: procedure Print (B : Integer); | |
14196 | 3: end bar; | |
14197 | @end cartouche | |
14198 | @end group | |
14199 | @end smallexample | |
14200 | ||
14201 | @table @code | |
88e1739c FW |
14202 | |
14203 | @noindent | |
7cd4527e AC |
14204 | The first thing to do is to recompile your application (for instance, in |
14205 | that case just by doing a @samp{gnatmake main}, so that GNAT generates | |
14206 | the cross-referencing information. | |
14207 | You can then issue any of the following commands: | |
14208 | ||
14209 | @item gnatxref main.adb | |
14210 | @code{gnatxref} generates cross-reference information for main.adb | |
14211 | and every unit 'with'ed by main.adb. | |
88e1739c | 14212 | |
7cd4527e | 14213 | The output would be: |
88e1739c | 14214 | @smallexample |
7cd4527e AC |
14215 | @iftex |
14216 | @leftskip=0cm | |
14217 | @end iftex | |
14218 | B Type: Integer | |
14219 | Decl: bar.ads 2:22 | |
14220 | B Type: Integer | |
14221 | Decl: main.ads 3:20 | |
14222 | Body: main.adb 2:20 | |
14223 | Ref: main.adb 4:13 5:13 6:19 | |
14224 | Bar Type: Unit | |
14225 | Decl: bar.ads 1:9 | |
14226 | Ref: main.adb 6:8 7:8 | |
14227 | main.ads 1:6 | |
14228 | C Type: Integer | |
14229 | Decl: main.ads 4:5 | |
14230 | Modi: main.adb 4:8 | |
14231 | Ref: main.adb 7:19 | |
14232 | D Type: Integer | |
14233 | Decl: main.ads 6:5 | |
14234 | Modi: main.adb 5:8 | |
14235 | Foo Type: Unit | |
14236 | Decl: main.ads 3:15 | |
14237 | Body: main.adb 2:15 | |
14238 | Main Type: Unit | |
14239 | Decl: main.ads 2:9 | |
14240 | Body: main.adb 1:14 | |
14241 | Print Type: Unit | |
14242 | Decl: bar.ads 2:15 | |
14243 | Ref: main.adb 6:12 7:12 | |
88e1739c FW |
14244 | @end smallexample |
14245 | ||
14246 | @noindent | |
7cd4527e AC |
14247 | that is the entity @code{Main} is declared in main.ads, line 2, column 9, |
14248 | its body is in main.adb, line 1, column 14 and is not referenced any where. | |
88e1739c | 14249 | |
7cd4527e AC |
14250 | The entity @code{Print} is declared in bar.ads, line 2, column 15 and it |
14251 | it referenced in main.adb, line 6 column 12 and line 7 column 12. | |
88e1739c | 14252 | |
7cd4527e AC |
14253 | @item gnatxref package1.adb package2.ads |
14254 | @code{gnatxref} will generates cross-reference information for | |
14255 | package1.adb, package2.ads and any other package 'with'ed by any | |
14256 | of these. | |
88e1739c | 14257 | |
7cd4527e | 14258 | @end table |
88e1739c | 14259 | |
7cd4527e AC |
14260 | @ifclear vms |
14261 | @subsection Using gnatxref with vi | |
88e1739c | 14262 | |
7cd4527e AC |
14263 | @code{gnatxref} can generate a tags file output, which can be used |
14264 | directly from @file{vi}. Note that the standard version of @file{vi} | |
14265 | will not work properly with overloaded symbols. Consider using another | |
14266 | free implementation of @file{vi}, such as @file{vim}. | |
88e1739c | 14267 | |
7cd4527e AC |
14268 | @smallexample |
14269 | $ gnatxref -v gnatfind.adb > tags | |
14270 | @end smallexample | |
88e1739c | 14271 | |
7cd4527e AC |
14272 | @noindent |
14273 | will generate the tags file for @code{gnatfind} itself (if the sources | |
14274 | are in the search path!). | |
88e1739c | 14275 | |
7cd4527e AC |
14276 | From @file{vi}, you can then use the command @samp{:tag @i{entity}} |
14277 | (replacing @i{entity} by whatever you are looking for), and vi will | |
14278 | display a new file with the corresponding declaration of entity. | |
14279 | @end ifclear | |
88e1739c | 14280 | |
7cd4527e AC |
14281 | @node Examples of gnatfind Usage |
14282 | @section Examples of @code{gnatfind} Usage | |
88e1739c | 14283 | |
88e1739c FW |
14284 | @table @code |
14285 | ||
7cd4527e AC |
14286 | @item gnatfind ^-f^/FULL_PATHNAME^ xyz:main.adb |
14287 | Find declarations for all entities xyz referenced at least once in | |
14288 | main.adb. The references are search in every library file in the search | |
14289 | path. | |
88e1739c | 14290 | |
7cd4527e AC |
14291 | The directories will be printed as well (as the @samp{^-f^/FULL_PATHNAME^} |
14292 | switch is set) | |
88e1739c | 14293 | |
7cd4527e AC |
14294 | The output will look like: |
14295 | @smallexample | |
14296 | ^directory/^[directory]^main.ads:106:14: xyz <= declaration | |
14297 | ^directory/^[directory]^main.adb:24:10: xyz <= body | |
14298 | ^directory/^[directory]^foo.ads:45:23: xyz <= declaration | |
14299 | @end smallexample | |
88e1739c | 14300 | |
7cd4527e AC |
14301 | @noindent |
14302 | that is to say, one of the entities xyz found in main.adb is declared at | |
14303 | line 12 of main.ads (and its body is in main.adb), and another one is | |
14304 | declared at line 45 of foo.ads | |
88e1739c | 14305 | |
7cd4527e AC |
14306 | @item gnatfind ^-fs^/FULL_PATHNAME/SOURCE_LINE^ xyz:main.adb |
14307 | This is the same command as the previous one, instead @code{gnatfind} will | |
14308 | display the content of the Ada source file lines. | |
88e1739c | 14309 | |
7cd4527e | 14310 | The output will look like: |
88e1739c | 14311 | |
7cd4527e AC |
14312 | @smallexample |
14313 | ^directory/^[directory]^main.ads:106:14: xyz <= declaration | |
14314 | procedure xyz; | |
14315 | ^directory/^[directory]^main.adb:24:10: xyz <= body | |
14316 | procedure xyz is | |
14317 | ^directory/^[directory]^foo.ads:45:23: xyz <= declaration | |
14318 | xyz : Integer; | |
14319 | @end smallexample | |
88e1739c | 14320 | |
7cd4527e AC |
14321 | @noindent |
14322 | This can make it easier to find exactly the location your are looking | |
14323 | for. | |
88e1739c | 14324 | |
7cd4527e AC |
14325 | @item gnatfind ^-r^/REFERENCES^ "*x*":main.ads:123 foo.adb |
14326 | Find references to all entities containing an x that are | |
14327 | referenced on line 123 of main.ads. | |
14328 | The references will be searched only in main.ads and foo.adb. | |
88e1739c | 14329 | |
7cd4527e AC |
14330 | @item gnatfind main.ads:123 |
14331 | Find declarations and bodies for all entities that are referenced on | |
14332 | line 123 of main.ads. | |
88e1739c | 14333 | |
7cd4527e | 14334 | This is the same as @code{gnatfind "*":main.adb:123}. |
88e1739c | 14335 | |
7cd4527e AC |
14336 | @item gnatfind ^mydir/^[mydir]^main.adb:123:45 |
14337 | Find the declaration for the entity referenced at column 45 in | |
14338 | line 123 of file main.adb in directory mydir. Note that it | |
14339 | is usual to omit the identifier name when the column is given, | |
14340 | since the column position identifies a unique reference. | |
88e1739c | 14341 | |
7cd4527e AC |
14342 | The column has to be the beginning of the identifier, and should not |
14343 | point to any character in the middle of the identifier. | |
88e1739c | 14344 | |
7cd4527e | 14345 | @end table |
88e1739c | 14346 | |
88e1739c | 14347 | |
7cd4527e AC |
14348 | @c ********************************* |
14349 | @node The GNAT Pretty-Printer gnatpp | |
14350 | @chapter The GNAT Pretty-Printer @command{gnatpp} | |
14351 | @findex gnatpp | |
14352 | @cindex Pretty-Printer | |
88e1739c | 14353 | |
7cd4527e AC |
14354 | @noindent |
14355 | ^The @command{gnatpp} tool^GNAT PRETTY^ is an ASIS-based utility | |
14356 | for source reformatting / pretty-printing. | |
14357 | It takes an Ada source file as input and generates a reformatted | |
14358 | version as output. | |
14359 | You can specify various style directives via switches; e.g., | |
14360 | identifier case conventions, rules of indentation, and comment layout. | |
88e1739c | 14361 | |
7cd4527e AC |
14362 | To produce a reformatted file, @command{gnatpp} generates and uses the ASIS |
14363 | tree for the input source and thus requires the input to be syntactically and | |
14364 | semantically legal. | |
14365 | If this condition is not met, @command{gnatpp} will terminate with an | |
14366 | error message; no output file will be generated. | |
88e1739c | 14367 | |
7cd4527e AC |
14368 | If the compilation unit |
14369 | contained in the input source depends semantically upon units located | |
14370 | outside the current directory, you have to provide the source search path | |
14371 | when invoking @command{gnatpp}; see the description of the @command{gnatpp} | |
14372 | switches below. | |
88e1739c | 14373 | |
7cd4527e | 14374 | The @command{gnatpp} command has the form |
88e1739c | 14375 | |
7cd4527e AC |
14376 | @smallexample |
14377 | $ gnatpp [@var{switches}] @var{filename} | |
14378 | @end smallexample | |
88e1739c FW |
14379 | |
14380 | @noindent | |
7cd4527e AC |
14381 | where |
14382 | @itemize @bullet | |
14383 | @item | |
14384 | @var{switches} is an optional sequence of switches defining such properties as | |
14385 | the formatting rules, the source search path, and the destination for the | |
14386 | output source file | |
88e1739c | 14387 | |
7cd4527e AC |
14388 | @item |
14389 | @var{filename} is the name (including the extension) of the source file to | |
14390 | reformat; ``wildcards'' or several file names on the same gnatpp command are | |
14391 | allowed. The file name may contain path information; it does not have to follow | |
14392 | the GNAT file naming rules | |
14393 | @end itemize | |
88e1739c | 14394 | |
88e1739c | 14395 | |
7cd4527e AC |
14396 | @menu |
14397 | * Switches for gnatpp:: | |
14398 | * Formatting Rules:: | |
14399 | @end menu | |
88e1739c | 14400 | |
7cd4527e AC |
14401 | @node Switches for gnatpp |
14402 | @section Switches for @command{gnatpp} | |
88e1739c | 14403 | |
7cd4527e AC |
14404 | @noindent |
14405 | The following subsections describe the various switches accepted by | |
14406 | @command{gnatpp}, organized by category. | |
88e1739c | 14407 | |
7cd4527e AC |
14408 | @ifclear vms |
14409 | You specify a switch by supplying a name and generally also a value. | |
14410 | In many cases the values for a switch with a given name are incompatible with | |
14411 | each other | |
14412 | (for example the switch that controls the casing of a reserved word may have | |
14413 | exactly one value: upper case, lower case, or | |
14414 | mixed case) and thus exactly one such switch can be in effect for an | |
14415 | invocation of @command{gnatpp}. | |
14416 | If more than one is supplied, the last one is used. | |
14417 | However, some values for the same switch are mutually compatible. | |
14418 | You may supply several such switches to @command{gnatpp}, but then | |
14419 | each must be specified in full, with both the name and the value. | |
14420 | Abbreviated forms (the name appearing once, followed by each value) are | |
14421 | not permitted. | |
14422 | For example, to set | |
14423 | the alignment of the assignment delimiter both in declarations and in | |
14424 | assignment statements, you must write @option{-A2A3} | |
14425 | (or @option{-A2 -A3}), but not @option{-A23}. | |
14426 | @end ifclear | |
88e1739c FW |
14427 | |
14428 | @ifset vms | |
7cd4527e AC |
14429 | In many cases the set of options for a given qualifier are incompatible with |
14430 | each other (for example the qualifier that controls the casing of a reserved | |
14431 | word may have exactly one option, which specifies either upper case, lower | |
14432 | case, or mixed case), and thus exactly one such option can be in effect for | |
14433 | an invocation of @command{gnatpp}. | |
14434 | If more than one is supplied, the last one is used. | |
14435 | However, some qualifiers have options that are mutually compatible, | |
14436 | and then you may then supply several such options when invoking | |
14437 | @command{gnatpp}. | |
88e1739c | 14438 | @end ifset |
7cd4527e AC |
14439 | |
14440 | In most cases, it is obvious whether or not the | |
14441 | ^values for a switch with a given name^options for a given qualifier^ | |
14442 | are compatible with each other. | |
14443 | When the semantics might not be evident, the summaries below explicitly | |
14444 | indicate the effect. | |
14445 | ||
14446 | @menu | |
14447 | * Alignment Control:: | |
14448 | * Casing Control:: | |
14449 | * Construct Layout Control:: | |
14450 | * General Text Layout Control:: | |
14451 | * Other Formatting Options:: | |
14452 | * Setting the Source Search Path:: | |
14453 | * Output File Control:: | |
14454 | * Other gnatpp Switches:: | |
14455 | @end menu | |
14456 | ||
14457 | ||
14458 | @node Alignment Control | |
14459 | @subsection Alignment Control | |
14460 | @cindex Alignment control in @command{gnatpp} | |
14461 | ||
14462 | @noindent | |
14463 | Programs can be easier to read if certain constructs are vertically aligned. | |
14464 | By default all alignments are set ON. | |
14465 | Through the @option{^-A0^/ALIGN=OFF^} switch you may reset the default to | |
14466 | OFF, and then use one or more of the other | |
14467 | ^@option{-A@var{n}} switches^@option{/ALIGN} options^ | |
14468 | to activate alignment for specific constructs. | |
14469 | ||
14470 | @table @option | |
14471 | @cindex @option{^-A@var{n}^/ALIGN^} (@command{gnatpp}) | |
88e1739c FW |
14472 | |
14473 | @ifset vms | |
7cd4527e AC |
14474 | @item /ALIGN=ON |
14475 | Set all alignments to ON | |
88e1739c | 14476 | @end ifset |
88e1739c | 14477 | |
7cd4527e AC |
14478 | @item ^-A0^/ALIGN=OFF^ |
14479 | Set all alignments to OFF | |
88e1739c | 14480 | |
7cd4527e AC |
14481 | @item ^-A1^/ALIGN=COLONS^ |
14482 | Align @code{:} in declarations | |
88e1739c | 14483 | |
7cd4527e AC |
14484 | @item ^-A2^/ALIGN=DECLARATIONS^ |
14485 | Align @code{:=} in initializations in declarations | |
88e1739c | 14486 | |
7cd4527e AC |
14487 | @item ^-A3^/ALIGN=STATEMENTS^ |
14488 | Align @code{:=} in assignment statements | |
88e1739c | 14489 | |
7cd4527e AC |
14490 | @item ^-A4^/ALIGN=ARROWS^ |
14491 | Align @code{=>} in associations | |
14492 | @end table | |
88e1739c FW |
14493 | |
14494 | @noindent | |
7cd4527e AC |
14495 | The @option{^-A^/ALIGN^} switches are mutually compatible; any combination |
14496 | is allowed. | |
88e1739c | 14497 | |
88e1739c | 14498 | |
7cd4527e AC |
14499 | @node Casing Control |
14500 | @subsection Casing Control | |
14501 | @cindex Casing control in @command{gnatpp} | |
88e1739c | 14502 | |
7cd4527e AC |
14503 | @noindent |
14504 | @command{gnatpp} allows you to specify the casing for reserved words, | |
14505 | pragma names, attribute designators and identifiers. | |
14506 | For identifiers you may define a | |
14507 | general rule for name casing but also override this rule | |
14508 | via a set of dictionary files. | |
88e1739c | 14509 | |
7cd4527e AC |
14510 | Three types of casing are supported: lower case, upper case, and mixed case. |
14511 | Lower and upper case are self-explanatory (but since some letters in | |
14512 | Latin1 and other GNAT-supported character sets | |
14513 | exist only in lower-case form, an upper case conversion will have no | |
14514 | effect on them.) | |
14515 | ``Mixed case'' means that the first letter, and also each letter immediately | |
14516 | following an underscore, are converted to their uppercase forms; | |
14517 | all the other letters are converted to their lowercase forms. | |
88e1739c | 14518 | |
7cd4527e AC |
14519 | @table @option |
14520 | @cindex @option{^-a@var{x}^/ATTRIBUTE^} (@command{gnatpp}) | |
14521 | @item ^-aL^/ATTRIBUTE_CASING=LOWER_CASE^ | |
14522 | Attribute designators are lower case | |
88e1739c | 14523 | |
7cd4527e AC |
14524 | @item ^-aU^/ATTRIBUTE_CASING=UPPER_CASE^ |
14525 | Attribute designators are upper case | |
88e1739c | 14526 | |
7cd4527e AC |
14527 | @item ^-aM^/ATTRIBUTE_CASING=MIXED_CASE^ |
14528 | Attribute designators are mixed case (this is the default) | |
88e1739c | 14529 | |
7cd4527e AC |
14530 | @cindex @option{^-k@var{x}^/KEYWORD_CASING^} (@command{gnatpp}) |
14531 | @item ^-kL^/KEYWORD_CASING=LOWER_CASE^ | |
14532 | Keywords (technically, these are known in Ada as @emph{reserved words}) are | |
14533 | lower case (this is the default) | |
88e1739c | 14534 | |
7cd4527e AC |
14535 | @item ^-kU^/KEYWORD_CASING=UPPER_CASE^ |
14536 | Keywords are upper case | |
88e1739c | 14537 | |
7cd4527e AC |
14538 | @cindex @option{^-n@var{x}^/NAME_CASING^} (@command{gnatpp}) |
14539 | @item ^-nD^/NAME_CASING=AS_DECLARED^ | |
14540 | Name casing for defining occurrences are as they appear in the source file | |
14541 | (this is the default) | |
88e1739c | 14542 | |
7cd4527e AC |
14543 | @item ^-nU^/NAME_CASING=UPPER_CASE^ |
14544 | Names are in upper case | |
88e1739c | 14545 | |
7cd4527e AC |
14546 | @item ^-nL^/NAME_CASING=LOWER_CASE^ |
14547 | Names are in lower case | |
88e1739c | 14548 | |
7cd4527e AC |
14549 | @item ^-nM^/NAME_CASING=MIXED_CASE^ |
14550 | Names are in mixed case | |
88e1739c | 14551 | |
7cd4527e AC |
14552 | @cindex @option{^-p@var{x}^/PRAGMA_CASING^} (@command{gnatpp}) |
14553 | @item ^-pL^/PRAGMA_CASING=LOWER_CASE^ | |
14554 | Pragma names are lower case | |
88e1739c | 14555 | |
7cd4527e AC |
14556 | @item ^-pU^/PRAGMA_CASING=UPPER_CASE^ |
14557 | Pragma names are upper case | |
14558 | ||
14559 | @item ^-pM^/PRAGMA_CASING=MIXED_CASE^ | |
14560 | Pragma names are mixed case (this is the default) | |
14561 | ||
14562 | @item ^-D@var{file}^/DICTIONARY=@var{file}^ | |
14563 | @cindex @option{^-D^/DICTIONARY^} (@command{gnatpp}) | |
14564 | Use @var{file} as a @emph{dictionary file} that defines | |
14565 | the casing for a set of specified names, | |
14566 | thereby overriding the effect on these names by | |
14567 | any explicit or implicit | |
14568 | ^-n^/NAME_CASING^ switch. | |
14569 | To supply more than one dictionary file, | |
14570 | use ^several @option{-D} switches^a list of files as options^. | |
88e1739c FW |
14571 | |
14572 | @noindent | |
7cd4527e AC |
14573 | @option{gnatpp} implicitly uses a @emph{default dictionary file} |
14574 | to define the casing for the Ada predefined names and | |
14575 | the names declared in the GNAT libraries. | |
88e1739c | 14576 | |
7cd4527e AC |
14577 | @item ^-D-^/SPECIFIC_CASING^ |
14578 | @cindex @option{^-D-^/SPECIFIC_CASING^} (@command{gnatpp}) | |
14579 | Do not use the default dictionary file; | |
14580 | instead, use the casing | |
14581 | defined by a @option{^-n^/NAME_CASING^} switch and any explicit | |
14582 | dictionary file(s) | |
14583 | @end table | |
88e1739c | 14584 | |
7cd4527e AC |
14585 | @noindent |
14586 | The structure of a dictionary file, and details on the conventions | |
14587 | used in the default dictionary file, are defined in @ref{Name Casing}. | |
88e1739c | 14588 | |
7cd4527e AC |
14589 | The @option{^-D-^/SPECIFIC_CASING^} and |
14590 | @option{^-D@var{file}^/DICTIONARY=@var{file}^} switches are mutually | |
14591 | compatible. | |
88e1739c | 14592 | |
7cd4527e AC |
14593 | |
14594 | @node Construct Layout Control | |
14595 | @subsection Construct Layout Control | |
14596 | @cindex Layout control in @command{gnatpp} | |
88e1739c FW |
14597 | |
14598 | @noindent | |
7cd4527e AC |
14599 | This group of @command{gnatpp} switches controls the layout of comments and |
14600 | complex syntactic constructs. See @ref{Formatting Comments}, for details | |
14601 | on their effect. | |
88e1739c | 14602 | |
7cd4527e AC |
14603 | @table @option |
14604 | @cindex @option{^-c@var{n}^/COMMENTS_LAYOUT^} (@command{gnatpp}) | |
14605 | @item ^-c1^/COMMENTS_LAYOUT=DEFAULT^ | |
14606 | GNAT-style comment line indentation (this is the default). | |
88e1739c | 14607 | |
7cd4527e AC |
14608 | @item ^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^ |
14609 | Reference-manual comment line indentation. | |
88e1739c | 14610 | |
7cd4527e AC |
14611 | @item ^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^ |
14612 | GNAT-style comment beginning | |
88e1739c | 14613 | |
7cd4527e AC |
14614 | @item ^-c4^/COMMENTS_LAYOUT=REFORMAT^ |
14615 | Reformat comment blocks | |
88e1739c | 14616 | |
7cd4527e AC |
14617 | @cindex @option{^-l@var{n}^/CONSTRUCT_LAYOUT^} (@command{gnatpp}) |
14618 | @item ^-l1^/CONSTRUCT_LAYOUT=GNAT^ | |
14619 | GNAT-style layout (this is the default) | |
14620 | ||
14621 | @item ^-l2^/CONSTRUCT_LAYOUT=COMPACT^ | |
14622 | Compact layout | |
14623 | ||
14624 | @item ^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^ | |
14625 | Uncompact layout | |
14626 | ||
14627 | @item ^-notab^/NOTABS^ | |
14628 | All the VT characters are removed from the comment text. All the HT characters are | |
14629 | expanded with the sequences of space characters to get to the next tab stops. | |
88e1739c FW |
14630 | |
14631 | @end table | |
14632 | ||
14633 | @ifclear vms | |
7cd4527e AC |
14634 | @noindent |
14635 | The @option{-c1} and @option{-c2} switches are incompatible. | |
14636 | The @option{-c3} and @option{-c4} switches are compatible with each other and | |
14637 | also with @option{-c1} and @option{-c2}. | |
88e1739c | 14638 | |
7cd4527e AC |
14639 | The @option{-l1}, @option{-l2}, and @option{-l3} switches are incompatible. |
14640 | @end ifclear | |
88e1739c | 14641 | |
7cd4527e AC |
14642 | @ifset vms |
14643 | @noindent | |
14644 | For the @option{/COMMENTS_LAYOUT} qualifier: | |
14645 | @itemize @bullet | |
14646 | @item | |
14647 | The @option{DEFAULT} and @option{STANDARD_INDENT} options are incompatible. | |
14648 | @item | |
14649 | The @option{GNAT_BEGINNING} and @option{REFORMAT} options are compatible with | |
14650 | each other and also with @option{DEFAULT} and @option{STANDARD_INDENT}. | |
14651 | @end itemize | |
88e1739c FW |
14652 | |
14653 | @noindent | |
7cd4527e AC |
14654 | The @option{GNAT}, @option{COMPACT}, and @option{UNCOMPACT} options for the |
14655 | @option{/CONSTRUCT_LAYOUT} qualifier are incompatible. | |
14656 | @end ifset | |
88e1739c | 14657 | |
7cd4527e AC |
14658 | @node General Text Layout Control |
14659 | @subsection General Text Layout Control | |
88e1739c | 14660 | |
7cd4527e AC |
14661 | @noindent |
14662 | These switches allow control over line length and indentation. | |
88e1739c | 14663 | |
7cd4527e AC |
14664 | @table @option |
14665 | @item ^-M@i{nnn}^/LINE_LENGTH_MAX=@i{nnn}^ | |
14666 | @cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp}) | |
14667 | Maximum line length, @i{nnn} from 32 ..256, the default value is 79 | |
88e1739c | 14668 | |
7cd4527e AC |
14669 | @item ^-i@i{nnn}^/INDENTATION_LEVEL=@i{nnn}^ |
14670 | @cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp}) | |
14671 | Indentation level, @i{nnn} from 1 .. 9, the default value is 3 | |
88e1739c | 14672 | |
7cd4527e AC |
14673 | @item ^-cl@i{nnn}^/CONTINUATION_INDENT=@i{nnn}^ |
14674 | @cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp}) | |
14675 | Indentation level for continuation lines (relative to the line being | |
14676 | continued), @i{nnn} from 1 .. 9. | |
14677 | The default | |
14678 | value is one less then the (normal) indentation level, unless the | |
14679 | indentation is set to 1 (in which case the default value for continuation | |
14680 | line indentation is also 1) | |
14681 | @end table | |
88e1739c | 14682 | |
7cd4527e AC |
14683 | |
14684 | @node Other Formatting Options | |
14685 | @subsection Other Formatting Options | |
14686 | ||
14687 | @noindent | |
14688 | These switches control the inclusion of missing end/exit labels, and | |
14689 | the indentation level in @b{case} statements. | |
14690 | ||
14691 | @table @option | |
14692 | @item ^-e^/NO_MISSED_LABELS^ | |
14693 | @cindex @option{^-e^/NO_MISSED_LABELS^} (@command{gnatpp}) | |
14694 | Do not insert missing end/exit labels. An end label is the name of | |
14695 | a construct that may optionally be repeated at the end of the | |
14696 | construct's declaration; | |
14697 | e.g., the names of packages, subprograms, and tasks. | |
14698 | An exit label is the name of a loop that may appear as target | |
14699 | of an exit statement within the loop. | |
14700 | By default, @command{gnatpp} inserts these end/exit labels when | |
14701 | they are absent from the original source. This option suppresses such | |
14702 | insertion, so that the formatted source reflects the original. | |
14703 | ||
14704 | @item ^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^ | |
14705 | @cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp}) | |
14706 | Insert a Form Feed character after a pragma Page. | |
14707 | ||
14708 | @item ^-T@i{nnn}^/MAX_INDENT=@i{nnn}^ | |
14709 | @cindex @option{^-T^/MAX_INDENT^} (@command{gnatpp}) | |
14710 | Do not use an additional indentation level for @b{case} alternatives | |
14711 | and variants if there are @i{nnn} or more (the default | |
14712 | value is 10). | |
14713 | If @i{nnn} is 0, an additional indentation level is | |
14714 | used for @b{case} alternatives and variants regardless of their number. | |
14715 | @end table | |
14716 | ||
14717 | @node Setting the Source Search Path | |
14718 | @subsection Setting the Source Search Path | |
88e1739c FW |
14719 | |
14720 | @noindent | |
7cd4527e AC |
14721 | To define the search path for the input source file, @command{gnatpp} |
14722 | uses the same switches as the GNAT compiler, with the same effects. | |
88e1739c | 14723 | |
7cd4527e AC |
14724 | @table @option |
14725 | @item ^-I^/SEARCH=^@var{dir} | |
14726 | @cindex @option{^-I^/SEARCH^} (@code{gnatpp}) | |
14727 | The same as the corresponding gcc switch | |
88e1739c | 14728 | |
7cd4527e AC |
14729 | @item ^-I-^/NOCURRENT_DIRECTORY^ |
14730 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatpp}) | |
14731 | The same as the corresponding gcc switch | |
88e1739c | 14732 | |
7cd4527e AC |
14733 | @item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE^=@var{path} |
14734 | @cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@code{gnatpp}) | |
14735 | The same as the corresponding gcc switch | |
88e1739c | 14736 | |
7cd4527e AC |
14737 | @item ^--RTS^/RUNTIME_SYSTEM^=@var{path} |
14738 | @cindex @option{^--RTS^/RUNTIME_SYSTEM^} (@code{gnatpp}) | |
14739 | The same as the corresponding gcc switch | |
88e1739c | 14740 | |
7cd4527e | 14741 | @end table |
88e1739c | 14742 | |
88e1739c | 14743 | |
7cd4527e AC |
14744 | @node Output File Control |
14745 | @subsection Output File Control | |
14746 | ||
14747 | @noindent | |
14748 | By default the output is sent to the file whose name is obtained by appending | |
14749 | the ^@file{.pp}^@file{$PP}^ suffix to the name of the input file | |
14750 | (if the file with this name already exists, it is unconditionally overwritten). | |
14751 | Thus if the input file is @file{^my_ada_proc.adb^MY_ADA_PROC.ADB^} then | |
14752 | @command{gnatpp} will produce @file{^my_ada_proc.adb.pp^MY_ADA_PROC.ADB$PP^} | |
14753 | as output file. | |
14754 | The output may be redirected by the following switches: | |
14755 | ||
14756 | @table @option | |
14757 | @item ^-pipe^/STANDARD_OUTPUT^ | |
14758 | @cindex @option{^-pipe^/STANDARD_OUTPUT^} (@code{gnatpp}) | |
14759 | Send the output to @code{Standard_Output} | |
14760 | ||
14761 | @item ^-o @var{output_file}^/OUTPUT=@var{output_file}^ | |
14762 | @cindex @option{^-o^/OUTPUT^} (@code{gnatpp}) | |
14763 | Write the output into @var{output_file}. | |
14764 | If @var{output_file} already exists, @command{gnatpp} terminates without | |
14765 | reading or processing the input file. | |
14766 | ||
14767 | @item ^-of ^/FORCED_OUTPUT=^@var{output_file} | |
14768 | @cindex @option{^-of^/FORCED_OUTPUT^} (@code{gnatpp}) | |
14769 | Write the output into @var{output_file}, overwriting the existing file | |
14770 | (if one is present). | |
14771 | ||
14772 | @item ^-r^/REPLACE^ | |
14773 | @cindex @option{^-r^/REPLACE^} (@code{gnatpp}) | |
14774 | Replace the input source file with the reformatted output, and copy the | |
14775 | original input source into the file whose name is obtained by appending the | |
14776 | ^@file{.npp}^@file{$NPP}^ suffix to the name of the input file. | |
14777 | If a file with this name already exists, @command{gnatpp} terminates without | |
14778 | reading or processing the input file. | |
14779 | ||
14780 | @item ^-rf^/OVERRIDING_REPLACE^ | |
14781 | @cindex @option{^-rf^/OVERRIDING_REPLACE^} (@code{gnatpp}) | |
14782 | Like @option{^-r^/REPLACE^} except that if the file with the specified name | |
14783 | already exists, it is overwritten. | |
14784 | @end table | |
88e1739c | 14785 | |
7cd4527e AC |
14786 | @noindent |
14787 | Options @option{^-pipe^/STANDARD_OUTPUT^}, | |
14788 | @option{^-o^/OUTPUT^} and | |
14789 | @option{^-of^/FORCED_OUTPUT^} are allowed only if the call to gnatpp | |
14790 | contains only one file to reformat | |
88e1739c | 14791 | |
7cd4527e AC |
14792 | @node Other gnatpp Switches |
14793 | @subsection Other @code{gnatpp} Switches | |
14794 | ||
14795 | @noindent | |
14796 | The additional @command{gnatpp} switches are defined in this subsection. | |
88e1739c | 14797 | |
7cd4527e AC |
14798 | @table @option |
14799 | @item ^-v^/VERBOSE^ | |
14800 | @cindex @option{^-v^/VERBOSE^} (@code{gnatpp}) | |
14801 | Verbose mode; | |
14802 | @command{gnatpp} generates version information and then | |
14803 | a trace of the actions it takes to produce or obtain the ASIS tree. | |
14804 | ||
14805 | @item ^-w^/WARNINGS^ | |
14806 | @cindex @option{^-w^/WARNINGS^} (@code{gnatpp}) | |
14807 | Warning mode; | |
14808 | @command{gnatpp} generates a warning whenever it can not provide | |
14809 | a required layout in the result source. | |
88e1739c FW |
14810 | @end table |
14811 | ||
7cd4527e AC |
14812 | |
14813 | @node Formatting Rules | |
14814 | @section Formatting Rules | |
88e1739c FW |
14815 | |
14816 | @noindent | |
7cd4527e AC |
14817 | The following subsections show how @command{gnatpp} treats ``white space'', |
14818 | comments, program layout, and name casing. | |
14819 | They provide the detailed descriptions of the switches shown above. | |
14820 | ||
88e1739c | 14821 | @menu |
7cd4527e AC |
14822 | * White Space and Empty Lines:: |
14823 | * Formatting Comments:: | |
14824 | * Construct Layout:: | |
14825 | * Name Casing:: | |
88e1739c FW |
14826 | @end menu |
14827 | ||
7cd4527e AC |
14828 | |
14829 | @node White Space and Empty Lines | |
14830 | @subsection White Space and Empty Lines | |
88e1739c FW |
14831 | |
14832 | @noindent | |
7cd4527e AC |
14833 | @command{gnatpp} does not have an option to control space characters. |
14834 | It will add or remove spaces according to the style illustrated by the | |
14835 | examples in the @cite{Ada Reference Manual}. | |
14836 | ||
14837 | The only format effectors | |
14838 | (see @cite{Ada Reference Manual}, paragraph 2.1(13)) | |
14839 | that will appear in the output file are platform-specific line breaks, | |
14840 | and also format effectors within (but not at the end of) comments. | |
14841 | In particular, each horizontal tab character that is not inside | |
14842 | a comment will be treated as a space and thus will appear in the | |
14843 | output file as zero or more spaces depending on | |
14844 | the reformatting of the line in which it appears. | |
14845 | The only exception is a Form Feed character, which is inserted after a | |
14846 | pragma @code{Page} when @option{-ff} is set. | |
14847 | ||
14848 | The output file will contain no lines with trailing ``white space'' (spaces, | |
14849 | format effectors). | |
14850 | ||
14851 | Empty lines in the original source are preserved | |
14852 | only if they separate declarations or statements. | |
14853 | In such contexts, a | |
14854 | sequence of two or more empty lines is replaced by exactly one empty line. | |
14855 | Note that a blank line will be removed if it separates two ``comment blocks'' | |
14856 | (a comment block is a sequence of whole-line comments). | |
14857 | In order to preserve a visual separation between comment blocks, use an | |
14858 | ``empty comment'' (a line comprising only hyphens) rather than an empty line. | |
14859 | Likewise, if for some reason you wish to have a sequence of empty lines, | |
14860 | use a sequence of empty comments instead. | |
14861 | ||
14862 | ||
14863 | @node Formatting Comments | |
14864 | @subsection Formatting Comments | |
14865 | ||
14866 | @noindent | |
14867 | Comments in Ada code are of two kinds: | |
88e1739c FW |
14868 | @itemize @bullet |
14869 | @item | |
7cd4527e AC |
14870 | a @emph{whole-line comment}, which appears by itself (possibly preceded by |
14871 | ``white space'') on a line | |
14872 | ||
88e1739c | 14873 | @item |
7cd4527e AC |
14874 | an @emph{end-of-line comment}, which follows some other Ada lexical element |
14875 | on the same line. | |
88e1739c | 14876 | @end itemize |
88e1739c FW |
14877 | |
14878 | @noindent | |
7cd4527e AC |
14879 | The indentation of a whole-line comment is that of either |
14880 | the preceding or following line in | |
14881 | the formatted source, depending on switch settings as will be described below. | |
14882 | ||
14883 | For an end-of-line comment, @command{gnatpp} leaves the same number of spaces | |
14884 | between the end of the preceding Ada lexical element and the beginning | |
14885 | of the comment as appear in the original source, | |
14886 | unless either the comment has to be split to | |
14887 | satisfy the line length limitation, or else the next line contains a | |
14888 | whole line comment that is considered a continuation of this end-of-line | |
14889 | comment (because it starts at the same position). | |
14890 | In the latter two | |
14891 | cases, the start of the end-of-line comment is moved right to the nearest | |
14892 | multiple of the indentation level. | |
14893 | This may result in a ``line overflow'' (the right-shifted comment extending | |
14894 | beyond the maximum line length), in which case the comment is split as | |
14895 | described below. | |
88e1739c | 14896 | |
7cd4527e AC |
14897 | There is a difference between @option{^-c1^/COMMENTS_LAYOUT=DEFAULT^} |
14898 | (GNAT-style comment line indentation) | |
14899 | and @option{^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^} | |
14900 | (reference-manual comment line indentation). | |
14901 | With reference-manual style, a whole-line comment is indented as if it | |
14902 | were a declaration or statement at the same place | |
14903 | (i.e., according to the indentation of the preceding line(s)). | |
14904 | With GNAT style, a whole-line comment that is immediately followed by an | |
14905 | @b{if} or @b{case} statement alternative, a record variant, or the reserved | |
14906 | word @b{begin}, is indented based on the construct that follows it. | |
88e1739c | 14907 | |
7cd4527e AC |
14908 | For example: |
14909 | @smallexample @c ada | |
14910 | @cartouche | |
14911 | if A then | |
14912 | null; | |
14913 | -- some comment | |
14914 | else | |
14915 | null; | |
14916 | end if; | |
14917 | @end cartouche | |
88e1739c | 14918 | @end smallexample |
88e1739c FW |
14919 | |
14920 | @noindent | |
7cd4527e | 14921 | Reference-manual indentation produces: |
88e1739c | 14922 | |
7cd4527e AC |
14923 | @smallexample @c ada |
14924 | @cartouche | |
14925 | if A then | |
14926 | null; | |
14927 | -- some comment | |
14928 | else | |
14929 | null; | |
14930 | end if; | |
14931 | @end cartouche | |
14932 | @end smallexample | |
88e1739c FW |
14933 | |
14934 | @noindent | |
7cd4527e | 14935 | while GNAT-style indentation produces: |
88e1739c | 14936 | |
7cd4527e AC |
14937 | @smallexample @c ada |
14938 | @cartouche | |
14939 | if A then | |
14940 | null; | |
14941 | -- some comment | |
14942 | else | |
14943 | null; | |
14944 | end if; | |
14945 | @end cartouche | |
14946 | @end smallexample | |
88e1739c FW |
14947 | |
14948 | @noindent | |
7cd4527e AC |
14949 | The @option{^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^} switch |
14950 | (GNAT style comment beginning) has the following | |
14951 | effect: | |
88e1739c FW |
14952 | |
14953 | @itemize @bullet | |
14954 | @item | |
7cd4527e AC |
14955 | For each whole-line comment that does not end with two hyphens, |
14956 | @command{gnatpp} inserts spaces if necessary after the starting two hyphens | |
14957 | to ensure that there are at least two spaces between these hyphens and the | |
14958 | first non-blank character of the comment. | |
14959 | @end itemize | |
88e1739c | 14960 | |
7cd4527e AC |
14961 | @noindent |
14962 | For an end-of-line comment, if in the original source the next line is a | |
14963 | whole-line comment that starts at the same position | |
14964 | as the end-of-line comment, | |
14965 | then the whole-line comment (and all whole-line comments | |
14966 | that follow it and that start at the same position) | |
14967 | will start at this position in the output file. | |
88e1739c | 14968 | |
7cd4527e AC |
14969 | @noindent |
14970 | That is, if in the original source we have: | |
88e1739c | 14971 | |
7cd4527e AC |
14972 | @smallexample @c ada |
14973 | @cartouche | |
14974 | begin | |
14975 | A := B + C; -- B must be in the range Low1..High1 | |
14976 | -- C must be in the range Low2..High2 | |
14977 | --B+C will be in the range Low1+Low2..High1+High2 | |
14978 | X := X + 1; | |
14979 | @end cartouche | |
88e1739c FW |
14980 | @end smallexample |
14981 | ||
7cd4527e AC |
14982 | @noindent |
14983 | Then in the formatted source we get | |
88e1739c | 14984 | |
7cd4527e AC |
14985 | @smallexample @c ada |
14986 | @cartouche | |
14987 | begin | |
14988 | A := B + C; -- B must be in the range Low1..High1 | |
14989 | -- C must be in the range Low2..High2 | |
14990 | -- B+C will be in the range Low1+Low2..High1+High2 | |
14991 | X := X + 1; | |
14992 | @end cartouche | |
14993 | @end smallexample | |
88e1739c | 14994 | |
7cd4527e AC |
14995 | @noindent |
14996 | A comment that exceeds the line length limit will be split. | |
14997 | Unless switch | |
14998 | @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} (reformat comment blocks) is set and | |
14999 | the line belongs to a reformattable block, splitting the line generates a | |
15000 | @command{gnatpp} warning. | |
15001 | The @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} switch specifies that whole-line | |
15002 | comments may be reformatted in typical | |
15003 | word processor style (that is, moving words between lines and putting as | |
15004 | many words in a line as possible). | |
15005 | ||
15006 | ||
15007 | @node Construct Layout | |
15008 | @subsection Construct Layout | |
15009 | ||
15010 | @noindent | |
15011 | The difference between GNAT style @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^} | |
15012 | and compact @option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^} | |
15013 | layout on the one hand, and uncompact layout | |
15014 | @option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} on the other hand, | |
15015 | can be illustrated by the following examples: | |
15016 | ||
15017 | @iftex | |
15018 | @cartouche | |
15019 | @multitable @columnfractions .5 .5 | |
15020 | @item @i{GNAT style, compact layout} @tab @i{Uncompact layout} | |
15021 | ||
15022 | @item | |
15023 | @smallexample @c ada | |
15024 | type q is record | |
15025 | a : integer; | |
15026 | b : integer; | |
15027 | end record; | |
15028 | @end smallexample | |
15029 | @tab | |
15030 | @smallexample @c ada | |
15031 | type q is | |
15032 | record | |
15033 | a : integer; | |
15034 | b : integer; | |
15035 | end record; | |
15036 | @end smallexample | |
15037 | ||
15038 | @item | |
15039 | @smallexample @c ada | |
15040 | Block : declare | |
15041 | A : Integer := 3; | |
15042 | begin | |
15043 | Proc (A, A); | |
15044 | end Block; | |
15045 | @end smallexample | |
15046 | @tab | |
15047 | @smallexample @c ada | |
15048 | Block : | |
15049 | declare | |
15050 | A : Integer := 3; | |
15051 | begin | |
15052 | Proc (A, A); | |
15053 | end Block; | |
15054 | @end smallexample | |
15055 | ||
15056 | @item | |
15057 | @smallexample @c ada | |
15058 | Clear : for J in 1 .. 10 loop | |
15059 | A (J) := 0; | |
15060 | end loop Clear; | |
15061 | @end smallexample | |
15062 | @tab | |
15063 | @smallexample @c ada | |
15064 | Clear : | |
15065 | for J in 1 .. 10 loop | |
15066 | A (J) := 0; | |
15067 | end loop Clear; | |
15068 | @end smallexample | |
15069 | @end multitable | |
15070 | @end cartouche | |
15071 | @end iftex | |
15072 | ||
6da7d579 | 15073 | @ifnottex |
7cd4527e AC |
15074 | @smallexample |
15075 | @cartouche | |
15076 | GNAT style, compact layout Uncompact layout | |
15077 | ||
15078 | type q is record type q is | |
15079 | a : integer; record | |
15080 | b : integer; a : integer; | |
15081 | end record; b : integer; | |
15082 | end record; | |
15083 | ||
15084 | ||
15085 | Block : declare Block : | |
15086 | A : Integer := 3; declare | |
15087 | begin A : Integer := 3; | |
15088 | Proc (A, A); begin | |
15089 | end Block; Proc (A, A); | |
15090 | end Block; | |
15091 | ||
15092 | Clear : for J in 1 .. 10 loop Clear : | |
15093 | A (J) := 0; for J in 1 .. 10 loop | |
15094 | end loop Clear; A (J) := 0; | |
15095 | end loop Clear; | |
15096 | @end cartouche | |
15097 | @end smallexample | |
6da7d579 | 15098 | @end ifnottex |
7cd4527e AC |
15099 | |
15100 | @noindent | |
15101 | A further difference between GNAT style layout and compact layout is that | |
15102 | GNAT style layout inserts empty lines as separation for | |
15103 | compound statements, return statements and bodies. | |
15104 | ||
15105 | ||
15106 | @node Name Casing | |
15107 | @subsection Name Casing | |
15108 | ||
15109 | @noindent | |
15110 | @command{gnatpp} always converts the usage occurrence of a (simple) name to | |
15111 | the same casing as the corresponding defining identifier. | |
15112 | ||
15113 | You control the casing for defining occurrences via the | |
15114 | @option{^-n^/NAME_CASING^} switch. | |
15115 | @ifclear vms | |
15116 | With @option{-nD} (``as declared'', which is the default), | |
15117 | @end ifclear | |
15118 | @ifset vms | |
15119 | With @option{/NAME_CASING=AS_DECLARED}, which is the default, | |
15120 | @end ifset | |
15121 | defining occurrences appear exactly as in the source file | |
15122 | where they are declared. | |
15123 | The other ^values for this switch^options for this qualifier^ --- | |
15124 | @option{^-nU^UPPER_CASE^}, | |
15125 | @option{^-nL^LOWER_CASE^}, | |
15126 | @option{^-nM^MIXED_CASE^} --- | |
15127 | result in | |
15128 | ^upper, lower, or mixed case, respectively^the corresponding casing^. | |
15129 | If @command{gnatpp} changes the casing of a defining | |
15130 | occurrence, it analogously changes the casing of all the | |
15131 | usage occurrences of this name. | |
15132 | ||
15133 | If the defining occurrence of a name is not in the source compilation unit | |
15134 | currently being processed by @command{gnatpp}, the casing of each reference to | |
15135 | this name is changed according to the value of the @option{^-n^/NAME_CASING^} | |
15136 | switch (subject to the dictionary file mechanism described below). | |
15137 | Thus @command{gnatpp} acts as though the @option{^-n^/NAME_CASING^} switch | |
15138 | had affected the | |
15139 | casing for the defining occurrence of the name. | |
15140 | ||
15141 | Some names may need to be spelled with casing conventions that are not | |
15142 | covered by the upper-, lower-, and mixed-case transformations. | |
15143 | You can arrange correct casing by placing such names in a | |
15144 | @emph{dictionary file}, | |
15145 | and then supplying a @option{^-D^/DICTIONARY^} switch. | |
15146 | The casing of names from dictionary files overrides | |
15147 | any @option{^-n^/NAME_CASING^} switch. | |
15148 | ||
15149 | To handle the casing of Ada predefined names and the names from GNAT libraries, | |
15150 | @command{gnatpp} assumes a default dictionary file. | |
15151 | The name of each predefined entity is spelled with the same casing as is used | |
15152 | for the entity in the @cite{Ada Reference Manual}. | |
15153 | The name of each entity in the GNAT libraries is spelled with the same casing | |
15154 | as is used in the declaration of that entity. | |
15155 | ||
15156 | The @w{@option{^-D-^/SPECIFIC_CASING^}} switch suppresses the use of the | |
15157 | default dictionary file. | |
15158 | Instead, the casing for predefined and GNAT-defined names will be established | |
15159 | by the @option{^-n^/NAME_CASING^} switch or explicit dictionary files. | |
15160 | For example, by default the names @code{Ada.Text_IO} and @code{GNAT.OS_Lib} | |
15161 | will appear as just shown, | |
15162 | even in the presence of a @option{^-nU^/NAME_CASING=UPPER_CASE^} switch. | |
15163 | To ensure that even such names are rendered in uppercase, | |
15164 | additionally supply the @w{@option{^-D-^/SPECIFIC_CASING^}} switch | |
15165 | (or else, less conveniently, place these names in upper case in a dictionary | |
15166 | file). | |
15167 | ||
15168 | A dictionary file is | |
15169 | a plain text file; each line in this file can be either a blank line | |
15170 | (containing only space characters and ASCII.HT characters), an Ada comment | |
15171 | line, or the specification of exactly one @emph{casing schema}. | |
15172 | ||
15173 | A casing schema is a string that has the following syntax: | |
15174 | ||
15175 | @smallexample | |
15176 | @cartouche | |
15177 | @var{casing_schema} ::= @var{identifier} | [*]@var{simple_identifier}[*] | |
15178 | ||
15179 | @var{simple_identifier} ::= @var{letter}@{@var{letter_or_digit}@} | |
15180 | @end cartouche | |
15181 | @end smallexample | |
15182 | ||
15183 | @noindent | |
15184 | (The @code{[]} metanotation stands for an optional part; | |
15185 | see @cite{Ada Reference Manual}, Section 2.3) for the definition of the | |
15186 | @var{identifier} lexical element and the @var{letter_or_digit} category). | |
15187 | ||
15188 | The casing schema string can be followed by white space and/or an Ada-style | |
15189 | comment; any amount of white space is allowed before the string. | |
15190 | ||
15191 | If a dictionary file is passed as | |
15192 | @ifclear vms | |
15193 | the value of a @option{-D@var{file}} switch | |
15194 | @end ifclear | |
15195 | @ifset vms | |
15196 | an option to the @option{/DICTIONARY} qualifier | |
15197 | @end ifset | |
15198 | then for every | |
15199 | simple name and every identifier, @command{gnatpp} checks if the dictionary | |
15200 | defines the casing for the name or for some of its parts (the term ``subword'' | |
15201 | is used below to denote the part of a name which is delimited by ``_'' or by | |
15202 | the beginning or end of the word and which does not contain any ``_'' inside): | |
15203 | ||
15204 | @itemize @bullet | |
15205 | @item | |
15206 | if the whole name is in the dictionary, @command{gnatpp} uses for this name | |
15207 | the casing defined by the dictionary; no subwords are checked for this word | |
15208 | ||
15209 | @item | |
15210 | for the first subword (that is, for the subword preceding the leftmost | |
15211 | ``_''), @command{gnatpp} checks if the dictionary contains the corresponding | |
15212 | string of the form @code{@var{simple_identifier}*}, and if it does, the | |
15213 | casing of this @var{simple_identifier} is used for this subword | |
15214 | ||
15215 | @item | |
15216 | for the last subword (following the rightmost ``_'') @command{gnatpp} | |
15217 | checks if the dictionary contains the corresponding string of the form | |
15218 | @code{*@var{simple_identifier}}, and if it does, the casing of this | |
15219 | @var{simple_identifier} is used for this subword | |
15220 | ||
15221 | @item | |
15222 | for every intermediate subword (surrounded by two'_') @command{gnatpp} checks | |
15223 | if the dictionary contains the corresponding string of the form | |
15224 | @code{*@var{simple_identifier}*}, and if it does, the casing of this | |
15225 | simple_identifier is used for this subword | |
15226 | ||
15227 | @item | |
15228 | if more than one dictionary file is passed as @command{gnatpp} switches, each | |
15229 | dictionary adds new casing exceptions and overrides all the existing casing | |
15230 | exceptions set by the previous dictionaries | |
15231 | ||
15232 | @item | |
15233 | when @command{gnatpp} checks if the word or subword is in the dictionary, | |
15234 | this check is not case sensitive | |
15235 | @end itemize | |
15236 | ||
15237 | @noindent | |
15238 | For example, suppose we have the following source to reformat: | |
15239 | ||
15240 | @smallexample @c ada | |
15241 | @cartouche | |
15242 | procedure test is | |
15243 | name1 : integer := 1; | |
15244 | name4_name3_name2 : integer := 2; | |
15245 | name2_name3_name4 : Boolean; | |
15246 | name1_var : Float; | |
15247 | begin | |
15248 | name2_name3_name4 := name4_name3_name2 > name1; | |
15249 | end; | |
15250 | @end cartouche | |
15251 | @end smallexample | |
15252 | ||
15253 | @noindent | |
15254 | And suppose we have two dictionaries: | |
15255 | ||
15256 | @smallexample | |
15257 | @cartouche | |
15258 | @i{dict1:} | |
15259 | NAME1 | |
15260 | *NaMe3* | |
15261 | *NAME2 | |
15262 | @end cartouche | |
15263 | ||
15264 | @cartouche | |
15265 | @i{dict2:} | |
15266 | *NAME3* | |
15267 | @end cartouche | |
15268 | @end smallexample | |
15269 | ||
15270 | @noindent | |
15271 | If @command{gnatpp} is called with the following switches: | |
15272 | ||
15273 | @smallexample | |
15274 | @ifclear vms | |
15275 | @command{gnatpp -nM -D dict1 -D dict2 test.adb} | |
15276 | @end ifclear | |
15277 | @ifset vms | |
15278 | @command{gnatpp test.adb /NAME_CASING=MIXED_CASE /DICTIONARY=(dict1, dict2)} | |
15279 | @end ifset | |
15280 | @end smallexample | |
15281 | ||
15282 | @noindent | |
15283 | then we will get the following name casing in the @command{gnatpp} output: | |
15284 | ||
15285 | @smallexample @c ada | |
15286 | @cartouche | |
15287 | procedure Test is | |
15288 | NAME1 : Integer := 1; | |
15289 | Name4_NAME3_NAME2 : integer := 2; | |
15290 | Name2_NAME3_Name4 : Boolean; | |
15291 | Name1_Var : Float; | |
15292 | begin | |
15293 | Name2_NAME3_Name4 := Name4_NAME3_NAME2 > NAME1; | |
15294 | end Test; | |
15295 | @end cartouche | |
15296 | @end smallexample | |
15297 | ||
15298 | ||
15299 | ||
15300 | @c *********************************** | |
15301 | @node File Name Krunching Using gnatkr | |
15302 | @chapter File Name Krunching Using @code{gnatkr} | |
15303 | @findex gnatkr | |
15304 | ||
15305 | @noindent | |
15306 | This chapter discusses the method used by the compiler to shorten | |
15307 | the default file names chosen for Ada units so that they do not | |
15308 | exceed the maximum length permitted. It also describes the | |
15309 | @code{gnatkr} utility that can be used to determine the result of | |
15310 | applying this shortening. | |
15311 | @menu | |
15312 | * About gnatkr:: | |
15313 | * Using gnatkr:: | |
15314 | * Krunching Method:: | |
15315 | * Examples of gnatkr Usage:: | |
15316 | @end menu | |
15317 | ||
15318 | @node About gnatkr | |
15319 | @section About @code{gnatkr} | |
15320 | ||
15321 | @noindent | |
15322 | The default file naming rule in GNAT | |
15323 | is that the file name must be derived from | |
15324 | the unit name. The exact default rule is as follows: | |
15325 | @itemize @bullet | |
15326 | @item | |
15327 | Take the unit name and replace all dots by hyphens. | |
15328 | @item | |
15329 | If such a replacement occurs in the | |
15330 | second character position of a name, and the first character is | |
15331 | ^a, g, s, or i^A, G, S, or I^ then replace the dot by the character | |
15332 | ^~ (tilde)^$ (dollar sign)^ | |
15333 | instead of a minus. | |
15334 | @end itemize | |
15335 | The reason for this exception is to avoid clashes | |
15336 | with the standard names for children of System, Ada, Interfaces, | |
15337 | and GNAT, which use the prefixes ^s- a- i- and g-^S- A- I- and G-^ | |
15338 | respectively. | |
15339 | ||
15340 | The @option{^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{nn}} | |
15341 | switch of the compiler activates a ``krunching'' | |
15342 | circuit that limits file names to nn characters (where nn is a decimal | |
15343 | integer). For example, using OpenVMS, | |
15344 | where the maximum file name length is | |
15345 | 39, the value of nn is usually set to 39, but if you want to generate | |
15346 | a set of files that would be usable if ported to a system with some | |
15347 | different maximum file length, then a different value can be specified. | |
15348 | The default value of 39 for OpenVMS need not be specified. | |
15349 | ||
15350 | The @code{gnatkr} utility can be used to determine the krunched name for | |
15351 | a given file, when krunched to a specified maximum length. | |
15352 | ||
15353 | @node Using gnatkr | |
15354 | @section Using @code{gnatkr} | |
15355 | ||
15356 | @noindent | |
15357 | The @code{gnatkr} command has the form | |
15358 | ||
15359 | @ifclear vms | |
15360 | @smallexample | |
15361 | $ gnatkr @var{name} [@var{length}] | |
15362 | @end smallexample | |
15363 | @end ifclear | |
15364 | ||
15365 | @ifset vms | |
15366 | @smallexample | |
15367 | $ gnatkr @var{name} /COUNT=nn | |
15368 | @end smallexample | |
15369 | @end ifset | |
15370 | ||
15371 | @noindent | |
15372 | @var{name} is the uncrunched file name, derived from the name of the unit | |
15373 | in the standard manner described in the previous section (i.e. in particular | |
15374 | all dots are replaced by hyphens). The file name may or may not have an | |
15375 | extension (defined as a suffix of the form period followed by arbitrary | |
15376 | characters other than period). If an extension is present then it will | |
15377 | be preserved in the output. For example, when krunching @file{hellofile.ads} | |
15378 | to eight characters, the result will be hellofil.ads. | |
15379 | ||
15380 | Note: for compatibility with previous versions of @code{gnatkr} dots may | |
15381 | appear in the name instead of hyphens, but the last dot will always be | |
15382 | taken as the start of an extension. So if @code{gnatkr} is given an argument | |
15383 | such as @file{Hello.World.adb} it will be treated exactly as if the first | |
15384 | period had been a hyphen, and for example krunching to eight characters | |
15385 | gives the result @file{hellworl.adb}. | |
15386 | ||
15387 | Note that the result is always all lower case (except on OpenVMS where it is | |
15388 | all upper case). Characters of the other case are folded as required. | |
15389 | ||
15390 | @var{length} represents the length of the krunched name. The default | |
15391 | when no argument is given is ^8^39^ characters. A length of zero stands for | |
15392 | unlimited, in other words do not chop except for system files where the | |
15393 | impled crunching length is always eight characters. | |
15394 | ||
15395 | @noindent | |
15396 | The output is the krunched name. The output has an extension only if the | |
15397 | original argument was a file name with an extension. | |
15398 | ||
15399 | @node Krunching Method | |
15400 | @section Krunching Method | |
15401 | ||
15402 | @noindent | |
15403 | The initial file name is determined by the name of the unit that the file | |
15404 | contains. The name is formed by taking the full expanded name of the | |
15405 | unit and replacing the separating dots with hyphens and | |
15406 | using ^lowercase^uppercase^ | |
15407 | for all letters, except that a hyphen in the second character position is | |
15408 | replaced by a ^tilde^dollar sign^ if the first character is | |
15409 | ^a, i, g, or s^A, I, G, or S^. | |
15410 | The extension is @code{.ads} for a | |
15411 | specification and @code{.adb} for a body. | |
15412 | Krunching does not affect the extension, but the file name is shortened to | |
15413 | the specified length by following these rules: | |
15414 | ||
15415 | @itemize @bullet | |
15416 | @item | |
15417 | The name is divided into segments separated by hyphens, tildes or | |
15418 | underscores and all hyphens, tildes, and underscores are | |
15419 | eliminated. If this leaves the name short enough, we are done. | |
15420 | ||
15421 | @item | |
15422 | If the name is too long, the longest segment is located (left-most | |
15423 | if there are two of equal length), and shortened by dropping | |
15424 | its last character. This is repeated until the name is short enough. | |
15425 | ||
15426 | As an example, consider the krunching of @*@file{our-strings-wide_fixed.adb} | |
15427 | to fit the name into 8 characters as required by some operating systems. | |
15428 | ||
15429 | @smallexample | |
15430 | our-strings-wide_fixed 22 | |
15431 | our strings wide fixed 19 | |
15432 | our string wide fixed 18 | |
15433 | our strin wide fixed 17 | |
15434 | our stri wide fixed 16 | |
15435 | our stri wide fixe 15 | |
15436 | our str wide fixe 14 | |
15437 | our str wid fixe 13 | |
15438 | our str wid fix 12 | |
15439 | ou str wid fix 11 | |
15440 | ou st wid fix 10 | |
15441 | ou st wi fix 9 | |
15442 | ou st wi fi 8 | |
15443 | Final file name: oustwifi.adb | |
15444 | @end smallexample | |
15445 | ||
15446 | @item | |
15447 | The file names for all predefined units are always krunched to eight | |
15448 | characters. The krunching of these predefined units uses the following | |
15449 | special prefix replacements: | |
15450 | ||
15451 | @table @file | |
15452 | @item ada- | |
15453 | replaced by @file{^a^A^-} | |
15454 | ||
15455 | @item gnat- | |
88e1739c FW |
15456 | replaced by @file{^g^G^-} |
15457 | ||
15458 | @item interfaces- | |
15459 | replaced by @file{^i^I^-} | |
15460 | ||
15461 | @item system- | |
15462 | replaced by @file{^s^S^-} | |
15463 | @end table | |
15464 | ||
15465 | These system files have a hyphen in the second character position. That | |
15466 | is why normal user files replace such a character with a | |
15467 | ^tilde^dollar sign^, to | |
15468 | avoid confusion with system file names. | |
15469 | ||
15470 | As an example of this special rule, consider | |
15471 | @*@file{ada-strings-wide_fixed.adb}, which gets krunched as follows: | |
15472 | ||
15473 | @smallexample | |
15474 | ada-strings-wide_fixed 22 | |
15475 | a- strings wide fixed 18 | |
15476 | a- string wide fixed 17 | |
15477 | a- strin wide fixed 16 | |
15478 | a- stri wide fixed 15 | |
15479 | a- stri wide fixe 14 | |
15480 | a- str wide fixe 13 | |
15481 | a- str wid fixe 12 | |
15482 | a- str wid fix 11 | |
15483 | a- st wid fix 10 | |
15484 | a- st wi fix 9 | |
15485 | a- st wi fi 8 | |
15486 | Final file name: a-stwifi.adb | |
15487 | @end smallexample | |
15488 | @end itemize | |
15489 | ||
15490 | Of course no file shortening algorithm can guarantee uniqueness over all | |
15491 | possible unit names, and if file name krunching is used then it is your | |
15492 | responsibility to ensure that no name clashes occur. The utility | |
15493 | program @code{gnatkr} is supplied for conveniently determining the | |
15494 | krunched name of a file. | |
15495 | ||
15496 | @node Examples of gnatkr Usage | |
15497 | @section Examples of @code{gnatkr} Usage | |
15498 | ||
15499 | @smallexample | |
15500 | @iftex | |
15501 | @leftskip=0cm | |
15502 | @end iftex | |
15503 | @ifclear vms | |
15504 | $ gnatkr very_long_unit_name.ads --> velounna.ads | |
15505 | $ gnatkr grandparent-parent-child.ads --> grparchi.ads | |
7cd4527e AC |
15506 | $ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads |
15507 | $ gnatkr grandparent-parent-child --> grparchi | |
88e1739c FW |
15508 | @end ifclear |
15509 | $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads | |
15510 | $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads | |
15511 | @end smallexample | |
15512 | ||
15513 | @node Preprocessing Using gnatprep | |
15514 | @chapter Preprocessing Using @code{gnatprep} | |
15515 | @findex gnatprep | |
15516 | ||
15517 | @noindent | |
15518 | The @code{gnatprep} utility provides | |
15519 | a simple preprocessing capability for Ada programs. | |
15520 | It is designed for use with GNAT, but is not dependent on any special | |
15521 | features of GNAT. | |
15522 | ||
15523 | @menu | |
15524 | * Using gnatprep:: | |
15525 | * Switches for gnatprep:: | |
15526 | * Form of Definitions File:: | |
15527 | * Form of Input Text for gnatprep:: | |
15528 | @end menu | |
15529 | ||
15530 | @node Using gnatprep | |
15531 | @section Using @code{gnatprep} | |
15532 | ||
15533 | @noindent | |
15534 | To call @code{gnatprep} use | |
15535 | ||
15536 | @smallexample | |
15537 | $ gnatprep [-bcrsu] [-Dsymbol=value] infile outfile [deffile] | |
15538 | @end smallexample | |
15539 | ||
15540 | @noindent | |
15541 | where | |
15542 | @table @code | |
15543 | @item infile | |
15544 | is the full name of the input file, which is an Ada source | |
15545 | file containing preprocessor directives. | |
15546 | ||
15547 | @item outfile | |
15548 | is the full name of the output file, which is an Ada source | |
15549 | in standard Ada form. When used with GNAT, this file name will | |
15550 | normally have an ads or adb suffix. | |
15551 | ||
15552 | @item deffile | |
15553 | is the full name of a text file containing definitions of | |
15554 | symbols to be referenced by the preprocessor. This argument is | |
7cd4527e | 15555 | optional, and can be replaced by the use of the @option{-D} switch. |
88e1739c FW |
15556 | |
15557 | @item switches | |
15558 | is an optional sequence of switches as described in the next section. | |
15559 | @end table | |
15560 | ||
15561 | @node Switches for gnatprep | |
15562 | @section Switches for @code{gnatprep} | |
15563 | ||
7cd4527e AC |
15564 | @table @option |
15565 | @c !sort! | |
88e1739c FW |
15566 | |
15567 | @item ^-b^/BLANK_LINES^ | |
7cd4527e | 15568 | @cindex @option{^-b^/BLANK_LINES^} (@command{gnatprep}) |
88e1739c FW |
15569 | Causes both preprocessor lines and the lines deleted by |
15570 | preprocessing to be replaced by blank lines in the output source file, | |
15571 | preserving line numbers in the output file. | |
15572 | ||
15573 | @item ^-c^/COMMENTS^ | |
7cd4527e | 15574 | @cindex @option{^-c^/COMMENTS^} (@command{gnatprep}) |
88e1739c FW |
15575 | Causes both preprocessor lines and the lines deleted |
15576 | by preprocessing to be retained in the output source as comments marked | |
7cd4527e | 15577 | with the special string @code{"--! "}. This option will result in line numbers |
88e1739c FW |
15578 | being preserved in the output file. |
15579 | ||
7cd4527e AC |
15580 | @item ^-Dsymbol=value^/ASSOCIATE="symbol=value"^ |
15581 | @cindex @option{^-D^/ASSOCIATE^} (@command{gnatprep}) | |
88e1739c FW |
15582 | Defines a new symbol, associated with value. If no value is given on the |
15583 | command line, then symbol is considered to be @code{True}. This switch | |
15584 | can be used in place of a definition file. | |
15585 | ||
15586 | @ifset vms | |
7cd4527e AC |
15587 | @item /REMOVE |
15588 | @cindex @option{/REMOVE} (@command{gnatprep}) | |
88e1739c FW |
15589 | This is the default setting which causes lines deleted by preprocessing |
15590 | to be entirely removed from the output file. | |
15591 | @end ifset | |
15592 | ||
15593 | @item ^-r^/REFERENCE^ | |
7cd4527e | 15594 | @cindex @option{^-r^/REFERENCE^} (@command{gnatprep}) |
88e1739c FW |
15595 | Causes a @code{Source_Reference} pragma to be generated that |
15596 | references the original input file, so that error messages will use | |
15597 | the file name of this original file. The use of this switch implies | |
15598 | that preprocessor lines are not to be removed from the file, so its | |
7cd4527e AC |
15599 | use will force @option{^-b^/BLANK_LINES^} mode if |
15600 | @option{^-c^/COMMENTS^} | |
88e1739c FW |
15601 | has not been specified explicitly. |
15602 | ||
15603 | Note that if the file to be preprocessed contains multiple units, then | |
15604 | it will be necessary to @code{gnatchop} the output file from | |
15605 | @code{gnatprep}. If a @code{Source_Reference} pragma is present | |
15606 | in the preprocessed file, it will be respected by | |
15607 | @code{gnatchop ^-r^/REFERENCE^} | |
15608 | so that the final chopped files will correctly refer to the original | |
15609 | input source file for @code{gnatprep}. | |
15610 | ||
15611 | @item ^-s^/SYMBOLS^ | |
7cd4527e | 15612 | @cindex @option{^-s^/SYMBOLS^} (@command{gnatprep}) |
88e1739c FW |
15613 | Causes a sorted list of symbol names and values to be |
15614 | listed on the standard output file. | |
15615 | ||
15616 | @item ^-u^/UNDEFINED^ | |
7cd4527e | 15617 | @cindex @option{^-u^/UNDEFINED^} (@command{gnatprep}) |
88e1739c FW |
15618 | Causes undefined symbols to be treated as having the value FALSE in the context |
15619 | of a preprocessor test. In the absence of this option, an undefined symbol in | |
15620 | a @code{#if} or @code{#elsif} test will be treated as an error. | |
15621 | ||
15622 | @end table | |
15623 | ||
15624 | @ifclear vms | |
15625 | @noindent | |
7cd4527e | 15626 | Note: if neither @option{-b} nor @option{-c} is present, |
88e1739c FW |
15627 | then preprocessor lines and |
15628 | deleted lines are completely removed from the output, unless -r is | |
15629 | specified, in which case -b is assumed. | |
15630 | @end ifclear | |
15631 | ||
15632 | @node Form of Definitions File | |
15633 | @section Form of Definitions File | |
15634 | ||
15635 | @noindent | |
15636 | The definitions file contains lines of the form | |
15637 | ||
15638 | @smallexample | |
15639 | symbol := value | |
15640 | @end smallexample | |
15641 | ||
15642 | @noindent | |
15643 | where symbol is an identifier, following normal Ada (case-insensitive) | |
15644 | rules for its syntax, and value is one of the following: | |
15645 | ||
15646 | @itemize @bullet | |
15647 | @item | |
15648 | Empty, corresponding to a null substitution | |
15649 | @item | |
15650 | A string literal using normal Ada syntax | |
15651 | @item | |
15652 | Any sequence of characters from the set | |
15653 | (letters, digits, period, underline). | |
15654 | @end itemize | |
15655 | ||
15656 | @noindent | |
15657 | Comment lines may also appear in the definitions file, starting with | |
15658 | the usual @code{--}, | |
15659 | and comments may be added to the definitions lines. | |
15660 | ||
15661 | @node Form of Input Text for gnatprep | |
15662 | @section Form of Input Text for @code{gnatprep} | |
15663 | ||
15664 | @noindent | |
15665 | The input text may contain preprocessor conditional inclusion lines, | |
15666 | as well as general symbol substitution sequences. | |
15667 | ||
15668 | The preprocessor conditional inclusion commands have the form | |
15669 | ||
15670 | @smallexample | |
15671 | @group | |
15672 | @cartouche | |
15673 | #if @i{expression} [then] | |
15674 | lines | |
15675 | #elsif @i{expression} [then] | |
15676 | lines | |
15677 | #elsif @i{expression} [then] | |
15678 | lines | |
15679 | ... | |
15680 | #else | |
15681 | lines | |
15682 | #end if; | |
15683 | @end cartouche | |
15684 | @end group | |
15685 | @end smallexample | |
15686 | ||
15687 | @noindent | |
15688 | In this example, @i{expression} is defined by the following grammar: | |
15689 | @smallexample | |
15690 | @i{expression} ::= <symbol> | |
15691 | @i{expression} ::= <symbol> = "<value>" | |
15692 | @i{expression} ::= <symbol> = <symbol> | |
15693 | @i{expression} ::= <symbol> 'Defined | |
15694 | @i{expression} ::= not @i{expression} | |
15695 | @i{expression} ::= @i{expression} and @i{expression} | |
15696 | @i{expression} ::= @i{expression} or @i{expression} | |
15697 | @i{expression} ::= @i{expression} and then @i{expression} | |
15698 | @i{expression} ::= @i{expression} or else @i{expression} | |
15699 | @i{expression} ::= ( @i{expression} ) | |
15700 | @end smallexample | |
15701 | ||
15702 | @noindent | |
15703 | For the first test (@i{expression} ::= <symbol>) the symbol must have | |
15704 | either the value true or false, that is to say the right-hand of the | |
15705 | symbol definition must be one of the (case-insensitive) literals | |
15706 | @code{True} or @code{False}. If the value is true, then the | |
15707 | corresponding lines are included, and if the value is false, they are | |
15708 | excluded. | |
15709 | ||
15710 | The test (@i{expression} ::= <symbol> @code{'Defined}) is true only if | |
7cd4527e | 15711 | the symbol has been defined in the definition file or by a @option{-D} |
88e1739c FW |
15712 | switch on the command line. Otherwise, the test is false. |
15713 | ||
15714 | The equality tests are case insensitive, as are all the preprocessor lines. | |
15715 | ||
15716 | If the symbol referenced is not defined in the symbol definitions file, | |
7cd4527e | 15717 | then the effect depends on whether or not switch @option{-u} |
88e1739c FW |
15718 | is specified. If so, then the symbol is treated as if it had the value |
15719 | false and the test fails. If this switch is not specified, then | |
15720 | it is an error to reference an undefined symbol. It is also an error to | |
15721 | reference a symbol that is defined with a value other than @code{True} | |
15722 | or @code{False}. | |
15723 | ||
15724 | The use of the @code{not} operator inverts the sense of this logical test, so | |
15725 | that the lines are included only if the symbol is not defined. | |
15726 | The @code{then} keyword is optional as shown | |
15727 | ||
15728 | The @code{#} must be the first non-blank character on a line, but | |
15729 | otherwise the format is free form. Spaces or tabs may appear between | |
15730 | the @code{#} and the keyword. The keywords and the symbols are case | |
15731 | insensitive as in normal Ada code. Comments may be used on a | |
15732 | preprocessor line, but other than that, no other tokens may appear on a | |
15733 | preprocessor line. Any number of @code{elsif} clauses can be present, | |
15734 | including none at all. The @code{else} is optional, as in Ada. | |
15735 | ||
15736 | The @code{#} marking the start of a preprocessor line must be the first | |
15737 | non-blank character on the line, i.e. it must be preceded only by | |
15738 | spaces or horizontal tabs. | |
15739 | ||
15740 | Symbol substitution outside of preprocessor lines is obtained by using | |
15741 | the sequence | |
15742 | ||
15743 | @smallexample | |
15744 | $symbol | |
15745 | @end smallexample | |
15746 | ||
15747 | @noindent | |
15748 | anywhere within a source line, except in a comment or within a | |
15749 | string literal. The identifier | |
15750 | following the @code{$} must match one of the symbols defined in the symbol | |
15751 | definition file, and the result is to substitute the value of the | |
15752 | symbol in place of @code{$symbol} in the output file. | |
15753 | ||
15754 | Note that although the substitution of strings within a string literal | |
15755 | is not possible, it is possible to have a symbol whose defined value is | |
15756 | a string literal. So instead of setting XYZ to @code{hello} and writing: | |
15757 | ||
15758 | @smallexample | |
15759 | Header : String := "$XYZ"; | |
15760 | @end smallexample | |
15761 | ||
15762 | @noindent | |
15763 | you should set XYZ to @code{"hello"} and write: | |
15764 | ||
15765 | @smallexample | |
15766 | Header : String := $XYZ; | |
15767 | @end smallexample | |
15768 | ||
15769 | @noindent | |
15770 | and then the substitution will occur as desired. | |
15771 | ||
15772 | @ifset vms | |
15773 | @node The GNAT Run-Time Library Builder gnatlbr | |
15774 | @chapter The GNAT Run-Time Library Builder @code{gnatlbr} | |
15775 | @findex gnatlbr | |
15776 | @cindex Library builder | |
15777 | ||
15778 | @noindent | |
15779 | @code{gnatlbr} is a tool for rebuilding the GNAT run time with user | |
15780 | supplied configuration pragmas. | |
15781 | ||
15782 | @menu | |
15783 | * Running gnatlbr:: | |
15784 | * Switches for gnatlbr:: | |
15785 | * Examples of gnatlbr Usage:: | |
15786 | @end menu | |
15787 | ||
15788 | @node Running gnatlbr | |
15789 | @section Running @code{gnatlbr} | |
15790 | ||
15791 | @noindent | |
15792 | The @code{gnatlbr} command has the form | |
15793 | ||
15794 | @smallexample | |
88e1739c | 15795 | $ GNAT LIBRARY /[CREATE | SET | DELETE]=directory [/CONFIG=file] |
88e1739c FW |
15796 | @end smallexample |
15797 | ||
15798 | @node Switches for gnatlbr | |
15799 | @section Switches for @code{gnatlbr} | |
15800 | ||
15801 | @noindent | |
15802 | @code{gnatlbr} recognizes the following switches: | |
15803 | ||
7cd4527e AC |
15804 | @table @option |
15805 | @c !sort! | |
f1093866 | 15806 | @item /CREATE=directory |
7cd4527e | 15807 | @cindex @code{/CREATE} (@code{gnatlbr}) |
88e1739c FW |
15808 | Create the new run-time library in the specified directory. |
15809 | ||
f1093866 | 15810 | @item /SET=directory |
7cd4527e | 15811 | @cindex @code{/SET} (@code{gnatlbr}) |
88e1739c FW |
15812 | Make the library in the specified directory the current run-time |
15813 | library. | |
15814 | ||
f1093866 | 15815 | @item /DELETE=directory |
7cd4527e | 15816 | @cindex @code{/DELETE} (@code{gnatlbr}) |
88e1739c FW |
15817 | Delete the run-time library in the specified directory. |
15818 | ||
f1093866 | 15819 | @item /CONFIG=file |
7cd4527e | 15820 | @cindex @code{/CONFIG} (@code{gnatlbr}) |
f1093866 | 15821 | With /CREATE: |
88e1739c FW |
15822 | Use the configuration pragmas in the specified file when building |
15823 | the library. | |
15824 | ||
f1093866 | 15825 | With /SET: |
88e1739c FW |
15826 | Use the configuration pragmas in the specified file when compiling. |
15827 | ||
15828 | @end table | |
15829 | ||
15830 | @node Examples of gnatlbr Usage | |
15831 | @section Example of @code{gnatlbr} Usage | |
15832 | ||
15833 | @smallexample | |
15834 | Contents of VAXFLOAT.ADC: | |
15835 | pragma Float_Representation (VAX_Float); | |
15836 | ||
15837 | $ GNAT LIBRARY /CREATE=[.VAXFLOAT] /CONFIG=VAXFLOAT.ADC | |
15838 | ||
15839 | GNAT LIBRARY rebuilds the run-time library in directory [.VAXFLOAT] | |
15840 | ||
15841 | @end smallexample | |
15842 | @end ifset | |
15843 | ||
15844 | @node The GNAT Library Browser gnatls | |
15845 | @chapter The GNAT Library Browser @code{gnatls} | |
15846 | @findex gnatls | |
15847 | @cindex Library browser | |
15848 | ||
15849 | @noindent | |
15850 | @code{gnatls} is a tool that outputs information about compiled | |
15851 | units. It gives the relationship between objects, unit names and source | |
15852 | files. It can also be used to check the source dependencies of a unit | |
15853 | as well as various characteristics. | |
15854 | ||
15855 | @menu | |
15856 | * Running gnatls:: | |
15857 | * Switches for gnatls:: | |
15858 | * Examples of gnatls Usage:: | |
15859 | @end menu | |
15860 | ||
15861 | @node Running gnatls | |
15862 | @section Running @code{gnatls} | |
15863 | ||
15864 | @noindent | |
15865 | The @code{gnatls} command has the form | |
15866 | ||
15867 | @smallexample | |
15868 | $ gnatls switches @var{object_or_ali_file} | |
15869 | @end smallexample | |
15870 | ||
15871 | @noindent | |
15872 | The main argument is the list of object or @file{ali} files | |
15873 | (@pxref{The Ada Library Information Files}) | |
15874 | for which information is requested. | |
15875 | ||
15876 | In normal mode, without additional option, @code{gnatls} produces a | |
15877 | four-column listing. Each line represents information for a specific | |
15878 | object. The first column gives the full path of the object, the second | |
15879 | column gives the name of the principal unit in this object, the third | |
15880 | column gives the status of the source and the fourth column gives the | |
15881 | full path of the source representing this unit. | |
15882 | Here is a simple example of use: | |
15883 | ||
15884 | @smallexample | |
15885 | $ gnatls *.o | |
15886 | ^./^[]^demo1.o demo1 DIF demo1.adb | |
15887 | ^./^[]^demo2.o demo2 OK demo2.adb | |
15888 | ^./^[]^hello.o h1 OK hello.adb | |
15889 | ^./^[]^instr-child.o instr.child MOK instr-child.adb | |
15890 | ^./^[]^instr.o instr OK instr.adb | |
15891 | ^./^[]^tef.o tef DIF tef.adb | |
15892 | ^./^[]^text_io_example.o text_io_example OK text_io_example.adb | |
15893 | ^./^[]^tgef.o tgef DIF tgef.adb | |
15894 | @end smallexample | |
15895 | ||
15896 | @noindent | |
15897 | The first line can be interpreted as follows: the main unit which is | |
15898 | contained in | |
15899 | object file @file{demo1.o} is demo1, whose main source is in | |
15900 | @file{demo1.adb}. Furthermore, the version of the source used for the | |
15901 | compilation of demo1 has been modified (DIF). Each source file has a status | |
15902 | qualifier which can be: | |
15903 | ||
15904 | @table @code | |
15905 | @item OK (unchanged) | |
15906 | The version of the source file used for the compilation of the | |
15907 | specified unit corresponds exactly to the actual source file. | |
15908 | ||
15909 | @item MOK (slightly modified) | |
15910 | The version of the source file used for the compilation of the | |
15911 | specified unit differs from the actual source file but not enough to | |
15912 | require recompilation. If you use gnatmake with the qualifier | |
7cd4527e | 15913 | @option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}, a file marked |
88e1739c FW |
15914 | MOK will not be recompiled. |
15915 | ||
15916 | @item DIF (modified) | |
15917 | No version of the source found on the path corresponds to the source | |
15918 | used to build this object. | |
15919 | ||
15920 | @item ??? (file not found) | |
15921 | No source file was found for this unit. | |
15922 | ||
15923 | @item HID (hidden, unchanged version not first on PATH) | |
15924 | The version of the source that corresponds exactly to the source used | |
15925 | for compilation has been found on the path but it is hidden by another | |
15926 | version of the same source that has been modified. | |
15927 | ||
15928 | @end table | |
15929 | ||
15930 | @node Switches for gnatls | |
15931 | @section Switches for @code{gnatls} | |
15932 | ||
15933 | @noindent | |
15934 | @code{gnatls} recognizes the following switches: | |
15935 | ||
7cd4527e AC |
15936 | @table @option |
15937 | @c !sort! | |
88e1739c | 15938 | @item ^-a^/ALL_UNITS^ |
7cd4527e | 15939 | @cindex @option{^-a^/ALL_UNITS^} (@code{gnatls}) |
88e1739c | 15940 | Consider all units, including those of the predefined Ada library. |
7cd4527e | 15941 | Especially useful with @option{^-d^/DEPENDENCIES^}. |
88e1739c FW |
15942 | |
15943 | @item ^-d^/DEPENDENCIES^ | |
7cd4527e | 15944 | @cindex @option{^-d^/DEPENDENCIES^} (@code{gnatls}) |
88e1739c FW |
15945 | List sources from which specified units depend on. |
15946 | ||
15947 | @item ^-h^/OUTPUT=OPTIONS^ | |
7cd4527e | 15948 | @cindex @option{^-h^/OUTPUT=OPTIONS^} (@code{gnatls}) |
88e1739c FW |
15949 | Output the list of options. |
15950 | ||
15951 | @item ^-o^/OUTPUT=OBJECTS^ | |
7cd4527e | 15952 | @cindex @option{^-o^/OUTPUT=OBJECTS^} (@code{gnatls}) |
88e1739c FW |
15953 | Only output information about object files. |
15954 | ||
15955 | @item ^-s^/OUTPUT=SOURCES^ | |
7cd4527e | 15956 | @cindex @option{^-s^/OUTPUT=SOURCES^} (@code{gnatls}) |
88e1739c FW |
15957 | Only output information about source files. |
15958 | ||
15959 | @item ^-u^/OUTPUT=UNITS^ | |
7cd4527e | 15960 | @cindex @option{^-u^/OUTPUT=UNITS^} (@code{gnatls}) |
88e1739c FW |
15961 | Only output information about compilation units. |
15962 | ||
15963 | @item ^-aO^/OBJECT_SEARCH=^@var{dir} | |
15964 | @itemx ^-aI^/SOURCE_SEARCH=^@var{dir} | |
15965 | @itemx ^-I^/SEARCH=^@var{dir} | |
15966 | @itemx ^-I-^/NOCURRENT_DIRECTORY^ | |
15967 | @itemx -nostdinc | |
7cd4527e AC |
15968 | @cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatls}) |
15969 | @cindex @option{^-aI^/SOURCE_SEARCH^} (@code{gnatls}) | |
15970 | @cindex @option{^-I^/SEARCH^} (@code{gnatls}) | |
15971 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatls}) | |
88e1739c FW |
15972 | Source path manipulation. Same meaning as the equivalent @code{gnatmake} flags |
15973 | (see @ref{Switches for gnatmake}). | |
15974 | ||
15975 | @item --RTS=@var{rts-path} | |
7cd4527e | 15976 | @cindex @option{--RTS} (@code{gnatls}) |
88e1739c FW |
15977 | Specifies the default location of the runtime library. Same meaning as the |
15978 | equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}). | |
15979 | ||
15980 | @item ^-v^/OUTPUT=VERBOSE^ | |
7cd4527e | 15981 | @cindex @option{^-v^/OUTPUT=VERBOSE^} (@code{gnatls}) |
88e1739c FW |
15982 | Verbose mode. Output the complete source and object paths. Do not use |
15983 | the default column layout but instead use long format giving as much as | |
15984 | information possible on each requested units, including special | |
15985 | characteristics such as: | |
15986 | ||
15987 | @table @code | |
15988 | @item Preelaborable | |
15989 | The unit is preelaborable in the Ada 95 sense. | |
15990 | ||
15991 | @item No_Elab_Code | |
15992 | No elaboration code has been produced by the compiler for this unit. | |
15993 | ||
15994 | @item Pure | |
15995 | The unit is pure in the Ada 95 sense. | |
15996 | ||
15997 | @item Elaborate_Body | |
15998 | The unit contains a pragma Elaborate_Body. | |
15999 | ||
16000 | @item Remote_Types | |
16001 | The unit contains a pragma Remote_Types. | |
16002 | ||
16003 | @item Shared_Passive | |
16004 | The unit contains a pragma Shared_Passive. | |
16005 | ||
16006 | @item Predefined | |
16007 | This unit is part of the predefined environment and cannot be modified | |
16008 | by the user. | |
16009 | ||
16010 | @item Remote_Call_Interface | |
16011 | The unit contains a pragma Remote_Call_Interface. | |
16012 | ||
16013 | @end table | |
16014 | ||
16015 | @end table | |
16016 | ||
16017 | @node Examples of gnatls Usage | |
16018 | @section Example of @code{gnatls} Usage | |
16019 | @ifclear vms | |
16020 | ||
16021 | @noindent | |
16022 | Example of using the verbose switch. Note how the source and | |
f1093866 | 16023 | object paths are affected by the -I switch. |
88e1739c FW |
16024 | |
16025 | @smallexample | |
16026 | $ gnatls -v -I.. demo1.o | |
16027 | ||
16028 | GNATLS 3.10w (970212) Copyright 1999 Free Software Foundation, Inc. | |
16029 | ||
16030 | Source Search Path: | |
16031 | <Current_Directory> | |
16032 | ../ | |
16033 | /home/comar/local/adainclude/ | |
16034 | ||
16035 | Object Search Path: | |
16036 | <Current_Directory> | |
16037 | ../ | |
16038 | /home/comar/local/lib/gcc-lib/mips-sni-sysv4/2.7.2/adalib/ | |
16039 | ||
16040 | ./demo1.o | |
16041 | Unit => | |
16042 | Name => demo1 | |
16043 | Kind => subprogram body | |
16044 | Flags => No_Elab_Code | |
16045 | Source => demo1.adb modified | |
16046 | @end smallexample | |
16047 | ||
16048 | @noindent | |
16049 | The following is an example of use of the dependency list. | |
16050 | Note the use of the -s switch | |
16051 | which gives a straight list of source files. This can be useful for | |
16052 | building specialized scripts. | |
16053 | ||
16054 | @smallexample | |
16055 | $ gnatls -d demo2.o | |
16056 | ./demo2.o demo2 OK demo2.adb | |
16057 | OK gen_list.ads | |
16058 | OK gen_list.adb | |
16059 | OK instr.ads | |
16060 | OK instr-child.ads | |
16061 | ||
16062 | $ gnatls -d -s -a demo1.o | |
16063 | demo1.adb | |
16064 | /home/comar/local/adainclude/ada.ads | |
16065 | /home/comar/local/adainclude/a-finali.ads | |
16066 | /home/comar/local/adainclude/a-filico.ads | |
16067 | /home/comar/local/adainclude/a-stream.ads | |
16068 | /home/comar/local/adainclude/a-tags.ads | |
16069 | gen_list.ads | |
16070 | gen_list.adb | |
16071 | /home/comar/local/adainclude/gnat.ads | |
16072 | /home/comar/local/adainclude/g-io.ads | |
16073 | instr.ads | |
16074 | /home/comar/local/adainclude/system.ads | |
16075 | /home/comar/local/adainclude/s-exctab.ads | |
16076 | /home/comar/local/adainclude/s-finimp.ads | |
16077 | /home/comar/local/adainclude/s-finroo.ads | |
16078 | /home/comar/local/adainclude/s-secsta.ads | |
16079 | /home/comar/local/adainclude/s-stalib.ads | |
16080 | /home/comar/local/adainclude/s-stoele.ads | |
16081 | /home/comar/local/adainclude/s-stratt.ads | |
16082 | /home/comar/local/adainclude/s-tasoli.ads | |
16083 | /home/comar/local/adainclude/s-unstyp.ads | |
16084 | /home/comar/local/adainclude/unchconv.ads | |
16085 | @end smallexample | |
16086 | @end ifclear | |
16087 | ||
16088 | @ifset vms | |
16089 | @smallexample | |
16090 | GNAT LIST /DEPENDENCIES /OUTPUT=SOURCES /ALL_UNITS DEMO1.ADB | |
16091 | ||
16092 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]ada.ads | |
16093 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-finali.ads | |
16094 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-filico.ads | |
16095 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-stream.ads | |
16096 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-tags.ads | |
16097 | demo1.adb | |
16098 | gen_list.ads | |
16099 | gen_list.adb | |
16100 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]gnat.ads | |
16101 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]g-io.ads | |
16102 | instr.ads | |
16103 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]system.ads | |
16104 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-exctab.ads | |
16105 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finimp.ads | |
16106 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finroo.ads | |
16107 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-secsta.ads | |
16108 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stalib.ads | |
16109 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stoele.ads | |
16110 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stratt.ads | |
16111 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-tasoli.ads | |
16112 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-unstyp.ads | |
16113 | GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]unchconv.ads | |
16114 | @end smallexample | |
16115 | @end ifset | |
16116 | ||
7cd4527e AC |
16117 | @node Cleaning Up Using gnatclean |
16118 | @chapter Cleaning Up Using @code{gnatclean} | |
16119 | @findex gnatclean | |
16120 | @cindex Cleaning tool | |
16121 | ||
16122 | @noindent | |
16123 | @code{gnatclean} is a tool that allows the deletion of files produced by the | |
16124 | compiler, binder and linker, including ALI files, object files, tree files, | |
16125 | expanded source files, library files, interface copy source files, binder | |
16126 | generated files and executable files. | |
16127 | ||
16128 | @menu | |
16129 | * Running gnatclean:: | |
16130 | * Switches for gnatclean:: | |
16131 | * Examples of gnatclean Usage:: | |
16132 | @end menu | |
16133 | ||
16134 | @node Running gnatclean | |
16135 | @section Running @code{gnatclean} | |
16136 | ||
16137 | @noindent | |
16138 | The @code{gnatclean} command has the form: | |
16139 | ||
16140 | @smallexample | |
16141 | $ gnatclean switches @var{names} | |
16142 | @end smallexample | |
16143 | ||
16144 | @noindent | |
16145 | @var{names} is a list of source file names. Suffixes @code{.^ads^ADS^} and | |
16146 | @code{^adb^ADB^} may be omitted. If a project file is specified using switch | |
16147 | @code{^-P^/PROJECT_FILE=^}, then @var{names} may be completely omitted. | |
16148 | ||
16149 | @noindent | |
16150 | In normal mode, @code{gnatclean} delete the files produced by the compiler and, | |
16151 | if switch @code{^-c^/COMPILER_FILES_ONLY^} is not specified, by the binder and | |
16152 | the linker. In informative-only mode, specified by switch | |
16153 | @code{^-n^/NODELETE^}, the list of files that would have been deleted in | |
16154 | normal mode is listed, but no file is actually deleted. | |
16155 | ||
16156 | @node Switches for gnatclean | |
16157 | @section Switches for @code{gnatclean} | |
16158 | ||
16159 | @noindent | |
16160 | @code{gnatclean} recognizes the following switches: | |
16161 | ||
16162 | @table @option | |
16163 | @c !sort! | |
16164 | @item ^-c^/COMPILER_FILES_ONLY^ | |
16165 | @cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean}) | |
16166 | Only attempt to delete the files produced by the compiler, not those produced | |
16167 | by the binder or the linker. The files that are not to be deleted are library | |
16168 | files, interface copy files, binder generated files and executable files. | |
16169 | ||
16170 | @item ^-D ^/DIRECTORY_OBJECTS=^@var{dir} | |
16171 | @cindex @option{^-D^/DIRECTORY_OBJECTS^} (@code{gnatclean}) | |
16172 | Indicate that ALI and object files should normally be found in directory | |
16173 | @var{dir}. | |
16174 | ||
16175 | @item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^ | |
16176 | @cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@code{gnatclean}) | |
16177 | When using project files, if some errors or warnings are detected during | |
16178 | parsing and verbose mode is not in effect (no use of switch | |
16179 | ^-v^/VERBOSE^), then error lines start with the full path name of the project | |
16180 | file, rather than its simple file name. | |
16181 | ||
16182 | @item ^-h^/HELP^ | |
16183 | @cindex @option{^-h^/HELP^} (@code{gnatclean}) | |
16184 | Output a message explaining the usage of @code{^gnatclean^gnatclean^}. | |
16185 | ||
16186 | @item ^-n^/NODELETE^ | |
16187 | @cindex @option{^-n^/NODELETE^} (@code{gnatclean}) | |
16188 | Informative-only mode. Do not delete any files. Output the list of the files | |
16189 | that would have been deleted if this switch was not specified. | |
16190 | ||
16191 | @item ^-P^/PROJECT_FILE=^@var{project} | |
16192 | @cindex @option{^-P^/PROJECT_FILE^} (@code{gnatclean}) | |
16193 | Use project file @var{project}. Only one such switch can be used. | |
16194 | When cleaning a project file, the files produced by the compilation of the | |
16195 | immediate sources or inherited sources of the project files are to be | |
16196 | deleted. This is not depending on the presence or not of executable names | |
16197 | on the command line. | |
16198 | ||
16199 | @item ^-q^/QUIET^ | |
16200 | @cindex @option{^-q^/QUIET^} (@code{gnatclean}) | |
16201 | Quiet output. If there are no error, do not ouuput anything, except in | |
16202 | verbose mode (switch ^-v^/VERBOSE^) or in informative-only mode | |
16203 | (switch ^-n^/NODELETE^). | |
16204 | ||
16205 | @item ^-r^/RECURSIVE^ | |
16206 | @cindex @option{^-r^/RECURSIVE^} (@code{gnatclean}) | |
16207 | When a project file is specified (using switch ^-P^/PROJECT_FILE=^), | |
16208 | clean all imported and extended project files, recursively. If this switch | |
16209 | is not specified, only the files related to the main project file are to be | |
16210 | deleted. This switch has no effect if no project file is specified. | |
16211 | ||
16212 | @item ^-v^/VERBOSE^ | |
16213 | @cindex @option{^-v^/VERBOSE^} (@code{gnatclean}) | |
16214 | Verbose mode. | |
16215 | ||
16216 | @item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} | |
16217 | @cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (@code{gnatclean}) | |
16218 | Indicates the verbosity of the parsing of GNAT project files. | |
16219 | See @ref{Switches Related to Project Files}. | |
16220 | ||
16221 | @item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} | |
16222 | @cindex @option{^-X^/EXTERNAL_REFERENCE^} (@code{gnatclean}) | |
16223 | Indicates that external variable @var{name} has the value @var{value}. | |
16224 | The Project Manager will use this value for occurrences of | |
16225 | @code{external(name)} when parsing the project file. | |
16226 | See @ref{Switches Related to Project Files}. | |
16227 | ||
16228 | @item ^-aO^/OBJECT_SEARCH=^@var{dir} | |
16229 | @cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatclean}) | |
16230 | When searching for ALI and object files, look in directory | |
16231 | @var{dir}. | |
16232 | ||
16233 | @item ^-I^/SEARCH=^@var{dir} | |
16234 | @cindex @option{^-I^/SEARCH^} (@code{gnatclean}) | |
16235 | Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir}}. | |
16236 | ||
16237 | @item ^-I-^/NOCURRENT_DIRECTORY^ | |
16238 | @cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatclean}) | |
16239 | @cindex Source files, suppressing search | |
16240 | Do not look for ALI or object files in the directory | |
16241 | where @code{gnatclean} was invoked. | |
16242 | ||
16243 | @end table | |
16244 | ||
16245 | @node Examples of gnatclean Usage | |
16246 | @section Examples of @code{gnatclean} Usage | |
16247 | ||
88e1739c FW |
16248 | @ifclear vms |
16249 | @node GNAT and Libraries | |
16250 | @chapter GNAT and Libraries | |
16251 | @cindex Library, building, installing | |
16252 | ||
16253 | @noindent | |
16254 | This chapter addresses some of the issues related to building and using | |
16255 | a library with GNAT. It also shows how the GNAT run-time library can be | |
16256 | recompiled. | |
16257 | ||
16258 | @menu | |
16259 | * Creating an Ada Library:: | |
16260 | * Installing an Ada Library:: | |
16261 | * Using an Ada Library:: | |
16262 | * Creating an Ada Library to be Used in a Non-Ada Context:: | |
16263 | * Rebuilding the GNAT Run-Time Library:: | |
16264 | @end menu | |
16265 | ||
16266 | @node Creating an Ada Library | |
16267 | @section Creating an Ada Library | |
16268 | ||
16269 | @noindent | |
16270 | In the GNAT environment, a library has two components: | |
16271 | @itemize @bullet | |
16272 | @item | |
16273 | Source files. | |
16274 | @item | |
16275 | Compiled code and Ali files. See @ref{The Ada Library Information Files}. | |
16276 | @end itemize | |
16277 | ||
16278 | @noindent | |
16279 | In order to use other packages @ref{The GNAT Compilation Model} | |
16280 | requires a certain number of sources to be available to the compiler. | |
16281 | The minimal set of | |
16282 | sources required includes the specs of all the packages that make up the | |
16283 | visible part of the library as well as all the sources upon which they | |
16284 | depend. The bodies of all visible generic units must also be provided. | |
16285 | @noindent | |
16286 | Although it is not strictly mandatory, it is recommended that all sources | |
16287 | needed to recompile the library be provided, so that the user can make | |
16288 | full use of inter-unit inlining and source-level debugging. This can also | |
16289 | make the situation easier for users that need to upgrade their compilation | |
16290 | toolchain and thus need to recompile the library from sources. | |
16291 | ||
16292 | @noindent | |
16293 | The compiled code can be provided in different ways. The simplest way is | |
16294 | to provide directly the set of objects produced by the compiler during | |
16295 | the compilation of the library. It is also possible to group the objects | |
16296 | into an archive using whatever commands are provided by the operating | |
16297 | system. Finally, it is also possible to create a shared library (see | |
16298 | option -shared in the GCC manual). | |
16299 | ||
16300 | @noindent | |
16301 | There are various possibilities for compiling the units that make up the | |
16302 | library: for example with a Makefile @ref{Using the GNU make Utility}, | |
16303 | or with a conventional script. | |
16304 | For simple libraries, it is also possible to create a | |
16305 | dummy main program which depends upon all the packages that comprise the | |
16306 | interface of the library. This dummy main program can then be given to | |
16307 | gnatmake, in order to build all the necessary objects. Here is an example | |
16308 | of such a dummy program and the generic commands used to build an | |
16309 | archive or a shared library. | |
16310 | ||
7cd4527e | 16311 | @smallexample @c ada |
88e1739c FW |
16312 | @iftex |
16313 | @leftskip=.7cm | |
16314 | @end iftex | |
7cd4527e AC |
16315 | with My_Lib.Service1; |
16316 | with My_Lib.Service2; | |
16317 | with My_Lib.Service3; | |
16318 | procedure My_Lib_Dummy is | |
16319 | begin | |
16320 | null; | |
16321 | end; | |
16322 | @end smallexample | |
88e1739c | 16323 | |
7cd4527e | 16324 | @smallexample |
88e1739c FW |
16325 | # compiling the library |
16326 | $ gnatmake -c my_lib_dummy.adb | |
16327 | ||
16328 | # we don't need the dummy object itself | |
16329 | $ rm my_lib_dummy.o my_lib_dummy.ali | |
16330 | ||
16331 | # create an archive with the remaining objects | |
16332 | $ ar rc libmy_lib.a *.o | |
16333 | # some systems may require "ranlib" to be run as well | |
16334 | ||
16335 | # or create a shared library | |
16336 | $ gcc -shared -o libmy_lib.so *.o | |
16337 | # some systems may require the code to have been compiled with -fPIC | |
7cd4527e AC |
16338 | |
16339 | # remove the object files that are now in the library | |
16340 | $ rm *.o | |
16341 | ||
16342 | # Make the ALI files read-only so that gnatmake will not try to | |
16343 | # regenerate the objects that are in the library | |
16344 | $ chmod -w *.ali | |
16345 | ||
88e1739c FW |
16346 | @end smallexample |
16347 | ||
16348 | @noindent | |
16349 | When the objects are grouped in an archive or a shared library, the user | |
16350 | needs to specify the desired library at link time, unless a pragma | |
16351 | linker_options has been used in one of the sources: | |
7cd4527e AC |
16352 | @smallexample @c ada |
16353 | pragma Linker_Options ("-lmy_lib"); | |
88e1739c FW |
16354 | @end smallexample |
16355 | ||
7cd4527e AC |
16356 | @noindent |
16357 | Please note that the library must have a name of the form libxxx.a or | |
16358 | libxxx.so in order to be accessed by the directive -lxxx at link | |
16359 | time. | |
16360 | ||
88e1739c FW |
16361 | @node Installing an Ada Library |
16362 | @section Installing an Ada Library | |
16363 | ||
16364 | @noindent | |
16365 | In the GNAT model, installing a library consists in copying into a specific | |
16366 | location the files that make up this library. It is possible to install | |
16367 | the sources in a different directory from the other files (ALI, objects, | |
16368 | archives) since the source path and the object path can easily be | |
16369 | specified separately. | |
16370 | ||
16371 | @noindent | |
16372 | For general purpose libraries, it is possible for the system | |
16373 | administrator to put those libraries in the default compiler paths. To | |
16374 | achieve this, he must specify their location in the configuration files | |
7cd4527e AC |
16375 | @file{ada_source_path} and @file{ada_object_path} that must be located in |
16376 | the GNAT | |
88e1739c FW |
16377 | installation tree at the same place as the gcc spec file. The location of |
16378 | the gcc spec file can be determined as follows: | |
16379 | @smallexample | |
16380 | $ gcc -v | |
16381 | @end smallexample | |
16382 | ||
16383 | @noindent | |
16384 | The configuration files mentioned above have simple format: each line in them | |
16385 | must contain one unique | |
16386 | directory name. Those names are added to the corresponding path | |
16387 | in their order of appearance in the file. The names can be either absolute | |
16388 | or relative, in the latter case, they are relative to where theses files | |
16389 | are located. | |
16390 | ||
16391 | @noindent | |
7cd4527e AC |
16392 | @file{ada_source_path} and @file{ada_object_path} might actually not be |
16393 | present in a | |
88e1739c | 16394 | GNAT installation, in which case, GNAT will look for its run-time library in |
7cd4527e AC |
16395 | he directories @file{adainclude} for the sources and @file{adalib} for the |
16396 | objects and @file{ALI} files. When the files exist, the compiler does not | |
16397 | look in @file{adainclude} and @file{adalib} at all, and thus the | |
16398 | @file{ada_source_path} file | |
88e1739c | 16399 | must contain the location for the GNAT run-time sources (which can simply |
7cd4527e AC |
16400 | be @file{adainclude}). In the same way, the @file{ada_object_path} file must |
16401 | contain the location for the GNAT run-time objects (which can simply | |
16402 | be @file{adalib}). | |
88e1739c FW |
16403 | |
16404 | @noindent | |
16405 | You can also specify a new default path to the runtime library at compilation | |
7cd4527e | 16406 | time with the switch @option{--RTS=rts-path}. You can easily choose and change |
88e1739c FW |
16407 | the runtime you want your program to be compiled with. This switch is |
16408 | recognized by gcc, gnatmake, gnatbind, gnatls, gnatfind and gnatxref. | |
16409 | ||
16410 | @noindent | |
16411 | It is possible to install a library before or after the standard GNAT | |
16412 | library, by reordering the lines in the configuration files. In general, a | |
7cd4527e AC |
16413 | library must be installed before the GNAT library if it redefines |
16414 | any part of it. | |
88e1739c FW |
16415 | |
16416 | @node Using an Ada Library | |
16417 | @section Using an Ada Library | |
16418 | ||
16419 | @noindent | |
16420 | In order to use a Ada library, you need to make sure that this | |
16421 | library is on both your source and object path | |
16422 | @ref{Search Paths and the Run-Time Library (RTL)} | |
16423 | and @ref{Search Paths for gnatbind}. For | |
7cd4527e AC |
16424 | instance, you can use the library @file{mylib} installed in |
16425 | @file{/dir/my_lib_src} and @file{/dir/my_lib_obj} with the following commands: | |
88e1739c FW |
16426 | |
16427 | @smallexample | |
16428 | $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \ | |
16429 | -largs -lmy_lib | |
16430 | @end smallexample | |
16431 | ||
16432 | @noindent | |
16433 | This can be simplified down to the following: | |
16434 | @smallexample | |
16435 | $ gnatmake my_appl | |
16436 | @end smallexample | |
16437 | when the following conditions are met: | |
16438 | @itemize @bullet | |
16439 | @item | |
7cd4527e AC |
16440 | @file{/dir/my_lib_src} has been added by the user to the environment |
16441 | variable @code{ADA_INCLUDE_PATH}, or by the administrator to the file | |
16442 | @file{ada_source_path} | |
88e1739c | 16443 | @item |
7cd4527e AC |
16444 | @file{/dir/my_lib_obj} has been added by the user to the environment |
16445 | variable @code{ADA_OBJECTS_PATH}, or by the administrator to the file | |
16446 | @file{ada_object_path} | |
88e1739c | 16447 | @item |
7cd4527e AC |
16448 | a pragma @code{Linker_Options}, as mentioned in @ref{Creating an Ada Library}, |
16449 | has been added to the sources. | |
88e1739c FW |
16450 | @end itemize |
16451 | @noindent | |
16452 | ||
16453 | @node Creating an Ada Library to be Used in a Non-Ada Context | |
16454 | @section Creating an Ada Library to be Used in a Non-Ada Context | |
16455 | ||
16456 | @noindent | |
16457 | The previous sections detailed how to create and install a library that | |
16458 | was usable from an Ada main program. Using this library in a non-Ada | |
16459 | context is not possible, because the elaboration of the library is | |
16460 | automatically done as part of the main program elaboration. | |
16461 | ||
16462 | GNAT also provides the ability to build libraries that can be used both | |
16463 | in an Ada and non-Ada context. This section describes how to build such | |
16464 | a library, and then how to use it from a C program. The method for | |
16465 | interfacing with the library from other languages such as Fortran for | |
16466 | instance remains the same. | |
16467 | ||
16468 | @subsection Creating the Library | |
16469 | ||
16470 | @itemize @bullet | |
16471 | @item Identify the units representing the interface of the library. | |
16472 | ||
16473 | Here is an example of simple library interface: | |
16474 | ||
7cd4527e | 16475 | @smallexample @c ada |
88e1739c FW |
16476 | package Interface is |
16477 | ||
16478 | procedure Do_Something; | |
16479 | ||
16480 | procedure Do_Something_Else; | |
16481 | ||
16482 | end Interface; | |
16483 | @end smallexample | |
16484 | ||
16485 | @item Use @code{pragma Export} or @code{pragma Convention} for the | |
16486 | exported entities. | |
16487 | ||
16488 | Our package @code{Interface} is then updated as follow: | |
7cd4527e | 16489 | @smallexample @c ada |
88e1739c FW |
16490 | package Interface is |
16491 | ||
16492 | procedure Do_Something; | |
16493 | pragma Export (C, Do_Something, "do_something"); | |
16494 | ||
16495 | procedure Do_Something_Else; | |
16496 | pragma Export (C, Do_Something_Else, "do_something_else"); | |
16497 | ||
16498 | end Interface; | |
16499 | @end smallexample | |
16500 | ||
16501 | @item Compile all the units composing the library. | |
16502 | ||
16503 | @item Bind the library objects. | |
16504 | ||
7cd4527e | 16505 | This step is performed by invoking gnatbind with the @option{-L<prefix>} |
88e1739c FW |
16506 | switch. @code{gnatbind} will then generate the library elaboration |
16507 | procedure (named @code{<prefix>init}) and the run-time finalization | |
16508 | procedure (named @code{<prefix>final}). | |
16509 | ||
16510 | @smallexample | |
16511 | # generate the binder file in Ada | |
16512 | $ gnatbind -Lmylib interface | |
16513 | ||
16514 | # generate the binder file in C | |
16515 | $ gnatbind -C -Lmylib interface | |
16516 | @end smallexample | |
16517 | ||
16518 | @item Compile the files generated by the binder | |
16519 | ||
16520 | @smallexample | |
16521 | $ gcc -c b~interface.adb | |
16522 | @end smallexample | |
16523 | ||
16524 | @item Create the library; | |
16525 | ||
16526 | The procedure is identical to the procedure explained in | |
16527 | @ref{Creating an Ada Library}, | |
16528 | except that @file{b~interface.o} needs to be added to | |
16529 | the list of objects. | |
16530 | ||
16531 | @smallexample | |
16532 | # create an archive file | |
16533 | $ ar cr libmylib.a b~interface.o <other object files> | |
16534 | ||
16535 | # create a shared library | |
16536 | $ gcc -shared -o libmylib.so b~interface.o <other object files> | |
16537 | @end smallexample | |
16538 | ||
7cd4527e | 16539 | @item Provide a ``foreign'' view of the library interface; |
88e1739c FW |
16540 | |
16541 | The example below shows the content of @code{mylib_interface.h} (note | |
16542 | that there is no rule for the naming of this file, any name can be used) | |
16543 | @smallexample | |
16544 | /* the library elaboration procedure */ | |
16545 | extern void mylibinit (void); | |
16546 | ||
16547 | /* the library finalization procedure */ | |
16548 | extern void mylibfinal (void); | |
16549 | ||
16550 | /* the interface exported by the library */ | |
16551 | extern void do_something (void); | |
16552 | extern void do_something_else (void); | |
16553 | @end smallexample | |
16554 | @end itemize | |
16555 | ||
16556 | @subsection Using the Library | |
16557 | ||
16558 | @noindent | |
16559 | Libraries built as explained above can be used from any program, provided | |
16560 | that the elaboration procedures (named @code{mylibinit} in the previous | |
16561 | example) are called before the library services are used. Any number of | |
16562 | libraries can be used simultaneously, as long as the elaboration | |
16563 | procedure of each library is called. | |
16564 | ||
16565 | Below is an example of C program that uses our @code{mylib} library. | |
16566 | ||
16567 | @smallexample | |
16568 | #include "mylib_interface.h" | |
16569 | ||
16570 | int | |
16571 | main (void) | |
16572 | @{ | |
16573 | /* First, elaborate the library before using it */ | |
16574 | mylibinit (); | |
16575 | ||
16576 | /* Main program, using the library exported entities */ | |
16577 | do_something (); | |
16578 | do_something_else (); | |
16579 | ||
16580 | /* Library finalization at the end of the program */ | |
16581 | mylibfinal (); | |
16582 | return 0; | |
16583 | @} | |
16584 | @end smallexample | |
16585 | ||
16586 | @noindent | |
16587 | Note that this same library can be used from an equivalent Ada main | |
16588 | program. In addition, if the libraries are installed as detailed in | |
16589 | @ref{Installing an Ada Library}, it is not necessary to invoke the | |
16590 | library elaboration and finalization routines. The binder will ensure | |
16591 | that this is done as part of the main program elaboration and | |
16592 | finalization phases. | |
16593 | ||
16594 | @subsection The Finalization Phase | |
16595 | ||
16596 | @noindent | |
16597 | Invoking any library finalization procedure generated by @code{gnatbind} | |
16598 | shuts down the Ada run time permanently. Consequently, the finalization | |
16599 | of all Ada libraries must be performed at the end of the program. No | |
16600 | call to these libraries nor the Ada run time should be made past the | |
16601 | finalization phase. | |
16602 | ||
16603 | @subsection Restrictions in Libraries | |
16604 | ||
16605 | @noindent | |
16606 | The pragmas listed below should be used with caution inside libraries, | |
16607 | as they can create incompatibilities with other Ada libraries: | |
16608 | @itemize @bullet | |
16609 | @item pragma @code{Locking_Policy} | |
16610 | @item pragma @code{Queuing_Policy} | |
16611 | @item pragma @code{Task_Dispatching_Policy} | |
16612 | @item pragma @code{Unreserve_All_Interrupts} | |
16613 | @end itemize | |
16614 | When using a library that contains such pragmas, the user must make sure | |
16615 | that all libraries use the same pragmas with the same values. Otherwise, | |
16616 | a @code{Program_Error} will | |
16617 | be raised during the elaboration of the conflicting | |
16618 | libraries. The usage of these pragmas and its consequences for the user | |
16619 | should therefore be well documented. | |
16620 | ||
16621 | Similarly, the traceback in exception occurrences mechanism should be | |
16622 | enabled or disabled in a consistent manner across all libraries. | |
16623 | Otherwise, a Program_Error will be raised during the elaboration of the | |
16624 | conflicting libraries. | |
16625 | ||
16626 | If the @code{'Version} and @code{'Body_Version} | |
16627 | attributes are used inside a library, then it is necessary to | |
7cd4527e | 16628 | perform a @code{gnatbind} step that mentions all @file{ALI} files in all |
88e1739c FW |
16629 | libraries, so that version identifiers can be properly computed. |
16630 | In practice these attributes are rarely used, so this is unlikely | |
16631 | to be a consideration. | |
16632 | ||
16633 | @node Rebuilding the GNAT Run-Time Library | |
16634 | @section Rebuilding the GNAT Run-Time Library | |
16635 | ||
16636 | @noindent | |
16637 | It may be useful to recompile the GNAT library in various contexts, the | |
16638 | most important one being the use of partition-wide configuration pragmas | |
16639 | such as Normalize_Scalar. A special Makefile called | |
16640 | @code{Makefile.adalib} is provided to that effect and can be found in | |
16641 | the directory containing the GNAT library. The location of this | |
16642 | directory depends on the way the GNAT environment has been installed and can | |
16643 | be determined by means of the command: | |
16644 | ||
16645 | @smallexample | |
16646 | $ gnatls -v | |
16647 | @end smallexample | |
16648 | ||
16649 | @noindent | |
16650 | The last entry in the object search path usually contains the | |
16651 | gnat library. This Makefile contains its own documentation and in | |
16652 | particular the set of instructions needed to rebuild a new library and | |
16653 | to use it. | |
16654 | ||
16655 | @node Using the GNU make Utility | |
16656 | @chapter Using the GNU @code{make} Utility | |
16657 | @findex make | |
16658 | ||
16659 | @noindent | |
16660 | This chapter offers some examples of makefiles that solve specific | |
16661 | problems. It does not explain how to write a makefile (see the GNU make | |
16662 | documentation), nor does it try to replace the @code{gnatmake} utility | |
16663 | (@pxref{The GNAT Make Program gnatmake}). | |
16664 | ||
16665 | All the examples in this section are specific to the GNU version of | |
16666 | make. Although @code{make} is a standard utility, and the basic language | |
16667 | is the same, these examples use some advanced features found only in | |
16668 | @code{GNU make}. | |
16669 | ||
16670 | @menu | |
16671 | * Using gnatmake in a Makefile:: | |
16672 | * Automatically Creating a List of Directories:: | |
16673 | * Generating the Command Line Switches:: | |
16674 | * Overcoming Command Line Length Limits:: | |
16675 | @end menu | |
16676 | ||
16677 | @node Using gnatmake in a Makefile | |
16678 | @section Using gnatmake in a Makefile | |
16679 | @findex makefile | |
16680 | @cindex GNU make | |
16681 | ||
16682 | @noindent | |
16683 | Complex project organizations can be handled in a very powerful way by | |
16684 | using GNU make combined with gnatmake. For instance, here is a Makefile | |
16685 | which allows you to build each subsystem of a big project into a separate | |
16686 | shared library. Such a makefile allows you to significantly reduce the link | |
16687 | time of very big applications while maintaining full coherence at | |
16688 | each step of the build process. | |
16689 | ||
16690 | The list of dependencies are handled automatically by | |
16691 | @code{gnatmake}. The Makefile is simply used to call gnatmake in each of | |
16692 | the appropriate directories. | |
16693 | ||
16694 | Note that you should also read the example on how to automatically | |
7cd4527e AC |
16695 | create the list of directories |
16696 | (@pxref{Automatically Creating a List of Directories}) | |
16697 | which might help you in case your project has a lot of subdirectories. | |
88e1739c FW |
16698 | |
16699 | @smallexample | |
16700 | @iftex | |
16701 | @leftskip=0cm | |
16702 | @font@heightrm=cmr8 | |
16703 | @heightrm | |
16704 | @end iftex | |
16705 | ## This Makefile is intended to be used with the following directory | |
16706 | ## configuration: | |
16707 | ## - The sources are split into a series of csc (computer software components) | |
16708 | ## Each of these csc is put in its own directory. | |
16709 | ## Their name are referenced by the directory names. | |
16710 | ## They will be compiled into shared library (although this would also work | |
16711 | ## with static libraries | |
16712 | ## - The main program (and possibly other packages that do not belong to any | |
16713 | ## csc is put in the top level directory (where the Makefile is). | |
16714 | ## toplevel_dir __ first_csc (sources) __ lib (will contain the library) | |
16715 | ## \_ second_csc (sources) __ lib (will contain the library) | |
16716 | ## \_ ... | |
16717 | ## Although this Makefile is build for shared library, it is easy to modify | |
16718 | ## to build partial link objects instead (modify the lines with -shared and | |
16719 | ## gnatlink below) | |
16720 | ## | |
16721 | ## With this makefile, you can change any file in the system or add any new | |
16722 | ## file, and everything will be recompiled correctly (only the relevant shared | |
16723 | ## objects will be recompiled, and the main program will be re-linked). | |
16724 | ||
16725 | # The list of computer software component for your project. This might be | |
16726 | # generated automatically. | |
16727 | CSC_LIST=aa bb cc | |
16728 | ||
16729 | # Name of the main program (no extension) | |
16730 | MAIN=main | |
16731 | ||
16732 | # If we need to build objects with -fPIC, uncomment the following line | |
16733 | #NEED_FPIC=-fPIC | |
16734 | ||
16735 | # The following variable should give the directory containing libgnat.so | |
16736 | # You can get this directory through 'gnatls -v'. This is usually the last | |
16737 | # directory in the Object_Path. | |
16738 | GLIB=... | |
16739 | ||
16740 | # The directories for the libraries | |
16741 | # (This macro expands the list of CSC to the list of shared libraries, you | |
16742 | # could simply use the expanded form : | |
16743 | # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so | |
16744 | LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@} | |
16745 | ||
16746 | $@{MAIN@}: objects $@{LIB_DIR@} | |
16747 | gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared | |
16748 | gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@} | |
16749 | ||
16750 | objects:: | |
16751 | # recompile the sources | |
16752 | gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@} | |
16753 | ||
16754 | # Note: In a future version of GNAT, the following commands will be simplified | |
16755 | # by a new tool, gnatmlib | |
16756 | $@{LIB_DIR@}: | |
16757 | mkdir -p $@{dir $@@ @} | |
16758 | cd $@{dir $@@ @}; gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat | |
16759 | cd $@{dir $@@ @}; cp -f ../*.ali . | |
16760 | ||
16761 | # The dependencies for the modules | |
7cd4527e AC |
16762 | # Note that we have to force the expansion of *.o, since in some cases |
16763 | # make won't be able to do it itself. | |
88e1739c FW |
16764 | aa/lib/libaa.so: $@{wildcard aa/*.o@} |
16765 | bb/lib/libbb.so: $@{wildcard bb/*.o@} | |
16766 | cc/lib/libcc.so: $@{wildcard cc/*.o@} | |
16767 | ||
16768 | # Make sure all of the shared libraries are in the path before starting the | |
16769 | # program | |
16770 | run:: | |
16771 | LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@} | |
16772 | ||
16773 | clean:: | |
16774 | $@{RM@} -rf $@{CSC_LIST:%=%/lib@} | |
16775 | $@{RM@} $@{CSC_LIST:%=%/*.ali@} | |
16776 | $@{RM@} $@{CSC_LIST:%=%/*.o@} | |
16777 | $@{RM@} *.o *.ali $@{MAIN@} | |
16778 | @end smallexample | |
16779 | ||
16780 | @node Automatically Creating a List of Directories | |
16781 | @section Automatically Creating a List of Directories | |
16782 | ||
16783 | @noindent | |
16784 | In most makefiles, you will have to specify a list of directories, and | |
16785 | store it in a variable. For small projects, it is often easier to | |
16786 | specify each of them by hand, since you then have full control over what | |
16787 | is the proper order for these directories, which ones should be | |
16788 | included... | |
16789 | ||
16790 | However, in larger projects, which might involve hundreds of | |
16791 | subdirectories, it might be more convenient to generate this list | |
16792 | automatically. | |
16793 | ||
16794 | The example below presents two methods. The first one, although less | |
16795 | general, gives you more control over the list. It involves wildcard | |
16796 | characters, that are automatically expanded by @code{make}. Its | |
16797 | shortcoming is that you need to explicitly specify some of the | |
16798 | organization of your project, such as for instance the directory tree | |
16799 | depth, whether some directories are found in a separate tree,... | |
16800 | ||
16801 | The second method is the most general one. It requires an external | |
16802 | program, called @code{find}, which is standard on all Unix systems. All | |
16803 | the directories found under a given root directory will be added to the | |
16804 | list. | |
16805 | ||
16806 | @smallexample | |
16807 | @iftex | |
16808 | @leftskip=0cm | |
16809 | @font@heightrm=cmr8 | |
16810 | @heightrm | |
16811 | @end iftex | |
16812 | # The examples below are based on the following directory hierarchy: | |
16813 | # All the directories can contain any number of files | |
16814 | # ROOT_DIRECTORY -> a -> aa -> aaa | |
16815 | # -> ab | |
16816 | # -> ac | |
16817 | # -> b -> ba -> baa | |
16818 | # -> bb | |
16819 | # -> bc | |
16820 | # This Makefile creates a variable called DIRS, that can be reused any time | |
16821 | # you need this list (see the other examples in this section) | |
16822 | ||
16823 | # The root of your project's directory hierarchy | |
16824 | ROOT_DIRECTORY=. | |
16825 | ||
16826 | #### | |
16827 | # First method: specify explicitly the list of directories | |
16828 | # This allows you to specify any subset of all the directories you need. | |
16829 | #### | |
16830 | ||
16831 | DIRS := a/aa/ a/ab/ b/ba/ | |
16832 | ||
16833 | #### | |
16834 | # Second method: use wildcards | |
16835 | # Note that the argument(s) to wildcard below should end with a '/'. | |
16836 | # Since wildcards also return file names, we have to filter them out | |
16837 | # to avoid duplicate directory names. | |
16838 | # We thus use make's @code{dir} and @code{sort} functions. | |
16839 | # It sets DIRs to the following value (note that the directories aaa and baa | |
16840 | # are not given, unless you change the arguments to wildcard). | |
16841 | # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ | |
16842 | #### | |
16843 | ||
7cd4527e AC |
16844 | DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/ |
16845 | $@{ROOT_DIRECTORY@}/*/*/@}@}@} | |
88e1739c FW |
16846 | |
16847 | #### | |
16848 | # Third method: use an external program | |
16849 | # This command is much faster if run on local disks, avoiding NFS slowdowns. | |
16850 | # This is the most complete command: it sets DIRs to the following value: | |
16851 | # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc | |
16852 | #### | |
16853 | ||
16854 | DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@} | |
16855 | ||
16856 | @end smallexample | |
16857 | ||
16858 | @node Generating the Command Line Switches | |
16859 | @section Generating the Command Line Switches | |
16860 | ||
16861 | @noindent | |
16862 | Once you have created the list of directories as explained in the | |
16863 | previous section (@pxref{Automatically Creating a List of Directories}), | |
16864 | you can easily generate the command line arguments to pass to gnatmake. | |
16865 | ||
16866 | For the sake of completeness, this example assumes that the source path | |
16867 | is not the same as the object path, and that you have two separate lists | |
16868 | of directories. | |
16869 | ||
16870 | @smallexample | |
16871 | # see "Automatically creating a list of directories" to create | |
16872 | # these variables | |
16873 | SOURCE_DIRS= | |
16874 | OBJECT_DIRS= | |
16875 | ||
16876 | GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@} | |
16877 | GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@} | |
16878 | ||
16879 | all: | |
16880 | gnatmake $@{GNATMAKE_SWITCHES@} main_unit | |
16881 | @end smallexample | |
16882 | ||
16883 | @node Overcoming Command Line Length Limits | |
16884 | @section Overcoming Command Line Length Limits | |
16885 | ||
16886 | @noindent | |
16887 | One problem that might be encountered on big projects is that many | |
16888 | operating systems limit the length of the command line. It is thus hard to give | |
16889 | gnatmake the list of source and object directories. | |
16890 | ||
16891 | This example shows how you can set up environment variables, which will | |
16892 | make @code{gnatmake} behave exactly as if the directories had been | |
16893 | specified on the command line, but have a much higher length limit (or | |
16894 | even none on most systems). | |
16895 | ||
16896 | It assumes that you have created a list of directories in your Makefile, | |
16897 | using one of the methods presented in | |
16898 | @ref{Automatically Creating a List of Directories}. | |
16899 | For the sake of completeness, we assume that the object | |
16900 | path (where the ALI files are found) is different from the sources patch. | |
16901 | ||
16902 | Note a small trick in the Makefile below: for efficiency reasons, we | |
16903 | create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are | |
16904 | expanded immediately by @code{make}. This way we overcome the standard | |
16905 | make behavior which is to expand the variables only when they are | |
16906 | actually used. | |
16907 | ||
7cd4527e AC |
16908 | On Windows, if you are using the standard Windows command shell, you must |
16909 | replace colons with semicolons in the assignments to these variables. | |
16910 | ||
88e1739c FW |
16911 | @smallexample |
16912 | @iftex | |
16913 | @leftskip=0cm | |
16914 | @font@heightrm=cmr8 | |
16915 | @heightrm | |
16916 | @end iftex | |
16917 | # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH. | |
16918 | # This is the same thing as putting the -I arguments on the command line. | |
16919 | # (the equivalent of using -aI on the command line would be to define | |
16920 | # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECT_PATH). | |
16921 | # You can of course have different values for these variables. | |
16922 | # | |
16923 | # Note also that we need to keep the previous values of these variables, since | |
16924 | # they might have been set before running 'make' to specify where the GNAT | |
16925 | # library is installed. | |
16926 | ||
16927 | # see "Automatically creating a list of directories" to create these | |
16928 | # variables | |
16929 | SOURCE_DIRS= | |
16930 | OBJECT_DIRS= | |
16931 | ||
16932 | empty:= | |
16933 | space:=$@{empty@} $@{empty@} | |
16934 | SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@} | |
16935 | OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@} | |
16936 | ADA_INCLUDE_PATH += $@{SOURCE_LIST@} | |
16937 | ADA_OBJECT_PATH += $@{OBJECT_LIST@} | |
16938 | export ADA_INCLUDE_PATH | |
16939 | export ADA_OBJECT_PATH | |
16940 | ||
16941 | all: | |
16942 | gnatmake main_unit | |
16943 | @end smallexample | |
7cd4527e | 16944 | @end ifclear |
88e1739c | 16945 | |
7cd4527e AC |
16946 | |
16947 | @node Finding Memory Problems | |
16948 | @chapter Finding Memory Problems | |
16949 | ||
16950 | @noindent | |
16951 | This chapter describes | |
16952 | @ifclear vms | |
16953 | the @command{gnatmem} tool, which can be used to track down | |
16954 | ``memory leaks'', and | |
16955 | @end ifclear | |
16956 | the GNAT Debug Pool facility, which can be used to detect incorrect uses of | |
16957 | access values (including ``dangling references''). | |
16958 | ||
16959 | @menu | |
16960 | @ifclear vms | |
16961 | * The gnatmem Tool:: | |
16962 | @end ifclear | |
16963 | * The GNAT Debug Pool Facility:: | |
16964 | @end menu | |
16965 | ||
16966 | ||
16967 | @ifclear vms | |
16968 | @node The gnatmem Tool | |
16969 | @section The @command{gnatmem} Tool | |
88e1739c FW |
16970 | @findex gnatmem |
16971 | ||
16972 | @noindent | |
7cd4527e | 16973 | The @code{gnatmem} utility monitors dynamic allocation and |
88e1739c | 16974 | deallocation activity in a program, and displays information about |
7cd4527e AC |
16975 | incorrect deallocations and possible sources of memory leaks. |
16976 | It provides three type of information: | |
88e1739c FW |
16977 | @itemize @bullet |
16978 | @item | |
16979 | General information concerning memory management, such as the total | |
16980 | number of allocations and deallocations, the amount of allocated | |
16981 | memory and the high water mark, i.e. the largest amount of allocated | |
16982 | memory in the course of program execution. | |
16983 | ||
16984 | @item | |
16985 | Backtraces for all incorrect deallocations, that is to say deallocations | |
16986 | which do not correspond to a valid allocation. | |
16987 | ||
16988 | @item | |
16989 | Information on each allocation that is potentially the origin of a memory | |
16990 | leak. | |
16991 | @end itemize | |
16992 | ||
88e1739c | 16993 | @menu |
7cd4527e | 16994 | * Running gnatmem:: |
88e1739c | 16995 | * Switches for gnatmem:: |
7cd4527e | 16996 | * Example of gnatmem Usage:: |
88e1739c FW |
16997 | @end menu |
16998 | ||
7cd4527e AC |
16999 | @node Running gnatmem |
17000 | @subsection Running @code{gnatmem} | |
17001 | ||
17002 | @noindent | |
17003 | @code{gnatmem} makes use of the output created by the special version of | |
17004 | allocation and deallocation routines that record call information. This | |
17005 | allows to obtain accurate dynamic memory usage history at a minimal cost to | |
17006 | the execution speed. Note however, that @code{gnatmem} is not supported on | |
17007 | all platforms (currently, it is supported on AIX, HP-UX, GNU/Linux x86, | |
17008 | Solaris (sparc and x86) and Windows NT/2000/XP (x86). | |
88e1739c FW |
17009 | |
17010 | @noindent | |
17011 | The @code{gnatmem} command has the form | |
17012 | ||
17013 | @smallexample | |
7cd4527e | 17014 | $ gnatmem [switches] user_program |
88e1739c FW |
17015 | @end smallexample |
17016 | ||
17017 | @noindent | |
7cd4527e AC |
17018 | The program must have been linked with the instrumented version of the |
17019 | allocation and deallocation routines. This is done by linking with the | |
17020 | @file{libgmem.a} library. For correct symbolic backtrace information, | |
17021 | the user program should be compiled with debugging options | |
17022 | @ref{Switches for gcc}. For example to build @file{my_program}: | |
17023 | ||
88e1739c | 17024 | @smallexample |
7cd4527e | 17025 | $ gnatmake -g my_program -largs -lgmem |
88e1739c | 17026 | @end smallexample |
7cd4527e AC |
17027 | |
17028 | @noindent | |
17029 | When running @file{my_program} the file @file{gmem.out} is produced. This file | |
17030 | contains information about all allocations and deallocations done by the | |
17031 | program. It is produced by the instrumented allocations and | |
17032 | deallocations routines and will be used by @code{gnatmem}. | |
17033 | ||
17034 | @noindent | |
17035 | Gnatmem must be supplied with the @file{gmem.out} file and the executable to | |
17036 | examine. If the location of @file{gmem.out} file was not explicitly supplied by | |
17037 | @code{-i} switch, gnatmem will assume that this file can be found in the | |
17038 | current directory. For example, after you have executed @file{my_program}, | |
17039 | @file{gmem.out} can be analyzed by @code{gnatmem} using the command: | |
17040 | ||
88e1739c | 17041 | @smallexample |
7cd4527e | 17042 | $ gnatmem my_program |
88e1739c FW |
17043 | @end smallexample |
17044 | ||
7cd4527e AC |
17045 | @noindent |
17046 | This will produce the output with the following format: | |
88e1739c FW |
17047 | |
17048 | *************** debut cc | |
17049 | @smallexample | |
7cd4527e | 17050 | $ gnatmem my_program |
88e1739c FW |
17051 | |
17052 | Global information | |
17053 | ------------------ | |
17054 | Total number of allocations : 45 | |
17055 | Total number of deallocations : 6 | |
17056 | Final Water Mark (non freed mem) : 11.29 Kilobytes | |
17057 | High Water Mark : 11.40 Kilobytes | |
17058 | ||
17059 | . | |
17060 | . | |
17061 | . | |
17062 | Allocation Root # 2 | |
17063 | ------------------- | |
17064 | Number of non freed allocations : 11 | |
17065 | Final Water Mark (non freed mem) : 1.16 Kilobytes | |
17066 | High Water Mark : 1.27 Kilobytes | |
17067 | Backtrace : | |
7cd4527e | 17068 | my_program.adb:23 my_program.alloc |
88e1739c FW |
17069 | . |
17070 | . | |
17071 | . | |
17072 | @end smallexample | |
17073 | ||
7cd4527e AC |
17074 | The first block of output gives general information. In this case, the |
17075 | Ada construct ``@code{@b{new}}'' was executed 45 times, and only 6 calls to an | |
17076 | Unchecked_Deallocation routine occurred. | |
88e1739c | 17077 | |
7cd4527e | 17078 | @noindent |
88e1739c FW |
17079 | Subsequent paragraphs display information on all allocation roots. |
17080 | An allocation root is a specific point in the execution of the program | |
7cd4527e AC |
17081 | that generates some dynamic allocation, such as a ``@code{@b{new}}'' |
17082 | construct. This root is represented by an execution backtrace (or subprogram | |
17083 | call stack). By default the backtrace depth for allocations roots is 1, so | |
88e1739c FW |
17084 | that a root corresponds exactly to a source location. The backtrace can |
17085 | be made deeper, to make the root more specific. | |
17086 | ||
88e1739c | 17087 | @node Switches for gnatmem |
7cd4527e | 17088 | @subsection Switches for @code{gnatmem} |
88e1739c FW |
17089 | |
17090 | @noindent | |
17091 | @code{gnatmem} recognizes the following switches: | |
17092 | ||
7cd4527e | 17093 | @table @option |
88e1739c | 17094 | |
7cd4527e AC |
17095 | @item -q |
17096 | @cindex @option{-q} (@code{gnatmem}) | |
88e1739c | 17097 | Quiet. Gives the minimum output needed to identify the origin of the |
7cd4527e | 17098 | memory leaks. Omits statistical information. |
88e1739c | 17099 | |
7cd4527e AC |
17100 | @item @var{N} |
17101 | @cindex @var{N} (@code{gnatmem}) | |
88e1739c FW |
17102 | N is an integer literal (usually between 1 and 10) which controls the |
17103 | depth of the backtraces defining allocation root. The default value for | |
17104 | N is 1. The deeper the backtrace, the more precise the localization of | |
17105 | the root. Note that the total number of roots can depend on this | |
7cd4527e AC |
17106 | parameter. This parameter must be specified @emph{before} the name of the |
17107 | executable to be analyzed, to avoid ambiguity. | |
17108 | ||
17109 | @item -b n | |
17110 | @cindex @option{-b} (@code{gnatmem}) | |
17111 | This switch has the same effect as just depth parameter. | |
17112 | ||
17113 | @item -i @var{file} | |
17114 | @cindex @option{-i} (@code{gnatmem}) | |
17115 | Do the @code{gnatmem} processing starting from @file{file}, rather than | |
17116 | @file{gmem.out} in the current directory. | |
17117 | ||
17118 | @item -m n | |
17119 | @cindex @option{-m} (@code{gnatmem}) | |
17120 | This switch causes @code{gnatmem} to mask the allocation roots that have less | |
17121 | than n leaks. The default value is 1. Specifying the value of 0 will allow to | |
17122 | examine even the roots that didn't result in leaks. | |
17123 | ||
17124 | @item -s order | |
17125 | @cindex @option{-s} (@code{gnatmem}) | |
17126 | This switch causes @code{gnatmem} to sort the allocation roots according to the | |
17127 | specified order of sort criteria, each identified by a single letter. The | |
17128 | currently supported criteria are @code{n, h, w} standing respectively for | |
17129 | number of unfreed allocations, high watermark, and final watermark | |
17130 | corresponding to a specific root. The default order is @code{nwh}. | |
88e1739c FW |
17131 | |
17132 | @end table | |
17133 | ||
7cd4527e AC |
17134 | @node Example of gnatmem Usage |
17135 | @subsection Example of @code{gnatmem} Usage | |
88e1739c FW |
17136 | |
17137 | @noindent | |
7cd4527e AC |
17138 | The following example shows the use of @code{gnatmem} |
17139 | on a simple memory-leaking program. | |
88e1739c FW |
17140 | Suppose that we have the following Ada program: |
17141 | ||
7cd4527e | 17142 | @smallexample @c ada |
88e1739c FW |
17143 | @group |
17144 | @cartouche | |
7cd4527e AC |
17145 | with Unchecked_Deallocation; |
17146 | procedure Test_Gm is | |
88e1739c | 17147 | |
7cd4527e AC |
17148 | type T is array (1..1000) of Integer; |
17149 | type Ptr is access T; | |
17150 | procedure Free is new Unchecked_Deallocation (T, Ptr); | |
88e1739c FW |
17151 | A : Ptr; |
17152 | ||
7cd4527e AC |
17153 | procedure My_Alloc is |
17154 | begin | |
17155 | A := new T; | |
17156 | end My_Alloc; | |
88e1739c | 17157 | |
7cd4527e | 17158 | procedure My_DeAlloc is |
88e1739c | 17159 | B : Ptr := A; |
7cd4527e | 17160 | begin |
88e1739c | 17161 | Free (B); |
7cd4527e | 17162 | end My_DeAlloc; |
88e1739c | 17163 | |
7cd4527e | 17164 | begin |
88e1739c | 17165 | My_Alloc; |
7cd4527e AC |
17166 | for I in 1 .. 5 loop |
17167 | for J in I .. 5 loop | |
88e1739c | 17168 | My_Alloc; |
7cd4527e | 17169 | end loop; |
88e1739c | 17170 | My_Dealloc; |
7cd4527e AC |
17171 | end loop; |
17172 | end; | |
88e1739c FW |
17173 | @end cartouche |
17174 | @end group | |
17175 | @end smallexample | |
17176 | ||
17177 | @noindent | |
7cd4527e AC |
17178 | The program needs to be compiled with debugging option and linked with |
17179 | @code{gmem} library: | |
17180 | ||
17181 | @smallexample | |
17182 | $ gnatmake -g test_gm -largs -lgmem | |
17183 | @end smallexample | |
17184 | ||
17185 | @noindent | |
17186 | Then we execute the program as usual: | |
88e1739c FW |
17187 | |
17188 | @smallexample | |
7cd4527e | 17189 | $ test_gm |
88e1739c FW |
17190 | @end smallexample |
17191 | ||
7cd4527e AC |
17192 | @noindent |
17193 | Then @code{gnatmem} is invoked simply with | |
88e1739c FW |
17194 | @smallexample |
17195 | $ gnatmem test_gm | |
17196 | @end smallexample | |
17197 | ||
17198 | @noindent | |
7cd4527e | 17199 | which produces the following output (result may vary on different platforms): |
88e1739c FW |
17200 | |
17201 | @smallexample | |
17202 | Global information | |
17203 | ------------------ | |
17204 | Total number of allocations : 18 | |
17205 | Total number of deallocations : 5 | |
17206 | Final Water Mark (non freed mem) : 53.00 Kilobytes | |
17207 | High Water Mark : 56.90 Kilobytes | |
17208 | ||
17209 | Allocation Root # 1 | |
17210 | ------------------- | |
17211 | Number of non freed allocations : 11 | |
17212 | Final Water Mark (non freed mem) : 42.97 Kilobytes | |
17213 | High Water Mark : 46.88 Kilobytes | |
17214 | Backtrace : | |
17215 | test_gm.adb:11 test_gm.my_alloc | |
17216 | ||
17217 | Allocation Root # 2 | |
17218 | ------------------- | |
17219 | Number of non freed allocations : 1 | |
17220 | Final Water Mark (non freed mem) : 10.02 Kilobytes | |
17221 | High Water Mark : 10.02 Kilobytes | |
17222 | Backtrace : | |
17223 | s-secsta.adb:81 system.secondary_stack.ss_init | |
17224 | ||
17225 | Allocation Root # 3 | |
17226 | ------------------- | |
17227 | Number of non freed allocations : 1 | |
17228 | Final Water Mark (non freed mem) : 12 Bytes | |
17229 | High Water Mark : 12 Bytes | |
17230 | Backtrace : | |
17231 | s-secsta.adb:181 system.secondary_stack.ss_init | |
17232 | @end smallexample | |
17233 | ||
17234 | @noindent | |
17235 | Note that the GNAT run time contains itself a certain number of | |
17236 | allocations that have no corresponding deallocation, | |
17237 | as shown here for root #2 and root | |
7cd4527e AC |
17238 | #3. This is a normal behavior when the number of non freed allocations |
17239 | is one, it allocates dynamic data structures that the run time needs for | |
88e1739c FW |
17240 | the complete lifetime of the program. Note also that there is only one |
17241 | allocation root in the user program with a single line back trace: | |
17242 | test_gm.adb:11 test_gm.my_alloc, whereas a careful analysis of the | |
17243 | program shows that 'My_Alloc' is called at 2 different points in the | |
17244 | source (line 21 and line 24). If those two allocation roots need to be | |
17245 | distinguished, the backtrace depth parameter can be used: | |
17246 | ||
17247 | @smallexample | |
17248 | $ gnatmem 3 test_gm | |
17249 | @end smallexample | |
17250 | ||
17251 | @noindent | |
17252 | which will give the following output: | |
17253 | ||
17254 | @smallexample | |
17255 | Global information | |
17256 | ------------------ | |
17257 | Total number of allocations : 18 | |
17258 | Total number of deallocations : 5 | |
17259 | Final Water Mark (non freed mem) : 53.00 Kilobytes | |
17260 | High Water Mark : 56.90 Kilobytes | |
17261 | ||
17262 | Allocation Root # 1 | |
17263 | ------------------- | |
17264 | Number of non freed allocations : 10 | |
17265 | Final Water Mark (non freed mem) : 39.06 Kilobytes | |
17266 | High Water Mark : 42.97 Kilobytes | |
17267 | Backtrace : | |
17268 | test_gm.adb:11 test_gm.my_alloc | |
17269 | test_gm.adb:24 test_gm | |
17270 | b_test_gm.c:52 main | |
17271 | ||
17272 | Allocation Root # 2 | |
17273 | ------------------- | |
17274 | Number of non freed allocations : 1 | |
17275 | Final Water Mark (non freed mem) : 10.02 Kilobytes | |
17276 | High Water Mark : 10.02 Kilobytes | |
17277 | Backtrace : | |
17278 | s-secsta.adb:81 system.secondary_stack.ss_init | |
17279 | s-secsta.adb:283 <system__secondary_stack___elabb> | |
17280 | b_test_gm.c:33 adainit | |
17281 | ||
17282 | Allocation Root # 3 | |
17283 | ------------------- | |
17284 | Number of non freed allocations : 1 | |
17285 | Final Water Mark (non freed mem) : 3.91 Kilobytes | |
17286 | High Water Mark : 3.91 Kilobytes | |
17287 | Backtrace : | |
17288 | test_gm.adb:11 test_gm.my_alloc | |
17289 | test_gm.adb:21 test_gm | |
17290 | b_test_gm.c:52 main | |
17291 | ||
17292 | Allocation Root # 4 | |
17293 | ------------------- | |
17294 | Number of non freed allocations : 1 | |
17295 | Final Water Mark (non freed mem) : 12 Bytes | |
17296 | High Water Mark : 12 Bytes | |
17297 | Backtrace : | |
17298 | s-secsta.adb:181 system.secondary_stack.ss_init | |
17299 | s-secsta.adb:283 <system__secondary_stack___elabb> | |
17300 | b_test_gm.c:33 adainit | |
17301 | @end smallexample | |
17302 | ||
17303 | @noindent | |
17304 | The allocation root #1 of the first example has been split in 2 roots #1 | |
17305 | and #3 thanks to the more precise associated backtrace. | |
17306 | ||
88e1739c FW |
17307 | @end ifclear |
17308 | ||
7cd4527e AC |
17309 | |
17310 | @node The GNAT Debug Pool Facility | |
17311 | @section The GNAT Debug Pool Facility | |
88e1739c FW |
17312 | @findex Debug Pool |
17313 | @cindex storage, pool, memory corruption | |
17314 | ||
17315 | @noindent | |
17316 | The use of unchecked deallocation and unchecked conversion can easily | |
17317 | lead to incorrect memory references. The problems generated by such | |
17318 | references are usually difficult to tackle because the symptoms can be | |
17319 | very remote from the origin of the problem. In such cases, it is | |
17320 | very helpful to detect the problem as early as possible. This is the | |
17321 | purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}. | |
17322 | ||
88e1739c FW |
17323 | In order to use the GNAT specific debugging pool, the user must |
17324 | associate a debug pool object with each of the access types that may be | |
7cd4527e AC |
17325 | related to suspected memory problems. See Ada Reference Manual 13.11. |
17326 | @smallexample @c ada | |
17327 | type Ptr is access Some_Type; | |
88e1739c | 17328 | Pool : GNAT.Debug_Pools.Debug_Pool; |
7cd4527e | 17329 | for Ptr'Storage_Pool use Pool; |
88e1739c FW |
17330 | @end smallexample |
17331 | ||
7cd4527e AC |
17332 | @noindent |
17333 | @code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of | |
17334 | pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools, | |
88e1739c FW |
17335 | allow the user to redefine allocation and deallocation strategies. They |
17336 | also provide a checkpoint for each dereference, through the use of | |
17337 | the primitive operation @code{Dereference} which is implicitly called at | |
17338 | each dereference of an access value. | |
17339 | ||
17340 | Once an access type has been associated with a debug pool, operations on | |
17341 | values of the type may raise four distinct exceptions, | |
17342 | which correspond to four potential kinds of memory corruption: | |
17343 | @itemize @bullet | |
17344 | @item | |
17345 | @code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage} | |
17346 | @item | |
17347 | @code{GNAT.Debug_Pools.Accessing_Deallocated_Storage} | |
17348 | @item | |
17349 | @code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage} | |
17350 | @item | |
17351 | @code{GNAT.Debug_Pools.Freeing_Deallocated_Storage } | |
17352 | @end itemize | |
17353 | ||
17354 | @noindent | |
17355 | For types associated with a Debug_Pool, dynamic allocation is performed using | |
17356 | the standard | |
17357 | GNAT allocation routine. References to all allocated chunks of memory | |
7cd4527e AC |
17358 | are kept in an internal dictionary. |
17359 | Several deallocation strategies are provided, whereupon the user can choose | |
17360 | to release the memory to the system, keep it allocated for further invalid | |
17361 | access checks, or fill it with an easily recognizable pattern for debug | |
17362 | sessions. | |
17363 | The memory pattern is the old IBM hexadecimal convention: @code{16#DEADBEEF#}. | |
17364 | ||
17365 | See the documentation in the file g-debpoo.ads for more information on the | |
17366 | various strategies. | |
17367 | ||
17368 | Upon each dereference, a check is made that the access value denotes a | |
17369 | properly allocated memory location. Here is a complete example of use of | |
88e1739c | 17370 | @code{Debug_Pools}, that includes typical instances of memory corruption: |
7cd4527e | 17371 | @smallexample @c ada |
88e1739c FW |
17372 | @iftex |
17373 | @leftskip=0cm | |
17374 | @end iftex | |
7cd4527e AC |
17375 | with Gnat.Io; use Gnat.Io; |
17376 | with Unchecked_Deallocation; | |
17377 | with Unchecked_Conversion; | |
17378 | with GNAT.Debug_Pools; | |
17379 | with System.Storage_Elements; | |
17380 | with Ada.Exceptions; use Ada.Exceptions; | |
17381 | procedure Debug_Pool_Test is | |
88e1739c | 17382 | |
7cd4527e AC |
17383 | type T is access Integer; |
17384 | type U is access all T; | |
88e1739c FW |
17385 | |
17386 | P : GNAT.Debug_Pools.Debug_Pool; | |
7cd4527e | 17387 | for T'Storage_Pool use P; |
88e1739c | 17388 | |
7cd4527e AC |
17389 | procedure Free is new Unchecked_Deallocation (Integer, T); |
17390 | function UC is new Unchecked_Conversion (U, T); | |
17391 | A, B : aliased T; | |
88e1739c | 17392 | |
7cd4527e | 17393 | procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); |
88e1739c | 17394 | |
7cd4527e | 17395 | begin |
88e1739c | 17396 | Info (P); |
7cd4527e AC |
17397 | A := new Integer; |
17398 | B := new Integer; | |
88e1739c FW |
17399 | B := A; |
17400 | Info (P); | |
17401 | Free (A); | |
7cd4527e AC |
17402 | begin |
17403 | Put_Line (Integer'Image(B.all)); | |
17404 | exception | |
17405 | when E : others => Put_Line ("raised: " & Exception_Name (E)); | |
17406 | end; | |
17407 | begin | |
88e1739c | 17408 | Free (B); |
7cd4527e AC |
17409 | exception |
17410 | when E : others => Put_Line ("raised: " & Exception_Name (E)); | |
17411 | end; | |
88e1739c | 17412 | B := UC(A'Access); |
7cd4527e AC |
17413 | begin |
17414 | Put_Line (Integer'Image(B.all)); | |
17415 | exception | |
17416 | when E : others => Put_Line ("raised: " & Exception_Name (E)); | |
17417 | end; | |
17418 | begin | |
88e1739c | 17419 | Free (B); |
7cd4527e AC |
17420 | exception |
17421 | when E : others => Put_Line ("raised: " & Exception_Name (E)); | |
17422 | end; | |
88e1739c | 17423 | Info (P); |
7cd4527e | 17424 | end Debug_Pool_Test; |
88e1739c | 17425 | @end smallexample |
7cd4527e | 17426 | |
88e1739c FW |
17427 | @noindent |
17428 | The debug pool mechanism provides the following precise diagnostics on the | |
17429 | execution of this erroneous program: | |
17430 | @smallexample | |
17431 | Debug Pool info: | |
17432 | Total allocated bytes : 0 | |
17433 | Total deallocated bytes : 0 | |
17434 | Current Water Mark: 0 | |
17435 | High Water Mark: 0 | |
17436 | ||
17437 | Debug Pool info: | |
17438 | Total allocated bytes : 8 | |
17439 | Total deallocated bytes : 0 | |
17440 | Current Water Mark: 8 | |
17441 | High Water Mark: 8 | |
17442 | ||
17443 | raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE | |
17444 | raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE | |
17445 | raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE | |
17446 | raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE | |
17447 | Debug Pool info: | |
17448 | Total allocated bytes : 8 | |
17449 | Total deallocated bytes : 4 | |
17450 | Current Water Mark: 4 | |
17451 | High Water Mark: 8 | |
88e1739c FW |
17452 | @end smallexample |
17453 | ||
7cd4527e | 17454 | |
88e1739c | 17455 | @node Creating Sample Bodies Using gnatstub |
7cd4527e | 17456 | @chapter Creating Sample Bodies Using @command{gnatstub} |
88e1739c FW |
17457 | @findex gnatstub |
17458 | ||
17459 | @noindent | |
7cd4527e | 17460 | @command{gnatstub} creates body stubs, that is, empty but compilable bodies |
88e1739c FW |
17461 | for library unit declarations. |
17462 | ||
7cd4527e | 17463 | To create a body stub, @command{gnatstub} has to compile the library |
88e1739c FW |
17464 | unit declaration. Therefore, bodies can be created only for legal |
17465 | library units. Moreover, if a library unit depends semantically upon | |
17466 | units located outside the current directory, you have to provide | |
7cd4527e AC |
17467 | the source search path when calling @command{gnatstub}, see the description |
17468 | of @command{gnatstub} switches below. | |
88e1739c FW |
17469 | |
17470 | @menu | |
17471 | * Running gnatstub:: | |
17472 | * Switches for gnatstub:: | |
17473 | @end menu | |
17474 | ||
17475 | @node Running gnatstub | |
7cd4527e | 17476 | @section Running @command{gnatstub} |
88e1739c FW |
17477 | |
17478 | @noindent | |
7cd4527e | 17479 | @command{gnatstub} has the command-line interface of the form |
88e1739c FW |
17480 | |
17481 | @smallexample | |
17482 | $ gnatstub [switches] filename [directory] | |
17483 | @end smallexample | |
17484 | ||
17485 | @noindent | |
17486 | where | |
7cd4527e | 17487 | @table @emph |
88e1739c FW |
17488 | @item filename |
17489 | is the name of the source file that contains a library unit declaration | |
7cd4527e AC |
17490 | for which a body must be created. The file name may contain the path |
17491 | information. | |
17492 | The file name does not have to follow the GNAT file name conventions. If the | |
17493 | name | |
17494 | does not follow GNAT file naming conventions, the name of the body file must | |
17495 | be provided | |
17496 | explicitly as the value of the @option{^-o^/BODY=^@var{body-name}} option. | |
17497 | If the file name follows the GNAT file naming | |
17498 | conventions and the name of the body file is not provided, | |
17499 | @command{gnatstub} | |
17500 | creates the name | |
17501 | of the body file from the argument file name by replacing the @file{.ads} | |
17502 | suffix | |
17503 | with the @file{.adb} suffix. | |
88e1739c FW |
17504 | |
17505 | @item directory | |
7cd4527e AC |
17506 | indicates the directory in which the body stub is to be placed (the default |
17507 | is the | |
88e1739c FW |
17508 | current directory) |
17509 | ||
17510 | @item switches | |
17511 | is an optional sequence of switches as described in the next section | |
17512 | @end table | |
17513 | ||
17514 | @node Switches for gnatstub | |
7cd4527e | 17515 | @section Switches for @command{gnatstub} |
88e1739c | 17516 | |
7cd4527e AC |
17517 | @table @option |
17518 | @c !sort! | |
88e1739c FW |
17519 | |
17520 | @item ^-f^/FULL^ | |
7cd4527e AC |
17521 | @cindex @option{^-f^/FULL^} (@command{gnatstub}) |
17522 | If the destination directory already contains a file with the name of the | |
17523 | body file | |
88e1739c FW |
17524 | for the argument spec file, replace it with the generated body stub. |
17525 | ||
17526 | @item ^-hs^/HEADER=SPEC^ | |
7cd4527e AC |
17527 | @cindex @option{^-hs^/HEADER=SPEC^} (@command{gnatstub}) |
17528 | Put the comment header (i.e., all the comments preceding the | |
88e1739c FW |
17529 | compilation unit) from the source of the library unit declaration |
17530 | into the body stub. | |
17531 | ||
17532 | @item ^-hg^/HEADER=GENERAL^ | |
7cd4527e | 17533 | @cindex @option{^-hg^/HEADER=GENERAL^} (@command{gnatstub}) |
88e1739c FW |
17534 | Put a sample comment header into the body stub. |
17535 | ||
7cd4527e | 17536 | @ifclear vms |
88e1739c | 17537 | @item -IDIR |
7cd4527e AC |
17538 | @cindex @option{-IDIR} (@command{gnatstub}) |
17539 | @itemx -I- | |
17540 | @cindex @option{-I-} (@command{gnatstub}) | |
17541 | @end ifclear | |
17542 | @ifset vms | |
17543 | @item /NOCURRENT_DIRECTORY | |
17544 | @cindex @option{/NOCURRENT_DIRECTORY} (@command{gnatstub}) | |
17545 | @end ifset | |
17546 | ^These switches have ^This switch has^ the same meaning as in calls to | |
17547 | @command{gcc}. | |
17548 | ^They define ^It defines ^ the source search path in the call to | |
17549 | @command{gcc} issued | |
17550 | by @command{gnatstub} to compile an argument source file. | |
17551 | ||
17552 | @item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE=^@var{PATH} | |
17553 | @cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@command{gnatstub}) | |
17554 | This switch has the same meaning as in calls to @command{gcc}. | |
17555 | It defines the additional configuration file to be passed to the call to | |
17556 | @command{gcc} issued | |
17557 | by @command{gnatstub} to compile an argument source file. | |
17558 | ||
17559 | @item ^-gnatyM^/MAX_LINE_LENGTH=^@var{n} | |
17560 | @cindex @option{^-gnatyM^/MAX_LINE_LENGTH^} (@command{gnatstub}) | |
17561 | (@var{n} is a non-negative integer). Set the maximum line length in the | |
17562 | body stub to @var{n}; the default is 79. The maximum value that can be | |
17563 | specified is 32767. | |
17564 | ||
17565 | @item ^-gnaty^/STYLE_CHECKS=^@var{n} | |
17566 | @cindex @option{^-gnaty^/STYLE_CHECKS=^} (@command{gnatstub}) | |
17567 | (@var{n} is a non-negative integer from 1 to 9). Set the indentation level in | |
17568 | the generated body sample to @var{n}. | |
17569 | The default indentation is 3. | |
17570 | ||
17571 | @item ^-gnatyo^/ORDERED_SUBPROGRAMS^ | |
17572 | @cindex @option{^-gnato^/ORDERED_SUBPROGRAMS^} (@command{gnatstub}) | |
17573 | Order local bodies alphabetically. (By default local bodies are ordered | |
17574 | in the same way as the corresponding local specs in the argument spec file.) | |
88e1739c FW |
17575 | |
17576 | @item ^-i^/INDENTATION=^@var{n} | |
7cd4527e AC |
17577 | @cindex @option{^-i^/INDENTATION^} (@command{gnatstub}) |
17578 | Same as @option{^-gnaty^/STYLE_CHECKS=^@var{n}} | |
88e1739c FW |
17579 | |
17580 | @item ^-k^/TREE_FILE=SAVE^ | |
7cd4527e AC |
17581 | @cindex @option{^-k^/TREE_FILE=SAVE^} (@command{gnatstub}) |
17582 | Do not remove the tree file (i.e., the snapshot of the compiler internal | |
17583 | structures used by @command{gnatstub}) after creating the body stub. | |
88e1739c FW |
17584 | |
17585 | @item ^-l^/LINE_LENGTH=^@var{n} | |
7cd4527e AC |
17586 | @cindex @option{^-l^/LINE_LENGTH^} (@command{gnatstub}) |
17587 | Same as @option{^-gnatyM^/MAX_LINE_LENGTH=^@var{n}} | |
17588 | ||
17589 | @item ^-o^/BODY=^@var{body-name} | |
17590 | @cindex @option{^-o^/BODY^} (@command{gnatstub}) | |
17591 | Body file name. This should be set if the argument file name does not | |
17592 | follow | |
17593 | the GNAT file naming | |
17594 | conventions. If this switch is omitted the default name for the body will be | |
17595 | obtained | |
17596 | from the argument file name according to the GNAT file naming conventions. | |
88e1739c FW |
17597 | |
17598 | @item ^-q^/QUIET^ | |
7cd4527e | 17599 | @cindex @option{^-q^/QUIET^} (@command{gnatstub}) |
88e1739c | 17600 | Quiet mode: do not generate a confirmation when a body is |
7cd4527e AC |
17601 | successfully created, and do not generate a message when a body is not |
17602 | required for an | |
88e1739c FW |
17603 | argument unit. |
17604 | ||
17605 | @item ^-r^/TREE_FILE=REUSE^ | |
7cd4527e AC |
17606 | @cindex @option{^-r^/TREE_FILE=REUSE^} (@command{gnatstub}) |
17607 | Reuse the tree file (if it exists) instead of creating it. Instead of | |
17608 | creating the tree file for the library unit declaration, @command{gnatstub} | |
88e1739c | 17609 | tries to find it in the current directory and use it for creating |
7cd4527e AC |
17610 | a body. If the tree file is not found, no body is created. This option |
17611 | also implies @option{^-k^/SAVE^}, whether or not | |
17612 | the latter is set explicitly. | |
88e1739c FW |
17613 | |
17614 | @item ^-t^/TREE_FILE=OVERWRITE^ | |
7cd4527e AC |
17615 | @cindex @option{^-t^/TREE_FILE=OVERWRITE^} (@command{gnatstub}) |
17616 | Overwrite the existing tree file. If the current directory already | |
17617 | contains the file which, according to the GNAT file naming rules should | |
17618 | be considered as a tree file for the argument source file, | |
17619 | @command{gnatstub} | |
17620 | will refuse to create the tree file needed to create a sample body | |
17621 | unless this option is set. | |
88e1739c FW |
17622 | |
17623 | @item ^-v^/VERBOSE^ | |
7cd4527e | 17624 | @cindex @option{^-v^/VERBOSE^} (@command{gnatstub}) |
88e1739c FW |
17625 | Verbose mode: generate version information. |
17626 | ||
17627 | @end table | |
17628 | ||
7cd4527e AC |
17629 | |
17630 | @node Other Utility Programs | |
17631 | @chapter Other Utility Programs | |
17632 | ||
17633 | @noindent | |
17634 | This chapter discusses some other utility programs available in the Ada | |
17635 | environment. | |
88e1739c FW |
17636 | |
17637 | @menu | |
7cd4527e AC |
17638 | * Using Other Utility Programs with GNAT:: |
17639 | * The External Symbol Naming Scheme of GNAT:: | |
17640 | @ifclear vms | |
17641 | * Ada Mode for Glide:: | |
17642 | @end ifclear | |
17643 | * Converting Ada Files to html with gnathtml:: | |
17644 | * Installing gnathtml:: | |
17645 | @ifset vms | |
17646 | * LSE:: | |
17647 | * Profiling:: | |
17648 | @end ifset | |
88e1739c FW |
17649 | @end menu |
17650 | ||
7cd4527e AC |
17651 | @node Using Other Utility Programs with GNAT |
17652 | @section Using Other Utility Programs with GNAT | |
88e1739c FW |
17653 | |
17654 | @noindent | |
7cd4527e AC |
17655 | The object files generated by GNAT are in standard system format and in |
17656 | particular the debugging information uses this format. This means | |
17657 | programs generated by GNAT can be used with existing utilities that | |
17658 | depend on these formats. | |
88e1739c | 17659 | |
7cd4527e AC |
17660 | @ifclear vms |
17661 | In general, any utility program that works with C will also often work with | |
17662 | Ada programs generated by GNAT. This includes software utilities such as | |
17663 | gprof (a profiling program), @code{gdb} (the FSF debugger), and utilities such | |
17664 | as Purify. | |
17665 | @end ifclear | |
88e1739c | 17666 | |
7cd4527e AC |
17667 | @node The External Symbol Naming Scheme of GNAT |
17668 | @section The External Symbol Naming Scheme of GNAT | |
88e1739c FW |
17669 | |
17670 | @noindent | |
7cd4527e AC |
17671 | In order to interpret the output from GNAT, when using tools that are |
17672 | originally intended for use with other languages, it is useful to | |
17673 | understand the conventions used to generate link names from the Ada | |
17674 | entity names. | |
88e1739c | 17675 | |
7cd4527e AC |
17676 | All link names are in all lowercase letters. With the exception of library |
17677 | procedure names, the mechanism used is simply to use the full expanded | |
17678 | Ada name with dots replaced by double underscores. For example, suppose | |
17679 | we have the following package spec: | |
17680 | ||
17681 | @smallexample @c ada | |
17682 | @group | |
88e1739c | 17683 | @cartouche |
7cd4527e AC |
17684 | package QRS is |
17685 | MN : Integer; | |
17686 | end QRS; | |
88e1739c | 17687 | @end cartouche |
7cd4527e | 17688 | @end group |
88e1739c FW |
17689 | @end smallexample |
17690 | ||
17691 | @noindent | |
7cd4527e AC |
17692 | The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so |
17693 | the corresponding link name is @code{qrs__mn}. | |
17694 | @findex Export | |
17695 | Of course if a @code{pragma Export} is used this may be overridden: | |
88e1739c | 17696 | |
7cd4527e | 17697 | @smallexample @c ada |
88e1739c FW |
17698 | @group |
17699 | @cartouche | |
7cd4527e | 17700 | package Exports is |
88e1739c | 17701 | Var1 : Integer; |
7cd4527e | 17702 | pragma Export (Var1, C, External_Name => "var1_name"); |
88e1739c | 17703 | Var2 : Integer; |
7cd4527e AC |
17704 | pragma Export (Var2, C, Link_Name => "var2_link_name"); |
17705 | end Exports; | |
88e1739c FW |
17706 | @end cartouche |
17707 | @end group | |
17708 | @end smallexample | |
17709 | ||
17710 | @noindent | |
17711 | In this case, the link name for @var{Var1} is whatever link name the | |
17712 | C compiler would assign for the C function @var{var1_name}. This typically | |
17713 | would be either @var{var1_name} or @var{_var1_name}, depending on operating | |
17714 | system conventions, but other possibilities exist. The link name for | |
17715 | @var{Var2} is @var{var2_link_name}, and this is not operating system | |
17716 | dependent. | |
17717 | ||
17718 | @findex _main | |
17719 | One exception occurs for library level procedures. A potential ambiguity | |
17720 | arises between the required name @code{_main} for the C main program, | |
17721 | and the name we would otherwise assign to an Ada library level procedure | |
17722 | called @code{Main} (which might well not be the main program). | |
17723 | ||
17724 | To avoid this ambiguity, we attach the prefix @code{_ada_} to such | |
17725 | names. So if we have a library level procedure such as | |
17726 | ||
7cd4527e | 17727 | @smallexample @c ada |
88e1739c FW |
17728 | @group |
17729 | @cartouche | |
7cd4527e | 17730 | procedure Hello (S : String); |
88e1739c FW |
17731 | @end cartouche |
17732 | @end group | |
17733 | @end smallexample | |
17734 | ||
17735 | @noindent | |
17736 | the external name of this procedure will be @var{_ada_hello}. | |
17737 | ||
7cd4527e | 17738 | @ifclear vms |
88e1739c FW |
17739 | @node Ada Mode for Glide |
17740 | @section Ada Mode for @code{Glide} | |
7cd4527e | 17741 | @cindex Ada mode (for Glide) |
88e1739c FW |
17742 | |
17743 | @noindent | |
7cd4527e AC |
17744 | The Glide mode for programming in Ada (both Ada83 and Ada95) helps the |
17745 | user to understand and navigate existing code, and facilitates writing | |
17746 | new code. It furthermore provides some utility functions for easier | |
17747 | integration of standard Emacs features when programming in Ada. | |
88e1739c | 17748 | |
7cd4527e | 17749 | Its general features include: |
88e1739c FW |
17750 | |
17751 | @itemize @bullet | |
17752 | @item | |
7cd4527e AC |
17753 | An Integrated Development Environment with functionality such as the |
17754 | following | |
88e1739c FW |
17755 | |
17756 | @itemize @bullet | |
17757 | @item | |
7cd4527e AC |
17758 | ``Project files'' for configuration-specific aspects |
17759 | (e.g. directories and compilation options) | |
88e1739c FW |
17760 | |
17761 | @item | |
7cd4527e | 17762 | Compiling and stepping through error messages. |
88e1739c FW |
17763 | |
17764 | @item | |
7cd4527e | 17765 | Running and debugging an applications within Glide. |
88e1739c FW |
17766 | @end itemize |
17767 | ||
17768 | @item | |
7cd4527e | 17769 | Pull-down menus |
88e1739c FW |
17770 | |
17771 | @item | |
7cd4527e | 17772 | User configurability |
88e1739c FW |
17773 | @end itemize |
17774 | ||
7cd4527e | 17775 | Some of the specific Ada mode features are: |
88e1739c FW |
17776 | |
17777 | @itemize @bullet | |
17778 | @item | |
7cd4527e | 17779 | Functions for easy and quick stepping through Ada code |
88e1739c FW |
17780 | |
17781 | @item | |
7cd4527e AC |
17782 | Getting cross reference information for identifiers (e.g., finding a |
17783 | defining occurrence) | |
88e1739c FW |
17784 | |
17785 | @item | |
7cd4527e AC |
17786 | Displaying an index menu of types and subprograms, allowing |
17787 | direct selection for browsing | |
88e1739c FW |
17788 | |
17789 | @item | |
7cd4527e | 17790 | Automatic color highlighting of the various Ada entities |
88e1739c FW |
17791 | @end itemize |
17792 | ||
7cd4527e | 17793 | Glide directly supports writing Ada code, via several facilities: |
88e1739c FW |
17794 | |
17795 | @itemize @bullet | |
17796 | @item | |
7cd4527e AC |
17797 | Switching between spec and body files with possible |
17798 | autogeneration of body files | |
88e1739c FW |
17799 | |
17800 | @item | |
7cd4527e | 17801 | Automatic formating of subprogram parameter lists |
88e1739c FW |
17802 | |
17803 | @item | |
7cd4527e | 17804 | Automatic indentation according to Ada syntax |
88e1739c FW |
17805 | |
17806 | @item | |
7cd4527e | 17807 | Automatic completion of identifiers |
88e1739c FW |
17808 | |
17809 | @item | |
7cd4527e | 17810 | Automatic (and configurable) casing of identifiers, keywords, and attributes |
88e1739c FW |
17811 | |
17812 | @item | |
7cd4527e | 17813 | Insertion of syntactic templates |
88e1739c FW |
17814 | |
17815 | @item | |
7cd4527e | 17816 | Block commenting / uncommenting |
88e1739c FW |
17817 | @end itemize |
17818 | ||
7cd4527e AC |
17819 | @noindent |
17820 | For more information, please refer to the online documentation | |
17821 | available in the @code{Glide} @result{} @code{Help} menu. | |
17822 | @end ifclear | |
17823 | ||
88e1739c FW |
17824 | |
17825 | @node Converting Ada Files to html with gnathtml | |
7cd4527e | 17826 | @section Converting Ada Files to HTML with @code{gnathtml} |
88e1739c FW |
17827 | |
17828 | @noindent | |
17829 | This @code{Perl} script allows Ada source files to be browsed using | |
17830 | standard Web browsers. For installation procedure, see the section | |
17831 | @xref{Installing gnathtml}. | |
17832 | ||
17833 | Ada reserved keywords are highlighted in a bold font and Ada comments in | |
17834 | a blue font. Unless your program was compiled with the gcc @option{-gnatx} | |
17835 | switch to suppress the generation of cross-referencing information, user | |
17836 | defined variables and types will appear in a different color; you will | |
17837 | be able to click on any identifier and go to its declaration. | |
17838 | ||
17839 | The command line is as follow: | |
17840 | @smallexample | |
17841 | $ perl gnathtml.pl [switches] ada-files | |
17842 | @end smallexample | |
17843 | ||
7cd4527e | 17844 | @noindent |
88e1739c FW |
17845 | You can pass it as many Ada files as you want. @code{gnathtml} will generate |
17846 | an html file for every ada file, and a global file called @file{index.htm}. | |
17847 | This file is an index of every identifier defined in the files. | |
17848 | ||
17849 | The available switches are the following ones : | |
17850 | ||
7cd4527e | 17851 | @table @option |
88e1739c | 17852 | @item -83 |
7cd4527e | 17853 | @cindex @option{-83} (@code{gnathtml}) |
88e1739c FW |
17854 | Only the subset on the Ada 83 keywords will be highlighted, not the full |
17855 | Ada 95 keywords set. | |
17856 | ||
17857 | @item -cc @var{color} | |
7cd4527e | 17858 | @cindex @option{-cc} (@code{gnathtml}) |
88e1739c FW |
17859 | This option allows you to change the color used for comments. The default |
17860 | value is green. The color argument can be any name accepted by html. | |
17861 | ||
17862 | @item -d | |
7cd4527e | 17863 | @cindex @option{-d} (@code{gnathtml}) |
88e1739c FW |
17864 | If the ada files depend on some other files (using for instance the |
17865 | @code{with} command, the latter will also be converted to html. | |
17866 | Only the files in the user project will be converted to html, not the files | |
17867 | in the run-time library itself. | |
17868 | ||
17869 | @item -D | |
7cd4527e AC |
17870 | @cindex @option{-D} (@code{gnathtml}) |
17871 | This command is the same as @option{-d} above, but @command{gnathtml} will | |
17872 | also look for files in the run-time library, and generate html files for them. | |
17873 | ||
17874 | @item -ext @var{extension} | |
17875 | @cindex @option{-ext} (@code{gnathtml}) | |
17876 | This option allows you to change the extension of the generated HTML files. | |
17877 | If you do not specify an extension, it will default to @file{htm}. | |
88e1739c FW |
17878 | |
17879 | @item -f | |
7cd4527e | 17880 | @cindex @option{-f} (@code{gnathtml}) |
88e1739c FW |
17881 | By default, gnathtml will generate html links only for global entities |
17882 | ('with'ed units, global variables and types,...). If you specify the | |
7cd4527e | 17883 | @option{-f} on the command line, then links will be generated for local |
88e1739c FW |
17884 | entities too. |
17885 | ||
17886 | @item -l @var{number} | |
7cd4527e | 17887 | @cindex @option{-l} (@code{gnathtml}) |
88e1739c FW |
17888 | If this switch is provided and @var{number} is not 0, then @code{gnathtml} |
17889 | will number the html files every @var{number} line. | |
17890 | ||
17891 | @item -I @var{dir} | |
7cd4527e AC |
17892 | @cindex @option{-I} (@code{gnathtml}) |
17893 | Specify a directory to search for library files (@file{.ALI} files) and | |
88e1739c FW |
17894 | source files. You can provide several -I switches on the command line, |
17895 | and the directories will be parsed in the order of the command line. | |
17896 | ||
17897 | @item -o @var{dir} | |
7cd4527e | 17898 | @cindex @option{-o} (@code{gnathtml}) |
88e1739c FW |
17899 | Specify the output directory for html files. By default, gnathtml will |
17900 | saved the generated html files in a subdirectory named @file{html/}. | |
17901 | ||
17902 | @item -p @var{file} | |
7cd4527e | 17903 | @cindex @option{-p} (@code{gnathtml}) |
88e1739c FW |
17904 | If you are using Emacs and the most recent Emacs Ada mode, which provides |
17905 | a full Integrated Development Environment for compiling, checking, | |
7cd4527e | 17906 | running and debugging applications, you may use @file{.gpr} files |
88e1739c FW |
17907 | to give the directories where Emacs can find sources and object files. |
17908 | ||
17909 | Using this switch, you can tell gnathtml to use these files. This allows | |
17910 | you to get an html version of your application, even if it is spread | |
17911 | over multiple directories. | |
17912 | ||
17913 | @item -sc @var{color} | |
7cd4527e | 17914 | @cindex @option{-sc} (@code{gnathtml}) |
88e1739c FW |
17915 | This option allows you to change the color used for symbol definitions. |
17916 | The default value is red. The color argument can be any name accepted by html. | |
17917 | ||
17918 | @item -t @var{file} | |
7cd4527e | 17919 | @cindex @option{-t} (@code{gnathtml}) |
88e1739c FW |
17920 | This switch provides the name of a file. This file contains a list of |
17921 | file names to be converted, and the effect is exactly as though they had | |
17922 | appeared explicitly on the command line. This | |
17923 | is the recommended way to work around the command line length limit on some | |
17924 | systems. | |
17925 | ||
17926 | @end table | |
17927 | ||
17928 | @node Installing gnathtml | |
17929 | @section Installing @code{gnathtml} | |
17930 | ||
17931 | @noindent | |
17932 | @code{Perl} needs to be installed on your machine to run this script. | |
17933 | @code{Perl} is freely available for almost every architecture and | |
17934 | Operating System via the Internet. | |
17935 | ||
17936 | On Unix systems, you may want to modify the first line of the script | |
17937 | @code{gnathtml}, to explicitly tell the Operating system where Perl | |
17938 | is. The syntax of this line is : | |
17939 | @smallexample | |
17940 | #!full_path_name_to_perl | |
17941 | @end smallexample | |
17942 | ||
17943 | @noindent | |
17944 | Alternatively, you may run the script using the following command line: | |
17945 | ||
17946 | @smallexample | |
17947 | $ perl gnathtml.pl [switches] files | |
17948 | @end smallexample | |
17949 | ||
17950 | @ifset vms | |
17951 | @node LSE | |
17952 | @section LSE | |
17953 | @findex LSE | |
17954 | ||
17955 | @noindent | |
17956 | The GNAT distribution provides an Ada 95 template for the Digital Language | |
17957 | Sensitive Editor (LSE), a component of DECset. In order to | |
17958 | access it, invoke LSE with the qualifier /ENVIRONMENT=GNU:[LIB]ADA95.ENV. | |
17959 | ||
17960 | @node Profiling | |
17961 | @section Profiling | |
17962 | @findex PCA | |
17963 | ||
17964 | @noindent | |
17965 | GNAT supports The Digital Performance Coverage Analyzer (PCA), a component | |
7cd4527e | 17966 | of DECset. To use it proceed as outlined under ``HELP PCA'', except for running |
88e1739c FW |
17967 | the collection phase with the /DEBUG qualifier. |
17968 | ||
17969 | @smallexample | |
17970 | $ GNAT MAKE /DEBUG <PROGRAM_NAME> | |
17971 | $ DEFINE LIB$DEBUG PCA$COLLECTOR | |
17972 | $ RUN/DEBUG <PROGRAM_NAME> | |
17973 | @end smallexample | |
17974 | @noindent | |
17975 | @end ifset | |
17976 | ||
17977 | @node Running and Debugging Ada Programs | |
17978 | @chapter Running and Debugging Ada Programs | |
17979 | @cindex Debugging | |
17980 | ||
17981 | @noindent | |
17982 | This chapter discusses how to debug Ada programs. An incorrect Ada program | |
17983 | may be handled in three ways by the GNAT compiler: | |
17984 | ||
17985 | @enumerate | |
17986 | @item | |
17987 | The illegality may be a violation of the static semantics of Ada. In | |
17988 | that case GNAT diagnoses the constructs in the program that are illegal. | |
17989 | It is then a straightforward matter for the user to modify those parts of | |
17990 | the program. | |
17991 | ||
17992 | @item | |
17993 | The illegality may be a violation of the dynamic semantics of Ada. In | |
17994 | that case the program compiles and executes, but may generate incorrect | |
17995 | results, or may terminate abnormally with some exception. | |
17996 | ||
17997 | @item | |
17998 | When presented with a program that contains convoluted errors, GNAT | |
17999 | itself may terminate abnormally without providing full diagnostics on | |
18000 | the incorrect user program. | |
18001 | @end enumerate | |
18002 | ||
18003 | @menu | |
18004 | * The GNAT Debugger GDB:: | |
18005 | * Running GDB:: | |
18006 | * Introduction to GDB Commands:: | |
18007 | * Using Ada Expressions:: | |
18008 | * Calling User-Defined Subprograms:: | |
18009 | * Using the Next Command in a Function:: | |
18010 | * Ada Exceptions:: | |
18011 | * Ada Tasks:: | |
18012 | * Debugging Generic Units:: | |
18013 | * GNAT Abnormal Termination or Failure to Terminate:: | |
18014 | * Naming Conventions for GNAT Source Files:: | |
18015 | * Getting Internal Debugging Information:: | |
18016 | * Stack Traceback:: | |
18017 | @end menu | |
18018 | ||
18019 | @cindex Debugger | |
18020 | @findex gdb | |
18021 | ||
18022 | @node The GNAT Debugger GDB | |
18023 | @section The GNAT Debugger GDB | |
18024 | ||
18025 | @noindent | |
18026 | @code{GDB} is a general purpose, platform-independent debugger that | |
18027 | can be used to debug mixed-language programs compiled with @code{GCC}, | |
18028 | and in particular is capable of debugging Ada programs compiled with | |
18029 | GNAT. The latest versions of @code{GDB} are Ada-aware and can handle | |
18030 | complex Ada data structures. | |
18031 | ||
18032 | The manual @cite{Debugging with GDB} | |
18033 | @ifset vms | |
18034 | , located in the GNU:[DOCS] directory, | |
18035 | @end ifset | |
18036 | contains full details on the usage of @code{GDB}, including a section on | |
18037 | its usage on programs. This manual should be consulted for full | |
18038 | details. The section that follows is a brief introduction to the | |
18039 | philosophy and use of @code{GDB}. | |
18040 | ||
18041 | When GNAT programs are compiled, the compiler optionally writes debugging | |
18042 | information into the generated object file, including information on | |
18043 | line numbers, and on declared types and variables. This information is | |
18044 | separate from the generated code. It makes the object files considerably | |
18045 | larger, but it does not add to the size of the actual executable that | |
18046 | will be loaded into memory, and has no impact on run-time performance. The | |
18047 | generation of debug information is triggered by the use of the | |
18048 | ^-g^/DEBUG^ switch in the gcc or gnatmake command used to carry out | |
18049 | the compilations. It is important to emphasize that the use of these | |
18050 | options does not change the generated code. | |
18051 | ||
18052 | The debugging information is written in standard system formats that | |
18053 | are used by many tools, including debuggers and profilers. The format | |
18054 | of the information is typically designed to describe C types and | |
18055 | semantics, but GNAT implements a translation scheme which allows full | |
18056 | details about Ada types and variables to be encoded into these | |
18057 | standard C formats. Details of this encoding scheme may be found in | |
18058 | the file exp_dbug.ads in the GNAT source distribution. However, the | |
18059 | details of this encoding are, in general, of no interest to a user, | |
18060 | since @code{GDB} automatically performs the necessary decoding. | |
18061 | ||
18062 | When a program is bound and linked, the debugging information is | |
18063 | collected from the object files, and stored in the executable image of | |
18064 | the program. Again, this process significantly increases the size of | |
18065 | the generated executable file, but it does not increase the size of | |
18066 | the executable program itself. Furthermore, if this program is run in | |
18067 | the normal manner, it runs exactly as if the debug information were | |
18068 | not present, and takes no more actual memory. | |
18069 | ||
18070 | However, if the program is run under control of @code{GDB}, the | |
18071 | debugger is activated. The image of the program is loaded, at which | |
18072 | point it is ready to run. If a run command is given, then the program | |
18073 | will run exactly as it would have if @code{GDB} were not present. This | |
18074 | is a crucial part of the @code{GDB} design philosophy. @code{GDB} is | |
18075 | entirely non-intrusive until a breakpoint is encountered. If no | |
18076 | breakpoint is ever hit, the program will run exactly as it would if no | |
18077 | debugger were present. When a breakpoint is hit, @code{GDB} accesses | |
18078 | the debugging information and can respond to user commands to inspect | |
18079 | variables, and more generally to report on the state of execution. | |
18080 | ||
7cd4527e | 18081 | @c ************** |
88e1739c FW |
18082 | @node Running GDB |
18083 | @section Running GDB | |
18084 | ||
88e1739c FW |
18085 | @noindent |
18086 | The debugger can be launched directly and simply from @code{glide} or | |
18087 | through its graphical interface: @code{gvd}. It can also be used | |
18088 | directly in text mode. Here is described the basic use of @code{GDB} | |
18089 | in text mode. All the commands described below can be used in the | |
7cd4527e | 18090 | @code{gvd} console window even though there is usually other more |
88e1739c FW |
18091 | graphical ways to achieve the same goals. |
18092 | ||
18093 | @ifclear vms | |
18094 | @noindent | |
7cd4527e | 18095 | The command to run the graphical interface of the debugger is |
88e1739c FW |
18096 | @smallexample |
18097 | $ gvd program | |
18098 | @end smallexample | |
18099 | @end ifclear | |
18100 | ||
18101 | @noindent | |
18102 | The command to run @code{GDB} in text mode is | |
18103 | ||
18104 | @smallexample | |
18105 | $ ^gdb program^$ GDB PROGRAM^ | |
18106 | @end smallexample | |
18107 | ||
18108 | @noindent | |
18109 | where @code{^program^PROGRAM^} is the name of the executable file. This | |
18110 | activates the debugger and results in a prompt for debugger commands. | |
18111 | The simplest command is simply @code{run}, which causes the program to run | |
18112 | exactly as if the debugger were not present. The following section | |
18113 | describes some of the additional commands that can be given to @code{GDB}. | |
88e1739c | 18114 | |
88e1739c | 18115 | |
7cd4527e | 18116 | @c ******************************* |
88e1739c FW |
18117 | @node Introduction to GDB Commands |
18118 | @section Introduction to GDB Commands | |
18119 | ||
18120 | @noindent | |
18121 | @code{GDB} contains a large repertoire of commands. The manual | |
18122 | @cite{Debugging with GDB} | |
18123 | @ifset vms | |
18124 | , located in the GNU:[DOCS] directory, | |
18125 | @end ifset | |
18126 | includes extensive documentation on the use | |
18127 | of these commands, together with examples of their use. Furthermore, | |
18128 | the command @var{help} invoked from within @code{GDB} activates a simple help | |
18129 | facility which summarizes the available commands and their options. | |
18130 | In this section we summarize a few of the most commonly | |
18131 | used commands to give an idea of what @code{GDB} is about. You should create | |
18132 | a simple program with debugging information and experiment with the use of | |
18133 | these @code{GDB} commands on the program as you read through the | |
18134 | following section. | |
18135 | ||
18136 | @table @code | |
18137 | @item set args @var{arguments} | |
18138 | The @var{arguments} list above is a list of arguments to be passed to | |
18139 | the program on a subsequent run command, just as though the arguments | |
18140 | had been entered on a normal invocation of the program. The @code{set args} | |
18141 | command is not needed if the program does not require arguments. | |
18142 | ||
18143 | @item run | |
18144 | The @code{run} command causes execution of the program to start from | |
18145 | the beginning. If the program is already running, that is to say if | |
18146 | you are currently positioned at a breakpoint, then a prompt will ask | |
18147 | for confirmation that you want to abandon the current execution and | |
18148 | restart. | |
18149 | ||
18150 | @item breakpoint @var{location} | |
18151 | The breakpoint command sets a breakpoint, that is to say a point at which | |
18152 | execution will halt and @code{GDB} will await further | |
18153 | commands. @var{location} is | |
18154 | either a line number within a file, given in the format @code{file:linenumber}, | |
18155 | or it is the name of a subprogram. If you request that a breakpoint be set on | |
18156 | a subprogram that is overloaded, a prompt will ask you to specify on which of | |
18157 | those subprograms you want to breakpoint. You can also | |
18158 | specify that all of them should be breakpointed. If the program is run | |
18159 | and execution encounters the breakpoint, then the program | |
18160 | stops and @code{GDB} signals that the breakpoint was encountered by | |
18161 | printing the line of code before which the program is halted. | |
18162 | ||
18163 | @item breakpoint exception @var{name} | |
18164 | A special form of the breakpoint command which breakpoints whenever | |
18165 | exception @var{name} is raised. | |
18166 | If @var{name} is omitted, | |
18167 | then a breakpoint will occur when any exception is raised. | |
18168 | ||
18169 | @item print @var{expression} | |
18170 | This will print the value of the given expression. Most simple | |
18171 | Ada expression formats are properly handled by @code{GDB}, so the expression | |
18172 | can contain function calls, variables, operators, and attribute references. | |
18173 | ||
18174 | @item continue | |
18175 | Continues execution following a breakpoint, until the next breakpoint or the | |
18176 | termination of the program. | |
18177 | ||
18178 | @item step | |
7cd4527e AC |
18179 | Executes a single line after a breakpoint. If the next statement |
18180 | is a subprogram call, execution continues into (the first statement of) | |
18181 | the called subprogram. | |
88e1739c FW |
18182 | |
18183 | @item next | |
18184 | Executes a single line. If this line is a subprogram call, executes and | |
18185 | returns from the call. | |
18186 | ||
18187 | @item list | |
18188 | Lists a few lines around the current source location. In practice, it | |
18189 | is usually more convenient to have a separate edit window open with the | |
18190 | relevant source file displayed. Successive applications of this command | |
18191 | print subsequent lines. The command can be given an argument which is a | |
18192 | line number, in which case it displays a few lines around the specified one. | |
18193 | ||
18194 | @item backtrace | |
18195 | Displays a backtrace of the call chain. This command is typically | |
18196 | used after a breakpoint has occurred, to examine the sequence of calls that | |
18197 | leads to the current breakpoint. The display includes one line for each | |
18198 | activation record (frame) corresponding to an active subprogram. | |
18199 | ||
18200 | @item up | |
18201 | At a breakpoint, @code{GDB} can display the values of variables local | |
18202 | to the current frame. The command @code{up} can be used to | |
18203 | examine the contents of other active frames, by moving the focus up | |
18204 | the stack, that is to say from callee to caller, one frame at a time. | |
18205 | ||
18206 | @item down | |
18207 | Moves the focus of @code{GDB} down from the frame currently being | |
18208 | examined to the frame of its callee (the reverse of the previous command), | |
18209 | ||
18210 | @item frame @var{n} | |
18211 | Inspect the frame with the given number. The value 0 denotes the frame | |
18212 | of the current breakpoint, that is to say the top of the call stack. | |
18213 | ||
18214 | @end table | |
18215 | ||
18216 | The above list is a very short introduction to the commands that | |
18217 | @code{GDB} provides. Important additional capabilities, including conditional | |
18218 | breakpoints, the ability to execute command sequences on a breakpoint, | |
18219 | the ability to debug at the machine instruction level and many other | |
18220 | features are described in detail in @cite{Debugging with GDB}. | |
18221 | Note that most commands can be abbreviated | |
18222 | (for example, c for continue, bt for backtrace). | |
18223 | ||
18224 | @node Using Ada Expressions | |
18225 | @section Using Ada Expressions | |
18226 | @cindex Ada expressions | |
18227 | ||
18228 | @noindent | |
18229 | @code{GDB} supports a fairly large subset of Ada expression syntax, with some | |
18230 | extensions. The philosophy behind the design of this subset is | |
18231 | ||
18232 | @itemize @bullet | |
18233 | @item | |
18234 | That @code{GDB} should provide basic literals and access to operations for | |
18235 | arithmetic, dereferencing, field selection, indexing, and subprogram calls, | |
18236 | leaving more sophisticated computations to subprograms written into the | |
18237 | program (which therefore may be called from @code{GDB}). | |
18238 | ||
18239 | @item | |
18240 | That type safety and strict adherence to Ada language restrictions | |
18241 | are not particularly important to the @code{GDB} user. | |
18242 | ||
18243 | @item | |
18244 | That brevity is important to the @code{GDB} user. | |
18245 | @end itemize | |
18246 | ||
18247 | Thus, for brevity, the debugger acts as if there were | |
18248 | implicit @code{with} and @code{use} clauses in effect for all user-written | |
18249 | packages, thus making it unnecessary to fully qualify most names with | |
18250 | their packages, regardless of context. Where this causes ambiguity, | |
18251 | @code{GDB} asks the user's intent. | |
18252 | ||
18253 | For details on the supported Ada syntax, see @cite{Debugging with GDB}. | |
18254 | ||
18255 | @node Calling User-Defined Subprograms | |
18256 | @section Calling User-Defined Subprograms | |
18257 | ||
18258 | @noindent | |
18259 | An important capability of @code{GDB} is the ability to call user-defined | |
18260 | subprograms while debugging. This is achieved simply by entering | |
18261 | a subprogram call statement in the form: | |
18262 | ||
18263 | @smallexample | |
18264 | call subprogram-name (parameters) | |
18265 | @end smallexample | |
18266 | ||
18267 | @noindent | |
18268 | The keyword @code{call} can be omitted in the normal case where the | |
18269 | @code{subprogram-name} does not coincide with any of the predefined | |
18270 | @code{GDB} commands. | |
18271 | ||
18272 | The effect is to invoke the given subprogram, passing it the | |
18273 | list of parameters that is supplied. The parameters can be expressions and | |
18274 | can include variables from the program being debugged. The | |
18275 | subprogram must be defined | |
18276 | at the library level within your program, and @code{GDB} will call the | |
18277 | subprogram within the environment of your program execution (which | |
18278 | means that the subprogram is free to access or even modify variables | |
18279 | within your program). | |
18280 | ||
18281 | The most important use of this facility is in allowing the inclusion of | |
18282 | debugging routines that are tailored to particular data structures | |
18283 | in your program. Such debugging routines can be written to provide a suitably | |
18284 | high-level description of an abstract type, rather than a low-level dump | |
18285 | of its physical layout. After all, the standard | |
18286 | @code{GDB print} command only knows the physical layout of your | |
18287 | types, not their abstract meaning. Debugging routines can provide information | |
18288 | at the desired semantic level and are thus enormously useful. | |
18289 | ||
18290 | For example, when debugging GNAT itself, it is crucial to have access to | |
18291 | the contents of the tree nodes used to represent the program internally. | |
18292 | But tree nodes are represented simply by an integer value (which in turn | |
18293 | is an index into a table of nodes). | |
18294 | Using the @code{print} command on a tree node would simply print this integer | |
18295 | value, which is not very useful. But the PN routine (defined in file | |
18296 | treepr.adb in the GNAT sources) takes a tree node as input, and displays | |
18297 | a useful high level representation of the tree node, which includes the | |
18298 | syntactic category of the node, its position in the source, the integers | |
18299 | that denote descendant nodes and parent node, as well as varied | |
18300 | semantic information. To study this example in more detail, you might want to | |
18301 | look at the body of the PN procedure in the stated file. | |
18302 | ||
18303 | @node Using the Next Command in a Function | |
18304 | @section Using the Next Command in a Function | |
18305 | ||
18306 | @noindent | |
18307 | When you use the @code{next} command in a function, the current source | |
18308 | location will advance to the next statement as usual. A special case | |
18309 | arises in the case of a @code{return} statement. | |
18310 | ||
7cd4527e | 18311 | Part of the code for a return statement is the ``epilog'' of the function. |
88e1739c FW |
18312 | This is the code that returns to the caller. There is only one copy of |
18313 | this epilog code, and it is typically associated with the last return | |
18314 | statement in the function if there is more than one return. In some | |
18315 | implementations, this epilog is associated with the first statement | |
18316 | of the function. | |
18317 | ||
18318 | The result is that if you use the @code{next} command from a return | |
18319 | statement that is not the last return statement of the function you | |
18320 | may see a strange apparent jump to the last return statement or to | |
18321 | the start of the function. You should simply ignore this odd jump. | |
18322 | The value returned is always that from the first return statement | |
18323 | that was stepped through. | |
18324 | ||
18325 | @node Ada Exceptions | |
18326 | @section Breaking on Ada Exceptions | |
18327 | @cindex Exceptions | |
18328 | ||
18329 | @noindent | |
18330 | You can set breakpoints that trip when your program raises | |
18331 | selected exceptions. | |
18332 | ||
18333 | @table @code | |
18334 | @item break exception | |
18335 | Set a breakpoint that trips whenever (any task in the) program raises | |
18336 | any exception. | |
18337 | ||
18338 | @item break exception @var{name} | |
18339 | Set a breakpoint that trips whenever (any task in the) program raises | |
18340 | the exception @var{name}. | |
18341 | ||
18342 | @item break exception unhandled | |
18343 | Set a breakpoint that trips whenever (any task in the) program raises an | |
18344 | exception for which there is no handler. | |
18345 | ||
18346 | @item info exceptions | |
18347 | @itemx info exceptions @var{regexp} | |
18348 | The @code{info exceptions} command permits the user to examine all defined | |
18349 | exceptions within Ada programs. With a regular expression, @var{regexp}, as | |
18350 | argument, prints out only those exceptions whose name matches @var{regexp}. | |
18351 | @end table | |
18352 | ||
18353 | @node Ada Tasks | |
18354 | @section Ada Tasks | |
18355 | @cindex Tasks | |
18356 | ||
18357 | @noindent | |
18358 | @code{GDB} allows the following task-related commands: | |
18359 | ||
18360 | @table @code | |
18361 | @item info tasks | |
18362 | This command shows a list of current Ada tasks, as in the following example: | |
18363 | ||
18364 | @smallexample | |
18365 | @iftex | |
18366 | @leftskip=0cm | |
18367 | @end iftex | |
18368 | (gdb) info tasks | |
18369 | ID TID P-ID Thread Pri State Name | |
18370 | 1 8088000 0 807e000 15 Child Activation Wait main_task | |
18371 | 2 80a4000 1 80ae000 15 Accept/Select Wait b | |
18372 | 3 809a800 1 80a4800 15 Child Activation Wait a | |
18373 | * 4 80ae800 3 80b8000 15 Running c | |
18374 | @end smallexample | |
18375 | ||
18376 | @noindent | |
18377 | In this listing, the asterisk before the first task indicates it to be the | |
18378 | currently running task. The first column lists the task ID that is used | |
18379 | to refer to tasks in the following commands. | |
18380 | ||
18381 | @item break @var{linespec} task @var{taskid} | |
18382 | @itemx break @var{linespec} task @var{taskid} if @dots{} | |
18383 | @cindex Breakpoints and tasks | |
18384 | These commands are like the @code{break @dots{} thread @dots{}}. | |
18385 | @var{linespec} specifies source lines. | |
18386 | ||
18387 | Use the qualifier @samp{task @var{taskid}} with a breakpoint command | |
18388 | to specify that you only want @code{GDB} to stop the program when a | |
18389 | particular Ada task reaches this breakpoint. @var{taskid} is one of the | |
18390 | numeric task identifiers assigned by @code{GDB}, shown in the first | |
18391 | column of the @samp{info tasks} display. | |
18392 | ||
18393 | If you do not specify @samp{task @var{taskid}} when you set a | |
18394 | breakpoint, the breakpoint applies to @emph{all} tasks of your | |
18395 | program. | |
18396 | ||
18397 | You can use the @code{task} qualifier on conditional breakpoints as | |
18398 | well; in this case, place @samp{task @var{taskid}} before the | |
18399 | breakpoint condition (before the @code{if}). | |
18400 | ||
18401 | @item task @var{taskno} | |
18402 | @cindex Task switching | |
18403 | ||
18404 | This command allows to switch to the task referred by @var{taskno}. In | |
18405 | particular, This allows to browse the backtrace of the specified | |
18406 | task. It is advised to switch back to the original task before | |
18407 | continuing execution otherwise the scheduling of the program may be | |
18408 | perturbated. | |
18409 | @end table | |
18410 | ||
18411 | @noindent | |
7cd4527e AC |
18412 | For more detailed information on the tasking support, |
18413 | see @cite{Debugging with GDB}. | |
88e1739c FW |
18414 | |
18415 | @node Debugging Generic Units | |
18416 | @section Debugging Generic Units | |
18417 | @cindex Debugging Generic Units | |
18418 | @cindex Generics | |
18419 | ||
18420 | @noindent | |
18421 | GNAT always uses code expansion for generic instantiation. This means that | |
18422 | each time an instantiation occurs, a complete copy of the original code is | |
18423 | made, with appropriate substitutions of formals by actuals. | |
18424 | ||
18425 | It is not possible to refer to the original generic entities in | |
18426 | @code{GDB}, but it is always possible to debug a particular instance of | |
18427 | a generic, by using the appropriate expanded names. For example, if we have | |
18428 | ||
7cd4527e | 18429 | @smallexample @c ada |
88e1739c FW |
18430 | @group |
18431 | @cartouche | |
7cd4527e | 18432 | procedure g is |
88e1739c | 18433 | |
7cd4527e AC |
18434 | generic package k is |
18435 | procedure kp (v1 : in out integer); | |
18436 | end k; | |
88e1739c | 18437 | |
7cd4527e AC |
18438 | package body k is |
18439 | procedure kp (v1 : in out integer) is | |
18440 | begin | |
88e1739c | 18441 | v1 := v1 + 1; |
7cd4527e AC |
18442 | end kp; |
18443 | end k; | |
88e1739c | 18444 | |
7cd4527e AC |
18445 | package k1 is new k; |
18446 | package k2 is new k; | |
88e1739c FW |
18447 | |
18448 | var : integer := 1; | |
18449 | ||
7cd4527e | 18450 | begin |
88e1739c FW |
18451 | k1.kp (var); |
18452 | k2.kp (var); | |
18453 | k1.kp (var); | |
18454 | k2.kp (var); | |
7cd4527e | 18455 | end; |
88e1739c FW |
18456 | @end cartouche |
18457 | @end group | |
18458 | @end smallexample | |
18459 | ||
18460 | @noindent | |
18461 | Then to break on a call to procedure kp in the k2 instance, simply | |
18462 | use the command: | |
18463 | ||
18464 | @smallexample | |
18465 | (gdb) break g.k2.kp | |
18466 | @end smallexample | |
18467 | ||
18468 | @noindent | |
18469 | When the breakpoint occurs, you can step through the code of the | |
18470 | instance in the normal manner and examine the values of local variables, as for | |
18471 | other units. | |
18472 | ||
18473 | @node GNAT Abnormal Termination or Failure to Terminate | |
18474 | @section GNAT Abnormal Termination or Failure to Terminate | |
18475 | @cindex GNAT Abnormal Termination or Failure to Terminate | |
18476 | ||
18477 | @noindent | |
18478 | When presented with programs that contain serious errors in syntax | |
18479 | or semantics, | |
18480 | GNAT may on rare occasions experience problems in operation, such | |
18481 | as aborting with a | |
18482 | segmentation fault or illegal memory access, raising an internal | |
18483 | exception, terminating abnormally, or failing to terminate at all. | |
18484 | In such cases, you can activate | |
18485 | various features of GNAT that can help you pinpoint the construct in your | |
18486 | program that is the likely source of the problem. | |
18487 | ||
18488 | The following strategies are presented in increasing order of | |
18489 | difficulty, corresponding to your experience in using GNAT and your | |
18490 | familiarity with compiler internals. | |
18491 | ||
18492 | @enumerate | |
18493 | @item | |
18494 | Run @code{gcc} with the @option{-gnatf}. This first | |
18495 | switch causes all errors on a given line to be reported. In its absence, | |
18496 | only the first error on a line is displayed. | |
18497 | ||
18498 | The @option{-gnatdO} switch causes errors to be displayed as soon as they | |
18499 | are encountered, rather than after compilation is terminated. If GNAT | |
18500 | terminates prematurely or goes into an infinite loop, the last error | |
18501 | message displayed may help to pinpoint the culprit. | |
18502 | ||
18503 | @item | |
7cd4527e | 18504 | Run @code{gcc} with the @option{^-v (verbose)^/VERBOSE^} switch. In this mode, |
88e1739c FW |
18505 | @code{gcc} produces ongoing information about the progress of the |
18506 | compilation and provides the name of each procedure as code is | |
18507 | generated. This switch allows you to find which Ada procedure was being | |
18508 | compiled when it encountered a code generation problem. | |
18509 | ||
18510 | @item | |
18511 | @cindex @option{-gnatdc} switch | |
18512 | Run @code{gcc} with the @option{-gnatdc} switch. This is a GNAT specific | |
7cd4527e AC |
18513 | switch that does for the front-end what @option{^-v^VERBOSE^} does |
18514 | for the back end. The system prints the name of each unit, | |
18515 | either a compilation unit or nested unit, as it is being analyzed. | |
88e1739c FW |
18516 | @item |
18517 | Finally, you can start | |
18518 | @code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the | |
18519 | front-end of GNAT, and can be run independently (normally it is just | |
18520 | called from @code{gcc}). You can use @code{gdb} on @code{gnat1} as you | |
18521 | would on a C program (but @pxref{The GNAT Debugger GDB} for caveats). The | |
18522 | @code{where} command is the first line of attack; the variable | |
18523 | @code{lineno} (seen by @code{print lineno}), used by the second phase of | |
18524 | @code{gnat1} and by the @code{gcc} backend, indicates the source line at | |
18525 | which the execution stopped, and @code{input_file name} indicates the name of | |
18526 | the source file. | |
18527 | @end enumerate | |
18528 | ||
18529 | @node Naming Conventions for GNAT Source Files | |
18530 | @section Naming Conventions for GNAT Source Files | |
18531 | ||
18532 | @noindent | |
18533 | In order to examine the workings of the GNAT system, the following | |
18534 | brief description of its organization may be helpful: | |
18535 | ||
18536 | @itemize @bullet | |
18537 | @item | |
18538 | Files with prefix @file{^sc^SC^} contain the lexical scanner. | |
18539 | ||
18540 | @item | |
18541 | All files prefixed with @file{^par^PAR^} are components of the parser. The | |
18542 | numbers correspond to chapters of the Ada 95 Reference Manual. For example, | |
18543 | parsing of select statements can be found in @file{par-ch9.adb}. | |
18544 | ||
18545 | @item | |
18546 | All files prefixed with @file{^sem^SEM^} perform semantic analysis. The | |
18547 | numbers correspond to chapters of the Ada standard. For example, all | |
18548 | issues involving context clauses can be found in @file{sem_ch10.adb}. In | |
18549 | addition, some features of the language require sufficient special processing | |
18550 | to justify their own semantic files: sem_aggr for aggregates, sem_disp for | |
18551 | dynamic dispatching, etc. | |
18552 | ||
18553 | @item | |
18554 | All files prefixed with @file{^exp^EXP^} perform normalization and | |
18555 | expansion of the intermediate representation (abstract syntax tree, or AST). | |
18556 | these files use the same numbering scheme as the parser and semantics files. | |
18557 | For example, the construction of record initialization procedures is done in | |
18558 | @file{exp_ch3.adb}. | |
18559 | ||
18560 | @item | |
18561 | The files prefixed with @file{^bind^BIND^} implement the binder, which | |
18562 | verifies the consistency of the compilation, determines an order of | |
18563 | elaboration, and generates the bind file. | |
18564 | ||
18565 | @item | |
18566 | The files @file{atree.ads} and @file{atree.adb} detail the low-level | |
18567 | data structures used by the front-end. | |
18568 | ||
18569 | @item | |
18570 | The files @file{sinfo.ads} and @file{sinfo.adb} detail the structure of | |
18571 | the abstract syntax tree as produced by the parser. | |
18572 | ||
18573 | @item | |
18574 | The files @file{einfo.ads} and @file{einfo.adb} detail the attributes of | |
18575 | all entities, computed during semantic analysis. | |
18576 | ||
18577 | @item | |
18578 | Library management issues are dealt with in files with prefix | |
18579 | @file{^lib^LIB^}. | |
18580 | ||
18581 | @item | |
18582 | @findex Ada | |
18583 | @cindex Annex A | |
18584 | Ada files with the prefix @file{^a-^A-^} are children of @code{Ada}, as | |
18585 | defined in Annex A. | |
18586 | ||
18587 | @item | |
18588 | @findex Interfaces | |
18589 | @cindex Annex B | |
18590 | Files with prefix @file{^i-^I-^} are children of @code{Interfaces}, as | |
18591 | defined in Annex B. | |
18592 | ||
18593 | @item | |
18594 | @findex System | |
18595 | Files with prefix @file{^s-^S-^} are children of @code{System}. This includes | |
18596 | both language-defined children and GNAT run-time routines. | |
18597 | ||
18598 | @item | |
18599 | @findex GNAT | |
18600 | Files with prefix @file{^g-^G-^} are children of @code{GNAT}. These are useful | |
18601 | general-purpose packages, fully documented in their specifications. All | |
18602 | the other @file{.c} files are modifications of common @code{gcc} files. | |
18603 | @end itemize | |
18604 | ||
18605 | @node Getting Internal Debugging Information | |
18606 | @section Getting Internal Debugging Information | |
18607 | ||
18608 | @noindent | |
18609 | Most compilers have internal debugging switches and modes. GNAT | |
18610 | does also, except GNAT internal debugging switches and modes are not | |
18611 | secret. A summary and full description of all the compiler and binder | |
18612 | debug flags are in the file @file{debug.adb}. You must obtain the | |
18613 | sources of the compiler to see the full detailed effects of these flags. | |
18614 | ||
18615 | The switches that print the source of the program (reconstructed from | |
18616 | the internal tree) are of general interest for user programs, as are the | |
18617 | options to print | |
18618 | the full internal tree, and the entity table (the symbol table | |
18619 | information). The reconstructed source provides a readable version of the | |
7cd4527e AC |
18620 | program after the front-end has completed analysis and expansion, |
18621 | and is useful when studying the performance of specific constructs. | |
18622 | For example, constraint checks are indicated, complex aggregates | |
18623 | are replaced with loops and assignments, and tasking primitives | |
18624 | are replaced with run-time calls. | |
88e1739c FW |
18625 | |
18626 | @node Stack Traceback | |
18627 | @section Stack Traceback | |
18628 | @cindex traceback | |
18629 | @cindex stack traceback | |
18630 | @cindex stack unwinding | |
18631 | ||
18632 | @noindent | |
18633 | Traceback is a mechanism to display the sequence of subprogram calls that | |
18634 | leads to a specified execution point in a program. Often (but not always) | |
18635 | the execution point is an instruction at which an exception has been raised. | |
18636 | This mechanism is also known as @i{stack unwinding} because it obtains | |
18637 | its information by scanning the run-time stack and recovering the activation | |
18638 | records of all active subprograms. Stack unwinding is one of the most | |
18639 | important tools for program debugging. | |
18640 | ||
88e1739c FW |
18641 | The first entry stored in traceback corresponds to the deepest calling level, |
18642 | that is to say the subprogram currently executing the instruction | |
18643 | from which we want to obtain the traceback. | |
18644 | ||
88e1739c | 18645 | Note that there is no runtime performance penalty when stack traceback |
7cd4527e | 18646 | is enabled, and no exception is raised during program execution. |
88e1739c FW |
18647 | |
18648 | @menu | |
18649 | * Non-Symbolic Traceback:: | |
18650 | * Symbolic Traceback:: | |
18651 | @end menu | |
18652 | ||
18653 | @node Non-Symbolic Traceback | |
18654 | @subsection Non-Symbolic Traceback | |
18655 | @cindex traceback, non-symbolic | |
18656 | ||
18657 | @noindent | |
18658 | Note: this feature is not supported on all platforms. See | |
18659 | @file{GNAT.Traceback spec in g-traceb.ads} for a complete list of supported | |
18660 | platforms. | |
18661 | ||
18662 | @menu | |
18663 | * Tracebacks From an Unhandled Exception:: | |
18664 | * Tracebacks From Exception Occurrences (non-symbolic):: | |
18665 | * Tracebacks From Anywhere in a Program (non-symbolic):: | |
18666 | @end menu | |
18667 | ||
18668 | @node Tracebacks From an Unhandled Exception | |
18669 | @subsubsection Tracebacks From an Unhandled Exception | |
18670 | ||
18671 | @noindent | |
18672 | A runtime non-symbolic traceback is a list of addresses of call instructions. | |
7cd4527e | 18673 | To enable this feature you must use the @option{-E} |
88e1739c | 18674 | @code{gnatbind}'s option. With this option a stack traceback is stored as part |
7cd4527e AC |
18675 | of exception information. You can retrieve this information using the |
18676 | @code{addr2line} tool. | |
88e1739c | 18677 | |
7cd4527e | 18678 | Here is a simple example: |
88e1739c | 18679 | |
7cd4527e | 18680 | @smallexample @c ada |
88e1739c | 18681 | @cartouche |
88e1739c FW |
18682 | procedure STB is |
18683 | ||
18684 | procedure P1 is | |
18685 | begin | |
18686 | raise Constraint_Error; | |
18687 | end P1; | |
18688 | ||
18689 | procedure P2 is | |
18690 | begin | |
18691 | P1; | |
18692 | end P2; | |
18693 | ||
18694 | begin | |
18695 | P2; | |
18696 | end STB; | |
88e1739c FW |
18697 | @end cartouche |
18698 | @end smallexample | |
18699 | ||
18700 | @smallexample | |
18701 | $ gnatmake stb -bargs -E | |
18702 | $ stb | |
18703 | ||
18704 | Execution terminated by unhandled exception | |
18705 | Exception name: CONSTRAINT_ERROR | |
18706 | Message: stb.adb:5 | |
18707 | Call stack traceback locations: | |
18708 | 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 | |
18709 | @end smallexample | |
18710 | ||
18711 | @noindent | |
18712 | As we see the traceback lists a sequence of addresses for the unhandled | |
7cd4527e | 18713 | exception @code{CONSTRAINT_ERROR} raised in procedure P1. It is easy to |
88e1739c FW |
18714 | guess that this exception come from procedure P1. To translate these |
18715 | addresses into the source lines where the calls appear, the | |
18716 | @code{addr2line} tool, described below, is invaluable. The use of this tool | |
18717 | requires the program to be compiled with debug information. | |
18718 | ||
18719 | @smallexample | |
18720 | $ gnatmake -g stb -bargs -E | |
18721 | $ stb | |
18722 | ||
18723 | Execution terminated by unhandled exception | |
18724 | Exception name: CONSTRAINT_ERROR | |
18725 | Message: stb.adb:5 | |
18726 | Call stack traceback locations: | |
18727 | 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 | |
18728 | ||
18729 | $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 | |
18730 | 0x4011f1 0x77e892a4 | |
18731 | ||
18732 | 00401373 at d:/stb/stb.adb:5 | |
18733 | 0040138B at d:/stb/stb.adb:10 | |
18734 | 0040139C at d:/stb/stb.adb:14 | |
18735 | 00401335 at d:/stb/b~stb.adb:104 | |
18736 | 004011C4 at /build/.../crt1.c:200 | |
18737 | 004011F1 at /build/.../crt1.c:222 | |
18738 | 77E892A4 in ?? at ??:0 | |
18739 | @end smallexample | |
18740 | ||
18741 | @noindent | |
7cd4527e | 18742 | The @code{addr2line} tool has several other useful options: |
88e1739c FW |
18743 | |
18744 | @table @code | |
18745 | @item --functions | |
18746 | to get the function name corresponding to any location | |
18747 | ||
18748 | @item --demangle=gnat | |
7cd4527e AC |
18749 | to use the gnat decoding mode for the function names. Note that |
18750 | for binutils version 2.9.x the option is simply @option{--demangle}. | |
88e1739c FW |
18751 | @end table |
18752 | ||
18753 | @smallexample | |
18754 | $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b | |
18755 | 0x40139c 0x401335 0x4011c4 0x4011f1 | |
18756 | ||
18757 | 00401373 in stb.p1 at d:/stb/stb.adb:5 | |
18758 | 0040138B in stb.p2 at d:/stb/stb.adb:10 | |
18759 | 0040139C in stb at d:/stb/stb.adb:14 | |
18760 | 00401335 in main at d:/stb/b~stb.adb:104 | |
18761 | 004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200 | |
18762 | 004011F1 in <mainCRTStartup> at /build/.../crt1.c:222 | |
18763 | @end smallexample | |
18764 | ||
18765 | @noindent | |
18766 | From this traceback we can see that the exception was raised in | |
18767 | @file{stb.adb} at line 5, which was reached from a procedure call in | |
18768 | @file{stb.adb} at line 10, and so on. The @file{b~std.adb} is the binder file, | |
18769 | which contains the call to the main program. | |
18770 | @pxref{Running gnatbind}. The remaining entries are assorted runtime routines, | |
18771 | and the output will vary from platform to platform. | |
18772 | ||
88e1739c FW |
18773 | It is also possible to use @code{GDB} with these traceback addresses to debug |
18774 | the program. For example, we can break at a given code location, as reported | |
18775 | in the stack traceback: | |
18776 | ||
18777 | @smallexample | |
18778 | $ gdb -nw stb | |
7cd4527e | 18779 | @ifclear vms |
88e1739c FW |
18780 | @noindent |
18781 | Furthermore, this feature is not implemented inside Windows DLL. Only | |
18782 | the non-symbolic traceback is reported in this case. | |
7cd4527e | 18783 | @end ifclear |
88e1739c FW |
18784 | |
18785 | (gdb) break *0x401373 | |
18786 | Breakpoint 1 at 0x401373: file stb.adb, line 5. | |
18787 | @end smallexample | |
18788 | ||
18789 | @noindent | |
18790 | It is important to note that the stack traceback addresses | |
18791 | do not change when debug information is included. This is particularly useful | |
18792 | because it makes it possible to release software without debug information (to | |
18793 | minimize object size), get a field report that includes a stack traceback | |
18794 | whenever an internal bug occurs, and then be able to retrieve the sequence | |
18795 | of calls with the same program compiled with debug information. | |
18796 | ||
18797 | @node Tracebacks From Exception Occurrences (non-symbolic) | |
18798 | @subsubsection Tracebacks From Exception Occurrences | |
18799 | ||
18800 | @noindent | |
7cd4527e | 18801 | Non-symbolic tracebacks are obtained by using the @option{-E} binder argument. |
88e1739c FW |
18802 | The stack traceback is attached to the exception information string, and can |
18803 | be retrieved in an exception handler within the Ada program, by means of the | |
18804 | Ada95 facilities defined in @code{Ada.Exceptions}. Here is a simple example: | |
18805 | ||
7cd4527e | 18806 | @smallexample @c ada |
88e1739c FW |
18807 | with Ada.Text_IO; |
18808 | with Ada.Exceptions; | |
18809 | ||
18810 | procedure STB is | |
18811 | ||
18812 | use Ada; | |
18813 | use Ada.Exceptions; | |
18814 | ||
18815 | procedure P1 is | |
18816 | K : Positive := 1; | |
18817 | begin | |
18818 | K := K - 1; | |
18819 | exception | |
18820 | when E : others => | |
18821 | Text_IO.Put_Line (Exception_Information (E)); | |
18822 | end P1; | |
18823 | ||
18824 | procedure P2 is | |
18825 | begin | |
18826 | P1; | |
18827 | end P2; | |
18828 | ||
18829 | begin | |
18830 | P2; | |
18831 | end STB; | |
88e1739c FW |
18832 | @end smallexample |
18833 | ||
18834 | @noindent | |
18835 | This program will output: | |
18836 | ||
18837 | @smallexample | |
18838 | $ stb | |
18839 | ||
18840 | Exception name: CONSTRAINT_ERROR | |
18841 | Message: stb.adb:12 | |
18842 | Call stack traceback locations: | |
18843 | 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 | |
18844 | @end smallexample | |
18845 | ||
18846 | @node Tracebacks From Anywhere in a Program (non-symbolic) | |
18847 | @subsubsection Tracebacks From Anywhere in a Program | |
18848 | ||
18849 | @noindent | |
18850 | It is also possible to retrieve a stack traceback from anywhere in a | |
18851 | program. For this you need to | |
18852 | use the @code{GNAT.Traceback} API. This package includes a procedure called | |
18853 | @code{Call_Chain} that computes a complete stack traceback, as well as useful | |
18854 | display procedures described below. It is not necessary to use the | |
7cd4527e | 18855 | @option{-E gnatbind} option in this case, because the stack traceback mechanism |
88e1739c FW |
18856 | is invoked explicitly. |
18857 | ||
18858 | @noindent | |
18859 | In the following example we compute a traceback at a specific location in | |
18860 | the program, and we display it using @code{GNAT.Debug_Utilities.Image} to | |
18861 | convert addresses to strings: | |
18862 | ||
7cd4527e | 18863 | @smallexample @c ada |
88e1739c FW |
18864 | with Ada.Text_IO; |
18865 | with GNAT.Traceback; | |
18866 | with GNAT.Debug_Utilities; | |
18867 | ||
18868 | procedure STB is | |
18869 | ||
18870 | use Ada; | |
18871 | use GNAT; | |
18872 | use GNAT.Traceback; | |
18873 | ||
18874 | procedure P1 is | |
18875 | TB : Tracebacks_Array (1 .. 10); | |
18876 | -- We are asking for a maximum of 10 stack frames. | |
18877 | Len : Natural; | |
18878 | -- Len will receive the actual number of stack frames returned. | |
18879 | begin | |
18880 | Call_Chain (TB, Len); | |
18881 | ||
18882 | Text_IO.Put ("In STB.P1 : "); | |
18883 | ||
18884 | for K in 1 .. Len loop | |
18885 | Text_IO.Put (Debug_Utilities.Image (TB (K))); | |
18886 | Text_IO.Put (' '); | |
18887 | end loop; | |
18888 | ||
18889 | Text_IO.New_Line; | |
18890 | end P1; | |
18891 | ||
18892 | procedure P2 is | |
18893 | begin | |
18894 | P1; | |
18895 | end P2; | |
18896 | ||
18897 | begin | |
18898 | P2; | |
18899 | end STB; | |
88e1739c FW |
18900 | @end smallexample |
18901 | ||
18902 | @smallexample | |
7cd4527e | 18903 | $ gnatmake -g stb |
88e1739c FW |
18904 | $ stb |
18905 | ||
18906 | In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# | |
18907 | 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# | |
18908 | @end smallexample | |
18909 | ||
7cd4527e AC |
18910 | @noindent |
18911 | You can then get further information by invoking the @code{addr2line} | |
18912 | tool as described earlier (note that the hexadecimal addresses | |
18913 | need to be specified in C format, with a leading ``0x''). | |
18914 | ||
18915 | ||
88e1739c FW |
18916 | @node Symbolic Traceback |
18917 | @subsection Symbolic Traceback | |
18918 | @cindex traceback, symbolic | |
18919 | ||
18920 | @noindent | |
18921 | A symbolic traceback is a stack traceback in which procedure names are | |
18922 | associated with each code location. | |
18923 | ||
18924 | @noindent | |
18925 | Note that this feature is not supported on all platforms. See | |
18926 | @file{GNAT.Traceback.Symbolic spec in g-trasym.ads} for a complete | |
18927 | list of currently supported platforms. | |
18928 | ||
18929 | @noindent | |
18930 | Note that the symbolic traceback requires that the program be compiled | |
18931 | with debug information. If it is not compiled with debug information | |
18932 | only the non-symbolic information will be valid. | |
18933 | ||
18934 | @menu | |
18935 | * Tracebacks From Exception Occurrences (symbolic):: | |
18936 | * Tracebacks From Anywhere in a Program (symbolic):: | |
18937 | @end menu | |
18938 | ||
18939 | @node Tracebacks From Exception Occurrences (symbolic) | |
18940 | @subsubsection Tracebacks From Exception Occurrences | |
18941 | ||
7cd4527e | 18942 | @smallexample @c ada |
88e1739c FW |
18943 | with Ada.Text_IO; |
18944 | with GNAT.Traceback.Symbolic; | |
18945 | ||
18946 | procedure STB is | |
18947 | ||
18948 | procedure P1 is | |
18949 | begin | |
18950 | raise Constraint_Error; | |
18951 | end P1; | |
18952 | ||
18953 | procedure P2 is | |
18954 | begin | |
18955 | P1; | |
18956 | end P2; | |
18957 | ||
18958 | procedure P3 is | |
18959 | begin | |
18960 | P2; | |
18961 | end P3; | |
18962 | ||
18963 | begin | |
18964 | P3; | |
18965 | exception | |
18966 | when E : others => | |
18967 | Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); | |
18968 | end STB; | |
88e1739c FW |
18969 | @end smallexample |
18970 | ||
18971 | @smallexample | |
7cd4527e | 18972 | $ gnatmake -g .\stb -bargs -E -largs -lgnat -laddr2line -lintl |
88e1739c FW |
18973 | $ stb |
18974 | ||
18975 | 0040149F in stb.p1 at stb.adb:8 | |
18976 | 004014B7 in stb.p2 at stb.adb:13 | |
18977 | 004014CF in stb.p3 at stb.adb:18 | |
18978 | 004015DD in ada.stb at stb.adb:22 | |
18979 | 00401461 in main at b~stb.adb:168 | |
18980 | 004011C4 in __mingw_CRTStartup at crt1.c:200 | |
18981 | 004011F1 in mainCRTStartup at crt1.c:222 | |
18982 | 77E892A4 in ?? at ??:0 | |
18983 | @end smallexample | |
18984 | ||
18985 | @noindent | |
7cd4527e AC |
18986 | In the above example the ``.\'' syntax in the @command{gnatmake} command |
18987 | is currently required by @command{addr2line} for files that are in | |
18988 | the current working directory. | |
18989 | Moreover, the exact sequence of linker options may vary from platform | |
18990 | to platform. | |
18991 | The above @option{-largs} section is for Windows platforms. By contrast, | |
18992 | under Unix there is no need for the @option{-largs} section. | |
88e1739c FW |
18993 | Differences across platforms are due to details of linker implementation. |
18994 | ||
18995 | @node Tracebacks From Anywhere in a Program (symbolic) | |
18996 | @subsubsection Tracebacks From Anywhere in a Program | |
18997 | ||
18998 | @noindent | |
18999 | It is possible to get a symbolic stack traceback | |
19000 | from anywhere in a program, just as for non-symbolic tracebacks. | |
19001 | The first step is to obtain a non-symbolic | |
19002 | traceback, and then call @code{Symbolic_Traceback} to compute the symbolic | |
19003 | information. Here is an example: | |
19004 | ||
7cd4527e | 19005 | @smallexample @c ada |
88e1739c FW |
19006 | with Ada.Text_IO; |
19007 | with GNAT.Traceback; | |
19008 | with GNAT.Traceback.Symbolic; | |
19009 | ||
19010 | procedure STB is | |
19011 | ||
19012 | use Ada; | |
19013 | use GNAT.Traceback; | |
19014 | use GNAT.Traceback.Symbolic; | |
19015 | ||
19016 | procedure P1 is | |
19017 | TB : Tracebacks_Array (1 .. 10); | |
19018 | -- We are asking for a maximum of 10 stack frames. | |
19019 | Len : Natural; | |
19020 | -- Len will receive the actual number of stack frames returned. | |
19021 | begin | |
19022 | Call_Chain (TB, Len); | |
19023 | Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); | |
19024 | end P1; | |
19025 | ||
19026 | procedure P2 is | |
19027 | begin | |
19028 | P1; | |
19029 | end P2; | |
19030 | ||
19031 | begin | |
19032 | P2; | |
19033 | end STB; | |
88e1739c FW |
19034 | @end smallexample |
19035 | ||
19036 | @ifset vms | |
19037 | @node Compatibility with DEC Ada | |
19038 | @chapter Compatibility with DEC Ada | |
19039 | @cindex Compatibility | |
19040 | ||
19041 | @noindent | |
19042 | This section of the manual compares DEC Ada for OpenVMS Alpha and GNAT | |
19043 | OpenVMS Alpha. GNAT achieves a high level of compatibility | |
19044 | with DEC Ada, and it should generally be straightforward to port code | |
19045 | from the DEC Ada environment to GNAT. However, there are a few language | |
19046 | and implementation differences of which the user must be aware. These | |
19047 | differences are discussed in this section. In | |
19048 | addition, the operating environment and command structure for the | |
19049 | compiler are different, and these differences are also discussed. | |
19050 | ||
19051 | Note that this discussion addresses specifically the implementation | |
19052 | of Ada 83 for DIGITAL OpenVMS Alpha Systems. In cases where the implementation | |
7cd4527e AC |
19053 | of DEC Ada differs between OpenVMS Alpha Systems and OpenVMS VAX Systems, |
19054 | GNAT always follows the Alpha implementation. | |
88e1739c FW |
19055 | |
19056 | @menu | |
19057 | * Ada 95 Compatibility:: | |
19058 | * Differences in the Definition of Package System:: | |
19059 | * Language-Related Features:: | |
19060 | * The Package STANDARD:: | |
19061 | * The Package SYSTEM:: | |
19062 | * Tasking and Task-Related Features:: | |
19063 | * Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems:: | |
19064 | * Pragmas and Pragma-Related Features:: | |
19065 | * Library of Predefined Units:: | |
19066 | * Bindings:: | |
19067 | * Main Program Definition:: | |
19068 | * Implementation-Defined Attributes:: | |
19069 | * Compiler and Run-Time Interfacing:: | |
19070 | * Program Compilation and Library Management:: | |
19071 | * Input-Output:: | |
19072 | * Implementation Limits:: | |
19073 | * Tools:: | |
19074 | @end menu | |
19075 | ||
19076 | @node Ada 95 Compatibility | |
19077 | @section Ada 95 Compatibility | |
19078 | ||
19079 | @noindent | |
19080 | GNAT is an Ada 95 compiler, and DEC Ada is an Ada 83 | |
19081 | compiler. Ada 95 is almost completely upwards compatible | |
19082 | with Ada 83, and therefore Ada 83 programs will compile | |
19083 | and run under GNAT with | |
19084 | no changes or only minor changes. The Ada 95 Reference | |
19085 | Manual (ANSI/ISO/IEC-8652:1995) provides details on specific | |
19086 | incompatibilities. | |
19087 | ||
19088 | GNAT provides the switch /83 on the GNAT COMPILE command, | |
19089 | as well as the pragma ADA_83, to force the compiler to | |
19090 | operate in Ada 83 mode. This mode does not guarantee complete | |
19091 | conformance to Ada 83, but in practice is sufficient to | |
19092 | eliminate most sources of incompatibilities. | |
19093 | In particular, it eliminates the recognition of the | |
19094 | additional Ada 95 keywords, so that their use as identifiers | |
19095 | in Ada83 program is legal, and handles the cases of packages | |
19096 | with optional bodies, and generics that instantiate unconstrained | |
19097 | types without the use of @code{(<>)}. | |
19098 | ||
19099 | @node Differences in the Definition of Package System | |
19100 | @section Differences in the Definition of Package System | |
19101 | ||
19102 | @noindent | |
19103 | Both the Ada 95 and Ada 83 reference manuals permit a compiler to add | |
19104 | implementation-dependent declarations to package System. In normal mode, | |
19105 | GNAT does not take advantage of this permission, and the version of System | |
19106 | provided by GNAT exactly matches that in the Ada 95 Reference Manual. | |
19107 | ||
19108 | However, DEC Ada adds an extensive set of declarations to package System, | |
19109 | as fully documented in the DEC Ada manuals. To minimize changes required | |
19110 | for programs that make use of these extensions, GNAT provides the pragma | |
19111 | Extend_System for extending the definition of package System. By using: | |
19112 | ||
7cd4527e | 19113 | @smallexample @c ada |
88e1739c FW |
19114 | @group |
19115 | @cartouche | |
7cd4527e | 19116 | pragma Extend_System (Aux_DEC); |
88e1739c FW |
19117 | @end cartouche |
19118 | @end group | |
19119 | @end smallexample | |
19120 | ||
19121 | @noindent | |
19122 | The set of definitions in System is extended to include those in package | |
19123 | @code{System.Aux_DEC}. | |
19124 | These definitions are incorporated directly into package | |
19125 | System, as though they had been declared there in the first place. For a | |
19126 | list of the declarations added, see the specification of this package, | |
19127 | which can be found in the file @code{s-auxdec.ads} in the GNAT library. | |
19128 | The pragma Extend_System is a configuration pragma, which means that | |
19129 | it can be placed in the file @file{gnat.adc}, so that it will automatically | |
19130 | apply to all subsequent compilations. See the section on Configuration | |
19131 | Pragmas for further details. | |
19132 | ||
19133 | An alternative approach that avoids the use of the non-standard | |
19134 | Extend_System pragma is to add a context clause to the unit that | |
19135 | references these facilities: | |
19136 | ||
7cd4527e | 19137 | @smallexample @c ada |
88e1739c FW |
19138 | @group |
19139 | @cartouche | |
7cd4527e AC |
19140 | with System.Aux_DEC; |
19141 | use System.Aux_DEC; | |
88e1739c FW |
19142 | @end cartouche |
19143 | @end group | |
19144 | @end smallexample | |
19145 | ||
19146 | @noindent | |
7cd4527e AC |
19147 | The effect is not quite semantically identical to incorporating |
19148 | the declarations directly into package @code{System}, | |
88e1739c FW |
19149 | but most programs will not notice a difference |
19150 | unless they use prefix notation (e.g. @code{System.Integer_8}) | |
19151 | to reference the | |
19152 | entities directly in package @code{System}. | |
19153 | For units containing such references, | |
19154 | the prefixes must either be removed, or the pragma @code{Extend_System} | |
19155 | must be used. | |
19156 | ||
19157 | @node Language-Related Features | |
19158 | @section Language-Related Features | |
19159 | ||
19160 | @noindent | |
19161 | The following sections highlight differences in types, | |
19162 | representations of types, operations, alignment, and | |
19163 | related topics. | |
19164 | ||
19165 | @menu | |
19166 | * Integer Types and Representations:: | |
19167 | * Floating-Point Types and Representations:: | |
19168 | * Pragmas Float_Representation and Long_Float:: | |
19169 | * Fixed-Point Types and Representations:: | |
19170 | * Record and Array Component Alignment:: | |
19171 | * Address Clauses:: | |
19172 | * Other Representation Clauses:: | |
19173 | @end menu | |
19174 | ||
19175 | @node Integer Types and Representations | |
19176 | @subsection Integer Types and Representations | |
19177 | ||
19178 | @noindent | |
19179 | The set of predefined integer types is identical in DEC Ada and GNAT. | |
19180 | Furthermore the representation of these integer types is also identical, | |
19181 | including the capability of size clauses forcing biased representation. | |
19182 | ||
19183 | In addition, | |
19184 | DEC Ada for OpenVMS Alpha systems has defined the | |
19185 | following additional integer types in package System: | |
19186 | ||
19187 | @itemize @bullet | |
19188 | ||
19189 | @item | |
19190 | INTEGER_8 | |
19191 | ||
19192 | @item | |
19193 | INTEGER_16 | |
19194 | ||
19195 | @item | |
19196 | INTEGER_32 | |
19197 | ||
19198 | @item | |
19199 | INTEGER_64 | |
19200 | ||
19201 | @item | |
19202 | LARGEST_INTEGER | |
19203 | @end itemize | |
19204 | ||
19205 | @noindent | |
19206 | When using GNAT, the first four of these types may be obtained from the | |
19207 | standard Ada 95 package @code{Interfaces}. | |
19208 | Alternatively, by use of the pragma | |
19209 | @code{Extend_System}, identical | |
19210 | declarations can be referenced directly in package @code{System}. | |
19211 | On both GNAT and DEC Ada, the maximum integer size is 64 bits. | |
19212 | ||
19213 | @node Floating-Point Types and Representations | |
19214 | @subsection Floating-Point Types and Representations | |
19215 | @cindex Floating-Point types | |
19216 | ||
19217 | @noindent | |
19218 | The set of predefined floating-point types is identical in DEC Ada and GNAT. | |
19219 | Furthermore the representation of these floating-point | |
19220 | types is also identical. One important difference is that the default | |
19221 | representation for DEC Ada is VAX_Float, but the default representation | |
19222 | for GNAT is IEEE. | |
19223 | ||
19224 | Specific types may be declared to be VAX_Float or IEEE, using the pragma | |
19225 | @code{Float_Representation} as described in the DEC Ada documentation. | |
19226 | For example, the declarations: | |
19227 | ||
7cd4527e | 19228 | @smallexample @c ada |
88e1739c FW |
19229 | @group |
19230 | @cartouche | |
7cd4527e AC |
19231 | type F_Float is digits 6; |
19232 | pragma Float_Representation (VAX_Float, F_Float); | |
88e1739c FW |
19233 | @end cartouche |
19234 | @end group | |
19235 | @end smallexample | |
19236 | ||
19237 | @noindent | |
19238 | declare a type F_Float that will be represented in VAX_Float format. | |
19239 | This set of declarations actually appears in System.Aux_DEC, which provides | |
19240 | the full set of additional floating-point declarations provided in | |
19241 | the DEC Ada version of package | |
7cd4527e AC |
19242 | System. This and similar declarations may be accessed in a user program |
19243 | by using pragma @code{Extend_System}. The use of this | |
88e1739c FW |
19244 | pragma, and the related pragma @code{Long_Float} is described in further |
19245 | detail in the following section. | |
19246 | ||
19247 | @node Pragmas Float_Representation and Long_Float | |
19248 | @subsection Pragmas Float_Representation and Long_Float | |
19249 | ||
19250 | @noindent | |
19251 | DEC Ada provides the pragma @code{Float_Representation}, which | |
19252 | acts as a program library switch to allow control over | |
19253 | the internal representation chosen for the predefined | |
19254 | floating-point types declared in the package @code{Standard}. | |
19255 | The format of this pragma is as follows: | |
19256 | ||
19257 | @smallexample | |
19258 | @group | |
19259 | @cartouche | |
19260 | @b{pragma} @code{Float_Representation}(VAX_Float | IEEE_Float); | |
19261 | @end cartouche | |
19262 | @end group | |
19263 | @end smallexample | |
19264 | ||
19265 | @noindent | |
19266 | This pragma controls the representation of floating-point | |
19267 | types as follows: | |
19268 | ||
19269 | @itemize @bullet | |
19270 | @item | |
19271 | @code{VAX_Float} specifies that floating-point | |
19272 | types are represented by default with the VAX hardware types | |
19273 | F-floating, D-floating, G-floating. Note that the H-floating | |
19274 | type is available only on DIGITAL Vax systems, and is not available | |
19275 | in either DEC Ada or GNAT for Alpha systems. | |
19276 | ||
19277 | @item | |
19278 | @code{IEEE_Float} specifies that floating-point | |
19279 | types are represented by default with the IEEE single and | |
19280 | double floating-point types. | |
19281 | @end itemize | |
19282 | ||
19283 | @noindent | |
19284 | GNAT provides an identical implementation of the pragma | |
19285 | @code{Float_Representation}, except that it functions as a | |
19286 | configuration pragma, as defined by Ada 95. Note that the | |
19287 | notion of configuration pragma corresponds closely to the | |
19288 | DEC Ada notion of a program library switch. | |
19289 | ||
19290 | When no pragma is used in GNAT, the default is IEEE_Float, which is different | |
19291 | from DEC Ada 83, where the default is VAX_Float. In addition, the | |
19292 | predefined libraries in GNAT are built using IEEE_Float, so it is not | |
19293 | advisable to change the format of numbers passed to standard library | |
19294 | routines, and if necessary explicit type conversions may be needed. | |
19295 | ||
19296 | The use of IEEE_Float is recommended in GNAT since it is more efficient, | |
19297 | and (given that it conforms to an international standard) potentially more | |
19298 | portable. The situation in which VAX_Float may be useful is in interfacing | |
19299 | to existing code and data that expects the use of VAX_Float. There are | |
19300 | two possibilities here. If the requirement for the use of VAX_Float is | |
19301 | localized, then the best approach is to use the predefined VAX_Float | |
19302 | types in package @code{System}, as extended by | |
19303 | @code{Extend_System}. For example, use @code{System.F_Float} | |
19304 | to specify the 32-bit @code{F-Float} format. | |
19305 | ||
19306 | Alternatively, if an entire program depends heavily on the use of | |
19307 | the @code{VAX_Float} and in particular assumes that the types in | |
19308 | package @code{Standard} are in @code{Vax_Float} format, then it | |
19309 | may be desirable to reconfigure GNAT to assume Vax_Float by default. | |
19310 | This is done by using the GNAT LIBRARY command to rebuild the library, and | |
19311 | then using the general form of the @code{Float_Representation} | |
19312 | pragma to ensure that this default format is used throughout. | |
19313 | The form of the GNAT LIBRARY command is: | |
19314 | ||
19315 | @smallexample | |
19316 | GNAT LIBRARY /CONFIG=@i{file} /CREATE=@i{directory} | |
19317 | @end smallexample | |
19318 | ||
19319 | @noindent | |
19320 | where @i{file} contains the new configuration pragmas | |
19321 | and @i{directory} is the directory to be created to contain | |
19322 | the new library. | |
19323 | ||
19324 | @noindent | |
19325 | On OpenVMS systems, DEC Ada provides the pragma @code{Long_Float} | |
19326 | to allow control over the internal representation chosen | |
19327 | for the predefined type @code{Long_Float} and for floating-point | |
19328 | type declarations with digits specified in the range 7 .. 15. | |
19329 | The format of this pragma is as follows: | |
19330 | ||
7cd4527e | 19331 | @smallexample @c ada |
88e1739c | 19332 | @cartouche |
7cd4527e | 19333 | pragma Long_Float (D_FLOAT | G_FLOAT); |
88e1739c FW |
19334 | @end cartouche |
19335 | @end smallexample | |
19336 | ||
19337 | @node Fixed-Point Types and Representations | |
19338 | @subsection Fixed-Point Types and Representations | |
19339 | ||
19340 | @noindent | |
19341 | On DEC Ada for OpenVMS Alpha systems, rounding is | |
19342 | away from zero for both positive and negative numbers. | |
19343 | Therefore, +0.5 rounds to 1 and -0.5 rounds to -1. | |
19344 | ||
19345 | On GNAT for OpenVMS Alpha, the results of operations | |
19346 | on fixed-point types are in accordance with the Ada 95 | |
19347 | rules. In particular, results of operations on decimal | |
19348 | fixed-point types are truncated. | |
19349 | ||
19350 | @node Record and Array Component Alignment | |
19351 | @subsection Record and Array Component Alignment | |
19352 | ||
19353 | @noindent | |
19354 | On DEC Ada for OpenVMS Alpha, all non composite components | |
19355 | are aligned on natural boundaries. For example, 1-byte | |
19356 | components are aligned on byte boundaries, 2-byte | |
19357 | components on 2-byte boundaries, 4-byte components on 4-byte | |
19358 | byte boundaries, and so on. The OpenVMS Alpha hardware | |
19359 | runs more efficiently with naturally aligned data. | |
19360 | ||
19361 | ON GNAT for OpenVMS Alpha, alignment rules are compatible | |
19362 | with DEC Ada for OpenVMS Alpha. | |
19363 | ||
19364 | @node Address Clauses | |
19365 | @subsection Address Clauses | |
19366 | ||
19367 | @noindent | |
19368 | In DEC Ada and GNAT, address clauses are supported for | |
19369 | objects and imported subprograms. | |
19370 | The predefined type @code{System.Address} is a private type | |
19371 | in both compilers, with the same representation (it is simply | |
19372 | a machine pointer). Addition, subtraction, and comparison | |
19373 | operations are available in the standard Ada 95 package | |
19374 | @code{System.Storage_Elements}, or in package @code{System} | |
19375 | if it is extended to include @code{System.Aux_DEC} using a | |
19376 | pragma @code{Extend_System} as previously described. | |
19377 | ||
19378 | Note that code that with's both this extended package @code{System} | |
19379 | and the package @code{System.Storage_Elements} should not @code{use} | |
19380 | both packages, or ambiguities will result. In general it is better | |
19381 | not to mix these two sets of facilities. The Ada 95 package was | |
19382 | designed specifically to provide the kind of features that DEC Ada | |
19383 | adds directly to package @code{System}. | |
19384 | ||
19385 | GNAT is compatible with DEC Ada in its handling of address | |
19386 | clauses, except for some limitations in | |
19387 | the form of address clauses for composite objects with | |
19388 | initialization. Such address clauses are easily replaced | |
19389 | by the use of an explicitly-defined constant as described | |
19390 | in the Ada 95 Reference Manual (13.1(22)). For example, the sequence | |
19391 | of declarations: | |
19392 | ||
7cd4527e | 19393 | @smallexample @c ada |
88e1739c FW |
19394 | @cartouche |
19395 | X, Y : Integer := Init_Func; | |
19396 | Q : String (X .. Y) := "abc"; | |
19397 | ... | |
7cd4527e | 19398 | for Q'Address use Compute_Address; |
88e1739c | 19399 | @end cartouche |
88e1739c FW |
19400 | @end smallexample |
19401 | ||
19402 | @noindent | |
19403 | will be rejected by GNAT, since the address cannot be computed at the time | |
19404 | that Q is declared. To achieve the intended effect, write instead: | |
19405 | ||
7cd4527e | 19406 | @smallexample @c ada |
88e1739c FW |
19407 | @group |
19408 | @cartouche | |
19409 | X, Y : Integer := Init_Func; | |
7cd4527e | 19410 | Q_Address : constant Address := Compute_Address; |
88e1739c FW |
19411 | Q : String (X .. Y) := "abc"; |
19412 | ... | |
7cd4527e | 19413 | for Q'Address use Q_Address; |
88e1739c FW |
19414 | @end cartouche |
19415 | @end group | |
19416 | @end smallexample | |
19417 | ||
19418 | @noindent | |
19419 | which will be accepted by GNAT (and other Ada 95 compilers), and is also | |
19420 | backwards compatible with Ada 83. A fuller description of the restrictions | |
19421 | on address specifications is found in the GNAT Reference Manual. | |
19422 | ||
19423 | @node Other Representation Clauses | |
19424 | @subsection Other Representation Clauses | |
19425 | ||
19426 | @noindent | |
19427 | GNAT supports in a compatible manner all the representation | |
19428 | clauses supported by DEC Ada. In addition, it | |
19429 | supports representation clause forms that are new in Ada 95 | |
19430 | including COMPONENT_SIZE and SIZE clauses for objects. | |
19431 | ||
19432 | @node The Package STANDARD | |
19433 | @section The Package STANDARD | |
19434 | ||
19435 | @noindent | |
19436 | The package STANDARD, as implemented by DEC Ada, is fully | |
19437 | described in the Reference Manual for the Ada Programming | |
19438 | Language (ANSI/MIL-STD-1815A-1983) and in the DEC Ada | |
19439 | Language Reference Manual. As implemented by GNAT, the | |
19440 | package STANDARD is described in the Ada 95 Reference | |
19441 | Manual. | |
19442 | ||
19443 | In addition, DEC Ada supports the Latin-1 character set in | |
19444 | the type CHARACTER. GNAT supports the Latin-1 character set | |
19445 | in the type CHARACTER and also Unicode (ISO 10646 BMP) in | |
19446 | the type WIDE_CHARACTER. | |
19447 | ||
19448 | The floating-point types supported by GNAT are those | |
19449 | supported by DEC Ada, but defaults are different, and are controlled by | |
19450 | pragmas. See @pxref{Floating-Point Types and Representations} for details. | |
19451 | ||
19452 | @node The Package SYSTEM | |
19453 | @section The Package SYSTEM | |
19454 | ||
19455 | @noindent | |
19456 | DEC Ada provides a system-specific version of the package | |
19457 | SYSTEM for each platform on which the language ships. | |
19458 | For the complete specification of the package SYSTEM, see | |
19459 | Appendix F of the DEC Ada Language Reference Manual. | |
19460 | ||
19461 | On DEC Ada, the package SYSTEM includes the following conversion functions: | |
19462 | @itemize @bullet | |
19463 | @item TO_ADDRESS(INTEGER) | |
19464 | ||
19465 | @item TO_ADDRESS(UNSIGNED_LONGWORD) | |
19466 | ||
19467 | @item TO_ADDRESS(universal_integer) | |
19468 | ||
19469 | @item TO_INTEGER(ADDRESS) | |
19470 | ||
19471 | @item TO_UNSIGNED_LONGWORD(ADDRESS) | |
19472 | ||
19473 | @item Function IMPORT_VALUE return UNSIGNED_LONGWORD and the | |
19474 | functions IMPORT_ADDRESS and IMPORT_LARGEST_VALUE | |
19475 | @end itemize | |
19476 | ||
19477 | @noindent | |
19478 | By default, GNAT supplies a version of SYSTEM that matches | |
19479 | the definition given in the Ada 95 Reference Manual. | |
19480 | This | |
19481 | is a subset of the DIGITAL system definitions, which is as | |
19482 | close as possible to the original definitions. The only difference | |
19483 | is that the definition of SYSTEM_NAME is different: | |
19484 | ||
7cd4527e | 19485 | @smallexample @c ada |
88e1739c FW |
19486 | @group |
19487 | @cartouche | |
7cd4527e AC |
19488 | type Name is (SYSTEM_NAME_GNAT); |
19489 | System_Name : constant Name := SYSTEM_NAME_GNAT; | |
88e1739c FW |
19490 | @end cartouche |
19491 | @end group | |
19492 | @end smallexample | |
19493 | ||
19494 | @noindent | |
19495 | Also, GNAT adds the new Ada 95 declarations for | |
19496 | BIT_ORDER and DEFAULT_BIT_ORDER. | |
19497 | ||
19498 | However, the use of the following pragma causes GNAT | |
19499 | to extend the definition of package SYSTEM so that it | |
19500 | encompasses the full set of DIGITAL-specific extensions, | |
19501 | including the functions listed above: | |
19502 | ||
7cd4527e | 19503 | @smallexample @c ada |
88e1739c | 19504 | @cartouche |
7cd4527e | 19505 | pragma Extend_System (Aux_DEC); |
88e1739c FW |
19506 | @end cartouche |
19507 | @end smallexample | |
19508 | ||
19509 | @noindent | |
19510 | The pragma Extend_System is a configuration pragma that | |
19511 | is most conveniently placed in the @file{gnat.adc} file. See the | |
19512 | GNAT Reference Manual for further details. | |
19513 | ||
19514 | DEC Ada does not allow the recompilation of the package | |
19515 | SYSTEM. Instead DEC Ada provides several pragmas (SYSTEM_ | |
19516 | NAME, STORAGE_UNIT, and MEMORY_SIZE) to modify values in | |
19517 | the package SYSTEM. On OpenVMS Alpha systems, the pragma | |
19518 | SYSTEM_NAME takes the enumeration literal OPENVMS_AXP as | |
19519 | its single argument. | |
19520 | ||
19521 | GNAT does permit the recompilation of package SYSTEM using | |
7cd4527e AC |
19522 | a special switch (@option{-gnatg}) and this switch can be used if |
19523 | it is necessary to modify the definitions in SYSTEM. GNAT does | |
88e1739c FW |
19524 | not permit the specification of SYSTEM_NAME, STORAGE_UNIT |
19525 | or MEMORY_SIZE by any other means. | |
19526 | ||
19527 | On GNAT systems, the pragma SYSTEM_NAME takes the | |
19528 | enumeration literal SYSTEM_NAME_GNAT. | |
19529 | ||
19530 | The definitions provided by the use of | |
19531 | ||
7cd4527e | 19532 | @smallexample @c ada |
88e1739c FW |
19533 | pragma Extend_System (AUX_Dec); |
19534 | @end smallexample | |
19535 | ||
19536 | @noindent | |
19537 | are virtually identical to those provided by the DEC Ada 83 package | |
19538 | System. One important difference is that the name of the TO_ADDRESS | |
19539 | function for type UNSIGNED_LONGWORD is changed to TO_ADDRESS_LONG. | |
19540 | See the GNAT Reference manual for a discussion of why this change was | |
19541 | necessary. | |
19542 | ||
19543 | @noindent | |
19544 | The version of TO_ADDRESS taking a universal integer argument is in fact | |
19545 | an extension to Ada 83 not strictly compatible with the reference manual. | |
19546 | In GNAT, we are constrained to be exactly compatible with the standard, | |
19547 | and this means we cannot provide this capability. In DEC Ada 83, the | |
19548 | point of this definition is to deal with a call like: | |
19549 | ||
7cd4527e | 19550 | @smallexample @c ada |
88e1739c FW |
19551 | TO_ADDRESS (16#12777#); |
19552 | @end smallexample | |
19553 | ||
19554 | @noindent | |
19555 | Normally, according to the Ada 83 standard, one would expect this to be | |
19556 | ambiguous, since it matches both the INTEGER and UNSIGNED_LONGWORD forms | |
19557 | of TO_ADDRESS. However, in DEC Ada 83, there is no ambiguity, since the | |
19558 | definition using universal_integer takes precedence. | |
19559 | ||
19560 | In GNAT, since the version with universal_integer cannot be supplied, it is | |
19561 | not possible to be 100% compatible. Since there are many programs using | |
19562 | numeric constants for the argument to TO_ADDRESS, the decision in GNAT was | |
19563 | to change the name of the function in the UNSIGNED_LONGWORD case, so the | |
19564 | declarations provided in the GNAT version of AUX_Dec are: | |
19565 | ||
7cd4527e | 19566 | @smallexample @c ada |
88e1739c FW |
19567 | function To_Address (X : Integer) return Address; |
19568 | pragma Pure_Function (To_Address); | |
19569 | ||
19570 | function To_Address_Long (X : Unsigned_Longword) return Address; | |
19571 | pragma Pure_Function (To_Address_Long); | |
19572 | @end smallexample | |
19573 | ||
19574 | @noindent | |
19575 | This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must | |
19576 | change the name to TO_ADDRESS_LONG. | |
19577 | ||
19578 | @node Tasking and Task-Related Features | |
19579 | @section Tasking and Task-Related Features | |
19580 | ||
19581 | @noindent | |
19582 | The concepts relevant to a comparison of tasking on GNAT | |
19583 | and on DEC Ada for OpenVMS Alpha systems are discussed in | |
19584 | the following sections. | |
19585 | ||
19586 | For detailed information on concepts related to tasking in | |
19587 | DEC Ada, see the DEC Ada Language Reference Manual and the | |
19588 | relevant run-time reference manual. | |
19589 | ||
19590 | @node Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems | |
19591 | @section Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems | |
19592 | ||
19593 | @noindent | |
19594 | On OpenVMS Alpha systems, each Ada task (except a passive | |
19595 | task) is implemented as a single stream of execution | |
19596 | that is created and managed by the kernel. On these | |
19597 | systems, DEC Ada tasking support is based on DECthreads, | |
19598 | an implementation of the POSIX standard for threads. | |
19599 | ||
19600 | Although tasks are implemented as threads, all tasks in | |
19601 | an Ada program are part of the same process. As a result, | |
19602 | resources such as open files and virtual memory can be | |
19603 | shared easily among tasks. Having all tasks in one process | |
19604 | allows better integration with the programming environment | |
19605 | (the shell and the debugger, for example). | |
19606 | ||
19607 | Also, on OpenVMS Alpha systems, DEC Ada tasks and foreign | |
19608 | code that calls DECthreads routines can be used together. | |
19609 | The interaction between Ada tasks and DECthreads routines | |
19610 | can have some benefits. For example when on OpenVMS Alpha, | |
19611 | DEC Ada can call C code that is already threaded. | |
19612 | GNAT on OpenVMS Alpha uses the facilities of DECthreads, | |
19613 | and Ada tasks are mapped to threads. | |
19614 | ||
19615 | @menu | |
19616 | * Assigning Task IDs:: | |
19617 | * Task IDs and Delays:: | |
19618 | * Task-Related Pragmas:: | |
19619 | * Scheduling and Task Priority:: | |
19620 | * The Task Stack:: | |
19621 | * External Interrupts:: | |
19622 | @end menu | |
19623 | ||
19624 | @node Assigning Task IDs | |
19625 | @subsection Assigning Task IDs | |
19626 | ||
19627 | @noindent | |
19628 | The DEC Ada Run-Time Library always assigns %TASK 1 to | |
19629 | the environment task that executes the main program. On | |
19630 | OpenVMS Alpha systems, %TASK 0 is often used for tasks | |
19631 | that have been created but are not yet activated. | |
19632 | ||
19633 | On OpenVMS Alpha systems, task IDs are assigned at | |
19634 | activation. On GNAT systems, task IDs are also assigned at | |
19635 | task creation but do not have the same form or values as | |
19636 | task ID values in DEC Ada. There is no null task, and the | |
19637 | environment task does not have a specific task ID value. | |
19638 | ||
19639 | @node Task IDs and Delays | |
19640 | @subsection Task IDs and Delays | |
19641 | ||
19642 | @noindent | |
19643 | On OpenVMS Alpha systems, tasking delays are implemented | |
19644 | using Timer System Services. The Task ID is used for the | |
19645 | identification of the timer request (the REQIDT parameter). | |
19646 | If Timers are used in the application take care not to use | |
19647 | 0 for the identification, because cancelling such a timer | |
19648 | will cancel all timers and may lead to unpredictable results. | |
19649 | ||
19650 | @node Task-Related Pragmas | |
19651 | @subsection Task-Related Pragmas | |
19652 | ||
19653 | @noindent | |
19654 | Ada supplies the pragma TASK_STORAGE, which allows | |
19655 | specification of the size of the guard area for a task | |
19656 | stack. (The guard area forms an area of memory that has no | |
19657 | read or write access and thus helps in the detection of | |
19658 | stack overflow.) On OpenVMS Alpha systems, if the pragma | |
19659 | TASK_STORAGE specifies a value of zero, a minimal guard | |
19660 | area is created. In the absence of a pragma TASK_STORAGE, a default guard | |
19661 | area is created. | |
19662 | ||
19663 | GNAT supplies the following task-related pragmas: | |
19664 | ||
19665 | @itemize @bullet | |
19666 | @item TASK_INFO | |
19667 | ||
19668 | This pragma appears within a task definition and | |
19669 | applies to the task in which it appears. The argument | |
19670 | must be of type SYSTEM.TASK_INFO.TASK_INFO_TYPE. | |
19671 | ||
19672 | @item TASK_STORAGE | |
19673 | ||
19674 | GNAT implements pragma TASK_STORAGE in the same way as | |
19675 | DEC Ada. | |
19676 | Both DEC Ada and GNAT supply the pragmas PASSIVE, | |
19677 | SUPPRESS, and VOLATILE. | |
19678 | @end itemize | |
19679 | @node Scheduling and Task Priority | |
19680 | @subsection Scheduling and Task Priority | |
19681 | ||
19682 | @noindent | |
19683 | DEC Ada implements the Ada language requirement that | |
19684 | when two tasks are eligible for execution and they have | |
19685 | different priorities, the lower priority task does not | |
19686 | execute while the higher priority task is waiting. The DEC | |
19687 | Ada Run-Time Library keeps a task running until either the | |
19688 | task is suspended or a higher priority task becomes ready. | |
19689 | ||
19690 | On OpenVMS Alpha systems, the default strategy is round- | |
19691 | robin with preemption. Tasks of equal priority take turns | |
19692 | at the processor. A task is run for a certain period of | |
19693 | time and then placed at the rear of the ready queue for | |
19694 | its priority level. | |
19695 | ||
19696 | DEC Ada provides the implementation-defined pragma TIME_SLICE, | |
19697 | which can be used to enable or disable round-robin | |
19698 | scheduling of tasks with the same priority. | |
19699 | See the relevant DEC Ada run-time reference manual for | |
19700 | information on using the pragmas to control DEC Ada task | |
19701 | scheduling. | |
19702 | ||
19703 | GNAT follows the scheduling rules of Annex D (real-time | |
19704 | Annex) of the Ada 95 Reference Manual. In general, this | |
19705 | scheduling strategy is fully compatible with DEC Ada | |
19706 | although it provides some additional constraints (as | |
19707 | fully documented in Annex D). | |
19708 | GNAT implements time slicing control in a manner compatible with | |
19709 | DEC Ada 83, by means of the pragma Time_Slice, whose semantics are identical | |
19710 | to the DEC Ada 83 pragma of the same name. | |
19711 | Note that it is not possible to mix GNAT tasking and | |
19712 | DEC Ada 83 tasking in the same program, since the two run times are | |
19713 | not compatible. | |
19714 | ||
19715 | @node The Task Stack | |
19716 | @subsection The Task Stack | |
19717 | ||
19718 | @noindent | |
19719 | In DEC Ada, a task stack is allocated each time a | |
19720 | non passive task is activated. As soon as the task is | |
19721 | terminated, the storage for the task stack is deallocated. | |
19722 | If you specify a size of zero (bytes) with T'STORAGE_SIZE, | |
19723 | a default stack size is used. Also, regardless of the size | |
19724 | specified, some additional space is allocated for task | |
19725 | management purposes. On OpenVMS Alpha systems, at least | |
19726 | one page is allocated. | |
19727 | ||
19728 | GNAT handles task stacks in a similar manner. According to | |
19729 | the Ada 95 rules, it provides the pragma STORAGE_SIZE as | |
19730 | an alternative method for controlling the task stack size. | |
19731 | The specification of the attribute T'STORAGE_SIZE is also | |
19732 | supported in a manner compatible with DEC Ada. | |
19733 | ||
19734 | @node External Interrupts | |
19735 | @subsection External Interrupts | |
19736 | ||
19737 | @noindent | |
19738 | On DEC Ada, external interrupts can be associated with task entries. | |
19739 | GNAT is compatible with DEC Ada in its handling of external interrupts. | |
19740 | ||
19741 | @node Pragmas and Pragma-Related Features | |
19742 | @section Pragmas and Pragma-Related Features | |
19743 | ||
19744 | @noindent | |
19745 | Both DEC Ada and GNAT supply all language-defined pragmas | |
19746 | as specified by the Ada 83 standard. GNAT also supplies all | |
19747 | language-defined pragmas specified in the Ada 95 Reference Manual. | |
19748 | In addition, GNAT implements the implementation-defined pragmas | |
19749 | from DEC Ada 83. | |
19750 | ||
19751 | @itemize @bullet | |
19752 | @item AST_ENTRY | |
19753 | ||
19754 | @item COMMON_OBJECT | |
19755 | ||
19756 | @item COMPONENT_ALIGNMENT | |
19757 | ||
19758 | @item EXPORT_EXCEPTION | |
19759 | ||
19760 | @item EXPORT_FUNCTION | |
19761 | ||
19762 | @item EXPORT_OBJECT | |
19763 | ||
19764 | @item EXPORT_PROCEDURE | |
19765 | ||
19766 | @item EXPORT_VALUED_PROCEDURE | |
19767 | ||
19768 | @item FLOAT_REPRESENTATION | |
19769 | ||
19770 | @item IDENT | |
19771 | ||
19772 | @item IMPORT_EXCEPTION | |
19773 | ||
19774 | @item IMPORT_FUNCTION | |
19775 | ||
19776 | @item IMPORT_OBJECT | |
19777 | ||
19778 | @item IMPORT_PROCEDURE | |
19779 | ||
19780 | @item IMPORT_VALUED_PROCEDURE | |
19781 | ||
19782 | @item INLINE_GENERIC | |
19783 | ||
19784 | @item INTERFACE_NAME | |
19785 | ||
19786 | @item LONG_FLOAT | |
19787 | ||
19788 | @item MAIN_STORAGE | |
19789 | ||
19790 | @item PASSIVE | |
19791 | ||
19792 | @item PSET_OBJECT | |
19793 | ||
19794 | @item SHARE_GENERIC | |
19795 | ||
19796 | @item SUPPRESS_ALL | |
19797 | ||
19798 | @item TASK_STORAGE | |
19799 | ||
19800 | @item TIME_SLICE | |
19801 | ||
19802 | @item TITLE | |
19803 | @end itemize | |
19804 | ||
19805 | @noindent | |
19806 | These pragmas are all fully implemented, with the exception of @code{Title}, | |
19807 | @code{Passive}, and @code{Share_Generic}, which are | |
19808 | recognized, but which have no | |
19809 | effect in GNAT. The effect of @code{Passive} may be obtained by the | |
19810 | use of protected objects in Ada 95. In GNAT, all generics are inlined. | |
19811 | ||
19812 | Unlike DEC Ada, the GNAT 'EXPORT_@i{subprogram}' pragmas require | |
19813 | a separate subprogram specification which must appear before the | |
19814 | subprogram body. | |
19815 | ||
19816 | GNAT also supplies a number of implementation-defined pragmas as follows: | |
19817 | @itemize @bullet | |
19818 | @item C_PASS_BY_COPY | |
19819 | ||
19820 | @item EXTEND_SYSTEM | |
19821 | ||
19822 | @item SOURCE_FILE_NAME | |
19823 | ||
19824 | @item UNSUPPRESS | |
19825 | ||
19826 | @item WARNINGS | |
19827 | ||
19828 | @item ABORT_DEFER | |
19829 | ||
19830 | @item ADA_83 | |
19831 | ||
19832 | @item ADA_95 | |
19833 | ||
19834 | @item ANNOTATE | |
19835 | ||
19836 | @item ASSERT | |
19837 | ||
19838 | @item CPP_CLASS | |
19839 | ||
19840 | @item CPP_CONSTRUCTOR | |
19841 | ||
19842 | @item CPP_DESTRUCTOR | |
19843 | ||
19844 | @item CPP_VIRTUAL | |
19845 | ||
19846 | @item CP_VTABLE | |
19847 | ||
19848 | @item DEBUG | |
19849 | ||
19850 | @item LINKER_ALIAS | |
19851 | ||
19852 | @item LINKER_SECTION | |
19853 | ||
19854 | @item MACHINE_ATTRIBUTE | |
19855 | ||
19856 | @item NO_RETURN | |
19857 | ||
19858 | @item PURE_FUNCTION | |
19859 | ||
19860 | @item SOURCE_REFERENCE | |
19861 | ||
19862 | @item TASK_INFO | |
19863 | ||
19864 | @item UNCHECKED_UNION | |
19865 | ||
19866 | @item UNIMPLEMENTED_UNIT | |
19867 | ||
7cd4527e AC |
19868 | @item UNIVERSAL_DATA |
19869 | ||
88e1739c FW |
19870 | @item WEAK_EXTERNAL |
19871 | @end itemize | |
19872 | ||
19873 | @noindent | |
19874 | For full details on these GNAT implementation-defined pragmas, see | |
19875 | the GNAT Reference Manual. | |
19876 | ||
19877 | @menu | |
19878 | * Restrictions on the Pragma INLINE:: | |
19879 | * Restrictions on the Pragma INTERFACE:: | |
19880 | * Restrictions on the Pragma SYSTEM_NAME:: | |
19881 | @end menu | |
19882 | ||
19883 | @node Restrictions on the Pragma INLINE | |
19884 | @subsection Restrictions on the Pragma INLINE | |
19885 | ||
19886 | @noindent | |
19887 | DEC Ada applies the following restrictions to the pragma INLINE: | |
19888 | @itemize @bullet | |
19889 | @item Parameters cannot be a task type. | |
19890 | ||
19891 | @item Function results cannot be task types, unconstrained | |
19892 | array types, or unconstrained types with discriminants. | |
19893 | ||
19894 | @item Bodies cannot declare the following: | |
19895 | @itemize @bullet | |
19896 | @item Subprogram body or stub (imported subprogram is allowed) | |
19897 | ||
19898 | @item Tasks | |
19899 | ||
19900 | @item Generic declarations | |
19901 | ||
19902 | @item Instantiations | |
19903 | ||
19904 | @item Exceptions | |
19905 | ||
19906 | @item Access types (types derived from access types allowed) | |
19907 | ||
19908 | @item Array or record types | |
19909 | ||
19910 | @item Dependent tasks | |
19911 | ||
19912 | @item Direct recursive calls of subprogram or containing | |
19913 | subprogram, directly or via a renaming | |
19914 | ||
19915 | @end itemize | |
19916 | @end itemize | |
19917 | ||
19918 | @noindent | |
19919 | In GNAT, the only restriction on pragma INLINE is that the | |
19920 | body must occur before the call if both are in the same | |
19921 | unit, and the size must be appropriately small. There are | |
19922 | no other specific restrictions which cause subprograms to | |
19923 | be incapable of being inlined. | |
19924 | ||
19925 | @node Restrictions on the Pragma INTERFACE | |
19926 | @subsection Restrictions on the Pragma INTERFACE | |
19927 | ||
19928 | @noindent | |
19929 | The following lists and describes the restrictions on the | |
19930 | pragma INTERFACE on DEC Ada and GNAT: | |
19931 | @itemize @bullet | |
19932 | @item Languages accepted: Ada, Bliss, C, Fortran, Default. | |
19933 | Default is the default on OpenVMS Alpha systems. | |
19934 | ||
19935 | @item Parameter passing: Language specifies default | |
19936 | mechanisms but can be overridden with an EXPORT pragma. | |
19937 | ||
19938 | @itemize @bullet | |
19939 | @item Ada: Use internal Ada rules. | |
19940 | ||
19941 | @item Bliss, C: Parameters must be mode @code{in}; cannot be | |
19942 | record or task type. Result cannot be a string, an | |
19943 | array, or a record. | |
19944 | ||
19945 | @item Fortran: Parameters cannot be a task. Result cannot | |
19946 | be a string, an array, or a record. | |
19947 | @end itemize | |
19948 | @end itemize | |
19949 | ||
19950 | @noindent | |
19951 | GNAT is entirely upwards compatible with DEC Ada, and in addition allows | |
19952 | record parameters for all languages. | |
19953 | ||
19954 | @node Restrictions on the Pragma SYSTEM_NAME | |
19955 | @subsection Restrictions on the Pragma SYSTEM_NAME | |
19956 | ||
19957 | @noindent | |
19958 | For DEC Ada for OpenVMS Alpha, the enumeration literal | |
19959 | for the type NAME is OPENVMS_AXP. In GNAT, the enumeration | |
19960 | literal for the type NAME is SYSTEM_NAME_GNAT. | |
19961 | ||
19962 | @node Library of Predefined Units | |
19963 | @section Library of Predefined Units | |
19964 | ||
19965 | @noindent | |
19966 | A library of predefined units is provided as part of the | |
19967 | DEC Ada and GNAT implementations. DEC Ada does not provide | |
19968 | the package MACHINE_CODE but instead recommends importing | |
19969 | assembler code. | |
19970 | ||
19971 | The GNAT versions of the DEC Ada Run-Time Library (ADA$PREDEFINED:) | |
19972 | units are taken from the OpenVMS Alpha version, not the OpenVMS VAX | |
19973 | version. During GNAT installation, the DEC Ada Predefined | |
19974 | Library units are copied into the GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] | |
19975 | (aka DECLIB) directory and patched to remove Ada 95 incompatibilities | |
19976 | and to make them interoperable with GNAT, @pxref{Changes to DECLIB} | |
19977 | for details. | |
19978 | ||
19979 | The GNAT RTL is contained in | |
19980 | the GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB] (aka ADALIB) directory and | |
19981 | the default search path is set up to find DECLIB units in preference | |
19982 | to ADALIB units with the same name (TEXT_IO, SEQUENTIAL_IO, and DIRECT_IO, | |
19983 | for example). | |
19984 | ||
19985 | However, it is possible to change the default so that the | |
19986 | reverse is true, or even to mix them using child package | |
19987 | notation. The DEC Ada 83 units are available as DEC.xxx where xxx | |
19988 | is the package name, and the Ada units are available in the | |
19989 | standard manner defined for Ada 95, that is to say as Ada.xxx. To | |
19990 | change the default, set ADA_INCLUDE_PATH and ADA_OBJECTS_PATH | |
19991 | appropriately. For example, to change the default to use the Ada95 | |
19992 | versions do: | |
19993 | ||
19994 | @smallexample | |
19995 | $ DEFINE ADA_INCLUDE_PATH GNU:[LIB.OPENVMS7_1.2_8_1.ADAINCLUDE],- | |
19996 | GNU:[LIB.OPENVMS7_1.2_8_1.DECLIB] | |
19997 | $ DEFINE ADA_OBJECTS_PATH GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB],- | |
19998 | GNU:[LIB.OPENVMS7_1.2_8_1.DECLIB] | |
19999 | @end smallexample | |
20000 | ||
20001 | @menu | |
20002 | * Changes to DECLIB:: | |
20003 | @end menu | |
20004 | ||
20005 | @node Changes to DECLIB | |
20006 | @subsection Changes to DECLIB | |
20007 | ||
20008 | @noindent | |
20009 | The changes made to the DEC Ada predefined library for GNAT and Ada 95 | |
20010 | compatibility are minor and include the following: | |
20011 | ||
20012 | @itemize @bullet | |
20013 | @item Adjusting the location of pragmas and record representation | |
20014 | clauses to obey Ada 95 rules | |
20015 | ||
20016 | @item Adding the proper notation to generic formal parameters | |
20017 | that take unconstrained types in instantiation | |
20018 | ||
20019 | @item Adding pragma ELABORATE_BODY to package specifications | |
20020 | that have package bodies not otherwise allowed | |
20021 | ||
7cd4527e AC |
20022 | @item Occurrences of the identifier @code{"PROTECTED"} are renamed to |
20023 | @code{"PROTECTD"}. | |
88e1739c FW |
20024 | Currently these are found only in the STARLET package spec. |
20025 | @end itemize | |
20026 | ||
20027 | @noindent | |
20028 | None of the above changes is visible to users. | |
20029 | ||
20030 | @node Bindings | |
20031 | @section Bindings | |
20032 | ||
20033 | @noindent | |
20034 | On OpenVMS Alpha, DEC Ada provides the following strongly-typed bindings: | |
20035 | @itemize @bullet | |
20036 | ||
20037 | @item Command Language Interpreter (CLI interface) | |
20038 | ||
20039 | @item DECtalk Run-Time Library (DTK interface) | |
20040 | ||
20041 | @item Librarian utility routines (LBR interface) | |
20042 | ||
20043 | @item General Purpose Run-Time Library (LIB interface) | |
20044 | ||
20045 | @item Math Run-Time Library (MTH interface) | |
20046 | ||
20047 | @item National Character Set Run-Time Library (NCS interface) | |
20048 | ||
20049 | @item Compiled Code Support Run-Time Library (OTS interface) | |
20050 | ||
20051 | @item Parallel Processing Run-Time Library (PPL interface) | |
20052 | ||
20053 | @item Screen Management Run-Time Library (SMG interface) | |
20054 | ||
20055 | @item Sort Run-Time Library (SOR interface) | |
20056 | ||
20057 | @item String Run-Time Library (STR interface) | |
20058 | ||
20059 | @item STARLET System Library | |
20060 | @findex Starlet | |
20061 | ||
20062 | @item X Window System Version 11R4 and 11R5 (X, XLIB interface) | |
20063 | ||
20064 | @item X Windows Toolkit (XT interface) | |
20065 | ||
20066 | @item X/Motif Version 1.1.3 and 1.2 (XM interface) | |
20067 | @end itemize | |
20068 | ||
20069 | @noindent | |
20070 | GNAT provides implementations of these DEC bindings in the DECLIB directory. | |
20071 | ||
20072 | The X/Motif bindings used to build DECLIB are whatever versions are in the | |
7cd4527e AC |
20073 | DEC Ada @file{ADA$PREDEFINED} directory with extension @file{.ADC}. |
20074 | The build script will | |
20075 | automatically add a pragma Linker_Options to packages @code{Xm}, @code{Xt}, | |
20076 | and @code{X_Lib} | |
20077 | causing the default X/Motif sharable image libraries to be linked in. This | |
20078 | is done via options files named @file{xm.opt}, @file{xt.opt}, and | |
20079 | @file{x_lib.opt} (also located in the @file{DECLIB} directory). | |
88e1739c FW |
20080 | |
20081 | It may be necessary to edit these options files to update or correct the | |
7cd4527e AC |
20082 | library names if, for example, the newer X/Motif bindings from |
20083 | @file{ADA$EXAMPLES} | |
20084 | had been (previous to installing GNAT) copied and renamed to supersede the | |
20085 | default @file{ADA$PREDEFINED} versions. | |
88e1739c FW |
20086 | |
20087 | @menu | |
20088 | * Shared Libraries and Options Files:: | |
20089 | * Interfaces to C:: | |
20090 | @end menu | |
20091 | ||
20092 | @node Shared Libraries and Options Files | |
20093 | @subsection Shared Libraries and Options Files | |
20094 | ||
20095 | @noindent | |
20096 | When using the DEC Ada | |
7cd4527e AC |
20097 | predefined X and Motif bindings, the linking with their sharable images is |
20098 | done automatically by @command{GNAT LINK}. | |
20099 | When using other X and Motif bindings, you need | |
20100 | to add the corresponding sharable images to the command line for | |
20101 | @code{GNAT LINK}. When linking with shared libraries, or with | |
20102 | @file{.OPT} files, you must | |
20103 | also add them to the command line for @command{GNAT LINK}. | |
88e1739c FW |
20104 | |
20105 | A shared library to be used with GNAT is built in the same way as other | |
20106 | libraries under VMS. The VMS Link command can be used in standard fashion. | |
20107 | ||
20108 | @node Interfaces to C | |
20109 | @subsection Interfaces to C | |
20110 | ||
20111 | @noindent | |
20112 | DEC Ada | |
20113 | provides the following Ada types and operations: | |
20114 | ||
20115 | @itemize @bullet | |
20116 | @item C types package (C_TYPES) | |
20117 | ||
20118 | @item C strings (C_TYPES.NULL_TERMINATED) | |
20119 | ||
20120 | @item Other_types (SHORT_INT) | |
20121 | @end itemize | |
20122 | ||
20123 | @noindent | |
20124 | Interfacing to C with GNAT, one can use the above approach | |
20125 | described for DEC Ada or the facilities of Annex B of | |
20126 | the Ada 95 Reference Manual (packages INTERFACES.C, | |
20127 | INTERFACES.C.STRINGS and INTERFACES.C.POINTERS). For more | |
7cd4527e AC |
20128 | information, see the section ``Interfacing to C'' in the |
20129 | @cite{GNAT Reference Manual}. | |
88e1739c FW |
20130 | |
20131 | The @option{-gnatF} qualifier forces default and explicit | |
20132 | @code{External_Name} parameters in pragmas Import and Export | |
20133 | to be uppercased for compatibility with the default behavior | |
7cd4527e | 20134 | of Compaq C. The qualifier has no effect on @code{Link_Name} parameters. |
88e1739c FW |
20135 | |
20136 | @node Main Program Definition | |
20137 | @section Main Program Definition | |
20138 | ||
20139 | @noindent | |
20140 | The following section discusses differences in the | |
20141 | definition of main programs on DEC Ada and GNAT. | |
20142 | On DEC Ada, main programs are defined to meet the | |
20143 | following conditions: | |
20144 | @itemize @bullet | |
20145 | @item Procedure with no formal parameters (returns 0 upon | |
20146 | normal completion) | |
20147 | ||
20148 | @item Procedure with no formal parameters (returns 42 when | |
20149 | unhandled exceptions are raised) | |
20150 | ||
20151 | @item Function with no formal parameters whose returned value | |
20152 | is of a discrete type | |
20153 | ||
20154 | @item Procedure with one OUT formal of a discrete type for | |
20155 | which a specification of pragma EXPORT_VALUED_PROCEDURE is given. | |
20156 | ||
20157 | @end itemize | |
20158 | ||
20159 | @noindent | |
20160 | When declared with the pragma EXPORT_VALUED_PROCEDURE, | |
20161 | a main function or main procedure returns a discrete | |
20162 | value whose size is less than 64 bits (32 on VAX systems), | |
20163 | the value is zero- or sign-extended as appropriate. | |
20164 | On GNAT, main programs are defined as follows: | |
20165 | @itemize @bullet | |
20166 | @item Must be a non-generic, parameter-less subprogram that | |
20167 | is either a procedure or function returning an Ada | |
20168 | STANDARD.INTEGER (the predefined type) | |
20169 | ||
20170 | @item Cannot be a generic subprogram or an instantiation of a | |
20171 | generic subprogram | |
20172 | @end itemize | |
20173 | ||
20174 | @node Implementation-Defined Attributes | |
20175 | @section Implementation-Defined Attributes | |
20176 | ||
20177 | @noindent | |
20178 | GNAT provides all DEC Ada implementation-defined | |
20179 | attributes. | |
20180 | ||
20181 | @node Compiler and Run-Time Interfacing | |
20182 | @section Compiler and Run-Time Interfacing | |
20183 | ||
20184 | @noindent | |
7cd4527e AC |
20185 | DEC Ada provides the following ways to pass options to the linker |
20186 | (ACS LINK): | |
88e1739c FW |
20187 | @itemize @bullet |
20188 | @item /WAIT and /SUBMIT qualifiers | |
20189 | ||
20190 | @item /COMMAND qualifier | |
20191 | ||
20192 | @item /[NO]MAP qualifier | |
20193 | ||
20194 | @item /OUTPUT=file-spec | |
20195 | ||
20196 | @item /[NO]DEBUG and /[NO]TRACEBACK qualifiers | |
20197 | @end itemize | |
20198 | ||
20199 | @noindent | |
20200 | To pass options to the linker, GNAT provides the following | |
20201 | switches: | |
20202 | ||
20203 | @itemize @bullet | |
7cd4527e | 20204 | @item @option{/EXECUTABLE=exec-name} |
88e1739c | 20205 | |
7cd4527e | 20206 | @item @option{/VERBOSE qualifier} |
88e1739c | 20207 | |
7cd4527e | 20208 | @item @option{/[NO]DEBUG} and @option{/[NO]TRACEBACK} qualifiers |
88e1739c FW |
20209 | @end itemize |
20210 | ||
20211 | @noindent | |
7cd4527e AC |
20212 | For more information on these switches, see |
20213 | @ref{Switches for gnatlink}. | |
20214 | In DEC Ada, the command-line switch @option{/OPTIMIZE} is available | |
88e1739c FW |
20215 | to control optimization. DEC Ada also supplies the |
20216 | following pragmas: | |
20217 | @itemize @bullet | |
7cd4527e | 20218 | @item @code{OPTIMIZE} |
88e1739c | 20219 | |
7cd4527e | 20220 | @item @code{INLINE} |
88e1739c | 20221 | |
7cd4527e | 20222 | @item @code{INLINE_GENERIC} |
88e1739c | 20223 | |
7cd4527e | 20224 | @item @code{SUPPRESS_ALL} |
88e1739c | 20225 | |
7cd4527e | 20226 | @item @code{PASSIVE} |
88e1739c FW |
20227 | @end itemize |
20228 | ||
20229 | @noindent | |
20230 | In GNAT, optimization is controlled strictly by command | |
20231 | line parameters, as described in the corresponding section of this guide. | |
20232 | The DIGITAL pragmas for control of optimization are | |
20233 | recognized but ignored. | |
20234 | ||
20235 | Note that in GNAT, the default is optimization off, whereas in DEC Ada 83, | |
20236 | the default is that optimization is turned on. | |
20237 | ||
20238 | @node Program Compilation and Library Management | |
20239 | @section Program Compilation and Library Management | |
20240 | ||
20241 | @noindent | |
20242 | DEC Ada and GNAT provide a comparable set of commands to | |
20243 | build programs. DEC Ada also provides a program library, | |
20244 | which is a concept that does not exist on GNAT. Instead, | |
20245 | GNAT provides directories of sources that are compiled as | |
20246 | needed. | |
20247 | ||
20248 | The following table summarizes | |
20249 | the DEC Ada commands and provides | |
20250 | equivalent GNAT commands. In this table, some GNAT | |
20251 | equivalents reflect the fact that GNAT does not use the | |
20252 | concept of a program library. Instead, it uses a model | |
20253 | in which collections of source and object files are used | |
20254 | in a manner consistent with other languages like C and | |
20255 | Fortran. Therefore, standard system file commands are used | |
20256 | to manipulate these elements. Those GNAT commands are marked with | |
7cd4527e AC |
20257 | an asterisk. |
20258 | Note that, unlike DEC Ada, none of the GNAT commands accepts wild cards. | |
88e1739c FW |
20259 | |
20260 | @need 1500 | |
7cd4527e AC |
20261 | @multitable @columnfractions .35 .65 |
20262 | ||
20263 | @item @emph{DEC Ada Command} | |
20264 | @tab @emph{GNAT Equivalent / Description} | |
20265 | ||
20266 | @item @command{ADA} | |
20267 | @tab @command{GNAT COMPILE}@* | |
20268 | Invokes the compiler to compile one or more Ada source files. | |
20269 | ||
20270 | @item @command{ACS ATTACH}@* | |
20271 | @tab [No equivalent]@* | |
20272 | Switches control of terminal from current process running the program | |
20273 | library manager. | |
20274 | ||
20275 | @item @command{ACS CHECK} | |
20276 | @tab @command{GNAT MAKE /DEPENDENCY_LIST}@* | |
20277 | Forms the execution closure of one | |
20278 | or more compiled units and checks completeness and currency. | |
20279 | ||
20280 | @item @command{ACS COMPILE} | |
20281 | @tab @command{GNAT MAKE /ACTIONS=COMPILE}@* | |
20282 | Forms the execution closure of one or | |
20283 | more specified units, checks completeness and currency, | |
20284 | identifies units that have revised source files, compiles same, | |
20285 | and recompiles units that are or will become obsolete. | |
20286 | Also completes incomplete generic instantiations. | |
20287 | ||
20288 | @item @command{ACS COPY FOREIGN} | |
20289 | @tab Copy (*)@* | |
20290 | Copies a foreign object file into the program library as a | |
20291 | library unit body. | |
20292 | ||
20293 | @item @command{ACS COPY UNIT} | |
20294 | @tab Copy (*)@* | |
20295 | Copies a compiled unit from one program library to another. | |
20296 | ||
20297 | @item @command{ACS CREATE LIBRARY} | |
20298 | @tab Create /directory (*)@* | |
20299 | Creates a program library. | |
20300 | ||
20301 | @item @command{ACS CREATE SUBLIBRARY} | |
20302 | @tab Create /directory (*)@* | |
20303 | Creates a program sublibrary. | |
20304 | ||
20305 | @item @command{ACS DELETE LIBRARY} | |
20306 | @tab @* | |
20307 | Deletes a program library and its contents. | |
20308 | ||
20309 | @item @command{ACS DELETE SUBLIBRARY} | |
20310 | @tab @* | |
20311 | Deletes a program sublibrary and its contents. | |
20312 | ||
20313 | @item @command{ACS DELETE UNIT} | |
20314 | @tab Delete file (*)@* | |
20315 | On OpenVMS systems, deletes one or more compiled units from | |
20316 | the current program library. | |
20317 | ||
20318 | @item @command{ACS DIRECTORY} | |
20319 | @tab Directory (*)@* | |
20320 | On OpenVMS systems, lists units contained in the current | |
20321 | program library. | |
20322 | ||
20323 | @item @command{ACS ENTER FOREIGN} | |
20324 | @tab Copy (*)@* | |
20325 | Allows the import of a foreign body as an Ada library | |
20326 | specification and enters a reference to a pointer. | |
20327 | ||
20328 | @item @command{ACS ENTER UNIT} | |
20329 | @tab Copy (*)@* | |
20330 | Enters a reference (pointer) from the current program library to | |
20331 | a unit compiled into another program library. | |
20332 | ||
20333 | @item @command{ACS EXIT} | |
20334 | @tab [No equivalent]@* | |
20335 | Exits from the program library manager. | |
20336 | ||
20337 | @item @command{ACS EXPORT} | |
20338 | @tab Copy (*)@* | |
20339 | Creates an object file that contains system-specific object code | |
20340 | for one or more units. With GNAT, object files can simply be copied | |
20341 | into the desired directory. | |
20342 | ||
20343 | @item @command{ACS EXTRACT SOURCE} | |
20344 | @tab Copy (*)@* | |
20345 | Allows access to the copied source file for each Ada compilation unit | |
20346 | ||
20347 | @item @command{ACS HELP} | |
20348 | @tab @command{HELP GNAT}@* | |
20349 | Provides online help. | |
20350 | ||
20351 | @item @command{ACS LINK} | |
20352 | @tab @command{GNAT LINK}@* | |
20353 | Links an object file containing Ada units into an executable file. | |
20354 | ||
20355 | @item @command{ACS LOAD} | |
20356 | @tab Copy (*)@* | |
20357 | Loads (partially compiles) Ada units into the program library. | |
20358 | Allows loading a program from a collection of files into a library | |
20359 | without knowing the relationship among units. | |
20360 | ||
20361 | @item @command{ACS MERGE} | |
20362 | @tab Copy (*)@* | |
20363 | Merges into the current program library, one or more units from | |
20364 | another library where they were modified. | |
20365 | ||
20366 | @item @command{ACS RECOMPILE} | |
20367 | @tab @command{GNAT MAKE /ACTIONS=COMPILE}@* | |
20368 | Recompiles from external or copied source files any obsolete | |
20369 | unit in the closure. Also, completes any incomplete generic | |
20370 | instantiations. | |
20371 | ||
20372 | @item @command{ACS REENTER} | |
20373 | @tab @command{GNAT MAKE}@* | |
20374 | Reenters current references to units compiled after last entered | |
20375 | with the @command{ACS ENTER UNIT} command. | |
20376 | ||
20377 | @item @command{ACS SET LIBRARY} | |
20378 | @tab Set default (*)@* | |
20379 | Defines a program library to be the compilation context as well | |
20380 | as the target library for compiler output and commands in general. | |
20381 | ||
20382 | @item @command{ACS SET PRAGMA} | |
20383 | @tab Edit @file{gnat.adc} (*)@* | |
20384 | Redefines specified values of the library characteristics | |
20385 | @code{LONG_ FLOAT}, @code{MEMORY_SIZE}, @code{SYSTEM_NAME}, | |
20386 | and @code{Float_Representation}. | |
20387 | ||
20388 | @item @command{ACS SET SOURCE} | |
20389 | @tab Define @code{ADA_INCLUDE_PATH} path (*)@* | |
20390 | Defines the source file search list for the @command{ACS COMPILE} command. | |
20391 | ||
20392 | @item @command{ACS SHOW LIBRARY} | |
20393 | @tab Directory (*)@* | |
20394 | Lists information about one or more program libraries. | |
20395 | ||
20396 | @item @command{ACS SHOW PROGRAM} | |
20397 | @tab [No equivalent]@* | |
20398 | Lists information about the execution closure of one or | |
20399 | more units in the program library. | |
20400 | ||
20401 | @item @command{ACS SHOW SOURCE} | |
20402 | @tab Show logical @code{ADA_INCLUDE_PATH}@* | |
20403 | Shows the source file search used when compiling units. | |
20404 | ||
20405 | @item @command{ACS SHOW VERSION} | |
20406 | @tab Compile with @option{VERBOSE} option | |
20407 | Displays the version number of the compiler and program library | |
20408 | manager used. | |
20409 | ||
20410 | @item @command{ACS SPAWN} | |
20411 | @tab [No equivalent]@* | |
20412 | Creates a subprocess of the current process (same as @command{DCL SPAWN} | |
20413 | command). | |
20414 | ||
20415 | @item @command{ACS VERIFY} | |
20416 | @tab [No equivalent]@* | |
20417 | Performs a series of consistency checks on a program library to | |
20418 | determine whether the library structure and library files are in | |
20419 | valid form. | |
88e1739c FW |
20420 | @end multitable |
20421 | ||
20422 | @noindent | |
20423 | ||
20424 | @node Input-Output | |
20425 | @section Input-Output | |
20426 | ||
20427 | @noindent | |
20428 | On OpenVMS Alpha systems, DEC Ada uses OpenVMS Record | |
20429 | Management Services (RMS) to perform operations on | |
20430 | external files. | |
20431 | ||
20432 | @noindent | |
20433 | DEC Ada and GNAT predefine an identical set of input- | |
20434 | output packages. To make the use of the | |
20435 | generic TEXT_IO operations more convenient, DEC Ada | |
20436 | provides predefined library packages that instantiate the | |
20437 | integer and floating-point operations for the predefined | |
20438 | integer and floating-point types as shown in the following table. | |
20439 | ||
7cd4527e AC |
20440 | @multitable @columnfractions .45 .55 |
20441 | @item @emph{Package Name} @tab Instantiation | |
88e1739c | 20442 | |
7cd4527e AC |
20443 | @item @code{INTEGER_TEXT_IO} |
20444 | @tab @code{INTEGER_IO(INTEGER)} | |
88e1739c | 20445 | |
7cd4527e AC |
20446 | @item @code{SHORT_INTEGER_TEXT_IO} |
20447 | @tab @code{INTEGER_IO(SHORT_INTEGER)} | |
88e1739c | 20448 | |
7cd4527e AC |
20449 | @item @code{SHORT_SHORT_INTEGER_TEXT_IO} |
20450 | @tab @code{INTEGER_IO(SHORT_SHORT_INTEGER)} | |
88e1739c | 20451 | |
7cd4527e AC |
20452 | @item @code{FLOAT_TEXT_IO} |
20453 | @tab @code{FLOAT_IO(FLOAT)} | |
88e1739c | 20454 | |
7cd4527e AC |
20455 | @item @code{LONG_FLOAT_TEXT_IO} |
20456 | @tab @code{FLOAT_IO(LONG_FLOAT)} | |
20457 | @end multitable | |
88e1739c FW |
20458 | |
20459 | @noindent | |
20460 | The DEC Ada predefined packages and their operations | |
20461 | are implemented using OpenVMS Alpha files and input- | |
20462 | output facilities. DEC Ada supports asynchronous input- | |
20463 | output on OpenVMS Alpha. Familiarity with the following is | |
20464 | recommended: | |
20465 | @itemize @bullet | |
20466 | @item RMS file organizations and access methods | |
20467 | ||
20468 | @item OpenVMS file specifications and directories | |
20469 | ||
20470 | @item OpenVMS File Definition Language (FDL) | |
20471 | @end itemize | |
20472 | ||
20473 | @noindent | |
20474 | GNAT provides I/O facilities that are completely | |
20475 | compatible with DEC Ada. The distribution includes the | |
20476 | standard DEC Ada versions of all I/O packages, operating | |
20477 | in a manner compatible with DEC Ada. In particular, the | |
20478 | following packages are by default the DEC Ada (Ada 83) | |
20479 | versions of these packages rather than the renamings | |
20480 | suggested in annex J of the Ada 95 Reference Manual: | |
20481 | @itemize @bullet | |
7cd4527e | 20482 | @item @code{TEXT_IO} |
88e1739c | 20483 | |
7cd4527e | 20484 | @item @code{SEQUENTIAL_IO} |
88e1739c | 20485 | |
7cd4527e | 20486 | @item @code{DIRECT_IO} |
88e1739c FW |
20487 | @end itemize |
20488 | ||
20489 | @noindent | |
20490 | The use of the standard Ada 95 syntax for child packages (for | |
7cd4527e | 20491 | example, @code{ADA.TEXT_IO}) retrieves the Ada 95 versions of these |
88e1739c FW |
20492 | packages, as defined in the Ada 95 Reference Manual. |
20493 | GNAT provides DIGITAL-compatible predefined instantiations | |
7cd4527e | 20494 | of the @code{TEXT_IO} packages, and also |
88e1739c FW |
20495 | provides the standard predefined instantiations required |
20496 | by the Ada 95 Reference Manual. | |
20497 | ||
20498 | For further information on how GNAT interfaces to the file | |
20499 | system or how I/O is implemented in programs written in | |
7cd4527e AC |
20500 | mixed languages, see the chapter ``Implementation of the |
20501 | Standard I/O'' in the @cite{GNAT Reference Manual}. | |
88e1739c FW |
20502 | This chapter covers the following: |
20503 | @itemize @bullet | |
20504 | @item Standard I/O packages | |
20505 | ||
7cd4527e | 20506 | @item @code{FORM} strings |
88e1739c | 20507 | |
7cd4527e | 20508 | @item @code{ADA.DIRECT_IO} |
88e1739c | 20509 | |
7cd4527e | 20510 | @item @code{ADA.SEQUENTIAL_IO} |
88e1739c | 20511 | |
7cd4527e | 20512 | @item @code{ADA.TEXT_IO} |
88e1739c FW |
20513 | |
20514 | @item Stream pointer positioning | |
20515 | ||
20516 | @item Reading and writing non-regular files | |
20517 | ||
7cd4527e | 20518 | @item @code{GET_IMMEDIATE} |
88e1739c | 20519 | |
7cd4527e | 20520 | @item Treating @code{TEXT_IO} files as streams |
88e1739c FW |
20521 | |
20522 | @item Shared files | |
20523 | ||
20524 | @item Open modes | |
20525 | @end itemize | |
20526 | ||
20527 | @node Implementation Limits | |
20528 | @section Implementation Limits | |
20529 | ||
20530 | @noindent | |
7cd4527e AC |
20531 | The following table lists implementation limits for DEC Ada |
20532 | and GNAT systems. | |
88e1739c | 20533 | @multitable @columnfractions .60 .20 .20 |
7cd4527e AC |
20534 | @sp 1 |
20535 | @item @emph{Compilation Parameter} | |
20536 | @tab @emph{DEC Ada} | |
20537 | @tab @emph{GNAT} | |
20538 | @sp 1 | |
88e1739c FW |
20539 | |
20540 | @item In a subprogram or entry declaration, maximum number of | |
20541 | formal parameters that are of an unconstrained record type | |
20542 | @tab 32 | |
20543 | @tab No set limit | |
7cd4527e | 20544 | @sp 1 |
88e1739c FW |
20545 | |
20546 | @item Maximum identifier length (number of characters) | |
20547 | @tab 255 | |
20548 | @tab 255 | |
7cd4527e AC |
20549 | @sp 1 |
20550 | ||
20551 | @item Maximum number of characters in a source line | |
20552 | @tab 255 | |
20553 | @tab 255 | |
20554 | @sp 1 | |
20555 | ||
20556 | @item Maximum collection size (number of bytes) | |
20557 | @tab 2**31-1 | |
20558 | @tab 2**31-1 | |
20559 | @sp 1 | |
20560 | ||
20561 | @item Maximum number of discriminants for a record type | |
20562 | @tab 245 | |
20563 | @tab No set limit | |
20564 | @sp 1 | |
20565 | ||
20566 | @item Maximum number of formal parameters in an entry or | |
20567 | subprogram declaration | |
20568 | @tab 246 | |
20569 | @tab No set limit | |
20570 | @sp 1 | |
20571 | ||
20572 | @item Maximum number of dimensions in an array type | |
20573 | @tab 255 | |
20574 | @tab No set limit | |
20575 | @sp 1 | |
20576 | ||
20577 | @item Maximum number of library units and subunits in a compilation. | |
20578 | @tab 4095 | |
20579 | @tab No set limit | |
20580 | @sp 1 | |
20581 | ||
20582 | @item Maximum number of library units and subunits in an execution. | |
20583 | @tab 16383 | |
20584 | @tab No set limit | |
20585 | @sp 1 | |
20586 | ||
20587 | @item Maximum number of objects declared with the pragma @code{COMMON_OBJECT} | |
20588 | or @code{PSECT_OBJECT} | |
20589 | @tab 32757 | |
20590 | @tab No set limit | |
20591 | @sp 1 | |
20592 | ||
20593 | @item Maximum number of enumeration literals in an enumeration type | |
20594 | definition | |
20595 | @tab 65535 | |
20596 | @tab No set limit | |
20597 | @sp 1 | |
20598 | ||
20599 | @item Maximum number of lines in a source file | |
20600 | @tab 65534 | |
20601 | @tab No set limit | |
20602 | @sp 1 | |
20603 | ||
20604 | @item Maximum number of bits in any object | |
20605 | @tab 2**31-1 | |
20606 | @tab 2**31-1 | |
20607 | @sp 1 | |
20608 | ||
20609 | @item Maximum size of the static portion of a stack frame (approximate) | |
20610 | @tab 2**31-1 | |
20611 | @tab 2**31-1 | |
20612 | @end multitable | |
20613 | ||
20614 | @node Tools | |
20615 | @section Tools | |
20616 | ||
20617 | @end ifset | |
20618 | ||
20619 | ||
20620 | @c ************************************** | |
20621 | @node Platform-Specific Information for the Run-Time Libraries | |
20622 | @appendix Platform-Specific Information for the Run-Time Libraries | |
20623 | @cindex Tasking and threads libraries | |
20624 | @cindex Threads libraries and tasking | |
20625 | @cindex Run-time libraries (platform-specific information) | |
20626 | ||
20627 | @noindent | |
20628 | The GNAT run-time implementation | |
20629 | may vary with respect to both the underlying threads library and | |
20630 | the exception handling scheme. | |
20631 | For threads support, one or more of the following are supplied: | |
20632 | @itemize @bullet | |
20633 | @item @b{native threads library}, a binding to the thread package from | |
20634 | the underlying operating system | |
20635 | ||
20636 | @item @b{FSU threads library}, a binding to the Florida State University | |
20637 | threads implementation, which complies fully with the requirements of Annex D | |
20638 | ||
20639 | @item @b{pthreads library} (Sparc Solaris only), a binding to the Solaris | |
20640 | POSIX thread package | |
20641 | @end itemize | |
20642 | ||
20643 | @noindent | |
20644 | For exception handling, either or both of two models are supplied: | |
20645 | @itemize @bullet | |
20646 | @item @b{Zero-Cost Exceptions} (``ZCX''),@footnote{ | |
20647 | Most programs should experience a substantial speed improvement by | |
20648 | being compiled with a ZCX run-time. | |
20649 | This is especially true for | |
20650 | tasking applications or applications with many exception handlers.} | |
20651 | @cindex Zero-Cost Exceptions | |
20652 | @cindex ZCX (Zero-Cost Exceptions) | |
20653 | which uses binder-generated tables that | |
20654 | are interrogated at run time to locate a handler | |
20655 | ||
20656 | @item @b{setjmp / longjmp} (``SJLJ''), | |
20657 | @cindex setjmp/longjmp Exception Model | |
20658 | @cindex SJLJ (setjmp/longjmp Exception Model) | |
20659 | which uses dynamically-set data to establish | |
20660 | the set of handlers | |
20661 | @end itemize | |
20662 | ||
20663 | @noindent | |
20664 | This appendix summarizes which combinations of threads and exception support | |
20665 | are supplied on various GNAT platforms. | |
20666 | It then shows how to select a particular library either | |
20667 | permanently or temporarily, | |
20668 | explains the properties of (and tradeoffs among) the various threads | |
20669 | libraries, and provides some additional | |
20670 | information about several specific platforms. | |
20671 | ||
20672 | @menu | |
20673 | * Summary of Run-Time Configurations:: | |
20674 | * Specifying a Run-Time Library:: | |
20675 | * Choosing between Native and FSU Threads Libraries:: | |
20676 | * Choosing the Scheduling Policy:: | |
20677 | * Solaris-Specific Considerations:: | |
20678 | * IRIX-Specific Considerations:: | |
20679 | * Linux-Specific Considerations:: | |
20680 | @end menu | |
20681 | ||
20682 | ||
20683 | @node Summary of Run-Time Configurations | |
20684 | @section Summary of Run-Time Configurations | |
20685 | ||
20686 | ||
20687 | @multitable @columnfractions .30 .70 | |
20688 | @item @b{alpha-openvms} | |
20689 | @item @code{@ @ }@i{rts-native (default)} | |
20690 | @item @code{@ @ @ @ }Tasking @tab native VMS threads | |
20691 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
20692 | @* | |
20693 | @item @b{pa-hpux} | |
20694 | @item @code{@ @ }@i{rts-native (default)} | |
20695 | @item @code{@ @ @ @ }Tasking @tab native HP threads library | |
20696 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
20697 | @* | |
20698 | @item @code{@ @ }@i{rts-sjlj} | |
20699 | @item @code{@ @ @ @ }Tasking @tab native HP threads library | |
20700 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
20701 | @* | |
20702 | @item @b{sparc-solaris} @tab | |
20703 | @item @code{@ @ }@i{rts-native (default)} | |
20704 | @item @code{@ @ @ @ }Tasking @tab native Solaris threads library | |
20705 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
20706 | @* | |
20707 | @item @code{@ @ }@i{rts-fsu} @tab | |
20708 | @item @code{@ @ @ @ }Tasking @tab FSU threads library | |
20709 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
20710 | @* | |
20711 | @item @code{@ @ }@i{rts-m64} | |
20712 | @item @code{@ @ @ @ }Tasking @tab native Solaris threads library | |
20713 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
20714 | @item @code{@ @ @ @ }Constraints @tab Use only when compiling in 64-bit mode; | |
20715 | @item @tab Use only on Solaris 8 or later. | |
20716 | @item @tab @xref{Building and Debugging 64-bit Applications}, for details. | |
20717 | @* | |
20718 | @item @code{@ @ }@i{rts-pthread} | |
20719 | @item @code{@ @ @ @ }Tasking @tab pthreads library | |
20720 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
20721 | @* | |
20722 | @item @code{@ @ }@i{rts-sjlj} | |
20723 | @item @code{@ @ @ @ }Tasking @tab native Solaris threads library | |
20724 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
20725 | @* | |
20726 | @item @b{x86-linux} | |
20727 | @item @code{@ @ }@i{rts-native (default)} | |
20728 | @item @code{@ @ @ @ }Tasking @tab LinuxThread library | |
20729 | @item @code{@ @ @ @ }Exceptions @tab ZCX | |
20730 | @* | |
20731 | @item @code{@ @ }@i{rts-fsu} | |
20732 | @item @code{@ @ @ @ }Tasking @tab FSU threads library | |
20733 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
20734 | @* | |
20735 | @item @code{@ @ }@i{rts-sjlj} | |
20736 | @item @code{@ @ @ @ }Tasking @tab LinuxThread library | |
20737 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
20738 | @* | |
20739 | @item @b{x86-windows} | |
20740 | @item @code{@ @ }@i{rts-native (default)} | |
20741 | @item @code{@ @ @ @ }Tasking @tab native Win32 threads | |
20742 | @item @code{@ @ @ @ }Exceptions @tab SJLJ | |
20743 | @* | |
20744 | @end multitable | |
20745 | ||
20746 | ||
20747 | ||
20748 | @node Specifying a Run-Time Library | |
20749 | @section Specifying a Run-Time Library | |
20750 | ||
20751 | @noindent | |
20752 | The @file{adainclude} subdirectory containing the sources of the GNAT | |
20753 | run-time library, and the @file{adalib} subdirectory containing the | |
20754 | @file{ALI} files and the static and/or shared GNAT library, are located | |
20755 | in the gcc target-dependent area: | |
20756 | ||
20757 | @smallexample | |
20758 | target=$prefix/lib/gcc-lib/gcc-@i{dumpmachine}/gcc-@i{dumpversion}/ | |
20759 | @end smallexample | |
20760 | ||
20761 | @noindent | |
20762 | As indicated above, on some platforms several run-time libraries are supplied. | |
20763 | These libraries are installed in the target dependent area and | |
20764 | contain a complete source and binary subdirectory. The detailed description | |
20765 | below explains the differences between the different libraries in terms of | |
20766 | their thread support. | |
20767 | ||
20768 | The default run-time library (when GNAT is installed) is @emph{rts-native}. | |
20769 | This default run time is selected by the means of soft links. | |
20770 | For example on x86-linux: | |
20771 | ||
20772 | @smallexample | |
20773 | @group | |
20774 | $(target-dir) | |
20775 | | | |
20776 | +--- adainclude----------+ | |
20777 | | | | |
20778 | +--- adalib-----------+ | | |
20779 | | | | | |
20780 | +--- rts-native | | | |
20781 | | | | | | |
20782 | | +--- adainclude <---+ | |
20783 | | | | | |
20784 | | +--- adalib <----+ | |
20785 | | | |
20786 | +--- rts-fsu | |
20787 | | | | |
20788 | | +--- adainclude | |
20789 | | | | |
20790 | | +--- adalib | |
20791 | | | |
20792 | +--- rts-sjlj | |
20793 | | | |
20794 | +--- adainclude | |
20795 | | | |
20796 | +--- adalib | |
20797 | @end group | |
20798 | @end smallexample | |
20799 | ||
20800 | @noindent | |
20801 | If the @i{rts-fsu} library is to be selected on a permanent basis, | |
20802 | these soft links can be modified with the following commands: | |
20803 | ||
20804 | @smallexample | |
20805 | $ cd $target | |
20806 | $ rm -f adainclude adalib | |
20807 | $ ln -s rts-fsu/adainclude adainclude | |
20808 | $ ln -s rts-fsu/adalib adalib | |
20809 | @end smallexample | |
20810 | ||
20811 | @noindent | |
20812 | Alternatively, you can specify @file{rts-fsu/adainclude} in the file | |
20813 | @file{$target/ada_source_path} and @file{rts-fsu/adalib} in | |
20814 | @file{$target/ada_object_path}. | |
20815 | ||
20816 | Selecting another run-time library temporarily can be | |
20817 | achieved by the regular mechanism for GNAT object or source path selection: | |
20818 | ||
20819 | @itemize @bullet | |
20820 | @item | |
20821 | Set the environment variables: | |
20822 | ||
20823 | @smallexample | |
20824 | $ ADA_INCLUDE_PATH=$target/rts-fsu/adainclude:$ADA_INCLUDE_PATH | |
20825 | $ ADA_OBJECTS_PATH=$target/rts-fsu/adalib:$ADA_OBJECTS_PATH | |
20826 | $ export ADA_INCLUDE_PATH ADA_OBJECTS_PATH | |
20827 | @end smallexample | |
20828 | ||
20829 | @item | |
20830 | Use @option{-aI$target/rts-fsu/adainclude} | |
20831 | and @option{-aO$target/rts-fsu/adalib} | |
20832 | on the @command{gnatmake} command line | |
20833 | ||
20834 | @item | |
20835 | Use the switch @option{--RTS}; e.g., @option{--RTS=fsu} | |
20836 | @cindex @option{--RTS} option | |
20837 | @end itemize | |
20838 | ||
20839 | @noindent | |
20840 | You can similarly switch to @emph{rts-sjlj}. | |
20841 | ||
20842 | @node Choosing between Native and FSU Threads Libraries | |
20843 | @section Choosing between Native and FSU Threads Libraries | |
20844 | @cindex Native threads library | |
20845 | @cindex FSU threads library | |
20846 | ||
20847 | @noindent | |
20848 | Some GNAT implementations offer a choice between | |
20849 | native threads and FSU threads. | |
20850 | ||
20851 | @itemize @bullet | |
20852 | @item | |
20853 | The @emph{native threads} library correspond to the standard system threads | |
20854 | implementation (e.g. LinuxThreads on GNU/Linux, | |
20855 | @cindex LinuxThreads library | |
20856 | POSIX threads on AIX, or | |
20857 | Solaris threads on Solaris). When this option is chosen, GNAT provides | |
20858 | a full and accurate implementation of the core language tasking model | |
20859 | as described in Chapter 9 of the Ada Reference Manual, | |
20860 | but might not (and probably does not) implement | |
20861 | the exact semantics as specified in @w{Annex D} (the Real-Time Systems Annex). | |
20862 | @cindex Annex D (Real-Time Systems Annex) compliance | |
20863 | @cindex Real-Time Systems Annex compliance | |
20864 | Indeed, the reason that a choice of libraries is offered | |
20865 | on a given target is because some of the | |
20866 | ACATS tests for @w{Annex D} fail using the native threads library. | |
20867 | As far as possible, this library is implemented | |
20868 | in accordance with Ada semantics (e.g., modifying priorities as required | |
20869 | to simulate ceiling locking), | |
20870 | but there are often slight inaccuracies, most often in the area of | |
20871 | absolutely respecting the priority rules on a single | |
20872 | processor. | |
20873 | Moreover, it is not possible in general to define the exact behavior, | |
20874 | because the native threads implementations | |
20875 | are not well enough documented. | |
20876 | ||
20877 | On systems where the @code{SCHED_FIFO} POSIX scheduling policy is supported, | |
20878 | @cindex POSIX scheduling policies | |
20879 | @cindex @code{SCHED_FIFO} scheduling policy | |
20880 | native threads will provide a behavior very close to the @w{Annex D} | |
20881 | requirements (i.e., a run-till-blocked scheduler with fixed priorities), but | |
20882 | on some systems (in particular GNU/Linux and Solaris), you need to have root | |
20883 | privileges to use the @code{SCHED_FIFO} policy. | |
20884 | ||
20885 | @item | |
20886 | The @emph{FSU threads} library provides a completely accurate implementation | |
20887 | of @w{Annex D}. | |
20888 | Thus, operating with this library, GNAT is 100% compliant with both the core | |
20889 | and all @w{Annex D} | |
20890 | requirements. | |
20891 | The formal validations for implementations offering | |
20892 | a choice of threads packages are always carried out using the FSU | |
20893 | threads option. | |
20894 | @end itemize | |
20895 | ||
20896 | @noindent | |
20897 | From these considerations, it might seem that FSU threads are the | |
20898 | better choice, | |
20899 | but that is by no means always the case. The FSU threads package | |
20900 | operates with all Ada tasks appearing to the system to be a single | |
20901 | thread. This is often considerably more efficient than operating | |
20902 | with separate threads, since for example, switching between tasks | |
20903 | can be accomplished without the (in some cases considerable) | |
20904 | overhead of a context switch between two system threads. However, | |
20905 | it means that you may well lose concurrency at the system | |
20906 | level. Notably, some system operations (such as I/O) may block all | |
20907 | tasks in a program and not just the calling task. More | |
20908 | significantly, the FSU threads approach likely means you cannot | |
20909 | take advantage of multiple processors, since for this you need | |
20910 | separate threads (or even separate processes) to operate on | |
20911 | different processors. | |
20912 | ||
20913 | For most programs, the native threads library is | |
20914 | usually the better choice. Use the FSU threads if absolute | |
20915 | conformance to @w{Annex D} is important for your application, or if | |
20916 | you find that the improved efficiency of FSU threads is significant to you. | |
20917 | ||
20918 | Note also that to take full advantage of Florist and Glade, it is highly | |
20919 | recommended that you use native threads. | |
20920 | ||
20921 | ||
20922 | @node Choosing the Scheduling Policy | |
20923 | @section Choosing the Scheduling Policy | |
20924 | ||
20925 | @noindent | |
20926 | When using a POSIX threads implementation, you have a choice of several | |
20927 | scheduling policies: @code{SCHED_FIFO}, | |
20928 | @cindex @code{SCHED_FIFO} scheduling policy | |
20929 | @code{SCHED_RR} | |
20930 | @cindex @code{SCHED_RR} scheduling policy | |
20931 | and @code{SCHED_OTHER}. | |
20932 | @cindex @code{SCHED_OTHER} scheduling policy | |
20933 | Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO} | |
20934 | or @code{SCHED_RR} requires special (e.g., root) privileges. | |
20935 | ||
20936 | By default, GNAT uses the @code{SCHED_OTHER} policy. To specify | |
20937 | @code{SCHED_FIFO}, | |
20938 | @cindex @code{SCHED_FIFO} scheduling policy | |
20939 | you can use one of the following: | |
20940 | ||
20941 | @itemize @bullet | |
20942 | @item | |
20943 | @code{pragma Time_Slice (0.0)} | |
20944 | @cindex pragma Time_Slice | |
20945 | @item | |
20946 | the corresponding binder option @option{-T0} | |
20947 | @cindex @option{-T0} option | |
20948 | @item | |
20949 | @code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} | |
20950 | @cindex pragma Task_Dispatching_Policy | |
20951 | @end itemize | |
20952 | ||
20953 | @noindent | |
20954 | To specify @code{SCHED_RR}, | |
20955 | @cindex @code{SCHED_RR} scheduling policy | |
20956 | you should use @code{pragma Time_Slice} with a | |
20957 | value greater than @code{0.0}, or else use the corresponding @option{-T} | |
20958 | binder option. | |
20959 | ||
20960 | ||
20961 | ||
20962 | @node Solaris-Specific Considerations | |
20963 | @section Solaris-Specific Considerations | |
20964 | @cindex Solaris Sparc threads libraries | |
20965 | ||
20966 | @noindent | |
20967 | This section addresses some topics related to the various threads libraries | |
20968 | on Sparc Solaris and then provides some information on building and | |
20969 | debugging 64-bit applications. | |
20970 | ||
20971 | @menu | |
20972 | * Solaris Threads Issues:: | |
20973 | * Building and Debugging 64-bit Applications:: | |
20974 | @end menu | |
20975 | ||
20976 | ||
20977 | @node Solaris Threads Issues | |
20978 | @subsection Solaris Threads Issues | |
20979 | ||
20980 | @noindent | |
20981 | Starting with version 3.14, GNAT under Solaris comes with a new tasking | |
20982 | run-time library based on POSIX threads --- @emph{rts-pthread}. | |
20983 | @cindex rts-pthread threads library | |
20984 | This run-time library has the advantage of being mostly shared across all | |
20985 | POSIX-compliant thread implementations, and it also provides under | |
20986 | @w{Solaris 8} the @code{PTHREAD_PRIO_INHERIT} | |
20987 | @cindex @code{PTHREAD_PRIO_INHERIT} policy (under rts-pthread) | |
20988 | and @code{PTHREAD_PRIO_PROTECT} | |
20989 | @cindex @code{PTHREAD_PRIO_PROTECT} policy (under rts-pthread) | |
20990 | semantics that can be selected using the predefined pragma | |
20991 | @code{Locking_Policy} | |
20992 | @cindex pragma Locking_Policy (under rts-pthread) | |
20993 | with respectively | |
20994 | @code{Inheritance_Locking} and @code{Ceiling_Locking} as the policy. | |
20995 | @cindex @code{Inheritance_Locking} (under rts-pthread) | |
20996 | @cindex @code{Ceiling_Locking} (under rts-pthread) | |
20997 | ||
20998 | As explained above, the native run-time library is based on the Solaris thread | |
20999 | library (@code{libthread}) and is the default library. | |
21000 | The FSU run-time library is based on the FSU threads. | |
21001 | @cindex FSU threads library | |
21002 | ||
21003 | Starting with Solaris 2.5.1, when the Solaris threads library is used | |
21004 | (this is the default), programs | |
21005 | compiled with GNAT can automatically take advantage of | |
21006 | and can thus execute on multiple processors. | |
21007 | The user can alternatively specify a processor on which the program should run | |
21008 | to emulate a single-processor system. The multiprocessor / uniprocessor choice | |
21009 | is made by | |
21010 | setting the environment variable @code{GNAT_PROCESSOR} | |
21011 | @cindex @code{GNAT_PROCESSOR} environment variable (on Sparc Solaris) | |
21012 | to one of the following: | |
21013 | ||
21014 | @table @code | |
21015 | @item -2 | |
21016 | Use the default configuration (run the program on all | |
21017 | available processors) - this is the same as having | |
21018 | @code{GNAT_PROCESSOR} unset | |
21019 | ||
21020 | @item -1 | |
21021 | Let the run-time implementation choose one processor and run the program on | |
21022 | that processor | |
21023 | ||
21024 | @item 0 .. Last_Proc | |
21025 | Run the program on the specified processor. | |
21026 | @code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1} | |
21027 | (where @code{_SC_NPROCESSORS_CONF} is a system variable). | |
21028 | @end table | |
21029 | ||
21030 | ||
21031 | @node Building and Debugging 64-bit Applications | |
21032 | @subsection Building and Debugging 64-bit Applications | |
21033 | ||
21034 | @noindent | |
21035 | In a 64-bit application, all the sources involved must be compiled with the | |
21036 | @option{-m64} command-line option, and a specific GNAT library (compiled with | |
21037 | this option) is required. | |
21038 | The easiest way to build a 64bit application is to add | |
21039 | @option{-m64 --RTS=m64} to the @command{gnatmake} flags. | |
21040 | ||
21041 | To debug these applications, dwarf-2 debug information is required, so you | |
21042 | have to add @option{-gdwarf-2} to your gnatmake arguments. | |
21043 | In addition, a special | |
21044 | version of gdb, called @command{gdb64}, needs to be used. | |
21045 | ||
21046 | To summarize, building and debugging a ``Hello World'' program in 64-bit mode | |
21047 | amounts to: | |
21048 | ||
21049 | @smallexample | |
21050 | $ gnatmake -m64 -gdwarf-2 --RTS=m64 hello.adb | |
21051 | $ gdb64 hello | |
21052 | @end smallexample | |
21053 | ||
21054 | ||
21055 | ||
21056 | @node IRIX-Specific Considerations | |
21057 | @section IRIX-Specific Considerations | |
21058 | @cindex IRIX thread library | |
21059 | ||
21060 | @noindent | |
21061 | On SGI IRIX, the thread library depends on which compiler is used. | |
21062 | The @emph{o32 ABI} compiler comes with a run-time library based on the | |
21063 | user-level @code{athread} | |
21064 | library. Thus kernel-level capabilities such as nonblocking system | |
21065 | calls or time slicing can only be achieved reliably by specifying different | |
21066 | @code{sprocs} via the pragma @code{Task_Info} | |
21067 | @cindex pragma Task_Info (and IRIX threads) | |
21068 | and the | |
21069 | @code{System.Task_Info} package. | |
21070 | @cindex @code{System.Task_Info} package (and IRIX threads) | |
21071 | See the @cite{GNAT Reference Manual} for further information. | |
21072 | ||
21073 | The @emph{n32 ABI} compiler comes with a run-time library based on the | |
21074 | kernel POSIX threads and thus does not have the limitations mentioned above. | |
21075 | ||
21076 | ||
21077 | @node Linux-Specific Considerations | |
21078 | @section Linux-Specific Considerations | |
21079 | @cindex Linux threads libraries | |
21080 | ||
21081 | @noindent | |
21082 | The default thread library under GNU/Linux has the following disadvantages | |
21083 | compared to other native thread libraries: | |
21084 | ||
21085 | @itemize @bullet | |
21086 | @item The size of the task's stack is limited to 2 megabytes. | |
21087 | @item The signal model is not POSIX compliant, which means that to send a | |
21088 | signal to the process, you need to send the signal to all threads, | |
21089 | e.g. by using @code{killpg()}. | |
21090 | @end itemize | |
21091 | ||
21092 | ||
21093 | ||
21094 | @c ******************************* | |
21095 | @node Example of Binder Output File | |
21096 | @appendix Example of Binder Output File | |
21097 | ||
21098 | @noindent | |
21099 | This Appendix displays the source code for @command{gnatbind}'s output | |
21100 | file generated for a simple ``Hello World'' program. | |
21101 | Comments have been added for clarification purposes. | |
21102 | ||
21103 | ||
21104 | @smallexample @c adanocomment | |
21105 | @iftex | |
21106 | @leftskip=0cm | |
21107 | @end iftex | |
21108 | -- The package is called Ada_Main unless this name is actually used | |
21109 | -- as a unit name in the partition, in which case some other unique | |
21110 | -- name is used. | |
21111 | ||
21112 | with System; | |
21113 | package ada_main is | |
21114 | ||
21115 | Elab_Final_Code : Integer; | |
21116 | pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code"); | |
21117 | ||
21118 | -- The main program saves the parameters (argument count, | |
21119 | -- argument values, environment pointer) in global variables | |
21120 | -- for later access by other units including | |
21121 | -- Ada.Command_Line. | |
21122 | ||
21123 | gnat_argc : Integer; | |
21124 | gnat_argv : System.Address; | |
21125 | gnat_envp : System.Address; | |
21126 | ||
21127 | -- The actual variables are stored in a library routine. This | |
21128 | -- is useful for some shared library situations, where there | |
21129 | -- are problems if variables are not in the library. | |
21130 | ||
21131 | pragma Import (C, gnat_argc); | |
21132 | pragma Import (C, gnat_argv); | |
21133 | pragma Import (C, gnat_envp); | |
21134 | ||
21135 | -- The exit status is similarly an external location | |
21136 | ||
21137 | gnat_exit_status : Integer; | |
21138 | pragma Import (C, gnat_exit_status); | |
21139 | ||
21140 | GNAT_Version : constant String := | |
21141 | "GNAT Version: 3.15w (20010315)"; | |
21142 | pragma Export (C, GNAT_Version, "__gnat_version"); | |
21143 | ||
21144 | -- This is the generated adafinal routine that performs | |
21145 | -- finalization at the end of execution. In the case where | |
21146 | -- Ada is the main program, this main program makes a call | |
21147 | -- to adafinal at program termination. | |
21148 | ||
21149 | procedure adafinal; | |
21150 | pragma Export (C, adafinal, "adafinal"); | |
21151 | ||
21152 | -- This is the generated adainit routine that performs | |
21153 | -- initialization at the start of execution. In the case | |
21154 | -- where Ada is the main program, this main program makes | |
21155 | -- a call to adainit at program startup. | |
21156 | ||
21157 | procedure adainit; | |
21158 | pragma Export (C, adainit, "adainit"); | |
21159 | ||
21160 | -- This routine is called at the start of execution. It is | |
21161 | -- a dummy routine that is used by the debugger to breakpoint | |
21162 | -- at the start of execution. | |
21163 | ||
21164 | procedure Break_Start; | |
21165 | pragma Import (C, Break_Start, "__gnat_break_start"); | |
21166 | ||
21167 | -- This is the actual generated main program (it would be | |
21168 | -- suppressed if the no main program switch were used). As | |
21169 | -- required by standard system conventions, this program has | |
21170 | -- the external name main. | |
21171 | ||
21172 | function main | |
21173 | (argc : Integer; | |
21174 | argv : System.Address; | |
21175 | envp : System.Address) | |
21176 | return Integer; | |
21177 | pragma Export (C, main, "main"); | |
21178 | ||
21179 | -- The following set of constants give the version | |
21180 | -- identification values for every unit in the bound | |
21181 | -- partition. This identification is computed from all | |
21182 | -- dependent semantic units, and corresponds to the | |
21183 | -- string that would be returned by use of the | |
21184 | -- Body_Version or Version attributes. | |
21185 | ||
21186 | type Version_32 is mod 2 ** 32; | |
21187 | u00001 : constant Version_32 := 16#7880BEB3#; | |
21188 | u00002 : constant Version_32 := 16#0D24CBD0#; | |
21189 | u00003 : constant Version_32 := 16#3283DBEB#; | |
21190 | u00004 : constant Version_32 := 16#2359F9ED#; | |
21191 | u00005 : constant Version_32 := 16#664FB847#; | |
21192 | u00006 : constant Version_32 := 16#68E803DF#; | |
21193 | u00007 : constant Version_32 := 16#5572E604#; | |
21194 | u00008 : constant Version_32 := 16#46B173D8#; | |
21195 | u00009 : constant Version_32 := 16#156A40CF#; | |
21196 | u00010 : constant Version_32 := 16#033DABE0#; | |
21197 | u00011 : constant Version_32 := 16#6AB38FEA#; | |
21198 | u00012 : constant Version_32 := 16#22B6217D#; | |
21199 | u00013 : constant Version_32 := 16#68A22947#; | |
21200 | u00014 : constant Version_32 := 16#18CC4A56#; | |
21201 | u00015 : constant Version_32 := 16#08258E1B#; | |
21202 | u00016 : constant Version_32 := 16#367D5222#; | |
21203 | u00017 : constant Version_32 := 16#20C9ECA4#; | |
21204 | u00018 : constant Version_32 := 16#50D32CB6#; | |
21205 | u00019 : constant Version_32 := 16#39A8BB77#; | |
21206 | u00020 : constant Version_32 := 16#5CF8FA2B#; | |
21207 | u00021 : constant Version_32 := 16#2F1EB794#; | |
21208 | u00022 : constant Version_32 := 16#31AB6444#; | |
21209 | u00023 : constant Version_32 := 16#1574B6E9#; | |
21210 | u00024 : constant Version_32 := 16#5109C189#; | |
21211 | u00025 : constant Version_32 := 16#56D770CD#; | |
21212 | u00026 : constant Version_32 := 16#02F9DE3D#; | |
21213 | u00027 : constant Version_32 := 16#08AB6B2C#; | |
21214 | u00028 : constant Version_32 := 16#3FA37670#; | |
21215 | u00029 : constant Version_32 := 16#476457A0#; | |
21216 | u00030 : constant Version_32 := 16#731E1B6E#; | |
21217 | u00031 : constant Version_32 := 16#23C2E789#; | |
21218 | u00032 : constant Version_32 := 16#0F1BD6A1#; | |
21219 | u00033 : constant Version_32 := 16#7C25DE96#; | |
21220 | u00034 : constant Version_32 := 16#39ADFFA2#; | |
21221 | u00035 : constant Version_32 := 16#571DE3E7#; | |
21222 | u00036 : constant Version_32 := 16#5EB646AB#; | |
21223 | u00037 : constant Version_32 := 16#4249379B#; | |
21224 | u00038 : constant Version_32 := 16#0357E00A#; | |
21225 | u00039 : constant Version_32 := 16#3784FB72#; | |
21226 | u00040 : constant Version_32 := 16#2E723019#; | |
21227 | u00041 : constant Version_32 := 16#623358EA#; | |
21228 | u00042 : constant Version_32 := 16#107F9465#; | |
21229 | u00043 : constant Version_32 := 16#6843F68A#; | |
21230 | u00044 : constant Version_32 := 16#63305874#; | |
21231 | u00045 : constant Version_32 := 16#31E56CE1#; | |
21232 | u00046 : constant Version_32 := 16#02917970#; | |
21233 | u00047 : constant Version_32 := 16#6CCBA70E#; | |
21234 | u00048 : constant Version_32 := 16#41CD4204#; | |
21235 | u00049 : constant Version_32 := 16#572E3F58#; | |
21236 | u00050 : constant Version_32 := 16#20729FF5#; | |
21237 | u00051 : constant Version_32 := 16#1D4F93E8#; | |
21238 | u00052 : constant Version_32 := 16#30B2EC3D#; | |
21239 | u00053 : constant Version_32 := 16#34054F96#; | |
21240 | u00054 : constant Version_32 := 16#5A199860#; | |
21241 | u00055 : constant Version_32 := 16#0E7F912B#; | |
21242 | u00056 : constant Version_32 := 16#5760634A#; | |
21243 | u00057 : constant Version_32 := 16#5D851835#; | |
21244 | ||
21245 | -- The following Export pragmas export the version numbers | |
21246 | -- with symbolic names ending in B (for body) or S | |
21247 | -- (for spec) so that they can be located in a link. The | |
21248 | -- information provided here is sufficient to track down | |
21249 | -- the exact versions of units used in a given build. | |
21250 | ||
21251 | pragma Export (C, u00001, "helloB"); | |
21252 | pragma Export (C, u00002, "system__standard_libraryB"); | |
21253 | pragma Export (C, u00003, "system__standard_libraryS"); | |
21254 | pragma Export (C, u00004, "adaS"); | |
21255 | pragma Export (C, u00005, "ada__text_ioB"); | |
21256 | pragma Export (C, u00006, "ada__text_ioS"); | |
21257 | pragma Export (C, u00007, "ada__exceptionsB"); | |
21258 | pragma Export (C, u00008, "ada__exceptionsS"); | |
21259 | pragma Export (C, u00009, "gnatS"); | |
21260 | pragma Export (C, u00010, "gnat__heap_sort_aB"); | |
21261 | pragma Export (C, u00011, "gnat__heap_sort_aS"); | |
21262 | pragma Export (C, u00012, "systemS"); | |
21263 | pragma Export (C, u00013, "system__exception_tableB"); | |
21264 | pragma Export (C, u00014, "system__exception_tableS"); | |
21265 | pragma Export (C, u00015, "gnat__htableB"); | |
21266 | pragma Export (C, u00016, "gnat__htableS"); | |
21267 | pragma Export (C, u00017, "system__exceptionsS"); | |
21268 | pragma Export (C, u00018, "system__machine_state_operationsB"); | |
21269 | pragma Export (C, u00019, "system__machine_state_operationsS"); | |
21270 | pragma Export (C, u00020, "system__machine_codeS"); | |
21271 | pragma Export (C, u00021, "system__storage_elementsB"); | |
21272 | pragma Export (C, u00022, "system__storage_elementsS"); | |
21273 | pragma Export (C, u00023, "system__secondary_stackB"); | |
21274 | pragma Export (C, u00024, "system__secondary_stackS"); | |
21275 | pragma Export (C, u00025, "system__parametersB"); | |
21276 | pragma Export (C, u00026, "system__parametersS"); | |
21277 | pragma Export (C, u00027, "system__soft_linksB"); | |
21278 | pragma Export (C, u00028, "system__soft_linksS"); | |
21279 | pragma Export (C, u00029, "system__stack_checkingB"); | |
21280 | pragma Export (C, u00030, "system__stack_checkingS"); | |
21281 | pragma Export (C, u00031, "system__tracebackB"); | |
21282 | pragma Export (C, u00032, "system__tracebackS"); | |
21283 | pragma Export (C, u00033, "ada__streamsS"); | |
21284 | pragma Export (C, u00034, "ada__tagsB"); | |
21285 | pragma Export (C, u00035, "ada__tagsS"); | |
21286 | pragma Export (C, u00036, "system__string_opsB"); | |
21287 | pragma Export (C, u00037, "system__string_opsS"); | |
21288 | pragma Export (C, u00038, "interfacesS"); | |
21289 | pragma Export (C, u00039, "interfaces__c_streamsB"); | |
21290 | pragma Export (C, u00040, "interfaces__c_streamsS"); | |
21291 | pragma Export (C, u00041, "system__file_ioB"); | |
21292 | pragma Export (C, u00042, "system__file_ioS"); | |
21293 | pragma Export (C, u00043, "ada__finalizationB"); | |
21294 | pragma Export (C, u00044, "ada__finalizationS"); | |
21295 | pragma Export (C, u00045, "system__finalization_rootB"); | |
21296 | pragma Export (C, u00046, "system__finalization_rootS"); | |
21297 | pragma Export (C, u00047, "system__finalization_implementationB"); | |
21298 | pragma Export (C, u00048, "system__finalization_implementationS"); | |
21299 | pragma Export (C, u00049, "system__string_ops_concat_3B"); | |
21300 | pragma Export (C, u00050, "system__string_ops_concat_3S"); | |
21301 | pragma Export (C, u00051, "system__stream_attributesB"); | |
21302 | pragma Export (C, u00052, "system__stream_attributesS"); | |
21303 | pragma Export (C, u00053, "ada__io_exceptionsS"); | |
21304 | pragma Export (C, u00054, "system__unsigned_typesS"); | |
21305 | pragma Export (C, u00055, "system__file_control_blockS"); | |
21306 | pragma Export (C, u00056, "ada__finalization__list_controllerB"); | |
21307 | pragma Export (C, u00057, "ada__finalization__list_controllerS"); | |
21308 | ||
21309 | -- BEGIN ELABORATION ORDER | |
21310 | -- ada (spec) | |
21311 | -- gnat (spec) | |
21312 | -- gnat.heap_sort_a (spec) | |
21313 | -- gnat.heap_sort_a (body) | |
21314 | -- gnat.htable (spec) | |
21315 | -- gnat.htable (body) | |
21316 | -- interfaces (spec) | |
21317 | -- system (spec) | |
21318 | -- system.machine_code (spec) | |
21319 | -- system.parameters (spec) | |
21320 | -- system.parameters (body) | |
21321 | -- interfaces.c_streams (spec) | |
21322 | -- interfaces.c_streams (body) | |
21323 | -- system.standard_library (spec) | |
21324 | -- ada.exceptions (spec) | |
21325 | -- system.exception_table (spec) | |
21326 | -- system.exception_table (body) | |
21327 | -- ada.io_exceptions (spec) | |
21328 | -- system.exceptions (spec) | |
21329 | -- system.storage_elements (spec) | |
21330 | -- system.storage_elements (body) | |
21331 | -- system.machine_state_operations (spec) | |
21332 | -- system.machine_state_operations (body) | |
21333 | -- system.secondary_stack (spec) | |
21334 | -- system.stack_checking (spec) | |
21335 | -- system.soft_links (spec) | |
21336 | -- system.soft_links (body) | |
21337 | -- system.stack_checking (body) | |
21338 | -- system.secondary_stack (body) | |
21339 | -- system.standard_library (body) | |
21340 | -- system.string_ops (spec) | |
21341 | -- system.string_ops (body) | |
21342 | -- ada.tags (spec) | |
21343 | -- ada.tags (body) | |
21344 | -- ada.streams (spec) | |
21345 | -- system.finalization_root (spec) | |
21346 | -- system.finalization_root (body) | |
21347 | -- system.string_ops_concat_3 (spec) | |
21348 | -- system.string_ops_concat_3 (body) | |
21349 | -- system.traceback (spec) | |
21350 | -- system.traceback (body) | |
21351 | -- ada.exceptions (body) | |
21352 | -- system.unsigned_types (spec) | |
21353 | -- system.stream_attributes (spec) | |
21354 | -- system.stream_attributes (body) | |
21355 | -- system.finalization_implementation (spec) | |
21356 | -- system.finalization_implementation (body) | |
21357 | -- ada.finalization (spec) | |
21358 | -- ada.finalization (body) | |
21359 | -- ada.finalization.list_controller (spec) | |
21360 | -- ada.finalization.list_controller (body) | |
21361 | -- system.file_control_block (spec) | |
21362 | -- system.file_io (spec) | |
21363 | -- system.file_io (body) | |
21364 | -- ada.text_io (spec) | |
21365 | -- ada.text_io (body) | |
21366 | -- hello (body) | |
21367 | -- END ELABORATION ORDER | |
21368 | ||
21369 | end ada_main; | |
21370 | ||
21371 | -- The following source file name pragmas allow the generated file | |
21372 | -- names to be unique for different main programs. They are needed | |
21373 | -- since the package name will always be Ada_Main. | |
21374 | ||
21375 | pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads"); | |
21376 | pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb"); | |
21377 | ||
21378 | -- Generated package body for Ada_Main starts here | |
21379 | ||
21380 | package body ada_main is | |
21381 | ||
21382 | -- The actual finalization is performed by calling the | |
21383 | -- library routine in System.Standard_Library.Adafinal | |
21384 | ||
21385 | procedure Do_Finalize; | |
21386 | pragma Import (C, Do_Finalize, "system__standard_library__adafinal"); | |
21387 | ||
21388 | ------------- | |
21389 | -- adainit -- | |
21390 | ------------- | |
21391 | ||
21392 | @findex adainit | |
21393 | procedure adainit is | |
21394 | ||
21395 | -- These booleans are set to True once the associated unit has | |
21396 | -- been elaborated. It is also used to avoid elaborating the | |
21397 | -- same unit twice. | |
88e1739c | 21398 | |
7cd4527e AC |
21399 | E040 : Boolean; |
21400 | pragma Import (Ada, E040, "interfaces__c_streams_E"); | |
88e1739c | 21401 | |
7cd4527e AC |
21402 | E008 : Boolean; |
21403 | pragma Import (Ada, E008, "ada__exceptions_E"); | |
88e1739c | 21404 | |
7cd4527e AC |
21405 | E014 : Boolean; |
21406 | pragma Import (Ada, E014, "system__exception_table_E"); | |
88e1739c | 21407 | |
7cd4527e AC |
21408 | E053 : Boolean; |
21409 | pragma Import (Ada, E053, "ada__io_exceptions_E"); | |
88e1739c | 21410 | |
7cd4527e AC |
21411 | E017 : Boolean; |
21412 | pragma Import (Ada, E017, "system__exceptions_E"); | |
88e1739c | 21413 | |
7cd4527e AC |
21414 | E024 : Boolean; |
21415 | pragma Import (Ada, E024, "system__secondary_stack_E"); | |
88e1739c | 21416 | |
7cd4527e AC |
21417 | E030 : Boolean; |
21418 | pragma Import (Ada, E030, "system__stack_checking_E"); | |
88e1739c | 21419 | |
7cd4527e AC |
21420 | E028 : Boolean; |
21421 | pragma Import (Ada, E028, "system__soft_links_E"); | |
88e1739c | 21422 | |
7cd4527e AC |
21423 | E035 : Boolean; |
21424 | pragma Import (Ada, E035, "ada__tags_E"); | |
88e1739c | 21425 | |
7cd4527e AC |
21426 | E033 : Boolean; |
21427 | pragma Import (Ada, E033, "ada__streams_E"); | |
88e1739c | 21428 | |
7cd4527e AC |
21429 | E046 : Boolean; |
21430 | pragma Import (Ada, E046, "system__finalization_root_E"); | |
88e1739c | 21431 | |
7cd4527e AC |
21432 | E048 : Boolean; |
21433 | pragma Import (Ada, E048, "system__finalization_implementation_E"); | |
88e1739c | 21434 | |
7cd4527e AC |
21435 | E044 : Boolean; |
21436 | pragma Import (Ada, E044, "ada__finalization_E"); | |
88e1739c | 21437 | |
7cd4527e AC |
21438 | E057 : Boolean; |
21439 | pragma Import (Ada, E057, "ada__finalization__list_controller_E"); | |
88e1739c | 21440 | |
7cd4527e AC |
21441 | E055 : Boolean; |
21442 | pragma Import (Ada, E055, "system__file_control_block_E"); | |
88e1739c | 21443 | |
7cd4527e AC |
21444 | E042 : Boolean; |
21445 | pragma Import (Ada, E042, "system__file_io_E"); | |
88e1739c | 21446 | |
7cd4527e AC |
21447 | E006 : Boolean; |
21448 | pragma Import (Ada, E006, "ada__text_io_E"); | |
88e1739c | 21449 | |
7cd4527e AC |
21450 | -- Set_Globals is a library routine that stores away the |
21451 | -- value of the indicated set of global values in global | |
21452 | -- variables within the library. | |
88e1739c | 21453 | |
7cd4527e AC |
21454 | procedure Set_Globals |
21455 | (Main_Priority : Integer; | |
21456 | Time_Slice_Value : Integer; | |
21457 | WC_Encoding : Character; | |
21458 | Locking_Policy : Character; | |
21459 | Queuing_Policy : Character; | |
21460 | Task_Dispatching_Policy : Character; | |
21461 | Adafinal : System.Address; | |
21462 | Unreserve_All_Interrupts : Integer; | |
21463 | Exception_Tracebacks : Integer); | |
21464 | @findex __gnat_set_globals | |
21465 | pragma Import (C, Set_Globals, "__gnat_set_globals"); | |
88e1739c | 21466 | |
7cd4527e AC |
21467 | -- SDP_Table_Build is a library routine used to build the |
21468 | -- exception tables. See unit Ada.Exceptions in files | |
21469 | -- a-except.ads/adb for full details of how zero cost | |
21470 | -- exception handling works. This procedure, the call to | |
21471 | -- it, and the two following tables are all omitted if the | |
21472 | -- build is in longjmp/setjump exception mode. | |
88e1739c | 21473 | |
7cd4527e AC |
21474 | @findex SDP_Table_Build |
21475 | @findex Zero Cost Exceptions | |
21476 | procedure SDP_Table_Build | |
21477 | (SDP_Addresses : System.Address; | |
21478 | SDP_Count : Natural; | |
21479 | Elab_Addresses : System.Address; | |
21480 | Elab_Addr_Count : Natural); | |
21481 | pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build"); | |
88e1739c | 21482 | |
7cd4527e AC |
21483 | -- Table of Unit_Exception_Table addresses. Used for zero |
21484 | -- cost exception handling to build the top level table. | |
88e1739c | 21485 | |
7cd4527e AC |
21486 | ST : aliased constant array (1 .. 23) of System.Address := ( |
21487 | Hello'UET_Address, | |
21488 | Ada.Text_Io'UET_Address, | |
21489 | Ada.Exceptions'UET_Address, | |
21490 | Gnat.Heap_Sort_A'UET_Address, | |
21491 | System.Exception_Table'UET_Address, | |
21492 | System.Machine_State_Operations'UET_Address, | |
21493 | System.Secondary_Stack'UET_Address, | |
21494 | System.Parameters'UET_Address, | |
21495 | System.Soft_Links'UET_Address, | |
21496 | System.Stack_Checking'UET_Address, | |
21497 | System.Traceback'UET_Address, | |
21498 | Ada.Streams'UET_Address, | |
21499 | Ada.Tags'UET_Address, | |
21500 | System.String_Ops'UET_Address, | |
21501 | Interfaces.C_Streams'UET_Address, | |
21502 | System.File_Io'UET_Address, | |
21503 | Ada.Finalization'UET_Address, | |
21504 | System.Finalization_Root'UET_Address, | |
21505 | System.Finalization_Implementation'UET_Address, | |
21506 | System.String_Ops_Concat_3'UET_Address, | |
21507 | System.Stream_Attributes'UET_Address, | |
21508 | System.File_Control_Block'UET_Address, | |
21509 | Ada.Finalization.List_Controller'UET_Address); | |
88e1739c | 21510 | |
7cd4527e AC |
21511 | -- Table of addresses of elaboration routines. Used for |
21512 | -- zero cost exception handling to make sure these | |
21513 | -- addresses are included in the top level procedure | |
21514 | -- address table. | |
88e1739c | 21515 | |
7cd4527e AC |
21516 | EA : aliased constant array (1 .. 23) of System.Address := ( |
21517 | adainit'Code_Address, | |
21518 | Do_Finalize'Code_Address, | |
21519 | Ada.Exceptions'Elab_Spec'Address, | |
21520 | System.Exceptions'Elab_Spec'Address, | |
21521 | Interfaces.C_Streams'Elab_Spec'Address, | |
21522 | System.Exception_Table'Elab_Body'Address, | |
21523 | Ada.Io_Exceptions'Elab_Spec'Address, | |
21524 | System.Stack_Checking'Elab_Spec'Address, | |
21525 | System.Soft_Links'Elab_Body'Address, | |
21526 | System.Secondary_Stack'Elab_Body'Address, | |
21527 | Ada.Tags'Elab_Spec'Address, | |
21528 | Ada.Tags'Elab_Body'Address, | |
21529 | Ada.Streams'Elab_Spec'Address, | |
21530 | System.Finalization_Root'Elab_Spec'Address, | |
21531 | Ada.Exceptions'Elab_Body'Address, | |
21532 | System.Finalization_Implementation'Elab_Spec'Address, | |
21533 | System.Finalization_Implementation'Elab_Body'Address, | |
21534 | Ada.Finalization'Elab_Spec'Address, | |
21535 | Ada.Finalization.List_Controller'Elab_Spec'Address, | |
21536 | System.File_Control_Block'Elab_Spec'Address, | |
21537 | System.File_Io'Elab_Body'Address, | |
21538 | Ada.Text_Io'Elab_Spec'Address, | |
21539 | Ada.Text_Io'Elab_Body'Address); | |
88e1739c | 21540 | |
7cd4527e | 21541 | -- Start of processing for adainit |
88e1739c | 21542 | |
7cd4527e | 21543 | begin |
88e1739c | 21544 | |
7cd4527e AC |
21545 | -- Call SDP_Table_Build to build the top level procedure |
21546 | -- table for zero cost exception handling (omitted in | |
21547 | -- longjmp/setjump mode). | |
88e1739c | 21548 | |
7cd4527e | 21549 | SDP_Table_Build (ST'Address, 23, EA'Address, 23); |
88e1739c | 21550 | |
7cd4527e AC |
21551 | -- Call Set_Globals to record various information for |
21552 | -- this partition. The values are derived by the binder | |
21553 | -- from information stored in the ali files by the compiler. | |
88e1739c | 21554 | |
7cd4527e AC |
21555 | @findex __gnat_set_globals |
21556 | Set_Globals | |
21557 | (Main_Priority => -1, | |
21558 | -- Priority of main program, -1 if no pragma Priority used | |
88e1739c | 21559 | |
7cd4527e AC |
21560 | Time_Slice_Value => -1, |
21561 | -- Time slice from Time_Slice pragma, -1 if none used | |
88e1739c | 21562 | |
7cd4527e AC |
21563 | WC_Encoding => 'b', |
21564 | -- Wide_Character encoding used, default is brackets | |
21565 | ||
21566 | Locking_Policy => ' ', | |
21567 | -- Locking_Policy used, default of space means not | |
21568 | -- specified, otherwise it is the first character of | |
21569 | -- the policy name. | |
88e1739c | 21570 | |
7cd4527e AC |
21571 | Queuing_Policy => ' ', |
21572 | -- Queuing_Policy used, default of space means not | |
21573 | -- specified, otherwise it is the first character of | |
21574 | -- the policy name. | |
88e1739c | 21575 | |
7cd4527e AC |
21576 | Task_Dispatching_Policy => ' ', |
21577 | -- Task_Dispatching_Policy used, default of space means | |
21578 | -- not specified, otherwise first character of the | |
21579 | -- policy name. | |
88e1739c | 21580 | |
7cd4527e AC |
21581 | Adafinal => System.Null_Address, |
21582 | -- Address of Adafinal routine, not used anymore | |
88e1739c | 21583 | |
7cd4527e AC |
21584 | Unreserve_All_Interrupts => 0, |
21585 | -- Set true if pragma Unreserve_All_Interrupts was used | |
88e1739c | 21586 | |
7cd4527e AC |
21587 | Exception_Tracebacks => 0); |
21588 | -- Indicates if exception tracebacks are enabled | |
88e1739c | 21589 | |
7cd4527e | 21590 | Elab_Final_Code := 1; |
88e1739c | 21591 | |
7cd4527e AC |
21592 | -- Now we have the elaboration calls for all units in the partition. |
21593 | -- The Elab_Spec and Elab_Body attributes generate references to the | |
21594 | -- implicit elaboration procedures generated by the compiler for | |
21595 | -- each unit that requires elaboration. | |
88e1739c | 21596 | |
7cd4527e AC |
21597 | if not E040 then |
21598 | Interfaces.C_Streams'Elab_Spec; | |
21599 | end if; | |
21600 | E040 := True; | |
21601 | if not E008 then | |
21602 | Ada.Exceptions'Elab_Spec; | |
21603 | end if; | |
21604 | if not E014 then | |
21605 | System.Exception_Table'Elab_Body; | |
21606 | E014 := True; | |
21607 | end if; | |
21608 | if not E053 then | |
21609 | Ada.Io_Exceptions'Elab_Spec; | |
21610 | E053 := True; | |
21611 | end if; | |
21612 | if not E017 then | |
21613 | System.Exceptions'Elab_Spec; | |
21614 | E017 := True; | |
21615 | end if; | |
21616 | if not E030 then | |
21617 | System.Stack_Checking'Elab_Spec; | |
21618 | end if; | |
21619 | if not E028 then | |
21620 | System.Soft_Links'Elab_Body; | |
21621 | E028 := True; | |
21622 | end if; | |
21623 | E030 := True; | |
21624 | if not E024 then | |
21625 | System.Secondary_Stack'Elab_Body; | |
21626 | E024 := True; | |
21627 | end if; | |
21628 | if not E035 then | |
21629 | Ada.Tags'Elab_Spec; | |
21630 | end if; | |
21631 | if not E035 then | |
21632 | Ada.Tags'Elab_Body; | |
21633 | E035 := True; | |
21634 | end if; | |
21635 | if not E033 then | |
21636 | Ada.Streams'Elab_Spec; | |
21637 | E033 := True; | |
21638 | end if; | |
21639 | if not E046 then | |
21640 | System.Finalization_Root'Elab_Spec; | |
21641 | end if; | |
21642 | E046 := True; | |
21643 | if not E008 then | |
21644 | Ada.Exceptions'Elab_Body; | |
21645 | E008 := True; | |
21646 | end if; | |
21647 | if not E048 then | |
21648 | System.Finalization_Implementation'Elab_Spec; | |
21649 | end if; | |
21650 | if not E048 then | |
21651 | System.Finalization_Implementation'Elab_Body; | |
21652 | E048 := True; | |
21653 | end if; | |
21654 | if not E044 then | |
21655 | Ada.Finalization'Elab_Spec; | |
21656 | end if; | |
21657 | E044 := True; | |
21658 | if not E057 then | |
21659 | Ada.Finalization.List_Controller'Elab_Spec; | |
21660 | end if; | |
21661 | E057 := True; | |
21662 | if not E055 then | |
21663 | System.File_Control_Block'Elab_Spec; | |
21664 | E055 := True; | |
21665 | end if; | |
21666 | if not E042 then | |
21667 | System.File_Io'Elab_Body; | |
21668 | E042 := True; | |
21669 | end if; | |
21670 | if not E006 then | |
21671 | Ada.Text_Io'Elab_Spec; | |
21672 | end if; | |
21673 | if not E006 then | |
21674 | Ada.Text_Io'Elab_Body; | |
21675 | E006 := True; | |
21676 | end if; | |
88e1739c | 21677 | |
7cd4527e AC |
21678 | Elab_Final_Code := 0; |
21679 | end adainit; | |
88e1739c | 21680 | |
7cd4527e AC |
21681 | -------------- |
21682 | -- adafinal -- | |
21683 | -------------- | |
88e1739c | 21684 | |
7cd4527e AC |
21685 | @findex adafinal |
21686 | procedure adafinal is | |
21687 | begin | |
21688 | Do_Finalize; | |
21689 | end adafinal; | |
88e1739c | 21690 | |
7cd4527e AC |
21691 | ---------- |
21692 | -- main -- | |
21693 | ---------- | |
88e1739c | 21694 | |
7cd4527e AC |
21695 | -- main is actually a function, as in the ANSI C standard, |
21696 | -- defined to return the exit status. The three parameters | |
21697 | -- are the argument count, argument values and environment | |
21698 | -- pointer. | |
88e1739c | 21699 | |
7cd4527e AC |
21700 | @findex Main Program |
21701 | function main | |
21702 | (argc : Integer; | |
21703 | argv : System.Address; | |
21704 | envp : System.Address) | |
21705 | return Integer | |
21706 | is | |
21707 | -- The initialize routine performs low level system | |
21708 | -- initialization using a standard library routine which | |
21709 | -- sets up signal handling and performs any other | |
21710 | -- required setup. The routine can be found in file | |
21711 | -- a-init.c. | |
88e1739c | 21712 | |
7cd4527e AC |
21713 | @findex __gnat_initialize |
21714 | procedure initialize; | |
21715 | pragma Import (C, initialize, "__gnat_initialize"); | |
88e1739c | 21716 | |
7cd4527e AC |
21717 | -- The finalize routine performs low level system |
21718 | -- finalization using a standard library routine. The | |
21719 | -- routine is found in file a-final.c and in the standard | |
21720 | -- distribution is a dummy routine that does nothing, so | |
21721 | -- really this is a hook for special user finalization. | |
88e1739c | 21722 | |
7cd4527e AC |
21723 | @findex __gnat_finalize |
21724 | procedure finalize; | |
21725 | pragma Import (C, finalize, "__gnat_finalize"); | |
88e1739c | 21726 | |
7cd4527e AC |
21727 | -- We get to the main program of the partition by using |
21728 | -- pragma Import because if we try to with the unit and | |
21729 | -- call it Ada style, then not only do we waste time | |
21730 | -- recompiling it, but also, we don't really know the right | |
21731 | -- switches (e.g. identifier character set) to be used | |
21732 | -- to compile it. | |
88e1739c | 21733 | |
7cd4527e AC |
21734 | procedure Ada_Main_Program; |
21735 | pragma Import (Ada, Ada_Main_Program, "_ada_hello"); | |
88e1739c | 21736 | |
7cd4527e | 21737 | -- Start of processing for main |
88e1739c | 21738 | |
7cd4527e AC |
21739 | begin |
21740 | -- Save global variables | |
88e1739c | 21741 | |
7cd4527e AC |
21742 | gnat_argc := argc; |
21743 | gnat_argv := argv; | |
21744 | gnat_envp := envp; | |
88e1739c | 21745 | |
7cd4527e | 21746 | -- Call low level system initialization |
88e1739c | 21747 | |
7cd4527e | 21748 | Initialize; |
88e1739c | 21749 | |
7cd4527e | 21750 | -- Call our generated Ada initialization routine |
88e1739c | 21751 | |
7cd4527e AC |
21752 | adainit; |
21753 | ||
21754 | -- This is the point at which we want the debugger to get | |
21755 | -- control | |
21756 | ||
21757 | Break_Start; | |
21758 | ||
21759 | -- Now we call the main program of the partition | |
88e1739c | 21760 | |
7cd4527e | 21761 | Ada_Main_Program; |
88e1739c | 21762 | |
7cd4527e | 21763 | -- Perform Ada finalization |
88e1739c | 21764 | |
7cd4527e | 21765 | adafinal; |
88e1739c | 21766 | |
7cd4527e | 21767 | -- Perform low level system finalization |
88e1739c | 21768 | |
7cd4527e | 21769 | Finalize; |
88e1739c | 21770 | |
7cd4527e AC |
21771 | -- Return the proper exit status |
21772 | return (gnat_exit_status); | |
21773 | end; | |
88e1739c | 21774 | |
7cd4527e AC |
21775 | -- This section is entirely comments, so it has no effect on the |
21776 | -- compilation of the Ada_Main package. It provides the list of | |
21777 | -- object files and linker options, as well as some standard | |
21778 | -- libraries needed for the link. The gnatlink utility parses | |
21779 | -- this b~hello.adb file to read these comment lines to generate | |
21780 | -- the appropriate command line arguments for the call to the | |
21781 | -- system linker. The BEGIN/END lines are used for sentinels for | |
21782 | -- this parsing operation. | |
88e1739c | 21783 | |
7cd4527e AC |
21784 | -- The exact file names will of course depend on the environment, |
21785 | -- host/target and location of files on the host system. | |
21786 | ||
21787 | @findex Object file list | |
21788 | -- BEGIN Object file/option list | |
21789 | -- ./hello.o | |
21790 | -- -L./ | |
21791 | -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/ | |
21792 | -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a | |
21793 | -- END Object file/option list | |
21794 | ||
21795 | end ada_main; | |
88e1739c | 21796 | @end smallexample |
7cd4527e | 21797 | |
88e1739c | 21798 | @noindent |
7cd4527e AC |
21799 | The Ada code in the above example is exactly what is generated by the |
21800 | binder. We have added comments to more clearly indicate the function | |
21801 | of each part of the generated @code{Ada_Main} package. | |
88e1739c | 21802 | |
7cd4527e AC |
21803 | The code is standard Ada in all respects, and can be processed by any |
21804 | tools that handle Ada. In particular, it is possible to use the debugger | |
21805 | in Ada mode to debug the generated @code{Ada_Main} package. For example, | |
21806 | suppose that for reasons that you do not understand, your program is crashing | |
21807 | during elaboration of the body of @code{Ada.Text_IO}. To locate this bug, | |
21808 | you can place a breakpoint on the call: | |
88e1739c | 21809 | |
7cd4527e AC |
21810 | @smallexample @c ada |
21811 | Ada.Text_Io'Elab_Body; | |
88e1739c FW |
21812 | @end smallexample |
21813 | ||
21814 | @noindent | |
7cd4527e AC |
21815 | and trace the elaboration routine for this package to find out where |
21816 | the problem might be (more usually of course you would be debugging | |
21817 | elaboration code in your own application). | |
88e1739c | 21818 | |
7cd4527e AC |
21819 | |
21820 | @node Elaboration Order Handling in GNAT | |
21821 | @appendix Elaboration Order Handling in GNAT | |
21822 | @cindex Order of elaboration | |
21823 | @cindex Elaboration control | |
21824 | ||
21825 | @menu | |
21826 | * Elaboration Code in Ada 95:: | |
21827 | * Checking the Elaboration Order in Ada 95:: | |
21828 | * Controlling the Elaboration Order in Ada 95:: | |
21829 | * Controlling Elaboration in GNAT - Internal Calls:: | |
21830 | * Controlling Elaboration in GNAT - External Calls:: | |
21831 | * Default Behavior in GNAT - Ensuring Safety:: | |
21832 | * Treatment of Pragma Elaborate:: | |
21833 | * Elaboration Issues for Library Tasks:: | |
21834 | * Mixing Elaboration Models:: | |
21835 | * What to Do If the Default Elaboration Behavior Fails:: | |
21836 | * Elaboration for Access-to-Subprogram Values:: | |
21837 | * Summary of Procedures for Elaboration Control:: | |
21838 | * Other Elaboration Order Considerations:: | |
21839 | @end menu | |
88e1739c FW |
21840 | |
21841 | @noindent | |
7cd4527e AC |
21842 | This chapter describes the handling of elaboration code in Ada 95 and |
21843 | in GNAT, and discusses how the order of elaboration of program units can | |
21844 | be controlled in GNAT, either automatically or with explicit programming | |
21845 | features. | |
88e1739c | 21846 | |
7cd4527e AC |
21847 | @node Elaboration Code in Ada 95 |
21848 | @section Elaboration Code in Ada 95 | |
88e1739c | 21849 | |
7cd4527e AC |
21850 | @noindent |
21851 | Ada 95 provides rather general mechanisms for executing code at elaboration | |
21852 | time, that is to say before the main program starts executing. Such code arises | |
21853 | in three contexts: | |
21854 | ||
21855 | @table @asis | |
21856 | @item Initializers for variables. | |
21857 | Variables declared at the library level, in package specs or bodies, can | |
21858 | require initialization that is performed at elaboration time, as in: | |
21859 | @smallexample @c ada | |
21860 | @cartouche | |
21861 | Sqrt_Half : Float := Sqrt (0.5); | |
21862 | @end cartouche | |
88e1739c FW |
21863 | @end smallexample |
21864 | ||
7cd4527e AC |
21865 | @item Package initialization code |
21866 | Code in a @code{BEGIN-END} section at the outer level of a package body is | |
21867 | executed as part of the package body elaboration code. | |
88e1739c | 21868 | |
7cd4527e AC |
21869 | @item Library level task allocators |
21870 | Tasks that are declared using task allocators at the library level | |
21871 | start executing immediately and hence can execute at elaboration time. | |
21872 | @end table | |
88e1739c | 21873 | |
7cd4527e AC |
21874 | @noindent |
21875 | Subprogram calls are possible in any of these contexts, which means that | |
21876 | any arbitrary part of the program may be executed as part of the elaboration | |
21877 | code. It is even possible to write a program which does all its work at | |
21878 | elaboration time, with a null main program, although stylistically this | |
21879 | would usually be considered an inappropriate way to structure | |
21880 | a program. | |
88e1739c | 21881 | |
7cd4527e AC |
21882 | An important concern arises in the context of elaboration code: |
21883 | we have to be sure that it is executed in an appropriate order. What we | |
21884 | have is a series of elaboration code sections, potentially one section | |
21885 | for each unit in the program. It is important that these execute | |
21886 | in the correct order. Correctness here means that, taking the above | |
21887 | example of the declaration of @code{Sqrt_Half}, | |
21888 | if some other piece of | |
21889 | elaboration code references @code{Sqrt_Half}, | |
21890 | then it must run after the | |
21891 | section of elaboration code that contains the declaration of | |
21892 | @code{Sqrt_Half}. | |
88e1739c | 21893 | |
7cd4527e AC |
21894 | There would never be any order of elaboration problem if we made a rule |
21895 | that whenever you @code{with} a unit, you must elaborate both the spec and body | |
21896 | of that unit before elaborating the unit doing the @code{with}'ing: | |
88e1739c | 21897 | |
7cd4527e AC |
21898 | @smallexample @c ada |
21899 | @group | |
21900 | @cartouche | |
21901 | with Unit_1; | |
21902 | package Unit_2 is ... | |
21903 | @end cartouche | |
88e1739c FW |
21904 | @end group |
21905 | @end smallexample | |
21906 | ||
7cd4527e AC |
21907 | @noindent |
21908 | would require that both the body and spec of @code{Unit_1} be elaborated | |
21909 | before the spec of @code{Unit_2}. However, a rule like that would be far too | |
21910 | restrictive. In particular, it would make it impossible to have routines | |
21911 | in separate packages that were mutually recursive. | |
88e1739c | 21912 | |
7cd4527e AC |
21913 | You might think that a clever enough compiler could look at the actual |
21914 | elaboration code and determine an appropriate correct order of elaboration, | |
21915 | but in the general case, this is not possible. Consider the following | |
21916 | example. | |
88e1739c | 21917 | |
7cd4527e AC |
21918 | In the body of @code{Unit_1}, we have a procedure @code{Func_1} |
21919 | that references | |
21920 | the variable @code{Sqrt_1}, which is declared in the elaboration code | |
21921 | of the body of @code{Unit_1}: | |
88e1739c | 21922 | |
7cd4527e AC |
21923 | @smallexample @c ada |
21924 | @cartouche | |
21925 | Sqrt_1 : Float := Sqrt (0.1); | |
21926 | @end cartouche | |
21927 | @end smallexample | |
88e1739c | 21928 | |
7cd4527e AC |
21929 | @noindent |
21930 | The elaboration code of the body of @code{Unit_1} also contains: | |
88e1739c | 21931 | |
7cd4527e | 21932 | @smallexample @c ada |
88e1739c | 21933 | @group |
7cd4527e AC |
21934 | @cartouche |
21935 | if expression_1 = 1 then | |
21936 | Q := Unit_2.Func_2; | |
21937 | end if; | |
21938 | @end cartouche | |
88e1739c FW |
21939 | @end group |
21940 | @end smallexample | |
21941 | ||
88e1739c | 21942 | @noindent |
7cd4527e AC |
21943 | @code{Unit_2} is exactly parallel, |
21944 | it has a procedure @code{Func_2} that references | |
21945 | the variable @code{Sqrt_2}, which is declared in the elaboration code of | |
21946 | the body @code{Unit_2}: | |
88e1739c | 21947 | |
7cd4527e AC |
21948 | @smallexample @c ada |
21949 | @cartouche | |
21950 | Sqrt_2 : Float := Sqrt (0.1); | |
21951 | @end cartouche | |
21952 | @end smallexample | |
88e1739c | 21953 | |
7cd4527e AC |
21954 | @noindent |
21955 | The elaboration code of the body of @code{Unit_2} also contains: | |
88e1739c | 21956 | |
7cd4527e AC |
21957 | @smallexample @c ada |
21958 | @group | |
21959 | @cartouche | |
21960 | if expression_2 = 2 then | |
21961 | Q := Unit_1.Func_1; | |
21962 | end if; | |
21963 | @end cartouche | |
88e1739c FW |
21964 | @end group |
21965 | @end smallexample | |
21966 | ||
7cd4527e AC |
21967 | @noindent |
21968 | Now the question is, which of the following orders of elaboration is | |
21969 | acceptable: | |
88e1739c FW |
21970 | |
21971 | @smallexample | |
21972 | @group | |
7cd4527e AC |
21973 | Spec of Unit_1 |
21974 | Spec of Unit_2 | |
21975 | Body of Unit_1 | |
21976 | Body of Unit_2 | |
88e1739c FW |
21977 | @end group |
21978 | @end smallexample | |
21979 | ||
21980 | @noindent | |
7cd4527e | 21981 | or |
88e1739c FW |
21982 | |
21983 | @smallexample | |
21984 | @group | |
7cd4527e AC |
21985 | Spec of Unit_2 |
21986 | Spec of Unit_1 | |
21987 | Body of Unit_2 | |
21988 | Body of Unit_1 | |
88e1739c FW |
21989 | @end group |
21990 | @end smallexample | |
21991 | ||
21992 | @noindent | |
7cd4527e AC |
21993 | If you carefully analyze the flow here, you will see that you cannot tell |
21994 | at compile time the answer to this question. | |
21995 | If @code{expression_1} is not equal to 1, | |
21996 | and @code{expression_2} is not equal to 2, | |
21997 | then either order is acceptable, because neither of the function calls is | |
21998 | executed. If both tests evaluate to true, then neither order is acceptable | |
21999 | and in fact there is no correct order. | |
88e1739c | 22000 | |
7cd4527e AC |
22001 | If one of the two expressions is true, and the other is false, then one |
22002 | of the above orders is correct, and the other is incorrect. For example, | |
22003 | if @code{expression_1} = 1 and @code{expression_2} /= 2, | |
22004 | then the call to @code{Func_2} | |
22005 | will occur, but not the call to @code{Func_1.} | |
22006 | This means that it is essential | |
22007 | to elaborate the body of @code{Unit_1} before | |
22008 | the body of @code{Unit_2}, so the first | |
22009 | order of elaboration is correct and the second is wrong. | |
22010 | ||
22011 | By making @code{expression_1} and @code{expression_2} | |
22012 | depend on input data, or perhaps | |
22013 | the time of day, we can make it impossible for the compiler or binder | |
22014 | to figure out which of these expressions will be true, and hence it | |
22015 | is impossible to guarantee a safe order of elaboration at run time. | |
22016 | ||
22017 | @node Checking the Elaboration Order in Ada 95 | |
22018 | @section Checking the Elaboration Order in Ada 95 | |
88e1739c FW |
22019 | |
22020 | @noindent | |
7cd4527e AC |
22021 | In some languages that involve the same kind of elaboration problems, |
22022 | e.g. Java and C++, the programmer is expected to worry about these | |
22023 | ordering problems himself, and it is common to | |
22024 | write a program in which an incorrect elaboration order gives | |
22025 | surprising results, because it references variables before they | |
22026 | are initialized. | |
22027 | Ada 95 is designed to be a safe language, and a programmer-beware approach is | |
22028 | clearly not sufficient. Consequently, the language provides three lines | |
22029 | of defense: | |
88e1739c | 22030 | |
7cd4527e AC |
22031 | @table @asis |
22032 | @item Standard rules | |
22033 | Some standard rules restrict the possible choice of elaboration | |
22034 | order. In particular, if you @code{with} a unit, then its spec is always | |
22035 | elaborated before the unit doing the @code{with}. Similarly, a parent | |
22036 | spec is always elaborated before the child spec, and finally | |
22037 | a spec is always elaborated before its corresponding body. | |
88e1739c | 22038 | |
7cd4527e AC |
22039 | @item Dynamic elaboration checks |
22040 | @cindex Elaboration checks | |
22041 | @cindex Checks, elaboration | |
22042 | Dynamic checks are made at run time, so that if some entity is accessed | |
22043 | before it is elaborated (typically by means of a subprogram call) | |
22044 | then the exception (@code{Program_Error}) is raised. | |
22045 | ||
22046 | @item Elaboration control | |
22047 | Facilities are provided for the programmer to specify the desired order | |
22048 | of elaboration. | |
22049 | @end table | |
22050 | ||
22051 | Let's look at these facilities in more detail. First, the rules for | |
22052 | dynamic checking. One possible rule would be simply to say that the | |
22053 | exception is raised if you access a variable which has not yet been | |
22054 | elaborated. The trouble with this approach is that it could require | |
22055 | expensive checks on every variable reference. Instead Ada 95 has two | |
22056 | rules which are a little more restrictive, but easier to check, and | |
22057 | easier to state: | |
22058 | ||
22059 | @table @asis | |
22060 | @item Restrictions on calls | |
22061 | A subprogram can only be called at elaboration time if its body | |
22062 | has been elaborated. The rules for elaboration given above guarantee | |
22063 | that the spec of the subprogram has been elaborated before the | |
22064 | call, but not the body. If this rule is violated, then the | |
22065 | exception @code{Program_Error} is raised. | |
22066 | ||
22067 | @item Restrictions on instantiations | |
22068 | A generic unit can only be instantiated if the body of the generic | |
22069 | unit has been elaborated. Again, the rules for elaboration given above | |
22070 | guarantee that the spec of the generic unit has been elaborated | |
22071 | before the instantiation, but not the body. If this rule is | |
22072 | violated, then the exception @code{Program_Error} is raised. | |
22073 | @end table | |
88e1739c FW |
22074 | |
22075 | @noindent | |
7cd4527e AC |
22076 | The idea is that if the body has been elaborated, then any variables |
22077 | it references must have been elaborated; by checking for the body being | |
22078 | elaborated we guarantee that none of its references causes any | |
22079 | trouble. As we noted above, this is a little too restrictive, because a | |
22080 | subprogram that has no non-local references in its body may in fact be safe | |
22081 | to call. However, it really would be unsafe to rely on this, because | |
22082 | it would mean that the caller was aware of details of the implementation | |
22083 | in the body. This goes against the basic tenets of Ada. | |
22084 | ||
22085 | A plausible implementation can be described as follows. | |
22086 | A Boolean variable is associated with each subprogram | |
22087 | and each generic unit. This variable is initialized to False, and is set to | |
22088 | True at the point body is elaborated. Every call or instantiation checks the | |
22089 | variable, and raises @code{Program_Error} if the variable is False. | |
22090 | ||
22091 | Note that one might think that it would be good enough to have one Boolean | |
22092 | variable for each package, but that would not deal with cases of trying | |
22093 | to call a body in the same package as the call | |
22094 | that has not been elaborated yet. | |
22095 | Of course a compiler may be able to do enough analysis to optimize away | |
22096 | some of the Boolean variables as unnecessary, and @code{GNAT} indeed | |
22097 | does such optimizations, but still the easiest conceptual model is to | |
22098 | think of there being one variable per subprogram. | |
22099 | ||
22100 | @node Controlling the Elaboration Order in Ada 95 | |
22101 | @section Controlling the Elaboration Order in Ada 95 | |
88e1739c | 22102 | |
88e1739c | 22103 | @noindent |
7cd4527e AC |
22104 | In the previous section we discussed the rules in Ada 95 which ensure |
22105 | that @code{Program_Error} is raised if an incorrect elaboration order is | |
22106 | chosen. This prevents erroneous executions, but we need mechanisms to | |
22107 | specify a correct execution and avoid the exception altogether. | |
22108 | To achieve this, Ada 95 provides a number of features for controlling | |
22109 | the order of elaboration. We discuss these features in this section. | |
88e1739c | 22110 | |
7cd4527e AC |
22111 | First, there are several ways of indicating to the compiler that a given |
22112 | unit has no elaboration problems: | |
88e1739c | 22113 | |
7cd4527e AC |
22114 | @table @asis |
22115 | @item packages that do not require a body | |
22116 | In Ada 95, a library package that does not require a body does not permit | |
22117 | a body. This means that if we have a such a package, as in: | |
22118 | ||
22119 | @smallexample @c ada | |
88e1739c | 22120 | @group |
7cd4527e AC |
22121 | @cartouche |
22122 | package Definitions is | |
22123 | generic | |
22124 | type m is new integer; | |
22125 | package Subp is | |
22126 | type a is array (1 .. 10) of m; | |
22127 | type b is array (1 .. 20) of m; | |
22128 | end Subp; | |
22129 | end Definitions; | |
22130 | @end cartouche | |
88e1739c FW |
22131 | @end group |
22132 | @end smallexample | |
22133 | ||
7cd4527e AC |
22134 | @noindent |
22135 | A package that @code{with}'s @code{Definitions} may safely instantiate | |
22136 | @code{Definitions.Subp} because the compiler can determine that there | |
22137 | definitely is no package body to worry about in this case | |
88e1739c | 22138 | |
7cd4527e AC |
22139 | @item pragma Pure |
22140 | @cindex pragma Pure | |
22141 | @findex Pure | |
22142 | Places sufficient restrictions on a unit to guarantee that | |
22143 | no call to any subprogram in the unit can result in an | |
22144 | elaboration problem. This means that the compiler does not need | |
22145 | to worry about the point of elaboration of such units, and in | |
22146 | particular, does not need to check any calls to any subprograms | |
22147 | in this unit. | |
88e1739c | 22148 | |
7cd4527e AC |
22149 | @item pragma Preelaborate |
22150 | @findex Preelaborate | |
22151 | @cindex pragma Preelaborate | |
22152 | This pragma places slightly less stringent restrictions on a unit than | |
22153 | does pragma Pure, | |
22154 | but these restrictions are still sufficient to ensure that there | |
22155 | are no elaboration problems with any calls to the unit. | |
88e1739c | 22156 | |
7cd4527e AC |
22157 | @item pragma Elaborate_Body |
22158 | @findex Elaborate_Body | |
22159 | @cindex pragma Elaborate_Body | |
22160 | This pragma requires that the body of a unit be elaborated immediately | |
22161 | after its spec. Suppose a unit @code{A} has such a pragma, | |
22162 | and unit @code{B} does | |
22163 | a @code{with} of unit @code{A}. Recall that the standard rules require | |
22164 | the spec of unit @code{A} | |
22165 | to be elaborated before the @code{with}'ing unit; given the pragma in | |
22166 | @code{A}, we also know that the body of @code{A} | |
22167 | will be elaborated before @code{B}, so | |
22168 | that calls to @code{A} are safe and do not need a check. | |
22169 | @end table | |
88e1739c | 22170 | |
7cd4527e AC |
22171 | @noindent |
22172 | Note that, | |
22173 | unlike pragma @code{Pure} and pragma @code{Preelaborate}, | |
22174 | the use of | |
22175 | @code{Elaborate_Body} does not guarantee that the program is | |
22176 | free of elaboration problems, because it may not be possible | |
22177 | to satisfy the requested elaboration order. | |
22178 | Let's go back to the example with @code{Unit_1} and @code{Unit_2}. | |
22179 | If a programmer | |
22180 | marks @code{Unit_1} as @code{Elaborate_Body}, | |
22181 | and not @code{Unit_2,} then the order of | |
22182 | elaboration will be: | |
88e1739c FW |
22183 | |
22184 | @smallexample | |
22185 | @group | |
7cd4527e AC |
22186 | Spec of Unit_2 |
22187 | Spec of Unit_1 | |
22188 | Body of Unit_1 | |
22189 | Body of Unit_2 | |
88e1739c FW |
22190 | @end group |
22191 | @end smallexample | |
22192 | ||
88e1739c | 22193 | @noindent |
7cd4527e AC |
22194 | Now that means that the call to @code{Func_1} in @code{Unit_2} |
22195 | need not be checked, | |
22196 | it must be safe. But the call to @code{Func_2} in | |
22197 | @code{Unit_1} may still fail if | |
22198 | @code{Expression_1} is equal to 1, | |
22199 | and the programmer must still take | |
22200 | responsibility for this not being the case. | |
88e1739c | 22201 | |
7cd4527e AC |
22202 | If all units carry a pragma @code{Elaborate_Body}, then all problems are |
22203 | eliminated, except for calls entirely within a body, which are | |
22204 | in any case fully under programmer control. However, using the pragma | |
22205 | everywhere is not always possible. | |
22206 | In particular, for our @code{Unit_1}/@code{Unit_2} example, if | |
22207 | we marked both of them as having pragma @code{Elaborate_Body}, then | |
22208 | clearly there would be no possible elaboration order. | |
88e1739c | 22209 | |
7cd4527e AC |
22210 | The above pragmas allow a server to guarantee safe use by clients, and |
22211 | clearly this is the preferable approach. Consequently a good rule in | |
22212 | Ada 95 is to mark units as @code{Pure} or @code{Preelaborate} if possible, | |
22213 | and if this is not possible, | |
22214 | mark them as @code{Elaborate_Body} if possible. | |
22215 | As we have seen, there are situations where neither of these | |
22216 | three pragmas can be used. | |
22217 | So we also provide methods for clients to control the | |
22218 | order of elaboration of the servers on which they depend: | |
88e1739c | 22219 | |
7cd4527e AC |
22220 | @table @asis |
22221 | @item pragma Elaborate (unit) | |
22222 | @findex Elaborate | |
22223 | @cindex pragma Elaborate | |
22224 | This pragma is placed in the context clause, after a @code{with} clause, | |
22225 | and it requires that the body of the named unit be elaborated before | |
22226 | the unit in which the pragma occurs. The idea is to use this pragma | |
22227 | if the current unit calls at elaboration time, directly or indirectly, | |
22228 | some subprogram in the named unit. | |
88e1739c | 22229 | |
7cd4527e AC |
22230 | @item pragma Elaborate_All (unit) |
22231 | @findex Elaborate_All | |
22232 | @cindex pragma Elaborate_All | |
22233 | This is a stronger version of the Elaborate pragma. Consider the | |
22234 | following example: | |
88e1739c FW |
22235 | |
22236 | @smallexample | |
7cd4527e AC |
22237 | Unit A @code{with}'s unit B and calls B.Func in elab code |
22238 | Unit B @code{with}'s unit C, and B.Func calls C.Func | |
22239 | @end smallexample | |
88e1739c | 22240 | |
7cd4527e AC |
22241 | @noindent |
22242 | Now if we put a pragma @code{Elaborate (B)} | |
22243 | in unit @code{A}, this ensures that the | |
22244 | body of @code{B} is elaborated before the call, but not the | |
22245 | body of @code{C}, so | |
22246 | the call to @code{C.Func} could still cause @code{Program_Error} to | |
22247 | be raised. | |
88e1739c | 22248 | |
7cd4527e AC |
22249 | The effect of a pragma @code{Elaborate_All} is stronger, it requires |
22250 | not only that the body of the named unit be elaborated before the | |
22251 | unit doing the @code{with}, but also the bodies of all units that the | |
22252 | named unit uses, following @code{with} links transitively. For example, | |
22253 | if we put a pragma @code{Elaborate_All (B)} in unit @code{A}, | |
22254 | then it requires | |
22255 | not only that the body of @code{B} be elaborated before @code{A}, | |
22256 | but also the | |
22257 | body of @code{C}, because @code{B} @code{with}'s @code{C}. | |
22258 | @end table | |
88e1739c | 22259 | |
7cd4527e AC |
22260 | @noindent |
22261 | We are now in a position to give a usage rule in Ada 95 for avoiding | |
22262 | elaboration problems, at least if dynamic dispatching and access to | |
22263 | subprogram values are not used. We will handle these cases separately | |
22264 | later. | |
88e1739c | 22265 | |
7cd4527e AC |
22266 | The rule is simple. If a unit has elaboration code that can directly or |
22267 | indirectly make a call to a subprogram in a @code{with}'ed unit, or instantiate | |
22268 | a generic unit in a @code{with}'ed unit, | |
22269 | then if the @code{with}'ed unit does not have | |
22270 | pragma @code{Pure} or @code{Preelaborate}, then the client should have | |
22271 | a pragma @code{Elaborate_All} | |
22272 | for the @code{with}'ed unit. By following this rule a client is | |
22273 | assured that calls can be made without risk of an exception. | |
22274 | If this rule is not followed, then a program may be in one of four | |
22275 | states: | |
88e1739c | 22276 | |
7cd4527e AC |
22277 | @table @asis |
22278 | @item No order exists | |
22279 | No order of elaboration exists which follows the rules, taking into | |
22280 | account any @code{Elaborate}, @code{Elaborate_All}, | |
22281 | or @code{Elaborate_Body} pragmas. In | |
22282 | this case, an Ada 95 compiler must diagnose the situation at bind | |
22283 | time, and refuse to build an executable program. | |
88e1739c | 22284 | |
7cd4527e AC |
22285 | @item One or more orders exist, all incorrect |
22286 | One or more acceptable elaboration orders exists, and all of them | |
22287 | generate an elaboration order problem. In this case, the binder | |
22288 | can build an executable program, but @code{Program_Error} will be raised | |
22289 | when the program is run. | |
88e1739c | 22290 | |
7cd4527e AC |
22291 | @item Several orders exist, some right, some incorrect |
22292 | One or more acceptable elaboration orders exists, and some of them | |
22293 | work, and some do not. The programmer has not controlled | |
22294 | the order of elaboration, so the binder may or may not pick one of | |
22295 | the correct orders, and the program may or may not raise an | |
22296 | exception when it is run. This is the worst case, because it means | |
22297 | that the program may fail when moved to another compiler, or even | |
22298 | another version of the same compiler. | |
88e1739c | 22299 | |
7cd4527e AC |
22300 | @item One or more orders exists, all correct |
22301 | One ore more acceptable elaboration orders exist, and all of them | |
22302 | work. In this case the program runs successfully. This state of | |
22303 | affairs can be guaranteed by following the rule we gave above, but | |
22304 | may be true even if the rule is not followed. | |
22305 | @end table | |
88e1739c | 22306 | |
7cd4527e AC |
22307 | @noindent |
22308 | Note that one additional advantage of following our Elaborate_All rule | |
22309 | is that the program continues to stay in the ideal (all orders OK) state | |
22310 | even if maintenance | |
22311 | changes some bodies of some subprograms. Conversely, if a program that does | |
22312 | not follow this rule happens to be safe at some point, this state of affairs | |
22313 | may deteriorate silently as a result of maintenance changes. | |
88e1739c | 22314 | |
7cd4527e AC |
22315 | You may have noticed that the above discussion did not mention |
22316 | the use of @code{Elaborate_Body}. This was a deliberate omission. If you | |
22317 | @code{with} an @code{Elaborate_Body} unit, it still may be the case that | |
22318 | code in the body makes calls to some other unit, so it is still necessary | |
22319 | to use @code{Elaborate_All} on such units. | |
88e1739c | 22320 | |
7cd4527e AC |
22321 | @node Controlling Elaboration in GNAT - Internal Calls |
22322 | @section Controlling Elaboration in GNAT - Internal Calls | |
88e1739c | 22323 | |
7cd4527e AC |
22324 | @noindent |
22325 | In the case of internal calls, i.e. calls within a single package, the | |
22326 | programmer has full control over the order of elaboration, and it is up | |
22327 | to the programmer to elaborate declarations in an appropriate order. For | |
22328 | example writing: | |
88e1739c | 22329 | |
7cd4527e AC |
22330 | @smallexample @c ada |
22331 | @group | |
22332 | @cartouche | |
22333 | function One return Float; | |
88e1739c | 22334 | |
7cd4527e | 22335 | Q : Float := One; |
88e1739c | 22336 | |
7cd4527e AC |
22337 | function One return Float is |
22338 | begin | |
22339 | return 1.0; | |
22340 | end One; | |
22341 | @end cartouche | |
22342 | @end group | |
22343 | @end smallexample | |
88e1739c | 22344 | |
7cd4527e AC |
22345 | @noindent |
22346 | will obviously raise @code{Program_Error} at run time, because function | |
22347 | One will be called before its body is elaborated. In this case GNAT will | |
22348 | generate a warning that the call will raise @code{Program_Error}: | |
22349 | ||
22350 | @smallexample | |
22351 | @group | |
22352 | @cartouche | |
22353 | 1. procedure y is | |
22354 | 2. function One return Float; | |
22355 | 3. | |
22356 | 4. Q : Float := One; | |
22357 | | | |
22358 | >>> warning: cannot call "One" before body is elaborated | |
22359 | >>> warning: Program_Error will be raised at run time | |
88e1739c | 22360 | |
7cd4527e AC |
22361 | 5. |
22362 | 6. function One return Float is | |
22363 | 7. begin | |
22364 | 8. return 1.0; | |
22365 | 9. end One; | |
22366 | 10. | |
22367 | 11. begin | |
22368 | 12. null; | |
22369 | 13. end; | |
22370 | @end cartouche | |
22371 | @end group | |
22372 | @end smallexample | |
88e1739c | 22373 | |
7cd4527e AC |
22374 | @noindent |
22375 | Note that in this particular case, it is likely that the call is safe, because | |
22376 | the function @code{One} does not access any global variables. | |
22377 | Nevertheless in Ada 95, we do not want the validity of the check to depend on | |
22378 | the contents of the body (think about the separate compilation case), so this | |
22379 | is still wrong, as we discussed in the previous sections. | |
88e1739c | 22380 | |
7cd4527e AC |
22381 | The error is easily corrected by rearranging the declarations so that the |
22382 | body of One appears before the declaration containing the call | |
22383 | (note that in Ada 95, | |
22384 | declarations can appear in any order, so there is no restriction that | |
22385 | would prevent this reordering, and if we write: | |
88e1739c | 22386 | |
7cd4527e AC |
22387 | @smallexample @c ada |
22388 | @group | |
22389 | @cartouche | |
22390 | function One return Float; | |
88e1739c | 22391 | |
7cd4527e AC |
22392 | function One return Float is |
22393 | begin | |
22394 | return 1.0; | |
22395 | end One; | |
88e1739c | 22396 | |
7cd4527e AC |
22397 | Q : Float := One; |
22398 | @end cartouche | |
22399 | @end group | |
22400 | @end smallexample | |
88e1739c | 22401 | |
7cd4527e AC |
22402 | @noindent |
22403 | then all is well, no warning is generated, and no | |
22404 | @code{Program_Error} exception | |
22405 | will be raised. | |
22406 | Things are more complicated when a chain of subprograms is executed: | |
88e1739c | 22407 | |
7cd4527e AC |
22408 | @smallexample @c ada |
22409 | @group | |
22410 | @cartouche | |
22411 | function A return Integer; | |
22412 | function B return Integer; | |
22413 | function C return Integer; | |
88e1739c | 22414 | |
7cd4527e AC |
22415 | function B return Integer is begin return A; end; |
22416 | function C return Integer is begin return B; end; | |
88e1739c | 22417 | |
7cd4527e | 22418 | X : Integer := C; |
88e1739c | 22419 | |
7cd4527e AC |
22420 | function A return Integer is begin return 1; end; |
22421 | @end cartouche | |
22422 | @end group | |
22423 | @end smallexample | |
88e1739c | 22424 | |
7cd4527e AC |
22425 | @noindent |
22426 | Now the call to @code{C} | |
22427 | at elaboration time in the declaration of @code{X} is correct, because | |
22428 | the body of @code{C} is already elaborated, | |
22429 | and the call to @code{B} within the body of | |
22430 | @code{C} is correct, but the call | |
22431 | to @code{A} within the body of @code{B} is incorrect, because the body | |
22432 | of @code{A} has not been elaborated, so @code{Program_Error} | |
22433 | will be raised on the call to @code{A}. | |
22434 | In this case GNAT will generate a | |
22435 | warning that @code{Program_Error} may be | |
22436 | raised at the point of the call. Let's look at the warning: | |
88e1739c | 22437 | |
7cd4527e AC |
22438 | @smallexample |
22439 | @group | |
22440 | @cartouche | |
22441 | 1. procedure x is | |
22442 | 2. function A return Integer; | |
22443 | 3. function B return Integer; | |
22444 | 4. function C return Integer; | |
22445 | 5. | |
22446 | 6. function B return Integer is begin return A; end; | |
22447 | | | |
22448 | >>> warning: call to "A" before body is elaborated may | |
22449 | raise Program_Error | |
22450 | >>> warning: "B" called at line 7 | |
22451 | >>> warning: "C" called at line 9 | |
88e1739c | 22452 | |
7cd4527e AC |
22453 | 7. function C return Integer is begin return B; end; |
22454 | 8. | |
22455 | 9. X : Integer := C; | |
22456 | 10. | |
22457 | 11. function A return Integer is begin return 1; end; | |
22458 | 12. | |
22459 | 13. begin | |
22460 | 14. null; | |
22461 | 15. end; | |
22462 | @end cartouche | |
22463 | @end group | |
22464 | @end smallexample | |
88e1739c | 22465 | |
7cd4527e AC |
22466 | @noindent |
22467 | Note that the message here says ``may raise'', instead of the direct case, | |
22468 | where the message says ``will be raised''. That's because whether | |
22469 | @code{A} is | |
22470 | actually called depends in general on run-time flow of control. | |
22471 | For example, if the body of @code{B} said | |
88e1739c | 22472 | |
7cd4527e AC |
22473 | @smallexample @c ada |
22474 | @group | |
22475 | @cartouche | |
22476 | function B return Integer is | |
22477 | begin | |
22478 | if some-condition-depending-on-input-data then | |
22479 | return A; | |
22480 | else | |
22481 | return 1; | |
88e1739c | 22482 | end if; |
7cd4527e AC |
22483 | end B; |
22484 | @end cartouche | |
22485 | @end group | |
22486 | @end smallexample | |
88e1739c | 22487 | |
7cd4527e AC |
22488 | @noindent |
22489 | then we could not know until run time whether the incorrect call to A would | |
22490 | actually occur, so @code{Program_Error} might | |
22491 | or might not be raised. It is possible for a compiler to | |
22492 | do a better job of analyzing bodies, to | |
22493 | determine whether or not @code{Program_Error} | |
22494 | might be raised, but it certainly | |
22495 | couldn't do a perfect job (that would require solving the halting problem | |
22496 | and is provably impossible), and because this is a warning anyway, it does | |
22497 | not seem worth the effort to do the analysis. Cases in which it | |
22498 | would be relevant are rare. | |
88e1739c | 22499 | |
7cd4527e AC |
22500 | In practice, warnings of either of the forms given |
22501 | above will usually correspond to | |
22502 | real errors, and should be examined carefully and eliminated. | |
22503 | In the rare case where a warning is bogus, it can be suppressed by any of | |
22504 | the following methods: | |
88e1739c | 22505 | |
7cd4527e AC |
22506 | @itemize @bullet |
22507 | @item | |
22508 | Compile with the @option{-gnatws} switch set | |
88e1739c | 22509 | |
7cd4527e AC |
22510 | @item |
22511 | Suppress @code{Elaboration_Check} for the called subprogram | |
88e1739c | 22512 | |
7cd4527e AC |
22513 | @item |
22514 | Use pragma @code{Warnings_Off} to turn warnings off for the call | |
22515 | @end itemize | |
88e1739c | 22516 | |
7cd4527e AC |
22517 | @noindent |
22518 | For the internal elaboration check case, | |
22519 | GNAT by default generates the | |
22520 | necessary run-time checks to ensure | |
22521 | that @code{Program_Error} is raised if any | |
22522 | call fails an elaboration check. Of course this can only happen if a | |
22523 | warning has been issued as described above. The use of pragma | |
22524 | @code{Suppress (Elaboration_Check)} may (but is not guaranteed to) suppress | |
22525 | some of these checks, meaning that it may be possible (but is not | |
22526 | guaranteed) for a program to be able to call a subprogram whose body | |
22527 | is not yet elaborated, without raising a @code{Program_Error} exception. | |
88e1739c | 22528 | |
7cd4527e AC |
22529 | @node Controlling Elaboration in GNAT - External Calls |
22530 | @section Controlling Elaboration in GNAT - External Calls | |
88e1739c | 22531 | |
7cd4527e AC |
22532 | @noindent |
22533 | The previous section discussed the case in which the execution of a | |
22534 | particular thread of elaboration code occurred entirely within a | |
22535 | single unit. This is the easy case to handle, because a programmer | |
22536 | has direct and total control over the order of elaboration, and | |
22537 | furthermore, checks need only be generated in cases which are rare | |
22538 | and which the compiler can easily detect. | |
22539 | The situation is more complex when separate compilation is taken into account. | |
22540 | Consider the following: | |
88e1739c | 22541 | |
7cd4527e AC |
22542 | @smallexample @c ada |
22543 | @cartouche | |
22544 | @group | |
22545 | package Math is | |
22546 | function Sqrt (Arg : Float) return Float; | |
22547 | end Math; | |
88e1739c | 22548 | |
7cd4527e AC |
22549 | package body Math is |
22550 | function Sqrt (Arg : Float) return Float is | |
22551 | begin | |
22552 | ... | |
22553 | end Sqrt; | |
22554 | end Math; | |
22555 | @end group | |
22556 | @group | |
22557 | with Math; | |
22558 | package Stuff is | |
22559 | X : Float := Math.Sqrt (0.5); | |
22560 | end Stuff; | |
88e1739c | 22561 | |
7cd4527e AC |
22562 | with Stuff; |
22563 | procedure Main is | |
22564 | begin | |
22565 | ... | |
22566 | end Main; | |
22567 | @end group | |
22568 | @end cartouche | |
22569 | @end smallexample | |
88e1739c | 22570 | |
7cd4527e AC |
22571 | @noindent |
22572 | where @code{Main} is the main program. When this program is executed, the | |
22573 | elaboration code must first be executed, and one of the jobs of the | |
22574 | binder is to determine the order in which the units of a program are | |
22575 | to be elaborated. In this case we have four units: the spec and body | |
22576 | of @code{Math}, | |
22577 | the spec of @code{Stuff} and the body of @code{Main}). | |
22578 | In what order should the four separate sections of elaboration code | |
22579 | be executed? | |
88e1739c | 22580 | |
7cd4527e AC |
22581 | There are some restrictions in the order of elaboration that the binder |
22582 | can choose. In particular, if unit U has a @code{with} | |
22583 | for a package @code{X}, then you | |
22584 | are assured that the spec of @code{X} | |
22585 | is elaborated before U , but you are | |
22586 | not assured that the body of @code{X} | |
22587 | is elaborated before U. | |
22588 | This means that in the above case, the binder is allowed to choose the | |
22589 | order: | |
88e1739c | 22590 | |
7cd4527e AC |
22591 | @smallexample |
22592 | spec of Math | |
22593 | spec of Stuff | |
22594 | body of Math | |
22595 | body of Main | |
22596 | @end smallexample | |
88e1739c | 22597 | |
7cd4527e AC |
22598 | @noindent |
22599 | but that's not good, because now the call to @code{Math.Sqrt} | |
22600 | that happens during | |
22601 | the elaboration of the @code{Stuff} | |
22602 | spec happens before the body of @code{Math.Sqrt} is | |
22603 | elaborated, and hence causes @code{Program_Error} exception to be raised. | |
22604 | At first glance, one might say that the binder is misbehaving, because | |
22605 | obviously you want to elaborate the body of something you @code{with} | |
22606 | first, but | |
22607 | that is not a general rule that can be followed in all cases. Consider | |
88e1739c | 22608 | |
7cd4527e AC |
22609 | @smallexample @c ada |
22610 | @group | |
22611 | @cartouche | |
22612 | package X is ... | |
88e1739c | 22613 | |
7cd4527e | 22614 | package Y is ... |
88e1739c | 22615 | |
7cd4527e AC |
22616 | with X; |
22617 | package body Y is ... | |
88e1739c | 22618 | |
7cd4527e AC |
22619 | with Y; |
22620 | package body X is ... | |
22621 | @end cartouche | |
22622 | @end group | |
22623 | @end smallexample | |
88e1739c | 22624 | |
7cd4527e AC |
22625 | @noindent |
22626 | This is a common arrangement, and, apart from the order of elaboration | |
22627 | problems that might arise in connection with elaboration code, this works fine. | |
22628 | A rule that says that you must first elaborate the body of anything you | |
22629 | @code{with} cannot work in this case: | |
22630 | the body of @code{X} @code{with}'s @code{Y}, | |
22631 | which means you would have to | |
22632 | elaborate the body of @code{Y} first, but that @code{with}'s @code{X}, | |
22633 | which means | |
22634 | you have to elaborate the body of @code{X} first, but ... and we have a | |
22635 | loop that cannot be broken. | |
88e1739c | 22636 | |
7cd4527e AC |
22637 | It is true that the binder can in many cases guess an order of elaboration |
22638 | that is unlikely to cause a @code{Program_Error} | |
22639 | exception to be raised, and it tries to do so (in the | |
22640 | above example of @code{Math/Stuff/Spec}, the GNAT binder will | |
22641 | by default | |
22642 | elaborate the body of @code{Math} right after its spec, so all will be well). | |
88e1739c | 22643 | |
7cd4527e AC |
22644 | However, a program that blindly relies on the binder to be helpful can |
22645 | get into trouble, as we discussed in the previous sections, so | |
22646 | GNAT | |
22647 | provides a number of facilities for assisting the programmer in | |
22648 | developing programs that are robust with respect to elaboration order. | |
88e1739c | 22649 | |
7cd4527e AC |
22650 | @node Default Behavior in GNAT - Ensuring Safety |
22651 | @section Default Behavior in GNAT - Ensuring Safety | |
88e1739c | 22652 | |
7cd4527e AC |
22653 | @noindent |
22654 | The default behavior in GNAT ensures elaboration safety. In its | |
22655 | default mode GNAT implements the | |
22656 | rule we previously described as the right approach. Let's restate it: | |
88e1739c | 22657 | |
7cd4527e AC |
22658 | @itemize |
22659 | @item | |
22660 | @emph{If a unit has elaboration code that can directly or indirectly make a | |
22661 | call to a subprogram in a @code{with}'ed unit, or instantiate a generic unit | |
22662 | in a @code{with}'ed unit, then if the @code{with}'ed unit | |
22663 | does not have pragma @code{Pure} or | |
22664 | @code{Preelaborate}, then the client should have an | |
22665 | @code{Elaborate_All} for the @code{with}'ed unit.} | |
22666 | @end itemize | |
88e1739c | 22667 | |
7cd4527e AC |
22668 | @noindent |
22669 | By following this rule a client is assured that calls and instantiations | |
22670 | can be made without risk of an exception. | |
88e1739c | 22671 | |
7cd4527e AC |
22672 | In this mode GNAT traces all calls that are potentially made from |
22673 | elaboration code, and puts in any missing implicit @code{Elaborate_All} | |
22674 | pragmas. | |
22675 | The advantage of this approach is that no elaboration problems | |
22676 | are possible if the binder can find an elaboration order that is | |
22677 | consistent with these implicit @code{Elaborate_All} pragmas. The | |
22678 | disadvantage of this approach is that no such order may exist. | |
88e1739c | 22679 | |
7cd4527e AC |
22680 | If the binder does not generate any diagnostics, then it means that it |
22681 | has found an elaboration order that is guaranteed to be safe. However, | |
22682 | the binder may still be relying on implicitly generated | |
22683 | @code{Elaborate_All} pragmas so portability to other compilers than | |
22684 | GNAT is not guaranteed. | |
88e1739c | 22685 | |
7cd4527e AC |
22686 | If it is important to guarantee portability, then the compilations should |
22687 | use the | |
22688 | @option{-gnatwl} | |
22689 | (warn on elaboration problems) switch. This will cause warning messages | |
22690 | to be generated indicating the missing @code{Elaborate_All} pragmas. | |
22691 | Consider the following source program: | |
88e1739c | 22692 | |
7cd4527e AC |
22693 | @smallexample @c ada |
22694 | @group | |
22695 | @cartouche | |
22696 | with k; | |
22697 | package j is | |
22698 | m : integer := k.r; | |
22699 | end; | |
22700 | @end cartouche | |
22701 | @end group | |
22702 | @end smallexample | |
88e1739c | 22703 | |
7cd4527e AC |
22704 | @noindent |
22705 | where it is clear that there | |
22706 | should be a pragma @code{Elaborate_All} | |
22707 | for unit @code{k}. An implicit pragma will be generated, and it is | |
22708 | likely that the binder will be able to honor it. However, if you want | |
22709 | to port this program to some other Ada compiler than GNAT. | |
22710 | it is safer to include the pragma explicitly in the source. If this | |
22711 | unit is compiled with the | |
22712 | @option{-gnatwl} | |
22713 | switch, then the compiler outputs a warning: | |
88e1739c | 22714 | |
7cd4527e AC |
22715 | @smallexample |
22716 | @group | |
22717 | @cartouche | |
22718 | 1. with k; | |
22719 | 2. package j is | |
22720 | 3. m : integer := k.r; | |
22721 | | | |
22722 | >>> warning: call to "r" may raise Program_Error | |
22723 | >>> warning: missing pragma Elaborate_All for "k" | |
88e1739c | 22724 | |
7cd4527e AC |
22725 | 4. end; |
22726 | @end cartouche | |
22727 | @end group | |
22728 | @end smallexample | |
88e1739c | 22729 | |
7cd4527e AC |
22730 | @noindent |
22731 | and these warnings can be used as a guide for supplying manually | |
22732 | the missing pragmas. It is usually a bad idea to use this warning | |
22733 | option during development. That's because it will warn you when | |
22734 | you need to put in a pragma, but cannot warn you when it is time | |
22735 | to take it out. So the use of pragma Elaborate_All may lead to | |
22736 | unnecessary dependencies and even false circularities. | |
88e1739c | 22737 | |
7cd4527e AC |
22738 | This default mode is more restrictive than the Ada Reference |
22739 | Manual, and it is possible to construct programs which will compile | |
22740 | using the dynamic model described there, but will run into a | |
22741 | circularity using the safer static model we have described. | |
88e1739c | 22742 | |
7cd4527e AC |
22743 | Of course any Ada compiler must be able to operate in a mode |
22744 | consistent with the requirements of the Ada Reference Manual, | |
22745 | and in particular must have the capability of implementing the | |
22746 | standard dynamic model of elaboration with run-time checks. | |
88e1739c | 22747 | |
7cd4527e AC |
22748 | In GNAT, this standard mode can be achieved either by the use of |
22749 | the @option{-gnatE} switch on the compiler (@code{gcc} or @code{gnatmake}) | |
22750 | command, or by the use of the configuration pragma: | |
88e1739c | 22751 | |
7cd4527e AC |
22752 | @smallexample @c ada |
22753 | pragma Elaboration_Checks (RM); | |
22754 | @end smallexample | |
88e1739c | 22755 | |
7cd4527e AC |
22756 | @noindent |
22757 | Either approach will cause the unit affected to be compiled using the | |
22758 | standard dynamic run-time elaboration checks described in the Ada | |
22759 | Reference Manual. The static model is generally preferable, since it | |
22760 | is clearly safer to rely on compile and link time checks rather than | |
22761 | run-time checks. However, in the case of legacy code, it may be | |
22762 | difficult to meet the requirements of the static model. This | |
22763 | issue is further discussed in | |
22764 | @ref{What to Do If the Default Elaboration Behavior Fails}. | |
88e1739c | 22765 | |
7cd4527e AC |
22766 | Note that the static model provides a strict subset of the allowed |
22767 | behavior and programs of the Ada Reference Manual, so if you do | |
22768 | adhere to the static model and no circularities exist, | |
22769 | then you are assured that your program will | |
22770 | work using the dynamic model, providing that you remove any | |
22771 | pragma Elaborate statements from the source. | |
22772 | ||
22773 | @node Treatment of Pragma Elaborate | |
22774 | @section Treatment of Pragma Elaborate | |
22775 | @cindex Pragma Elaborate | |
22776 | ||
22777 | @noindent | |
22778 | The use of @code{pragma Elaborate} | |
22779 | should generally be avoided in Ada 95 programs. | |
22780 | The reason for this is that there is no guarantee that transitive calls | |
22781 | will be properly handled. Indeed at one point, this pragma was placed | |
22782 | in Annex J (Obsolescent Features), on the grounds that it is never useful. | |
22783 | ||
22784 | Now that's a bit restrictive. In practice, the case in which | |
22785 | @code{pragma Elaborate} is useful is when the caller knows that there | |
22786 | are no transitive calls, or that the called unit contains all necessary | |
22787 | transitive @code{pragma Elaborate} statements, and legacy code often | |
22788 | contains such uses. | |
22789 | ||
22790 | Strictly speaking the static mode in GNAT should ignore such pragmas, | |
22791 | since there is no assurance at compile time that the necessary safety | |
22792 | conditions are met. In practice, this would cause GNAT to be incompatible | |
22793 | with correctly written Ada 83 code that had all necessary | |
22794 | @code{pragma Elaborate} statements in place. Consequently, we made the | |
22795 | decision that GNAT in its default mode will believe that if it encounters | |
22796 | a @code{pragma Elaborate} then the programmer knows what they are doing, | |
22797 | and it will trust that no elaboration errors can occur. | |
22798 | ||
22799 | The result of this decision is two-fold. First to be safe using the | |
22800 | static mode, you should remove all @code{pragma Elaborate} statements. | |
22801 | Second, when fixing circularities in existing code, you can selectively | |
22802 | use @code{pragma Elaborate} statements to convince the static mode of | |
22803 | GNAT that it need not generate an implicit @code{pragma Elaborate_All} | |
22804 | statement. | |
22805 | ||
22806 | When using the static mode with @option{-gnatwl}, any use of | |
22807 | @code{pragma Elaborate} will generate a warning about possible | |
22808 | problems. | |
88e1739c | 22809 | |
7cd4527e AC |
22810 | @node Elaboration Issues for Library Tasks |
22811 | @section Elaboration Issues for Library Tasks | |
22812 | @cindex Library tasks, elaboration issues | |
22813 | @cindex Elaboration of library tasks | |
88e1739c | 22814 | |
7cd4527e AC |
22815 | @noindent |
22816 | In this section we examine special elaboration issues that arise for | |
22817 | programs that declare library level tasks. | |
88e1739c | 22818 | |
7cd4527e AC |
22819 | Generally the model of execution of an Ada program is that all units are |
22820 | elaborated, and then execution of the program starts. However, the | |
22821 | declaration of library tasks definitely does not fit this model. The | |
22822 | reason for this is that library tasks start as soon as they are declared | |
22823 | (more precisely, as soon as the statement part of the enclosing package | |
22824 | body is reached), that is to say before elaboration | |
22825 | of the program is complete. This means that if such a task calls a | |
22826 | subprogram, or an entry in another task, the callee may or may not be | |
22827 | elaborated yet, and in the standard | |
22828 | Reference Manual model of dynamic elaboration checks, you can even | |
22829 | get timing dependent Program_Error exceptions, since there can be | |
22830 | a race between the elaboration code and the task code. | |
88e1739c | 22831 | |
7cd4527e AC |
22832 | The static model of elaboration in GNAT seeks to avoid all such |
22833 | dynamic behavior, by being conservative, and the conservative | |
22834 | approach in this particular case is to assume that all the code | |
22835 | in a task body is potentially executed at elaboration time if | |
22836 | a task is declared at the library level. | |
88e1739c | 22837 | |
7cd4527e AC |
22838 | This can definitely result in unexpected circularities. Consider |
22839 | the following example | |
88e1739c | 22840 | |
7cd4527e AC |
22841 | @smallexample @c ada |
22842 | package Decls is | |
22843 | task Lib_Task is | |
22844 | entry Start; | |
22845 | end Lib_Task; | |
88e1739c | 22846 | |
7cd4527e | 22847 | type My_Int is new Integer; |
88e1739c | 22848 | |
7cd4527e AC |
22849 | function Ident (M : My_Int) return My_Int; |
22850 | end Decls; | |
88e1739c | 22851 | |
7cd4527e AC |
22852 | with Utils; |
22853 | package body Decls is | |
22854 | task body Lib_Task is | |
22855 | begin | |
22856 | accept Start; | |
22857 | Utils.Put_Val (2); | |
22858 | end Lib_Task; | |
88e1739c | 22859 | |
7cd4527e AC |
22860 | function Ident (M : My_Int) return My_Int is |
22861 | begin | |
22862 | return M; | |
22863 | end Ident; | |
22864 | end Decls; | |
88e1739c | 22865 | |
7cd4527e AC |
22866 | with Decls; |
22867 | package Utils is | |
22868 | procedure Put_Val (Arg : Decls.My_Int); | |
22869 | end Utils; | |
88e1739c | 22870 | |
7cd4527e AC |
22871 | with Text_IO; |
22872 | package body Utils is | |
22873 | procedure Put_Val (Arg : Decls.My_Int) is | |
22874 | begin | |
22875 | Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); | |
22876 | end Put_Val; | |
22877 | end Utils; | |
88e1739c | 22878 | |
7cd4527e AC |
22879 | with Decls; |
22880 | procedure Main is | |
22881 | begin | |
22882 | Decls.Lib_Task.Start; | |
22883 | end; | |
22884 | @end smallexample | |
88e1739c | 22885 | |
7cd4527e AC |
22886 | @noindent |
22887 | If the above example is compiled in the default static elaboration | |
22888 | mode, then a circularity occurs. The circularity comes from the call | |
22889 | @code{Utils.Put_Val} in the task body of @code{Decls.Lib_Task}. Since | |
22890 | this call occurs in elaboration code, we need an implicit pragma | |
22891 | @code{Elaborate_All} for @code{Utils}. This means that not only must | |
22892 | the spec and body of @code{Utils} be elaborated before the body | |
22893 | of @code{Decls}, but also the spec and body of any unit that is | |
22894 | @code{with'ed} by the body of @code{Utils} must also be elaborated before | |
22895 | the body of @code{Decls}. This is the transitive implication of | |
22896 | pragma @code{Elaborate_All} and it makes sense, because in general | |
22897 | the body of @code{Put_Val} might have a call to something in a | |
22898 | @code{with'ed} unit. | |
88e1739c | 22899 | |
7cd4527e AC |
22900 | In this case, the body of Utils (actually its spec) @code{with's} |
22901 | @code{Decls}. Unfortunately this means that the body of @code{Decls} | |
22902 | must be elaborated before itself, in case there is a call from the | |
22903 | body of @code{Utils}. | |
88e1739c | 22904 | |
7cd4527e | 22905 | Here is the exact chain of events we are worrying about: |
88e1739c | 22906 | |
7cd4527e AC |
22907 | @enumerate |
22908 | @item | |
22909 | In the body of @code{Decls} a call is made from within the body of a library | |
22910 | task to a subprogram in the package @code{Utils}. Since this call may | |
22911 | occur at elaboration time (given that the task is activated at elaboration | |
22912 | time), we have to assume the worst, i.e. that the | |
22913 | call does happen at elaboration time. | |
88e1739c | 22914 | |
7cd4527e AC |
22915 | @item |
22916 | This means that the body and spec of @code{Util} must be elaborated before | |
22917 | the body of @code{Decls} so that this call does not cause an access before | |
22918 | elaboration. | |
88e1739c | 22919 | |
7cd4527e AC |
22920 | @item |
22921 | Within the body of @code{Util}, specifically within the body of | |
22922 | @code{Util.Put_Val} there may be calls to any unit @code{with}'ed | |
22923 | by this package. | |
88e1739c | 22924 | |
7cd4527e AC |
22925 | @item |
22926 | One such @code{with}'ed package is package @code{Decls}, so there | |
22927 | might be a call to a subprogram in @code{Decls} in @code{Put_Val}. | |
22928 | In fact there is such a call in this example, but we would have to | |
22929 | assume that there was such a call even if it were not there, since | |
22930 | we are not supposed to write the body of @code{Decls} knowing what | |
22931 | is in the body of @code{Utils}; certainly in the case of the | |
22932 | static elaboration model, the compiler does not know what is in | |
22933 | other bodies and must assume the worst. | |
88e1739c | 22934 | |
7cd4527e AC |
22935 | @item |
22936 | This means that the spec and body of @code{Decls} must also be | |
22937 | elaborated before we elaborate the unit containing the call, but | |
22938 | that unit is @code{Decls}! This means that the body of @code{Decls} | |
22939 | must be elaborated before itself, and that's a circularity. | |
22940 | @end enumerate | |
88e1739c | 22941 | |
7cd4527e AC |
22942 | @noindent |
22943 | Indeed, if you add an explicit pragma Elaborate_All for @code{Utils} in | |
22944 | the body of @code{Decls} you will get a true Ada Reference Manual | |
22945 | circularity that makes the program illegal. | |
88e1739c | 22946 | |
7cd4527e AC |
22947 | In practice, we have found that problems with the static model of |
22948 | elaboration in existing code often arise from library tasks, so | |
22949 | we must address this particular situation. | |
88e1739c | 22950 | |
7cd4527e AC |
22951 | Note that if we compile and run the program above, using the dynamic model of |
22952 | elaboration (that is to say use the @option{-gnatE} switch), | |
22953 | then it compiles, binds, | |
22954 | links, and runs, printing the expected result of 2. Therefore in some sense | |
22955 | the circularity here is only apparent, and we need to capture | |
22956 | the properties of this program that distinguish it from other library-level | |
22957 | tasks that have real elaboration problems. | |
88e1739c | 22958 | |
7cd4527e | 22959 | We have four possible answers to this question: |
88e1739c | 22960 | |
7cd4527e | 22961 | @itemize @bullet |
88e1739c | 22962 | |
7cd4527e AC |
22963 | @item |
22964 | Use the dynamic model of elaboration. | |
88e1739c | 22965 | |
7cd4527e AC |
22966 | If we use the @option{-gnatE} switch, then as noted above, the program works. |
22967 | Why is this? If we examine the task body, it is apparent that the task cannot | |
22968 | proceed past the | |
22969 | @code{accept} statement until after elaboration has been completed, because | |
22970 | the corresponding entry call comes from the main program, not earlier. | |
22971 | This is why the dynamic model works here. But that's really giving | |
22972 | up on a precise analysis, and we prefer to take this approach only if we cannot | |
22973 | solve the | |
22974 | problem in any other manner. So let us examine two ways to reorganize | |
22975 | the program to avoid the potential elaboration problem. | |
88e1739c | 22976 | |
7cd4527e AC |
22977 | @item |
22978 | Split library tasks into separate packages. | |
88e1739c | 22979 | |
7cd4527e AC |
22980 | Write separate packages, so that library tasks are isolated from |
22981 | other declarations as much as possible. Let us look at a variation on | |
22982 | the above program. | |
88e1739c | 22983 | |
7cd4527e AC |
22984 | @smallexample @c ada |
22985 | package Decls1 is | |
22986 | task Lib_Task is | |
22987 | entry Start; | |
22988 | end Lib_Task; | |
22989 | end Decls1; | |
88e1739c | 22990 | |
7cd4527e AC |
22991 | with Utils; |
22992 | package body Decls1 is | |
22993 | task body Lib_Task is | |
22994 | begin | |
22995 | accept Start; | |
22996 | Utils.Put_Val (2); | |
22997 | end Lib_Task; | |
22998 | end Decls1; | |
88e1739c | 22999 | |
7cd4527e AC |
23000 | package Decls2 is |
23001 | type My_Int is new Integer; | |
23002 | function Ident (M : My_Int) return My_Int; | |
23003 | end Decls2; | |
88e1739c | 23004 | |
7cd4527e AC |
23005 | with Utils; |
23006 | package body Decls2 is | |
23007 | function Ident (M : My_Int) return My_Int is | |
23008 | begin | |
23009 | return M; | |
23010 | end Ident; | |
23011 | end Decls2; | |
88e1739c | 23012 | |
7cd4527e AC |
23013 | with Decls2; |
23014 | package Utils is | |
23015 | procedure Put_Val (Arg : Decls2.My_Int); | |
23016 | end Utils; | |
88e1739c | 23017 | |
7cd4527e AC |
23018 | with Text_IO; |
23019 | package body Utils is | |
23020 | procedure Put_Val (Arg : Decls2.My_Int) is | |
23021 | begin | |
23022 | Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg))); | |
23023 | end Put_Val; | |
23024 | end Utils; | |
88e1739c | 23025 | |
7cd4527e AC |
23026 | with Decls1; |
23027 | procedure Main is | |
23028 | begin | |
23029 | Decls1.Lib_Task.Start; | |
23030 | end; | |
23031 | @end smallexample | |
88e1739c | 23032 | |
7cd4527e AC |
23033 | @noindent |
23034 | All we have done is to split @code{Decls} into two packages, one | |
23035 | containing the library task, and one containing everything else. Now | |
23036 | there is no cycle, and the program compiles, binds, links and executes | |
23037 | using the default static model of elaboration. | |
88e1739c | 23038 | |
7cd4527e AC |
23039 | @item |
23040 | Declare separate task types. | |
88e1739c | 23041 | |
7cd4527e AC |
23042 | A significant part of the problem arises because of the use of the |
23043 | single task declaration form. This means that the elaboration of | |
23044 | the task type, and the elaboration of the task itself (i.e. the | |
23045 | creation of the task) happen at the same time. A good rule | |
23046 | of style in Ada 95 is to always create explicit task types. By | |
23047 | following the additional step of placing task objects in separate | |
23048 | packages from the task type declaration, many elaboration problems | |
23049 | are avoided. Here is another modified example of the example program: | |
88e1739c | 23050 | |
7cd4527e AC |
23051 | @smallexample @c ada |
23052 | package Decls is | |
23053 | task type Lib_Task_Type is | |
23054 | entry Start; | |
23055 | end Lib_Task_Type; | |
88e1739c | 23056 | |
7cd4527e | 23057 | type My_Int is new Integer; |
88e1739c | 23058 | |
7cd4527e AC |
23059 | function Ident (M : My_Int) return My_Int; |
23060 | end Decls; | |
88e1739c | 23061 | |
7cd4527e AC |
23062 | with Utils; |
23063 | package body Decls is | |
23064 | task body Lib_Task_Type is | |
23065 | begin | |
23066 | accept Start; | |
23067 | Utils.Put_Val (2); | |
23068 | end Lib_Task_Type; | |
88e1739c | 23069 | |
7cd4527e AC |
23070 | function Ident (M : My_Int) return My_Int is |
23071 | begin | |
23072 | return M; | |
23073 | end Ident; | |
23074 | end Decls; | |
88e1739c | 23075 | |
7cd4527e AC |
23076 | with Decls; |
23077 | package Utils is | |
23078 | procedure Put_Val (Arg : Decls.My_Int); | |
23079 | end Utils; | |
88e1739c | 23080 | |
7cd4527e AC |
23081 | with Text_IO; |
23082 | package body Utils is | |
23083 | procedure Put_Val (Arg : Decls.My_Int) is | |
23084 | begin | |
23085 | Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); | |
23086 | end Put_Val; | |
23087 | end Utils; | |
88e1739c | 23088 | |
7cd4527e AC |
23089 | with Decls; |
23090 | package Declst is | |
23091 | Lib_Task : Decls.Lib_Task_Type; | |
23092 | end Declst; | |
88e1739c | 23093 | |
7cd4527e AC |
23094 | with Declst; |
23095 | procedure Main is | |
23096 | begin | |
23097 | Declst.Lib_Task.Start; | |
23098 | end; | |
23099 | @end smallexample | |
88e1739c | 23100 | |
7cd4527e AC |
23101 | @noindent |
23102 | What we have done here is to replace the @code{task} declaration in | |
23103 | package @code{Decls} with a @code{task type} declaration. Then we | |
23104 | introduce a separate package @code{Declst} to contain the actual | |
23105 | task object. This separates the elaboration issues for | |
23106 | the @code{task type} | |
23107 | declaration, which causes no trouble, from the elaboration issues | |
23108 | of the task object, which is also unproblematic, since it is now independent | |
23109 | of the elaboration of @code{Utils}. | |
23110 | This separation of concerns also corresponds to | |
23111 | a generally sound engineering principle of separating declarations | |
23112 | from instances. This version of the program also compiles, binds, links, | |
23113 | and executes, generating the expected output. | |
88e1739c | 23114 | |
7cd4527e AC |
23115 | @item |
23116 | Use No_Entry_Calls_In_Elaboration_Code restriction. | |
23117 | @cindex No_Entry_Calls_In_Elaboration_Code | |
23118 | ||
23119 | The previous two approaches described how a program can be restructured | |
23120 | to avoid the special problems caused by library task bodies. in practice, | |
23121 | however, such restructuring may be difficult to apply to existing legacy code, | |
23122 | so we must consider solutions that do not require massive rewriting. | |
88e1739c | 23123 | |
7cd4527e AC |
23124 | Let us consider more carefully why our original sample program works |
23125 | under the dynamic model of elaboration. The reason is that the code | |
23126 | in the task body blocks immediately on the @code{accept} | |
23127 | statement. Now of course there is nothing to prohibit elaboration | |
23128 | code from making entry calls (for example from another library level task), | |
23129 | so we cannot tell in isolation that | |
23130 | the task will not execute the accept statement during elaboration. | |
88e1739c | 23131 | |
7cd4527e AC |
23132 | However, in practice it is very unusual to see elaboration code |
23133 | make any entry calls, and the pattern of tasks starting | |
23134 | at elaboration time and then immediately blocking on @code{accept} or | |
23135 | @code{select} statements is very common. What this means is that | |
23136 | the compiler is being too pessimistic when it analyzes the | |
23137 | whole package body as though it might be executed at elaboration | |
23138 | time. | |
88e1739c | 23139 | |
7cd4527e AC |
23140 | If we know that the elaboration code contains no entry calls, (a very safe |
23141 | assumption most of the time, that could almost be made the default | |
23142 | behavior), then we can compile all units of the program under control | |
23143 | of the following configuration pragma: | |
88e1739c | 23144 | |
7cd4527e AC |
23145 | @smallexample |
23146 | pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); | |
23147 | @end smallexample | |
88e1739c | 23148 | |
7cd4527e AC |
23149 | @noindent |
23150 | This pragma can be placed in the @file{gnat.adc} file in the usual | |
23151 | manner. If we take our original unmodified program and compile it | |
23152 | in the presence of a @file{gnat.adc} containing the above pragma, | |
23153 | then once again, we can compile, bind, link, and execute, obtaining | |
23154 | the expected result. In the presence of this pragma, the compiler does | |
23155 | not trace calls in a task body, that appear after the first @code{accept} | |
23156 | or @code{select} statement, and therefore does not report a potential | |
23157 | circularity in the original program. | |
88e1739c | 23158 | |
7cd4527e AC |
23159 | The compiler will check to the extent it can that the above |
23160 | restriction is not violated, but it is not always possible to do a | |
23161 | complete check at compile time, so it is important to use this | |
23162 | pragma only if the stated restriction is in fact met, that is to say | |
23163 | no task receives an entry call before elaboration of all units is completed. | |
88e1739c | 23164 | |
7cd4527e | 23165 | @end itemize |
88e1739c | 23166 | |
7cd4527e AC |
23167 | @node Mixing Elaboration Models |
23168 | @section Mixing Elaboration Models | |
23169 | @noindent | |
23170 | So far, we have assumed that the entire program is either compiled | |
23171 | using the dynamic model or static model, ensuring consistency. It | |
23172 | is possible to mix the two models, but rules have to be followed | |
23173 | if this mixing is done to ensure that elaboration checks are not | |
23174 | omitted. | |
88e1739c | 23175 | |
7cd4527e AC |
23176 | The basic rule is that @emph{a unit compiled with the static model cannot |
23177 | be @code{with'ed} by a unit compiled with the dynamic model}. The | |
23178 | reason for this is that in the static model, a unit assumes that | |
23179 | its clients guarantee to use (the equivalent of) pragma | |
23180 | @code{Elaborate_All} so that no elaboration checks are required | |
23181 | in inner subprograms, and this assumption is violated if the | |
23182 | client is compiled with dynamic checks. | |
88e1739c | 23183 | |
7cd4527e AC |
23184 | The precise rule is as follows. A unit that is compiled with dynamic |
23185 | checks can only @code{with} a unit that meets at least one of the | |
23186 | following criteria: | |
88e1739c | 23187 | |
7cd4527e | 23188 | @itemize @bullet |
88e1739c | 23189 | |
7cd4527e AC |
23190 | @item |
23191 | The @code{with'ed} unit is itself compiled with dynamic elaboration | |
23192 | checks (that is with the @option{-gnatE} switch. | |
88e1739c | 23193 | |
7cd4527e AC |
23194 | @item |
23195 | The @code{with'ed} unit is an internal GNAT implementation unit from | |
23196 | the System, Interfaces, Ada, or GNAT hierarchies. | |
88e1739c | 23197 | |
7cd4527e AC |
23198 | @item |
23199 | The @code{with'ed} unit has pragma Preelaborate or pragma Pure. | |
88e1739c | 23200 | |
7cd4527e AC |
23201 | @item |
23202 | The @code{with'ing} unit (that is the client) has an explicit pragma | |
23203 | @code{Elaborate_All} for the @code{with'ed} unit. | |
88e1739c | 23204 | |
7cd4527e | 23205 | @end itemize |
88e1739c | 23206 | |
7cd4527e AC |
23207 | @noindent |
23208 | If this rule is violated, that is if a unit with dynamic elaboration | |
23209 | checks @code{with's} a unit that does not meet one of the above four | |
23210 | criteria, then the binder (@code{gnatbind}) will issue a warning | |
23211 | similar to that in the following example: | |
88e1739c | 23212 | |
7cd4527e AC |
23213 | @smallexample |
23214 | warning: "x.ads" has dynamic elaboration checks and with's | |
23215 | warning: "y.ads" which has static elaboration checks | |
23216 | @end smallexample | |
88e1739c | 23217 | |
7cd4527e AC |
23218 | @noindent |
23219 | These warnings indicate that the rule has been violated, and that as a result | |
23220 | elaboration checks may be missed in the resulting executable file. | |
23221 | This warning may be suppressed using the @option{-ws} binder switch | |
23222 | in the usual manner. | |
88e1739c | 23223 | |
7cd4527e AC |
23224 | One useful application of this mixing rule is in the case of a subsystem |
23225 | which does not itself @code{with} units from the remainder of the | |
23226 | application. In this case, the entire subsystem can be compiled with | |
23227 | dynamic checks to resolve a circularity in the subsystem, while | |
23228 | allowing the main application that uses this subsystem to be compiled | |
23229 | using the more reliable default static model. | |
88e1739c | 23230 | |
7cd4527e AC |
23231 | @node What to Do If the Default Elaboration Behavior Fails |
23232 | @section What to Do If the Default Elaboration Behavior Fails | |
88e1739c | 23233 | |
7cd4527e AC |
23234 | @noindent |
23235 | If the binder cannot find an acceptable order, it outputs detailed | |
23236 | diagnostics. For example: | |
23237 | @smallexample | |
23238 | @group | |
23239 | @iftex | |
23240 | @leftskip=0cm | |
23241 | @end iftex | |
23242 | error: elaboration circularity detected | |
23243 | info: "proc (body)" must be elaborated before "pack (body)" | |
23244 | info: reason: Elaborate_All probably needed in unit "pack (body)" | |
23245 | info: recompile "pack (body)" with -gnatwl | |
23246 | info: for full details | |
23247 | info: "proc (body)" | |
23248 | info: is needed by its spec: | |
23249 | info: "proc (spec)" | |
23250 | info: which is withed by: | |
23251 | info: "pack (body)" | |
23252 | info: "pack (body)" must be elaborated before "proc (body)" | |
23253 | info: reason: pragma Elaborate in unit "proc (body)" | |
23254 | @end group | |
88e1739c | 23255 | |
7cd4527e | 23256 | @end smallexample |
88e1739c | 23257 | |
7cd4527e AC |
23258 | @noindent |
23259 | In this case we have a cycle that the binder cannot break. On the one | |
23260 | hand, there is an explicit pragma Elaborate in @code{proc} for | |
23261 | @code{pack}. This means that the body of @code{pack} must be elaborated | |
23262 | before the body of @code{proc}. On the other hand, there is elaboration | |
23263 | code in @code{pack} that calls a subprogram in @code{proc}. This means | |
23264 | that for maximum safety, there should really be a pragma | |
23265 | Elaborate_All in @code{pack} for @code{proc} which would require that | |
23266 | the body of @code{proc} be elaborated before the body of | |
23267 | @code{pack}. Clearly both requirements cannot be satisfied. | |
23268 | Faced with a circularity of this kind, you have three different options. | |
88e1739c | 23269 | |
7cd4527e AC |
23270 | @table @asis |
23271 | @item Fix the program | |
23272 | The most desirable option from the point of view of long-term maintenance | |
23273 | is to rearrange the program so that the elaboration problems are avoided. | |
23274 | One useful technique is to place the elaboration code into separate | |
23275 | child packages. Another is to move some of the initialization code to | |
23276 | explicitly called subprograms, where the program controls the order | |
23277 | of initialization explicitly. Although this is the most desirable option, | |
23278 | it may be impractical and involve too much modification, especially in | |
23279 | the case of complex legacy code. | |
88e1739c | 23280 | |
7cd4527e AC |
23281 | @item Perform dynamic checks |
23282 | If the compilations are done using the | |
23283 | @option{-gnatE} | |
23284 | (dynamic elaboration check) switch, then GNAT behaves in | |
23285 | a quite different manner. Dynamic checks are generated for all calls | |
23286 | that could possibly result in raising an exception. With this switch, | |
23287 | the compiler does not generate implicit @code{Elaborate_All} pragmas. | |
23288 | The behavior then is exactly as specified in the Ada 95 Reference Manual. | |
23289 | The binder will generate an executable program that may or may not | |
23290 | raise @code{Program_Error}, and then it is the programmer's job to ensure | |
23291 | that it does not raise an exception. Note that it is important to | |
23292 | compile all units with the switch, it cannot be used selectively. | |
88e1739c | 23293 | |
7cd4527e AC |
23294 | @item Suppress checks |
23295 | The drawback of dynamic checks is that they generate a | |
23296 | significant overhead at run time, both in space and time. If you | |
23297 | are absolutely sure that your program cannot raise any elaboration | |
23298 | exceptions, and you still want to use the dynamic elaboration model, | |
23299 | then you can use the configuration pragma | |
23300 | @code{Suppress (Elaboration_Check)} to suppress all such checks. For | |
23301 | example this pragma could be placed in the @file{gnat.adc} file. | |
88e1739c | 23302 | |
7cd4527e AC |
23303 | @item Suppress checks selectively |
23304 | When you know that certain calls in elaboration code cannot possibly | |
23305 | lead to an elaboration error, and the binder nevertheless generates warnings | |
23306 | on those calls and inserts Elaborate_All pragmas that lead to elaboration | |
23307 | circularities, it is possible to remove those warnings locally and obtain | |
23308 | a program that will bind. Clearly this can be unsafe, and it is the | |
23309 | responsibility of the programmer to make sure that the resulting program has | |
23310 | no elaboration anomalies. The pragma @code{Suppress (Elaboration_Check)} can | |
23311 | be used with different granularity to suppress warnings and break | |
23312 | elaboration circularities: | |
88e1739c | 23313 | |
7cd4527e AC |
23314 | @itemize @bullet |
23315 | @item | |
23316 | Place the pragma that names the called subprogram in the declarative part | |
23317 | that contains the call. | |
88e1739c | 23318 | |
7cd4527e AC |
23319 | @item |
23320 | Place the pragma in the declarative part, without naming an entity. This | |
23321 | disables warnings on all calls in the corresponding declarative region. | |
88e1739c | 23322 | |
7cd4527e AC |
23323 | @item |
23324 | Place the pragma in the package spec that declares the called subprogram, | |
23325 | and name the subprogram. This disables warnings on all elaboration calls to | |
23326 | that subprogram. | |
88e1739c | 23327 | |
7cd4527e AC |
23328 | @item |
23329 | Place the pragma in the package spec that declares the called subprogram, | |
23330 | without naming any entity. This disables warnings on all elaboration calls to | |
23331 | all subprograms declared in this spec. | |
88e1739c | 23332 | |
7cd4527e AC |
23333 | @item Use Pragma Elaborate |
23334 | As previously described in section @xref{Treatment of Pragma Elaborate}, | |
23335 | GNAT in static mode assumes that a @code{pragma} Elaborate indicates correctly | |
23336 | that no elaboration checks are required on calls to the designated unit. | |
23337 | There may be cases in which the caller knows that no transitive calls | |
23338 | can occur, so that a @code{pragma Elaborate} will be sufficient in a | |
23339 | case where @code{pragma Elaborate_All} would cause a circularity. | |
23340 | @end itemize | |
88e1739c | 23341 | |
7cd4527e AC |
23342 | @noindent |
23343 | These five cases are listed in order of decreasing safety, and therefore | |
23344 | require increasing programmer care in their application. Consider the | |
23345 | following program: | |
88e1739c | 23346 | |
7cd4527e AC |
23347 | @smallexample @c adanocomment |
23348 | package Pack1 is | |
23349 | function F1 return Integer; | |
23350 | X1 : Integer; | |
23351 | end Pack1; | |
88e1739c | 23352 | |
7cd4527e AC |
23353 | package Pack2 is |
23354 | function F2 return Integer; | |
23355 | function Pure (x : integer) return integer; | |
23356 | -- pragma Suppress (Elaboration_Check, On => Pure); -- (3) | |
23357 | -- pragma Suppress (Elaboration_Check); -- (4) | |
23358 | end Pack2; | |
88e1739c | 23359 | |
7cd4527e AC |
23360 | with Pack2; |
23361 | package body Pack1 is | |
23362 | function F1 return Integer is | |
23363 | begin | |
23364 | return 100; | |
23365 | end F1; | |
23366 | Val : integer := Pack2.Pure (11); -- Elab. call (1) | |
23367 | begin | |
23368 | declare | |
23369 | -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1) | |
23370 | -- pragma Suppress(Elaboration_Check); -- (2) | |
23371 | begin | |
23372 | X1 := Pack2.F2 + 1; -- Elab. call (2) | |
23373 | end; | |
23374 | end Pack1; | |
88e1739c | 23375 | |
7cd4527e AC |
23376 | with Pack1; |
23377 | package body Pack2 is | |
23378 | function F2 return Integer is | |
23379 | begin | |
23380 | return Pack1.F1; | |
23381 | end F2; | |
23382 | function Pure (x : integer) return integer is | |
23383 | begin | |
23384 | return x ** 3 - 3 * x; | |
23385 | end; | |
23386 | end Pack2; | |
88e1739c | 23387 | |
7cd4527e AC |
23388 | with Pack1, Ada.Text_IO; |
23389 | procedure Proc3 is | |
23390 | begin | |
23391 | Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 | |
23392 | end Proc3; | |
23393 | @end smallexample | |
23394 | In the absence of any pragmas, an attempt to bind this program produces | |
23395 | the following diagnostics: | |
23396 | @smallexample | |
23397 | @group | |
23398 | @iftex | |
23399 | @leftskip=.5cm | |
23400 | @end iftex | |
23401 | error: elaboration circularity detected | |
23402 | info: "pack1 (body)" must be elaborated before "pack1 (body)" | |
23403 | info: reason: Elaborate_All probably needed in unit "pack1 (body)" | |
23404 | info: recompile "pack1 (body)" with -gnatwl for full details | |
23405 | info: "pack1 (body)" | |
23406 | info: must be elaborated along with its spec: | |
23407 | info: "pack1 (spec)" | |
23408 | info: which is withed by: | |
23409 | info: "pack2 (body)" | |
23410 | info: which must be elaborated along with its spec: | |
23411 | info: "pack2 (spec)" | |
23412 | info: which is withed by: | |
23413 | info: "pack1 (body)" | |
23414 | @end group | |
23415 | @end smallexample | |
23416 | The sources of the circularity are the two calls to @code{Pack2.Pure} and | |
23417 | @code{Pack2.F2} in the body of @code{Pack1}. We can see that the call to | |
23418 | F2 is safe, even though F2 calls F1, because the call appears after the | |
23419 | elaboration of the body of F1. Therefore the pragma (1) is safe, and will | |
23420 | remove the warning on the call. It is also possible to use pragma (2) | |
23421 | because there are no other potentially unsafe calls in the block. | |
88e1739c | 23422 | |
7cd4527e AC |
23423 | @noindent |
23424 | The call to @code{Pure} is safe because this function does not depend on the | |
23425 | state of @code{Pack2}. Therefore any call to this function is safe, and it | |
23426 | is correct to place pragma (3) in the corresponding package spec. | |
88e1739c | 23427 | |
7cd4527e AC |
23428 | @noindent |
23429 | Finally, we could place pragma (4) in the spec of @code{Pack2} to disable | |
23430 | warnings on all calls to functions declared therein. Note that this is not | |
23431 | necessarily safe, and requires more detailed examination of the subprogram | |
23432 | bodies involved. In particular, a call to @code{F2} requires that @code{F1} | |
23433 | be already elaborated. | |
23434 | @end table | |
88e1739c | 23435 | |
7cd4527e AC |
23436 | @noindent |
23437 | It is hard to generalize on which of these four approaches should be | |
23438 | taken. Obviously if it is possible to fix the program so that the default | |
23439 | treatment works, this is preferable, but this may not always be practical. | |
23440 | It is certainly simple enough to use | |
23441 | @option{-gnatE} | |
23442 | but the danger in this case is that, even if the GNAT binder | |
23443 | finds a correct elaboration order, it may not always do so, | |
23444 | and certainly a binder from another Ada compiler might not. A | |
23445 | combination of testing and analysis (for which the warnings generated | |
23446 | with the | |
23447 | @option{-gnatwl} | |
23448 | switch can be useful) must be used to ensure that the program is free | |
23449 | of errors. One switch that is useful in this testing is the | |
23450 | @option{^-p (pessimistic elaboration order)^/PESSIMISTIC_ELABORATION_ORDER^} | |
23451 | switch for | |
23452 | @code{gnatbind}. | |
23453 | Normally the binder tries to find an order that has the best chance of | |
23454 | of avoiding elaboration problems. With this switch, the binder | |
23455 | plays a devil's advocate role, and tries to choose the order that | |
23456 | has the best chance of failing. If your program works even with this | |
23457 | switch, then it has a better chance of being error free, but this is still | |
23458 | not a guarantee. | |
88e1739c | 23459 | |
7cd4527e AC |
23460 | For an example of this approach in action, consider the C-tests (executable |
23461 | tests) from the ACVC suite. If these are compiled and run with the default | |
23462 | treatment, then all but one of them succeed without generating any error | |
23463 | diagnostics from the binder. However, there is one test that fails, and | |
23464 | this is not surprising, because the whole point of this test is to ensure | |
23465 | that the compiler can handle cases where it is impossible to determine | |
23466 | a correct order statically, and it checks that an exception is indeed | |
23467 | raised at run time. | |
88e1739c | 23468 | |
7cd4527e AC |
23469 | This one test must be compiled and run using the |
23470 | @option{-gnatE} | |
23471 | switch, and then it passes. Alternatively, the entire suite can | |
23472 | be run using this switch. It is never wrong to run with the dynamic | |
23473 | elaboration switch if your code is correct, and we assume that the | |
23474 | C-tests are indeed correct (it is less efficient, but efficiency is | |
23475 | not a factor in running the ACVC tests.) | |
88e1739c | 23476 | |
7cd4527e AC |
23477 | @node Elaboration for Access-to-Subprogram Values |
23478 | @section Elaboration for Access-to-Subprogram Values | |
23479 | @cindex Access-to-subprogram | |
88e1739c | 23480 | |
7cd4527e AC |
23481 | @noindent |
23482 | The introduction of access-to-subprogram types in Ada 95 complicates | |
23483 | the handling of elaboration. The trouble is that it becomes | |
23484 | impossible to tell at compile time which procedure | |
23485 | is being called. This means that it is not possible for the binder | |
23486 | to analyze the elaboration requirements in this case. | |
88e1739c | 23487 | |
7cd4527e AC |
23488 | If at the point at which the access value is created |
23489 | (i.e., the evaluation of @code{P'Access} for a subprogram @code{P}), | |
23490 | the body of the subprogram is | |
23491 | known to have been elaborated, then the access value is safe, and its use | |
23492 | does not require a check. This may be achieved by appropriate arrangement | |
23493 | of the order of declarations if the subprogram is in the current unit, | |
23494 | or, if the subprogram is in another unit, by using pragma | |
23495 | @code{Pure}, @code{Preelaborate}, or @code{Elaborate_Body} | |
23496 | on the referenced unit. | |
88e1739c | 23497 | |
7cd4527e AC |
23498 | If the referenced body is not known to have been elaborated at the point |
23499 | the access value is created, then any use of the access value must do a | |
23500 | dynamic check, and this dynamic check will fail and raise a | |
23501 | @code{Program_Error} exception if the body has not been elaborated yet. | |
23502 | GNAT will generate the necessary checks, and in addition, if the | |
23503 | @option{-gnatwl} | |
23504 | switch is set, will generate warnings that such checks are required. | |
88e1739c | 23505 | |
7cd4527e AC |
23506 | The use of dynamic dispatching for tagged types similarly generates |
23507 | a requirement for dynamic checks, and premature calls to any primitive | |
23508 | operation of a tagged type before the body of the operation has been | |
23509 | elaborated, will result in the raising of @code{Program_Error}. | |
88e1739c | 23510 | |
7cd4527e AC |
23511 | @node Summary of Procedures for Elaboration Control |
23512 | @section Summary of Procedures for Elaboration Control | |
23513 | @cindex Elaboration control | |
88e1739c | 23514 | |
7cd4527e AC |
23515 | @noindent |
23516 | First, compile your program with the default options, using none of | |
23517 | the special elaboration control switches. If the binder successfully | |
23518 | binds your program, then you can be confident that, apart from issues | |
23519 | raised by the use of access-to-subprogram types and dynamic dispatching, | |
23520 | the program is free of elaboration errors. If it is important that the | |
23521 | program be portable, then use the | |
23522 | @option{-gnatwl} | |
23523 | switch to generate warnings about missing @code{Elaborate_All} | |
23524 | pragmas, and supply the missing pragmas. | |
88e1739c | 23525 | |
7cd4527e AC |
23526 | If the program fails to bind using the default static elaboration |
23527 | handling, then you can fix the program to eliminate the binder | |
23528 | message, or recompile the entire program with the | |
23529 | @option{-gnatE} switch to generate dynamic elaboration checks, | |
23530 | and, if you are sure there really are no elaboration problems, | |
23531 | use a global pragma @code{Suppress (Elaboration_Check)}. | |
88e1739c | 23532 | |
7cd4527e AC |
23533 | @node Other Elaboration Order Considerations |
23534 | @section Other Elaboration Order Considerations | |
23535 | @noindent | |
23536 | This section has been entirely concerned with the issue of finding a valid | |
23537 | elaboration order, as defined by the Ada Reference Manual. In a case | |
23538 | where several elaboration orders are valid, the task is to find one | |
23539 | of the possible valid elaboration orders (and the static model in GNAT | |
23540 | will ensure that this is achieved). | |
88e1739c | 23541 | |
7cd4527e AC |
23542 | The purpose of the elaboration rules in the Ada Reference Manual is to |
23543 | make sure that no entity is accessed before it has been elaborated. For | |
23544 | a subprogram, this means that the spec and body must have been elaborated | |
23545 | before the subprogram is called. For an object, this means that the object | |
23546 | must have been elaborated before its value is read or written. A violation | |
23547 | of either of these two requirements is an access before elaboration order, | |
23548 | and this section has been all about avoiding such errors. | |
88e1739c | 23549 | |
7cd4527e AC |
23550 | In the case where more than one order of elaboration is possible, in the |
23551 | sense that access before elaboration errors are avoided, then any one of | |
23552 | the orders is ``correct'' in the sense that it meets the requirements of | |
23553 | the Ada Reference Manual, and no such error occurs. | |
88e1739c | 23554 | |
7cd4527e AC |
23555 | However, it may be the case for a given program, that there are |
23556 | constraints on the order of elaboration that come not from consideration | |
23557 | of avoiding elaboration errors, but rather from extra-lingual logic | |
23558 | requirements. Consider this example: | |
88e1739c | 23559 | |
7cd4527e AC |
23560 | @smallexample @c ada |
23561 | with Init_Constants; | |
23562 | package Constants is | |
23563 | X : Integer := 0; | |
23564 | Y : Integer := 0; | |
23565 | end Constants; | |
88e1739c | 23566 | |
7cd4527e AC |
23567 | package Init_Constants is |
23568 | procedure P; -- require a body | |
23569 | end Init_Constants; | |
88e1739c | 23570 | |
7cd4527e AC |
23571 | with Constants; |
23572 | package body Init_Constants is | |
23573 | procedure P is begin null; end; | |
23574 | begin | |
23575 | Constants.X := 3; | |
23576 | Constants.Y := 4; | |
23577 | end Init_Constants; | |
88e1739c | 23578 | |
7cd4527e AC |
23579 | with Constants; |
23580 | package Calc is | |
23581 | Z : Integer := Constants.X + Constants.Y; | |
23582 | end Calc; | |
88e1739c | 23583 | |
7cd4527e AC |
23584 | with Calc; |
23585 | with Text_IO; use Text_IO; | |
23586 | procedure Main is | |
23587 | begin | |
23588 | Put_Line (Calc.Z'Img); | |
23589 | end Main; | |
23590 | @end smallexample | |
88e1739c | 23591 | |
7cd4527e AC |
23592 | @noindent |
23593 | In this example, there is more than one valid order of elaboration. For | |
23594 | example both the following are correct orders: | |
88e1739c | 23595 | |
7cd4527e AC |
23596 | @smallexample |
23597 | Init_Constants spec | |
23598 | Constants spec | |
23599 | Calc spec | |
23600 | Init_Constants body | |
23601 | Main body | |
88e1739c | 23602 | |
7cd4527e | 23603 | and |
88e1739c | 23604 | |
7cd4527e AC |
23605 | Init_Constants spec |
23606 | Init_Constants body | |
23607 | Constants spec | |
23608 | Calc spec | |
23609 | Main body | |
88e1739c | 23610 | @end smallexample |
88e1739c FW |
23611 | |
23612 | @noindent | |
7cd4527e AC |
23613 | There is no language rule to prefer one or the other, both are correct |
23614 | from an order of elaboration point of view. But the programmatic effects | |
23615 | of the two orders are very different. In the first, the elaboration routine | |
23616 | of @code{Calc} initializes @code{Z} to zero, and then the main program | |
23617 | runs with this value of zero. But in the second order, the elaboration | |
23618 | routine of @code{Calc} runs after the body of Init_Constants has set | |
23619 | @code{X} and @code{Y} and thus @code{Z} is set to 7 before @code{Main} | |
23620 | runs. | |
88e1739c | 23621 | |
7cd4527e AC |
23622 | One could perhaps by applying pretty clever non-artificial intelligence |
23623 | to the situation guess that it is more likely that the second order of | |
23624 | elaboration is the one desired, but there is no formal linguistic reason | |
23625 | to prefer one over the other. In fact in this particular case, GNAT will | |
23626 | prefer the second order, because of the rule that bodies are elaborated | |
23627 | as soon as possible, but it's just luck that this is what was wanted | |
23628 | (if indeed the second order was preferred). | |
88e1739c | 23629 | |
7cd4527e AC |
23630 | If the program cares about the order of elaboration routines in a case like |
23631 | this, it is important to specify the order required. In this particular | |
23632 | case, that could have been achieved by adding to the spec of Calc: | |
88e1739c | 23633 | |
7cd4527e AC |
23634 | @smallexample @c ada |
23635 | pragma Elaborate_All (Constants); | |
23636 | @end smallexample | |
88e1739c | 23637 | |
7cd4527e AC |
23638 | @noindent |
23639 | which requires that the body (if any) and spec of @code{Constants}, | |
23640 | as well as the body and spec of any unit @code{with}'ed by | |
23641 | @code{Constants} be elaborated before @code{Calc} is elaborated. | |
88e1739c | 23642 | |
7cd4527e AC |
23643 | Clearly no automatic method can always guess which alternative you require, |
23644 | and if you are working with legacy code that had constraints of this kind | |
23645 | which were not properly specified by adding @code{Elaborate} or | |
23646 | @code{Elaborate_All} pragmas, then indeed it is possible that two different | |
23647 | compilers can choose different orders. | |
88e1739c | 23648 | |
7cd4527e AC |
23649 | The @code{gnatbind} |
23650 | @option{^-p^/PESSIMISTIC_ELABORATION^} switch may be useful in smoking | |
23651 | out problems. This switch causes bodies to be elaborated as late as possible | |
23652 | instead of as early as possible. In the example above, it would have forced | |
23653 | the choice of the first elaboration order. If you get different results | |
23654 | when using this switch, and particularly if one set of results is right, | |
23655 | and one is wrong as far as you are concerned, it shows that you have some | |
23656 | missing @code{Elaborate} pragmas. For the example above, we have the | |
23657 | following output: | |
88e1739c | 23658 | |
7cd4527e AC |
23659 | @smallexample |
23660 | gnatmake -f -q main | |
23661 | main | |
23662 | 7 | |
23663 | gnatmake -f -q main -bargs -p | |
23664 | main | |
23665 | 0 | |
23666 | @end smallexample | |
88e1739c | 23667 | |
7cd4527e AC |
23668 | @noindent |
23669 | It is of course quite unlikely that both these results are correct, so | |
23670 | it is up to you in a case like this to investigate the source of the | |
23671 | difference, by looking at the two elaboration orders that are chosen, | |
23672 | and figuring out which is correct, and then adding the necessary | |
23673 | @code{Elaborate_All} pragmas to ensure the desired order. | |
88e1739c | 23674 | |
88e1739c | 23675 | |
7cd4527e AC |
23676 | @node Inline Assembler |
23677 | @appendix Inline Assembler | |
88e1739c FW |
23678 | |
23679 | @noindent | |
7cd4527e AC |
23680 | If you need to write low-level software that interacts directly |
23681 | with the hardware, Ada provides two ways to incorporate assembly | |
23682 | language code into your program. First, you can import and invoke | |
23683 | external routines written in assembly language, an Ada feature fully | |
23684 | supported by GNAT. However, for small sections of code it may be simpler | |
23685 | or more efficient to include assembly language statements directly | |
23686 | in your Ada source program, using the facilities of the implementation-defined | |
23687 | package @code{System.Machine_Code}, which incorporates the gcc | |
23688 | Inline Assembler. The Inline Assembler approach offers a number of advantages, | |
23689 | including the following: | |
88e1739c FW |
23690 | |
23691 | @itemize @bullet | |
7cd4527e AC |
23692 | @item No need to use non-Ada tools |
23693 | @item Consistent interface over different targets | |
23694 | @item Automatic usage of the proper calling conventions | |
23695 | @item Access to Ada constants and variables | |
23696 | @item Definition of intrinsic routines | |
23697 | @item Possibility of inlining a subprogram comprising assembler code | |
23698 | @item Code optimizer can take Inline Assembler code into account | |
88e1739c FW |
23699 | @end itemize |
23700 | ||
7cd4527e AC |
23701 | This chapter presents a series of examples to show you how to use |
23702 | the Inline Assembler. Although it focuses on the Intel x86, | |
23703 | the general approach applies also to other processors. | |
23704 | It is assumed that you are familiar with Ada | |
23705 | and with assembly language programming. | |
88e1739c FW |
23706 | |
23707 | @menu | |
7cd4527e AC |
23708 | * Basic Assembler Syntax:: |
23709 | * A Simple Example of Inline Assembler:: | |
23710 | * Output Variables in Inline Assembler:: | |
23711 | * Input Variables in Inline Assembler:: | |
23712 | * Inlining Inline Assembler Code:: | |
23713 | * Other Asm Functionality:: | |
23714 | * A Complete Example:: | |
88e1739c FW |
23715 | @end menu |
23716 | ||
7cd4527e AC |
23717 | @c --------------------------------------------------------------------------- |
23718 | @node Basic Assembler Syntax | |
23719 | @section Basic Assembler Syntax | |
23720 | ||
88e1739c | 23721 | @noindent |
7cd4527e AC |
23722 | The assembler used by GNAT and gcc is based not on the Intel assembly |
23723 | language, but rather on a language that descends from the AT&T Unix | |
23724 | assembler @emph{as} (and which is often referred to as ``AT&T syntax''). | |
23725 | The following table summarizes the main features of @emph{as} syntax | |
23726 | and points out the differences from the Intel conventions. | |
23727 | See the gcc @emph{as} and @emph{gas} (an @emph{as} macro | |
23728 | pre-processor) documentation for further information. | |
88e1739c | 23729 | |
7cd4527e AC |
23730 | @table @asis |
23731 | @item Register names | |
23732 | gcc / @emph{as}: Prefix with ``%''; for example @code{%eax} | |
23733 | @* | |
23734 | Intel: No extra punctuation; for example @code{eax} | |
88e1739c | 23735 | |
7cd4527e AC |
23736 | @item Immediate operand |
23737 | gcc / @emph{as}: Prefix with ``$''; for example @code{$4} | |
23738 | @* | |
23739 | Intel: No extra punctuation; for example @code{4} | |
88e1739c | 23740 | |
7cd4527e AC |
23741 | @item Address |
23742 | gcc / @emph{as}: Prefix with ``$''; for example @code{$loc} | |
23743 | @* | |
23744 | Intel: No extra punctuation; for example @code{loc} | |
88e1739c | 23745 | |
7cd4527e AC |
23746 | @item Memory contents |
23747 | gcc / @emph{as}: No extra punctuation; for example @code{loc} | |
23748 | @* | |
23749 | Intel: Square brackets; for example @code{[loc]} | |
23750 | ||
23751 | @item Register contents | |
23752 | gcc / @emph{as}: Parentheses; for example @code{(%eax)} | |
23753 | @* | |
23754 | Intel: Square brackets; for example @code{[eax]} | |
23755 | ||
23756 | @item Hexadecimal numbers | |
23757 | gcc / @emph{as}: Leading ``0x'' (C language syntax); for example @code{0xA0} | |
23758 | @* | |
23759 | Intel: Trailing ``h''; for example @code{A0h} | |
23760 | ||
23761 | @item Operand size | |
23762 | gcc / @emph{as}: Explicit in op code; for example @code{movw} to move | |
23763 | a 16-bit word | |
23764 | @* | |
23765 | Intel: Implicit, deduced by assembler; for example @code{mov} | |
23766 | ||
23767 | @item Instruction repetition | |
23768 | gcc / @emph{as}: Split into two lines; for example | |
23769 | @* | |
23770 | @code{rep} | |
23771 | @* | |
23772 | @code{stosl} | |
23773 | @* | |
23774 | Intel: Keep on one line; for example @code{rep stosl} | |
23775 | ||
23776 | @item Order of operands | |
23777 | gcc / @emph{as}: Source first; for example @code{movw $4, %eax} | |
23778 | @* | |
23779 | Intel: Destination first; for example @code{mov eax, 4} | |
88e1739c FW |
23780 | @end table |
23781 | ||
7cd4527e AC |
23782 | @c --------------------------------------------------------------------------- |
23783 | @node A Simple Example of Inline Assembler | |
23784 | @section A Simple Example of Inline Assembler | |
88e1739c FW |
23785 | |
23786 | @noindent | |
7cd4527e AC |
23787 | The following example will generate a single assembly language statement, |
23788 | @code{nop}, which does nothing. Despite its lack of run-time effect, | |
23789 | the example will be useful in illustrating the basics of | |
23790 | the Inline Assembler facility. | |
23791 | ||
23792 | @smallexample @c ada | |
23793 | @group | |
23794 | with System.Machine_Code; use System.Machine_Code; | |
23795 | procedure Nothing is | |
23796 | begin | |
23797 | Asm ("nop"); | |
23798 | end Nothing; | |
23799 | @end group | |
23800 | @end smallexample | |
88e1739c | 23801 | |
7cd4527e AC |
23802 | @code{Asm} is a procedure declared in package @code{System.Machine_Code}; |
23803 | here it takes one parameter, a @emph{template string} that must be a static | |
23804 | expression and that will form the generated instruction. | |
23805 | @code{Asm} may be regarded as a compile-time procedure that parses | |
23806 | the template string and additional parameters (none here), | |
23807 | from which it generates a sequence of assembly language instructions. | |
88e1739c | 23808 | |
7cd4527e AC |
23809 | The examples in this chapter will illustrate several of the forms |
23810 | for invoking @code{Asm}; a complete specification of the syntax | |
23811 | is found in the @cite{GNAT Reference Manual}. | |
23812 | ||
23813 | Under the standard GNAT conventions, the @code{Nothing} procedure | |
23814 | should be in a file named @file{nothing.adb}. | |
23815 | You can build the executable in the usual way: | |
23816 | @smallexample | |
23817 | gnatmake nothing | |
23818 | @end smallexample | |
23819 | However, the interesting aspect of this example is not its run-time behavior | |
23820 | but rather the generated assembly code. | |
23821 | To see this output, invoke the compiler as follows: | |
23822 | @smallexample | |
23823 | gcc -c -S -fomit-frame-pointer -gnatp @file{nothing.adb} | |
23824 | @end smallexample | |
23825 | where the options are: | |
88e1739c | 23826 | |
7cd4527e AC |
23827 | @table @code |
23828 | @item -c | |
23829 | compile only (no bind or link) | |
23830 | @item -S | |
23831 | generate assembler listing | |
23832 | @item -fomit-frame-pointer | |
23833 | do not set up separate stack frames | |
23834 | @item -gnatp | |
23835 | do not add runtime checks | |
23836 | @end table | |
88e1739c | 23837 | |
7cd4527e AC |
23838 | This gives a human-readable assembler version of the code. The resulting |
23839 | file will have the same name as the Ada source file, but with a @code{.s} | |
23840 | extension. In our example, the file @file{nothing.s} has the following | |
23841 | contents: | |
88e1739c | 23842 | |
7cd4527e AC |
23843 | @smallexample |
23844 | @group | |
23845 | .file "nothing.adb" | |
23846 | gcc2_compiled.: | |
23847 | ___gnu_compiled_ada: | |
23848 | .text | |
23849 | .align 4 | |
23850 | .globl __ada_nothing | |
23851 | __ada_nothing: | |
23852 | #APP | |
23853 | nop | |
23854 | #NO_APP | |
23855 | jmp L1 | |
23856 | .align 2,0x90 | |
23857 | L1: | |
23858 | ret | |
23859 | @end group | |
23860 | @end smallexample | |
88e1739c | 23861 | |
7cd4527e AC |
23862 | The assembly code you included is clearly indicated by |
23863 | the compiler, between the @code{#APP} and @code{#NO_APP} | |
23864 | delimiters. The character before the 'APP' and 'NOAPP' | |
23865 | can differ on different targets. For example, GNU/Linux uses '#APP' while | |
23866 | on NT you will see '/APP'. | |
88e1739c | 23867 | |
7cd4527e AC |
23868 | If you make a mistake in your assembler code (such as using the |
23869 | wrong size modifier, or using a wrong operand for the instruction) GNAT | |
23870 | will report this error in a temporary file, which will be deleted when | |
23871 | the compilation is finished. Generating an assembler file will help | |
23872 | in such cases, since you can assemble this file separately using the | |
23873 | @emph{as} assembler that comes with gcc. | |
88e1739c | 23874 | |
7cd4527e | 23875 | Assembling the file using the command |
88e1739c | 23876 | |
7cd4527e AC |
23877 | @smallexample |
23878 | as @file{nothing.s} | |
23879 | @end smallexample | |
88e1739c | 23880 | @noindent |
7cd4527e AC |
23881 | will give you error messages whose lines correspond to the assembler |
23882 | input file, so you can easily find and correct any mistakes you made. | |
23883 | If there are no errors, @emph{as} will generate an object file | |
23884 | @file{nothing.out}. | |
88e1739c | 23885 | |
7cd4527e AC |
23886 | @c --------------------------------------------------------------------------- |
23887 | @node Output Variables in Inline Assembler | |
23888 | @section Output Variables in Inline Assembler | |
88e1739c | 23889 | |
7cd4527e AC |
23890 | @noindent |
23891 | The examples in this section, showing how to access the processor flags, | |
23892 | illustrate how to specify the destination operands for assembly language | |
23893 | statements. | |
88e1739c | 23894 | |
7cd4527e AC |
23895 | @smallexample @c ada |
23896 | @group | |
23897 | with Interfaces; use Interfaces; | |
23898 | with Ada.Text_IO; use Ada.Text_IO; | |
23899 | with System.Machine_Code; use System.Machine_Code; | |
23900 | procedure Get_Flags is | |
23901 | Flags : Unsigned_32; | |
23902 | use ASCII; | |
23903 | begin | |
23904 | Asm ("pushfl" & LF & HT & -- push flags on stack | |
23905 | "popl %%eax" & LF & HT & -- load eax with flags | |
23906 | "movl %%eax, %0", -- store flags in variable | |
23907 | Outputs => Unsigned_32'Asm_Output ("=g", Flags)); | |
23908 | Put_Line ("Flags register:" & Flags'Img); | |
23909 | end Get_Flags; | |
23910 | @end group | |
23911 | @end smallexample | |
88e1739c | 23912 | |
7cd4527e AC |
23913 | In order to have a nicely aligned assembly listing, we have separated |
23914 | multiple assembler statements in the Asm template string with linefeed | |
23915 | (ASCII.LF) and horizontal tab (ASCII.HT) characters. | |
23916 | The resulting section of the assembly output file is: | |
88e1739c FW |
23917 | |
23918 | @smallexample | |
7cd4527e AC |
23919 | @group |
23920 | #APP | |
23921 | pushfl | |
23922 | popl %eax | |
23923 | movl %eax, -40(%ebp) | |
23924 | #NO_APP | |
23925 | @end group | |
88e1739c FW |
23926 | @end smallexample |
23927 | ||
7cd4527e | 23928 | It would have been legal to write the Asm invocation as: |
88e1739c | 23929 | |
7cd4527e AC |
23930 | @smallexample |
23931 | Asm ("pushfl popl %%eax movl %%eax, %0") | |
23932 | @end smallexample | |
88e1739c | 23933 | |
7cd4527e | 23934 | but in the generated assembler file, this would come out as: |
88e1739c | 23935 | |
7cd4527e AC |
23936 | @smallexample |
23937 | #APP | |
23938 | pushfl popl %eax movl %eax, -40(%ebp) | |
23939 | #NO_APP | |
23940 | @end smallexample | |
88e1739c | 23941 | |
7cd4527e | 23942 | which is not so convenient for the human reader. |
88e1739c | 23943 | |
7cd4527e AC |
23944 | We use Ada comments |
23945 | at the end of each line to explain what the assembler instructions | |
23946 | actually do. This is a useful convention. | |
88e1739c | 23947 | |
7cd4527e AC |
23948 | When writing Inline Assembler instructions, you need to precede each register |
23949 | and variable name with a percent sign. Since the assembler already requires | |
23950 | a percent sign at the beginning of a register name, you need two consecutive | |
23951 | percent signs for such names in the Asm template string, thus @code{%%eax}. | |
23952 | In the generated assembly code, one of the percent signs will be stripped off. | |
88e1739c | 23953 | |
7cd4527e AC |
23954 | Names such as @code{%0}, @code{%1}, @code{%2}, etc., denote input or output |
23955 | variables: operands you later define using @code{Input} or @code{Output} | |
23956 | parameters to @code{Asm}. | |
23957 | An output variable is illustrated in | |
23958 | the third statement in the Asm template string: | |
23959 | @smallexample | |
23960 | movl %%eax, %0 | |
23961 | @end smallexample | |
23962 | The intent is to store the contents of the eax register in a variable that can | |
23963 | be accessed in Ada. Simply writing @code{movl %%eax, Flags} would not | |
23964 | necessarily work, since the compiler might optimize by using a register | |
23965 | to hold Flags, and the expansion of the @code{movl} instruction would not be | |
23966 | aware of this optimization. The solution is not to store the result directly | |
23967 | but rather to advise the compiler to choose the correct operand form; | |
23968 | that is the purpose of the @code{%0} output variable. | |
88e1739c | 23969 | |
7cd4527e AC |
23970 | Information about the output variable is supplied in the @code{Outputs} |
23971 | parameter to @code{Asm}: | |
23972 | @smallexample | |
23973 | Outputs => Unsigned_32'Asm_Output ("=g", Flags)); | |
23974 | @end smallexample | |
88e1739c | 23975 | |
7cd4527e AC |
23976 | The output is defined by the @code{Asm_Output} attribute of the target type; |
23977 | the general format is | |
23978 | @smallexample | |
23979 | Type'Asm_Output (constraint_string, variable_name) | |
23980 | @end smallexample | |
88e1739c | 23981 | |
7cd4527e AC |
23982 | The constraint string directs the compiler how |
23983 | to store/access the associated variable. In the example | |
23984 | @smallexample | |
23985 | Unsigned_32'Asm_Output ("=m", Flags); | |
23986 | @end smallexample | |
23987 | the @code{"m"} (memory) constraint tells the compiler that the variable | |
23988 | @code{Flags} should be stored in a memory variable, thus preventing | |
23989 | the optimizer from keeping it in a register. In contrast, | |
23990 | @smallexample | |
23991 | Unsigned_32'Asm_Output ("=r", Flags); | |
23992 | @end smallexample | |
23993 | uses the @code{"r"} (register) constraint, telling the compiler to | |
23994 | store the variable in a register. | |
88e1739c | 23995 | |
7cd4527e AC |
23996 | If the constraint is preceded by the equal character (@strong{=}), it tells |
23997 | the compiler that the variable will be used to store data into it. | |
88e1739c | 23998 | |
7cd4527e AC |
23999 | In the @code{Get_Flags} example, we used the @code{"g"} (global) constraint, |
24000 | allowing the optimizer to choose whatever it deems best. | |
88e1739c | 24001 | |
7cd4527e AC |
24002 | There are a fairly large number of constraints, but the ones that are |
24003 | most useful (for the Intel x86 processor) are the following: | |
88e1739c | 24004 | |
7cd4527e AC |
24005 | @table @code |
24006 | @item = | |
24007 | output constraint | |
24008 | @item g | |
24009 | global (i.e. can be stored anywhere) | |
24010 | @item m | |
24011 | in memory | |
24012 | @item I | |
24013 | a constant | |
24014 | @item a | |
24015 | use eax | |
24016 | @item b | |
24017 | use ebx | |
24018 | @item c | |
24019 | use ecx | |
24020 | @item d | |
24021 | use edx | |
24022 | @item S | |
24023 | use esi | |
24024 | @item D | |
24025 | use edi | |
24026 | @item r | |
24027 | use one of eax, ebx, ecx or edx | |
24028 | @item q | |
24029 | use one of eax, ebx, ecx, edx, esi or edi | |
24030 | @end table | |
88e1739c | 24031 | |
7cd4527e AC |
24032 | The full set of constraints is described in the gcc and @emph{as} |
24033 | documentation; note that it is possible to combine certain constraints | |
24034 | in one constraint string. | |
88e1739c | 24035 | |
7cd4527e AC |
24036 | You specify the association of an output variable with an assembler operand |
24037 | through the @code{%}@emph{n} notation, where @emph{n} is a non-negative | |
24038 | integer. Thus in | |
24039 | @smallexample @c ada | |
24040 | @group | |
24041 | Asm ("pushfl" & LF & HT & -- push flags on stack | |
24042 | "popl %%eax" & LF & HT & -- load eax with flags | |
24043 | "movl %%eax, %0", -- store flags in variable | |
24044 | Outputs => Unsigned_32'Asm_Output ("=g", Flags)); | |
24045 | @end group | |
24046 | @end smallexample | |
88e1739c | 24047 | @noindent |
7cd4527e AC |
24048 | @code{%0} will be replaced in the expanded code by the appropriate operand, |
24049 | whatever | |
24050 | the compiler decided for the @code{Flags} variable. | |
88e1739c | 24051 | |
7cd4527e | 24052 | In general, you may have any number of output variables: |
88e1739c FW |
24053 | @itemize @bullet |
24054 | @item | |
7cd4527e | 24055 | Count the operands starting at 0; thus @code{%0}, @code{%1}, etc. |
88e1739c | 24056 | @item |
7cd4527e AC |
24057 | Specify the @code{Outputs} parameter as a parenthesized comma-separated list |
24058 | of @code{Asm_Output} attributes | |
88e1739c FW |
24059 | @end itemize |
24060 | ||
7cd4527e AC |
24061 | For example: |
24062 | @smallexample @c ada | |
24063 | @group | |
24064 | Asm ("movl %%eax, %0" & LF & HT & | |
24065 | "movl %%ebx, %1" & LF & HT & | |
24066 | "movl %%ecx, %2", | |
24067 | Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A | |
24068 | Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B | |
24069 | Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C | |
24070 | @end group | |
24071 | @end smallexample | |
88e1739c | 24072 | @noindent |
7cd4527e AC |
24073 | where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables |
24074 | in the Ada program. | |
88e1739c | 24075 | |
7cd4527e AC |
24076 | As a variation on the @code{Get_Flags} example, we can use the constraints |
24077 | string to direct the compiler to store the eax register into the @code{Flags} | |
24078 | variable, instead of including the store instruction explicitly in the | |
24079 | @code{Asm} template string: | |
88e1739c | 24080 | |
7cd4527e AC |
24081 | @smallexample @c ada |
24082 | @group | |
24083 | with Interfaces; use Interfaces; | |
24084 | with Ada.Text_IO; use Ada.Text_IO; | |
24085 | with System.Machine_Code; use System.Machine_Code; | |
24086 | procedure Get_Flags_2 is | |
24087 | Flags : Unsigned_32; | |
24088 | use ASCII; | |
24089 | begin | |
24090 | Asm ("pushfl" & LF & HT & -- push flags on stack | |
24091 | "popl %%eax", -- save flags in eax | |
24092 | Outputs => Unsigned_32'Asm_Output ("=a", Flags)); | |
24093 | Put_Line ("Flags register:" & Flags'Img); | |
24094 | end Get_Flags_2; | |
24095 | @end group | |
88e1739c FW |
24096 | @end smallexample |
24097 | ||
24098 | @noindent | |
7cd4527e AC |
24099 | The @code{"a"} constraint tells the compiler that the @code{Flags} |
24100 | variable will come from the eax register. Here is the resulting code: | |
88e1739c FW |
24101 | |
24102 | @smallexample | |
24103 | @group | |
7cd4527e AC |
24104 | #APP |
24105 | pushfl | |
24106 | popl %eax | |
24107 | #NO_APP | |
24108 | movl %eax,-40(%ebp) | |
88e1739c FW |
24109 | @end group |
24110 | @end smallexample | |
24111 | ||
24112 | @noindent | |
7cd4527e AC |
24113 | The compiler generated the store of eax into Flags after |
24114 | expanding the assembler code. | |
88e1739c | 24115 | |
7cd4527e AC |
24116 | Actually, there was no need to pop the flags into the eax register; |
24117 | more simply, we could just pop the flags directly into the program variable: | |
88e1739c | 24118 | |
7cd4527e AC |
24119 | @smallexample @c ada |
24120 | @group | |
24121 | with Interfaces; use Interfaces; | |
24122 | with Ada.Text_IO; use Ada.Text_IO; | |
24123 | with System.Machine_Code; use System.Machine_Code; | |
24124 | procedure Get_Flags_3 is | |
24125 | Flags : Unsigned_32; | |
24126 | use ASCII; | |
24127 | begin | |
24128 | Asm ("pushfl" & LF & HT & -- push flags on stack | |
24129 | "pop %0", -- save flags in Flags | |
24130 | Outputs => Unsigned_32'Asm_Output ("=g", Flags)); | |
24131 | Put_Line ("Flags register:" & Flags'Img); | |
24132 | end Get_Flags_3; | |
24133 | @end group | |
24134 | @end smallexample | |
24135 | ||
24136 | @c --------------------------------------------------------------------------- | |
24137 | @node Input Variables in Inline Assembler | |
24138 | @section Input Variables in Inline Assembler | |
88e1739c FW |
24139 | |
24140 | @noindent | |
7cd4527e AC |
24141 | The example in this section illustrates how to specify the source operands |
24142 | for assembly language statements. | |
24143 | The program simply increments its input value by 1: | |
88e1739c | 24144 | |
7cd4527e AC |
24145 | @smallexample @c ada |
24146 | @group | |
24147 | with Interfaces; use Interfaces; | |
24148 | with Ada.Text_IO; use Ada.Text_IO; | |
24149 | with System.Machine_Code; use System.Machine_Code; | |
24150 | procedure Increment is | |
88e1739c | 24151 | |
7cd4527e AC |
24152 | function Incr (Value : Unsigned_32) return Unsigned_32 is |
24153 | Result : Unsigned_32; | |
24154 | begin | |
24155 | Asm ("incl %0", | |
24156 | Inputs => Unsigned_32'Asm_Input ("a", Value), | |
24157 | Outputs => Unsigned_32'Asm_Output ("=a", Result)); | |
24158 | return Result; | |
24159 | end Incr; | |
88e1739c | 24160 | |
7cd4527e AC |
24161 | Value : Unsigned_32; |
24162 | ||
24163 | begin | |
24164 | Value := 5; | |
24165 | Put_Line ("Value before is" & Value'Img); | |
24166 | Value := Incr (Value); | |
24167 | Put_Line ("Value after is" & Value'Img); | |
24168 | end Increment; | |
24169 | @end group | |
88e1739c FW |
24170 | @end smallexample |
24171 | ||
7cd4527e AC |
24172 | The @code{Outputs} parameter to @code{Asm} specifies |
24173 | that the result will be in the eax register and that it is to be stored | |
24174 | in the @code{Result} variable. | |
24175 | ||
24176 | The @code{Inputs} parameter looks much like the @code{Outputs} parameter, | |
24177 | but with an @code{Asm_Input} attribute. | |
24178 | The @code{"="} constraint, indicating an output value, is not present. | |
24179 | ||
24180 | You can have multiple input variables, in the same way that you can have more | |
24181 | than one output variable. | |
24182 | ||
24183 | The parameter count (%0, %1) etc, now starts at the first input | |
24184 | statement, and continues with the output statements. | |
24185 | When both parameters use the same variable, the | |
24186 | compiler will treat them as the same %n operand, which is the case here. | |
24187 | ||
24188 | Just as the @code{Outputs} parameter causes the register to be stored into the | |
24189 | target variable after execution of the assembler statements, so does the | |
24190 | @code{Inputs} parameter cause its variable to be loaded into the register | |
24191 | before execution of the assembler statements. | |
24192 | ||
24193 | Thus the effect of the @code{Asm} invocation is: | |
24194 | @enumerate | |
24195 | @item load the 32-bit value of @code{Value} into eax | |
24196 | @item execute the @code{incl %eax} instruction | |
24197 | @item store the contents of eax into the @code{Result} variable | |
24198 | @end enumerate | |
88e1739c | 24199 | |
7cd4527e | 24200 | The resulting assembler file (with @option{-O2} optimization) contains: |
88e1739c FW |
24201 | @smallexample |
24202 | @group | |
7cd4527e AC |
24203 | _increment__incr.1: |
24204 | subl $4,%esp | |
24205 | movl 8(%esp),%eax | |
24206 | #APP | |
24207 | incl %eax | |
24208 | #NO_APP | |
24209 | movl %eax,%edx | |
24210 | movl %ecx,(%esp) | |
24211 | addl $4,%esp | |
24212 | ret | |
88e1739c FW |
24213 | @end group |
24214 | @end smallexample | |
24215 | ||
7cd4527e AC |
24216 | @c --------------------------------------------------------------------------- |
24217 | @node Inlining Inline Assembler Code | |
24218 | @section Inlining Inline Assembler Code | |
24219 | ||
88e1739c | 24220 | @noindent |
7cd4527e AC |
24221 | For a short subprogram such as the @code{Incr} function in the previous |
24222 | section, the overhead of the call and return (creating / deleting the stack | |
24223 | frame) can be significant, compared to the amount of code in the subprogram | |
24224 | body. A solution is to apply Ada's @code{Inline} pragma to the subprogram, | |
24225 | which directs the compiler to expand invocations of the subprogram at the | |
24226 | point(s) of call, instead of setting up a stack frame for out-of-line calls. | |
24227 | Here is the resulting program: | |
88e1739c | 24228 | |
7cd4527e | 24229 | @smallexample @c ada |
88e1739c | 24230 | @group |
7cd4527e AC |
24231 | with Interfaces; use Interfaces; |
24232 | with Ada.Text_IO; use Ada.Text_IO; | |
24233 | with System.Machine_Code; use System.Machine_Code; | |
24234 | procedure Increment_2 is | |
24235 | ||
24236 | function Incr (Value : Unsigned_32) return Unsigned_32 is | |
24237 | Result : Unsigned_32; | |
24238 | begin | |
24239 | Asm ("incl %0", | |
24240 | Inputs => Unsigned_32'Asm_Input ("a", Value), | |
24241 | Outputs => Unsigned_32'Asm_Output ("=a", Result)); | |
24242 | return Result; | |
24243 | end Incr; | |
24244 | pragma Inline (Increment); | |
24245 | ||
24246 | Value : Unsigned_32; | |
24247 | ||
24248 | begin | |
24249 | Value := 5; | |
24250 | Put_Line ("Value before is" & Value'Img); | |
24251 | Value := Increment (Value); | |
24252 | Put_Line ("Value after is" & Value'Img); | |
24253 | end Increment_2; | |
88e1739c FW |
24254 | @end group |
24255 | @end smallexample | |
24256 | ||
7cd4527e AC |
24257 | Compile the program with both optimization (@option{-O2}) and inlining |
24258 | enabled (@option{-gnatpn} instead of @option{-gnatp}). | |
24259 | ||
24260 | The @code{Incr} function is still compiled as usual, but at the | |
24261 | point in @code{Increment} where our function used to be called: | |
88e1739c FW |
24262 | |
24263 | @smallexample | |
24264 | @group | |
7cd4527e AC |
24265 | pushl %edi |
24266 | call _increment__incr.1 | |
88e1739c FW |
24267 | @end group |
24268 | @end smallexample | |
24269 | ||
24270 | @noindent | |
7cd4527e AC |
24271 | the code for the function body directly appears: |
24272 | ||
24273 | @smallexample | |
24274 | @group | |
24275 | movl %esi,%eax | |
24276 | #APP | |
24277 | incl %eax | |
24278 | #NO_APP | |
24279 | movl %eax,%edx | |
24280 | @end group | |
24281 | @end smallexample | |
88e1739c FW |
24282 | |
24283 | @noindent | |
7cd4527e | 24284 | thus saving the overhead of stack frame setup and an out-of-line call. |
88e1739c | 24285 | |
7cd4527e AC |
24286 | @c --------------------------------------------------------------------------- |
24287 | @node Other Asm Functionality | |
24288 | @section Other @code{Asm} Functionality | |
88e1739c FW |
24289 | |
24290 | @noindent | |
7cd4527e AC |
24291 | This section describes two important parameters to the @code{Asm} |
24292 | procedure: @code{Clobber}, which identifies register usage; | |
24293 | and @code{Volatile}, which inhibits unwanted optimizations. | |
88e1739c | 24294 | |
7cd4527e AC |
24295 | @menu |
24296 | * The Clobber Parameter:: | |
24297 | * The Volatile Parameter:: | |
24298 | @end menu | |
24299 | ||
24300 | @c --------------------------------------------------------------------------- | |
24301 | @node The Clobber Parameter | |
24302 | @subsection The @code{Clobber} Parameter | |
88e1739c FW |
24303 | |
24304 | @noindent | |
7cd4527e AC |
24305 | One of the dangers of intermixing assembly language and a compiled language |
24306 | such as Ada is that the compiler needs to be aware of which registers are | |
24307 | being used by the assembly code. In some cases, such as the earlier examples, | |
24308 | the constraint string is sufficient to indicate register usage (e.g., | |
24309 | @code{"a"} for | |
24310 | the eax register). But more generally, the compiler needs an explicit | |
24311 | identification of the registers that are used by the Inline Assembly | |
24312 | statements. | |
88e1739c | 24313 | |
7cd4527e AC |
24314 | Using a register that the compiler doesn't know about |
24315 | could be a side effect of an instruction (like @code{mull} | |
24316 | storing its result in both eax and edx). | |
24317 | It can also arise from explicit register usage in your | |
24318 | assembly code; for example: | |
88e1739c FW |
24319 | @smallexample |
24320 | @group | |
7cd4527e AC |
24321 | Asm ("movl %0, %%ebx" & LF & HT & |
24322 | "movl %%ebx, %1", | |
24323 | Inputs => Unsigned_32'Asm_Input ("g", Var_In), | |
24324 | Outputs => Unsigned_32'Asm_Output ("=g", Var_Out)); | |
88e1739c FW |
24325 | @end group |
24326 | @end smallexample | |
88e1739c | 24327 | @noindent |
7cd4527e AC |
24328 | where the compiler (since it does not analyze the @code{Asm} template string) |
24329 | does not know you are using the ebx register. | |
88e1739c | 24330 | |
7cd4527e AC |
24331 | In such cases you need to supply the @code{Clobber} parameter to @code{Asm}, |
24332 | to identify the registers that will be used by your assembly code: | |
24333 | ||
24334 | @smallexample | |
24335 | @group | |
24336 | Asm ("movl %0, %%ebx" & LF & HT & | |
24337 | "movl %%ebx, %1", | |
24338 | Inputs => Unsigned_32'Asm_Input ("g", Var_In), | |
24339 | Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), | |
24340 | Clobber => "ebx"); | |
24341 | @end group | |
24342 | @end smallexample | |
88e1739c | 24343 | |
7cd4527e AC |
24344 | The Clobber parameter is a static string expression specifying the |
24345 | register(s) you are using. Note that register names are @emph{not} prefixed | |
24346 | by a percent sign. Also, if more than one register is used then their names | |
24347 | are separated by commas; e.g., @code{"eax, ebx"} | |
24348 | ||
24349 | The @code{Clobber} parameter has several additional uses: | |
88e1739c | 24350 | @enumerate |
7cd4527e AC |
24351 | @item Use ``register'' name @code{cc} to indicate that flags might have changed |
24352 | @item Use ``register'' name @code{memory} if you changed a memory location | |
24353 | @end enumerate | |
88e1739c | 24354 | |
7cd4527e AC |
24355 | @c --------------------------------------------------------------------------- |
24356 | @node The Volatile Parameter | |
24357 | @subsection The @code{Volatile} Parameter | |
24358 | @cindex Volatile parameter | |
88e1739c | 24359 | |
7cd4527e AC |
24360 | @noindent |
24361 | Compiler optimizations in the presence of Inline Assembler may sometimes have | |
24362 | unwanted effects. For example, when an @code{Asm} invocation with an input | |
24363 | variable is inside a loop, the compiler might move the loading of the input | |
24364 | variable outside the loop, regarding it as a one-time initialization. | |
88e1739c | 24365 | |
7cd4527e AC |
24366 | If this effect is not desired, you can disable such optimizations by setting |
24367 | the @code{Volatile} parameter to @code{True}; for example: | |
88e1739c | 24368 | |
7cd4527e AC |
24369 | @smallexample @c ada |
24370 | @group | |
24371 | Asm ("movl %0, %%ebx" & LF & HT & | |
24372 | "movl %%ebx, %1", | |
24373 | Inputs => Unsigned_32'Asm_Input ("g", Var_In), | |
24374 | Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), | |
24375 | Clobber => "ebx", | |
24376 | Volatile => True); | |
24377 | @end group | |
24378 | @end smallexample | |
88e1739c | 24379 | |
7cd4527e AC |
24380 | By default, @code{Volatile} is set to @code{False} unless there is no |
24381 | @code{Outputs} parameter. | |
88e1739c | 24382 | |
7cd4527e AC |
24383 | Although setting @code{Volatile} to @code{True} prevents unwanted |
24384 | optimizations, it will also disable other optimizations that might be | |
24385 | important for efficiency. In general, you should set @code{Volatile} | |
24386 | to @code{True} only if the compiler's optimizations have created | |
24387 | problems. | |
88e1739c | 24388 | |
7cd4527e AC |
24389 | @c --------------------------------------------------------------------------- |
24390 | @node A Complete Example | |
24391 | @section A Complete Example | |
88e1739c FW |
24392 | |
24393 | @noindent | |
7cd4527e AC |
24394 | This section contains a complete program illustrating a realistic usage |
24395 | of GNAT's Inline Assembler capabilities. It comprises a main procedure | |
24396 | @code{Check_CPU} and a package @code{Intel_CPU}. | |
24397 | The package declares a collection of functions that detect the properties | |
24398 | of the 32-bit x86 processor that is running the program. | |
24399 | The main procedure invokes these functions and displays the information. | |
88e1739c | 24400 | |
7cd4527e AC |
24401 | The Intel_CPU package could be enhanced by adding functions to |
24402 | detect the type of x386 co-processor, the processor caching options and | |
24403 | special operations such as the SIMD extensions. | |
88e1739c | 24404 | |
7cd4527e AC |
24405 | Although the Intel_CPU package has been written for 32-bit Intel |
24406 | compatible CPUs, it is OS neutral. It has been tested on DOS, | |
24407 | Windows/NT and GNU/Linux. | |
88e1739c FW |
24408 | |
24409 | @menu | |
7cd4527e AC |
24410 | * Check_CPU Procedure:: |
24411 | * Intel_CPU Package Specification:: | |
24412 | * Intel_CPU Package Body:: | |
88e1739c FW |
24413 | @end menu |
24414 | ||
7cd4527e AC |
24415 | @c --------------------------------------------------------------------------- |
24416 | @node Check_CPU Procedure | |
24417 | @subsection @code{Check_CPU} Procedure | |
24418 | @cindex Check_CPU procedure | |
88e1739c | 24419 | |
7cd4527e AC |
24420 | @smallexample @c adanocomment |
24421 | --------------------------------------------------------------------- | |
24422 | -- -- | |
24423 | -- Uses the Intel_CPU package to identify the CPU the program is -- | |
24424 | -- running on, and some of the features it supports. -- | |
24425 | -- -- | |
24426 | --------------------------------------------------------------------- | |
88e1739c | 24427 | |
7cd4527e AC |
24428 | with Intel_CPU; -- Intel CPU detection functions |
24429 | with Ada.Text_IO; -- Standard text I/O | |
24430 | with Ada.Command_Line; -- To set the exit status | |
88e1739c | 24431 | |
7cd4527e | 24432 | procedure Check_CPU is |
88e1739c | 24433 | |
7cd4527e AC |
24434 | Type_Found : Boolean := False; |
24435 | -- Flag to indicate that processor was identified | |
88e1739c | 24436 | |
7cd4527e AC |
24437 | Features : Intel_CPU.Processor_Features; |
24438 | -- The processor features | |
88e1739c | 24439 | |
7cd4527e AC |
24440 | Signature : Intel_CPU.Processor_Signature; |
24441 | -- The processor type signature | |
88e1739c | 24442 | |
7cd4527e | 24443 | begin |
88e1739c | 24444 | |
7cd4527e AC |
24445 | ----------------------------------- |
24446 | -- Display the program banner. -- | |
24447 | ----------------------------------- | |
88e1739c | 24448 | |
7cd4527e AC |
24449 | Ada.Text_IO.Put_Line (Ada.Command_Line.Command_Name & |
24450 | ": check Intel CPU version and features, v1.0"); | |
24451 | Ada.Text_IO.Put_Line ("distribute freely, but no warranty whatsoever"); | |
24452 | Ada.Text_IO.New_Line; | |
88e1739c | 24453 | |
7cd4527e AC |
24454 | ----------------------------------------------------------------------- |
24455 | -- We can safely start with the assumption that we are on at least -- | |
24456 | -- a x386 processor. If the CPUID instruction is present, then we -- | |
24457 | -- have a later processor type. -- | |
24458 | ----------------------------------------------------------------------- | |
88e1739c | 24459 | |
7cd4527e | 24460 | if Intel_CPU.Has_CPUID = False then |
88e1739c | 24461 | |
7cd4527e AC |
24462 | -- No CPUID instruction, so we assume this is indeed a x386 |
24463 | -- processor. We can still check if it has a FP co-processor. | |
24464 | if Intel_CPU.Has_FPU then | |
24465 | Ada.Text_IO.Put_Line | |
24466 | ("x386-type processor with a FP co-processor"); | |
24467 | else | |
24468 | Ada.Text_IO.Put_Line | |
24469 | ("x386-type processor without a FP co-processor"); | |
24470 | end if; -- check for FPU | |
88e1739c | 24471 | |
7cd4527e AC |
24472 | -- Program done |
24473 | Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); | |
24474 | return; | |
88e1739c | 24475 | |
7cd4527e | 24476 | end if; -- check for CPUID |
88e1739c | 24477 | |
7cd4527e AC |
24478 | ----------------------------------------------------------------------- |
24479 | -- If CPUID is supported, check if this is a true Intel processor, -- | |
24480 | -- if it is not, display a warning. -- | |
24481 | ----------------------------------------------------------------------- | |
88e1739c | 24482 | |
7cd4527e AC |
24483 | if Intel_CPU.Vendor_ID /= Intel_CPU.Intel_Processor then |
24484 | Ada.Text_IO.Put_Line ("*** This is a Intel compatible processor"); | |
24485 | Ada.Text_IO.Put_Line ("*** Some information may be incorrect"); | |
24486 | end if; -- check if Intel | |
88e1739c | 24487 | |
7cd4527e AC |
24488 | ---------------------------------------------------------------------- |
24489 | -- With the CPUID instruction present, we can assume at least a -- | |
24490 | -- x486 processor. If the CPUID support level is < 1 then we have -- | |
24491 | -- to leave it at that. -- | |
24492 | ---------------------------------------------------------------------- | |
88e1739c | 24493 | |
7cd4527e | 24494 | if Intel_CPU.CPUID_Level < 1 then |
88e1739c | 24495 | |
7cd4527e AC |
24496 | -- Ok, this is a x486 processor. we still can get the Vendor ID |
24497 | Ada.Text_IO.Put_Line ("x486-type processor"); | |
24498 | Ada.Text_IO.Put_Line ("Vendor ID is " & Intel_CPU.Vendor_ID); | |
88e1739c | 24499 | |
7cd4527e AC |
24500 | -- We can also check if there is a FPU present |
24501 | if Intel_CPU.Has_FPU then | |
24502 | Ada.Text_IO.Put_Line ("Floating-Point support"); | |
24503 | else | |
24504 | Ada.Text_IO.Put_Line ("No Floating-Point support"); | |
24505 | end if; -- check for FPU | |
88e1739c | 24506 | |
7cd4527e AC |
24507 | -- Program done |
24508 | Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); | |
24509 | return; | |
88e1739c | 24510 | |
7cd4527e AC |
24511 | end if; -- check CPUID level |
24512 | ||
24513 | --------------------------------------------------------------------- | |
24514 | -- With a CPUID level of 1 we can use the processor signature to -- | |
24515 | -- determine it's exact type. -- | |
24516 | --------------------------------------------------------------------- | |
88e1739c | 24517 | |
7cd4527e | 24518 | Signature := Intel_CPU.Signature; |
88e1739c | 24519 | |
7cd4527e AC |
24520 | ---------------------------------------------------------------------- |
24521 | -- Ok, now we go into a lot of messy comparisons to get the -- | |
24522 | -- processor type. For clarity, no attememt to try to optimize the -- | |
24523 | -- comparisons has been made. Note that since Intel_CPU does not -- | |
24524 | -- support getting cache info, we cannot distinguish between P5 -- | |
24525 | -- and Celeron types yet. -- | |
24526 | ---------------------------------------------------------------------- | |
88e1739c | 24527 | |
7cd4527e AC |
24528 | -- x486SL |
24529 | if Signature.Processor_Type = 2#00# and | |
24530 | Signature.Family = 2#0100# and | |
24531 | Signature.Model = 2#0100# then | |
24532 | Type_Found := True; | |
24533 | Ada.Text_IO.Put_Line ("x486SL processor"); | |
24534 | end if; | |
88e1739c | 24535 | |
7cd4527e AC |
24536 | -- x486DX2 Write-Back |
24537 | if Signature.Processor_Type = 2#00# and | |
24538 | Signature.Family = 2#0100# and | |
24539 | Signature.Model = 2#0111# then | |
24540 | Type_Found := True; | |
24541 | Ada.Text_IO.Put_Line ("Write-Back Enhanced x486DX2 processor"); | |
24542 | end if; | |
88e1739c | 24543 | |
7cd4527e AC |
24544 | -- x486DX4 |
24545 | if Signature.Processor_Type = 2#00# and | |
24546 | Signature.Family = 2#0100# and | |
24547 | Signature.Model = 2#1000# then | |
24548 | Type_Found := True; | |
24549 | Ada.Text_IO.Put_Line ("x486DX4 processor"); | |
24550 | end if; | |
88e1739c | 24551 | |
7cd4527e AC |
24552 | -- x486DX4 Overdrive |
24553 | if Signature.Processor_Type = 2#01# and | |
24554 | Signature.Family = 2#0100# and | |
24555 | Signature.Model = 2#1000# then | |
24556 | Type_Found := True; | |
24557 | Ada.Text_IO.Put_Line ("x486DX4 OverDrive processor"); | |
24558 | end if; | |
88e1739c | 24559 | |
7cd4527e AC |
24560 | -- Pentium (60, 66) |
24561 | if Signature.Processor_Type = 2#00# and | |
24562 | Signature.Family = 2#0101# and | |
24563 | Signature.Model = 2#0001# then | |
24564 | Type_Found := True; | |
24565 | Ada.Text_IO.Put_Line ("Pentium processor (60, 66)"); | |
24566 | end if; | |
88e1739c | 24567 | |
7cd4527e AC |
24568 | -- Pentium (75, 90, 100, 120, 133, 150, 166, 200) |
24569 | if Signature.Processor_Type = 2#00# and | |
24570 | Signature.Family = 2#0101# and | |
24571 | Signature.Model = 2#0010# then | |
24572 | Type_Found := True; | |
24573 | Ada.Text_IO.Put_Line | |
24574 | ("Pentium processor (75, 90, 100, 120, 133, 150, 166, 200)"); | |
24575 | end if; | |
88e1739c | 24576 | |
7cd4527e AC |
24577 | -- Pentium OverDrive (60, 66) |
24578 | if Signature.Processor_Type = 2#01# and | |
24579 | Signature.Family = 2#0101# and | |
24580 | Signature.Model = 2#0001# then | |
24581 | Type_Found := True; | |
24582 | Ada.Text_IO.Put_Line ("Pentium OverDrive processor (60, 66)"); | |
24583 | end if; | |
88e1739c | 24584 | |
7cd4527e AC |
24585 | -- Pentium OverDrive (75, 90, 100, 120, 133, 150, 166, 200) |
24586 | if Signature.Processor_Type = 2#01# and | |
24587 | Signature.Family = 2#0101# and | |
24588 | Signature.Model = 2#0010# then | |
24589 | Type_Found := True; | |
24590 | Ada.Text_IO.Put_Line | |
24591 | ("Pentium OverDrive cpu (75, 90, 100, 120, 133, 150, 166, 200)"); | |
24592 | end if; | |
88e1739c | 24593 | |
7cd4527e AC |
24594 | -- Pentium OverDrive processor for x486 processor-based systems |
24595 | if Signature.Processor_Type = 2#01# and | |
24596 | Signature.Family = 2#0101# and | |
24597 | Signature.Model = 2#0011# then | |
24598 | Type_Found := True; | |
24599 | Ada.Text_IO.Put_Line | |
24600 | ("Pentium OverDrive processor for x486 processor-based systems"); | |
24601 | end if; | |
88e1739c | 24602 | |
7cd4527e AC |
24603 | -- Pentium processor with MMX technology (166, 200) |
24604 | if Signature.Processor_Type = 2#00# and | |
24605 | Signature.Family = 2#0101# and | |
24606 | Signature.Model = 2#0100# then | |
24607 | Type_Found := True; | |
24608 | Ada.Text_IO.Put_Line | |
24609 | ("Pentium processor with MMX technology (166, 200)"); | |
24610 | end if; | |
88e1739c | 24611 | |
7cd4527e AC |
24612 | -- Pentium OverDrive with MMX for Pentium (75, 90, 100, 120, 133) |
24613 | if Signature.Processor_Type = 2#01# and | |
24614 | Signature.Family = 2#0101# and | |
24615 | Signature.Model = 2#0100# then | |
24616 | Type_Found := True; | |
24617 | Ada.Text_IO.Put_Line | |
24618 | ("Pentium OverDrive processor with MMX " & | |
24619 | "technology for Pentium processor (75, 90, 100, 120, 133)"); | |
24620 | end if; | |
88e1739c | 24621 | |
7cd4527e AC |
24622 | -- Pentium Pro processor |
24623 | if Signature.Processor_Type = 2#00# and | |
24624 | Signature.Family = 2#0110# and | |
24625 | Signature.Model = 2#0001# then | |
24626 | Type_Found := True; | |
24627 | Ada.Text_IO.Put_Line ("Pentium Pro processor"); | |
24628 | end if; | |
88e1739c | 24629 | |
7cd4527e AC |
24630 | -- Pentium II processor, model 3 |
24631 | if Signature.Processor_Type = 2#00# and | |
24632 | Signature.Family = 2#0110# and | |
24633 | Signature.Model = 2#0011# then | |
24634 | Type_Found := True; | |
24635 | Ada.Text_IO.Put_Line ("Pentium II processor, model 3"); | |
24636 | end if; | |
88e1739c | 24637 | |
7cd4527e AC |
24638 | -- Pentium II processor, model 5 or Celeron processor |
24639 | if Signature.Processor_Type = 2#00# and | |
24640 | Signature.Family = 2#0110# and | |
24641 | Signature.Model = 2#0101# then | |
24642 | Type_Found := True; | |
24643 | Ada.Text_IO.Put_Line | |
24644 | ("Pentium II processor, model 5 or Celeron processor"); | |
24645 | end if; | |
88e1739c | 24646 | |
7cd4527e AC |
24647 | -- Pentium Pro OverDrive processor |
24648 | if Signature.Processor_Type = 2#01# and | |
24649 | Signature.Family = 2#0110# and | |
24650 | Signature.Model = 2#0011# then | |
24651 | Type_Found := True; | |
24652 | Ada.Text_IO.Put_Line ("Pentium Pro OverDrive processor"); | |
24653 | end if; | |
88e1739c | 24654 | |
7cd4527e AC |
24655 | -- If no type recognized, we have an unknown. Display what |
24656 | -- we _do_ know | |
24657 | if Type_Found = False then | |
24658 | Ada.Text_IO.Put_Line ("Unknown processor"); | |
24659 | end if; | |
88e1739c | 24660 | |
7cd4527e AC |
24661 | ----------------------------------------- |
24662 | -- Display processor stepping level. -- | |
24663 | ----------------------------------------- | |
88e1739c | 24664 | |
7cd4527e | 24665 | Ada.Text_IO.Put_Line ("Stepping level:" & Signature.Stepping'Img); |
88e1739c | 24666 | |
7cd4527e AC |
24667 | --------------------------------- |
24668 | -- Display vendor ID string. -- | |
24669 | --------------------------------- | |
88e1739c | 24670 | |
7cd4527e | 24671 | Ada.Text_IO.Put_Line ("Vendor ID: " & Intel_CPU.Vendor_ID); |
88e1739c | 24672 | |
7cd4527e AC |
24673 | ------------------------------------ |
24674 | -- Get the processors features. -- | |
24675 | ------------------------------------ | |
88e1739c | 24676 | |
7cd4527e | 24677 | Features := Intel_CPU.Features; |
88e1739c | 24678 | |
7cd4527e AC |
24679 | ----------------------------- |
24680 | -- Check for a FPU unit. -- | |
24681 | ----------------------------- | |
88e1739c | 24682 | |
7cd4527e AC |
24683 | if Features.FPU = True then |
24684 | Ada.Text_IO.Put_Line ("Floating-Point unit available"); | |
24685 | else | |
24686 | Ada.Text_IO.Put_Line ("no Floating-Point unit"); | |
24687 | end if; -- check for FPU | |
88e1739c | 24688 | |
7cd4527e AC |
24689 | -------------------------------- |
24690 | -- List processor features. -- | |
24691 | -------------------------------- | |
88e1739c | 24692 | |
7cd4527e | 24693 | Ada.Text_IO.Put_Line ("Supported features: "); |
88e1739c | 24694 | |
7cd4527e AC |
24695 | -- Virtual Mode Extension |
24696 | if Features.VME = True then | |
24697 | Ada.Text_IO.Put_Line (" VME - Virtual Mode Extension"); | |
24698 | end if; | |
88e1739c | 24699 | |
7cd4527e AC |
24700 | -- Debugging Extension |
24701 | if Features.DE = True then | |
24702 | Ada.Text_IO.Put_Line (" DE - Debugging Extension"); | |
24703 | end if; | |
88e1739c | 24704 | |
7cd4527e AC |
24705 | -- Page Size Extension |
24706 | if Features.PSE = True then | |
24707 | Ada.Text_IO.Put_Line (" PSE - Page Size Extension"); | |
24708 | end if; | |
88e1739c | 24709 | |
7cd4527e AC |
24710 | -- Time Stamp Counter |
24711 | if Features.TSC = True then | |
24712 | Ada.Text_IO.Put_Line (" TSC - Time Stamp Counter"); | |
24713 | end if; | |
88e1739c | 24714 | |
7cd4527e AC |
24715 | -- Model Specific Registers |
24716 | if Features.MSR = True then | |
24717 | Ada.Text_IO.Put_Line (" MSR - Model Specific Registers"); | |
24718 | end if; | |
88e1739c | 24719 | |
7cd4527e AC |
24720 | -- Physical Address Extension |
24721 | if Features.PAE = True then | |
24722 | Ada.Text_IO.Put_Line (" PAE - Physical Address Extension"); | |
24723 | end if; | |
88e1739c | 24724 | |
7cd4527e AC |
24725 | -- Machine Check Extension |
24726 | if Features.MCE = True then | |
24727 | Ada.Text_IO.Put_Line (" MCE - Machine Check Extension"); | |
24728 | end if; | |
88e1739c | 24729 | |
7cd4527e AC |
24730 | -- CMPXCHG8 instruction supported |
24731 | if Features.CX8 = True then | |
24732 | Ada.Text_IO.Put_Line (" CX8 - CMPXCHG8 instruction"); | |
24733 | end if; | |
88e1739c | 24734 | |
7cd4527e AC |
24735 | -- on-chip APIC hardware support |
24736 | if Features.APIC = True then | |
24737 | Ada.Text_IO.Put_Line (" APIC - on-chip APIC hardware support"); | |
24738 | end if; | |
88e1739c | 24739 | |
7cd4527e AC |
24740 | -- Fast System Call |
24741 | if Features.SEP = True then | |
24742 | Ada.Text_IO.Put_Line (" SEP - Fast System Call"); | |
24743 | end if; | |
88e1739c | 24744 | |
7cd4527e AC |
24745 | -- Memory Type Range Registers |
24746 | if Features.MTRR = True then | |
24747 | Ada.Text_IO.Put_Line (" MTTR - Memory Type Range Registers"); | |
24748 | end if; | |
88e1739c | 24749 | |
7cd4527e AC |
24750 | -- Page Global Enable |
24751 | if Features.PGE = True then | |
24752 | Ada.Text_IO.Put_Line (" PGE - Page Global Enable"); | |
24753 | end if; | |
88e1739c | 24754 | |
7cd4527e AC |
24755 | -- Machine Check Architecture |
24756 | if Features.MCA = True then | |
24757 | Ada.Text_IO.Put_Line (" MCA - Machine Check Architecture"); | |
24758 | end if; | |
88e1739c | 24759 | |
7cd4527e AC |
24760 | -- Conditional Move Instruction Supported |
24761 | if Features.CMOV = True then | |
24762 | Ada.Text_IO.Put_Line | |
24763 | (" CMOV - Conditional Move Instruction Supported"); | |
24764 | end if; | |
88e1739c | 24765 | |
7cd4527e AC |
24766 | -- Page Attribute Table |
24767 | if Features.PAT = True then | |
24768 | Ada.Text_IO.Put_Line (" PAT - Page Attribute Table"); | |
24769 | end if; | |
88e1739c | 24770 | |
7cd4527e AC |
24771 | -- 36-bit Page Size Extension |
24772 | if Features.PSE_36 = True then | |
24773 | Ada.Text_IO.Put_Line (" PSE_36 - 36-bit Page Size Extension"); | |
24774 | end if; | |
88e1739c | 24775 | |
7cd4527e AC |
24776 | -- MMX technology supported |
24777 | if Features.MMX = True then | |
24778 | Ada.Text_IO.Put_Line (" MMX - MMX technology supported"); | |
24779 | end if; | |
88e1739c | 24780 | |
7cd4527e AC |
24781 | -- Fast FP Save and Restore |
24782 | if Features.FXSR = True then | |
24783 | Ada.Text_IO.Put_Line (" FXSR - Fast FP Save and Restore"); | |
24784 | end if; | |
88e1739c | 24785 | |
7cd4527e AC |
24786 | --------------------- |
24787 | -- Program done. -- | |
24788 | --------------------- | |
88e1739c | 24789 | |
7cd4527e | 24790 | Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success); |
88e1739c | 24791 | |
7cd4527e | 24792 | exception |
88e1739c | 24793 | |
7cd4527e AC |
24794 | when others => |
24795 | Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Failure); | |
24796 | raise; | |
88e1739c | 24797 | |
7cd4527e | 24798 | end Check_CPU; |
88e1739c FW |
24799 | @end smallexample |
24800 | ||
7cd4527e AC |
24801 | @c --------------------------------------------------------------------------- |
24802 | @node Intel_CPU Package Specification | |
24803 | @subsection @code{Intel_CPU} Package Specification | |
24804 | @cindex Intel_CPU package specification | |
88e1739c | 24805 | |
7cd4527e AC |
24806 | @smallexample @c adanocomment |
24807 | ------------------------------------------------------------------------- | |
24808 | -- -- | |
24809 | -- file: intel_cpu.ads -- | |
24810 | -- -- | |
24811 | -- ********************************************* -- | |
24812 | -- * WARNING: for 32-bit Intel processors only * -- | |
24813 | -- ********************************************* -- | |
24814 | -- -- | |
24815 | -- This package contains a number of subprograms that are useful in -- | |
24816 | -- determining the Intel x86 CPU (and the features it supports) on -- | |
24817 | -- which the program is running. -- | |
24818 | -- -- | |
24819 | -- The package is based upon the information given in the Intel -- | |
24820 | -- Application Note AP-485: "Intel Processor Identification and the -- | |
24821 | -- CPUID Instruction" as of April 1998. This application note can be -- | |
24822 | -- found on www.intel.com. -- | |
24823 | -- -- | |
24824 | -- It currently deals with 32-bit processors only, will not detect -- | |
24825 | -- features added after april 1998, and does not guarantee proper -- | |
24826 | -- results on Intel-compatible processors. -- | |
24827 | -- -- | |
24828 | -- Cache info and x386 fpu type detection are not supported. -- | |
24829 | -- -- | |
24830 | -- This package does not use any privileged instructions, so should -- | |
24831 | -- work on any OS running on a 32-bit Intel processor. -- | |
24832 | -- -- | |
24833 | ------------------------------------------------------------------------- | |
88e1739c | 24834 | |
7cd4527e AC |
24835 | with Interfaces; use Interfaces; |
24836 | -- for using unsigned types | |
88e1739c | 24837 | |
7cd4527e AC |
24838 | with System.Machine_Code; use System.Machine_Code; |
24839 | -- for using inline assembler code | |
88e1739c | 24840 | |
7cd4527e AC |
24841 | with Ada.Characters.Latin_1; use Ada.Characters.Latin_1; |
24842 | -- for inserting control characters | |
88e1739c | 24843 | |
7cd4527e | 24844 | package Intel_CPU is |
88e1739c | 24845 | |
7cd4527e AC |
24846 | ---------------------- |
24847 | -- Processor bits -- | |
24848 | ---------------------- | |
88e1739c | 24849 | |
7cd4527e AC |
24850 | subtype Num_Bits is Natural range 0 .. 31; |
24851 | -- the number of processor bits (32) | |
88e1739c | 24852 | |
7cd4527e AC |
24853 | -------------------------- |
24854 | -- Processor register -- | |
24855 | -------------------------- | |
88e1739c | 24856 | |
7cd4527e AC |
24857 | -- define a processor register type for easy access to |
24858 | -- the individual bits | |
88e1739c | 24859 | |
7cd4527e AC |
24860 | type Processor_Register is array (Num_Bits) of Boolean; |
24861 | pragma Pack (Processor_Register); | |
24862 | for Processor_Register'Size use 32; | |
88e1739c | 24863 | |
7cd4527e AC |
24864 | ------------------------- |
24865 | -- Unsigned register -- | |
24866 | ------------------------- | |
88e1739c | 24867 | |
7cd4527e AC |
24868 | -- define a processor register type for easy access to |
24869 | -- the individual bytes | |
88e1739c | 24870 | |
7cd4527e AC |
24871 | type Unsigned_Register is |
24872 | record | |
24873 | L1 : Unsigned_8; | |
24874 | H1 : Unsigned_8; | |
24875 | L2 : Unsigned_8; | |
24876 | H2 : Unsigned_8; | |
24877 | end record; | |
88e1739c | 24878 | |
7cd4527e AC |
24879 | for Unsigned_Register use |
24880 | record | |
24881 | L1 at 0 range 0 .. 7; | |
24882 | H1 at 0 range 8 .. 15; | |
24883 | L2 at 0 range 16 .. 23; | |
24884 | H2 at 0 range 24 .. 31; | |
24885 | end record; | |
88e1739c | 24886 | |
7cd4527e | 24887 | for Unsigned_Register'Size use 32; |
88e1739c | 24888 | |
7cd4527e AC |
24889 | --------------------------------- |
24890 | -- Intel processor vendor ID -- | |
24891 | --------------------------------- | |
88e1739c | 24892 | |
7cd4527e AC |
24893 | Intel_Processor : constant String (1 .. 12) := "GenuineIntel"; |
24894 | -- indicates an Intel manufactured processor | |
88e1739c | 24895 | |
7cd4527e AC |
24896 | ------------------------------------ |
24897 | -- Processor signature register -- | |
24898 | ------------------------------------ | |
88e1739c | 24899 | |
7cd4527e | 24900 | -- a register type to hold the processor signature |
88e1739c | 24901 | |
7cd4527e AC |
24902 | type Processor_Signature is |
24903 | record | |
24904 | Stepping : Natural range 0 .. 15; | |
24905 | Model : Natural range 0 .. 15; | |
24906 | Family : Natural range 0 .. 15; | |
24907 | Processor_Type : Natural range 0 .. 3; | |
24908 | Reserved : Natural range 0 .. 262143; | |
24909 | end record; | |
88e1739c | 24910 | |
7cd4527e AC |
24911 | for Processor_Signature use |
24912 | record | |
24913 | Stepping at 0 range 0 .. 3; | |
24914 | Model at 0 range 4 .. 7; | |
24915 | Family at 0 range 8 .. 11; | |
24916 | Processor_Type at 0 range 12 .. 13; | |
24917 | Reserved at 0 range 14 .. 31; | |
24918 | end record; | |
88e1739c | 24919 | |
7cd4527e | 24920 | for Processor_Signature'Size use 32; |
88e1739c | 24921 | |
7cd4527e AC |
24922 | ----------------------------------- |
24923 | -- Processor features register -- | |
24924 | ----------------------------------- | |
88e1739c | 24925 | |
7cd4527e | 24926 | -- a processor register to hold the processor feature flags |
88e1739c | 24927 | |
7cd4527e AC |
24928 | type Processor_Features is |
24929 | record | |
24930 | FPU : Boolean; -- floating point unit on chip | |
24931 | VME : Boolean; -- virtual mode extension | |
24932 | DE : Boolean; -- debugging extension | |
24933 | PSE : Boolean; -- page size extension | |
24934 | TSC : Boolean; -- time stamp counter | |
24935 | MSR : Boolean; -- model specific registers | |
24936 | PAE : Boolean; -- physical address extension | |
24937 | MCE : Boolean; -- machine check extension | |
24938 | CX8 : Boolean; -- cmpxchg8 instruction | |
24939 | APIC : Boolean; -- on-chip apic hardware | |
24940 | Res_1 : Boolean; -- reserved for extensions | |
24941 | SEP : Boolean; -- fast system call | |
24942 | MTRR : Boolean; -- memory type range registers | |
24943 | PGE : Boolean; -- page global enable | |
24944 | MCA : Boolean; -- machine check architecture | |
24945 | CMOV : Boolean; -- conditional move supported | |
24946 | PAT : Boolean; -- page attribute table | |
24947 | PSE_36 : Boolean; -- 36-bit page size extension | |
24948 | Res_2 : Natural range 0 .. 31; -- reserved for extensions | |
24949 | MMX : Boolean; -- MMX technology supported | |
24950 | FXSR : Boolean; -- fast FP save and restore | |
24951 | Res_3 : Natural range 0 .. 127; -- reserved for extensions | |
24952 | end record; | |
88e1739c | 24953 | |
7cd4527e AC |
24954 | for Processor_Features use |
24955 | record | |
24956 | FPU at 0 range 0 .. 0; | |
24957 | VME at 0 range 1 .. 1; | |
24958 | DE at 0 range 2 .. 2; | |
24959 | PSE at 0 range 3 .. 3; | |
24960 | TSC at 0 range 4 .. 4; | |
24961 | MSR at 0 range 5 .. 5; | |
24962 | PAE at 0 range 6 .. 6; | |
24963 | MCE at 0 range 7 .. 7; | |
24964 | CX8 at 0 range 8 .. 8; | |
24965 | APIC at 0 range 9 .. 9; | |
24966 | Res_1 at 0 range 10 .. 10; | |
24967 | SEP at 0 range 11 .. 11; | |
24968 | MTRR at 0 range 12 .. 12; | |
24969 | PGE at 0 range 13 .. 13; | |
24970 | MCA at 0 range 14 .. 14; | |
24971 | CMOV at 0 range 15 .. 15; | |
24972 | PAT at 0 range 16 .. 16; | |
24973 | PSE_36 at 0 range 17 .. 17; | |
24974 | Res_2 at 0 range 18 .. 22; | |
24975 | MMX at 0 range 23 .. 23; | |
24976 | FXSR at 0 range 24 .. 24; | |
24977 | Res_3 at 0 range 25 .. 31; | |
24978 | end record; | |
24979 | ||
24980 | for Processor_Features'Size use 32; | |
88e1739c | 24981 | |
7cd4527e AC |
24982 | ------------------- |
24983 | -- Subprograms -- | |
24984 | ------------------- | |
88e1739c | 24985 | |
7cd4527e AC |
24986 | function Has_FPU return Boolean; |
24987 | -- return True if a FPU is found | |
24988 | -- use only if CPUID is not supported | |
88e1739c | 24989 | |
7cd4527e AC |
24990 | function Has_CPUID return Boolean; |
24991 | -- return True if the processor supports the CPUID instruction | |
88e1739c | 24992 | |
7cd4527e AC |
24993 | function CPUID_Level return Natural; |
24994 | -- return the CPUID support level (0, 1 or 2) | |
24995 | -- can only be called if the CPUID instruction is supported | |
88e1739c | 24996 | |
7cd4527e AC |
24997 | function Vendor_ID return String; |
24998 | -- return the processor vendor identification string | |
24999 | -- can only be called if the CPUID instruction is supported | |
88e1739c | 25000 | |
7cd4527e AC |
25001 | function Signature return Processor_Signature; |
25002 | -- return the processor signature | |
25003 | -- can only be called if the CPUID instruction is supported | |
88e1739c | 25004 | |
7cd4527e AC |
25005 | function Features return Processor_Features; |
25006 | -- return the processors features | |
25007 | -- can only be called if the CPUID instruction is supported | |
88e1739c | 25008 | |
7cd4527e | 25009 | private |
88e1739c | 25010 | |
7cd4527e AC |
25011 | ------------------------ |
25012 | -- EFLAGS bit names -- | |
25013 | ------------------------ | |
88e1739c | 25014 | |
7cd4527e AC |
25015 | ID_Flag : constant Num_Bits := 21; |
25016 | -- ID flag bit | |
88e1739c | 25017 | |
7cd4527e AC |
25018 | end Intel_CPU; |
25019 | @end smallexample | |
88e1739c | 25020 | |
7cd4527e AC |
25021 | @c --------------------------------------------------------------------------- |
25022 | @node Intel_CPU Package Body | |
25023 | @subsection @code{Intel_CPU} Package Body | |
25024 | @cindex Intel_CPU package body | |
88e1739c | 25025 | |
7cd4527e AC |
25026 | @smallexample @c adanocomment |
25027 | package body Intel_CPU is | |
88e1739c | 25028 | |
7cd4527e AC |
25029 | --------------------------- |
25030 | -- Detect FPU presence -- | |
25031 | --------------------------- | |
88e1739c | 25032 | |
7cd4527e AC |
25033 | -- There is a FPU present if we can set values to the FPU Status |
25034 | -- and Control Words. | |
88e1739c | 25035 | |
7cd4527e | 25036 | function Has_FPU return Boolean is |
88e1739c | 25037 | |
7cd4527e AC |
25038 | Register : Unsigned_16; |
25039 | -- processor register to store a word | |
88e1739c | 25040 | |
7cd4527e | 25041 | begin |
88e1739c | 25042 | |
7cd4527e AC |
25043 | -- check if we can change the status word |
25044 | Asm ( | |
88e1739c | 25045 | |
7cd4527e AC |
25046 | -- the assembler code |
25047 | "finit" & LF & HT & -- reset status word | |
25048 | "movw $0x5A5A, %%ax" & LF & HT & -- set value status word | |
25049 | "fnstsw %0" & LF & HT & -- save status word | |
25050 | "movw %%ax, %0", -- store status word | |
88e1739c | 25051 | |
7cd4527e AC |
25052 | -- output stored in Register |
25053 | -- register must be a memory location | |
25054 | Outputs => Unsigned_16'Asm_output ("=m", Register), | |
88e1739c | 25055 | |
7cd4527e AC |
25056 | -- tell compiler that we used eax |
25057 | Clobber => "eax"); | |
88e1739c | 25058 | |
7cd4527e AC |
25059 | -- if the status word is zero, there is no FPU |
25060 | if Register = 0 then | |
25061 | return False; -- no status word | |
25062 | end if; -- check status word value | |
88e1739c | 25063 | |
7cd4527e AC |
25064 | -- check if we can get the control word |
25065 | Asm ( | |
88e1739c | 25066 | |
7cd4527e AC |
25067 | -- the assembler code |
25068 | "fnstcw %0", -- save the control word | |
88e1739c | 25069 | |
7cd4527e AC |
25070 | -- output into Register |
25071 | -- register must be a memory location | |
25072 | Outputs => Unsigned_16'Asm_output ("=m", Register)); | |
88e1739c | 25073 | |
7cd4527e AC |
25074 | -- check the relevant bits |
25075 | if (Register and 16#103F#) /= 16#003F# then | |
25076 | return False; -- no control word | |
25077 | end if; -- check control word value | |
88e1739c | 25078 | |
7cd4527e AC |
25079 | -- FPU found |
25080 | return True; | |
88e1739c | 25081 | |
7cd4527e | 25082 | end Has_FPU; |
88e1739c | 25083 | |
7cd4527e AC |
25084 | -------------------------------- |
25085 | -- Detect CPUID instruction -- | |
25086 | -------------------------------- | |
88e1739c | 25087 | |
7cd4527e AC |
25088 | -- The processor supports the CPUID instruction if it is possible |
25089 | -- to change the value of ID flag bit in the EFLAGS register. | |
88e1739c | 25090 | |
7cd4527e | 25091 | function Has_CPUID return Boolean is |
88e1739c | 25092 | |
7cd4527e AC |
25093 | Original_Flags, Modified_Flags : Processor_Register; |
25094 | -- EFLAG contents before and after changing the ID flag | |
88e1739c | 25095 | |
7cd4527e | 25096 | begin |
88e1739c | 25097 | |
7cd4527e AC |
25098 | -- try flipping the ID flag in the EFLAGS register |
25099 | Asm ( | |
88e1739c | 25100 | |
7cd4527e AC |
25101 | -- the assembler code |
25102 | "pushfl" & LF & HT & -- push EFLAGS on stack | |
25103 | "pop %%eax" & LF & HT & -- pop EFLAGS into eax | |
25104 | "movl %%eax, %0" & LF & HT & -- save EFLAGS content | |
25105 | "xor $0x200000, %%eax" & LF & HT & -- flip ID flag | |
25106 | "push %%eax" & LF & HT & -- push EFLAGS on stack | |
25107 | "popfl" & LF & HT & -- load EFLAGS register | |
25108 | "pushfl" & LF & HT & -- push EFLAGS on stack | |
25109 | "pop %1", -- save EFLAGS content | |
88e1739c | 25110 | |
7cd4527e AC |
25111 | -- output values, may be anything |
25112 | -- Original_Flags is %0 | |
25113 | -- Modified_Flags is %1 | |
25114 | Outputs => | |
25115 | (Processor_Register'Asm_output ("=g", Original_Flags), | |
25116 | Processor_Register'Asm_output ("=g", Modified_Flags)), | |
88e1739c | 25117 | |
7cd4527e AC |
25118 | -- tell compiler eax is destroyed |
25119 | Clobber => "eax"); | |
88e1739c | 25120 | |
7cd4527e AC |
25121 | -- check if CPUID is supported |
25122 | if Original_Flags(ID_Flag) /= Modified_Flags(ID_Flag) then | |
25123 | return True; -- ID flag was modified | |
25124 | else | |
25125 | return False; -- ID flag unchanged | |
25126 | end if; -- check for CPUID | |
25127 | ||
25128 | end Has_CPUID; | |
88e1739c | 25129 | |
7cd4527e AC |
25130 | ------------------------------- |
25131 | -- Get CPUID support level -- | |
25132 | ------------------------------- | |
88e1739c | 25133 | |
7cd4527e | 25134 | function CPUID_Level return Natural is |
88e1739c | 25135 | |
7cd4527e AC |
25136 | Level : Unsigned_32; |
25137 | -- returned support level | |
88e1739c | 25138 | |
7cd4527e | 25139 | begin |
88e1739c | 25140 | |
7cd4527e AC |
25141 | -- execute CPUID, storing the results in the Level register |
25142 | Asm ( | |
88e1739c | 25143 | |
7cd4527e AC |
25144 | -- the assembler code |
25145 | "cpuid", -- execute CPUID | |
88e1739c | 25146 | |
7cd4527e AC |
25147 | -- zero is stored in eax |
25148 | -- returning the support level in eax | |
25149 | Inputs => Unsigned_32'Asm_input ("a", 0), | |
88e1739c | 25150 | |
7cd4527e AC |
25151 | -- eax is stored in Level |
25152 | Outputs => Unsigned_32'Asm_output ("=a", Level), | |
88e1739c | 25153 | |
7cd4527e AC |
25154 | -- tell compiler ebx, ecx and edx registers are destroyed |
25155 | Clobber => "ebx, ecx, edx"); | |
88e1739c | 25156 | |
7cd4527e AC |
25157 | -- return the support level |
25158 | return Natural (Level); | |
88e1739c | 25159 | |
7cd4527e | 25160 | end CPUID_Level; |
88e1739c | 25161 | |
7cd4527e AC |
25162 | -------------------------------- |
25163 | -- Get CPU Vendor ID String -- | |
25164 | -------------------------------- | |
88e1739c | 25165 | |
7cd4527e AC |
25166 | -- The vendor ID string is returned in the ebx, ecx and edx register |
25167 | -- after executing the CPUID instruction with eax set to zero. | |
25168 | -- In case of a true Intel processor the string returned is | |
25169 | -- "GenuineIntel" | |
88e1739c | 25170 | |
7cd4527e | 25171 | function Vendor_ID return String is |
88e1739c | 25172 | |
7cd4527e AC |
25173 | Ebx, Ecx, Edx : Unsigned_Register; |
25174 | -- registers containing the vendor ID string | |
88e1739c | 25175 | |
7cd4527e AC |
25176 | Vendor_ID : String (1 .. 12); |
25177 | -- the vendor ID string | |
88e1739c | 25178 | |
7cd4527e | 25179 | begin |
88e1739c | 25180 | |
7cd4527e AC |
25181 | -- execute CPUID, storing the results in the processor registers |
25182 | Asm ( | |
88e1739c | 25183 | |
7cd4527e AC |
25184 | -- the assembler code |
25185 | "cpuid", -- execute CPUID | |
88e1739c | 25186 | |
7cd4527e AC |
25187 | -- zero stored in eax |
25188 | -- vendor ID string returned in ebx, ecx and edx | |
25189 | Inputs => Unsigned_32'Asm_input ("a", 0), | |
88e1739c | 25190 | |
7cd4527e AC |
25191 | -- ebx is stored in Ebx |
25192 | -- ecx is stored in Ecx | |
25193 | -- edx is stored in Edx | |
25194 | Outputs => (Unsigned_Register'Asm_output ("=b", Ebx), | |
25195 | Unsigned_Register'Asm_output ("=c", Ecx), | |
25196 | Unsigned_Register'Asm_output ("=d", Edx))); | |
88e1739c | 25197 | |
7cd4527e AC |
25198 | -- now build the vendor ID string |
25199 | Vendor_ID( 1) := Character'Val (Ebx.L1); | |
25200 | Vendor_ID( 2) := Character'Val (Ebx.H1); | |
25201 | Vendor_ID( 3) := Character'Val (Ebx.L2); | |
25202 | Vendor_ID( 4) := Character'Val (Ebx.H2); | |
25203 | Vendor_ID( 5) := Character'Val (Edx.L1); | |
25204 | Vendor_ID( 6) := Character'Val (Edx.H1); | |
25205 | Vendor_ID( 7) := Character'Val (Edx.L2); | |
25206 | Vendor_ID( 8) := Character'Val (Edx.H2); | |
25207 | Vendor_ID( 9) := Character'Val (Ecx.L1); | |
25208 | Vendor_ID(10) := Character'Val (Ecx.H1); | |
25209 | Vendor_ID(11) := Character'Val (Ecx.L2); | |
25210 | Vendor_ID(12) := Character'Val (Ecx.H2); | |
88e1739c | 25211 | |
7cd4527e AC |
25212 | -- return string |
25213 | return Vendor_ID; | |
88e1739c | 25214 | |
7cd4527e | 25215 | end Vendor_ID; |
88e1739c | 25216 | |
7cd4527e AC |
25217 | ------------------------------- |
25218 | -- Get processor signature -- | |
25219 | ------------------------------- | |
88e1739c | 25220 | |
7cd4527e | 25221 | function Signature return Processor_Signature is |
88e1739c | 25222 | |
7cd4527e AC |
25223 | Result : Processor_Signature; |
25224 | -- processor signature returned | |
88e1739c | 25225 | |
7cd4527e | 25226 | begin |
88e1739c | 25227 | |
7cd4527e AC |
25228 | -- execute CPUID, storing the results in the Result variable |
25229 | Asm ( | |
88e1739c | 25230 | |
7cd4527e AC |
25231 | -- the assembler code |
25232 | "cpuid", -- execute CPUID | |
88e1739c | 25233 | |
7cd4527e AC |
25234 | -- one is stored in eax |
25235 | -- processor signature returned in eax | |
25236 | Inputs => Unsigned_32'Asm_input ("a", 1), | |
88e1739c | 25237 | |
7cd4527e AC |
25238 | -- eax is stored in Result |
25239 | Outputs => Processor_Signature'Asm_output ("=a", Result), | |
88e1739c | 25240 | |
7cd4527e AC |
25241 | -- tell compiler that ebx, ecx and edx are also destroyed |
25242 | Clobber => "ebx, ecx, edx"); | |
88e1739c | 25243 | |
7cd4527e AC |
25244 | -- return processor signature |
25245 | return Result; | |
88e1739c | 25246 | |
7cd4527e | 25247 | end Signature; |
88e1739c | 25248 | |
7cd4527e AC |
25249 | ------------------------------ |
25250 | -- Get processor features -- | |
25251 | ------------------------------ | |
88e1739c | 25252 | |
7cd4527e | 25253 | function Features return Processor_Features is |
88e1739c | 25254 | |
7cd4527e AC |
25255 | Result : Processor_Features; |
25256 | -- processor features returned | |
88e1739c | 25257 | |
7cd4527e | 25258 | begin |
88e1739c | 25259 | |
7cd4527e AC |
25260 | -- execute CPUID, storing the results in the Result variable |
25261 | Asm ( | |
88e1739c | 25262 | |
7cd4527e AC |
25263 | -- the assembler code |
25264 | "cpuid", -- execute CPUID | |
88e1739c | 25265 | |
7cd4527e AC |
25266 | -- one stored in eax |
25267 | -- processor features returned in edx | |
25268 | Inputs => Unsigned_32'Asm_input ("a", 1), | |
88e1739c | 25269 | |
7cd4527e AC |
25270 | -- edx is stored in Result |
25271 | Outputs => Processor_Features'Asm_output ("=d", Result), | |
88e1739c | 25272 | |
7cd4527e AC |
25273 | -- tell compiler that ebx and ecx are also destroyed |
25274 | Clobber => "ebx, ecx"); | |
88e1739c | 25275 | |
7cd4527e AC |
25276 | -- return processor signature |
25277 | return Result; | |
88e1739c | 25278 | |
7cd4527e | 25279 | end Features; |
88e1739c | 25280 | |
7cd4527e | 25281 | end Intel_CPU; |
88e1739c | 25282 | @end smallexample |
7cd4527e AC |
25283 | @c END OF INLINE ASSEMBLER CHAPTER |
25284 | @c =============================== | |
88e1739c | 25285 | |
88e1739c | 25286 | |
88e1739c | 25287 | |
7cd4527e AC |
25288 | @c *********************************** |
25289 | @c * Compatibility and Porting Guide * | |
25290 | @c *********************************** | |
25291 | @node Compatibility and Porting Guide | |
25292 | @appendix Compatibility and Porting Guide | |
88e1739c | 25293 | |
7cd4527e AC |
25294 | @noindent |
25295 | This chapter describes the compatibility issues that may arise between | |
25296 | GNAT and other Ada 83 and Ada 95 compilation systems, and shows how GNAT | |
25297 | can expedite porting | |
25298 | applications developed in other Ada environments. | |
88e1739c | 25299 | |
7cd4527e AC |
25300 | @menu |
25301 | * Compatibility with Ada 83:: | |
25302 | * Implementation-dependent characteristics:: | |
25303 | * Compatibility with DEC Ada 83:: | |
25304 | * Compatibility with Other Ada 95 Systems:: | |
25305 | * Representation Clauses:: | |
25306 | @end menu | |
88e1739c | 25307 | |
7cd4527e AC |
25308 | @node Compatibility with Ada 83 |
25309 | @section Compatibility with Ada 83 | |
25310 | @cindex Compatibility (between Ada 83 and Ada 95) | |
88e1739c FW |
25311 | |
25312 | @noindent | |
7cd4527e AC |
25313 | Ada 95 is designed to be highly upwards compatible with Ada 83. In |
25314 | particular, the design intention is that the difficulties associated | |
25315 | with moving from Ada 83 to Ada 95 should be no greater than those | |
25316 | that occur when moving from one Ada 83 system to another. | |
88e1739c | 25317 | |
7cd4527e AC |
25318 | However, there are a number of points at which there are minor |
25319 | incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains | |
25320 | full details of these issues, | |
25321 | and should be consulted for a complete treatment. | |
25322 | In practice the | |
25323 | following subsections treat the most likely issues to be encountered. | |
88e1739c FW |
25324 | |
25325 | @menu | |
7cd4527e AC |
25326 | * Legal Ada 83 programs that are illegal in Ada 95:: |
25327 | * More deterministic semantics:: | |
25328 | * Changed semantics:: | |
25329 | * Other language compatibility issues:: | |
88e1739c FW |
25330 | @end menu |
25331 | ||
7cd4527e AC |
25332 | @node Legal Ada 83 programs that are illegal in Ada 95 |
25333 | @subsection Legal Ada 83 programs that are illegal in Ada 95 | |
88e1739c | 25334 | |
7cd4527e AC |
25335 | @table @asis |
25336 | @item Character literals | |
25337 | Some uses of character literals are ambiguous. Since Ada 95 has introduced | |
25338 | @code{Wide_Character} as a new predefined character type, some uses of | |
25339 | character literals that were legal in Ada 83 are illegal in Ada 95. | |
25340 | For example: | |
25341 | @smallexample @c ada | |
25342 | for Char in 'A' .. 'Z' loop ... end loop; | |
25343 | @end smallexample | |
88e1739c | 25344 | @noindent |
7cd4527e AC |
25345 | The problem is that @code{'A'} and @code{'Z'} could be from either |
25346 | @code{Character} or @code{Wide_Character}. The simplest correction | |
25347 | is to make the type explicit; e.g.: | |
25348 | @smallexample @c ada | |
25349 | for Char in Character range 'A' .. 'Z' loop ... end loop; | |
25350 | @end smallexample | |
25351 | ||
25352 | @item New reserved words | |
25353 | The identifiers @code{abstract}, @code{aliased}, @code{protected}, | |
25354 | @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. | |
25355 | Existing Ada 83 code using any of these identifiers must be edited to | |
25356 | use some alternative name. | |
25357 | ||
25358 | @item Freezing rules | |
25359 | The rules in Ada 95 are slightly different with regard to the point at | |
25360 | which entities are frozen, and representation pragmas and clauses are | |
25361 | not permitted past the freeze point. This shows up most typically in | |
25362 | the form of an error message complaining that a representation item | |
25363 | appears too late, and the appropriate corrective action is to move | |
25364 | the item nearer to the declaration of the entity to which it refers. | |
25365 | ||
25366 | A particular case is that representation pragmas | |
25367 | @ifset vms | |
25368 | (including the | |
25369 | extended DEC Ada 83 compatibility pragmas such as @code{Export_Procedure}) | |
25370 | @end ifset | |
25371 | cannot be applied to a subprogram body. If necessary, a separate subprogram | |
25372 | declaration must be introduced to which the pragma can be applied. | |
25373 | ||
25374 | @item Optional bodies for library packages | |
25375 | In Ada 83, a package that did not require a package body was nevertheless | |
25376 | allowed to have one. This lead to certain surprises in compiling large | |
25377 | systems (situations in which the body could be unexpectedly ignored by the | |
25378 | binder). In Ada 95, if a package does not require a body then it is not | |
25379 | permitted to have a body. To fix this problem, simply remove a redundant | |
25380 | body if it is empty, or, if it is non-empty, introduce a dummy declaration | |
25381 | into the spec that makes the body required. One approach is to add a private | |
25382 | part to the package declaration (if necessary), and define a parameterless | |
25383 | procedure called @code{Requires_Body}, which must then be given a dummy | |
25384 | procedure body in the package body, which then becomes required. | |
25385 | Another approach (assuming that this does not introduce elaboration | |
25386 | circularities) is to add an @code{Elaborate_Body} pragma to the package spec, | |
25387 | since one effect of this pragma is to require the presence of a package body. | |
25388 | ||
25389 | @item @code{Numeric_Error} is now the same as @code{Constraint_Error} | |
25390 | In Ada 95, the exception @code{Numeric_Error} is a renaming of | |
25391 | @code{Constraint_Error}. | |
25392 | This means that it is illegal to have separate exception handlers for | |
25393 | the two exceptions. The fix is simply to remove the handler for the | |
25394 | @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise | |
25395 | @code{Constraint_Error} in place of @code{Numeric_Error} in all cases). | |
25396 | ||
25397 | @item Indefinite subtypes in generics | |
25398 | In Ada 83, it was permissible to pass an indefinite type (e.g.@: @code{String}) | |
25399 | as the actual for a generic formal private type, but then the instantiation | |
25400 | would be illegal if there were any instances of declarations of variables | |
25401 | of this type in the generic body. In Ada 95, to avoid this clear violation | |
25402 | of the methodological principle known as the ``contract model'', | |
25403 | the generic declaration explicitly indicates whether | |
25404 | or not such instantiations are permitted. If a generic formal parameter | |
25405 | has explicit unknown discriminants, indicated by using @code{(<>)} after the | |
25406 | type name, then it can be instantiated with indefinite types, but no | |
25407 | stand-alone variables can be declared of this type. Any attempt to declare | |
25408 | such a variable will result in an illegality at the time the generic is | |
25409 | declared. If the @code{(<>)} notation is not used, then it is illegal | |
25410 | to instantiate the generic with an indefinite type. | |
25411 | This is the potential incompatibility issue when porting Ada 83 code to Ada 95. | |
25412 | It will show up as a compile time error, and | |
25413 | the fix is usually simply to add the @code{(<>)} to the generic declaration. | |
25414 | @end table | |
25415 | ||
25416 | @node More deterministic semantics | |
25417 | @subsection More deterministic semantics | |
25418 | ||
25419 | @table @asis | |
25420 | @item Conversions | |
25421 | Conversions from real types to integer types round away from 0. In Ada 83 | |
25422 | the conversion Integer(2.5) could deliver either 2 or 3 as its value. This | |
25423 | implementation freedom was intended to support unbiased rounding in | |
25424 | statistical applications, but in practice it interfered with portability. | |
25425 | In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 | |
25426 | is required. Numeric code may be affected by this change in semantics. | |
25427 | Note, though, that this issue is no worse than already existed in Ada 83 | |
25428 | when porting code from one vendor to another. | |
25429 | ||
25430 | @item Tasking | |
25431 | The Real-Time Annex introduces a set of policies that define the behavior of | |
25432 | features that were implementation dependent in Ada 83, such as the order in | |
25433 | which open select branches are executed. | |
25434 | @end table | |
25435 | ||
25436 | @node Changed semantics | |
25437 | @subsection Changed semantics | |
88e1739c FW |
25438 | |
25439 | @noindent | |
7cd4527e AC |
25440 | The worst kind of incompatibility is one where a program that is legal in |
25441 | Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not | |
25442 | possible in Ada 83. Fortunately this is extremely rare, but the one | |
25443 | situation that you should be alert to is the change in the predefined type | |
25444 | @code{Character} from 7-bit ASCII to 8-bit Latin-1. | |
88e1739c | 25445 | |
7cd4527e AC |
25446 | @table @asis |
25447 | @item range of @code{Character} | |
25448 | The range of @code{Standard.Character} is now the full 256 characters | |
25449 | of Latin-1, whereas in most Ada 83 implementations it was restricted | |
25450 | to 128 characters. Although some of the effects of | |
25451 | this change will be manifest in compile-time rejection of legal | |
25452 | Ada 83 programs it is possible for a working Ada 83 program to have | |
25453 | a different effect in Ada 95, one that was not permitted in Ada 83. | |
25454 | As an example, the expression | |
25455 | @code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now | |
25456 | delivers @code{255} as its value. | |
25457 | In general, you should look at the logic of any | |
25458 | character-processing Ada 83 program and see whether it needs to be adapted | |
25459 | to work correctly with Latin-1. Note that the predefined Ada 95 API has a | |
25460 | character handling package that may be relevant if code needs to be adapted | |
25461 | to account for the additional Latin-1 elements. | |
25462 | The desirable fix is to | |
25463 | modify the program to accommodate the full character set, but in some cases | |
25464 | it may be convenient to define a subtype or derived type of Character that | |
25465 | covers only the restricted range. | |
25466 | @cindex Latin-1 | |
25467 | @end table | |
88e1739c | 25468 | |
7cd4527e AC |
25469 | @node Other language compatibility issues |
25470 | @subsection Other language compatibility issues | |
25471 | @table @asis | |
25472 | @item @option{-gnat83 switch} | |
25473 | All implementations of GNAT provide a switch that causes GNAT to operate | |
25474 | in Ada 83 mode. In this mode, some but not all compatibility problems | |
25475 | of the type described above are handled automatically. For example, the | |
25476 | new Ada 95 reserved words are treated simply as identifiers as in Ada 83. | |
25477 | However, | |
25478 | in practice, it is usually advisable to make the necessary modifications | |
25479 | to the program to remove the need for using this switch. | |
25480 | See @ref{Compiling Ada 83 Programs}. | |
25481 | ||
25482 | @item Support for removed Ada 83 pragmas and attributes | |
25483 | A number of pragmas and attributes from Ada 83 have been removed from Ada 95, | |
25484 | generally because they have been replaced by other mechanisms. Ada 95 | |
25485 | compilers are allowed, but not required, to implement these missing | |
25486 | elements. In contrast with some other Ada 95 compilers, GNAT implements all | |
25487 | such pragmas and attributes, eliminating this compatibility concern. These | |
25488 | include @code{pragma Interface} and the floating point type attributes | |
25489 | (@code{Emax}, @code{Mantissa}, etc.), among other items. | |
25490 | @end table | |
88e1739c | 25491 | |
88e1739c | 25492 | |
7cd4527e AC |
25493 | @node Implementation-dependent characteristics |
25494 | @section Implementation-dependent characteristics | |
25495 | @noindent | |
25496 | Although the Ada language defines the semantics of each construct as | |
25497 | precisely as practical, in some situations (for example for reasons of | |
25498 | efficiency, or where the effect is heavily dependent on the host or target | |
25499 | platform) the implementation is allowed some freedom. In porting Ada 83 | |
25500 | code to GNAT, you need to be aware of whether / how the existing code | |
25501 | exercised such implementation dependencies. Such characteristics fall into | |
25502 | several categories, and GNAT offers specific support in assisting the | |
25503 | transition from certain Ada 83 compilers. | |
88e1739c | 25504 | |
7cd4527e AC |
25505 | @menu |
25506 | * Implementation-defined pragmas:: | |
25507 | * Implementation-defined attributes:: | |
25508 | * Libraries:: | |
25509 | * Elaboration order:: | |
25510 | * Target-specific aspects:: | |
25511 | @end menu | |
88e1739c | 25512 | |
7cd4527e AC |
25513 | |
25514 | @node Implementation-defined pragmas | |
25515 | @subsection Implementation-defined pragmas | |
25516 | ||
25517 | @noindent | |
25518 | Ada compilers are allowed to supplement the language-defined pragmas, and | |
25519 | these are a potential source of non-portability. All GNAT-defined pragmas | |
25520 | are described in the GNAT Reference Manual, and these include several that | |
25521 | are specifically intended to correspond to other vendors' Ada 83 pragmas. | |
25522 | For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. | |
25523 | For | |
25524 | compatibility with DEC Ada 83, GNAT supplies the pragmas | |
25525 | @code{Extend_System}, @code{Ident}, @code{Inline_Generic}, | |
25526 | @code{Interface_Name}, @code{Passive}, @code{Suppress_All}, | |
25527 | and @code{Volatile}. | |
25528 | Other relevant pragmas include @code{External} and @code{Link_With}. | |
25529 | Some vendor-specific | |
25530 | Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are | |
25531 | recognized, thus | |
25532 | avoiding compiler rejection of units that contain such pragmas; they are not | |
25533 | relevant in a GNAT context and hence are not otherwise implemented. | |
25534 | ||
25535 | @node Implementation-defined attributes | |
25536 | @subsection Implementation-defined attributes | |
25537 | ||
25538 | Analogous to pragmas, the set of attributes may be extended by an | |
25539 | implementation. All GNAT-defined attributes are described in the | |
25540 | @cite{GNAT Reference Manual}, and these include several that are specifically | |
25541 | intended | |
25542 | to correspond to other vendors' Ada 83 attributes. For migrating from VADS, | |
25543 | the attribute @code{VADS_Size} may be useful. For compatibility with DEC | |
25544 | Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and | |
25545 | @code{Type_Class}. | |
25546 | ||
25547 | @node Libraries | |
25548 | @subsection Libraries | |
25549 | @noindent | |
25550 | Vendors may supply libraries to supplement the standard Ada API. If Ada 83 | |
25551 | code uses vendor-specific libraries then there are several ways to manage | |
25552 | this in Ada 95: | |
25553 | @enumerate | |
88e1739c | 25554 | @item |
7cd4527e AC |
25555 | If the source code for the libraries (specifications and bodies) are |
25556 | available, then the libraries can be migrated in the same way as the | |
25557 | application. | |
25558 | @item | |
25559 | If the source code for the specifications but not the bodies are | |
25560 | available, then you can reimplement the bodies. | |
25561 | @item | |
25562 | Some new Ada 95 features obviate the need for library support. For | |
25563 | example most Ada 83 vendors supplied a package for unsigned integers. The | |
25564 | Ada 95 modular type feature is the preferred way to handle this need, so | |
25565 | instead of migrating or reimplementing the unsigned integer package it may | |
25566 | be preferable to retrofit the application using modular types. | |
25567 | @end enumerate | |
88e1739c | 25568 | |
7cd4527e AC |
25569 | @node Elaboration order |
25570 | @subsection Elaboration order | |
25571 | @noindent | |
25572 | The implementation can choose any elaboration order consistent with the unit | |
25573 | dependency relationship. This freedom means that some orders can result in | |
25574 | Program_Error being raised due to an ``Access Before Elaboration'': an attempt | |
25575 | to invoke a subprogram its body has been elaborated, or to instantiate a | |
25576 | generic before the generic body has been elaborated. By default GNAT | |
25577 | attempts to choose a safe order (one that will not encounter access before | |
25578 | elaboration problems) by implicitly inserting Elaborate_All pragmas where | |
25579 | needed. However, this can lead to the creation of elaboration circularities | |
25580 | and a resulting rejection of the program by gnatbind. This issue is | |
25581 | thoroughly described in @ref{Elaboration Order Handling in GNAT}. | |
25582 | In brief, there are several | |
25583 | ways to deal with this situation: | |
88e1739c | 25584 | |
7cd4527e | 25585 | @itemize @bullet |
88e1739c | 25586 | @item |
7cd4527e AC |
25587 | Modify the program to eliminate the circularities, e.g. by moving |
25588 | elaboration-time code into explicitly-invoked procedures | |
25589 | @item | |
25590 | Constrain the elaboration order by including explicit @code{Elaborate_Body} or | |
25591 | @code{Elaborate} pragmas, and then inhibit the generation of implicit | |
25592 | @code{Elaborate_All} | |
25593 | pragmas either globally (as an effect of the @option{-gnatE} switch) or locally | |
25594 | (by selectively suppressing elaboration checks via pragma | |
25595 | @code{Suppress(Elaboration_Check)} when it is safe to do so). | |
25596 | @end itemize | |
88e1739c | 25597 | |
7cd4527e AC |
25598 | @node Target-specific aspects |
25599 | @subsection Target-specific aspects | |
88e1739c | 25600 | @noindent |
7cd4527e AC |
25601 | Low-level applications need to deal with machine addresses, data |
25602 | representations, interfacing with assembler code, and similar issues. If | |
25603 | such an Ada 83 application is being ported to different target hardware (for | |
25604 | example where the byte endianness has changed) then you will need to | |
25605 | carefully examine the program logic; the porting effort will heavily depend | |
25606 | on the robustness of the original design. Moreover, Ada 95 is sometimes | |
25607 | incompatible with typical Ada 83 compiler practices regarding implicit | |
25608 | packing, the meaning of the Size attribute, and the size of access values. | |
25609 | GNAT's approach to these issues is described in @ref{Representation Clauses}. | |
88e1739c | 25610 | |
7cd4527e AC |
25611 | |
25612 | @node Compatibility with Other Ada 95 Systems | |
25613 | @section Compatibility with Other Ada 95 Systems | |
88e1739c FW |
25614 | |
25615 | @noindent | |
7cd4527e AC |
25616 | Providing that programs avoid the use of implementation dependent and |
25617 | implementation defined features of Ada 95, as documented in the Ada 95 | |
25618 | reference manual, there should be a high degree of portability between | |
25619 | GNAT and other Ada 95 systems. The following are specific items which | |
25620 | have proved troublesome in moving GNAT programs to other Ada 95 | |
25621 | compilers, but do not affect porting code to GNAT@. | |
88e1739c | 25622 | |
7cd4527e AC |
25623 | @table @asis |
25624 | @item Ada 83 Pragmas and Attributes | |
25625 | Ada 95 compilers are allowed, but not required, to implement the missing | |
25626 | Ada 83 pragmas and attributes that are no longer defined in Ada 95. | |
25627 | GNAT implements all such pragmas and attributes, eliminating this as | |
25628 | a compatibility concern, but some other Ada 95 compilers reject these | |
25629 | pragmas and attributes. | |
25630 | ||
25631 | @item Special-needs Annexes | |
25632 | GNAT implements the full set of special needs annexes. At the | |
25633 | current time, it is the only Ada 95 compiler to do so. This means that | |
25634 | programs making use of these features may not be portable to other Ada | |
25635 | 95 compilation systems. | |
25636 | ||
25637 | @item Representation Clauses | |
25638 | Some other Ada 95 compilers implement only the minimal set of | |
25639 | representation clauses required by the Ada 95 reference manual. GNAT goes | |
25640 | far beyond this minimal set, as described in the next section. | |
25641 | @end table | |
25642 | ||
25643 | @node Representation Clauses | |
25644 | @section Representation Clauses | |
88e1739c FW |
25645 | |
25646 | @noindent | |
7cd4527e AC |
25647 | The Ada 83 reference manual was quite vague in describing both the minimal |
25648 | required implementation of representation clauses, and also their precise | |
25649 | effects. The Ada 95 reference manual is much more explicit, but the minimal | |
25650 | set of capabilities required in Ada 95 is quite limited. | |
88e1739c | 25651 | |
7cd4527e AC |
25652 | GNAT implements the full required set of capabilities described in the |
25653 | Ada 95 reference manual, but also goes much beyond this, and in particular | |
25654 | an effort has been made to be compatible with existing Ada 83 usage to the | |
25655 | greatest extent possible. | |
88e1739c | 25656 | |
7cd4527e AC |
25657 | A few cases exist in which Ada 83 compiler behavior is incompatible with |
25658 | requirements in the Ada 95 reference manual. These are instances of | |
25659 | intentional or accidental dependence on specific implementation dependent | |
25660 | characteristics of these Ada 83 compilers. The following is a list of | |
25661 | the cases most likely to arise in existing legacy Ada 83 code. | |
88e1739c | 25662 | |
7cd4527e AC |
25663 | @table @asis |
25664 | @item Implicit Packing | |
25665 | Some Ada 83 compilers allowed a Size specification to cause implicit | |
25666 | packing of an array or record. This could cause expensive implicit | |
25667 | conversions for change of representation in the presence of derived | |
25668 | types, and the Ada design intends to avoid this possibility. | |
25669 | Subsequent AI's were issued to make it clear that such implicit | |
25670 | change of representation in response to a Size clause is inadvisable, | |
25671 | and this recommendation is represented explicitly in the Ada 95 RM | |
25672 | as implementation advice that is followed by GNAT@. | |
25673 | The problem will show up as an error | |
25674 | message rejecting the size clause. The fix is simply to provide | |
25675 | the explicit pragma @code{Pack}, or for more fine tuned control, provide | |
25676 | a Component_Size clause. | |
25677 | ||
25678 | @item Meaning of Size Attribute | |
25679 | The Size attribute in Ada 95 for discrete types is defined as being the | |
25680 | minimal number of bits required to hold values of the type. For example, | |
25681 | on a 32-bit machine, the size of Natural will typically be 31 and not | |
25682 | 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and | |
25683 | some 32 in this situation. This problem will usually show up as a compile | |
25684 | time error, but not always. It is a good idea to check all uses of the | |
25685 | 'Size attribute when porting Ada 83 code. The GNAT specific attribute | |
25686 | Object_Size can provide a useful way of duplicating the behavior of | |
25687 | some Ada 83 compiler systems. | |
25688 | ||
25689 | @item Size of Access Types | |
25690 | A common assumption in Ada 83 code is that an access type is in fact a pointer, | |
25691 | and that therefore it will be the same size as a System.Address value. This | |
25692 | assumption is true for GNAT in most cases with one exception. For the case of | |
25693 | a pointer to an unconstrained array type (where the bounds may vary from one | |
25694 | value of the access type to another), the default is to use a ``fat pointer'', | |
25695 | which is represented as two separate pointers, one to the bounds, and one to | |
25696 | the array. This representation has a number of advantages, including improved | |
25697 | efficiency. However, it may cause some difficulties in porting existing Ada 83 | |
25698 | code which makes the assumption that, for example, pointers fit in 32 bits on | |
25699 | a machine with 32-bit addressing. | |
25700 | ||
25701 | To get around this problem, GNAT also permits the use of ``thin pointers'' for | |
25702 | access types in this case (where the designated type is an unconstrained array | |
25703 | type). These thin pointers are indeed the same size as a System.Address value. | |
25704 | To specify a thin pointer, use a size clause for the type, for example: | |
25705 | ||
25706 | @smallexample @c ada | |
25707 | type X is access all String; | |
25708 | for X'Size use Standard'Address_Size; | |
25709 | @end smallexample | |
25710 | ||
25711 | @noindent | |
25712 | which will cause the type X to be represented using a single pointer. | |
25713 | When using this representation, the bounds are right behind the array. | |
25714 | This representation is slightly less efficient, and does not allow quite | |
25715 | such flexibility in the use of foreign pointers or in using the | |
25716 | Unrestricted_Access attribute to create pointers to non-aliased objects. | |
25717 | But for any standard portable use of the access type it will work in | |
25718 | a functionally correct manner and allow porting of existing code. | |
25719 | Note that another way of forcing a thin pointer representation | |
25720 | is to use a component size clause for the element size in an array, | |
25721 | or a record representation clause for an access field in a record. | |
25722 | @end table | |
88e1739c | 25723 | |
7cd4527e AC |
25724 | @node Compatibility with DEC Ada 83 |
25725 | @section Compatibility with DEC Ada 83 | |
88e1739c | 25726 | |
7cd4527e AC |
25727 | @noindent |
25728 | The VMS version of GNAT fully implements all the pragmas and attributes | |
25729 | provided by DEC Ada 83, as well as providing the standard DEC Ada 83 | |
25730 | libraries, including Starlet. In addition, data layouts and parameter | |
25731 | passing conventions are highly compatible. This means that porting | |
25732 | existing DEC Ada 83 code to GNAT in VMS systems should be easier than | |
25733 | most other porting efforts. The following are some of the most | |
25734 | significant differences between GNAT and DEC Ada 83. | |
88e1739c | 25735 | |
7cd4527e AC |
25736 | @table @asis |
25737 | @item Default floating-point representation | |
25738 | In GNAT, the default floating-point format is IEEE, whereas in DEC Ada 83, | |
25739 | it is VMS format. GNAT does implement the necessary pragmas | |
25740 | (Long_Float, Float_Representation) for changing this default. | |
88e1739c | 25741 | |
7cd4527e AC |
25742 | @item System |
25743 | The package System in GNAT exactly corresponds to the definition in the | |
25744 | Ada 95 reference manual, which means that it excludes many of the | |
25745 | DEC Ada 83 extensions. However, a separate package Aux_DEC is provided | |
25746 | that contains the additional definitions, and a special pragma, | |
25747 | Extend_System allows this package to be treated transparently as an | |
25748 | extension of package System. | |
88e1739c | 25749 | |
7cd4527e AC |
25750 | @item To_Address |
25751 | The definitions provided by Aux_DEC are exactly compatible with those | |
25752 | in the DEC Ada 83 version of System, with one exception. | |
25753 | DEC Ada provides the following declarations: | |
25754 | ||
25755 | @smallexample @c ada | |
25756 | TO_ADDRESS (INTEGER) | |
25757 | TO_ADDRESS (UNSIGNED_LONGWORD) | |
25758 | TO_ADDRESS (universal_integer) | |
88e1739c FW |
25759 | @end smallexample |
25760 | ||
7cd4527e AC |
25761 | @noindent |
25762 | The version of TO_ADDRESS taking a universal integer argument is in fact | |
25763 | an extension to Ada 83 not strictly compatible with the reference manual. | |
25764 | In GNAT, we are constrained to be exactly compatible with the standard, | |
25765 | and this means we cannot provide this capability. In DEC Ada 83, the | |
25766 | point of this definition is to deal with a call like: | |
88e1739c | 25767 | |
7cd4527e AC |
25768 | @smallexample @c ada |
25769 | TO_ADDRESS (16#12777#); | |
88e1739c FW |
25770 | @end smallexample |
25771 | ||
7cd4527e AC |
25772 | @noindent |
25773 | Normally, according to the Ada 83 standard, one would expect this to be | |
25774 | ambiguous, since it matches both the INTEGER and UNSIGNED_LONGWORD forms | |
25775 | of TO_ADDRESS@. However, in DEC Ada 83, there is no ambiguity, since the | |
25776 | definition using universal_integer takes precedence. | |
88e1739c | 25777 | |
7cd4527e AC |
25778 | In GNAT, since the version with universal_integer cannot be supplied, it is |
25779 | not possible to be 100% compatible. Since there are many programs using | |
25780 | numeric constants for the argument to TO_ADDRESS, the decision in GNAT was | |
25781 | to change the name of the function in the UNSIGNED_LONGWORD case, so the | |
25782 | declarations provided in the GNAT version of AUX_Dec are: | |
88e1739c | 25783 | |
7cd4527e AC |
25784 | @smallexample @c ada |
25785 | function To_Address (X : Integer) return Address; | |
25786 | pragma Pure_Function (To_Address); | |
88e1739c | 25787 | |
7cd4527e AC |
25788 | function To_Address_Long (X : Unsigned_Longword) |
25789 | return Address; | |
25790 | pragma Pure_Function (To_Address_Long); | |
88e1739c FW |
25791 | @end smallexample |
25792 | ||
88e1739c | 25793 | @noindent |
7cd4527e AC |
25794 | This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must |
25795 | change the name to TO_ADDRESS_LONG@. | |
88e1739c | 25796 | |
7cd4527e AC |
25797 | @item Task_Id values |
25798 | The Task_Id values assigned will be different in the two systems, and GNAT | |
25799 | does not provide a specified value for the Task_Id of the environment task, | |
25800 | which in GNAT is treated like any other declared task. | |
25801 | @end table | |
88e1739c | 25802 | |
7cd4527e AC |
25803 | For full details on these and other less significant compatibility issues, |
25804 | see appendix E of the Digital publication entitled @cite{DEC Ada, Technical | |
25805 | Overview and Comparison on DIGITAL Platforms}. | |
88e1739c | 25806 | |
7cd4527e AC |
25807 | For GNAT running on other than VMS systems, all the DEC Ada 83 pragmas and |
25808 | attributes are recognized, although only a subset of them can sensibly | |
25809 | be implemented. The description of pragmas in this reference manual | |
25810 | indicates whether or not they are applicable to non-VMS systems. | |
88e1739c | 25811 | |
88e1739c | 25812 | |
7cd4527e AC |
25813 | |
25814 | @ifset unw | |
25815 | @node Microsoft Windows Topics | |
25816 | @appendix Microsoft Windows Topics | |
25817 | @cindex Windows NT | |
25818 | @cindex Windows 95 | |
25819 | @cindex Windows 98 | |
88e1739c FW |
25820 | |
25821 | @noindent | |
7cd4527e AC |
25822 | This chapter describes topics that are specific to the Microsoft Windows |
25823 | platforms (NT, 2000, and XP Professional). | |
88e1739c | 25824 | |
7cd4527e AC |
25825 | @menu |
25826 | * Using GNAT on Windows:: | |
25827 | * Using a network installation of GNAT:: | |
25828 | * CONSOLE and WINDOWS subsystems:: | |
25829 | * Temporary Files:: | |
25830 | * Mixed-Language Programming on Windows:: | |
25831 | * Windows Calling Conventions:: | |
25832 | * Introduction to Dynamic Link Libraries (DLLs):: | |
25833 | * Using DLLs with GNAT:: | |
25834 | * Building DLLs with GNAT:: | |
25835 | * GNAT and Windows Resources:: | |
25836 | * Debugging a DLL:: | |
25837 | * GNAT and COM/DCOM Objects:: | |
25838 | @end menu | |
88e1739c | 25839 | |
7cd4527e AC |
25840 | @node Using GNAT on Windows |
25841 | @section Using GNAT on Windows | |
88e1739c FW |
25842 | |
25843 | @noindent | |
7cd4527e AC |
25844 | One of the strengths of the GNAT technology is that its tool set |
25845 | (@code{gcc}, @code{gnatbind}, @code{gnatlink}, @code{gnatmake}, the | |
25846 | @code{gdb} debugger, etc.) is used in the same way regardless of the | |
25847 | platform. | |
88e1739c | 25848 | |
7cd4527e AC |
25849 | On Windows this tool set is complemented by a number of Microsoft-specific |
25850 | tools that have been provided to facilitate interoperability with Windows | |
25851 | when this is required. With these tools: | |
88e1739c | 25852 | |
7cd4527e | 25853 | @itemize @bullet |
88e1739c | 25854 | |
7cd4527e AC |
25855 | @item |
25856 | You can build applications using the @code{CONSOLE} or @code{WINDOWS} | |
25857 | subsystems. | |
88e1739c | 25858 | |
7cd4527e AC |
25859 | @item |
25860 | You can use any Dynamically Linked Library (DLL) in your Ada code (both | |
25861 | relocatable and non-relocatable DLLs are supported). | |
88e1739c | 25862 | |
7cd4527e AC |
25863 | @item |
25864 | You can build Ada DLLs for use in other applications. These applications | |
25865 | can be written in a language other than Ada (e.g., C, C++, etc). Again both | |
25866 | relocatable and non-relocatable Ada DLLs are supported. | |
88e1739c | 25867 | |
7cd4527e AC |
25868 | @item |
25869 | You can include Windows resources in your Ada application. | |
88e1739c | 25870 | |
7cd4527e AC |
25871 | @item |
25872 | You can use or create COM/DCOM objects. | |
25873 | @end itemize | |
88e1739c FW |
25874 | |
25875 | @noindent | |
7cd4527e AC |
25876 | Immediately below are listed all known general GNAT-for-Windows restrictions. |
25877 | Other restrictions about specific features like Windows Resources and DLLs | |
25878 | are listed in separate sections below. | |
88e1739c | 25879 | |
7cd4527e | 25880 | @itemize @bullet |
88e1739c | 25881 | |
7cd4527e AC |
25882 | @item |
25883 | It is not possible to use @code{GetLastError} and @code{SetLastError} | |
25884 | when tasking, protected records, or exceptions are used. In these | |
25885 | cases, in order to implement Ada semantics, the GNAT run-time system | |
25886 | calls certain Win32 routines that set the last error variable to 0 upon | |
25887 | success. It should be possible to use @code{GetLastError} and | |
25888 | @code{SetLastError} when tasking, protected record, and exception | |
25889 | features are not used, but it is not guaranteed to work. | |
88e1739c | 25890 | |
7cd4527e AC |
25891 | @item |
25892 | It is not possible to link against Microsoft libraries except for | |
25893 | import libraries. The library must be built to be compatible with | |
25894 | @file{MSVCRT.LIB} (/MD Microsoft compiler option), @file{LIBC.LIB} and | |
25895 | @file{LIBCMT.LIB} (/ML or /MT Microsoft compiler options) are known to | |
25896 | not be compatible with the GNAT runtime. Even if the library is | |
25897 | compatible with @file{MSVCRT.LIB} it is not guaranteed to work. | |
88e1739c | 25898 | |
7cd4527e AC |
25899 | @item |
25900 | When the compilation environment is located on FAT32 drives, users may | |
25901 | experience recompilations of the source files that have not changed if | |
25902 | Daylight Saving Time (DST) state has changed since the last time files | |
25903 | were compiled. NTFS drives do not have this problem. | |
88e1739c | 25904 | |
7cd4527e AC |
25905 | @item |
25906 | No components of the GNAT toolset use any entries in the Windows | |
25907 | registry. The only entries that can be created are file associations and | |
25908 | PATH settings, provided the user has chosen to create them at installation | |
25909 | time, as well as some minimal book-keeping information needed to correctly | |
25910 | uninstall or integrate different GNAT products. | |
25911 | @end itemize | |
88e1739c | 25912 | |
7cd4527e AC |
25913 | @node Using a network installation of GNAT |
25914 | @section Using a network installation of GNAT | |
88e1739c FW |
25915 | |
25916 | @noindent | |
7cd4527e AC |
25917 | Make sure the system on which GNAT is installed is accessible from the |
25918 | current machine, i.e. the install location is shared over the network. | |
25919 | Shared resources are accessed on Windows by means of UNC paths, which | |
25920 | have the format @code{\\server\sharename\path} | |
25921 | ||
25922 | In order to use such a network installation, simply add the UNC path of the | |
25923 | @file{bin} directory of your GNAT installation in front of your PATH. For | |
25924 | example, if GNAT is installed in @file{\GNAT} directory of a share location | |
25925 | called @file{c-drive} on a machine @file{LOKI}, the following command will | |
25926 | make it available: | |
25927 | ||
25928 | @code{@ @ @ path \\loki\c-drive\gnat\bin;%path%} | |
25929 | ||
25930 | Be aware that every compilation using the network installation results in the | |
25931 | transfer of large amounts of data across the network and will likely cause | |
25932 | serious performance penalty. | |
25933 | ||
25934 | @node CONSOLE and WINDOWS subsystems | |
25935 | @section CONSOLE and WINDOWS subsystems | |
25936 | @cindex CONSOLE Subsystem | |
25937 | @cindex WINDOWS Subsystem | |
25938 | @cindex -mwindows | |
88e1739c | 25939 | |
7cd4527e AC |
25940 | @noindent |
25941 | There are two main subsystems under Windows. The @code{CONSOLE} subsystem | |
25942 | (which is the default subsystem) will always create a console when | |
25943 | launching the application. This is not something desirable when the | |
25944 | application has a Windows GUI. To get rid of this console the | |
25945 | application must be using the @code{WINDOWS} subsystem. To do so | |
25946 | the @option{-mwindows} linker option must be specified. | |
88e1739c FW |
25947 | |
25948 | @smallexample | |
7cd4527e | 25949 | $ gnatmake winprog -largs -mwindows |
88e1739c FW |
25950 | @end smallexample |
25951 | ||
7cd4527e AC |
25952 | @node Temporary Files |
25953 | @section Temporary Files | |
25954 | @cindex Temporary files | |
88e1739c FW |
25955 | |
25956 | @noindent | |
7cd4527e AC |
25957 | It is possible to control where temporary files gets created by setting |
25958 | the TMP environment variable. The file will be created: | |
88e1739c | 25959 | |
7cd4527e AC |
25960 | @itemize |
25961 | @item Under the directory pointed to by the TMP environment variable if | |
25962 | this directory exists. | |
88e1739c | 25963 | |
7cd4527e AC |
25964 | @item Under c:\temp, if the TMP environment variable is not set (or not |
25965 | pointing to a directory) and if this directory exists. | |
88e1739c | 25966 | |
7cd4527e AC |
25967 | @item Under the current working directory otherwise. |
25968 | @end itemize | |
88e1739c FW |
25969 | |
25970 | @noindent | |
7cd4527e AC |
25971 | This allows you to determine exactly where the temporary |
25972 | file will be created. This is particularly useful in networked | |
25973 | environments where you may not have write access to some | |
25974 | directories. | |
88e1739c | 25975 | |
7cd4527e AC |
25976 | @node Mixed-Language Programming on Windows |
25977 | @section Mixed-Language Programming on Windows | |
88e1739c FW |
25978 | |
25979 | @noindent | |
7cd4527e AC |
25980 | Developing pure Ada applications on Windows is no different than on |
25981 | other GNAT-supported platforms. However, when developing or porting an | |
25982 | application that contains a mix of Ada and C/C++, the choice of your | |
25983 | Windows C/C++ development environment conditions your overall | |
25984 | interoperability strategy. | |
25985 | ||
25986 | If you use @code{gcc} to compile the non-Ada part of your application, | |
25987 | there are no Windows-specific restrictions that affect the overall | |
25988 | interoperability with your Ada code. If you plan to use | |
25989 | Microsoft tools (e.g. Microsoft Visual C/C++), you should be aware of | |
25990 | the following limitations: | |
88e1739c FW |
25991 | |
25992 | @itemize @bullet | |
25993 | @item | |
7cd4527e AC |
25994 | You cannot link your Ada code with an object or library generated with |
25995 | Microsoft tools if these use the @code{.tls} section (Thread Local | |
25996 | Storage section) since the GNAT linker does not yet support this section. | |
88e1739c FW |
25997 | |
25998 | @item | |
7cd4527e AC |
25999 | You cannot link your Ada code with an object or library generated with |
26000 | Microsoft tools if these use I/O routines other than those provided in | |
26001 | the Microsoft DLL: @code{msvcrt.dll}. This is because the GNAT run time | |
26002 | uses the services of @code{msvcrt.dll} for its I/Os. Use of other I/O | |
26003 | libraries can cause a conflict with @code{msvcrt.dll} services. For | |
26004 | instance Visual C++ I/O stream routines conflict with those in | |
26005 | @code{msvcrt.dll}. | |
88e1739c FW |
26006 | @end itemize |
26007 | ||
88e1739c | 26008 | @noindent |
7cd4527e AC |
26009 | If you do want to use the Microsoft tools for your non-Ada code and hit one |
26010 | of the above limitations, you have two choices: | |
88e1739c | 26011 | |
7cd4527e AC |
26012 | @enumerate |
26013 | @item | |
26014 | Encapsulate your non Ada code in a DLL to be linked with your Ada | |
26015 | application. In this case, use the Microsoft or whatever environment to | |
26016 | build the DLL and use GNAT to build your executable | |
26017 | (@pxref{Using DLLs with GNAT}). | |
88e1739c | 26018 | |
7cd4527e AC |
26019 | @item |
26020 | Or you can encapsulate your Ada code in a DLL to be linked with the | |
26021 | other part of your application. In this case, use GNAT to build the DLL | |
26022 | (@pxref{Building DLLs with GNAT}) and use the Microsoft or whatever | |
26023 | environment to build your executable. | |
26024 | @end enumerate | |
88e1739c | 26025 | |
7cd4527e AC |
26026 | @node Windows Calling Conventions |
26027 | @section Windows Calling Conventions | |
26028 | @findex Stdcall | |
26029 | @findex APIENTRY | |
88e1739c | 26030 | |
7cd4527e AC |
26031 | @menu |
26032 | * C Calling Convention:: | |
26033 | * Stdcall Calling Convention:: | |
26034 | * DLL Calling Convention:: | |
26035 | @end menu | |
88e1739c FW |
26036 | |
26037 | @noindent | |
7cd4527e AC |
26038 | When a subprogram @code{F} (caller) calls a subprogram @code{G} |
26039 | (callee), there are several ways to push @code{G}'s parameters on the | |
26040 | stack and there are several possible scenarios to clean up the stack | |
26041 | upon @code{G}'s return. A calling convention is an agreed upon software | |
26042 | protocol whereby the responsibilities between the caller (@code{F}) and | |
26043 | the callee (@code{G}) are clearly defined. Several calling conventions | |
26044 | are available for Windows: | |
88e1739c FW |
26045 | |
26046 | @itemize @bullet | |
26047 | @item | |
7cd4527e | 26048 | @code{C} (Microsoft defined) |
88e1739c FW |
26049 | |
26050 | @item | |
7cd4527e | 26051 | @code{Stdcall} (Microsoft defined) |
88e1739c FW |
26052 | |
26053 | @item | |
7cd4527e | 26054 | @code{DLL} (GNAT specific) |
88e1739c FW |
26055 | @end itemize |
26056 | ||
7cd4527e AC |
26057 | @node C Calling Convention |
26058 | @subsection @code{C} Calling Convention | |
88e1739c FW |
26059 | |
26060 | @noindent | |
7cd4527e AC |
26061 | This is the default calling convention used when interfacing to C/C++ |
26062 | routines compiled with either @code{gcc} or Microsoft Visual C++. | |
88e1739c | 26063 | |
7cd4527e AC |
26064 | In the @code{C} calling convention subprogram parameters are pushed on the |
26065 | stack by the caller from right to left. The caller itself is in charge of | |
26066 | cleaning up the stack after the call. In addition, the name of a routine | |
26067 | with @code{C} calling convention is mangled by adding a leading underscore. | |
88e1739c | 26068 | |
7cd4527e AC |
26069 | The name to use on the Ada side when importing (or exporting) a routine |
26070 | with @code{C} calling convention is the name of the routine. For | |
26071 | instance the C function: | |
88e1739c FW |
26072 | |
26073 | @smallexample | |
7cd4527e AC |
26074 | int get_val (long); |
26075 | @end smallexample | |
88e1739c | 26076 | |
7cd4527e AC |
26077 | @noindent |
26078 | should be imported from Ada as follows: | |
88e1739c | 26079 | |
7cd4527e AC |
26080 | @smallexample @c ada |
26081 | @group | |
26082 | function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; | |
26083 | pragma Import (C, Get_Val, External_Name => "get_val"); | |
26084 | @end group | |
26085 | @end smallexample | |
88e1739c | 26086 | |
7cd4527e AC |
26087 | @noindent |
26088 | Note that in this particular case the @code{External_Name} parameter could | |
26089 | have been omitted since, when missing, this parameter is taken to be the | |
26090 | name of the Ada entity in lower case. When the @code{Link_Name} parameter | |
26091 | is missing, as in the above example, this parameter is set to be the | |
26092 | @code{External_Name} with a leading underscore. | |
88e1739c | 26093 | |
7cd4527e AC |
26094 | When importing a variable defined in C, you should always use the @code{C} |
26095 | calling convention unless the object containing the variable is part of a | |
26096 | DLL (in which case you should use the @code{DLL} calling convention, | |
26097 | @pxref{DLL Calling Convention}). | |
88e1739c | 26098 | |
7cd4527e AC |
26099 | @node Stdcall Calling Convention |
26100 | @subsection @code{Stdcall} Calling Convention | |
88e1739c | 26101 | |
7cd4527e AC |
26102 | @noindent |
26103 | This convention, which was the calling convention used for Pascal | |
26104 | programs, is used by Microsoft for all the routines in the Win32 API for | |
26105 | efficiency reasons. It must be used to import any routine for which this | |
26106 | convention was specified. | |
88e1739c | 26107 | |
7cd4527e AC |
26108 | In the @code{Stdcall} calling convention subprogram parameters are pushed |
26109 | on the stack by the caller from right to left. The callee (and not the | |
26110 | caller) is in charge of cleaning the stack on routine exit. In addition, | |
26111 | the name of a routine with @code{Stdcall} calling convention is mangled by | |
26112 | adding a leading underscore (as for the @code{C} calling convention) and a | |
26113 | trailing @code{@@}@code{@i{nn}}, where @i{nn} is the overall size (in | |
26114 | bytes) of the parameters passed to the routine. | |
88e1739c | 26115 | |
7cd4527e AC |
26116 | The name to use on the Ada side when importing a C routine with a |
26117 | @code{Stdcall} calling convention is the name of the C routine. The leading | |
26118 | underscore and trailing @code{@@}@code{@i{nn}} are added automatically by | |
26119 | the compiler. For instance the Win32 function: | |
88e1739c | 26120 | |
7cd4527e AC |
26121 | @smallexample |
26122 | @b{APIENTRY} int get_val (long); | |
26123 | @end smallexample | |
88e1739c | 26124 | |
7cd4527e AC |
26125 | @noindent |
26126 | should be imported from Ada as follows: | |
88e1739c | 26127 | |
7cd4527e AC |
26128 | @smallexample @c ada |
26129 | @group | |
26130 | function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; | |
26131 | pragma Import (Stdcall, Get_Val); | |
26132 | -- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4" | |
26133 | @end group | |
26134 | @end smallexample | |
88e1739c | 26135 | |
7cd4527e AC |
26136 | @noindent |
26137 | As for the @code{C} calling convention, when the @code{External_Name} | |
26138 | parameter is missing, it is taken to be the name of the Ada entity in lower | |
26139 | case. If instead of writing the above import pragma you write: | |
88e1739c | 26140 | |
7cd4527e AC |
26141 | @smallexample @c ada |
26142 | @group | |
26143 | function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; | |
26144 | pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val"); | |
26145 | @end group | |
26146 | @end smallexample | |
88e1739c | 26147 | |
7cd4527e AC |
26148 | @noindent |
26149 | then the imported routine is @code{_retrieve_val@@4}. However, if instead | |
26150 | of specifying the @code{External_Name} parameter you specify the | |
26151 | @code{Link_Name} as in the following example: | |
88e1739c | 26152 | |
7cd4527e AC |
26153 | @smallexample @c ada |
26154 | @group | |
26155 | function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; | |
26156 | pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val"); | |
26157 | @end group | |
88e1739c FW |
26158 | @end smallexample |
26159 | ||
88e1739c | 26160 | @noindent |
7cd4527e AC |
26161 | then the imported routine is @code{retrieve_val@@4}, that is, there is no |
26162 | trailing underscore but the appropriate @code{@@}@code{@i{nn}} is always | |
26163 | added at the end of the @code{Link_Name} by the compiler. | |
88e1739c | 26164 | |
7cd4527e AC |
26165 | @noindent |
26166 | Note, that in some special cases a DLL's entry point name lacks a trailing | |
26167 | @code{@@}@code{@i{nn}} while the exported name generated for a call has it. | |
26168 | The @code{gnatdll} tool, which creates the import library for the DLL, is able | |
26169 | to handle those cases (see the description of the switches in | |
26170 | @pxref{Using gnatdll} section). | |
88e1739c | 26171 | |
7cd4527e AC |
26172 | @node DLL Calling Convention |
26173 | @subsection @code{DLL} Calling Convention | |
88e1739c | 26174 | |
7cd4527e AC |
26175 | @noindent |
26176 | This convention, which is GNAT-specific, must be used when you want to | |
26177 | import in Ada a variables defined in a DLL. For functions and procedures | |
26178 | this convention is equivalent to the @code{Stdcall} convention. As an | |
26179 | example, if a DLL contains a variable defined as: | |
88e1739c FW |
26180 | |
26181 | @smallexample | |
7cd4527e AC |
26182 | int my_var; |
26183 | @end smallexample | |
88e1739c | 26184 | |
7cd4527e AC |
26185 | @noindent |
26186 | then, to access this variable from Ada you should write: | |
88e1739c | 26187 | |
7cd4527e AC |
26188 | @smallexample @c ada |
26189 | @group | |
26190 | My_Var : Interfaces.C.int; | |
26191 | pragma Import (DLL, My_Var); | |
26192 | @end group | |
26193 | @end smallexample | |
88e1739c | 26194 | |
7cd4527e AC |
26195 | The remarks concerning the @code{External_Name} and @code{Link_Name} |
26196 | parameters given in the previous sections equally apply to the @code{DLL} | |
26197 | calling convention. | |
88e1739c | 26198 | |
7cd4527e AC |
26199 | @node Introduction to Dynamic Link Libraries (DLLs) |
26200 | @section Introduction to Dynamic Link Libraries (DLLs) | |
26201 | @findex DLL | |
88e1739c | 26202 | |
7cd4527e AC |
26203 | @noindent |
26204 | A Dynamically Linked Library (DLL) is a library that can be shared by | |
26205 | several applications running under Windows. A DLL can contain any number of | |
26206 | routines and variables. | |
88e1739c | 26207 | |
7cd4527e AC |
26208 | One advantage of DLLs is that you can change and enhance them without |
26209 | forcing all the applications that depend on them to be relinked or | |
26210 | recompiled. However, you should be aware than all calls to DLL routines are | |
26211 | slower since, as you will understand below, such calls are indirect. | |
88e1739c | 26212 | |
7cd4527e AC |
26213 | To illustrate the remainder of this section, suppose that an application |
26214 | wants to use the services of a DLL @file{API.dll}. To use the services | |
26215 | provided by @file{API.dll} you must statically link against an import | |
26216 | library which contains a jump table with an entry for each routine and | |
26217 | variable exported by the DLL. In the Microsoft world this import library is | |
26218 | called @file{API.lib}. When using GNAT this import library is called either | |
26219 | @file{libAPI.a} or @file{libapi.a} (names are case insensitive). | |
88e1739c | 26220 | |
7cd4527e AC |
26221 | After you have statically linked your application with the import library |
26222 | and you run your application, here is what happens: | |
88e1739c | 26223 | |
7cd4527e AC |
26224 | @enumerate |
26225 | @item | |
26226 | Your application is loaded into memory. | |
88e1739c | 26227 | |
7cd4527e AC |
26228 | @item |
26229 | The DLL @file{API.dll} is mapped into the address space of your | |
26230 | application. This means that: | |
88e1739c | 26231 | |
7cd4527e AC |
26232 | @itemize @bullet |
26233 | @item | |
26234 | The DLL will use the stack of the calling thread. | |
88e1739c | 26235 | |
7cd4527e AC |
26236 | @item |
26237 | The DLL will use the virtual address space of the calling process. | |
88e1739c | 26238 | |
7cd4527e AC |
26239 | @item |
26240 | The DLL will allocate memory from the virtual address space of the calling | |
26241 | process. | |
88e1739c | 26242 | |
7cd4527e AC |
26243 | @item |
26244 | Handles (pointers) can be safely exchanged between routines in the DLL | |
26245 | routines and routines in the application using the DLL. | |
26246 | @end itemize | |
88e1739c | 26247 | |
7cd4527e AC |
26248 | @item |
26249 | The entries in the @file{libAPI.a} or @file{API.lib} jump table which is | |
26250 | part of your application are initialized with the addresses of the routines | |
26251 | and variables in @file{API.dll}. | |
88e1739c | 26252 | |
7cd4527e AC |
26253 | @item |
26254 | If present in @file{API.dll}, routines @code{DllMain} or | |
26255 | @code{DllMainCRTStartup} are invoked. These routines typically contain | |
26256 | the initialization code needed for the well-being of the routines and | |
26257 | variables exported by the DLL. | |
26258 | @end enumerate | |
88e1739c FW |
26259 | |
26260 | @noindent | |
7cd4527e AC |
26261 | There is an additional point which is worth mentioning. In the Windows |
26262 | world there are two kind of DLLs: relocatable and non-relocatable | |
26263 | DLLs. Non-relocatable DLLs can only be loaded at a very specific address | |
26264 | in the target application address space. If the addresses of two | |
26265 | non-relocatable DLLs overlap and these happen to be used by the same | |
26266 | application, a conflict will occur and the application will run | |
26267 | incorrectly. Hence, when possible, it is always preferable to use and | |
26268 | build relocatable DLLs. Both relocatable and non-relocatable DLLs are | |
26269 | supported by GNAT. Note that the @option{-s} linker option (see GNU Linker | |
26270 | User's Guide) removes the debugging symbols from the DLL but the DLL can | |
26271 | still be relocated. | |
88e1739c | 26272 | |
7cd4527e AC |
26273 | As a side note, an interesting difference between Microsoft DLLs and |
26274 | Unix shared libraries, is the fact that on most Unix systems all public | |
26275 | routines are exported by default in a Unix shared library, while under | |
26276 | Windows the exported routines must be listed explicitly in a definition | |
26277 | file (@pxref{The Definition File}). | |
88e1739c | 26278 | |
7cd4527e AC |
26279 | @node Using DLLs with GNAT |
26280 | @section Using DLLs with GNAT | |
88e1739c | 26281 | |
7cd4527e AC |
26282 | @menu |
26283 | * Creating an Ada Spec for the DLL Services:: | |
26284 | * Creating an Import Library:: | |
26285 | @end menu | |
88e1739c | 26286 | |
7cd4527e AC |
26287 | @noindent |
26288 | To use the services of a DLL, say @file{API.dll}, in your Ada application | |
26289 | you must have: | |
88e1739c | 26290 | |
7cd4527e AC |
26291 | @enumerate |
26292 | @item | |
26293 | The Ada spec for the routines and/or variables you want to access in | |
26294 | @file{API.dll}. If not available this Ada spec must be built from the C/C++ | |
26295 | header files provided with the DLL. | |
88e1739c | 26296 | |
7cd4527e AC |
26297 | @item |
26298 | The import library (@file{libAPI.a} or @file{API.lib}). As previously | |
26299 | mentioned an import library is a statically linked library containing the | |
26300 | import table which will be filled at load time to point to the actual | |
26301 | @file{API.dll} routines. Sometimes you don't have an import library for the | |
26302 | DLL you want to use. The following sections will explain how to build one. | |
88e1739c | 26303 | |
7cd4527e AC |
26304 | @item |
26305 | The actual DLL, @file{API.dll}. | |
26306 | @end enumerate | |
88e1739c | 26307 | |
7cd4527e AC |
26308 | @noindent |
26309 | Once you have all the above, to compile an Ada application that uses the | |
26310 | services of @file{API.dll} and whose main subprogram is @code{My_Ada_App}, | |
26311 | you simply issue the command | |
88e1739c | 26312 | |
7cd4527e AC |
26313 | @smallexample |
26314 | $ gnatmake my_ada_app -largs -lAPI | |
26315 | @end smallexample | |
88e1739c | 26316 | |
7cd4527e AC |
26317 | @noindent |
26318 | The argument @option{-largs -lAPI} at the end of the @code{gnatmake} command | |
26319 | tells the GNAT linker to look first for a library named @file{API.lib} | |
26320 | (Microsoft-style name) and if not found for a library named @file{libAPI.a} | |
26321 | (GNAT-style name). Note that if the Ada package spec for @file{API.dll} | |
26322 | contains the following pragma | |
88e1739c | 26323 | |
7cd4527e AC |
26324 | @smallexample @c ada |
26325 | pragma Linker_Options ("-lAPI"); | |
26326 | @end smallexample | |
88e1739c | 26327 | |
7cd4527e AC |
26328 | @noindent |
26329 | you do not have to add @option{-largs -lAPI} at the end of the @code{gnatmake} | |
26330 | command. | |
88e1739c | 26331 | |
7cd4527e AC |
26332 | If any one of the items above is missing you will have to create it |
26333 | yourself. The following sections explain how to do so using as an | |
26334 | example a fictitious DLL called @file{API.dll}. | |
88e1739c | 26335 | |
7cd4527e AC |
26336 | @node Creating an Ada Spec for the DLL Services |
26337 | @subsection Creating an Ada Spec for the DLL Services | |
88e1739c | 26338 | |
7cd4527e AC |
26339 | @noindent |
26340 | A DLL typically comes with a C/C++ header file which provides the | |
26341 | definitions of the routines and variables exported by the DLL. The Ada | |
26342 | equivalent of this header file is a package spec that contains definitions | |
26343 | for the imported entities. If the DLL you intend to use does not come with | |
26344 | an Ada spec you have to generate one such spec yourself. For example if | |
26345 | the header file of @file{API.dll} is a file @file{api.h} containing the | |
26346 | following two definitions: | |
88e1739c | 26347 | |
7cd4527e AC |
26348 | @smallexample |
26349 | @group | |
26350 | @cartouche | |
26351 | int some_var; | |
26352 | int get (char *); | |
26353 | @end cartouche | |
26354 | @end group | |
26355 | @end smallexample | |
88e1739c | 26356 | |
7cd4527e AC |
26357 | @noindent |
26358 | then the equivalent Ada spec could be: | |
88e1739c | 26359 | |
7cd4527e AC |
26360 | @smallexample @c ada |
26361 | @group | |
26362 | @cartouche | |
26363 | with Interfaces.C.Strings; | |
26364 | package API is | |
26365 | use Interfaces; | |
88e1739c | 26366 | |
7cd4527e AC |
26367 | Some_Var : C.int; |
26368 | function Get (Str : C.Strings.Chars_Ptr) return C.int; | |
88e1739c | 26369 | |
7cd4527e AC |
26370 | private |
26371 | pragma Import (C, Get); | |
26372 | pragma Import (DLL, Some_Var); | |
26373 | end API; | |
26374 | @end cartouche | |
26375 | @end group | |
26376 | @end smallexample | |
88e1739c | 26377 | |
7cd4527e AC |
26378 | @noindent |
26379 | Note that a variable is @strong{always imported with a DLL convention}. A | |
26380 | function can have @code{C}, @code{Stdcall} or @code{DLL} convention. For | |
26381 | subprograms, the @code{DLL} convention is a synonym of @code{Stdcall} | |
26382 | (@pxref{Windows Calling Conventions}). | |
88e1739c | 26383 | |
7cd4527e AC |
26384 | @node Creating an Import Library |
26385 | @subsection Creating an Import Library | |
26386 | @cindex Import library | |
88e1739c | 26387 | |
7cd4527e AC |
26388 | @menu |
26389 | * The Definition File:: | |
26390 | * GNAT-Style Import Library:: | |
26391 | * Microsoft-Style Import Library:: | |
26392 | @end menu | |
88e1739c | 26393 | |
7cd4527e AC |
26394 | @noindent |
26395 | If a Microsoft-style import library @file{API.lib} or a GNAT-style | |
26396 | import library @file{libAPI.a} is available with @file{API.dll} you | |
26397 | can skip this section. Otherwise read on. | |
88e1739c | 26398 | |
7cd4527e AC |
26399 | @node The Definition File |
26400 | @subsubsection The Definition File | |
26401 | @cindex Definition file | |
26402 | @findex .def | |
88e1739c | 26403 | |
7cd4527e AC |
26404 | @noindent |
26405 | As previously mentioned, and unlike Unix systems, the list of symbols | |
26406 | that are exported from a DLL must be provided explicitly in Windows. | |
26407 | The main goal of a definition file is precisely that: list the symbols | |
26408 | exported by a DLL. A definition file (usually a file with a @code{.def} | |
26409 | suffix) has the following structure: | |
88e1739c | 26410 | |
7cd4527e AC |
26411 | @smallexample |
26412 | @group | |
26413 | @cartouche | |
26414 | [LIBRARY @i{name}] | |
26415 | [DESCRIPTION @i{string}] | |
26416 | EXPORTS | |
26417 | @i{symbol1} | |
26418 | @i{symbol2} | |
26419 | ... | |
26420 | @end cartouche | |
26421 | @end group | |
88e1739c FW |
26422 | @end smallexample |
26423 | ||
7cd4527e AC |
26424 | @table @code |
26425 | @item LIBRARY @i{name} | |
26426 | This section, which is optional, gives the name of the DLL. | |
88e1739c | 26427 | |
7cd4527e AC |
26428 | @item DESCRIPTION @i{string} |
26429 | This section, which is optional, gives a description string that will be | |
26430 | embedded in the import library. | |
88e1739c | 26431 | |
7cd4527e AC |
26432 | @item EXPORTS |
26433 | This section gives the list of exported symbols (procedures, functions or | |
26434 | variables). For instance in the case of @file{API.dll} the @code{EXPORTS} | |
26435 | section of @file{API.def} looks like: | |
88e1739c FW |
26436 | |
26437 | @smallexample | |
7cd4527e AC |
26438 | @group |
26439 | @cartouche | |
26440 | EXPORTS | |
26441 | some_var | |
26442 | get | |
26443 | @end cartouche | |
26444 | @end group | |
88e1739c | 26445 | @end smallexample |
7cd4527e | 26446 | @end table |
88e1739c FW |
26447 | |
26448 | @noindent | |
7cd4527e AC |
26449 | Note that you must specify the correct suffix (@code{@@}@code{@i{nn}}) |
26450 | (@pxref{Windows Calling Conventions}) for a Stdcall | |
26451 | calling convention function in the exported symbols list. | |
88e1739c | 26452 | |
7cd4527e AC |
26453 | @noindent |
26454 | There can actually be other sections in a definition file, but these | |
26455 | sections are not relevant to the discussion at hand. | |
88e1739c | 26456 | |
7cd4527e AC |
26457 | @node GNAT-Style Import Library |
26458 | @subsubsection GNAT-Style Import Library | |
88e1739c | 26459 | |
7cd4527e AC |
26460 | @noindent |
26461 | To create a static import library from @file{API.dll} with the GNAT tools | |
26462 | you should proceed as follows: | |
88e1739c | 26463 | |
7cd4527e AC |
26464 | @enumerate |
26465 | @item | |
26466 | Create the definition file @file{API.def} (@pxref{The Definition File}). | |
26467 | For that use the @code{dll2def} tool as follows: | |
88e1739c | 26468 | |
7cd4527e AC |
26469 | @smallexample |
26470 | $ dll2def API.dll > API.def | |
26471 | @end smallexample | |
88e1739c | 26472 | |
7cd4527e AC |
26473 | @noindent |
26474 | @code{dll2def} is a very simple tool: it takes as input a DLL and prints | |
26475 | to standard output the list of entry points in the DLL. Note that if | |
26476 | some routines in the DLL have the @code{Stdcall} convention | |
26477 | (@pxref{Windows Calling Conventions}) with stripped @code{@@}@i{nn} | |
26478 | suffix then you'll have to edit @file{api.def} to add it. | |
88e1739c | 26479 | |
7cd4527e AC |
26480 | @noindent |
26481 | Here are some hints to find the right @code{@@}@i{nn} suffix. | |
88e1739c | 26482 | |
7cd4527e AC |
26483 | @enumerate |
26484 | @item | |
26485 | If you have the Microsoft import library (.lib), it is possible to get | |
26486 | the right symbols by using Microsoft @code{dumpbin} tool (see the | |
26487 | corresponding Microsoft documentation for further details). | |
88e1739c | 26488 | |
7cd4527e AC |
26489 | @smallexample |
26490 | $ dumpbin /exports api.lib | |
26491 | @end smallexample | |
88e1739c | 26492 | |
7cd4527e AC |
26493 | @item |
26494 | If you have a message about a missing symbol at link time the compiler | |
26495 | tells you what symbol is expected. You just have to go back to the | |
26496 | definition file and add the right suffix. | |
26497 | @end enumerate | |
88e1739c | 26498 | |
7cd4527e AC |
26499 | @item |
26500 | Build the import library @code{libAPI.a}, using @code{gnatdll} | |
26501 | (@pxref{Using gnatdll}) as follows: | |
88e1739c | 26502 | |
7cd4527e AC |
26503 | @smallexample |
26504 | $ gnatdll -e API.def -d API.dll | |
26505 | @end smallexample | |
88e1739c | 26506 | |
7cd4527e AC |
26507 | @noindent |
26508 | @code{gnatdll} takes as input a definition file @file{API.def} and the | |
26509 | name of the DLL containing the services listed in the definition file | |
26510 | @file{API.dll}. The name of the static import library generated is | |
26511 | computed from the name of the definition file as follows: if the | |
26512 | definition file name is @i{xyz}@code{.def}, the import library name will | |
26513 | be @code{lib}@i{xyz}@code{.a}. Note that in the previous example option | |
26514 | @option{-e} could have been removed because the name of the definition | |
26515 | file (before the ``@code{.def}'' suffix) is the same as the name of the | |
26516 | DLL (@pxref{Using gnatdll} for more information about @code{gnatdll}). | |
26517 | @end enumerate | |
88e1739c | 26518 | |
7cd4527e AC |
26519 | @node Microsoft-Style Import Library |
26520 | @subsubsection Microsoft-Style Import Library | |
88e1739c | 26521 | |
7cd4527e AC |
26522 | @noindent |
26523 | With GNAT you can either use a GNAT-style or Microsoft-style import | |
26524 | library. A Microsoft import library is needed only if you plan to make an | |
26525 | Ada DLL available to applications developed with Microsoft | |
26526 | tools (@pxref{Mixed-Language Programming on Windows}). | |
88e1739c | 26527 | |
7cd4527e AC |
26528 | To create a Microsoft-style import library for @file{API.dll} you |
26529 | should proceed as follows: | |
88e1739c | 26530 | |
7cd4527e AC |
26531 | @enumerate |
26532 | @item | |
26533 | Create the definition file @file{API.def} from the DLL. For this use either | |
26534 | the @code{dll2def} tool as described above or the Microsoft @code{dumpbin} | |
26535 | tool (see the corresponding Microsoft documentation for further details). | |
88e1739c | 26536 | |
7cd4527e AC |
26537 | @item |
26538 | Build the actual import library using Microsoft's @code{lib} utility: | |
88e1739c FW |
26539 | |
26540 | @smallexample | |
7cd4527e | 26541 | $ lib -machine:IX86 -def:API.def -out:API.lib |
88e1739c FW |
26542 | @end smallexample |
26543 | ||
26544 | @noindent | |
7cd4527e AC |
26545 | If you use the above command the definition file @file{API.def} must |
26546 | contain a line giving the name of the DLL: | |
88e1739c FW |
26547 | |
26548 | @smallexample | |
7cd4527e | 26549 | LIBRARY "API" |
88e1739c FW |
26550 | @end smallexample |
26551 | ||
26552 | @noindent | |
7cd4527e AC |
26553 | See the Microsoft documentation for further details about the usage of |
26554 | @code{lib}. | |
26555 | @end enumerate | |
88e1739c | 26556 | |
7cd4527e AC |
26557 | @node Building DLLs with GNAT |
26558 | @section Building DLLs with GNAT | |
26559 | @cindex DLLs, building | |
88e1739c | 26560 | |
7cd4527e AC |
26561 | @menu |
26562 | * Limitations When Using Ada DLLs from Ada:: | |
26563 | * Exporting Ada Entities:: | |
26564 | * Ada DLLs and Elaboration:: | |
26565 | * Ada DLLs and Finalization:: | |
26566 | * Creating a Spec for Ada DLLs:: | |
26567 | * Creating the Definition File:: | |
26568 | * Using gnatdll:: | |
26569 | @end menu | |
88e1739c FW |
26570 | |
26571 | @noindent | |
7cd4527e AC |
26572 | This section explains how to build DLLs containing Ada code. These DLLs |
26573 | will be referred to as Ada DLLs in the remainder of this section. | |
88e1739c | 26574 | |
7cd4527e AC |
26575 | The steps required to build an Ada DLL that is to be used by Ada as well as |
26576 | non-Ada applications are as follows: | |
88e1739c | 26577 | |
7cd4527e AC |
26578 | @enumerate |
26579 | @item | |
26580 | You need to mark each Ada @i{entity} exported by the DLL with a @code{C} or | |
26581 | @code{Stdcall} calling convention to avoid any Ada name mangling for the | |
26582 | entities exported by the DLL (@pxref{Exporting Ada Entities}). You can | |
26583 | skip this step if you plan to use the Ada DLL only from Ada applications. | |
88e1739c | 26584 | |
7cd4527e AC |
26585 | @item |
26586 | Your Ada code must export an initialization routine which calls the routine | |
26587 | @code{adainit} generated by @code{gnatbind} to perform the elaboration of | |
26588 | the Ada code in the DLL (@pxref{Ada DLLs and Elaboration}). The initialization | |
26589 | routine exported by the Ada DLL must be invoked by the clients of the DLL | |
26590 | to initialize the DLL. | |
88e1739c | 26591 | |
7cd4527e AC |
26592 | @item |
26593 | When useful, the DLL should also export a finalization routine which calls | |
26594 | routine @code{adafinal} generated by @code{gnatbind} to perform the | |
26595 | finalization of the Ada code in the DLL (@pxref{Ada DLLs and Finalization}). | |
26596 | The finalization routine exported by the Ada DLL must be invoked by the | |
26597 | clients of the DLL when the DLL services are no further needed. | |
26598 | ||
26599 | @item | |
26600 | You must provide a spec for the services exported by the Ada DLL in each | |
26601 | of the programming languages to which you plan to make the DLL available. | |
88e1739c | 26602 | |
7cd4527e AC |
26603 | @item |
26604 | You must provide a definition file listing the exported entities | |
26605 | (@pxref{The Definition File}). | |
88e1739c | 26606 | |
7cd4527e AC |
26607 | @item |
26608 | Finally you must use @code{gnatdll} to produce the DLL and the import | |
26609 | library (@pxref{Using gnatdll}). | |
26610 | @end enumerate | |
88e1739c FW |
26611 | |
26612 | @noindent | |
7cd4527e AC |
26613 | Note that a relocatable DLL stripped using the @code{strip} binutils |
26614 | tool will not be relocatable anymore. To build a DLL without debug | |
26615 | information pass @code{-largs -s} to @code{gnatdll}. | |
88e1739c | 26616 | |
7cd4527e AC |
26617 | @node Limitations When Using Ada DLLs from Ada |
26618 | @subsection Limitations When Using Ada DLLs from Ada | |
88e1739c FW |
26619 | |
26620 | @noindent | |
7cd4527e AC |
26621 | When using Ada DLLs from Ada applications there is a limitation users |
26622 | should be aware of. Because on Windows the GNAT run time is not in a DLL of | |
26623 | its own, each Ada DLL includes a part of the GNAT run time. Specifically, | |
26624 | each Ada DLL includes the services of the GNAT run time that are necessary | |
26625 | to the Ada code inside the DLL. As a result, when an Ada program uses an | |
26626 | Ada DLL there are two independent GNAT run times: one in the Ada DLL and | |
26627 | one in the main program. | |
88e1739c | 26628 | |
7cd4527e AC |
26629 | It is therefore not possible to exchange GNAT run-time objects between the |
26630 | Ada DLL and the main Ada program. Example of GNAT run-time objects are file | |
26631 | handles (e.g. @code{Text_IO.File_Type}), tasks types, protected objects | |
26632 | types, etc. | |
88e1739c | 26633 | |
7cd4527e AC |
26634 | It is completely safe to exchange plain elementary, array or record types, |
26635 | Windows object handles, etc. | |
88e1739c | 26636 | |
7cd4527e AC |
26637 | @node Exporting Ada Entities |
26638 | @subsection Exporting Ada Entities | |
26639 | @cindex Export table | |
88e1739c | 26640 | |
88e1739c | 26641 | @noindent |
7cd4527e AC |
26642 | Building a DLL is a way to encapsulate a set of services usable from any |
26643 | application. As a result, the Ada entities exported by a DLL should be | |
26644 | exported with the @code{C} or @code{Stdcall} calling conventions to avoid | |
26645 | any Ada name mangling. Please note that the @code{Stdcall} convention | |
26646 | should only be used for subprograms, not for variables. As an example here | |
26647 | is an Ada package @code{API}, spec and body, exporting two procedures, a | |
26648 | function, and a variable: | |
88e1739c | 26649 | |
7cd4527e AC |
26650 | @smallexample @c ada |
26651 | @group | |
26652 | @cartouche | |
26653 | with Interfaces.C; use Interfaces; | |
26654 | package API is | |
26655 | Count : C.int := 0; | |
26656 | function Factorial (Val : C.int) return C.int; | |
88e1739c | 26657 | |
7cd4527e AC |
26658 | procedure Initialize_API; |
26659 | procedure Finalize_API; | |
26660 | -- Initialization & Finalization routines. More in the next section. | |
26661 | private | |
26662 | pragma Export (C, Initialize_API); | |
26663 | pragma Export (C, Finalize_API); | |
26664 | pragma Export (C, Count); | |
26665 | pragma Export (C, Factorial); | |
26666 | end API; | |
26667 | @end cartouche | |
26668 | @end group | |
88e1739c FW |
26669 | @end smallexample |
26670 | ||
7cd4527e AC |
26671 | @smallexample @c ada |
26672 | @group | |
26673 | @cartouche | |
26674 | package body API is | |
26675 | function Factorial (Val : C.int) return C.int is | |
26676 | Fact : C.int := 1; | |
26677 | begin | |
26678 | Count := Count + 1; | |
26679 | for K in 1 .. Val loop | |
26680 | Fact := Fact * K; | |
26681 | end loop; | |
26682 | return Fact; | |
26683 | end Factorial; | |
88e1739c | 26684 | |
7cd4527e AC |
26685 | procedure Initialize_API is |
26686 | procedure Adainit; | |
26687 | pragma Import (C, Adainit); | |
26688 | begin | |
26689 | Adainit; | |
26690 | end Initialize_API; | |
88e1739c | 26691 | |
7cd4527e AC |
26692 | procedure Finalize_API is |
26693 | procedure Adafinal; | |
26694 | pragma Import (C, Adafinal); | |
26695 | begin | |
26696 | Adafinal; | |
26697 | end Finalize_API; | |
26698 | end API; | |
26699 | @end cartouche | |
26700 | @end group | |
88e1739c FW |
26701 | @end smallexample |
26702 | ||
7cd4527e AC |
26703 | @noindent |
26704 | If the Ada DLL you are building will only be used by Ada applications | |
26705 | you do not have to export Ada entities with a @code{C} or @code{Stdcall} | |
26706 | convention. As an example, the previous package could be written as | |
26707 | follows: | |
26708 | ||
26709 | @smallexample @c ada | |
26710 | @group | |
26711 | @cartouche | |
26712 | package API is | |
26713 | Count : Integer := 0; | |
26714 | function Factorial (Val : Integer) return Integer; | |
26715 | ||
26716 | procedure Initialize_API; | |
26717 | procedure Finalize_API; | |
26718 | -- Initialization and Finalization routines. | |
26719 | end API; | |
26720 | @end cartouche | |
26721 | @end group | |
88e1739c | 26722 | @end smallexample |
88e1739c | 26723 | |
7cd4527e AC |
26724 | @smallexample @c ada |
26725 | @group | |
26726 | @cartouche | |
26727 | package body API is | |
26728 | function Factorial (Val : Integer) return Integer is | |
26729 | Fact : Integer := 1; | |
26730 | begin | |
26731 | Count := Count + 1; | |
26732 | for K in 1 .. Val loop | |
26733 | Fact := Fact * K; | |
26734 | end loop; | |
26735 | return Fact; | |
26736 | end Factorial; | |
88e1739c | 26737 | |
7cd4527e AC |
26738 | ... |
26739 | -- The remainder of this package body is unchanged. | |
26740 | end API; | |
26741 | @end cartouche | |
26742 | @end group | |
88e1739c FW |
26743 | @end smallexample |
26744 | ||
26745 | @noindent | |
7cd4527e AC |
26746 | Note that if you do not export the Ada entities with a @code{C} or |
26747 | @code{Stdcall} convention you will have to provide the mangled Ada names | |
26748 | in the definition file of the Ada DLL | |
26749 | (@pxref{Creating the Definition File}). | |
88e1739c | 26750 | |
7cd4527e AC |
26751 | @node Ada DLLs and Elaboration |
26752 | @subsection Ada DLLs and Elaboration | |
26753 | @cindex DLLs and elaboration | |
88e1739c FW |
26754 | |
26755 | @noindent | |
7cd4527e AC |
26756 | The DLL that you are building contains your Ada code as well as all the |
26757 | routines in the Ada library that are needed by it. The first thing a | |
26758 | user of your DLL must do is elaborate the Ada code | |
26759 | (@pxref{Elaboration Order Handling in GNAT}). | |
26760 | ||
26761 | To achieve this you must export an initialization routine | |
26762 | (@code{Initialize_API} in the previous example), which must be invoked | |
26763 | before using any of the DLL services. This elaboration routine must call | |
26764 | the Ada elaboration routine @code{adainit} generated by the GNAT binder | |
26765 | (@pxref{Binding with Non-Ada Main Programs}). See the body of | |
26766 | @code{Initialize_Api} for an example. Note that the GNAT binder is | |
26767 | automatically invoked during the DLL build process by the @code{gnatdll} | |
26768 | tool (@pxref{Using gnatdll}). | |
26769 | ||
26770 | When a DLL is loaded, Windows systematically invokes a routine called | |
26771 | @code{DllMain}. It would therefore be possible to call @code{adainit} | |
26772 | directly from @code{DllMain} without having to provide an explicit | |
26773 | initialization routine. Unfortunately, it is not possible to call | |
26774 | @code{adainit} from the @code{DllMain} if your program has library level | |
26775 | tasks because access to the @code{DllMain} entry point is serialized by | |
26776 | the system (that is, only a single thread can execute ``through'' it at a | |
26777 | time), which means that the GNAT run time will deadlock waiting for the | |
26778 | newly created task to complete its initialization. | |
26779 | ||
26780 | @node Ada DLLs and Finalization | |
26781 | @subsection Ada DLLs and Finalization | |
26782 | @cindex DLLs and finalization | |
88e1739c FW |
26783 | |
26784 | @noindent | |
7cd4527e AC |
26785 | When the services of an Ada DLL are no longer needed, the client code should |
26786 | invoke the DLL finalization routine, if available. The DLL finalization | |
26787 | routine is in charge of releasing all resources acquired by the DLL. In the | |
26788 | case of the Ada code contained in the DLL, this is achieved by calling | |
26789 | routine @code{adafinal} generated by the GNAT binder | |
26790 | (@pxref{Binding with Non-Ada Main Programs}). | |
26791 | See the body of @code{Finalize_Api} for an | |
26792 | example. As already pointed out the GNAT binder is automatically invoked | |
26793 | during the DLL build process by the @code{gnatdll} tool | |
26794 | (@pxref{Using gnatdll}). | |
26795 | ||
26796 | @node Creating a Spec for Ada DLLs | |
26797 | @subsection Creating a Spec for Ada DLLs | |
88e1739c FW |
26798 | |
26799 | @noindent | |
7cd4527e AC |
26800 | To use the services exported by the Ada DLL from another programming |
26801 | language (e.g. C), you have to translate the specs of the exported Ada | |
26802 | entities in that language. For instance in the case of @code{API.dll}, | |
26803 | the corresponding C header file could look like: | |
88e1739c | 26804 | |
88e1739c | 26805 | @smallexample |
7cd4527e AC |
26806 | @group |
26807 | @cartouche | |
26808 | extern int *_imp__count; | |
26809 | #define count (*_imp__count) | |
26810 | int factorial (int); | |
26811 | @end cartouche | |
26812 | @end group | |
88e1739c | 26813 | @end smallexample |
88e1739c FW |
26814 | |
26815 | @noindent | |
7cd4527e AC |
26816 | It is important to understand that when building an Ada DLL to be used by |
26817 | other Ada applications, you need two different specs for the packages | |
26818 | contained in the DLL: one for building the DLL and the other for using | |
26819 | the DLL. This is because the @code{DLL} calling convention is needed to | |
26820 | use a variable defined in a DLL, but when building the DLL, the variable | |
26821 | must have either the @code{Ada} or @code{C} calling convention. As an | |
26822 | example consider a DLL comprising the following package @code{API}: | |
88e1739c | 26823 | |
7cd4527e AC |
26824 | @smallexample @c ada |
26825 | @group | |
26826 | @cartouche | |
26827 | package API is | |
26828 | Count : Integer := 0; | |
26829 | ... | |
26830 | -- Remainder of the package omitted. | |
26831 | end API; | |
26832 | @end cartouche | |
26833 | @end group | |
26834 | @end smallexample | |
88e1739c FW |
26835 | |
26836 | @noindent | |
7cd4527e AC |
26837 | After producing a DLL containing package @code{API}, the spec that |
26838 | must be used to import @code{API.Count} from Ada code outside of the | |
26839 | DLL is: | |
88e1739c | 26840 | |
7cd4527e AC |
26841 | @smallexample @c ada |
26842 | @group | |
26843 | @cartouche | |
26844 | package API is | |
26845 | Count : Integer; | |
26846 | pragma Import (DLL, Count); | |
26847 | end API; | |
26848 | @end cartouche | |
26849 | @end group | |
88e1739c | 26850 | @end smallexample |
88e1739c | 26851 | |
7cd4527e AC |
26852 | @node Creating the Definition File |
26853 | @subsection Creating the Definition File | |
88e1739c FW |
26854 | |
26855 | @noindent | |
7cd4527e AC |
26856 | The definition file is the last file needed to build the DLL. It lists |
26857 | the exported symbols. As an example, the definition file for a DLL | |
26858 | containing only package @code{API} (where all the entities are exported | |
26859 | with a @code{C} calling convention) is: | |
88e1739c | 26860 | |
88e1739c | 26861 | @smallexample |
7cd4527e AC |
26862 | @group |
26863 | @cartouche | |
26864 | EXPORTS | |
26865 | count | |
26866 | factorial | |
26867 | finalize_api | |
26868 | initialize_api | |
26869 | @end cartouche | |
26870 | @end group | |
88e1739c FW |
26871 | @end smallexample |
26872 | ||
88e1739c | 26873 | @noindent |
7cd4527e AC |
26874 | If the @code{C} calling convention is missing from package @code{API}, |
26875 | then the definition file contains the mangled Ada names of the above | |
26876 | entities, which in this case are: | |
88e1739c | 26877 | |
88e1739c | 26878 | @smallexample |
7cd4527e AC |
26879 | @group |
26880 | @cartouche | |
26881 | EXPORTS | |
26882 | api__count | |
26883 | api__factorial | |
26884 | api__finalize_api | |
26885 | api__initialize_api | |
26886 | @end cartouche | |
26887 | @end group | |
88e1739c FW |
26888 | @end smallexample |
26889 | ||
7cd4527e AC |
26890 | @node Using gnatdll |
26891 | @subsection Using @code{gnatdll} | |
26892 | @findex gnatdll | |
88e1739c FW |
26893 | |
26894 | @menu | |
7cd4527e AC |
26895 | * gnatdll Example:: |
26896 | * gnatdll behind the Scenes:: | |
26897 | * Using dlltool:: | |
88e1739c FW |
26898 | @end menu |
26899 | ||
26900 | @noindent | |
7cd4527e AC |
26901 | @code{gnatdll} is a tool to automate the DLL build process once all the Ada |
26902 | and non-Ada sources that make up your DLL have been compiled. | |
26903 | @code{gnatdll} is actually in charge of two distinct tasks: build the | |
26904 | static import library for the DLL and the actual DLL. The form of the | |
26905 | @code{gnatdll} command is | |
88e1739c | 26906 | |
7cd4527e AC |
26907 | @smallexample |
26908 | @cartouche | |
26909 | $ gnatdll [@var{switches}] @var{list-of-files} [-largs @var{opts}] | |
26910 | @end cartouche | |
26911 | @end smallexample | |
88e1739c FW |
26912 | |
26913 | @noindent | |
7cd4527e AC |
26914 | where @i{list-of-files} is a list of ALI and object files. The object |
26915 | file list must be the exact list of objects corresponding to the non-Ada | |
26916 | sources whose services are to be included in the DLL. The ALI file list | |
26917 | must be the exact list of ALI files for the corresponding Ada sources | |
26918 | whose services are to be included in the DLL. If @i{list-of-files} is | |
26919 | missing, only the static import library is generated. | |
88e1739c | 26920 | |
7cd4527e AC |
26921 | @noindent |
26922 | You may specify any of the following switches to @code{gnatdll}: | |
88e1739c | 26923 | |
7cd4527e AC |
26924 | @table @code |
26925 | @item -a[@var{address}] | |
26926 | @cindex @option{-a} (@code{gnatdll}) | |
26927 | Build a non-relocatable DLL at @var{address}. If @var{address} is not | |
26928 | specified the default address @var{0x11000000} will be used. By default, | |
26929 | when this switch is missing, @code{gnatdll} builds relocatable DLL. We | |
26930 | advise the reader to build relocatable DLL. | |
88e1739c | 26931 | |
7cd4527e AC |
26932 | @item -b @var{address} |
26933 | @cindex @option{-b} (@code{gnatdll}) | |
26934 | Set the relocatable DLL base address. By default the address is | |
26935 | @var{0x11000000}. | |
88e1739c | 26936 | |
7cd4527e AC |
26937 | @item -bargs @var{opts} |
26938 | @cindex @option{-bargs} (@code{gnatdll}) | |
26939 | Binder options. Pass @var{opts} to the binder. | |
88e1739c | 26940 | |
7cd4527e AC |
26941 | @item -d @var{dllfile} |
26942 | @cindex @option{-d} (@code{gnatdll}) | |
26943 | @var{dllfile} is the name of the DLL. This switch must be present for | |
26944 | @code{gnatdll} to do anything. The name of the generated import library is | |
26945 | obtained algorithmically from @var{dllfile} as shown in the following | |
26946 | example: if @var{dllfile} is @code{xyz.dll}, the import library name is | |
26947 | @code{libxyz.a}. The name of the definition file to use (if not specified | |
26948 | by option @option{-e}) is obtained algorithmically from @var{dllfile} | |
26949 | as shown in the following example: | |
26950 | if @var{dllfile} is @code{xyz.dll}, the definition | |
26951 | file used is @code{xyz.def}. | |
88e1739c | 26952 | |
7cd4527e AC |
26953 | @item -e @var{deffile} |
26954 | @cindex @option{-e} (@code{gnatdll}) | |
26955 | @var{deffile} is the name of the definition file. | |
88e1739c | 26956 | |
7cd4527e AC |
26957 | @item -g |
26958 | @cindex @option{-g} (@code{gnatdll}) | |
26959 | Generate debugging information. This information is stored in the object | |
26960 | file and copied from there to the final DLL file by the linker, | |
26961 | where it can be read by the debugger. You must use the | |
26962 | @option{-g} switch if you plan on using the debugger or the symbolic | |
26963 | stack traceback. | |
88e1739c | 26964 | |
7cd4527e AC |
26965 | @item -h |
26966 | @cindex @option{-h} (@code{gnatdll}) | |
26967 | Help mode. Displays @code{gnatdll} switch usage information. | |
88e1739c | 26968 | |
7cd4527e AC |
26969 | @item -Idir |
26970 | @cindex @option{-I} (@code{gnatdll}) | |
26971 | Direct @code{gnatdll} to search the @var{dir} directory for source and | |
26972 | object files needed to build the DLL. | |
26973 | (@pxref{Search Paths and the Run-Time Library (RTL)}). | |
88e1739c | 26974 | |
7cd4527e AC |
26975 | @item -k |
26976 | @cindex @option{-k} (@code{gnatdll}) | |
26977 | Removes the @code{@@}@i{nn} suffix from the import library's exported | |
26978 | names. You must specified this option if you want to use a | |
26979 | @code{Stdcall} function in a DLL for which the @code{@@}@i{nn} suffix | |
26980 | has been removed. This is the case for most of the Windows NT DLL for | |
26981 | example. This option has no effect when @option{-n} option is specified. | |
88e1739c | 26982 | |
7cd4527e AC |
26983 | @item -l @var{file} |
26984 | @cindex @option{-l} (@code{gnatdll}) | |
26985 | The list of ALI and object files used to build the DLL are listed in | |
26986 | @var{file}, instead of being given in the command line. Each line in | |
26987 | @var{file} contains the name of an ALI or object file. | |
88e1739c | 26988 | |
7cd4527e AC |
26989 | @item -n |
26990 | @cindex @option{-n} (@code{gnatdll}) | |
26991 | No Import. Do not create the import library. | |
88e1739c | 26992 | |
7cd4527e AC |
26993 | @item -q |
26994 | @cindex @option{-q} (@code{gnatdll}) | |
26995 | Quiet mode. Do not display unnecessary messages. | |
88e1739c | 26996 | |
7cd4527e AC |
26997 | @item -v |
26998 | @cindex @option{-v} (@code{gnatdll}) | |
26999 | Verbose mode. Display extra information. | |
88e1739c | 27000 | |
7cd4527e AC |
27001 | @item -largs @var{opts} |
27002 | @cindex @option{-largs} (@code{gnatdll}) | |
27003 | Linker options. Pass @var{opts} to the linker. | |
27004 | @end table | |
88e1739c | 27005 | |
7cd4527e AC |
27006 | @node gnatdll Example |
27007 | @subsubsection @code{gnatdll} Example | |
88e1739c FW |
27008 | |
27009 | @noindent | |
7cd4527e AC |
27010 | As an example the command to build a relocatable DLL from @file{api.adb} |
27011 | once @file{api.adb} has been compiled and @file{api.def} created is | |
88e1739c | 27012 | |
88e1739c | 27013 | @smallexample |
7cd4527e | 27014 | $ gnatdll -d api.dll api.ali |
88e1739c FW |
27015 | @end smallexample |
27016 | ||
27017 | @noindent | |
7cd4527e AC |
27018 | The above command creates two files: @file{libapi.a} (the import |
27019 | library) and @file{api.dll} (the actual DLL). If you want to create | |
27020 | only the DLL, just type: | |
88e1739c | 27021 | |
88e1739c | 27022 | @smallexample |
7cd4527e | 27023 | $ gnatdll -d api.dll -n api.ali |
88e1739c FW |
27024 | @end smallexample |
27025 | ||
27026 | @noindent | |
7cd4527e | 27027 | Alternatively if you want to create just the import library, type: |
88e1739c | 27028 | |
88e1739c | 27029 | @smallexample |
7cd4527e | 27030 | $ gnatdll -d api.dll |
88e1739c FW |
27031 | @end smallexample |
27032 | ||
7cd4527e AC |
27033 | @node gnatdll behind the Scenes |
27034 | @subsubsection @code{gnatdll} behind the Scenes | |
88e1739c | 27035 | |
7cd4527e AC |
27036 | @noindent |
27037 | This section details the steps involved in creating a DLL. @code{gnatdll} | |
27038 | does these steps for you. Unless you are interested in understanding what | |
27039 | goes on behind the scenes, you should skip this section. | |
88e1739c | 27040 | |
7cd4527e AC |
27041 | We use the previous example of a DLL containing the Ada package @code{API}, |
27042 | to illustrate the steps necessary to build a DLL. The starting point is a | |
27043 | set of objects that will make up the DLL and the corresponding ALI | |
27044 | files. In the case of this example this means that @file{api.o} and | |
27045 | @file{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does | |
27046 | the following: | |
88e1739c | 27047 | |
7cd4527e | 27048 | @enumerate |
88e1739c | 27049 | @item |
7cd4527e AC |
27050 | @code{gnatdll} builds the base file (@file{api.base}). A base file gives |
27051 | the information necessary to generate relocation information for the | |
27052 | DLL. | |
88e1739c | 27053 | |
7cd4527e AC |
27054 | @smallexample |
27055 | @group | |
27056 | $ gnatbind -n api | |
27057 | $ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base | |
27058 | @end group | |
27059 | @end smallexample | |
88e1739c FW |
27060 | |
27061 | @noindent | |
7cd4527e AC |
27062 | In addition to the base file, the @code{gnatlink} command generates an |
27063 | output file @file{api.jnk} which can be discarded. The @option{-mdll} switch | |
27064 | asks @code{gnatlink} to generate the routines @code{DllMain} and | |
27065 | @code{DllMainCRTStartup} that are called by the Windows loader when the DLL | |
27066 | is loaded into memory. | |
88e1739c FW |
27067 | |
27068 | @item | |
7cd4527e AC |
27069 | @code{gnatdll} uses @code{dlltool} (@pxref{Using dlltool}) to build the |
27070 | export table (@file{api.exp}). The export table contains the relocation | |
27071 | information in a form which can be used during the final link to ensure | |
27072 | that the Windows loader is able to place the DLL anywhere in memory. | |
88e1739c | 27073 | |
88e1739c | 27074 | @smallexample |
7cd4527e AC |
27075 | @group |
27076 | $ dlltool --dllname api.dll --def api.def --base-file api.base \ | |
27077 | --output-exp api.exp | |
27078 | @end group | |
88e1739c FW |
27079 | @end smallexample |
27080 | ||
27081 | @item | |
7cd4527e AC |
27082 | @code{gnatdll} builds the base file using the new export table. Note that |
27083 | @code{gnatbind} must be called once again since the binder generated file | |
27084 | has been deleted during the previous call to @code{gnatlink}. | |
88e1739c | 27085 | |
7cd4527e AC |
27086 | @smallexample |
27087 | @group | |
27088 | $ gnatbind -n api | |
27089 | $ gnatlink api -o api.jnk api.exp -mdll | |
27090 | -Wl,--base-file,api.base | |
27091 | @end group | |
27092 | @end smallexample | |
88e1739c FW |
27093 | |
27094 | @item | |
7cd4527e AC |
27095 | @code{gnatdll} builds the new export table using the new base file and |
27096 | generates the DLL import library @file{libAPI.a}. | |
88e1739c | 27097 | |
88e1739c | 27098 | @smallexample |
7cd4527e AC |
27099 | @group |
27100 | $ dlltool --dllname api.dll --def api.def --base-file api.base \ | |
27101 | --output-exp api.exp --output-lib libAPI.a | |
27102 | @end group | |
88e1739c | 27103 | @end smallexample |
88e1739c | 27104 | |
7cd4527e AC |
27105 | @item |
27106 | Finally @code{gnatdll} builds the relocatable DLL using the final export | |
27107 | table. | |
88e1739c FW |
27108 | |
27109 | @smallexample | |
7cd4527e AC |
27110 | @group |
27111 | $ gnatbind -n api | |
27112 | $ gnatlink api api.exp -o api.dll -mdll | |
27113 | @end group | |
88e1739c | 27114 | @end smallexample |
7cd4527e | 27115 | @end enumerate |
88e1739c | 27116 | |
7cd4527e AC |
27117 | @node Using dlltool |
27118 | @subsubsection Using @code{dlltool} | |
88e1739c FW |
27119 | |
27120 | @noindent | |
7cd4527e AC |
27121 | @code{dlltool} is the low-level tool used by @code{gnatdll} to build |
27122 | DLLs and static import libraries. This section summarizes the most | |
27123 | common @code{dlltool} switches. The form of the @code{dlltool} command | |
27124 | is | |
88e1739c | 27125 | |
7cd4527e AC |
27126 | @smallexample |
27127 | $ dlltool [@var{switches}] | |
27128 | @end smallexample | |
88e1739c FW |
27129 | |
27130 | @noindent | |
7cd4527e | 27131 | @code{dlltool} switches include: |
88e1739c | 27132 | |
7cd4527e AC |
27133 | @table @option |
27134 | @item --base-file @var{basefile} | |
27135 | @cindex @option{--base-file} (@command{dlltool}) | |
27136 | Read the base file @var{basefile} generated by the linker. This switch | |
27137 | is used to create a relocatable DLL. | |
88e1739c | 27138 | |
7cd4527e AC |
27139 | @item --def @var{deffile} |
27140 | @cindex @option{--def} (@command{dlltool}) | |
27141 | Read the definition file. | |
88e1739c | 27142 | |
7cd4527e AC |
27143 | @item --dllname @var{name} |
27144 | @cindex @option{--dllname} (@command{dlltool}) | |
27145 | Gives the name of the DLL. This switch is used to embed the name of the | |
27146 | DLL in the static import library generated by @code{dlltool} with switch | |
27147 | @option{--output-lib}. | |
88e1739c | 27148 | |
7cd4527e AC |
27149 | @item -k |
27150 | @cindex @option{-k} (@command{dlltool}) | |
27151 | Kill @code{@@}@i{nn} from exported names | |
27152 | (@pxref{Windows Calling Conventions} | |
27153 | for a discussion about @code{Stdcall}-style symbols. | |
88e1739c | 27154 | |
7cd4527e AC |
27155 | @item --help |
27156 | @cindex @option{--help} (@command{dlltool}) | |
27157 | Prints the @code{dlltool} switches with a concise description. | |
88e1739c | 27158 | |
7cd4527e AC |
27159 | @item --output-exp @var{exportfile} |
27160 | @cindex @option{--output-exp} (@command{dlltool}) | |
27161 | Generate an export file @var{exportfile}. The export file contains the | |
27162 | export table (list of symbols in the DLL) and is used to create the DLL. | |
88e1739c | 27163 | |
7cd4527e AC |
27164 | @item --output-lib @i{libfile} |
27165 | @cindex @option{--output-lib} (@command{dlltool}) | |
27166 | Generate a static import library @var{libfile}. | |
88e1739c | 27167 | |
7cd4527e AC |
27168 | @item -v |
27169 | @cindex @option{-v} (@command{dlltool}) | |
27170 | Verbose mode. | |
88e1739c | 27171 | |
7cd4527e AC |
27172 | @item --as @i{assembler-name} |
27173 | @cindex @option{--as} (@command{dlltool}) | |
27174 | Use @i{assembler-name} as the assembler. The default is @code{as}. | |
27175 | @end table | |
88e1739c | 27176 | |
7cd4527e AC |
27177 | @node GNAT and Windows Resources |
27178 | @section GNAT and Windows Resources | |
27179 | @cindex Resources, windows | |
88e1739c | 27180 | |
7cd4527e AC |
27181 | @menu |
27182 | * Building Resources:: | |
27183 | * Compiling Resources:: | |
27184 | * Using Resources:: | |
27185 | @end menu | |
88e1739c FW |
27186 | |
27187 | @noindent | |
7cd4527e AC |
27188 | Resources are an easy way to add Windows specific objects to your |
27189 | application. The objects that can be added as resources include: | |
88e1739c | 27190 | |
7cd4527e AC |
27191 | @itemize @bullet |
27192 | @item | |
27193 | menus | |
88e1739c | 27194 | |
7cd4527e AC |
27195 | @item |
27196 | accelerators | |
88e1739c | 27197 | |
7cd4527e AC |
27198 | @item |
27199 | dialog boxes | |
88e1739c | 27200 | |
7cd4527e AC |
27201 | @item |
27202 | string tables | |
88e1739c | 27203 | |
7cd4527e AC |
27204 | @item |
27205 | bitmaps | |
88e1739c | 27206 | |
7cd4527e AC |
27207 | @item |
27208 | cursors | |
88e1739c | 27209 | |
7cd4527e AC |
27210 | @item |
27211 | icons | |
88e1739c | 27212 | |
7cd4527e AC |
27213 | @item |
27214 | fonts | |
27215 | @end itemize | |
88e1739c FW |
27216 | |
27217 | @noindent | |
7cd4527e | 27218 | This section explains how to build, compile and use resources. |
88e1739c | 27219 | |
7cd4527e AC |
27220 | @node Building Resources |
27221 | @subsection Building Resources | |
27222 | @cindex Resources, building | |
88e1739c FW |
27223 | |
27224 | @noindent | |
7cd4527e AC |
27225 | A resource file is an ASCII file. By convention resource files have an |
27226 | @file{.rc} extension. | |
27227 | The easiest way to build a resource file is to use Microsoft tools | |
27228 | such as @code{imagedit.exe} to build bitmaps, icons and cursors and | |
27229 | @code{dlgedit.exe} to build dialogs. | |
27230 | It is always possible to build an @file{.rc} file yourself by writing a | |
27231 | resource script. | |
88e1739c | 27232 | |
7cd4527e AC |
27233 | It is not our objective to explain how to write a resource file. A |
27234 | complete description of the resource script language can be found in the | |
27235 | Microsoft documentation. | |
88e1739c | 27236 | |
7cd4527e AC |
27237 | @node Compiling Resources |
27238 | @subsection Compiling Resources | |
27239 | @findex rc | |
27240 | @findex windres | |
27241 | @cindex Resources, compiling | |
88e1739c FW |
27242 | |
27243 | @noindent | |
7cd4527e AC |
27244 | This section describes how to build a GNAT-compatible (COFF) object file |
27245 | containing the resources. This is done using the Resource Compiler | |
27246 | @code{windres} as follows: | |
88e1739c FW |
27247 | |
27248 | @smallexample | |
7cd4527e | 27249 | $ windres -i myres.rc -o myres.o |
88e1739c FW |
27250 | @end smallexample |
27251 | ||
27252 | @noindent | |
7cd4527e AC |
27253 | By default @code{windres} will run @code{gcc} to preprocess the @file{.rc} |
27254 | file. You can specify an alternate preprocessor (usually named | |
27255 | @file{cpp.exe}) using the @code{windres} @option{--preprocessor} | |
27256 | parameter. A list of all possible options may be obtained by entering | |
27257 | the command @code{windres} @option{--help}. | |
27258 | ||
27259 | It is also possible to use the Microsoft resource compiler @code{rc.exe} | |
27260 | to produce a @file{.res} file (binary resource file). See the | |
27261 | corresponding Microsoft documentation for further details. In this case | |
27262 | you need to use @code{windres} to translate the @file{.res} file to a | |
27263 | GNAT-compatible object file as follows: | |
88e1739c FW |
27264 | |
27265 | @smallexample | |
7cd4527e | 27266 | $ windres -i myres.res -o myres.o |
88e1739c FW |
27267 | @end smallexample |
27268 | ||
7cd4527e AC |
27269 | @node Using Resources |
27270 | @subsection Using Resources | |
27271 | @cindex Resources, using | |
27272 | ||
88e1739c | 27273 | @noindent |
7cd4527e AC |
27274 | To include the resource file in your program just add the |
27275 | GNAT-compatible object file for the resource(s) to the linker | |
27276 | arguments. With @code{gnatmake} this is done by using the @option{-largs} | |
27277 | option: | |
88e1739c FW |
27278 | |
27279 | @smallexample | |
7cd4527e | 27280 | $ gnatmake myprog -largs myres.o |
88e1739c | 27281 | @end smallexample |
88e1739c | 27282 | |
7cd4527e AC |
27283 | @node Debugging a DLL |
27284 | @section Debugging a DLL | |
27285 | @cindex DLL debugging | |
88e1739c | 27286 | |
7cd4527e AC |
27287 | @menu |
27288 | * Program and DLL Both Built with GCC/GNAT:: | |
27289 | * Program Built with Foreign Tools and DLL Built with GCC/GNAT:: | |
27290 | @end menu | |
88e1739c FW |
27291 | |
27292 | @noindent | |
7cd4527e AC |
27293 | Debugging a DLL is similar to debugging a standard program. But |
27294 | we have to deal with two different executable parts: the DLL and the | |
27295 | program that uses it. We have the following four possibilities: | |
88e1739c | 27296 | |
7cd4527e | 27297 | @enumerate 1 |
88e1739c | 27298 | @item |
7cd4527e | 27299 | The program and the DLL are built with @code{GCC/GNAT}. |
88e1739c | 27300 | @item |
7cd4527e AC |
27301 | The program is built with foreign tools and the DLL is built with |
27302 | @code{GCC/GNAT}. | |
88e1739c | 27303 | @item |
7cd4527e AC |
27304 | The program is built with @code{GCC/GNAT} and the DLL is built with |
27305 | foreign tools. | |
88e1739c | 27306 | @item |
7cd4527e | 27307 | @end enumerate |
88e1739c FW |
27308 | |
27309 | @noindent | |
7cd4527e AC |
27310 | In this section we address only cases one and two above. |
27311 | There is no point in trying to debug | |
27312 | a DLL with @code{GNU/GDB}, if there is no GDB-compatible debugging | |
27313 | information in it. To do so you must use a debugger compatible with the | |
27314 | tools suite used to build the DLL. | |
88e1739c | 27315 | |
7cd4527e AC |
27316 | @node Program and DLL Both Built with GCC/GNAT |
27317 | @subsection Program and DLL Both Built with GCC/GNAT | |
88e1739c FW |
27318 | |
27319 | @noindent | |
7cd4527e AC |
27320 | This is the simplest case. Both the DLL and the program have @code{GDB} |
27321 | compatible debugging information. It is then possible to break anywhere in | |
27322 | the process. Let's suppose here that the main procedure is named | |
27323 | @code{ada_main} and that in the DLL there is an entry point named | |
27324 | @code{ada_dll}. | |
88e1739c FW |
27325 | |
27326 | @noindent | |
7cd4527e AC |
27327 | The DLL (@pxref{Introduction to Dynamic Link Libraries (DLLs)}) and |
27328 | program must have been built with the debugging information (see GNAT -g | |
27329 | switch). Here are the step-by-step instructions for debugging it: | |
88e1739c | 27330 | |
7cd4527e AC |
27331 | @enumerate 1 |
27332 | @item Launch @code{GDB} on the main program. | |
88e1739c | 27333 | |
7cd4527e AC |
27334 | @smallexample |
27335 | $ gdb -nw ada_main | |
27336 | @end smallexample | |
88e1739c | 27337 | |
7cd4527e | 27338 | @item Break on the main procedure and run the program. |
88e1739c | 27339 | |
7cd4527e AC |
27340 | @smallexample |
27341 | (gdb) break ada_main | |
27342 | (gdb) run | |
27343 | @end smallexample | |
88e1739c FW |
27344 | |
27345 | @noindent | |
7cd4527e AC |
27346 | This step is required to be able to set a breakpoint inside the DLL. As long |
27347 | as the program is not run, the DLL is not loaded. This has the | |
27348 | consequence that the DLL debugging information is also not loaded, so it is not | |
27349 | possible to set a breakpoint in the DLL. | |
88e1739c | 27350 | |
7cd4527e | 27351 | @item Set a breakpoint inside the DLL |
88e1739c | 27352 | |
7cd4527e AC |
27353 | @smallexample |
27354 | (gdb) break ada_dll | |
27355 | (gdb) run | |
27356 | @end smallexample | |
88e1739c | 27357 | |
7cd4527e | 27358 | @end enumerate |
88e1739c | 27359 | |
7cd4527e AC |
27360 | @noindent |
27361 | At this stage a breakpoint is set inside the DLL. From there on | |
27362 | you can use the standard approach to debug the whole program | |
27363 | (@pxref{Running and Debugging Ada Programs}). | |
88e1739c | 27364 | |
7cd4527e AC |
27365 | @node Program Built with Foreign Tools and DLL Built with GCC/GNAT |
27366 | @subsection Program Built with Foreign Tools and DLL Built with GCC/GNAT | |
88e1739c | 27367 | |
7cd4527e AC |
27368 | @menu |
27369 | * Debugging the DLL Directly:: | |
27370 | * Attaching to a Running Process:: | |
27371 | @end menu | |
88e1739c | 27372 | |
7cd4527e AC |
27373 | @noindent |
27374 | In this case things are slightly more complex because it is not possible to | |
27375 | start the main program and then break at the beginning to load the DLL and the | |
27376 | associated DLL debugging information. It is not possible to break at the | |
27377 | beginning of the program because there is no @code{GDB} debugging information, | |
27378 | and therefore there is no direct way of getting initial control. This | |
27379 | section addresses this issue by describing some methods that can be used | |
27380 | to break somewhere in the DLL to debug it. | |
88e1739c FW |
27381 | |
27382 | @noindent | |
7cd4527e AC |
27383 | First suppose that the main procedure is named @code{main} (this is for |
27384 | example some C code built with Microsoft Visual C) and that there is a | |
27385 | DLL named @code{test.dll} containing an Ada entry point named | |
27386 | @code{ada_dll}. | |
88e1739c | 27387 | |
7cd4527e AC |
27388 | @noindent |
27389 | The DLL (@pxref{Introduction to Dynamic Link Libraries (DLLs)}) must have | |
27390 | been built with debugging information (see GNAT -g option). | |
88e1739c | 27391 | |
7cd4527e AC |
27392 | @node Debugging the DLL Directly |
27393 | @subsubsection Debugging the DLL Directly | |
88e1739c | 27394 | |
7cd4527e | 27395 | @enumerate 1 |
88e1739c | 27396 | @item |
7cd4527e | 27397 | Launch the debugger on the DLL. |
88e1739c | 27398 | |
7cd4527e AC |
27399 | @smallexample |
27400 | $ gdb -nw test.dll | |
27401 | @end smallexample | |
88e1739c | 27402 | |
7cd4527e | 27403 | @item Set a breakpoint on a DLL subroutine. |
88e1739c | 27404 | |
7cd4527e AC |
27405 | @smallexample |
27406 | (gdb) break ada_dll | |
27407 | @end smallexample | |
88e1739c | 27408 | |
88e1739c | 27409 | @item |
7cd4527e | 27410 | Specify the executable file to @code{GDB}. |
88e1739c | 27411 | |
7cd4527e AC |
27412 | @smallexample |
27413 | (gdb) exec-file main.exe | |
27414 | @end smallexample | |
88e1739c FW |
27415 | |
27416 | @item | |
7cd4527e | 27417 | Run the program. |
88e1739c | 27418 | |
7cd4527e AC |
27419 | @smallexample |
27420 | (gdb) run | |
27421 | @end smallexample | |
88e1739c FW |
27422 | |
27423 | @noindent | |
7cd4527e AC |
27424 | This will run the program until it reaches the breakpoint that has been |
27425 | set. From that point you can use the standard way to debug a program | |
27426 | as described in (@pxref{Running and Debugging Ada Programs}). | |
88e1739c | 27427 | |
7cd4527e | 27428 | @end enumerate |
88e1739c FW |
27429 | |
27430 | @noindent | |
7cd4527e | 27431 | It is also possible to debug the DLL by attaching to a running process. |
88e1739c | 27432 | |
7cd4527e AC |
27433 | @node Attaching to a Running Process |
27434 | @subsubsection Attaching to a Running Process | |
27435 | @cindex DLL debugging, attach to process | |
88e1739c | 27436 | |
7cd4527e AC |
27437 | @noindent |
27438 | With @code{GDB} it is always possible to debug a running process by | |
27439 | attaching to it. It is possible to debug a DLL this way. The limitation | |
27440 | of this approach is that the DLL must run long enough to perform the | |
27441 | attach operation. It may be useful for instance to insert a time wasting | |
27442 | loop in the code of the DLL to meet this criterion. | |
88e1739c | 27443 | |
7cd4527e | 27444 | @enumerate 1 |
88e1739c | 27445 | |
7cd4527e | 27446 | @item Launch the main program @file{main.exe}. |
88e1739c | 27447 | |
7cd4527e AC |
27448 | @smallexample |
27449 | $ main | |
27450 | @end smallexample | |
88e1739c | 27451 | |
7cd4527e AC |
27452 | @item Use the Windows @i{Task Manager} to find the process ID. Let's say |
27453 | that the process PID for @file{main.exe} is 208. | |
88e1739c | 27454 | |
7cd4527e | 27455 | @item Launch gdb. |
88e1739c | 27456 | |
7cd4527e AC |
27457 | @smallexample |
27458 | $ gdb -nw | |
27459 | @end smallexample | |
88e1739c | 27460 | |
7cd4527e | 27461 | @item Attach to the running process to be debugged. |
88e1739c | 27462 | |
7cd4527e AC |
27463 | @smallexample |
27464 | (gdb) attach 208 | |
27465 | @end smallexample | |
88e1739c | 27466 | |
7cd4527e | 27467 | @item Load the process debugging information. |
88e1739c FW |
27468 | |
27469 | @smallexample | |
7cd4527e | 27470 | (gdb) symbol-file main.exe |
88e1739c FW |
27471 | @end smallexample |
27472 | ||
7cd4527e | 27473 | @item Break somewhere in the DLL. |
88e1739c | 27474 | |
7cd4527e AC |
27475 | @smallexample |
27476 | (gdb) break ada_dll | |
27477 | @end smallexample | |
88e1739c | 27478 | |
7cd4527e | 27479 | @item Continue process execution. |
88e1739c | 27480 | |
7cd4527e AC |
27481 | @smallexample |
27482 | (gdb) continue | |
27483 | @end smallexample | |
88e1739c | 27484 | |
7cd4527e | 27485 | @end enumerate |
88e1739c | 27486 | |
7cd4527e AC |
27487 | @noindent |
27488 | This last step will resume the process execution, and stop at | |
27489 | the breakpoint we have set. From there you can use the standard | |
27490 | approach to debug a program as described in | |
27491 | (@pxref{Running and Debugging Ada Programs}). | |
27492 | ||
27493 | @node GNAT and COM/DCOM Objects | |
27494 | @section GNAT and COM/DCOM Objects | |
27495 | @findex COM | |
27496 | @findex DCOM | |
88e1739c FW |
27497 | |
27498 | @noindent | |
7cd4527e AC |
27499 | This section is temporarily left blank. |
27500 | ||
88e1739c FW |
27501 | @end ifset |
27502 | ||
7cd4527e AC |
27503 | |
27504 | @c ********************************** | |
27505 | @c * GNU Free Documentation License * | |
27506 | @c ********************************** | |
88e1739c FW |
27507 | @include fdl.texi |
27508 | @c GNU Free Documentation License | |
27509 | ||
27510 | @node Index,,GNU Free Documentation License, Top | |
27511 | @unnumbered Index | |
27512 | ||
27513 | @printindex cp | |
27514 | ||
27515 | @contents | |
7cd4527e AC |
27516 | @c Put table of contents at end, otherwise it precedes the "title page" in |
27517 | @c the .txt version | |
27518 | @c Edit the pdf file to move the contents to the beginning, after the title | |
27519 | @c page | |
88e1739c FW |
27520 | |
27521 | @bye |