Debian Codegraph @

gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst

raw
1 .. role:: switch(samp)
2
3 .. |with| replace:: *with*
4 .. |withs| replace:: *with*\ s
5 .. |withed| replace:: *with*\ ed
6 .. |withing| replace:: *with*\ ing
7
8 .. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
9
10
11 .. _The_GNAT_Compilation_Model:
12
13 **************************
14 The GNAT Compilation Model
15 **************************
16
17 .. index:: ! GNAT compilation model
18
19 .. index:: Compilation model
20
21 This chapter describes the compilation model used by GNAT. Although
22 similar to that used by other languages such as C and C++, this model
23 is substantially different from the traditional Ada compilation models,
24 which are based on a centralized program library. The chapter covers
25 the following material:
26
27 * Topics related to source file makeup and naming
28
29 * :ref:`Source_Representation`
30 * :ref:`Foreign_Language_Representation`
31 * :ref:`File_Naming_Topics_and_Utilities`
32
33 * :ref:`Configuration_Pragmas`
34 * :ref:`Generating_Object_Files`
35 * :ref:`Source_Dependencies`
36 * :ref:`The_Ada_Library_Information_Files`
37 * :ref:`Binding_an_Ada_Program`
38 * :ref:`GNAT_and_Libraries`
39 * :ref:`Conditional_Compilation`
40 * :ref:`Mixed_Language_Programming`
41 * :ref:`GNAT_and_Other_Compilation_Models`
42 * :ref:`Using_GNAT_Files_with_External_Tools`
43
44
45 .. _Source_Representation:
46
47 Source Representation
48 =====================
49
50 .. index:: Latin-1
51
52 .. index:: VT, HT, CR, LF, FF
53
54 Ada source programs are represented in standard text files, using
55 Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar
56 7-bit ASCII set plus additional characters used for
57 representing foreign languages (see :ref:`Foreign_Language_Representation`
58 for support of non-USA character sets). The format effector characters
59 are represented using their standard ASCII encodings, as follows:
60
61 =========== ======================= ===========
62 Character Effect Code
63 ----------- ----------------------- -----------
64 :kbd:`VT` Vertical tab ``16#0B#``
65 :kbd:`HT` Horizontal tab ``16#09#``
66 :kbd:`CR` Carriage return ``16#0D#``
67 :kbd:`LF` Line feed ``16#0A#``
68 :kbd:`FF` Form feed ``16#0C#``
69 =========== ======================= ===========
70
71 Source files are in standard text file format. In addition, GNAT
72 recognizes a wide variety of stream formats, in which the end of
73 physical lines is marked by any of the following sequences:
74 ``LF``, ``CR``, ``CR-LF``, or ``LF-CR``. This is useful
75 in accommodating files imported from other operating systems.
76
77 .. index:: pair: End of source file; Source file, end
78
79 .. index:: SUB (control character)
80
81 The end of a source file is normally represented by the physical end of
82 file. However, the control character ``16#1A#`` (:kbd:`SUB`) is also
83 recognized as signalling the end of the source file. Again, this is
84 provided for compatibility with other, legacy, operating systems where this
85 code is used to represent the end of file.
86
87 .. index:: spec (definition), compilation (definition)
88
89 Each file contains a single Ada compilation unit, including any pragmas
90 associated with the unit. For example, this means you must place a
91 package declaration (a package *spec*) and the corresponding body in
92 separate files. An Ada *compilation* (which is a sequence of
93 compilation units) is represented using a sequence of files. Similarly,
94 you place each subunit or child unit in a separate file.
95
96 .. _Foreign_Language_Representation:
97
98 Foreign Language Representation
99 ===============================
100
101 GNAT supports the standard character sets defined in Ada as well as
102 several other non-standard character sets for use in localized versions
103 of the compiler (:ref:`Character_Set_Control`).
104
105 .. _Latin-1:
106
107 Latin-1
108 -------
109
110 .. index:: Latin-1
111
112 The basic character set is Latin-1. This character set is defined by ISO
113 standard 8859, part 1. The lower half (character codes ``16#00#``
114 ... ``16#7F#)`` is identical to standard ASCII coding but the upper
115 half is used to represent additional characters. These include extended letters
116 used by European languages, such as French accents, the vowels with umlauts
117 used in German, and the extra letter A-ring used in Swedish.
118
119 .. index:: Ada.Characters.Latin_1
120
121 For a complete list of Latin-1 codes and their encodings, see the source
122 file of library unit ``Ada.Characters.Latin_1`` in file
123 :file:`a-chlat1.ads`.
124 You may use any of these extended characters freely in character or
125 string literals. In addition, the extended characters that represent
126 letters can be used in identifiers.
127
128 .. _Other_8-Bit_Codes:
129
130 Other 8-Bit Codes
131 -----------------
132
133 GNAT also supports several other 8-bit coding schemes:
134
135
136 .. index:: Latin-2
137 .. index:: ISO 8859-2
138
139 *ISO 8859-2 (Latin-2)*
140 Latin-2 letters allowed in identifiers, with uppercase and lowercase
141 equivalence.
142
143 .. index:: Latin-3
144 .. index:: ISO 8859-3
145
146 *ISO 8859-3 (Latin-3)*
147 Latin-3 letters allowed in identifiers, with uppercase and lowercase
148 equivalence.
149
150
151 .. index:: Latin-4
152 .. index:: ISO 8859-4
153
154 *ISO 8859-4 (Latin-4)*
155 Latin-4 letters allowed in identifiers, with uppercase and lowercase
156 equivalence.
157
158
159 .. index:: ISO 8859-5
160 .. index:: Cyrillic
161
162 *ISO 8859-5 (Cyrillic)*
163 ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and
164 lowercase equivalence.
165
166 .. index:: ISO 8859-15
167 .. index:: Latin-9
168
169 *ISO 8859-15 (Latin-9)*
170 ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and
171 lowercase equivalence.
172
173 .. index:: code page 437 (IBM PC)
174
175 *IBM PC (code page 437)*
176 This code page is the normal default for PCs in the US. It corresponds
177 to the original IBM PC character set. This set has some, but not all, of
178 the extended Latin-1 letters, but these letters do not have the same
179 encoding as Latin-1. In this mode, these letters are allowed in
180 identifiers with uppercase and lowercase equivalence.
181
182 .. index:: code page 850 (IBM PC)
183
184 *IBM PC (code page 850)*
185 This code page is a modification of 437 extended to include all the
186 Latin-1 letters, but still not with the usual Latin-1 encoding. In this
187 mode, all these letters are allowed in identifiers with uppercase and
188 lowercase equivalence.
189
190
191 *Full Upper 8-bit*
192 Any character in the range 80-FF is allowed in identifiers and all are
193 considered distinct. In other words, there are no uppercase and lowercase
194 equivalences in this range. This is useful in conjunction with
195 certain encoding schemes used for some foreign character sets (e.g.,
196 the typical method of representing Chinese characters on the PC).
197
198
199 *No Upper-Half*
200 No upper-half characters in the range 80-FF are allowed in identifiers.
201 This gives Ada 83 compatibility for identifier names.
202
203 For precise data on the encodings permitted, and the uppercase and lowercase
204 equivalences that are recognized, see the file :file:`csets.adb` in
205 the GNAT compiler sources. You will need to obtain a full source release
206 of GNAT to obtain this file.
207
208 .. _Wide_Character_Encodings:
209
210 Wide_Character Encodings
211 ------------------------
212
213 GNAT allows wide character codes to appear in character and string
214 literals, and also optionally in identifiers, by means of the following
215 possible encoding schemes:
216
217 *Hex Coding*
218 In this encoding, a wide character is represented by the following five
219 character sequence::
220
221 ESC a b c d
222
223 where ``a``, ``b``, ``c``, ``d`` are the four hexadecimal
224 characters (using uppercase letters) of the wide character code. For
225 example, ESC A345 is used to represent the wide character with code
226 ``16#A345#``.
227 This scheme is compatible with use of the full Wide_Character set.
228
229 .. index:: Upper-Half Coding
230
231 *Upper-Half Coding*
232 The wide character with encoding ``16#abcd#`` where the upper bit is on
233 (in other words, 'a' is in the range 8-F) is represented as two bytes,
234 ``16#ab#`` and ``16#cd#``. The second byte cannot be a format control
235 character, but is not required to be in the upper half. This method can
236 be also used for shift-JIS or EUC, where the internal coding matches the
237 external coding.
238
239 .. index:: Shift JIS Coding
240
241 *Shift JIS Coding*
242 A wide character is represented by a two-character sequence,
243 ``16#ab#`` and
244 ``16#cd#``, with the restrictions described for upper-half encoding as
245 described above. The internal character code is the corresponding JIS
246 character according to the standard algorithm for Shift-JIS
247 conversion. You can only use characters defined in the JIS code set table
248 with this encoding method.
249
250 .. index:: EUC Coding
251
252 *EUC Coding*
253 A wide character is represented by a two-character sequence
254 ``16#ab#`` and ``16#cd#``, with both characters being in the upper
255 half. The internal character code is the corresponding JIS character
256 according to the EUC encoding algorithm. You can only use characters
257 defined in the JIS code set table with this encoding method.
258
259
260 *UTF-8 Coding*
261 A wide character is represented using
262 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
263 10646-1/Am.2. Depending on the character value, the representation
264 is a one, two, or three byte sequence::
265
266 16#0000#-16#007f#: 2#0xxxxxxx#
267 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
268 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
269
270 where the ``xxx`` bits correspond to the left-padded bits of the
271 16-bit character value. Note that all lower half ASCII characters
272 are represented as ASCII bytes and all upper half characters and
273 other wide characters are represented as sequences of upper-half
274 (The full UTF-8 scheme allows for encoding 31-bit characters as
275 6-byte sequences the use of these sequences is documented in the
276 following section on wide wide characters.)
277
278
279 *Brackets Coding*
280 In this encoding, a wide character is represented by the following eight
281 character sequence::
282
283 [ " a b c d " ]
284
285 where ``a``, ``b``, ``c``, ``d`` are the four hexadecimal characters
286 (using uppercase letters) of the wide character code. For example,
287 ['A345'] is used to represent the wide character with code
288 ``16#A345#``. You can also (though you are not required to) use the
289 Brackets coding for upper half characters. For example, you can
290 represent the code ``16#A3#`` as ``['A3']``.
291
292 This scheme is compatible with use of the full ``Wide_Character`` set,
293 and is also the method used for wide character encoding in some standard
294 ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
295
296 .. note::
297
298 Some of these coding schemes do not permit the full use of the
299 Ada character set. For example, neither Shift JIS nor EUC allow the
300 use of the upper half of the Latin-1 set.
301
302 .. _Wide_Wide_Character_Encodings:
303
304 Wide_Wide_Character Encodings
305 -----------------------------
306
307 GNAT allows wide wide character codes to appear in character and string
308 literals, and also optionally in identifiers, by means of the following
309 possible encoding schemes:
310
311 *UTF-8 Coding*
312 A wide character is represented using
313 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
314 10646-1/Am.2. Depending on the character value, the representation
315 of character codes with values greater than 16#FFFF# is a
316 is a four, five, or six byte sequence::
317
318 16#01_0000#-16#10_FFFF#: 11110xxx 10xxxxxx 10xxxxxx
319 10xxxxxx
320 16#0020_0000#-16#03FF_FFFF#: 111110xx 10xxxxxx 10xxxxxx
321 10xxxxxx 10xxxxxx
322 16#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx
323 10xxxxxx 10xxxxxx 10xxxxxx
324
325
326 where the ``xxx`` bits correspond to the left-padded bits of the
327 32-bit character value.
328
329 *Brackets Coding*
330 In this encoding, a wide wide character is represented by the following ten or
331 twelve byte character sequence::
332
333 [ " a b c d e f " ]
334 [ " a b c d e f g h " ]
335
336 where ``a-h`` are the six or eight hexadecimal
337 characters (using uppercase letters) of the wide wide character code. For
338 example, ["1F4567"] is used to represent the wide wide character with code
339 ``16#001F_4567#``.
340
341 This scheme is compatible with use of the full ``Wide_Wide_Character`` set,
342 and is also the method used for wide wide character encoding in some standard
343 ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
344
345
346 .. _File_Naming_Topics_and_Utilities:
347
348 File Naming Topics and Utilities
349 ================================
350
351 GNAT has a default file naming scheme, but and also provides you
352 with a high degree of control over how the names and extensions of your
353 source files correspond to the Ada compilation units that they
354 contain.
355
356
357 .. _File_Naming_Rules:
358
359 File Naming Rules
360 -----------------
361
362 GNAT determines the default file name by the name of the unit that the
363 file contains. The name is formed by taking the full expanded name of
364 the unit, replacing the separating dots with hyphens, and using
365 lowercase for all letters.
366
367 An exception occurs if the file name generated by the above rules starts
368 with one of the characters
369 ``a``, ``g``, ``i``, or ``s`` and the second character is a
370 hyphen. In this case, the character tilde is used in place
371 of the hypen. This special rule avoids clashes with
372 the standard names for child units of the packages ``System``, ``Ada``,
373 ``Interfaces``, and ``GNAT``, which use the prefixes
374 ``s-``, ``a-``, ``i-``, and ``g-``,
375 respectively.
376
377 The file extension is :file:`.ads` for a spec and
378 :file:`.adb` for a body. The following table shows some
379 examples of these rules.
380
381 ============================ ===============================
382 Source File Ada Compilation Unit
383 ---------------------------- -------------------------------
384 :file:`main.ads` Main (spec)
385 :file:`main.adb` Main (body)
386 :file:`arith_functions.ads` Arith_Functions (package spec)
387 :file:`arith_functions.adb` Arith_Functions (package body)
388 :file:`func-spec.ads` Func.Spec (child package spec)
389 :file:`func-spec.adb` Func.Spec (child package body)
390 :file:`main-sub.adb` Sub (subunit of Main)
391 :file:`a~bad.adb` A.Bad (child package body)
392 ============================ ===============================
393
394 Following these rules can result in excessively long
395 file names if corresponding
396 unit names are long (for example, if child units or subunits are
397 heavily nested). An option is available to shorten such long file names
398 (called file name 'krunching'). You may find this particularly useful when
399 programs being developed with GNAT are to be used on operating systems
400 with limited file name lengths. :ref:`Using_gnatkr`.
401
402 Of course, no file shortening algorithm can guarantee uniqueness over
403 all possible unit names; if file name krunching is used, it is your
404 responsibility to ensure no name clashes occur. Alternatively, you
405 can specify the exact file names that you want used, as described
406 in the next section. Finally, if your Ada programs are migrating from a
407 compiler with a different naming convention, you can use the ``gnatchop``
408 utility to produce source files that follow the GNAT naming conventions.
409 (For details see :ref:`Renaming_Files_with_gnatchop`.)
410
411 Note: in the case of Windows or Mac OS operating systems, case is not
412 significant. So, for example, on Windows if the canonical name is
413 :file:`main-sub.adb`, you can use the file name :file:`Main-Sub.adb` instead.
414 However, case is significant for other operating systems, so, for example,
415 if you want to use other than canonically cased file names on a Unix system,
416 you need to follow the procedures described in the next section.
417
418 .. _Using_Other_File_Names:
419
420 Using Other File Names
421 ----------------------
422
423 .. index:: File names
424
425 The previous section described the default rules used by
426 GNAT to determine the file name in which a given unit resides. It is
427 usually convenient to follow these default rules, and if you follow them,
428 the compiler knows without being explicitly told where to find all
429 the files it needs.
430
431 .. index:: Source_File_Name pragma
432
433 However, in some cases, particularly when a program is imported from
434 another Ada compiler environment, it may be more convenient for you
435 to specify which file names contain which units. GNAT allows
436 arbitrary file names to be used by means of the ``Source_File_Name`` pragma.
437 The form of this pragma is as shown in the following examples:
438
439 .. code-block:: ada
440
441 pragma Source_File_Name (My_Utilities.Stacks,
442 Spec_File_Name => "myutilst_a.ada");
443 pragma Source_File_name (My_Utilities.Stacks,
444 Body_File_Name => "myutilst.ada");
445
446 As shown in this example, the first argument for the pragma is the unit
447 name (in this example a child unit). The second argument has the form
448 of a named association. The identifier
449 indicates whether the file name is for a spec or a body;
450 the file name itself is given by a string literal.
451
452 The source file name pragma is a configuration pragma, which means that
453 normally you will place it in the :file:`gnat.adc`
454 file used to hold configuration
455 pragmas that apply to a complete compilation environment.
456 For more details on how the :file:`gnat.adc` file is created and used
457 see :ref:`Handling_of_Configuration_Pragmas`.
458
459 .. index:: gnat.adc
460
461 GNAT allows you to specify completely arbitrary file names using the
462 source file name pragma. However, if the file name specified has an
463 extension other than :file:`.ads` or :file:`.adb` you must use a
464 special syntax when compiling the file. The name on the command line
465 in this case must be preceded by the special sequence ``-x`` followed
466 by a space and the name of the language, here ``ada``, as in:
467
468 .. code-block:: sh
469
470 $ gcc -c -x ada peculiar_file_name.sim
471
472 ``gnatmake`` handles non-standard file names in the usual manner (the
473 non-standard file name for the main program is simply used as the
474 argument to ``gnatmake``). Note that if the extension is also non-standard,
475 you must include it in the ``gnatmake`` command; it may not
476 be omitted.
477
478 .. _Alternative_File_Naming_Schemes:
479
480 Alternative File Naming Schemes
481 -------------------------------
482
483 .. index:: File naming schemes, alternative
484
485 .. index:: File names
486
487 The previous section described the use of the ``Source_File_Name``
488 pragma to allow arbitrary names to be assigned to individual source files.
489 However, this approach requires one pragma for each file and, especially in
490 large systems, can result in very long :file:`gnat.adc` files, which can create
491 a maintenance problem.
492
493 .. index:: Source_File_Name pragma
494
495 GNAT also provides a facility for specifying systematic file naming schemes
496 other than the standard default naming scheme previously described. An
497 alternative scheme for naming is specified by the use of
498 ``Source_File_Name`` pragmas having the following format:
499
500 .. code-block:: ada
501
502 pragma Source_File_Name (
503 Spec_File_Name => FILE_NAME_PATTERN
504 [ , Casing => CASING_SPEC]
505 [ , Dot_Replacement => STRING_LITERAL ] );
506
507 pragma Source_File_Name (
508 Body_File_Name => FILE_NAME_PATTERN
509 [ , Casing => CASING_SPEC ]
510 [ , Dot_Replacement => STRING_LITERAL ] ) ;
511
512 pragma Source_File_Name (
513 Subunit_File_Name => FILE_NAME_PATTERN
514 [ , Casing => CASING_SPEC ]
515 [ , Dot_Replacement => STRING_LITERAL ] ) ;
516
517 FILE_NAME_PATTERN ::= STRING_LITERAL
518 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
519
520 The ``FILE_NAME_PATTERN`` string shows how the file name is constructed.
521 It contains a single asterisk character, and the unit name is substituted
522 systematically for this asterisk. The optional parameter
523 ``Casing`` indicates
524 whether the unit name is to be all upper-case letters, all lower-case letters,
525 or mixed-case. If no
526 ``Casing`` parameter is used, the default is all
527 lower-case.
528
529 You use the optional ``Dot_Replacement`` string to replace any periods
530 that occur in subunit or child unit names. If you don't specify a
531 ``Dot_Replacement`` argument, separating dots appear unchanged in the
532 resulting file name. The above syntax indicates that the ``Casing``
533 argument must appear before the ``Dot_Replacement`` argument, but you
534 can write these arguments in any order.
535
536 As indicated, you can specify different naming schemes for
537 bodies, specs, and subunits. Quite often, the rule for subunits is the
538 same as the rule for bodies, in which case, you need not provide
539 a separate ``Subunit_File_Name`` rule; in this case the
540 ``Body_File_name`` rule is used for subunits as well.
541
542 You can also use the separate rule for subunits to implement the rather
543 unusual case of a compilation environment (e.g., a single directory) which
544 contains a subunit and a child unit with the same unit name. Although
545 both units cannot appear in the same partition, the Ada Reference Manual
546 allows (but does not require) the possibility of the two units coexisting
547 in the same environment.
548
549 File name translation consists of the following steps:
550
551 * If there is a specific ``Source_File_Name`` pragma for the given unit,
552 this is always used and any general pattern rules are ignored.
553
554 * If there is a pattern type ``Source_File_Name`` pragma that applies to
555 the unit, the resulting file name is used if the file exists. If
556 more than one pattern matches, the latest one is tried first and the
557 first attempt that results in a reference to a file that exists is used.
558
559 * If no pattern type ``Source_File_Name`` pragma that applies to the unit
560 for which the corresponding file exists, the standard GNAT default
561 naming rules are used.
562
563 As an example of the use of this mechanism, consider a commonly used scheme
564 in which file names are all lower case, with separating periods copied
565 unchanged to the resulting file name, specs end with :file:`.1.ada`, and
566 bodies end with :file:`.2.ada`. GNAT will follow this scheme if the following
567 two pragmas appear:
568
569 .. code-block:: ada
570
571 pragma Source_File_Name
572 (Spec_File_Name => ".1.ada");
573 pragma Source_File_Name
574 (Body_File_Name => ".2.ada");
575
576 The default GNAT scheme is equivalent to providing the following
577 default pragmas:
578
579 .. code-block:: ada
580
581 pragma Source_File_Name
582 (Spec_File_Name => ".ads", Dot_Replacement => "-");
583 pragma Source_File_Name
584 (Body_File_Name => ".adb", Dot_Replacement => "-");
585
586 Our final example implements a scheme typically used with one of the
587 legacy Ada 83 compilers, where the separator character for subunits was '__'
588 (two underscores), specs were identified by adding :file:`_.ADA`, bodies
589 by adding :file:`.ADA`, and subunits by
590 adding :file:`.SEP`. All file names were
591 upper case. Child units were not present, of course, since this was an
592 Ada 83 compiler, but it seems reasonable to extend this scheme to use
593 the same double underscore separator for child units.
594
595 .. code-block:: ada
596
597 pragma Source_File_Name
598 (Spec_File_Name => "_.ADA",
599 Dot_Replacement => "__",
600 Casing = Uppercase);
601 pragma Source_File_Name
602 (Body_File_Name => ".ADA",
603 Dot_Replacement => "__",
604 Casing = Uppercase);
605 pragma Source_File_Name
606 (Subunit_File_Name => ".SEP",
607 Dot_Replacement => "__",
608 Casing = Uppercase);
609
610
611 .. index:: ! gnatname
612
613 .. _Handling_Arbitrary_File_Naming_Conventions_with_gnatname:
614
615 Handling Arbitrary File Naming Conventions with ``gnatname``
616 ------------------------------------------------------------
617
618 .. index:: File Naming Conventions
619
620 .. _Arbitrary_File_Naming_Conventions:
621
622 Arbitrary File Naming Conventions
623 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
624
625 The GNAT compiler must know the source file name of a compilation unit
626 in order to compile it. When using the standard GNAT default file
627 naming conventions (``.ads`` for specs, ``.adb`` for bodies), it
628 does not need additional information.
629
630 When the source file names do not follow the standard GNAT default
631 file naming conventions, you must give the GNAT compiler additional
632 information through a configuration pragmas file
633 (:ref:`Configuration_Pragmas`) or a project file. When the
634 non-standard file naming conventions are well-defined, a small number
635 of pragmas ``Source_File_Name`` specifying a naming pattern
636 (:ref:`Alternative_File_Naming_Schemes`) may be sufficient. However,
637 if the file naming conventions are irregular or arbitrary, you must
638 define a number of pragma ``Source_File_Name`` for individual
639 compilation units. To help maintain the correspondence between
640 compilation unit names and source file names within the compiler, GNAT
641 provides a tool ``gnatname`` to generate the required pragmas for a
642 set of files.
643
644 .. _Running_gnatname:
645
646 Running ``gnatname``
647 ^^^^^^^^^^^^^^^^^^^^
648
649 The usual form of the ``gnatname`` command is:
650
651 .. code-block:: sh
652
653 $ gnatname [ switches ] naming_pattern [ naming_patterns ]
654 [--and [ switches ] naming_pattern [ naming_patterns ]]
655
656
657 All of the arguments are optional. If invoked without any arguments,
658 ``gnatname`` will display its usage.
659
660 When used with at least one naming pattern, ``gnatname`` attempts to
661 find all the compilation units in files that follow at least one of the
662 naming patterns. To find these compilation units,
663 ``gnatname`` uses the GNAT compiler in syntax-check-only mode on all
664 regular files.
665
666 One or several *Naming Patterns* may be given as arguments to ``gnatname``.
667 Each Naming Pattern is enclosed between double quotes (or single
668 quotes on Windows).
669 A Naming Pattern is a regular expression similar to the wildcard patterns
670 used in file names by the Unix shells or the DOS prompt.
671
672 You may call ``gnatname`` with several sections of
673 directories/patterns. Sections are separated by the switch
674 :switch:`--and`. In each section, you must include at least one
675 pattern. If you don't specify a directory a section, the current
676 directory (or the project directory if :switch:`-P` is used) is
677 used. The options other that the directory switches and the
678 patterns apply globally even if they are in different sections.
679
680 Examples of Naming Patterns are::
681
682 "*.[12].ada"
683 "*.ad[sb]*"
684 "body_*" "spec_*"
685
686 For a more complete description of the syntax of Naming Patterns,
687 see the second kind of regular expressions described in :file:`g-regexp.ads`
688 (the 'Glob' regular expressions).
689
690 When invoked without the switch :switch:`-P`, ``gnatname`` will create a
691 configuration pragmas file :file:`gnat.adc` in the current working directory,
692 with pragmas ``Source_File_Name`` for each file that contains a valid Ada
693 unit.
694
695 .. _Switches_for_gnatname:
696
697 Switches for ``gnatname``
698 ^^^^^^^^^^^^^^^^^^^^^^^^^
699
700 Switches for ``gnatname`` must precede any specified Naming Pattern.
701
702 You may specify any of the following switches to ``gnatname``:
703
704 .. index:: --version (gnatname)
705
706 :switch:`--version`
707 Display Copyright and version, then exit disregarding, all other options.
708
709 .. index:: --help (gnatname)
710
711 :switch:`--help`
712 If :switch:`--version` was not used, display usage, then exit, disregarding
713 all other options.
714
715 :switch:`--subdirs={dir}`
716 Actual object, library or exec directories are subdirectories <dir> of the
717 specified ones.
718
719 :switch:`--no-backup`
720 Do not create a backup copy of an existing project file.
721
722 :switch:`--and`
723 Start another section of directories/patterns.
724
725 .. index:: -c (gnatname)
726
727 :switch:`-c{filename}`
728 Create a configuration pragmas file :file:`filename` (instead of the default
729 :file:`gnat.adc`).
730 There may be zero, one, or more space between :switch:`-c` and
731 :file:`filename`.
732 :file:`filename` may include directory information. :file:`filename` must be
733 writable. You can specify only one switch :switch:`-c`.
734 When a switch :switch:`-c` is
735 specified, you may not specify switch :switch:`-P` (see below).
736
737 .. index:: -d (gnatname)
738
739 :switch:`-d{dir}`
740 Look for source files in directory :file:`dir`. You may put zero, one or more
741 spaces between :switch:`-d` and :file:`dir`.
742 :file:`dir` may end with ``/**``, i.e., you may write it the form
743 ``root_dir/**``. In this case, the directory ``root_dir`` and all of its
744 subdirectories, recursively, have to be searched for sources.
745 When you specify a :switch:`-d` switch,
746 the current working directory will is not searched for source
747 files unless you explicitly specify it with a :switch:`-d`
748 or :switch:`-D` switch.
749 You may specify several switches :switch:`-d`.
750 If :file:`dir` is a relative path, it is relative to the directory of
751 the configuration pragmas file specified with switch
752 :switch:`-c`,
753 or to the directory of the project file specified with switch
754 :switch:`-P` or,
755 if you don't specify either switch :switch:`-c`
756 or switch :switch:`-P`, it's relative to the
757 current working directory. The directory
758 you specified with switch :switch:`-d` must exist and be readable.
759
760 .. index:: -D (gnatname)
761
762 :switch:`-D{filename}`
763 Look for source files in all directories listed in text file :file:`filename`.
764 You may place zero, one or more spaces between :switch:`-D`
765 and :file:`filename`.
766 :file:`filename` must be an existing, readable text file.
767 Each nonempty line in :file:`filename` must be a directory.
768 Specifying switch :switch:`-D` is equivalent to specifying as many
769 switches :switch:`-d` as there are nonempty lines in
770 :file:`file`.
771
772 :switch:`-eL`
773 Follow symbolic links when processing project files.
774
775 .. index:: -f (gnatname)
776
777 :switch:`-f{pattern}`
778 Foreign patterns. Using this switch, you can add sources of languages
779 other than Ada to the list of sources of a project file, but
780 it's only useful if you also specify a :switch:`-P` switch.
781 For example,
782
783 .. code-block:: sh
784
785 gnatname -Pprj -f"*.c" "*.ada"
786
787 looks for Ada units in all files with the :file:`.ada` extension,
788 and adds the C files with extension :file:`.c` to the list of file
789 for project :file:`prj.gpr` .
790
791 .. index:: -h (gnatname)
792
793 :switch:`-h`
794 Output usage (help) information. The output is written to :file:`stdout`.
795
796 .. index:: -P (gnatname)
797
798 :switch:`-P{proj}`
799
800 Create or update project file :file:`proj`. You may place zero, one
801 or more space between :switch:`-P` and :file:`proj`. :file:`proj`
802 may include directory information. :file:`proj` must be writable.
803 There may be only one switch :switch:`-P`. When you specify switch
804 :switch:`-P`, you may not also include switch :switch:`-c`. On all
805 platforms except VMS when ``gnatname`` is invoked for an existing
806 project file :file:`<proj>.gpr``, ``gnatname`` creates a backup copy
807 of the project file in the project directory with file name
808 :file:`<proj>.gpr.saved_x` where ``x`` is the first non negative
809 number that creates a unique filename.
810
811 .. index:: -v (gnatname)
812
813 :switch:`-v`
814 Verbose mode. Output detailed explanation of what it's doing to :file:`stdout`.
815 This includes name of the file written, the name of the directories searched,
816 and, for each file in those directories whose name matches at least one of
817 the Naming Patterns, an indication of whether the file contains a unit,
818 and, if so, the name of the unit.
819
820 .. index:: -v -v (gnatname)
821
822 :switch:`-v -v`
823 Very verbose mode. In addition to the output produced in verbose mode
824 (a single :switch:`-v` switch),
825 for each file in the searched directories whose name matches none of
826 the Naming Patterns, ``gnatname`` indicates that there is no match.
827
828 .. index:: -x (gnatname)
829
830 :switch:`-x{pattern}`
831 Excluded patterns. Using this switch, you can exclude some files
832 that otherwise would match the name patterns. For example,
833
834 .. code-block:: sh
835
836 gnatname -x "*_nt.ada" "*.ada"
837
838 looks for Ada units in all files with the :file:`.ada` extension,
839 except those whose names end with :file:`_nt.ada`.
840
841
842 .. _Examples_of_gnatname_Usage:
843
844 Examples of ``gnatname`` Usage
845 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
846
847 .. code-block:: sh
848
849 $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"
850
851 In this example, the directory :file:`/home/me` must already exist
852 and be writable. In addition, the directory
853 :file:`/home/me/sources` (specified by
854 :switch:`-d sources`) must exist and be readable.
855
856 Note the optional spaces after :switch:`-c` and :switch:`-d`.
857
858 .. code-block:: sh
859
860 $ gnatname -P/home/me/proj -x "*_nt_body.ada"
861 -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
862
863 Note that you may use several :switch:`-d` switches, even in
864 conjunction with one or several :switch:`-D` switches. This example
865 illustrates multiple Naming Patterns and one excluded pattern.
866
867
868 .. _File_Name_Krunching_with_gnatkr:
869
870 File Name Krunching with ``gnatkr``
871 -----------------------------------
872
873 .. index:: ! gnatkr
874
875 Here we discuss the method used by the compiler to shorten
876 the default file names chosen for Ada units so that they do not
877 exceed the maximum length permitted. We also describe the
878 ``gnatkr`` utility, which you can use to determine the result of
879 applying this shortening.
880
881 .. _About_gnatkr:
882
883 About ``gnatkr``
884 ^^^^^^^^^^^^^^^^
885
886 GNAT requires that the file name must be derived from the unit
887 name. The default rule is as follows:
888
889 * Take the unit name and replace all dots by hyphens.
890
891 * If such a replacement occurs in the
892 second character position of a name, and the first character is
893 :samp:`a`, :samp:`g`, :samp:`s`, or :samp:`i`,
894 then replace the dot by the character
895 :samp:`~` (tilde)
896 instead of a hyphen.
897
898 This exception avoids clashes
899 with the standard names for children of System, Ada, Interfaces,
900 and GNAT, which use the prefixes
901 :samp:`s-`, :samp:`a-`, :samp:`i-`, and :samp:`g-`,
902 respectively.
903
904 The :switch:`-gnatk{nn}`
905 switch of the compiler activates a 'krunching'
906 circuit that limits file names to ``nn`` characters (where ``nn`` is a decimal
907 integer).
908
909 You can use the ``gnatkr`` utility to determine the krunched name for
910 a given file when krunched to a specified maximum length.
911
912 .. _Using_gnatkr:
913
914 Using ``gnatkr``
915 ^^^^^^^^^^^^^^^^
916
917 You invoke the ``gnatkr`` command as follows:
918
919 .. code-block:: sh
920
921 $ gnatkr name [ length ]
922
923 ``name`` is the uncrunched file name, derived from the name of the unit
924 in the default manner described in the previous section (i.e., in particular
925 all dots are replaced by hyphens). You may or may not include an
926 extension (defined as a suffix of the form period followed by arbitrary
927 characters other than period) in the filename. If you do, ``gnatkr`` will
928 preserve it in the output. For example, when krunching :file:`hellofile.ads`
929 to eight characters, the result will be :file:`hellofil.ads`.
930
931 Note: for compatibility with previous versions of ``gnatkr``, you can
932 use dots in the name instead of hyphens, but ``gnatkr`` always
933 interprets the last dot as the start of an extension. So if you pass ``gnatkr``
934 an argument such as :file:`Hello.World.adb`, it treats it
935 exactly as if the first period had been a hyphen, so, for
936 example, krunching to eight characters gives the result
937 :file:`hellworl.adb`.
938
939 Note that the result is always all lower case. Other characters are
940 folded as required.
941
942 ``length`` represents the length of the krunched name. The default
943 if you don't specify it, is 8 characters. A length of zero means
944 unlimited, in other words don't chop except for system files where the
945 implied crunching length is always eight characters.
946
947 The output is the krunched name. The output has an extension only if the
948 original argument was a file name with an extension.
949
950 .. _Krunching_Method:
951
952 Krunching Method
953 ^^^^^^^^^^^^^^^^
954
955 The initial file name is determined by the name of the unit that the file
956 contains. The name is formed by taking the full expanded name of the
957 unit and replacing the separating dots with hyphens and
958 using lowercase
959 for all letters, except that a hyphen in the second character position is
960 replaced by a tilde if the first character is
961 :samp:`a`, :samp:`i`, :samp:`g`, or :samp:`s`.
962 The extension is ``.ads`` for a
963 spec and ``.adb`` for a body.
964 Krunching does not affect the extension, but the file name is shortened to
965 the specified length by following these rules:
966
967 * The name is divided into segments separated by hyphens, tildes, or
968 underscores and all hyphens, tildes, and underscores are
969 eliminated. If this leaves the name short enough, we are done.
970
971 * If the name is too long, the longest segment is located (left-most
972 if there are two of equal length) and shortened by dropping
973 its last character. This is repeated until the name is short enough.
974
975 As an example, consider the krunching of :file:`our-strings-wide_fixed.adb`
976 to fit the name into 8 characters, as required by some operating systems::
977
978 our-strings-wide_fixed 22
979 our strings wide fixed 19
980 our string wide fixed 18
981 our strin wide fixed 17
982 our stri wide fixed 16
983 our stri wide fixe 15
984 our str wide fixe 14
985 our str wid fixe 13
986 our str wid fix 12
987 ou str wid fix 11
988 ou st wid fix 10
989 ou st wi fix 9
990 ou st wi fi 8
991 Final file name: oustwifi.adb
992
993 * The file names for all predefined units are always krunched to eight
994 characters. The krunching of these predefined units uses the following
995 special prefix replacements:
996
997 ===================== ==============
998 Prefix Replacement
999 --------------------- --------------
1000 :file:`ada-` :file:`a-`
1001 :file:`gnat-` :file:`g-`
1002 :file:`interfac es-` :file:`i-`
1003 :file:`system-` :file:`s-`
1004 ===================== ==============
1005
1006 These system files have a hyphen in the second character
1007 position. That's is why normal user files replace such a character
1008 with a tilde.
1009
1010 As an example of this special rule, consider
1011 :file:`ada-strings-wide_fixed.adb`, which gets krunched as follows::
1012
1013 ada-strings-wide_fixed 22
1014 a- strings wide fixed 18
1015 a- string wide fixed 17
1016 a- strin wide fixed 16
1017 a- stri wide fixed 15
1018 a- stri wide fixe 14
1019 a- str wide fixe 13
1020 a- str wid fixe 12
1021 a- str wid fix 11
1022 a- st wid fix 10
1023 a- st wi fix 9
1024 a- st wi fi 8
1025 Final file name: a-stwifi.adb
1026
1027 Of course, no file shortening algorithm can guarantee uniqueness over all
1028 possible unit names. If file name krunching is used, it'is your
1029 responsibility to ensure that no name clashes occur. The utility
1030 program ``gnatkr`` is supplied so that you can conveniently determine the
1031 krunched name of a file.
1032
1033 .. _Examples_of_gnatkr_Usage:
1034
1035 Examples of ``gnatkr`` Usage
1036 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1037
1038 ::
1039
1040 $ gnatkr very_long_unit_name.ads --> velounna.ads
1041 $ gnatkr grandparent-parent-child.ads --> grparchi.ads
1042 $ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads
1043 $ gnatkr grandparent-parent-child --> grparchi
1044 $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
1045 $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads
1046
1047
1048 .. _Renaming_Files_with_gnatchop:
1049
1050 Renaming Files with ``gnatchop``
1051 --------------------------------
1052
1053 .. index:: ! gnatchop
1054
1055 This section discusses how to handle files with multiple units by using
1056 the ``gnatchop`` utility. You will also find this utility useful in renaming
1057 files to meet the standard GNAT default file naming conventions.
1058
1059 .. _Handling_Files_with_Multiple_Units:
1060
1061 Handling Files with Multiple Units
1062 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1063
1064 GNAT's fundamental compilation model requires that a file submitted to the
1065 compiler contain only one unit and there be a strict correspondence
1066 between the file name and the unit name.
1067
1068 If you want to have your files contain multiple units,
1069 perhaps to maintain compatibility with some other Ada compilation system,
1070 you can use ``gnatname`` to generate or update your project files, which
1071 can be processed by GNAT.
1072
1073 See :ref:`Handling_Arbitrary_File_Naming_Conventions_with_gnatname`
1074 for more details on how to use `gnatname`.
1075
1076 Alternatively, if you want to permanently restructure a set of
1077 'foreign' files so that they match the GNAT rules, and do the
1078 remaining development using the GNAT structure, you can simply use
1079 ``gnatchop`` once, generate the new set of files containing only one
1080 unit per file, and work with them from that point on.
1081
1082 Note that if your file containing multiple units starts with a byte order
1083 mark (BOM) specifying UTF-8 encoding, each file generated by gnatchop
1084 will start with a copy of this BOM, meaning that they can be compiled
1085 automatically in UTF-8 mode without you needing to specify an explicit encoding.
1086
1087 .. _Operating_gnatchop_in_Compilation_Mode:
1088
1089 Operating gnatchop in Compilation Mode
1090 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1091
1092 The basic function of ``gnatchop`` is to take a file with multiple units
1093 and split it into separate files. The boundary between units is reasonably
1094 clear, except for the issue of comments and pragmas. In default mode, the
1095 rule is that any pragmas between units belong to the previous unit, except
1096 that configuration pragmas always belong to the following unit. Any comments
1097 belong to the following unit. These rules
1098 almost always result in the right choice of
1099 the split point without you needing to mark it explicitly and you'll likely
1100 find this default to be what you want. In this default mode, you may not
1101 submit a file containing only configuration pragmas, or one that ends in
1102 configuration pragmas, to ``gnatchop``.
1103
1104 However, using a special switch to activate 'compilation mode',
1105 ``gnatchop``
1106 can perform another function, which is to provide exactly the semantics
1107 required by the RM for the handling of configuration pragmas in a compilation.
1108 In the absence of configuration pragmas at the main file level, this
1109 switch has no effect, but it causes such configuration pragmas to be handled
1110 in a very different manner.
1111
1112 First, in compilation mode, if you give ``gnatchop`` a file that consists of
1113 only configuration pragmas, it appends this file to the
1114 :file:`gnat.adc` file in the current directory. This behavior provides
1115 the required behavior described in the RM for the actions to be taken
1116 on submitting such a file to the compiler, namely that these pragmas
1117 should apply to all subsequent compilations in the same compilation
1118 environment. Using GNAT, the current directory, possibly containing a
1119 :file:`gnat.adc` file is the representation
1120 of a compilation environment. For more information on the
1121 :file:`gnat.adc` file, see :ref:`Handling_of_Configuration_Pragmas`.
1122
1123 Second, in compilation mode, if you give ``gnatchop`` a file that
1124 starts with configuration pragmas and contains one or more units, then
1125 configuration pragmas are prepended to each of the chopped
1126 files. This behavior provides the required behavior described in the
1127 RM for the actions to be taken on compiling such a file, namely that
1128 the pragmas apply to all units in the compilation, but not to
1129 subsequently compiled units.
1130
1131 Finally, if configuration pragmas appear between units, they are appended
1132 to the previous unit. This results in the previous unit being illegal,
1133 since the compiler does not accept configuration pragmas that follow
1134 a unit. This provides the required RM behavior that forbids configuration
1135 pragmas other than those preceding the first compilation unit of a
1136 compilation.
1137
1138 For most purposes, you will use ``gnatchop`` in default mode. You only
1139 use the compilation mode described above if you need precisely
1140 accurate behavior with respect to compilations and you have files
1141 that contain multiple units and configuration pragmas. In this
1142 circumstance, the use of ``gnatchop`` with the compilation mode
1143 switch provides the required behavior. This is the mode
1144 in which GNAT processes the ACVC tests.
1145
1146
1147 .. _Command_Line_for_gnatchop:
1148
1149 Command Line for ``gnatchop``
1150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1151
1152 You call ``gnatchop`` as follows:
1153
1154 .. code-block:: sh
1155
1156 $ gnatchop switches file_name [file_name ...]
1157 [directory]
1158
1159 The only required argument is the file name of the file to be chopped.
1160 There are no restrictions on the form of this file name. The file itself
1161 contains one or more Ada units, in normal GNAT format, concatenated
1162 together. As shown, more than one file may be presented to be chopped.
1163
1164 When run in default mode, ``gnatchop`` generates one output file in
1165 the current directory for each unit in each of the files.
1166
1167 ``directory``, if specified, gives the name of the directory to which
1168 the output files will be written. If you don't specify it, all files are
1169 written to the current directory.
1170
1171 For example, given a
1172 file called :file:`hellofiles` containing
1173
1174 .. code-block:: ada
1175
1176 procedure Hello;
1177
1178 with Ada.Text_IO; use Ada.Text_IO;
1179 procedure Hello is
1180 begin
1181 Put_Line ("Hello");
1182 end Hello;
1183
1184 the command
1185
1186 .. code-block:: sh
1187
1188 $ gnatchop hellofiles
1189
1190 generates two files in the current directory, one called
1191 :file:`hello.ads` containing the single line that is the procedure spec,
1192 and the other called :file:`hello.adb` containing the remaining text. The
1193 original file is not affected. You can compile these generated files in
1194 the normal manner.
1195
1196 When you invoke ``gnatchop`` on a file that is empty or contains only
1197 empty lines and/or comments, ``gnatchop`` will complete normally, but
1198 won't produce any new file.
1199
1200 For example, given a
1201 file called :file:`toto.txt` containing
1202
1203 .. code-block:: ada
1204
1205 -- Just a comment
1206
1207 the command
1208
1209 .. code-block:: sh
1210
1211 $ gnatchop toto.txt
1212
1213 will not produce any new file and will result in the following warnings::
1214
1215 toto.txt:1:01: warning: empty file, contains no compilation units
1216 no compilation units found
1217 no source files written
1218
1219
1220 .. _Switches_for_gnatchop:
1221
1222 Switches for ``gnatchop``
1223 ^^^^^^^^^^^^^^^^^^^^^^^^^
1224
1225 ``gnatchop`` recognizes the following switches:
1226
1227
1228 .. index:: --version (gnatchop)
1229
1230 :switch:`--version`
1231 Display copyright and version, then exit, disregarding all other options.
1232
1233 .. index:: --help (gnatchop)
1234
1235 :switch:`--help`
1236 If :switch:`--version` is not present, display usage, then exit, disregarding
1237 all other options.
1238
1239 .. index:: -c (gnatchop)
1240
1241 :switch:`-c`
1242 Causes ``gnatchop`` to operate in compilation mode, in which
1243 configuration pragmas are handled according to strict RM rules. See the
1244 previous section for a full description of this mode.
1245
1246 :switch:`-gnat{xxx}`
1247 This passes the given :switch:`-gnat{xxx}` switch to ``gcc`` which is
1248 used to parse the given file. Not all *xxx* options make sense,
1249 but, for example, the use of :switch:`-gnati2` allows ``gnatchop`` to
1250 process a source file that uses Latin-2 coding for identifiers.
1251
1252 :switch:`-h`
1253 Causes ``gnatchop`` to generate a brief help summary to the standard
1254 output file showing usage information.
1255
1256 .. index:: -k (gnatchop)
1257
1258 :switch:`-k{mm}`
1259
1260 Limit generated file names to the specified number ``mm`` of
1261 characters. This is useful if the resulting set of files is
1262 required to be interoperable with systems which limit the length of
1263 file names. You may not place any space between the :switch:`-k`
1264 and the numeric value. You can omit the numeric value, in which case
1265 ``gnatchop`` will use a default of :switch:`-k8`, suitable for use
1266 with DOS-like file systems. If you don't specify a :switch:`-k` switch,
1267 there is no limit on the length of file names.
1268
1269 .. index:: -p (gnatchop)
1270
1271 :switch:`-p`
1272 Causes the file modification time stamp of the input file to be
1273 preserved and used for the time stamp of the output file(s). You may find this
1274 useful for preserving coherency of time stamps in an environment where
1275 ``gnatchop`` is used as part of a standard build process.
1276
1277 .. index:: -q (gnatchop)
1278
1279 :switch:`-q`
1280 Causes output of informational messages indicating the set of generated
1281 files to be suppressed. Warnings and error messages are unaffected.
1282
1283 .. index:: -r (gnatchop)
1284 .. index:: Source_Reference pragmas
1285
1286 :switch:`-r`
1287 Generate ``Source_Reference`` pragmas. Use this switch if the output
1288 files are regarded as temporary and development is to be done from
1289 of the original unchopped file. This switch causes
1290 ``Source_Reference`` pragmas to be inserted into each of the
1291 generated files to refer back to the original file name and line number.
1292 The result is that all error messages refer back to the original
1293 unchopped file.
1294 In addition, the debugging information placed into the object file (when
1295 the :switch:`-g` switch of ``gcc`` or ``gnatmake`` is
1296 specified)
1297 also refers back to this original file so that tools like profilers and
1298 debuggers will give information in terms of the original unchopped file.
1299
1300 If the original file to be chopped itself contains
1301 a ``Source_Reference``
1302 pragma referencing a third file, ``gnatchop`` respects these
1303 pragmas and the generated ``Source_Reference`` pragmas
1304 in the chopped file refer to the original file, with appropriate
1305 line numbers. This is particularly useful when ``gnatchop``
1306 is used in conjunction with ``gnatprep`` to compile files that
1307 contain preprocessing statements and multiple units.
1308
1309 .. index:: -v (gnatchop)
1310
1311 :switch:`-v`
1312 Causes ``gnatchop`` to operate in verbose mode. It outputs the
1313 version number and copyright notice as well as exact copies of the
1314 commands spawned to obtain the information needed to control chopping.
1315
1316 .. index:: -w (gnatchop)
1317
1318 :switch:`-w`
1319 Overwrite existing file names. Normally, ``gnatchop`` treats it as a
1320 fatal error if there's already a file with the same name as a
1321 file it would otherwise output. This can happen either if you've previously
1322 chopped that file or if the files to be
1323 chopped contain duplicated units. This switch bypasses this
1324 check and causes all but the last instance of such duplicated
1325 units to be skipped.
1326
1327 .. index:: --GCC= (gnatchop)
1328
1329 :switch:`--GCC={xxxx}`
1330 Specify the path of the GNAT parser to be used. When this switch is used,
1331 ``gnatchop`` makes no attempt to add a prefix to the GNAT parser executable,
1332 so it must include the full pathname.
1333
1334
1335 .. _Examples_of_gnatchop_Usage:
1336
1337 Examples of ``gnatchop`` Usage
1338 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1339
1340 .. code-block:: sh
1341
1342 $ gnatchop -w hello_s.ada prerelease/files
1343
1344 Chops the source file :file:`hello_s.ada`. The output files are
1345 placed in the directory :file:`prerelease/files`,
1346 overwriting any
1347 files with matching names in that directory (no files in the current
1348 directory are modified).
1349
1350 .. code-block:: sh
1351
1352 $ gnatchop archive
1353
1354 Chops the source file :file:`archive`
1355 into the current directory. One
1356 useful application of ``gnatchop`` is in sending sets of sources
1357 around, for example in email messages. The required sources are simply
1358 concatenated (for example, using a Unix ``cat``
1359 command) and
1360 ``gnatchop`` is used at the other end to reconstitute the original
1361 files.
1362
1363 .. code-block:: sh
1364
1365 $ gnatchop file1 file2 file3 direc
1366
1367 Chops all units in files :file:`file1`, :file:`file2`, :file:`file3`,
1368 placing the resulting files in the directory :file:`direc`. Note that
1369 if any units occur more than once anywhere within this set of files,
1370 ``gnatchop`` generates an error message, and doesn't write any
1371 files. To override this check, use the :switch:`-w` switch, in which
1372 case the last occurrence in the last file will be the one that is
1373 output and ``gnatchop`` will skip earlier duplicate occurrences for
1374 the same unit.
1375
1376 .. _Configuration_Pragmas:
1377
1378 Configuration Pragmas
1379 =====================
1380
1381 .. index:: Configuration pragmas
1382
1383 .. index:: Pragmas, configuration
1384
1385 Configuration pragmas supported by GNAT consist of those pragmas described as
1386 such in the Ada Reference Manual and the
1387 implementation-dependent pragmas that are configuration pragmas.
1388 See the ``Implementation_Defined_Pragmas`` chapter in the
1389 :title:`GNAT_Reference_Manual` for details on these
1390 additional GNAT-specific configuration pragmas.
1391 Most notably, the pragma ``Source_File_Name``, which allows
1392 specifying non-default names for source files, is a configuration
1393 pragma. The following is a complete list of configuration pragmas
1394 recognized by GNAT::
1395
1396 Ada_83
1397 Ada_95
1398 Ada_05
1399 Ada_2005
1400 Ada_12
1401 Ada_2012
1402 Ada_2022
1403 Aggregate_Individually_Assign
1404 Allow_Integer_Address
1405 Annotate
1406 Assertion_Policy
1407 Assume_No_Invalid_Values
1408 C_Pass_By_Copy
1409 Check_Float_Overflow
1410 Check_Name
1411 Check_Policy
1412 Component_Alignment
1413 Convention_Identifier
1414 Debug_Policy
1415 Default_Scalar_Storage_Order
1416 Default_Storage_Pool
1417 Detect_Blocking
1418 Disable_Atomic_Synchronization
1419 Discard_Names
1420 Elaboration_Checks
1421 Eliminate
1422 Enable_Atomic_Synchronization
1423 Extend_System
1424 Extensions_Allowed
1425 External_Name_Casing
1426 Fast_Math
1427 Favor_Top_Level
1428 Ignore_Pragma
1429 Implicit_Packing
1430 Initialize_Scalars
1431 Interrupt_State
1432 Interrupts_System_By_Default
1433 License
1434 Locking_Policy
1435 No_Component_Reordering
1436 No_Heap_Finalization
1437 No_Strict_Aliasing
1438 Normalize_Scalars
1439 Optimize_Alignment
1440 Overflow_Mode
1441 Overriding_Renamings
1442 Partition_Elaboration_Policy
1443 Persistent_BSS
1444 Prefix_Exception_Messages
1445 Priority_Specific_Dispatching
1446 Profile
1447 Profile_Warnings
1448 Queuing_Policy
1449 Rename_Pragma
1450 Restrictions
1451 Restriction_Warnings
1452 Reviewable
1453 Short_Circuit_And_Or
1454 Source_File_Name
1455 Source_File_Name_Project
1456 SPARK_Mode
1457 Style_Checks
1458 Suppress
1459 Suppress_Exception_Locations
1460 Task_Dispatching_Policy
1461 Unevaluated_Use_Of_Old
1462 Unsuppress
1463 Use_VADS_Size
1464 User_Aspect_Definition
1465 Validity_Checks
1466 Warning_As_Error
1467 Warnings
1468 Wide_Character_Encoding
1469
1470
1471 .. _Handling_of_Configuration_Pragmas:
1472
1473 Handling of Configuration Pragmas
1474 ---------------------------------
1475
1476 You can place configuration pragmas either appear at the start of a compilation
1477 unit or in a configuration pragma file that applies to
1478 all compilations performed in a given compilation environment.
1479
1480 GNAT includes the ``gnatchop`` utility to provide an automatic
1481 way to handle configuration pragmas that follows the semantics for
1482 compilations (that is, files with multiple units) described in the RM.
1483 See :ref:`Operating_gnatchop_in_Compilation_Mode` for details.
1484 However, for most purposes, you will find it more convenient to edit the
1485 :file:`gnat.adc` file that contains configuration pragmas directly,
1486 as described in the following section.
1487
1488 In the case of ``Restrictions`` pragmas appearing as configuration
1489 pragmas in individual compilation units, the exact handling depends on
1490 the type of restriction.
1491
1492 Restrictions that require partition-wide consistency (like
1493 ``No_Tasking``) are
1494 recognized wherever they appear
1495 and can be freely inherited, e.g. from a |withed| unit to the |withing|
1496 unit. This makes sense since the binder will always insist on seeing
1497 consistent us, so any unit not conforming to any restrictions
1498 anywhere in the partition will be rejected and it's better for you to find
1499 that out at compile time rather than bind time.
1500
1501 For restrictions that do not require partition-wide consistency, e.g.
1502 ``SPARK`` or ``No_Implementation_Attributes``, the restriction
1503 normally applies only to the unit in which the pragma appears, and not
1504 to any other units.
1505
1506 The exception is ``No_Elaboration_Code``, which always applies to the
1507 entire object file from a compilation, i.e. to the body, spec, and all
1508 subunits. You can apply this restriction in a configuration pragma
1509 file or you can ace it in the body and/or the spec (in either case it
1510 applies to all the relevant units). You can place it on a subunit only if
1511 you have previously placed it in the body of spec.
1512
1513
1514 .. _The_Configuration_Pragmas_Files:
1515
1516 The Configuration Pragmas Files
1517 -------------------------------
1518
1519 .. index:: gnat.adc
1520
1521 In GNAT, a compilation environment is defined by the current directory
1522 at the time that a compile command is given. This current directory is
1523 searched for a file whose name is :file:`gnat.adc`. If this file is
1524 present, it is expected to contain one or more configuration pragmas
1525 that will be applied to the current compilation. However, if you
1526 specify the switch :switch:`-gnatA`, GNAT ignores
1527 :file:`gnat.adc`. When used, GNAT adds :file:`gnat.adc` to the
1528 dependencies so that if :file:`gnat.adc` is modified later, the source
1529 will be recompiled on a future invocation of ``gnatmake``.
1530
1531 You can add
1532 configuration pragmas into the :file:`gnat.adc` file
1533 either by running ``gnatchop`` on a source file consisting only of
1534 configuration pragmas or, more conveniently, by directly editing the
1535 :file:`gnat.adc` file, which is a standard format source file.
1536
1537 Besides :file:`gnat.adc`, you may apply additional files containing
1538 configuration pragmas to the current compilation using the
1539 :switch:`-gnatec={path}` switch, where ``path`` must designate an
1540 existing file that contains only configuration pragmas. These
1541 configuration pragmas are in addition to those found in
1542 :file:`gnat.adc` (provided :file:`gnat.adc` is present and you do not
1543 use switch :switch:`-gnatA`).
1544 You can specify multiple :switch:`-gnatec=` switches.
1545
1546 GNAT will add files containing configuration pragmas specified with switches
1547 :switch:`-gnatec=` to the dependencies, unless they are
1548 temporary files. A file is considered temporary if its name ends in
1549 :file:`.tmp` or :file:`.TMP`. Certain tools follow this naming
1550 convention because they pass information to ``gcc`` via
1551 temporary files that are immediately deleted; it doesn't make sense to
1552 depend on a file that no longer exists. Such tools include
1553 ``gprbuild``, ``gnatmake``, and ``gnatcheck``.
1554
1555 By default, configuration pragma files are stored by their absolute
1556 paths in ALI files. You can use the :switch:`-gnateb` switch to
1557 request they be stored instead by just their basename.
1558
1559 If you are using project file, they provide a separate mechanism using
1560 project attributes.
1561
1562 .. --Comment
1563 See :ref:`Specifying_Configuration_Pragmas` for more details.
1564
1565
1566 .. _Generating_Object_Files:
1567
1568 Generating Object Files
1569 =======================
1570
1571 An Ada program consists of a set of source files and the first step in
1572 compiling the program is generating the corresponding object files.
1573 You generate these by compiling a subset of these source files.
1574 The files you need to compile are the following:
1575
1576 * If a package spec has no body, compile the package spec to produce the
1577 object file for the package.
1578
1579 * If a package has both a spec and a body, compile the body to produce
1580 the object file for the package. You need not compile the source
1581 file for the package spec in this case because there's only one
1582 object file, which contains the code for both the spec and body of
1583 the package.
1584
1585 * For a subprogram, compile the subprogram body to produce the object
1586 file for the subprogram. You need not compile the spec, if such a file is
1587 present.
1588
1589 .. index:: Subunits
1590
1591 * In the case of subunits, only compile the parent unit. GNAT
1592 generates a single object file for the entire subunit tree, which
1593 includes all the subunits.
1594
1595 * Compile child units independently of their parent units (though, of
1596 course, the spec of all the ancestor unit must be present in order
1597 to compile a child unit).
1598
1599 .. index:: Generics
1600
1601 * Compile generic units in the same manner as any other units. The
1602 object files in this case are small dummy files that contain, at
1603 most, the flag used for elaboration checking. This is because GNAT
1604 always handles generic instantiation by means of macro
1605 expansion. However, you still must compile generic units
1606 for dependency checking and elaboration purposes.
1607
1608 The preceding rules describe the set of files that must be compiled to
1609 generate all the object files for a program. See the following section on dependencies for more details on computing that set of files.
1610 Each object file has the same
1611 name as the corresponding source file, except that the extension is
1612 :file:`.o`, as usual.
1613
1614 You may wish to compile other files for the purpose of checking their
1615 syntactic and semantic correctness. For example, in the case where a
1616 package has a separate spec and body, you would not normally compile the
1617 spec. However, it is convenient in practice to compile the spec to make
1618 sure it is error-free before compiling clients of this spec because such
1619 compilations will fail if there is an error in the spec.
1620
1621 GNAT provides an option for compiling such files purely for the
1622 purposes of checking correctness; such compilations are not required as
1623 part of the process of building a program. To compile a file in this
1624 checking mode, use the :switch:`-gnatc` switch.
1625
1626 .. _Source_Dependencies:
1627
1628 Source Dependencies
1629 ===================
1630
1631 Each object file obviously depends on at least the source file which
1632 is compiled to produce it. Here we are using "depends" in the sense of
1633 a typical ``make`` utility; in other words, an object file depends on
1634 a source file if changes to the source file require the object file to
1635 be recompiled. In addition to this basic dependency, a given object
1636 may depend on additional source files as follows:
1637
1638 * If a file being compiled |withs| a unit ``X``, the object file
1639 depends on the file containing the spec of unit ``X``. This includes
1640 files that are |withed| implicitly either because they are parents
1641 of |withed| child units or are run-time units required by the
1642 language constructs used in a particular unit.
1643
1644 * If a file being compiled instantiates a library level generic unit, the
1645 object file depends on both the spec and body files for this generic
1646 unit.
1647
1648 * If a file being compiled instantiates a generic unit defined within a
1649 package, the object file depends on the body file for the package as
1650 well as the spec file.
1651
1652 .. index:: Inline
1653 .. index:: -gnatn switch
1654
1655 * If a file being compiled contains a call to a subprogram for which
1656 pragma ``Inline`` applies and you have activated inlining with the
1657 :switch:`-gnatn` switch, the object file depends on the file containing the
1658 body of this subprogram as well as on the file containing the spec. Note
1659 that for inlining to actually occur as a result of the use of this switch,
1660 you must compile in optimizing mode.
1661
1662 .. index:: -gnatN switch
1663
1664 The use of :switch:`-gnatN` activates inlining optimization
1665 that is performed by the front end of the compiler. This inlining does
1666 not require that the code generation be optimized. Like :switch:`-gnatn`,
1667 the use of this switch generates additional dependencies.
1668
1669 When using a ``gcc`` or LLVM based back end, the use of
1670 :switch:`-gnatN` is deprecated and the use of :switch:`-gnatn` is preferred.
1671 Historically front end inlining was more extensive than back end
1672 inlining, but that is no longer the case.
1673
1674 * If an object file :file:`O` depends on the proper body of a subunit through
1675 inlining or instantiation, it depends on the parent unit of the subunit.
1676 This means that any modification of the parent unit or one of its subunits
1677 affects the compilation of :file:`O`.
1678
1679 * The object file for a parent unit depends on all its subunit body files.
1680
1681 * The previous two rules means that, for purposes of computing
1682 dependencies and recompilation, a body and all its subunits are
1683 treated as an indivisible whole.
1684
1685 These rules are applied transitively: if unit ``A`` |withs|
1686 unit ``B``, whose elaboration calls an inlined procedure in package
1687 ``C``, the object file for unit ``A`` depends on the body of
1688 ``C``, in file :file:`c.adb`.
1689
1690 The set of dependent files described by these rules includes all the
1691 files on which the unit is semantically dependent, as dictated by the
1692 Ada language standard. However, it is a superset of what the
1693 standard describes, because it includes generic, inline, and subunit
1694 dependencies.
1695
1696 An object file must be recreated by recompiling the corresponding
1697 source file if any of the source files on which it depends are
1698 modified. For example, if the ``make`` utility is used to control
1699 compilation, the rule for an Ada object file must mention all the
1700 source files on which the object file depends, according to the
1701 above definition. Invoking ``gnatmake`` will cause it to determine
1702 the necessary recompilations.
1703
1704 .. _The_Ada_Library_Information_Files:
1705
1706 The Ada Library Information Files
1707 =================================
1708
1709 .. index:: Ada Library Information files
1710
1711 .. index:: ALI files
1712
1713 Each compilation actually generates two output files. The first of these
1714 is the actual object file that has a :file:`.o` extension. The second is a
1715 text file containing full dependency information. It has the same
1716 name as the source file, but an :file:`.ali` extension.
1717 This file is known as the Ada Library Information (:file:`ALI`) file.
1718 The following information is contained in that file:
1719
1720 * Version information (indicates which version of GNAT was used to compile
1721 the unit(s) in question)
1722
1723 * Main program information (including priority and time slice settings,
1724 as well as the wide character encoding used during compilation).
1725
1726 * List of arguments used in the compilation command
1727
1728 * Attributes of the unit, including the configuration pragmas used, an
1729 indication of whether the compilation was successful, and the exception
1730 model used.
1731
1732 * A list of relevant restrictions applying to the unit (used for consistency
1733 checking).
1734
1735 * Categorization information (e.g., use of pragma ``Pure``).
1736
1737 * Information on all |withed| units, including presence of
1738 ``Elaborate`` or ``Elaborate_All`` pragmas.
1739
1740 * Information from any ``Linker_Options`` pragmas used in the unit
1741
1742 * Information on the use of ``Body_Version`` or ``Version``
1743 attributes in the unit.
1744
1745 * Dependency information. This is a list of files, together with
1746 time stamp and checksum information. These are files on which
1747 the unit depends in the sense that the modification of any of
1748 these units requires the recompilation of the unit in question.
1749
1750 * Cross-reference data. Contains information on all entities referenced
1751 in the unit. Used by some tools to provide cross-reference information.
1752
1753 For a full detailed description of the format of the :file:`ALI` file,
1754 see the source of the spec of unit ``Lib.Writ``, contained in file
1755 :file:`lib-writ.ads` in the GNAT compiler sources.
1756
1757
1758 .. _Binding_an_Ada_Program:
1759
1760 Binding an Ada Program
1761 ======================
1762
1763 When using languages such as C and C++, once the source files have been
1764 compiled the only remaining step in building an executable program
1765 is linking the object modules together. This means that you can
1766 link an inconsistent version of a program, in which two units have
1767 included different versions of the same header.
1768
1769 The rules of Ada do not permit such an inconsistent program to be built.
1770 For example, if two clients have different versions of the same package,
1771 it is illegal to build a program containing these two clients.
1772 These rules are enforced by the GNAT binder, which also determines an
1773 elaboration order consistent with the Ada rules.
1774
1775 The GNAT binder is run after all the object files for a program have
1776 been created. It is given the name of the main program unit and from
1777 this determines the set of units required by the program by reading the
1778 corresponding ALI files. It generates error messages if the program is
1779 inconsistent or if no valid order of elaboration exists.
1780
1781 If no errors are detected, the binder produces a main program in Ada
1782 that contains calls to the elaboration procedures of those
1783 compilation unit that require them, followed by
1784 a call to the main program. This Ada program is compiled to generate the
1785 object file for the main program. The name of
1786 the Ada file is :file:`b~xxx.adb` (with the corresponding spec
1787 :file:`b~xxx.ads`) where ``xxx`` is the name of the
1788 main program unit.
1789
1790 Finally, the linker is used to build the resulting executable program,
1791 using the object from the main program from the bind step as well as the
1792 object files for the Ada units of the program.
1793
1794
1795 .. _GNAT_and_Libraries:
1796
1797 GNAT and Libraries
1798 ==================
1799
1800 .. index:: Library building and referencing
1801
1802 This section describes how to build and use libraries with GNAT and
1803 how to recompile the GNAT run-time library. You should be familiar with the
1804 Project Manager facility (see the *GNAT_Project_Manager* chapter of the
1805 :title:`GPRbuild User's Guide`) before reading this chapter.
1806
1807 .. _Introduction_to_Libraries_in_GNAT:
1808
1809 Introduction to Libraries in GNAT
1810 ---------------------------------
1811
1812 A library is, conceptually, a collection of objects which does not have its
1813 own main thread of execution but instead provides certain services to the
1814 applications that use it. A library can be either statically linked with the
1815 application, in which case its code is directly included in the application,
1816 or, on platforms that support it, be dynamically linked, in which case
1817 its code is shared by all applications making use of this library.
1818
1819 GNAT supports both types of libraries.
1820 In the static case, you can provide the compiled code in different ways. The
1821 simplest approach is to directly provide the set of objects resulting from
1822 compilation of the library source files. Alternatively, you can group the
1823 objects into an archive using whatever commands are provided by the operating
1824 system.
1825
1826 In the GNAT environment, a library has these components:
1827
1828 * Source files,
1829
1830 * :file:`ALI` files (see :ref:`The_Ada_Library_Information_Files`), and
1831
1832 * Object files, an archive, or a shared library.
1833
1834 A GNAT library may expose all its source files, which is useful for
1835 documentation purposes. Alternatively, it may expose only the units needed by
1836 an external user to make use of the library, in other words, the specs
1837 reflecting the library services along with all the units needed to compile
1838 those specs, which can include generic bodies or any body implementing an
1839 inlined routine. In the case of *stand-alone libraries* those exposed
1840 units are called *interface units* (:ref:`Stand-alone_Ada_Libraries`).
1841
1842 All compilation units comprising an application, including those in a library,
1843 need to be elaborated in an order partially defined by Ada's semantics. GNAT
1844 computes the elaboration order from the :file:`ALI` files and this is why they
1845 constitute a mandatory part of GNAT libraries.
1846 *Stand-alone libraries* are the exception to this rule because a specific
1847 library elaboration routine is produced independently of the application(s)
1848 using the library.
1849
1850 .. _General_Ada_Libraries:
1851
1852 General Ada Libraries
1853 ---------------------
1854
1855
1856 .. _Building_a_library:
1857
1858 Building a library
1859 ^^^^^^^^^^^^^^^^^^
1860
1861 The easiest way to build a library is to use the Project Manager,
1862 which supports a special type of project called a *Library Project*
1863 (see the *Library Projects* section in the *GNAT Project Manager*
1864 chapter of the :title:`GPRbuild User's Guide`).
1865
1866 A project is considered a library project when two project-level
1867 attributes are defined in it: ``Library_Name`` and ``Library_Dir``. In
1868 order to control different aspects of library configuration, you can
1869 specify additional optional project-level attributes:
1870
1871 * ``Library_Kind``
1872 This attribute controls whether the library is to be static or dynamic
1873
1874 * ``Library_Version``
1875 This attribute specifies the library version. Its value is used
1876 during dynamic linking of shared libraries to determine if the currently
1877 installed versions of the binaries are compatible.
1878
1879 * ``Library_Options``
1880
1881 * ``Library_GCC``
1882 These attributes specify additional low-level options to be used during
1883 library generation and the commands used to generate the
1884 library.
1885
1886 The GNAT Project Manager takes complete care of the library maintenance task,
1887 including recompilation of the source files for which objects do not exist
1888 or are not up to date, assembly of the library archive, and installation of
1889 the library (i.e., copying associated source, object and :file:`ALI` files
1890 to the specified location).
1891
1892 Here's a simple library project file:
1893
1894 .. code-block:: gpr
1895
1896 project My_Lib is
1897 for Source_Dirs use ("src1", "src2");
1898 for Object_Dir use "obj";
1899 for Library_Name use "mylib";
1900 for Library_Dir use "lib";
1901 for Library_Kind use "dynamic";
1902 end My_lib;
1903
1904 and the compilation command to build and install the library:
1905
1906 .. code-block:: sh
1907
1908 $ gnatmake -Pmy_lib
1909
1910 It's complex to manually perform all the steps required to
1911 produce a library, so we recommend you use the GNAT Project Manager
1912 for this task. In case this is not desired, we discuss the necessary
1913 steps below.
1914
1915 There are various possibilities for compiling the units that make up
1916 the library: for example with a :file:`Makefile`
1917 (:ref:`Using_the_GNU_make_Utility`) or with a conventional script. For
1918 simple libraries, you can also create a dummy main program
1919 that depends upon all the packages that comprise the interface of the
1920 library. You can then pass this dummy main program to ``gnatmake``,
1921 which will ensure all necessary objects are built.
1922
1923 After the above has been accomplished, you should follow the standard procedure
1924 of the underlying operating system to produce the static or shared library.
1925
1926 Here's an example of such a dummy program:
1927
1928 .. code-block:: ada
1929
1930 with My_Lib.Service1;
1931 with My_Lib.Service2;
1932 with My_Lib.Service3;
1933 procedure My_Lib_Dummy is
1934 begin
1935 null;
1936 end;
1937
1938 Here are the generic commands that will build an archive or a shared library.
1939
1940 .. code-block:: sh
1941
1942 # compiling the library
1943 $ gnatmake -c my_lib_dummy.adb
1944
1945 # we don't need the dummy object itself
1946 $ rm my_lib_dummy.o my_lib_dummy.ali
1947
1948 # create an archive with the remaining objects
1949 $ ar rc libmy_lib.a *.o
1950 # some systems may require "ranlib" to be run as well
1951
1952 # or create a shared library
1953 $ gcc -shared -o libmy_lib.so *.o
1954 # some systems may require the code to have been compiled with -fPIC
1955
1956 # remove the object files that are now in the library
1957 $ rm *.o
1958
1959 # Make the ALI files read-only so that gnatmake will not try to
1960 # regenerate the objects that are in the library
1961 $ chmod -w *.ali
1962
1963 Please note that the library must have a name of the form :file:`lib{xxx}.a`
1964 or :file:`lib{xxx}.so` (or :file:`lib{xxx}.dll` on Windows) in order to
1965 be accessed by the :switch:`-l{xxx}` switch at link time.
1966
1967 .. _Installing_a_library:
1968
1969 Installing a library
1970 ^^^^^^^^^^^^^^^^^^^^
1971
1972 .. index:: ADA_PROJECT_PATH
1973 .. index:: GPR_PROJECT_PATH
1974
1975 If you use project files, library installation is part of the library build
1976 process (see the *Installing a Library with Project Files* section of the
1977 *GNAT Project Manager* chapter of the :title:`GPRbuild User's Guide`).
1978
1979 When you're not able to use project files for some reason, you can
1980 also install the library so that the sources needed to use the library
1981 are on the Ada source path and the ALI files & libraries be on the Ada
1982 Object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`),
1983 but we don't recommend doing this. Alternatively, the system
1984 administrator can place general-purpose libraries in the default
1985 compiler paths, by specifying the libraries' location in the
1986 configuration files :file:`ada_source_path` and
1987 :file:`ada_object_path`. These configuration files must be located in
1988 the GNAT installation tree at the same place as the ``gcc`` spec
1989 file. The location of the ``gcc`` spec file can be determined as follows:
1990
1991 .. code-block:: sh
1992
1993 $ gcc -v
1994
1995
1996 The configuration files mentioned above have a simple format: each line
1997 must contain one unique directory name.
1998 Those names are added to the corresponding path
1999 in their order of appearance in the file. The names can be either absolute
2000 or relative; in the latter case, they are relative to where theses files
2001 are located.
2002
2003 The files :file:`ada_source_path` and :file:`ada_object_path` might not be
2004 present in a
2005 GNAT installation, in which case, GNAT looks for its run-time library in
2006 the directories :file:`adainclude` (for the sources) and :file:`adalib` (for the
2007 objects and :file:`ALI` files). When the files exist, the compiler does not
2008 look in :file:`adainclude` and :file:`adalib`, and thus the
2009 :file:`ada_source_path` file
2010 must contain the location for the GNAT run-time sources (which can simply
2011 be :file:`adainclude`). In the same way, the :file:`ada_object_path` file must
2012 contain the location for the GNAT run-time objects (which can simply
2013 be :file:`adalib`).
2014
2015 You can also specify a new default path to the run-time library at
2016 compilation time with the :switch:`--RTS=rts-path` switch. You can
2017 thus choose the run-time library you want your program to be
2018 compiled with. This switch is recognized by ``gcc``, ``gnatmake``,
2019 ``gnatbind``, ``gnatls``, and all project aware tools.
2020
2021 You can install a library before or after the standard GNAT library by
2022 selecting the ordering the lines in the configuration files. In
2023 general, a library must be installed before the GNAT library if it
2024 redefines any part of it.
2025
2026 .. _Using_a_library:
2027
2028 Using a library
2029 ^^^^^^^^^^^^^^^
2030
2031 Once again, the project facility greatly simplifies the use of
2032 libraries. In this context, using a library is just a matter of adding a
2033 |with| clause in your project. For example, to make use of the
2034 library ``My_Lib`` shown in examples in earlier sections, you can
2035 write:
2036
2037 .. code-block:: gpr
2038
2039 with "my_lib";
2040 project My_Proj is
2041 ...
2042 end My_Proj;
2043
2044 Even if you have a third-party, non-Ada library, you can still use GNAT's
2045 Project Manager facility to provide a wrapper for it. For example, the
2046 following project, when |withed| by your main project, will link with the
2047 third-party library :file:`liba.a`:
2048
2049 .. code-block:: gpr
2050
2051 project Liba is
2052 for Externally_Built use "true";
2053 for Source_Files use ();
2054 for Library_Dir use "lib";
2055 for Library_Name use "a";
2056 for Library_Kind use "static";
2057 end Liba;
2058
2059 This is an alternative to the use of ``pragma Linker_Options``. It is
2060 especially interesting in the context of systems with several interdependent
2061 static libraries where finding a proper linker order is not easy and best be
2062 left to the tools having visibility over project dependence information.
2063
2064 In order to use an Ada library manually, you need to make sure that this
2065 library is on both your source and object path
2066 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`
2067 and :ref:`Search_Paths_for_gnatbind`). Furthermore, when the objects are grouped
2068 in an archive or a shared library, you need to specify the desired
2069 library at link time.
2070
2071 For example, you can use the library :file:`mylib` installed in
2072 :file:`/dir/my_lib_src` and :file:`/dir/my_lib_obj` with the following commands:
2073
2074 .. code-block:: sh
2075
2076 $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\
2077 -largs -lmy_lib
2078
2079 This can be expressed more simply:
2080
2081 .. code-block:: sh
2082
2083 $ gnatmake my_appl
2084
2085 when the following conditions are met:
2086
2087 * :file:`/dir/my_lib_src` has been added by the user to the environment
2088 variable :envvar:`ADA_INCLUDE_PATH`, or by the administrator to the file
2089 :file:`ada_source_path`
2090
2091 * :file:`/dir/my_lib_obj` has been added by the user to the environment
2092 variable :envvar:`ADA_OBJECTS_PATH`, or by the administrator to the file
2093 :file:`ada_object_path`
2094
2095 * a pragma ``Linker_Options`` has been added to one of the sources.
2096 For example:
2097
2098 .. code-block:: ada
2099
2100 pragma Linker_Options ("-lmy_lib");
2101
2102 Note that you may also load a library dynamically at
2103 run time given its filename, as illustrated in the GNAT :file:`plugins` example
2104 in the directory :file:`share/examples/gnat/plugins` within the GNAT
2105 install area.
2106
2107 .. _Stand-alone_Ada_Libraries:
2108
2109 Stand-alone Ada Libraries
2110 -------------------------
2111
2112 .. index:: ! Stand-alone libraries
2113
2114 .. _Introduction_to_Stand-alone_Libraries:
2115
2116 Introduction to Stand-alone Libraries
2117 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2118
2119 A Stand-alone Library (abbreviated 'SAL') is a library that contains
2120 the necessary code to elaborate the Ada units that are included in the
2121 library. In contrast with an ordinary library, which consists of all
2122 sources, objects and :file:`ALI` files of the library, a SAL may
2123 specify a restricted subset of compilation units to serve as a library
2124 interface. In this case, the fully self-sufficient set of files will
2125 normally consist of an objects archive, the sources of interface
2126 units' specs, and the :file:`ALI` files of interface units. If an
2127 interface spec contains a generic unit or an inlined subprogram, you
2128 must also provide the body's source; if the units that must be
2129 provided in the source form depend on other units, you must also
2130 provide the source and :file:`ALI` files of those units.
2131
2132 The main purpose of a SAL is to minimize the recompilation overhead of client
2133 applications when a new version of the library is installed. Specifically,
2134 if the interface sources have not changed, client applications don't need to
2135 be recompiled. If, furthermore, a SAL is provided in the shared form and its
2136 version, controlled by ``Library_Version`` attribute, is not changed,
2137 the clients also do not need to be relinked.
2138
2139 SALs also allow the library providers to minimize the amount of library source
2140 text exposed to the clients. Such 'information hiding' might be useful or
2141 necessary for various reasons.
2142
2143 Stand-alone libraries are also well suited to be used in an executable whose
2144 main routine is not written in Ada.
2145
2146 .. _Building_a_Stand-alone_Library:
2147
2148 Building a Stand-alone Library
2149 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2150
2151 GNAT's Project facility provides a simple way of building and installing
2152 stand-alone libraries; see the *Stand-alone Library Projects* section
2153 in the *GNAT Project Manager* chapter of the :title:`GPRbuild User's Guide`.
2154 To be a Stand-alone Library Project, in addition to the two attributes
2155 that make a project a Library Project (``Library_Name`` and
2156 ``Library_Dir``; see the *Library Projects* section in the
2157 *GNAT Project Manager* chapter of the *GPRbuild User's Guide*),
2158 you must define the attribute ``Library_Interface``. For example:
2159
2160 .. code-block:: gpr
2161
2162 for Library_Dir use "lib_dir";
2163 for Library_Name use "dummy";
2164 for Library_Interface use ("int1", "int1.child");
2165
2166 Attribute ``Library_Interface`` has a non-empty string list value,
2167 each string in the list designating a unit contained in an immediate source
2168 of the project file.
2169
2170 When a Stand-alone Library is built, the binder is first invoked to build
2171 a package whose name depends on the library name
2172 (:file:`b~dummy.ads/b` in the example above).
2173 This binder-generated package includes initialization and
2174 finalization procedures whose
2175 names depend on the library name (``dummyinit`` and ``dummyfinal``
2176 in the example
2177 above). The object corresponding to this package is included in the library.
2178
2179 You must ensure timely (e.g., prior to any use of interfaces in the SAL)
2180 calling of these procedures if a static SAL is built, or if a shared SAL
2181 is built
2182 with the project-level attribute ``Library_Auto_Init`` set to
2183 ``"false"``.
2184
2185 For a Stand-Alone Library, only the :file:`ALI` files of the Interface Units
2186 (those that are listed in attribute ``Library_Interface``) are copied to
2187 the Library Directory. As a consequence, only the Interface Units may be
2188 imported from Ada units outside of the library. If other units are imported,
2189 the binding phase will fail.
2190
2191 You can also build an encapsulated library where not only
2192 the code to elaborate and finalize the library is embedded but also
2193 ensure that the library is linked only against static
2194 libraries. That means that an encapsulated library only depends on system
2195 libraries: all other code, including the GNAT runtime, is embedded. To
2196 build an encapsulated library you must set attribute
2197 ``Library_Standalone`` to ``encapsulated``:
2198
2199 .. code-block:: gpr
2200
2201 for Library_Dir use "lib_dir";
2202 for Library_Name use "dummy";
2203 for Library_Kind use "dynamic";
2204 for Library_Interface use ("int1", "int1.child");
2205 for Library_Standalone use "encapsulated";
2206
2207 The default value for this attribute is ``standard`` in which case
2208 a stand-alone library is built.
2209
2210 You may specify the attribute ``Library_Src_Dir`` for a Stand-Alone
2211 Library. ``Library_Src_Dir`` has a single string value. Its value must
2212 be the path (absolute or relative to the project directory) of an
2213 existing directory. This directory cannot be the object directory or
2214 one of the source directories, but it can be the same as the library
2215 directory. The sources of the Interface Units of the library that are
2216 needed by an Ada client of the library are copied to the designated
2217 directory, called the Interface Copy directory, when the library is
2218 built. These sources include the specs of the Interface Units, but
2219 they may also include bodies and subunits when pragmas ``Inline`` or
2220 ``Inline_Always`` are used or when there is a generic unit in the
2221 spec. Before the sources are copied to the Interface Copy directory,
2222 the building process makes an attempt to delete all files in the
2223 Interface Copy directory.
2224
2225 Building stand-alone libraries by hand is somewhat tedious, but for those
2226 occasions when it is necessary here are the steps that you need to perform:
2227
2228 * Compile all library sources.
2229
2230 * Invoke the binder with the switch :switch:`-n` (No Ada main program),
2231 with all the :file:`ALI` files of the interfaces, and
2232 with the switch :switch:`-L` to give specific names to the ``init``
2233 and ``final`` procedures. For example:
2234
2235 .. code-block:: sh
2236
2237 $ gnatbind -n int1.ali int2.ali -Lsal1
2238
2239 * Compile the binder generated file:
2240
2241 .. code-block:: sh
2242
2243 $ gcc -c b~int2.adb
2244
2245 * Link the dynamic library with all the necessary object files,
2246 passing to the linker the names of the ``init`` (and possibly
2247 ``final``) procedures for automatic initialization (and finalization).
2248 You should place the built library in a different directory than
2249 the object files.
2250
2251 * Copy the ``ALI`` files of the interface to the library directory,
2252 add in this copy an indication that it is an interface to a SAL
2253 (i.e., add a word ``SL`` on the line in the :file:`ALI` file that starts
2254 with letter 'P') and make the modified copy of the :file:`ALI` file
2255 read-only.
2256
2257 Using SALs is not different from using other libraries
2258 (see :ref:`Using_a_library`).
2259
2260 .. _Creating_a_Stand-alone_Library_to_be_used_in_a_non-Ada_context:
2261
2262 Creating a Stand-alone Library to be used in a non-Ada context
2263 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2264
2265 It's easy for you to adapt the SAL build procedure discussed above for
2266 use of a SAL in a non-Ada context.
2267
2268 The only extra step required is to ensure that library interface subprograms
2269 are compatible with the main program, by means of ``pragma Export``
2270 or ``pragma Convention``.
2271
2272 Here's an example of simple library interface for use with C main program:
2273
2274 .. code-block:: ada
2275
2276 package My_Package is
2277
2278 procedure Do_Something;
2279 pragma Export (C, Do_Something, "do_something");
2280
2281 procedure Do_Something_Else;
2282 pragma Export (C, Do_Something_Else, "do_something_else");
2283
2284 end My_Package;
2285
2286 On the C side, you must provide a 'foreign' view of the
2287 library interface; remember that it should contain elaboration routines in
2288 addition to interface subprograms.
2289
2290 The example below shows the content of :file:`mylib_interface.h` (note
2291 that there is no rule for the naming of this file, any name can be used)
2292
2293 .. code-block:: c
2294
2295 /* the library elaboration procedure */
2296 extern void mylibinit (void);
2297
2298 /* the library finalization procedure */
2299 extern void mylibfinal (void);
2300
2301 /* the interface exported by the library */
2302 extern void do_something (void);
2303 extern void do_something_else (void);
2304
2305 Libraries built as explained above can be used from any program, provided
2306 the elaboration procedures (named ``mylibinit`` in the previous
2307 example) are called before any library services are used. Any number of
2308 libraries can be called from a single executable as long as the elaboration
2309 procedure of each library is called.
2310
2311 Below is an example of a C program that uses the ``mylib`` library.
2312
2313 .. code-block:: c
2314
2315 #include "mylib_interface.h"
2316
2317 int
2318 main (void)
2319 {
2320 /* First, elaborate the library before using it */
2321 mylibinit ();
2322
2323 /* Main program, using the library exported entities */
2324 do_something ();
2325 do_something_else ();
2326
2327 /* Library finalization at the end of the program */
2328 mylibfinal ();
2329 return 0;
2330 }
2331
2332 Note that invoking any library finalization procedure generated by
2333 ``gnatbind`` shuts down the Ada run-time environment.
2334 Consequently, the
2335 finalization of all Ada libraries must be performed at the end of the program.
2336 No call to these libraries or to the Ada run-time library should be made
2337 after the finalization phase.
2338
2339 Information on limitations of binding Ada code in non-Ada contexts can be
2340 found under :ref:`Binding_with_Non-Ada_Main_Programs`.
2341
2342 Note also that you must take special care with multi-tasking
2343 applications. In that case, the initialization and finalization
2344 routines are not protected against concurrent access. If you need such
2345 requirement, you must ensure it at the application level
2346 using a specific operating system services like a mutex or a
2347 critical-section.
2348
2349 .. _Restrictions_in_Stand-alone_Libraries:
2350
2351 Restrictions in Stand-alone Libraries
2352 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2353
2354 You should use the pragmas listed below with caution inside libraries,
2355 since they can create incompatibilities with other Ada libraries:
2356
2357 * pragma ``Locking_Policy``
2358 * pragma ``Partition_Elaboration_Policy``
2359 * pragma ``Queuing_Policy``
2360 * pragma ``Task_Dispatching_Policy``
2361 * pragma ``Unreserve_All_Interrupts``
2362
2363 When using a library that contains such pragmas, the user of the
2364 library must ensure that all libraries use the same pragmas with the
2365 same values. Otherwise, ``Program_Error`` will be raised during the
2366 elaboration of the conflicting libraries. You should document the
2367 usage of these pragmas and its consequences for the user.
2368
2369 Similarly, the traceback in the exception occurrence mechanism should be
2370 enabled or disabled in a consistent manner across all libraries.
2371 Otherwise, ``Program_Error`` will be raised during the elaboration of the
2372 conflicting libraries.
2373
2374 If you use the ``Version`` or ``Body_Version``
2375 attributes inside a library, you need to
2376 perform a ``gnatbind`` step that specifies all :file:`ALI` files in all
2377 libraries so that version identifiers can be properly computed.
2378 In practice these attributes are rarely used, so this is unlikely
2379 to be a consideration.
2380
2381 .. _Rebuilding_the_GNAT_Run-Time_Library:
2382
2383 Rebuilding the GNAT Run-Time Library
2384 ------------------------------------
2385
2386 .. index:: GNAT Run-Time Library, rebuilding
2387 .. index:: Building the GNAT Run-Time Library
2388 .. index:: Rebuilding the GNAT Run-Time Library
2389 .. index:: Run-Time Library, rebuilding
2390
2391 You may need to recompile the GNAT library in various debugging or
2392 experimentation contexts. The GNAT distribution provides a project
2393 file called :file:`libada.gpr` to do that; it can be found in the
2394 directory containing the GNAT library. The location of this directory
2395 depends on the way the GNAT environment has been installed and can be
2396 determined by means of the command:
2397
2398 .. code-block:: sh
2399
2400 $ gnatls -v
2401
2402 The last entry in the source search path usually contains the
2403 GNAT library (the :file:`adainclude` directory).
2404
2405 This project file contains its own documentation and, in particular, the
2406 set of instructions needed to rebuild a new library and to use it.
2407
2408 Note that rebuilding the GNAT Run-Time is only recommended for temporary
2409 experiments or debugging and is not supported for other purposes.
2410
2411 .. index:: ! Conditional compilation
2412
2413 .. _Conditional_Compilation:
2414
2415 Conditional Compilation
2416 =======================
2417
2418 This section presents some guidelines for modeling conditional compilation in Ada and describes the
2419 gnatprep preprocessor utility.
2420
2421 .. index:: ! Conditional compilation
2422
2423 .. _Modeling_Conditional_Compilation_in_Ada:
2424
2425 Modeling Conditional Compilation in Ada
2426 ---------------------------------------
2427
2428 You may want to arrange for a single source program
2429 to serve multiple purposes, where it is compiled in different
2430 ways to achieve these different goals. Some examples of the
2431 need for this feature are
2432
2433 * Adapting a program to a different hardware environment
2434 * Adapting a program to a different target architecture
2435 * Turning debugging features on and off
2436 * Arranging for a program to compile with different compilers
2437
2438 In C, or C++, the typical approach is to use the preprocessor
2439 defined as part of the language. The Ada language does not
2440 contain such a feature. This is not an oversight, but rather a very
2441 deliberate design decision, based on the experience that overuse of
2442 the preprocessing features in C and C++ can result in programs that
2443 are extremely difficult to maintain. For example, if we have ten
2444 switches that can be on or off, this means that there are a thousand
2445 separate programs, any one of which might not even be syntactically
2446 correct, and, even if syntactically correct,
2447 might not work correctly. Testing all combinations can quickly become
2448 impossible.
2449
2450 Nevertheless, the need to tailor programs certainly exists and in
2451 this section we will discuss how this can
2452 be achieved using Ada in general and GNAT in particular.
2453
2454 .. _Use_of_Boolean_Constants:
2455
2456 Use of Boolean Constants
2457 ^^^^^^^^^^^^^^^^^^^^^^^^
2458
2459 In the case where the difference is simply which code
2460 sequence is executed, the cleanest solution is to use Boolean
2461 constants to control which code is executed.
2462
2463 .. code-block:: ada
2464
2465 FP_Initialize_Required : constant Boolean := True;
2466 ...
2467 if FP_Initialize_Required then
2468 ...
2469 end if;
2470
2471 Not only will the code inside the ``if`` statement not be executed if
2472 the constant Boolean is ``False``, but it will also be completely
2473 deleted from the program.
2474 However, the code is only deleted after the ``if`` statement block
2475 has been checked for syntactic and semantic correctness.
2476 (In contrast, with preprocessors the code is deleted before the
2477 compiler ever gets to see it, so it is not checked until the switch
2478 is turned on.)
2479
2480 .. index:: Preprocessors (contrasted with conditional compilation)
2481
2482 Typically the Boolean constants will be in a separate package,
2483 something like:
2484
2485 .. code-block:: ada
2486
2487 package Config is
2488 FP_Initialize_Required : constant Boolean := True;
2489 Reset_Available : constant Boolean := False;
2490 ...
2491 end Config;
2492
2493 You would write the ``Config`` package multiple forms for various targets,
2494 with an appropriate script selecting the version of ``Config`` needed.
2495 Then, any other unit requiring conditional compilation can do a |with|
2496 of ``Config`` to make the constants visible.
2497
2498 .. _Debugging_-_A_Special_Case:
2499
2500 Debugging - A Special Case
2501 ^^^^^^^^^^^^^^^^^^^^^^^^^^
2502
2503 A common use of conditional code is to execute statements (for example
2504 dynamic checks, or output of intermediate results) under control of a
2505 debug switch, so that the debugging behavior can be turned on and off.
2506 You can do this by using a Boolean constant to control whether the debug code
2507 is active:
2508
2509 .. code-block:: ada
2510
2511 if Debugging then
2512 Put_Line ("got to the first stage!");
2513 end if;
2514
2515 or
2516
2517 .. code-block:: ada
2518
2519 if Debugging and then Temperature > 999.0 then
2520 raise Temperature_Crazy;
2521 end if;
2522
2523 .. index:: pragma Assert
2524
2525 Since this is a common case, GNAT provides special features to deal
2526 with this in a convenient manner. For the case of tests, Ada 2005 has
2527 added a pragma ``Assert`` that you can use for such tests. This pragma
2528 is modeled on the ``Assert`` pragma that has always been available in
2529 GNAT, so you can use this feature with GNAT even if you are not using
2530 Ada 2005 features. The use of pragma ``Assert`` is described in the
2531 :title:`GNAT_Reference_Manual`, but as an example, the last test could
2532 be written:
2533
2534 .. code-block:: ada
2535
2536 pragma Assert (Temperature <= 999.0, "Temperature Crazy");
2537
2538 or simply
2539
2540 .. code-block:: ada
2541
2542 pragma Assert (Temperature <= 999.0);
2543
2544 In both cases, if assertions are active and the temperature is
2545 excessive, the exception ``Assert_Failure`` is raised with the
2546 exception message using the specified string in the first case or a
2547 string indicating the location of the pragma in the second case.
2548
2549 .. index:: pragma Assertion_Policy
2550
2551 You can turn assertions on and off by using the ``Assertion_Policy``
2552 pragma.
2553
2554 .. index:: -gnata switch
2555
2556 This is an Ada 2005 pragma that is implemented in all modes by
2557 GNAT. Alternatively, you can use the :switch:`-gnata` switch
2558 to enable assertions from the command line, which also applies to
2559 all versions of Ada.
2560
2561 .. index:: pragma Debug
2562
2563 For the example above with the ``Put_Line``, the GNAT-specific pragma
2564 ``Debug`` can be used:
2565
2566 .. code-block:: ada
2567
2568 pragma Debug (Put_Line ("got to the first stage!"));
2569
2570 If debug pragmas are enabled, the argument, which must be of the form
2571 of a procedure call, is executed (in this case, ``Put_Line`` is
2572 called). You can specify only one call, but you can of course include
2573 a special debugging procedure containing any code you like in the
2574 program and call it in a pragma ``Debug`` argument as needed.
2575
2576 One advantage of pragma ``Debug`` over the ``if Debugging then``
2577 construct is that pragma ``Debug`` can appear in declarative contexts,
2578 such as at the very beginning of a procedure, before local declarations have
2579 been elaborated.
2580
2581 .. index:: pragma Debug_Policy
2582
2583 You can enable debug pragmas using either the :switch:`-gnata` switch that also
2584 controls assertions, or with a separate Debug_Policy pragma.
2585
2586 The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used
2587 in Ada 95 and Ada 83 programs as well) and is analogous to
2588 pragma ``Assertion_Policy`` to control assertions.
2589
2590 ``Assertion_Policy`` and ``Debug_Policy`` are configuration pragmas,
2591 and thus can appear in :file:`gnat.adc` if you are not using a
2592 project file or in the file designated to contain configuration pragmas
2593 in a project file.
2594 They then apply to all subsequent compilations. In practice the use of
2595 the :switch:`-gnata` switch is often the most convenient method of controlling
2596 the status of these pragmas.
2597
2598 Note that a pragma is not a statement, so in contexts where a statement
2599 sequence is required, you can't just write a pragma on its own. You have
2600 to add a ``null`` statement.
2601
2602 .. code-block:: ada
2603
2604 if ... then
2605 ... -- some statements
2606 else
2607 pragma Assert (Num_Cases < 10);
2608 null;
2609 end if;
2610
2611 .. _Conditionalizing_Declarations:
2612
2613 Conditionalizing Declarations
2614 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2615
2616 In some cases it may be necessary to conditionalize declarations to meet
2617 different requirements. For example we might want a bit string whose length
2618 is set to meet some hardware message requirement.
2619
2620 This may be possible using declare blocks controlled
2621 by conditional constants:
2622
2623 .. code-block:: ada
2624
2625 if Small_Machine then
2626 declare
2627 X : Bit_String (1 .. 10);
2628 begin
2629 ...
2630 end;
2631 else
2632 declare
2633 X : Large_Bit_String (1 .. 1000);
2634 begin
2635 ...
2636 end;
2637 end if;
2638
2639 Note that in this approach, both declarations are analyzed by the
2640 compiler so this can only be used where both declarations are legal,
2641 even though one of them will not be used.
2642
2643 Another approach is to define integer constants, e.g., ``Bits_Per_Word``,
2644 or Boolean constants, e.g., ``Little_Endian``, and then write declarations
2645 that are parameterized by these constants. For example
2646
2647 .. code-block:: ada
2648
2649 for Rec use
2650 Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word;
2651 end record;
2652
2653 If ``Bits_Per_Word`` is set to 32, this generates either
2654
2655 .. code-block:: ada
2656
2657 for Rec use
2658 Field1 at 0 range 0 .. 32;
2659 end record;
2660
2661 for the big endian case, or
2662
2663 .. code-block:: ada
2664
2665 for Rec use record
2666 Field1 at 0 range 10 .. 32;
2667 end record;
2668
2669 for the little endian case. Since a powerful subset of Ada expression
2670 notation is usable for creating static constants, clever use of this
2671 feature can often solve quite difficult problems in conditionalizing
2672 compilation (note incidentally that in Ada 95, the little endian
2673 constant was introduced as ``System.Default_Bit_Order``, so you don't
2674 need to define this one yourself).
2675
2676 .. _Use_of_Alternative_Implementations:
2677
2678 Use of Alternative Implementations
2679 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2680
2681 In some cases, none of the approaches described above are adequate. This
2682 can occur, for example, if the set of declarations required is radically
2683 different for two different configurations.
2684
2685 In this situation, the official Ada way of dealing with conditionalizing
2686 such code is to write separate units for the different cases. As long as
2687 this doesn't result in excessive duplication of code, you can do this
2688 without creating maintenance problems. The approach is to share common
2689 code as far as possible and then isolate the code and declarations
2690 that are different. Subunits are often a convenient method for breaking
2691 out a piece of a unit that you need to be conditionalized, with separate files
2692 for different versions of the subunit for different targets, where the
2693 build script selects the right one to give to the compiler.
2694
2695 .. index:: Subunits (and conditional compilation)
2696
2697 As an example, consider a situation where a new feature in Ada 2005
2698 allows something to be done in a really nice way. But your code must be able
2699 to compile with an Ada 95 compiler. Conceptually you want to say:
2700
2701 .. code-block:: ada
2702
2703 if Ada_2005 then
2704 ... neat Ada 2005 code
2705 else
2706 ... not quite as neat Ada 95 code
2707 end if;
2708
2709 where ``Ada_2005`` is a Boolean constant.
2710
2711 But this won't work when ``Ada_2005`` is set to ``False``,
2712 since the ``then`` clause will be illegal for an Ada 95 compiler.
2713 (Recall that although such unreachable code would eventually be deleted
2714 by the compiler, it still needs to be legal. If it uses features
2715 introduced in Ada 2005, it's still illegal in Ada 95.)
2716
2717 So instead, we write
2718
2719 .. code-block:: ada
2720
2721 procedure Insert is separate;
2722
2723 Then we have two files for the subunit ``Insert``, with the two sets of
2724 code.
2725 If the package containing this is called ``File_Queries``, then we might
2726 have two files
2727
2728 * :file:`file_queries-insert-2005.adb`
2729 * :file:`file_queries-insert-95.adb`
2730
2731 and the build script renames the appropriate file to :file:`file_queries-insert.adb` and then carries out the compilation.
2732
2733 This can also be done with project files' naming schemes. For example:
2734
2735 .. code-block:: gpr
2736
2737 for body ("File_Queries.Insert") use "file_queries-insert-2005.ada";
2738
2739 Note also that with project files, you should use a different extension
2740 than :file:`ads` / :file:`adb` for alternative versions. Otherwise, a naming
2741 conflict may arise through another commonly used feature: declaring as part
2742 of the project a set of directories containing all the sources obeying the
2743 default naming scheme.
2744
2745 The use of alternative units is certainly feasible in all situations,
2746 and for example the Ada part of the GNAT run-time is conditionalized
2747 based on the target architecture using this approach. As a specific example,
2748 consider the implementation of the AST feature in VMS. There is one
2749 spec: :file:`s-asthan.ads` which is the same for all architectures, and three
2750 bodies:
2751
2752 * :file:`s-asthan.adb`
2753 used for all non-VMS operating systems
2754
2755 * :file:`s-asthan-vms-alpha.adb`
2756 used for VMS on the Alpha
2757
2758 * :file:`s-asthan-vms-ia64.adb`
2759 used for VMS on the ia64
2760
2761 The dummy version :file:`s-asthan.adb` simply raises exceptions noting that
2762 this operating system feature is not available and the two remaining
2763 versions interface with the corresponding versions of VMS to provide
2764 VMS-compatible AST handling. The GNAT build script knows the architecture
2765 and operating system, and automatically selects the right version,
2766 renaming it if necessary to :file:`s-asthan.adb` before the run-time build.
2767
2768 Another style for arranging alternative implementations is through
2769 Ada's access-to-subprogram facility. In case some functionality is to
2770 be conditionally included, you can declare an access-to-procedure
2771 variable ``Ref`` that is initialized to designate a 'do nothing'
2772 procedure, and then invoke ``Ref.all`` when appropriate. Then, in,
2773 some library package, set ``Ref`` to ``Proc'Access`` for some
2774 procedure ``Proc`` that performs the relevant processing. The
2775 initialization only occurs if the library package is included in the
2776 program. The same idea can also be implemented using tagged types and
2777 dispatching calls.
2778
2779 .. _Preprocessing:
2780
2781 Preprocessing
2782 ^^^^^^^^^^^^^
2783
2784 .. index:: Preprocessing
2785
2786 Although it is quite possible to conditionalize code without the use of
2787 C-style preprocessing, as described in the cases above, it is
2788 nevertheless convenient in some cases to use the C approach. Moreover,
2789 older Ada compilers have often provided some preprocessing capability,
2790 so legacy code may depend on this approach, even though it is not
2791 standard.
2792
2793 To accommodate such use, GNAT provides a preprocessor (modeled to a large
2794 extent on the various preprocessors that have been used
2795 with legacy code on other compilers, to enable easier transition).
2796
2797 .. index:: gnatprep
2798
2799 You can use the preprocessor used in two different modes. You can use it
2800 separately from the compiler to generate a separate output source file,
2801 which you then feed to the compiler as a separate step. This is the
2802 ``gnatprep`` utility, whose use is fully described in
2803 :ref:`Preprocessing_with_gnatprep`.
2804
2805 The preprocessing language allows such constructs as
2806
2807 .. code-block:: c
2808
2809 #if DEBUG or else (PRIORITY > 4) then
2810 sequence of declarations
2811 #else
2812 completely different sequence of declarations
2813 #end if;
2814
2815 The values of the symbols ``DEBUG`` and ``PRIORITY`` can be
2816 defined either on the command line or in a separate file.
2817
2818 The other way of running the preprocessor is even closer to the C style and
2819 often more convenient. In this approach, the preprocessing is integrated into
2820 the compilation process. You pass the compiler the preprocessor input, which
2821 includes ``#if`` lines etc, and the compiler carries out the
2822 preprocessing internally and compiles the resulting output.
2823 For more details on this approach, see :ref:`Integrated_Preprocessing`.
2824
2825 .. _Preprocessing_with_gnatprep:
2826
2827 Preprocessing with ``gnatprep``
2828 -------------------------------
2829
2830 .. index:: ! gnatprep
2831 .. index:: Preprocessing (gnatprep)
2832
2833 This section discusses how to you can use GNAT's ``gnatprep`` utility
2834 for simple preprocessing. Although designed for use with GNAT,
2835 ``gnatprep`` does not depend on any special GNAT features. For
2836 further discussion of conditional compilation in general, see
2837 :ref:`Conditional_Compilation`.
2838
2839 .. _Preprocessing_Symbols:
2840
2841 Preprocessing Symbols
2842 ^^^^^^^^^^^^^^^^^^^^^
2843
2844 Preprocessing symbols are defined in *definition files* and referenced in the
2845 sources to be preprocessed. A preprocessing symbol is an identifier, following
2846 normal Ada (case-insensitive) rules for its syntax, with the restriction that
2847 all characters need to be in the ASCII set (no accented letters).
2848
2849 .. _Using_gnatprep:
2850
2851 Using ``gnatprep``
2852 ^^^^^^^^^^^^^^^^^^
2853
2854 To call ``gnatprep`` use:
2855
2856 .. code-block:: sh
2857
2858 $ gnatprep [ switches ] infile outfile [ deffile ]
2859
2860 where
2861
2862 * *switches*
2863 is an optional sequence of switches as described in the next section.
2864
2865 * *infile*
2866 is the full name of the input file, which is an Ada source
2867 file containing preprocessor directives.
2868
2869 * *outfile*
2870 is the full name of the output file, which is an Ada source
2871 in standard Ada form. When used with GNAT, this file name will
2872 normally have an ``ads`` or ``adb`` suffix.
2873
2874 * ``deffile``
2875 is the full name of a text file containing definitions of
2876 preprocessing symbols to be referenced by the preprocessor. You
2877 can omit this argument and instead use the :switch:`-D` switch.
2878
2879
2880 .. _Switches_for_gnatprep:
2881
2882 Switches for ``gnatprep``
2883 ^^^^^^^^^^^^^^^^^^^^^^^^^
2884
2885 .. index:: --version (gnatprep)
2886
2887 :switch:`--version`
2888 Display copyright and version, then exit, disregarding all other options.
2889
2890 .. index:: --help (gnatprep)
2891
2892 :switch:`--help`
2893 If :switch:`--version` was not used, display usage and then exit, disregarding
2894 all other options.
2895
2896 .. index:: -b (gnatprep)
2897
2898 :switch:`-b`
2899 Causes both preprocessor lines and the lines deleted by
2900 preprocessing to be replaced by blank lines in the output source file,
2901 preserving line numbers in the output file.
2902
2903 .. index:: -c (gnatprep)
2904
2905 :switch:`-c`
2906 Causes both preprocessor lines and the lines deleted
2907 by preprocessing to be retained in the output source as comments marked
2908 with the special string ``"--! "``. This option also results in line numbers
2909 being preserved in the output file.
2910
2911 .. index:: -C (gnatprep)
2912
2913 :switch:`-C`
2914 Causes comments to be scanned. Normally comments are ignored by
2915 ``gnatprep``. If you specify this option, ``gnatprep`` scans
2916 comments and any $symbol substitutions performed as in program
2917 text. You will find this particularly useful when structured
2918 comments are used (e.g., for programs written in a pre-2014 version
2919 of the SPARK Ada subset). This switch is not available
2920 when doing integrated preprocessing (it would be useless in this
2921 context since comments are always ignored by the compiler).
2922
2923 .. index:: -D (gnatprep)
2924
2925 :switch:`-D{symbol}[={value}]`
2926 Defines a new preprocessing symbol with the specified value. If you
2927 don't specify a value, the symbol is defined to be ``True``. You can
2928 use this switch instead of providing a definition file.
2929
2930 .. index:: -r (gnatprep)
2931
2932 :switch:`-r`
2933 Causes ``gnatprep`` to generate a ``Source_Reference`` pragma that
2934 references the original input file, so that error messages will use
2935 the file name of this original file. The use of this switch implies
2936 that preprocessor lines are not to be removed from the file, so
2937 the :switch:`-b` and :switch:`-c` are always enabled.
2938
2939 If the file to be preprocessed contains multiple units, you
2940 must call ``gnatchop`` on the the output file from
2941 ``gnatprep``. If a ``Source_Reference`` pragma is present
2942 in the preprocessed file, it will be respected by
2943 ``gnatchop -r``
2944 so that the final chopped files will correctly refer to the original
2945 input source file passed to ``gnatprep``.
2946
2947 .. index:: -s (gnatprep)
2948
2949 :switch:`-s`
2950 Causes a sorted list of symbol names and values to be
2951 listed on the standard output file.
2952
2953 .. index:: -T (gnatprep)
2954
2955 :switch:`-T`
2956 Use LF as line terminators when writing files. By default the line terminator
2957 of the host (LF under unix, CR/LF under Windows) is used.
2958
2959 .. index:: -u (gnatprep)
2960
2961 :switch:`-u`
2962 Causes undefined symbols to be treated as having the value ``False``
2963 in the context of a preprocessor test. If you don't specify this
2964 switch, ``gnatprep`` will treat an undefined symbol in a ``#if`` or
2965 ``#elsif`` test as an error.
2966
2967 .. index:: -v (gnatprep)
2968
2969 :switch:`-v`
2970 Verbose mode: generates more output about what is done.
2971
2972 Note: if you don't specify either :switch:`-b` or :switch:`-c`,
2973 then preprocessor lines and
2974 deleted lines are completely removed from the output, unless you specify
2975 :switch:`-r`, in which case ``gnatprep`` enables the :switch:`-b` switch.
2976
2977
2978 .. _Form_of_Definitions_File:
2979
2980 Form of Definitions File
2981 ^^^^^^^^^^^^^^^^^^^^^^^^
2982
2983 The definitions file contains lines of the form::
2984
2985 symbol := value
2986
2987 where ``symbol`` is a preprocessing symbol, and ``value`` is one of the following:
2988
2989 * Empty, corresponding to a null substitution,
2990 * A string literal using normal Ada syntax, or
2991 * Any sequence of characters from the set {letters, digits, period, underline}.
2992
2993 You may also place comment lines in the definitions file, starting with
2994 the usual ``--``
2995 and comments may be added to the end of each definition line.
2996
2997
2998 .. _Form_of_Input_Text_for_gnatprep:
2999
3000 Form of Input Text for ``gnatprep``
3001 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3002
3003 The input text contains preprocessor conditional inclusion lines
3004 as well as general symbol substitution sequences.
3005
3006 Preprocessor conditional inclusion commands have the form:
3007
3008 .. code-block:: c
3009
3010 #if <expression> [then]
3011 lines
3012 #elsif <expression> [then]
3013 lines
3014 #elsif <expression> [then]
3015 lines
3016 ...
3017 #else
3018 lines
3019 #end if;
3020
3021 In this example, <expression> is defined by the following grammar::
3022
3023 <expression> ::= <symbol>
3024 <expression> ::= <symbol> = "<value>"
3025 <expression> ::= <symbol> = <symbol>
3026 <expression> ::= <symbol> = <integer>
3027 <expression> ::= <symbol> > <integer>
3028 <expression> ::= <symbol> >= <integer>
3029 <expression> ::= <symbol> < <integer>
3030 <expression> ::= <symbol> <= <integer>
3031 <expression> ::= <symbol> 'Defined
3032 <expression> ::= not <expression>
3033 <expression> ::= <expression> and <expression>
3034 <expression> ::= <expression> or <expression>
3035 <expression> ::= <expression> and then <expression>
3036 <expression> ::= <expression> or else <expression>
3037 <expression> ::= ( <expression> )
3038
3039 For the first test, (<expression> ::= <symbol>), the symbol must have
3040 either the value true or false. The right-hand of the
3041 symbol definition must be one of the (case-insensitive) literals
3042 ``True`` or ``False``. If the value is true, the
3043 corresponding lines are included and if the value is false, they are
3044 excluded.
3045
3046 When comparing a symbol to an integer, the integer is any non negative
3047 literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or
3048 2#11#. The symbol value must also be a non negative integer. Integer values
3049 in the range 0 .. 2**31-1 are supported.
3050
3051 The test (<expression> ::= <symbol>'Defined) is true only if
3052 the symbol has been defined in the definition file or by a :switch:`-D`
3053 switch on the command line. Otherwise, the test is false.
3054
3055 The equality tests are case insensitive, as are all the preprocessor lines.
3056
3057 If the symbol referenced is not defined in the symbol definitions
3058 file, the result depends on whether or not you have specified the
3059 :switch:`-u` switch. If you have, the symbol is treated as if it had
3060 the value false and the test fails. If not,
3061 it's an error to reference an undefined symbol. It's also an
3062 error to reference a symbol that you have defined with a value other than
3063 ``True`` or ``False``.
3064
3065 The use of the ``not`` operator inverts the sense of this logical
3066 test. You can't combine the ``not`` operator with the ``or`` or
3067 ``and`` operators without parentheses. For example, you can't write
3068 "if not X or Y then" allowed, but can write either "if (not X) or Y
3069 then" or "if not (X or Y) then".
3070
3071 The ``then`` keyword is optional, as shown.
3072
3073 You must place the ``#`` in the first non-blank character on a line,
3074 i.e., it must be preceded only by spaces or horizontal tabs, but
3075 otherwise the format is free form. You may place spaces or tabs
3076 between the ``#`` and the keyword. The keywords and the symbols are
3077 case insensitive, as in normal Ada code. You can write comments on a
3078 preprocessor line, but other than that, you can't place any other
3079 tokens on a preprocessor line. You can have any number of ``elsif``
3080 clauses, including none at all. The ``else`` is optional, as in Ada.
3081
3082 You obtain symbol substitution outside of preprocessor lines by using
3083 the sequence::
3084
3085 $symbol
3086
3087 anywhere within a source line, except in a comment or within a
3088 string literal. The identifier
3089 following the ``$`` must match one of the symbols defined in the symbol
3090 definition file and the resulting output substitutes the value of the
3091 symbol in place of ``$symbol`` in the output file.
3092
3093 Note that although you can't substitute strings within a string
3094 literal, you can have a symbol whose defined value is a string
3095 literal. So instead of setting XYZ to ``hello`` and writing:
3096
3097 .. code-block:: ada
3098
3099 Header : String := "$XYZ";
3100
3101 you should set XYZ to ``"hello"`` and write:
3102
3103 .. code-block:: ada
3104
3105 Header : String := $XYZ;
3106
3107 and then the substitution will occur as desired.
3108
3109
3110 .. _Integrated_Preprocessing:
3111
3112 Integrated Preprocessing
3113 ------------------------
3114
3115 As noted above, a file to be preprocessed consists of Ada source code
3116 in which preprocessing lines have been inserted. However, instead of
3117 using ``gnatprep`` to explicitly preprocess a file as a separate step
3118 before compilation, you can carry out the preprocessing implicitly as
3119 part of compilation. Such *integrated preprocessing*, which is the
3120 common style with C, is performed when you pass either or both of the
3121 following switches to the compiler:
3122
3123 * :switch:`-gnatep`, which specifies the *preprocessor data file*.
3124 This file dictates how the source files will be preprocessed (e.g., which
3125 symbol definition files apply to which sources).
3126
3127 * :switch:`-gnateD`, which defines values for preprocessing symbols.
3128
3129 Integrated preprocessing applies only to Ada source files; it's
3130 not available for configuration pragma files.
3131
3132 With integrated preprocessing, GNAT doesn't write the output from the
3133 preprocessor, by default, to any external file. Instead it's passed
3134 internally to the compiler. To preserve the result of preprocessing in
3135 a file, either run ``gnatprep`` in standalone mode or supply the
3136 :switch:`-gnateG` switch to the compiler.
3137
3138 When using project files:
3139
3140 * you should use the builder switch :switch:`-x` if any Ada source is
3141 compiled with :switch:`gnatep=` so that the compiler finds the
3142 *preprocessor data file*.
3143
3144 * you should place the preprocessing data file and the symbol
3145 definition files in the source directories of the project.
3146
3147 Note that the ``gnatmake`` switch :switch:`-m` will almost
3148 always trigger recompilation for sources that are preprocessed,
3149 because ``gnatmake`` cannot compute the checksum of the source after
3150 preprocessing.
3151
3152 The actual preprocessing function is described in detail in
3153 :ref:`Preprocessing_with_gnatprep`. This section explains the switches
3154 that relate to integrated preprocessing.
3155
3156 .. index:: -gnatep (gcc)
3157
3158 :switch:`-gnatep={preprocessor_data_file}`
3159 This switch specifies the file name (without directory
3160 information) of the preprocessor data file. Either place this file
3161 in one of the source directories, or, when using project
3162 files, reference the project file's directory via the
3163 ``project_name'Project_Dir`` project attribute; e.g:
3164
3165 .. code-block:: gpr
3166
3167 project Prj is
3168 package Compiler is
3169 for Switches ("Ada") use
3170 ("-gnatep=" & Prj'Project_Dir & "prep.def");
3171 end Compiler;
3172 end Prj;
3173
3174 A preprocessor data file is a text file that contains *preprocessor
3175 control lines*. A preprocessor control line directs the preprocessing of
3176 either a particular source file, or, analogous to ``others`` in Ada,
3177 all sources not specified elsewhere in the preprocessor data file.
3178 A preprocessor control line
3179 can optionally identify a *definition file* that assigns values to
3180 preprocessor symbols, as well as a list of switches that relate to
3181 preprocessing.
3182 You can also include empty lines and comments (using Ada syntax), with no
3183 semantic effect.
3184
3185 Here's an example of a preprocessor data file:
3186
3187 .. code-block:: ada
3188
3189 "toto.adb" "prep.def" -u
3190 -- Preprocess toto.adb, using definition file prep.def
3191 -- Undefined symbols are treated as False
3192
3193 * -c -DVERSION=V101
3194 -- Preprocess all other sources without using a definition file
3195 -- Suppressed lined are commented
3196 -- Symbol VERSION has the value V101
3197
3198 "tata.adb" "prep2.def" -s
3199 -- Preprocess tata.adb, using definition file prep2.def
3200 -- List all symbols with their values
3201
3202 A preprocessor control line has the following syntax:
3203
3204 ::
3205
3206 <preprocessor_control_line> ::=
3207 <preprocessor_input> [ <definition_file_name> ] { <switch> }
3208
3209 <preprocessor_input> ::= <source_file_name> | '*'
3210
3211 <definition_file_name> ::= <string_literal>
3212
3213 <source_file_name> := <string_literal>
3214
3215 <switch> := (See below for list)
3216
3217 Thus, you start each preprocessor control line either a literal
3218 string or the character '*':
3219
3220 * A literal string is the file name (without directory information) of the source
3221 file that will be input to the preprocessor.
3222
3223 * The character '*' is a wild-card indicator; the additional parameters on the line
3224 indicate the preprocessing for all the sources
3225 that are not specified explicitly on other lines (the order of the lines is not
3226 significant).
3227
3228 You cannot have two lines with the same file name or two
3229 lines starting with the '*' character.
3230
3231 After the file name or '*', you can place an optional literal string
3232 to specify the name of the definition file to be used for
3233 preprocessing (:ref:`Form_of_Definitions_File`). The definition
3234 files are found by the compiler in one of the source directories. In
3235 some cases, when compiling a source in a directory other than the
3236 current directory, if the definition file is in the current
3237 directory, you may need to add the current directory as a
3238 source directory through the :switch:`-I` switch; otherwise the
3239 compiler would not find the definition file.
3240
3241 Finally, switches similar to those of ``gnatprep`` may optionally appear:
3242
3243 :switch:`-b`
3244 Causes both preprocessor lines and the lines deleted by
3245 preprocessing to be replaced by blank lines, preserving the line number.
3246 This switch is always implied; however, if specified after :switch:`-c`
3247 it cancels the effect of :switch:`-c`.
3248
3249 :switch:`-c`
3250 Causes both preprocessor lines and the lines deleted
3251 by preprocessing to be retained as comments marked
3252 with the special string '`--!`'.
3253
3254
3255 :switch:`-D{symbol}={new_value}`
3256 Define or redefine ``symbol`` to have ``new_value`` as its value.
3257 You can write ``symbol`` as either an Ada identifier or any Ada
3258 reserved word aside from ``if``, ``else``, ``elsif``, ``end``,
3259 ``and``, ``or`` and ``then``. You can write ``new_value`` as a
3260 literal string, an Ada identifier or any Ada reserved word. A
3261 symbol declared with this switch replaces a symbol with the same
3262 name defined in a definition file.
3263
3264
3265 :switch:`-s`
3266 Causes a sorted list of symbol names and values to be
3267 listed on the standard output file.
3268
3269
3270 :switch:`-u`
3271 Causes undefined symbols to be treated as having the value
3272 ``FALSE`` in the context of a preprocessor test. If you don't
3273 specify this switch, an undefined symbol in a ``#if`` or
3274 ``#elsif`` test is treated as an error.
3275
3276
3277 .. index:: -gnateD (gcc)
3278
3279 :switch:`-gnateD{symbol}[={new_value}]`
3280 Define or redefine ``symbol`` to have ``new_value`` as its value. If
3281 you don't specify a value, the value of ``symbol`` is ``True``. You
3282 write ``symbol`` as an identifier, following normal Ada
3283 (case-insensitive) rules for its syntax, and ``new_value`` as either
3284 an arbitrary string between double quotes or any sequence (including
3285 an empty sequence) of characters from the set (letters, digits,
3286 period, underline). Ada reserved words may be used as symbols, with
3287 the exceptions of ``if``, ``else``, ``elsif``, ``end``, ``and``,
3288 ``or`` and ``then``.
3289
3290 Examples:
3291
3292 ::
3293
3294 -gnateDToto=Tata
3295 -gnateDFoo
3296 -gnateDFoo=\"Foo-Bar\"
3297
3298 A symbol declared with this switch on the command line replaces a
3299 symbol with the same name either in a definition file or specified with a
3300 switch :switch:`-D` in the preprocessor data file.
3301
3302 This switch is similar to switch :switch:`-D` of ``gnatprep``.
3303
3304
3305 :switch:`-gnateG`
3306 When integrated preprocessing is performed on source file :file:`filename.extension`,
3307 create or overwrite :file:`filename.extension.prep` to contain
3308 the result of the preprocessing.
3309 For example if the source file is :file:`foo.adb` then
3310 the output file is :file:`foo.adb.prep`.
3311
3312
3313 .. _Mixed_Language_Programming:
3314
3315 Mixed Language Programming
3316 ==========================
3317
3318 .. index:: Mixed Language Programming
3319
3320 This section describes how to develop a mixed-language program,
3321 with a focus on combining Ada with C or C++.
3322
3323 .. _Interfacing_to_C:
3324
3325 Interfacing to C
3326 ----------------
3327
3328 Interfacing Ada with a foreign language such as C involves using
3329 compiler directives to import and/or export entity definitions in each
3330 language -- using ``extern`` statements in C, for example, and the
3331 ``Import``, ``Export``, and ``Convention`` pragmas in Ada.
3332 A full treatment of these topics is provided in Appendix B, section 1
3333 of the Ada Reference Manual.
3334
3335 There are two ways to build a program using GNAT that contains some Ada
3336 sources and some foreign language sources, depending on whether or not
3337 the main subprogram is written in Ada. Here's an example with
3338 the main subprogram in Ada:
3339
3340 .. code-block:: c
3341
3342 /* file1.c */
3343 #include <stdio.h>
3344
3345 void print_num (int num)
3346 {
3347 printf ("num is %d.\\n", num);
3348 return;
3349 }
3350
3351 .. code-block:: c
3352
3353 /* file2.c */
3354
3355 /* num_from_Ada is declared in my_main.adb */
3356 extern int num_from_Ada;
3357
3358 int get_num (void)
3359 {
3360 return num_from_Ada;
3361 }
3362
3363 .. code-block:: ada
3364
3365 -- my_main.adb
3366 procedure My_Main is
3367
3368 -- Declare then export an Integer entity called num_from_Ada
3369 My_Num : Integer := 10;
3370 pragma Export (C, My_Num, "num_from_Ada");
3371
3372 -- Declare an Ada function spec for Get_Num, then use
3373 -- C function get_num for the implementation.
3374 function Get_Num return Integer;
3375 pragma Import (C, Get_Num, "get_num");
3376
3377 -- Declare an Ada procedure spec for Print_Num, then use
3378 -- C function print_num for the implementation.
3379 procedure Print_Num (Num : Integer);
3380 pragma Import (C, Print_Num, "print_num");
3381
3382 begin
3383 Print_Num (Get_Num);
3384 end My_Main;
3385
3386 To build this example:
3387
3388 * First compile the foreign language files to
3389 generate object files:
3390
3391 .. code-block:: sh
3392
3393 $ gcc -c file1.c
3394 $ gcc -c file2.c
3395
3396 * Then compile the Ada units to produce a set of object files and ALI
3397 files:
3398
3399 .. code-block:: sh
3400
3401 $ gnatmake -c my_main.adb
3402
3403 * Run the Ada binder on the Ada main program:
3404
3405 .. code-block:: sh
3406
3407 $ gnatbind my_main.ali
3408
3409 * Link the Ada main program, the Ada objects, and the other language
3410 objects:
3411
3412 .. code-block:: sh
3413
3414 $ gnatlink my_main.ali file1.o file2.o
3415
3416 You can merge the last three steps into a single command:
3417
3418 .. code-block:: sh
3419
3420 $ gnatmake my_main.adb -largs file1.o file2.o
3421
3422
3423 .. index:: Binder output file
3424
3425 If the main program is in a language other than Ada, you may have more
3426 than one entry point into the Ada subsystem. You must use a special
3427 binder option to generate callable routines that initialize and
3428 finalize the Ada units (:ref:`Binding_with_Non-Ada_Main_Programs`).
3429 You must insert calls to the initialization and finalization routines
3430 in the main program or some other appropriate point in the code. You
3431 must place the call to initialize the Ada units so that it occurs
3432 before the first Ada subprogram is called and must place the call to
3433 finalize the Ada units so it occurs after the last Ada subprogram
3434 returns. The binder places the initialization and finalization
3435 subprograms into the :file:`b~xxx.adb` file, where they can be
3436 accessed by your C sources. To illustrate, we have the following
3437 example:
3438
3439 .. code-block:: c
3440
3441 /* main.c */
3442 extern void adainit (void);
3443 extern void adafinal (void);
3444 extern int add (int, int);
3445 extern int sub (int, int);
3446
3447 int main (int argc, char *argv[])
3448 {
3449 int a = 21, b = 7;
3450
3451 adainit();
3452
3453 /* Should print "21 + 7 = 28" */
3454 printf ("%d + %d = %d\\n", a, b, add (a, b));
3455
3456 /* Should print "21 - 7 = 14" */
3457 printf ("%d - %d = %d\\n", a, b, sub (a, b));
3458
3459 adafinal();
3460 }
3461
3462 .. code-block:: ada
3463
3464 -- unit1.ads
3465 package Unit1 is
3466 function Add (A, B : Integer) return Integer;
3467 pragma Export (C, Add, "add");
3468 end Unit1;
3469
3470 .. code-block:: ada
3471
3472 -- unit1.adb
3473 package body Unit1 is
3474 function Add (A, B : Integer) return Integer is
3475 begin
3476 return A + B;
3477 end Add;
3478 end Unit1;
3479
3480 .. code-block:: ada
3481
3482 -- unit2.ads
3483 package Unit2 is
3484 function Sub (A, B : Integer) return Integer;
3485 pragma Export (C, Sub, "sub");
3486 end Unit2;
3487
3488 .. code-block:: ada
3489
3490 -- unit2.adb
3491 package body Unit2 is
3492 function Sub (A, B : Integer) return Integer is
3493 begin
3494 return A - B;
3495 end Sub;
3496 end Unit2;
3497
3498 The build procedure for this application is similar to the last
3499 example's:
3500
3501 * First, compile the foreign language files to generate object files:
3502
3503 .. code-block:: sh
3504
3505 $ gcc -c main.c
3506
3507
3508 * Next, compile the Ada units to produce a set of object files and ALI
3509 files:
3510
3511 .. code-block:: sh
3512
3513 $ gnatmake -c unit1.adb
3514 $ gnatmake -c unit2.adb
3515
3516 * Run the Ada binder on every generated ALI file. Make sure to use the
3517 :switch:`-n` option to specify a foreign main program:
3518
3519 .. code-block:: sh
3520
3521 $ gnatbind -n unit1.ali unit2.ali
3522
3523 * Link the Ada main program, the Ada objects and the foreign language
3524 objects. You need only list the last ALI file here:
3525
3526 .. code-block:: sh
3527
3528 $ gnatlink unit2.ali main.o -o exec_file
3529
3530 This procedure yields a binary executable called :file:`exec_file`.
3531
3532 Depending on the circumstances (for example when your non-Ada main object
3533 does not provide symbol ``main``), you may also need to instruct the
3534 GNAT linker not to include the standard startup objects by passing the
3535 :switch:`-nostartfiles` switch to ``gnatlink``.
3536
3537 .. _Calling_Conventions:
3538
3539 Calling Conventions
3540 -------------------
3541
3542 .. index:: Foreign Languages
3543
3544 .. index:: Calling Conventions
3545
3546 GNAT follows standard calling sequence conventions and will interface
3547 to any other language that also follows these conventions. The following
3548 Convention identifiers are recognized by GNAT:
3549
3550
3551 .. index:: Interfacing to Ada
3552
3553 .. index:: Other Ada compilers
3554
3555 .. index:: Convention Ada
3556
3557 ``Ada``
3558 This indicates that the standard Ada calling sequence is
3559 used and all Ada data items may be passed without any limitations in the
3560 case where GNAT is used to generate both the caller and callee. You can also
3561 mix GNAT generated code and code generated by another Ada
3562 compiler. In this case, you should restrict the data types to simple
3563 cases, including primitive types. Whether complex data types can be passed
3564 depends on the situation. It is probably safe to pass simple arrays, such
3565 as arrays of integers or floats. Records may or may not work, depending
3566 on whether both compilers lay them out identically. Complex structures
3567 involving variant records, access parameters, tasks, or protected types,
3568 are unlikely to be able to be passed.
3569
3570 If output from two different compilers is mixed, you are responsible
3571 for dealing with elaboration issues. Probably the safest approach is
3572 to write the main program in the version of Ada other than GNAT, so
3573 it takes care of its own elaboration requirements, and
3574 call the GNAT-generated adainit procedure to ensure elaboration of
3575 the GNAT components. Consult the documentation of the other Ada
3576 compiler for further details on elaboration.
3577
3578 .. index:: Interfacing to Assembly
3579
3580 .. index:: Convention Assembler
3581
3582
3583 ``Assembler``
3584 Specifies assembler as the convention. In practice this has the
3585 same effect as convention Ada (but is not equivalent in the sense of being
3586 considered the same convention).
3587
3588 .. index:: Convention Asm
3589
3590 .. index:: Asm
3591
3592 ``Asm``
3593 Equivalent to Assembler.
3594
3595 .. index:: Interfacing to COBOL
3596
3597 .. index:: Convention COBOL
3598
3599 .. index:: COBOL
3600
3601 ``COBOL``
3602 Data is passed according to the conventions described
3603 in section B.4 of the Ada Reference Manual.
3604
3605 .. index:: C
3606 .. index:: Interfacing to C
3607
3608 .. index:: Convention C
3609
3610
3611 ``C``
3612 Data is passed according to the conventions described
3613 in section B.3 of the Ada Reference Manual.
3614
3615 A note on interfacing to a C 'varargs' function:
3616
3617 .. index:: C varargs function
3618 .. index:: Interfacing to C varargs function
3619 .. index:: varargs function interfaces
3620
3621 In C, ``varargs`` allows a function to take a variable number of
3622 arguments. There is no direct equivalent in this to Ada. One
3623 approach that you can use is to create a C wrapper for each
3624 different profile and then interface to this C wrapper. For
3625 example, to print an ``int`` value using ``printf``,
3626 create a C function ``printfi`` that takes two arguments, a
3627 pointer to a string and an int, and calls ``printf``.
3628 Then in the Ada program, use pragma ``Import`` to
3629 interface to ``printfi``.
3630
3631 It may work on some platforms to directly interface to
3632 a ``varargs`` function by providing a specific Ada profile
3633 for a particular call. However, this does not work on
3634 all platforms since there is no guarantee that the
3635 calling sequence for a two-argument normal C function
3636 is the same as for calling a ``varargs`` C function with
3637 the same two arguments.
3638
3639 .. index:: Convention Default
3640
3641 .. index:: Default
3642
3643 ``Default``
3644 Equivalent to C.
3645
3646 .. index:: Convention External
3647
3648 .. index:: External
3649
3650 ``External``
3651 Equivalent to C.
3652
3653 .. index:: C++
3654 .. index:: Interfacing to C++
3655
3656 .. index:: Convention C++
3657
3658
3659 ``C_Plus_Plus`` (or ``CPP``)
3660 This stands for C++. For most purposes, this is identical to C.
3661 See the separate description of the specialized GNAT pragmas relating to
3662 C++ interfacing for further details.
3663
3664 .. index:: Fortran
3665 .. index:: Interfacing to Fortran
3666 .. index:: Convention Fortran
3667
3668
3669 ``Fortran``
3670 Data is passed according to the conventions described
3671 in section B.5 of the Ada Reference Manual.
3672
3673
3674 ``Intrinsic``
3675 This applies to an intrinsic operation, as defined in the Ada
3676 Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram,
3677 it means the body of the subprogram is provided by the compiler itself,
3678 usually by means of an efficient code sequence, and that you don't
3679 supply an explicit body for it. In an application program, the pragma may
3680 be applied to the following sets of names:
3681
3682
3683 * ``Rotate_Left``, ``Rotate_Right``, ``Shift_Left``, ``Shift_Right``, ``Shift_Right_Arithmetic``.
3684 The corresponding subprogram declaration must have
3685 two formal parameters. The
3686 first must be a signed integer type or a modular type with a binary
3687 modulus and the second parameter must be of type Natural.
3688 The return type must be the same as the type of the first argument. The size
3689 of this type can only be 8, 16, 32, or 64.
3690
3691
3692 * Binary arithmetic operators: '+', '-', '*', '/'.
3693 The corresponding operator declaration must have parameters and result type
3694 that have the same root numeric type (for example, all three are long_float
3695 types). This simplifies the definition of operations that use type checking
3696 to perform dimensional checks:
3697
3698
3699 .. code-block:: ada
3700
3701 type Distance is new Long_Float;
3702 type Time is new Long_Float;
3703 type Velocity is new Long_Float;
3704 function "/" (D : Distance; T : Time)
3705 return Velocity;
3706 pragma Import (Intrinsic, "/");
3707
3708 You often program this common idiom with a generic definition and an
3709 explicit body. The pragma makes it simpler to introduce such declarations.
3710 It incurs no overhead in compilation time or code size because it is
3711 implemented as a single machine instruction.
3712
3713
3714 * General subprogram entities. This is used to bind an Ada subprogram
3715 declaration to
3716 a compiler builtin by name with back ends where such interfaces are
3717 available. A typical example is the set of ``__builtin`` functions
3718 exposed by the ``gcc`` back end, as in the following example:
3719
3720
3721 .. code-block:: ada
3722
3723 function builtin_sqrt (F : Float) return Float;
3724 pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf");
3725
3726 Most of the ``gcc`` builtins are accessible this way, and as for other
3727 import conventions (e.g. C), it is the user's responsibility to ensure
3728 that the Ada subprogram profile matches the underlying builtin
3729 expectations.
3730
3731 .. index:: Stdcall
3732 .. index:: Convention Stdcall
3733
3734 ``Stdcall``
3735 This is relevant only to Windows implementations of GNAT
3736 and specifies that the ``Stdcall`` calling sequence is used,
3737 as defined by the NT API. To simplify building
3738 cross-platform bindings, this convention is handled as a ``C`` calling
3739 convention on non-Windows platforms.
3740
3741 .. index:: DLL
3742 .. index:: Convention DLL
3743
3744
3745 ``DLL``
3746 This is equivalent to ``Stdcall``.
3747
3748 .. index:: Win32
3749 .. index:: Convention Win32
3750
3751
3752 ``Win32``
3753 This is equivalent to ``Stdcall``.
3754
3755 .. index:: Stubbed
3756 .. index:: Convention Stubbed
3757
3758
3759 ``Stubbed``
3760 This is a special convention that indicates that the compiler
3761 should provide a stub body that raises ``Program_Error``.
3762
3763 GNAT additionally provides a useful pragma ``Convention_Identifier``
3764 that you can use to parameterize conventions and allow additional synonyms.
3765 For example, if you have legacy code in which the convention
3766 identifier Fortran77 was used for Fortran, you can use the configuration
3767 pragma:
3768
3769 .. code-block:: ada
3770
3771 pragma Convention_Identifier (Fortran77, Fortran);
3772
3773 And from now on, you can use the identifier ``Fortran77`` as a convention
3774 identifier (for example in an ``Import`` pragma) with the same
3775 meaning as ``Fortran``.
3776
3777
3778 .. _Building_Mixed_Ada_and_C++_Programs:
3779
3780 Building Mixed Ada and C++ Programs
3781 -----------------------------------
3782
3783 If you are inexperienced with mixed-language development, you may find that
3784 building an application containing both Ada and C++ code can be a
3785 challenge. This section gives a few hints that should make this task easier.
3786
3787 .. _Interfacing_to_C++:
3788
3789 Interfacing to C++
3790 ^^^^^^^^^^^^^^^^^^
3791
3792 GNAT supports interfacing with the G++ compiler (or any C++ compiler
3793 generating code that is compatible with the G++ Application Binary
3794 Interface ---see http://itanium-cxx-abi.github.io/cxx-abi/abi.html).
3795
3796 You can do interfacing at three levels: simple data, subprograms, and
3797 classes. In the first two cases, GNAT offers a specific ``Convention C_Plus_Plus``
3798 (or ``CPP``) that behaves exactly like ``Convention C``.
3799 Usually, C++ mangles the names of subprograms. To generate proper mangled
3800 names automatically, see :ref:`Generating_Ada_Bindings_for_C_and_C++_headers`).
3801 You can also address this problem addressed manually in two ways:
3802
3803 * by modifying the C++ code in order to force a C convention using
3804 the ``extern "C"`` syntax.
3805
3806 * by figuring out the mangled name (using e.g. ``nm`` or by looking at the
3807 assembly code generated by the C++ compiler) and using it as the
3808 ``Link_Name`` argument of the pragma ``Import``.
3809
3810 You can achieve interfacing at the class level by using the GNAT specific
3811 pragmas such as ``CPP_Constructor``. See the :title:`GNAT_Reference_Manual` for additional information.
3812
3813 .. _Linking_a_Mixed_C++_and_Ada_Program:
3814
3815 Linking a Mixed C++ & Ada Program
3816 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3817
3818 Usually the linker, of the C++ development system must be used to link
3819 mixed applications because most C++ systems resolve elaboration
3820 issues (such as calling constructors on global class instances)
3821 transparently during the link phase. GNAT has been adapted to ease the
3822 use of a foreign linker for the last phase. We consider three cases:
3823
3824
3825 * Using GNAT and G++ (GNU C++ compiler) from the same GCC installation:
3826 You can call the C++ linker by using the C++ specific driver
3827 called ``g++``.
3828
3829 If the C++ code uses inline functions that you plan to call from
3830 Ada, you need to compile your C++ code with the
3831 :switch:`-fkeep-inline-functions` so ``g++`` doesn't delete these
3832 functions.
3833
3834 .. code-block:: sh
3835
3836 $ g++ -c -fkeep-inline-functions file1.C
3837 $ g++ -c -fkeep-inline-functions file2.C
3838 $ gnatmake ada_unit -largs file1.o file2.o --LINK=g++
3839
3840
3841 * Using GNAT and G++ from two different GCC installations: If both
3842 compilers are on the :envvar:`PATH`, you may use the previous
3843 method. However, environment variables such as
3844 :envvar:`C_INCLUDE_PATH`, :envvar:`GCC_EXEC_PREFIX`,
3845 :envvar:`BINUTILS_ROOT`, and :envvar:`GCC_ROOT` affect both
3846 compilers at the same time and may make one of the two compilers
3847 operate improperly if set during invocation of the wrong compiler.
3848 It is also very important that the linker uses the proper
3849 :file:`libgcc.a` ``gcc`` library -- that is, the one from the C++
3850 compiler installation. You can replace the implicit link command as
3851 suggested in the ``gnatmake`` command from the former example with
3852 an explicit link command with the full-verbosity option
3853 in order to verify which library is used:
3854
3855 .. code-block:: sh
3856
3857 $ gnatbind ada_unit
3858 $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++
3859
3860 If there's a problem due to interfering environment variables, you can
3861 work around it by using an intermediate script. The following example
3862 shows the proper script to use when GNAT has not been installed at its
3863 default location and ``g++`` has been installed at its default location:
3864
3865 .. code-block:: sh
3866
3867 $ cat ./my_script
3868 #!/bin/sh
3869 unset BINUTILS_ROOT
3870 unset GCC_ROOT
3871 c++ $*
3872 $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script
3873
3874
3875 * Using a non-GNU C++ compiler: You can use the commands previously described
3876 used to insure that the C++ linker is used. Nonetheless, you need to add
3877 a few more parameters to the link command line, depending on the exception
3878 mechanism used.
3879
3880 If you are using the ``setjmp`` / ``longjmp`` exception mechanism, you need only
3881 inclue the paths to the ``libgcc`` libraries:
3882
3883 .. code-block:: sh
3884
3885 $ cat ./my_script
3886 #!/bin/sh
3887 CC $* gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a
3888 $ gnatlink ada_unit file1.o file2.o --LINK=./my_script
3889
3890
3891 where CC is the name of the non-GNU C++ compiler.
3892
3893 If you are using the "zero cost" exception mechanism and the platform
3894 supports automatic registration of exception tables (e.g., Solaris),
3895 you need to include paths to more objects:
3896
3897 .. code-block:: sh
3898
3899 $ cat ./my_script
3900 #!/bin/sh
3901 CC gcc -print-file-name=crtbegin.o $* \\
3902 gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a \\
3903 gcc -print-file-name=crtend.o
3904 $ gnatlink ada_unit file1.o file2.o --LINK=./my_script
3905
3906
3907 If you are using the "zero cost exception" mechanism is used and the platform
3908 doesn't support automatic registration of exception tables (e.g., HP-UX
3909 or AIX), the simple approach described above won't work and
3910 a you will need to preform a pre-linking phase using GNAT.
3911
3912
3913 Another alternative is to use the :command:`gprbuild` multi-language builder
3914 which has a large knowledge base and knows how to link Ada and C++ code
3915 together automatically in most cases.
3916
3917 .. _A_Simple_Example:
3918
3919 A Simple Example
3920 ^^^^^^^^^^^^^^^^
3921
3922 The following example, provided as part of the GNAT examples, shows how
3923 to achieve procedural interfacing between Ada and C++ in both
3924 directions. The C++ class ``A`` has two methods. The first method is exported
3925 to Ada by the means of an extern C wrapper function. The second method
3926 calls an Ada subprogram. On the Ada side, the C++ calls are modelled by
3927 a limited record with a layout comparable to the C++ class. The Ada
3928 subprogram, in turn, calls the C++ method. So, starting from the C++
3929 main program, execution passes back and forth between the two
3930 languages.
3931
3932 Here are the compilation commands:
3933
3934 .. code-block:: sh
3935
3936 $ gnatmake -c simple_cpp_interface
3937 $ g++ -c cpp_main.C
3938 $ g++ -c ex7.C
3939 $ gnatbind -n simple_cpp_interface
3940 $ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ -lstdc++ ex7.o cpp_main.o
3941
3942 Here are the corresponding sources:
3943
3944 .. code-block:: cpp
3945
3946 //cpp_main.C
3947
3948 #include "ex7.h"
3949
3950 extern "C" {
3951 void adainit (void);
3952 void adafinal (void);
3953 void method1 (A *t);
3954 }
3955
3956 void method1 (A *t)
3957 {
3958 t->method1 ();
3959 }
3960
3961 int main ()
3962 {
3963 A obj;
3964 adainit ();
3965 obj.method2 (3030);
3966 adafinal ();
3967 }
3968
3969 .. code-block:: cpp
3970
3971 //ex7.h
3972
3973 class Origin {
3974 public:
3975 int o_value;
3976 };
3977 class A : public Origin {
3978 public:
3979 void method1 (void);
3980 void method2 (int v);
3981 A();
3982 int a_value;
3983 };
3984
3985 .. code-block:: cpp
3986
3987 //ex7.C
3988
3989 #include "ex7.h"
3990 #include <stdio.h>
3991
3992 extern "C" { void ada_method2 (A *t, int v);}
3993
3994 void A::method1 (void)
3995 {
3996 a_value = 2020;
3997 printf ("in A::method1, a_value = %d \\n",a_value);
3998 }
3999
4000 void A::method2 (int v)
4001 {
4002 ada_method2 (this, v);
4003 printf ("in A::method2, a_value = %d \\n",a_value);
4004 }
4005
4006 A::A(void)
4007 {
4008 a_value = 1010;
4009 printf ("in A::A, a_value = %d \\n",a_value);
4010 }
4011
4012 .. code-block:: ada
4013
4014 -- simple_cpp_interface.ads
4015 with System;
4016 package Simple_Cpp_Interface is
4017 type A is limited
4018 record
4019 Vptr : System.Address;
4020 O_Value : Integer;
4021 A_Value : Integer;
4022 end record;
4023 pragma Convention (C, A);
4024
4025 procedure Method1 (This : in out A);
4026 pragma Import (C, Method1);
4027
4028 procedure Ada_Method2 (This : in out A; V : Integer);
4029 pragma Export (C, Ada_Method2);
4030
4031 end Simple_Cpp_Interface;
4032
4033 .. code-block:: ada
4034
4035 -- simple_cpp_interface.adb
4036 package body Simple_Cpp_Interface is
4037
4038 procedure Ada_Method2 (This : in out A; V : Integer) is
4039 begin
4040 Method1 (This);
4041 This.A_Value := V;
4042 end Ada_Method2;
4043
4044 end Simple_Cpp_Interface;
4045
4046
4047 .. _Interfacing_with_C++_constructors:
4048
4049 Interfacing with C++ constructors
4050 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4051
4052 To interface with C++ constructors GNAT provides the
4053 ``pragma CPP_Constructor`` (see the :title:`GNAT_Reference_Manual`
4054 for additional information).
4055 In this section, we present some common uses of C++ constructors
4056 in mixed-languages programs in GNAT.
4057
4058 Let us assume we need to interface with the following
4059 C++ class:
4060
4061 .. code-block:: cpp
4062
4063 class Root {
4064 public:
4065 int a_value;
4066 int b_value;
4067 virtual int Get_Value ();
4068 Root(); // Default constructor
4069 Root(int v); // 1st non-default constructor
4070 Root(int v, int w); // 2nd non-default constructor
4071 };
4072
4073 For this purpose, we can write the following package spec (further
4074 information on how to build this spec is available in
4075 :ref:`Interfacing_with_C++_at_the_Class_Level` and
4076 :ref:`Generating_Ada_Bindings_for_C_and_C++_headers`).
4077
4078 .. code-block:: ada
4079
4080 with Interfaces.C; use Interfaces.C;
4081 package Pkg_Root is
4082 type Root is tagged limited record
4083 A_Value : int;
4084 B_Value : int;
4085 end record;
4086 pragma Import (CPP, Root);
4087
4088 function Get_Value (Obj : Root) return int;
4089 pragma Import (CPP, Get_Value);
4090
4091 function Constructor return Root;
4092 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev");
4093
4094 function Constructor (v : Integer) return Root;
4095 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei");
4096
4097 function Constructor (v, w : Integer) return Root;
4098 pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii");
4099 end Pkg_Root;
4100
4101 On the Ada side, the constructor is represented by a function (whose
4102 name is arbitrary) that returns the classwide type corresponding to
4103 the imported C++ class. Although the constructor is described as a
4104 function, it's typically a procedure with an extra implicit argument
4105 (the object being initialized) at the implementation level. GNAT
4106 issues the appropriate call, whatever it is, to get the object
4107 properly initialized.
4108
4109 Constructors can only appear in the following contexts:
4110
4111 * On the right side of an initialization of an object of type.
4112 * On the right side of an initialization of a record component of type.
4113 * In an Ada 2005 limited aggregate.
4114 * In an Ada 2005 nested limited aggregate.
4115 * In an Ada 2005 limited aggregate that initializes an object built in
4116 place by an extended return statement.
4117
4118 In a declaration of an object whose type is a class imported from C++,
4119 either the default C++ constructor is implicitly called by GNAT or you must
4120 explicitly call the required C++ constructor in the
4121 expression that initializes the object. For example:
4122
4123 .. code-block:: ada
4124
4125 Obj1 : Root;
4126 Obj2 : Root := Constructor;
4127 Obj3 : Root := Constructor (v => 10);
4128 Obj4 : Root := Constructor (30, 40);
4129
4130 The first two declarations are equivalent: in both cases the default C++
4131 constructor is invoked (in the former case the call to the constructor is
4132 implicit and in the latter case the call is explicit in the object
4133 declaration). ``Obj3`` is initialized by the C++ non-default constructor
4134 that takes an integer argument and ``Obj4`` is initialized by the
4135 non-default C++ constructor that takes two integers.
4136
4137 Let's derive the imported C++ class in the Ada side. For example:
4138
4139 .. code-block:: ada
4140
4141 type DT is new Root with record
4142 C_Value : Natural := 2009;
4143 end record;
4144
4145 In this case, you must initialize the components ``DT`` inherited from
4146 the C++ side by a C++ constructor and the additional Ada components
4147 of type DT are initialized by GNAT. The initialization of such an
4148 object is done either by default, or by means of a function returning
4149 an aggregate of type DT, or by means of an extension aggregate.
4150
4151 .. code-block:: ada
4152
4153 Obj5 : DT;
4154 Obj6 : DT := Function_Returning_DT (50);
4155 Obj7 : DT := (Constructor (30,40) with C_Value => 50);
4156
4157 The declaration of ``Obj5`` invokes the default constructors: the
4158 C++ default constructor of the parent type takes care of the initialization
4159 of the components inherited from Root and GNAT takes care of the default
4160 initialization of the additional Ada components of type DT (that is,
4161 ``C_Value`` is initialized to value 2009). The order of invocation of
4162 the constructors is consistent with the order of elaboration required by
4163 Ada and C++. That is, the constructor of the parent type is always called
4164 before the constructor of the derived type.
4165
4166 Let's now consider a record that has components whose type is imported
4167 from C++. For example:
4168
4169 .. code-block:: ada
4170
4171 type Rec1 is limited record
4172 Data1 : Root := Constructor (10);
4173 Value : Natural := 1000;
4174 end record;
4175
4176 type Rec2 (D : Integer := 20) is limited record
4177 Rec : Rec1;
4178 Data2 : Root := Constructor (D, 30);
4179 end record;
4180
4181 The initialization of an object of type ``Rec2`` calls the non-default
4182 C++ constructors specified for the imported components. For example:
4183
4184 .. code-block:: ada
4185
4186 Obj8 : Rec2 (40);
4187
4188 Using Ada 2005, we can use limited aggregates to initialize an object
4189 invoking C++ constructors that differ from those specified in the type
4190 declarations. For example:
4191
4192 .. code-block:: ada
4193
4194 Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16),
4195 others => <>),
4196 others => <>);
4197
4198 The above declaration uses an Ada 2005 limited aggregate to
4199 initialize ``Obj9`` and the C++ constructor that has two integer
4200 arguments is invoked to initialize the ``Data1`` component instead
4201 of the constructor specified in the declaration of type ``Rec1``. In
4202 Ada 2005, the box in the aggregate indicates that unspecified components
4203 are initialized using the expression (if any) available in the component
4204 declaration. That is, in this case discriminant ``D`` is initialized
4205 to value ``20``, ``Value`` is initialized to value 1000, and the
4206 non-default C++ constructor that handles two integers takes care of
4207 initializing component ``Data2`` with values ``20,30``.
4208
4209 In Ada 2005, we can use the extended return statement to build the Ada
4210 equivalent to C++ non-default constructors. For example:
4211
4212 .. code-block:: ada
4213
4214 function Constructor (V : Integer) return Rec2 is
4215 begin
4216 return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20),
4217 others => <>),
4218 others => <>) do
4219 -- Further actions required for construction of
4220 -- objects of type Rec2
4221 ...
4222 end record;
4223 end Constructor;
4224
4225 In this example, we use the extended return statement construct to
4226 build in place the returned object whose components are initialized by
4227 means of a limited aggregate. We could also place any further action
4228 associated with the constructor inside the construct.
4229
4230 .. _Interfacing_with_C++_at_the_Class_Level:
4231
4232 Interfacing with C++ at the Class Level
4233 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4234
4235 In this section, we demonstrate the GNAT features for interfacing with
4236 C++ by means of an example making use of Ada 2005 abstract interface
4237 types. This example consists of a classification of animals; classes
4238 have been used to model our main classification of animals and
4239 interfaces provide support for the management of secondary
4240 classifications. We first demonstrate a case in which the types and
4241 constructors are defined on the C++ side and imported from the Ada
4242 side and then the reverse case.
4243
4244 The root of our derivation is the ``Animal`` class, with a
4245 single private attribute (the ``Age`` of the animal), a constructor,
4246 and two public primitives to set and get the value of this attribute.
4247
4248 .. code-block:: cpp
4249
4250 class Animal {
4251 public:
4252 virtual void Set_Age (int New_Age);
4253 virtual int Age ();
4254 Animal() {Age_Count = 0;};
4255 private:
4256 int Age_Count;
4257 };
4258
4259 Abstract interface types are defined in C++ by means of classes with pure
4260 virtual functions and no data members. In our example we use two
4261 interfaces that provide support for the common management of ``Carnivore``
4262 and ``Domestic`` animals:
4263
4264 .. code-block:: cpp
4265
4266 class Carnivore {
4267 public:
4268 virtual int Number_Of_Teeth () = 0;
4269 };
4270
4271 class Domestic {
4272 public:
4273 virtual void Set_Owner (char* Name) = 0;
4274 };
4275
4276 Using these declarations, we can now say that a ``Dog`` is an animal that is
4277 both Carnivore and Domestic, that is:
4278
4279 .. code-block:: cpp
4280
4281 class Dog : Animal, Carnivore, Domestic {
4282 public:
4283 virtual int Number_Of_Teeth ();
4284 virtual void Set_Owner (char* Name);
4285
4286 Dog(); // Constructor
4287 private:
4288 int Tooth_Count;
4289 char *Owner;
4290 };
4291
4292 In the following examples we assume that the previous declarations are
4293 located in a file named :file:`animals.h`. The following package demonstrates
4294 how to import these C++ declarations from the Ada side:
4295
4296 .. code-block:: ada
4297
4298 with Interfaces.C.Strings; use Interfaces.C.Strings;
4299 package Animals is
4300 type Carnivore is limited interface;
4301 pragma Convention (C_Plus_Plus, Carnivore);
4302 function Number_Of_Teeth (X : Carnivore)
4303 return Natural is abstract;
4304
4305 type Domestic is limited interface;
4306 pragma Convention (C_Plus_Plus, Domestic);
4307 procedure Set_Owner
4308 (X : in out Domestic;
4309 Name : Chars_Ptr) is abstract;
4310
4311 type Animal is tagged limited record
4312 Age : Natural;
4313 end record;
4314 pragma Import (C_Plus_Plus, Animal);
4315
4316 procedure Set_Age (X : in out Animal; Age : Integer);
4317 pragma Import (C_Plus_Plus, Set_Age);
4318
4319 function Age (X : Animal) return Integer;
4320 pragma Import (C_Plus_Plus, Age);
4321
4322 function New_Animal return Animal;
4323 pragma CPP_Constructor (New_Animal);
4324 pragma Import (CPP, New_Animal, "_ZN6AnimalC1Ev");
4325
4326 type Dog is new Animal and Carnivore and Domestic with record
4327 Tooth_Count : Natural;
4328 Owner : Chars_Ptr;
4329 end record;
4330 pragma Import (C_Plus_Plus, Dog);
4331
4332 function Number_Of_Teeth (A : Dog) return Natural;
4333 pragma Import (C_Plus_Plus, Number_Of_Teeth);
4334
4335 procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
4336 pragma Import (C_Plus_Plus, Set_Owner);
4337
4338 function New_Dog return Dog;
4339 pragma CPP_Constructor (New_Dog);
4340 pragma Import (CPP, New_Dog, "_ZN3DogC2Ev");
4341 end Animals;
4342
4343 Thanks to the compatibility between GNAT run-time structures and the
4344 C++ ABI, interfacing with these C++ classes is easy. The only
4345 requirement is that you must declare all the primitives and components
4346 exactly in the same order in the two languages.
4347
4348 Regarding the abstract interfaces, we must indicate to the GNAT
4349 compiler, by means of a ``pragma Convention (C_Plus_Plus)``, that the
4350 convention used to pass the arguments to the called primitives will be
4351 the same as for C++. For the imported classes, we use ``pragma
4352 Import`` with convention ``C_Plus_Plus`` to indicate they have been
4353 defined on the C++ side; this is required because the dispatch table
4354 associated with these tagged types will be built in the C++ side and
4355 therefore will not contain the predefined Ada primitives which Ada
4356 would otherwise expect.
4357
4358 As the reader can see, there is no need to indicate the C++ mangled names
4359 associated with each subprogram because it is assumed that all the calls to
4360 these primitives will be dispatching calls. The only exception is the
4361 constructor, which we must register with the compiler by means of
4362 ``pragma CPP_Constructor`` and we need to provide its associated C++
4363 mangled name because the Ada compiler generates direct calls to it.
4364
4365 With the above packages, we can now declare objects of type ``Dog`` on
4366 the Ada side and dispatch calls to the corresponding subprograms on
4367 the C++ side. We can also extend the tagged type ``Dog`` with further
4368 fields and primitives and override some of its C++ primitives on the
4369 Ada side. For example, here we have a type derivation defined on the
4370 Ada side that inherits all the dispatching primitives of the ancestor
4371 from the C++ side.
4372
4373 .. code-block:: ada
4374
4375 with Animals; use Animals;
4376 package Vaccinated_Animals is
4377 type Vaccinated_Dog is new Dog with null record;
4378 function Vaccination_Expired (A : Vaccinated_Dog) return Boolean;
4379 end Vaccinated_Animals;
4380
4381 It is important to note that, because of the ABI compatibility, we
4382 don't need to add any further information to indicate either the object
4383 layout or the dispatch table entry associated with each dispatching operation.
4384
4385 Now let's define all the types and constructors on the Ada side and export
4386 them to C++, using the same hierarchy of our previous example:
4387
4388 .. code-block:: ada
4389
4390 with Interfaces.C.Strings;
4391 use Interfaces.C.Strings;
4392 package Animals is
4393 type Carnivore is limited interface;
4394 pragma Convention (C_Plus_Plus, Carnivore);
4395 function Number_Of_Teeth (X : Carnivore)
4396 return Natural is abstract;
4397
4398 type Domestic is limited interface;
4399 pragma Convention (C_Plus_Plus, Domestic);
4400 procedure Set_Owner
4401 (X : in out Domestic;
4402 Name : Chars_Ptr) is abstract;
4403
4404 type Animal is tagged record
4405 Age : Natural;
4406 end record;
4407 pragma Convention (C_Plus_Plus, Animal);
4408
4409 procedure Set_Age (X : in out Animal; Age : Integer);
4410 pragma Export (C_Plus_Plus, Set_Age);
4411
4412 function Age (X : Animal) return Integer;
4413 pragma Export (C_Plus_Plus, Age);
4414
4415 function New_Animal return Animal'Class;
4416 pragma Export (C_Plus_Plus, New_Animal);
4417
4418 type Dog is new Animal and Carnivore and Domestic with record
4419 Tooth_Count : Natural;
4420 Owner : String (1 .. 30);
4421 end record;
4422 pragma Convention (C_Plus_Plus, Dog);
4423
4424 function Number_Of_Teeth (A : Dog) return Natural;
4425 pragma Export (C_Plus_Plus, Number_Of_Teeth);
4426
4427 procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
4428 pragma Export (C_Plus_Plus, Set_Owner);
4429
4430 function New_Dog return Dog'Class;
4431 pragma Export (C_Plus_Plus, New_Dog);
4432 end Animals;
4433
4434 Compared with our previous example the only differences are the use of
4435 ``pragma Convention`` (instead of ``pragma Import``) and the use of
4436 ``pragma Export`` to indicate to the GNAT compiler that the primitives will
4437 be available to C++. Thanks to the ABI compatibility, on the C++ side there is
4438 nothing else to be done; as explained above, the only requirement is that all
4439 the primitives and components are declared in exactly the same order.
4440
4441 For completeness, let us see a brief C++ main program that uses the
4442 declarations available in :file:`animals.h` (presented in our first example) to
4443 import and use the declarations from the Ada side, properly initializing and
4444 finalizing the Ada run-time system along the way:
4445
4446 .. code-block:: cpp
4447
4448 #include "animals.h"
4449 #include <iostream>
4450 using namespace std;
4451
4452 void Check_Carnivore (Carnivore *obj) {...}
4453 void Check_Domestic (Domestic *obj) {...}
4454 void Check_Animal (Animal *obj) {...}
4455 void Check_Dog (Dog *obj) {...}
4456
4457 extern "C" {
4458 void adainit (void);
4459 void adafinal (void);
4460 Dog* new_dog ();
4461 }
4462
4463 void test ()
4464 {
4465 Dog *obj = new_dog(); // Ada constructor
4466 Check_Carnivore (obj); // Check secondary DT
4467 Check_Domestic (obj); // Check secondary DT
4468 Check_Animal (obj); // Check primary DT
4469 Check_Dog (obj); // Check primary DT
4470 }
4471
4472 int main ()
4473 {
4474 adainit (); test(); adafinal ();
4475 return 0;
4476 }
4477
4478 .. _Partition_Wide_Settings:
4479
4480 Partition-Wide Settings
4481 -----------------------
4482
4483 When building a mixed-language application, you must be aware that
4484 Ada enforces some partition-wide settings that may implicitly impact the
4485 behavior of the other languages.
4486
4487 This is the case for certain signals that are reserved to the
4488 implementation to implement proper Ada semantics (such as the behavior
4489 of ``abort`` statements).
4490 It means that the Ada part of the application may override signal handlers
4491 that were previously installed by either the system or by other user code.
4492
4493 If your application requires that either system or user signals be preserved,
4494 you need to instruct the Ada part not to install its own signal handler.
4495 You do this using ``pragma Interrupt_State`` that provides a general
4496 mechanism for overriding such uses of interrupts.
4497
4498 Additionally, you can use pragma ``Interrupts_System_By_Default`` to default
4499 all interrupts to System.
4500
4501 The set of interrupts for which the Ada run-time library sets a specific signal
4502 handler is the following:
4503
4504 * Ada.Interrupts.Names.SIGSEGV
4505 * Ada.Interrupts.Names.SIGBUS
4506 * Ada.Interrupts.Names.SIGFPE
4507 * Ada.Interrupts.Names.SIGILL
4508 * Ada.Interrupts.Names.SIGABRT
4509
4510 You can instruct the run-time library not to install its signal
4511 handler for a particular signal by using the configuration pragma
4512 ``Interrupt_State`` in the Ada code. For example:
4513
4514 .. code-block:: ada
4515
4516 pragma Interrupt_State (Ada.Interrupts.Names.SIGSEGV, System);
4517 pragma Interrupt_State (Ada.Interrupts.Names.SIGBUS, System);
4518 pragma Interrupt_State (Ada.Interrupts.Names.SIGFPE, System);
4519 pragma Interrupt_State (Ada.Interrupts.Names.SIGILL, System);
4520 pragma Interrupt_State (Ada.Interrupts.Names.SIGABRT, System);
4521
4522 Obviously, if the Ada run-time system cannot set these handlers it comes with the
4523 drawback of not fully preserving Ada semantics. ``SIGSEGV``, ``SIGBUS``, ``SIGFPE``
4524 and ``SIGILL`` are used to raise corresponding Ada exceptions in the application,
4525 while ``SIGABRT`` is used to asynchronously abort an action or a task.
4526
4527 .. _Generating_Ada_Bindings_for_C_and_C++_headers:
4528
4529 Generating Ada Bindings for C and C++ headers
4530 ---------------------------------------------
4531
4532 .. index:: Binding generation (for C and C++ headers)
4533 .. index:: C headers (binding generation)
4534 .. index:: C++ headers (binding generation)
4535
4536 GNAT includes a binding generator for C and C++ headers, which is
4537 intended to do 95% of the tedious work of generating Ada specs from C
4538 or C++ header files.
4539
4540 This capability is not intended to generate 100% correct Ada specs and
4541 it will in some cases require you to make manual adjustments, although
4542 it can often be used out of the box in practice.
4543
4544 Some of the known limitations include:
4545
4546 * only very simple character constant macros are translated into Ada
4547 constants. Function macros (macros with arguments) are partially translated
4548 as comments, to be completed manually if needed.
4549 * some extensions (e.g. vector types) are not supported
4550 * pointers to pointers are mapped to ``System.Address``
4551 * identifiers with names that are identical except for casing may generate
4552 compilation errors (e.g. ``shm_get`` vs ``SHM_GET``).
4553
4554 The code is generated using Ada 2012 syntax, which makes it easier to interface
4555 with other languages. In most cases, you can still use the generated binding
4556 even if your code is compiled using earlier versions of Ada (e.g. ``-gnat95``).
4557
4558 .. _Running_the_binding_generator:
4559
4560 Running the Binding Generator
4561 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4562
4563 The binding generator is part of the ``gcc`` compiler and you can
4564 invoke it via the :switch:`-fdump-ada-spec` switch, which generates Ada
4565 spec files for the header files specified on the command line and all
4566 header files needed by these files transitively. For example:
4567
4568 .. code-block:: sh
4569
4570 $ gcc -c -fdump-ada-spec -C /usr/include/time.h
4571 $ gcc -c *.ads
4572
4573 generates, under GNU/Linux, the following files: :file:`time_h.ads`,
4574 :file:`bits_time_h.ads`, :file:`stddef_h.ads`, :file:`bits_types_h.ads` which
4575 correspond to the files :file:`/usr/include/time.h`, and
4576 :file:`/usr/include/bits/time.h` and then compile these Ada specs.
4577 The name of the Ada specs is consistent with the relative path
4578 under :file:`/usr/include/` of the header files. This behavior is specific to
4579 paths ending with :file:`/include/`; in all the other cases, the name of the
4580 Ada specs is derived from the simple name of the header files instead.
4581
4582 The :switch:`-C` switch tells ``gcc`` to extract comments from headers,
4583 and attempt to generate corresponding Ada comments.
4584
4585 If you want to generate a single Ada file and not the transitive closure, you
4586 can use instead the :switch:`-fdump-ada-spec-slim` switch.
4587
4588 You can optionally specify a parent unit, of which all generated units will
4589 be children, using :switch:`-fada-spec-parent={unit}`.
4590
4591 The simple ``gcc``-based command works only for C headers. For C++ headers
4592 you need to use either the ``g++`` command or the combination ``gcc -x c++``.
4593
4594 In some cases, the generated bindings will be more complete or more meaningful
4595 when defining some macros, which you can do via the :switch:`-D` switch. This
4596 is for example the case with :file:`Xlib.h` under GNU/Linux:
4597
4598 .. code-block:: sh
4599
4600 $ gcc -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
4601
4602 The above generates more complete bindings than a call without
4603 the :switch:`-DXLIB_ILLEGAL_ACCESS` switch.
4604
4605 In other cases, you can't parse a header file in a stand-alone
4606 manner because other include files need to be included first. In this
4607 case, the solution is to create a small header file including the needed
4608 ``#include`` and possible ``#define`` directives. For example, to
4609 generate Ada bindings for :file:`readline/readline.h`, you need to first
4610 include :file:`stdio.h`, so you can create a file with the following two
4611 lines in e.g. :file:`readline1.h`:
4612
4613 .. code-block:: cpp
4614
4615 #include <stdio.h>
4616 #include <readline/readline.h>
4617
4618 and then generate Ada bindings from this file:
4619
4620 .. code-block:: sh
4621
4622 $ gcc -c -fdump-ada-spec readline1.h
4623
4624
4625 .. _Generating_bindings_for_C++_headers:
4626
4627 Generating Bindings for C++ Headers
4628 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4629
4630 Generating bindings for C++ headers is done using the same options, but
4631 with the ``g++`` compiler. Note that generating Ada spec from C++ headers is a
4632 much more complex job and support for C++ headers is much more limited that
4633 support for C headers. As a result, you will need to modify the resulting
4634 bindings by hand more extensively when using C++ headers.
4635
4636 In this mode, C++ classes are mapped to Ada tagged types, constructors
4637 are mapped using the ``CPP_Constructor`` pragma, and when possible,
4638 multiple inheritance of abstract classes are mapped to Ada interfaces
4639 (see the *Interfacing to C++* section in the :title:`GNAT Reference Manual`
4640 for additional information on interfacing to C++).
4641
4642 For example, given the following C++ header file:
4643
4644 .. code-block:: cpp
4645
4646 class Carnivore {
4647 public:
4648 virtual int Number_Of_Teeth () = 0;
4649 };
4650
4651 class Domestic {
4652 public:
4653 virtual void Set_Owner (char* Name) = 0;
4654 };
4655
4656 class Animal {
4657 public:
4658 int Age_Count;
4659 virtual void Set_Age (int New_Age);
4660 };
4661
4662 class Dog : Animal, Carnivore, Domestic {
4663 public:
4664 int Tooth_Count;
4665 char *Owner;
4666
4667 virtual int Number_Of_Teeth ();
4668 virtual void Set_Owner (char* Name);
4669
4670 Dog();
4671 };
4672
4673 The corresponding Ada code is generated:
4674
4675 .. code-block:: ada
4676
4677 package Class_Carnivore is
4678 type Carnivore is limited interface;
4679 pragma Import (CPP, Carnivore);
4680
4681 function Number_Of_Teeth (this : access Carnivore) return int is abstract;
4682 end;
4683 use Class_Carnivore;
4684
4685 package Class_Domestic is
4686 type Domestic is limited interface;
4687 pragma Import (CPP, Domestic);
4688
4689 procedure Set_Owner
4690 (this : access Domestic;
4691 Name : Interfaces.C.Strings.chars_ptr) is abstract;
4692 end;
4693 use Class_Domestic;
4694
4695 package Class_Animal is
4696 type Animal is tagged limited record
4697 Age_Count : aliased int;
4698 end record;
4699 pragma Import (CPP, Animal);
4700
4701 procedure Set_Age (this : access Animal; New_Age : int);
4702 pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi");
4703 end;
4704 use Class_Animal;
4705
4706 package Class_Dog is
4707 type Dog is new Animal and Carnivore and Domestic with record
4708 Tooth_Count : aliased int;
4709 Owner : Interfaces.C.Strings.chars_ptr;
4710 end record;
4711 pragma Import (CPP, Dog);
4712
4713 function Number_Of_Teeth (this : access Dog) return int;
4714 pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv");
4715
4716 procedure Set_Owner
4717 (this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
4718 pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");
4719
4720 function New_Dog return Dog;
4721 pragma CPP_Constructor (New_Dog);
4722 pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
4723 end;
4724 use Class_Dog;
4725
4726
4727 .. _Switches_for_Ada_Binding_Generation:
4728
4729 Switches
4730 ^^^^^^^^
4731
4732 .. index:: -fdump-ada-spec (gcc)
4733
4734 :switch:`-fdump-ada-spec`
4735 Generate Ada spec files for the given header files transitively (including
4736 all header files that these headers depend upon).
4737
4738 .. index:: -fdump-ada-spec-slim (gcc)
4739
4740 :switch:`-fdump-ada-spec-slim`
4741 Only generate Ada spec files for the header files specified on the
4742 command line.
4743
4744 .. index:: -fada-spec-parent (gcc)
4745
4746 :switch:`-fada-spec-parent={unit}`
4747 Specifies that all files generated by :switch:`-fdump-ada-spec` are
4748 to be child units of the specified parent unit.
4749
4750 .. index:: -C (gcc)
4751
4752 :switch:`-C`
4753 Extract comments from headers and generate Ada comments in the Ada spec files.
4754
4755 .. _Generating_C_Headers_for_Ada_Specifications:
4756
4757 Generating C Headers for Ada Specifications
4758 -------------------------------------------
4759
4760 .. index:: Binding generation (for Ada specs)
4761 .. index:: C headers (binding generation)
4762
4763 GNAT includes a C header generator for Ada specifications that
4764 supports Ada types that have a direct mapping to C types. This
4765 specifically includes support for:
4766
4767 * Scalar types
4768 * Constrained arrays
4769 * Records (untagged)
4770 * Composition of the above types
4771 * Constant declarations
4772 * Object declarations
4773 * Subprogram declarations
4774
4775 Running the C Header Generator
4776 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4777
4778 The C header generator is part of the GNAT compiler and can be invoked via
4779 the :switch:`-gnatceg` switch, which generates a :file:`.h`
4780 file corresponding to the given input file (Ada spec or body). Note that
4781 only spec files are processed, so giving a spec or a body file
4782 as input is equivalent. For example:
4783
4784 .. code-block:: sh
4785
4786 $ gcc -c -gnatceg pack1.ads
4787
4788 generates a self-contained file called :file:`pack1.h` including
4789 common definitions from the Ada Standard package followed by the
4790 definitions included in :file:`pack1.ads` as well as all the other units
4791 withed by this file.
4792
4793 For instance, given the following Ada files:
4794
4795 .. code-block:: ada
4796
4797 package Pack2 is
4798 type Int is range 1 .. 10;
4799 end Pack2;
4800
4801 .. code-block:: ada
4802
4803 with Pack2;
4804
4805 package Pack1 is
4806 type Rec is record
4807 Field1, Field2 : Pack2.Int;
4808 end record;
4809
4810 Global : Rec := (1, 2);
4811
4812 procedure Proc1 (R : Rec);
4813 procedure Proc2 (R : in out Rec);
4814 end Pack1;
4815
4816 The above ``gcc`` command generates the following :file:`pack1.h` file:
4817
4818 .. code-block:: c
4819
4820 /* Standard definitions skipped */
4821 #ifndef PACK2_ADS
4822 #define PACK2_ADS
4823 typedef short_short_integer pack2__TintB;
4824 typedef pack2__TintB pack2__int;
4825 #endif /* PACK2_ADS */
4826
4827 #ifndef PACK1_ADS
4828 #define PACK1_ADS
4829 typedef struct _pack1__rec {
4830 pack2__int field1;
4831 pack2__int field2;
4832 } pack1__rec;
4833 extern pack1__rec pack1__global;
4834 extern void pack1__proc1(const pack1__rec r);
4835 extern void pack1__proc2(pack1__rec *r);
4836 #endif /* PACK1_ADS */
4837
4838 You can then ``include`` :file:`pack1.h` from a C source file and use the types,
4839 call subprograms, reference objects, and constants.
4840
4841 .. _GNAT_and_Other_Compilation_Models:
4842
4843 GNAT and Other Compilation Models
4844 =================================
4845
4846 This section compares the GNAT model with the approaches taken in
4847 other environments: first the C/C++ model and then the mechanism that
4848 has been used in other Ada systems, in particular those traditionally
4849 used for Ada 83.
4850
4851 .. _Comparison_between_GNAT_and_C/C++_Compilation_Models:
4852
4853 Comparison between GNAT and C/C++ Compilation Models
4854 ----------------------------------------------------
4855
4856 The GNAT compilation model is close to the C and C++ models. You can
4857 think of Ada specs as corresponding to header files in C. As in C, you
4858 don't need to compile specs; they are compiled when they are used. The
4859 Ada |with| is similar in effect to the ``#include`` of a C header.
4860
4861 One notable difference is that, in Ada, you may compile specs separately
4862 to check them for semantic and syntactic accuracy. This is not always
4863 possible with C headers because they are fragments of programs that have
4864 less specific syntactic or semantic rules.
4865
4866 The other major difference is the requirement for running the binder,
4867 which performs two important functions. First, it checks for
4868 consistency. In C or C++, the only defense against assembling
4869 inconsistent programs lies outside the compiler, in a :file:`makefile`, for
4870 example. The binder satisfies the Ada requirement that it be impossible
4871 to construct an inconsistent program when the compiler is used in normal
4872 mode.
4873
4874 .. index:: Elaboration order control
4875
4876 The other important function of the binder is to deal with elaboration
4877 issues. There are also elaboration issues in C++ that are handled
4878 automatically. This automatic handling has the advantage of being
4879 simpler to use, but the C++ programmer has no control over elaboration.
4880 Where ``gnatbind`` might complain there was no valid order of
4881 elaboration, a C++ compiler would simply construct a program that
4882 malfunctioned at run time.
4883
4884 .. _Comparison_between_GNAT_and_Conventional_Ada_Library_Models:
4885
4886 Comparison between GNAT and Conventional Ada Library Models
4887 -----------------------------------------------------------
4888
4889 This section is intended for Ada programmers who have
4890 used an Ada compiler implementing the traditional Ada library
4891 model, as described in the Ada Reference Manual.
4892
4893 .. index:: GNAT library
4894
4895 In GNAT, there is no 'library' in the normal sense. Instead, the set of
4896 source files themselves acts as the library. Compiling Ada programs does
4897 not generate any centralized information, but rather an object file and
4898 a :file:`.ali` file, which are of interest only to the binder and linker.
4899 In a traditional system, the compiler reads information not only from
4900 the source file being compiled but also from the centralized library.
4901 This means that the effect of a compilation depends on what has been
4902 previously compiled. In particular:
4903
4904 * When a unit is |withed|, the unit seen by the compiler corresponds
4905 to the version of the unit most recently compiled into the library.
4906
4907 * Inlining is effective only if the necessary body has already been
4908 compiled into the library.
4909
4910 * Compiling a unit may obsolete other units in the library.
4911
4912 In GNAT, compiling one unit never affects the compilation of any other
4913 units because the compiler reads only source files. Only changes to source
4914 files can affect the results of a compilation. In particular:
4915
4916 * When a unit is |withed|, the unit seen by the compiler corresponds
4917 to the source version of the unit that is currently accessible to the
4918 compiler.
4919
4920 .. index:: Inlining
4921
4922 * Inlining requires the appropriate source files for the package or
4923 subprogram bodies to be available to the compiler. Inlining is always
4924 effective, independent of the order in which units are compiled.
4925
4926 * Compiling a unit never affects any other compilations. The editing of
4927 sources may cause previous compilations to be out of date if they
4928 depended on the source file being modified.
4929
4930 The most important result of these differences is that order of compilation
4931 is never significant in GNAT. There is no situation in which you are
4932 required to do one compilation before another. What shows up as order of
4933 compilation requirements in the traditional Ada library becomes, in
4934 GNAT, simple source dependencies; in other words, there is only a set
4935 of rules saying what source files must be present when a file is
4936 compiled.
4937
4938
4939 .. _Using_GNAT_Files_with_External_Tools:
4940
4941 Using GNAT Files with External Tools
4942 ====================================
4943
4944 This section explains how files that are produced by GNAT may be
4945 used with tools designed for other languages.
4946
4947
4948 .. _Using_Other_Utility_Programs_with_GNAT:
4949
4950 Using Other Utility Programs with GNAT
4951 --------------------------------------
4952
4953 The object files generated by GNAT are in standard system format and, in
4954 particular, the debugging information uses this format. This means
4955 programs generated by GNAT can be used with existing utilities that
4956 depend on these formats.
4957
4958 In general, any utility program that works with C will also often work with
4959 Ada programs generated by GNAT. This includes software utilities such as
4960 ``gprof`` (a profiling program), ``gdb`` (the FSF debugger), and utilities such
4961 as ``Purify``.
4962
4963
4964 .. _The_External_Symbol_Naming_Scheme_of_GNAT:
4965
4966 The External Symbol Naming Scheme of GNAT
4967 -----------------------------------------
4968
4969 To interpret the output from GNAT when using tools that are
4970 originally intended for use with other languages, you need to
4971 understand the conventions used to generate link names from the Ada
4972 entity names.
4973
4974 All link names are in all lowercase. With the exception of library
4975 procedure names, the mechanism used is simply to use the full expanded
4976 Ada name with dots replaced by double underscores. For example, suppose
4977 we have the following package spec:
4978
4979 .. code-block:: ada
4980
4981 package QRS is
4982 MN : Integer;
4983 end QRS;
4984
4985 .. index:: pragma Export
4986
4987 The variable ``MN`` has a full expanded Ada name of ``QRS.MN``, so
4988 the corresponding link name is ``qrs__mn``.
4989 Of course if you use a pragma ``Export``, you maye override this:
4990
4991 .. code-block:: ada
4992
4993 package Exports is
4994 Var1 : Integer;
4995 pragma Export (Var1, C, External_Name => "var1_name");
4996 Var2 : Integer;
4997 pragma Export (Var2, C, Link_Name => "var2_link_name");
4998 end Exports;
4999
5000 In this case, the link name for ``Var1`` is whatever link name the
5001 C compiler would assign for the C function ``var1_name``. This typically
5002 would be either ``var1_name`` or ``_var1_name``, depending on operating
5003 system conventions, but other possibilities exist. The link name for
5004 ``Var2`` is ``var2_link_name``, and this is not operating system
5005 dependent.
5006
5007 One exception occurs for library level procedures. A potential ambiguity
5008 arises between the required name ``_main`` for the C main program,
5009 and the name we would otherwise assign to an Ada library level procedure
5010 called ``Main`` (which might well not be the main program).
5011
5012 To avoid this ambiguity, GNAT adds the prefix ``_ada_`` to such
5013 names. So if we have a library level procedure such as:
5014
5015 .. code-block:: ada
5016
5017 procedure Hello (S : String);
5018
5019 the external name of this procedure is ``_ada_hello``.