GCC v8.2
[gcc.git] / gcc / ada / doc / gnat_ugn / the_gnat_compilation_model.rst
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 will
72 recognize 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 that are 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 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 will 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 U.S. 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 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 *Upper-Half Coding*
230   .. index:: Upper-Half Coding
231
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 *Shift JIS Coding*
240   .. index:: Shift JIS Coding
241
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. Only characters defined in the JIS code set table can be
248   used with this encoding method.
249
250
251 *EUC Coding*
252   .. index:: EUC Coding
253
254   A wide character is represented by a two-character sequence
255   ``16#ab#`` and
256   ``16#cd#``, with both characters being in the upper half. The internal
257   character code is the corresponding JIS character according to the EUC
258   encoding algorithm. Only characters defined in the JIS code set table
259   can be used with this encoding method.
260
261
262 *UTF-8 Coding*
263   A wide character is represented using
264   UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
265   10646-1/Am.2. Depending on the character value, the representation
266   is a one, two, or three byte sequence::
267
268     16#0000#-16#007f#: 2#0xxxxxxx#
269     16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
270     16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
271
272   where the ``xxx`` bits correspond to the left-padded bits of the
273   16-bit character value. Note that all lower half ASCII characters
274   are represented as ASCII bytes and all upper half characters and
275   other wide characters are represented as sequences of upper-half
276   (The full UTF-8 scheme allows for encoding 31-bit characters as
277   6-byte sequences, and in the following section on wide wide
278   characters, the use of these sequences is documented).
279
280
281 *Brackets Coding*
282   In this encoding, a wide character is represented by the following eight
283   character sequence::
284
285     [ " a b c d " ]
286
287   where ``a``, ``b``, ``c``, ``d`` are the four hexadecimal
288   characters (using uppercase letters) of the wide character code. For
289   example, ['A345'] is used to represent the wide character with code
290   ``16#A345#``. It is also possible (though not required) to use the
291   Brackets coding for upper half characters. For example, the code
292   ``16#A3#`` can be represented as ``['A3']``.
293
294   This scheme is compatible with use of the full Wide_Character set,
295   and is also the method used for wide character encoding in some standard
296   ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
297
298 .. note::
299
300   Some of these coding schemes do not permit the full use of the
301   Ada character set. For example, neither Shift JIS nor EUC allow the
302   use of the upper half of the Latin-1 set.
303
304 .. _Wide_Wide_Character_Encodings:
305
306 Wide_Wide_Character Encodings
307 -----------------------------
308
309 GNAT allows wide wide character codes to appear in character and string
310 literals, and also optionally in identifiers, by means of the following
311 possible encoding schemes:
312
313 *UTF-8 Coding*
314   A wide character is represented using
315   UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
316   10646-1/Am.2. Depending on the character value, the representation
317   of character codes with values greater than 16#FFFF# is a
318   is a four, five, or six byte sequence::
319
320     16#01_0000#-16#10_FFFF#:     11110xxx 10xxxxxx 10xxxxxx
321                                  10xxxxxx
322     16#0020_0000#-16#03FF_FFFF#: 111110xx 10xxxxxx 10xxxxxx
323                                  10xxxxxx 10xxxxxx
324     16#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx
325                                  10xxxxxx 10xxxxxx 10xxxxxx
326
327
328   where the ``xxx`` bits correspond to the left-padded bits of the
329   32-bit character value.
330
331 *Brackets Coding*
332   In this encoding, a wide wide character is represented by the following ten or
333   twelve byte character sequence::
334
335     [ " a b c d e f " ]
336     [ " a b c d e f g h " ]
337
338   where ``a-h`` are the six or eight hexadecimal
339   characters (using uppercase letters) of the wide wide character code. For
340   example, ["1F4567"] is used to represent the wide wide character with code
341   ``16#001F_4567#``.
342
343   This scheme is compatible with use of the full Wide_Wide_Character set,
344   and is also the method used for wide wide character encoding in some standard
345   ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
346
347
348 .. _File_Naming_Topics_and_Utilities:
349
350 File Naming Topics and Utilities
351 ================================
352
353 GNAT has a default file naming scheme and also provides the user with
354 a high degree of control over how the names and extensions of the
355 source files correspond to the Ada compilation units that they contain.
356
357
358 .. _File_Naming_Rules:
359
360 File Naming Rules
361 -----------------
362
363 The default file name is determined by the name of the unit that the
364 file contains. The name is formed by taking the full expanded name of
365 the unit and replacing the separating dots with hyphens and using
366 lowercase for all letters.
367
368 An exception arises if the file name generated by the above rules starts
369 with one of the characters
370 ``a``, ``g``, ``i``, or ``s``, and the second character is a
371 minus. In this case, the character tilde is used in place
372 of the minus. The reason for this special rule is to avoid clashes with
373 the standard names for child units of the packages System, Ada,
374 Interfaces, and GNAT, which use the prefixes
375 ``s-``, ``a-``, ``i-``, and ``g-``,
376 respectively.
377
378 The file extension is :file:`.ads` for a spec and
379 :file:`.adb` for a body. The following table shows some
380 examples of these rules.
381
382    ============================ ===============================
383    Source File                   Ada Compilation Unit
384    ---------------------------- -------------------------------
385    :file:`main.ads`              Main (spec)
386    :file:`main.adb`              Main (body)
387    :file:`arith_functions.ads`   Arith_Functions (package spec)
388    :file:`arith_functions.adb`   Arith_Functions (package body)
389    :file:`func-spec.ads`         Func.Spec (child package spec)
390    :file:`func-spec.adb`         Func.Spec (child package body)
391    :file:`main-sub.adb`          Sub (subunit of Main)
392    :file:`a~bad.adb`             A.Bad (child package body)
393    ============================ ===============================
394
395 Following these rules can result in excessively long
396 file names if corresponding
397 unit names are long (for example, if child units or subunits are
398 heavily nested). An option is available to shorten such long file names
399 (called file name 'krunching'). This may be particularly useful when
400 programs being developed with GNAT are to be used on operating systems
401 with limited file name lengths. :ref:`Using_gnatkr`.
402
403 Of course, no file shortening algorithm can guarantee uniqueness over
404 all possible unit names; if file name krunching is used, it is your
405 responsibility to ensure no name clashes occur. Alternatively you
406 can specify the exact file names that you want used, as described
407 in the next section. Finally, if your Ada programs are migrating from a
408 compiler with a different naming convention, you can use the gnatchop
409 utility to produce source files that follow the GNAT naming conventions.
410 (For details see :ref:`Renaming_Files_with_gnatchop`.)
411
412 Note: in the case of Windows or Mac OS operating systems, case is not
413 significant. So for example on Windows if the canonical name is
414 :file:`main-sub.adb`, you can use the file name :file:`Main-Sub.adb` instead.
415 However, case is significant for other operating systems, so for example,
416 if you want to use other than canonically cased file names on a Unix system,
417 you need to follow the procedures described in the next section.
418
419 .. _Using_Other_File_Names:
420
421 Using Other File Names
422 ----------------------
423
424 .. index:: File names
425
426 In the previous section, we have described the default rules used by
427 GNAT to determine the file name in which a given unit resides. It is
428 often convenient to follow these default rules, and if you follow them,
429 the compiler knows without being explicitly told where to find all
430 the files it needs.
431
432 .. index:: Source_File_Name pragma
433
434 However, in some cases, particularly when a program is imported from
435 another Ada compiler environment, it may be more convenient for the
436 programmer to specify which file names contain which units. GNAT allows
437 arbitrary file names to be used by means of the Source_File_Name pragma.
438 The form of this pragma is as shown in the following examples:
439
440 .. code-block:: ada
441
442       pragma Source_File_Name (My_Utilities.Stacks,
443         Spec_File_Name => "myutilst_a.ada");
444       pragma Source_File_name (My_Utilities.Stacks,
445         Body_File_Name => "myutilst.ada");
446
447 As shown in this example, the first argument for the pragma is the unit
448 name (in this example a child unit). The second argument has the form
449 of a named association. The identifier
450 indicates whether the file name is for a spec or a body;
451 the file name itself is given by a string literal.
452
453 The source file name pragma is a configuration pragma, which means that
454 normally it will be placed in the :file:`gnat.adc`
455 file used to hold configuration
456 pragmas that apply to a complete compilation environment.
457 For more details on how the :file:`gnat.adc` file is created and used
458 see :ref:`Handling_of_Configuration_Pragmas`.
459
460 .. index:: gnat.adc
461
462 GNAT allows completely arbitrary file names to be specified using the
463 source file name pragma. However, if the file name specified has an
464 extension other than :file:`.ads` or :file:`.adb` it is necessary to use
465 a special syntax when compiling the file. The name in this case must be
466 preceded by the special sequence ``-x`` followed by a space and the name
467 of the language, here ``ada``, as in:
468
469 .. code-block:: sh
470
471      $ gcc -c -x ada peculiar_file_name.sim
472
473 ``gnatmake`` handles non-standard file names in the usual manner (the
474 non-standard file name for the main program is simply used as the
475 argument to gnatmake). Note that if the extension is also non-standard,
476 then it must be included in the ``gnatmake`` command, it may not
477 be omitted.
478
479 .. _Alternative_File_Naming_Schemes:
480
481 Alternative File Naming Schemes
482 -------------------------------
483
484 .. index:: File naming schemes, alternative
485
486 .. index:: File names
487
488 The previous section described the use of the ``Source_File_Name``
489 pragma to allow arbitrary names to be assigned to individual source files.
490 However, this approach requires one pragma for each file, and especially in
491 large systems can result in very long :file:`gnat.adc` files, and also create
492 a maintenance problem.
493
494 .. index:: Source_File_Name pragma
495
496 GNAT also provides a facility for specifying systematic file naming schemes
497 other than the standard default naming scheme previously described. An
498 alternative scheme for naming is specified by the use of
499 ``Source_File_Name`` pragmas having the following format:
500
501 .. code-block:: ada
502
503      pragma Source_File_Name (
504         Spec_File_Name  => FILE_NAME_PATTERN
505       [ , Casing          => CASING_SPEC]
506       [ , Dot_Replacement => STRING_LITERAL ] );
507
508      pragma Source_File_Name (
509         Body_File_Name  => FILE_NAME_PATTERN
510       [ , Casing          => CASING_SPEC ]
511       [ , Dot_Replacement => STRING_LITERAL ] ) ;
512
513      pragma Source_File_Name (
514         Subunit_File_Name  => FILE_NAME_PATTERN
515       [ , Casing          => CASING_SPEC ]
516       [ , Dot_Replacement => STRING_LITERAL ] ) ;
517
518      FILE_NAME_PATTERN ::= STRING_LITERAL
519      CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
520
521 The ``FILE_NAME_PATTERN`` string shows how the file name is constructed.
522 It contains a single asterisk character, and the unit name is substituted
523 systematically for this asterisk. The optional parameter
524 ``Casing`` indicates
525 whether the unit name is to be all upper-case letters, all lower-case letters,
526 or mixed-case. If no
527 ``Casing`` parameter is used, then the default is all
528 lower-case.
529
530 The optional ``Dot_Replacement`` string is used to replace any periods
531 that occur in subunit or child unit names. If no ``Dot_Replacement``
532 argument is used then separating dots appear unchanged in the resulting
533 file name.
534 Although the above syntax indicates that the
535 ``Casing`` argument must appear
536 before the ``Dot_Replacement`` argument, but it
537 is also permissible to write these arguments in the opposite order.
538
539 As indicated, it is possible to specify different naming schemes for
540 bodies, specs, and subunits. Quite often the rule for subunits is the
541 same as the rule for bodies, in which case, there is no need to give
542 a separate ``Subunit_File_Name`` rule, and in this case the
543 ``Body_File_name`` rule is used for subunits as well.
544
545 The separate rule for subunits can also be used to implement the rather
546 unusual case of a compilation environment (e.g., a single directory) which
547 contains a subunit and a child unit with the same unit name. Although
548 both units cannot appear in the same partition, the Ada Reference Manual
549 allows (but does not require) the possibility of the two units coexisting
550 in the same environment.
551
552 The file name translation works in the following steps:
553
554 * If there is a specific ``Source_File_Name`` pragma for the given unit,
555   then this is always used, and any general pattern rules are ignored.
556
557 * If there is a pattern type ``Source_File_Name`` pragma that applies to
558   the unit, then the resulting file name will be used if the file exists. If
559   more than one pattern matches, the latest one will be tried first, and the
560   first attempt resulting in a reference to a file that exists will be used.
561
562 * If no pattern type ``Source_File_Name`` pragma that applies to the unit
563   for which the corresponding file exists, then the standard GNAT default
564   naming rules are used.
565
566 As an example of the use of this mechanism, consider a commonly used scheme
567 in which file names are all lower case, with separating periods copied
568 unchanged to the resulting file name, and specs end with :file:`.1.ada`, and
569 bodies end with :file:`.2.ada`. GNAT will follow this scheme if the following
570 two pragmas appear:
571
572 .. code-block:: ada
573
574      pragma Source_File_Name
575        (Spec_File_Name => ".1.ada");
576      pragma Source_File_Name
577        (Body_File_Name => ".2.ada");
578
579 The default GNAT scheme is actually implemented by providing the following
580 default pragmas internally:
581
582 .. code-block:: ada
583
584      pragma Source_File_Name
585        (Spec_File_Name => ".ads", Dot_Replacement => "-");
586      pragma Source_File_Name
587        (Body_File_Name => ".adb", Dot_Replacement => "-");
588
589 Our final example implements a scheme typically used with one of the
590 Ada 83 compilers, where the separator character for subunits was '__'
591 (two underscores), specs were identified by adding :file:`_.ADA`, bodies
592 by adding :file:`.ADA`, and subunits by
593 adding :file:`.SEP`. All file names were
594 upper case. Child units were not present of course since this was an
595 Ada 83 compiler, but it seems reasonable to extend this scheme to use
596 the same double underscore separator for child units.
597
598 .. code-block:: ada
599
600      pragma Source_File_Name
601        (Spec_File_Name => "_.ADA",
602         Dot_Replacement => "__",
603         Casing = Uppercase);
604      pragma Source_File_Name
605        (Body_File_Name => ".ADA",
606         Dot_Replacement => "__",
607         Casing = Uppercase);
608      pragma Source_File_Name
609        (Subunit_File_Name => ".SEP",
610         Dot_Replacement => "__",
611         Casing = Uppercase);
612
613
614 .. index:: ! gnatname
615
616 .. _Handling_Arbitrary_File_Naming_Conventions_with_gnatname:
617
618 Handling Arbitrary File Naming Conventions with ``gnatname``
619 ------------------------------------------------------------
620
621 .. index:: File Naming Conventions
622
623 .. _Arbitrary_File_Naming_Conventions:
624
625 Arbitrary File Naming Conventions
626 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
627
628 The GNAT compiler must be able to know the source file name of a compilation
629 unit.  When using the standard GNAT default file naming conventions
630 (``.ads`` for specs, ``.adb`` for bodies), the GNAT compiler
631 does not need additional information.
632
633 When the source file names do not follow the standard GNAT default file naming
634 conventions, the GNAT compiler must be given additional information through
635 a configuration pragmas file (:ref:`Configuration_Pragmas`)
636 or a project file.
637 When the non-standard file naming conventions are well-defined,
638 a small number of pragmas ``Source_File_Name`` specifying a naming pattern
639 (:ref:`Alternative_File_Naming_Schemes`) may be sufficient. However,
640 if the file naming conventions are irregular or arbitrary, a number
641 of pragma ``Source_File_Name`` for individual compilation units
642 must be defined.
643 To help maintain the correspondence between compilation unit names and
644 source file names within the compiler,
645 GNAT provides a tool ``gnatname`` to generate the required pragmas for a
646 set of files.
647
648 .. _Running_gnatname:
649
650 Running ``gnatname``
651 ^^^^^^^^^^^^^^^^^^^^
652
653 The usual form of the ``gnatname`` command is:
654
655 .. code-block:: sh
656
657       $ gnatname [ switches ]  naming_pattern  [ naming_patterns ]
658           [--and [ switches ]  naming_pattern  [ naming_patterns ]]
659
660
661 All of the arguments are optional. If invoked without any argument,
662 ``gnatname`` will display its usage.
663
664 When used with at least one naming pattern, ``gnatname`` will attempt to
665 find all the compilation units in files that follow at least one of the
666 naming patterns. To find these compilation units,
667 ``gnatname`` will use the GNAT compiler in syntax-check-only mode on all
668 regular files.
669
670 One or several Naming Patterns may be given as arguments to ``gnatname``.
671 Each Naming Pattern is enclosed between double quotes (or single
672 quotes on Windows).
673 A Naming Pattern is a regular expression similar to the wildcard patterns
674 used in file names by the Unix shells or the DOS prompt.
675
676 ``gnatname`` may be called with several sections of directories/patterns.
677 Sections are separated by the switch :switch:`--and`. In each section, there must be
678 at least one pattern. If no directory is specified in a section, the current
679 directory (or the project directory if :switch:`-P` is used) is implied.
680 The options other that the directory switches and the patterns apply globally
681 even if they are in different sections.
682
683 Examples of Naming Patterns are::
684
685      "*.[12].ada"
686      "*.ad[sb]*"
687      "body_*"    "spec_*"
688
689 For a more complete description of the syntax of Naming Patterns,
690 see the second kind of regular expressions described in :file:`g-regexp.ads`
691 (the 'Glob' regular expressions).
692
693 When invoked without the switch :switch:`-P`, ``gnatname`` will create a
694 configuration pragmas file :file:`gnat.adc` in the current working directory,
695 with pragmas ``Source_File_Name`` for each file that contains a valid Ada
696 unit.
697
698 .. _Switches_for_gnatname:
699
700 Switches for ``gnatname``
701 ^^^^^^^^^^^^^^^^^^^^^^^^^
702
703 Switches for ``gnatname`` must precede any specified Naming Pattern.
704
705 You may specify any of the following switches to ``gnatname``:
706
707 .. index:: --version (gnatname)
708
709 :switch:`--version`
710   Display Copyright and version, then exit disregarding all other options.
711
712 .. index:: --help (gnatname)
713
714 :switch:`--help`
715   If :switch:`--version` was not used, display usage, then exit disregarding
716   all other options.
717
718 :switch:`--subdirs={dir}`
719   Real object, library or exec directories are subdirectories <dir> of the
720   specified ones.
721
722 :switch:`--no-backup`
723   Do not create a backup copy of an existing project file.
724
725 :switch:`--and`
726   Start another section of directories/patterns.
727
728 .. index:: -c (gnatname)
729
730 :switch:`-c{filename}`
731   Create a configuration pragmas file :file:`filename` (instead of the default
732   :file:`gnat.adc`).
733   There may be zero, one or more space between :switch:`-c` and
734   :file:`filename`.
735   :file:`filename` may include directory information. :file:`filename` must be
736   writable. There may be only one switch :switch:`-c`.
737   When a switch :switch:`-c` is
738   specified, no switch :switch:`-P` may be specified (see below).
739
740 .. index:: -d (gnatname)
741
742 :switch:`-d{dir}`
743   Look for source files in directory :file:`dir`. There may be zero, one or more
744   spaces between :switch:`-d` and :file:`dir`.
745   :file:`dir` may end with ``/**``, that is it may be of the form
746   ``root_dir/**``. In this case, the directory ``root_dir`` and all of its
747   subdirectories, recursively, have to be searched for sources.
748   When a switch :switch:`-d`
749   is specified, the current working directory will not be searched for source
750   files, unless it is explicitly specified with a :switch:`-d`
751   or :switch:`-D` switch.
752   Several switches :switch:`-d` may be specified.
753   If :file:`dir` is a relative path, it is relative to the directory of
754   the configuration pragmas file specified with switch
755   :switch:`-c`,
756   or to the directory of the project file specified with switch
757   :switch:`-P` or,
758   if neither switch :switch:`-c`
759   nor switch :switch:`-P` are specified, it is relative to the
760   current working directory. The directory
761   specified with switch :switch:`-d` must exist and be readable.
762
763 .. index:: -D (gnatname)
764
765 :switch:`-D{filename}`
766   Look for source files in all directories listed in text file :file:`filename`.
767   There may be zero, one or more spaces between :switch:`-D`
768   and :file:`filename`.
769   :file:`filename` must be an existing, readable text file.
770   Each nonempty line in :file:`filename` must be a directory.
771   Specifying switch :switch:`-D` is equivalent to specifying as many
772   switches :switch:`-d` as there are nonempty lines in
773   :file:`file`.
774
775 :switch:`-eL`
776   Follow symbolic links when processing project files.
777
778   .. index:: -f (gnatname)
779
780 :switch:`-f{pattern}`
781   Foreign patterns. Using this switch, it is possible to add sources of languages
782   other than Ada to the list of sources of a project file.
783   It is only useful if a -P switch is used.
784   For example,
785
786   .. code-block:: sh
787
788      gnatname -Pprj -f"*.c" "*.ada"
789
790   will look for Ada units in all files with the :file:`.ada` extension,
791   and will add to the list of file for project :file:`prj.gpr` the C files
792   with extension :file:`.c`.
793
794   .. index:: -h (gnatname)
795
796 :switch:`-h`
797   Output usage (help) information. The output is written to :file:`stdout`.
798
799   .. index:: -P (gnatname)
800
801 :switch:`-P{proj}`
802   Create or update project file :file:`proj`. There may be zero, one or more space
803   between :switch:`-P` and :file:`proj`. :file:`proj` may include directory
804   information. :file:`proj` must be writable.
805   There may be only one switch :switch:`-P`.
806   When a switch :switch:`-P` is specified,
807   no switch :switch:`-c` may be specified.
808   On all platforms, except on VMS, when ``gnatname`` is invoked for an
809   existing project file <proj>.gpr, a backup copy of the project file is created
810   in the project directory with file name <proj>.gpr.saved_x. 'x' is the first
811   non negative number that makes this backup copy a new file.
812
813   .. index:: -v (gnatname)
814
815 :switch:`-v`
816   Verbose mode. Output detailed explanation of behavior to :file:`stdout`.
817   This includes name of the file written, the name of the directories to search
818   and, for each file in those directories whose name matches at least one of
819   the Naming Patterns, an indication of whether the file contains a unit,
820   and if so the name of the unit.
821
822 .. index:: -v -v (gnatname)
823
824 :switch:`-v -v`
825   Very Verbose mode. In addition to the output produced in verbose mode,
826   for each file in the searched directories whose name matches none of
827   the Naming Patterns, an indication is given that there is no match.
828
829   .. index:: -x (gnatname)
830
831 :switch:`-x{pattern}`
832   Excluded patterns. Using this switch, it is possible to exclude some files
833   that would match the name patterns. For example,
834
835   .. code-block:: sh
836
837       gnatname -x "*_nt.ada" "*.ada"
838
839   will look for Ada units in all files with the :file:`.ada` extension,
840   except those whose names end with :file:`_nt.ada`.
841
842
843 .. _Examples_of_gnatname_Usage:
844
845 Examples of ``gnatname`` Usage
846 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
847
848 .. code-block:: sh
849
850      $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"
851
852 In this example, the directory :file:`/home/me` must already exist
853 and be writable. In addition, the directory
854 :file:`/home/me/sources` (specified by
855 :switch:`-d sources`) must exist and be readable.
856
857 Note the optional spaces after :switch:`-c` and :switch:`-d`.
858
859 .. code-block:: sh
860
861      $ gnatname -P/home/me/proj -x "*_nt_body.ada"
862      -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
863
864 Note that several switches :switch:`-d` may be used,
865 even in conjunction with one or several switches
866 :switch:`-D`. Several Naming Patterns and one excluded pattern
867 are used in this example.
868
869
870 .. _File_Name_Krunching_with_gnatkr:
871
872 File Name Krunching with ``gnatkr``
873 -----------------------------------
874
875 .. index:: ! gnatkr
876
877 This section discusses the method used by the compiler to shorten
878 the default file names chosen for Ada units so that they do not
879 exceed the maximum length permitted. It also describes the
880 ``gnatkr`` utility that can be used to determine the result of
881 applying this shortening.
882
883 .. _About_gnatkr:
884
885 About ``gnatkr``
886 ^^^^^^^^^^^^^^^^
887
888 The default file naming rule in GNAT
889 is that the file name must be derived from
890 the unit name. The exact default rule is as follows:
891
892 * Take the unit name and replace all dots by hyphens.
893
894 * If such a replacement occurs in the
895   second character position of a name, and the first character is
896   :samp:`a`, :samp:`g`, :samp:`s`, or :samp:`i`,
897   then replace the dot by the character
898   :samp:`~` (tilde)
899   instead of a minus.
900
901   The reason for this exception is to avoid clashes
902   with the standard names for children of System, Ada, Interfaces,
903   and GNAT, which use the prefixes
904   :samp:`s-`, :samp:`a-`, :samp:`i-`, and :samp:`g-`,
905   respectively.
906
907 The :switch:`-gnatk{nn}`
908 switch of the compiler activates a 'krunching'
909 circuit that limits file names to nn characters (where nn is a decimal
910 integer).
911
912 The ``gnatkr`` utility can be used to determine the krunched name for
913 a given file, when krunched to a specified maximum length.
914
915 .. _Using_gnatkr:
916
917 Using ``gnatkr``
918 ^^^^^^^^^^^^^^^^
919
920 The ``gnatkr`` command has the form:
921
922 .. code-block:: sh
923
924       $ gnatkr name [ length ]
925
926 ``name`` is the uncrunched file name, derived from the name of the unit
927 in the standard manner described in the previous section (i.e., in particular
928 all dots are replaced by hyphens). The file name may or may not have an
929 extension (defined as a suffix of the form period followed by arbitrary
930 characters other than period). If an extension is present then it will
931 be preserved in the output. For example, when krunching :file:`hellofile.ads`
932 to eight characters, the result will be hellofil.ads.
933
934 Note: for compatibility with previous versions of ``gnatkr`` dots may
935 appear in the name instead of hyphens, but the last dot will always be
936 taken as the start of an extension. So if ``gnatkr`` is given an argument
937 such as :file:`Hello.World.adb` it will be treated exactly as if the first
938 period had been a hyphen, and for example krunching to eight characters
939 gives the result :file:`hellworl.adb`.
940
941 Note that the result is always all lower case.
942 Characters of the other case are folded as required.
943
944 ``length`` represents the length of the krunched name. The default
945 when no argument is given is 8 characters. A length of zero stands for
946 unlimited, in other words do not chop except for system files where the
947 implied crunching length is always eight characters.
948
949 The output is the krunched name. The output has an extension only if the
950 original argument was a file name with an extension.
951
952 .. _Krunching_Method:
953
954 Krunching Method
955 ^^^^^^^^^^^^^^^^
956
957 The initial file name is determined by the name of the unit that the file
958 contains. The name is formed by taking the full expanded name of the
959 unit and replacing the separating dots with hyphens and
960 using lowercase
961 for all letters, except that a hyphen in the second character position is
962 replaced by a tilde if the first character is
963 :samp:`a`, :samp:`i`, :samp:`g`, or :samp:`s`.
964 The extension is ``.ads`` for a
965 spec and ``.adb`` for a body.
966 Krunching does not affect the extension, but the file name is shortened to
967 the specified length by following these rules:
968
969 * The name is divided into segments separated by hyphens, tildes or
970   underscores and all hyphens, tildes, and underscores are
971   eliminated. If this leaves the name short enough, we are done.
972
973 * If the name is too long, the longest segment is located (left-most
974   if there are two of equal length), and shortened by dropping
975   its last character. This is repeated until the name is short enough.
976
977   As an example, consider the krunching of :file:`our-strings-wide_fixed.adb`
978   to fit the name into 8 characters as required by some operating systems::
979
980       our-strings-wide_fixed 22
981       our strings wide fixed 19
982       our string  wide fixed 18
983       our strin   wide fixed 17
984       our stri    wide fixed 16
985       our stri    wide fixe  15
986       our str     wide fixe  14
987       our str     wid  fixe  13
988       our str     wid  fix   12
989       ou  str     wid  fix   11
990       ou  st      wid  fix   10
991       ou  st      wi   fix   9
992       ou  st      wi   fi    8
993       Final file name: oustwifi.adb
994
995 * The file names for all predefined units are always krunched to eight
996   characters. The krunching of these predefined units uses the following
997   special prefix replacements:
998
999   ===================== ==============
1000   Prefix                 Replacement
1001   --------------------- --------------
1002   :file:`ada-`           :file:`a-`
1003   :file:`gnat-`          :file:`g-`
1004   :file:`interfac es-`   :file:`i-`
1005   :file:`system-`        :file:`s-`
1006   ===================== ==============
1007
1008   These system files have a hyphen in the second character position. That
1009   is why normal user files replace such a character with a
1010   tilde, to avoid confusion with system file names.
1011
1012   As an example of this special rule, consider
1013   :file:`ada-strings-wide_fixed.adb`, which gets krunched as follows::
1014
1015       ada-strings-wide_fixed 22
1016       a-  strings wide fixed 18
1017       a-  string  wide fixed 17
1018       a-  strin   wide fixed 16
1019       a-  stri    wide fixed 15
1020       a-  stri    wide fixe  14
1021       a-  str     wide fixe  13
1022       a-  str     wid  fixe  12
1023       a-  str     wid  fix   11
1024       a-  st      wid  fix   10
1025       a-  st      wi   fix   9
1026       a-  st      wi   fi    8
1027       Final file name: a-stwifi.adb
1028
1029 Of course no file shortening algorithm can guarantee uniqueness over all
1030 possible unit names, and if file name krunching is used then it is your
1031 responsibility to ensure that no name clashes occur. The utility
1032 program ``gnatkr`` is supplied for conveniently determining the
1033 krunched name of a file.
1034
1035 .. _Examples_of_gnatkr_Usage:
1036
1037 Examples of ``gnatkr`` Usage
1038 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1039
1040 ::
1041
1042     $ gnatkr very_long_unit_name.ads      --> velounna.ads
1043     $ gnatkr grandparent-parent-child.ads --> grparchi.ads
1044     $ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads
1045     $ gnatkr grandparent-parent-child     --> grparchi
1046     $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
1047     $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads
1048
1049
1050 .. _Renaming_Files_with_gnatchop:
1051
1052 Renaming Files with ``gnatchop``
1053 --------------------------------
1054
1055 .. index:: ! gnatchop
1056
1057 This section discusses how to handle files with multiple units by using
1058 the ``gnatchop`` utility. This utility is also useful in renaming
1059 files to meet the standard GNAT default file naming conventions.
1060
1061 .. _Handling_Files_with_Multiple_Units:
1062
1063 Handling Files with Multiple Units
1064 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1065
1066 The basic compilation model of GNAT requires that a file submitted to the
1067 compiler have only one unit and there be a strict correspondence
1068 between the file name and the unit name.
1069
1070 The ``gnatchop`` utility allows both of these rules to be relaxed,
1071 allowing GNAT to process files which contain multiple compilation units
1072 and files with arbitrary file names. ``gnatchop``
1073 reads the specified file and generates one or more output files,
1074 containing one unit per file. The unit and the file name correspond,
1075 as required by GNAT.
1076
1077 If you want to permanently restructure a set of 'foreign' files so that
1078 they match the GNAT rules, and do the remaining development using the
1079 GNAT structure, you can simply use ``gnatchop`` once, generate the
1080 new set of files and work with them from that point on.
1081
1082 Alternatively, if you want to keep your files in the 'foreign' format,
1083 perhaps to maintain compatibility with some other Ada compilation
1084 system, you can set up a procedure where you use ``gnatchop`` each
1085 time you compile, regarding the source files that it writes as temporary
1086 files that you throw away.
1087
1088 Note that if your file containing multiple units starts with a byte order
1089 mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop
1090 will each start with a copy of this BOM, meaning that they can be compiled
1091 automatically in UTF-8 mode without needing to specify an explicit encoding.
1092
1093 .. _Operating_gnatchop_in_Compilation_Mode:
1094
1095 Operating gnatchop in Compilation Mode
1096 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1097
1098 The basic function of ``gnatchop`` is to take a file with multiple units
1099 and split it into separate files. The boundary between files is reasonably
1100 clear, except for the issue of comments and pragmas. In default mode, the
1101 rule is that any pragmas between units belong to the previous unit, except
1102 that configuration pragmas always belong to the following unit. Any comments
1103 belong to the following unit. These rules
1104 almost always result in the right choice of
1105 the split point without needing to mark it explicitly and most users will
1106 find this default to be what they want. In this default mode it is incorrect to
1107 submit a file containing only configuration pragmas, or one that ends in
1108 configuration pragmas, to ``gnatchop``.
1109
1110 However, using a special option to activate 'compilation mode',
1111 ``gnatchop``
1112 can perform another function, which is to provide exactly the semantics
1113 required by the RM for handling of configuration pragmas in a compilation.
1114 In the absence of configuration pragmas (at the main file level), this
1115 option has no effect, but it causes such configuration pragmas to be handled
1116 in a quite different manner.
1117
1118 First, in compilation mode, if ``gnatchop`` is given a file that consists of
1119 only configuration pragmas, then this file is appended to the
1120 :file:`gnat.adc` file in the current directory. This behavior provides
1121 the required behavior described in the RM for the actions to be taken
1122 on submitting such a file to the compiler, namely that these pragmas
1123 should apply to all subsequent compilations in the same compilation
1124 environment. Using GNAT, the current directory, possibly containing a
1125 :file:`gnat.adc` file is the representation
1126 of a compilation environment. For more information on the
1127 :file:`gnat.adc` file, see :ref:`Handling_of_Configuration_Pragmas`.
1128
1129 Second, in compilation mode, if ``gnatchop``
1130 is given a file that starts with
1131 configuration pragmas, and contains one or more units, then these
1132 configuration pragmas are prepended to each of the chopped files. This
1133 behavior provides the required behavior described in the RM for the
1134 actions to be taken on compiling such a file, namely that the pragmas
1135 apply to all units in the compilation, but not to subsequently compiled
1136 units.
1137
1138 Finally, if configuration pragmas appear between units, they are appended
1139 to the previous unit. This results in the previous unit being illegal,
1140 since the compiler does not accept configuration pragmas that follow
1141 a unit. This provides the required RM behavior that forbids configuration
1142 pragmas other than those preceding the first compilation unit of a
1143 compilation.
1144
1145 For most purposes, ``gnatchop`` will be used in default mode. The
1146 compilation mode described above is used only if you need exactly
1147 accurate behavior with respect to compilations, and you have files
1148 that contain multiple units and configuration pragmas. In this
1149 circumstance the use of ``gnatchop`` with the compilation mode
1150 switch provides the required behavior, and is for example the mode
1151 in which GNAT processes the ACVC tests.
1152
1153
1154 .. _Command_Line_for_gnatchop:
1155
1156 Command Line for ``gnatchop``
1157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1158
1159 The ``gnatchop`` command has the form:
1160
1161 .. code-block:: sh
1162
1163      $ gnatchop switches file_name [file_name ...]
1164            [directory]
1165
1166 The only required argument is the file name of the file to be chopped.
1167 There are no restrictions on the form of this file name. The file itself
1168 contains one or more Ada units, in normal GNAT format, concatenated
1169 together. As shown, more than one file may be presented to be chopped.
1170
1171 When run in default mode, ``gnatchop`` generates one output file in
1172 the current directory for each unit in each of the files.
1173
1174 ``directory``, if specified, gives the name of the directory to which
1175 the output files will be written. If it is not specified, all files are
1176 written to the current directory.
1177
1178 For example, given a
1179 file called :file:`hellofiles` containing
1180
1181 .. code-block:: ada
1182
1183      procedure Hello;
1184
1185      with Ada.Text_IO; use Ada.Text_IO;
1186      procedure Hello is
1187      begin
1188         Put_Line ("Hello");
1189      end Hello;
1190
1191 the command
1192
1193 .. code-block:: sh
1194
1195      $ gnatchop hellofiles
1196
1197 generates two files in the current directory, one called
1198 :file:`hello.ads` containing the single line that is the procedure spec,
1199 and the other called :file:`hello.adb` containing the remaining text. The
1200 original file is not affected. The generated files can be compiled in
1201 the normal manner.
1202
1203 When gnatchop is invoked on a file that is empty or that contains only empty
1204 lines and/or comments, gnatchop will not fail, but will not produce any
1205 new sources.
1206
1207 For example, given a
1208 file called :file:`toto.txt` containing
1209
1210 .. code-block:: ada
1211
1212      --  Just a comment
1213
1214 the command
1215
1216 .. code-block:: sh
1217
1218      $ gnatchop toto.txt
1219
1220 will not produce any new file and will result in the following warnings::
1221
1222      toto.txt:1:01: warning: empty file, contains no compilation units
1223      no compilation units found
1224      no source files written
1225
1226
1227 .. _Switches_for_gnatchop:
1228
1229 Switches for ``gnatchop``
1230 ^^^^^^^^^^^^^^^^^^^^^^^^^
1231
1232 ``gnatchop`` recognizes the following switches:
1233
1234
1235 .. index:: --version (gnatchop)
1236
1237 :switch:`--version`
1238   Display Copyright and version, then exit disregarding all other options.
1239
1240 .. index:: --help (gnatchop)
1241
1242 :switch:`--help`
1243   If :switch:`--version` was not used, display usage, then exit disregarding
1244   all other options.
1245
1246 .. index:: -c (gnatchop)
1247
1248 :switch:`-c`
1249   Causes ``gnatchop`` to operate in compilation mode, in which
1250   configuration pragmas are handled according to strict RM rules. See
1251   previous section for a full description of this mode.
1252
1253 :switch:`-gnat{xxx}`
1254   This passes the given :switch:`-gnat{xxx}` switch to ``gnat`` which is
1255   used to parse the given file. Not all *xxx* options make sense,
1256   but for example, the use of :switch:`-gnati2` allows ``gnatchop`` to
1257   process a source file that uses Latin-2 coding for identifiers.
1258
1259 :switch:`-h`
1260   Causes ``gnatchop`` to generate a brief help summary to the standard
1261   output file showing usage information.
1262
1263 .. index:: -k (gnatchop)
1264
1265 :switch:`-k{mm}`
1266   Limit generated file names to the specified number ``mm``
1267   of characters.
1268   This is useful if the
1269   resulting set of files is required to be interoperable with systems
1270   which limit the length of file names.
1271   No space is allowed between the :switch:`-k` and the numeric value. The numeric
1272   value may be omitted in which case a default of :switch:`-k8`,
1273   suitable for use
1274   with DOS-like file systems, is used. If no :switch:`-k` switch
1275   is present then
1276   there is no limit on the length of file names.
1277
1278 .. index:: -p (gnatchop)
1279
1280 :switch:`-p`
1281   Causes the file modification time stamp of the input file to be
1282   preserved and used for the time stamp of the output file(s). This may be
1283   useful for preserving coherency of time stamps in an environment where
1284   ``gnatchop`` is used as part of a standard build process.
1285
1286 .. index:: -q (gnatchop)
1287
1288 :switch:`-q`
1289   Causes output of informational messages indicating the set of generated
1290   files to be suppressed. Warnings and error messages are unaffected.
1291
1292 .. index:: -r (gnatchop)
1293 .. index:: Source_Reference pragmas
1294
1295 :switch:`-r`
1296   Generate ``Source_Reference`` pragmas. Use this switch if the output
1297   files are regarded as temporary and development is to be done in terms
1298   of the original unchopped file. This switch causes
1299   ``Source_Reference`` pragmas to be inserted into each of the
1300   generated files to refers back to the original file name and line number.
1301   The result is that all error messages refer back to the original
1302   unchopped file.
1303   In addition, the debugging information placed into the object file (when
1304   the :switch:`-g` switch of ``gcc`` or ``gnatmake`` is
1305   specified)
1306   also refers back to this original file so that tools like profilers and
1307   debuggers will give information in terms of the original unchopped file.
1308
1309   If the original file to be chopped itself contains
1310   a ``Source_Reference``
1311   pragma referencing a third file, then gnatchop respects
1312   this pragma, and the generated ``Source_Reference`` pragmas
1313   in the chopped file refer to the original file, with appropriate
1314   line numbers. This is particularly useful when ``gnatchop``
1315   is used in conjunction with ``gnatprep`` to compile files that
1316   contain preprocessing statements and multiple units.
1317
1318 .. index:: -v (gnatchop)
1319
1320 :switch:`-v`
1321   Causes ``gnatchop`` to operate in verbose mode. The version
1322   number and copyright notice are output, as well as exact copies of
1323   the gnat1 commands spawned to obtain the chop control information.
1324
1325 .. index:: -w (gnatchop)
1326
1327 :switch:`-w`
1328   Overwrite existing file names. Normally ``gnatchop`` regards it as a
1329   fatal error if there is already a file with the same name as a
1330   file it would otherwise output, in other words if the files to be
1331   chopped contain duplicated units. This switch bypasses this
1332   check, and causes all but the last instance of such duplicated
1333   units to be skipped.
1334
1335 .. index:: --GCC= (gnatchop)
1336
1337 :switch:`--GCC={xxxx}`
1338   Specify the path of the GNAT parser to be used. When this switch is used,
1339   no attempt is made to add the prefix to the GNAT parser executable.
1340
1341
1342 .. _Examples_of_gnatchop_Usage:
1343
1344 Examples of ``gnatchop`` Usage
1345 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1346
1347 .. code-block:: sh
1348
1349       $ gnatchop -w hello_s.ada prerelease/files
1350
1351 Chops the source file :file:`hello_s.ada`. The output files will be
1352 placed in the directory :file:`prerelease/files`,
1353 overwriting any
1354 files with matching names in that directory (no files in the current
1355 directory are modified).
1356
1357 .. code-block:: sh
1358
1359       $ gnatchop archive
1360
1361 Chops the source file :file:`archive`
1362 into the current directory. One
1363 useful application of ``gnatchop`` is in sending sets of sources
1364 around, for example in email messages. The required sources are simply
1365 concatenated (for example, using a Unix ``cat``
1366 command), and then
1367 ``gnatchop`` is used at the other end to reconstitute the original
1368 file names.
1369
1370 .. code-block:: sh
1371
1372       $ gnatchop file1 file2 file3 direc
1373
1374 Chops all units in files :file:`file1`, :file:`file2`, :file:`file3`, placing
1375 the resulting files in the directory :file:`direc`. Note that if any units
1376 occur more than once anywhere within this set of files, an error message
1377 is generated, and no files are written. To override this check, use the
1378 :switch:`-w` switch,
1379 in which case the last occurrence in the last file will
1380 be the one that is output, and earlier duplicate occurrences for a given
1381 unit will be skipped.
1382
1383 .. _Configuration_Pragmas:
1384
1385 Configuration Pragmas
1386 =====================
1387
1388 .. index:: Configuration pragmas
1389
1390 .. index:: Pragmas, configuration
1391
1392 Configuration pragmas include those pragmas described as
1393 such in the Ada Reference Manual, as well as
1394 implementation-dependent pragmas that are configuration pragmas.
1395 See the ``Implementation_Defined_Pragmas`` chapter in the
1396 :title:`GNAT_Reference_Manual` for details on these
1397 additional GNAT-specific configuration pragmas.
1398 Most notably, the pragma ``Source_File_Name``, which allows
1399 specifying non-default names for source files, is a configuration
1400 pragma. The following is a complete list of configuration pragmas
1401 recognized by GNAT::
1402
1403      Ada_83
1404      Ada_95
1405      Ada_05
1406      Ada_2005
1407      Ada_12
1408      Ada_2012
1409      Allow_Integer_Address
1410      Annotate
1411      Assertion_Policy
1412      Assume_No_Invalid_Values
1413      C_Pass_By_Copy
1414      Check_Float_Overflow
1415      Check_Name
1416      Check_Policy
1417      Compile_Time_Error
1418      Compile_Time_Warning
1419      Compiler_Unit
1420      Compiler_Unit_Warning
1421      Component_Alignment
1422      Convention_Identifier
1423      Debug_Policy
1424      Detect_Blocking
1425      Default_Scalar_Storage_Order
1426      Default_Storage_Pool
1427      Disable_Atomic_Synchronization
1428      Discard_Names
1429      Elaboration_Checks
1430      Eliminate
1431      Enable_Atomic_Synchronization
1432      Extend_System
1433      Extensions_Allowed
1434      External_Name_Casing
1435      Fast_Math
1436      Favor_Top_Level
1437      Ignore_Pragma
1438      Implicit_Packing
1439      Initialize_Scalars
1440      Interrupt_State
1441      License
1442      Locking_Policy
1443      No_Component_Reordering
1444      No_Heap_Finalization
1445      No_Run_Time
1446      No_Strict_Aliasing
1447      Normalize_Scalars
1448      Optimize_Alignment
1449      Overflow_Mode
1450      Overriding_Renamings
1451      Partition_Elaboration_Policy
1452      Persistent_BSS
1453      Polling
1454      Prefix_Exception_Messages
1455      Priority_Specific_Dispatching
1456      Profile
1457      Profile_Warnings
1458      Propagate_Exceptions
1459      Queuing_Policy
1460      Rational
1461      Ravenscar
1462      Rename_Pragma
1463      Restricted_Run_Time
1464      Restrictions
1465      Restrictions_Warnings
1466      Reviewable
1467      Short_Circuit_And_Or
1468      Short_Descriptors
1469      Source_File_Name
1470      Source_File_Name_Project
1471      SPARK_Mode
1472      Style_Checks
1473      Suppress
1474      Suppress_Exception_Locations
1475      Task_Dispatching_Policy
1476      Unevaluated_Use_Of_Old
1477      Universal_Data
1478      Unsuppress
1479      Use_VADS_Size
1480      Validity_Checks
1481      Warning_As_Error
1482      Warnings
1483      Wide_Character_Encoding
1484
1485
1486 .. _Handling_of_Configuration_Pragmas:
1487
1488 Handling of Configuration Pragmas
1489 ---------------------------------
1490
1491 Configuration pragmas may either appear at the start of a compilation
1492 unit, or they can appear in a configuration pragma file to apply to
1493 all compilations performed in a given compilation environment.
1494
1495 GNAT also provides the ``gnatchop`` utility to provide an automatic
1496 way to handle configuration pragmas following the semantics for
1497 compilations (that is, files with multiple units), described in the RM.
1498 See :ref:`Operating_gnatchop_in_Compilation_Mode` for details.
1499 However, for most purposes, it will be more convenient to edit the
1500 :file:`gnat.adc` file that contains configuration pragmas directly,
1501 as described in the following section.
1502
1503 In the case of ``Restrictions`` pragmas appearing as configuration
1504 pragmas in individual compilation units, the exact handling depends on
1505 the type of restriction.
1506
1507 Restrictions that require partition-wide consistency (like
1508 ``No_Tasking``) are
1509 recognized wherever they appear
1510 and can be freely inherited, e.g. from a |withed| unit to the |withing|
1511 unit. This makes sense since the binder will in any case insist on seeing
1512 consistent use, so any unit not conforming to any restrictions that are
1513 anywhere in the partition will be rejected, and you might as well find
1514 that out at compile time rather than at bind time.
1515
1516 For restrictions that do not require partition-wide consistency, e.g.
1517 SPARK or No_Implementation_Attributes, in general the restriction applies
1518 only to the unit in which the pragma appears, and not to any other units.
1519
1520 The exception is No_Elaboration_Code which always applies to the entire
1521 object file from a compilation, i.e. to the body, spec, and all subunits.
1522 This restriction can be specified in a configuration pragma file, or it
1523 can be on the body and/or the spec (in eithe case it applies to all the
1524 relevant units). It can appear on a subunit only if it has previously
1525 appeared in the body of spec.
1526
1527
1528 .. _The_Configuration_Pragmas_Files:
1529
1530 The Configuration Pragmas Files
1531 -------------------------------
1532
1533 .. index:: gnat.adc
1534
1535 In GNAT a compilation environment is defined by the current
1536 directory at the time that a compile command is given. This current
1537 directory is searched for a file whose name is :file:`gnat.adc`. If
1538 this file is present, it is expected to contain one or more
1539 configuration pragmas that will be applied to the current compilation.
1540 However, if the switch :switch:`-gnatA` is used, :file:`gnat.adc` is not
1541 considered. When taken into account, :file:`gnat.adc` is added to the
1542 dependencies, so that if :file:`gnat.adc` is modified later, an invocation of
1543 ``gnatmake`` will recompile the source.
1544
1545 Configuration pragmas may be entered into the :file:`gnat.adc` file
1546 either by running ``gnatchop`` on a source file that consists only of
1547 configuration pragmas, or more conveniently by direct editing of the
1548 :file:`gnat.adc` file, which is a standard format source file.
1549
1550 Besides :file:`gnat.adc`, additional files containing configuration
1551 pragmas may be applied to the current compilation using the switch
1552 :switch:`-gnatec={path}` where ``path`` must designate an existing file that
1553 contains only configuration pragmas. These configuration pragmas are
1554 in addition to those found in :file:`gnat.adc` (provided :file:`gnat.adc`
1555 is present and switch :switch:`-gnatA` is not used).
1556
1557 It is allowable to specify several switches :switch:`-gnatec=`, all of which
1558 will be taken into account.
1559
1560 Files containing configuration pragmas specified with switches
1561 :switch:`-gnatec=` are added to the dependencies, unless they are
1562 temporary files. A file is considered temporary if its name ends in
1563 :file:`.tmp` or :file:`.TMP`. Certain tools follow this naming
1564 convention because they pass information to ``gcc`` via
1565 temporary files that are immediately deleted; it doesn't make sense to
1566 depend on a file that no longer exists. Such tools include
1567 ``gprbuild``, ``gnatmake``, and ``gnatcheck``.
1568
1569 If you are using project file, a separate mechanism is provided using
1570 project attributes.
1571
1572 .. --Comment
1573    See :ref:`Specifying_Configuration_Pragmas` for more details.
1574
1575
1576 .. _Generating_Object_Files:
1577
1578 Generating Object Files
1579 =======================
1580
1581 An Ada program consists of a set of source files, and the first step in
1582 compiling the program is to generate the corresponding object files.
1583 These are generated by compiling a subset of these source files.
1584 The files you need to compile are the following:
1585
1586 * If a package spec has no body, compile the package spec to produce the
1587   object file for the package.
1588
1589 * If a package has both a spec and a body, compile the body to produce the
1590   object file for the package. The source file for the package spec need
1591   not be compiled in this case because there is only one object file, which
1592   contains the code for both the spec and body of the package.
1593
1594 * For a subprogram, compile the subprogram body to produce the object file
1595   for the subprogram. The spec, if one is present, is as usual in a
1596   separate file, and need not be compiled.
1597
1598 .. index:: Subunits
1599
1600 * In the case of subunits, only compile the parent unit. A single object
1601   file is generated for the entire subunit tree, which includes all the
1602   subunits.
1603
1604 * Compile child units independently of their parent units
1605   (though, of course, the spec of all the ancestor unit must be present in order
1606   to compile a child unit).
1607
1608   .. index:: Generics
1609
1610 * Compile generic units in the same manner as any other units. The object
1611   files in this case are small dummy files that contain at most the
1612   flag used for elaboration checking. This is because GNAT always handles generic
1613   instantiation by means of macro expansion. However, it is still necessary to
1614   compile generic units, for dependency checking and elaboration purposes.
1615
1616 The preceding rules describe the set of files that must be compiled to
1617 generate the object files for a program. Each object file has the same
1618 name as the corresponding source file, except that the extension is
1619 :file:`.o` as usual.
1620
1621 You may wish to compile other files for the purpose of checking their
1622 syntactic and semantic correctness. For example, in the case where a
1623 package has a separate spec and body, you would not normally compile the
1624 spec. However, it is convenient in practice to compile the spec to make
1625 sure it is error-free before compiling clients of this spec, because such
1626 compilations will fail if there is an error in the spec.
1627
1628 GNAT provides an option for compiling such files purely for the
1629 purposes of checking correctness; such compilations are not required as
1630 part of the process of building a program. To compile a file in this
1631 checking mode, use the :switch:`-gnatc` switch.
1632
1633 .. _Source_Dependencies:
1634
1635 Source Dependencies
1636 ===================
1637
1638 A given object file clearly depends on the source file which is compiled
1639 to produce it. Here we are using "depends" in the sense of a typical
1640 ``make`` utility; in other words, an object file depends on a source
1641 file if changes to the source file require the object file to be
1642 recompiled.
1643 In addition to this basic dependency, a given object may depend on
1644 additional source files as follows:
1645
1646 * If a file being compiled |withs| a unit ``X``, the object file
1647   depends on the file containing the spec of unit ``X``. This includes
1648   files that are |withed| implicitly either because they are parents
1649   of |withed| child units or they are run-time units required by the
1650   language constructs used in a particular unit.
1651
1652 * If a file being compiled instantiates a library level generic unit, the
1653   object file depends on both the spec and body files for this generic
1654   unit.
1655
1656 * If a file being compiled instantiates a generic unit defined within a
1657   package, the object file depends on the body file for the package as
1658   well as the spec file.
1659
1660 .. index:: Inline
1661 .. index:: -gnatn switch
1662
1663 * If a file being compiled contains a call to a subprogram for which
1664   pragma ``Inline`` applies and inlining is activated with the
1665   :switch:`-gnatn` switch, the object file depends on the file containing the
1666   body of this subprogram as well as on the file containing the spec. Note
1667   that for inlining to actually occur as a result of the use of this switch,
1668   it is necessary to compile in optimizing mode.
1669
1670   .. index:: -gnatN switch
1671
1672   The use of :switch:`-gnatN` activates  inlining optimization
1673   that is performed by the front end of the compiler. This inlining does
1674   not require that the code generation be optimized. Like :switch:`-gnatn`,
1675   the use of this switch generates additional dependencies.
1676
1677   When using a gcc-based back end (in practice this means using any version
1678   of GNAT other than for the JVM, .NET or GNAAMP platforms), then the use of
1679   :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
1680   Historically front end inlining was more extensive than the gcc back end
1681   inlining, but that is no longer the case.
1682
1683 * If an object file :file:`O` depends on the proper body of a subunit through
1684   inlining or instantiation, it depends on the parent unit of the subunit.
1685   This means that any modification of the parent unit or one of its subunits
1686   affects the compilation of :file:`O`.
1687
1688 * The object file for a parent unit depends on all its subunit body files.
1689
1690 * The previous two rules meant that for purposes of computing dependencies and
1691   recompilation, a body and all its subunits are treated as an indivisible whole.
1692
1693   These rules are applied transitively: if unit ``A`` |withs|
1694   unit ``B``, whose elaboration calls an inlined procedure in package
1695   ``C``, the object file for unit ``A`` will depend on the body of
1696   ``C``, in file :file:`c.adb`.
1697
1698   The set of dependent files described by these rules includes all the
1699   files on which the unit is semantically dependent, as dictated by the
1700   Ada language standard. However, it is a superset of what the
1701   standard describes, because it includes generic, inline, and subunit
1702   dependencies.
1703
1704   An object file must be recreated by recompiling the corresponding source
1705   file if any of the source files on which it depends are modified. For
1706   example, if the ``make`` utility is used to control compilation,
1707   the rule for an Ada object file must mention all the source files on
1708   which the object file depends, according to the above definition.
1709   The determination of the necessary
1710   recompilations is done automatically when one uses ``gnatmake``.
1711
1712 .. _The_Ada_Library_Information_Files:
1713
1714 The Ada Library Information Files
1715 =================================
1716
1717 .. index:: Ada Library Information files
1718
1719 .. index:: ALI files
1720
1721 Each compilation actually generates two output files. The first of these
1722 is the normal object file that has a :file:`.o` extension. The second is a
1723 text file containing full dependency information. It has the same
1724 name as the source file, but an :file:`.ali` extension.
1725 This file is known as the Ada Library Information (:file:`ALI`) file.
1726 The following information is contained in the :file:`ALI` file.
1727
1728 * Version information (indicates which version of GNAT was used to compile
1729   the unit(s) in question)
1730
1731 * Main program information (including priority and time slice settings,
1732   as well as the wide character encoding used during compilation).
1733
1734 * List of arguments used in the ``gcc`` command for the compilation
1735
1736 * Attributes of the unit, including configuration pragmas used, an indication
1737   of whether the compilation was successful, exception model used etc.
1738
1739 * A list of relevant restrictions applying to the unit (used for consistency)
1740   checking.
1741
1742 * Categorization information (e.g., use of pragma ``Pure``).
1743
1744 * Information on all |withed| units, including presence of
1745   ``Elaborate`` or ``Elaborate_All`` pragmas.
1746
1747 * Information from any ``Linker_Options`` pragmas used in the unit
1748
1749 * Information on the use of ``Body_Version`` or ``Version``
1750   attributes in the unit.
1751
1752 * Dependency information. This is a list of files, together with
1753   time stamp and checksum information. These are files on which
1754   the unit depends in the sense that recompilation is required
1755   if any of these units are modified.
1756
1757 * Cross-reference data. Contains information on all entities referenced
1758   in the unit. Used by tools like ``gnatxref`` and ``gnatfind`` to
1759   provide cross-reference information.
1760
1761 For a full detailed description of the format of the :file:`ALI` file,
1762 see the source of the body of unit ``Lib.Writ``, contained in file
1763 :file:`lib-writ.adb` in the GNAT compiler sources.
1764
1765
1766 .. _Binding_an_Ada_Program:
1767
1768 Binding an Ada Program
1769 ======================
1770
1771 When using languages such as C and C++, once the source files have been
1772 compiled the only remaining step in building an executable program
1773 is linking the object modules together. This means that it is possible to
1774 link an inconsistent version of a program, in which two units have
1775 included different versions of the same header.
1776
1777 The rules of Ada do not permit such an inconsistent program to be built.
1778 For example, if two clients have different versions of the same package,
1779 it is illegal to build a program containing these two clients.
1780 These rules are enforced by the GNAT binder, which also determines an
1781 elaboration order consistent with the Ada rules.
1782
1783 The GNAT binder is run after all the object files for a program have
1784 been created. It is given the name of the main program unit, and from
1785 this it determines the set of units required by the program, by reading the
1786 corresponding ALI files. It generates error messages if the program is
1787 inconsistent or if no valid order of elaboration exists.
1788
1789 If no errors are detected, the binder produces a main program, in Ada by
1790 default, that contains calls to the elaboration procedures of those
1791 compilation unit that require them, followed by
1792 a call to the main program. This Ada program is compiled to generate the
1793 object file for the main program. The name of
1794 the Ada file is :file:`b~xxx`.adb` (with the corresponding spec
1795 :file:`b~xxx`.ads`) where ``xxx`` is the name of the
1796 main program unit.
1797
1798 Finally, the linker is used to build the resulting executable program,
1799 using the object from the main program from the bind step as well as the
1800 object files for the Ada units of the program.
1801
1802
1803 .. _GNAT_and_Libraries:
1804
1805 GNAT and Libraries
1806 ==================
1807
1808 .. index:: Library building and using
1809
1810 This section describes how to build and use libraries with GNAT, and also shows
1811 how to recompile the GNAT run-time library. You should be familiar with the
1812 Project Manager facility (see the *GNAT_Project_Manager* chapter of the
1813 *GPRbuild User's Guide*) before reading this chapter.
1814
1815 .. _Introduction_to_Libraries_in_GNAT:
1816
1817 Introduction to Libraries in GNAT
1818 ---------------------------------
1819
1820 A library is, conceptually, a collection of objects which does not have its
1821 own main thread of execution, but rather provides certain services to the
1822 applications that use it. A library can be either statically linked with the
1823 application, in which case its code is directly included in the application,
1824 or, on platforms that support it, be dynamically linked, in which case
1825 its code is shared by all applications making use of this library.
1826
1827 GNAT supports both types of libraries.
1828 In the static case, the compiled code can be provided in different ways. The
1829 simplest approach is to provide directly the set of objects resulting from
1830 compilation of the library source files. Alternatively, you can group the
1831 objects into an archive using whatever commands are provided by the operating
1832 system. For the latter case, the objects are grouped into a shared library.
1833
1834 In the GNAT environment, a library has three types of components:
1835
1836 *  Source files,
1837
1838 *  :file:`ALI` files (see :ref:`The_Ada_Library_Information_Files`), and
1839
1840 *  Object files, an archive or a shared library.
1841
1842 A GNAT library may expose all its source files, which is useful for
1843 documentation purposes. Alternatively, it may expose only the units needed by
1844 an external user to make use of the library. That is to say, the specs
1845 reflecting the library services along with all the units needed to compile
1846 those specs, which can include generic bodies or any body implementing an
1847 inlined routine. In the case of *stand-alone libraries* those exposed
1848 units are called *interface units* (:ref:`Stand-alone_Ada_Libraries`).
1849
1850 All compilation units comprising an application, including those in a library,
1851 need to be elaborated in an order partially defined by Ada's semantics. GNAT
1852 computes the elaboration order from the :file:`ALI` files and this is why they
1853 constitute a mandatory part of GNAT libraries.
1854 *Stand-alone libraries* are the exception to this rule because a specific
1855 library elaboration routine is produced independently of the application(s)
1856 using the library.
1857
1858 .. _General_Ada_Libraries:
1859
1860 General Ada Libraries
1861 ---------------------
1862
1863
1864 .. _Building_a_library:
1865
1866 Building a library
1867 ^^^^^^^^^^^^^^^^^^
1868
1869 The easiest way to build a library is to use the Project Manager,
1870 which supports a special type of project called a *Library Project*
1871 (see the *Library Projects* section in the *GNAT Project Manager*
1872 chapter of the *GPRbuild User's Guide*).
1873
1874 A project is considered a library project, when two project-level attributes
1875 are defined in it: ``Library_Name`` and ``Library_Dir``. In order to
1876 control different aspects of library configuration, additional optional
1877 project-level attributes can be specified:
1878
1879 * ``Library_Kind``
1880     This attribute controls whether the library is to be static or dynamic
1881
1882
1883 * ``Library_Version``
1884     This attribute specifies the library version; this value is used
1885     during dynamic linking of shared libraries to determine if the currently
1886     installed versions of the binaries are compatible.
1887
1888 * ``Library_Options``
1889
1890 * ``Library_GCC``
1891     These attributes specify additional low-level options to be used during
1892     library generation, and redefine the actual application used to generate
1893     library.
1894
1895 The GNAT Project Manager takes full care of the library maintenance task,
1896 including recompilation of the source files for which objects do not exist
1897 or are not up to date, assembly of the library archive, and installation of
1898 the library (i.e., copying associated source, object and :file:`ALI` files
1899 to the specified location).
1900
1901 Here is a simple library project file:
1902
1903 .. code-block:: gpr
1904
1905        project My_Lib is
1906          for Source_Dirs use ("src1", "src2");
1907          for Object_Dir use "obj";
1908          for Library_Name use "mylib";
1909          for Library_Dir use "lib";
1910          for Library_Kind use "dynamic";
1911        end My_lib;
1912
1913 and the compilation command to build and install the library:
1914
1915 .. code-block:: sh
1916
1917      $ gnatmake -Pmy_lib
1918
1919 It is not entirely trivial to perform manually all the steps required to
1920 produce a library. We recommend that you use the GNAT Project Manager
1921 for this task. In special cases where this is not desired, the necessary
1922 steps are discussed below.
1923
1924 There are various possibilities for compiling the units that make up the
1925 library: for example with a Makefile (:ref:`Using_the_GNU_make_Utility`) or
1926 with a conventional script. For simple libraries, it is also possible to create
1927 a dummy main program which depends upon all the packages that comprise the
1928 interface of the library. This dummy main program can then be given to
1929 ``gnatmake``, which will ensure that all necessary objects are built.
1930
1931 After this task is accomplished, you should follow the standard procedure
1932 of the underlying operating system to produce the static or shared library.
1933
1934 Here is an example of such a dummy program:
1935
1936 .. code-block:: ada
1937
1938        with My_Lib.Service1;
1939        with My_Lib.Service2;
1940        with My_Lib.Service3;
1941        procedure My_Lib_Dummy is
1942        begin
1943           null;
1944        end;
1945
1946 Here are the generic commands that will build an archive or a shared library.
1947
1948 .. code-block:: sh
1949
1950      # compiling the library
1951      $ gnatmake -c my_lib_dummy.adb
1952
1953      # we don't need the dummy object itself
1954      $ rm my_lib_dummy.o my_lib_dummy.ali
1955
1956      # create an archive with the remaining objects
1957      $ ar rc libmy_lib.a *.o
1958      # some systems may require "ranlib" to be run as well
1959
1960      # or create a shared library
1961      $ gcc -shared -o libmy_lib.so *.o
1962      # some systems may require the code to have been compiled with -fPIC
1963
1964      # remove the object files that are now in the library
1965      $ rm *.o
1966
1967      # Make the ALI files read-only so that gnatmake will not try to
1968      # regenerate the objects that are in the library
1969      $ chmod -w *.ali
1970
1971 Please note that the library must have a name of the form :file:`lib{xxx}.a`
1972 or :file:`lib{xxx}.so` (or :file:`lib{xxx}.dll` on Windows) in order to
1973 be accessed by the directive :switch:`-l{xxx}` at link time.
1974
1975 .. _Installing_a_library:
1976
1977 Installing a library
1978 ^^^^^^^^^^^^^^^^^^^^
1979
1980 .. index:: ADA_PROJECT_PATH
1981 .. index:: GPR_PROJECT_PATH
1982
1983 If you use project files, library installation is part of the library build
1984 process (see the *Installing a Library with Project Files* section of the
1985 *GNAT Project Manager* chapter of the *GPRbuild User's Guide*).
1986
1987 When project files are not an option, it is also possible, but not recommended,
1988 to install the library so that the sources needed to use the library are on the
1989 Ada source path and the ALI files & libraries be on the Ada Object path (see
1990 :ref:`Search_Paths_and_the_Run-Time_Library_RTL`. Alternatively, the system
1991 administrator can place general-purpose libraries in the default compiler
1992 paths, by specifying the libraries' location in the configuration files
1993 :file:`ada_source_path` and :file:`ada_object_path`. These configuration files
1994 must be located in the GNAT installation tree at the same place as the gcc spec
1995 file. The location of the gcc spec file can be determined as follows:
1996
1997 .. code-block:: sh
1998
1999      $ gcc -v
2000
2001
2002 The configuration files mentioned above have a simple format: each line
2003 must contain one unique directory name.
2004 Those names are added to the corresponding path
2005 in their order of appearance in the file. The names can be either absolute
2006 or relative; in the latter case, they are relative to where theses files
2007 are located.
2008
2009 The files :file:`ada_source_path` and :file:`ada_object_path` might not be
2010 present in a
2011 GNAT installation, in which case, GNAT will look for its run-time library in
2012 the directories :file:`adainclude` (for the sources) and :file:`adalib` (for the
2013 objects and :file:`ALI` files). When the files exist, the compiler does not
2014 look in :file:`adainclude` and :file:`adalib`, and thus the
2015 :file:`ada_source_path` file
2016 must contain the location for the GNAT run-time sources (which can simply
2017 be :file:`adainclude`). In the same way, the :file:`ada_object_path` file must
2018 contain the location for the GNAT run-time objects (which can simply
2019 be :file:`adalib`).
2020
2021 You can also specify a new default path to the run-time library at compilation
2022 time with the switch :switch:`--RTS=rts-path`. You can thus choose / change
2023 the run-time library you want your program to be compiled with. This switch is
2024 recognized by ``gcc``, ``gnatmake``, ``gnatbind``,
2025 ``gnatls``, ``gnatfind`` and ``gnatxref``.
2026
2027 It is possible to install a library before or after the standard GNAT
2028 library, by reordering the lines in the configuration files. In general, a
2029 library must be installed before the GNAT library if it redefines
2030 any part of it.
2031
2032 .. _Using_a_library:
2033
2034 Using a library
2035 ^^^^^^^^^^^^^^^
2036
2037 Once again, the project facility greatly simplifies the use of
2038 libraries. In this context, using a library is just a matter of adding a
2039 |with| clause in the user project. For instance, to make use of the
2040 library ``My_Lib`` shown in examples in earlier sections, you can
2041 write:
2042
2043 .. code-block:: gpr
2044
2045        with "my_lib";
2046        project My_Proj is
2047          ...
2048        end My_Proj;
2049
2050 Even if you have a third-party, non-Ada library, you can still use GNAT's
2051 Project Manager facility to provide a wrapper for it. For example, the
2052 following project, when |withed| by your main project, will link with the
2053 third-party library :file:`liba.a`:
2054
2055 .. code-block:: gpr
2056
2057        project Liba is
2058           for Externally_Built use "true";
2059           for Source_Files use ();
2060           for Library_Dir use "lib";
2061           for Library_Name use "a";
2062           for Library_Kind use "static";
2063        end Liba;
2064
2065 This is an alternative to the use of ``pragma Linker_Options``. It is
2066 especially interesting in the context of systems with several interdependent
2067 static libraries where finding a proper linker order is not easy and best be
2068 left to the tools having visibility over project dependence information.
2069
2070 In order to use an Ada library manually, you need to make sure that this
2071 library is on both your source and object path
2072 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`
2073 and :ref:`Search_Paths_for_gnatbind`). Furthermore, when the objects are grouped
2074 in an archive or a shared library, you need to specify the desired
2075 library at link time.
2076
2077 For example, you can use the library :file:`mylib` installed in
2078 :file:`/dir/my_lib_src` and :file:`/dir/my_lib_obj` with the following commands:
2079
2080 .. code-block:: sh
2081
2082      $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\
2083        -largs -lmy_lib
2084
2085 This can be expressed more simply:
2086
2087 .. code-block:: sh
2088
2089     $ gnatmake my_appl
2090
2091 when the following conditions are met:
2092
2093 * :file:`/dir/my_lib_src` has been added by the user to the environment
2094   variable :envvar:`ADA_INCLUDE_PATH`, or by the administrator to the file
2095   :file:`ada_source_path`
2096
2097 * :file:`/dir/my_lib_obj` has been added by the user to the environment
2098   variable :envvar:`ADA_OBJECTS_PATH`, or by the administrator to the file
2099   :file:`ada_object_path`
2100
2101 * a pragma ``Linker_Options`` has been added to one of the sources.
2102   For example:
2103
2104   .. code-block:: ada
2105
2106        pragma Linker_Options ("-lmy_lib");
2107
2108 Note that you may also load a library dynamically at
2109 run time given its filename, as illustrated in the GNAT :file:`plugins` example
2110 in the directory :file:`share/examples/gnat/plugins` within the GNAT
2111 install area.
2112
2113 .. _Stand-alone_Ada_Libraries:
2114
2115 Stand-alone Ada Libraries
2116 -------------------------
2117
2118 .. index:: ! Stand-alone libraries
2119
2120 .. _Introduction_to_Stand-alone_Libraries:
2121
2122 Introduction to Stand-alone Libraries
2123 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2124
2125 A Stand-alone Library (abbreviated 'SAL') is a library that contains the
2126 necessary code to
2127 elaborate the Ada units that are included in the library. In contrast with
2128 an ordinary library, which consists of all sources, objects and :file:`ALI`
2129 files of the
2130 library, a SAL may specify a restricted subset of compilation units
2131 to serve as a library interface. In this case, the fully
2132 self-sufficient set of files will normally consist of an objects
2133 archive, the sources of interface units' specs, and the :file:`ALI`
2134 files of interface units.
2135 If an interface spec contains a generic unit or an inlined subprogram,
2136 the body's
2137 source must also be provided; if the units that must be provided in the source
2138 form depend on other units, the source and :file:`ALI` files of those must
2139 also be provided.
2140
2141 The main purpose of a SAL is to minimize the recompilation overhead of client
2142 applications when a new version of the library is installed. Specifically,
2143 if the interface sources have not changed, client applications do not need to
2144 be recompiled. If, furthermore, a SAL is provided in the shared form and its
2145 version, controlled by ``Library_Version`` attribute, is not changed,
2146 then the clients do not need to be relinked.
2147
2148 SALs also allow the library providers to minimize the amount of library source
2149 text exposed to the clients.  Such 'information hiding' might be useful or
2150 necessary for various reasons.
2151
2152 Stand-alone libraries are also well suited to be used in an executable whose
2153 main routine is not written in Ada.
2154
2155 .. _Building_a_Stand-alone_Library:
2156
2157 Building a Stand-alone Library
2158 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2159
2160 GNAT's Project facility provides a simple way of building and installing
2161 stand-alone libraries; see the *Stand-alone Library Projects* section
2162 in the *GNAT Project Manager* chapter of the *GPRbuild User's Guide*.
2163 To be a Stand-alone Library Project, in addition to the two attributes
2164 that make a project a Library Project (``Library_Name`` and
2165 ``Library_Dir``; see the *Library Projects* section in the
2166 *GNAT Project Manager* chapter of the *GPRbuild User's Guide*),
2167 the attribute ``Library_Interface`` must be defined.  For example:
2168
2169 .. code-block:: gpr
2170
2171        for Library_Dir use "lib_dir";
2172        for Library_Name use "dummy";
2173        for Library_Interface use ("int1", "int1.child");
2174
2175 Attribute ``Library_Interface`` has a non-empty string list value,
2176 each string in the list designating a unit contained in an immediate source
2177 of the project file.
2178
2179 When a Stand-alone Library is built, first the binder is invoked to build
2180 a package whose name depends on the library name
2181 (:file:`b~dummy.ads/b` in the example above).
2182 This binder-generated package includes initialization and
2183 finalization procedures whose
2184 names depend on the library name (``dummyinit`` and ``dummyfinal``
2185 in the example
2186 above). The object corresponding to this package is included in the library.
2187
2188 You must ensure timely (e.g., prior to any use of interfaces in the SAL)
2189 calling of these procedures if a static SAL is built, or if a shared SAL
2190 is built
2191 with the project-level attribute ``Library_Auto_Init`` set to
2192 ``"false"``.
2193
2194 For a Stand-Alone Library, only the :file:`ALI` files of the Interface Units
2195 (those that are listed in attribute ``Library_Interface``) are copied to
2196 the Library Directory. As a consequence, only the Interface Units may be
2197 imported from Ada units outside of the library. If other units are imported,
2198 the binding phase will fail.
2199
2200 It is also possible to build an encapsulated library where not only
2201 the code to elaborate and finalize the library is embedded but also
2202 ensuring that the library is linked only against static
2203 libraries. So an encapsulated library only depends on system
2204 libraries, all other code, including the GNAT runtime, is embedded. To
2205 build an encapsulated library the attribute
2206 ``Library_Standalone`` must be set to ``encapsulated``:
2207
2208 .. code-block:: gpr
2209
2210        for Library_Dir use "lib_dir";
2211        for Library_Name use "dummy";
2212        for Library_Kind use "dynamic";
2213        for Library_Interface use ("int1", "int1.child");
2214        for Library_Standalone use "encapsulated";
2215
2216 The default value for this attribute is ``standard`` in which case
2217 a stand-alone library is built.
2218
2219 The attribute ``Library_Src_Dir`` may be specified for a
2220 Stand-Alone Library. ``Library_Src_Dir`` is a simple attribute that has a
2221 single string value. Its value must be the path (absolute or relative to the
2222 project directory) of an existing directory. This directory cannot be the
2223 object directory or one of the source directories, but it can be the same as
2224 the library directory. The sources of the Interface
2225 Units of the library that are needed by an Ada client of the library will be
2226 copied to the designated directory, called the Interface Copy directory.
2227 These sources include the specs of the Interface Units, but they may also
2228 include bodies and subunits, when pragmas ``Inline`` or ``Inline_Always``
2229 are used, or when there is a generic unit in the spec. Before the sources
2230 are copied to the Interface Copy directory, an attempt is made to delete all
2231 files in the Interface Copy directory.
2232
2233 Building stand-alone libraries by hand is somewhat tedious, but for those
2234 occasions when it is necessary here are the steps that you need to perform:
2235
2236 * Compile all library sources.
2237
2238 * Invoke the binder with the switch :switch:`-n` (No Ada main program),
2239   with all the :file:`ALI` files of the interfaces, and
2240   with the switch :switch:`-L` to give specific names to the ``init``
2241   and ``final`` procedures.  For example:
2242
2243   .. code-block:: sh
2244
2245       $ gnatbind -n int1.ali int2.ali -Lsal1
2246
2247 * Compile the binder generated file:
2248
2249   .. code-block:: sh
2250
2251       $ gcc -c b~int2.adb
2252
2253 * Link the dynamic library with all the necessary object files,
2254   indicating to the linker the names of the ``init`` (and possibly
2255   ``final``) procedures for automatic initialization (and finalization).
2256   The built library should be placed in a directory different from
2257   the object directory.
2258
2259 * Copy the ``ALI`` files of the interface to the library directory,
2260   add in this copy an indication that it is an interface to a SAL
2261   (i.e., add a word ``SL`` on the line in the :file:`ALI` file that starts
2262   with letter 'P') and make the modified copy of the :file:`ALI` file
2263   read-only.
2264
2265 Using SALs is not different from using other libraries
2266 (see :ref:`Using_a_library`).
2267
2268 .. _Creating_a_Stand-alone_Library_to_be_used_in_a_non-Ada_context:
2269
2270 Creating a Stand-alone Library to be used in a non-Ada context
2271 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2272
2273 It is easy to adapt the SAL build procedure discussed above for use of a SAL in
2274 a non-Ada context.
2275
2276 The only extra step required is to ensure that library interface subprograms
2277 are compatible with the main program, by means of ``pragma Export``
2278 or ``pragma Convention``.
2279
2280 Here is an example of simple library interface for use with C main program:
2281
2282 .. code-block:: ada
2283
2284        package My_Package is
2285
2286           procedure Do_Something;
2287           pragma Export (C, Do_Something, "do_something");
2288
2289           procedure Do_Something_Else;
2290           pragma Export (C, Do_Something_Else, "do_something_else");
2291
2292        end My_Package;
2293
2294 On the foreign language side, you must provide a 'foreign' view of the
2295 library interface; remember that it should contain elaboration routines in
2296 addition to interface subprograms.
2297
2298 The example below shows the content of :file:`mylib_interface.h` (note
2299 that there is no rule for the naming of this file, any name can be used)
2300
2301 .. code-block:: c
2302
2303        /* the library elaboration procedure */
2304        extern void mylibinit (void);
2305
2306        /* the library finalization procedure */
2307        extern void mylibfinal (void);
2308
2309        /* the interface exported by the library */
2310        extern void do_something (void);
2311        extern void do_something_else (void);
2312
2313 Libraries built as explained above can be used from any program, provided
2314 that the elaboration procedures (named ``mylibinit`` in the previous
2315 example) are called before the library services are used. Any number of
2316 libraries can be used simultaneously, as long as the elaboration
2317 procedure of each library is called.
2318
2319 Below is an example of a C program that uses the ``mylib`` library.
2320
2321 .. code-block:: c
2322
2323        #include "mylib_interface.h"
2324
2325        int
2326        main (void)
2327        {
2328           /* First, elaborate the library before using it */
2329           mylibinit ();
2330
2331           /* Main program, using the library exported entities */
2332           do_something ();
2333           do_something_else ();
2334
2335           /* Library finalization at the end of the program */
2336           mylibfinal ();
2337           return 0;
2338        }
2339
2340 Note that invoking any library finalization procedure generated by
2341 ``gnatbind`` shuts down the Ada run-time environment.
2342 Consequently, the
2343 finalization of all Ada libraries must be performed at the end of the program.
2344 No call to these libraries or to the Ada run-time library should be made
2345 after the finalization phase.
2346
2347 Note also that special care must be taken with multi-tasks
2348 applications. The initialization and finalization routines are not
2349 protected against concurrent access. If such requirement is needed it
2350 must be ensured at the application level using a specific operating
2351 system services like a mutex or a critical-section.
2352
2353 .. _Restrictions_in_Stand-alone_Libraries:
2354
2355 Restrictions in Stand-alone Libraries
2356 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2357
2358 The pragmas listed below should be used with caution inside libraries,
2359 as they can create incompatibilities with other Ada libraries:
2360
2361 * pragma ``Locking_Policy``
2362 * pragma ``Partition_Elaboration_Policy``
2363 * pragma ``Queuing_Policy``
2364 * pragma ``Task_Dispatching_Policy``
2365 * pragma ``Unreserve_All_Interrupts``
2366
2367 When using a library that contains such pragmas, the user must make sure
2368 that all libraries use the same pragmas with the same values. Otherwise,
2369 ``Program_Error`` will
2370 be raised during the elaboration of the conflicting
2371 libraries. The usage of these pragmas and its consequences for the user
2372 should therefore be well documented.
2373
2374 Similarly, the traceback in the exception occurrence mechanism should be
2375 enabled or disabled in a consistent manner across all libraries.
2376 Otherwise, Program_Error will be raised during the elaboration of the
2377 conflicting libraries.
2378
2379 If the ``Version`` or ``Body_Version``
2380 attributes are used inside a library, then you need to
2381 perform a ``gnatbind`` step that specifies all :file:`ALI` files in all
2382 libraries, so that version identifiers can be properly computed.
2383 In practice these attributes are rarely used, so this is unlikely
2384 to be a consideration.
2385
2386 .. _Rebuilding_the_GNAT_Run-Time_Library:
2387
2388 Rebuilding the GNAT Run-Time Library
2389 ------------------------------------
2390
2391 .. index:: GNAT Run-Time Library, rebuilding
2392 .. index:: Building the GNAT Run-Time Library
2393 .. index:: Rebuilding the GNAT Run-Time Library
2394 .. index:: Run-Time Library, rebuilding
2395
2396 It may be useful to recompile the GNAT library in various contexts, the
2397 most important one being the use of partition-wide configuration pragmas
2398 such as ``Normalize_Scalars``. A special Makefile called
2399 :file:`Makefile.adalib` is provided to that effect and can be found in
2400 the directory containing the GNAT library. The location of this
2401 directory depends on the way the GNAT environment has been installed and can
2402 be determined by means of the command:
2403
2404 .. code-block:: sh
2405
2406       $ gnatls -v
2407
2408 The last entry in the object search path usually contains the
2409 gnat library. This Makefile contains its own documentation and in
2410 particular the set of instructions needed to rebuild a new library and
2411 to use it.
2412
2413
2414 .. index:: ! Conditional compilation
2415
2416 .. _Conditional_Compilation:
2417
2418 Conditional Compilation
2419 =======================
2420
2421 This section presents some guidelines for modeling conditional compilation in Ada and describes the
2422 gnatprep preprocessor utility.
2423
2424 .. index:: ! Conditional compilation
2425
2426 .. _Modeling_Conditional_Compilation_in_Ada:
2427
2428 Modeling Conditional Compilation in Ada
2429 ---------------------------------------
2430
2431 It is often necessary to arrange for a single source program
2432 to serve multiple purposes, where it is compiled in different
2433 ways to achieve these different goals. Some examples of the
2434 need for this feature are
2435
2436 * Adapting a program to a different hardware environment
2437 * Adapting a program to a different target architecture
2438 * Turning debugging features on and off
2439 * Arranging for a program to compile with different compilers
2440
2441 In C, or C++, the typical approach would be to use the preprocessor
2442 that is defined as part of the language. The Ada language does not
2443 contain such a feature. This is not an oversight, but rather a very
2444 deliberate design decision, based on the experience that overuse of
2445 the preprocessing features in C and C++ can result in programs that
2446 are extremely difficult to maintain. For example, if we have ten
2447 switches that can be on or off, this means that there are a thousand
2448 separate programs, any one of which might not even be syntactically
2449 correct, and even if syntactically correct, the resulting program
2450 might not work correctly. Testing all combinations can quickly become
2451 impossible.
2452
2453 Nevertheless, the need to tailor programs certainly exists, and in
2454 this section we will discuss how this can
2455 be achieved using Ada in general, and GNAT in particular.
2456
2457 .. _Use_of_Boolean_Constants:
2458
2459 Use of Boolean Constants
2460 ^^^^^^^^^^^^^^^^^^^^^^^^
2461
2462 In the case where the difference is simply which code
2463 sequence is executed, the cleanest solution is to use Boolean
2464 constants to control which code is executed.
2465
2466 .. code-block:: ada
2467
2468       FP_Initialize_Required : constant Boolean := True;
2469       ...
2470       if FP_Initialize_Required then
2471       ...
2472       end if;
2473
2474 Not only will the code inside the ``if`` statement not be executed if
2475 the constant Boolean is ``False``, but it will also be completely
2476 deleted from the program.
2477 However, the code is only deleted after the ``if`` statement
2478 has been checked for syntactic and semantic correctness.
2479 (In contrast, with preprocessors the code is deleted before the
2480 compiler ever gets to see it, so it is not checked until the switch
2481 is turned on.)
2482
2483 .. index:: Preprocessors (contrasted with conditional compilation)
2484
2485 Typically the Boolean constants will be in a separate package,
2486 something like:
2487
2488 .. code-block:: ada
2489
2490        package Config is
2491           FP_Initialize_Required : constant Boolean := True;
2492           Reset_Available        : constant Boolean := False;
2493           ...
2494        end Config;
2495
2496 The ``Config`` package exists in multiple forms for the various targets,
2497 with an appropriate script selecting the version of ``Config`` needed.
2498 Then any other unit requiring conditional compilation can do a |with|
2499 of ``Config`` to make the constants visible.
2500
2501 .. _Debugging_-_A_Special_Case:
2502
2503 Debugging - A Special Case
2504 ^^^^^^^^^^^^^^^^^^^^^^^^^^
2505
2506 A common use of conditional code is to execute statements (for example
2507 dynamic checks, or output of intermediate results) under control of a
2508 debug switch, so that the debugging behavior can be turned on and off.
2509 This can be done using a Boolean constant to control whether the code
2510 is active:
2511
2512 .. code-block:: ada
2513
2514        if Debugging then
2515           Put_Line ("got to the first stage!");
2516        end if;
2517
2518 or
2519
2520 .. code-block:: ada
2521
2522        if Debugging and then Temperature > 999.0 then
2523           raise Temperature_Crazy;
2524        end if;
2525
2526 .. index:: pragma Assert
2527
2528 Since this is a common case, there are special features to deal with
2529 this in a convenient manner. For the case of tests, Ada 2005 has added
2530 a pragma ``Assert`` that can be used for such tests. This pragma is modeled
2531 on the ``Assert`` pragma that has always been available in GNAT, so this
2532 feature may be used with GNAT even if you are not using Ada 2005 features.
2533 The use of pragma ``Assert`` is described in the
2534 :title:`GNAT_Reference_Manual`, but as an
2535 example, the last test could be written:
2536
2537 .. code-block:: ada
2538
2539        pragma Assert (Temperature <= 999.0, "Temperature Crazy");
2540
2541 or simply
2542
2543 .. code-block:: ada
2544
2545        pragma Assert (Temperature <= 999.0);
2546
2547 In both cases, if assertions are active and the temperature is excessive,
2548 the exception ``Assert_Failure`` will be raised, with the given string in
2549 the first case or a string indicating the location of the pragma in the second
2550 case used as the exception message.
2551
2552 .. index:: pragma Assertion_Policy
2553
2554 You can turn assertions on and off by using the ``Assertion_Policy``
2555 pragma.
2556
2557 .. index:: -gnata switch
2558
2559 This is an Ada 2005 pragma which is implemented in all modes by
2560 GNAT. Alternatively, you can use the :switch:`-gnata` switch
2561 to enable assertions from the command line, which applies to
2562 all versions of Ada.
2563
2564 .. index:: pragma Debug
2565
2566 For the example above with the ``Put_Line``, the GNAT-specific pragma
2567 ``Debug`` can be used:
2568
2569 .. code-block:: ada
2570
2571        pragma Debug (Put_Line ("got to the first stage!"));
2572
2573 If debug pragmas are enabled, the argument, which must be of the form of
2574 a procedure call, is executed (in this case, ``Put_Line`` will be called).
2575 Only one call can be present, but of course a special debugging procedure
2576 containing any code you like can be included in the program and then
2577 called in a pragma ``Debug`` argument as needed.
2578
2579 One advantage of pragma ``Debug`` over the ``if Debugging then``
2580 construct is that pragma ``Debug`` can appear in declarative contexts,
2581 such as at the very beginning of a procedure, before local declarations have
2582 been elaborated.
2583
2584 .. index:: pragma Debug_Policy
2585
2586 Debug pragmas are enabled using either the :switch:`-gnata` switch that also
2587 controls assertions, or with a separate Debug_Policy pragma.
2588
2589 The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used
2590 in Ada 95 and Ada 83 programs as well), and is analogous to
2591 pragma ``Assertion_Policy`` to control assertions.
2592
2593 ``Assertion_Policy`` and ``Debug_Policy`` are configuration pragmas,
2594 and thus they can appear in :file:`gnat.adc` if you are not using a
2595 project file, or in the file designated to contain configuration pragmas
2596 in a project file.
2597 They then apply to all subsequent compilations. In practice the use of
2598 the :switch:`-gnata` switch is often the most convenient method of controlling
2599 the status of these pragmas.
2600
2601 Note that a pragma is not a statement, so in contexts where a statement
2602 sequence is required, you can't just write a pragma on its own. You have
2603 to add a ``null`` statement.
2604
2605 .. code-block:: ada
2606
2607        if ... then
2608           ... -- some statements
2609        else
2610           pragma Assert (Num_Cases < 10);
2611           null;
2612        end if;
2613
2614 .. _Conditionalizing_Declarations:
2615
2616 Conditionalizing Declarations
2617 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2618
2619 In some cases it may be necessary to conditionalize declarations to meet
2620 different requirements. For example we might want a bit string whose length
2621 is set to meet some hardware message requirement.
2622
2623 This may be possible using declare blocks controlled
2624 by conditional constants:
2625
2626 .. code-block:: ada
2627
2628        if Small_Machine then
2629           declare
2630              X : Bit_String (1 .. 10);
2631           begin
2632              ...
2633           end;
2634        else
2635           declare
2636              X : Large_Bit_String (1 .. 1000);
2637           begin
2638              ...
2639           end;
2640        end if;
2641
2642 Note that in this approach, both declarations are analyzed by the
2643 compiler so this can only be used where both declarations are legal,
2644 even though one of them will not be used.
2645
2646 Another approach is to define integer constants, e.g., ``Bits_Per_Word``,
2647 or Boolean constants, e.g., ``Little_Endian``, and then write declarations
2648 that are parameterized by these constants. For example
2649
2650 .. code-block:: ada
2651
2652        for Rec use
2653          Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word;
2654        end record;
2655
2656 If ``Bits_Per_Word`` is set to 32, this generates either
2657
2658 .. code-block:: ada
2659
2660        for Rec use
2661          Field1 at 0 range 0 .. 32;
2662        end record;
2663
2664 for the big endian case, or
2665
2666 .. code-block:: ada
2667
2668        for Rec use record
2669            Field1 at 0 range 10 .. 32;
2670        end record;
2671
2672 for the little endian case. Since a powerful subset of Ada expression
2673 notation is usable for creating static constants, clever use of this
2674 feature can often solve quite difficult problems in conditionalizing
2675 compilation (note incidentally that in Ada 95, the little endian
2676 constant was introduced as ``System.Default_Bit_Order``, so you do not
2677 need to define this one yourself).
2678
2679 .. _Use_of_Alternative_Implementations:
2680
2681 Use of Alternative Implementations
2682 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2683
2684 In some cases, none of the approaches described above are adequate. This
2685 can occur for example if the set of declarations required is radically
2686 different for two different configurations.
2687
2688 In this situation, the official Ada way of dealing with conditionalizing
2689 such code is to write separate units for the different cases. As long as
2690 this does not result in excessive duplication of code, this can be done
2691 without creating maintenance problems. The approach is to share common
2692 code as far as possible, and then isolate the code and declarations
2693 that are different. Subunits are often a convenient method for breaking
2694 out a piece of a unit that is to be conditionalized, with separate files
2695 for different versions of the subunit for different targets, where the
2696 build script selects the right one to give to the compiler.
2697
2698 .. index:: Subunits (and conditional compilation)
2699
2700 As an example, consider a situation where a new feature in Ada 2005
2701 allows something to be done in a really nice way. But your code must be able
2702 to compile with an Ada 95 compiler. Conceptually you want to say:
2703
2704 .. code-block:: ada
2705
2706        if Ada_2005 then
2707           ... neat Ada 2005 code
2708        else
2709           ... not quite as neat Ada 95 code
2710        end if;
2711
2712 where ``Ada_2005`` is a Boolean constant.
2713
2714 But this won't work when ``Ada_2005`` is set to ``False``,
2715 since the ``then`` clause will be illegal for an Ada 95 compiler.
2716 (Recall that although such unreachable code would eventually be deleted
2717 by the compiler, it still needs to be legal.  If it uses features
2718 introduced in Ada 2005, it will be illegal in Ada 95.)
2719
2720 So instead we write
2721
2722 .. code-block:: ada
2723
2724        procedure Insert is separate;
2725
2726 Then we have two files for the subunit ``Insert``, with the two sets of
2727 code.
2728 If the package containing this is called ``File_Queries``, then we might
2729 have two files
2730
2731 * :file:`file_queries-insert-2005.adb`
2732 * :file:`file_queries-insert-95.adb`
2733
2734 and the build script renames the appropriate file to :file:`file_queries-insert.adb` and then carries out the compilation.
2735
2736 This can also be done with project files' naming schemes. For example:
2737
2738 .. code-block:: gpr
2739
2740        for body ("File_Queries.Insert") use "file_queries-insert-2005.ada";
2741
2742 Note also that with project files it is desirable to use a different extension
2743 than :file:`ads` / :file:`adb` for alternative versions. Otherwise a naming
2744 conflict may arise through another commonly used feature: to declare as part
2745 of the project a set of directories containing all the sources obeying the
2746 default naming scheme.
2747
2748 The use of alternative units is certainly feasible in all situations,
2749 and for example the Ada part of the GNAT run-time is conditionalized
2750 based on the target architecture using this approach. As a specific example,
2751 consider the implementation of the AST feature in VMS. There is one
2752 spec: :file:`s-asthan.ads` which is the same for all architectures, and three
2753 bodies:
2754
2755 * :file:`s-asthan.adb`
2756     used for all non-VMS operating systems
2757
2758 * :file:`s-asthan-vms-alpha.adb`
2759     used for VMS on the Alpha
2760
2761 * :file:`s-asthan-vms-ia64.adb`
2762     used for VMS on the ia64
2763
2764 The dummy version :file:`s-asthan.adb` simply raises exceptions noting that
2765 this operating system feature is not available, and the two remaining
2766 versions interface with the corresponding versions of VMS to provide
2767 VMS-compatible AST handling. The GNAT build script knows the architecture
2768 and operating system, and automatically selects the right version,
2769 renaming it if necessary to :file:`s-asthan.adb` before the run-time build.
2770
2771 Another style for arranging alternative implementations is through Ada's
2772 access-to-subprogram facility.
2773 In case some functionality is to be conditionally included,
2774 you can declare an access-to-procedure variable ``Ref`` that is initialized
2775 to designate a 'do nothing' procedure, and then invoke ``Ref.all``
2776 when appropriate.
2777 In some library package, set ``Ref`` to ``Proc'Access`` for some
2778 procedure ``Proc`` that performs the relevant processing.
2779 The initialization only occurs if the library package is included in the
2780 program.
2781 The same idea can also be implemented using tagged types and dispatching
2782 calls.
2783
2784 .. _Preprocessing:
2785
2786 Preprocessing
2787 ^^^^^^^^^^^^^
2788
2789 .. index:: Preprocessing
2790
2791 Although it is quite possible to conditionalize code without the use of
2792 C-style preprocessing, as described earlier in this section, it is
2793 nevertheless convenient in some cases to use the C approach. Moreover,
2794 older Ada compilers have often provided some preprocessing capability,
2795 so legacy code may depend on this approach, even though it is not
2796 standard.
2797
2798 To accommodate such use, GNAT provides a preprocessor (modeled to a large
2799 extent on the various preprocessors that have been used
2800 with legacy code on other compilers, to enable easier transition).
2801
2802 .. index:: gnatprep
2803
2804 The preprocessor may be used in two separate modes. It can be used quite
2805 separately from the compiler, to generate a separate output source file
2806 that is then fed to the compiler as a separate step. This is the
2807 ``gnatprep`` utility, whose use is fully described in
2808 :ref:`Preprocessing_with_gnatprep`.
2809
2810 The preprocessing language allows such constructs as
2811
2812 .. code-block:: c
2813
2814        #if DEBUG or else (PRIORITY > 4) then
2815           sequence of declarations
2816        #else
2817           completely different sequence of declarations
2818        #end if;
2819
2820 The values of the symbols ``DEBUG`` and ``PRIORITY`` can be
2821 defined either on the command line or in a separate file.
2822
2823 The other way of running the preprocessor is even closer to the C style and
2824 often more convenient. In this approach the preprocessing is integrated into
2825 the compilation process. The compiler is given the preprocessor input which
2826 includes ``#if`` lines etc, and then the compiler carries out the
2827 preprocessing internally and processes the resulting output.
2828 For more details on this approach, see :ref:`Integrated_Preprocessing`.
2829
2830 .. _Preprocessing_with_gnatprep:
2831
2832 Preprocessing with ``gnatprep``
2833 -------------------------------
2834
2835 .. index:: ! gnatprep
2836 .. index:: Preprocessing (gnatprep)
2837
2838 This section discusses how to use GNAT's ``gnatprep`` utility for simple
2839 preprocessing.
2840 Although designed for use with GNAT, ``gnatprep`` does not depend on any
2841 special GNAT features.
2842 For further discussion of conditional compilation in general, see
2843 :ref:`Conditional_Compilation`.
2844
2845 .. _Preprocessing_Symbols:
2846
2847 Preprocessing Symbols
2848 ^^^^^^^^^^^^^^^^^^^^^
2849
2850 Preprocessing symbols are defined in *definition files* and referenced in the
2851 sources to be preprocessed. A preprocessing symbol is an identifier, following
2852 normal Ada (case-insensitive) rules for its syntax, with the restriction that
2853 all characters need to be in the ASCII set (no accented letters).
2854
2855 .. _Using_gnatprep:
2856
2857 Using ``gnatprep``
2858 ^^^^^^^^^^^^^^^^^^
2859
2860 To call ``gnatprep`` use:
2861
2862 .. code-block:: sh
2863
2864     $ gnatprep [ switches ] infile outfile [ deffile ]
2865
2866 where
2867
2868 * *switches*
2869     is an optional sequence of switches as described in the next section.
2870
2871 * *infile*
2872     is the full name of the input file, which is an Ada source
2873     file containing preprocessor directives.
2874
2875 * *outfile*
2876     is the full name of the output file, which is an Ada source
2877     in standard Ada form. When used with GNAT, this file name will
2878     normally have an ``ads`` or ``adb`` suffix.
2879
2880 * ``deffile``
2881     is the full name of a text file containing definitions of
2882     preprocessing symbols to be referenced by the preprocessor. This argument is
2883     optional, and can be replaced by the use of the :switch:`-D` switch.
2884
2885
2886 .. _Switches_for_gnatprep:
2887
2888 Switches for ``gnatprep``
2889 ^^^^^^^^^^^^^^^^^^^^^^^^^
2890
2891 .. index:: --version (gnatprep)
2892
2893 :switch:`--version`
2894   Display Copyright and version, then exit disregarding all other options.
2895
2896 .. index:: --help (gnatprep)
2897
2898 :switch:`--help`
2899   If :switch:`--version` was not used, display usage and then exit disregarding
2900   all other options.
2901
2902 .. index:: -b (gnatprep)
2903
2904 :switch:`-b`
2905   Causes both preprocessor lines and the lines deleted by
2906   preprocessing to be replaced by blank lines in the output source file,
2907   preserving line numbers in the output file.
2908
2909 .. index:: -c (gnatprep)
2910
2911 :switch:`-c`
2912   Causes both preprocessor lines and the lines deleted
2913   by preprocessing to be retained in the output source as comments marked
2914   with the special string ``"--! "``. This option will result in line numbers
2915   being preserved in the output file.
2916
2917 .. index:: -C (gnatprep)
2918
2919 :switch:`-C`
2920   Causes comments to be scanned. Normally comments are ignored by gnatprep.
2921   If this option is specified, then comments are scanned and any $symbol
2922   substitutions performed as in program text. This is particularly useful
2923   when structured comments are used (e.g., for programs written in a
2924   pre-2014 version of the SPARK Ada subset). Note that this switch is not
2925   available when  doing integrated preprocessing (it would be useless in
2926   this context since comments are ignored by the compiler in any case).
2927
2928 .. index:: -D (gnatprep)
2929
2930 :switch:`-D{symbol}[={value}]`
2931   Defines a new preprocessing symbol with the specified value. If no value is given
2932   on the command line, then symbol is considered to be ``True``. This switch
2933   can be used in place of a definition file.
2934
2935 .. index:: -r (gnatprep)
2936
2937 :switch:`-r`
2938   Causes a ``Source_Reference`` pragma to be generated that
2939   references the original input file, so that error messages will use
2940   the file name of this original file. The use of this switch implies
2941   that preprocessor lines are not to be removed from the file, so its
2942   use will force ``-b`` mode if ``-c``
2943   has not been specified explicitly.
2944
2945   Note that if the file to be preprocessed contains multiple units, then
2946   it will be necessary to ``gnatchop`` the output file from
2947   ``gnatprep``. If a ``Source_Reference`` pragma is present
2948   in the preprocessed file, it will be respected by
2949   ``gnatchop -r``
2950   so that the final chopped files will correctly refer to the original
2951   input source file for ``gnatprep``.
2952
2953 .. index:: -s (gnatprep)
2954
2955 :switch:`-s`
2956   Causes a sorted list of symbol names and values to be
2957   listed on the standard output file.
2958
2959 .. index:: -T (gnatprep)
2960
2961 :switch:`-T`
2962   Use LF as line terminators when writing files. By default the line terminator
2963   of the host (LF under unix, CR/LF under Windows) is used.
2964
2965 .. index:: -u (gnatprep)
2966
2967 :switch:`-u`
2968   Causes undefined symbols to be treated as having the value FALSE in the context
2969   of a preprocessor test. In the absence of this option, an undefined symbol in
2970   a ``#if`` or ``#elsif`` test will be treated as an error.
2971
2972 .. index:: -v (gnatprep)
2973
2974 :switch:`-v`
2975   Verbose mode: generates more output about work done.
2976
2977
2978 Note: if neither :switch:`-b` nor :switch:`-c` is present,
2979 then preprocessor lines and
2980 deleted lines are completely removed from the output, unless -r is
2981 specified, in which case -b is assumed.
2982
2983
2984 .. _Form_of_Definitions_File:
2985
2986 Form of Definitions File
2987 ^^^^^^^^^^^^^^^^^^^^^^^^
2988
2989 The definitions file contains lines of the form::
2990
2991       symbol := value
2992
2993 where ``symbol`` is a preprocessing symbol, and ``value`` is one of the following:
2994
2995 *  Empty, corresponding to a null substitution,
2996 *  A string literal using normal Ada syntax, or
2997 *  Any sequence of characters from the set {letters, digits, period, underline}.
2998
2999 Comment lines may also appear in the definitions file, starting with
3000 the usual ``--``,
3001 and comments may be added to the definitions lines.
3002
3003
3004 .. _Form_of_Input_Text_for_gnatprep:
3005
3006 Form of Input Text for ``gnatprep``
3007 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3008
3009 The input text may contain preprocessor conditional inclusion lines,
3010 as well as general symbol substitution sequences.
3011
3012 The preprocessor conditional inclusion commands have the form:
3013
3014 .. code-block:: c
3015
3016        #if <expression> [then]
3017           lines
3018        #elsif <expression> [then]
3019           lines
3020        #elsif <expression> [then]
3021           lines
3022        ...
3023        #else
3024           lines
3025        #end if;
3026
3027 In this example, <expression> is defined by the following grammar::
3028
3029        <expression> ::=  <symbol>
3030        <expression> ::=  <symbol> = "<value>"
3031        <expression> ::=  <symbol> = <symbol>
3032        <expression> ::=  <symbol> = <integer>
3033        <expression> ::=  <symbol> > <integer>
3034        <expression> ::=  <symbol> >= <integer>
3035        <expression> ::=  <symbol> < <integer>
3036        <expression> ::=  <symbol> <= <integer>
3037        <expression> ::=  <symbol> 'Defined
3038        <expression> ::=  not <expression>
3039        <expression> ::=  <expression> and <expression>
3040        <expression> ::=  <expression> or <expression>
3041        <expression> ::=  <expression> and then <expression>
3042        <expression> ::=  <expression> or else <expression>
3043        <expression> ::=  ( <expression> )
3044
3045 Note the following restriction: it is not allowed to have "and" or "or"
3046 following "not" in the same expression without parentheses. For example, this
3047 is not allowed:
3048
3049 .. code-block:: ada
3050
3051        not X or Y
3052
3053 This can be expressed instead as one of the following forms:
3054
3055 .. code-block:: ada
3056
3057      (not X) or Y
3058      not (X or Y)
3059
3060 For the first test (<expression> ::= <symbol>) the symbol must have
3061 either the value true or false, that is to say the right-hand of the
3062 symbol definition must be one of the (case-insensitive) literals
3063 ``True`` or ``False``. If the value is true, then the
3064 corresponding lines are included, and if the value is false, they are
3065 excluded.
3066
3067 When comparing a symbol to an integer, the integer is any non negative
3068 literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or
3069 2#11#. The symbol value must also be a non negative integer. Integer values
3070 in the range 0 .. 2**31-1 are supported.
3071
3072 The test (<expression> ::= <symbol>'Defined) is true only if
3073 the symbol has been defined in the definition file or by a :switch:`-D`
3074 switch on the command line. Otherwise, the test is false.
3075
3076 The equality tests are case insensitive, as are all the preprocessor lines.
3077
3078 If the symbol referenced is not defined in the symbol definitions file,
3079 then the effect depends on whether or not switch :switch:`-u`
3080 is specified. If so, then the symbol is treated as if it had the value
3081 false and the test fails. If this switch is not specified, then
3082 it is an error to reference an undefined symbol. It is also an error to
3083 reference a symbol that is defined with a value other than ``True``
3084 or ``False``.
3085
3086 The use of the ``not`` operator inverts the sense of this logical test.
3087 The ``not`` operator cannot be combined with the ``or`` or ``and``
3088 operators, without parentheses. For example, "if not X or Y then" is not
3089 allowed, but "if (not X) or Y then" and "if not (X or Y) then" are.
3090
3091 The ``then`` keyword is optional as shown
3092
3093 The ``#`` must be the first non-blank character on a line, but
3094 otherwise the format is free form. Spaces or tabs may appear between
3095 the ``#`` and the keyword. The keywords and the symbols are case
3096 insensitive as in normal Ada code. Comments may be used on a
3097 preprocessor line, but other than that, no other tokens may appear on a
3098 preprocessor line. Any number of ``elsif`` clauses can be present,
3099 including none at all. The ``else`` is optional, as in Ada.
3100
3101 The ``#`` marking the start of a preprocessor line must be the first
3102 non-blank character on the line, i.e., it must be preceded only by
3103 spaces or horizontal tabs.
3104
3105 Symbol substitution outside of preprocessor lines is obtained by using
3106 the sequence::
3107
3108       $symbol
3109
3110 anywhere within a source line, except in a comment or within a
3111 string literal. The identifier
3112 following the ``$`` must match one of the symbols defined in the symbol
3113 definition file, and the result is to substitute the value of the
3114 symbol in place of ``$symbol`` in the output file.
3115
3116 Note that although the substitution of strings within a string literal
3117 is not possible, it is possible to have a symbol whose defined value is
3118 a string literal. So instead of setting XYZ to ``hello`` and writing:
3119
3120 .. code-block:: ada
3121
3122      Header : String := "$XYZ";
3123
3124 you should set XYZ to ``"hello"`` and write:
3125
3126 .. code-block:: ada
3127
3128      Header : String := $XYZ;
3129
3130 and then the substitution will occur as desired.
3131
3132
3133 .. _Integrated_Preprocessing:
3134
3135 Integrated Preprocessing
3136 ------------------------
3137
3138 As noted above, a file to be preprocessed consists of Ada source code
3139 in which preprocessing lines have been inserted. However,
3140 instead of using ``gnatprep`` to explicitly preprocess a file as a separate
3141 step before compilation, you can carry out the preprocessing implicitly
3142 as part of compilation. Such *integrated preprocessing*, which is the common
3143 style with C, is performed when either or both of the following switches
3144 are passed to the compiler:
3145
3146    *   :switch:`-gnatep`, which specifies the *preprocessor data file*.
3147        This file dictates how the source files will be preprocessed (e.g., which
3148        symbol definition files apply to which sources).
3149
3150    *   :switch:`-gnateD`, which defines values for preprocessing symbols.
3151
3152 Integrated preprocessing applies only to Ada source files, it is
3153 not available for configuration pragma files.
3154
3155 With integrated preprocessing, the output from the preprocessor is not,
3156 by default, written to any external file. Instead it is passed
3157 internally to the compiler. To preserve the result of
3158 preprocessing in a file, either run ``gnatprep``
3159 in standalone mode or else supply the :switch:`-gnateG` switch
3160 (described below) to the compiler.
3161
3162 When using project files:
3163
3164    *    the builder switch :switch:`-x` should be used if any Ada source is
3165         compiled with :switch:`gnatep=`, so that the compiler finds the
3166         *preprocessor data file*.
3167
3168    *    the preprocessing data file and the symbol definition files should be
3169         located in the source directories of the project.
3170
3171 Note that the ``gnatmake`` switch :switch:`-m` will almost
3172 always trigger recompilation for sources that are preprocessed,
3173 because ``gnatmake`` cannot compute the checksum of the source after
3174 preprocessing.
3175
3176 The actual preprocessing function is described in detail in
3177 :ref:`Preprocessing_with_gnatprep`. This section explains the switches
3178 that relate to integrated preprocessing.
3179
3180 .. index:: -gnatep (gcc)
3181
3182 :switch:`-gnatep={preprocessor_data_file}`
3183   This switch specifies the file name (without directory
3184   information) of the preprocessor data file. Either place this file
3185   in one of the source directories, or, when using project
3186   files, reference the project file's directory via the
3187   ``project_name'Project_Dir`` project attribute; e.g:
3188
3189      .. code-block:: gpr
3190
3191          project Prj is
3192             package Compiler is
3193                for Switches ("Ada") use
3194                  ("-gnatep=" & Prj'Project_Dir & "prep.def");
3195             end Compiler;
3196          end Prj;
3197
3198   A preprocessor data file is a text file that contains *preprocessor
3199   control lines*.  A preprocessor control line directs the preprocessing of
3200   either a particular source file, or, analogous to ``others`` in Ada,
3201   all sources not specified elsewhere in  the preprocessor data file.
3202   A preprocessor control line
3203   can optionally identify a *definition file* that assigns values to
3204   preprocessor symbols, as well as a list of switches that relate to
3205   preprocessing.
3206   Empty lines and comments (using Ada syntax) are also permitted, with no
3207   semantic effect.
3208
3209   Here's an example of a preprocessor data file:
3210
3211     .. code-block:: ada
3212
3213         "toto.adb"  "prep.def" -u
3214         --  Preprocess toto.adb, using definition file prep.def
3215         --  Undefined symbols are treated as False
3216
3217         * -c -DVERSION=V101
3218         --  Preprocess all other sources without using a definition file
3219         --  Suppressed lined are commented
3220         --  Symbol VERSION has the value V101
3221
3222         "tata.adb" "prep2.def" -s
3223         --  Preprocess tata.adb, using definition file prep2.def
3224         --  List all symbols with their values
3225
3226   A preprocessor control line has the following syntax:
3227
3228     ::
3229
3230         <preprocessor_control_line> ::=
3231            <preprocessor_input> [ <definition_file_name> ] { <switch> }
3232
3233         <preprocessor_input> ::= <source_file_name> | '*'
3234
3235         <definition_file_name> ::= <string_literal>
3236
3237         <source_file_name> := <string_literal>
3238
3239         <switch> := (See below for list)
3240
3241   Thus  each preprocessor control line starts with either a literal string or
3242   the character '*':
3243
3244   *  A literal string is the file name (without directory information) of the source
3245      file that will be input to the preprocessor.
3246
3247   *  The character '*' is a wild-card indicator; the additional parameters on the line
3248      indicate the preprocessing for all the sources
3249      that are not specified explicitly on other lines (the order of the lines is not
3250      significant).
3251
3252   It is an error to have two lines with the same file name or two
3253   lines starting with the character '*'.
3254
3255   After the file name or '*', an optional literal string specifies the name of
3256   the definition file to be used for preprocessing
3257   (:ref:`Form_of_Definitions_File`). The definition files are found by the
3258   compiler in one of the source directories. In some cases, when compiling
3259   a source in a directory other than the current directory, if the definition
3260   file is in the current directory, it may be necessary to add the current
3261   directory as a source directory through the :switch:`-I` switch; otherwise
3262   the compiler would not find the definition file.
3263
3264   Finally, switches similar to those of ``gnatprep`` may optionally appear:
3265
3266   :switch:`-b`
3267     Causes both preprocessor lines and the lines deleted by
3268     preprocessing to be replaced by blank lines, preserving the line number.
3269     This switch is always implied; however, if specified after :switch:`-c`
3270     it cancels the effect of :switch:`-c`.
3271
3272
3273   :switch:`-c`
3274     Causes both preprocessor lines and the lines deleted
3275     by preprocessing to be retained as comments marked
3276     with the special string '`--!`'.
3277
3278
3279   :switch:`-D{symbol}={new_value}`
3280     Define or redefine ``symbol`` to have ``new_value`` as its value.
3281     The permitted form for ``symbol`` is either an Ada identifier, or any Ada reserved word
3282     aside from ``if``,
3283     ``else``, ``elsif``, ``end``, ``and``, ``or`` and ``then``.
3284     The permitted form for ``new_value`` is a literal string, an Ada identifier or any Ada reserved
3285     word. A symbol declared with this switch replaces a symbol with the
3286     same name defined in a definition file.
3287
3288
3289   :switch:`-s`
3290     Causes a sorted list of symbol names and values to be
3291     listed on the standard output file.
3292
3293
3294   :switch:`-u`
3295     Causes undefined symbols to be treated as having the value ``FALSE``
3296     in the context
3297     of a preprocessor test. In the absence of this option, an undefined symbol in
3298     a ``#if`` or ``#elsif`` test will be treated as an error.
3299
3300
3301 .. index:: -gnateD (gcc)
3302
3303 :switch:`-gnateD{symbol}[={new_value}]`
3304   Define or redefine ``symbol`` to have ``new_value`` as its value. If no value
3305   is supplied, then the value of ``symbol`` is ``True``.
3306   The form of ``symbol`` is an identifier, following normal Ada (case-insensitive)
3307   rules for its syntax, and ``new_value`` is either an arbitrary string between double
3308   quotes or any sequence (including an empty sequence) of characters from the
3309   set (letters, digits, period, underline).
3310   Ada reserved words may be used as symbols, with the exceptions of ``if``,
3311   ``else``, ``elsif``, ``end``, ``and``, ``or`` and ``then``.
3312
3313   Examples:
3314
3315     ::
3316
3317         -gnateDToto=Tata
3318         -gnateDFoo
3319         -gnateDFoo=\"Foo-Bar\"
3320
3321   A symbol declared with this switch on the command line replaces a
3322   symbol with the same name either in a definition file or specified with a
3323   switch :switch:`-D` in the preprocessor data file.
3324
3325   This switch is similar to switch :switch:`-D` of ``gnatprep``.
3326
3327
3328 :switch:`-gnateG`
3329   When integrated preprocessing is performed on source file :file:`filename.extension`,
3330   create or overwrite :file:`filename.extension.prep` to contain
3331   the result of the preprocessing.
3332   For example if the source file is :file:`foo.adb` then
3333   the output file will be :file:`foo.adb.prep`.
3334
3335
3336 .. _Mixed_Language_Programming:
3337
3338 Mixed Language Programming
3339 ==========================
3340
3341 .. index:: Mixed Language Programming
3342
3343 This section describes how to develop a mixed-language program,
3344 with a focus on combining Ada with C or C++.
3345
3346 .. _Interfacing_to_C:
3347
3348 Interfacing to C
3349 ----------------
3350
3351 Interfacing Ada with a foreign language such as C involves using
3352 compiler directives to import and/or export entity definitions in each
3353 language -- using ``extern`` statements in C, for instance, and the
3354 ``Import``, ``Export``, and ``Convention`` pragmas in Ada.
3355 A full treatment of these topics is provided in Appendix B, section 1
3356 of the Ada Reference Manual.
3357
3358 There are two ways to build a program using GNAT that contains some Ada
3359 sources and some foreign language sources, depending on whether or not
3360 the main subprogram is written in Ada.  Here is a source example with
3361 the main subprogram in Ada:
3362
3363 .. code-block:: c
3364
3365     /* file1.c */
3366     #include <stdio.h>
3367
3368     void print_num (int num)
3369     {
3370       printf ("num is %d.\\n", num);
3371       return;
3372     }
3373
3374 .. code-block:: c
3375
3376     /* file2.c */
3377
3378     /* num_from_Ada is declared in my_main.adb */
3379     extern int num_from_Ada;
3380
3381     int get_num (void)
3382     {
3383       return num_from_Ada;
3384     }
3385
3386 .. code-block:: ada
3387
3388     --  my_main.adb
3389     procedure My_Main is
3390
3391        --  Declare then export an Integer entity called num_from_Ada
3392        My_Num : Integer := 10;
3393        pragma Export (C, My_Num, "num_from_Ada");
3394
3395        --  Declare an Ada function spec for Get_Num, then use
3396        --  C function get_num for the implementation.
3397        function Get_Num return Integer;
3398        pragma Import (C, Get_Num, "get_num");
3399
3400        --  Declare an Ada procedure spec for Print_Num, then use
3401        --  C function print_num for the implementation.
3402        procedure Print_Num (Num : Integer);
3403        pragma Import (C, Print_Num, "print_num");
3404
3405     begin
3406        Print_Num (Get_Num);
3407     end My_Main;
3408
3409 To build this example:
3410
3411 * First compile the foreign language files to
3412   generate object files:
3413
3414   .. code-block:: sh
3415
3416       $ gcc -c file1.c
3417       $ gcc -c file2.c
3418
3419 * Then, compile the Ada units to produce a set of object files and ALI
3420   files:
3421
3422   .. code-block:: sh
3423
3424       $ gnatmake -c my_main.adb
3425
3426 * Run the Ada binder on the Ada main program:
3427